pi-harness-delegate 0.6.2 → 0.7.1

package/README.md

@@ -39,10 +39,38 @@ Manual delegation:
 
 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).
 
+| Flag | Meaning |
+| --- | --- |
+| `--harness=<name>` | `claude`, `codex`, `opencode`, `amp` (`omp`), `devin`, `all`, or a comma list (fan-out, below) |
+| `--mode=<template>` | Any template name (`review`, `plan`, `implement`, `security-audit`, `docs`, `general`, or your own) |
+| `--model=<model>` | Model or alias (`economy`/`balanced`/`max`, see `modelAliases`) |
+| `--scope=<scope>` | `diff` (current `git diff HEAD`), `pr` (`gh pr diff` for the current branch), or a path list |
+| `--pr=<pr>` | A specific PR to scope to: a number, an http(s) PR URL (`https://<host>/<owner>/<repo>/pull/<n>`, no `user@`), or `owner/repo#123` (implies the PR diff as scope) |
+| `--budget=<usd>` | Per-run spend cap in USD (same as the tool's `maxBudgetUsd`) |
+| `--add-dir=<path>` | Extra directory the harness may access; repeatable (`--add-dir=../shared --add-dir=/opt/lib`) |
+| `--resume=<session-id>` | Continue a previous delegated session (single harness only — not with a fan-out) |
+| `--verify="<cmd>"` | Host-run check after the harness exits (see [Verify](#modes-templates)) |
+| `--allow-dangerous` | Run this one invocation with `danger` (unrestricted) permission — required for a `permission: danger` template, and escalates any other template to `danger`. Always asks you to confirm first (one prompt for a whole fan-out); refused in a non-interactive session. Never read from config. `--allow-dangerous=true` also works; any other value is off. See [Security model](#security-model) |
+
+Extra directories (`--add-dir`, the tool's `addDirs`, and template `addDirs:`) are merged, resolved against the working directory, and passed as each harness's native option where one exists: `--add-dir` for `claude`, `codex` (fresh runs only — `codex exec resume` has no such flag), and `amp`/`omp`; `additionalDirectories` on the ACP session for `devin`/`opencode` over ACP. `opencode run` (stdout) has no equivalent, so they're ignored there. On the `delegate` **tool**, `addDirs` entries that resolve (after `..` and symlinks) outside the working directory ask you to confirm interactively and are refused in a non-interactive session — the model alone can't widen a run to arbitrary host paths. Template `addDirs:` and `/delegate --add-dir` (both set by you) are not gated.
+
+Flag values may be quoted (`--verify="bun test && bun run lint"`). `--resume`, `--model`, and `--pr` values are validated before anything runs — e.g. a value starting with `-` is rejected, so it can never be smuggled into a harness's command line as a flag.
+
+**Subcommands** (work on `/delegate` and on every alias, where the alias pins the harness filter):
+
+| Subcommand | What it does |
+| --- | --- |
+| `/delegate list [harness]` | Available modes/templates (all harnesses, or one) |
+| `/delegate history [harness]` (alias `logs`) | Past transcripts, newest first; open one to read it (and see its resume hint) |
+| `/delegate status [harness]` (aliases `health`, `doctor`, `check`) | Config provenance, project trust, per-harness detection/version/templates/active-vs-cap, spend rollup |
+| `/delegate config` | What was read from `settings.json` and the effective config (print-only) |
+| `/delegate config init` | Write the effective config into `settings.json`'s `delegate` key (the only write this extension does) |
+| `/delegate watch` (alias `show`) | Re-open a minimized progress overlay |
+
 Some modes have **default tasks** when the prompt is omitted:
 `/delegate review` reviews the current git diff (`scope: diff`), `/delegate security-audit` audits the repo. Modes without a default (`plan`, `implement`, `docs`, `general`) print a hint asking for a prompt.
 
-The `delegate` tool takes: `harness`, `task`, `mode`, `scope` (`diff` = git diff, `pr` = PR diff, path list, or whole repo), `model`, `maxBudgetUsd`, `allowDangerous`, `sessionId`, `pr`. (`verify` is deliberately *not* a tool parameter — see below.)
+The `delegate` tool takes: `harness`, `task`, `mode`, `scope` (`diff` = git diff, `pr` = PR diff, path list, or whole repo), `model`, `maxBudgetUsd`, `allowDangerous`, `sessionId`, `pr`, `addDirs`. (`verify` is deliberately *not* a tool parameter — see below.) Setting `allowDangerous` from the tool always asks you to confirm interactively, and is refused outright in a non-interactive session — see [Security model](#security-model).
 
 `claude_delegate` remains as a deprecated alias for `delegate{harness:claude}`.
 
@@ -56,10 +84,9 @@ 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).
+- `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. With all five harnesses installed, `all` means five runs.
+- 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`) — a run beyond the cap queues for a free slot instead of failing (so a 5-harness `all` runs four at once and the fifth when a slot frees), and the cap is enforced across pi processes, not just this one. **This means fan-out spend is genuinely simultaneous**: up to `maxConcurrent` harnesses can bill at once instead of one after another — budget accordingly (`maxBudgetUsd` still applies per run, not to the fan-out as a whole).
+- `--resume`/`sessionId` can't be combined with a fan-out — a session id belongs to exactly one harness — and is rejected up front with a message saying so.
 - 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.
 - A single-harness call (`harness: "claude"`, or omitted) behaves exactly as before, including the concurrency guard: it still fails fast with "another delegate run is already in progress" at capacity rather than queueing. Fan-out is opt-in by typing `all`/a list.
 - `/delegate all …` batches successful completions into one notification instead of one per harness; a failure is never delayed or folded into the batch — it surfaces immediately.
@@ -89,7 +116,7 @@ Detect availability: `delegate` checks `harness --version` at startup; missing h
 
 ### 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.
+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 `contextWindow` (`null` over stdout) and a server-side running cost total (stdout reports cost too, summed from each step's `step_finish` — `null` only if no step reported one), plus 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)
 
@@ -116,6 +143,23 @@ You are a senior engineer delegated by the pi coding agent.
 ...
 ```
 
+All frontmatter keys (one `key: value` per line; only `name` is required):
+
+| Key | Meaning |
+| --- | --- |
+| `name` | The mode name used to select it (`--mode=`/`mode`) |
+| `description` | Shown by `/delegate list` |
+| `permission` | `readonly` \| `edit` \| `danger` (default `edit`). Any other value is treated as a native permission string |
+| `permissionMode` / `sandbox` | Legacy/native escape hatch (see below) |
+| `model` | Default model for this mode (call → template → harness → global) |
+| `maxBudgetUsd` | Default per-run spend cap in USD (a call's `maxBudgetUsd`/`--budget` wins) |
+| `skill` | Appends `Use the "<skill>" skill.` to the prompt |
+| `defaultTask` | Task used when the prompt is omitted (e.g. `review` → review the current diff) |
+| `defaultScope` | Scope used with `defaultTask` (e.g. `diff`) |
+| `verify` | Host-run check command (see below) |
+| `addDirs` | Comma-separated extra directories the harness may access (merged with the call's `addDirs`/`--add-dir`) |
+| `harness` | Informational: which harness a template targets (shown by `/delegate list`) |
+
 **Native escape hatch:** if you need a harness-specific permission not covered by the normalized set, use the native key (`permissionMode: dontAsk`, `sandbox: ...`) — it overrides `permission` for that harness.
 
 **Verify:** `verify` is a shell command run **on the host** (never handed to the harness) right after it exits — e.g. `verify: bun test` on an `implement`/`docs`/`general` template turns "the harness says it's done" into an actual pass/fail. It's report-only: a failing verify is appended as its own section in the transcript and injected report, and surfaced in the tool result's `details.verify` (`{command, exitCode, ok}`), but it never changes whether the run itself is reported as an error — that stays whatever the harness reported. No template ships one by default — there's no universally-correct check command, so nothing is invented for you.
@@ -144,7 +188,7 @@ Custom templates are just files dropped in the above dirs — any registered nam
 ## Inspecting what the harness is doing
 
 - **Live activity feed** — `▶ Bash: ... ✓/✗`, `💭 thinking…`, text tail. `/delegate` shows a framed progress window (spinner, `danger` banner for `danger` permission, `esc`×2 cancels, `m` minimizes, `watch` re-opens).
-- **Full transcript every run** — `~/.pi/agent/delegate/outputs/<harness>/<ts>-<mode>.md` (also legacy `claude-delegate/outputs/` for claude). Tool result ends with path.
+- **Full transcript every run** — `~/.pi/agent/delegate/outputs/<harness>/<ts>-<mode>.md` (also legacy `claude-delegate/outputs/` for claude). Tool result ends with path. Transcripts contain your prompts, diffs, and the harness's full output, so they're written owner-only (directory `0700`, files `0600`).
 - **Resume:** every run records a session id.
 
 ```bash
@@ -157,7 +201,7 @@ Reveal thinking live with `"inspectThinking": true` in config (off by default).
 
 ## Config
 
-In `~/.pi/agent/settings.json`:
+In `~/.pi/agent/settings.json` (or `$PI_CODING_AGENT_DIR/settings.json` — `PI_CODING_AGENT_DIR`, pi's own agent-dir override, relocates everything this extension keeps under `~/.pi/agent`: settings, user templates, transcripts, and the active-run registry):
 
 ```json
 {
@@ -198,6 +242,14 @@ Config lives as a key inside pi's own `~/.pi/agent/settings.json` rather than a
 
 `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.
 
+### Budgets (`maxBudgetUsd` / `--budget`)
+
+A per-run cap, resolved call → template → global config → per-harness config. How it's enforced depends on the harness, and the outcome is always recorded (tool result `details.budget`, a `- budget:` line in the transcript):
+
+- **Native** — `claude` gets `--max-budget-usd` and enforces it itself.
+- **Host-enforced (best-effort)** — harnesses with no budget flag that *do* stream a running cost (`opencode`, `amp`/`omp`, and `opencode` over ACP): the host checks the reported total each time the harness reports one and kills the run once it's over the cap, recording `budget exceeded` (`stopReason: budget_exceeded`, a `⛔ budget exceeded … run stopped` line at the top of the result, `(host-enforced, best-effort)` in the transcript). This is **not a hard cap**: cost is only visible at the step/turn boundaries the harness reports, so spend already incurred within the step that crossed the line can't be prevented — a run can overshoot by up to one step/turn (more if a single step is expensive). Use a native-budget harness (`claude`) when the cap must be strict. For `opencode` over ACP the reported cost is a session running total, so on a resumed session only the spend since this run started counts against the cap, and the reported cost is just this run's share — or `—` (unmeasured) when the session didn't report its prior total before the new prompt, rather than an under-count.
+- **Not enforceable** — `codex` (no `$` cost on ChatGPT-plan auth) and `devin` report no cost and have no flag, so a budget can't be applied; the run proceeds and the result starts with `⚠ maxBudgetUsd … was not enforced`, never silently.
+
 ## Metrics recorded
 
 Every run records in details + transcript: harness, mode, permission (normalized + native), cost, tokens (input/output/cache), context% (prompt ÷ window), model, turns, duration, TTFT, stop reason, session id. Token + cost feed pi's `Usage`.
@@ -210,7 +262,11 @@ One deliberate, narrow exception: pi's own `Usage` (the footer/session token+cos
 
 - `readonly` — no edits (e.g. Claude `plan`, Codex `read-only`).
 - `edit` — workspace writes auto-accepted (e.g. `acceptEdits`, `workspace-write`).
-- `danger` — unrestricted, **only via `allowDangerous:true` on the call** — never a default. Shows `⚠ danger` banner. `review`/`plan`/`security-audit` templates stay `readonly`.
+- `danger` — unrestricted, **only via an explicit per-call opt-in** — `allowDangerous:true` on the tool, or `--allow-dangerous` on `/delegate` — never a default (and never from config). Shows `⚠ danger` banner. `review`/`plan`/`security-audit` templates stay `readonly`.
+- When the **model** sets `allowDangerous: true` on the `delegate` tool, the extension asks you to confirm it (`Allow dangerous delegation?`) before anything runs; declining aborts the call, and in a non-interactive session (no UI to ask) it is refused outright. The model alone can never grant `danger`.
+- `/delegate --allow-dangerous` (and the `/claude`, `/codex`, … aliases) is the human-typed counterpart: it also asks you to confirm (`Allow dangerous delegation?`, naming the harness(es), mode, and that it runs with full, unrestricted permissions) — a fan-out gets one prompt covering every harness — and a decline runs nothing. In a non-interactive session it is refused outright, since there's no one to confirm with. It applies to that invocation only.
+- Likewise, when the **model** passes `addDirs` on the `delegate` tool, entries that resolve (after `..` and symlinks) outside the working directory need your interactive confirmation (`Allow access outside the project?`) and are refused in a non-interactive session. Entries inside the working directory, template `addDirs:`, and `/delegate --add-dir` are not gated.
+- Values that end up on a harness's command line (`sessionId`/`--resume`, `model`, `pr`) are validated first — notably, nothing starting with `-` is accepted, so a prompt-injected value can't masquerade as a CLI flag.
 
 Review what the harness is asked to do before granting broad permissions.
 

package/extensions/acp-runner.ts

@@ -21,7 +21,14 @@
 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';
+import {
+  budgetStoppedResult,
+  type HarnessResult,
+  isCostOverBudget,
+  isOverBudget,
+  type RunHarnessOptions,
+} from './runner.ts';
+import { appendActivities, appendStreamed } from './stream-caps.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. */
@@ -60,14 +67,78 @@ function supportsSessionModes(sessionResult: unknown): boolean {
   return false;
 }
 
+/**
+ * The cost to report for *this* run of a session whose harness reports a session-cumulative running
+ * total (opencode over ACP: `usage_update.cost.amount`). On a fresh session that total is this run's
+ * spend as-is. On a resume it also includes every prior turn — reporting it unchanged would make
+ * `/delegate status`'s spend rollup count those turns again on every resume — so the delta since
+ * `baselineUsd` (the same baseline the host budget check uses; see `costBaseline` in
+ * `runAcpHarness`) is reported instead.
+ *
+ * When the baseline wasn't replayed before the prompt (`baselineFromReplay: false`) it is the first
+ * running total seen *after* the prompt, so any delta silently omits that first step's spend — an
+ * under-report that looks measured (with one sample it's even a fake "$0"). That case is reported
+ * as `null` (unmeasured), per the honest-metrics convention. The host budget check still uses that
+ * first-sample baseline on purpose (biased toward never killing a resumed run for prior turns'
+ * spend); only the *reported* figure refuses to guess. Pure.
+ */
+export function resumedRunCost(opts: {
+  totalCostUsd: number | null;
+  resumed: boolean;
+  baselineUsd: number | undefined;
+  baselineFromReplay: boolean;
+  postPromptCostSamples: number;
+}): number | null {
+  const { totalCostUsd, resumed, baselineUsd, baselineFromReplay, postPromptCostSamples } = opts;
+  if (!resumed || totalCostUsd === null) return totalCostUsd;
+  // no cost reported during this run at all — whatever total we hold is prior turns' spend
+  if (baselineUsd === undefined || postPromptCostSamples === 0) return null;
+  // baseline is this run's own first sample: the true spend is unknowable, not "the delta"
+  if (!baselineFromReplay) return null;
+  return Math.max(0, totalCostUsd - baselineUsd);
+}
+
+/** Placeholder for a run the host stops mid-turn before the harness produced anything result-shaped. */
+function emptyResult(): StreamedResult {
+  return {
+    result: '',
+    isError: false,
+    numTurns: null,
+    totalCostUsd: null,
+    sessionId: null,
+    stopReason: null,
+    permissionDenials: [],
+    durationMs: null,
+    durationApiMs: null,
+    ttftMs: null,
+    model: null,
+    contextWindow: null,
+    maxOutputTokens: null,
+    usage: null,
+  };
+}
+
 interface PendingRequest {
   resolve: (result: unknown) => void;
   reject: (err: Error) => void;
   timer?: ReturnType<typeof setTimeout>;
 }
 
-export function runAcpHarness(opts: RunHarnessOptions): Promise<HarnessResult> {
+/** Test-only knobs — production callers pass only `opts`. */
+export interface AcpRunnerInternals {
+  /** Overrides `HANDSHAKE_TIMEOUT_MS` so a hung-handshake test doesn't take 30s. */
+  handshakeTimeoutMs?: number;
+}
+
+export function runAcpHarness(opts: RunHarnessOptions, internals: AcpRunnerInternals = {}): Promise<HarnessResult> {
+  const handshakeTimeoutMs = internals.handshakeTimeoutMs ?? HANDSHAKE_TIMEOUT_MS;
   return new Promise((resolve, reject) => {
+    // Already cancelled (e.g. the user hit cancel while this run was still being set up) —
+    // never spawn a process just to kill it.
+    if (opts.signal?.aborted) {
+      reject(new Error('cancelled'));
+      return;
+    }
     const args = opts.harness.buildArgs({
       prompt: opts.prompt,
       cwd: opts.cwd,
@@ -80,6 +151,10 @@ export function runAcpHarness(opts: RunHarnessOptions): Promise<HarnessResult> {
     });
 
     const proc = spawn(opts.harness.binary, args, { cwd: opts.cwd, stdio: ['pipe', 'pipe', 'pipe'] });
+    // A write to a child that already exited surfaces as an async EPIPE 'error' on stdin — not as a
+    // throw from write() (writeLine's try/catch can't see it). Unhandled, that event would crash the
+    // host process; the run itself already ends through the 'close'/timeout/abort paths.
+    proc.stdin.on('error', () => {});
 
     const state: ParseState = { streamedText: '', activities: [], result: null, _harness: {} };
     let stderr = '';
@@ -89,25 +164,48 @@ export function runAcpHarness(opts: RunHarnessOptions): Promise<HarnessResult> {
     // 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;
+    // Host budget accounting. opencode's ACP `usage_update.cost` is a *session* running total, so
+    // on a resume it already includes every prior turn — `costBaseline` is what the session had
+    // spent before this run's prompt, and only the delta counts against `maxBudgetUsd`. A fresh
+    // session starts at 0. On a resume it's the last cost replayed before the prompt (if any), else
+    // the first cost seen after it — which under-counts that first step, a deliberate bias toward
+    // never killing a resumed run for spend it didn't incur.
+    let prePromptCost: number | undefined;
+    let costBaseline: number | undefined;
+    let postPromptCostSamples = 0;
     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) => {
+    const finish = (r: StreamedResult, budgetExceeded = false) => {
       if (settled) return;
       settled = true;
       clearTimeout(timer);
+      opts.signal?.removeEventListener('abort', onAbort);
       rejectAllPending(new Error('session ended'));
       const ttft = firstTokenAt !== null ? firstTokenAt - startAt : r.ttftMs;
-      resolve({ ...r, ttftMs: ttft, streamedText: state.streamedText, harness: opts.harness.name });
+      resolve({
+        ...r,
+        // a resumed session's running total includes prior turns — report only this run's share
+        totalCostUsd: resumedRunCost({
+          totalCostUsd: r.totalCostUsd,
+          resumed: Boolean(opts.resumeSessionId),
+          baselineUsd: costBaseline,
+          baselineFromReplay: prePromptCost !== undefined,
+          postPromptCostSamples,
+        }),
+        ttftMs: ttft,
+        streamedText: state.streamedText,
+        harness: opts.harness.name,
+        ...(budgetExceeded ? { budgetExceeded: true } : {}),
+      });
     };
     const fail = (err: Error) => {
       if (settled) return;
       settled = true;
       clearTimeout(timer);
+      opts.signal?.removeEventListener('abort', onAbort);
       rejectAllPending(err);
       reject(err);
     };
@@ -210,31 +308,56 @@ export function runAcpHarness(opts: RunHarnessOptions): Promise<HarnessResult> {
       }
 
       const outcome = opts.harness.parseLine(line, state);
+      if (typeof outcome.runningCostUsd === 'number') {
+        if (!promptSent) prePromptCost = outcome.runningCostUsd;
+        else {
+          postPromptCostSamples++;
+          costBaseline ??= outcome.runningCostUsd;
+          if (!settled && isCostOverBudget(opts.harness, opts.maxBudgetUsd, outcome.runningCostUsd, costBaseline)) {
+            proc.kill('SIGKILL');
+            const partial = state.result ?? opts.harness.extractResult(state) ?? emptyResult();
+            const latchedId = state._harness?.sessionId;
+            finish(
+              budgetStoppedResult(
+                {
+                  ...partial,
+                  totalCostUsd: outcome.runningCostUsd,
+                  sessionId: partial.sessionId ?? (typeof latchedId === 'string' ? latchedId : null),
+                },
+                state.streamedText,
+              ),
+              true,
+            );
+            return;
+          }
+        }
+      }
       // 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);
-          }
-        }
+        appendStreamed(state, outcome.streamedText, opts.onStream); // capped — see stream-caps.ts
       }
+      if (promptSent && outcome.activities) appendActivities(state, outcome.activities, opts.onActivity);
       if (outcome.result) {
         if (!outcome.result.result) outcome.result.result = state.streamedText;
         state.result = outcome.result;
+        // Same host-side budget enforcement as runner.ts (see isOverBudget). Replayed history
+        // from a resume can't trip it — only once the new prompt is in flight.
+        if (
+          promptSent &&
+          !settled &&
+          isOverBudget(
+            opts.harness,
+            opts.maxBudgetUsd,
+            state.result,
+            // a resume that never saw a cost during this run has no evidence of new spend at all
+            costBaseline ?? (opts.resumeSessionId ? Number.POSITIVE_INFINITY : 0),
+          )
+        ) {
+          proc.kill('SIGKILL');
+          finish(budgetStoppedResult(state.result, state.streamedText), true);
+        }
       }
     });
 
@@ -265,14 +388,13 @@ export function runAcpHarness(opts: RunHarnessOptions): Promise<HarnessResult> {
     }, opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
     timer.unref?.();
 
-    opts.signal?.addEventListener(
-      'abort',
-      () => {
-        proc.kill('SIGKILL');
-        fail(new Error('cancelled'));
-      },
-      { once: true },
-    );
+    // Removed again in finish()/fail() — a long-lived signal (e.g. one shared by a fan-out, or the
+    // tool call's own) must not accumulate a dead listener per run.
+    function onAbort(): void {
+      proc.kill('SIGKILL');
+      fail(new Error('cancelled'));
+    }
+    opts.signal?.addEventListener('abort', onAbort, { 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.
@@ -284,7 +406,7 @@ export function runAcpHarness(opts: RunHarnessOptions): Promise<HarnessResult> {
           protocolVersion: PROTOCOL_VERSION,
           clientCapabilities: {}, // no fs/terminal proxying — decline those requests if asked (see handleServerRequest)
         },
-        HANDSHAKE_TIMEOUT_MS,
+        handshakeTimeoutMs,
       );
       if (settled) return;
       // The client "should disconnect" (spec text) if the agent didn't echo back the version we
@@ -312,11 +434,11 @@ export function runAcpHarness(opts: RunHarnessOptions): Promise<HarnessResult> {
         sessionResult = await sendRequest(
           'session/load',
           { sessionId: opts.resumeSessionId, ...sessionParams },
-          HANDSHAKE_TIMEOUT_MS,
+          handshakeTimeoutMs,
         );
         sessionId = opts.resumeSessionId;
       } else {
-        sessionResult = await sendRequest('session/new', sessionParams, HANDSHAKE_TIMEOUT_MS);
+        sessionResult = await sendRequest('session/new', sessionParams, handshakeTimeoutMs);
         sessionId =
           isRecord(sessionResult) && typeof sessionResult.sessionId === 'string' ? sessionResult.sessionId : null;
       }
@@ -342,9 +464,10 @@ export function runAcpHarness(opts: RunHarnessOptions): Promise<HarnessResult> {
             `cannot verify the "${opts.permission}" permission tier would be honored over ACP`,
         );
       }
-      await sendRequest('session/set_mode', { sessionId, modeId }, HANDSHAKE_TIMEOUT_MS);
+      await sendRequest('session/set_mode', { sessionId, modeId }, handshakeTimeoutMs);
       if (settled) return;
       promptSent = true;
+      costBaseline = opts.resumeSessionId ? prePromptCost : 0;
       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

package/extensions/activity.ts

@@ -1,4 +1,4 @@
-import { readdirSync, rmSync, statSync } from 'node:fs';
+import { chmodSync, mkdirSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import type { ActivityEvent, NormalizedPermission } from './harnesses/types.ts';
 
@@ -169,6 +169,68 @@ export function formatVerifySection(v: VerifyResult): string {
   return lines.join('\n');
 }
 
+/** How a run's `maxBudgetUsd` was (or wasn't) enforced, and whether it was exceeded. */
+export interface BudgetNote {
+  limitUsd: number;
+  /** `native`: the harness CLI enforces it itself. `host`: best-effort — the runner kills the run
+   *  when the harness's streamed cost (checked only at the step/turn boundaries it reports) is over
+   *  the cap, so spend can overshoot by up to one step/turn. `unenforced`: neither — no native flag and no cost reported. */
+  enforcement: 'native' | 'host' | 'unenforced';
+  exceeded: boolean;
+  /** Human-readable warning, or null when there's nothing to warn about. */
+  message: string | null;
+}
+
+/**
+ * Pure: describe a run's budget outcome. Undefined when no budget was set. `stoppedByHost` is the
+ * runner's own `budgetExceeded` flag; `costUsd` is the run's final `totalCostUsd` (null = unmeasured).
+ */
+export function describeBudget(opts: {
+  harness: string;
+  limitUsd: number | undefined;
+  native: boolean;
+  costUsd: number | null;
+  stoppedByHost: boolean;
+}): BudgetNote | undefined {
+  const { harness, limitUsd, native, costUsd, stoppedByHost } = opts;
+  if (limitUsd === undefined) return undefined;
+  const limit = `$${limitUsd.toFixed(3)}`;
+  const cost = costUsd !== null ? `$${costUsd.toFixed(3)}` : '$—';
+  if (native) {
+    const exceeded = costUsd !== null && costUsd > limitUsd;
+    return {
+      limitUsd,
+      enforcement: 'native',
+      exceeded,
+      message: exceeded ? `⛔ budget exceeded: ${cost} spent against a ${limit} cap (enforced by ${harness})` : null,
+    };
+  }
+  if (stoppedByHost) {
+    return {
+      limitUsd,
+      enforcement: 'host',
+      exceeded: true,
+      message: `⛔ budget exceeded: ${harness} reported ${cost} against a ${limit} cap — run stopped (best-effort: cost is only checked at each step/turn the harness reports, so spend can overshoot the cap)`,
+    };
+  }
+  if (costUsd === null) {
+    return {
+      limitUsd,
+      enforcement: 'unenforced',
+      exceeded: false,
+      message: `⚠ maxBudgetUsd ${limit} was not enforced — ${harness} has no native budget flag and reported no cost`,
+    };
+  }
+  return { limitUsd, enforcement: 'host', exceeded: costUsd > limitUsd, message: null };
+}
+
+/** One transcript header line for a budget note. */
+export function formatBudgetLine(b: BudgetNote): string {
+  const how =
+    b.enforcement === 'native' ? 'native' : b.enforcement === 'host' ? 'host-enforced, best-effort' : 'NOT enforced';
+  return `- budget: $${b.limitUsd.toFixed(3)} (${how})${b.exceeded ? ' · budget exceeded' : ''}`;
+}
+
 /** Build the markdown report content injected into the session on the next turn. */
 export function buildReportContent(opts: {
   harness?: string;
@@ -256,6 +318,30 @@ export function buildClaudeReportContent(opts: {
 }
 
 /** Delete oldest transcript files beyond `maxCount` (0 = keep everything). */
+/**
+ * Write one transcript to `dir` (created if needed) and return its path. Transcripts hold the
+ * delegated prompt, repo diffs, and the harness's full output — owner-only: the directory is
+ * `0700` and each file `0600` (chmod'd explicitly too, since `mkdirSync`'s `mode` only applies to
+ * directories it creates and is subject to the umask).
+ */
+export function writeTranscript(dir: string, mode: string, text: string): string {
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  try {
+    chmodSync(dir, 0o700);
+  } catch {
+    // best-effort — e.g. a dir owned by someone else; the file mode below still applies
+  }
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const file = join(dir, `${stamp}-${safeSegmentName(mode)}.md`);
+  writeFileSync(file, text, { encoding: 'utf8', mode: 0o600 });
+  try {
+    chmodSync(file, 0o600);
+  } catch {
+    // best-effort
+  }
+  return file;
+}
+
 export function pruneOutputs(dir: string, maxCount: number): void {
   if (maxCount <= 0) return;
   let files: string[];
@@ -373,6 +459,8 @@ export function buildTranscript(
     output: string;
     /** Host-run verification result, when a `verify` command was configured for this run. */
     verify?: VerifyResult;
+    /** Budget outcome, when `maxBudgetUsd` was set for this run. */
+    budget?: BudgetNote;
   } & Record<string, unknown>,
 ): string {
   const harness = (opts.harness as string | undefined) ?? 'claude';
@@ -426,6 +514,8 @@ export function buildTranscript(
     `- context: ${context ?? 'n/a'}`,
     `- duration: ${duration ?? 'n/a'}`,
     `- stop reason: ${opts.stopReason ?? 'n/a'}`,
+    ...(opts.budget ? [formatBudgetLine(opts.budget)] : []),
+    ...(opts.budget?.message ? ['', opts.budget.message] : []),
     '',
     '## Activity',
     opts.activityLog.length > 0 ? opts.activityLog.join('\n') : '(no tool activity)',