@with-logic/elwood 0.2.0 → 0.2.2

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

@@ -53,7 +53,7 @@ interface SendOptions {
 // with an explicit format (never both — the alternatives are mutually exclusive).
 // Bytes are written to a short-lived temp file so the adapter attach paths (which
 // are file- or clipboard-based) have something to read; the temp file is removed
-// (best-effort) after the submission is attached.
+// (best-effort) after the submission is attached, or at once when the attach is aborted.
 type ImageInput =
   | { readonly path: string }
   | { readonly data: Uint8Array; readonly format: "png" | "jpeg" | "gif" | "webp" };
@@ -144,6 +144,24 @@ failing MCP server's retry spinner) or a session whose readiness hook never
 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.
+Codex's deadline releases readiness only onto a frame showing a configured
+session's composer outside any blocking dialog. Codex 0.164 paints a boot
+composer before its session is configured and adds the model footer beneath the
+composer once it is; under load its directory-trust gate followed 11 to 31
+seconds after its first frame, so a deadline releasing the boot composer reported
+`ready` before trust was answered and drained the queue toward that gate. A Codex
+deadline that expires before the configured composer paints fires on the first
+frame that shows it (after any blocking dialog clears, as below); work on screen
+does not delay it. A backstop 60 seconds after the first rendered frame, twice
+the longest gate delay measured, releases readiness without that composer, so a
+footer Elwood does not recognize delays readiness but never starves it. Codex's
+deadline is therefore two-stage, and 10 seconds is not its maximum: a gate that
+paints after the backstop can still follow `ready`. When the backstop releases
+readiness while the latest frame shows no configured composer, Codex emits one
+live-only, content-free `initial_ready_backstop` warning (§5.7), so a host can
+tell that readiness from readiness on configured-composer evidence. A backstop
+mark that a blocking dialog deferred until the configured composer painted does
+not warn.
 Subsequent turn readiness comes from
 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
@@ -352,7 +370,10 @@ submits the text, BEFORE the text's submitting Enter, so a single call produces
 a single agent turn carrying both. An image given as bytes is written to a
 short-lived temp file (the adapter attach paths are file- or clipboard-based);
 Elwood attempts to remove every such temp file after the submission is attached,
-on success or failure (best-effort — see the residual limitations below).
+on success or failure (best-effort — see the residual limitations below). When the
+attach is aborted, as when its session closes, Elwood removes the temp files at once,
+so `stop`, `kill`, and `teardown` resolve with an in-flight attach's temp files gone
+unless that removal fails; the attach then retries it once it unwinds.
 
 Inputs are validated and bounded BEFORE any temp file is written or any input
 reaches the composer, and a validation failure rejects the whole call so nothing
@@ -405,21 +426,38 @@ CLIs (Claude 2.1.215, codex-cli 0.144.6):
   is the clipboard contents is accepted by design. When the restore itself fails,
   the attach result is unchanged (still success) but Elwood surfaces a content-free
   `clipboard_restore_failed` warning (no clipboard contents) so the possible loss
-  of the user's prior clipboard is diagnosable rather than silent.
+  of the user's prior clipboard is diagnosable rather than silent. Codex saves
+  each pasted image as a `codex-clipboard-*.png` file directly in its temp
+  directory and never removes it. Once a Codex session's CLI has exited, by
+  `stop`, `kill`, `teardown`, or on its own, Elwood removes (best-effort) every
+  such file the session's transcript recorded as a `local_image` of a user
+  message while Elwood watched it, one file at a time, before the session emits
+  `terminal:exit` and before that `stop`, `kill`, or `teardown` resolves. It
+  removes no other file: not an image the caller named by its own path, not a
+  copy the transcript never named, and not a path with a `..` segment, which a
+  link could lead out of the temp directory. A copy already gone is not a
+  failure. A removal that fails leaves that copy for the OS to reap and does not
+  stop the removals after it; when any fails, the session emits one content-free
+  `image_copy_removal_failed` warning (§5.7), before `terminal:exit`, carrying the
+  first failure's errno token, or `UnknownError` when it has none. When every copy
+  was removed or was already gone, there is no warning.
 
 Image attachment carries several accepted residual limitations. First, temp-file
-removal after an attach is best-effort: the primary attach/materialize error is
-always preserved (a cleanup failure never masks it), but a failed removal is not
-retried and leaves the file in the OS temp directory for the OS to reap rather
-than surfacing a distinct error. Second, the
+removal is best-effort: the primary attach/materialize error is always preserved
+(a cleanup failure never masks it), and a failed removal surfaces no distinct error.
+A removal that fails when the attach is aborted is retried once, when the attach
+unwinds, which `stop`, `kill`, and `teardown` do not wait for; a removal that fails
+as the attach unwinds is not retried. Either leaves the file in the OS temp directory
+for the OS to reap. Second, the
 Codex clipboard lock serializes attachments within a SINGLE Elwood process only;
 two Elwood processes sharing one OS clipboard are not coordinated, so a
 cross-process cross-attach remains possible (callers running concurrent
 Elwood processes that attach Codex images should serialize that themselves).
-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).
+Third, session close during an in-flight attach rejects the operation, blocks
+the text write, and removes the attach's temp files at once (best-effort, per the
+first limitation), but does not join the attach's clipboard-restore finalizer or its
+retry of a failed removal; on an abrupt teardown those may not complete before
+process exit (clipboard restore is already best-effort).
 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
@@ -431,6 +469,11 @@ metadata: this defeats stray transcript/assistant `[Image #N]` text on
 non-composer lines, but a running-turn render that puts a prompt-glyph line
 on-screen at the confirmation moment, or a chip on a wrapped composer
 continuation row, is a known edge the glyph heuristic does not perfectly resolve.
+Sixth, Codex's copy of a pasted image is removed only once a transcript names it,
+which happens when the message is submitted: an image whose attach fails or is
+aborted after its Ctrl+V leaves its copy for the OS to reap. Copies are also
+removed only from Elwood's own temp directory, so a login shell that points Codex
+at another `TMPDIR` leaves them.
 
 Turn boundaries MUST be observable even when no completion hook fires. Claude
 does not fire a `Stop` hook when a running turn is interrupted (Escape), so
@@ -452,8 +495,10 @@ 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 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
+half-circle prefixes, `◐ ` and `◑ `, which Claude 2.1.310 alternates between for the
+whole turn. Every frame of that animation reads as working. 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
 anywhere. Hook-driven readiness (`Stop`) remains a redundant turn-end source;
@@ -466,8 +511,13 @@ are suppressed until the composer has stayed quiet and non-blocking (composer
 visible, no working token, no blocking dialog) for a SUSTAINED run of consecutive
 frames, not merely one. The replay repaints those footers in bursts separated by
 brief quiet gaps, so a single quiet frame does not prove the replay finished; any
-working or blocking frame during suppression resets the run. Once the quiet run is
-reached, detection behaves exactly as it does post-readiness on a cold start.
+working or blocking frame during suppression resets the run. A frame showing the
+CLI's own resume-loading placeholder is not quiet either: Codex 0.164 paints
+`Resuming session…` above a live composer, repaints it, and only then loads the
+conversation under a working title. Once that placeholder has painted and the load's
+working indicator has been seen, the first quiet composer ends suppression, because
+an idle CLI may not repaint again. Once the quiet run is reached, detection behaves
+exactly as it does post-readiness on a cold start.
 Explicit running evidence (a caller submission,
 a hook) releases that suppression IMMEDIATELY — a real turn has begun, so the replay
 is over by definition — and synchronizes the watcher into the running state without
@@ -547,11 +597,43 @@ type AgentModelOption = {
 
 `id` is a stable lowercase selector (the Claude option label, such as `haiku`,
 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.
+session is using now; `isDefault` reflects the CLI's configured default. Codex
+draws a `(default)` marker only on some versions (0.164 marks just the
+`(current)` row), so when none renders, its default is the model a plain `codex`
+launch would run with the `CODEX_HOME` the session's own Codex process runs
+with, as its launch script reports it (§4.2, C-CODEX-24): the `model` of the
+profile that `config.toml`'s root `profile` key selects, else its root `model`
+key. Elwood reads it once per listing, after the picker closes, under the lock
+for that `config.toml` that `setModel` holds through its restore, so an
+in-flight switch on the same file by another session in the same process is
+never reported as the default (the lock is process-local, like the restore it
+guards). A `config.toml` that exists but cannot be read rejects the listing
+with `model_automation_failed`, with `details.path` and `details.code`. Elwood
+reads `config.toml` only as a regular file of at most 1 MiB (1,048,576 bytes), opened without waiting for a writer
+(C-CODEX-25): the file may sit where the agent can replace it, and a FIFO in its
+place would otherwise block the whole process until something wrote to it. A
+directory (`EISDIR`), a FIFO, socket, or device (`EFTYPE`, including a socket
+macOS refuses to open), or a larger file (`EFBIG`) cannot be read. The
+session's own `model`, `profile`, and `configOverrides` launch options are not
+the default. When the config names no model (Codex then runs a built-in default
+it does not identify) or names one the picker does not list, no Codex row is 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.
+A dialog has cleared only once no stage of it, complete or partly painted, has
+been the bottom-most region across five readings at least 40 ms apart; any
+reading that shows one restarts the count. Dialog text above a conversation or
+composer row, such as a transcript quoting the picker's title, is not the dialog.
+One frame without the picker is not enough: a blank or half-painted repaint lacks
+it too, and the picker can paint again after it, where a released Enter would
+apply the highlighted model. Absence is counted rather than positive composer
+clearance because model operations also run during a turn, when the composer is
+never clear. A dialog that does not stay gone by the deadline fails the operation
+with `model_automation_failed`. Each reading first renders everything the terminal
+has received, as before a picker key, so a repaint still queued for rendering is
+counted; a reading whose received output cannot be rendered fails the operation
+the same way, since the last frame proves nothing.
 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
@@ -583,9 +665,17 @@ 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
+a running turn, the real composer, or another prompt. Every picker key — a
+navigation arrow, the selecting key, a follow-up's answer, listing's Escape, and
+cleanup's Escape — is decided on everything RECEIVED, not the last rendered
+frame: Elwood renders and observes all received PTY output, re-checks the
+operation's own dialog on that frame, and writes before further output is
+delivered, so a prompt already in the PTY buffer never receives a key aimed at
+the picker (C-API-56). When the screen cannot be vouched for, an operation's key
+is withheld and the operation rejects with `model_automation_failed`, and
+cleanup's Escape is withheld; an operation cancelled meanwhile (its deadline, the
+session closing, or caller input) rejects with that cancellation's own error, as
+it does at any other step. 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,
@@ -605,11 +695,15 @@ 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.
+A dialog that survived Elwood's own cleanup clears the same way. Observations
+count at least 40 ms apart, so readings bunched into one instant, or a burst of
+repaints, count once. An idle CLI does not repaint, so the evidence is the same
+completed frame read over time, not a run of new frames.
 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
+Codex retains its 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
@@ -629,8 +723,29 @@ configuration lock when its session closes MUST reject promptly with
 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
+with Escape, and MUST leave the session's model unchanged. It returns EVERY row
+the picker lists, in picker order, including rows outside a scrolling window:
+Claude shows at most ten rows of a longer list, numbering rows by their absolute
+position, marking a window that starts past row 1 with `↑` and one that ends
+before the last row with `↓`, and counting the rows below it with `… +K models`.
+Elwood reveals the hidden rows by moving the cursor one row at a time with the
+arrow keys, never past either end of the list, each key gated on the operation's
+own live picker and each move confirmed on screen, and merges the windows by row
+number. Arrow keys only move the highlight; the Escape that follows keeps both
+the model and its effort level. A list that fits its window is read without any
+arrow key. While a walk still needs rows (a listing, or `setModel` before its
+target is rendered), the rendered count and row numbers are validated rather
+than trusted: the walk never acts on a frame that marks rows hidden below
+without a positive count, has a row number or list length that is not an exact
+integer, or states a list length other than the first one it read. Claude
+repaints a scrolled window across more than one render, so such a frame is
+waited out; if no frame that adds up renders, or the cursor does not move, the
+walk rejects with `model_automation_failed`, because one timeout bounds the
+whole walk however many rows the picker claims.
+`setModel` selects the requested row through cursor navigation, walking the
+window the same way only until the requested row is rendered, so every id
+`listModels` returns is selectable; an unknown id walks the whole list and the
+rejection lists every row. Elwood itself MUST NOT persist a
 new default model into the user's configuration (§4.5): for Claude it applies
 with the session-only key rather than Enter, and it never selects rows via
 number keys because Claude's number shortcut immediately saves the choice as
@@ -648,8 +763,14 @@ MUST leave that decision to the human and keep it classified as a blocking
 prompt. For Codex, the Codex CLI itself persists the confirmed
 picker selection (model and reasoning effort) into the user's `config.toml` —
 there is no session-only affordance — so Elwood compensates: it snapshots
-`config.toml` before opening the picker and, after the switch is confirmed,
-restores the prior contents if and only if the file differs solely in the
+the session's `config.toml` (the one in the `CODEX_HOME` its Codex process runs
+with, §4.2) before opening the picker (a `config.toml` that cannot be read, by
+the rule above, fails `setModel` with `model_automation_failed` before the picker
+opens, because Codex would persist its selection into a file Elwood could not
+restore) and, after the switch is confirmed, rereads it the same way (one that
+cannot be read then rejects the call with `model_automation_failed`,
+`details.path`, and `details.code`, or, once the call has settled, puts that
+code in the warning's `raw`) and restores the prior contents if and only if the file differs solely in the
 root-level `model` and `model_reasoning_effort` keys the picker writes
 (compare-and-swap on the untouched remainder). The restore never affects the
 live session, which keeps the switched model because Codex reads its config
@@ -661,9 +782,19 @@ revokes restoration authority: Elwood leaves any resulting config change in plac
 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
-is process-local: two SEPARATE Elwood processes sharing one `config.toml` can
+transaction holds a lock for that `config.toml` so two concurrent `setModel`
+switches on one file in the SAME Elwood process cannot interleave and leave the
+wrong default. The lock is per file, the one the session's launch reported
+(C-CODEX-24): every path that names the same file (a symlinked home or config,
+another letter case, or another Unicode form) shares one lock, even before Codex
+creates the file: a dangling symlink shares its target's lock. Lock keys ignore
+Unicode normalization and fold letter case fully, as APFS does (`ß` and `ss` are
+one name), for every path, existing or not, so a key never changes when its file
+appears. Sessions whose config paths have different keys never wait on each
+other; paths that differ only in case share a key on every volume, so on a
+case-sensitive volume two such files share a lock, which only serializes them. A config
+path that cannot be resolved (a symlink loop, say) rejects the operation with
+`model_automation_failed`, `details.path`, and `details.errno`. This lock is process-local: two SEPARATE Elwood processes sharing one `config.toml` can
 still interleave their transactions. That cross-process race is an accepted
 current limitation (the compare-and-swap still refuses to clobber an unrelated
 edit; the residual risk is a transiently-persisted picker model surviving as the
@@ -880,7 +1011,8 @@ terminal object between Node and the browser.
 `stop` attempts graceful process termination while preserving Elwood metadata and
 loop definitions for resume. It should wait for process exit for a bounded grace period, then escalate
 to force termination so callers do not get a terminal status while the process is
-still indefinitely alive. `kill` force-terminates the process and permanently
+still indefinitely alive. A Codex `stop` or `teardown` called during or right after a
+`Stop` hook first gives Codex up to 2 seconds to record that turn (§5.7). `kill` force-terminates the process and permanently
 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.
@@ -894,19 +1026,114 @@ 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
+PTY leader, except Codex's shared app-server daemon, its updater, and what they
+started, which every Codex on the same `CODEX_HOME` shares (the walk below spares them). The adapter CLI spawns helper subprocesses that are descendants of
 the PTY leader — notably the per-session hook bridge (`node hook-bridge.mjs`) the
 CLI runs on each hook — and signaling only the leader can orphan them, leaking a
-process tree that accumulates across launch/quit cycles. Elwood MUST reap these
-by SIGKILLing the leader's process group: node-pty starts the leader as its own
-session leader, so every descendant inherits its process group, and a group
-SIGKILL reaches them even after a descendant has been reparented to PID 1 by the
-leader's exit — which a parent-pid walk cannot. The reap MUST run for `stop()`,
-`kill()`, and `teardown()`, including when the leader has already exited on its
-own (an already-terminal session still reaps the group). A dead or empty group
-is a no-op. A `teardown()` that rejects in-flight control-queue operations MUST
-still complete: rejecting a pending `sendMessage`/`compact`/model operation does
-not skip the group reap or the rest of teardown.
+process tree that accumulates across launch/quit cycles. Elwood reaps them in two
+parts. A descendant that stays in the leader's process group MUST be reaped by
+SIGKILLing that group: node-pty starts the leader as its own session leader, so such
+a descendant is reached by a group SIGKILL even after it has been reparented to PID 1
+by the leader's exit — which a parent-pid walk cannot. A descendant that moved into
+a process group of its own, as each hook command does, is outside that kill and is
+reaped by the detached-descendant walk below. The group reap MUST run for `stop()`,
+`kill()`, and `teardown()`, including when the leader has already exited on its own
+(an already-terminal session still reaps the group). A dead or empty group is a
+no-op. If the detached sweep confirms the entire leader group gone (SIGSTOP
+returns ESRCH, or a bounded fresh read after EPERM shows no live group member),
+that fact is terminal for this session: no later PTY or group signal may reuse its
+numeric id, including the final reap and subsequent shutdown attempts. This never
+clears an earlier unresolved descendant-sweep failure. An exit callback arriving
+during a detached sweep leaves the group reap to that sweep’s shutdown owner,
+after its pending confirmation settles. A live or failed confirming read still
+permits the normal final reap and preserves any unresolved sweep failure. A `teardown()` that rejects in-flight control-queue operations MUST still
+complete: rejecting a pending `sendMessage`/`compact`/model operation does not
+skip the group reap or the rest of teardown.
+
+Native process-table scans and daemon-path probes share a process-wide limit of
+two in-flight subprocesses. Admission is FIFO and its wait consumes the read’s
+existing timeout; an expired queued read starts no subprocess and reports ETIMEDOUT.
+A native slot is retained until that subprocess runner settles, including failure.
+Per-session observation requests still coalesce before admission; a short consumer’s
+timeout cannot cancel the shared read needed by another consumer.
+
+Not every descendant stays in that group. Both CLIs start each hook command with
+`setsid()`, in its own session and process group, and Codex starts MCP servers in
+their own process group. While the leader is alive its parent-pid link is the only
+thing that ties such a descendant to the session. So whenever Elwood SIGKILLs a
+live leader — `kill()`, `teardown()`, and the escalation after a `stop()` or
+startup-cleanup SIGTERM the leader did not exit on — it MUST first reap the
+leader's detached descendants: SIGSTOP the leader's process group so it cannot
+start another hook, walk the host process table by parent pid from the leader,
+SIGSTOP each process group outside the leader's that holds a live descendant,
+repeat the walk until a read converges (below), then SIGKILL each group it
+stopped, deepest first, but one it resumes as holding Codex's daemon (below).
+
+Only descendants of the leader are signaled: every member of such a group descends
+from the leader, and the host's own group is never signaled. One descendant is never
+killed: Codex's managed app-server daemon. The walk may stop its group, but then resumes
+it. Codex 0.158 and later can start, for its
+`CODEX_HOME`, an app-server daemon and its updater loop from the copy of the CLI it
+installs under `$CODEX_HOME/packages/app-server-daemon/`, each in a session of its own
+and a child of the TUI that started it until that TUI exits. The daemon belongs to the
+`CODEX_HOME`, shared by every Codex using it, the user's own included, so the walk MUST
+NOT descend into such a process: one whose binary is named `codex`, that leads its own
+process group, whose parent is a process named `codex` or PID 1, and whose path as `ps`
+shows it (`comm`, its `argv[0]`, which Codex sets to the full path) has a
+`/packages/app-server-daemon/` directory in it. Neither it nor anything it started is
+killed: the TUI forks the daemon as a `codex` group leader and then `exec`s it, so a group
+the walk stopped is resumed (SIGCONT), not killed, when the latest read shows it holding
+the daemon, or a process not shown stopped that could still become it; a SIGCONT
+refused for any reason but the group being gone fails the walk. These tests read what
+`ps` reports, which a process can set for itself, so a descendant that imitates the
+daemon is spared like it: the walk reaps a tree that stays in reach, as a descendant
+whose own parent exits before the walk already does not (below). Each read also lists
+every process's short name, which `ps` prints raw, so a name with a newline in it could
+forge a row: a read with any line that is not one whole row, or one process twice, is
+not used. A group id read from the table can be reused once that group is gone, a
+SIGSTOP takes effect only once it is delivered, and a table read sees each process at
+its own moment, so Elwood
+relies only on processes it holds: ones that read stopped, inside a group Elwood
+stopped, in a read and in the read before it. A group is stopped only once a held
+process is a parent of one of its members: a stopped parent cannot reap its exited
+child, so the group keeps its id until the signal. The walk succeeds only on a
+read that converges: it shows the leader itself live, leaves no live group
+unreached, and shows every live process in every group Elwood stopped, the
+leader's included, as held, so none of them can have started a process the read
+missed.
+A process forked while a group's SIGSTOP is being sent can miss it, so whenever a
+read shows a live process in a group Elwood stopped that is not stopped, Elwood
+MUST send that group SIGSTOP again. With no hook in flight that takes two reads,
+and each level of nesting, or a process that missed its group's SIGSTOP, adds two
+more. If the leader's group cannot be stopped, no other group is signaled and the
+walk fails, unless the leader had already exited: its group is gone, or holds only
+unreaped zombies, which a fresh read must show. The walk
+reaches only descendants still linked to the leader by parent pid: a process whose
+own parent exited earlier has been reparented to PID 1 and is not traced. The
+walk's process-table reads share one ten-second deadline, and the walk runs
+before the leader's existing SIGKILL wait, which keeps its own bound. Once the
+leader's exit has been observed, its pid may belong to another process: Elwood
+then sends the leader no further SIGSTOP or SIGKILL and stops no further group. A
+group it has already stopped is still killed, or resumed as holding the daemon,
+because a stopped process cannot exit and so keeps its id. (The process-group reap above still runs.) If the walk
+cannot complete — the table cannot be read, no read converges by the deadline,
+the leader's group cannot be stopped, a live group cannot be stopped or killed, a
+group held as the daemon's cannot be resumed, or the leader's exit is observed before
+a read converges —
+Elwood still SIGKILLs the leader (unless it has exited) and reaps its group, then
+rejects because the tree could not be confirmed reaped: `stop()` and `kill()` with
+`termination_failed`, `teardown()` with `teardown_failed`, either naming the
+reason. Once the leader is gone that cannot be retried, so every later `stop()`,
+`kill()`, or `teardown()` of the session rejects the same way instead of reporting
+success. A leader that exits on SIGTERM within the graceful window is not walked,
+so the `stop()` leaves running any detached descendant the CLI's own shutdown does
+not end. Claude ends an in-flight hook itself. Codex 0.164 does not end the shell it
+starts in a session of its own a few seconds after launch to snapshot the user's
+shell environment: a `stop()` while that shell sources a slow profile leaves the
+shell, and whatever the profile started, running under PID 1. (A human's `/quit`
+then leaves the profile's processes running too.) Nor is a leader that exits on its
+own before Elwood signals it walked: nothing links its detached descendants to the
+session any more.
 
 ### Automated input and pending decisions
 

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

@@ -131,14 +131,44 @@ 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
+before every number, selection, confirmation, 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.
+A numbered answer's first write types its number. A frame that still shows the
+gate does not prove the CLI ignored that write: under load a CLI can take it and
+paint its next screen after the retry interval, and the number typed again would
+be submitted from its composer as a user message. Retries therefore never type
+the number on that evidence alone. Codex's answer retries, at bounded intervals,
+as Enter alone while the rendered caret is on the affirmative: on the gate Enter confirms that option, and
+on Codex's empty composer it submits nothing. Otherwise (any Claude layout, or a
+caret on another option) the number is typed again only after a frame rendered
+from output received after the last write still shows the gate. Once Elwood has
+started writing a gate's number, every later attempt at that gate retries the
+same way, even when that write or a retry was rejected (a rejected write may
+still have reached the CLI), until another complete dialog replaces the gate and
+the CLI draws it afresh. A cursor layout never receives a relative arrow or a bare
+Enter: Elwood selects the affirmative by its absolute row (Home, then one Down
+per option above it), repeats that selection while the rendered cursor is
+elsewhere, and sends Enter only in the same write as the selection, once the
+rendered cursor is on the affirmative. A delayed, duplicated, or lost key, or a
+CLI that resets its own selection after Elwood read the frame, therefore cannot
+confirm another option.
+Raw input through `sendKeys`, `terminal.sendInput`, or `xterm.input` while a
+trust dialog generation is on screen hands that generation to the caller. Its
+attempt is cancelled before the caller's keys are written, and Elwood writes
+nothing more to it, even if it repaints or outlives its five-second deadline
+(it then falls back to `blocked` as below). The frame Elwood reads can trail
+the CLI, so a retry typed after the caller's keys could land in the composer
+and submit them. A later dialog generation is answered as usual. The same raw
+input ends a running Codex update-skip attempt before the caller's keys are
+written, so none of its retries follow them. A Codex update prompt that is on
+screen, or that left the screen without positive native composer clearance,
+then belongs to the caller: Elwood writes no skip to it, even when its frame
+loses and regains the prompt, until positive native composer clearance. An
+update prompt appearing after that clearance is handled as usual.
 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,
@@ -153,8 +183,16 @@ 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.
+An unknown replacement is not successful clearance. Nor does a frame without the
+gate end a fulfilled confirmation: once the confirming write fulfills, blank,
+banner-only, or other dialog-free frames (the CLI erased the answered dialog and
+is painting its next screen) neither settle nor cancel the attempt, which writes
+nothing while the gate is absent. Later verified clearance reports it exactly
+once; the same gate's return resumes answering within its remaining budget; a
+changed gate, a complete off-allowlist gate (C-ATTN-03), expiry, and closing
+cancel it without a report.
+Lost revalidation before the confirmation fulfills 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
@@ -162,9 +200,19 @@ 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.
+activity, even without another terminal frame. Those five seconds count only time
+the gate is on the current rendered frame. A frame without it — the CLI erased an
+answered dialog and is still painting its next screen — pauses the deadline, and
+the same gate's return resumes the remainder rather than a fresh interval, so the
+budget is five seconds of cumulative visible time. A gate that leaves the frame
+before those five seconds are spent and stays absent until verified clearance
+therefore never produces `blocked` or `attention`, however long the CLI then
+takes to paint its composer: no prompt is left for a human to answer. A gate that
+returns spends only what remains and falls back once its visible time reaches
+five seconds. Its input hold is unchanged and lasts until verified clearance. 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,
@@ -201,6 +249,18 @@ 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.
 
+Claude's verified composer is the empty `❯` row between its two rules, plus native
+chrome: the permission-mode footer as the very next row, or the `Claude Code v…`
+version banner. The footer proves the composer in every permission mode the CLI
+offers (manual, plan, accept edits, auto, don't ask, bypass permissions), with or
+without vim's `-- INSERT --` prefix, the transient `← for agents` and `? for
+shortcuts` hints, and the right-aligned token count or effort level. The banner
+MUST NOT be required, because it scrolls out of the viewport in a long session.
+Trust clearance, foreign model-picker release (C-API-55) and empty-input
+observation (C-API-56) share this evidence. A footer quoted anywhere other than
+directly under the composer's bottom rule is transcript, not chrome, and a footer
+truncated on a narrow terminal does not prove the composer.
+
 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`,
@@ -224,6 +284,13 @@ 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.
 
+Codex 0.164 draws two more footers when hook trust is not bypassed:
+`enter continue · esc back` on its folder-access gate, whose decline then reads
+`Back to Agent Command Center`, and `enter confirm · esc skip` on `Hooks need review`.
+Neither is one of the rows above. Each ends a dialog only under the allowlisted gate
+that draws it, with that gate's header, explanation, and options, so under any other
+header or options, including conversation text, it makes no frame a trust gate.
+
 Two prompts are exceptions to the `autotrust` gate. Codex hook trust
 (`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,

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

@@ -33,7 +33,9 @@ declare function startCodex(options: StartCodexOptions): Promise<CodexSessionApi
 ```
 
 Elwood sets the PTY working directory and also passes Codex `--cd <cwd>` so
-Codex's own session state and the shell's current directory agree.
+Codex's own session state and the shell's current directory agree. `cwd` MUST
+already be a directory, with the same `codex_start_failed` rejection, the same
+check after preflight, and the same guarantees as `startClaude` (§5.1, C-API-61).
 
 `reasoningEffort`, when set, is forwarded as the Codex `-c
 model_reasoning_effort=<value>` config override so the session starts at the

package/prd/05-api/5.6-resuming-codex.md

@@ -26,7 +26,10 @@ Because the default state store is project-local, callers that resume from a
 different process working directory must pass the original `cwd` or the explicit
 `stateDir` used at start time. Calling `resumeCodex({ elwoodSessionId })`
 without `cwd` or `stateDir` uses the current process working directory to
-discover the project-local state store.
+discover the project-local state store. Codex relaunches in the record's `cwd`
+even when a `cwd` is given, since a given `cwd` only locates the state store.
+The record's `cwd` must still be a directory, checked before and after
+preflight as on start, and `details.cwd` names it (§5.1, C-API-61).
 
 `resumeCodex` must verify that the persisted Elwood session record belongs to
 the Codex adapter before launching. Passing a Claude session ID to `resumeCodex`