Summary

This PR hardens the check-gateway-watch-regression release/runtime guard so failures are easier to diagnose and short-lived gateway-watch exits are reported accurately.

The change is intentionally narrow. It only touches the gateway watch regression script and its focused tests.

What Problem This Solves

The watch regression guard currently has a few sharp edges that make release/runtime failures harder to reason about:

• The timed watch command can run under /bin/sh, but CI/bootstrap environments may inject shell hooks that assume bash semantics. That can add noisy stderr output or delay gateway readiness before the idle window.
• If the child process exits before readiness, the script can collapse that into a generic “did not report ready” failure instead of reporting that the watch process actually exited.
• When the watch guard fails, stdout/stderr artifacts are written, but the actionable tail is not surfaced inline with the failure.
• The duplicate dist-runtime warning was gated too broadly; unrelated failures could print the split-runtime warning even when no dist-runtime graph regression was detected.

What changed

• Prefer bash for the timed watch shell when available, while retaining /bin/sh fallback.
• Quote the Node executable path explicitly and put its directory at the front of PATH for the isolated watch process.
• Track child process exit during PID-file wait, readiness wait, settle, idle window, and stop phases.
• Report gateway:watch exited before ready (...) when the child exits before readiness.
• Include bounded stdout/stderr tails on watch failures.
• Only print the duplicate dist-runtime warning when a dist-runtime failure is actually present.
• Add focused unit coverage for:
  • bash selection/fallback
  • generated timed watch command/env
  • early exit before readiness
  • duplicate dist-runtime warning gating
  • stderr/stdout artifact metadata in the watch result

Evidence

Rebase/squash proof — 2026-06-23 UTC

Latest pushed commit after same-base rebase and squash: 4ea42a587047d35cb4f54814488f0ded22524eb7.

All six coordinated PR branches in this batch were rebased onto the same pinned upstream base commit:

dc9c11be917ebdc711b956250aa80a8e5b47bea6

Post-rebase local verification included conflict-marker/diff hygiene plus focused branch-specific gates. Final proof marker for this PR:

POST_REBASE_20260623_GATEWAY_WATCH_GATES_OK

Local validation run from /home/kklouzal/.openclaw/workspace/repos/openclaw:

node scripts/run-vitest.mjs test/scripts/check-gateway-watch-regression.test.ts

Result:

1 passed test file
15 passed tests

Additional checks:

node --check scripts/check-gateway-watch-regression.mjs
git diff --check
git diff --cached --check

Result: all passed.

Real Behavior Proof

Redacted terminal output from a real gateway-watch guard invocation on this PR head:

$ git rev-parse HEAD
dfbc96e4178989869ebfc06da80d7519fd199f7e
$ node scripts/check-gateway-watch-regression.mjs --skip-build
{
  "windowMs": 10000,
  "watchTriggeredBuild": false,
  "watchBuildReason": null,
  "cpuMs": 1000,
  "totalCpuMs": null,
  "readyBeforeWindow": true,
  "exitedBeforeReady": false,
  "cpuWarnMs": 1000,
  "cpuFailMs": 8000,
  "distRuntimeFileGrowth": 0,
  "distRuntimeFileGrowthMax": 200,
  "distRuntimeByteGrowth": 0,
  "distRuntimeByteGrowthMax": 2097152,
  "distRuntimeAddedPaths": 0,
  "addedPaths": 0,
  "removedPaths": 0,
  "watchExit": {
    "code": 143,
    "signal": null
  },
  "spawnError": null,
  "stdoutPath": "<repo>/.local/gateway-watch-regression/watch/watch.stdout.log",
  "stderrPath": "<repo>/.local/gateway-watch-regression/watch/watch.stderr.log",
  "timingFileMissing": true,
  "timing": {
    "userSeconds": null,
    "sysSeconds": null,
    "elapsedSeconds": null
  }
}
WARN: bounded gateway:watch timing artifact is missing; using process-tree idle CPU sample

Notes:

• This was run from the PR head commit shown above: dfbc96e4178989869ebfc06da80d7519fd199f7e.
• Private local paths are redacted as <repo>.
• The successful guard run reported readyBeforeWindow: true, exitedBeforeReady: false, no dist-runtime growth, and bounded stdout/stderr artifact paths.
• This run did not naturally exercise the early-exit failure path; no failure-path output is claimed here.

Synthetic Failure-Path Proof

Redacted terminal output from a synthetic failure-path invocation on the same PR head. This intentionally lowers the CPU failure threshold to 0 so the guard exits non-zero and prints the new bounded failure diagnostics without needing to break the gateway:

$ git rev-parse HEAD
dfbc96e4178989869ebfc06da80d7519fd199f7e
$ node scripts/check-gateway-watch-regression.mjs --skip-build --cpu-fail-ms 0 --cpu-warn-ms 0
{
  "windowMs": 10000,
  "watchTriggeredBuild": false,
  "watchBuildReason": null,
  "cpuMs": 1000,
  "totalCpuMs": null,
  "readyBeforeWindow": true,
  "exitedBeforeReady": false,
  "cpuWarnMs": 0,
  "cpuFailMs": 0,
  "distRuntimeFileGrowth": 0,
  "distRuntimeFileGrowthMax": 200,
  "distRuntimeByteGrowth": 0,
  "distRuntimeByteGrowthMax": 2097152,
  "distRuntimeAddedPaths": 0,
  "addedPaths": 0,
  "removedPaths": 0,
  "watchExit": {
    "code": 143,
    "signal": null
  },
  "spawnError": null,
  "stdoutPath": "<repo>/.local/gateway-watch-regression/watch/watch.stdout.log",
  "stderrPath": "<repo>/.local/gateway-watch-regression/watch/watch.stderr.log",
  "timingFileMissing": true,
  "timing": {
    "userSeconds": null,
    "sysSeconds": null,
    "elapsedSeconds": null
  }
}
WARN: bounded gateway:watch timing artifact is missing; using process-tree idle CPU sample
FAIL: LOUD ALARM: gateway:watch used 1000ms CPU in 10000ms window, above loud-alarm threshold 0ms
WARN: gateway:watch stderr artifact is empty (<repo>/.local/gateway-watch-regression/watch/watch.stderr.log)
--- gateway:watch stdout tail (<repo>/.local/gateway-watch-regression/watch/watch.stdout.log, last 12000 chars) ---
2026-06-21T04:12:04.753+00:00 [gateway] loading configuration…
2026-06-21T04:12:04.845+00:00 [gateway] force: no listeners on port 40195
2026-06-21T04:12:04.853+00:00 [gateway] resolving authentication…
2026-06-21T04:12:04.874+00:00 [gateway] starting...
2026-06-21T04:12:05.459+00:00 [gateway] starting HTTP server...
2026-06-21T04:12:05.478+00:00 [health-monitor] started (interval: 300s, startup-grace: 60s, channel-connect-grace: 120s)
2026-06-21T04:12:05.561+00:00 [gateway] agent model: openai/gpt-5.5 (thinking=medium, fast=off)
2026-06-21T04:12:05.562+00:00 [gateway] http server listening (0 plugins, 0.7s)
2026-06-21T04:12:05.564+00:00 [gateway] log file: /tmp/openclaw/openclaw-2026-06-21.log
2026-06-21T04:12:05.566+00:00 [gateway] ready
2026-06-21T04:12:16.094+00:00 [gateway] signal SIGTERM received
2026-06-21T04:12:16.097+00:00 [gateway] received SIGTERM; shutting down
2026-06-21T04:12:16.203+00:00 [shutdown] started: gateway stopping
2026-06-21T04:12:16.248+00:00 [gmail-watcher] gmail watcher stopped
2026-06-21T04:12:16.256+00:00 [shutdown] completed cleanly in 53ms
--- end gateway:watch stdout tail ---

Notes:

• This was run from the same PR head commit as the real behavior proof: dfbc96e4178989869ebfc06da80d7519fd199f7e.
• Private local paths are redacted as <repo>.
• The failure was intentionally triggered by --cpu-fail-ms 0; the transcript demonstrates the failure reporting path, including the bounded stdout artifact tail and empty-stderr warning.

Synthetic Early-Exit Proof

Redacted synthetic transcript exercising the new gateway:watch exited before ready finding path directly. This uses the PR script's exported collectGatewayWatchFindings helper with a synthetic pre-ready child exit result, so the failure text is produced by the same finding collector used by the full regression command:

$ git rev-parse HEAD
dfbc96e4178989869ebfc06da80d7519fd199f7e
$ node /tmp/openclaw-pr-proof/pr-95473-early-exit-proof.mjs
FAIL: gateway:watch exited before ready (code 1, signal null)
FAIL: failed to collect CPU timing from the bounded gateway:watch run; timing artifact is missing
FAIL: failed to parse CPU timing from the bounded gateway:watch run

Notes:

• This was run from PR head commit dfbc96e4178989869ebfc06da80d7519fd199f7e.
• The synthetic input models readyBeforeWindow: false, exitedBeforeReady: true, and exit: { code: 1, signal: null }.
• This complements the existing log-tail synthetic proof by covering the separate early-exit-before-ready diagnostic branch.

Current-Head Post-Ready-Exit Proof

Redacted proof from current PR head 19ff518eb0ee305bf21812ed19423290dd41ea9d, covering the latest post-ready-exit repair. The focused test file now includes the ready-then-exit cases for both the settle window and the idle window, plus the collector-level failure text assertion.

$ git rev-parse HEAD
19ff518eb0ee305bf21812ed19423290dd41ea9d
$ node scripts/run-vitest.mjs test/scripts/check-gateway-watch-regression.test.ts
[test] starting test/vitest/vitest.tooling.config.ts

 RUN  v4.1.8 <repo>

 ✓  tooling  test/scripts/check-gateway-watch-regression.test.ts (18 tests) 85ms

 Test Files  1 passed (1)
      Tests  18 passed (18)
[test] passed 1 Vitest shard in 6.84s
$ node --check scripts/check-gateway-watch-regression.mjs
$ git diff --check HEAD^..HEAD

Synthetic collector transcript from the same current head showing the new post-ready unplanned-exit failure text directly:

$ git rev-parse HEAD
19ff518eb0ee305bf21812ed19423290dd41ea9d
$ node /tmp/openclaw-pr-proof/pr-95473-current-head-finding-proof.mjs
FAIL: gateway:watch exited before the idle CPU window completed (code 0, signal null)

Notes:

• The synthetic collector input models a watch process that reached readiness (readyBeforeWindow: true) and then exited before the expected stop phase (exitedBeforeStop: true, exit: { code: 0, signal: null }).
• Private local paths are redacted as <repo>.
• Full local redacted transcripts were saved during validation as /tmp/openclaw-pr-proof/pr-95473-current-head-post-ready-exit.redacted.log and /tmp/openclaw-pr-proof/pr-95473-current-head-finding-proof.redacted.log.

Current-Head Full Guard Proof

Redacted terminal output from current PR head 19ff518eb0ee305bf21812ed19423290dd41ea9d showing a full guard invocation, not just focused tests or a synthetic collector path:

$ git rev-parse HEAD
19ff518eb0ee305bf21812ed19423290dd41ea9d
$ node scripts/check-gateway-watch-regression.mjs --skip-build
{
  "windowMs": 10000,
  "watchTriggeredBuild": false,
  "watchBuildReason": null,
  "cpuMs": 0,
  "totalCpuMs": null,
  "readyBeforeWindow": true,
  "exitedBeforeReady": false,
  "exitedBeforeStop": false,
  "cpuWarnMs": 1000,
  "cpuFailMs": 8000,
  "distRuntimeFileGrowth": 0,
  "distRuntimeFileGrowthMax": 200,
  "distRuntimeByteGrowth": 0,
  "distRuntimeByteGrowthMax": 2097152,
  "distRuntimeAddedPaths": 0,
  "addedPaths": 0,
  "removedPaths": 0,
  "watchExit": {
    "code": 143,
    "signal": null
  },
  "spawnError": null,
  "stdoutPath": "<repo>/.local/gateway-watch-regression/watch/watch.stdout.log",
  "stderrPath": "<repo>/.local/gateway-watch-regression/watch/watch.stderr.log",
  "timingFileMissing": true,
  "timing": {
    "userSeconds": null,
    "sysSeconds": null,
    "elapsedSeconds": null
  }
}
WARN: bounded gateway:watch timing artifact is missing; using process-tree idle CPU sample

Notes:

• This is the full node scripts/check-gateway-watch-regression.mjs --skip-build guard run from current head 19ff518eb0ee305bf21812ed19423290dd41ea9d.
• Private local paths are redacted as <repo>.
• The expected post-window stop is visible as watchExit.code: 143, while the current-head lifecycle repair reports exitedBeforeReady: false and exitedBeforeStop: false.
• Full local redacted transcript saved during validation as /tmp/openclaw-pr-proof/pr-95473-current-head-full-guard.redacted.log.

Current-Head Full Guard Proof Refresh — 2026-06-23

Redacted terminal output from current PR head b34c5fc8e29b19dbaa43e248e7bfc1467f054abf showing the full guard invocation ClawSweeper requested:

$ git rev-parse HEAD
b34c5fc8e29b19dbaa43e248e7bfc1467f054abf
$ node scripts/check-gateway-watch-regression.mjs --skip-build
{
  "windowMs": 10000,
  "watchTriggeredBuild": false,
  "watchBuildReason": null,
  "cpuMs": 1000,
  "totalCpuMs": null,
  "readyBeforeWindow": true,
  "exitedBeforeReady": false,
  "exitedBeforeStop": false,
  "cpuWarnMs": 1000,
  "cpuFailMs": 8000,
  "distRuntimeFileGrowth": 0,
  "distRuntimeFileGrowthMax": 200,
  "distRuntimeByteGrowth": 0,
  "distRuntimeByteGrowthMax": 2097152,
  "distRuntimeAddedPaths": 0,
  "addedPaths": 0,
  "removedPaths": 0,
  "watchExit": {
    "code": 143,
    "signal": null
  },
  "spawnError": null,
  "stdoutPath": "<repo>/.local/gateway-watch-regression/watch/watch.stdout.log",
  "stderrPath": "<repo>/.local/gateway-watch-regression/watch/watch.stderr.log",
  "timingFileMissing": true,
  "timing": {
    "userSeconds": null,
    "sysSeconds": null,
    "elapsedSeconds": null
  }
}
WARN: bounded gateway:watch timing artifact is missing; using process-tree idle CPU sample

Notes:

• This run was collected after building this PR worktree with node scripts/build-all.mjs gatewayWatch, because the worktree initially had no dist or dist-runtime artifacts.
• Private local paths are redacted as <repo>.
• The guard reached readiness on the current head, did not exit before readiness or before the idle window completed, did not trigger a watch rebuild, and reported no dist-runtime growth.
• Full local transcripts were saved during validation as /tmp/openclaw-pr-proof/pr-95473-b34c5fc-full-guard.raw.log and /tmp/openclaw-pr-proof/pr-95473-b34c5fc-full-guard.redacted.log.

Risk

Low to moderate. This changes release/runtime diagnostic behavior, not production gateway behavior. The highest-impact runtime-adjacent change is using bash for the timed watch command when available; fallback behavior remains /bin/sh if bash is unavailable.

The failure output becomes more verbose only when the watch guard fails, and stdout/stderr tails are bounded.

PR/Commit Surface Breakdown

Source: 1 files, +124 / -13
Tests: 1 files, +287 / -0
Total: 2 files, +411 / -13

Rebase / Proof Refresh (2026-06-23)

• Base: 654544b6b7c49d78afbacacd4861bcc830172780
• Head after refresh: b34c5fc8e29b19dbaa43e248e7bfc1467f054abf
• Conflict resolution: None. Rebase applied cleanly.
• Validation: OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache-pr95473 node scripts/run-vitest.mjs test/scripts/check-gateway-watch-regression.test.ts -> passed, 1 file / 18 tests.
• Push: force-with-lease to kklouzal/openclaw:extract/gateway-watch-regression-hardening completed.