copperhead 0.7.0 → 0.8.0

package/src/config.ts

@@ -96,7 +96,7 @@ export async function loadConfig(repoRoot: string): Promise<CopperheadConfig> {
 }
 
 /** Which level of the model-selection precedence chain won. */
-export type ModelSource = 'flag' | 'env' | 'config' | 'openai-key' | 'anthropic-key';
+export type ModelSource = 'flag' | 'env' | 'config' | 'openai-key' | 'anthropic-key' | 'picker';
 
 export interface ResolvedModel {
   model: string;
@@ -111,6 +111,8 @@ export interface ResolvedModel {
  * Accepted values (same set for `--model`, COPPERHEAD_MODEL, and `model` in
  * .copperhead/config.json):
  *
+ * - `cursor`          : the Cursor Agent CLI using saved login (`agent login`).
+ * - `cursor:<id>`     : the same provider on a specific model id.
  * - `claude-code`     : the Claude Code saved-login provider on its default
  *                       model. Needs NO API key — it reuses the logged-in Claude
  *                       Code CLI / CLAUDE_CODE_OAUTH_TOKEN via the Agent SDK.
@@ -131,7 +133,8 @@ export interface ResolvedModel {
  * a typo like `claud-sonnet-5` silently routes to OpenAI and fails there.
  * Anthropic and direct OpenAI providers require their API keys; `codex` requires
  * a locally installed and authenticated Codex CLI, and `claude-code` requires a
- * Claude Code login (CLAUDE_CODE_OAUTH_TOKEN); neither needs a model API key.
+ * Claude Code login (CLAUDE_CODE_OAUTH_TOKEN); `cursor` requires `agent login`.
+ * None of the saved-login providers need a model API key.
  */
 export function resolveModel(flag: string | undefined, config: CopperheadConfig, env = process.env): ResolvedModel {
   if (flag) return { model: flag, source: 'flag' };
@@ -140,6 +143,6 @@ export function resolveModel(flag: string | undefined, config: CopperheadConfig,
   if (env.OPENAI_API_KEY) return { model: 'gpt-5', source: 'openai-key' };
   if (env.ANTHROPIC_API_KEY) return { model: 'claude', source: 'anthropic-key' };
   throw new Error(
-    'no model configured: pass --model codex (uses your local Codex login), set COPPERHEAD_MODEL, set model in .copperhead/config.json, or provide OPENAI_API_KEY/ANTHROPIC_API_KEY',
+    'no model configured: pass --model, set COPPERHEAD_MODEL, or export an API key; see https://docs.copperhead.sh/reference/configuration/',
   );
 }

package/src/kicad/cli.ts

@@ -1,4 +1,5 @@
 import { execa, ExecaError } from 'execa';
+import { existsSync } from 'node:fs';
 import { mkdtemp, readFile, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
@@ -13,6 +14,7 @@ export class KicadCliMissingError extends PreflightError {
       [
         'install KiCad ≥ 8: https://www.kicad.org/download/',
         'ensure the kicad-cli binary is on PATH (on macOS it ships inside KiCad.app/Contents/MacOS)',
+        'or set COPPERHEAD_KICAD_CLI=/Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli',
         'confirm with "kicad-cli version", then rerun',
       ],
     );
@@ -20,12 +22,134 @@ export class KicadCliMissingError extends PreflightError {
   }
 }
 
+/**
+ * `COPPERHEAD_KICAD_CLI` points somewhere that does not exist. Distinct from
+ * KicadCliMissingError because the advice is the opposite: the override was
+ * seen and rejected, so telling the user to set it would be nonsense.
+ */
+export class KicadCliBadOverrideError extends PreflightError {
+  constructor(configured: string) {
+    super(
+      `COPPERHEAD_KICAD_CLI points to a path that does not exist: ${configured}`,
+      'the override wins over PATH, so falling back silently would run a different binary than the one you named and make the failure impossible to diagnose',
+      [
+        `check the path: ls -l "${configured}"`,
+        'on macOS the binary lives at /Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli',
+        'or unset COPPERHEAD_KICAD_CLI to fall back to PATH',
+        'confirm with "$COPPERHEAD_KICAD_CLI version", then rerun',
+      ],
+    );
+    this.name = 'KicadCliBadOverrideError';
+  }
+}
+
+/** Well-known install locations when `kicad-cli` is not on PATH (macOS app bundle). */
+const FALLBACK_BINARIES = [
+  '/Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli',
+  '/Applications/KiCad-10.0/KiCad.app/Contents/MacOS/kicad-cli',
+  '/Applications/KiCad-9.0/KiCad.app/Contents/MacOS/kicad-cli',
+  '/Applications/KiCad-8.0/KiCad.app/Contents/MacOS/kicad-cli',
+];
+
+let fallbackBinaries: readonly string[] = FALLBACK_BINARIES;
+
+let cachedBinary: string | null | undefined;
+
+/**
+ * Resolve the kicad-cli executable: `COPPERHEAD_KICAD_CLI` > PATH name
+ * (`kicad-cli`). On PATH miss, `runKicad` falls back to macOS KiCad.app paths.
+ */
+export function resolveKicadCli(): string {
+  if (cachedBinary !== undefined) {
+    if (cachedBinary === null) throw new KicadCliMissingError();
+    return cachedBinary;
+  }
+  const fromEnv = envOverride();
+  if (fromEnv) {
+    cachedBinary = fromEnv;
+    return fromEnv;
+  }
+  cachedBinary = 'kicad-cli';
+  return cachedBinary;
+}
+
+/**
+ * The `COPPERHEAD_KICAD_CLI` override, or null when unset. Set-but-missing is
+ * a hard error rather than a silent fallthrough to PATH: the user told us
+ * which binary to run, and quietly running a different one (or reporting
+ * "not found on PATH" with advice to set the variable they already set) is
+ * the worst possible answer.
+ */
+function envOverride(): string | null {
+  const fromEnv = process.env.COPPERHEAD_KICAD_CLI?.trim();
+  if (!fromEnv) return null;
+  if (!existsSync(fromEnv)) throw new KicadCliBadOverrideError(fromEnv);
+  return fromEnv;
+}
+
+/**
+ * After ENOENT on PATH, retry with a known macOS install path.
+ *
+ * Deliberately does not re-read `COPPERHEAD_KICAD_CLI`: this is reached only
+ * when resolveKicadCli() cached the bare PATH name, which in turn happens only
+ * when the override was unset (set-but-missing throws there instead), so an
+ * override re-check here could never fire.
+ */
+function fallbackAfterMissing(): string {
+  for (const candidate of fallbackBinaries) {
+    if (existsSync(candidate)) {
+      cachedBinary = candidate;
+      return candidate;
+    }
+  }
+  cachedBinary = null;
+  throw new KicadCliMissingError();
+}
+
+async function runKicad(args: string[], opts?: { reject?: boolean }): Promise<Awaited<ReturnType<typeof execa>>> {
+  let bin = resolveKicadCli();
+  let res = await execa(bin, args, { reject: false });
+  if (res.failed && (res as unknown as ExecaError).code === 'ENOENT') {
+    if (bin === 'kicad-cli') {
+      bin = fallbackAfterMissing();
+      res = await execa(bin, args, { reject: false });
+    } else {
+      throw new KicadCliMissingError();
+    }
+  }
+  if (opts?.reject === false) return res;
+  if (res.failed && (res as unknown as ExecaError).code === 'ENOENT') {
+    throw new KicadCliMissingError();
+  }
+  if (res.failed) {
+    throw Object.assign(new Error(res.stderr || res.stdout || `kicad-cli exited ${res.exitCode}`), res);
+  }
+  return res;
+}
+
+/** Test helper: clear the resolved-binary cache. */
+export function resetKicadCliCache(): void {
+  cachedBinary = undefined;
+}
+
+/**
+ * Test helper: point the app-bundle probe at fixture paths, or call with no
+ * argument to restore the real list. Without this the fallback branch is only
+ * exercisable on a macOS host that happens to have KiCad installed, which
+ * makes the outcome depend on the developer's machine.
+ */
+export function setKicadFallbackBinaries(paths?: readonly string[]): void {
+  fallbackBinaries = paths ?? FALLBACK_BINARIES;
+}
+
 export async function kicadCliVersion(): Promise<string> {
   try {
-    const { stdout } = await execa('kicad-cli', ['version']);
-    return stdout.trim();
+    const res = await runKicad(['version']);
+    return String(res.stdout ?? '').trim();
   } catch (err) {
     if ((err as ExecaError).code === 'ENOENT') throw new KicadCliMissingError();
+    // runKicad already maps PATH ENOENT → fallback → KicadCliMissingError
+    if (err instanceof KicadCliMissingError) throw err;
     throw err;
   }
 }
@@ -39,8 +163,7 @@ async function runCheck(
   const out = path.join(dir, `${kind}.json`);
   const sub = kind === 'erc' ? ['sch', 'erc'] : ['pcb', 'drc'];
   try {
-    const res = await execa(
-      'kicad-cli',
+    const res = await runKicad(
       [...sub, '--format', 'json', '--exit-code-violations', '--output', out, ...extraArgs, filePath],
       { reject: false },
     );
@@ -94,7 +217,7 @@ export async function kicadLoadError(filePath: string): Promise<string | null> {
     ? ['sch', 'export', 'netlist', '--output', path.join(dir, 'probe.net'), filePath]
     : ['pcb', 'export', 'pos', '--output', path.join(dir, 'probe.pos'), filePath];
   try {
-    const res = await execa('kicad-cli', args, { reject: false });
+    const res = await runKicad(args, { reject: false });
     if (res.failed && (res as unknown as ExecaError).code === 'ENOENT') throw new KicadCliMissingError();
     if (res.exitCode === 0) return null;
     return [res.stderr, res.stdout].filter(Boolean).join('\n').trim() || `kicad-cli exited ${res.exitCode}`;
@@ -131,9 +254,10 @@ export async function exportFab(pcbPath: string, schPath: string | null, outDir:
   }
   for (const job of jobs) {
     try {
-      await execa('kicad-cli', job.args);
+      await runKicad(job.args);
       result.produced.push(job.artifact);
     } catch (err) {
+      if (err instanceof KicadCliMissingError) throw err;
       if ((err as ExecaError).code === 'ENOENT') throw new KicadCliMissingError();
       result.failed.push({ artifact: job.artifact, reason: String((err as ExecaError).stderr ?? (err as Error).message).slice(0, 200) });
     }
@@ -148,8 +272,9 @@ export async function exportSvg(kind: 'sch' | 'pcb', filePath: string, outDir: s
       ? ['sch', 'export', 'svg', '--output', outDir, filePath]
       : ['pcb', 'export', 'svg', '--output', path.join(outDir, 'board.svg'), '--layers', 'F.Cu,B.Cu,Edge.Cuts', filePath];
   try {
-    await execa('kicad-cli', args);
+    await runKicad(args);
   } catch (err) {
+    if (err instanceof KicadCliMissingError) throw err;
     if ((err as ExecaError).code === 'ENOENT') throw new KicadCliMissingError();
     throw err;
   }

package/src/layout/claude-ui-layout.md

@@ -0,0 +1,72 @@
+# Claude Code UI layout (measured reference)
+
+Captured from the real `claude` CLI (v2.1.220) under a pty + VT102 emulator at
+100x30, with per-cell SGR attributes extracted, so every color below is
+measured, not eyeballed. This is the reference to diff
+[repl-ui-layout.md](repl-ui-layout.md) against when editing copperhead's
+chrome.
+
+## State 1: idle prompt
+
+```text
+ 2| ▐▛███▜▌   Claude Code v2.1.220                       <- logo[#d77757]  name[bold, default fg] version[#999999]
+ 3|▝▜█████▛▘  Fable 5 with high effort · Claude Max      <- logo[#d77757]  model+plan[#999999]
+ 4|  ▘▘ ▝▝    ~/Github/chouhan-industries/copperhead     <- logo[#d77757]  cwd[#999999]
+ 5|
+ 6|   Tackle your toughest work with Opus 5. ...          <- notice body[default fg]
+ 7|   +1 more · /status                                   <- [#999999]
+..|                                                       <- content region, output scrolls here
+25|                                     ● high · /effort  <- meta right-aligned, all [#999999]
+26|─────────────────────────────────────────────────────  <- rule[#888888], full width
+27|❯ Try "create a util logging.py that..."               <- ❯ + nbsp[default], placeholder[faint], caret = real cursor
+28|─────────────────────────────────────────────────────  <- rule[#888888], full width
+29|  ⚠ Transcript saving is off · ...                     <- warning line (only when present)
+30|  ⏸ manual mode on · ? for shortcuts                   <- status left[#999999]
+```
+
+## State 2: slash menu open (upward overlay, input row fixed at 27)
+
+```text
+22|  /pr-review     Review a copperhead pull request...   <- hovered: label+desc[#b1b9f9], no inverse video
+23|                 spec workflow. Use when the user...   <- description wraps to a second row
+24|  /review        Review a GitHub pull request; ...     <- unhovered: [#999999]
+26|─────────────────────────────────────────────────────
+27|❯ /                                                    <- typed filter[default fg]
+28|─────────────────────────────────────────────────────
+30|  ⏸ manual mode on                                     <- status shrinks while menu is open
+```
+
+## State 3: Ctrl+C pressed once
+
+```text
+30|  Press Ctrl-C again to exit                           <- [#999999], replaces the status line
+```
+
+## Measured color palette
+
+| Role                        | Value             | Notes                                   |
+| --------------------------- | ----------------- | --------------------------------------- |
+| Accent (logo)               | `#d77757`         | truecolor; the only saturated color     |
+| Title (`Claude Code`)       | bold, default fg  | not white-forced: follows the theme     |
+| Secondary text              | `#999999`         | truecolor gray, softer than SGR 90      |
+| Rules                       | `#888888`         | one step darker than secondary text     |
+| Menu hover                  | `#b1b9f9`         | periwinkle, hover is a color change     |
+| Placeholder                 | faint (SGR 2)     | not fg-colored, uses the faint attr     |
+| Caret                       | terminal cursor   | real cursor, not a synthetic inverse    |
+
+## Structural notes vs copperhead's current implementation
+
+1. Grays: adopted. copperhead's `dim`/`ruleDim` are truecolor
+   `#999999`/`#888888` (with an SGR 90 fallback when truecolor is off).
+2. Menu hover: adopted as a color change. Claude recolors the row with
+   periwinkle `#b1b9f9`; copperhead recolors with `copperLight` (#eec9a5)
+   instead of inverse video.
+3. Hovered menu descriptions: adopted. Both wrap to a second row.
+4. Caret: adopted. copperhead parks the real terminal cursor in the input
+   row instead of drawing a synthetic inverse block.
+5. The name `Claude Code` is bold in the terminal's default foreground, so it
+   adapts to light/dark themes, it is not hard-coded white.
+6. There is a non-breaking space after `❯` in the prompt.
+
+To adopt any of these in copperhead, edit the corresponding line in
+[repl-ui-layout.md](repl-ui-layout.md) and paste it back.

package/src/layout/repl-ui-layout.md

@@ -0,0 +1,139 @@
+# REPL UI layout spec
+
+Captured from a real run (pty + VT102 emulator, 100x30). This file is the
+editing surface for the interactive shell's chrome: change any line below,
+paste it back, and the implementation follows. Every visual token maps to one
+function in `src/agent/theme.ts`, so color changes are one-line edits.
+
+## State 1: idle prompt
+
+```text
+ 1|                                                                        <- blank
+ 2|   ▄▟▙▄       copperhead v0.7.0                                         <- mark[copper]  name[bold] version[dim]
+ 3| ███  ███     claude via flag · kicad-cli 9.0.4                         <- mark[copper]  meta[dim]
+ 4|   ▀▜▛▀       ~/Github/chouhan-industries/copperhead                    <- mark[copper]  cwd[dim]
+ 5|                                                                        <- blank
+ 6| ▎ New repository?                                                      <- bar[copper] title[copper]
+ 7| ▎  `copperhead init` scaffolds docs/ from an existing schematic        <- bar[copper] body[default]
+ 8| ▎  `copperhead demo` runs the USB-C breakout create pipeline           <- bar[copper] body[default]
+ 9| ▎ Docs: https://docs.copperhead.sh                                     <- bar[copper] body[copper]
+10|                                                                        <- content region: echoes + agent
+..|  ❯ rename net KEY_DAH to KEY_DASH                                      <-   output scroll here, oldest
+..|  ▸ run_erc  clean — 0 violations                                       <-   scrolls off the top
+26|                                                     ● claude · main*   <- meta right-aligned: dot[copper] text[dim]
+27|──────────────────────────────────────────────────────────────────────  <- rule[dim], full width
+28|❯ Try "add reverse-polarity protection on VIN"                          <- prompt[copper]+nbsp, caret = real cursor, placeholder[dim] typed[bright]
+29|──────────────────────────────────────────────────────────────────────  <- rule[dim], full width
+30|  / for commands · pgup history · ctrl+c twice to quit         In copperhead   <- left[dim]  right[dim]
+```
+
+## State 2: slash menu open (overlays upward, input row never moves)
+
+```text
+16|  ❯ /demo         what copperhead does + how to try it                  <- hovered: ❯[copper] label+desc[copperLight], desc wraps to a 2nd row
+17|    /examples     example change-request prompts                        <- label[default] desc[default]
+..|    ...up to 10 items...
+26|  ↓ 10 more                                                             <- overflow marker[dim]
+27|──────────────────────────────────────────────────────────────────────  <- rule[dim]
+28|❯ /                                                                     <- typed filter[bright]
+29|──────────────────────────────────────────────────────────────────────  <- rule[dim]
+30|  / for commands · pgup history · ctrl+c twice to quit         In copperhead
+```
+
+## State 3: agent turn running (observability row pinned in the dock)
+
+```text
+26|                                                     ● claude · main*   <- meta stays
+27|──────────────────────────────────────────────────────────────────────
+28|⠹ Reflowing...              turn 2/40 · 1.2k in / 300 out · 12s · ERC   <- word left[copper], stats right[dim] busy[warn]
+29|──────────────────────────────────────────────────────────────────────
+30|  ctrl+c interrupts the run · output above scrolls into history
+```
+
+The working word is a PCB term (Routing, Etching, Reflowing, Soldering,
+Drilling, Plating, Probing, Fluxing, Tinning, Laminating, Silkscreening,
+Panelizing), one per turn, with animated dots: Claude Code's working verbs,
+board-shop edition; on rotation the old word crossfades char by char
+through `_` slots, dots included. Durable output (tool lines, turn markers, the outcome)
+scrolls in the content region; the observability row never moves. Between
+submit and the first turn a passive `… working` row shows briefly.
+
+First Ctrl+C at the prompt: input clears, row 30 becomes `press ctrl+c again to exit` [warn].
+
+History: every content line is kept in a session buffer (cap 5000). PgUp at
+the prompt scrolls the content region back through it (arrow keys / mouse
+wheel line-scroll too at an empty prompt), PgDn scrolls forward,
+any other key snaps back to the live tail; row 30 shows
+`history ↑N · pgup/pgdn scroll · any key returns` while scrolled. The same
+lines are mirrored by default to `.copperhead/runs/repl-<timestamp>.log`
+(plain text: SGR stripped, `sk-` keys redacted per AC-4.1); the path is
+printed when the session ends. Injected loggers (tests/embeds) disable the
+file sink.
+
+Startup: the full screen loads instantly (banner, callout, input dock), then
+the mark pulses in place twice over rows 2-4 (dot, thin ring, thick
+ring, full via) while the prompt is already usable. First run in a repo (no
+`.copperhead/` yet) uses slow timing (110ms/frame) and shows the New
+repository callout; later runs pulse fast (45ms/frame) and hide it.
+
+## Color tokens (src/agent/theme.ts)
+
+| Token         | SGR                | Current value             | Used for                               |
+| ------------- | ------------------ | ------------------------- | -------------------------------------- |
+| `copper`      | `38;2;184;115;51`  | #b87333 (brand: #b87333)  | mark, prompt ❯, callout bar, meta dot  |
+| `copperLight` | `38;2;238;201;165` | #eec9a5 (accent-high)     | hovered menu row                       |
+| `bold`        | `1`                | bold, default fg          | `copperhead` name (theme-adaptive)     |
+| `bright`      | `97`               | white                     | typed input text                       |
+| `dim`         | `38;2;153;153;153` | #999999 (SGR 90 fallback) | hints, placeholder, version, paths     |
+| `ruleDim`     | `38;2;136;136;136` | #888888 (SGR 90 fallback) | input-area rules                       |
+| `ok`          | `32`               | green                     | success lines (`check: all green`)     |
+| `warn`        | `33`               | amber                     | ctrl+c hint, cautions                  |
+| `err`         | `31`               | red                       | failures                               |
+
+Note: `copper` is the exact brand #b87333 on truecolor terminals
+(COLORTERM=truecolor/24bit); terminals without truecolor fall back to
+256-color 173. See [claude-ui-layout.md](claude-ui-layout.md) for the measured
+Claude Code reference palette to diff against.
+
+## Region -> source map
+
+| Region                | Source                                          |
+| --------------------- | ----------------------------------------------- |
+| Banner + callout      | `banner()` in `src/commands/repl.ts`            |
+| Meta line, status bar | `ask()` options in `src/commands/repl.ts`       |
+| Input rows, menu      | `src/util/live-prompt.ts` (`renderDock`)        |
+| Rules, callout, bars  | `src/agent/box.ts`                              |
+| Screen ownership      | `src/util/dock.ts` (alt screen + DECSTBM fence) |
+
+To iterate: edit the annotated lines above (text, alignment, or `[token]`
+tags), paste the block back, and the code gets updated to match. Verify with
+`npm run demo:ui` (see below).
+
+## Demo recording (npm run demo:ui)
+
+`npm run demo:ui` from the repo root runs `scripts/ui-demo.ts` via tsx: the
+real REPL UI with a canned agent run, no build step, no API key, no repo
+mutations. Same script every take, so recordings are reproducible.
+
+Standard take:
+
+1. Let the banner settle and the via mark pulse
+2. Type `/`, hover a few commands with the arrow keys, Esc to dismiss
+3. Type `rename net KEY_DAH to KEY_DASH`, Enter, let the mock run play
+   (~17s, four sections: propose, edit, verify, remember, each closed by a
+   summary line; the pinned observability row animates and the working word
+   morphs at each section)
+4. `/check` for the mock green ERC/DRC/drift pass
+5. Ctrl+C twice to exit
+
+The demo uses the current directory as the repo. A directory that already has
+`.copperhead/` gets the fast mark pulse and no callout; for the full
+first-run intro (slow pulse + New repository callout), run from a fresh
+directory:
+
+```bash
+cd $(mktemp -d) && node <repo>/node_modules/.bin/tsx <repo>/scripts/ui-demo.ts
+```
+
+The mark itself can be regenerated from the website logo geometry at any
+size with `node scripts/gen-logo.mjs <rows>`.

package/src/util/cli-args.ts

@@ -0,0 +1,42 @@
+/**
+ * Pure argument helpers for the CLI surface. They live here rather than in
+ * cli.ts because that module wires up commander and parses argv at import
+ * time, which makes it untestable in-process: importing it runs the program.
+ * Anything with a branch worth pinning belongs on this side of the line.
+ */
+
+import path from 'node:path';
+import type { BudgetExhaustedStats } from '../agent/loop.js';
+
+/** Resolve `--repo` against the working directory; absolute paths pass through. */
+export function repoOf(opts: { repo?: string }): string {
+  return path.resolve(opts.repo ?? process.cwd());
+}
+
+/** `--max-turns` accepts only a positive integer; "5oops" and "NaN" refuse to start. */
+export function parseMaxTurns(raw: string): number {
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n <= 0) {
+    throw new Error(`--max-turns must be a positive integer, got "${raw}"`);
+  }
+  return n;
+}
+
+/**
+ * Turns offered when the budget runs out: ceil of the ORIGINAL budget (design
+ * D1), so repeat extensions offer the same increment instead of escalating
+ * with the already-extended turn count.
+ */
+export function budgetExtraTurns(stats: Pick<BudgetExhaustedStats, 'maxTurns'>): number {
+  return Math.ceil(stats.maxTurns / 2);
+}
+
+/** The attended "continue?" question, with the cost of the run so far spelled out. */
+export function budgetPromptText(stats: BudgetExhaustedStats): string {
+  const k = (n: number): string => `${(n / 1000).toFixed(1)}k`;
+  return (
+    `Turn budget exhausted (${stats.turnsUsed} turns, ${k(stats.tokensIn)} in / ${k(stats.tokensOut)} out, ` +
+    `${stats.filesTouched.length} file(s) touched, ${stats.openObligations} open obligation(s)). ` +
+    `Continue with ${budgetExtraTurns(stats)} more turns?`
+  );
+}

package/src/util/dock.ts

@@ -0,0 +1,161 @@
+/**
+ * Bottom-of-viewport dock built on DECSTBM scroll regions: content is fenced
+ * into rows [1, H - dockHeight] and the dock is painted with absolute cursor
+ * addressing below the scroll margin, so no amount of content output (or
+ * mouse wheel) can ever move it. Runs inside the alternate screen buffer the
+ * REPL enters at startup. This is the FrankenTUI/ratatui-inline technique;
+ * see also DECSTBM (CSI r).
+ */
+
+import { truncateVisible } from '../agent/box.js';
+
+const HIDE = '\x1b[?25l';
+const SHOW = '\x1b[?25h';
+/** Synchronized-output guards; terminals without support ignore them. */
+const SYNC_ON = '\x1b[?2026h';
+const SYNC_OFF = '\x1b[?2026l';
+/** Reset the scroll region to the full screen. Homes the cursor (hence DECSC/DECRC around it). */
+const REGION_RESET = '\x1b[r';
+const SAVE = '\x1b7';
+const RESTORE = '\x1b8';
+
+export class TerminalDock {
+  /** Rows the dock currently occupies at the bottom of the screen. */
+  private dockH = 0;
+  /**
+   * True while the real cursor is parked at a caret position inside the dock
+   * (the DECSC slot then holds the content-region position to return to).
+   */
+  private parked = false;
+  /** Last set() payload, replayable after an external overdraw (animations). */
+  private last: { lines: string[]; caret?: { row: number; col: number } } | null = null;
+
+  constructor(private readonly out: NodeJS.WriteStream) {}
+
+  cols(): number {
+    return typeof this.out.columns === 'number' && this.out.columns ? this.out.columns : 80;
+  }
+
+  rows(): number {
+    return typeof this.out.rows === 'number' && this.out.rows ? this.out.rows : 24;
+  }
+
+  /**
+   * Replace the docked region. On a height change the content scroll region
+   * is re-fenced; same-height repaints are pure absolute-addressed writes and
+   * can never scroll anything. With `caret` (dock-relative 1-based row and
+   * column) the real terminal cursor is left parked there, Claude Code-style.
+   */
+  set(lines: string[], caret?: { row: number; col: number }): void {
+    if (!lines.length) {
+      this.release();
+      return;
+    }
+    const h = this.rows();
+    const shown = lines.slice(0, Math.max(1, h - 3)).map((l) => truncateVisible(l, this.cols() - 1));
+    const newH = shown.length;
+
+    let seq = SYNC_ON + HIDE;
+    if (this.parked) {
+      // Return to the content position first so the SAVE/RESTORE pairs below
+      // keep preserving it, not the old caret.
+      seq += RESTORE;
+      this.parked = false;
+    }
+    if (this.dockH === 0) {
+      // First activation: free the bottom rows by scrolling exactly as much
+      // as needed (preserves the banner above), then fence content into
+      // [1, h - newH]. DECSTBM homes the cursor; save/restore keeps it.
+      seq += SAVE + REGION_RESET + RESTORE;
+      seq += '\n'.repeat(newH) + `\x1b[${newH}A`;
+      seq += SAVE + `\x1b[1;${h - newH}r` + RESTORE;
+    } else if (newH !== this.dockH) {
+      // Height change while active (menu open/close): overlay mode. Re-fence
+      // and clear any rows freed by a shrink; never scroll content.
+      seq += SAVE + `\x1b[1;${h - newH}r`;
+      for (let r = h - Math.max(this.dockH, newH) + 1; r <= h - newH; r++) {
+        seq += `\x1b[${r};1H\x1b[2K`;
+      }
+      seq += RESTORE;
+    }
+    seq += SAVE;
+    for (let i = 0; i < newH; i++) {
+      seq += `\x1b[${h - newH + 1 + i};1H\x1b[2K${shown[i]!}`;
+    }
+    seq += RESTORE;
+    if (caret) {
+      const row = Math.min(h, h - newH + Math.max(1, caret.row));
+      const col = Math.max(1, Math.min(this.cols(), caret.col));
+      seq += SAVE + `\x1b[${row};${col}H`;
+      this.parked = true;
+    }
+    seq += SHOW + SYNC_OFF;
+    this.out.write(seq);
+    this.dockH = newH;
+    this.last = caret ? { lines, caret } : { lines };
+  }
+
+  /** Replay the last set() (e.g. after an animation overdrew part of the screen). */
+  repaint(): void {
+    if (this.last) this.set(this.last.lines, this.last.caret);
+  }
+
+  /** Rows available to content above the dock. */
+  contentRows(): number {
+    return Math.max(1, this.rows() - this.dockH);
+  }
+
+  /**
+   * Absolute-paint the whole content region (rows 1..contentRows) from the
+   * given lines — used by history scrolling to show any window of the session
+   * log. Does not touch the DECSC slot or the fence; callers repaint() the
+   * dock afterwards to restore the caret.
+   */
+  paintContent(lines: string[]): void {
+    const rowsN = this.contentRows();
+    const shown = lines.slice(-rowsN).map((l) => truncateVisible(l, this.cols() - 1));
+    let seq = SYNC_ON + HIDE;
+    for (let r = 1; r <= rowsN; r++) {
+      seq += `\x1b[${r};1H\x1b[2K${shown[r - 1] ?? ''}`;
+    }
+    seq += SYNC_OFF;
+    this.out.write(seq);
+  }
+
+  /**
+   * Write a scrollback line above the dock. With the fence in place a plain
+   * write cannot touch the dock rows; if the cursor is parked at the caret,
+   * hop back to the content region for the write and re-park after.
+   */
+  log(line: string): void {
+    if (!this.parked) {
+      this.out.write(line + '\n');
+      return;
+    }
+    this.out.write(SYNC_ON + RESTORE + line + '\n' + SAVE + SYNC_OFF);
+    // The slot now holds the advanced content position; the caret will be
+    // re-established by the next set() with a caret argument.
+    this.parked = false;
+  }
+
+  /** Drop the fence, clear the dock rows, and restore the cursor. */
+  release(): void {
+    if (!this.dockH) {
+      this.out.write(SHOW);
+      return;
+    }
+    const h = this.rows();
+    let seq = SYNC_ON;
+    if (this.parked) {
+      seq += RESTORE;
+      this.parked = false;
+    }
+    seq += SAVE + REGION_RESET + RESTORE;
+    seq += SAVE;
+    for (let r = h - this.dockH + 1; r <= h; r++) seq += `\x1b[${r};1H\x1b[2K`;
+    seq += RESTORE + SHOW + SYNC_OFF;
+    this.out.write(seq);
+    this.dockH = 0;
+    this.last = null;
+  }
+}