rovecode 0.3.2

package/src/lanes/registry.ts

@@ -0,0 +1,178 @@
+/** Lane registry (#47): the four adapters by id, the `ROVECODE_LANES_ALLOW` gate, the LaneOpts defaults
+ *  (+ the user-side knobs that shape a lane's permissions), and the ONE function that turns a lane's
+ *  options into the approval-card text — the TaskManager stores the same string on the TaskInfo, so the
+ *  card and the running lane agree.
+ *
+ *  THE GATE IS ON BY DEFAULT (changed 2026-09-07, at the user's request). It used to be an opt-in
+ *  allow-list: unset meant no lane could start, so a CLI the user had installed was unreachable until
+ *  they found an env knob nobody reads. Now an UNSET knob allows every adapter and a DEFINED knob is an
+ *  exact list — `ROVECODE_LANES_ALLOW=` (empty) is the kill switch, and `=codex` still means codex only.
+ *  Defined-wins is what makes that safe: turning the default on cannot silently widen a machine whose
+ *  owner had already written a narrower list.
+ *
+ *  What replaces the gate as the thing that stops a lane is INSTALLEDNESS. With lanes off, a missing CLI
+ *  was academic; with lanes on it is the common case, and the honest place to say so is here, before a
+ *  worktree exists. Left to the spawn it surfaces as `spawn failed: codex: ENOENT` after the lane has
+ *  built a worktree and burned a turn — a refusal at the gate costs neither. The probe reads PATH only
+ *  (plus PATHEXT on win32); it is injectable so no test ever depends on what this machine has installed,
+ *  and it is memoised per (bin, PATH) because `task start` may be called in a loop.
+ *
+ *  Turning the gate on removes the approval that came WITH it for anyone running permission=auto, where
+ *  no card is ever shown. `laneStartNote` is the replacement: the text a surface states when a lane
+ *  starts, at every permission level, so "an external CLI just began working in your repo" is never
+ *  something the user has to infer from a spinner. It is the card's own sentence — one function builds
+ *  both, so the note cannot drift from the flags the lane actually got. */
+
+import { existsSync } from "node:fs";
+import { delimiter, join } from "node:path";
+import { isObj } from "./events.ts";
+import { ADAPTER_IDS, isAdapterId, type AdapterId, type AgentAdapter, type LaneOpts } from "./types.ts";
+import { claudeAdapter } from "./claude.ts";
+import { codexAdapter } from "./codex.ts";
+import { opencodeAdapter } from "./opencode.ts";
+import { agyAdapter } from "./agy.ts";
+
+export const ADAPTERS: Readonly<Record<AdapterId, AgentAdapter>> = {
+  claude: claudeAdapter, codex: codexAdapter, opencode: opencodeAdapter, agy: agyAdapter,
+};
+
+export type Env = Readonly<Record<string, string | undefined>>;
+
+// The knobs, by their documented names. The harness this came from routed every read through a central
+// core/env.ts that also consulted a settings file; rovecode has no such reader — it reads ROVECODE_* off
+// the environment in 45 places — so the two helpers below are the whole of it, and a lane knob behaves
+// like every other rovecode knob. `envName` exists so the name is written once and displayed the same
+// way it is read: a refusal that names the wrong variable is worse than no refusal.
+/** the full variable name for a knob: `LANES_ALLOW` → `ROVECODE_LANES_ALLOW` */
+export const envName = (knob: string): string => `ROVECODE_${knob}`;
+/** read a knob; DEFINED wins, even when empty (the call sites treat "" exactly as they treat unset) */
+const readEnv = (knob: string, env: Env = process.env): string | undefined => env[envName(knob)];
+/** comma list of adapter ids that may be STARTED at all; UNSET = all four, empty = none (the kill switch) */
+export const LANES_ALLOW_ENV = envName("LANES_ALLOW");
+/** comma list of adapter ids that get an explicit allow-all (agy: `--dangerously-skip-permissions`) */
+export const LANES_ALLOW_ALL_ENV = envName("LANES_ALLOW_ALL");
+/** claude `--allowedTools` rules, comma-separated (default Read,Edit,Write) */
+export const LANE_CLAUDE_ALLOW_ENV = envName("LANE_CLAUDE_ALLOW");
+/** claude `--bare`: "1" forces it, "0" drops it; unset = on only when ANTHROPIC_API_KEY is set in the lane
+ *  env (live-verified 2026-09-03: `--bare` authenticates with the key ALONE — the CLI's login is never read) */
+export const LANE_CLAUDE_BARE_ENV = envName("LANE_CLAUDE_BARE");
+/** claude's documented headless login (`claude setup-token`) — the CLI reads it itself when the lane is not
+ *  `--bare` (process.ts KEPT_ENV_EXACT lets it through); the registry reads it only for the card's auth word */
+export const CLAUDE_OAUTH_TOKEN_ENV = "CLAUDE_CODE_OAUTH_TOKEN";
+/** the knob suffix of a lane's model flag (`--model` / `-m provider/model`): LANE_<ID>_MODEL — read through
+ *  ROVECODE_LANE_<ID>_MODEL — unset means the lane's CLI picks its own default, which is not ours to guess */
+export const laneModelKnob = (id: AdapterId): string => `LANE_${id.toUpperCase()}_MODEL`;
+/** the documented name of that knob: ROVECODE_LANE_<ID>_MODEL */
+export const laneModelEnv = (id: AdapterId): string => envName(laneModelKnob(id));
+/** codex `--sandbox`: read-only | workspace-write (default) */
+export const LANE_CODEX_SANDBOX_ENV = envName("LANE_CODEX_SANDBOX");
+/** wall-clock budget per lane in ms (default 15 min) */
+export const LANE_TIMEOUT_ENV = envName("LANE_TIMEOUT_MS");
+export const DEFAULT_LANE_TIMEOUT_MS = 15 * 60_000;
+
+function idList(raw: string | undefined): Set<AdapterId> {
+  const out = new Set<AdapterId>();
+  for (const tok of (raw ?? "").split(",")) {
+    const id = tok.trim().toLowerCase();
+    if (isAdapterId(id)) out.add(id);
+  }
+  return out;
+}
+
+/** Adapter ids that may start. UNSET `ROVECODE_LANES_ALLOW` = all four; a DEFINED value is an exact
+ *  list, so an empty string allows nothing (the kill switch) and unknown tokens are ignored. */
+export const lanesAllowed = (env: Env = process.env): Set<AdapterId> => {
+  const raw = readEnv("LANES_ALLOW", env);
+  return raw === undefined ? new Set(ADAPTER_IDS) : idList(raw);
+};
+/** The binary an adapter would run, without building a lane: `command()` is pure and takes no process. */
+export const laneBinary = (id: AdapterId, env: Env = process.env): string =>
+  ADAPTERS[id].command({ goal: "probe" }, laneOptsFor(id, ".", env)).bin;
+
+/** Is `bin` runnable? PATH only (plus PATHEXT on win32) — the same lookup the OS would do at spawn.
+ *  Injectable and memoised; a bare name with no PATH at all is assumed present rather than refused,
+ *  because guessing "missing" would block a lane the OS could in fact have started. */
+export type PathProbe = (bin: string, env: Env) => boolean;
+const probeCache = new Map<string, boolean>();
+export const onPath: PathProbe = (bin, env) => {
+  const path = env["PATH"] ?? env["Path"] ?? "";
+  const key = `${process.platform}|${bin}|${path}`;
+  const hit = probeCache.get(key);
+  if (hit !== undefined) return hit;
+  const ok = lookup(bin, path, env);
+  probeCache.set(key, ok);
+  return ok;
+};
+function lookup(bin: string, path: string, env: Env): boolean {
+  if (bin.includes("/") || bin.includes("\\")) return existsSync(bin);   // an explicit path is not a PATH lookup
+  if (path === "") return true;                                          // nothing to search: do not claim it is missing
+  const exts = process.platform === "win32"
+    ? (env["PATHEXT"] ?? ".COM;.EXE;.BAT;.CMD").split(";").map((e) => e.trim()).filter(Boolean)
+    : [""];
+  for (const dir of path.split(delimiter)) {
+    if (dir === "") continue;
+    for (const ext of exts) if (existsSync(join(dir, bin + ext))) return true;
+  }
+  return false;
+}
+/** test seam: forget what was probed (the cache is keyed by PATH, so only a test needs this) */
+export const resetPathProbe = (): void => { probeCache.clear(); };
+
+/** null when `id` may start; otherwise the refusal text `task start` returns (no process is spawned,
+ *  and no worktree is built — both refusals below land before the lane exists). */
+export function laneRefusal(id: AdapterId, env: Env = process.env, probe: PathProbe = onPath): string | null {
+  const allowed = lanesAllowed(env);
+  if (!allowed.has(id)) {
+    // Only reachable when the user wrote a list themselves, so the refusal talks about THEIR list
+    // rather than telling them to opt in to something that is already on by default.
+    const now = allowed.size ? [...allowed].join(",") : "none";
+    return `external lane '${id}' is not in ${LANES_ALLOW_ENV} (currently allowed: ${now}) — add it, or unset ${LANES_ALLOW_ENV} to allow all of ${ADAPTER_IDS.join(",")}`;
+  }
+  const bin = laneBinary(id, env);
+  if (!probe(bin, env)) return `external lane '${id}' needs the '${bin}' CLI, which is not on PATH — install it, or start a different lane (${ADAPTER_IDS.filter((o) => o !== id).join(", ")})`;
+  return null;
+}
+
+/** The sentence a surface states when a lane starts — shown at EVERY permission level, because
+ *  permission=auto shows no approval card and an external CLI beginning work in the user's repo is
+ *  not something to leave implicit. Built from `lanePermissions`, so it names the flags the lane
+ *  actually got rather than a description of them. */
+export function laneStartNote(id: AdapterId, env: Env = process.env, over: Partial<LaneOpts> = {}): string {
+  return `${lanePermissions(id, env, over)} — started; it works in its own worktree and its diff comes back as a patch`;
+}
+
+export function laneTimeoutFromEnv(env: Env = process.env): number {
+  const n = Number(readEnv("LANE_TIMEOUT_MS", env) ?? "");
+  return Number.isInteger(n) && n >= 1_000 ? n : DEFAULT_LANE_TIMEOUT_MS;
+}
+
+/** The options a lane of `id` runs with in `cwd` (its worktree): env knobs, then `over`; cwd always wins. */
+export function laneOptsFor(id: AdapterId, cwd: string, env: Env = process.env, over: Partial<LaneOpts> = {}): LaneOpts {
+  const opts: LaneOpts = { cwd, timeoutMs: laneTimeoutFromEnv(env) };
+  const model = (readEnv(laneModelKnob(id), env) ?? "").trim();
+  if (model) opts.model = model;
+  if (id === "claude") {
+    const raw = readEnv("LANE_CLAUDE_ALLOW", env);
+    if (raw !== undefined) opts.allowlist = raw.split(",").map((s) => s.trim()).filter(Boolean);
+    const bare = readEnv("LANE_CLAUDE_BARE", env);
+    opts.bare = bare === "1" ? true : bare === "0" ? false : (env["ANTHROPIC_API_KEY"] ?? "") !== "";
+    if ((env[CLAUDE_OAUTH_TOKEN_ENV] ?? "") !== "") opts.oauthToken = true;
+  }
+  if (id === "codex") {
+    const sb = readEnv("LANE_CODEX_SANDBOX", env);
+    opts.sandbox = sb === "read-only" ? "read-only" : "workspace-write";
+  }
+  if (id === "agy" && idList(readEnv("LANES_ALLOW_ALL", env)).has("agy")) opts.allowAll = true;
+  return { ...opts, ...over, cwd };
+}
+
+/** The approval-card text for a lane — `spawn codex lane · sandbox workspace-write · approval never · worktree`. */
+export function lanePermissions(id: AdapterId, env: Env = process.env, over: Partial<LaneOpts> = {}): string {
+  return `spawn ${id} lane · ${ADAPTERS[id].permissionSummary(laneOptsFor(id, "<worktree>", env, over))}`;
+}
+
+/** A `task start` args object naming an external lane → its card text; null for every other call. */
+export function laneApprovalText(args: unknown, env: Env = process.env): string | null {
+  if (!isObj(args) || args["action"] !== "start" || !isAdapterId(args["agent"])) return null;
+  return lanePermissions(args["agent"], env);
+}

package/src/lanes/runner.ts

@@ -0,0 +1,124 @@
+/** Lane runner (#47): ONE external CLI process → LaneResult. Spawns through the injected LaneSpawn
+ *  (default lanes/process.ts bunLaneSpawn = the executor's tree-kill path), reads stdout line by line,
+ *  feeds the adapter's parse(), keeps a bounded log ring (the running preview), reports every event to
+ *  the caller, enforces the wall-clock budget, and cancels in the order the CLIs want: SIGINT first for
+ *  the ones that finish their turn on it (claude/opencode), the tree kill after a grace — or at once for
+ *  the others — then the reader is abandoned after ABORT_GRACE_MS so an orphan holding the pipe cannot
+ *  park the job. Every event also folds into the run's counters (lanes/progress.ts) — tool calls, confirmed
+ *  file writes, usage — which ride along with each onEvent so a surface can show what the lane has DONE
+ *  while it is still doing it, not just its last log line. Every timer is cleared on the way out (a pending timer would hold the process; a parked
+ *  promise with no timer hangs the Bun runner). A signal that is ALREADY aborted when the runner is called
+ *  spawns nothing at all (the job awaited its worktree meanwhile; executor.ts bunRunner's pre-aborted pin).
+ *  The verdict: cancelled > timed out > the CLI's own fail/done event > exit-code fallback (≠0 → fail;
+ *  0 without a result event → fail, honestly). */
+
+import { ABORT_GRACE_MS } from "../core/executor.ts";
+import type { TokenUsage } from "../core/types.ts";
+import { addUsage, renderEvent } from "./events.ts";
+import { LaneTally, type LaneProgress } from "./progress.ts";
+import { bunLaneSpawn, type LaneProcess, type LaneSpawn } from "./process.ts";
+import { newParseState, type AgentAdapter, type LaneEvent, type LaneOpts, type LaneResult, type LaneTask } from "./types.ts";
+
+/** rendered event lines kept while a lane runs (the preview + the failure context) */
+export const LOG_RING = 200;
+/** SIGINT → tree kill grace for interruptFirst adapters (docs/test.md §3.6: dead within 5 s) */
+export const INTERRUPT_GRACE_MS = 3_000;
+
+export type KillStep = "interrupt" | "kill" | "abandon";
+
+export interface LaneRunnerDeps {
+  spawn?: LaneSpawn;
+  /** cancel: the TaskManager's per-task controller */
+  signal?: AbortSignal;
+  /** every parsed event, with the current log tail (≤3 lines) and the running counters — what the
+   *  lane has DONE so far (progress.ts), so a surface can show more than one log line */
+  onEvent?: (ev: LaneEvent, tail: readonly string[], progress: LaneProgress) => void;
+  graceMs?: number;
+  /** the kill choreography, appended as it happens (tests pin the order) */
+  steps?: KillStep[];
+}
+
+export class LogRing {
+  private lines: string[] = [];
+  constructor(readonly cap: number) {}
+  push(line: string): void {
+    this.lines.push(line);
+    if (this.lines.length > this.cap) this.lines.splice(0, this.lines.length - this.cap);
+  }
+  tail(n = this.cap): string[] { return this.lines.slice(-n); }
+  get length(): number { return this.lines.length; }
+}
+
+const msg = (e: unknown): string => (e instanceof Error ? e.message : String(e));
+
+export async function runExternalLane(adapter: AgentAdapter, task: LaneTask, opts: LaneOpts, deps: LaneRunnerDeps = {}): Promise<LaneResult> {
+  // cancelled before the spawn (the job was still creating its worktree): nothing starts — executor.ts:110 idiom
+  if (deps.signal?.aborted) return { status: "cancelled", summary: "", error: "cancelled", exitCode: null, log: [], garbage: 0, progress: new LaneTally().snapshot() };
+  const cmd = opts.resume && adapter.resume ? adapter.resume(opts.resume, task.goal, opts) : adapter.command(task, opts);
+  const ring = new LogRing(LOG_RING);
+  const tally = new LaneTally();
+  const st = newParseState();
+  let proc: LaneProcess;
+  try {
+    proc = (deps.spawn ?? bunLaneSpawn)(cmd);
+  } catch (e) {
+    return { status: "failed", summary: "", error: `spawn failed: ${cmd.bin}: ${msg(e)}`, exitCode: null, log: [], garbage: 0, progress: tally.snapshot() };
+  }
+  let done: Extract<LaneEvent, { kind: "done" }> | undefined, fail: Extract<LaneEvent, { kind: "fail" }> | undefined;
+  let usage: TokenUsage | undefined;
+  let timedOut = false, cancelled = false, stopping = false;
+  // every timer lands here and is cleared in finally — so a SIGINT that ends the turn inside the grace
+  // (the runner returns) never fires the pending kill, and no timer outlives the lane
+  const timers = new Set<ReturnType<typeof setTimeout>>();
+  const later = (fn: () => void, ms: number): void => {
+    const t = setTimeout(() => { timers.delete(t); fn(); }, ms);
+    timers.add(t);
+  };
+  const step = (s: KillStep): void => { deps.steps?.push(s); };
+  const killNow = (): void => {
+    step("kill"); proc.kill();
+    later(() => { step("abandon"); proc.abandon(); }, ABORT_GRACE_MS);
+  };
+  const stop = (): void => {
+    if (stopping) return;
+    stopping = true;
+    if (adapter.interruptFirst && proc.interrupt()) { step("interrupt"); later(killNow, deps.graceMs ?? INTERRUPT_GRACE_MS); }
+    else killNow();
+  };
+  const onAbort = (): void => { cancelled = true; stop(); };
+  try {
+    deps.signal?.addEventListener("abort", onAbort, { once: true }); // not aborted: checked above, and the spawn is synchronous
+    later(() => { timedOut = true; stop(); }, Math.max(0, opts.timeoutMs));
+    for await (const raw of proc.lines()) {
+      const line = raw.trimEnd();
+      if (!line) continue;
+      let events: LaneEvent[];
+      try { events = adapter.parse(line, st); } catch { st.garbage++; continue; }
+      for (const ev of events) {
+        ring.push(renderEvent(ev));
+        tally.add(ev); // the counters and the log line come off the SAME event — nothing is parsed twice
+        if (ev.kind === "done") done = ev;
+        else if (ev.kind === "fail") fail = ev;
+        else if (ev.kind === "usage") usage = addUsage(usage, ev.usage);
+        deps.onEvent?.(ev, ring.tail(3), tally.snapshot());
+      }
+    }
+    // EOF: the process is gone or about to be — never wait on it unbounded (an abandoned pipe may
+    // belong to a launcher that is still alive)
+    let waitTimer: ReturnType<typeof setTimeout> | undefined;
+    const code = await Promise.race([proc.exited, new Promise<null>((r) => { waitTimer = setTimeout(() => r(null), ABORT_GRACE_MS); })]);
+    clearTimeout(waitTimer);
+    const sessionId = done?.sessionId ?? fail?.sessionId ?? st.sessionId;
+    const base = { exitCode: code, log: ring.tail(), garbage: st.garbage, progress: tally.snapshot(), ...(usage ? { usage } : {}), ...(sessionId ? { sessionId } : {}) };
+    if (cancelled) return { ...base, status: "cancelled", summary: "", error: "cancelled" };
+    if (timedOut) return { ...base, status: "failed", summary: "", error: `timed out after ${opts.timeoutMs}ms` };
+    if (fail) return { ...base, status: "failed", summary: "", error: fail.error };
+    if (done) return { ...base, status: "done", summary: done.summary || st.lastText || "" };
+    const err = proc.stderrTail();
+    if (code !== 0) return { ...base, status: "failed", summary: "", error: `${cmd.bin} exited with code ${code ?? "?"} without a result${err ? `: ${err.slice(-300)}` : ""}` };
+    return { ...base, status: "failed", summary: "", error: `${cmd.bin} exited 0 without a result event${err ? `: ${err.slice(-300)}` : ""}` };
+  } finally {
+    deps.signal?.removeEventListener("abort", onAbort);
+    for (const t of timers) clearTimeout(t);
+  }
+}

package/src/lanes/types.ts

@@ -0,0 +1,112 @@
+/** External agentic-CLI lanes (port #47): the adapter contract between rovecode's TaskManager and a
+ *  headless coding CLI — claude code, codex, opencode, antigravity (`agy`). Source: the user's own
+ *  notes, sextant docs/agentic-clis.md §1 (adapter = command() + parse() + resume()) and §3 (the
+ *  event → lane mapping table); flags verified against the official docs on 2026-09-02.
+ *  A lane is a JOB of core/tasks.ts (TaskInfo.kind "external"), never a second loop (ADR-003/013):
+ *  the CLI's JSONL stdout becomes LaneEvents, the events become TaskInfo updates, the process rides
+ *  the executor's tree-kill path (lanes/process.ts over core/win-job.ts), and the lane works in its
+ *  OWN git worktree whose diff merges back as a patch — exactly like an isolated child. */
+
+import type { TokenUsage } from "../core/types.ts";
+import type { LaneProgress } from "./progress.ts";
+
+export type AdapterId = "claude" | "codex" | "opencode" | "agy";
+export const ADAPTER_IDS: readonly AdapterId[] = ["claude", "codex", "opencode", "agy"];
+export const isAdapterId = (s: unknown): s is AdapterId =>
+  typeof s === "string" && (ADAPTER_IDS as readonly string[]).includes(s);
+
+export interface LaneTask { goal: string; label?: string }
+
+export interface LaneOpts {
+  /** the lane's working directory — its OWN isolated worktree, never the parent tree */
+  cwd: string;
+  /** claude: `--allowedTools` rules ("Read", "Bash(npm test)"); the other CLIs have no allowlist flag */
+  allowlist?: string[];
+  /** claude: pass `--bare` (the table's CI shape — auth is STRICTLY `ANTHROPIC_API_KEY`; the CLI's own
+   *  login is never read). Default true; the registry sets false when the lane env has no key so the
+   *  lane runs on the CLI's login instead (verified 2026-09-03: `--bare` without a key exits 1 at once,
+   *  `apiKeySource: "none"`; without `--bare` the same CLI reads its OAuth login). */
+  bare?: boolean;
+  /** claude: the lane env carries `CLAUDE_CODE_OAUTH_TOKEN` (`claude setup-token`, the documented headless
+   *  login; the process seam keeps it). Label only — the card's auth word becomes `oauth token` instead of
+   *  `cli login`; under `--bare` the word stays `bare` (`--help`: strictly ANTHROPIC_API_KEY, the token is never read). */
+  oauthToken?: boolean;
+  /** codex: `--sandbox`; default workspace-write (danger-full-access is deliberately not offered) */
+  sandbox?: "read-only" | "workspace-write";
+  /** wall-clock cutter enforced by the runner; agy also receives it as `--print-timeout` */
+  timeoutMs: number;
+  model?: string;
+  /** agy ONLY: an explicit allow-all adds `--dangerously-skip-permissions`; default = the soft-deny path */
+  allowAll?: boolean;
+  /** codex: `-o/--output-last-message` target; default = a file under the OS temp dir */
+  lastMessageFile?: string;
+  /** opencode: `--attach <url>` of a running `opencode serve` */
+  attach?: string;
+  /** continue a previous lane session (`--resume` / `exec resume` / `-s` / `--conversation`) */
+  resume?: string;
+}
+
+export interface LaneCommand { bin: string; args: string[]; env?: Record<string, string>; stdin?: string; cwd: string }
+
+/** The lane DSL (agentic-clis.md §1/§3): what the crew board and the TaskInfo updates consume. */
+export type LaneEvent =
+  | { kind: "log"; text: string }
+  /** `wrote` means the CLI CONFIRMED this write (a tool result, a completed change) — never merely that
+   *  the path appeared in a tool's arguments. lanes/progress.ts counts files on that flag alone. */
+  | { kind: "edit"; path: string; op: "edit" | "write" | "delete"; callId?: string; wrote?: true }
+  | { kind: "bash"; command: string; output?: string; exitCode?: number; callId?: string }
+  /** a tool that is neither a file edit nor a shell command (read, grep, todo, a CLI's own) — kept as a
+   *  COUNTABLE event rather than folded into `log`, so "12 tool calls" includes the twenty greps a lane
+   *  really made instead of silently reading zero */
+  | { kind: "tool"; name: string; detail?: string; callId?: string }
+  | { kind: "ask"; text: string }
+  | { kind: "progress"; text: string }
+  | { kind: "done"; summary: string; sessionId?: string }
+  | { kind: "fail"; error: string; sessionId?: string }
+  | { kind: "usage"; usage: TokenUsage };
+
+export interface LaneParseState {
+  /** lines that were not JSON objects with a `type` — skipped and counted, never thrown */
+  garbage: number;
+  /** the CLI's own session/thread/conversation id, for resume() */
+  sessionId?: string;
+  /** the last agent text seen: the summary fallback when the terminal event carries none */
+  lastText?: string;
+  /** adapter scratch (pending tool ids and their paths, partial text, dedupe keys) */
+  scratch: Record<string, unknown>;
+}
+export const newParseState = (): LaneParseState => ({ garbage: 0, scratch: {} });
+
+export interface AgentAdapter {
+  id: AdapterId;
+  /** SIGINT finishes the current turn for this CLI: the runner interrupts first, kills after a grace */
+  interruptFirst: boolean;
+  /** dry-run-able argv — EXACTLY the flags of agentic-clis.md §2, no process started */
+  command(task: LaneTask, opts: LaneOpts): LaneCommand;
+  /** one stdout line → zero or more lane events; garbage is skipped and counted, never thrown */
+  parse(line: string, st: LaneParseState): LaneEvent[];
+  /** continue the CLI's own session with a follow-up prompt */
+  resume?(sessionId: string, followUp: string, opts: LaneOpts): LaneCommand;
+  /** the lane's OWN permission flags, stated on the approval card BEFORE the lane starts */
+  permissionSummary(opts: LaneOpts): string;
+  /** attached to a `done` whose worktree diff is EMPTY (agy: soft-deny exits 0 having done nothing) */
+  emptyDiffNote?: string;
+}
+
+export interface LaneResult {
+  status: "done" | "failed" | "cancelled";
+  /** what the lane did, folded from its own events (lanes/progress.ts) — present on every outcome,
+   *  including a cancel, because "it made 9 calls and wrote 2 files before you stopped it" is exactly
+   *  what a cancelled lane should still be able to tell you */
+  progress: LaneProgress;
+  /** the CLI's final message (done); empty otherwise */
+  summary: string;
+  error?: string;
+  usage?: TokenUsage;
+  sessionId?: string;
+  /** null = the process had not exited when the runner gave up waiting (abandoned pipe) */
+  exitCode: number | null;
+  /** bounded tail of the rendered event log (runner LOG_RING lines) */
+  log: string[];
+  garbage: number;
+}