@with-logic/elwood 0.1.3 → 0.2.0

package/prd/05-api/5.4-events.md

@@ -61,12 +61,36 @@ populate the normalized metadata fields whenever those values are present in the
 source hook, transcript item, or lifecycle event. Adapter-specific `raw` remains
 available for deep debugging and unsupported future payloads.
 
+Codex assistant messages with explicit `phase: "commentary"` in committed
+`response_item` message records produce `kind: "assistant_progress"`,
+`label: "assistant"`, and untruncated normalized `text`. String content and
+array-form `output_text` blocks are supported; array text is concatenated in
+order. Analysis/unknown phases and non-output-text blocks are excluded from this
+user-facing channel. Final-answer and legacy unphased assistant messages retain
+their `assistant_message` behavior. Progress carries the usual session identity,
+transcript path, optional native turn ID, and raw source item.
+
+Response items are the canonical source of commentary. Legacy `agent_message`
+records with an explicit non-final phase remain raw transcript observations
+with an `other` summary/activity and no normalized text; their mirror must not
+publish a second progress message or a premature final answer. Unphased and
+`final_answer` legacy agent messages retain existing behavior.
+
+Progress is observational: it does not change status, indicate a turn boundary,
+or enter ergonomic `send()` results or `stream()` text events. Consumers render
+it in chronological order while retaining working state, reply context and trace
+ownership until a final reply or native lifecycle boundary. Consumers must not
+treat progress mentions as reply-routing instructions.
+
 When Elwood detects and answers an interactive startup prompt on behalf of the
 parent app, it MUST emit an activity event with `source: "terminal"`,
 `kind: "startup_prompt"`, a stable label, and text describing the key sent. This
 `startup_prompt` activity is emitted only after the prompt's PTY write actually
 fulfills; a rejected write emits no such activity and instead surfaces the
-`startup_prompt_write_failed` warning (§5.7) while leaving the prompt retryable.
+`startup_prompt_write_failed` warning (§5.7) while leaving the prompt retryable
+within the live session. Claude browser-tools disposal is a silent, permanent
+cancellation: pending writes produce neither activity nor a write-failure warning,
+and no later frame retries the decline (C-CLAUDE-22).
 The stable startup-prompt label set is EXACTLY the following, and no other value
 may be emitted with `kind: "startup_prompt"`:
 
@@ -86,39 +110,125 @@ The trust-prompt labels (`workspace_trust`, `skill_trust`, `plugin_trust`,
 trust-prompt allowlist; a second implementation MUST treat this table as the
 complete output union.
 
-Under a caller's full-trust launch (`autotrust`), an agent MUST NEVER be left
-waiting on a trust gate: when an allowlisted trust prompt is visible in the
-current rendered frame, Elwood selects its affirmative option and sends it —
-always say yes. The trust prompt family is folder/directory trust, the CLI's
-first-run prompts for loading a skill, a plugin, or an MCP server, and Claude's
-one-time bypass-permissions acceptance dialog (§5.1). This is an
-EXPLICIT ALLOWLIST: each entry names one prompt by its on-screen HEADER wording
-and an affirmative-option matcher. Recognition — and ONLY recognition — is the
-guard: (1) Elwood auto-answers only ALLOWLISTED prompts, so an off-allowlist
-first-run confirmation is left to the human and a future CLI security gate is
-never blanket-bypassed; and (2) a prompt is recognized ONLY by its HEADER wording
-outside the option region — a trust phrase appearing only inside a numbered or
-cursor-selectable option label (e.g. "1. Yes, trust this plugin and grant admin
-access") does NOT identify a prompt, so a hostile option cannot spoof one.
-Recognition matches the header against the frame's joined non-option lines, so a
-header wrapped across physical rows still matches; the affirmative is the first
-option whose label matches the prompt's affirmative pattern. Numbered layouts
-are answered by sending their option number; cursor layouts are answered by
-navigating from the rendered selection to the affirmative and pressing Enter.
-Elwood matches only against the CURRENT frame, never accumulated history. If an
-allowlisted prompt is recognized but its affirmative option has not rendered
-yet, Elwood emits an `attention` activity (labelled with the prompt id) at most
-once, and keeps watching so a later frame carrying the option is still answered —
-it never permanently wedges. These trust prompts are answered only when
-`autotrust` is set; with it off, an unanswered trust prompt is a blocking prompt
-that holds session state for the human. A prompt that Elwood
-auto-answers (including an always-answered one) MUST NOT be classified as a
-blocking prompt.
+Under a caller's full-trust launch (`autotrust`), Elwood MUST attempt to approve
+every safely recognized allowlisted trust gate. The family covers workspace,
+skill, plugin, MCP, and Claude bypass-permissions acceptance (§5.1). This is an
+EXPLICIT ALLOWLIST: automatic input requires a native header, recognized
+explanatory/path rows, and an exact affirmative choice in the same active,
+bottom-most dialog. Transcript content, quoted instructions, earlier headers,
+unknown intervening prose, and unrelated options MUST NOT authorize input.
+Wrapped native copy and partial rendering remain supported. Where a prompt's
+native dialog carries explanatory copy (Claude workspace and bypass-permissions,
+Codex directory and hooks), that copy is REQUIRED: a bare allowlisted header with
+affirmative options is only a candidate, held and never typed into, until its
+native body paints. Prompts with no known native body (skill, plugin, MCP) are
+recognized from their header and native option rows.
+
+A known native-header candidate immediately holds initial readiness and queued
+input, even when its copy/options are incomplete or unsupported. Candidate
+recognition is only authority to hold input, never authority to approve. One
+session-owned coordinator gives each observed dialog generation its own
+reservation and bounded five-second deadline, beginning at first candidate
+observation. Partial first paints receive that interval without an immediate
+`blocked` transition. Numbered and cursor layouts share the same safety checks:
+before every number, arrow, Enter, and retry, the session must still be live and
+the same generation, native header, and exact affirmative choice must remain
+valid. Cursor selection movement and completion of native option rows do not
+alone replace a generation. Clearing and reappearance do. An older completion
+cannot release or settle a newer generation's reservation.
+
+Numbered confirmations retry at bounded intervals when the native input loop
+has not consumed them; cursor navigation likewise waits for verified progress.
+An unambiguous changed versioned Codex update banner, a bannered replacement with
+changed or removed safe-option bindings and a valid safe choice, or a fresh unambiguous
+banner with a valid current safe choice after update eligibility was revoked,
+emits terminal `attention` labelled
+`codex-update-prompt` with an optional numeric `promptGeneration`. This generation
+is monotonically increasing within the live session. Fresh evidence may repeat the
+same version pair after revocation; ordinary redraws, bannerless choices, and
+ambiguous frames cannot renew it. After revocation, banner-only and action-only
+repaints cannot reauthorize old bannerless choices or renew grace. It renews the CLI's bounded update grace once;
+duplicate or older generation signals cannot extend that grace. It does not claim
+that a key was written or that the prompt was answered.
+
+With a live frame reader, `startup_prompt` is emitted only after a fulfilled
+confirmation and a verified native composer or distinct native successor gate.
+An unknown replacement is not successful clearance. Lost revalidation cancels
+that attempt quietly, retaining input ownership while clearance is unverified.
+Stop, kill, teardown, startup cleanup, and PTY exit cancel all trust attempts and
+timers before disposal; late completions emit neither success nor warnings.
+Only an actual rejected PTY write in a still-live matching attempt produces the
+content-free `startup_prompt_write_failed` warning.
+
+If automation cannot safely clear the gate within five seconds, the live session
+MUST enter recoverable `blocked` status and emit the existing human `attention`
+activity, even without another terminal frame. Unsupported layouts and exhausted
+attempts use this same fallback; they never cause blind input or false write
+warnings. An unchanged redraw cannot restart an expired attempt indefinitely.
+A newly valid layout or a new dialog generation re-arms bounded safe automation;
+once fallback has occurred, the public block remains until verified clearance.
+Raw `sendKeys` remains available for human recovery, while queued persona,
+message, and command input remains held. Headless CLI callers report the existing
+`blocked_prompt` failure. No new public status, warning, or activity shape is added.
+
+Normally successful automation MUST NOT produce a `blocked` transition. A
+recognized prompt whose affirmative is still painting may retain its once-per-
+generation transient `attention` labelled with the prompt id; it is distinct
+from the fallback attention's blocking rule id. A candidate whose native body has
+not validated emits no transient `attention`. With `autotrust` off, an
+unanswered trust candidate blocks immediately for the human. This hold survives
+partial or unknown replacements until a verified native composer or a recognized
+successor takes ownership; losing the header alone never reopens queued input.
+All recognition
+uses the current rendered frame, never accumulated history.
+
+Both adapters MUST retain trust input ownership until all received terminal output
+has rendered successfully. A staged tail, pending render, synchronized redraw, or
+render failure cannot clear human trust or authorize a trust retry. Retry reads
+that are temporarily unavailable wait within the existing attempt deadline;
+they never reuse the previous frame or enter the no-reader compatibility path.
+
+Live Claude and Codex composer clearance requires a visible native input cursor on the
+verified composer row. Cursor visibility, coordinates, title, and text must belong
+to the same completed render; output received but not yet rendered cannot prove
+clearance. Transcript caret/option text and ordinary quoted working prose are not current
+input controls merely because they resemble one. Native dialog cursor hiding or a
+cursor outside the composer keeps caller input held through partial repaints.
+Native approval headers at the dialog's leading column also retain the hold;
+a still-visible cursor on an older composer cannot override that replacement
+evidence. Indented transcript quotations are not native approval headers.
+An exact-shaped native working row remains ambiguous even with a visible input
+cursor: Codex permits typing while running, and its title spinner is configurable.
+Such a row conservatively retains the hold, including an identical transcript quotation.
+
+An unrecognized gate behind a recognized native header prefix is hold-only
+under every `autotrust` value. The recognized prefixes are exactly the
+line-leading `Do you`, `Quick safety`, `Is this`, `Load this`, `Trust the`, `Trust this`,
+`New MCP`, `WARNING:`, `Claude Code running`, and `Hooks need` (the adapter's
+`headerStart`). When the bottom-most such region has non-empty header text,
+selectable options, nothing below them but option rows and the native footer
+that ends the frame (`Enter to confirm`/`Esc to cancel`, or `Press enter to
+continue|confirm or esc to cancel|go back`, or `enter continue · esc quit`), no
+conversation row above it, and no region names an allowlisted prompt, it MUST hold
+readiness and queued input, MUST NOT receive any automated keypress (trust answers,
+the Codex update skip and its retries, or the Claude browser-tools decline), and
+blocks for the human
+with the attention rule id `<agent>-unknown_gate-prompt`. A dialog that another blocking
+rule already names (a tool permission or approval dialog) keeps that rule's
+label alone. The hold follows the current frame: it releases once that gate is
+no longer rendered, and raw `sendKeys` remains available to answer it. While
+ANY trust candidate is rendered — this gate or an allowlisted header, even a
+hold-only one with unsupported copy — the Codex update skip (first write and
+every retry) and the Claude browser-tools decline MUST NOT write. This is
+NOT a general guarantee: a gate whose header starts with any other words, whose
+footer is not yet painted or not one of those rows, or that carries other rows
+below its options is outside this grammar and is not held.
 
 Two prompts are exceptions to the `autotrust` gate. Codex hook trust
-(`hook_trust`) is Elwood's OWN integration — the session cannot function without
-its hook bridge trusted — so it is always answered, and `update` is not a trust
-decision at all; both are handled independently of `autotrust`.
+(`hook_trust`) is always enabled because the session requires its hook bridge.
+Codex's hook-trust bypass is session-wide: it trusts ALL configured hooks,
+including third-party hooks, independently of `autotrust`. `update` is not a
+trust decision at all and is also handled independently of `autotrust`.
 Every hook dispatch must also emit an adapter-neutral hook-result activity after
 parent handlers run. The result activity must include the hook event name,
 whether the dispatch failed open, and the raw in-memory result payload when
@@ -143,3 +253,20 @@ session.on("hook:PreToolUse", async (event) => {
 
 The exact naming may vary, but the type system MUST narrow event payload and
 valid response shape by hook event name.
+
+The common `question` event and normalized `question` activity expose live native questionnaires as specified in [§5.10](5.10-questions.md).
+
+Normalized `question` activities require the structured `question` payload.
+`assistant_progress` requires readable `text`; committed Codex commentary summaries
+likewise require text. The kind mapping covers every Codex summary variant.
+
+A contained `question` listener failure or failure of its companion normalized
+question activity emits at most one live `question_observer_failed` warning per
+session and its normalized warning activity. The warning has `source: "lifecycle"`,
+`severity: "warning"`, the session ID and agent, and `phase: "question" | "activity"`
+for the first observed failure. Its message and raw diagnostic contain only fixed
+text and that phase; no exception, prompt, question, answer, or transcript content
+is included. Synchronous throws and returned native Promise rejections are contained.
+All notification subscribers still receive delivery; registry state and native
+input ownership continue normally. Diagnostic listener failures do not recursively
+warn. This warning never interprets listener return values as question answers.

package/prd/05-api/5.5-starting-codex.md

@@ -63,25 +63,90 @@ later shows an interactive update prompt inside the TUI, Elwood skips that
 prompt through PTY input, including Codex's cursor-addressed update screen.
 Elwood never selects "Update now" inside the live TUI (an in-TUI update restarts
 Codex out from under the session); the real update is the preflight `codex update`
-above, and the in-TUI prompt is always skipped. The skip is edge-triggered, so if
-the same update screen reappears after a restart — the update did not take — Elwood
-skips it again rather than leaving the session stuck looping on it. While an
-update screen remains rendered, Elwood treats it as input-blocking even after the
-skip key is written: readiness and queued persona/caller input stay suspended until
-the screen clears. A captured first-party banner that renders before its options
-therefore fails safe, and a following safe-option-only frame remains latched as the
-same prompt; generic agent prose containing "update available" does not activate
-the blocker. Because current Codex versions can paint this menu before their input
-loop reliably accepts the first key, Elwood retries the safe numbered choice for a
-bounded interval. Before every write it re-reads the current frame and requires the
-still-active first-party prompt generation plus that frame's safe numbered option;
-this includes an option-only continuation belonging to a previously captured banner.
+above; interactive selection is limited to verified safe choices. When an update action is visible,
+the safe choice must follow it in the numbered option list and must not itself
+perform the update. A skip-shaped row before `Update now` is left unanswered.
+Initial selection and every retry require a validated first-party update banner in
+that same current frame, together with a safe numbered choice. A bannerless frame
+never authorizes automation, even when its option numbers and labels match an
+older update appearance. Recognition still holds queued input through partial or
+bannerless replacements until positive native composer clearance; withholding a
+selection does not release that hold. A clipped first-party banner without a safe
+option is blocking evidence only. Generic agent prose containing "update available"
+does not activate the blocker.
+
+Codex can paint this menu before its input loop accepts the first key, so the safe
+numbered choice is retried for a bounded interval. Retain only the current validated
+first-party option block, with at most 32 options and 200 characters per label;
+exceeding either bound withholds automation without releasing input. A later
+validated first-party banner with a safe option block within both bounds retires
+the overflowed appearance and may start one fresh bounded attempt, even for the
+same version pair. Redraws of that valid block cannot renew the attempt again.
+Before each write, compare the current block with the captured appearance. Changed labels,
+removed safe bindings, or renumbering invalidate the old retry even before the next
+frame observer runs. A bannered safe choice replacing a removed safe number starts
+a new appearance rather than extending an accumulated union of old bindings.
+A banner-only or action-only repaint cannot renew grace; a later unambiguous
+banner with a current safe choice may establish a fresh bounded attempt.
+Choices must form one current native numbered block: numbered pre-banner rows
+(including clipped prefixes), duplicate or restarted numbering, unknown option labels,
+and unrelated rows within or after the block withhold automation. Native update/skip/later labels,
+the captured install-command continuation, release-notes header, and Enter footer
+remain accepted; a recognized banner still blocks even when its option block is
+ambiguous. Such a recognized-but-ambiguous frame permanently revokes its
+active attempt; later bannerless choices cannot restore it. Fresh unambiguous
+first-party banner evidence with a valid current safe choice starts a new attempt,
+never the revoked one. Banner-only or action-only repaints remain blocked after
+revocation and cannot reauthorize later bannerless choices or renew CLI grace.
 It stops without another write once that generation clears or changes, and fails the
 startup operation if the update prompt remains but its safe option disappears or the
-retry interval is exhausted. A blocked update screen therefore becomes a bounded run
+retry interval is exhausted. An unknown or blank replacement permanently revokes
+its attempt; bannerless choices cannot reauthorize it, and fresh first-party banner
+evidence is required. Authoritative positive native composer clearance preserves
+the completed attempt’s settlement. Live sessions decide clearance after the current
+frame’s retained input hold is classified; composer text alone cannot restore
+eligibility. One unambiguous changed first-party version banner supersedes the prior appearance
+without a clear frame. Captured retries reject the changed banner before another
+write; the new appearance may start its own bounded attempt. Generation-tagged
+attention (§5.4) renews the CLI grace once for a replaced banner, or for fresh
+unambiguous first-party banner evidence with a current safe choice after revocation,
+even when the version pair is unchanged. Duplicate or stale generations and
+ordinary same-banner redraws cannot extend it. Each appearance of the
+update screen is its own generation: an exhausted attempt stays latched until that
+screen clears, so one
+persistent screen gets one bounded attempt rather than a fresh retry loop per frame,
+and a completion from an earlier generation never re-arms the current one. Once a later
+appearance has superseded it, an earlier attempt's late success or rejected write
+settles as a quiet cancellation: only the current generation reports `startup_prompt`
+or `startup_prompt_write_failed`. A write rejected after its screen has merely cleared
+is quiet too (nothing is left to retry or block on), while a screen that clears after
+the key was written reports `startup_prompt` only after positive native composer
+clearance. A missing reader, unknown replacement, partial frame, or retained input
+hold settles quietly as cancellation even when the digit write completed. A rejected PTY write, or a safe option that has not
+painted yet, stays retryable within the generation. A blocked update screen therefore becomes a bounded run
 failure even when the caller supplied no whole-run timeout; delayed input cannot
 reach the restored composer or a replacement dialog. This prevents a queued Enter
-from selecting Codex's default "Update now" action (C-CODEX-12).
+from selecting Codex's default "Update now" action (C-CODEX-12). Closing the session
+cancels update retry timers and prevents pending automated keys from reaching the
+PTY. A disposed responder starts no new attempt, and late completion or rejection
+settles quietly without startup success activity or a write-failure warning.
+
+Update automation eligibility and queued-input blocking have separate lifetimes.
+After a recognized update screen is replaced by an unknown dialog or partial frame,
+queued input remains held until the live terminal positively identifies its native
+composer and visible input cursor in a completed render with no working-title
+signal. The title may be absent or contain an ordinary directory name. A bare caret
+or pending render cannot release the hold. A continuously visible pre-update
+composer cannot clear new replacement text above it, even with its old cursor
+visible. Once verified composer evidence is lost, a newly appearing native
+composer may clear the hold with newly loaded resume history. This retained hold does not start
+for an unrecognized dialog without a prior update appearance. It reports
+`codex-unidentified-dialog` only when no more specific blocking rule identifies
+the replacement; a recognized trust gate keeps its own diagnostic rule (C-CODEX-12,
+C-ATTN-03). Pending automated trust owns partial repaints without emitting the
+generic retained-update label. A current human or unknown gate takes diagnostic
+precedence over a retained trust label.
+
 `strictVersionCheck` makes unparseable Codex versions fatal instead of
 warning-and-continuing.
 
@@ -97,9 +162,11 @@ When true, Elwood detects Codex's first-party directory trust prompt in the
 rendered terminal and chooses the trust/continue option through PTY input,
 emitting `startup_prompt` activity with label `workspace_trust`. The default is
 false because trusting a workspace is a security-sensitive decision. Independent
-of `autotrust`, Codex's `Hooks need review` prompt is answered once — hook trust
-is Elwood's own integration, required for the session to function, not
-third-party trust — emitting `startup_prompt` activity with label `hook_trust`.
+of `autotrust`, Elwood launches Codex with session-wide hook trust bypassed.
+This trusts ALL configured Codex hooks, including third-party hooks, so the
+required Elwood hook bridge can function. If a `Hooks need review` prompt still
+appears, it is answered once, emitting `startup_prompt` activity with label
+`hook_trust`.
 
 `persona` behaves exactly as specified for Claude in §5.1: enqueued before
 control returns to the caller, delivered as the first user message on the first

package/prd/05-api/5.7-codex-session-api.md

@@ -51,6 +51,9 @@ type ElwoodWarningEvent =
       // still meets the minimum, so the session started from it. Safe diagnostics
       // only: the installed version in use and an allowlisted error code (a probe
       // timeout/`errno`); never terminal transcripts, prompts, tokens, or secrets.
+      // `errorCode: "update_active"` means no local update command ran: another
+      // updater still held the adapter's lease after the bounded wait, or its
+      // surviving process group still does (§9.2).
       readonly installedVersion: string;
       readonly errorCode: string;
       readonly raw: string;
@@ -66,6 +69,18 @@ type ElwoodWarningEvent =
       readonly recoveryCommand: string;
       readonly raw: string;
     }
+  | {
+      // Claude's proactive renewal notice; the session remains usable.
+      readonly elwoodSessionId: string;
+      readonly agent: "claude";
+      readonly source: "terminal";
+      readonly code: "login_expiring";
+      readonly severity: "warning";
+      readonly message: string;
+      readonly expiresInDays: number;
+      readonly recoveryCommand: "/login";
+      readonly raw: string;
+    }
   | {
       // Claude's login lapsed AFTER the session was usable (C-CLAUDE-18). Content-
       // free: the message and raw are FIXED canonical strings and the recovery
@@ -134,6 +149,16 @@ type ElwoodWarningEvent =
       readonly transcriptPath: string;
       readonly raw: string;
     }
+  | {
+      readonly elwoodSessionId: string;
+      readonly agent: "codex";
+      readonly source: "terminal";
+      readonly code: "transcript_listener_error";
+      readonly severity: "warning";
+      readonly message: string;
+      readonly channel: "codex:transcript" | "activity";
+      readonly raw: string;
+    }
   | {
       readonly elwoodSessionId: string;
       readonly agent: "claude" | "codex";
@@ -213,6 +238,45 @@ type ElwoodWarningEvent =
       readonly message: string;
       readonly raw: string;
     }
+  | {
+      readonly elwoodSessionId: string;
+      readonly agent: "claude" | "codex";
+      readonly source: "lifecycle";
+      readonly code: "hook_observer_failed";
+      readonly severity: "warning";
+      readonly message: string;
+      readonly phase: "hook" | "activity" | "hook_error" | "transcript" | "lifecycle";
+      readonly raw: string;
+    }
+  | {
+      readonly elwoodSessionId: string;
+      readonly agent: "codex";
+      readonly source: "lifecycle";
+      readonly code: "question_automation_disabled";
+      readonly severity: "warning";
+      readonly message: string;
+      readonly raw: string;
+    }
+  | {
+      readonly elwoodSessionId: string;
+      readonly agent: "claude" | "codex";
+      readonly source: "lifecycle";
+      readonly code: "question_observer_failed";
+      readonly severity: "warning";
+      readonly message: "A question notification failed; native question ownership was preserved.";
+      readonly phase: "question" | "activity";
+      readonly raw: `question_observer_failed phase=${"question" | "activity"}`;
+    }
+  | {
+      readonly elwoodSessionId: string;
+      readonly agent: "codex";
+      readonly source: "lifecycle";
+      readonly code: "initial_ready_observer_failed";
+      readonly severity: "warning";
+      readonly message: string;
+      readonly phase: "lifecycle";
+      readonly raw: string;
+    }
   | {
       // Recording the one-shot initial-ready transition threw (a lifecycle-event
       // listener), so Elwood released the control queue directly (anti-starvation)
@@ -228,14 +292,48 @@ type ElwoodWarningEvent =
   };
 ```
 
+Claude's `Your login expires in N day(s) · run /login to renew` notice produces
+`login_expiring` with the CLI-reported nonnegative safe-integer `expiresInDays`.
+It is recognized in the native welcome region (with `⚠`) or below a verified
+empty native composer, including on resume and before readiness. Conversation
+and draft quotations are not sources.
+Footer recognition requires the visible native input cursor on that composer in
+the current completed render; text geometry alone is insufficient.
+Welcome recognition permanently ends after
+the first observed conversation/composer boundary; footer recognition continues.
+Wrapped notice rows are joined. Each distinct countdown value is emitted once
+per live session, even if the notice
+disappears and returns. Early observations reach listeners registered immediately
+after `startClaude` or `resumeClaude` returns. Message and raw
+contain only canonical renewal text and the parsed duration, never surrounding
+terminal content. The warning does not change status, block input, run `/login`,
+or infer an exact expiry timestamp. Actual loss of authentication retains the
+separate `login_expired` contract. Like all warnings, it is live-only.
+
+MCP terminal warnings require the native `⚠` banner marker and canonical banner
+wording in the startup region before any composer or conversation row. Bare
+canonical text and matching text inside a user/assistant turn are not diagnostic
+sources; they must not emit warnings or recovery commands. Recognition is
+startup-only: a resumed session never recognizes them, and a new session stops
+when it first writes caller input or when any assistant-marker row renders. After that no frame is a
+warning source, so a copied welcome region whose conversation marker has scrolled
+away cannot regain authority. Every assistant-marker row ends recognition,
+including one that resembles a status spinner: recognition fails toward fewer
+warnings, never forged ones.
+
 A startup prompt Elwood auto-answers is marked settled and emits its
 `startup_prompt` activity ONLY after its PTY `sendInput` write actually fulfills.
-If that write is rejected (for example, the terminal was disposed mid-startup),
+For trust prompts, live revalidation additionally confirms the native dialog has
+cleared (§5.4); a fulfilled write into a still-visible gate is not success.
+If that write is rejected while the session remains live,
 Elwood emits NO `startup_prompt` activity for that attempt and instead surfaces a
 bounded, content-free `startup_prompt_write_failed` warning carrying only the
 prompt label; the prompt is left un-settled (retryable) so a later frame
 re-attempts it. This prevents a failed write from being reported as an answered
 prompt and from becoming permanently unanswerable (C-CLAUDE-16, C-CODEX-17).
+Claude session disposal cancels pending browser-tools automation without activity,
+write-failure warnings, or retries, including a warning buffered before disposal
+but not yet delivered (C-CLAUDE-22).
 
 When Elwood recognizes an allowlisted trust prompt but its affirmative option has
 not rendered in the current frame yet, it emits a transient `attention` activity
@@ -243,7 +341,10 @@ not rendered in the current frame yet, it emits a transient `attention` activity
 state, not a wedge: under the say-yes policy Elwood keeps watching and answers the
 prompt on a later frame once the option paints, so there is deliberately NO
 warning emitted for it — a warning here would read as a "not auto-answered" signal
-even after the prompt is successfully answered (C-CLAUDE-14).
+even after the prompt is successfully answered (C-CLAUDE-14). The wait is bounded:
+if the gate cannot be verified and cleared within five seconds of first being
+seen, the session becomes recoverably `blocked` with its `attention` event and
+queued input stays held (§5.4, C-TRUST-01).
 
 The `transcript_records_dropped` warning is emitted when committed transcript
 records cannot be parsed as JSON, when a single un-terminated record exceeds a
@@ -301,8 +402,9 @@ flush runs behind an error boundary and lifecycle completion is guaranteed. Like
 every warning these carry no raw conversation content: only a bounded `cause` or
 `phase` label, an error code or short reason, and the transcript path — no counts
 and no byte magnitude. They are live-only: emitted as a `warning` + `activity`
-event, never persisted, deduplicated across time, or replayed to a late
-subscriber. To keep telemetry off the hot read path, drops are COALESCED per scan
+event, never persisted or replayed to a late subscriber. Codex listener-error
+diagnostics have the per-watcher bound described below; other warnings are not
+deduplicated across time. To keep telemetry off the hot read path, drops are COALESCED per scan
 pass: many malformed records in one bounded scan surface at most one
 `transcript_records_dropped` warning per `(transcript path, cause)` for that pass,
 rather than one synchronous fan-out per record — so pathological input cannot stall
@@ -348,6 +450,27 @@ itself. Once the session's PTY
 exits, the watcher becomes permanently terminal: no scan, emit, or observation
 occurs after `finish()`, so no transcript activity is ever delivered past
 `terminal:exit`.
+If a Codex transcript listener synchronously initiates shutdown, the current
+bounded scan finishes delivering its records before the final flush and terminal
+exit notification. Reentrant PTY exit notifications do not duplicate finalization.
+The same ordering covers transcript diagnostics and their activity projection.
+Shutdown requested during an observed natural exit joins its finalization without
+signaling the already-exited PTY or waiting for another exit notification.
+
+`hook_observer_failed` reports the first contained notification failure in one
+Claude or Codex hook invocation or bridge-error delivery. Its message is fixed
+and `raw` is `hook_observer_failed phase=<phase>`; neither
+listener error text nor hook payloads are included. Both warning and activity
+delivery are attempted independently, without retrying or recursively warning.
+Observer Promise rejections are contained without delaying the hook reply; a
+warning may follow that reply when the first observed failure is asynchronous.
+Only the newest 1,024 pending observer registrations retain diagnostic state
+(§6.4); older rejections remain consumed without a late warning.
+Codex initial-ready status/activity Promise rejections outside a hook report one
+content-free `initial_ready_observer_failed` warning with
+`raw: "initial_ready_observer_failed phase=lifecycle"`. Readiness triggered within
+`SessionStart` shares that hook's observer boundary and warning limit. Neither
+diagnostic delays the ready transition or queue release.
 
 Warnings are LIVE-ONLY. A warning is emitted once, when observed, as a `warning`
 event and a projected `activity` event, and is never persisted, never replayed to
@@ -388,13 +511,26 @@ the SAME content-free `transcript_records_dropped` warning as Claude's (now
 `agent: "codex" | "claude"`), carrying only the bounded `cause` (`"unparseable"`,
 `"oversized"`, or `"unread_backlog"`) and the transcript path — never a count and
 never raw transcript content — as a live event, exactly like Claude's. A
-scan that throws (for example a downstream activity listener that raises) MUST be
+scan that throws from an internal reader failure MUST be
 contained rather than escaping the poll timer as an uncaught exception: the Codex
 watcher stops itself and surfaces the SAME content-free `transcript_poll_stopped`
 warning as Claude's (now `agent: "codex" | "claude"`), carrying only an
 allowlisted error `reason` and the `phase`. Drops and read errors are live-only
 signals; Elwood keeps no running total and continues nothing across resume.
 
+Codex transcript delivery isolates synchronous public listener exceptions separately
+for `codex:transcript` and projected `activity`. Both deliveries are attempted for
+every record, later records in the same scan are delivered, and periodic polling
+continues after a listener failure. Only the first failure per channel per watcher
+emits a live `transcript_listener_error` warning (at most two per watcher). Delivery
+of this diagnostic is deferred to a microtask after the current synchronous scan
+or final flush; final-flush diagnostics may therefore follow `terminal:exit`. The
+warning carries only its bounded `channel` label and fixed message/raw text, never
+the thrown value or transcript content. Warning
+listener exceptions are contained and do not interrupt transcript delivery. This also
+applies during the final flush; these listener failures do not emit
+`transcript_poll_stopped`, which remains reserved for actual reader failures.
+
 As with Claude, the Codex transcript is the single source of truth for committed
 `assistant_message`, `tool_call`, and `tool_result` activity. The Codex `Stop`,
 `PreToolUse`, and `PostToolUse` hooks MUST NOT also project those activities from
@@ -423,3 +559,5 @@ the transcript watcher before emitting `terminal:exit` or terminal lifecycle
 status. Parent applications should not receive delayed transcript activity after
 the session has already emitted `terminal:exit`, `exited`, `stopped`, or
 `killed`.
+
+Native question snapshots and answering are shared controls; see [§5.10](5.10-questions.md).