@with-logic/elwood 0.2.0 → 0.2.2

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

@@ -53,10 +53,14 @@ type ElwoodWarningEvent =
       // 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).
+      // surviving process group still does (§9.2). `errorCode: "login_shell_failed"`
+      // means the user's login shell failed before the update command ran (§9.2).
       readonly installedVersion: string;
       readonly errorCode: string;
       readonly raw: string;
+      // The update command's exit status, 128+n if a signal killed it; absent when
+      // it reported none (a timeout, an overflow, a login-shell failure, contention).
+      readonly exitStatus?: number;
     }
   | {
       readonly elwoodSessionId: string;
@@ -238,6 +242,32 @@ type ElwoodWarningEvent =
       readonly message: string;
       readonly raw: string;
     }
+  | {
+      // Codex-only: once the CLI exited, Elwood could not remove a copy Codex saved of
+      // an image pasted into it (§5.3), so the copy is left for the OS to reap. At most
+      // one per session, before `terminal:exit`. Content-free: the first failure's errno
+      // token (such as `EPERM`), else `UnknownError`; never a path or image data.
+      readonly elwoodSessionId: string;
+      readonly agent: "codex";
+      readonly source: "lifecycle";
+      readonly code: "image_copy_removal_failed";
+      readonly severity: "warning";
+      readonly message: string;
+      readonly errorCode: string;
+      readonly raw: string;
+    }
+  | {
+      // Codex-only: `stop()`/`teardown()` saw no record of the turn its `Stop` hook
+      // ended within the full 2 seconds, and shutdown proceeds, so that turn may be
+      // lost. Emitted before the signal. A fixed, content-free message and raw token only.
+      readonly elwoodSessionId: string;
+      readonly agent: "codex";
+      readonly source: "lifecycle";
+      readonly code: "turn_commit_wait_expired";
+      readonly severity: "warning";
+      readonly message: string;
+      readonly raw: string;
+    }
   | {
       readonly elwoodSessionId: string;
       readonly agent: "claude" | "codex";
@@ -289,6 +319,18 @@ type ElwoodWarningEvent =
       readonly message: string;
       readonly raw: string;
     }
+  | {
+      // The initial-readiness backstop released readiness while the latest
+      // frame showed no configured composer (the model footer), for example after
+      // a footer layout change (§5.3, C-API-28). Content-free.
+      readonly elwoodSessionId: string;
+      readonly agent: "codex";
+      readonly source: "lifecycle";
+      readonly code: "initial_ready_backstop";
+      readonly severity: "warning";
+      readonly message: string;
+      readonly raw: string;
+    }
   };
 ```
 
@@ -321,6 +363,14 @@ 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.
 
+Codex 0.154 and later collapse these failures to a count: `⚠ 1 MCP startup issue ·
+ctrl + t for details` in 0.154, and a `⚠ N warning(s) · f2 to view` badge at the end
+of the composer footer in 0.164. A count names no server and no recovery command, so
+it is not a warning source, and Elwood never opens the CLI's detail view (in 0.164, a
+transcript overlay that also renders the conversation). On these versions a session
+therefore emits no MCP startup warning, and the 0.164 badge reads as part of the
+idle composer.
+
 A startup prompt Elwood auto-answers is marked settled and emits its
 `startup_prompt` activity ONLY after its PTY `sendInput` write actually fulfills.
 For trust prompts, live revalidation additionally confirms the native dialog has
@@ -369,8 +419,13 @@ 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
+slice is spent is accounted as a content-free drop. The slice can stop a call's
+read of a transcript only after its first unread chunk, for up to 16 transcripts a
+call (what one live scan reads): a host too loaded to begin the drain within its
+slice still reads what each of them committed since the last poll, up to one chunk,
+and any bytes past that chunk may still be dropped as `"unread_backlog"`. A record
+the bound cuts off is part of that drop, never reported as `"unparseable"`.
+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
@@ -388,7 +443,14 @@ 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
+does not swallow it silently. A transcript that has not been created yet is not
+a read race: Claude names its transcript in `SessionStart` before its first turn
+writes the file, so until Elwood has seen the file exist, a missing file is
+waited on silently. Once the file has existed, its removal still warns, and any
+other read failure warns whether or not the file was ever seen. Both adapters'
+transcripts follow these rules. A removed Codex transcript is therefore not read
+as a truncated, empty one: each poll warns while it is missing, as does the final
+flush if it is still missing. 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
@@ -504,7 +566,8 @@ that exceeds it is discarded through its next newline (so a pathological no-newl
 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
+slice, which can end the drain only after its first unread chunk; whatever is still
+unread when that bound is spent, including a record it cuts off, 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
@@ -560,4 +623,23 @@ status. Parent applications should not receive delayed transcript activity after
 the session has already emitted `terminal:exit`, `exited`, `stopped`, or
 `killed`.
 
+Codex runs the `Stop` hook before it records the turn's completion
+(`task_complete`) in its transcript, and Elwood reports `ready` from that hook. If
+Codex is signaled after the hook returns but before it writes that record, it exits
+without the record, and the resumed conversation then ends as interrupted. So once a
+`Stop` hook with a `transcript_path` arrives, `stop()` and `teardown()` give Codex a
+bounded time to record the turn before signaling the process, including when a hook
+observer, hook handler, or `ready` listener calls them. The wait ends at the first of:
+a transcript record of that turn's end (`task_complete`, `turn_complete`,
+`turn_aborted`, or `turn_failed` carrying the hook's `turn_id`); a hook result that
+blocks the stop, since the turn then continues; the CLI's exit; or 2 seconds. After 2
+seconds shutdown proceeds, and a turn Codex has still not recorded can be lost; it is
+not waited for again. The session first emits one `turn_commit_wait_expired` warning
+(with its `activity`), even when `stop()` and `teardown()` overlap, so a host can tell
+that stop from an ordinary one. The warning states only that Elwood saw no record in
+time. Both calls still reject queued input and pause loops at once.
+`kill()` never waits. With no such turn pending, shutdown starts in the same tick as
+the call. A CLI that exits on its own during the wait reports `exited`, because Elwood
+did not signal it (C-LIFE-13).
+
 Native question snapshots and answering are shared controls; see [§5.10](5.10-questions.md).

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

@@ -65,7 +65,7 @@ after `Stop` never clears an installed signal — so the adapter-neutral turn ru
 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
+turn, or an empty/null `last_assistant_message` — 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
@@ -133,6 +133,37 @@ collection. They refine causal serialization rather than authenticate caller-own
 configuration or unrelated host processes; 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).
+
+**Rejected turn.** When Claude rejects a turn, the turn fails with `turn_failed` (§10):
+`send` rejects and `stream` throws after yielding any events it already collected. The
+evidence is a `StopFailure` hook (§6.1), which Claude fires instead of `Stop` when, for
+example, the selected model does not exist. The hook counts only for the turn whose
+own submission it rejects: the turn must already have observed its own
+`UserPromptSubmit`, whose prompt is the submitted text as pasted, without the control
+characters §5.3 removes, and when both hooks carry `prompt_id` the two must match. A
+`StopFailure` that arrives before the turn's own submission hook, or that names
+another `prompt_id`, belongs to an earlier turn whose hook arrived late and is
+ignored. The error message is the bounded diagnostic of §6.1, never assistant text,
+and `details.agentError` carries the hook's `error` name when one is present. When Codex
+rejects a turn, it fires no `Stop` hook at all. Its evidence is the committed transcript's
+`event_msg` `task_complete` record whose `error` is an object (§7A), and that record ends
+the turn instead of `Stop`. The record counts only when its `turn_id` is the one the
+turn's own `UserPromptSubmit` reported, so a record from another turn is ignored, and a
+`task_complete` whose `error` is absent or `null` is not a rejection. The error message is
+the record's `error.message`, bounded like the §6.1 diagnostic (2,000 characters). When that
+message is absent or blank, the error message is a generic rejection, which names the
+error kind when one is usable (`Codex rejected the turn: <kind>`) and otherwise is
+`Codex rejected the turn.`
+`details.agentError` is the `error.codex_error_info` kind: its string value (for example
+`other`), or the single key of its object form (for example `http_connection_failed`).
+A rejection is a consumer failure like any other: the serialized slot is still held
+until the real `ready` or terminal boundary and its transcript drain, and acceptance
+recovery never replays a rejected prompt. Only adapter failure evidence fails a turn;
+an empty reply, a `Stop` with an empty `last_assistant_message`, and a pure-tool
+turn still succeed. Rejection evidence that arrives after the turn has already
+settled does not reopen it. The raw session API does not interpret rejection: it
+emits the `StopFailure` `hook` event and its hook `activity`, or the Codex
+`task_complete` `codex:transcript` event and its transcript `activity`, as before.
 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

package/prd/06-claude-hook-bridge.md

@@ -40,6 +40,8 @@ input and fail open until first-class types are added. Elwood should add an
 unknown-but-safe event path before promising forward-compatible hook handling.
 
 `StopFailure` identifies a rejected Claude turn even when diagnostic fields drift.
+Ergonomic `send`/`stream` turns and headless CLI runs fail such a turn with
+`turn_failed` (§5.8, §12A.2).
 After validating the common hook envelope, ingress MUST admit missing or arbitrarily
 shaped `error`, `error_details`, and `last_assistant_message` fields. Their public
 TypeScript types are optional `unknown`; consumers must narrow them before use.

package/prd/07a-codex-hook-bridge.md

@@ -89,6 +89,11 @@ should read the committed live transcript data with one bounded per-pass scan
 reserved for PTY exit) so parent applications receive transcript-derived turn
 activity before the ready transition whenever Codex has already written it.
 
+A turn Codex rejects (for example an unknown model) fires no `Stop`. Its only
+evidence is the committed transcript's `event_msg` `task_complete` record whose
+`error` is an object, tagged with the turn's `turn_id`. For ergonomic turns that
+record is the turn's boundary instead of `Stop` (§5.8).
+
 ### 7A.4 Non-Hook Transcript Activity
 
 Current Codex hooks do not cover every TUI-visible activity. Reasoning/status

package/prd/08-state.md

@@ -14,10 +14,52 @@ spellings address the same session store. When Elwood initializes the default
 project-local state directory, it should create `.elwood/.gitignore` when that
 file does not already exist. Elwood MUST NOT overwrite an existing gitignore
 file and MUST NOT create gitignore files in caller-provided custom state
-directories unless a future explicit option asks it to.
+directories unless a future explicit option asks it to. The default ignore file is
+fully written before installation, which must preserve a concurrently created
+file. Failed installation must not leave an empty or partial default ignore. A complete
+published ignore is retained if later installation cleanup or directory syncing
+fails, since another start may already rely on it. Existing entries must be
+regular files, never symlinks, and their directory is synced before setup accepts them. Successful syncs
+may be reused for up to 32 unchanged file/parent observations per process; changed
+observations and failed syncs are never retained. This does not cache safety checks.
+The default ignore’s parent path must also pass the owner, mode-bit, sticky-bit,
+and private-primary-group lookup checks used for CLI workspaces (§12A.5), including
+link targets. These checks prevent replacement by other users; they do not inspect
+ACLs or isolate another process running as the same user or root.
 The default `.elwood/` directory and generated `.elwood/.gitignore` should be
 readable by normal local tooling, while session-specific subdirectories remain
 private.
+A state directory is made only while the session's `cwd` exists, and `cwd`
+itself is never made. One at or under `cwd`, the default `.elwood/` or a
+caller-provided `stateDir`, is made only below it, one directory at a time,
+however either path is spelled (in another letter case on a case-insensitive
+volume, or through a symlink). A caller-provided `stateDir` elsewhere is
+created with its missing parents, and `cwd` is checked again once it, its
+`sessions` directory, and the new session's directory are made: if `cwd` was
+removed meanwhile, every directory that setup made is removed again, except one
+another start has put its session directory in, and the start fails, with the
+`cleanupErrorCode` of any directory that could not be removed. A start that
+finds a directory removed under it by such a start makes it again while its own
+`cwd` exists. The `sessions` directory, each session
+directory, and every state file are made only inside their existing parent: a
+missing parent fails the write with `ENOENT`. So a removed worktree, or a
+removed state directory, is never recreated by a start, a resume, or a running
+session's later writes. A start fails instead, before its agent is spawned, and
+so does a write whose state directory is gone, as when it was in the removed
+worktree; a running session whose state directory is elsewhere keeps writing
+there (C-STATE-14). If state preparation fails, its empty owned scaffolding is removed.
+The default shared state root and `sessions` directory are retained: another setup,
+including one without a session ID yet, may already rely on them. Only the failed
+attempt's empty named session directory is removed there. A complete published
+default ignore is shared configuration and is never rolled back by that attempt.
+Custom-state empty scaffolding remains eligible for removal. Cleanup attempts every
+eligible directory and preserves the primary setup failure with its first cleanup
+code, including inside typed error details.
+
+Custom rollback preserves entries whose parent lookup crosses a foreign-owned or
+non-sticky shared writable ancestor, using the existing mode-bit, private-group and
+sticky-directory policy. Root-owned sticky `/tmp` remains eligible. These bounded
+observations provide no same-user/root isolation or ACL audit.
 
 Before creating or changing state, Elwood MUST reject a symlink at the state
 root, sessions directory, or session directory, and reject user-owned symlink
@@ -43,12 +85,22 @@ reused; the socket path is a per-launch runtime value, embedded only in the gene
 private bridge script and never in the session record, so a
 recorded socket path can never be trusted. `teardown` removes the whole socket
 home (every launch's socket) along with the session directory, so no per-launch
-socket can leak undiscoverably across restart/resume cycles. Across separate Elwood
+socket can leak undiscoverably across restart/resume cycles. Each Codex launch also
+writes its `CODEX_HOME` report (§4.2) into the socket home, named after that
+launch's socket file, so a failed first start leaves nothing in the session
+directory. The report is removed when its launch's PTY exits, a failed start
+included, and teardown removes any that remain with the home. A launch that ends
+without teardown — `stop`, `kill`, the agent exiting, or a failed start — removes
+its own socket file and then the socket home if that left it empty, so a session
+that is never torn down leaves nothing in the OS temp dir; a home that still holds
+another launch's socket is kept, and the session's next start or resume
+recreates the home. Across separate Elwood
 processes, running two live sessions with the same full identity (`stateDir`,
 adapter, and session id) is unsupported: the processes share files and socket
 homes without a cross-process ownership protocol. Within one process, overlapping
 resume and cleanup follow the successor protocol below. A failed start removes
-only its own socket file, preserving any overlapping launch. `stateDir`
+only its own socket file (and the home only once it is empty), preserving any
+overlapping launch. `stateDir`
 length MUST NOT constrain whether a session can start.
 
 Within one Elwood process, a validated resume attempt revokes the prior launch's
@@ -64,8 +116,10 @@ committed successor keeps its state, while a failed successor permits the predec
 to finish the requested cleanup before its shutdown promise resolves. A pending
 successor does not activate loop timers. Successful activation rereads the latest
 durable loop definitions and revokes prior scheduling in the same synchronous commit,
-so a successful predecessor cancellation or creation is preserved. An activation
-read failure stops the built launch before ownership rolls back. If resume fails,
+so a successful predecessor cancellation or creation is preserved. Activation prunes
+loops that expired since the launch read them as part of the startup publication. An
+activation read or prune failure stops the built launch before ownership rolls back,
+and rollback restores that prune. If resume fails,
 ownership returns to the prior
 viable launch only when no newer reservation or launch has replaced that attempt.
 A failed overlapping launch therefore preserves the original live launch's cleanup
@@ -78,7 +132,8 @@ settings instead use fresh per-launch filenames permanently bound to that launch
 PTY. Pending or committed successors never redirect a predecessor's hook policy. A failed
 attempt restores each prior file only while it still owns the reservation and the
 file still contains that attempt's exact published bytes. A newer predecessor
-record update or newer generation is preserved. If a predecessor updates a file
+record or loop update, even one whose bytes match the attempt's, or a newer
+generation is preserved. If a predecessor updates a file
 between two pending-launch writes, that external version becomes the rollback
 baseline for the later write. Pending-launch hook record writes participate in the
 same transaction. Superseded or failed generations cannot publish metadata.
@@ -155,7 +210,8 @@ core state must not become a transcript store.
 
 ### 8.4 Cleanup
 
-Runtime files needed for resume/debugging are kept by default after `stop`.
+Runtime files needed for resume/debugging are kept by default after `stop`. The
+socket home is not among them: `stop` removes it once it is empty (§8.1).
 Loop definitions are likewise kept after `stop`, unexpected exit, or process
 failure. `kill` permanently removes all loop definitions while preserving the
 ordinary session record; a later resume has no loops.

package/prd/09-lifecycle.md

@@ -75,24 +75,39 @@ an inherited `SHELL` environment override from the parent process.
 
 These probes MUST run asynchronously and MUST NOT block the host process's
 event loop: a parent that spawns a roster of sessions must not serialize their
-preflights on a single thread. Elwood reads each adapter's `--version` at most
-once per parent process — concurrent first reads share a single subprocess, and
-later reads reuse the cached result — mirroring the once-per-process autoupdate
-dedupe (C-LIFE-09). The cached version and adapter-capability reads are invalidated
-after every coordinated update attempt, including a failed or peer-owned attempt,
-because a failed installer may still have partially changed the binary. When
-`autoupdate` is set, concurrent callers share one update and all validate the same
-post-attempt version, so no caller proceeds on a stale pre-update version or races
-a second update. This mutual exclusion also applies across separate Elwood parent
+preflights on a single thread. Version, Codex capability, update and verification
+probes start in the validated launch directory. Version and capability answers are
+cached per adapter, directory path and observed device/inode (C-PERF-02). Concurrent
+reads for one key share a subprocess. Each cache keeps the 32 most recently used
+successful settled answers; in-flight reads are shared without counting toward
+that bound. Version results are retained only when both stdout and stderr contain
+at most 65,536 UTF-16 code units; larger results are returned unchanged but not
+retained. Capability caching retains only the derived boolean, not the help text.
+A result is retained only if directory identities observed before and after its
+read match. These bounded snapshots can miss a replacement restored between checks;
+they do not track executable changes or PATH changes within the same directory.
+The cached version and adapter-capability reads are invalidated after every
+coordinated update attempt, including a failed or peer-owned attempt, because a
+failed installer may still have partially changed the binary. Update coordination
+remains once per parent process and adapter across workspaces (C-LIFE-09): its
+owner verifies and updates from that caller's captured directory, and each caller
+validates its own workspace's post-attempt version without racing a second update. This mutual exclusion also applies across separate Elwood parent
 processes for the same macOS user and adapter: an atomic lease names the adapter in
 a stable per-account cache independent of `TMPDIR`; contenders wait without
 blocking the event loop, then invalidate their local caches and continue without
-running a duplicate update. Contender waiting is bounded to 60 seconds; an owner
-that has not finished by then causes the contender to skip its update and warn,
-without deleting the owner's lease. This warning uses `errorCode: "update_active"`
+running a duplicate update. Contender waiting is bounded to 165 seconds: the owner
+runs two probes under the lease, a `--version` read confirming the CLI exists and then
+the update, each allowed 75 seconds by its launch and command bounds (§9.2), and the
+rest covers their abort cleanup. An owner that has not finished by then causes the
+contender to skip its update and warn, without deleting the owner's lease. This warning uses `errorCode: "update_active"`
 and a canonical message explaining that the update was skipped because another
 updater is still active; no local update command ran, so it carries no exit status
-or stderr. The lease records the owner's process id and a unique
+or stderr. Completion publication atomically replaces the marker's token file. A contender
+pins its baseline file before observing the owner, then compares the pinned token
+with the current pathname after acquisition; recovered owner generations remain
+completion evidence. Concurrent older Elwood writers that modify a marker inode
+in place retain the earlier snapshot race; its token payload remains compatible.
+The lease records the owner's process id and a unique
 generation. Cleanup removes only the generation it owns, a live owner is never
 evicted solely because the stale bound elapsed, and recovery of a dead owner's
 lease is itself serialized before removal, so neither cleanup nor concurrent stale
@@ -140,9 +155,48 @@ rejected result: a later caller re-attempts rather than inheriting the prior
 failure.
 
 Each probe is bounded so a broken or hostile CLI on PATH cannot hang or flood
-the host: a probe that does not exit within a default timeout (15 seconds) or
-whose captured output exceeds a per-stream byte cap (1,000,000 bytes) is
-killed, and its captured output is truncated to the cap. Abort cleanup has an
+the host. A probe runs through the user's interactive login shell (§4.2), and
+loading that shell's startup files is the user's profile, not the CLI: under
+concurrent launches on a loaded machine the profile alone can outlast the CLI's
+bound while the CLI itself answers in milliseconds. The two phases are therefore
+bounded separately. After the startup files load, and before the probe
+command runs, the probe shell writes a start line of Elwood's own, ending in a random
+token chosen once per parent process so that no startup file's output can pass for it,
+on a private channel that is neither stdout nor stderr, so a startup file that
+redirects either cannot hide the line. A shell that closed that channel at startup (macOS's bash 3.2,
+started as an interactive login shell, closes every inherited descriptor above
+stderr) writes the line on stdout instead. Not stderr, which a startup file may
+discard or merge into stdout: a startup file that hid stdout would also hide the
+command's own output. Elwood removes the line from captured stdout, so on either
+channel the probe's captured output is exactly the shell's and the command's.
+The private channel stays open past the start line, for the e2e home guard's stop
+line (§12), and closes before the command, which never inherits it.
+After the start line and before the command, the probe script removes the user's
+not-found handlers, zsh's `command_not_found_handler` and bash's
+`command_not_found_handle`, under the command's bound, which starts at the line. A
+Version probes explicitly check command lookup after removing those handlers. A
+failed lookup emits a private random marker over the existing control channel
+(or stdout fallback) and exits 127. Only that conclusive lookup signal or native
+`ENOENT` reports a CLI as not found; numeric status 127 alone is insufficient. A
+resolved CLI exiting 127 reports `*_start_failed` with its stderr and exit status.
+Lookup markers are removed from captured output, and no handler output is captured.
+The shell has 60 seconds from spawn to write that line (the launch bound),
+and the probe command then has a default timeout of 15 seconds from that line until
+it exits. A probe that
+exceeds either bound, or whose captured output exceeds a per-stream byte cap
+(1,000,000 bytes), is killed, and its captured output is truncated to the cap.
+Either timeout reports `ETIMEDOUT`. Once the probe command has started, a probe whose
+process dies of a signal Elwood did not send reports the status a shell would, 128 plus
+the signal's number; a login shell that dies before then is a login-shell failure, as
+follows. A login shell that misses the launch bound, or
+exits without writing the start line (a startup file that `exec`s another program,
+say), never ran the probe command, so the probe fails as a login-shell failure
+rather than reporting the shell's exit status as the command's: its cause names the
+login shell, and its typed error details carry `phase: "login_shell"`. Its captured
+stderr is only the user's startup output, which can hold expanded secrets, so it is
+withheld: `details.stderr` is empty. A best-effort update probe that fails this way
+surfaces the `agent_update_failed` warning with `errorCode: "login_shell_failed"` and
+an empty `raw`. Abort cleanup has an
 additional one-second bound: an aborted probe retries process-group termination,
 falls back to terminating the direct child once group signals have kept failing,
 and awaits exit within that window. A process-group id is signaled only while the
@@ -169,14 +223,21 @@ non-PTY probe — `--version`, `--help` capability detection, and
 otherwise) surfaces through that probe's existing public error name —
 `claude_start_failed` / `codex_start_failed` — with the underlying reason
 preserved in the error `details` as `cause` (and `errno`, e.g. `ETIMEDOUT` on
-timeout or `E2BIG` on overflow) alongside any `stderr`. An UPDATE failure
+timeout or `E2BIG` on overflow) alongside any `stderr`, and the status the probe
+reported, if any, as `exitStatus`. An UPDATE failure
 (`claude update` / `codex update`), being best-effort maintenance, does NOT
 surface as a start-blocking error; it is contained and surfaces as the live
-`agent_update_failed` warning carrying the same bounded diagnostics (exit status,
+`agent_update_failed` warning carrying the same bounded diagnostics (`exitStatus`,
 `errno`, `stderr`), while startup continues through the compatibility gate. A
 killed probe is signaled only because Elwood aborted it; a probe that exits or
 fails to spawn on its own is not signaled.
 
+At most 8 non-PTY probes run at once in a parent process, because each starts an
+interactive login shell and a heavy profile slows every shell that runs beside it.
+Further probes wait their turn in arrival order. A waiting probe has not started:
+its launch bound begins when it runs, and a probe that fails frees its turn like
+one that succeeds.
+
 After spawning the PTY, Elwood waits briefly for immediate process exits or
 known authentication/startup failure banners before reporting the session as
 running. The default wait must be long enough to catch typical local CLI startup
@@ -194,16 +255,32 @@ flush of any transcript diagnostics buffered before the session sink existed
 (emitted as live warnings), PTY-exit registration, the readiness/authentication
 assertion, and the startup-usable evidence. If ANY of them fails, Elwood tears
 down the now-live PTY, hook bridge, terminal, and transcript watcher before
-rejecting, so a failed `startClaude`/`startCodex` never leaks a live process, IPC
-endpoint, or file watcher. (The one-shot version/preflight warning is NOT part of
-this boundary — it is scheduled for delivery AFTER start resolves, per C-API-14.) Tearing down the PTY routes through the SAME one-shot
-process-group reap the normal exit path uses (§9.4, C-LIFE-10): the PTY is
-signaled, its exit is awaited within a bounded window, and the leader's process
-group is SIGKILLed on every path — even if the PTY signal throws — so a
-CLI-spawned descendant such as a hook-bridge grandchild (which POSIX reparents to
-PID 1 the instant the leader exits) cannot survive or reparent past a failed
-startup. The original startup error is preserved; a cleanup or reap failure is
-secondary and never replaces it.
+rejecting. This teardown is best-effort: it stops the hook bridge and the transcript
+watcher and disposes the terminal on every path, but a CLI process it could not confirm
+reaped may remain (see below). (The one-shot version/preflight warning is NOT part of
+this boundary — it is scheduled for delivery AFTER start resolves, per C-API-14.)
+The session ends the PTY with the same one-shot process-group reaper its exit path
+uses (§9.4, C-LIFE-10), so any successful group SIGKILL occurs at most once across paths.
+If the session has already seen the PTY exit (for example, the CLI exited during
+startup), the PTY is not signaled again: the leader's pid may already belong to an
+unrelated process, so only that shared reaper runs. That reaper does nothing if the
+exit's reap succeeded and retries it if it failed. Otherwise the PTY is signaled, its
+exit is awaited within a bounded window, and the leader's process-group reap is attempted
+on every path, even if the PTY signal throws. If the detached sweep confirms the entire
+group gone, the final group SIGKILL is skipped, avoiding a signal to a possibly reused
+numeric id; an earlier unresolved descendant-sweep failure still rejects. An eligible
+group kill stops a CLI-spawned
+descendant such as a hook-bridge grandchild, which POSIX reparents to PID 1 the instant
+the leader exits. A leader that ignores the SIGTERM has its detached descendants
+reaped before the escalating SIGKILL, as §5.3 specifies. The original startup error is
+preserved; a cleanup or reap failure is secondary and never replaces it. When that PTY termination or group reap cannot be
+confirmed, part of the CLI's process tree may still be running, and a typed startup
+error keeps its code and message and gains two details. `cleanupErrorCode` is
+content-free: the failed group reap's errno if there is one, else the termination's,
+when that errno is on the reap allowlist; otherwise `UnknownError`.
+`cleanupProcessGroupId` is the leader's group id, for diagnosis only: it may already
+have been reissued to an unrelated group, so it must never be signaled. A startup error
+that is not one of Elwood's typed errors is rethrown unchanged.
 
 ### 9.3 Resume
 
@@ -241,9 +318,12 @@ intentionally not persisted yet.
 For either adapter, resume validates the loop sidecar before starting the agent,
 silently removes definitions whose seven-day wall-clock expiry passed during
 downtime, and restores surviving definitions with the same IDs and persisted
-jitter. It restores no timer or due state: every surviving cadence starts fresh
-from the resumed session's first readiness, using that launch's current
-permissions and blocking-dialog posture, and no missed run is replayed.
+jitter. That removal, and any at activation (§8.1), is part of the launch's startup
+publication, so a resume that then fails restores the sidecar it found unless the
+earlier launch has written it since. It restores no timer or due state: every
+surviving cadence starts fresh from the resumed session's first readiness, using
+that launch's current permissions and blocking-dialog posture, and no missed run is
+replayed.
 
 ### 9.4 Exit
 
@@ -265,7 +345,12 @@ not delay the native process-exit notification, terminal status, or unconditiona
 process-group reap; the final `terminal:data` tail may therefore arrive after
 `terminal:exit`. A stalled renderer, or a PTY that never goes quiet, is disposed
 when the budget expires. Explicit direct `terminal.dispose()` does not wait for
-pending output.
+pending output. Runtime cleanup also stops the hook bridge and finishes the
+transcript watcher: one bounded final flush of what the transcript already holds,
+then no more polling. So a PTY that outlives a failed shutdown produces no later
+transcript activity, and its hook commands reach no handler: the stopped bridge
+accepts no new request. A host hook handler already running when cleanup starts may
+still finish and report its result.
 
 Reaping the leader's process group is unconditional on every exit path
 (C-LIFE-10). On an unsolicited PTY exit the terminal status is submitted first,
@@ -276,7 +361,11 @@ a live `reap_failed` warning rather than aborting the exit callback. An explicit
 survivor reap (it does not re-signal the dead PTY — node-pty does not replay the
 exit event, and the pid may already be recycled) and rejects with a typed
 `termination_failed` error if that reap fails, leaving the reap retryable by a
-later `teardown()`.
+later `teardown()`. Every `stop()`/`kill()` attempt runs runtime cleanup after its
+termination or survivor reap, even when that failed: the PTY could not be signaled,
+did not exit, or its group could not be reaped. The call still rejects with that
+failure, and a cleanup failure alongside it is kept as its message in
+`details.cleanupError`.
 
 Overlapping `stop()`, `kill()`, and `teardown()` calls on one session are
 serialized so the PTY is signaled at most once. The first caller owns the in-flight
@@ -294,5 +383,7 @@ and (for teardown) remove files. A settled shutdown failure is not permanently
 sticky: because signal ownership is separate from the in-flight promise, a later
 `stop()`/`kill()`/`teardown()` after a failed one runs a fresh attempt that RETRIES
 the reap, runtime cleanup, and file removal — without re-signaling the PTY — rather
-than returning the earlier rejection forever (C-LIFE-10 retry posture). Each caller
-still observes its own operation's success or typed failure.
+than returning the earlier rejection forever (C-LIFE-10 retry posture). The one
+exception is a detached-descendant walk that could not complete (§5.3): with the
+leader gone it cannot be retried, so every later call keeps rejecting for it. Each
+caller still observes its own operation's success or typed failure.

package/prd/10-errors.md

@@ -9,14 +9,14 @@ Initial required error names:
 |---|---|
 | `unsupported_platform` | The current OS is not supported by the implementation. |
 | `claude_not_found` | `claude` could not be resolved or spawned. |
-| `claude_start_failed` | Claude started but exited or failed before the session was usable. |
+| `claude_start_failed` | Claude started but exited or failed before the session was usable, or the session's `cwd` is not an existing directory (C-API-61). |
 | `claude_update_failed` | `claude update` failed. Best-effort: contained by the autoupdate preflight and surfaced as the `agent_update_failed` warning (never thrown out of `startClaude` when the installed CLI meets the minimum). |
 | `claude_not_authenticated` | Startup output or status indicates Claude is not authenticated. |
 | `claude_version_unsupported` | Installed Claude version lacks required features. |
 | `claude_invalid_reasoning_effort` | `reasoningEffort` was not one of the valid `ClaudeReasoningEffort` values; rejected before spawn. |
 | `claude_high_trust_conflict` | `highTrust: true` was combined with an explicit `permissionMode`; rejected before spawn. |
 | `codex_not_found` | `codex` could not be resolved or spawned. |
-| `codex_start_failed` | Codex started but exited or failed before the session was usable. |
+| `codex_start_failed` | Codex started but exited or failed before the session was usable, or the session's `cwd` is not an existing directory (C-API-61). |
 | `codex_update_failed` | `codex update` failed. Best-effort: contained by the autoupdate preflight and surfaced as the `agent_update_failed` warning (never thrown out of `startCodex` when the installed CLI meets the minimum). |
 | `codex_not_authenticated` | Startup output or status indicates Codex is not authenticated. |
 | `codex_version_unsupported` | Installed Codex version lacks required features. |
@@ -30,8 +30,8 @@ Initial required error names:
 | `hook_bridge_failed` | The hook bridge or IPC endpoint could not be initialized. |
 | `input_queue_full` | A live session control queue would exceed 1,024 outstanding operations or 8 MiB aggregate UTF-8 input text; no input or attachment is performed for the rejected operation. |
 | `session_not_running` | Operation requires a running process but the session is stopped. |
-| `termination_failed` | A stop/kill request did not observe process exit after escalation, or the PTY exited but its process group could not be confirmed reaped. |
-| `teardown_failed` | Elwood could not remove all owned session files. |
+| `termination_failed` | A stop/kill request could not signal the PTY, did not observe process exit after escalation, or the PTY exited but its process group or its detached descendants could not be confirmed reaped. A PTY signaling failure keeps the underlying message as `cause` and any `errno`/`syscall`/`path` in `details`. When the PTY was not confirmed terminated and its group reap failed too, `details.reapError` keeps the reap's message and `details.reapErrno` its errno when it has one. A failed reap retry, in a `stop()`/`kill()` of an already-signaled or exited session or in `teardown()`, keeps the leader's process-group id as `details.processGroupId`. A retained detached-sweep failure after the leader group is confirmed gone is still reported as a detached-sweep failure. When the detached-descendant walk could not complete, its reason is the `cause` (or `details.sweepError` alongside another termination failure), and `details.unconfirmedProcessGroupIds` lists up to 16 ids of the process groups it could not confirm reaped, the leader's own included when its group was not confirmed stopped; like `processGroupId`, they are diagnostic only and may already belong to another group. Runtime cleanup runs after a failed termination too: a cleanup failure on its own is `termination_failed` with its message as `cause`, and one alongside another termination failure is kept as its message in `details.cleanupError`. When `close()` (§5.8) fails both its stop and its kill, it keeps each one's cleanup message too, as `details.cleanupError` and `details.killCleanupError`. |
+| `teardown_failed` | A `teardown()` step failed: the PTY could not be terminated or its process tree, including detached descendants, confirmed reaped, runtime cleanup failed, or Elwood could not remove all owned session files. Every step still runs. `details.causes` lists each failed step's message, and `details.failures` lists each failed step as `{ message }`, adding `code` and `details` when the step failed with a typed Elwood error, so a `termination_failed`'s errno, its reap's, its `processGroupId`, and its `unconfirmedProcessGroupIds` survive teardown. |
 | `compact_failed` | A requested conversation compaction did not report completion in time. |
 | `interrupt_failed` | A requested turn interrupt did not return the session to ready in time. |
 | `model_automation_failed` | The adapter's model picker could not be recognized or driven to completion. |
@@ -40,12 +40,19 @@ Initial required error names:
 | `invalid_image` | An `images` input is not attachable: an unsupported/absent byte format, empty bytes, a path that is not a readable file, or a total image count/size beyond the documented limits (C-API-44). Raised before any partial input reaches the composer. |
 | `image_attach_failed` | An image could not be confirmed attached: the CLI's `[Image #N]` chip did not appear before the confirmation timeout, the OS clipboard could not be read/written, or terminal rendering permanently failed. No text is submitted afterward. (A session that TERMINATES mid-attach rejects with `session_not_running`, like any queued op.) (C-API-44/45/46) |
 | `wait_timeout` | A `waitForStatus`/`waitForActivity` call did not observe its condition before the timeout, the PTY rejected a staged-draft cleanup write before successor input, or raw input replaced an initial/replay ergonomic submission awaiting empty-input confirmation (§5.3). The same code rejects queue-backed input admitted from an expired Stop callback/observer context (§6.3), before terminal-state checks even after teardown. Cleanup failures retain the pending draft and use a bounded message without raw PTY diagnostics. |
+| `turn_failed` | The agent itself rejected an ergonomic `send`/`stream` turn and reported it through its own failure evidence: a Claude `StopFailure` hook that rejects the turn's own submission (§5.8, §6.1), or a Codex transcript `task_complete` whose `error` names the turn's own `turn_id` (§5.8), such as an unknown model or an API error. The message is the bounded rejection diagnostic of §6.1, or Codex's bounded `error.message`; `details.agentError`, when present, is Claude's `error` name (e.g. `model_not_found`) or Codex's `codex_error_info` kind (e.g. `other`) and is diagnostic only. An empty or absent reply is never this error (§5.8). |
 | `invalid_loop` | A loop request or recognized `/loop` command violates the documented shape, interval, or UTF-8 message bounds. |
 | `loop_limit_reached` | Creating a loop would exceed 50 unexpired definitions; existing loops are unchanged. |
 | `loop_not_found` | Cancellation targeted an unknown or already-finished loop ID. |
 | `loop_persistence_failed` | A loop-sidecar write required by creation, cancellation, kill, expiry, or teardown did not complete safely. |
 | `loop_submission_failed` | Live loop scheduling or readiness-safe prompt submission failed; details identify only the loop ID. |
 
+A confirmed command lookup failure reports `*_not_found` with `exitStatus: 127`,
+the fixed cause ``The login shell found no `<command>` (status 127).``, and no
+`stderr` field. Native `ENOENT` retains its native cause and diagnostic fields. A
+resolved CLI returning 127 is `*_start_failed`, preserving its stderr and status;
+a numeric exit status alone is never proof of failed command lookup.
+
 Hook handler failures are normally surfaced as `hookError` events, not thrown
 from the hook bridge path.