stablyai--orca/docs/reference/terminal-query-authority.md

Terminal Query Authority

Status: Shipped — Phase 5 of the terminal model/view architecture, kill switch terminalModelQueryAuthority (default on). Builds on terminal-model-view-contract.md (this phase amends invariant 6), terminal-side-effect-authority.md (Phase 3), and the Phase-4 hidden-delivery gate (src/main/ipc/pty-hidden-delivery-gate.ts).

Problem

Phase 4 drops renderer-bound bytes for hidden-gated PTYs after model ingestion (src/main/ipc/pty.ts:1426,1515, src/main/ssh/ssh-relay-session.ts:931). Queries embedded in dropped bytes get no reply: DA1 (ConPTY 1.22+ blocks waiting for it — terminal-conpty-device-attributes.ts:22), CPR probes hang TUIs, OSC 10/11 leaves claude /theme blind while hidden. The pre-Phase-4 hidden skip latch had the same hole (only mode 2031 and the 10s codex startup window answered), so this is not a regression — it is the long-standing gap this phase closes.

Contract invariant 6 ("the model must never answer queries") was written against a real bug: the daemon emulator replying ahead of the renderer with default-xterm values (the OSC-11 default-black-background race, headless-emulator.ts:86-97, pinned by session.test.ts:163-190). The danger was never "the model answers" — it was two answerers for the same bytes, one of them with wrong values. Phase 5 keeps the singularity and fixes the values.

Decision: the delivery decision is the reply decision

Main answers a query iff main dropped the chunk that carried it. The same per-chunk hidden-gate predicate (shouldDropHiddenRendererPtyData) that decides renderer delivery decides reply ownership, evaluated once, synchronously, at ingestion:

• Visible/unmarked PTY → chunk delivered → renderer xterm auto-replies via Terminal.onData → transport.sendInput, unchanged.
• Hidden-marked, no delivery interest → chunk dropped → main answers from the runtime headless emulator, via the provider input path (provider.write, same path as pty:write; daemon shell-ready write gating and the SSH relay write apply unchanged).
• Replayed/seeded/snapshot bytes → answered by no one (replay guards on both sides).

This is structurally exactly-one-responder: a chunk is delivered or dropped, never both, and each side only answers bytes it actually parsed live. The mark/unmark ordering, unhide-before-restore, and restore-marker IPC all exist from Phase 4 and are reused, not duplicated.

Rejected alternatives:

• Fact-based renderer replies per query class (the mode-2031 pattern generalized): needs a main-side detection grammar per query, a fact round trip per reply, and the renderer cannot answer CPR/DECRPM anyway — the emulator is the only state for a hidden pane. The 2031 fact stays because it is subscription registration, not a state query.
• Emulator always answers: re-creates the OSC-11 double-reply race for visible panes. Never.

Mechanism: forwarded emulator onData, not a new grammar

HeadlessEmulator has onData wiring behind a per-write capture flag. For static and model-state queries, xterm core is the query grammar: the runtime emulator runs the same xterm version with equivalent options as the renderer pane, so main's reply set equals the visible renderer's by construction — verified empirically against the bundled headless build: DA1/DA2, DSR 5n, CPR, DECRPM (including unknown-mode 0), DECRQSS (including DECSCUSR from cursor options), XTVERSION, kitty CSI ? u all reply; XTWINOPS (windowOptions stays default-off) and XTGETTCAP stay silent, matching visible behavior today. The headless build has no theme service: OSC 4/10/11/12 queries and DSR ?996n return nothing even with the theme option set, so the view-attribute class is answered by responder-registered parser handlers instead (below) — never by core defaults.

Forwarding predicate, captured per chunk in OrcaRuntimeService.onPtyData and attached to the emulator writeChain link (the mark can flip between ingestion and an async write; the decision must not be re-read at reply time):

1. gate enabled (terminalMainSideEffectAuthority and terminalHiddenDeliveryGate both on) AND new kill switch terminalModelQueryAuthority !== false;
2. the chunk was hidden-dropped for this PTY (shouldDropHiddenRendererPtyData — same module state, same tick as the drop sites);
3. the write is live PTY data — never seedHeadlessTerminal, maybeHydrateHeadlessFromRenderer, option pushes, or any snapshot replay (main-side replay guard, mirror of the renderer's replay-guard.ts);
4. no remote view subscriber is attached to the PTY (runtime terminal-RPC subscriber records / mobileSubscribers): a mobile/web/remote-desktop xterm receiving the multiplexed stream answers with view authority, exactly like a visible local pane. Legacy JSON terminal.subscribe streams do register as view subscribers and suppress, even when the consumer is a read-only watcher — deliberately conservative, because the stream may feed an older live xterm view and a withheld reply (the pre-Phase-5 status quo) is strictly safer than a double reply. Consumers that never register a stream (CLI terminal.read, automation observers) do not suppress — they also do not answer; that bounded no-reply case matches today's behavior.

Mobile streams preserve that singularity across snapshot startup and multiple views. The mobile WebView suppresses onData during snapshot replay, then enables replies at an explicit live-output boundary. Clearing the WebView drops that replay queue and resumes live reply authority immediately. If a live query arrived while the initial snapshot was being built and its output sequence is covered by that snapshot, runtime RPC re-emits only the bounded query sequence after the snapshot; ordinary covered output stays deduplicated. terminal.send accepts the resulting inputKind: query-reply only from the earliest active phone-fitted mobile subscriber while mobile owns the terminal driver. Earliest is determined by preserved subscribedAt, so a soft-leave resubscribe does not change reply ownership; passive desktop-mode watchers are excluded. Peer phones are rejected, the next subscriber is promoted on unsubscribe, and desktop parser and capability handlers stay silent until desktop retakes the driver. Mixed versions: hosts advertise terminal.query-reply-input.v1; a mobile client never forwards replies to a host that lacks it, because such hosts strip inputKind and would treat the bytes as floor-taking shell input. Residual: a desktop→mobile driver handoff has a bounded double-reply window until the async driver-change event reaches the desktop renderer's cached driver map (isPtyLocked).

Everything the emulator emits outside a forwarding window is discarded, which also swallows unsolicited core emissions (e.g. native 997 color-scheme pushes triggered by option mutations).

Reply classes

Class	Queries	Answer source
Static	DA1 CSI c (ConPTY override below), DA2, DSR 5n, XTVERSION, DECRQM unknown → 0, kitty CSI ? u	xterm core constants + kitty flag state
Model-state	CPR 6n/?6n, DECRPM mode table (?1 ?6 ?7 ?25 mouse ?1004 ?1006 ?1016 ?1049 ?2004 ?2026, insert), DECRQSS DECSTBM/DECSCA/SGR, kitty flags	emulator buffer/mode state — for a hidden pane it is the only state, hence authoritative
View-attribute	OSC 4/10/11/12 ;? queries, DSR ?996n	responder parser handlers + renderer attribute push (below); silent until first push
View-attribute (via options)	DECRQSS DECSCUSR, DECRQM 12	xterm core, from pushed cursorStyle/cursorBlink emulator options
Silent	XTWINOPS, XTGETTCAP, ?15n/?25n/?26n/?53n	nobody, visible or hidden
Mode 2031	DECSET 2031 subscribe	unchanged in Phase 5: main emits the 2031-subscribe fact, the renderer replies (handleHiddenMode2031SubscribeFact, pty-connection.ts; parked watcher fact callback). Emulator-native 2031/997 output is suppressed by the forwarding guard

View-attribute bridge

Renderer→main push, pty:terminalViewAttributes — one global snapshot, not per-PTY: the composed terminal ITheme (from applyTerminalAppearance, terminal-appearance.ts), terminalCursorStyle, terminalCursorBlink, and the resolved color-scheme mode (resolveTerminalColorSchemeMode — the same source as the existing hidden 2031 reply). Pushed on renderer startup and on every theme/settings apply.

Main consumes it two ways:

• cursorStyle/cursorBlink are applied to every runtime emulator's options inside the replay guard; xterm core then answers DECRQSS DECSCUSR and DECRQM 12 with renderer-true values (verified working headless).
• Palette and color-scheme replies come from responder-registered parser handlers on the emulator (registerOscHandler 4/10/11/12, registerCsiHandler for DSR ?996n), because the headless core cannot answer them. The OSC handlers see SET payloads too, so runtime OSC 4/10/11/12 mutations (and 104/110/111/112 resets) from the byte stream are tracked per PTY and layered over the pushed base palette — matching what the renderer's theme service reports for a visible pane.

Staleness rules: replies use the last push; a theme flip is stale for at most one IPC hop (subscribed TUIs are corrected by the 2031/997 flip push). Before the first push main answers no view-attribute query — a fabricated default would resurrect the default-black OSC-11 bug; silence is the documented hidden status quo.

Kitty keyboard flags

vtExtensions.kittyKeyboard: true is enabled in HeadlessEmulator, matching buildDefaultTerminalOptions (pane-terminal-options.ts:50). Risk is low: for the write-only daemon use, keyboard state never alters serialization; the change only makes the emulator parse CSI =/>/< u pushes instead of ignoring them, and lets the responder answer CSI ? u with the flags the hidden app actually pushed. Snapshot parity: add kittyKeyboardFlags to TerminalModes for emulator re-seed parity only. rehydrateSequences must not push kitty flags into a renderer xterm — POST_REPLAY_REATTACH_RESET's deliberate kitty reset (stale CSI-u Ctrl+C hazard, terminal-replay-cursor-state.test.ts) stays authoritative. Slice 3 wires the re-seed consumer: the daemon warm-reattach snapshot threads modes.kittyKeyboardFlags through the spawn result into seedHeadlessTerminal, which applies them to the fresh runtime emulator via its own CSI = flags ; 1 u parse (outside any forwarding window), so hidden CSI ? u reports the flags the hidden app actually pushed. Paths without a snapshot (cold restore spawns a fresh shell) answer ?0u; protocol-conformant programs re-push.

ConPTY DA1 variant

The provider kind is known main-side: mirror isLocalNativeWindowsPty (windows-pty-compatibility.ts:59) from the spawn record (local/daemon provider, win32, not WSL). For such PTYs register a CSI c override on the emulator parser (the main-side twin of installConptyDeviceAttributesHandler) replying CSI ?61;4c, still gated by the forwarding predicate. The override is installed at emulator creation and retrofitted when the spawn mark lands (daemon stream data can create the emulator before the awaited spawn response marks the PTY). ConPTY blocking on a missing DA1 is a spawn-time hazard; the hidden-at-spawn loss window is closed by the slice-3 initiallyHidden spawn flag (races section).

Suppression: when main never replies

• Visible or unmarked PTY (chunk was delivered).
• Renderer delivery interest registered (chunk was delivered to a sidecar).
• Remote-runtime (remote:) PTYs — never markable (isHiddenDeliveryGateManagedPty), bytes never transit local main.
• Remote view subscriber attached (mobile/web/remote desktop owns replies).
• Seed/hydration/snapshot writes into the emulator, and option pushes.
• Kill switches off — no marks exist, and terminalModelQueryAuthority is an independent off switch for the responder alone.
• The daemon emulator: never, under any setting. The responder lives in main's runtime only; session.test.ts:163-190 stays pinned verbatim.

Transition races

Worst cases, per direction:

• visible→hidden: chunks delivered between the visibility flip and the mark landing in main are hidden-skipped by the renderer write path without query scanning. No reply, no duplicate — identical to the pre-Phase-4 hidden skip behavior, bounded by one renderer→main IPC hop. After the mark lands, main answers everything it drops.
• hidden→visible: unmark consumes the drop latch and emits the restore marker; the snapshot replay is replay-guarded, so queries main already answered are never re-answered from the snapshot; post-unmark live chunks are answered by xterm once (restore-queued live chunks reply late, not twice).
• Split queries across the drop/deliver boundary: neither parser saw the whole sequence → no reply; the restore marker resets renderer cross-chunk state and replay hygiene resets the parser. At-most-once holds.

Safe-side rule per class: duplicates are structurally impossible (one decision point per chunk); where the race costs anything it costs a missing reply. That is acceptable for state queries (DSR/CPR/DECRPM — TUIs re-probe or tolerate silence, as they did for every hidden pane before this phase). The one blocking-on-no-reply sequence, ConPTY DA1, only fires at spawn. A visible pane answers it from the renderer xterm. A PTY spawned hidden previously had no answerer until the renderer's hidden mark landed in main (one IPC hop after spawn). Slice 3 closes that window with the initiallyHidden spawn-record flag: the renderer declares hidden-at-spawn on pty:spawn (never for remote-runtime transports), and main marks the PTY hidden before the first byte — pre-spawn for daemon-host sessions whose id is minted up front, immediately after provider.spawn resolves otherwise — so the gate and responder own queries from byte one. The pane's first visibility sync then re-marks or unmarks through the existing Phase-4 machinery (unmark emits the restore marker for any spawn-window drops).

Invariants

1. Exactly one party may answer any query, chosen by the chunk's delivery decision: delivered → the consuming live view's xterm; dropped → main's model responder; replayed/seeded → no one. The decision is captured once, synchronously, at ingestion.
2. Main answers only from live PTY bytes parsed by the runtime emulator — never from snapshot, seed, hydration, or option-push writes.
3. View-attribute answers are renderer-true or absent: no reply is ever fabricated from emulator defaults (the OSC-11 lesson).
4. The daemon emulator stays write-only; daemon subprocess query writes stay zero (session.test.ts pins are permanent).
5. Reply parity is structural for static and model-state classes: same xterm core, equivalent options, no hand-rolled grammar — the only overrides are the documented ConPTY DA1 variant and the view-attribute parser handlers the headless core cannot serve.
6. Remote views keep view authority; main yields whenever a remote view subscriber is attached. When multiple desktop/mobile views coexist, the terminal driver and server-side mobile election keep one reply writer.

Contract amendment — terminal-model-view-contract.md invariant 6 is replaced by:

6. Terminal query authority is singular and structural: the party that writes a chunk into a live terminal answers its queries. Visible renderer and remote views keep xterm authority. Chunks dropped by the hidden-delivery gate are answered exactly once by the main model responder, from runtime-emulator state plus renderer-pushed view attributes. Replayed, seeded, or snapshot bytes are answered by no one. The daemon emulator never answers.

The contract's test bullet "headless tracking does not answer DA, DSR, OSC 11, or theme-sensitive queries" splits into: daemon emulator never answers (unchanged pins) / runtime responder answers only hidden-dropped chunks. The side-effect authority matrix row "DECSET 2031 reply — query authority stays with the view (contract invariant 6)" gains a pointer here; its reply path is otherwise untouched in this phase.

Test strategy

• Responder unit tests beside orca-runtime.test.ts: marked vs unmarked vs interest-suppressed; each reply class; seed/hydrate silence; remote- subscriber suppression; ConPTY DA1 variant; kill-switch off; mark flip between ingestion and async emulator write (captured decision wins).
• Parity harness: shared query byte fixtures through a renderer-configured xterm (onData capture) and through the responder; assert byte-identical replies for static + model-state classes, and for view-attribute classes after an attribute push.
• session.test.ts:163-190: assertions stay; the comment is updated to name the main responder (not "the renderer") as the hidden answerer.
• E2E: hidden claude /theme reports the configured theme; hidden TUI blocked on CPR/DA unblocks while gated; reveal shows no stray reply fragments (?1;2c, rgb: …) on the prompt; Windows ConPTY golden and terminal-hidden-view-parking.spec.ts stay green.

Cut-offs (shipped as three stacked slices)

1. Responder core. Emulator onData wiring + per-write capture + main replay guard; kitty flag enable (+ TerminalModes.kittyKeyboardFlags); static + model-state classes; ConPTY DA1 override; remote-subscriber suppression; terminalModelQueryAuthority switch; unit + parity tests. Main-only — no renderer change. Ships the DA1/CPR/DECRPM unblock.
2. View-attribute bridge. pty:terminalViewAttributes push, cursor option application under the guard, responder OSC/DSR parser handlers with per-PTY palette-mutation tracking, silent-until-push rule, /theme e2e.
3. Contract alignment. Invariant-6 amendment in the contract doc, test bullet split, session.test.ts comment, side-effect matrix pointer, and the Phase 6 prerequisites below recorded as accepted.

Phase 6 (delete skip grammar + startup window): prerequisites from this design

Phase 6 is shipped: the renderer hidden-skip eligibility grammar and the 10s codex startup renderer-query window are deleted. Kill-switch-off hidden panes fall back to the pre-grammar path — hidden bytes ride the bounded background scheduler queue; overflow latches the model-snapshot restore — and never run a per-chunk content scan.

Accepted and shipped in slice 3 (except where noted):

• Mark-before-first-byte (shipped): panes spawned without a visible view are hidden-marked at spawn via the initiallyHidden flag on pty:spawn (spawn-record flag, not a renderer round trip) so startup queries — including ConPTY's blocking DA1 — are main-owned from byte zero. Phase 6 removed the codex exclusion with the window: codex spawns are main-owned from byte zero too, the responder answering their startup probes.
• Attributes before spawn (shipped): the renderer pushes composed view attributes once at app start (right after settings load, before terminal reconnect/spawn), so spawn-time view-attribute queries no longer fall into the silent-until-push rule. Per-pane appearance applies keep re-publishing through the same deduped publisher.
• Daemon shell-ready write gating (verified): responder replies through ptyController.write → daemon Session.write are QUEUED pre-ready, never dropped, and the queue flushes at the shell-ready marker or the 15s SHELL_READY_TIMEOUT_MS bound (session.ts). The codex window was removed with hosted ConPTY golden coverage, unit DA1 parity, and the kill switches as the safety net; explicit spawn-time e2e on Windows daemon PTYs remains worth adding.
• With the skip grammar deleted, every chunk is either written to a live xterm or dropped — the delivered-but-skipped no-reply gap disappears and the only remaining loss window is the mark IPC race.
• 2031 consolidation (optional follow-up): move the subscription registry into the responder (the headless core cannot serve 997 pushes any more than it can ?996n) and push 997 flips from the attribute cache, retiring the 2031-subscribe fact reply, the parked responder, and the parked-tab theme-flip gap.