@with-logic/elwood 0.2.0 → 0.2.2

package/docs/cli.md

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

package/docs/codex/cli.md

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

package/docs/embedding.md

@@ -80,3 +80,10 @@ cap does not constrain your state layout.
   before the user starts a session — use `listClaudeModels`/`listCodexModels`.
   They spin up a throwaway session, list, and always tear it down, so they cost
   a few seconds each; cache the result in the parent app if you call them often.
+
+## Scaling concurrent sessions
+
+See [performance.md](performance.md) for the fifty-session workload, measured
+CPU improvement, and the existing `terminal.xterm.options.scrollback` history
+budget. Headless history and the browser terminal's history are separate;
+choose both budgets and avoid polling fresh snapshots for hidden sessions.

package/docs/performance/terminal-engines.md

@@ -0,0 +1,88 @@
+# Terminal engine assessment — October 24, 2026
+
+Keep xterm for the current optimization. A private Ghostty WASM probe showed
+a useful parser/formatter CPU reduction, but does not yet implement Elwood's
+terminal contract. Replacing the engine requires an explicit API migration: the
+public `terminal.xterm` exposes the complete headless xterm Terminal, including proposed
+APIs. Running both engines would retain both parsing and buffer costs.
+
+## Probe scope and provenance
+
+The experiment instantiated the official full `ghostty-vt.wasm` in Node 26.3.1
+with one WASM instance containing 50 terminals. Both engines parsed the same
+80 full-screen redraws at 120 columns by 40 rows. The snapshot variant decoded
+Ghostty's plain formatter output and checked final round markers. UTF-8 copy
+and decoding were included. This was a standalone diagnostic, not the full
+Elwood runtime workload; no hook/watch/classification or browser costs were
+included. The trace did not fill scrollback.
+
+The official nightly release was associated with source revision
+`22f100c6367045bb5fc86172f837047dee2f7670`, library `0.1.0-dev`.
+The 1,189,559-byte WASM SHA-256 was
+`e23598cefe95b42d441221a45d22d435c9c1915bca7475fe735e7617eac1a0d1`.
+Its embedded type metadata had a null commit field: the binary hash pins the
+measured bytes; the source association comes from release metadata. The `tip`
+URL moves and must not be treated as an immutable version. No dependency or
+WASM binary was added to Elwood.
+
+Sources: [official release](https://github.com/ghostty-org/ghostty/releases/tag/tip),
+[WASM API](https://github.com/ghostty-org/ghostty/blob/22f100c6367045bb5fc86172f837047dee2f7670/include/ghostty/vt/wasm.h),
+[official example](https://github.com/ghostty-org/ghostty/blob/22f100c6367045bb5fc86172f837047dee2f7670/example/wasm-vt/index.html).
+
+## Standalone measurements
+
+Three alternating fresh processes per engine used shared input/output scratch
+for all Ghostty terminals. The xterm side included Elwood's headless write queue
+and cursor tracking from commit `34ab7dd5`. The snapshot paths differ: xterm extracts the full physical
+viewport; Ghostty formats plain text. These numbers compare the prototypes,
+not equivalent complete engines.
+
+| Diagnostic median | xterm path | Ghostty WASM path |
+|---|---:|---:|
+| Parsing path CPU | 326.275 ms | 176.598 ms |
+| Parsing plus snapshot/formatter CPU | 559.623 ms | 343.816 ms |
+| Parsing plus snapshot/formatter RSS | 131.6 MiB | 139.5 MiB |
+
+Parsing CPU samples were 345.918 / 326.275 / 229.376 ms for xterm and
+225.668 / 147.451 / 176.598 ms for Ghostty. Snapshot/formatter samples were
+575.996 / 559.623 / 429.162 ms and 356.796 / 343.816 / 322.240 ms.
+The host was busy; all paired CPU comparisons favored the prototype, but the
+variation is substantial. The approximately 39% lower median CPU in the
+formatter comparison is not a whole-Elwood speedup.
+
+Ghostty's shared linear memory reached 23.625 MiB; WASM allocations must not
+be inferred from JS heap alone. Process RSS was not lower in the formatter
+comparison. No lower-memory replacement conclusion follows from this trace.
+An earlier per-terminal scratch variant allocated about 16 MiB unnecessarily;
+only the shared-scratch measurements above are used for this comparison.
+
+## Compatibility work required before replacement
+
+Elwood needs exactly one line per physical viewport row, cursor coordinates
+through scrollback and reflow, and cell-column prefix extraction for wide and
+combining characters. Question editors require cursor-cell dimming to distinguish
+placeholder text from real answers. Plain formatter output does not prove those
+properties.
+
+A replacement must also preserve parser-completion ordering, input ownership,
+protocol replies, title updates, synchronized-output holds, resize events,
+wrap-pending cursor positions and failure/disposal behavior. The WASM prototype
+did not install the write-to-PTY callback; query responses were therefore absent.
+Its marker checks establish only the diagnostic trace, not native CLI safety.
+
+The next useful engine experiment would compare full viewport/cursor/style and
+protocol-event fixtures through a compatibility adapter. A native addon should
+follow only if measured WASM boundary costs justify its build/distribution cost.
+Sources: [render state](https://github.com/ghostty-org/ghostty/blob/22f100c6367045bb5fc86172f837047dee2f7670/include/ghostty/vt/render.h),
+[grid references](https://github.com/ghostty-org/ghostty/blob/22f100c6367045bb5fc86172f837047dee2f7670/include/ghostty/vt/grid_ref.h),
+[terminal effects](https://github.com/ghostty-org/ghostty/blob/22f100c6367045bb5fc86172f837047dee2f7670/include/ghostty/vt/terminal.h).
+
+## Other candidates
+
+[libvterm 0.3.3](https://www.leonerd.org.uk/code/libvterm/) provides a screen and
+output callbacks, but its released screen-cell attributes lack the dim/faint
+flag used by question provenance. [vte](https://github.com/alacritty/vte) is a
+parser rather than a complete terminal emulator.
+[libtsm](https://github.com/Aetf/libtsm) still needs protocol, Unicode, dimming,
+resize and packaging verification. None offered a measured compatible replacement
+within this investigation.

package/docs/performance.md

@@ -71,3 +71,123 @@ under active output.
 Re-run the probe after changes to rendering, frame classification, replay,
 transcript polling, or cleanup. Compare output correctness and cleanup as well
 as throughput, memory, and event-loop delay.
+
+## Fifty-session runtime workload
+
+```sh
+node --expose-gc --no-warnings scripts/performance/fleet/index.ts
+```
+
+This probe starts 50 production runtimes, alternating Claude and Codex, with
+synthetic PTY producers. Dependency seams model macOS even on other hosts; this
+does not test native-agent support on those hosts. It exercises real local hook
+sockets, transcript watchers, frame observers, public snapshots and cleanup without
+launching agent CLIs or making model calls. Each session receives 80 full-screen redraws at
+120 columns by 40 rows, then 1,200 scrolling lines. Assertions check all
+15,155,250 output bytes, 500 transcript activities and final viewport markers.
+The process reports setup separately, a two-second idle CPU sample, active CPU,
+wall time, event-loop delay, live memory after GC and resource cleanup.
+For a quick smoke run, set `ELWOOD_BENCH_SESSIONS=2 ELWOOD_BENCH_ROUNDS=2`.
+
+### October 24, 2026: shared completed-frame text
+
+Three alternating reference/candidate pairs used the same worktree, v2 probe
+and Node 26.3.1 on the development Mac. Both sides used the benchmark from
+`f6e4406c`; the reference restored runtime files from release `ba8b634e`
+(0.2.0), while the candidate used the runtime at `f6e4406c`.
+Values below are medians, not guarantees. Host activity changed absolute
+timings substantially between measurement windows; compare matched pairs.
+
+| Parent-process metric | Reference | Shared frame | Change |
+|---|---:|---:|---:|
+| Active CPU | 1,177.071 ms | 1,043.927 ms | −11.3% |
+| Idle CPU over two seconds | 20.955 ms | 22.113 ms | +1.158 ms; variable |
+| Live JS heap | 52.828 MiB | 53.084 MiB | +0.5% |
+
+Active CPU samples were 1,176.453 / 1,177.071 / 1,195.298 ms before and
+1,043.927 / 1,045.998 / 1,031.162 ms after. Every v2 run passed per-session
+byte/activity attribution, final viewport markers and resource-count checks.
+The probe awaits teardown of every session, removing private socket homes before
+its shared root. Regression tests verify filesystem cleanup, rejection ordering,
+extra handles of an existing type and offsetting per-session accounting gaps.
+Idle samples ranged from 20.275–25.492 ms before and 16.285–23.858 ms after;
+no idle optimization is claimed. The CPU reduction is below the initial 15%
+estimate, with effectively unchanged live heap.
+
+The change removes a second viewport conversion in foreign-picker observation
+while preserving fresh public snapshots and input-boundary reads. Raw xterm
+writes, writeln and reset invalidate private cached text; disposal restores the
+original methods. Regression tests fail with the change removed, including a
+raw write in an owned parser drain, writeln's synchronous parse after user input
+and method restoration on disposal.
+
+An earlier v1 comparison measured 10.3% lower CPU. Its aggregate assertions
+did not establish per-session completeness, same-type handle counts or socket-home
+removal; the v2 comparison above supersedes that result.
+
+These measurements exclude browser rendering and agent-process memory/CPU.
+The probe's final screen assertions and 500 activity count protect this workload;
+they do not establish correctness for every native dialog. The repository's
+conformance suite remains the merge gate.
+
+## Consumer memory and rendering budgets
+
+Elwood's headless xterm retains 1,000 history lines by default. Consumers that
+retain their own raw terminal history can opt out of headless scrollback through
+the existing advanced xterm handle:
+
+```ts
+import { CodexSession } from "@with-logic/elwood";
+
+const session = await new CodexSession({ cwd }).start();
+session.terminal.xterm.options.scrollback = 0;
+```
+
+The same setting applies to Claude sessions. Apply it at session creation,
+before sustained output. This discards headless scrollback and changes what
+xterm can recover/reflow on scrolling and resizing; choose a small nonzero
+budget if that history is needed. It does not change the consumer's own replay
+store or browser terminal's independent scrollback setting.
+
+Three alternating default/zero-history runs of the fixed 50-session workload
+on Node 26.3.1, commit `f6e4406c`, measured the following medians after
+1,200 scrolling lines per session. The experimental preload changed only xterm
+constructor scrollback; all byte, transcript, viewport and cleanup assertions
+passed. A separate two-adapter smoke used the public setter above and verified
+zero history rows after scrolling. This is a configuration comparison, not a
+runtime default change.
+
+| Parent-process memory | Default 1,000 lines | Zero history |
+|---|---:|---:|
+| Live JS heap | 53.080 MiB | 38.977 MiB |
+| External memory | 81.017 MiB | 13.065 MiB |
+| Process RSS | 318.766 MiB | 231.484 MiB |
+
+JS heap samples ranged from 53.078–53.080 MiB at the default budget and
+34.650–38.987 MiB at zero history. History, dimensions, GC and host activity
+affect these values. CPU and
+idle timing varied enough that no CPU benefit is claimed for this setting.
+
+For many-session consumers:
+
+- Feed all ordered `terminal:data` bytes to the consumer's terminal/history
+  pipeline; batch browser writes without dropping bytes or ANSI boundaries.
+- Keep only visible terminals rendering. Bound browser scrollback independently
+  and avoid polling public snapshots for every hidden session. Public snapshots
+  deliberately perform a fresh viewport read.
+- Use normalized activity for chat/progress updates. Append to a bounded store
+  and batch UI updates instead of rerendering all terminal history per event.
+- Measure Elwood parent CPU separately from agent child processes and the UI
+  renderer. Browser refresh/history costs do not appear in the headless probe.
+
+The update-dialog prefilter prototype reduced active CPU by 3.8% in its matched
+window, below this investigation's 5% decision threshold, and was not retained.
+Fifty idle sessions used roughly 20 ms of parent CPU per two seconds; the
+measurements did not justify a polling rewrite. The
+[terminal engine assessment](performance/terminal-engines.md) records the
+Ghostty prototype and the compatibility requirements for a replacement.
+
+The fleet probe dispatches authenticated local hook requests directly; it does
+not launch the generated hook-bridge subprocess for each request. Bridge-process
+startup/CPU, agent processes and the browser need separate measurements. The
+parent-process results do not establish a whole-system scaling guarantee.

package/package.json

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

package/prd/04-architecture.md

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

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

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

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

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