@with-logic/elwood 0.1.1 → 0.1.2

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

@@ -0,0 +1,425 @@
+## 5.7 CodexSessionApi (the raw live session)
+
+`CodexSessionApi` exposes the same control surface as `ClaudeSessionApi`: typed event
+subscription, `statusDecisions`, `waitForStatus`, `waitForActivity`,
+`sendPrompt`, `sendMessage`, `sendGuidance`, `sendKeys`, `resize`, `interrupt`,
+`compact`, `listModels`, `setModel`, `createLoop`, `listLoops`, `cancelLoop`,
+`stop`, `kill`, and `teardown`. Prompt
+submission and raw input semantics are the same as Claude: Elwood writes to
+the PTY as a human would. `sendGuidance` follows the state-aware intervention
+contract in §5.3. `interrupt` follows the §5.3 contract — Codex also cancels a
+running turn with a bare Escape keypress.
+`compact` follows the §5.3 contract using Codex's `/compact` command and
+`PostCompact` hook; `listModels`/`setModel` follow the §5.3 contract against
+Codex's `Select Model and Effort` picker.
+
+The package also exports `ElwoodAgentSession`, a structural supertype both
+concrete session types satisfy, covering the shared identity/status
+properties, the common event names (`terminal:data`, `terminal:exit`,
+`status`, `activity`, `warning`, `loop`, `hookError`), the diagnostics and wait
+helpers (`statusDecisions`, `waitForStatus`, `waitForActivity`), and the
+shared io, command, and lifecycle methods. Parent-app code generic over "any
+agent session" can be written once against this type; adapter-specific hooks
+and events remain on the concrete types.
+
+Both `ClaudeSession` and `CodexSession` deliver typed non-fatal issues observed
+by Elwood through the `warning` event, projected into the adapter-neutral
+`activity` stream. Warnings are LIVE-ONLY: there is no `warnings` snapshot
+property — a warning is emitted once when observed and is never persisted,
+replayed to a late subscriber, or accumulated (§5.7). Consumers collect warnings
+by listening for the `warning` event. The MVP warning contract is:
+
+```ts
+type ElwoodWarningEvent =
+  | {
+      readonly elwoodSessionId: string;
+      readonly agent: "claude" | "codex";
+      readonly source: "lifecycle";
+      readonly code: "version_unparseable";
+      readonly severity: "warning";
+      readonly message: string;
+      readonly raw: string;
+    }
+  | {
+      readonly elwoodSessionId: string;
+      readonly agent: "claude" | "codex";
+      readonly source: "lifecycle";
+      readonly code: "agent_update_failed";
+      readonly severity: "warning";
+      readonly message: string;
+      // Best-effort `claude update` / `codex update` failed, but the INSTALLED CLI
+      // 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.
+      readonly installedVersion: string;
+      readonly errorCode: string;
+      readonly raw: string;
+    }
+  | {
+      readonly elwoodSessionId: string;
+      readonly agent: "codex";
+      readonly source: "terminal";
+      readonly code: "mcp_server_not_logged_in";
+      readonly severity: "warning";
+      readonly message: string;
+      readonly mcpServerName: string;
+      readonly recoveryCommand: string;
+      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
+      // command is the literal "/login"; no field carries banner or session text.
+      // Detection is edge-based: a banner persisting across many frames does not
+      // re-emit, so a session emits this live warning at most once for its login
+      // expiring. The session is left alive for in-place recovery via `login`.
+      readonly elwoodSessionId: string;
+      readonly agent: "claude";
+      readonly source: "terminal";
+      readonly code: "login_expired";
+      readonly severity: "warning";
+      readonly message: string;
+      readonly recoveryCommand: "/login";
+      readonly raw: string;
+    }
+  | {
+      readonly elwoodSessionId: string;
+      readonly agent: "codex";
+      readonly source: "terminal";
+      readonly code: "mcp_startup_incomplete";
+      readonly severity: "warning";
+      readonly message: string;
+      readonly failedServers: readonly string[];
+      readonly recoveryCommands: readonly string[];
+      readonly raw: string;
+    }
+  | {
+      readonly elwoodSessionId: string;
+      readonly agent: "codex";
+      readonly source: "lifecycle";
+      readonly code: "codex_default_model_persisted";
+      readonly severity: "warning";
+      readonly message: string;
+      readonly raw: string;
+    }
+  | {
+      readonly elwoodSessionId: string;
+      // Both adapters observe a committed JSONL transcript with a bounded cursor,
+      // so either can lose committed data the same three ways (unparseable,
+      // oversized, unread backlog) and surface it through this same warning.
+      readonly agent: "claude" | "codex";
+      readonly source: "terminal";
+      readonly code: "transcript_records_dropped";
+      readonly severity: "warning";
+      readonly message: string;
+      // Why data was lost: an unparseable committed record, an over-length record
+      // discarded through its next newline, or an unread teardown backlog. A bounded
+      // label only — no count and no byte magnitude (a live "something couldn't be
+      // displayed" signal, not a running tally).
+      readonly cause: "unparseable" | "oversized" | "unread_backlog";
+      readonly transcriptPath: string;
+      readonly raw: string;
+    }
+  | {
+      readonly elwoodSessionId: string;
+      // Shared: either adapter's bounded transcript cursor can hit a contained fs
+      // read error (a rotation/removal/permission race) and surface it here.
+      readonly agent: "claude" | "codex";
+      readonly source: "terminal";
+      readonly code: "transcript_read_error";
+      readonly severity: "warning";
+      readonly message: string;
+      // Last error code and path only — never a count, never raw transcript content.
+      readonly lastErrorCode: string;
+      readonly transcriptPath: string;
+      readonly raw: string;
+    }
+  | {
+      readonly elwoodSessionId: string;
+      readonly agent: "claude" | "codex";
+      readonly source: "terminal";
+      readonly code: "transcript_poll_stopped";
+      readonly severity: "warning";
+      readonly message: string;
+      // A short, allowlisted error reason only — never raw transcript content.
+      readonly reason: string;
+      // Which lifecycle phase failed: a live periodic poll, or the final flush at
+      // PTY exit. Lets an operator tell lost trailing activity during shutdown from
+      // a live-watcher poll failure without a distinct warning code.
+      readonly phase: "poll" | "final_flush";
+      readonly raw: string;
+    }
+  | {
+      readonly elwoodSessionId: string;
+      readonly agent: "claude" | "codex";
+      readonly source: "lifecycle";
+      readonly code: "reap_failed";
+      readonly severity: "warning";
+      readonly message: string;
+      // The leaked leader's process-group id and a normalized, allowlisted error
+      // code only (e.g. "EPERM") — enough to locate + explain the un-reaped group,
+      // never a raw system message or conversation content.
+      readonly processGroupId: number;
+      readonly errorCode: string;
+      readonly raw: string;
+    }
+  | {
+      readonly elwoodSessionId: string;
+      readonly agent: "claude";
+      readonly source: "lifecycle";
+      readonly code: "resize_restore_failed";
+      readonly severity: "warning";
+      readonly message: string;
+      // The size Elwood tried to restore after the narrow bootstrap and a
+      // normalized, allowlisted error code only — never a raw system message
+      // or conversation content.
+      readonly requestedCols: number;
+      readonly requestedRows: number;
+      readonly errorCode: string;
+      readonly raw: string;
+    }
+  | {
+      // Agent-discriminated: the LABEL is drawn only from THAT agent's own fixed
+      // startup-prompt labels (§5.4), so an impossible pairing (Claude + `update`,
+      // Codex + `browser_tools`) is unrepresentable. Never carries raw prompt or
+      // screen content; the prompt is left retryable so a later frame re-attempts.
+      readonly elwoodSessionId: string;
+      readonly agent: "claude";
+      readonly source: "terminal";
+      readonly code: "startup_prompt_write_failed";
+      readonly severity: "warning";
+      readonly message: string;
+      readonly label: StartupPromptLabelFor<"claude">;
+      readonly raw: string;
+    }
+  | {
+      readonly elwoodSessionId: string;
+      readonly agent: "codex";
+      readonly source: "terminal";
+      readonly code: "startup_prompt_write_failed";
+      readonly severity: "warning";
+      readonly message: string;
+      readonly label: StartupPromptLabelFor<"codex">;
+      readonly raw: string;
+    }
+  | {
+      // Codex-only: restoring the user's clipboard after an image paste failed. A
+      // fixed, content-free message and raw token only — never clipboard content.
+      readonly elwoodSessionId: string;
+      readonly agent: "codex";
+      readonly source: "lifecycle";
+      readonly code: "clipboard_restore_failed";
+      readonly severity: "warning";
+      readonly message: string;
+      readonly raw: string;
+    }
+  | {
+      // Recording the one-shot initial-ready transition threw (a lifecycle-event
+      // listener), so Elwood released the control queue directly (anti-starvation)
+      // while emitted lifecycle events may be stale. Content-free. Both adapters.
+      readonly elwoodSessionId: string;
+      readonly agent: "claude" | "codex";
+      readonly source: "lifecycle";
+      readonly code: "initial_ready_fallback";
+      readonly severity: "warning";
+      readonly message: string;
+      readonly raw: string;
+    }
+  };
+```
+
+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),
+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).
+
+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
+(labelled with the prompt id) at most once. This is a TRANSIENT render-delay
+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).
+
+The `transcript_records_dropped` warning is emitted when committed transcript
+records cannot be parsed as JSON, when a single un-terminated record exceeds a
+bounded size and is discarded through its next newline (so a pathological line
+can neither exhaust memory nor cause quadratic processing), OR when a teardown
+drain (subagent retirement or the final flush at PTY exit) reaches its bound with
+an unread backlog still on disk: the backlog's size is accounted as a drop rather
+than read in a single unbounded synchronous loop. A bounded `cause`
+discriminator distinguishes these three sources — `"unparseable"` for a malformed
+committed record, `"oversized"` for an over-length record discarded through its
+next newline, and `"unread_backlog"` for a teardown backlog left unread when the
+drain bound is spent — so the warning never mislabels a valid unread backlog as an
+unparseable record. The warning carries no count and no byte magnitude: it is a
+live, content-free signal that some committed activity could not be displayed,
+cause-tagged, emitted when the loss occurs. Elwood keeps no running total of
+dropped records and does not continue any such total across resume — a human at
+the terminal has no loss odometer, and neither does Elwood. That drain is bounded
+two ways.
+First, a single chunk budget is shared across every subagent retirement AND the
+final flush for a watcher's whole lifetime — a retirement never gets a fresh full
+budget — so aggregate terminal read work is watcher-bounded, not per-retire.
+Second, each individual drain call stops at a small wall-clock slice, so it
+returns to the event loop promptly instead of monopolizing it grinding a
+hundreds-of-MiB backlog; whatever is still unread when the shared budget or the
+slice is spent is accounted as a content-free drop. Termination and retirement
+therefore always complete in bounded-latency work — capped by both the shared
+budget and the per-call slice — rather than an unbounded synchronous drain.
+
+When the first hook to carry a transcript path is a turn-boundary hook, Elwood
+recovers the current turn already committed on disk by scanning backward from the
+file's end to the last user prompt. That scan is bounded: it reads in fixed
+blocks, carries any UTF-8 code point split at a block boundary so recovered text
+is byte-exact, and reaches back only a bounded distance. If the current turn is
+larger than that bound, Elwood recovers the committed records that fall within
+the bounded window rather than discarding the whole turn; only the portion beyond
+the window (including the prompt boundary itself) is not recovered, and that
+truncation is surfaced as a bounded, content-free `transcript_records_dropped`
+drop (`cause: "unread_backlog"`, no count, no record text) so the observability
+gap is closed rather than silent. A turn larger
+than the recovery bound therefore never silently loses all of its committed
+activity. The `transcript_read_error`
+warning is emitted when a transcript filesystem read is contained (a
+rotation/removal/permission race): the watcher never crashes the host, but also
+does not swallow it silently. The `transcript_poll_stopped` warning is emitted
+when a programming error escapes the periodic transcript poll OR the final flush
+at PTY exit: the watcher stops itself and surfaces a bounded reason rather than
+letting the failure become an unhandled rejection or abort the exit path. A
+bounded `phase` discriminator records which of the two failed — `"poll"` for a
+live periodic poll, `"final_flush"` for the final flush at PTY exit — so an
+operator can tell lost trailing activity during shutdown from a live-watcher poll
+failure without a distinct warning code. A
+throwing activity listener during the final flush never prevents `terminal:exit`
+emission, the live terminal-status transition, or the process-tree reap (C-LIFE-10): the
+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
+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
+the event loop with millions of listener calls (§5.7, C-CLAUDE-15).
+
+The `reap_failed` warning is emitted when the best-effort survivor reap on an
+unsolicited PTY exit fails (for example the group SIGKILL returns `EPERM`): the
+session still reaches its terminal status, but the descendant process group may
+have leaked, so the risk is surfaced instead of thrown out of the native exit
+callback. This is a live lifecycle warning (`source: "lifecycle"`) carrying only
+the leaked leader's process-group id and a normalized error code drawn from a
+fixed allowlist (standard error names and common Node errnos; any unrecognized
+value collapses to `UnknownError`) — never a raw system message or a
+caller-controlled string — emitted once through the `warning`/`activity` contract
+like every other warning, not persisted or replayed. A reap failure on an
+*explicit* `stop()`/`kill()`/`teardown()` is NOT downgraded to this warning: it
+rejects with a typed `termination_failed` error so the caller learns the group
+was not confirmed reaped (C-LIFE-10, C-ERR-01).
+
+The `resize_restore_failed` warning is emitted when the narrow-bootstrap restore
+of the latest requested terminal size at the one-shot initial-ready transition
+fails with a real (non-closed) native PTY resize error: the session stays at its
+safe bootstrap width rather than reporting a resize it never applied, but the
+queued persona or caller message is still released so a failed restore never
+starves input. This is a lifecycle warning (`source: "lifecycle"`, Claude only)
+carrying only the size Elwood tried to restore and a normalized error code drawn
+from a fixed allowlist (standard error names and common native-resize errnos; any
+unrecognized value collapses to `UnknownError`) — never a raw system message —
+emitted once through the `warning`/`activity` contract like every other warning,
+not persisted or replayed. A closed-fd resize at this transition is the ordinary
+benign process-exit race and is a silent no-op, not a warning (C-API-39).
+
+A stopped subagent's transcript (`agent_transcript_path` on a `SubagentStop`) is
+a one-shot input for Claude: Elwood observes that path, flushes it once, and then
+retires it from active polling, so a long-lived session with many subagents does
+not accumulate an unbounded set of transcript files polled for the rest of its
+lifetime. Codex subagent transcripts are NOT observed: the Codex watcher follows
+only the session's own rollout file, so a Codex subagent's committed records
+reach the host only insofar as the parent session's transcript carries them.
+`agent_transcript_path` is still validated and delivered on the Codex
+`SubagentStop` hook payload, so a host that wants those records can read the file
+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`.
+
+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
+a subscriber that attaches later, and never accumulated into a session snapshot or
+running tally. This matches what a human at the terminal experiences: a diagnostic
+banner appears live and then scrolls away; reopening the session does not re-show
+the banners from before. A subscriber receives whatever warnings are emitted after
+it subscribes. Warning `raw` fields still carry only short environment diagnostics
+(never prompts, terminal transcripts, hook payloads, or conversation content), but
+they are live event fields, not persisted state.
+For `mcp_startup_incomplete`, `recoveryCommands` are derived from the failed MCP
+server names as `codex mcp login <server>`. If Codex later emits richer recovery
+metadata, Elwood may prefer the CLI-provided command.
+
+`CodexSession` also emits `codex:transcript` when it can observe new items from
+Codex's own JSONL transcript. Parent apps may use this live-only event to render
+thinking/status phases, assistant messages, web search calls, and other
+transcript activity that is not currently represented as a Codex hook. Those
+same observations are also projected into the adapter-neutral `activity` event
+stream. `CodexTranscriptSummary.kind` values are `message`, `tool_call`,
+`tool_result`, `reasoning`, `web_search`, and `other`.
+
+The Codex transcript reader is bounded exactly as Claude's is. Each read pass
+reads at most a fixed chunk (256 KiB) of new committed bytes rather than the whole
+unread delta, decoding only to the last complete UTF-8 code point so a split
+multibyte character is never corrupted, and a scan pass consumes at most a bounded
+per-pass chunk budget so a large delta streams across poll ticks instead of
+blocking the event loop in one synchronous read of a hundreds-of-MiB file. A
+single un-terminated record may buffer only up to a bounded size (1 MiB); a record
+that exceeds it is discarded through its next newline (so a pathological no-newline
+line can neither exhaust memory nor cause quadratic re-concatenation) and its bytes
+are accounted as an `"oversized"` drop. At teardown — the final flush at PTY exit —
+the reader drains to end only within a bounded chunk budget and a small wall-clock
+slice; whatever is still unread when that bound is spent is accounted as an
+`"unread_backlog"` drop rather than read in a single unbounded synchronous loop, so
+the flush returns to the event loop promptly. Codex data loss is surfaced through
+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
+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.
+
+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
+their hook payloads (`last_assistant_message`, `tool_name`/`tool_input`,
+`tool_name`/`tool_output`); doing so would surface every reply and every tool
+step twice — once from the hook and once from the transcript. Those hooks remain
+turn-boundary and lifecycle signals, emitted as plain `hook` activity. The
+`Stop` hook's `last_assistant_message` in particular can carry an un-submitted
+ghost-text draft, so — exactly as for Claude — only the committed transcript
+turn becomes an `assistant_message` (C-CODEX-16).
+
+`ClaudeSession` likewise observes Claude's own JSONL transcript at the
+`transcript_path` (and `agent_transcript_path`) the hook payloads carry, and is
+the source of truth for committed Claude activity. A Claude `assistant_message`,
+`tool_call`, or `tool_result` MUST be projected from the committed transcript
+record — a Messages-API turn whose `content` blocks are `text`, `tool_use`, and
+`tool_result` — and MUST NOT be projected from the `Stop` hook's
+`last_assistant_message`. That hook field can carry an un-sent ghost-text or
+autocomplete suggestion the user never submitted; sourcing the message from the
+transcript ensures only a genuinely committed turn becomes a room message
+(C-CLAUDE-15). The `Stop` hook remains a turn-boundary signal. As with Codex,
+Elwood flushes readable transcript data and stops the watcher when the PTY exits.
+
+When a Codex PTY exits, Elwood must flush readable live transcript data and stop
+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`.

package/prd/05-api/5.8-session-api.md

@@ -0,0 +1,122 @@
+## 5.8 The session API — `ClaudeSession` / `CodexSession`
+
+`ClaudeSession` and `CodexSession` are the primary public API: ONE class per
+adapter that exposes BOTH the ergonomic `send`/`stream` convenience (for the common
+"ask a question, get an answer" and "watch the work" shapes) AND the full low-level
+control surface (`sendMessage`, `sendPrompt`, `sendGuidance`, `sendKeys`, `resize`,
+`interrupt`, `compact`, `listModels`, `setModel`, `createLoop`, `listLoops`,
+`cancelLoop`, `on`/`off`, `waitForStatus`, `waitForActivity`,
+`stop`/`kill`/`teardown`, and Claude's `login`). Every method is
+lazy-start-aware. The class is a thin wrapper over the same PTY-backed session the
+`start*` factories build — it adds no new lifecycle or persistence behavior and reads
+only public events. The `startClaude`/`startCodex` factories remain as the low-level
+eager entry points but are DEPRECATED in favor of the class; they still return the
+same live session object (typed `ClaudeSessionApi`/`CodexSessionApi`) the class wraps.
+
+**Construction (lazy start).** `ClaudeSession` / `CodexSession` are constructed
+synchronously with the same options as the factory, except `cwd` defaults to
+`process.cwd()` so `new ClaudeSession()` is valid (the working directory and any
+relative `stateDir` are snapshotted at construction, so a later `process.chdir()`
+cannot move the target project). The underlying session is NOT started at
+construction; it starts lazily on the first `send`/`stream` or OPERATIONAL control
+call (or an explicit `start()`), so a caller never has to reason about start ordering.
+The SHUTDOWN methods `stop`/`kill`/`teardown` are the exception — they do NOT start a
+session, and are no-ops before start (so `close()` is safe in a `finally`). A
+startup failure surfaces from that first call (or from `start()`), rejecting with the
+same typed `ElwoodError` the factory would throw. `start()` is idempotent and
+concurrent-safe (a second `start()`, or any lazy-starting call during startup, awaits
+the same in-flight start). `on`/`off` may be called BEFORE start — subscriptions are
+buffered and attached when the session starts, so subscribing never forces a start —
+and `status` reads `starting` until the underlying session exists. The started
+underlying session is reachable via a read-only `session` accessor (undefined until
+started) for callers that need the raw object. Only `send`/`stream` turns serialize
+with one another; control methods (`interrupt`, `sendKeys`, `createLoop`,
+`listLoops`, `cancelLoop`, `stop`, `kill`, …) go
+through immediately so an intervention reaches a running turn rather than queuing.
+
+**Turn boundary.** A "turn" begins when a `send`/`stream` submits its prompt and
+ends when its content is complete. A turn's assistant text is transcript-sourced
+(C-CLAUDE-15) and the transcript is written ASYNCHRONOUSLY, so the text can arrive
+shortly AFTER the `ready` status. The boundary is therefore a COMPLETENESS ORACLE,
+not a timer: the turn-boundary `Stop` hook carries `last_assistant_message` — the
+final assistant text of the just-completed turn — and Elwood uses it ONLY as a
+completeness signal (never as displayed text, since it can be un-submitted ghost
+text). Each adapter NORMALIZES its raw hook into that signal: a turn-boundary hook
+yields an expected-text string (empty when the boundary carries no text), and any
+other hook yields none and is IGNORED — a `Notification` or similar hook arriving
+after `Stop` never clears an installed signal — so the adapter-neutral turn runner
+reads the normalized signal, never raw provider hook field names. Once `ready` is
+observed, the turn ends the instant the transcript-collected assistant text CONTAINS
+that expected text, so it waits exactly as long as the transcript needs. When no completeness signal is available for a turn — a pure-tool
+turn, or an empty/null `last_assistant_message` (e.g. `StopFailure`) — the turn falls
+back to a bounded quiet-window settle after `ready` (no new content for a short
+window). When a NON-EMPTY expected text IS present but never appears in the
+transcript within `catchUpMs` of `ready`, the turn does NOT fall back to the quiet
+window: it rejects with `wait_timeout` (a promised completion that never arrives is a
+failure, not a quiet success). A terminal status ends the turn immediately (it is
+final). A turn may legitimately run for HOURS (running a test
+suite, polling a PR), so there is NO whole-turn timeout by default — a still-live turn
+is never failed by a clock; a caller may pass an OPT-IN `timeoutMs` whole-turn
+ceiling. The tight cap is `catchUpMs` (default 10000 ms), armed only ONCE `ready`
+fires: the agent is done, so the transcript flush should be near-instant — if it
+stalls past `catchUpMs`, the turn rejects with `wait_timeout` rather than leaving the
+caller hanging. Turns
+are serialized: overlapping `send`/`stream` calls queue and run one at a time in call
+order, so a turn's activity never interleaves with another's. This serialization covers
+the ergonomic `send`/`stream` turns only. The raw turn-producing control methods
+(`sendMessage`, `sendPrompt`, `sendGuidance`) submit immediately and are NOT part of
+the ergonomic turn queue, so calling one CONCURRENTLY with an in-flight `send`/`stream`
+turn is unsupported — its produced turn can interleave with the ergonomic turn's
+collection. Use one mode at a time: the ergonomic `send`/`stream`, or the raw
+turn-producing methods, not both concurrently. Turn isolation rests on
+that SERIALIZATION — the facade holds a turn's serialized slot until the AGENT reaches
+its real boundary, NOT merely until the consumer stops reading. On a normal turn that
+boundary is the turn's genuine completion (the transcript caught up / went quiet), which
+lands shortly AFTER `ready` — never bare `ready`, since transcript activity arrives after
+`ready`. On a consumer FAILURE (timeout / catch-up / backlog) the agent may still be
+running — and a silent long-running tool is quiet, not done — so the slot is held until a
+reliable "turn done" signal: a real `ready` (a busy agent is `running`, not ready) or a
+terminal status, then a short transcript-drain settle. A hung agent holds the slot until
+`close()`/`kill()` forces a terminal status. The facade subscribes to `activity` BEFORE
+submitting so no early event of the turn is missed. Where the adapter tags activity with a
+`turnId` (Codex), the facade additionally binds collection to the first turn's id as a
+refinement; Claude transcript activity carries no `turnId`, so for Claude the
+serialized-slot boundary is the sole isolation guarantee (which is why releasing the
+slot on the real agent boundary, not on consumer cancellation, is load-bearing).
+Because a turn has no default timeout, its buffered state is BOUNDED: the oracle
+matches against a rolling window of recent assistant text (not the whole turn, and
+capped even when the Stop hook's expected text is itself huge), and a turn whose
+UNCONSUMED events exceed an internal cap — either in COUNT (many small events) or in
+total BYTES (a few very large payloads) — fails with `wait_timeout` rather than
+growing without limit. The byte cap is what actually bounds memory: the count cap
+alone cannot, since a single agent-controlled event may carry an arbitrarily large
+string.
+
+**`stream(prompt, options?)`** returns an async iterable of SIMPLIFIED, typed
+events for exactly one turn, yielded in arrival order and ending when the turn
+settles:
+
+- `{ type: "text"; text }` — an assistant message (`assistant_message`).
+- `{ type: "thinking"; text }` — reasoning/thinking (`reasoning`).
+- `{ type: "tool_call"; name; input? }` — a tool invocation (`tool_call`).
+- `{ type: "tool_result"; name?; output? }` — a tool result (`tool_result`).
+
+Other internal activity kinds (lifecycle, hook, warning, attention, status) are
+NOT yielded — `stream` is the turn's content, not its telemetry (those remain on
+the `activity`/`warning` events of the underlying `session`). The simplified union
+is a stable public contract insulated from the richer internal
+`ElwoodActivityEvent` shape. If the turn ends by terminal exit rather than
+`ready`, the iterator ends without error; a `timeoutMs` breach throws
+`wait_timeout` from the iterator.
+
+**`send(prompt, options?): Promise<string>`** is defined AS `stream` drained for
+text: it concatenates the `text` of every `type: "text"` event of the turn, in
+order, joined by a blank line (`\n\n`) between distinct assistant messages, and
+resolves with that string when the turn settles. It never includes thinking or
+tool text. A turn that produces no assistant text resolves to the empty string.
+`send` and `stream` share one turn-boundary definition, so their completion and
+text-collection semantics are identical.
+
+**Teardown.** `close()` stops the underlying session (falling back to `kill` on a
+stop failure) and is a no-op if the session never started; it is the ergonomic
+counterpart to `stop`/`kill`/`teardown` and safe to call in a `finally`.