@with-logic/elwood 0.2.1 → 0.2.2

package/docs/cli.md

@@ -33,6 +33,8 @@ Pick an agent with `--agent`, `ELWOOD_AGENT`, or the config `agent` key. When
 nothing selects one, a new run auto-detects: Elwood tries `claude` first, then
 `codex`, and uses the first whose command resolves in your login shell. It only
 asks the shell `command -v`, so neither agent starts during detection.
+Detection runs from the effective workspace, so `-C`/`--cwd` changes the command
+lookup directory, including for `config effective`.
 `config effective` reports that choice with source `auto-detected`. If neither
 resolves, the run fails before launch with `no_agent_found` (status 2) and a
 message naming both agents and how to install or select one. Once an agent is

package/docs/codex/cli.md

@@ -28,8 +28,10 @@ Useful CLI capabilities for Elwood:
 - Some Codex versions expose `--dangerously-bypass-hook-trust`, which lets
   generated Elwood hooks run for one invocation without requiring a persisted
   trust prompt. Elwood must detect support before passing it because other Codex
-  versions reject unknown flags. Detection is cached for the lifetime of the
-  Elwood process.
+  versions reject unknown flags. Detection retains the derived boolean for up to
+  32 successful directory identities per process and is invalidated after an
+  update attempt. Version results use the same directory bound, and are retained
+  only when stdout and stderr each contain at most 65,536 UTF-16 units.
 - Codex can also render interactive trust and update prompts before the session
   is usable. Elwood should select `Trust all and continue` for hook prompts, and
   skip TUI update prompts because API-level `autoupdate` runs `codex update`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@with-logic/elwood",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Control interactive agentic coding CLIs (Claude Code, Codex) through real terminal sessions: typed hooks, a unified activity stream, resumable sessions, and a headless CLI.",
   "license": "MIT",
   "author": "Logic App, Inc.",
@@ -65,7 +65,7 @@
     "check:lines": "node --no-warnings scripts/check-lines.ts",
     "check": "npm run build && npm run typecheck && npm run lint && npm run check:lines && npm test",
     "check:all": "npm run check && npm run test:e2e",
-    "test:e2e": "exec node --no-warnings --experimental-test-coverage --test-coverage-include='src/**/*.ts' --test-coverage-exclude='tests/**' --test-timeout=240000 --test-concurrency=1 --test tests/e2e/*.e2e.ts",
+    "test:e2e": "exec node --no-warnings --experimental-test-coverage --test-coverage-include='src/**/*.ts' --test-coverage-exclude='tests/**' --test-timeout=240000 --test-concurrency=1 --import ./tests/e2e/codex-home.ts --import ./tests/e2e/claude-home.ts --import ./tests/e2e/run-dir.ts --test tests/e2e/*.e2e.ts",
     "dev:app": "exec node --no-warnings dev/dev.ts",
     "dev:web": "exec node --no-warnings scripts/supervise.ts dev/web/dev.ts",
     "example:minimal": "exec node --no-warnings scripts/supervise.ts examples/minimal.ts",
@@ -76,11 +76,11 @@
     "@biomejs/biome": "2.4.15",
     "@types/node": "^25.9.1",
     "@types/ws": "^8.18.1",
-    "@vitest/coverage-istanbul": "^4.1.11",
+    "@vitest/coverage-istanbul": "^4.1.12",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/xterm": "^6.0.0",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.11",
+    "vitest": "^4.1.12",
     "ws": "^8.21.0"
   },
   "dependencies": {

package/prd/04-architecture.md

@@ -45,10 +45,42 @@ This interactive login form (`-l -i` for zsh) applies to both the **agent PTY**
 and one-shot, non-PTY preflight probes (`--version`, `update`, `--help`). The
 same shell startup files MUST resolve the CLI for every lifecycle operation so
 preflight, update, launch, and resume cannot operate on different installations.
+A probe's shell startup and its command are bounded separately (§9.2), so a slow
+profile is not reported as a failing CLI.
 
 Elwood MUST provide diagnostics or tests proving that environment variables from
 the user's shell startup are visible to the launched agent process.
 
+Shell startup files can also export `CODEX_HOME`, which moves Codex's
+`config.toml`, and can derive it from anything the launch has: the directory the
+shell starts in (`$PWD`), whether it has a terminal, or the session's environment
+(`ELWOOD_SESSION_ID`). Elwood therefore never reads Codex's home from its own
+process environment, and does not ask a second shell, which would have neither
+the terminal nor the session's environment. The Codex launch script itself, after
+the startup files load and immediately before `exec codex`, writes the
+`CODEX_HOME` and `HOME` that a child process receives (only exported values,
+exactly what Codex inherits), and the directory it starts Codex in (`$PWD`), to a
+per-launch report in the session's private socket home (§8.1). If that write
+fails, the script exits with status 73 and never starts Codex, and a start that
+fails this way rejects with `codex_start_failed` whose `details.phase` is
+`"codex_home_report"` and whose `details.path` names the report. The session reads
+the report when a model operation first needs it. An operation can start before
+Codex does, so a report the launch shell has not finished is waited for within
+that operation's deadline, and a deadline that ends the wait rejects with
+`details.path` naming the report. The session applies Codex's own rule: a non-empty
+`CODEX_HOME`, canonicalized as Codex canonicalizes it (a relative value from the
+reported directory, following each symlink before a later `..`, as the kernel
+does), else `$HOME/.codex` (an empty `HOME` falls back to the account's home
+directory, and a relative one names a path from the reported directory, as Codex
+uses `HOME` as given). The session keeps the resulting `config.toml` path, and its configured
+default (§5.3 `isDefault`) and `setModel` snapshot and restore (C-CODEX-14) use
+only that file. A report that cannot be read, or a `CODEX_HOME` that does not
+exist, fails `listModels` and `setModel` with `model_automation_failed`, whose
+`details.path` names the report; `setModel` fails before it opens the picker, so
+Codex never persists a selection that Elwood could not restore. Elwood does not
+fall back to its own environment: guessing would read and restore a file that
+Codex might not use. C-CODEX-24.
+
 ### 4.3 Claude settings behavior
 
 Elwood MUST NOT mutate `.claude/settings.local.json` by default.

package/prd/05-api/5.1-starting-claude.md

@@ -27,7 +27,23 @@ type ClaudeReasoningEffort = "low" | "medium" | "high" | "xhigh" | "max";
 declare function startClaude(options: StartClaudeOptions): Promise<ClaudeSessionApi>;
 ```
 
-`cwd` is the working directory where Claude should start. `stateDir` overrides
+`cwd` is the working directory where Claude should start. It MUST already be a
+directory: otherwise `startClaude` rejects with `claude_start_failed`, whose
+`details` carry `cwd` and the failed check's `errno` (`ENOENT`, `ENOTDIR`, or,
+when the check itself fails, its own code such as `EACCES`), before it runs any
+probe, writes any state, or spawns Claude. A relative `cwd` is resolved against
+the process working directory when `startClaude` is called; one that can't be,
+because that directory was deleted, rejects the same way, with `cwd` as given.
+Because `cwd` can be removed while the probes run, it is checked again after
+preflight, before any state is written, and a launch that fails while `cwd` is
+gone, no longer a directory, can't be checked, or is no longer the directory
+that check found (it was deleted and made again) rejects the same way, keeping
+the failed launch's `cause` and any cleanup details (§9.1, §10). Elwood never
+creates it: a state directory is made only while `cwd` exists, one at or under
+`cwd`, the default `<cwd>/.elwood` or a caller's own, only below it, and no
+state write makes a missing parent (§8.1, C-STATE-14), so a deleted worktree is
+not silently recreated empty (C-API-61).
+`stateDir` overrides
 the default Elwood state directory. `name` is a launch-time convenience forwarded
 to Claude's documented `--name` flag; it is not persisted in Elwood state (§8.2).
 `hooks` registers

package/prd/05-api/5.2-resuming-claude.md

@@ -29,6 +29,11 @@ callers that resume from a different process working directory must pass the
 original `cwd` or the explicit `stateDir` used at start time. Calling
 `resumeClaude({ elwoodSessionId })` without `cwd` or `stateDir` uses the current
 process working directory to discover the project-local state store.
+Claude relaunches in the given `cwd`, resolved against the process working
+directory when `resumeClaude` is called (one that can't be resolved rejects as on
+start), else in the record's `cwd`. That
+directory must still be a directory, checked before and after preflight as on
+start, and `details.cwd` names it (§5.1, C-API-61).
 
 `resumeClaude` must verify that the persisted Elwood session record belongs to
 the Claude adapter before launching. Passing a Codex session ID to `resumeClaude`

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