openclaw/docs/cli/doctor
Peter Steinberger 54abbae585
fix: refresh stale Gateway shutdown budgets during updates and Doctor (#153636)
* fix: refresh stale Gateway stop policies before maintenance

Main recognized historical systemd timeouts, but maintenance could stop the
resident before repair, and Doctor and already-current or no-restart updates
could preserve stale computed policy. A published 2026.9.5 resident also retains
its startup shutdown budget after the unit changes.

Refresh owned policy through the existing definition-mutation and backup owners,
confirm daemon reload, preserve operator drop-ins, and retain restore/reload/input
retirement ordering. Share maintenance between update and Doctor, and warn when
a non-stopping refresh still has a short effective manager timeout.

Publish process-owned shutdown budgets and lifecycle write-custody facts. Reuse
the suspension owner and existing update deadline: stop when idle, warn and stop
at the deadline for ordinary work or unknown custody, and refuse only current
reported write custody with its exact owner phase. Reread native policy when the
new Gateway accepts shutdown without resetting its elapsed budget or watchdog.

Thanks @ezimerman for the installed-unit and shutdown evidence.
Fixes #153153. Refs #150898, #152879, #153017.

* fix: preserve the resident shutdown budget in Gateway status

The kernel request-context adapter copied host lifecycle control methods but
dropped the recorded shutdown-budget getter. Real Linux package proof observed
a 325-second startup budget while status omitted it, forcing maintenance onto
the legacy unknown-budget path.

Forward the live getter through the existing adapter without changing request
authority or adding another budget owner. Add a real-kernel registered-status
regression for short and adequate budgets; the corrected test fails on the
original adapter and passes with the forwarding line.

Refs #153153.

* test: control the Gateway shutdown clock consistently

Restore the explicit node:perf_hooks performance import for the run-loop regressions that retain their own fake-clock assertions. They must control the same monotonic clock as the production shutdown-budget owner. Keep the deadline assertions, timers, and production behavior unchanged.

* fix: preserve Doctor legacy reads during Gateway preflight

The stale-Gateway probe opened the canonical owner-lease database without
Doctor's existing legacy-catalog admission. With a built install and a busy
Gateway port, that read created WAL/SHM files and rejected a supported repair
before maintenance could stop the Gateway.

Carry the existing read admission through restart inspection to the lease owner.
Keep ordinary restart validation unchanged and preserve canonical artifacts.
Use synthetic port, build, and reachability facts in the regression fixture while
retaining real lease reads and byte-preservation assertions.

Refs #153153.

* refactor: keep Gateway maintenance owners within line limits

The L903 stop-policy repair exceeded the existing line-growth gate after
composition with current restart and service identity handling. Move request
upgrade policy into its existing request owner and service revalidation into
one sibling implementation without changing their behavior.

Preserve original request admission time and Doctor's statically primed
maintenance facade across package replacement. The bounded drain, recorded
custody-only refusal, warning policy, and native backup/reload ordering remain
unchanged. No options, schema changes, suppressions, or baseline growth.

Validation: 398 focused tests, core typecheck, line-growth ratchet, and fresh
Codex P1 review passed. Full changed checks continue on the frozen source.

* test: retain backup custody coverage through the archive walker

The rebase incorporated the maintained archive walker, but the L903 custody
regression still referenced the retired tar-create mock. Use the existing
walker mock bound to the real backup command without changing assertions or
production code.

Validation: 132 backup, migration, cron, coordinator, and suspension tests
passed. Fresh Codex P1 review is clean. Full changed checks continue.

* fix: preserve maintenance lifecycle and wrapper contracts

Doctor fixtures advertised a running native service without the matching
resident identity, effective policy, or lifecycle readiness response. Supply
those facts through the same RPC and native-query boundaries used by the real
maintenance owner, including fresh readiness without a resident budget.

Keep exact suspension assertions current with the additive custody category.
Install the model-acquisition fixture's manager after normal PATH setup so
startup and shutdown observe the same policy under the original deadlines.
Include the custody owner in the canonical PR-wrapper source inventory.

Move the unchanged Doctor inspection assertion and shared fixtures into their
existing policy/support owners to preserve the line-growth ratchet. Do not
change the bounded-deferral, warning, or reported-write-custody refusal policy.

* fix: preserve Stop ownership through shutdown budget refresh

An asynchronous systemd budget read could resume after Stop captured a
foreground updater and re-arm the hard-exit worker. Keep watchdog admission
with the run loop's current successor owner, and represent an absent cleanup
deadline with no process-cleanup budget.

Preserve foreground no-op service ownership and the full native allowance
after verified parking. Keep one fake clock for boundary tests, prepare
fixture operations before held scripts, and join cancelled fixture work
before the next case. Move unchanged budget cases into their support owner.

Retain the ruling that unknown custody cannot block an update and only
reported write custody may refuse maintenance. Preserve all existing test
assertions and limits. The full Linux changed gate, 790 focused Linux tests,
and a fresh P1 review passed; local host limitations are recorded in the PR.

* refactor(doctor): extract update-run admission from doctor-maintenance

* fix: preserve native policy and write custody during maintenance

* fix: keep shutdown integration within source and type gates

* fix(test): own survivor model endpoint before baseline setup

---------

Co-authored-by: Vincent Koc <vincentkoc@ieee.org>
2026-09-21 12:31:05 +08:00
..
checks.md fix: refresh stale Gateway shutdown budgets during updates and Doctor (#153636) 2026-09-21 12:31:05 +08:00
health-contract.md docs: correct verified accuracy defects in CLI, tools, and automation pages (#143179) 2026-09-09 23:57:06 +09:00
lint.md fix(update): retain Doctor advisories and terminal reports (#153147) 2026-09-20 04:52:04 -07:00
recovery.md fix(update): reconcile a managed service pinned to another install (#150898) 2026-09-20 02:40:54 -07:00
running.md fix: refresh stale Gateway shutdown budgets during updates and Doctor (#153636) 2026-09-21 12:31:05 +08:00
sqlite-maintenance.md fix(doctor): recover verified session imports with missing or replaced files (#153655) 2026-09-20 16:10:56 -07:00
state-migrations.md fix: avoid circular plugin migration recovery advice (#153419) 2026-09-20 11:23:13 -07:00