docs: restarting the module that serves your session is self-decapitating

[iceteaSA]

Operator documentation for the #5 behaviour, separate from the code fixes there. Worth having regardless of which of those land, because the invocation is structurally unfixable — the route carrying the answer is the route being torn down, so no client change makes that call report cleanly.

Three things it records:

The mechanism. Harness tool calls execute by a module, so bash → sh → aft-subc → ck-subc means restarting aft from an aft-served session severs the command's own reply path.

The outcome is UNKNOWN, not failed. This is the part that costs real work if an operator gets it wrong. The drain forces teardown after its budget regardless of whether in-flight requests finished, so a lost response doesn't mean lost work. Observed directly: a ck module rescan && ck module restart aft chain returned only the transport error, with the rescan's already-printed stdout gone from the buffer too. The rescan had run. So: verify with ck module health, never blind-retry a mutation.

The control case. Restarting a module that doesn't serve your session is uneventful, because teardown is scoped to the draining module's endpoint. Verified with a stop claustrum && ck-auth import && start claustrum && health chain from an aft-served session — full buffer survived, no transport error. Same operator, same wrapper, same daemon, different module.

Cited by symbol (begin_forwarding_drain_with, release_module_endpoint_routes) rather than file:line, so it doesn't rot on the next refactor.

---

^{Need help on this PR? Tag @codesmith with what you need. Autofix is disabled.}

---

Summary by cubic

Add operator docs explaining that restarting the module that serves your session is inherently “self-decapitating”: the restart succeeds but the command always returns a transport error because its own reply route is torn down. Covers why the outcome is UNKNOWN (not failed), how to verify with ck module health, the unaffected control case, and how to avoid the issue.

^{Written for commit 4bdaa42. Summary will update on new commits.}

[cubic-dev-ai]

No issues found across 1 file

<sub>You're on the cubic free plan with 17 free PR reviews remaining this month. Upgrade for unlimited reviews.

Re-trigger cubic</sub>

[iceteaSA]

Fixed in 99793df — the review bot caught a real one. ck module health doesn't exist; health is its own domain (ck health <id>) and the module domain carries list/status/restart/stop/start/rescan. I'd invented a verb by pattern-matching the two domains together.

Worth noting where it landed: in the sentence telling operators to verify rather than re-run. A doc whose entire argument is "the outcome is unknown, go check" failing on the check step would have sent someone to an unknown verb error at exactly the moment they'd been told not to trust the error they were already looking at.

Both references now point at real commands, and I ran every ck invocation left in the file against the live daemon rather than eyeballing them:

$ ck health aft
aft: ok
  8 root(s) warming background indexes (serving normally)

$ ck module status aft
id   state    enabled  live  health  failures  last_action  last_exit  restarts  detail
aft  running  true     true  ok      0         restart      code0      0         8 root(s)…

Fork is private, and staying that way — noted on the docs/ history point.