@with-logic/elwood 0.2.1 → 0.2.2

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`

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.