pi-harness-delegate 0.4.1 → 0.6.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/pi-harness-delegate?logo=npm&color=CB3837)](https://www.npmjs.com/package/pi-harness-delegate) [![CI](https://github.com/yorch/pi-harness-delegate/actions/workflows/ci.yml/badge.svg)](https://github.com/yorch/pi-harness-delegate/actions/workflows/ci.yml) [![Release](https://github.com/yorch/pi-harness-delegate/actions/workflows/release.yml/badge.svg)](https://github.com/yorch/pi-harness-delegate/actions/workflows/release.yml) [![Node](https://img.shields.io/badge/node-26.x-brightgreen?logo=node.js)](https://nodejs.org) [![Bun](https://img.shields.io/badge/bun-1.3.14-black?logo=bun)](https://bun.sh) [![Biome](https://img.shields.io/badge/Biome-2.5.10-60a5fa)](https://biomejs.dev) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-Delegate work to **any harness** ([Claude Code](https://github.com/anthropics/claude-code), [Muse](https://github.com/openai/codex), [OpenCode](https://opencode.ai), [Amp](https://ampcode.com)) from the [pi coding agent](https://github.com/badlogic/pi-mono): code reviews, detailed plans, implementation, security audits, docs — or your own custom templates.
+Delegate work to **any harness** ([Claude Code](https://github.com/anthropics/claude-code), [Muse](https://github.com/openai/codex), [OpenCode](https://opencode.ai), [Amp](https://ampcode.com), [Devin](https://devin.ai)) from the [pi coding agent](https://github.com/badlogic/pi-mono): code reviews, detailed plans, implementation, security audits, docs — or your own custom templates.
 
 Each harness runs headless in your repo with a normalized permission (`readonly` / `edit` / `danger`). Results stream back live, and token/cost usage feeds into pi's footer stats. Templates are portable — prompt bodies live in `templates/shared/`, harness-specific frontmatter selects the native permission.
 
@@ -16,7 +16,9 @@ pi install npm:pi-harness-delegate
 pi install git:github.com/yorch/pi-harness-delegate
 ```
 
-Requires at least one harness binary on PATH (`claude --version`, `codex --version`, `opencode --version`, `amp --version`). Restart pi (or `/reload`) to activate.
+Requires at least one harness binary on PATH (`claude --version`, `codex --version`, `opencode --version`, `amp --version`, `devin --version`). Restart pi (or `/reload`) to activate.
+
+**Devin setup note:** `devin` refuses to run interactively (`devin`, `devin -p`) in a directory you haven't trusted yet — but this extension runs Devin over `devin acp` (see below), and live testing found that transport is **not** gated by workspace trust in the tested version (`3000.6.7`): a fresh, never-touched directory worked over ACP with no refusal and no prompt. This extension never sets Devin's `skip_workspace_trust` config key on your behalf either way — that stays a decision you make interactively, if you ever need it for `devin` itself.
 
 ## Usage
 
@@ -32,6 +34,7 @@ Manual delegation:
 /claude --mode=security-audit --scope=auth/ …          # alias → delegate --harness=claude
 /opencode plan the cache migration
 /amp implement the caching layer
+/devin review the new auth flow
 ```
 
 Only the prompt is required. A **harness as first word** and/or **mode as next word** selects them; every `--flag` is optional (harness defaults to `delegate.defaultHarness`, mode to `delegate.defaultMode`, scope to whole repo).
@@ -53,6 +56,8 @@ The `delegate` tool takes: `harness`, `task`, `mode`, `scope` (`diff` = git diff
 delegate({ harness: "all", mode: "review", scope: "diff" })   # tool call form
 ```
 
+- `all` resolves against *detected* harnesses, so Devin joins a fan-out automatically once `devin` is installed — a 5-harness fan-out costs more (and runs one more concurrent process) than the 4-harness one did, budget accordingly.
+
 - `all` resolves to whatever's actually installed (`detectAll()`) — an uninstalled harness is skipped and named in the report, it doesn't fail the run. An explicit list is validated the same way; an unknown name is also reported rather than aborting the rest.
 - Each harness's run goes through the same `delegate()` engine as a single-harness call and writes its own transcript to its own `~/.pi/agent/delegate/outputs/<harness>/`. Runs are launched together and execute in parallel, bounded by `maxConcurrent` (default `4`, one slot per supported harness) — a run beyond the cap queues for a free slot instead of failing, and the cap is enforced across pi processes, not just this one. **This means fan-out spend is genuinely simultaneous**: with the default cap, a 4-harness fan-out can bill all four at once instead of one after another — budget accordingly (`maxBudgetUsd` still applies per run).
 - The synthesized report is always ordered by the resolved harness list (e.g. `claude, codex, opencode`), regardless of which harness actually finishes first — it groups each harness's metrics + output and a total spend line (unknown-cost runs called out separately, same as `/delegate status`), assembled mechanically, not by asking a model to summarize.
@@ -76,11 +81,16 @@ delegate({ harness: "all", mode: "review", scope: "diff" })   # tool call form
 | --- | --- | --- | --- |
 | `claude` | `claude` | `readonly→plan`, `edit→acceptEdits`, `danger→bypassPermissions` | Full stream-json, cost + context%. Schema-verified against Claude Code 2.1.247. |
 | `codex` | `codex` | `readonly→read-only`, `edit→workspace-write`, `danger→danger-full-access` | `codex exec --json`. Schema-verified against codex-cli 0.149.1; cost is always unmeasured (`null`) on ChatGPT-plan auth. |
-| `opencode` | `opencode` | `readonly→read-only`, `edit→allow-edit`, `danger→danger` | `opencode run --format json`. Schema-verified against opencode 1.18.16. |
-| `amp` | `amp` (`omp` alias) | `readonly→read-only`, `edit→workspace`, `danger→danger` | `<binary> -p --mode json`, resolves whichever of `amp`/`omp` is actually on `PATH`. Schema-verified against omp 17.2.9 (Sourcegraph's real Amp CLI is unverified). |
+| `opencode` | `opencode` | `readonly→plan`, `edit→build`, `danger→build --auto` | `opencode run --format json` (stdout, default) or `opencode acp` ([ACP](https://agentclientprotocol.com), opt-in via `transport: "acp"` — see Config). Schema-verified against opencode 1.18.16. |
+| `amp` | `amp` (`omp` alias) | `readonly→always-ask`, `edit→write`, `danger→yolo` | `<binary> -p --mode json`, resolves whichever of `amp`/`omp` is actually on `PATH`. Schema-verified against omp 17.2.9 (Sourcegraph's real Amp CLI is unverified). `omp acp` is real but not offered as a `transport` option — its ACP mode surface only has 2 tiers against this CLI's genuine 3. |
+| `devin` | `devin` | `readonly→plan`, `edit→accept-edits`, `danger→bypass` | Runs `devin acp` — [Agent Client Protocol](https://agentclientprotocol.com) over stdio, not stdout JSONL (see `acp-runner.ts`). Real tool-call ids, a genuine context-window %, and a working `sessionId`/resume via `session/load`. Reports no `$` cost (stays `null`) and no turn count. `model` is wired via `devin acp --model <MODEL>` (fuzzy names, e.g. `opus`); the reported `model` is read back from Devin's own `_cognition.ai/agent_stopped` event rather than echoed from the request, so it reflects what actually ran. Schema-verified against `devin 3000.6.7 (260a97c8)`. |
 
 Detect availability: `delegate` checks `harness --version` at startup; missing harnesses hint install instructions.
 
+### Transport
+
+Every harness runs over its native CLI's stdout (`stdout`, the default and only option for `claude`/`codex`/`amp`). `opencode` and `devin` also speak [ACP](https://agentclientprotocol.com) (Agent Client Protocol — bidirectional JSON-RPC over stdio): Devin ships ACP-only (no stdout mode exists), and `opencode` supports both — `stdout` stays the default, `transport: "acp"` is opt-in per harness in config (see below). ACP gives `opencode` a genuine `cost`/`contextWindow` (both `null` over stdout today) and a resume path independently proven to recall cross-process state; the tradeoff is `model`/`numTurns` staying unmeasured (`null`) either way. `amp`/`omp` has a real `acp` subcommand too, but isn't offered as a `transport` value — its ACP mode surface has only 2 permission tiers against the stdout CLI's genuine 3, a real regression, not just an unverified one. Configuring a transport a harness doesn't support fails immediately with a clear error, before anything spawns.
+
 ## Modes (templates)
 
 | Mode | Permission | Purpose |
@@ -112,18 +122,20 @@ You are a senior engineer delegated by the pi coding agent.
 
 - **Sources, deliberately limited:** a verify command can only come from a template's `verify:` frontmatter, or a human typing `/delegate --verify="<cmd>"` (quotes needed for multi-word commands) — the call-level value wins over the template's. **It is not a parameter on the `delegate` tool** — that's on purpose, not an oversight: a tool param is set by the model, and the model's context includes repo content and delegated-harness output, both of which an attacker could influence, so a model-settable verify command would be a prompt-injection → arbitrary-host-command path. A model that wants verification simply picks a template that declares one.
 - **Never runs on a `readonly` template.** `readonly` (`review`/`plan`/`security-audit`) guarantees no execution or modification — a verify command riding along on one would quietly break that guarantee. If a `readonly` template (or override) has a `verify` configured, it's recorded as skipped (`### Verify: \`cmd\`` / `⊘ skipped (readonly run)`) rather than run, and never silently dropped.
-- A project-local template's `verify` command is gated by the same trust check (`PI_TRUSTED=1` / `.pi/trusted`) as the rest of the template.
+- A project-local template's `verify` command is gated by the same project-trust check as the rest of the template.
 
 **Template sources (later wins):**
 
 - `templates/shared/*.md` — portable prompt bodies
 - `templates/<harness>/*.md` — harness-specific frontmatter (built-ins)
 - `~/.pi/agent/delegate/templates/<harness>/<name>.md` (global)
-- `.pi/delegate/templates/<harness>/<name>.md` (project — when trusted)
+- `.pi/delegate/templates/<harness>/<name>.md` (project — only when the project is trusted, see below)
 - Legacy `~/.pi/agent/claude-delegate/templates/` and `.pi/claude-delegate/templates/` still loaded for migration
 
 Custom templates are just files dropped in the above dirs — any registered name becomes a valid `mode`.
 
+**Project trust:** project-local templates (`.pi/delegate/templates/`) load only when pi itself considers the current project trusted (`ctx.isProjectTrusted()`, backed by pi's own trust store outside the project — the same trust that gates other project-scoped behavior). Trust it via pi's own trust prompt (shown the first time you open an untrusted directory) or your `defaultProjectTrust` setting; `/delegate status` reports whether the current project is trusted and, if not, that project-local templates are being skipped. There is **no way to grant trust from inside the project** — no `.pi/trusted` file, no environment variable. Earlier versions supported both (`.pi/trusted` containing `1`, or `PI_TRUSTED=1`/`PI_DELEGATE_TRUSTED=1` in the environment); both were removed as a security fix — a repo could commit `.pi/trusted` and declare itself trusted, letting a cloned hostile repo's templates silently override a builtin (e.g. widening `review` from `readonly` to `edit` and attaching a `verify:` command that runs host-side). If you relied on either, switch to pi's trust prompt or `defaultProjectTrust`.
+
 ## How the main session consumes the output
 
 - **Agent-driven (`delegate` tool)** — report is the tool result, flows into agent context.
@@ -164,16 +176,24 @@ In `~/.pi/agent/settings.json`:
     "harnesses": {
       "claude": { "model": "sonnet" },
       "codex": { "model": "gpt-5" },
-      "opencode": { "model": "opencode-default" }
+      "opencode": { "model": "opencode-default", "transport": "acp" }
     }
   }
 }
 ```
 
-Legacy `claudeDelegate` is auto-migrated into `delegate.harnesses.claude` (deprecated).
+Run `/delegate config` to see exactly what was read from `settings.json` (or why nothing was — no file, no `delegate` key, or a parse error), plus the effective config with defaults filled in, as a paste-ready JSON block for the `delegate` key. `/delegate status` shows the same provenance as one summary line.
+
+`/delegate config init` writes that effective config into `settings.json` under the `delegate` key — the only thing this extension ever writes there, and only on this explicit command. It reads the whole file, replaces only the `delegate` key, and preserves every other key (pi's `theme`/`defaultProvider`/`packages`/…, and a leftover `claudeDelegate`, verbatim). The write is atomic (temp file + rename in the same directory — no torn file if the process dies mid-write) and refuses outright if the existing file fails to parse, rather than clobbering whatever's actually in it; `/delegate config`'s paste-ready block is the fallback in that case.
+
+Legacy `claudeDelegate` is auto-migrated into `delegate.harnesses.claude` (deprecated) — most fields migrate, including per-harness settings like `harnesses.<name>.transport`. Two things never migrate, though, and stay silently unreachable as long as `claudeDelegate` is your *only* key (no `delegate` key at all): `defaultHarness` (stays pinned to `claude`) and a top-level default `model` (only `claudeDelegate.model` → `harnesses.claude.model` migrates — there's no global fallback). Both `/delegate status` and `/delegate config` call this out when it's happening; fix it by renaming `claudeDelegate` to `delegate`, or by running `/delegate config init`, which writes an explicit `delegate` key (with the legacy values already correctly migrated) without touching `claudeDelegate` itself.
+
+Config lives as a key inside pi's own `~/.pi/agent/settings.json` rather than a dedicated file — small enough that this fits comfortably, and pi's extension docs don't prescribe a convention either way for global (as opposed to project-local) preferences. If per-project overrides are ever wanted, pi's documented pattern for extension-owned project config is `.pi/<CONFIG_DIR_NAME>/pi-harness-delegate.json` (gated by project trust); not implemented today.
+
+- `harnesses.<name>.transport` — `"stdout"` (default for every harness except `devin`, which is ACP-only) or `"acp"`. Only legal where the harness actually supports it — see [Transport](#transport) above; an unsupported value fails the run immediately with a clear message rather than being silently ignored or failing at spawn time.
 
 - `modelAliases` — templates may use `economy|balanced|max` or any alias; resolution: call → template → harness → global.
-- `maxConcurrent` — cap overlapping runs (default **`4`**, one slot per supported harness; may be `{global:4, perHarness:{claude:1}}`). Enforced across pi processes, not just the current one — a file-based registry under `~/.pi/agent/delegate/runs/` tracks active runs, so the slots available to you also depend on any other pi session running `delegate`. This is a **genuinely parallel** spend cap now, not just a "don't overlap" guard: a single-harness `/delegate` call still fails fast (`another delegate run is already in progress`) the moment it's at capacity, but `/delegate all …` fan-out queues for a free slot instead and can run up to `maxConcurrent` harnesses at once — meaning up to that many harnesses billing simultaneously. Lower it if you want fan-out to stay sequential/cheaper (`"maxConcurrent": 1` restores the old one-at-a-time behavior for everything, single runs included).
+- `maxConcurrent` — cap overlapping runs (default **`4`**, one slot per supported harness; may be `{global:4, perHarness:{claude:1}}`). Enforced across pi processes, not just the current one — a file-based registry under `~/.pi/agent/delegate/runs/` tracks active runs, so the slots available to you also depend on any other pi session running `delegate`. This is a **genuinely parallel** spend cap now, not just a "don't overlap" guard: a single-harness `/delegate` call still fails fast (`another delegate run is already in progress`) the moment it's at capacity, but `/delegate all …` fan-out queues for a free slot instead and can run up to `maxConcurrent` harnesses at once — meaning up to that many harnesses billing simultaneously. Lower it if you want fan-out to stay sequential/cheaper (`"maxConcurrent": 1` restores the old one-at-a-time behavior for everything, single runs included). `/delegate status` shows each harness's `active` count next to the cap that actually applies to it (e.g. `1/2`), so a `{perHarness: {...}}` override is visible per-row, not just the raw config JSON in the header; the summary line at the bottom shows the same for the global cap.
 - `maxTranscripts` — oldest transcripts pruned beyond this count per harness (`0` disables).
 
 `autoDelegateHints` is off by default — no system-prompt bias. When `true`, explicit markers (`@harness`, `with codex`, `delegate … to claude`) and imperative review/plan phrasing append a hint.
@@ -184,6 +204,8 @@ Every run records in details + transcript: harness, mode, permission (normalized
 
 Claude reports turns and cost on every run; Codex/OpenCode/Amp don't always. An unmeasured turn count or cost renders as `—`/`n/a` (never `0`/`$0.000`) everywhere it's shown — the transcript header, `formatMetrics`, tool results, and `/delegate history` — so an unmeasured run is never mistaken for a free one. `/delegate status` shows a per-harness spend rollup (e.g. `$1.234 over 12 run(s) (3 unknown)`); runs with unknown cost are counted separately rather than folded into the total as `$0`.
 
+One deliberate, narrow exception: pi's own `Usage` (the footer/session token+cost stats) has no way to express "cost unknown" — its `cost.total` field is mandatory. Codex and Devin never report a `$` cost, so treating unknown-cost as unknown-usage there would drop those two harnesses' tokens out of pi's session totals entirely. `mapHarnessUsage`/`mapClaudeUsage` (`extensions/usage.ts`) report the real token counts with `cost.total: 0` in that one case — under-reporting spend by a bounded, knowable amount beats losing 40% of token accounting. This does not change anything above: transcripts, `formatMetrics`, and `/delegate status` still render unmeasured cost as `—`/`n/a`, never `$0`.
+
 ## Security model
 
 - `readonly` — no edits (e.g. Claude `plan`, Codex `read-only`).

package/extensions/acp-runner.ts

@@ -0,0 +1,370 @@
+/**
+ * Sibling to runner.ts for harnesses whose `transport` is `'acp'` (Agent Client Protocol,
+ * https://agentclientprotocol.com — JSON-RPC 2.0, newline-delimited, over stdio). Unlike the
+ * stdout harnesses' one-way JSONL stream, ACP is bidirectional and stateful: the runner must
+ * drive a handshake (`initialize` -> `session/new` -> `session/set_mode` -> `session/prompt`)
+ * and hold stdin open for the session's lifetime — the agent exits on stdin EOF. It must also
+ * answer requests the agent sends back to us (permission prompts, fs reads) so the session
+ * doesn't hang, since we run non-interactively with a permission mode already negotiated.
+ *
+ * Exposes the exact `RunHarnessOptions`/`HarnessResult` shape as runner.ts, so `delegate()`
+ * can pick either runner from the resolved `transport` (see config.ts's `resolveTransport`) and
+ * everything downstream (transcripts, `ToolCallIndex`, progress overlays, fan-out, spend rollup)
+ * is unchanged.
+ *
+ * Deliberately general: an agent's mode ids and result shape live in its `Harness` (`buildArgs`/
+ * `buildAcpArgs`, `permissionMap`/`acpPermissionMap`, `parseLine`/`parseAcpLine`, `extractResult`)
+ * — this file only knows the ACP wire protocol. Callers driving a dual-transport harness over ACP
+ * pass it through `acpView()` (below) first, so this file always reads the stdout-shaped field
+ * names regardless of which harness it's given.
+ */
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { DEFAULT_TIMEOUT_MS, type Harness, type ParseState, type StreamedResult } from './harnesses/types.ts';
+import type { HarnessResult, RunHarnessOptions } from './runner.ts';
+
+/** Bound on the initial handshake (initialize / session/new / session/set_mode) so a hung agent
+ *  doesn't wedge the whole `timeoutMs` budget before `session/prompt` — the actual work — even starts. */
+const HANDSHAKE_TIMEOUT_MS = 30_000;
+
+const PROTOCOL_VERSION = 1;
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/** Presents the ACP-shaped view of a dual-transport `Harness` (buildAcpArgs/parseAcpLine/
+ *  acpPermissionMap) to this file, falling back to the stdout-shaped fields for an ACP-only
+ *  harness like Devin that never declares the Acp-prefixed ones. Devin needs zero changes for
+ *  this — every field below already exists on it under the stdout-shaped name. */
+export function acpView(harness: Harness): Harness {
+  return {
+    ...harness,
+    buildArgs: harness.buildAcpArgs ?? harness.buildArgs,
+    parseLine: harness.parseAcpLine ?? harness.parseLine,
+    permissionMap: harness.acpPermissionMap ?? harness.permissionMap,
+  };
+}
+
+/** Does this `session/new`/`session/load` result advertise support for switching session modes?
+ *  Two independently-real dialects, both live-verified (docs/acp-harness-assessment.md §2/§4):
+ *  the spec-standard `modes` field (Devin, omp), or a `configOptions` entry with `category: "mode"`
+ *  (opencode, which never populates `modes` at all but implements `session/set_mode` anyway). Either
+ *  signal is enough to trust the upcoming `session/set_mode` call. */
+function supportsSessionModes(sessionResult: unknown): boolean {
+  if (!isRecord(sessionResult)) return false;
+  if (isRecord(sessionResult.modes)) return true;
+  if (Array.isArray(sessionResult.configOptions)) {
+    return sessionResult.configOptions.some(o => isRecord(o) && o.category === 'mode');
+  }
+  return false;
+}
+
+interface PendingRequest {
+  resolve: (result: unknown) => void;
+  reject: (err: Error) => void;
+  timer?: ReturnType<typeof setTimeout>;
+}
+
+export function runAcpHarness(opts: RunHarnessOptions): Promise<HarnessResult> {
+  return new Promise((resolve, reject) => {
+    const args = opts.harness.buildArgs({
+      prompt: opts.prompt,
+      cwd: opts.cwd,
+      permission: opts.permission,
+      nativePermission: opts.nativePermission,
+      model: opts.model,
+      maxBudgetUsd: opts.maxBudgetUsd,
+      addDirs: opts.addDirs,
+      resumeSessionId: opts.resumeSessionId,
+    });
+
+    const proc = spawn(opts.harness.binary, args, { cwd: opts.cwd, stdio: ['pipe', 'pipe', 'pipe'] });
+
+    const state: ParseState = { streamedText: '', activities: [], result: null, _harness: {} };
+    let stderr = '';
+    let settled = false;
+    let firstTokenAt: number | null = null;
+    // Resumed sessions replay every prior turn as session/update notifications before the new
+    // prompt's — set once session/prompt is actually sent, so replayed text/activities (and a
+    // replay-skewed TTFT) never reach the caller. See the handshake IIFE below.
+    let promptSent = false;
+    const startAt = Date.now();
+    const MAX_STREAMED = 5 * 1024 * 1024; // 5MB cap to prevent OOM on compromised harness
+    const MAX_ACTIVITIES = 5000;
+
+    let nextId = 1;
+    const pending = new Map<number, PendingRequest>();
+
+    const finish = (r: StreamedResult) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      rejectAllPending(new Error('session ended'));
+      const ttft = firstTokenAt !== null ? firstTokenAt - startAt : r.ttftMs;
+      resolve({ ...r, ttftMs: ttft, streamedText: state.streamedText, harness: opts.harness.name });
+    };
+    const fail = (err: Error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      rejectAllPending(err);
+      reject(err);
+    };
+    function rejectAllPending(err: Error): void {
+      for (const p of pending.values()) {
+        clearTimeout(p.timer);
+        p.reject(err);
+      }
+      pending.clear();
+    }
+
+    const writeLine = (msg: Record<string, unknown>): void => {
+      try {
+        proc.stdin.write(`${JSON.stringify(msg)}\n`);
+      } catch {
+        // stdin already closed (process exiting) — the pending request(s) time out/reject normally.
+      }
+    };
+
+    /** Send a JSON-RPC request and await its response. `timeoutMs` bounds only this request —
+     *  distinct from the overall run timeout — so a hung handshake step fails fast and clearly.
+     *  Omitted for `session/prompt`: that's the actual work, already bounded by the overall
+     *  `timer` below, which kills the process and rejects every pending request on fire. */
+    const sendRequest = (method: string, params: unknown, timeoutMs?: number): Promise<unknown> => {
+      const id = nextId++;
+      return new Promise((res, rej) => {
+        const entry: PendingRequest = { resolve: res, reject: rej };
+        if (timeoutMs !== undefined) {
+          entry.timer = setTimeout(() => {
+            pending.delete(id);
+            rej(new Error(`${method} timed out after ${timeoutMs}ms`));
+          }, timeoutMs);
+        }
+        pending.set(id, entry);
+        writeLine({ jsonrpc: '2.0', id, method, params });
+      });
+    };
+
+    /** Respond to a request the agent sent to us. Every request needs a reply or the agent's
+     *  session hangs waiting for it. */
+    const respond = (id: unknown, result: unknown): void => writeLine({ jsonrpc: '2.0', id, result });
+    const respondError = (id: unknown, message: string): void =>
+      writeLine({ jsonrpc: '2.0', id, error: { code: -32601, message } });
+
+    /** Handle a request FROM the agent (has both `method` and `id`). We run non-interactively
+     *  with a permission mode already negotiated, so the safe default is to decline anything
+     *  not already covered by that mode rather than auto-approve — never observed in the captured
+     *  fixture this harness was built from, but handled defensively since the spec allows it. */
+    const handleServerRequest = (msg: Record<string, unknown>): void => {
+      const { id, method, params } = msg;
+      if (method === 'session/request_permission' && isRecord(params) && Array.isArray(params.options)) {
+        const options = params.options as Array<{ optionId?: unknown; kind?: unknown }>;
+        const reject =
+          options.find(o => o.kind === 'reject_once') ??
+          options.find(o => o.kind === 'reject_always') ??
+          options.find(o => typeof o.kind === 'string' && o.kind.startsWith('reject'));
+        if (reject && typeof reject.optionId === 'string') {
+          respond(id, { outcome: { outcome: 'selected', optionId: reject.optionId } });
+        } else {
+          respond(id, { outcome: { outcome: 'cancelled' } });
+        }
+        return;
+      }
+      // fs/read_text_file, fs/write_text_file, terminal/* etc. — we declare no client capabilities
+      // for these in `initialize`, so a well-behaved agent shouldn't ask; decline defensively if one does.
+      respondError(id, `${String(method)} not supported by this client`);
+    };
+
+    const rl = createInterface({ input: proc.stdout });
+    rl.on('line', line => {
+      let msg: unknown;
+      try {
+        msg = JSON.parse(line);
+      } catch {
+        return;
+      }
+      if (!isRecord(msg)) return;
+
+      if (typeof msg.method === 'string' && msg.id !== undefined) {
+        handleServerRequest(msg);
+        return;
+      }
+      if (msg.id !== undefined && 'result' in msg) {
+        const entry = pending.get(msg.id as number);
+        if (entry) {
+          pending.delete(msg.id as number);
+          clearTimeout(entry.timer);
+          entry.resolve(msg.result);
+        }
+        // still fall through: `harness.parseLine` may also want to extract activity/result data.
+      } else if (msg.id !== undefined && 'error' in msg) {
+        const entry = pending.get(msg.id as number);
+        if (entry) {
+          pending.delete(msg.id as number);
+          clearTimeout(entry.timer);
+          const err = isRecord(msg.error) ? msg.error : {};
+          entry.reject(new Error(typeof err.message === 'string' ? err.message : `${msg.id} failed`));
+        }
+        return;
+      }
+
+      const outcome = opts.harness.parseLine(line, state);
+      // Discard streamed text/activities from anything that arrives before the new session/prompt
+      // is sent — on a resume that's the replayed prior conversation, not the new turn's own output.
+      if (promptSent && outcome.streamedText) {
+        if (firstTokenAt === null) firstTokenAt = Date.now();
+        if (state.streamedText.length < MAX_STREAMED) {
+          const remaining = MAX_STREAMED - state.streamedText.length;
+          const chunk =
+            outcome.streamedText.length > remaining
+              ? `${outcome.streamedText.slice(0, remaining)} [truncated ${outcome.streamedText.length - remaining} chars]`
+              : outcome.streamedText;
+          state.streamedText += chunk;
+          opts.onStream?.(chunk);
+        }
+      }
+      if (promptSent && outcome.activities) {
+        for (const a of outcome.activities) {
+          if (state.activities.length < MAX_ACTIVITIES) {
+            state.activities.push(a);
+            opts.onActivity?.(a);
+          }
+        }
+      }
+      if (outcome.result) {
+        if (!outcome.result.result) outcome.result.result = state.streamedText;
+        state.result = outcome.result;
+      }
+    });
+
+    proc.stderr.on('data', (d: Buffer) => (stderr += d.toString()));
+    proc.on('close', code => {
+      rejectAllPending(new Error(`${opts.harness.binary} exited`));
+      if (code !== 0 && !state.result) {
+        fail(new Error(stderr.trim() || `${opts.harness.binary} exited with code ${code}`));
+        return;
+      }
+      const final = state.result ?? opts.harness.extractResult(state);
+      if (final) {
+        if (!final.result) final.result = state.streamedText;
+        finish(final);
+      } else if (code !== 0) {
+        fail(new Error(stderr.trim() || `${opts.harness.binary} exited with code ${code}`));
+      } else {
+        fail(new Error(`${opts.harness.binary} finished without emitting a result`));
+      }
+    });
+    proc.on('error', err => {
+      fail(new Error(`failed to start ${opts.harness.binary}: ${err.message}`));
+    });
+
+    const timer = setTimeout(() => {
+      proc.kill('SIGKILL');
+      fail(new Error(`${opts.harness.binary} timed out after ${opts.timeoutMs ?? DEFAULT_TIMEOUT_MS}ms`));
+    }, opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    timer.unref?.();
+
+    opts.signal?.addEventListener(
+      'abort',
+      () => {
+        proc.kill('SIGKILL');
+        fail(new Error('cancelled'));
+      },
+      { once: true },
+    );
+
+    // Drive the handshake. `session/prompt` has no separate timeout — it's the actual work,
+    // bounded by the overall `timer` above like everything else.
+    (async () => {
+      const modeId = opts.nativePermission ?? opts.harness.permissionMap?.[opts.permission]?.[0] ?? opts.permission;
+      const initResult = await sendRequest(
+        'initialize',
+        {
+          protocolVersion: PROTOCOL_VERSION,
+          clientCapabilities: {}, // no fs/terminal proxying — decline those requests if asked (see handleServerRequest)
+        },
+        HANDSHAKE_TIMEOUT_MS,
+      );
+      if (settled) return;
+      // The client "should disconnect" (spec text) if the agent didn't echo back the version we
+      // asked for — only `1` has ever shipped, so this is cheap insurance against a future
+      // version-mismatched agent producing a confusing mid-handshake failure instead of a clear one.
+      const negotiatedVersion = isRecord(initResult) ? initResult.protocolVersion : undefined;
+      if (negotiatedVersion !== PROTOCOL_VERSION) {
+        throw new Error(
+          `${opts.harness.binary} negotiated ACP protocolVersion ${JSON.stringify(negotiatedVersion)}, expected ${PROTOCOL_VERSION}`,
+        );
+      }
+      const sessionParams = {
+        cwd: opts.cwd,
+        mcpServers: [],
+        ...(opts.addDirs && opts.addDirs.length > 0 ? { additionalDirectories: opts.addDirs } : {}),
+      };
+      // `session/load` resumes a prior session by id (its response carries no sessionId of its
+      // own — the client already has it) and replays prior turns as session/update notifications
+      // before the new prompt's; `session/new` mints a fresh one. Verified live: loadSession is
+      // advertised in agentCapabilities and a real session/load + follow-up prompt round-trips
+      // cleanly, replaying history and continuing the same token-usage accounting.
+      let sessionId: string | null;
+      let sessionResult: unknown;
+      if (opts.resumeSessionId) {
+        sessionResult = await sendRequest(
+          'session/load',
+          { sessionId: opts.resumeSessionId, ...sessionParams },
+          HANDSHAKE_TIMEOUT_MS,
+        );
+        sessionId = opts.resumeSessionId;
+      } else {
+        sessionResult = await sendRequest('session/new', sessionParams, HANDSHAKE_TIMEOUT_MS);
+        sessionId =
+          isRecord(sessionResult) && typeof sessionResult.sessionId === 'string' ? sessionResult.sessionId : null;
+      }
+      if (settled) return;
+      if (!sessionId) throw new Error('session/new did not return a sessionId');
+      // session/load's response carries no sessionId of its own (unlike session/new's) — stash it
+      // so the harness's parseLine can still report the real session id on the final result.
+      if (opts.resumeSessionId) {
+        state._harness ??= {};
+        state._harness.sessionId = sessionId;
+      }
+      // `session/set_mode` (and `NewSessionResponse.modes`) are spec-optional — calling it
+      // unconditionally against a mode-less agent would fail the whole handshake with a raw
+      // "method not found" instead of a clear message. Every agent this project has captured
+      // (Devin, opencode, omp) does support it, so this never fires for a real run today — but per
+      // the brief, a mode we can't confirm is a hard error, not a silent downgrade to whatever the
+      // agent's default permissiveness happens to be: we already promised the caller a specific
+      // permission tier.
+      if (!supportsSessionModes(sessionResult)) {
+        throw new Error(
+          `${opts.harness.binary} does not advertise session-mode support (no "modes" field or ` +
+            `configOptions "mode" category on session/${opts.resumeSessionId ? 'load' : 'new'}) — ` +
+            `cannot verify the "${opts.permission}" permission tier would be honored over ACP`,
+        );
+      }
+      await sendRequest('session/set_mode', { sessionId, modeId }, HANDSHAKE_TIMEOUT_MS);
+      if (settled) return;
+      promptSent = true;
+      await sendRequest('session/prompt', { sessionId, prompt: [{ type: 'text', text: opts.prompt }] });
+      if (settled) return;
+      // The agent doesn't exit on its own once the turn is done — an ACP session can outlive a
+      // single prompt (resume, follow-up turns). `delegate()` is one-shot per process, so finish
+      // as soon as the prompt response resolves (parseLine already turned it into state.result,
+      // synchronously, before this await's continuation runs) and tear the process down ourselves.
+      const final = state.result ?? opts.harness.extractResult(state);
+      if (final) {
+        if (!final.result) final.result = state.streamedText;
+        finish(final);
+      } else {
+        fail(new Error(`${opts.harness.binary} session/prompt completed without emitting a result`));
+      }
+      proc.kill('SIGKILL');
+    })().catch(err => {
+      // Every other exit path (timeout, abort, success) kills the child — a rejected handshake
+      // step (bad modeId, a JSON-RPC error, a HANDSHAKE_TIMEOUT_MS expiry) must too, or the
+      // process leaks: ACP agents only exit on stdin EOF, which nothing else here sends.
+      proc.kill('SIGKILL');
+      fail(err instanceof Error ? err : new Error(String(err)));
+    });
+  });
+}

package/extensions/command.ts

@@ -92,6 +92,27 @@ export function isFanoutSpec(harness: string | undefined): boolean {
   return lower === 'all' || lower.includes(',');
 }
 
+export type HarnessFilterResolution =
+  | { kind: 'none' } // no filter word given
+  | { kind: 'known'; harness: string } // resolved to its canonical name (aliases/case normalized)
+  | { kind: 'unknown'; requested: string }; // word given, but not a known harness or alias
+
+/**
+ * Resolve a single optional harness-filter word — as used by `/delegate list`/`history`'s bare
+ * word or `--harness=` flag — to its canonical name via `aliasOf`, case-insensitively, so `omp`,
+ * `OMP`, and `amp` all filter identically. Pure and shared by both subcommands so they can't drift
+ * on alias/case handling the way they once did.
+ */
+export function resolveHarnessFilter(
+  word: string | undefined,
+  opts: { isKnown: (name: string) => boolean; aliasOf: (name: string) => string },
+): HarnessFilterResolution {
+  if (!word) return { kind: 'none' };
+  const lower = word.toLowerCase();
+  if (!opts.isKnown(lower)) return { kind: 'unknown', requested: word };
+  return { kind: 'known', harness: opts.aliasOf(lower) };
+}
+
 export interface HarnessListResolution {
   /** Canonical harness names to run, in request order, deduped. */
   resolved: string[];

package/extensions/concurrency.ts

@@ -11,7 +11,7 @@
  */
 
 import { type DelegateConfig, getMaxConcurrent } from './config.ts';
-import { acquireRun, countActiveRuns, releaseRun } from './run-registry.ts';
+import { acquireRunWithinLimits, countActiveRuns, releaseRun } from './run-registry.ts';
 
 const activeRuns = new Map<string, number>();
 let globalActiveRuns = 0;
@@ -70,7 +70,11 @@ function sleep(ms: number, signal?: AbortSignal): Promise<void> {
  * never throws) once a slot is held; the caller must call it exactly once when the run finishes.
  *
  * Checks the global limit before the per-harness limit — same precedence and error text as the
- * original inline guard, so single-run (`wait: false`) callers see unchanged behavior.
+ * original inline guard, so single-run (`wait: false`) callers see unchanged behavior. Those two
+ * checks are still a plain (racy) read, kept as a cheap fail-fast/error-message step; the actual
+ * grant is `acquireRunWithinLimits()` (run-registry.ts), which re-verifies after registering so a
+ * race lost between the check here and the write there is caught — see its doc comment. Losing
+ * that race is handled exactly like losing the check above: throw (wait:false) or poll (wait:true).
  */
 export async function acquireSlot(opts: AcquireSlotOptions): Promise<() => void> {
   const { harness, mode, config, wait, signal, pollIntervalMs = 200 } = opts;
@@ -91,9 +95,18 @@ export async function acquireSlot(opts: AcquireSlotOptions): Promise<() => void>
       continue;
     }
 
+    const claim = acquireRunWithinLimits(harness, mode, maxGlobal, perHarnessLimit);
+    if (claim.status === 'full') {
+      // the check above passed, but another racer's write landed first and used up the slot —
+      // handled exactly like hitting the cap on the check itself.
+      if (!wait) throw new ConcurrencyLimitError(`another delegate run claimed the last available slot for ${harness}`);
+      await sleep(pollIntervalMs, signal);
+      continue;
+    }
+
     activeRuns.set(harness, perHarnessCount + 1);
     globalActiveRuns++;
-    const runHandle = acquireRun(harness, mode);
+    const runHandle = claim.status === 'acquired' ? claim.handle : null;
     let released = false;
     return () => {
       if (released) return;