@with-logic/elwood 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -7,15 +7,76 @@ and doc tweaks are omitted. The format follows
 [Keep a Changelog](https://keepachangelog.com); this project is pre-1.0, so
 everything lands under **Unreleased** until the first tagged release.
 
-Observable behavior is specified in `PRD.md`; the conformance criteria that
-back each entry are listed in PRD.md §14.
+Observable behavior is specified in `prd/`; the conformance criteria that
+back each entry are listed in `prd/14-conformance.md`.
 
 ## [Unreleased]
 
-First public release.
+## [0.1.2] - 2026-09-13
+
+- Preserve the inherited PATH when an interactive login shell exits successfully
+  without returning the PATH probe.
+
+- Keep permission dialogs blocking across cursor movement and hold slash-command
+  input and recovery Enter while a decision is pending; cancel expired picker submissions.
+- Reject planted state-directory and generated-file links before permission changes or writes.
+- Forward `highTrust` on start-or-resume, wait for model-discovery readiness,
+  and resolve session listings independently of agent-specific environment defaults.
+- Align foreground interactive launches with login-shell agent detection.
+- Correct trust and IPC-persistence documentation, include linked package references,
+  and revalidate mutable website sprites using fresh URLs for previously cached clients.
+
+## [0.1.1]
+
+First usable public release.
+
+0.1.0 was published from a checkout that sat 18 commits behind `main`. It
+shipped without the `resume`, `sessions`, `interactive` and `models`
+subcommands, without `--high-trust`, without agent auto-detection, and with a
+stale README. Nothing was wrong with 0.1.0's own code; it was simply built from
+the wrong commit. 0.1.1 is the same work published from `main`, and is the
+version to install.
 
 ### Added
 
+- **The `elwood` CLI now explains and cleanly overrides its effective behavior.**
+  `--no-stream` and `--no-verbose` reverse inherited boolean defaults,
+  `--no-defaults` bypasses saved config and `ELWOOD_*` run settings, and
+  `elwood config effective` reports validated launch/output values with their
+  provenance without starting an agent. Routine warnings now reach stderr for
+  text and JSON runs, `--verbose` is a concise elapsed progress view, and
+  `--debug` retains full sanitized event detail. JSONL records include elapsed
+  timing plus tool-call correlation IDs when available. Help, validation errors,
+  resume/persona/ephemeral wording, and the new scripting guide now make defaults,
+  recovery actions, and lifecycle effects explicit. (§5.8/§12A,
+  C-API-48/C-CLI-02/03/08/10/11/14/19/20)
+- **The `elwood` CLI can now mirror the live agent TUI in the current terminal.**
+  `--head` sends the agent's ordered raw VT/ANSI stream to terminal stderr while
+  preserving the final text or JSON result on stdout, including cursor-addressed
+  redraws, alternate screens, colors, spinners, and OSC title changes. It follows
+  terminal resizes, restores terminal modes on every handled outcome, and treats
+  Ctrl-C like the existing interrupt lifecycle. The display is intentionally
+  view-only and cannot be combined with `--stream`, `--verbose`, or JSONL.
+  Pending terminal writes are bounded by bytes and frame count, so a stalled
+  terminal becomes a clean run failure instead of an unbounded memory queue.
+  An argument-free `elwood` invocation now prints help instead of waiting for a
+  prompt. (§12A.1/§12A.6, C-CLI-02/C-CLI-18)
+- **The `elwood` CLI gained `sessions`, `resume`, `interactive`, and `models`
+  commands.** `elwood sessions` lists Elwood-owned session records (id, agent,
+  workspace, `createdAt`/`lastUsedAt`, `resumable`, socket-presence `live`) as an
+  aligned table or one `{"type":"sessions"}` JSON document without starting an
+  agent. `elwood resume <id> [prompt...]` is a parse-time rewrite of
+  `run --resume <id>`. `elwood interactive [id]` runs the real `claude`/`codex`
+  TUI in the foreground with Elwood's resolved agent, model, effort, workspace,
+  and posture passed as the agent's own flags — no PTY, automation, observation,
+  or state — resuming a stored session's own conversation when given an id.
+  `elwood models` starts the agent briefly, reads its model picker through the
+  public `listModels` operation, tears the session down, and prints a table or a
+  `{"type":"models"}` document of `AgentModelOption` rows. The adapters' launch
+  flag mapping now lives in shared `claudeLaunchArguments`/`codexLaunchArguments`
+  builders so interactive and headless launches cannot drift. (§12A.7–§12A.10,
+  C-CLI-23 through C-CLI-26)
+
 - Claude Code and Codex CLI adapters that run the real interactive CLI in a
   PTY, launched through the user's login shell, and observe it through a
   headless xterm.js model. macOS only; Claude Code 2.1.144+ and Codex CLI
@@ -86,10 +147,27 @@ First public release.
   `agent`, a new run tries `claude` then `codex` in the login shell and fails
   with `no_agent_found` (status 2) when neither resolves. Error records
   emitted before an agent was selected report `agent: null`.
+- An agent-neutral "never ask for permissions" switch: `--high-trust` /
+  `--no-high-trust`, `ELWOOD_HIGH_TRUST`, the `highTrust` config key, and
+  `highTrust?: boolean` on both session classes and both resume functions. It
+  expands to Claude `permissionMode: "bypassPermissions"` or Codex
+  `sandbox: "danger-full-access"` with `approvalPolicy: "never"` before the
+  posture is persisted and the process spawned. Combining it with an explicit
+  per-agent posture is rejected: the CLI names both sources as a usage error and
+  the library throws `claude_high_trust_conflict` / `codex_high_trust_conflict`.
+  `config effective` reports `highTrust` and attributes the posture it decided
+  to the high-trust source. Claude's one-time "running in Bypass Permissions
+  mode" acceptance dialog is an allowlisted trust prompt answered under
+  `autotrust` (`startup_prompt` label `bypass_permissions`).
 
 ### Changed
 
 - Published as `@with-logic/elwood` under the MIT license.
+- The published package runs no install scripts. `dist/` is built before publish
+  (`prepublishOnly`) and shipped in the tarball, so `npm install -g
+  @with-logic/elwood` needs no build step and raises no npm allow-scripts
+  prompt for Elwood itself. Working from a checkout now requires an explicit
+  `npm run build` before `npm link`.
 - Warnings are live-only events. Nothing is persisted, replayed, or counted;
   there is no `session.warnings` property.
 - The persisted session record holds only schema version, `elwoodSessionId`,
@@ -109,6 +187,107 @@ First public release.
 
 ### Fixed
 
+- **Headed runs no longer suspend themselves or leave the invoking terminal unusable.**
+  Interactive version and capability probes now run in an isolated process session,
+  preventing their shell-managed commands from stealing the real terminal's foreground
+  process group. `--head` can therefore restore cooked input and display modes before
+  returning to an interactive shell, without a cleanup-time `SIGTTOU` stop or leaked
+  terminal-protocol replies. Its defensive restore now also pops the Kitty keyboard
+  enhancement mode used by current agent TUIs, so subsequent shell keystrokes remain
+  ordinary text instead of encoded key-event sequences. (§12A.6, C-CLI-18)
+- **Codex's startup update dialog no longer wedges headed or headless runs.**
+  Codex 0.153.x can paint its numbered update menu before its input loop accepts
+  the first safe Skip hotkey. Elwood now retries that hotkey for a bounded interval
+  only after revalidating the complete current update dialog, and the CLI no longer
+  mistakes the responder-owned dialog's replayed blocking edge for a human prompt.
+  A persistent or unanswerable update dialog now fails and cleans up boundedly even
+  without `--timeout`; no retry can escape into the composer or another dialog.
+  (§5.5/§12A.2, C-CODEX-12/C-CLI-05)
+- **Headless turns now survive real-CLI startup, resume, and teardown races.**
+  Codex 0.153.3 can accept the 10-second fallback paste into its cold-start
+  placeholder, swallow it during a later boot repaint, and appear to finish an
+  empty turn; ergonomic turns now require positive submission evidence, replay
+  an unaccepted prompt at most twice, and fail explicitly instead of reporting
+  false success. A resumed Claude turn no longer treats its stale composer as
+  an immediate end before real work paints. The headless owner also ignores
+  transient attention from trust prompts it is already authorized to answer,
+  and macOS teardown retries the short-lived post-exit `EPERM` process-group
+  window instead of surfacing `cleanup_failed`. (§5.3/§5.8/§12A, C-API-48,
+  C-TURN-03, C-CLI-05/09)
+- **Claude model switches now complete through model/effort cache warnings.**
+  Claude 2.1.258 may interpose `Switch model?` or `Change effort level?` after
+  Elwood applies a session-only picker choice; Elwood previously treated that
+  dialog as successful picker closure and returned while the session was still
+  waiting. Elwood now recognizes numbered and unnumbered variants, navigates
+  from the rendered cursor to the affirmative action, confirms the built-in
+  cache warning, and waits for the idle composer before resolving `setModel`.
+  Recognition is scoped to the bottom-most live dialog and revalidated before
+  Enter, so transcript text cannot spoof a cache warning or composer. Hook-requested
+  `PreModelSwitch` confirmations remain blocking and human-controlled. (§5.3,
+  C-API-24/C-ATTN-04)
+- **Concurrent Codex starts no longer race global npm updates.** Codex's live
+  update dialog is now input-blocking until its rendered frame clears, so queued
+  persona/caller input cannot press Enter on the default "Update now" action when
+  a prompt layout is partial or drifts. Elwood still skips every recognized safe
+  option automatically. Separately, `autoupdate` now holds an atomic per-user,
+  per-adapter cross-process lease around the global updater; another Elwood host
+  waits asynchronously, skips its duplicate install, and validates the resulting
+  binary. The lease uses a stable account cache across differing `TMPDIR` values,
+  records its owner/generation so live or successor updates cannot be evicted,
+  and recovers dead owners safely. Failed partial installs also invalidate version
+  and capability caches before validation. Coal Harbor and other consumers need
+  no API or configuration changes. (§5.5/§9.2, C-CODEX-12/C-PERF-04/C-LIFE-09)
+- **Claude's current cursor-style workspace trust prompt is auto-approved again.**
+  Claude 2.1.252 replaced the older numbered, affirmative-first layout with an
+  unnumbered menu that defaults to `No, exit`; the responder recognized its header
+  but found no numbered affirmative, wrote nothing, and the readiness fallback
+  could report `ready` over the still-visible gate. Elwood now supports both
+  layouts, navigates cursor menus to the affirmative before Enter, keeps their
+  entire option region out of header recognition, and verifies the real trust
+  screen clears before readiness. The gate remains independent of Claude's
+  `bypassPermissions` / `--dangerously-skip-permissions` policy. (§5.1/§5.3,
+  C-CLAUDE-10/C-CLAUDE-14/C-E2E-09)
+- **Modern Codex final replies now carry their text on `assistant_message`
+  activity.** Codex 0.149.1 writes replies as assistant `message` response items
+  with `phase: "final_answer"` and `content[].output_text`; Elwood previously
+  expected a plain string (or a legacy `agent_message` duplicate), so consumers
+  received a textless event and could silently discard the reply. Elwood now
+  extracts the full final-answer text—including `@mentions`—while keeping
+  commentary and user/developer transcript records out of assistant activity.
+  (§5.4/§7A.4, C-API-12/C-CODEX-16)
+- **Claude's `Not logged in · Run /login` sign-out is now detected mid-session.**
+  A ready Claude session that gets logged out mid-run renders `Not logged in`
+  (paired with a `run /login` hint) — a different wording than the `Login expired`
+  / `Session expired` / `OAuth token revoked` banners Elwood already recognized.
+  That form previously went undetected mid-session, so no `login_expired` warning
+  fired. It now surfaces the same content-free `login_expired` warning (+ `warning`
+  activity), leaving the session alive to recover via `session.login()`. (§5.3/§5.7,
+  C-CLAUDE-17/18)
+- **Codex's in-TUI update prompt is now re-skipped on the restart loop.** Elwood
+  always skips Codex's interactive "update available" prompt (it never selects
+  "Update now"; the real update is the `autoupdate` preflight). The skip was latched
+  once per session, so if Codex restarted and the SAME update screen reappeared — the
+  update did not take — the session got stuck looping on it. The skip is now
+  edge-triggered: it re-arms when the update screen leaves the frame and re-skips the
+  reappearance. (§5.5, C-CODEX-12)
+- **Autoupdate is now best-effort and never fails a start on its own.** When
+  `autoupdate: true` and `claude update` / `codex update` fails (a flaky network,
+  a partial native-installer download, contention during a fleet launch), Elwood no
+  longer rejects `startClaude`/`startCodex` with `claude_update_failed` /
+  `codex_update_failed`. If the INSTALLED CLI still meets the minimum version, the
+  session starts from it and Elwood emits a live `agent_update_failed` warning (safe
+  diagnostics only: installed version, an allowlisted error code, bounded stderr).
+  Startup fails only when the installed version is actually below the minimum. The
+  warning is zero-burden — a consumer that does not subscribe to `warning` is
+  unaffected and the session still reaches `ready`. (§9.2, C-LIFE-11)
+- **A failed shared update no longer poisons the process.** A once-per-process
+  update/probe cache that rejected was retained and replayed, so one failed
+  `claude update` could reject every concurrent roster start AND every later start
+  until the process restarted. Cached probes (autoupdate, version read, capability
+  detection) now never retain a rejected result: concurrent callers share one attempt
+  and a later caller re-attempts rather than inheriting the failure. (§9.2,
+  C-LIFE-09/11)
+
 - Trust, update, and model-switch dialogs on current Claude and Codex releases
   are recognized and answered; unrecognized dialogs block instead of guessing.
 - Hook payloads are measured identically on both sides of the bridge, and

package/CONTRIBUTING.md

@@ -0,0 +1,104 @@
+# Contributing
+
+Thanks for helping with Elwood. This project is spec-first: `prd/` is the
+contract for observable behavior, and `CLAUDE.md` (also linked as `AGENTS.md`)
+is the implementation guide for anyone, human or AI, changing code. Read both
+before opening a pull request.
+
+## Requirements
+
+- macOS (the only supported platform for v0.1; the unit suite also runs on
+  Linux).
+- Node.js 24 or newer. `.node-version` pins the major version for version
+  managers.
+- For end-to-end tests: an installed and authenticated Claude Code and/or
+  Codex CLI.
+
+## Setup and checks
+
+```sh
+npm install
+npm run check
+```
+
+`npm run check` is the merge gate. It runs, in order:
+
+1. `npm run build` (emits `dist/`, which the CLI tests and `npm link` need),
+2. `tsc --noEmit`,
+3. `biome check .`,
+4. `scripts/check-lines.ts` (every code file at or below 200 lines),
+5. `vitest run --coverage` with 100% line, branch, function, and statement
+   coverage.
+
+Useful narrower commands:
+
+```sh
+npm run typecheck
+npm run lint            # or npm run lint:fix
+npx vitest run tests/unit/some-file.test.ts
+npm run test:e2e        # real Claude/Codex sessions; uses model quota
+```
+
+The e2e suite skips any test whose agent CLI is not installed. It starts real
+sessions in temporary directories and answers workspace trust prompts for those
+directories automatically.
+
+## Making a change
+
+1. If the change is observable by a user, an API consumer, or a second
+   implementation (commands, flags, events, output shapes, config, state,
+   errors, defaults, limits, security guarantees, conformance criteria), update
+   `prd/` first.
+2. Implement the smallest matching slice in `src/`.
+3. Add or update tests in `tests/`. Conformance tests name their criterion in
+   the title, for example `C-CLI-03 resume rejects --cwd`.
+4. If the change is consumer-facing, add a bullet to `CHANGELOG.md` under
+   `## [Unreleased]`.
+5. If the real Claude or Codex CLI taught you something a unit test could not,
+   record it in `docs/cli-behavior.md`.
+6. Run `npm run check`.
+
+## Pull requests
+
+- Keep pull requests small and focused on one change.
+- Do not include secrets, access tokens, credentials, or private data in
+  issues, tests, logs, screenshots, or fixtures.
+- Describe what changed and why. If the change touches readiness, turn
+  detection, trust prompts, resume, or input paths, say how you verified it
+  against the real CLI.
+
+## Local test apps
+
+Two maintainer tools exercise the library interactively:
+
+```sh
+# Terminal smoke app, Claude by default.
+npm run dev:app -- --cwd /path/to/project
+npm run dev:app -- --agent codex --cwd /path/to/project
+npm run dev:app -- --cwd /path/to/project --resume <elwoodSessionId>
+
+# Browser debugger on http://localhost:4317 with an xterm.js mirror and a
+# structured event inspector.
+npm run dev:web
+```
+
+They live under `dev/`, outside `src/`, and are not part of the published
+package. They are development utilities, so they are typechecked and linted
+like everything else but are excluded from the coverage gate.
+
+## Repository map
+
+| Path | Purpose |
+|---|---|
+| `prd/` | Source of truth for behavior and conformance criteria (one file per section). |
+| `src/index.ts` | Public package exports. |
+| `src/core/` | Adapter-neutral session machinery: control queue, status detection, turns, loops, images, warnings. |
+| `src/runtime/` | Shared session base class, startup checks, teardown, and test seams. |
+| `src/claude/`, `src/codex/` | The two adapters: launch, hooks, transcripts, validation. |
+| `src/cli/` | The `elwood` executable. |
+| `src/state/` | Session records and private sidecar files. |
+| `src/bridge/` | Local hook bridge server and generated bridge script. |
+| `src/terminal/`, `src/pty/` | Headless xterm.js model and node-pty adapter. |
+| `dev/` | Local terminal and browser dev apps (not published, not coverage-gated). |
+| `tests/` | Unit, conformance, and e2e suites. |
+| `docs/` | Guides and the record of empirically learned CLI behavior. |

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Logic, Inc.
+Copyright (c) 2026 Logic App, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal