Summary

• report the three planned startup migration/config/plugin refusal reasons at their owner, then throw ExitError(1) so ensureConfigReady uses its existing typed runtime.exit path
• add a hermetic child-process regression that exercises a real conflicting plugin-state migration, requires exit status 1 with no signal, verifies the refusal appears exactly once, and confirms the startup migration lease is released
• audit the core DatabaseSync migration/checkpoint paths for throw-time handle leaks; every direct handle is already closed by finally, so no unrelated migration refactor is included

This PR was originally stacked on #110200. That prerequisite has now merged as 748fc044192a1c98d8344ea6682a3f38dd7ef384; the branch was rebased onto origin/main at 82fa956d5a22c65d0dd9f2bfc5ff964e45c9728e, and the already-applied ce6e200aaa2 commit dropped from this PR's history. The landing dependency is satisfied.

Refs #109831.

What Problem This Solves

Startup migration, invalid-config, and plugin-verification refusals were ordinary Errors. They bypassed the typed exit handling in src/cli/program/config-guard.ts, reached the generic src/entry.ts failure handler, and ended in its direct process.exit(1) path. In the reported supervised deployment, that path terminated with signal 11 / status 139 instead of a clean refusal status, turning a fail-closed migration result into a supervisor crash loop.

Root Cause

The proven pre-fix control flow is:

1. src/commands/doctor-config-preflight.ts formatted an intentional readiness refusal but threw a plain Error.
2. ensureConfigReady only converts ExitError into runtime.exit(error.code), so it rethrew the plain refusal.
3. src/entry.ts added Could not start the CLI. / Reason: formatting and called process.exit(1).

The preflight's existing finally already releases its heartbeat and startup migration lease before the error leaves the owner. The fix preserves that unwind and hands the intentional refusal to the typed caller contract instead of treating it as an unexpected CLI startup failure.

The reporter's exact native signal source is not established without their core dump. This change fixes the incorrect refusal path and locks down the observable process contract; it does not claim to identify or patch the native module.

Why This Change Was Made

The refusal owner must print the reason because the typed ExitError branch intentionally does not format errors, while the generic entry catch is no longer reached. Printing once immediately before throwing ExitError(1) preserves the complete operator guidance without duplicating the generic wrapper.

This is the narrow owner-boundary fix: unexpected preflight errors still use the generic failure handler, and gateway readiness remains fail-closed.

The core migration audit covered the direct DatabaseSync constructors in src/infra/state-migrations.debug-proxy.ts, src/infra/state-migrations.task-sidecar-rows.ts, and src/infra/state-migrations.storage.ts, plus the checkpoint database wrapper used by src/infra/startup-migration-checkpoint.ts. Each closes in finally, including throw paths. No plugin-owned code was changed.

User Impact

When a startup migration gate refuses readiness, operators retain the full actionable refusal text exactly once. The CLI exits through the typed status-1 path, the migration lease is released, and supervisors see a normal non-zero exit rather than a signal in the covered regression environment.

Evidence

Rebase result

After #110200 merged, git fetch origin main and git rebase origin/main skipped its already-applied ce6e200aaa2 commit and replayed only this PR's fix. Main advanced once during the proof window, so the branch was rebased a second time before the final proof.

git log --oneline origin/main..HEAD on the published branch contains one commit:

d0281e2cc2a fix(cli): exit cleanly on migration refusal

Final identities:

origin/main=82fa956d5a22c65d0dd9f2bfc5ff964e45c9728e
head=d0281e2cc2a852f2c20903275fa7fa74ac996c92

Real behavior proof — exact rebased head

Environment: Linux source checkout, Node v25.9.0, actual src/entry.ts, no provider/channel credentials, and an isolated realpathed temporary HOME, config, and OPENCLAW_STATE_DIR. The canonical plugin-state row had timestamp 2000 and value {"version":1}; the legacy sidecar held the same key with newer timestamp 3000 and divergent value {"version":2}. That is intentionally unresolved under the merged #109832 migration contract.

A Node supervisor wrapper used spawnSync with a 60-second timeout and captured the wait status and signal separately. It launched the actual gateway entry twice against the same unresolved state:

node --import tsx src/entry.ts gateway run --allow-unconfigured

Observed on exact head d0281e2cc2a852f2c20903275fa7fa74ac996c92:

gateway_run_1 status=1 signal=none refusal_count=1 stale_lease_count=0 generic_wrapper_count=0
after_gateway_run_1 active_startup_migration_lease=false
gateway_run_2 status=1 signal=none refusal_count=1 stale_lease_count=0 generic_wrapper_count=0
after_gateway_run_2 active_startup_migration_lease=false

Redacted stderr from the first run:

[state-migrations] Legacy state migration warnings:
- Left plugin-state sidecar in place because 1 row differs from shared state without a newer canonical timestamp. First key: proof-plugin/proof-namespace/proof-key
OpenClaw startup migrations did not complete cleanly; refusing to report the gateway ready.
- Left plugin-state sidecar in place because 1 row differs from shared state without a newer canonical timestamp. First key: proof-plugin/proof-namespace/proof-key
Run "openclaw doctor --fix" against the mounted state/config, then restart the container.

This proves both supervisor-observed gateway attempts exited with code 1 rather than a signal/status 139, printed the refusal headline exactly once on stderr, omitted the generic outer-entry wrapper, and released the startup migration lease. The second run acquired a fresh lease and did not report a stale/active lease.

Doctor-path parity

The same exact-head wrapper and unresolved fixture then ran:

node --import tsx src/entry.ts doctor --fix --non-interactive --yes

Observed:

doctor_fix status=0 signal=none stale_lease_count=0 active_startup_migration_lease=false

Doctor continues to report the unresolved migration without gating gateway readiness, exits normally, and releases its lease. Gateway remains fail-closed on the next startup attempt.

Guard-boundary verification

The existing ensureConfigReady catch in src/cli/program/config-guard.ts intercepts ExitError and calls runtime.exit(error.code). The live process transcript proves the refusal reaches that branch: the generic [openclaw] Could not start the CLI. wrapper count is zero, while the refusal owner prints its reason exactly once.

Post-rebase fixture correction

The first focused run after rebasing failed because merged #109832 correctly archived the old fixture's older sidecar row; the child then continued to a locally occupied gateway port. That was a stale test premise, not a product regression. The fixture now uses a newer divergent sidecar timestamp, which is the migration state that must remain unresolved. The corrected exact-head run is green.

Mandatory uncommitted autoreview of that fixture correction reported:

autoreview clean: no accepted/actionable findings reported
overall: patch is correct (0.98)

Pre-fix contrast and native-crash boundary

An earlier run from pre-fix merge base 433b3ce86d71a88fb34d4f61f6f10c36b912aeee exited status 1 with no signal on this host, but included generic_wrapper_count=1; the patched path has generic_wrapper_count=0. The reporter's SIGSEGV did not reproduce in this environment on either revision. This proof establishes the clean typed-exit contract owned by this PR; identifying the reporter's crashing native module remains deferred pending their core dump.

Verification

pnpm format src/commands/doctor-config-preflight.process.test.ts
Finished in 4ms on 1 files using 1 threads.

node scripts/run-vitest.mjs src/commands/doctor-config-preflight.state-migration.test.ts src/commands/doctor-config-preflight.process.test.ts
Test Files  2 passed (2)
Tests       24 passed (24)
Duration    2.51s
[test] passed 1 Vitest shard in 4.62s

git diff --check origin/main...HEAD
passed

What Was Not Tested

• The reporter's exact container/supervisor/native-module failure was not reproduced; identifying the crashing native module requires the reporter's core dump and is intentionally deferred.
• No successful full gateway channel/provider startup was exercised. The real child process stops at the intended preflight refusal, before runGatewayCommand starts runtime services.
• No broad suite was run; focused coverage exercises the changed refusal owner, existing migration cases, child-process exit semantics, lease cleanup, and the scoped core changed gate.