Plan: headless hosts — plan approval by select, gate asks that time out to deny, no hangs under RPC (#135)

pi runs our extensions under hosts other than the terminal: pi --mode rpc (IDE plugins, pi-web-ui, remote-pi’s daemons, the DHS pivot client being built in its own repository), and later pi-server. Two of our surfaces do the wrong thing there.

What pi provides (pinned to the installed @earendil-works/pi-coding-agent 0.85.1; the package is not in this tree, so the plan quotes it):

No file in this tree reads ctx.mode today; this plan introduces the one predicate that does.

Everything else we raise already crosses RPC correctly: the ask tool is select/input, the ADC-retry notices are notify, the status line is setStatus. The judge’s own asks - the permission system’s select/confirm - also cross correctly when forwarded; the problem is only that nothing bounds them.

Principle. Detect the host, not the human: isHeadless(ctx.mode) - a string mode other than "tui" - is the signal, available on every ExtensionContext and tool context. Outside the TUI, every dialog we own is bounded, and silence is the safe answer - a refused approval, a denied ask. Inside the TUI nothing changes: the pane, the permission system’s own dialog with its allow-always memory, no timeouts. pi’s ExtensionUIDialogOptions.timeout does the bounding: under RPC an unanswered select resolves undefined and an unanswered confirm resolves false (rpc-mode.js createDialogPromise); we never build a timer of our own.

1. Plan approval outside the TUI (plan-tools.ts). askApproval branches on toolCtx.mode: "tui" → the pane as today; otherwise hostApproval: the plan is already in the transcript (onUpdate renders it before any ask); a notify carries the review’s one line when there is one (matchingPlanReview: verdict, reviewer, edited since); then ui.select(title, exitPlanChoices(), { timeout: dialogTimeoutMs }). A select answer goes through interpretExitChoice unchanged. An undefined outside the TUI is no answer, not keep planning: exitPlanMode returns a distinct refusal - "no approval from the host within N min; staying in plan mode" - and never calls ui.input. A genuine Keep planning choice still asks for feedback, with the same timeout. Fail-closed is unchanged: nothing but an explicit approve option approves.

2. Gate defers at a headless host (new packages/pi-modes/host-ask.ts, wired in judge-wiring.ts adjudicateAsk). After authorizeAsk returns, when the verdict is defer and modes.lastCtx()?.mode is not "tui": confirmAtHost(ui, ask, verdict, timeoutMs) calls ui.confirm(title, body, { timeout: gateTimeoutMs }) with a title naming the tool and a body carrying the command or path preview (capped), the mode, and why it was deferred (the source and pattern the verdict carries). true → { kind: "allow", source: "host" }. false → { kind: "deny", source: "host", reason: "denied by the human at the host" }. Silence resolves false too, so the two are told apart by elapsed time against the timeout: at or past it → { kind: "deny", source: "unattended", reason: "no answer from the host within 30 s; run the session interactively to approve, or allow the pattern in the mode’s rules" }. gateTimeoutMs: 0 denies without asking (an operator’s "never wait"). The permission system receives allow or deny - both legitimate authorizer answers - and never a defer from a headless session. recordVerdict counts a host allow as allowed and the two denies as denied; the trace carries the new sources. authorize.ts is untouched: it stays pure and TUI-agnostic; the host step is the wiring’s.

3. ask outside the TUI (command-wiring.ts). The AskUi seam widens: mode: string beside hasUI, and select(title, options, opts?) / input(title, placeholder, opts?) gain the options parameter - today the interface types them without one, so the timeout cannot be passed until it does. askHuman passes { timeout: dialogTimeoutMs } when headless and nothing inside the TUI; a timeout reads as no answer, which interpretAnswer (ask-tool.ts:60) already renders.

4. Trace and attribution (trace.ts, judge-wiring.ts). Two new sources, additive:

5. Two tunables (config.ts, modes.json). A new block on ModesConfig, resolved by one helper hostTimeouts(config) so no caller reads it raw. Validation needs a nonNegativeInteger check: ConfigCheck has nonNegativeNumber (config.ts:269) and no integer form. Not doctrine: waits, like reviewTimeoutMs.

6. The proof (tools/consumer-sim.mjs, a live() check). With the packed distribution installed and an overlay gadhs-pi-modes.json setting unattended.gateTimeoutMs to 3 000, dialogTimeoutMs to 3 000 and highConsequence: ["git push*"] on auto, spawn pi --mode rpc from the scratch repo, write two prompts over stdin - one that runs git push --dry-run, one that calls enter_plan_mode then exit_plan_mode - and never answer any extension_ui_request. Pass when: an extension_ui_request with method: "confirm" was emitted, the matching tool result carries the unattended deny reason, and agent_end arrived within the wait plus a margin; and for the plan, a select request with timeout: 3000 was emitted and the tool result carries the "no approval from the host" refusal. The check reads stdout as strict JSONL (LF only, per docs/rpc.md), fails on any hang past 120 s, and is skipped under --no-model like the other live checks. It rides in the tag pipeline’s rehearse job only through its pack-based run before the tag, as every live check does.

7. Docs. modes.adoc: a section Headless hosts (RPC) under the talking-to-the-human section - what changes outside the TUI, what does not, the two sources in the trace. tuning.adoc: the unattended block beside the other knobs. security.adoc: the posture (silence is deny; a headless session never defers to a human it cannot reach), the two residuals (the permission system’s own ask rules on the excluded surfaces still prompt without us - the seed keeps them allow and reconcile advises; allow-always is unavailable from a host since we return one-shot decisions), and one doctrine paragraph: delegation goes through the gate; a tool that injects into another session as the user (remote-pi’s mesh agent_send) is out of policy for the agency distribution; and the misattribution residual - a human’s false landing exactly at the deadline is recorded as unattended. A new page remote.adoc under Operations (nav beside local-dev): the supported remote workflows - VS Code Remote-SSH and code tunnel with pi in the terminal, ssh + tmux from a phone (Termius, Blink) over the agency VPN, both carrying the whole distribution unchanged; messenger bridges and remote-pi as personal-use tools whose transcripts transit a third party and whose dialogs stay at the desk; the pivot project as the first-class path. CHANGELOG.adoc.

The TUI: pane, permission-system dialog, no timeouts, no new notices. authorize.ts and its order. The permission system, consumed unmodified. hasUI === false hosts (print, json): NO_HUMAN_REFUSAL and NO_HUMAN_ASK as today - a host with no dialogs at all is not a host to wait on. The battery, the eval corpus, the judge prompt. Nothing crosses the event bus: pi offers no hook to mirror a dialog to a sibling extension, and that remains an upstream ask, not ours.

Fail-open - a host answer misread as allow. confirm returns a boolean; only true inside the wait allows; every other outcome denies. The property test in U1 holds it.

Hang - a dialog without a timeout outside the TUI. The grep-able invariant: outside the TUI every ui.select/confirm/input we make passes timeout; the consumer-sim check is the live proof that a headless session ends. The permission system’s own prompt is not ours to time - and after this change it is never reached from a headless session, because we no longer return defer there.

Hang, by wrong host detection. One predicate, isHeadless(mode), is typeof mode === "string" && mode !== "tui"; every branch uses it and nothing else. So: "tui" is the terminal; any other string - rpc, json, print, or a host pi adds later - is headless and gets timeouts, never a hang; a missing mode (a pi that stopped reporting it) is treated as the terminal, which is today’s behaviour - the known state rather than a new one - and the consumer-sim check would go red on such a pi.

Misattribution (fail-closed) - silence told as a human’s no, or a human’s no told as silence. The two denies differ in source and wording; elapsed time against the deadline decides; a host that answers false exactly at the deadline reads as unattended. Both are denies, so the direction is safe; the residual is recorded in security.adoc.

Fail-closed by design, but unusable - an approval given 30 s. Approvals and ask use the dialog wait (10 min), not the gate wait; the tunables are separate for this reason.

Silent regression - the coverage bar. pi-modes holds 97/90 as thresholds; every new branch above has a named test, so the gate stays green or says why.

Scope. remote.adoc and the delegation-doctrine paragraph are not headless mechanics; they are in this plan because the operator decided both in the same session as the mechanics (2026-09-14) and because the feature is only usable if developers are told which remote paths carry the distribution and which do not. They ship as docs in U2 and add no code.