Summary

• Problem: Gmail post-ready sidecars could run with stale state during hot reload, Tailscale setup could outlive cancellation, and aborting a command could be treated like a clean exit.
• Why it matters: stale sidecar startup can execute against outdated runtime state, rewrite the Tailscale public target, and incorrect command-status classification hides failures.
• What changed:
  • Stop queued post-ready sidecars before restarting the Gmail watcher in reload flow.
  • Propagate cancellation from post-ready sidecar stop through Gmail watcher startup into Tailscale status and serve/funnel commands.
  • Track abort-initiated kills separately and normalize their outcome as signal termination.
  • Add tests for ordered sidecar shutdown, Tailscale cancellation, and pre-aborted command execution.
• What did NOT change (scope boundary):
  • No public schema, provider contracts, or dependency changes.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #
• Related #
• This PR fixes a bug or regression

Real behavior proof (required for external PRs)

• Behavior addressed:
  • Sidecars ordering in Gmail watcher restart no longer allows stale post-ready sidecars to survive into fresh config reload.
  • Cancelling a stale Gmail startup now aborts in-flight Tailscale setup before it can apply an old serve/funnel target.
  • Abort-driven command shutdown now resolves as signal termination, not synthesized success.
• Real environment tested:
  • macOS local OpenClaw source worktree, Node.js v24.14.0.
  • Runtime proof imported the actual src/hooks/gmail-watcher.ts module and used temporary executable shims on PATH to record tailscale and gog process calls without real credentials.
• Exact steps or command run after this patch:
  • node --import tsx --input-type=module <<'NODE' with a runtime probe that:
    • installs temporary tailscale and gog executables on PATH;
    • starts stale Gmail watcher config for [email protected] with Tailscale target old-target:8788;
    • aborts that startup while the first tailscale status --json command is still in flight;
    • starts fresh Gmail watcher config for [email protected] with Tailscale target new-target:8788;
    • asserts stale result is startup cancelled, old Tailscale serve mutations are 0, and new Tailscale serve mutations are 1.
  • node scripts/run-vitest.mjs src/hooks/gmail-watcher.test.ts src/hooks/gmail-setup-utils.test.ts src/hooks/gmail-watcher-lifecycle.test.ts src/gateway/server-startup-post-attach.test.ts
  • node scripts/run-tsgo.mjs -p tsconfig.core.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/core.tsbuildinfo
  • node scripts/run-tsgo.mjs -p test/tsconfig/tsconfig.test.src.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/test-src.tsbuildinfo
  • node scripts/run-oxlint.mjs --tsconfig config/tsconfig/oxlint.core.json src/gateway/server-startup-post-attach.test.ts src/gateway/server-startup-post-attach.ts src/hooks/gmail-setup-utils.test.ts src/hooks/gmail-setup-utils.ts src/hooks/gmail-watcher-lifecycle.test.ts src/hooks/gmail-watcher-lifecycle.ts src/hooks/gmail-watcher.test.ts src/hooks/gmail-watcher.ts
  • pnpm exec oxfmt --check --threads=1 src/gateway/server-startup-post-attach.test.ts src/gateway/server-startup-post-attach.ts src/hooks/gmail-setup-utils.test.ts src/hooks/gmail-setup-utils.ts src/hooks/gmail-watcher-lifecycle.test.ts src/hooks/gmail-watcher-lifecycle.ts src/hooks/gmail-watcher.test.ts src/hooks/gmail-watcher.ts
  • git diff --check
• Evidence after fix:
  • Runtime proof output:

    OpenClaw Gmail watcher restart abort proof
    stale result: {"started":false,"reason":"startup cancelled"}
    fresh result: {"started":true}
    old tailscale serve mutations: 0
    new tailscale serve mutations: 1
    observed command log:
      tailscale status --json
      tailscale status --json
      tailscale serve --bg --set-path /gmail-pubsub --yes new-target:8788
      gog gmail watch start --account [email protected] --label INBOX --topic projects/proof/topics/gmail
    RESULT: pass - aborted stale startup did not mutate the old Tailscale endpoint; fresh startup configured the new target.
    

  • Targeted Vitest output: Test Files 4 passed (4), Tests 44 passed (44).
  • tsgo core and source-test type checks completed with exit code 0.
  • Targeted oxlint reported Found 0 warnings and 0 errors.
  • Formatting and diff whitespace checks passed.
• Observed result after fix:
  • Stale cancelled startup returned startup cancelled.
  • No tailscale serve --set-path ... old-target:8788 command ran after cancellation.
  • Fresh watcher startup configured exactly one tailscale serve --set-path /gmail-pubsub --yes new-target:8788 command.
  • runCommandWithTimeout sets abort termination state and does not collapse it into exit-success semantics.
• What was not tested:
  • Real Gmail API credentials and real Tailscale network mutation against an operator tailnet were not used; the runtime proof used local executable shims to exercise actual OpenClaw watcher and process-control code without secrets.
  • Broad Testbox gate was not run because crabbox was unavailable locally (crabbox not in PATH, ../crabbox/bin/crabbox missing, and scripts/crabbox-wrapper.mjs failed sanity checks).

Root Cause (if applicable)

• Root cause:
  • Missing sequencing before Gmail watcher restart.
  • Missing cancellation propagation into Tailscale setup.
  • Missing abort-state carry-through in exit normalization.
• Missing detection / guardrail:
  • No stop-before-start check for post-ready sidecar queue in this path.
  • No regression proving Tailscale setup receives cancellation and avoids stale endpoint mutation.
  • Abort handling only inferred through generic kill state.
• Contributing context (if known):
  • Timing race during hot reload.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file:
  • src/gateway/server-reload-handlers.test.ts
  • src/gateway/server-startup-post-attach.test.ts
  • src/hooks/gmail-watcher.test.ts
  • src/hooks/gmail-setup-utils.test.ts
  • src/process/exec.test.ts
• Scenario the test should lock in:
  • Sidecars are stopped before restart, post-ready stop aborts the active watcher startup signal, Tailscale commands receive the abort signal, and abort path does not resolve as exit success.
• Why this is the smallest reliable guardrail:
  • The bug is a deterministic cancellation boundary across Gateway sidecar scheduling, Gmail watcher startup, and command execution.
• Existing test that already covers this (if any):
  • Prior reload and process execution tests covered only part of the sequence.
• If no new test is added, why not:
  • New tests were needed for Tailscale setup cancellation.

User-visible / Behavior Changes

• Hot-reload Gmail watcher now clears queued post-ready sidecars before restart.
• Cancelled stale Gmail startup can no longer continue Tailscale setup and overwrite the public Gmail hook target after a newer watcher starts.
• Abort-triggered command kill is reported as signal termination with non-success result semantics.

Diagram (if applicable)

N/A

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) No
• If any Yes, explain risk + mitigation:
  • Not applicable.

Repro + Verification

Environment

• OS: macOS local shell
• Runtime/container: local shell, Node.js v24.14.0
• Model/provider: N/A
• Integration/channel (if any): Gmail watcher with local tailscale/gog executable shims
• Relevant config (redacted): local proof config with fake account names, fake hook token values, and no real credentials

Steps

1. Run the runtime proof command described in the Real behavior proof section.
2. Confirm stale startup returns startup cancelled.
3. Confirm command log has no old-target:8788 Tailscale serve mutation.
4. Confirm command log has exactly one new-target:8788 Tailscale serve mutation.
5. Run the targeted tests, type checks, lint, format, and diff checks listed above.

Expected

• No stale sidecar restart race.
• Cancelled stale Tailscale setup does not mutate the old endpoint.
• Fresh Gmail watcher startup configures the new endpoint once.
• Abort kill does not read as successful process exit.

Actual

• Runtime proof and targeted checks matched expected behavior.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios:
  • Runtime Gmail watcher restart/abort proof with temporary process shims and copied command output.
  • Unit test verification for sidecar sequencing, Tailscale signal propagation, and abort path.
  • Type/lint/format checks for the touched files.
• Edge cases checked:
  • Pre-aborted signal path.
  • close/reload ordering.
  • In-flight Tailscale setup cancellation.
• What you did not verify:
  • Real production Gmail/Tailscale credentials or real tailnet endpoint mutation.
  • Broad Testbox validation, because Crabbox was unavailable in this local worktree.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps:
  • Not applicable.

Risks and Mitigations

• Risk: additional cleanup step adds small shutdown overhead in hot-reload path.
  • Mitigation: already using existing lifecycle close helpers; only ordering changed.