@with-logic/elwood 0.1.0

package/docs/cli.md

@@ -0,0 +1,171 @@
+# The `elwood` command
+
+Purpose: the complete guide to the headless `elwood` executable, from a first
+prompt to scripted JSON and JSONL pipelines.
+
+## Basics
+
+```sh
+elwood "What's the weather today in Seattle?"
+elwood --agent claude "Summarize this repository"
+git diff | elwood "Review this diff and list only correctness risks"
+elwood --image screenshot.png "Explain this failure"
+elwood -C ../service --timeout 10m "Run the tests and diagnose failures"
+elwood run --output json < prompt.txt
+```
+
+`elwood "prompt"` runs in the current directory, waits for one complete turn,
+prints the combined assistant text to stdout, then tears its Elwood session
+state down. It does not undo files the agent changed or remove history owned by
+the agent CLI. `elwood run "prompt"` is the same command in explicit form.
+
+Positional words are joined with spaces. Non-empty piped stdin is appended after
+one blank line, so a short instruction can accompany a large document or diff.
+Terminal stdin is not read. Repeat `--image` to attach multiple images in order.
+Input is capped at 8 MiB. Durations accept positive integer `ms`, `s`, `m`, or
+`h` values. Running `elwood` with no arguments prints the same text as
+`elwood --help`; explicit `elwood run` still requires prompt input.
+
+## Agent selection
+
+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.
+`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
+selected, Elwood never silently falls back to the other. Resume never probes;
+it uses the stored agent.
+
+## Defaults and configuration
+
+`elwood config` manages one strict global JSON file. Project-local
+configuration is deliberately unsupported, and global config is never loaded
+from the repository being opened. The path is `$ELWOOD_CONFIG`, then an
+absolute `$XDG_CONFIG_HOME/elwood/config.json`, then
+`~/.config/elwood/config.json`:
+
+```sh
+elwood config path
+elwood config show
+elwood config effective
+elwood config effective --agent claude --output json
+elwood config set agent claude
+elwood config set timeout 10m
+elwood config get agent
+elwood config unset timeout
+```
+
+Supported keys are `agent`, `output`, `timeout`, `trust`, `stateDir`,
+`verbose`, `stream`, `persona`, `claude.model`, `claude.reasoningEffort`,
+`claude.permissionMode`, `codex.model`, `codex.reasoningEffort`,
+`codex.sandbox`, and `codex.approvalPolicy` (`schemaVersion` is always `1`).
+Values are typed and unknown keys are rejected.
+
+`config show` prints only the saved file. `config effective` validates and
+prints the resolved launch and output values, the source of each, the config
+path, and whether that file was loaded, without reading a prompt or starting an
+agent. Its JSON includes `head` and, for Claude, the effective
+`permissionMode`, `allowedTools`, `disallowedTools`, and `tools`; resume
+inspection reports persisted tool rules with stored-session provenance.
+
+Precedence is flags, environment, global config, then built-ins. `--no-stream`
+and `--no-verbose` reverse inherited true values. `--no-defaults` ignores the
+saved config and all `ELWOOD_*` run-setting variables for a reproducible
+invocation; it does not strip the environment passed to the agent. Environment
+names are `ELWOOD_AGENT`, `ELWOOD_OUTPUT`, `ELWOOD_TIMEOUT`, `ELWOOD_TRUST`,
+`ELWOOD_STATE_DIR`, `ELWOOD_VERBOSE`, `ELWOOD_STREAM`, `ELWOOD_PERSONA`,
+`ELWOOD_MODEL`, `ELWOOD_REASONING_EFFORT`, `ELWOOD_CLAUDE_PERMISSION_MODE`,
+`ELWOOD_CODEX_SANDBOX`, and `ELWOOD_CODEX_APPROVAL_POLICY`. Boolean environment
+values are exactly `true` or `false`.
+
+Run `elwood --help` for the full flag list. Launch controls include `--model`,
+`--reasoning-effort`, `--persona`, `--claude-permission-mode`,
+`--codex-sandbox`, `--codex-approval-policy`, `--state-dir`, `--verbose`,
+`--debug`, and `--trust` / `--no-trust`. The built-in non-interactive posture
+is Claude `dontAsk`, or Codex `workspace-write` with approval policy `never`.
+
+A reproducible run ignores saved defaults and states the important settings:
+
+```sh
+elwood --no-defaults \
+  --agent codex \
+  --output json \
+  --timeout 10m \
+  --codex-sandbox workspace-write \
+  --codex-approval-policy never \
+  "Run the tests and summarize failures"
+```
+
+## Output and pipelines
+
+Text is the default output protocol. `--output json` emits one terminal
+document, `--output jsonl` emits sequenced progress records, and `--stream`
+prints assistant text as it arrives. Warnings and diagnostics go to stderr.
+Field references, exit codes, and safe shell recipes are in
+[cli-output.md](cli-output.md).
+
+## Live terminal view
+
+Add `--head` to watch the real agent interface while keeping a
+pipeline-friendly final result:
+
+```sh
+elwood --head "Run the test suite and fix the failure"
+elwood --head --output json "Review this repository" >result.json
+```
+
+The display receives the raw PTY byte stream on stderr. It is a real VT/ANSI
+mirror, so full-screen layouts, cursor-addressed updates, alternate-screen
+buffers, colors, spinners, and title changes render as they do in the
+underlying client. Stdout remains only the final text or JSON protocol. Pending
+display work is capped at 4 MiB or 1,024 writes; a terminal that stays
+backpressured fails the run cleanly instead of growing memory without bound.
+
+Head mode is view-only: keyboard, mouse, paste, and terminal-response bytes are
+discarded while attached. Ctrl-C still interrupts. Terminal resizes propagate to
+the agent. Elwood restores raw/cooked input state, mouse and paste modes,
+attributes, cursor visibility, and the main screen before printing the final
+result. Both stdin and stderr must be terminals, and `--head` cannot be
+combined with `--stream`, `--verbose`, `--debug`, or `--output jsonl`.
+
+## Continuation and cleanup
+
+New runs are ephemeral unless `--keep` is supplied. A kept text run reports its
+session ID on stderr; JSON and JSONL include it in the terminal record:
+
+```sh
+first=$(elwood --keep --output json "Remember that the release color is teal")
+id=$(printf '%s' "$first" | jq -r .sessionId)
+elwood --resume "$id" "What is the release color?"
+elwood --resume "$id" --ephemeral "Finish this conversation"
+```
+
+Resume uses the exact stored agent and workspace; a conflicting `--agent` and
+any `--cwd` are rejected. Resumed sessions stay preserved after success or
+failure unless `--ephemeral` requests teardown. Teardown removes Elwood's
+session record and loop definitions; it does not undo workspace changes or
+delete conversation history owned by Claude or Codex. CLI state defaults to an
+absolute `$XDG_STATE_HOME/elwood` or `~/.local/state/elwood`; its private
+records hold resume metadata, not prompts or output.
+
+`--persona` runs a real extra agent turn before the requested turn. Elwood
+discards that setup turn's answer, but any tools it invokes or files it changes
+remain. It is supported only for new sessions, never with `--resume`.
+
+## Trust and security
+
+Headless mode is non-interactive. With the default `--trust`, Elwood answers
+only its allowlisted workspace-directory and extension trust dialogs, plus the
+Elwood-owned Codex hook trust needed for operation. `--no-trust` disables the
+workspace and extension approvals. Any other recognized dialog fails safely as
+`blocked_prompt` instead of hanging or guessing.
+
+Piped text and image paths are prompt input with the same authority as text
+typed by the caller. Do not combine untrusted input with broad filesystem
+permissions.
+
+Head mode renders agent-controlled terminal escape sequences verbatim, exactly
+as running the interactive CLI directly would. Use it only with agents and
+workspaces you trust to control the current terminal display.

package/docs/design-notes.md

@@ -0,0 +1,74 @@
+# Design notes
+
+Purpose: the reasoning behind decisions that reviewers and integrators ask
+about, plus what Elwood does and does not persist.
+
+## Decisions
+
+- **The agent must not know it is wrapped.** Agents run in a real PTY, not
+  print mode, SDK mode, or a pipe-only subprocess, launched through the user's
+  interactive login shell so PATH and environment match a human's terminal.
+  Hooks and transcripts are the control and observability layer.
+- **Headless terminal model.** PTY output is rendered through headless
+  xterm.js before Elwood inspects TUI state, so prompt detection works on the
+  rendered screen rather than on raw escape sequences.
+- **Claude tool flags.** Elwood passes the camelCase `--allowedTools` /
+  `--disallowedTools` flags with one comma-separated value; current
+  `claude --help` documents comma or space-separated lists.
+- **Claude settings.** Session-scoped settings are passed with `--settings`.
+  Elwood does not mutate `.claude/settings.local.json`.
+- **Codex hook enablement.** Elwood reserves `features.hooks=true` and
+  `hookTrust="trust-all"` because the library is not useful unless hooks run.
+- **Workspace trust.** `autotrust` is an explicit opt-in because answering
+  Claude or Codex workspace trust prompts changes the security posture of the
+  launched agent. The gate is independent of Claude's permission mode.
+- **Codex `PermissionRequest`.** The wire response nests `{ behavior, message? }`
+  under `hookSpecificOutput.decision`; `PreToolUse` uses direct event-specific
+  fields. Elwood mirrors Codex's protocol rather than normalizing the shape.
+- **Hooks fail open.** A handler timeout, thrown handler, invalid input, or
+  invalid response is reported as `hookError` and the agent proceeds, so a
+  parent-app bug cannot deadlock the wrapped agent.
+- **Raw bytes.** `sendKeys(Uint8Array)` writes bytes to the PTY instead of
+  decoding them as UTF-8, so forwarded user keystrokes arrive verbatim.
+- **Readiness comes from signals, not files.** Observe `session.status`, the
+  `status` event, or `waitForStatus`. The persisted record exists only to
+  enable resume and is not part of the readiness contract.
+- **Turn boundaries are deterministic.** An ergonomic turn ends when the
+  transcript catches up to the `Stop` hook's expected final text, with a
+  bounded quiet-window fallback for pure-tool turns. There is no whole-turn
+  timeout by default; `timeoutMs` is opt-in and armed only after submission.
+- **Lifecycle.** `stop()` waits for a bounded graceful exit and escalates to
+  force termination; `kill()` starts with force termination. Failed cleanup
+  never latches: a later call retries.
+- **Version checks.** An unparseable CLI version becomes a `version_unparseable`
+  warning and startup continues; `strictVersionCheck: true` fails closed. A
+  failed `autoupdate` is non-fatal when the installed CLI meets the minimum
+  (`agent_update_failed` warning).
+
+## State, privacy, and safety
+
+Elwood is deliberately live-first.
+
+- The persisted session record is minimal: schema version, `elwoodSessionId`,
+  adapter kind, `cwd`, and per-adapter resume state (the CLI's conversation id
+  plus launch posture). Nothing else is written. Sessions live under
+  `<cwd>/.elwood` by default; pass `stateDir` for a caller-managed location.
+- Explicit loop definitions live in a separate versioned, owner-only `0600`
+  sidecar with the loop message and cadence metadata, but no live timer, due
+  state, or submission state. That message is the sole persisted prompt.
+- Session status, timestamps, warnings, terminal size, the hook bridge token,
+  the socket path, and runtime file paths are not persisted. Status and
+  warnings are live-only events. Runtime paths are derived on demand; the
+  socket home is a deterministic fingerprint of the session identity in a
+  short Elwood-owned temp home (so a deep `stateDir` never hits the macOS
+  socket path cap), while the bridge token and socket file are minted fresh on
+  every start and never trusted from disk.
+- Ordinary prompts, PTY output, hook payloads, hook responses, Codex
+  transcript items, and derived prompt or tool content are never persisted.
+- Hook bridge messages travel over local IPC with per-session tokens; requests
+  are capped at 8 MiB on both sides.
+- Malformed state records fail with typed `state_corrupt` errors. State
+  directories are created `0700` and files `0600`.
+- `teardown()` removes only Elwood-owned files: the session record, loop
+  sidecar, generated settings, bridge script, and socket home. It never
+  touches agent-owned auth, transcripts, or user settings.

package/docs/embedding.md

@@ -0,0 +1,82 @@
+# Embedding Elwood in a parent application
+
+The canonical embedding is an Electron app: Elwood runs in the main process,
+terminal output streams to a renderer xterm over IPC, and renderer keystrokes
+flow back. The same shape applies to any host (web server, TUI multiplexer,
+daemon).
+
+## The loop
+
+```ts
+import { startOrResumeClaude, type ElwoodAgentSession } from "@with-logic/elwood";
+
+const { session, resumed } = await startOrResumeClaude({
+  cwd: workspacePath,
+  stateDir: join(appStateDir, "sessions", mySessionId, "elwood"),
+  elwoodSessionId: persisted?.elwoodSessionId,
+  autotrust: true,
+  hooks: { /* policy hooks */ },
+});
+if (!resumed) persist({ elwoodSessionId: session.elwoodSessionId });
+
+// Main -> renderer: raw PTY bytes into a visual xterm.
+session.on("terminal:data", (event) => window.webContents.send("pty", event.data));
+// Renderer -> main: forward user keystrokes verbatim as bytes.
+ipcMain.on("keys", (_event, bytes: Uint8Array) => void session.sendKeys(bytes));
+// Keep the visual and headless terminals the same size.
+ipcMain.on("resize", (_event, size) => void session.resize(size));
+```
+
+A late `terminal:data` subscriber first receives up to 128 KB of replayed
+output as one chunk, so a freshly-opened renderer view paints recent history
+immediately; write it into the xterm like any other chunk.
+
+## Lifecycle
+
+- **Relaunch:** persist `elwoodSessionId`, keep `stateDir` intact, and call
+  `startOrResume*` at boot. It falls back to a fresh session only when no
+  resumable session exists (`state_not_found` / `resume_unavailable` /
+  `adapter_mismatch`) and reports which path ran.
+- **Removal:** call `teardown()` — it removes Elwood-owned state (session
+  record, loop sidecar, generated settings, bridge script, socket home) without touching the
+  agent CLI's own user data.
+- **Shutdown:** `stop()` for graceful, `kill()` for wedged sessions. Both are
+  safe after the process already exited. Stop and unexpected exit preserve
+  loop definitions for resume; kill clears them permanently.
+
+Recurring loops are owned by Elwood and need no parent timer. Use
+`createLoop`/`listLoops`/`cancelLoop`; resume restores unexpired definitions with
+fresh clocks and no catch-up. Use the opt-in `parseLoopCommand` helper for a
+shared `/loop` UX, since ordinary send methods keep slash-prefixed text literal.
+
+`stateDir` can be arbitrarily deep: the hook bridge socket binds in a short
+Elwood-owned temp home, not under `stateDir`, so macOS's ~104-byte socket path
+cap does not constrain your state layout.
+
+## Gotchas
+
+- **CJS bundlers (Electron main).** Elwood constructs its `require` from
+  `import.meta.url ?? __filename`, so bundling to CJS works without a
+  `define` workaround. If you bundle, keep `node-pty` external — it is a
+  native module.
+- **Nested agent sessions.** Claude Code ≥ 2.1.201 does not persist
+  conversations for instances launched from inside another Claude Code
+  session (`CLAUDECODE`/`CLAUDE_CODE_*` in the environment). Hooks and turns
+  work, but resume will find nothing. If your parent app can itself be
+  launched from a Claude session (dev workflows, test runners), strip those
+  variables from the child environment when you need resumable sessions —
+  Elwood's own e2e suite does exactly this.
+- **User keystrokes** should be forwarded with the `Uint8Array` overload of
+  `sendKeys` for verbatim delivery; the string overload applies terminal
+  input semantics (see [api.md](api.md)).
+- **Interrupting a turn** (a stop button, the user's Escape) should call
+  `interrupt()` rather than forwarding a raw Escape byte: it no-ops safely
+  when no turn is running and resolves once the session is `ready` again.
+- **Model switching** via `setModel` preserves the user's saved defaults on
+  both adapters: Claude applies session-only, and Elwood restores Codex's
+  config.toml after the CLI persists its picker selection (watch for the
+  `codex_default_model_persisted` warning in the rare concurrent-edit case).
+- **Enumerating models without a session** — to populate a model selector
+  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.

package/docs/images.md

@@ -0,0 +1,67 @@
+# Attaching images
+
+Purpose: how to attach image content to a turn, what is validated, and how
+each adapter ingests it.
+
+`send`, `stream`, `sendPrompt`, `sendMessage`, and `sendGuidance` accept an
+optional `images` list so a submission can carry image content alongside its
+text, the equivalent of pasting or dragging an image into the CLI. It is an
+attached-content model, not interleaving: images have no position within the
+text, but the list is ordered (array order sets chip order). Elwood attaches
+them as part of the same queued turn, before the text is submitted. The CLI
+exposes the same thing as a repeatable `--image <path>` flag.
+
+```ts
+await session.sendMessage("What's wrong with this screenshot?", {
+  images: [
+    { path: "/abs/path/to/shot.png" },  // an existing image file
+    { data: pngBytes, format: "png" },   // or in-memory bytes
+  ],
+});
+```
+
+## Validation and limits
+
+`ImageInput` is exactly `{ path }` or `{ data, format }` where `format` is
+`"png" | "jpeg" | "gif" | "webp"`; extra keys are rejected. Inputs are
+validated before anything reaches the composer:
+
+- At most 16 images per submission.
+- At most 25 MiB per image and 50 MiB per submission, counting path inputs
+  and byte inputs alike.
+- At most 200 MiB of cloned image bytes held across all queued, not yet
+  attached submissions in one session.
+
+A violation rejects the call with `invalid_image`. Malformed or over-limit
+input rejects synchronously, before the submission takes a queue slot. Path
+readability is checked at dispatch, so a file made unreadable after the call
+still rejects. A `{ data }` buffer is cloned at the call, so mutating it
+afterwards does not change what is attached. Byte inputs are written to a
+short-lived temp file that is removed once the submission is attached.
+
+## Confirmation
+
+Attachment is confirmed, never assumed. Each image waits for the CLI's
+`[Image #N]` chip on the composer line. If the chip is not confirmed within
+10 s, or the clipboard cannot be read or written, the call rejects with
+`image_attach_failed` and no text is submitted. If the session terminates
+mid-attach the call rejects with `session_not_running`, like any queued
+operation. An attach rejection leaves queue readiness unchanged.
+
+## Adapter mechanics
+
+Each CLI ingests images through its own native path, so behavior differs.
+
+**Claude** reads a pasted absolute image path itself. Elwood bracketed-pastes
+each path (the same delivery a terminal produces on drag-and-drop), Claude
+encodes the file, and an `[Image #N]` chip appears. The mechanism is
+platform-neutral, but Elwood itself currently supports macOS only: both
+adapters reject at startup with `unsupported_platform` elsewhere.
+
+**Codex** ingests an interactive image only from the OS clipboard (Ctrl+V).
+Elwood snapshots your clipboard once, writes each image onto the macOS
+pasteboard, sends Ctrl+V, waits for the `[Image #N]` chip, and then restores
+your prior clipboard. The whole transaction runs under a process-wide lock so
+concurrent Codex sessions cannot cross-attach. Restoring the clipboard is
+best-effort (text contents), and there is a brief window during the attach
+when the injected image is the clipboard's contents.

package/docs/lifecycle.md

@@ -0,0 +1,45 @@
+# Session lifecycle
+
+Purpose: event delivery guarantees, terminal sizing, and how to persist and
+resume a session across parent-app restarts.
+
+## Event delivery guarantees
+
+- `terminal:exit` is emitted exactly once per session process exit.
+- A handler never fires after its unsubscribe function returns.
+- A late `terminal:data` subscriber first receives the replay buffer as one
+  coalesced chunk, then live chunks, with no gap and no duplicates. The buffer
+  is bounded at 128 KB (oldest data dropped); use
+  `session.terminal.snapshot()` for current-screen ground truth.
+- `stop()` / `kill()` after exit do not re-signal the PTY and preserve the exit
+  status, but they still confirm or retry the process-group reap and may
+  reject with `termination_failed`. `teardown()` is safe to call twice.
+- `status` transitions mark every real turn boundary: `running` when a turn
+  starts and `ready` when it ends, including turns ended by an interrupt.
+  Consumers can clear "agent is working" UI on the `ready` beat.
+
+The default terminal size is 189x48, wide enough that full-width TUI layouts
+render without artificial wrapping. Visual embedders should pass and maintain
+their real xterm size instead.
+
+## Persisting and resuming
+
+To resume across parent-app restarts, persist exactly two things: the
+`elwoodSessionId` and the `stateDir` it lives in (keep that directory intact).
+Everything else Elwood needs is in the session record.
+
+- Resume restores only the launch posture from the record: `permissionMode`,
+  allowed/disallowed tools, and `tools` for Claude; `sandbox` and
+  `approvalPolicy` for Codex. Explicit resume options override those fields
+  one by one and the result is re-persisted. Everything else is per-call and
+  must be re-supplied: `model`, `reasoningEffort`, hook handlers, `autotrust`,
+  `autoupdate`, `hookTimeoutMs`, `strictVersionCheck`, and `initialSize`.
+- `resumeClaude` / `resumeCodex` reject with `resume_unavailable` when the CLI
+  never reported its conversation id (Claude is resumable only after one
+  completed turn), `state_not_found` when no record exists, and
+  `adapter_mismatch` when the id belongs to the other adapter.
+- Prefer `startOrResumeClaude` / `startOrResumeCodex`: they fall back to a
+  fresh start only on those three errors, rethrow everything else (for example
+  `state_corrupt`), and return `{ session, resumed }`.
+- Loop definitions are restored with the same ids and jitter but fresh clocks;
+  expired loops are pruned and missed runs are never replayed.

package/docs/login-recovery.md

@@ -0,0 +1,86 @@
+# Recovering an expired Claude login
+
+Purpose: how Elwood detects a lapsed Claude login and how `ClaudeSession.login`
+recovers it in place, including its security properties and limits.
+
+If Claude's login lapses, the CLI stops responding and shows a banner such as
+"Login expired · Please run /login" or "Not logged in · Run /login". Elwood
+surfaces this so a session never wedges silently:
+
+- At startup, a login-expired banner rejects the start with
+  `claude_not_authenticated`. The session is torn down, not reported usable.
+- Mid-session, Elwood emits a content-free `login_expired` warning (and the
+  matching `warning` activity) carrying `recoveryCommand: "/login"`, and leaves
+  the session alive so you can recover without restarting.
+
+## Driving `/login`
+
+`ClaudeSession.login(options)` drives the interactive `/login` flow. The
+default account login ends with a human copying an authorization code from a
+browser, so `login` cannot complete unattended; it brackets the human step:
+
+```ts
+// Keep the event listener synchronous. Elwood's emitter ignores returned
+// promises, so an async listener's rejection would be unhandled. Launch
+// recovery from a separate function with its own catch.
+session.on("warning", (w) => {
+  if (w.code === "login_expired") void recoverLogin();
+});
+
+async function recoverLogin() {
+  try {
+    await session.login({
+      onAuthUrl: (url) => openInBrowser(url), // optional: the browser sign-in URL
+      provideCode: () => promptHumanForCode(), // required: the code from the browser
+      // method defaults to "claudeai"; timeoutMs defaults to 300000
+    });
+  } catch (err) {
+    // login_failed / login_timeout / session_not_running: decide whether to
+    // retry, tear down, or alert a human. Never rethrow into the event loop.
+    reportLoginFailure(err);
+  }
+}
+```
+
+`ClaudeLoginOptions.method` is `"claudeai"`, `"console"`, or `"third_party"`.
+
+`login` runs as an exclusive transaction. It serializes with every other
+control operation, so nothing interleaves with its picker keys, the code, or
+its Enters, and it never sends keystrokes into a blocking dialog. It submits
+`/login`, selects the login `method` if the CLI shows its picker, reports a
+validated authorization URL via `onAuthUrl`, and, when the CLI asks for a code,
+calls `provideCode`, validates the returned code (rejecting empty, oversized,
+or control-bearing values), and submits it followed by exactly one Enter.
+Screen stages count only when they newly appear after the `/login` submission,
+so stale on-screen text cannot drive the flow. It resolves only after the CLI
+reports success and the session reaches a fresh `ready` state, and rejects
+with `login_failed` (an explicit failure, an invalid code, or a failing
+`provideCode`), `login_timeout`, or `session_not_running`. A flow that
+completes without prompting for a code never calls `provideCode`.
+
+## Security considerations
+
+`login` layers several defenses so an untrusted screen cannot hijack the flow:
+
+- The transaction holds the control queue exclusively; nothing else writes
+  during it.
+- The scraped URL must be `https:` on an exactly-approved Anthropic host with
+  no credentials, or the flow fails.
+- The human-provided code is validated before it is written.
+- Stage markers are scoped to the screen's active tail and must be new
+  relative to a pre-`/login` baseline.
+- Login keystrokes hold while a blocking dialog is on screen.
+- The code prompt is re-checked as still current immediately before the code
+  is written.
+
+Two residual limitations remain by design:
+
+- A single frame that renders both a genuine approved-host `claude.ai` OAuth
+  URL and a paste-code prompt in the active region can still advance the flow.
+  This requires forging a host-valid OAuth URL, not merely a phrase. Only run
+  `login` when the session is genuinely at Claude's `/login` prompt, not while
+  untrusted tool or model output is streaming into the terminal.
+- The `/login` screen matchers are version-coupled to the Claude CLI and are
+  covered by unit tests against captured CLI strings, not by a live e2e test:
+  driving `/login` against a real authenticated session would mutate the
+  developer's auth and cannot run unattended in CI.

package/docs/loops.md

@@ -0,0 +1,58 @@
+# Recurring loops
+
+Purpose: how to schedule, inspect, cancel, and persist recurring prompts on a
+session.
+
+Elwood schedules loops itself, so Claude and Codex behave the same and no
+parent-app timer is needed. The typed API supports fixed intervals and an idle
+cadence, multiple loops per session, inspection, and cancellation:
+
+```ts
+const fixed = await session.createLoop({
+  mode: "fixed",
+  intervalMs: 5 * 60_000,
+  message: "Check the deployment and report regressions.",
+});
+await session.createLoop({ mode: "idle", message: "Continue with the next useful task." });
+
+console.log(await session.listLoops());
+await session.cancelLoop(fixed.id);
+```
+
+## Parsing a `/loop` command
+
+`parseLoopCommand("/loop 5m check the deployment")` returns the same fixed
+request shape; `parseLoopCommand("/loop check the deployment")` returns an
+idle request. Parsing is opt-in: `sendMessage("/loop ...")` still sends the
+literal text. Use the helper when your app wants a shared `/loop` UX.
+
+## Limits
+
+- Fixed intervals are one minute to less than seven days. Idle loops fire
+  after five minutes of readiness.
+- At most 50 active loops per session; messages are 1 to 65,536 bytes.
+- Delivery is readiness-safe and serial: a loop never interrupts a running
+  turn or writes into a blocking dialog.
+- Each loop gets a stable, id-derived, delay-only jitter of up to 30 seconds.
+- Loops expire after seven wall-clock days.
+- Missed runs are never replayed after resume.
+
+Validation, capacity, not-found cancellation, persistence, and
+scheduling/submission failures reject with stable typed errors.
+
+## Persistence and lifecycle
+
+Loop definitions live in a private, versioned, owner-only (`0600`) sidecar next
+to the session record. The sidecar stores the loop message and cadence
+metadata, but no live timer, due state, or submission state. This is the one
+place Elwood persists prompt text; see
+[design-notes.md](design-notes.md#state-privacy-and-safety).
+
+- `stop()` and unexpected exits preserve definitions.
+- `kill()` clears them permanently.
+- `teardown()` removes them with the session.
+- Resume restores unexpired definitions with the same ids and jitter, starting
+  fresh clocks from the resumed session's first real readiness.
+
+Subscribe to the `loop` event for redacted `created`, `fired`, `cancelled`,
+`expired`, and `failed` lifecycle events. The event never carries prompt text.

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@with-logic/elwood",
+  "version": "0.1.0",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/with-logic/elwood.git"
+  },
+  "homepage": "https://github.com/with-logic/elwood#readme",
+  "bugs": {
+    "url": "https://github.com/with-logic/elwood/issues"
+  },
+  "keywords": [
+    "claude-code",
+    "codex",
+    "agent",
+    "pty",
+    "terminal",
+    "hooks",
+    "cli",
+    "automation",
+    "llm"
+  ],
+  "type": "module",
+  "files": [
+    "dist",
+    "docs/*.md",
+    "CHANGELOG.md",
+    "README.md"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "elwood": "./dist/cli/entry.js"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node scripts/postbuild.mjs",
+    "prepare": "npm run build",
+    "test": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write .",
+    "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='src/app/**' --test-coverage-exclude='tests/**' --test-timeout=240000 --test-concurrency=1 --test tests/e2e/*.e2e.ts",
+    "dev:app": "exec node --no-warnings src/app/dev.ts",
+    "dev:web": "exec node --no-warnings scripts/supervise.ts src/app/web-dev.ts",
+    "example:minimal": "exec node --no-warnings scripts/supervise.ts examples/minimal.ts",
+    "example:stream": "exec node --no-warnings scripts/supervise.ts examples/stream.ts",
+    "example:full": "exec node --no-warnings scripts/supervise.ts examples/full.ts"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.15",
+    "@types/node": "^25.9.1",
+    "@types/ws": "^8.18.1",
+    "@vitest/coverage-istanbul": "^4.1.9",
+    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/xterm": "^6.0.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9",
+    "ws": "^8.21.0"
+  },
+  "dependencies": {
+    "@xterm/headless": "^6.0.0",
+    "node-pty": "^1.1.0"
+  }
+}