@with-logic/elwood 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -12,6 +12,576 @@ back each entry are listed in `prd/14-conformance.md`.
 
 ## [Unreleased]
 
+## [0.2.2] - 2026-11-03
+
+- Preserve custom state directories during rollback when another user could redirect their parent lookup.
+
+- State rollback records successful directory creation and checks observed ownership before removing empty scaffolding, preserving directories another actor created or replaced.
+
+- Shutdown permanently stops signaling a leader PID or group once its detached
+  sweep confirms the group gone, retaining any earlier unresolved descendant failure.
+  An exit during that confirmation waits for its shutdown owner’s final reap, and
+  saved sweep failures report the unresolved descendants and retain their unconfirmed
+  group IDs through teardown.
+
+- Shutdown bounds native process-table scans and daemon-path probes to two concurrent
+  subprocesses per parent process, preserving coalescing and existing read deadlines.
+
+- Resolve CLI auto-detection and interactive PATH lookup from the effective workspace, including relative and absolute `--cwd` overrides. Missing, non-directory or non-searchable workspaces report the path-specific usage error before auto-detection.
+- Run version, capability and update probes in the launch workspace, with bounded directory-identity caches so sessions cannot reuse another workspace's CLI results. A workspace removed or replaced during preflight reports a startup failure instead of a missing CLI.
+
+- Concurrent Elwood processes avoid repeating an automatic agent update that another process has completed.
+
+- Preserve native cause, `syscall`, and `path` diagnostics for probe failures surfaced as startup errors, including missing login shells; missing-command diagnostics withhold shell output.
+- Preserve a resolved CLI's diagnostic when it exits with status 127 instead of reporting it missing from PATH. A command lookup must fail before Elwood uses the fixed not-found diagnostic.
+- Clean up eligible empty state scaffolding after setup fails while retaining shared default directories and complete ignores that another setup may already use; report cleanup failures with the original error.
+
+- Install the default `.elwood/.gitignore` atomically without overwriting a competing writer or leaving partial contents after a failed write.
+
+- A session's final transcript flush, and a Claude subagent's retirement, now read
+  the first unread chunk (up to 256 KiB) of each transcript they drain, for up to 16
+  transcripts, before their 50 ms time limit can stop them. Before, a host too loaded
+  to begin the flush within that limit read nothing: the session's last records never
+  arrived as activity, and a `transcript_records_dropped` warning with cause
+  `unread_backlog` reported them instead. A record the flush cuts off is now part of
+  that `unread_backlog` warning instead of a second warning with cause `unparseable`.
+- The walk that reaps detached hook processes now reads each process's short name,
+  which `ps` prints raw, and refuses a table read it cannot trust instead of acting
+  on it: one with a line that is not one whole row, such as a line a newline in a
+  process's name starts, or with a pid listed twice. A refused read fails as an
+  unreadable table does, so while a process on the host has a newline in its name,
+  `kill()`, `teardown()`, and a `stop()` that escalates reject with
+  `termination_failed` (`teardown_failed` from `teardown()`).
+- A Codex session now removes the `codex-clipboard-*.png` file Codex saves in the
+  temp directory for each image Elwood pastes into it, once the session's CLI has
+  exited by `stop()`, `kill()`, `teardown()`, or on its own. Before, every Codex image
+  attach left one such file behind for good. Only files the session's own transcript
+  names directly in Elwood's temp directory are removed; a Codex whose login shell sets
+  another `TMPDIR` keeps its copies there.
+- A Codex session that cannot remove one of those copies now emits one
+  `image_copy_removal_failed` warning before `terminal:exit`. Its `errorCode` is the
+  first failure's errno token, or `UnknownError` when it has none. The copy is left
+  for the OS to reap. A copy that was already gone is not a failure.
+- A CLI missing from the login shell's PATH is reported as `claude_not_found` or
+  `codex_not_found` even when the user's startup files define a not-found handler
+  (zsh's `command_not_found_handler`, bash's `command_not_found_handle`). The probe
+  ran the handler, so a handler that returned another status made a missing CLI
+  read as `*_start_failed`, and whatever it printed reached that error's
+  `details.stderr` or `agent_update_failed`'s `raw`. Probes now remove both
+  handlers before running the CLI.
+- A probe whose command dies of a signal now reports the status a shell would,
+  128 plus the signal's number, instead of no status. A login shell that dies
+  before starting the command is still a login-shell failure. `elwood interactive`'s
+  PATH lookup likewise now fails with "login shell exited with status 143" where it
+  said "status null".
+- `*_start_failed` details and the `agent_update_failed` warning now carry a failed
+  probe's exit status as `exitStatus`, as the spec already said the warning would.
+- `kill()`, `teardown()`, and a `stop()` that escalates now give the walk that reaps
+  detached hook processes ten seconds, up from three, before they reject with
+  `termination_failed` (`teardown_failed` from `teardown()`). On a loaded host, one
+  process-table read can take over half a second, and a hook that started a detached
+  child of its own takes six reads. So these calls rejected, and kept rejecting,
+  while the walk was still making progress. The ten seconds bound the walk, not the
+  whole call: `kill()` and `teardown()` also wait for the PTY to exit after their
+  SIGKILL, and a `stop()` that escalates waits out its graceful window first. On an
+  idle host they take as long as before, because the walk ends as soon as it is done.
+- `stop()`, `kill()`, and `teardown()` during an in-flight image attach now remove
+  the attach's `elwood-image-*` temp directory before they resolve, even while its
+  image is still being written. Before, the attach removed it only after it unwound,
+  which could come after shutdown resolved, so a host that exited right away left
+  the directory in the OS temp dir. Removal stays best-effort: one that fails at
+  shutdown is retried when the attach unwinds.
+- `elwood interactive` hands the agent the login shell's own PATH even when the
+  user's startup files define a `printf` function or alias. The PATH lookup ran
+  the login shell's `printf`, which such a function or alias replaced, so the
+  agent could get another PATH, or Elwood's own when nothing framed was printed.
+- `teardown()`, `kill()`, or a `stop()` that escalates no longer end Codex's shared
+  app-server daemon, its updater loop, or what the daemon started, such as plugin
+  MCP servers. Codex 0.158+ can start the daemon for its `CODEX_HOME`, for every Codex
+  on that home, yours included, as a detached child of the TUI: when the session's
+  own TUI had started it, the walk that reaps detached hooks SIGKILLed it.
+- A Claude session resumed under `autotrust` now reaches `ready` after Elwood answers
+  a startup trust gate, such as the bypass-permissions dialog when a resume adds
+  `highTrust` in a config that never accepted bypass mode. Before, it stayed
+  `running` after the gate cleared: the resumed transcript repaints the earlier
+  prompts as `❯ <prompt>`, and Elwood did not count the composer below them as
+  proof that the gate was gone.
+- A Claude session whose permission dialog is declined with Escape now returns to
+  `ready`, as C-ATTN-02 requires, and releases queued input. Before, it stayed
+  `blocked` while the prompt that led to the dialog was still on screen: Claude
+  echoes each submitted prompt as `❯ <prompt>` in its transcript, and Elwood read
+  that caret as a dialog still in the way of the idle composer.
+- Codex sessions now use the `CODEX_HOME` their login shell exports, not
+  Elwood's own. The launch script writes the exported `CODEX_HOME` and `HOME`, and
+  the directory it starts Codex in, to a private report just before `exec codex`,
+  and starts Codex only if that write succeeds. `listModels()` reads `isDefault`
+  from that home's `config.toml`, and `setModel` snapshots and restores that file.
+  Elwood used to read and restore `$CODEX_HOME` or `~/.codex` from its own
+  environment, which, when a profile moved the home, reported the wrong default and
+  restored a file Codex never touched while leaving the picker's change in the real
+  one. A relative `CODEX_HOME` or `HOME` resolves as Codex resolves it, from a
+  symlinked `cwd` too. A model operation that starts before the report is written
+  waits for it within its deadline, and a deadline that ends the wait names the
+  report in `details.path`. A report that cannot be read rejects with
+  `model_automation_failed`, and `setModel` rejects before it opens the picker. A
+  start whose report could not be written rejects with `codex_start_failed` and
+  `details.phase: "codex_home_report"`. `listCodexModels()` and `elwood models`
+  follow the same rule.
+- A Claude session started with `highTrust` or `permissionMode: "bypassPermissions"`
+  now answers Claude 2.1.310's bypass-permissions acceptance dialog under
+  `autotrust`, as C-CLAUDE-21 requires. Claude 2.1.310 added a sandbox warning and a
+  security-guide link to the dialog, and Elwood did not recognize the longer copy,
+  so the session stayed `blocked` wherever the dialog renders: a Claude config that
+  has never accepted it and whose settings do not set
+  `skipDangerousModePermissionPrompt`.
+- A session that ends without `teardown()` no longer leaves an empty
+  `elwood-<fingerprint>` directory in the OS temp dir. `stop()`, `kill()`, the
+  agent exiting on its own, and a failed start now remove the session's socket
+  home once the launch's own socket file is gone, unless another live launch of
+  the same session still has its socket there. The next start or resume
+  recreates the home. Previously every stopped or failed session kept its empty
+  home until it was torn down.
+- A start or resume whose launch fails while its `cwd` is deleted and made again
+  now fails with the adapter's `*_start_failed` for that `cwd`, as it does when
+  `cwd` is simply gone. It used to find the new directory in its place and report
+  the launch's own failure instead.
+
+- A resume that fails partway through launching, such as when its PTY can't be
+  spawned, no longer leaves its session's expired loops pruned from `loops.json`.
+  Resume removes expired loops before it starts the agent and again as it commits,
+  and both writes now belong to the launch's startup publication, which a failed
+  launch restores, as it already restored the session record. A prune the earlier
+  session made meanwhile, through `listLoops()` for instance, stays.
+- Starting a session whose `cwd` was deleted no longer recreates it. The default
+  state directory lives under `cwd`, and creating it created every missing parent,
+  so a session for a deleted worktree started in a new, empty directory. A state
+  directory is now made only while `cwd` exists, and one at or under `cwd`, the
+  default `.elwood/` or your own `stateDir`, only below it, so such a start
+  rejects before spawning and the worktree stays gone, as does a `stateDir`
+  elsewhere. State writes no longer make missing parent directories either, so a
+  running session whose state directory was in its removed worktree fails its
+  later writes (a new loop rejects with `loop_persistence_failed`), and a resume
+  whose state directory is removed fails, instead of recreating either.
+- `elwood run` no longer recreates a workspace removed between its validation
+  and the launch when `--state-dir` is inside it. The CLI made its state root
+  with every missing parent, the workspace included. It now makes the root only
+  while the workspace exists, and the launch fails with `claude_start_failed` or
+  `codex_start_failed`, with `details.cwd`, instead. A state root elsewhere, the
+  CLI's own or a library `stateDir`, that is made while the workspace is being
+  removed is removed again rather than left behind, unless another start has
+  put its session in it meanwhile; a directory that can't be removed shows as
+  `details.cleanupErrorCode`.
+- Starting or resuming a session whose `cwd` does not exist now rejects with
+  `claude_start_failed` or `codex_start_failed`, with `details.cwd` and
+  `details.errno`, before any probe, state write, or spawn (resume reads and
+  validates its record first), instead of failing on a state write. A `cwd` that
+  is a file is rejected the same way, and so is one removed while the start's
+  version probes run, and a relative `cwd` that can't be resolved because the
+  process's own working directory was deleted. A launch that fails while `cwd`
+  is gone, no longer a directory, or can't be checked reports the same error and
+  keeps the launch failure's `cause` and cleanup details. A resumed Claude
+  session with a relative `cwd` now launches in the directory it checked, even
+  if the process working directory changes during the probes.
+  rejects before spawning (for now with `ENOENT`) and the worktree stays gone,
+  as does a `stateDir` elsewhere. State writes no longer make missing parent
+  directories either, so a running session whose state directory was in its
+  removed worktree fails its later writes (a new loop rejects with
+  `loop_persistence_failed`), and a resume whose state directory is removed
+  fails, instead of recreating either.
+- Codex `listModels()` and `setModel` no longer freeze the process when
+  `config.toml` is a FIFO. Elwood read the file with a blocking read, so a FIFO
+  left in its place, by an agent that can write to its `CODEX_HOME`, blocked the
+  event loop and every session in the process until something wrote to it. Elwood
+  now opens the file without waiting, reads it only if it is a regular file of at
+  most 1 MiB, and rejects anything else with `model_automation_failed`
+  (`details.code` `EFTYPE`, `EISDIR`, or `EFBIG`). A `setModel` that cannot read
+  the config now rejects with `model_automation_failed` before it opens the picker,
+  and one that cannot reread it for the restore rejects the same way; both used to
+  reject with the raw file-system error.
+- Elwood now recognizes Codex 0.164's folder-access and `Hooks need review` gates as
+  0.164 draws them when hook trust is not bypassed: the folder gate's decline reads
+  `Back to Agent Command Center`, and the two gates end in `enter continue · esc back`
+  and `enter confirm · esc skip`. Before, both gates were held but never answered.
+  Each of these footers counts only under its own gate, so the same text under any
+  other dialog or in conversation text makes no frame a trust gate. Elwood's own
+  launches bypass hook trust, so they get the `Quit` / `enter continue · esc quit`
+  layout Elwood already handled.
+
+- The CLI now refuses a workspace that another user could swap out before the
+  agent starts in it. It checked that the workspace was yours, then launched in
+  its path, so anyone able to write to a directory on that path, or to a
+  directory holding a symlink on it, could replace it with their own in between.
+  Every directory the path is looked up through must now be owned by you or root
+  and not writable by group or others unless it is sticky (your own private group
+  is fine, but not root's group 0), or the run fails with status 2 naming the
+  directory to fix. Workspaces under `/tmp` or the macOS temporary directories,
+  and home paths, are unaffected. Owners and mode bits only: ACLs are not
+  checked.
+
+- Elwood now runs at most 8 login-shell probes (`--version`, `--help`, `update`,
+  and PATH lookups) at once in a process; more wait their turn, and a probe's time
+  bounds start when it runs. Each probe starts an interactive login shell, and with
+  a heavy shell profile many at once slowed every one of them.
+
+- A `claude --version` or `codex --version` check that fails (it exits nonzero,
+  times out, or cannot start) no longer fails every later start of that adapter
+  in the process. Elwood kept the failed result and replayed it as the same
+  `claude_start_failed` or `codex_start_failed`; a later start now runs the
+  check again. Concurrent starts still share one check and its outcome.
+
+- `teardown()`'s retry of a failed process-group reap now fails with the typed
+  `termination_failed`, as `stop()`'s and `kill()`'s retries already did. Before,
+  its raw system error made the retry an untyped step failure, so
+  `teardown_failed.details.failures` lost its errno and process-group id and the
+  CLI's cleanup diagnostic read only `Cleanup failed.` when no other step was
+  typed.
+
+- `teardown_failed` now keeps what each failed step reported. Alongside
+  `details.causes` (the messages), `details.failures` lists each failed step,
+  with its `code` and `details` when it was a typed Elwood error, so a failed
+  reap's `termination_failed` errno is no longer lost. The CLI's cleanup
+  diagnostic names those typed causes by code, plus their valid errno and reap
+  errno tokens when present, for example `Cleanup failed (termination_failed
+  EPERM).`, instead of only `Cleanup failed.`; it still never prints their
+  messages or paths. In text mode, a cleanup failure behind a timeout,
+  interruption, or other primary failure now gets its own stderr line after the
+  primary error, in `run`, `models`, and combined `models`; before, text mode
+  printed only the primary error.
+
+- A `stop()` or `kill()` whose termination fails now still cleans up the
+  session's runtime (its hook bridge and terminal renderer, and Codex's transcript
+  watcher). Before, a PTY that could not be signaled, did not exit, or could not be
+  reaped skipped that cleanup, and so did every retry while the reap kept failing,
+  until a `teardown()`. The call still rejects with the same `termination_failed`;
+  if cleanup fails as well, its message is in `details.cleanupError`. `close()`
+  keeps those messages too, as `cleanupError` and `killCleanupError`.
+
+- Raw input a host sends from inside one of Elwood's own writes, such as from an
+  `xterm.onData` listener reacting to Elwood's keys, now revokes Elwood's
+  automation like any other raw input. Before, it counted as part of Elwood's
+  write, so a model-picker operation, composer cleanup, question answer, or
+  startup-prompt answer kept writing after the caller's keys.
+
+- A Claude session's runtime cleanup now finishes its transcript watcher, as
+  Codex's already did. Before, only the Claude process's exit finished it, so
+  after a `stop()`, `kill()`, or `teardown()` that could not terminate the PTY,
+  the session kept polling the transcript and emitting its activity. Claude's
+  `transcript_poll_stopped` warning for a failed final flush now reads
+  "Transcript final flush failed after an unexpected error.", without "at exit",
+  since runtime cleanup can now run that flush while the PTY lives.
+
+- Sessions start again for macOS users whose login shell is `/bin/bash` or
+  `/bin/sh`. macOS's bash 3.2, started as an interactive login shell, closes
+  every inherited descriptor above stderr, so the probe start line added for
+  slow profiles never arrived on descriptor 3. Every `--version`, `--help` and
+  `update` probe, and the CLI's agent detection, failed with `login shell
+  exited with status 0 before starting the probe command`
+  (`phase: "login_shell"`), even though the command had run. A shell that
+  closed descriptor 3 now writes the line on stdout, and Elwood removes it from
+  the captured output.
+- Codex `setModel` and `listModels` calls on sessions that use different
+  `config.toml` files no longer wait on each other. The lock that keeps two switches
+  from interleaving their snapshot and restore was shared by every Codex session in
+  the process, so a slow switch in one home could use up another home's picker
+  deadline and fail it with `model_automation_failed`. Each config file, the one the
+  session's launch shell reported, now has its own lock, and paths that name the same
+  file through a symlink, another letter case, or another Unicode form share it, even
+  before Codex creates the file. On a case-sensitive volume, two configs whose paths
+  differ only in case share one lock too. A config path that cannot be resolved, such
+  as a symlink loop, rejects with `model_automation_failed`.
+- A Codex `stop()` or `teardown()` that gives up waiting for the ended turn's record
+  now says so. When the 2-second wait runs out with Codex still running, the session
+  emits one content-free `turn_commit_wait_expired` warning, with its `activity`, before
+  signaling Codex, even when `stop()` and `teardown()` overlap. A host can then tell
+  that a resume may show that turn as interrupted.
+- Stopping a Codex session as soon as a turn ends no longer cuts off Codex before it
+  records the turn. Codex records a turn as complete only after its `Stop` hook
+  returns, and Elwood reports `ready` from that hook, so a `stop()` or `teardown()`
+  called at that `ready`, or from a `Stop` hook observer, could end Codex before it
+  wrote the record. Resuming the conversation then showed "Conversation interrupted".
+  Both now give Codex up to 2 seconds to record the turn before signaling it, about
+  100 ms in practice; past that bound they proceed and the turn can still be lost.
+  `kill()` still ends Codex at once.
+- `listModels` and `setModel` now read each picker frame they wait for while
+  opening and moving through the picker as soon as it renders, rather than at the
+  next 100 ms poll. They return sooner and hold the session's
+  input queue for less time. The poll remains as a fallback when no render
+  notification arrives.
+
+- A Codex session whose readiness falls back to the 60-second backstop now emits
+  an `initial_ready_backstop` warning, so a host can tell it from ordinary
+  readiness. The backstop releases readiness when Elwood never recognizes Codex's
+  configured composer (the model footer), for example after a layout change in a
+  new Codex release. Before, that readiness looked like any other.
+
+- Removing a Codex transcript that Elwood was reading now emits
+  `transcript_read_error` with `lastErrorCode: "ENOENT"` on each poll while the
+  file is missing, and at the final flush if it is still gone, as a removed Claude
+  transcript already does. Elwood used to
+  read the missing file as an empty, truncated one and say nothing, so a host lost
+  the session's transcript activity without a warning. A transcript that has not
+  been created yet still waits silently.
+
+- A Codex session no longer reports `ready` before a late directory-trust prompt
+  is answered. Codex paints an empty composer while it boots, before its session is
+  configured, and under load its trust prompt followed 11 to 31 seconds after the
+  first frame. Elwood's 10-second readiness deadline fired on that boot composer,
+  so the session reported `ready` before the prompt even appeared (24 of 32
+  loaded launches on Codex 0.164). The deadline now waits for the composer with
+  Codex's model footer, which appears once the session is configured, so a cold
+  start can now take longer than 10 seconds to report `ready`.
+  A backstop still releases readiness 60 seconds after the first frame if that
+  footer is never recognized; a prompt painted after that would still follow
+  `ready`.
+
+- `autotrust` no longer sends "1" to Codex as a user message. On a loaded
+  machine Codex 0.164 can take the directory-trust answer (`1` + Enter) but
+  paint its composer more than 250 ms later, and Elwood's retry typed the answer
+  again into that composer, which submitted "1" as a turn to the model. The
+  number is now typed once. Codex retries are Enter alone while the gate's
+  caret is on the affirmative, which confirms the gate and does nothing on an
+  empty composer. Other numbered gates are answered again only after new output
+  still shows the gate.
+
+- With `autotrust`, keys a caller sends with `sendKeys` (or `terminal.sendInput`,
+  `xterm.input`) while a trust prompt is on screen now hand that prompt to the
+  caller: Elwood stops answering it. Before, its retry could follow the caller's
+  keys. When the CLI had already left the prompt but Elwood's screen had not caught
+  up, that retry landed in the composer and submitted the caller's text along with
+  the answer. A prompt the caller owns that stays up past five seconds is reported
+  `blocked`, as before; a later trust prompt is answered as usual. The same keys
+  also stop Elwood retrying its skip choice on a Codex update prompt, which could
+  otherwise follow them onto whatever Codex drew next. Elwood then leaves that
+  update prompt to the caller until Codex shows its composer.
+
+- A successful `listModels` or `setModel` no longer releases queued input on the
+  first frame without the picker. It now waits until no part of the picker has
+  been the bottom of the screen across five readings at least 40 ms apart. Before,
+  a blank or half-painted repaint could end the operation and let a queued
+  message's Enter land in the picker when it painted again, applying the
+  highlighted model. Picker text quoted above the composer does not hold the
+  operation. Each reading first renders all output the terminal has received, and
+  one that cannot fails the operation with `model_automation_failed` instead of
+  reporting success.
+- A Codex turn the agent rejects, for example one run with an unknown model, now
+  fails with `turn_failed`. `CodexSession.send` rejects, `stream` throws after the
+  events it already yielded, and `elwood run` exits 1, as Claude rejections already
+  do. Codex fires no `Stop` hook for such a turn. On Codex 0.164.0, `send` resolved
+  `''` about 20 seconds later, as if the turn had succeeded with an empty reply, or
+  stayed pending until the CLI exited, and `elwood run` exited 0 with an empty
+  `response`. The evidence is the transcript's failed `task_complete` for the turn's own
+  `turn_id`. The error message is Codex's `error.message`, and
+  `details.agentError` is its `codex_error_info` kind (for example `other`).
+
+- `autotrust` now reports an answered Claude folder-trust prompt. Claude erases
+  the dialog as soon as it is answered, then shows a blank or banner-only screen
+  until its composer paints. Elwood treated that screen as the answer being
+  lost, so the `startup_prompt` activity (`workspace_trust`, for example
+  `sent home+down+enter`) never fired: 0 of 30 real launches on Claude Code
+  2.1.310 emitted it. The answer is now reported once, when the composer
+  appears. Codex 0.164 lost its directory-trust answers the same way (0 of 16
+  fresh git-folder launches reported one); they are now reported too.
+
+- `kill()`, `teardown()`, and a `stop()` that has to escalate no longer leave a
+  CLI hook running after the session ends. Claude and Codex start every hook
+  command in its own session and process group, so killing the CLI's process
+  group missed a hook still in flight, such as a slow `SessionEnd` hook; it kept
+  running under PID 1. Before Elwood SIGKILLs a live CLI it now freezes it,
+  finds those descendants by parent pid, and kills their groups (a process whose
+  own parent already exited is under PID 1 and out of reach). That adds two
+  process-table reads to those paths, or four when such a hook exists, because
+  Elwood acts only on processes two consecutive reads show stopped; deeper
+  nesting, or a process forked as the CLI was frozen (Elwood stops its group
+  again), takes more reads within a three-second bound. Sessions shutting down
+  together share reads. If the walk cannot confirm every group stopped (including
+  when the CLI exits on its own first), the call still kills the CLI and then
+  rejects: `stop()` and `kill()` with `termination_failed` (with up to
+  16 of the unconfirmed process-group ids in `details.unconfirmedProcessGroupIds`),
+  `teardown()` with `teardown_failed`, and later shutdown calls on that session
+  keep rejecting. The CLI's cleanup diagnostic names those ids too, for example
+  `Cleanup failed (termination_failed EAGAIN process groups 4242).` The walk also
+  reaps the shell Codex starts a few seconds after launch to snapshot the user's
+  shell environment, which a slow shell profile keeps running. A `stop()` that
+  Codex exits on gracefully is not walked, so a snapshot shell still running then
+  is left running.
+
+- A failed start or resume (`startClaude`, `startCodex`, `resumeClaude`,
+  `resumeCodex`) whose cleanup could not confirm that the CLI's process group was
+  reaped now says so. The typed startup error keeps its code and
+  message and gains `details.cleanupErrorCode` (an allowlisted errno, else
+  `UnknownError`) and `details.cleanupProcessGroupId`, which is for diagnosis only and
+  must never be signaled. Before, that failure was dropped silently. When a PTY is not
+  confirmed terminated and its group reap fails too, `termination_failed` now also
+  carries the reap's errno as `details.reapErrno`, next to `details.reapError`.
+
+- On Claude Code 2.1.310, `send` no longer returns an empty or truncated reply, and
+  `stream` no longer ends early, when a turn takes more than about two seconds to
+  produce text. A Claude session also stays `running` for the whole turn instead of
+  flipping to `ready` and back about once a second. Claude 2.1.310 alternates its
+  working window title between `◐` and `◑`, and Elwood read every `◑` frame as idle.
+  An ergonomic turn treated that false `ready` as the start of its 2-second quiet
+  window. Both half circles now mean working.
+
+- A failed start or resume no longer signals a CLI that already exited during startup,
+  and no longer reaps its process group a second time. The leader's pid could already
+  belong to another process. Cleanup used to send that pid SIGTERM and then SIGKILL and
+  wait about six seconds for an exit that had already happened.
+
+- Resuming a Codex 0.164.0 session no longer reports a phantom `running` → `ready`
+  turn shortly after readiness, which a host could show as a false unread reply.
+  Codex 0.164.0 first paints `Resuming session…` above its composer and then loads the
+  conversation under a working title spinner; Elwood counted the placeholder's repaints
+  as proof the replay had finished. It now waits for that load to end. When the replayed
+  conversation ends in `Conversation interrupted`, the false turn appeared twice.
+- `stop()` and `kill()` reject with `termination_failed` when signaling the PTY itself
+  throws. They used to pass the raw system error through, whose own `code` (for example
+  `ESRCH`) read like an Elwood error name. The underlying message is kept as
+  `details.cause`, with `errno`, `syscall` and `path` when present.
+
+- A slow login-shell profile no longer fails startup as `claude_start_failed` /
+  `codex_start_failed` ("`--version` failed", `ETIMEDOUT`). Preflight probes run
+  through the user's interactive login shell, and the fixed 15-second bound counted
+  loading that profile as the CLI's time. Under 16 concurrent headless runs on a
+  loaded machine the profile alone took 7–19 seconds, while the CLI answered in
+  milliseconds. The shell now has 60 seconds to load the profile, and the CLI still
+  has 15 seconds from then. A shell that never starts the probe, by timing out or by
+  exiting first, fails with a cause naming the login shell and `details.phase:
+  "login_shell"`; for `autoupdate` the `agent_update_failed` warning carries
+  `errorCode: "login_shell_failed"`. The profile's own startup output is left out of
+  both, since it can contain expanded secrets. A contender waiting on another process's update
+  now waits up to 165 seconds instead of 60, so it does not give up and re-read the
+  version while the owner's version and update probes are still within their bounds.
+
+- `autotrust` no longer reports a Claude folder-trust prompt that it has
+  already answered as needing attention. Claude erases the dialog at once but
+  can take several seconds to paint its composer, longer under load. Elwood
+  counted that wait against the prompt's five-second limit, so the session
+  briefly went `blocked` with `claude-workspace_trust-prompt` attention while no
+  prompt was on screen. That happened in 17 of the 27 launches that reached
+  `ready` (out of 30 started, 10 at a time in fresh folders) on Claude Code
+  2.1.310. Headless `elwood run` killed those sessions
+  and failed with `blocked_prompt` (5 of 7 concurrent fresh-folder runs). The
+  limit now counts only time the prompt is on screen. Queued input is still
+  held until Claude's composer appears.
+
+- A fresh Claude session no longer emits `transcript_read_error` (`ENOENT`) while it waits
+  for its first turn. Claude names its transcript at startup but writes the file only once
+  a turn begins, and Elwood had reported each poll of the missing file as a read error.
+  Removing a transcript after it existed still warns, as does any other read failure.
+- A Claude transcript removed between a poll's size check and its read now warns
+  `transcript_read_error` (`ENOENT`) on that poll. Before, the read took the missing file
+  for a truncation: it skipped the warning and rewound to the start, so a file restored
+  before the next poll replayed its earlier records as new activity. The same warning
+  now covers a seen transcript that is missing when a stopped subagent's transcript is
+  drained, at the final flush, and at a `Stop`-first tail recovery, which each read it
+  as empty before. A transcript that was never created still reads as nothing.
+- `listModels` and `setModel` no longer send a picker key into a prompt that has
+  reached the terminal but has not rendered yet. Each arrow, selecting key, follow-up
+  answer and Escape is now decided after every received byte is rendered, like
+  queued input and failure cleanup already were. If the screen cannot be verified,
+  the key is withheld and the operation fails with `model_automation_failed`.
+  Before, an arrow chosen from the stale picker frame could move a permission or
+  question prompt's selection.
+
+- A Claude turn that Claude itself rejects, such as one sent with a model that does not
+  exist, now fails with the new `turn_failed` error instead of passing as a successful
+  reply. `ClaudeSession.send` rejects and `stream` throws after its collected events;
+  `error.details.agentError` carries Claude's error name (for example `model_not_found`).
+  `elwood run` exits 1 with a `turn_failed` error record where it used to exit 0 and
+  print Claude's error text as the response. A late rejection whose `prompt_id` names an
+  earlier submission than the current turn's does not fail the current turn. When either
+  hook lacks a `prompt_id`, a rejection that arrives during a turn is attributed to that
+  turn.
+
+- A failed model operation no longer releases queued input on a blank or half-painted
+  frame left after its cleanup. Elwood never sends a key, Escape included, to a picker
+  that has not finished painting or to a bare `Select model` header, which agent output
+  can print; failure cleanup cancels the dialog once it is recognizable. Until the
+  composer is positively clear, queued input stays held, because Enter on a repainting
+  picker applies its highlighted model.
+
+- Claude `listModels`, `listClaudeModels` and `setModel` work on accounts whose model
+  list is longer than the picker's ten-row window, and on any row whose effort control
+  is Medium, High or Max. Elwood now recognizes the scrolled picker (`↑`/`↓` rows,
+  `… +K models`) and every measured effort glyph, and follows the cursor across a
+  scrolling window. `listModels` also returns the `↓`-marked last visible row, with the
+  marker kept in its `raw`.
+- Claude `listModels()` and `listClaudeModels()` return every model the `/model`
+  picker lists, not just its ten-row window: an account with 13 models now gets 13
+  rows, in picker order. Elwood reveals the hidden rows with arrow keys and then
+  cancels, so the model and effort are unchanged. `setModel` can select any listed
+  row, including one outside the window, walking only until that row is on screen,
+  and an unknown id's error lists every row. The list's length is the highest
+  rendered row plus the `… +K models` count, and `K` falls as the window scrolls
+  while that sum stays the same. A frame that marks rows hidden without a count, or
+  implies a different length from the first one read, is never acted on: Elwood waits
+  for a repaint that matches, and fails with `model_automation_failed` at the timeout
+  rather than returning part of the list. A frame with no count line is read as the
+  whole list; Claude 2.1.310 paints that line before the dialog's footer, so a complete
+  dialog always carries it.
+- `listModels` and `listClaudeModels` no longer return a partial catalog read while
+  the picker was still painting. Claude draws it over the slash-command menu, so a
+  probe could return only `default`, or fail with "Could not parse any model picker
+  rows". The picker is parsed only once the complete dialog is on screen.
+
+- Codex `setModel` works on Codex 0.164.0, whose model picker closes with an
+  `enter select · esc back` hint and whose reasoning screen closes with
+  `enter default · s session · esc back`. It failed on its first key with "The model
+  picker was replaced".
+
+- Queued input stays held on a model dialog until the composer is positively
+  clear. A dialog that survived a failed model operation's cleanup could be
+  forgotten after five frames that neither grammar recognized, such as a blank
+  or half-painted repaint. Any hold could also be cleared by five readings
+  taken in the same instant. Either way, a queued message could be typed into
+  the picker, where Enter applies the highlighted model.
+
+- `autotrust` no longer makes Claude exit at its folder-trust prompt. Claude
+  Code resets that dialog's selection to "No, exit" a moment after it opens, so
+  under load Elwood's Enter could land on "No, exit" and the CLI exited with
+  code 1 (7 of 60 fresh-folder launches on 2.1.310). Elwood now selects
+  Claude's trust options by absolute position (Home, then Down) and sends Enter
+  in the same write as that selection, so a reset, a delayed key, or a retried
+  key can no longer confirm another option. The `startup_prompt` input text for
+  cursor-layout prompts now names the absolute sequence (`home+enter`, or
+  `home+` then one `down+` per row above the affirmative, then `enter`) instead
+  of a cursor-relative label such as `enter`, `up+enter`, or `down+enter`.
+
+- Codex `listModels()` and `listCodexModels()` no longer report the session's
+  current model as the configured default. Codex 0.164 marks only the current
+  row, so `isDefault` now follows `config.toml`: the `model` of the profile the
+  root `profile` key selects, else the root `model`. A session launched or
+  switched onto another model keeps the configured row as its default, and a
+  config that names no model reports no default. A `config.toml` that exists but
+  cannot be read rejects the listing with `model_automation_failed`. Listings and
+  `setModel` restores keep using the `config.toml` path captured at session
+  launch, even if `CODEX_HOME` changes later.
+
+- Claude questions are raised again on Claude Code 2.1.310 and in named
+  sessions (`name`). 2.1.310 pads the single-question header chip with a
+  trailing space, and a named session draws its label into the border below the
+  questionnaire; either one left the native dialog on screen without raising
+  the question.
+
+- Named Claude sessions (`name`) recognize their composer again. Claude insets
+  the name into the composer's top rule, which kept trust clearance and
+  empty-input checks from matching: a named session in an untrusted folder
+  stayed `blocked` after autotrust answered the trust prompt.
+
+- Claude sessions recognize their idle composer in every permission mode after
+  the version banner has scrolled away. Elwood accepted only the exact footers
+  captured earlier (auto mode and don't ask on 2.1.278, manual mode on 2.1.305).
+  On Claude Code 2.1.310 it missed bypass permissions, accept edits and plan mode,
+  footers that end in a token count or effort level, and footers that have
+  dropped the `← for agents` hint. In a long session, trust clearance, the
+  model-picker hold and empty-input checks then never saw the idle composer.
+
+## [0.2.1] - 2026-10-24
+
+- Reduce median active Elwood CPU by 11.3% in the measured 50-session workload
+  by sharing completed-frame text, preserving fresh public snapshots and direct
+  xterm writes.
+
 ## [0.2.0] - 2026-10-22
 
 - Codex question turns settle after native completion even when consecutive answer echoes contain caret-like multiline text.
@@ -292,7 +862,7 @@ back each entry are listed in `prd/14-conformance.md`.
   records those even when its signal did not take. The wait now applies whether the
   switch succeeded or failed: the question is whether the dying CLI can still write
   `config.toml`, not whether Elwood's automation worked.
-- A Codex `setModel` still waiting for the process-wide `config.toml` lock rejects
+- A Codex `setModel` still waiting for its `config.toml` lock rejects
   with `session_not_running` as soon as its own session closes, instead of staying
   pending until the session ahead of it finishes its transaction and exit wait. A
   cancelled call never runs its switch when the lock frees.

package/CONTRIBUTING.md

@@ -21,6 +21,9 @@ The instructions below are for maintainers. This project is spec-first:
 
 ## Setup and checks
 
+For source-checkout Git hooks and repository secret-scanning exceptions, see the
+[maintainer guide](https://github.com/with-logic/elwood/blob/main/.github/secret-scanning.md).
+
 ```sh
 npm install
 npm run check

package/README.md

@@ -122,8 +122,10 @@ elwood --resume <sessionId> "What is the release color?"
 
 When nothing selects an agent, Elwood tries `claude` and then `codex` in your
 login shell and uses the first that resolves; if neither does, the run fails
-with `no_agent_found`. See [docs/cli.md](docs/cli.md) for configuration,
-output protocols, head mode, and continuation.
+with `no_agent_found`. Detection runs from the effective workspace, so
+`-C`/`--cwd` changes where the shell looks for those commands. See
+[docs/cli.md](docs/cli.md) for configuration, output protocols, head mode, and
+continuation.
 
 ## Core concepts
 
@@ -549,6 +551,8 @@ immediate; both are safe after the process has already exited.
   size, and persisting/resuming.
 - [docs/embedding.md](docs/embedding.md): wiring a session into a host
   application (Electron and similar).
+- [docs/performance.md](docs/performance.md): fifty-session measurements, headless
+  history budgets, and terminal-engine assessment.
 - [docs/loops.md](docs/loops.md): recurring prompts and `/loop` parsing.
 - [docs/images.md](docs/images.md): attaching images to a turn.
 - [docs/login-recovery.md](docs/login-recovery.md): detecting and recovering an

package/dist/bridge/socket-release.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Releases a launch's socket when its hook bridge stops (PRD §8.1): the bridge unlinks
+ * its socket file, and the session's socket home goes too once no other launch's socket
+ * is in it. Wraps each adapter's bridge factory seam, so every bridge a launch builds,
+ * including a test's, releases its socket on `stop`, `kill`, the agent exiting, and a
+ * failed start.
+ */
+type Bridge = {
+    readonly start: () => Promise<void>;
+    readonly stop: () => Promise<void>;
+};
+/** `factory`, with each bridge's successful `stop()` followed by its socket's release. */
+export declare function releasingSocketOnStop<Rest extends readonly unknown[]>(factory: (socketPath: string, ...rest: Rest) => Bridge): (socketPath: string, ...rest: Rest) => Bridge;
+export {};
+//# sourceMappingURL=socket-release.d.ts.map

package/dist/bridge/socket-release.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket-release.d.ts","sourceRoot":"","sources":["../../src/bridge/socket-release.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,KAAK,MAAM,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC;AAE1F,0FAA0F;AAC1F,wBAAgB,qBAAqB,CAAC,IAAI,SAAS,SAAS,OAAO,EAAE,EACnE,OAAO,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,IAAI,KAAK,MAAM,GACrD,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,IAAI,KAAK,MAAM,CAW/C"}