--once against an open conversation is refused with a sentence nothing documents #1338

What happened

2026-09-21, PR #1071 at 78ddda475 (on dev@49b4a58fb). The fix round on that PR made headless roads (codeaf chat --once, and any Hello with Headless set) build their own approval gate and refuse to attach to an agent that was built interactive, or the reverse. The refusal is one sentence, errExecutionMode in internal/remote/server.go:

this conversation is already open in a different interactive or headless mode; close it before retrying

It is the right default: a headless caller reusing an already-open interactive agent would inherit that agent's gate, which is the bypass the fix exists to close. But it is a new refusal on a road people script against, nothing documents it, and the sentence does not say which mode holds the conversation, where, or what "close it" means for someone who has the interactive session open in another terminal on purpose. Neither docs/changes/unreleased/1071-approvals-wheel.md nor any page under internal/manual/chat/ mentions it, so the chat cannot answer "why does --once say the conversation is already open".

Replication

Deterministic (no model).

The errExecutionMode path in internal/remote/server.go is reached whenever a hello's Headless disagrees with the mode the agent was opened in; a unit case beside it with a stub engine shows the refusal and its exact bytes. Through the real door: internal/manual/chat_test.go with the probe why does --once say the conversation is already open reaches no page today.

Field (real models).

Open a workspace interactively with codeaf, then from a second shell run codeaf chat --once "say hi" in the same workspace. The second command exits non-zero and prints the sentence above. Needs a provider key only for the first process; the refusal itself costs nothing.

Where

errExecutionMode and its check in internal/remote/server.go; Hello.Headless in internal/remote/wire.go; the --once flag in cmd/codeaf/chatv3.go; internal/manual/chat/running-from-the-terminal.md for the page that should carry it; docs/changes/unreleased/1071-approvals-wheel.md for the entry.

The fix

Three things, all wording:

1. The refusal names the other side and the way out, on the model of the product's other refusals: this conversation is open interactively in another terminal; --once cannot join it. Close it there, or run --once in a different session. and the mirror sentence when an interactive launch finds a headless holder.
2. internal/manual/chat/running-from-the-terminal.md gets a ## heading in the asker's words (--once says the conversation is already open) that quotes the sentence and says why it exists: a headless run answers its own approvals and never borrows an open session's gate.
3. The UX changes: home navigation and consistent message-box controls #1071 change entry's invalidates says that --once used to join an open conversation and now refuses.

Acceptance

• e2e: an interactive codeaf holding a workspace, then codeaf chat --once "say hi" in the same workspace from a second process: exit code non-zero and the new sentence printed in full.
• e2e: control: codeaf chat --once "say hi" in a workspace nobody holds runs, prints the reply and exits zero; --once without --yolo still refuses a tool call with needs approval but no resolver is attached.
• Unit: the manual probe why does --once say the conversation is already open reaches running-from-the-terminal.
• The manual page quotes the wording exactly as internal/remote/server.go spells it, and the change entry's invalidates names what people believed before.