@with-logic/elwood 0.1.2 → 0.2.0

package/prd/05-api/5.10-questions.md

@@ -0,0 +1,117 @@
+## 5.10 Native questions
+
+`ElwoodAgentSession`, both raw adapter interfaces, and both lazy session classes
+expose `listQuestions(): Promise<readonly ElwoodQuestionRequest[]>` and
+`answerQuestions(requestId, answers, options?): Promise<void>`. These controls
+bypass the ergonomic turn queue; answering never creates a user turn or finishes
+an existing `send`/`stream`. Lazy controls start the session before delegation.
+
+A request has readonly `id`, `agent`, `delivery` (`blocking` or `queued`), and
+ordered `questions`. Each question has readonly `id`, `prompt`, optional `header`,
+`options` (ordered readonly `id`, `label`, optional `description`), `selection`
+(`single`, `multiple`, or `none`), `textMode` (`none`, `alternative`, or
+`additional`), and `supportsSecretInput`. IDs are opaque and scoped to the live process.
+`alternative` permits text instead of options; `additional` permits text alongside
+options. Capabilities describe only supported native input, not model intent.
+
+The snapshot lists currently available requests in discovery order and is deeply immutable.
+Redraws and mirrored source records retain identities. A semantic replacement
+closes the old request as unavailable and raises a new ID. No question or answer
+is stored in Elwood session state or restored by Elwood on resume.
+
+`question` events carry `elwoodSessionId`, `agent`, `request`, and `phase`
+(`raised` or `closed`). Closed events also carry `reason`: `answered`,
+`cancelled`, or `unavailable`. `answered` requires native acceptance evidence;
+`cancelled` requires native dismissal evidence; withdrawal, turn end, replacement,
+and shutdown use `unavailable` when no stronger evidence exists. Matching
+normalized activities have `kind: "question"`, `source: "terminal"`, the same
+structured event in `question`, and a phase label. They contain request prompts,
+not answer values. Existing raw hook/transcript observations remain unredacted.
+Question activity is telemetry and never ergonomic answer text. The request, event
+and normalized activity agents agree, including in their public discriminated types.
+
+Each answer contains `questionId`, optional ordered `optionIds`, and optional
+`text`. Exactly one answer for every question in the selected request is required.
+Unknown/duplicate IDs, unsupported text, multiple options on single-select,
+empty answers, and control-bearing text reject as `invalid_question_answer`
+before any write. The complete validated answer batch is limited to 8 MiB: the sum of UTF-8 bytes
+in its question IDs, selected option IDs and text. JSON syntax and unknown fields
+do not count toward this limit. Malformed UTF-16 is rejected. Multiline text is safely bracketed-pasted. An unknown, closed,
+retired, or previous-process request rejects as `question_not_found` before input.
+
+`options` accepts optional positive finite `timeoutMs` (default 20,000) and
+`signal: AbortSignal`. Long deadlines use bounded timer chunks. A single answer transaction owns the physical question
+input lane; overlapping calls reject as `question_answer_failed` before reading
+caller answer or options fields, including stale IDs and invalid batches. When
+no attempt owns the lane, unknown or retired IDs reject as `question_not_found`
+before input. It operates
+even while an ordinary queued writer or ergonomic turn is waiting. Every write
+revalidates current completed native frames, live request ownership and caller
+intervention. Raw keys and interruption revoke the transaction. Timeout,
+cancellation, changed/unsupported layout, rejected input and uncertain acceptance
+reject with content-free `question_answer_failed`; a submitting Enter is never
+blindly retried. Closing the session prevents further writes. Failures may expose
+only fixed `details.category` categories: `frame_wait`, `adapter`, `terminal_write`,
+`native_acceptance`, or `aborted`; they never retain raw exceptions or answer text.
+
+A failed attempt that has not started a physical write can remain answerable. If
+input may have reached the CLI and native acceptance is unconfirmed, the API
+request closes once as `unavailable` and disappears from snapshots. Retrying its
+ID rejects as `question_not_found` before input. Elwood retains the native identity
+and holds ordinary automation until correlated native closure, turn end or
+shutdown releases it. Redraws, changed metadata for that same reserved identity
+and late write completion cannot republish or reauthorize the request. Native
+closure releases this reservation silently, without a second question closure.
+Both the physical write and the correlated native reservation must settle before
+ordinary input can resume, whichever settles first. The API closure alone does
+not mean the CLI is ready for ordinary input.
+
+Pending requests and native question editors hold ordinary prompt, command,
+loop and login writes. Native lifecycle status remains independent of queued
+question availability. Unknown question layouts are hold-only, observable through
+the existing terminal/attention surfaces, and never receive guessed keys.
+
+Claude `AskUserQuestion` hooks supply grouped request metadata. A request is
+published only when its matching native questionnaire is visible; direct caller
+hook answers and denials retain precedence and do not create a phantom pending
+request, even if a matching stale screen is still visible. Initial hook activity
+keeps its existing timing; discovery waits for that exact caller decision and
+then a fresh completed native paint.
+Overlapping Claude hooks retain independent native tool-use identities and exact
+caller outcomes, including out-of-order resolution and completion. A pending
+outcome withholds only its matching candidate; it cannot suppress discovery of an
+unrelated resolved request. Matching `PermissionRequest` mirrors retain the
+original candidate even when their hook IDs differ. A native panel that matches
+multiple independent candidates grants no answer authority; ownership remains
+held until native evidence disambiguates it. ID-less completion requires one
+uniquely matching candidate and cannot retire an ambiguous group.
+The adapter supports the captured single-choice, checkbox, tabbed sequential
+question and review stages, with alternative free text. It requires a recognized
+initial first-question stage; a human-navigated unsupported partial stage rejects
+safely. Only a matching `AskUserQuestion` completion acknowledges the whole
+request. A supplied native completion ID must match the active request; without an ID,
+ordered question definitions must match its prompts, headers, selection modes and
+ordered option labels/descriptions. Unrelated tools or mismatched question
+metadata cannot acknowledge, cancel or retire that request. The standard hook
+timeout is unchanged and never waits for a human answer.
+
+Codex native text acceptance normalizes CRLF and CR to LF, then trims Rust
+Unicode White_Space at both ends (U+FEFF is retained); interior whitespace is
+preserved. Queued selected labels are trimmed; modal selected labels remain
+exact and optional notes use the text normalization. Long, clipped, multiline and literal placeholder text is accepted only while
+the submitted text remains in the same native question editor. The complete
+committed native answer must match the submitted answer before success.
+Unsupported or opaque Codex native identities reserve ordinary automation until
+explicit native turn end; raw human terminal input remains available.
+Codex metadata budget overflow emits one content-free `question_automation_disabled`
+warning and normalized warning activity per session, then disables automation.
+
+A successful Claude final submission awaits matching native completion through
+a newly empty composer. An interrupted, unconfirmed answer retires the API
+request while retaining its native identity and input hold until native closure;
+a later acknowledgement releases that reservation without another closure event.
+
+Question notification failures are contained without changing request state or
+native input holds. The first failed question or companion question-activity
+observer in a live session produces the content-free `question_observer_failed`
+warning and normalized warning activity specified in [§5.4](5.4-events.md).

package/prd/05-api/5.3-claude-session-api.md

@@ -145,7 +145,24 @@ arrives (a missing or failed hook bridge) must not starve readiness forever, so
 initial readiness fires no later than a fixed deadline after the first rendered
 frame even when neither a hook nor (on cold start) any composer signal arrives.
 Subsequent turn readiness comes from
-completion signals such as an unblocked `Stop` hook. Queued messages are
+completion signals such as an unblocked `Stop` hook. A Stop captures the current
+queue-backed caller submission before notifying observers or invoking handlers. If a newer
+`sendPrompt`, `sendMessage`, or `sendGuidance` prompt is physically submitted while
+that Stop is being handled, the older Stop
+MUST NOT mark the newer submission ready or release its queued successor.
+Hook-observer failure diagnostics publish before this final generation check and
+readiness transition, so their callbacks share the same submission boundary.
+Retained rendered work, idle, or interrupt frames from before that physical
+submission MUST NOT complete it. Rendered idle completion requires fresh work
+after submission; a fresh interrupt banner absent at submission still completes
+without a working footer. A terminal with no received output has no prior banner;
+an incomplete or unverified prior frame does not establish absence. Guidance can
+steer an existing turn, but receives the
+same conservative rendered-frame boundary.
+Immediate input remains available inside Stop callbacks, including a handler
+that awaits `sendPrompt()`; waiting for Stop completion must not deadlock it.
+Blocked outcomes still retain the active turn, and failed-open callbacks use the
+same submission boundary as an ordinary unblocked outcome. Queued messages are
 submitted in FIFO order, one message per ready transition, so back-to-back calls
 do not accidentally paste multiple user turns into one active agent prompt. A
 queued `sendMessage` promise resolves when that message has been written to the
@@ -158,12 +175,31 @@ acceptance before an idle `ready` transition may complete a turn. A matching
 closes the cold-start deadline race: under load, Codex may repaint a boot spinner
 and composer after the deadline-released paste, swallow that paste, and otherwise
 look exactly like a completed empty turn. When `ready` returns without positive
-acceptance, Elwood waits the normal no-oracle quiet window and replays the same
+acceptance, and no awaited input writer still owns native recovery, Elwood waits
+the normal no-oracle quiet window and replays the same
 submission at the now-idle composer, at most twice. A still-unaccepted turn fails
 with `wait_timeout`; it never reports a false empty success. A positive acceptance
 arriving during the quiet window cancels recovery and lets the observed `ready`
 settle normally.
 
+The per-session control queue accepts at most **1,024 outstanding operations**
+and **8 MiB (8 × 1,024 × 1,024 bytes) of aggregate UTF-8 input text**, including
+its active physical operation. This shared limit covers queued messages, prompts,
+guidance, commands, exclusive controls, and loop-origin submissions. An admission
+that would exceed either limit rejects with `input_queue_full` before attachment,
+admission preparation, or terminal input; existing operations keep their order.
+Text is measured before paste sanitization. Image clones retain their separate
+§5.3 budget. Cancelling a waiting operation or physically settling an active one
+releases its reservation; cancelling an active write does not release capacity
+before that write settles. Physical loop completion releases capacity before
+`fired` observers run, while retaining queue ordering through the following
+running notification. Session close rejects waiting operations and releases
+their reservations; new calls on a closed session still reject with
+`session_not_running`, even if the queue was full. Direct `sendKeys`, terminal
+input, and interrupt remain available outside this queue. Capacity is a rejection
+boundary, not another unbounded waiting list. A loop whose admission is rejected
+follows the existing failed-submission retry/warning policy (§5.9), never `fired`.
+
 `sendGuidance` is the adapter-neutral intervention API. Before the session has
 ever reached semantic readiness, and while a blocking dialog is visible, it has
 the same readiness-safe behavior as `sendMessage`. During a real running turn
@@ -179,12 +215,118 @@ write can be consumed by the paste boundary — leaving the prompt staged in
 the composer, never submitted (long multi-line prompts such as personas hit
 this reliably). Elwood therefore writes the bracketed paste and the
 submitting Enter as separate PTY writes, with the Enter following after a
-short settle delay, and then confirms submission against the rendered
+short settle delay, and then observes the rendered
 screen: while the composer still shows staged content (Claude's
 "[Pasted text" chip; for Codex the paste's final line still in the
-composer), Elwood re-sends Enter a bounded number of times. A surplus Enter
-on an empty composer is a no-op on both CLIs, so the recovery cannot
-double-submit.
+composer), ordinary submissions may re-send Enter at most twice, over at most four observation
+attempts spaced one second apart after the first Enter. Only the completed,
+visible, idle composer at the native cursor can establish staged text; matching
+transcript text is insufficient. Working, hidden, incomplete, and unknown frames
+withhold Enter and consume an observation attempt, not a physical retry. A fresh
+positive empty-input observation retires that submission's recovery permanently;
+an empty frame retained from before its paste does not. Dialogs withhold recovery
+under the same observation bound. This bound does not shorten the initial
+submission's dialog wait.
+
+Working indicators alone cannot distinguish accepted work from startup or resume
+replay. A later verified idle staged draft may therefore recover, whether or not
+initial readiness has fired. Recovery does not infer acceptance from optimistic
+status or permanently remember a working indicator. A cached staged frame is not
+proof that the native CLI has not accepted the submission. Recovery therefore
+requires a completed native render received after the most recent attempted
+Enter, including a failed recovery write; moving the viewport or resizing alone
+is not a fresh render. This applies to text and image-only or whitespace drafts.
+Image chips qualify only inside the visible, idle, cursor-owned composer.
+
+Native `user_message` activity permanently revokes background recovery captured
+before a submission's paste and first Enter, including activity received while
+that physical Enter is pending. Optimistic caller-submitted status does not
+revoke recovery. This conservatively withholds further Enter; it does not prove
+correlation to a particular prompt, change the first-write promise, or release
+composer cleanup ownership.
+
+Initial and replay ergonomic submissions retain their queue slot and staged-draft
+cleanup ownership beyond the first physical Enter. They release only after a
+positive empty native input frame whose completed PTY output arrived after that
+Enter; changed geometry or a new empty-frame token without new output is not
+acceptance. Missing staged text, blank/partial output, and native submission
+activity alone cannot release a retained image or whitespace-only draft. Native
+activity revokes recovery Enter authority while the empty-input wait continues.
+Whitespace-only retry recognition is supported for Codex’s captured live advanced-cursor
+layout. Claude has no whitespace-only retry guarantee: an unverifiable whitespace
+draft remains cancellably held until positive empty-input acceptance or termination.
+Image-bearing whitespace submissions on both adapters retain image ownership.
+These submissions reuse the same staged-input, dialog, render-progress and
+physical-retry guards as ordinary recovery. Acceptance is checked immediately after
+Enter and on completed native render notifications, without ordinary recovery’s
+four-observation or one-second observation ceiling. Unchanged ambiguous or blocked
+frames do not cause recurring scans or timers; they retain cancellable ownership.
+Only fresh staged-input evidence schedules a paced retry or final observation.
+Pending render observations are shared, and timed-out or cancelled observers are
+removed without adding another reaction to the same pending render promise.
+After at most two recovery Enters,
+a fresh still-staged observation rejects with `wait_timeout`; the final Enter
+must be independently observed before acceptance or exhaustion. Ambiguous or
+blocked observations remain cancellable without a whole-turn deadline. Raw input
+revokes both automated retry and cleanup authority. While an initial or replay
+ergonomic submission awaits empty-input confirmation, raw takeover rejects it
+with `wait_timeout` and a submission-specific message; model picker operations
+retain their `model_automation_failed` diagnostic. Cancellation and session
+closure retain a pending physical write until it settles, then use the existing
+cleanup/error rules. Raw control submission promises retain their first-Enter
+contract; ergonomic consumer and physical-input lifetimes are specified in §5.8.
+
+Queued input MUST NOT be written into a screen Elwood has not observed (C-API-56).
+Terminal rendering is asynchronous (§4.1), so a blocking dialog can be received
+from the PTY before any rendered frame shows it. Before writing a queued paste,
+command text, submitting Enter, or recovery Enter, Elwood renders and observes
+every PTY byte it has already received, and only then evaluates the
+blocking-dialog hold; the write follows that decision before any further PTY
+output is delivered. Output received while that observation is in progress is
+part of it. When the received output cannot be observed — the PTY does not go
+quiet within one second, or any render has failed (no later output can prove the
+terminal model complete again) — the write is withheld
+exactly as if a dialog were visible and re-attempted; input is never written
+through an unobserved screen.
+
+The same rule binds Elwood's own NON-TRUST automated startup writes — the Codex
+update skip and its retries, and the Claude browser-tools decline. Each observes
+everything received and re-checks the settled frame before writing, so neither
+can reach a trust dialog that arrived while the previous screen was still
+rendering. A withheld automated write is silent: it is not a write failure,
+emits no `startup_prompt` activity and no warning, and the prompt stays
+answerable on a later frame while the session remains live. Claude browser-tools
+automation is permanently cancelled at disposal: no later retry, success activity,
+or write-failure warning is emitted (C-CLAUDE-22). The trust responder is exempt from this veto,
+because answering a trust dialog is precisely its role. Cancellation
+interrupts the wait. The compact recovery Enter and the cancellation cleanup keys
+follow the same rule, and the compact recovery Enter is cancelled as soon as a
+later queued operation dispatches, because the composer then belongs to it.
+Raw input through `sendKeys`, `terminal.sendInput`, or `xterm.input` also cancels
+remaining recovery Enters for the staged paste: the caller now owns that draft.
+`sendKeys` remains the explicit raw-input escape hatch and
+does not wait.
+
+A failed or cancelled queued submission retains ownership of its staged draft
+until cleanup or raw input. Cleanup never writes through an unsafe frame;
+if held, it is deferred until the next queued operation, before that operation
+attaches images or writes input. This includes cancellation after attachment
+succeeds but before text submission. A rejected cleanup write retains the hold
+and rejects the successor with `wait_timeout`; it cannot append to the stale draft.
+A physical clear write is not confirmation: cleanup requires a fresh completed
+native empty-composer observation within one second. An unchanged pre-clear
+frame, unsafe observation, or expiry retains the draft for a later safe attempt.
+Raw input through `sendKeys`, `terminal.sendInput`, or `xterm.input` revokes this
+cleanup authority: the caller now owns the draft, and subsequent queued input
+has its ordinary semantics. Later failed staging cannot reacquire cleanup authority
+over caller-owned text; a successful submitting Enter establishes a new cleanup
+baseline only if no raw input intervened during that submission. Cleanup precedes
+caller-turn publication and readiness consumption, so a failed clear leaves those
+unchanged. Exclusive model/login deadlines include the deferred cleanup wait,
+without revoking an already-started operation’s authority to cancel its own dialog.
+Closing drops deferred cleanup without waiting for a
+dialog or writing later cleanup keys. Clipboard restoration does not wait for
+this deferred composer cleanup.
 
 Message text is DATA, never terminal control. `sendPrompt`, `sendMessage`, and
 `sendGuidance` submit caller- or model-controlled text as the content of a
@@ -226,13 +368,17 @@ rather than a raw type error.
 Image attachment is CONFIRMED, never assumed. For each image Elwood waits for the
 CLI's `[Image #N]` chip to appear in the composer region; if the chip is not
 observed within the per-image confirmation timeout (10 s), or the OS clipboard
-cannot be read or written, the call rejects with `image_attach_failed` and Elwood
+cannot be read or written, or terminal rendering permanently fails, the call
+rejects with `image_attach_failed` and Elwood
 submits NO text and attaches no further images. A confirmation timeout therefore
 surfaces (e.g. on TUI-wording drift) rather than silently degrading to a text-only
 turn. A session that TERMINATES mid-attach rejects the call with
 `session_not_running`, like any other queued operation. Chip confirmation is
 scoped to the composer region so unrelated on-screen text containing a literal
-`[Image #N]` cannot spoof it.
+`[Image #N]` cannot spoof it. The baseline chip count is read only after received
+output has settled, immediately before the image key is sent. A permanent render
+failure rejects the attachment without waiting for session closure; Codex restores
+its clipboard text and releases the clipboard lock before that rejection settles.
 
 The attach path is adapter-specific because the two CLIs ingest images
 differently, and this is a version-coupled TUI behavior verified against real
@@ -274,10 +420,9 @@ Third, session close during an in-flight attach rejects the operation and blocks
 the text write, but does not join the attach's temp-cleanup and clipboard-restore
 finalizers; on an abrupt teardown those may not complete before process exit
 (clipboard restore is already best-effort, and temp files fall to OS reaping).
-Fourth, composer isolation on a failed attach is best-effort: when an attach
-fails after staging began, Elwood clears the composer draft (kill-to-line-start
-plus kill-to-line-end) so the rejected images do not leak into a later caller's
-turn, but it does not run an adapter-specific transactional confirm-and-restore
+Fourth, failed-attach cleanup follows the owned, deferred cleanup rule above.
+The clear uses kill-to-line-start plus kill-to-line-end, but does not run an
+adapter-specific transactional confirm-and-restore
 of the exact prior composer baseline; a partially-staged draft that those keys do
 not fully clear could still carry over (mitigated because a caller does not
 interleave submissions on one session). Fifth, chip confirmation identifies the
@@ -305,8 +450,9 @@ adapter also has a documented interrupt end banner (Claude renders
 "⎿ Interrupted", Codex renders "Conversation interrupted") whose appearance
 fires the turn-end transition even when the working token was never visible.
 Together the sources cover every width. Turn start is a rendered-state signal:
-the on-screen working token where it fits, plus the OSC window-title braille
-spinner (C-TURN-05) which is width-independent and reveals a running turn even
+the on-screen working token where it fits, plus the OSC window-title working
+spinner (C-TURN-05): the braille range on both adapters and Claude's observed
+`◐ ` prefix. This signal is width-independent and reveals a running turn even
 when the footer token is elided; a caller `sendMessage`/`sendPrompt` also moves
 the session to `running`. Normal completion comes from the `Stop` hook, and
 interrupts from the working-token edge on wide screens or the end banner
@@ -404,6 +550,84 @@ or the Codex model slug, such as `gpt-5.4`). `isCurrent` reflects the model the
 session is using now; `isDefault` reflects the CLI's configured default. When
 Codex renders only a `(current)` marker, that row is also the default.
 
+Model operations hold an exclusive session-input queue slot for the entire
+open/navigate/apply-or-cancel flow, including waiting for the dialog to clear.
+Concurrent model operations and normal submissions cannot interleave writes:
+they are dispatched only after the operation settles. The queue wait and picker
+operation share the supplied `timeoutMs` budget, so an operation still queued at
+its deadline rejects with `model_automation_failed` without opening a picker.
+The deadline and termination abort pending navigation before any further write.
+
+When an operation fails with its model dialog still open, Elwood cancels it before
+releasing the slot, within one additional second. Cancelling a follow-up stage
+(Codex's reasoning level, Claude's cache warning) returns the CLI to the picker, so
+each stage receives one Escape; an Escape already written for a stage is never
+repeated, and termination stops cleanup before any further write. A dialog still
+visible after that second keeps every queued writer held (messages, commands,
+`/login`) while it remains; raw `sendKeys` stays available for manual recovery.
+A dialog can also paint after the failure: a submitted `/model` whose picker had
+not rendered can still open it, and an accepted stage can still paint its follow-up.
+In those cases Elwood keeps the slot for the same bounded second and cancels a
+dialog that appears in it; when none appears the slot is released at the bound. A
+dialog that repaints after clearing is a new dialog and receives its own Escape.
+Model picker text already visible when the operation acquires the slot (a human's
+dialog, or a transcript quoting one) is not Elwood's: the operation rejects with
+`model_automation_failed` without writing, cancelling, or holding input.
+A partially painted Claude switch dialog (its title without its options yet) holds
+input like a complete one but is never sent a key, because a cache warning and a
+`PreModelSwitch` hook confirmation share that shell; `setModel` likewise does not
+settle while one is on screen. Nor may it settle while a COMPLETE confirmation of
+either kind is on screen: a hook's confirmation is the human's to answer, and the
+model has not changed until they do, so reporting success there would report a
+change that may never happen.
+Every picker wait and write MUST be gated on the operation's own dialog, not on a
+bare header match: a header alone is untrusted candidate evidence that transcript
+or agent output can satisfy, so navigating or cancelling on it could send keys into
+a running turn, the real composer, or another prompt. Cleanup's Escape is decided
+on everything RECEIVED, not the last rendered frame, and is withheld when the
+screen cannot be vouched for. A single clear frame does not end cleanup once a
+dialog has been seen, because a repainting picker is briefly unrecognizable.
+When session termination races a Codex `setModel`, the call rejects at once rather
+than waiting out the exit bound, and the exit barrier is consulted on every outcome,
+because the question is whether the dying CLI can still write `config.toml` — not
+whether Elwood's automation succeeded. Since that rejection settles the call before
+the restore runs, a restore failure afterwards MUST still be reported as a warning
+rather than swallowed, or the temporary model silently stays the user's default.
+A model dialog nobody Elwood opened — a human who typed `/model` themselves — is never
+Elwood's to drive, but a write that is not part of a picker transaction (`/login`
+recovery) MUST still stand off it while it is visible, because Enter applies its
+highlighted row and Escape discards the human's state. That guard applies to the WRITE
+only; it MUST NOT suppress readiness, which would deadlock Elwood's own picker whose
+dialog is on screen by design.
+Before dispatching `/model`, Elwood revalidates that no foreign picker is visible.
+Public raw input through `sendKeys`, terminal `sendInput`, or `xterm.input` revokes
+the active picker operation: it rejects with `model_automation_failed` and sends
+no further navigation or cleanup keys into the human-owned generation. A foreign
+picker hold survives partial repaints and clears only after five consecutive
+positive native-composer observations, never from an empty or unrecognized frame.
+Only the bottom-most region of the viewport is a model dialog: dialog text with a
+conversation or composer row below it is transcript content (a reply quoting a
+picker), which Elwood neither cancels nor holds on. Unrelated dialogs, including a
+`PreModelSwitch` hook confirmation, are left for the caller.
+Codex retains its process-wide configuration transaction lock, but acquires it INSIDE
+the session queue slot: claiming the lock first would let a following submission
+dispatch while the switch waited on another session's transaction, sending under the
+old model. When the
+session terminates during a Codex `setModel`, the call rejects at once but the
+`config.toml` restore, and with it the configuration lock, waits until the CLI
+process has exited (at most five seconds), because a dying CLI can still persist
+the selection it had confirmed. The barrier MUST be the observed process exit:
+a terminal session status (`stopped`, `killed`, `torn_down`) is recorded by the
+shutdown path itself and is reached even when termination did not take, so it is
+not proof the CLI can no longer write. The five-second bound is best-effort — it
+prevents a process that never exits from holding the lock, and after it elapses
+the restore proceeds without a confirmed exit. The barrier applies whether the
+switch succeeded or failed, since a successful switch racing termination leaves
+the same dying process able to write. A `setModel` still WAITING for the
+configuration lock when its session closes MUST reject promptly with
+`session_not_running` rather than wait out the transaction ahead of it, and MUST
+NOT then apply its switch when the lock frees.
+
 `listModels` opens the picker, parses the rendered rows, cancels the picker
 with Escape, and MUST leave the session's model unchanged. `setModel` selects
 the requested row through cursor navigation. Elwood itself MUST NOT persist a
@@ -432,7 +656,10 @@ live session, which keeps the switched model because Codex reads its config
 at launch. When the compare fails — for example the user edited `config.toml`
 concurrently — Elwood MUST NOT clobber the file; it leaves the CLI's write in
 place and emits the `codex_default_model_persisted` warning so the deviation
-is surfaced rather than silent. Elwood confirms the CLI's own default
+is surfaced rather than silent. Raw input taking over an active picker also
+revokes restoration authority: Elwood leaves any resulting config change in place
+and emits that same warning with a content-free takeover explanation. It must
+not restore its snapshot over a model choice the human may have just made. Elwood confirms the CLI's own default
 reasoning level for the chosen Codex model. The whole snapshot/apply/restore
 transaction holds a process-wide lock so two concurrent `setModel` switches in
 the SAME Elwood process cannot interleave and leave the wrong default. This lock
@@ -525,6 +752,14 @@ the promise rejects with `session_not_running`. Hook and activity events for
 `PreCompact`/`PostCompact` flow to the parent app exactly as for any other
 hook.
 
+A slash-command popup can swallow the Enter that submits `/compact`. When no
+`PreCompact` hook has arrived after three seconds (or half of a shorter
+`timeoutMs`), Elwood sends one recovery Enter. That Enter is a queued write like
+any other: it waits behind a model operation that owns the input queue and is
+written once the queue is released, it is dropped when compaction settles or the
+session terminates first, and it is withheld while a blocking dialog or any model
+dialog (one that survived cleanup, or a human's) is visible.
+
 `ElwoodSessionStatus` values are `starting`, `running`, `ready`, `blocked`,
 `stopped`, `exited`, `killed`, and `torn_down`.
 
@@ -537,19 +772,39 @@ in `running`. Adapter readiness signals move the session back to `ready`.
 
 `blocked` reports that the wrapped agent is waiting on a human decision it
 cannot answer itself: a tool permission or approval dialog, or a workspace
-trust prompt Elwood was not authorized to answer (`autotrust: false`).
+trust prompt Elwood was not authorized to answer (`autotrust: false`), or an
+authorized trust gate whose bounded safe automation could not finish (§5.4).
 Blocked detection derives from the rendered screen via the adapter's
-documented screen-fact rules. A session enters `blocked` from any live status
+documented screen-fact rules. Native Claude questionnaires are blocking even
+when their question copy contains composer-like carets, header-like rows, fences,
+or navigation-footer text. A completed questionnaire quoted above a later native
+composer does not provide questionnaire-blocking evidence (C-ATTN-05).
+A session enters `blocked` from any live status
 (`running` or `ready`) when a blocking dialog appears — an adapter may finish
 its working indicator before the dialog settles, so the block can follow a
-`ready` beat — and settles to `ready` when the dialog resolves, since the
-composer is then waiting for input again. Prompts Elwood answers automatically
-(startup prompt automation, or workspace trust with `autotrust: true`) MUST
-NOT produce a `blocked` transition. Terminal statuses absorb blocking
+`ready` beat. Verified clearance settles directly to `running` when the same
+frame shows ongoing work, keeping queued messages suspended without an
+intermediate `ready` event; it settles to `ready` only when a positive idle
+composer is visible. A caret alone is not positive idle evidence: clearance
+requires the adapter's verified native composer and current rendered frame. A
+partial or blank repaint retains the pending block and input hold. Initial readiness requested behind a dialog remains deferred until
+a positive idle composer frame. Working clearance synchronizes resumed turn
+detection so the next idle composer ends that turn; an older interrupt banner
+on that same working clearance frame does not end the newly resumed work. If a caller prompt was held behind the dialog, its
+physical submission restores `running` before the queue can release a follow-up;
+this does not repeat caller intent or recurring-loop bookkeeping. Prompts Elwood answers automatically
+(startup prompt automation, or workspace trust with `autotrust: true`) do not
+produce a `blocked` transition when automation succeeds within its bound. Trust
+automation that cannot safely finish falls back to a recoverable block after
+five seconds (§5.4); raw input can recover it and safe automation re-arms on a
+new valid layout or dialog generation. The block lasts until verified clearance. Terminal statuses absorb blocking
 evidence. On the transition into `blocked`, Elwood also emits an `activity`
 event with `source: "terminal"`, `kind: "attention"`, a label naming the
 matched screen-fact rule ids, and text describing that the agent is waiting on
-a human decision.
+a human decision. While the session remains blocked, a changed set of blocking
+rule ids emits another attention activity with the current ids, without submitting
+another blocking status decision. Repainting the
+same rule set (including a different ordering) emits no duplicate.
 
 `statusDecisions()` returns a live-only log of at most the 50 most recent
 status decisions, oldest first. Each `ElwoodStatusDecision` records the evidence that
@@ -601,8 +856,12 @@ renderers. The handle also exposes terminal-control methods used internally
 (`sendInput`, `writeOutput`, `resize`, `settled`, and `dispose`); callers should
 prefer the session-level `sendPrompt`, `sendMessage`, `sendKeys`, `resize`,
 `stop`, `kill`, and `teardown` APIs unless they are building advanced terminal
-integrations. Consumers that need diagnostics may await `terminal.settled()` and
-read `terminal.snapshot()`, but visual terminal renderers SHOULD render the raw
+integrations. Consumers that need diagnostics may await `terminal.settled()` —
+which covers output received while waiting and never rejects — and read
+`terminal.snapshot()`. The read-only boolean property `terminal.renderFailed`
+becomes true when a render fails and stays true: the lost output cannot be
+restored and no later output proves a complete redraw, so snapshots may be stale
+and queued input stays withheld (raw `sendKeys` and a restart remain available). Visual terminal renderers SHOULD render the raw
 `terminal:data` byte stream instead of repainting from snapshots.
 `sendInput` resolves after input has been forwarded to the PTY and rejects when
 that forwarding fails.
@@ -626,6 +885,14 @@ clears its loop definitions. `teardown` removes
 Elwood-owned state for the session and must not remove Claude-owned transcripts,
 auth, or project/user settings that Elwood did not create.
 
+Claude transcript activity and diagnostic delivery already in progress must finish
+before terminal exit and terminal lifecycle status, including when a listener
+synchronously stops the session. Deferred startup diagnostics obey the same order.
+When the PTY exit has already been observed, `stop`, `kill`, and `teardown` invoked
+from final-flush listeners join that finalization before shutdown cleanup, without
+signaling the exited PTY or waiting for another exit notification. Terminal exit,
+terminal status, and natural-exit reaping occur once even if PTY callbacks reenter.
+
 `stop`, `kill`, and `teardown` MUST reap the full PTY process tree, not only the
 PTY leader. The adapter CLI spawns helper subprocesses that are descendants of
 the PTY leader — notably the per-session hook bridge (`node hook-bridge.mjs`) the
@@ -656,3 +923,5 @@ before writing; only the existing first-party cache-confirmation policy may own
 its specific blocking screen. Compaction recovery Enter must also respect the dialog guard. Explicit caller
 `sendKeys` and narrowly scoped login/picker confirmation automation retain their
 existing contracts. C-API-23/24/37 and C-ATTN-01.
+
+Native question snapshots and answering are shared controls; see [§5.10](5.10-questions.md).