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

Merged
IC
3mo ago
+74-0

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.


View with [code]smith Autofix with [code]smith
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.