@with-logic/elwood 0.2.1 → 0.2.2

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.
 

package/prd/12-e2e.md

@@ -17,6 +17,87 @@ CLIs, it is intentionally separate from `npm run check`. E2E coverage should be
 reported separately and made as high as practical; unit/conformance tests remain
 responsible for hard-to-force error paths and 100% default coverage.
 
+Neither gate may write the developer's own Codex home or read its state; the e2e
+suite only copies its `auth.json`. By default, every `test:e2e` process runs with
+`CODEX_HOME` pointed at a private directory seeded with only a 0600 copy of that file,
+removed when the process exits. A single e2e file run on its own gets the same default.
+A test that needs its own Codex config uses another private home, seeded the same way,
+for its duration. Whichever private home is active receives the project trust entries,
+model selections, sessions, and logs Codex persists while the suite drives it, so none
+of them reach the developer's config. The default gate runs each test file with `HOME`
+and `CODEX_HOME` pointed at a private directory. Both gates refuse to create these
+homes when the temp directory is inside the developer's Codex home.
+
+The e2e suite may not write the developer's own Claude config either. By default,
+every `test:e2e` process, and a single e2e file run on its own, runs Claude with
+`CLAUDE_CONFIG_DIR` pointed at a private directory, removed when the process exits.
+It is seeded with three copies: a 0600 `.credentials.json` holding the developer's
+Claude login without its refresh token, so the copy can never rotate and so
+invalidate the developer's own login. The login is read from where the developer's
+own Claude reads it. On macOS that is the keychain item Claude names for the developer's
+`CLAUDE_SECURESTORAGE_CONFIG_DIR` when it is set, else for their `CLAUDE_CONFIG_DIR`,
+set or not, and their `.credentials.json` only when there is no such item. On other
+platforms it is the `.credentials.json`. The suite removes
+`CLAUDE_SECURESTORAGE_CONFIG_DIR` from its own environment, so the Claude it runs
+reads the private copy, never the developer's item. The second copy is the developer's
+global config without its per-project entries, MCP servers, or bypass-permissions
+acceptance, and the third is Claude's cached model catalog. The global-config
+entry Claude writes for each scratch project, its transcripts, and its history land
+there, never in the developer's `~/.claude.json` or `~/.claude/`, which are only read.
+The private directory holds none of the developer's settings, so the suite runs Claude
+with Claude's defaults rather than the developer's permission mode, hooks, or plugins.
+The suite refuses to create it when the temp directory is inside the developer's Claude
+config dir.
+Each such process also points `CLAUDE_CODE_TMPDIR`, Claude's temp root, at a second
+private directory, removed when the process exits. Claude otherwise keeps its temp files
+under the shared `/tmp`: a directory per working directory, holding each session's
+scratchpad, which outlives the session, and its messaging socket. So no scratch project
+leaves a directory there. The suite keeps that variable when it drops the other
+`CLAUDE_CODE_` variables a parent Claude session set.
+A test that needs its own Claude config dir copies the login the same way, without the
+refresh token.
+
+Both CLIs start through the developer's login shell, whose startup files run after
+Elwood hands over its environment and could replace, unset, or unexport `CODEX_HOME`,
+`CLAUDE_CONFIG_DIR`, or `CLAUDE_CODE_TMPDIR`. So the suite registers each private CLI home
+and Claude temp root it creates in
+`ELWOOD_E2E_PRIVATE_HOMES`, a JSON array of absolute paths holding each home's given and
+real path, which the Elwood processes it starts inherit. Each e2e process discards the
+list it inherited and registers only the homes it creates, so an inherited entry, such as
+the developer's own home, is never accepted. Each of these variables that
+Elwood's own environment sets to a registered home is guarded. Every login shell Elwood
+starts, for a session or a probe, checks after its startup files that each guarded
+variable is still exported and that the real path of the directory it names, relative
+names resolved against the shell's working directory, is a registered home. If one is
+not, the shell writes a stop line with why and exits 97 before running its command, so
+no CLI starts against another home, the developer's own included. A value that is not
+such an array stops every launch the same way. Unset or empty, as outside the suite, the
+variable changes nothing.
+
+The stop line starts with a token Elwood draws once per process, so neither a startup
+file nor a command can print it. It is never written to stderr, which a startup file can
+redirect. A session's shell writes it to its terminal, which the session's PTY captures
+however the startup files redirected the shell's input and output, and falls back to
+stdout only when it cannot open the terminal. A probe's shell runs in a session of its
+own, with no terminal, so it writes the line where it wrote its start line (§9.2): on the
+probe's private channel, which a startup file's redirection of stdout cannot hide, or, from
+a shell that closed that channel at startup, on stdout. In that shell, a startup file that
+hid stdout hid the start line too, so the probe is the login shell's own failure.
+Elwood counts a launch as stopped by the guard only when its shell exited 97 and wrote
+that line. A command that itself exits 97 is the command's own failure. A session's
+startup check (§9.1) finds the line however much startup output came before it. Since a
+PTY's last output can arrive after its exit (§9.4), once the check sees a status-97 exit
+of a launch the guard checks, it waits up to one second more for the line; a launch the
+guard does not check fails at once.
+
+A probe runs the check after its start line (§9.2). A probe the guard stops after that
+line is a login-shell failure (C-PERF-05) whose only diagnostic is the guard's fixed
+reason: like any login-shell failure, its stderr is withheld. A login shell that exits
+before the start line is still the login shell's own failure. A session whose login
+shell the guard stops during startup (§9.1) fails with the adapter's `*_start_failed`,
+whose message names the guard instead of repeating the shell's output. A session stopped
+later exits with status 97, its terminal showing the stop line and the guard's reason.
+
 The repository should also provide `npm run check:all`, an opt-in convenience
 gate that runs the default `npm run check` gate and then `npm run test:e2e`.
 `check:all` does not change the composition of `npm run check`; the default gate

package/prd/12a-cli.md

@@ -28,7 +28,13 @@ A new session defaults to the invocation directory; `-C`/`--cwd` overrides it.
 When no flag, environment variable, or configuration key selects an agent, a
 new session auto-detects one: Elwood tries `claude` first, then `codex`, and
 uses the first whose command resolves in the user's login shell — the same
-resolution the agent launch itself uses (§4.2) — without running either agent.
+resolution the agent launch itself uses (§4.2), from the effective workspace — without
+running either agent.
+Before this unselected new-session auto-detection, including `config effective`,
+Elwood MUST validate the effective workspace under §12A.5, whether it comes from
+`--cwd` or the invocation directory. A workspace usage error takes precedence over
+`no_agent_found` or a probe failure. Explicit-agent and resume validation order is
+unchanged; resume never probes.
 Both probes run concurrently; the order only decides the winner. The resolved
 agent reports the source `auto-detected`. When neither command resolves, the
 invocation fails before any launch with the stable code `no_agent_found` and
@@ -106,12 +112,27 @@ setup turn and discards that turn's response before observing the user turn. It
 is a real agent turn: tools and other side effects performed during persona setup
 remain even though its assistant response is omitted from CLI output. Explicit
 persona plus resume is a usage error. An agent process exit before
-CLI-requested cleanup is `agent_exited`, including a zero-status exit. Response
-data already collected remains available on later failure.
+CLI-requested cleanup is `agent_exited`, including a zero-status exit. A Claude or Codex
+turn the agent rejects (§5.8), including the persona setup turn, is `turn_failed`
+rather than a successful result. Response data already collected remains
+available on later failure.
 
 Cleanup runs exactly once. A cleanup failure never masks a primary usage,
 agent, timeout, or interruption outcome, and it changes an otherwise successful
-invocation to failure.
+invocation to failure. Its diagnostic names only the typed Elwood failures behind
+it. Each always appears as its error code, followed by its errno token and then
+`reap` and its reap's errno token (§10 `termination_failed`) when those are valid
+errno names, then `process groups` and the ids in its
+`unconfirmedProcessGroupIds` (positive integers, at most 16) when it has any: for
+example `Cleanup failed (termination_failed EPERM).`, `Cleanup failed
+(termination_failed reap EPERM).`, or `Cleanup failed (termination_failed EAGAIN
+process groups 4242 4243).` Those ids are for diagnosis only and may already
+belong to other groups. For a failed teardown those are its failed
+steps', in order (§10 `teardown_failed`). The diagnostic never carries their
+messages or paths, and a failure with no typed cause reads `Cleanup failed.` In
+text mode, a cleanup failure behind a different primary failure is its own stderr
+line after the primary error's; a combined `models` listing (§12A.10) prefixes it
+with the agent, as it does that agent's error.
 
 ### 12A.3 Output protocols
 
@@ -213,13 +234,18 @@ symlinks, non-regular files, wrong ownership, and non-private permissions.
 CLI-owned state defaults to `$XDG_STATE_HOME/elwood` when that base is absolute,
 otherwise `~/.local/state/elwood`. It never defaults to the invocation
 workspace. CLI state directories and records MUST be private, owner-matched,
-regular where applicable, symlink-safe, and atomically written. One session
+regular where applicable, symlink-safe, and atomically written. A new session's
+state root is made only while its workspace exists, and one at or under the
+workspace only below it (§8.1, C-STATE-14). A workspace removed after it was
+validated fails the launch with the adapter's `*_start_failed` (C-API-61)
+instead of being recreated. One session
 identity supports at most one live owner; concurrent exact resumes may fail on
 the adapter's underlying startup conflict in v1.
 
-Exit status is 0 for success or consumer closure, 1 for agent or cleanup
-failure, 2 for usage or configuration failure, 124 for timeout, and 130 for
-interruption. A primary nonzero status survives cleanup failure. Text errors are
+Exit status is 0 for success or consumer closure, 1 for agent failure
+(including `agent_exited` and `turn_failed`) or cleanup failure, 2 for usage
+or configuration failure, 124 for timeout, and 130 for interruption. A primary
+nonzero status survives cleanup failure. Text errors are
 concise and go to stderr while structured protocols retain stable error codes.
 Unknown long options identify the token and suggest the nearest documented
 option when the match is unambiguous. Validation messages identify relevant
@@ -229,6 +255,29 @@ include sanitized event detail but never weakens §12A.3. Static arguments, envi
 compatibility MUST be validated before session creation whenever validation
 does not require a stored resume record.
 
+The effective workspace, new or resumed, MUST be an absolute, existing directory
+owned by the current user that no other user can replace before the agent
+launches in it. An OS directory-search permission check MUST also confirm the
+current user can enter it; refusal is a path-specific `invalid_arguments` usage
+error. This is a bounded check, not an atomic launch guarantee.
+Resolving its path as given, name by name and through every
+symlink, every directory a name is looked up in MUST be owned by root or the
+current user and MUST NOT be writable by group or others unless it is sticky,
+and every directory and symlink passed MUST be owned by root or the current
+user. A group-writable directory is accepted when its group is the user's
+private group: the user's primary group, with the same number as the user, as
+Debian, Ubuntu, and Fedora create it. Root's group 0 is a shared system group and
+never counts as private, even for root. Anything else is a usage error that names
+the directory or link and how to fix it. The replacement check reads owners and mode bits
+only: an ACL that grants another user write access, or another member added to
+the user's private group, is not detected, and where the platform reports no user
+id neither the ownership nor this check applies. The path is launched and
+stored as given. A link whose target is not UTF-8, or a path that follows more
+than 40 links, fails as uninspectable, naming the link.
+Workspaces under `/tmp` and the macOS temporary directories pass, those being
+sticky or the user's own; `/tmp` itself, owned by root, fails the ownership
+rule for every user but root.
+
 ### 12A.6 Same-terminal head mode
 
 `--head` is an opt-in, view-only terminal mirror for a run. It requires both a
@@ -402,7 +451,12 @@ Listing sessions resolves only state-directory and output settings. Adapter,
 model, permission, trust, and turn-lifecycle environment defaults are irrelevant
 and MUST NOT prevent listing. Config files still undergo strict schema decoding.
 Interactive foreground launches MUST resolve the executable in the same
-interactive login-shell environment used by auto-detection. If the shell exits
+interactive login-shell environment and effective workspace used by auto-detection, through the same
+bounded probe, so the user's startup files get the login shell's launch bound and
+the lookup the command bound (§9.2, C-PERF-05). The frame carries the login
+shell's own `$PATH`, printed by `/bin/sh`, which loads no startup file, so a
+`printf` function or alias in the user's startup files cannot print another
+PATH in its place. If the shell exits
 successfully without returning a complete PATH probe frame, the foreground
 launch MUST preserve the inherited PATH. A complete frame containing an empty
 PATH remains authoritative. C-CLI-24/25.