fix(cli): the terminal asks the daemon before it asks you for the user-action key (SD-11 follow-up)

[Broccolito]

Stacked on #240 (SD-11), which is not merged. This branch is main with #240 merged into it,
so the diff carries #240's three commits until it lands. Merge #240 first. The work to review
is these five commits — everything else in the diff is #240 or a merge of main:

• 46d5f7e9 fix(cli): ask the daemon before asking for the user-action key
• 7cd22cf8 test(server): pin the refusal shapes the terminal reads
• f6347f89 docs: the terminal asks the daemon before it asks you
• ade905ea fix(cli): read a chunked empty refusal as empty, not as a body of "0"
• fbef097f refactor(cli): keep the key-verdict types to the module that reads them

Targeting main rather than #240's branch, so that merging #240 cannot close this one.
main was merged in at d5ad76c3 to pick up the reach-sites census fix (#258/#259), without
which every branch off the older base is red on privacy_capability.

SD-11 made a daemon that holds no user-action key admit POST /agent/cancel, POST /interrupt
and /agent/continuation/* for any caller the reach gate admits, a subagent's session excepted. The
terminal had not caught up: session cancel, attach and send demanded the key before they sent
anything, so against biorouter serve they refused locally the very requests SD-11 admits — and
asked every serve user for a key that does not exist. It is the browser's defect, one client over.

What changes

A terminal cannot ask a daemon whether it holds a key, so it lets the daemon answer. Each command
sends its request without the proof — unless the person supplied it with
--user-action-key-stdin — and asks for the key only when the answer is the one refusal that means
"this daemon holds a key": turn control's empty 403. Then it sends once more, with the key. A
refusal that carries a sentence, which is every refusal a keyless daemon gives on these routes, is
printed instead, because no key would change it.

• attach asks as it joins, with an empty steer: /interrupt judges who may steer before it
  reads the text, and refuses empty text before it touches the turn or the agent's queue. It cannot
  wait for the first real steer — by then the stdin reader holds stdin's lock for its whole loop, so
  a hidden prompt would block on that lock, and without it the typed key would race the reader and
  could be delivered to the session as a message. The key is also checked there, before anything
  is typed, instead of at the first steer.
• send asks the same question after a refused /reply, whose own 403 for a subagent's session
  is empty on either kind of daemon and so cannot say which kind this is. On a daemon that holds a
  key, send into an ordinary chat now needs no key at all — which is what the docs always claimed.
• A wrong key, typed or piped, is reported as wrong and never answered with a second prompt.

Nothing is relaxed. The daemon stays the boundary; every refusal read here is given before the
route touches the turn, so making the request again cannot deliver anything twice; a subagent's
session still needs the proof, and a keyless daemon still refuses it. The raw key still comes only
from the terminal or stdin — never argv, environment, config or logs — and is now sent only when the
person supplied it or a daemon asked for it. The local refusal it replaces was never a boundary,
only a guess about which daemon was on the other end.

What this does not change

watch and attach --read-only still never send the key, so a private chat is reached there the
way the docs already describe — by running the terminal under a private model, which the capability
header states. And a daemon that gains a key while an attach is running cannot be answered with a
prompt (stdin is the steering channel by then), so that steer says the daemon was restarted with one
and to attach again, rather than asking.

A bug the runtime check caught

Driving a real daemon that holds a key found that hyper answers an empty 403 with
transfer-encoding: chunked and a lone 0\r\n\r\n terminator, and post_json handed that framing
back as the body — so the terminal read "0" as the daemon's sentence and printed the daemon would
not stop the turn: 0 instead of asking for the key. post_json and daemon_json_request now share
one response parser, which dechunks as the latter already did. The fake daemon in the tests frames
its empty 403 the way the real one does: a content-length: 0 fixture passed every test while the
real thing was misread.

Tests

• crates/biorouter-cli/src/commands/session_watch.rs — the reading of a refusal, the flow over
  every answer order (through the real with_key_if_wanted, as run_ladder's test is), and six
  end-to-end flows over a socket against a stand-in daemon that records what went over the wire:
  the first request carries no key, the person is asked once and only on the empty 403, a sentence
  is printed rather than prompted for, a wrong key is reported as wrong, and an empty refusal reads
  as empty however it is framed.
• The daemon's side of the same contract, because it is what decides whether a person is asked:
  routes::reply's keyed tests (an unproven stop or steer, empty text included, is a 403 with an
  EMPTY body, answered before the text is read; with the proof the empty steer is a 400) and
  tests/turn_control_no_user_key.rs (the empty steer is a 400 where the terminal may steer, and
  otherwise carries the daemon's sentence, never an empty 403, and touches neither the turn nor the
  queue).

cargo test -p biorouter-cli --lib session_watch          50 passed
cargo test -p biorouter-server --test turn_control_no_user_key    9 passed
cargo test -p biorouter-server --lib -- routes::reply routes::session_reach   97 passed

Both new suites were mutation-checked: dropping the "a supplied key is never followed by a prompt"
condition, reading every 403 as "wants the key", and disabling the dechunk each fail 5–6 tests.

Measured against real daemons

Two biorouterd instances on a throwaway root, no model needed (an unconfigured daemon starts an
idle chat), with a sub_agent row for the subagent cases:

	daemon with no key	daemon with a key
session cancel <chat>	stops it, nothing asked	asks, and stops it with the key
session cancel <subagent>	the daemon's sentence, nothing asked	admitted with the key
session send <chat>	sends, nothing asked	sends, nothing asked
session send <subagent>	the daemon's sentence	admitted with the key
attach <chat>	attaches and steers	asks (or says how to supply the key)
attach <subagent>	the sentence, plus --read-only	asks
wrong key	—	it is not the key this daemon was started with
no terminal, no --user-action-key-stdin	not reached	says how to supply it; --read-only for attach

The interactive prompt was driven through a real pty: the key is not echoed, and the raw key appears
nowhere on disk in the sandbox.

CI

test (ubuntu-latest) is red here on one test this branch does not touch —
agent_drafter::bundle::tests::a_timed_out_esbuild_reaps_its_whole_process_group in
biorouter-mcp (1634 passed, 1 failed). It is main's own failure, not this PR's: the same
single test is the only failure on main's push run
34655094806 at 5181f544, the
commit this branch merged, and it failed the same way on 2026-09-03 when it landed. git diff origin/main...HEAD -- crates/biorouter-mcp is empty. (The test races the process reaper: the
grandchild has exited but is a zombie, and kill(pid, 0) returns 0 for a zombie. Filed separately.)

Docs

docs/agent-loop/workspace-control.md (its user-action-key paragraph said attach and cancel prompt
before steering, and that send needs no proof — while send prompted too), SD-11's CLI row and its
"Not decided here" paragraph, now The terminal, since; docs/cli/command-reference.md, which
never mentioned the key or --user-action-key-stdin; the subagents page; and CLAUDE.md's SD-11
bullet, with the refusal-shape invariant the terminal now depends on.

🤖 Generated with Claude Code