fix(daemon-client): document the drain timeout and tighten ensureDaemon follow-ups

[thymikee]

Part of #3747. References #3754 and #3780 (merged before these landed).

Follow-ups to the quiesce/ensure stack:

• Docs: daemon-drain-timeout and the post-drain force retire in client-api.md and the help lifecycle topic.
• A drain-deadline retirement now goes through the typed stopAndRetireDaemon result (stopDaemonForTakeover), replacing the cast on error.details.retirement.
• A daemon force-retired for outlasting its drain is reported as unreachable (Replaced unreachable daemon), not Replaced idle daemon.
• The daemon-not-running hint names --state-dir <dir> when the directory is not the default.
• isDaemonNotRunningError(error) replaces the bare reason string in daemon-client-ensuring.ts.
• session-store.ts uses DAEMON_SHUTTING_DOWN_REASON.
• Test: ensureDaemon against a busy daemon with startingUp: true asserts the startup hint.

Already on main, so unchanged: the client reads the startingUp census (readDaemonQuiesceCensus) and daemonBusyError gives the startup hint; the stale comment in daemon-client-metadata.ts no longer exists.

The "answers a probe" stand-in keeps serving /health: a stand-in that stops serving is the previous test (no probe answered, force retire). Its comment now says it models a stuck drain.

🤖 Generated with Claude Code

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-10-17 14:50 UTC

[cubic-dev-ai]

All reported issues were addressed across 11 files

_{You’re at about 97% of the monthly reviewed-line limit. You may want to disable incremental reviews to conserve quota. Reviews will continue until that limit is exceeded. If you need help avoiding interruptions, please contact contact@cubic.dev.}

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[github-actions]

Size Report

Metric	Base	Current	Diff
Installed (including dependencies)	5.38 MB	5.38 MB	+576 B
Package (unpacked)	5.38 MB	5.38 MB	+576 B
Package (download)	1.62 MB	1.62 MB	+207 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	20.4 ms	19.4 ms	-1.0 ms
CLI --help	53.7 ms	53.0 ms	-0.8 ms

[cubic-dev-ai]

All reported issues were addressed across 3 files (changes from recent commits).

_{You’re at about 97% of the monthly reviewed-line limit. You may want to disable incremental reviews to conserve quota. Reviews will continue until that limit is exceeded. If you need help avoiding interruptions, please contact contact@cubic.dev.}

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[thymikee]

Rebased onto main (after the plugin v2 stack, #3767–#3770). No review comments were outstanding: all three threads were already replied to and resolved. check:affected passed on the rebased head 11200c0.

🤖 Generated with Claude Code

[thymikee]

The PR is ready at 11200c0, and I found no problems in the code.

Not blocking: the hint in daemon-lifecycle-errors.ts leaves out --state-dir when the state dir equals the default, but that default ignores AGENT_DEVICE_STATE_DIR, which the CLI reads. If the shell exports that variable and an SDK caller passes ~/.agent-device, the hint suggests 'agent-device devices' and that starts a daemon in the wrong directory. Always including --state-dir, as daemonStopCommand does, would fix it and let you drop the default branch and its test. You can take this or leave it, and moving the error factory into daemon-lifecycle-errors.ts is optional too.

I did not run the tests. By reading the diff, the onStart 'missing' assertion and both hint assertions would fail on the merge-base code. No test covers the daemon_retirement_unconfirmed branch after a drain, but it behaves like the old rethrow. The 60 s figure is written by hand in the docs, help, CHANGELOG and the test, and nothing ties it to DRAIN_DEADLINE_MS. All of them match today.

The three open inline threads (#3783 (comment), #3783 (comment), #3783 (comment)) are fixed at this commit, so please resolve them.

Both Smoke Tests jobs are still running with no failures. They cover the CLI and MCP path through ensureDaemon, but they start a missing daemon and do not reach the drain or force-retire branches this PR changes. Once both jobs finish green, the PR can merge.

[thymikee]

Applied the 13:35Z review in 0fa2373:

• The daemon-not-running hint now always includes --state-dir <dir>, like daemonStopCommand. The default-directory comparison ignored AGENT_DEVICE_STATE_DIR, so it could point at the wrong directory. The default branch and its test are gone, and the CHANGELOG line is updated.
• daemonRetirementUnconfirmedError moved into daemon-lifecycle-errors.ts.

check:affected passed on this head.

🤖 Generated with Claude Code

[thymikee]

I re-reviewed 0fa2373 and the code looks good. The hint text and the error-constructor move from the earlier review are now in place, and I found nothing else to change. I read the diff and searched the code at this commit but did not run tests. The change only touches error and hint text, the error constructor, a CHANGELOG line and one removed unit test, so it does not affect a device or daemon runtime route. The only check that has not passed is Smoke Tests, which is still running with no failure so far, so it needs to finish green before merge. No conflicts.