pi-harness-delegate 0.4.1 → 0.6.0

package/extensions/config.ts

@@ -1,13 +1,20 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
-import { DEFAULT_TIMEOUT_MS } from './harnesses/types.ts';
+import { dirname, join } from 'node:path';
+import { DEFAULT_TIMEOUT_MS, type Harness, type Transport } from './harnesses/types.ts';
 
 export interface HarnessConfig {
   model?: string;
   timeoutMs?: number;
   allowDangerous?: boolean;
   maxBudgetUsd?: number;
+  /** Overrides the harness's default transport ('stdout' unless the harness itself defaults to
+   *  'acp', e.g. Devin). A malformed value (not 'stdout'/'acp') is dropped at load time, same as
+   *  every other per-harness field's defensive parsing below; a well-formed but unsupported value
+   *  (e.g. 'acp' for a harness with no ACP surface) is *not* dropped here — it's validated against
+   *  `Harness.supportsTransports` by `resolveTransport()` instead, so misconfiguring it fails the
+   *  run with a clear message rather than being silently ignored. */
+  transport?: Transport;
 }
 
 export interface DelegateConfig {
@@ -25,6 +32,36 @@ export interface DelegateConfig {
   harnesses: Record<string, HarnessConfig>;
 }
 
+/**
+ * Provenance for how `loadConfig()` actually resolved its settings — the bit a bare `try/catch {}`
+ * used to erase entirely, making "no file", "file, no relevant key", and "file, unparseable" all
+ * look identical (empty defaults, no signal anywhere). `usedKey` is which key ended up populating
+ * `cfg`: `'delegate'` and `'claudeDelegate'` are mutually exclusive (the legacy branch only runs
+ * when `delegate` is *absent*), so `'claudeDelegate'` here means the legacy-only case that costs
+ * the user every setting under `delegate` — not "legacy key present at all" (see
+ * `legacyKeyPresent` for that). `raw` is the literal value of whichever key was used, exactly as
+ * read from the file — no defaults merged in, no per-field sanitizing — so `/delegate config` can
+ * show what was actually written next to what it resolved to.
+ */
+export interface ConfigSource {
+  file: string;
+  fileExists: boolean;
+  /** Set when the file exists but `JSON.parse` failed, or the parsed value isn't a JSON object
+   *  (e.g. an array or a bare string) — either way `cfg` fell back to defaults. */
+  parseError?: string;
+  usedKey: 'delegate' | 'claudeDelegate' | 'none';
+  /** Whether a `claudeDelegate` key exists in the file at all, independent of `usedKey` — true
+   *  even when `delegate` won and `claudeDelegate` was only partially merged (the `model`
+   *  fallback below). */
+  legacyKeyPresent: boolean;
+  raw?: unknown;
+}
+
+export interface ConfigLoadResult {
+  config: DelegateConfig;
+  source: ConfigSource;
+}
+
 export function agentDir(): string {
   return process.env.PI_CODING_AGENT_DIR ?? join(homedir(), '.pi', 'agent');
 }
@@ -38,7 +75,24 @@ export function legacyOutputsDir(): string {
   return join(agentDir(), 'claude-delegate', 'outputs');
 }
 
-export function loadConfig(): DelegateConfig {
+/** Drops a malformed `transport` (anything but 'stdout'/'acp', including absent) before it's
+ *  stored — the rest of `HarnessConfig`'s fields are spread through as-is by `loadConfig()`. */
+function sanitizeHarnessConfig(v: HarnessConfig): HarnessConfig {
+  const out = { ...v };
+  if (out.transport !== 'stdout' && out.transport !== 'acp') delete out.transport;
+  return out;
+}
+
+/**
+ * Loads `delegate` config from `~/.pi/agent/settings.json` alongside `ConfigSource`, describing
+ * how that happened (file present? which key won? did it fail to parse?) — see `ConfigSource`'s
+ * doc comment. `loadConfig()` below is a thin wrapper for the existing call sites that only want
+ * the resolved values; this is the one place that actually reads/parses the file, so a caller
+ * needing both never pays for a second parse. Never throws — any failure (missing file, bad JSON,
+ * a non-object root) is recorded on `source` and falls back to the same defaults `loadConfig()`
+ * has always returned.
+ */
+export function loadConfigWithSource(): ConfigLoadResult {
   const cfg: DelegateConfig = {
     timeoutMs: DEFAULT_TIMEOUT_MS,
     defaultMode: 'general',
@@ -51,15 +105,31 @@ export function loadConfig(): DelegateConfig {
     maxTranscripts: 100,
     harnesses: {},
   };
+  const file = join(agentDir(), 'settings.json');
+  const source: ConfigSource = { file, fileExists: false, usedKey: 'none', legacyKeyPresent: false };
   try {
-    const file = join(agentDir(), 'settings.json');
-    if (!existsSync(file)) return cfg;
-    const settings = JSON.parse(readFileSync(file, 'utf8')) as {
+    if (!existsSync(file)) return { config: cfg, source };
+    source.fileExists = true;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(readFileSync(file, 'utf8'));
+    } catch (err) {
+      source.parseError = err instanceof Error ? err.message : String(err);
+      return { config: cfg, source };
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      source.parseError = 'settings.json root is not a JSON object';
+      return { config: cfg, source };
+    }
+    const settings = parsed as {
       delegate?: Partial<DelegateConfig & { harnesses: Record<string, HarnessConfig> }>;
       claudeDelegate?: Partial<DelegateConfig & { model?: string }>;
     };
+    source.legacyKeyPresent = Boolean(settings.claudeDelegate);
     // Legacy claudeDelegate -> delegate.harnesses.claude migration
     if (settings.claudeDelegate && !settings.delegate) {
+      source.usedKey = 'claudeDelegate';
+      source.raw = settings.claudeDelegate;
       const c = settings.claudeDelegate as Partial<DelegateConfig>;
       if (typeof c.model === 'string') cfg.harnesses.claude = { ...(cfg.harnesses.claude ?? {}), model: c.model };
       if (typeof c.timeoutMs === 'number' && c.timeoutMs > 0) cfg.timeoutMs = c.timeoutMs;
@@ -92,12 +162,15 @@ export function loadConfig(): DelegateConfig {
       if (typeof c.maxTranscripts === 'number' && c.maxTranscripts >= 0) cfg.maxTranscripts = c.maxTranscripts;
       if (c.harnesses && typeof c.harnesses === 'object') {
         for (const [k, v] of Object.entries(c.harnesses)) {
-          if (v && typeof v === 'object') cfg.harnesses[k] = { ...(cfg.harnesses[k] ?? {}), ...(v as HarnessConfig) };
+          if (v && typeof v === 'object')
+            cfg.harnesses[k] = { ...(cfg.harnesses[k] ?? {}), ...sanitizeHarnessConfig(v as HarnessConfig) };
         }
       }
       // also map harnesses.claude if any
-      return cfg;
+      return { config: cfg, source };
     }
+    source.usedKey = settings.delegate ? 'delegate' : 'none';
+    source.raw = settings.delegate;
     const d = settings.delegate ?? {};
     if (typeof d.defaultHarness === 'string' && d.defaultHarness) cfg.defaultHarness = d.defaultHarness;
     if (typeof d.defaultMode === 'string') cfg.defaultMode = d.defaultMode;
@@ -129,7 +202,7 @@ export function loadConfig(): DelegateConfig {
     if (typeof d.maxTranscripts === 'number' && d.maxTranscripts >= 0) cfg.maxTranscripts = d.maxTranscripts;
     if (d.harnesses && typeof d.harnesses === 'object') {
       for (const [k, v] of Object.entries(d.harnesses)) {
-        if (v && typeof v === 'object') cfg.harnesses[k] = { ...(v as HarnessConfig) };
+        if (v && typeof v === 'object') cfg.harnesses[k] = sanitizeHarnessConfig(v as HarnessConfig);
       }
     }
     // also support legacy claudeDelegate merged when delegate also present (delegate wins)
@@ -139,10 +212,121 @@ export function loadConfig(): DelegateConfig {
         cfg.harnesses.claude = { ...(cfg.harnesses.claude ?? {}), model: c.model };
       }
     }
-  } catch {
-    // invalid settings — fall back to defaults
+  } catch (err) {
+    // Anything unexpected (e.g. a read error after existsSync's check raced a delete) — still
+    // never throw; record it as a parse error so it's not silently indistinguishable from "no
+    // config" if it wasn't already caught (and thus reported) above.
+    if (!source.parseError) source.parseError = err instanceof Error ? err.message : String(err);
+  }
+  return { config: cfg, source };
+}
+
+export function loadConfig(): DelegateConfig {
+  return loadConfigWithSource().config;
+}
+
+/**
+ * Human-readable lines describing how `loadConfig()` actually resolved its settings — the
+ * provenance report used by both `/delegate status` and `/delegate config`. Pure: takes the
+ * `ConfigSource` companion to `loadConfigWithSource()`'s result, no I/O, so it's testable without
+ * touching the filesystem.
+ */
+export function describeConfigSource(source: ConfigSource): string[] {
+  if (source.parseError) {
+    return [
+      `⚠ ${source.file} exists but failed to parse: ${source.parseError}`,
+      '  using defaults until this is fixed',
+    ];
+  }
+  if (!source.fileExists) {
+    return [`${source.file} not found — using defaults`];
+  }
+  if (source.usedKey === 'none') {
+    return [`${source.file} has no "delegate" key — using defaults`];
+  }
+  if (source.usedKey === 'claudeDelegate') {
+    return [
+      `⚠ using legacy "claudeDelegate" key in ${source.file}`,
+      '  two settings can never be reached this way: "defaultHarness" stays pinned to "claude", and there\'s no',
+      '  top-level default "model" (only claudeDelegate.model -> harnesses.claude.model migrates) — everything',
+      '  else (including per-harness settings like harnesses.<name>.transport) migrates fine',
+      '  rename "claudeDelegate" to "delegate" to unlock those two, or run `/delegate config init` to write an',
+      '  explicit "delegate" key for you (claudeDelegate itself is left untouched either way)',
+    ];
+  }
+  const lines = [`"delegate" key in ${source.file}`];
+  if (source.legacyKeyPresent) {
+    lines.push('  legacy "claudeDelegate" key is also present — ignored except claudeDelegate.model as a fallback');
+  }
+  return lines;
+}
+
+/**
+ * Full `/delegate config` report: provenance (`describeConfigSource`), the raw `delegate`/
+ * `claudeDelegate` value exactly as written in the file, and the effective config with defaults
+ * merged in — so a user can see both what they wrote and what it resolved to, and has a
+ * paste-ready starting point either way. Pure — takes an already-loaded `ConfigLoadResult`.
+ */
+export function buildConfigReport(result: ConfigLoadResult): string[] {
+  const lines = [...describeConfigSource(result.source)];
+  lines.push('');
+  lines.push('from file (as written, before defaults are applied):');
+  lines.push(JSON.stringify(result.source.raw ?? {}, null, 2));
+  lines.push('');
+  lines.push('effective config (file merged with defaults) — paste under "delegate" in settings.json,');
+  lines.push('or run `/delegate config init` to write it there directly:');
+  lines.push(JSON.stringify({ delegate: result.config }, null, 2));
+  return lines;
+}
+
+export interface WriteConfigResult {
+  ok: boolean;
+  file: string;
+  message: string;
+}
+
+/**
+ * Writes `delegateSubtree` into `settings.json` under the `delegate` key — replacing only that
+ * key and preserving every other top-level key verbatim (including a leftover `claudeDelegate`,
+ * which is never touched or removed here; that's the user's call, made by editing the file
+ * themselves). Read-modify-write, atomic: writes to `<file>.<pid>.tmp` in the same directory then
+ * `renameSync`s over the target, so a process death mid-write can never leave a torn file. Refuses
+ * to write (returns `ok: false`, file untouched) when the existing file is present but fails to
+ * parse or isn't a JSON object — overwriting an already-broken file would destroy whatever the
+ * user has in it; the caller should fall back to `buildConfigReport`'s paste-ready block instead.
+ * Never throws. Only ever called from an explicit user action (`/delegate config init`) — never
+ * on the strength of a read like `loadConfig()`/`showStatus`.
+ */
+export function writeDelegateConfig(delegateSubtree: unknown): WriteConfigResult {
+  const file = join(agentDir(), 'settings.json');
+  try {
+    let root: Record<string, unknown> = {};
+    if (existsSync(file)) {
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(readFileSync(file, 'utf8'));
+      } catch (err) {
+        return {
+          ok: false,
+          file,
+          message: `refusing to write: ${file} exists but failed to parse (${err instanceof Error ? err.message : String(err)}) — fix or remove it first`,
+        };
+      }
+      if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return { ok: false, file, message: `refusing to write: ${file} exists but its root isn't a JSON object` };
+      }
+      root = parsed as Record<string, unknown>;
+    }
+    root.delegate = delegateSubtree;
+    const dir = dirname(file);
+    mkdirSync(dir, { recursive: true });
+    const tmp = join(dir, `settings.json.${process.pid}.tmp`);
+    writeFileSync(tmp, `${JSON.stringify(root, null, 2)}\n`, 'utf8');
+    renameSync(tmp, file);
+    return { ok: true, file, message: `wrote "delegate" key to ${file}` };
+  } catch (err) {
+    return { ok: false, file, message: `failed to write ${file}: ${err instanceof Error ? err.message : String(err)}` };
   }
-  return cfg;
 }
 
 export function resolveModelForHarness(
@@ -155,6 +339,25 @@ export function resolveModelForHarness(
   return resolve(model) ?? resolve(templateModel) ?? resolve(cfg.harnesses[harness]?.model) ?? resolve(cfg.model);
 }
 
+/**
+ * Which transport a run should actually use: config override, falling back to the harness's own
+ * default (`harness.transport`, e.g. Devin's static 'acp'), falling back to 'stdout'. Validated
+ * against `harness.supportsTransports` — the ceiling of what the binary can actually do, distinct
+ * from what's configured — *before* the caller acquires a run slot or spawns anything, so
+ * misconfiguring e.g. `transport: 'acp'` for `claude` fails fast with a clear message instead of a
+ * cryptic "unknown subcommand" from the spawned process. See docs/acp-harness-assessment.md §5/§6.
+ */
+export function resolveTransport(cfg: DelegateConfig, harnessName: string, harness: Harness): Transport {
+  const transport = cfg.harnesses[harnessName]?.transport ?? harness.transport ?? 'stdout';
+  const allowed = harness.supportsTransports ?? [harness.transport ?? 'stdout'];
+  if (!allowed.includes(transport)) {
+    throw new Error(
+      `delegate.harnesses.${harnessName}.transport is "${transport}", but ${harnessName} only supports: ${allowed.join(', ')}`,
+    );
+  }
+  return transport;
+}
+
 export function getMaxConcurrent(cfg: DelegateConfig, harness?: string): number {
   if (typeof cfg.maxConcurrent === 'number') return cfg.maxConcurrent;
   // if object shape {global, perHarness}

package/extensions/harnesses/amp.ts

@@ -159,14 +159,22 @@ export function parseAmpLine(line: string, state: ParseState): ParseOutcome {
         ? (o.messages[o.messages.length - 1] as Record<string, unknown>)
         : null;
     const measured = (hs.turnCount ?? 0) > 0;
+    // real error shape: message.stopReason === 'error' + message.errorMessage — observed live on a
+    // 429 quota rejection, where message.content is an empty array, so the text-block extraction
+    // above never sets streamedText and this would otherwise silently report success with empty
+    // text (tests/fixtures/amp-error.jsonl).
+    const errorMessage = typeof msg?.errorMessage === 'string' ? (msg.errorMessage as string) : undefined;
+    const isErrorTurn = msg?.stopReason === 'error' || errorMessage !== undefined;
     const result: StreamedResult = {
       result:
         typeof o.result === 'string'
           ? o.result
-          : streamedText
-            ? state.streamedText + streamedText
-            : state.streamedText || (text ?? ''),
-      isError: o.is_error === true,
+          : errorMessage
+            ? errorMessage
+            : streamedText
+              ? state.streamedText + streamedText
+              : state.streamedText || (text ?? ''),
+      isError: o.is_error === true || isErrorTurn,
       numTurns: measured ? (hs.turnCount as number) : null,
       totalCostUsd: measured ? (hs.costAccum as number) : null,
       sessionId:
@@ -228,6 +236,9 @@ export const ampHarness: Harness = {
     const args = ['-p', '--mode', 'json', '--approval-mode', approvalMode];
     if (opts.model) args.push('--model', opts.model);
     if (opts.resumeSessionId) args.push('--resume', opts.resumeSessionId);
+    // `--add-dir=<value>` is real and repeatable per `omp --help` — confirmed live: a run with
+    // --add-dir echoed the directory back in the session line's `additionalDirectories`. (Earlier
+    // research had flagged this as possibly absent; that was wrong for omp 17.2.9.)
     for (const dir of opts.addDirs ?? []) args.push('--add-dir', dir);
     args.push(opts.prompt);
     return args;
@@ -259,4 +270,13 @@ export const ampHarness: Harness = {
     return null;
   },
   permissionMap: { readonly: ['always-ask'], edit: ['write'], danger: ['yolo'] },
+  // `omp acp` is real and live-verified (docs/acp-harness-assessment.md §2/§4) — but deliberately
+  // NOT offered as a config value yet: its ACP mode surface only has 2 tiers (`default`/`plan`),
+  // while the stdout `--approval-mode` above has 3 genuine ones. Adding 'acp' here would let a
+  // user configure `edit`, expecting "ask before every write", and silently collapse it onto the
+  // same `default` mode as `danger` — a real permission-tier regression, not a cosmetic one. Only
+  // revisit if a future omp ACP version exposes a third tier (e.g. an `approval-mode`-shaped
+  // `configOptions` category, the same slot `thinking` already occupies today) — redo the §4-style
+  // live permission-tier analysis before changing this, don't just add 'acp' to the list.
+  supportsTransports: ['stdout'],
 };

package/extensions/harnesses/claude.ts

@@ -156,4 +156,7 @@ export const claudeHarness: Harness = {
     edit: ['acceptEdits'],
     danger: ['bypassPermissions'],
   },
+  // No `acp` subcommand exists (docs/acp-harness-assessment.md §2) — confirmed against the full
+  // `claude --help` output, not just an earlier probe.
+  supportsTransports: ['stdout'],
 };

package/extensions/harnesses/codex.ts

@@ -14,6 +14,11 @@ import type {
 // non-interactive; sandbox alone governs what's allowed) and resume is a subcommand
 // (`exec resume <id> <prompt>`), not a `--thread-id` flag — both confirmed via `codex exec
 // --help` / `codex exec resume --help`, not just the JSONL capture.
+//
+// Resume itself live-verified end-to-end against codex-cli 0.150.1 — see
+// tests/fixtures/codex-resume.jsonl: a first `codex exec` turn was taught a fact, then a second,
+// independent process ran `codex exec resume <id> <prompt>` and correctly recalled it, proving
+// resume genuinely restores prior context rather than just replaying/echoing the session id.
 
 const execFileAsync = promisify(execFile);
 function isRecord(v: unknown): v is Record<string, unknown> {
@@ -245,7 +250,10 @@ export const codexHarness: Harness = {
       ? ['exec', 'resume', opts.resumeSessionId, opts.prompt, '--json']
       : ['exec', '--json', opts.prompt, '--sandbox', sandbox];
     if (opts.model) args.push('--model', opts.model);
-    for (const dir of opts.addDirs ?? []) args.push('--add-dir', dir);
+    // `codex exec resume --help` has no `--sandbox`/`--add-dir` at all (confirmed live: passing
+    // --add-dir to resume is a hard CLI error, "unexpected argument '--add-dir' found") — only the
+    // fresh-turn branch above supports either flag.
+    if (!opts.resumeSessionId) for (const dir of opts.addDirs ?? []) args.push('--add-dir', dir);
     return args;
   },
   parseLine(line: string, state: ParseState): ParseOutcome {
@@ -275,4 +283,8 @@ export const codexHarness: Harness = {
     return null;
   },
   permissionMap: { readonly: ['read-only'], edit: ['workspace-write'], danger: ['danger-full-access'] },
+  // No `acp` subcommand exists; `app-server` is a different, codex-proprietary JSON-RPC protocol,
+  // not ACP (docs/acp-harness-assessment.md §2) — confirmed against the full `--help` output of
+  // `codex`, `codex mcp-server`, `codex app-server`, and `codex exec`.
+  supportsTransports: ['stdout'],
 };

package/extensions/harnesses/devin.ts

@@ -0,0 +1,208 @@
+/**
+ * Devin — runs over the Agent Client Protocol (`devin acp`), not stdout JSONL. `transport: 'acp'`
+ * routes it through extensions/acp-runner.ts instead of runner.ts; `buildArgs` here only needs to
+ * spawn the ACP server (`devin acp`) — the prompt, permission mode, and session lifecycle are all
+ * negotiated over the wire by acp-runner.ts, not passed as CLI flags.
+ *
+ * `parseLine`/`extractResult` translate raw ACP JSON-RPC lines (one per line, same as any other
+ * harness's JSONL) into `ParseOutcome`/`StreamedResult` — this is what makes the JSON-RPC plumbing
+ * testable via the same fixture-replay pattern as the stdout harnesses (tests/fixtures.test.ts),
+ * without spawning a process: `tests/fixtures/devin-acp.jsonl` is a real captured session.
+ *
+ * Schema verified against `devin 3000.6.7 (260a97c8)` — see docs/devin-acp-harness-design.md.
+ *
+ * Workspace trust: the design note this was built from flagged `devin`'s interactive workspace-trust
+ * gate as a hazard needing a `detect()` hint. Live verification found that gate applies to `devin -p`
+ * / interactive `devin`, but NOT to `devin acp` — confirmed by running the raw `initialize`/`session/new`
+ * handshake against a directory never seen by devin before (no `--config` bypass), which succeeded with
+ * no refusal, while `devin -p` in the same directory refused. So this harness's actual code path was
+ * never gated in the first place; no hint or bypass is needed. If a future devin version starts
+ * enforcing trust over ACP too, the generic non-zero-exit path in acp-runner.ts already surfaces
+ * whatever refusal message devin prints, same as any other process failure.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import type {
+  ActivityEvent,
+  BuildArgsOpts,
+  Harness,
+  NormalizedPermission,
+  ParseOutcome,
+  ParseState,
+  StreamedResult,
+} from './types.ts';
+
+const execFileAsync = promisify(execFile);
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/** Exact structural match to Claude's tiers (session/new's captured `availableModes`: plan, accept-edits,
+ *  smart, ask, bypass). `smart`/`ask` stay reachable via the existing `nativePermission` escape hatch. */
+const PERMISSION_MAP: Record<NormalizedPermission, string> = {
+  readonly: 'plan',
+  edit: 'accept-edits',
+  danger: 'bypass',
+};
+
+/** Translate one `session/update` notification's `params.update` payload into ParseOutcome deltas. */
+function translateUpdate(update: Record<string, unknown>, state: ParseState): ParseOutcome {
+  const activities: ActivityEvent[] = [];
+  let streamedText: string | undefined;
+  const content = isRecord(update.content) ? update.content : undefined;
+  const text = content?.type === 'text' && typeof content.text === 'string' ? content.text : undefined;
+
+  switch (update.sessionUpdate) {
+    case 'agent_message_chunk':
+      if (text !== undefined) streamedText = text;
+      break;
+    case 'agent_thought_chunk':
+      if (text !== undefined) activities.push({ kind: 'thinking', chars: text.length });
+      break;
+    case 'tool_call': {
+      if (typeof update.toolCallId !== 'string') break;
+      const meta = isRecord(update._meta) ? update._meta : {};
+      const inferenceName = meta['cognition.ai/inferenceToolName'];
+      const name =
+        typeof inferenceName === 'string' ? inferenceName : typeof update.kind === 'string' ? update.kind : 'tool';
+      activities.push({
+        kind: 'tool_input',
+        name,
+        input: isRecord(update.rawInput) ? update.rawInput : {},
+        id: update.toolCallId,
+      });
+      break;
+    }
+    case 'tool_call_update': {
+      // Only a terminal status produces a tool_result. A call fires multiple `in_progress`
+      // updates for the same toolCallId before its `completed`/`failed` (real fixture: 2-3 per
+      // id) — ToolCallIndex.resolve() consumes the pending entry on first match, so an earlier
+      // in_progress "result" would eat the id and strand the real completion unattributed.
+      if (typeof update.toolCallId !== 'string') break;
+      if (update.status === 'completed' || update.status === 'failed') {
+        activities.push({ kind: 'tool_result', isError: update.status === 'failed', id: update.toolCallId });
+      }
+      break;
+    }
+    case 'usage_update':
+      state._harness ??= {};
+      if (typeof update.size === 'number') state._harness.contextWindow = update.size;
+      break;
+    default:
+      break;
+  }
+  return { streamedText, activities };
+}
+
+export function parseDevinLine(line: string, state: ParseState): ParseOutcome {
+  let o: unknown;
+  try {
+    o = JSON.parse(line);
+  } catch {
+    return {};
+  }
+  if (!isRecord(o)) return {};
+
+  if (o.method === 'session/update' && isRecord(o.params) && isRecord(o.params.update)) {
+    return translateUpdate(o.params.update, state);
+  }
+
+  if (o.method === '_cognition.ai/agent_stopped' && isRecord(o.params) && isRecord(o.params.stats)) {
+    // The real model Devin ran, independent of whatever --model was requested — the honest
+    // value to report, since `--model` accepts fuzzy names and enterprise config can override it.
+    const label = o.params.stats.modelLabel;
+    if (typeof label === 'string') {
+      state._harness ??= {};
+      state._harness.model = label;
+    }
+    return {};
+  }
+
+  if (isRecord(o.result)) {
+    const r = o.result;
+    if (typeof r.stopReason === 'string') {
+      // session/prompt response — the turn is over, build the final result.
+      const u = isRecord(r.usage) ? r.usage : null;
+      const harnessState = isRecord(state._harness) ? state._harness : {};
+      // Devin's inputTokens already includes cachedReadTokens as a subset (fixture: on every
+      // usage_update/prompt result, used === inputTokens + outputTokens exactly, and
+      // cachedReadTokens < inputTokens). StreamedUsage follows Claude's convention where
+      // inputTokens EXCLUDES cache reads (index.ts sums inputTokens + cacheReadInputTokens into
+      // promptTokens) — so subtract the cache-read subset back out here, or promptTokens/context%
+      // double-counts it. Math.max guards against a negative if that invariant ever breaks.
+      const cacheReadInputTokens = typeof u?.cachedReadTokens === 'number' ? u.cachedReadTokens : 0;
+      const rawInputTokens = typeof u?.inputTokens === 'number' ? u.inputTokens : 0;
+      const result: StreamedResult = {
+        result: state.streamedText,
+        // Devin's ACP prompt response carries no error flag of its own — a genuine failure
+        // (JSON-RPC `error`, non-zero exit, workspace-trust refusal) surfaces via acp-runner.ts's
+        // process-level fail() path instead, same as every other harness's non-zero-exit case.
+        isError: false,
+        numTurns: null, // not reported for a single prompt turn
+        totalCostUsd: null, // Devin reports no $ cost over ACP — honest-metrics convention (#11)
+        sessionId: typeof harnessState.sessionId === 'string' ? harnessState.sessionId : null,
+        stopReason: r.stopReason,
+        permissionDenials: [],
+        durationMs: null,
+        durationApiMs: null,
+        ttftMs: null,
+        model: typeof harnessState.model === 'string' ? harnessState.model : null,
+        contextWindow: typeof harnessState.contextWindow === 'number' ? harnessState.contextWindow : null,
+        maxOutputTokens: null,
+        usage: u
+          ? {
+              inputTokens: Math.max(0, rawInputTokens - cacheReadInputTokens),
+              outputTokens: typeof u.outputTokens === 'number' ? u.outputTokens : 0,
+              cacheCreationInputTokens: 0, // not reported over ACP
+              cacheReadInputTokens,
+            }
+          : null,
+      };
+      return { result };
+    }
+    if (typeof r.sessionId === 'string') {
+      // session/new response — stash the id; the prompt response above has no sessionId of its own.
+      state._harness ??= {};
+      state._harness.sessionId = r.sessionId;
+    }
+  }
+  return {};
+}
+
+export const devinHarness: Harness = {
+  name: 'devin',
+  displayName: 'Devin',
+  binary: 'devin',
+  transport: 'acp',
+  async detect() {
+    try {
+      const { stdout } = await execFileAsync('devin', ['--version'], { timeout: 5000 });
+      return { ok: true, version: stdout.trim() };
+    } catch {
+      return { ok: false, hint: 'Install the Devin CLI: https://docs.devin.ai/' };
+    }
+  },
+  buildArgs(opts: BuildArgsOpts): string[] {
+    // The prompt, permission mode, and session lifecycle are all negotiated over the ACP wire
+    // (see acp-runner.ts) — this just launches the ACP server. `--model` is the one real CLI flag
+    // `devin acp` accepts (verified: `devin acp --help`); it sets the default model for every new
+    // ACP session on this server, and accepts fuzzy names (family slug, alias, or partial name).
+    const args = ['acp'];
+    if (opts.model) args.push('--model', opts.model);
+    return args;
+  },
+  parseLine(line: string, state: ParseState): ParseOutcome {
+    return parseDevinLine(line, state);
+  },
+  extractResult(state: ParseState): StreamedResult | null {
+    return state.result;
+  },
+  permissionMap: {
+    readonly: [PERMISSION_MAP.readonly],
+    edit: [PERMISSION_MAP.edit],
+    danger: [PERMISSION_MAP.danger],
+  },
+  // ACP-only — no stdout mode exists to select between, so there's nothing to configure.
+  supportsTransports: ['acp'],
+};