pi-harness-delegate 0.6.2 → 0.7.0

package/extensions/fanout.ts

@@ -0,0 +1,526 @@
+/**
+ * Fan-out (`harness: "all"` or a comma list): the tool path (`runFanoutTool`) and the `/delegate`
+ * command path (`runFanoutCommand` -> `runFanoutConcurrent`, one multi-run overlay). Split out of
+ * index.ts with no behavior change; the command path's overlay state is passed in as `RunUiState`.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type { OverlayHandle } from '@earendil-works/pi-tui';
+import {
+  buildFanoutReport,
+  type FanoutRunSummary,
+  formatMetrics,
+  formatToolUse,
+  orderFanoutResults,
+} from './activity.ts';
+import { fanoutResumeError, type parseDelegateCommand, resolveDefaults, resolveHarnessList } from './command.ts';
+import { type DelegateConfig, loadConfig } from './config.ts';
+import {
+  type DelegateToolParams,
+  delegate,
+  injectReport,
+  isProjectTrusted,
+  runDelegateForTool,
+  summarize,
+  type ToolProgressUpdate,
+} from './engine.ts';
+import { detectAll, HARNESS_NAMES, isKnownHarness, resolveHarnessName } from './harnesses/registry.ts';
+import type { ActivityEvent } from './harnesses/types.ts';
+import { NotifyBatcher } from './notify.ts';
+import { formatFanoutChip, multiProgressWindow, type RunRow } from './progress-multi.ts';
+import { loadTemplates } from './templates.ts';
+import { mapClaudeUsage } from './usage.ts';
+import { confirmDangerousCommand, validateDelegateInputs } from './validate.ts';
+/** How long the fan-out overlay lingers on the finished board after the last run resolves, so a
+ *  user who looked away still catches the final state instead of it clearing instantly. */
+export const FANOUT_LINGER_MS = 3000;
+
+export async function closeWhenMounted(getClose: () => (() => void) | null, capMs: number): Promise<void> {
+  const close = getClose();
+  if (close) {
+    close();
+    return;
+  }
+  await new Promise<void>(resolve => {
+    const start = Date.now();
+    const timer = setInterval(() => {
+      const fn = getClose();
+      if (fn || Date.now() - start > capMs) {
+        clearInterval(timer);
+        fn?.();
+        resolve();
+      }
+    }, 20);
+  });
+}
+
+/** `delegate({harness:"all"|"a,b"})` — resolve the requested harnesses to detected installs, run the
+ *  existing `delegate()` engine concurrently across all of them (bounded by `maxConcurrent` via
+ *  `acquireSlot({wait:true})` — see concurrency.ts), and mechanically synthesize one comparison
+ *  report ordered by the resolved harness list regardless of completion order. No second model call. */
+export async function runFanoutTool(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  config: DelegateConfig,
+  params: DelegateToolParams,
+  signal: AbortSignal | undefined,
+  onUpdate: ((u: ToolProgressUpdate) => void) | undefined,
+): Promise<{ content: { type: string; text: string }[]; details: Record<string, unknown>; usage?: unknown }> {
+  const resumeErr = fanoutResumeError(params.harness, params.sessionId);
+  if (resumeErr) throw new Error(resumeErr);
+  validateDelegateInputs({
+    sessionId: params.sessionId,
+    model: params.model,
+    pr: params.pr,
+    addDirs: params.addDirs,
+    cwd: ctx.cwd,
+  });
+  const detection = await detectAll();
+  const { resolved, unknown, skipped } = resolveHarnessList(params.harness ?? 'all', {
+    knownHarnesses: HARNESS_NAMES,
+    aliasOf: resolveHarnessName,
+    isKnown: isKnownHarness,
+    detection,
+  });
+  if (resolved.length === 0) {
+    throw new Error(
+      `no harness available to fan out to (unknown: ${unknown.join(', ') || '—'}; not installed: ${skipped.join(', ') || '—'})`,
+    );
+  }
+
+  const mode = params.mode ?? config.defaultMode;
+
+  type TaskResult = FanoutRunSummary & {
+    usage?: import('./harnesses/types.ts').StreamedUsage | null;
+  };
+  const tasks = resolved.map(async (h): Promise<TaskResult> => {
+    onUpdate?.({ content: [{ type: 'text', text: `[${h}] queued…` }], details: { progress: 0.5 } });
+    try {
+      const run = await runDelegateForTool(
+        pi,
+        ctx,
+        config,
+        {
+          harness: h,
+          task: params.task,
+          mode: params.mode,
+          scope: params.scope,
+          model: params.model,
+          maxBudgetUsd: params.maxBudgetUsd,
+          allowDangerous: params.allowDangerous === true,
+          sessionId: params.sessionId,
+          pr: params.pr,
+          addDirs: params.addDirs,
+          // no verify: intentionally not model-settable — see DelegateToolParams
+          waitForSlot: true,
+          onAcquired: () =>
+            onUpdate?.({ content: [{ type: 'text', text: `[${h}] running…` }], details: { progress: 0.5 } }),
+        },
+        signal,
+        onUpdate,
+        `[${h}] `,
+      );
+      const summary = summarize(run.content);
+      return {
+        harness: h,
+        ok: !run.result.isError,
+        metrics: formatMetrics({
+          numTurns: run.result.numTurns,
+          totalCostUsd: run.result.totalCostUsd,
+          promptTokens: 0,
+          contextPercent: typeof run.details.contextPercent === 'number' ? run.details.contextPercent : null,
+          durationMs: run.result.durationMs,
+        }),
+        cost: run.result.totalCostUsd,
+        body: summary.text,
+        file: (run.details.file as string) ?? undefined,
+        sessionId: (run.details.sessionId as string) ?? undefined,
+        verify: run.verify,
+        usage: run.result.usage,
+      };
+    } catch (err) {
+      return { harness: h, ok: false, cost: null, error: err instanceof Error ? err.message : String(err) };
+    }
+  });
+
+  const settled = await Promise.all(tasks);
+  const runs = orderFanoutResults(resolved, settled);
+
+  let sumInput = 0;
+  let sumOutput = 0;
+  let sumCacheCreate = 0;
+  let sumCacheRead = 0;
+  let sumCost = 0;
+  let anyCostKnown = false;
+  for (const r of runs) {
+    if (r.usage) {
+      sumInput += r.usage.inputTokens;
+      sumOutput += r.usage.outputTokens;
+      sumCacheCreate += r.usage.cacheCreationInputTokens;
+      sumCacheRead += r.usage.cacheReadInputTokens;
+    }
+    if (r.cost !== null) {
+      sumCost += r.cost;
+      anyCostKnown = true;
+    }
+  }
+
+  const report = buildFanoutReport({ runs, skipped, unknown });
+  const okCount = runs.filter(r => r.ok).length;
+  const head = `## delegate all — ${mode} (${okCount}/${runs.length} ok)`;
+  const usage = mapClaudeUsage({
+    inputTokens: sumInput,
+    outputTokens: sumOutput,
+    cacheCreationInputTokens: sumCacheCreate,
+    cacheReadInputTokens: sumCacheRead,
+    totalCostUsd: anyCostKnown ? sumCost : null,
+  });
+  return {
+    content: [{ type: 'text', text: `${head}\n\n${report}` }],
+    details: { fanout: true, harness: 'all', mode, harnesses: resolved, skipped, unknown, runs },
+    usage,
+  };
+}
+
+/** Mutable UI state shared by the command-path runners — owned by the extension factory. */
+export interface RunUiState {
+  activeRunId: number;
+  activeOverlay: { show(): void; focus(): void; runId: number } | null;
+}
+
+export interface FanoutSpec {
+  harnessName: string;
+  task: string;
+  scope?: string;
+  model?: string;
+  budget?: number;
+  sessionId?: string;
+  pr?: string;
+  addDirs?: string[];
+  verify?: string;
+  isDanger: boolean;
+  /** Only ever true after `confirmDangerousCommand` approved this invocation's --allow-dangerous. */
+  allowDangerous?: boolean;
+}
+export interface FanoutOutcome {
+  harnessName: string;
+  result: Awaited<ReturnType<typeof delegate>> | null;
+  error: Error | null;
+  cancelled: boolean;
+}
+
+/** Run `delegate()` concurrently across every spec in one multi-run overlay — the fan-out
+ *  counterpart to `runOneDelegation`. Concurrency is bounded by `maxConcurrent`: every run passes
+ *  `waitForSlot:true`, so `acquireSlot` (concurrency.ts) queues the ones that don't fit instead of
+ *  failing them, and a fan-out never exceeds the configured cap just because it's a fan-out.
+ *  Double-ESC cancel aborts every in-flight (and still-queued) run via one shared AbortController. */
+export async function runFanoutConcurrent(
+  pi: ExtensionAPI,
+  ui: RunUiState,
+  ctx: ExtensionContext,
+  mode: string | undefined,
+  specs: FanoutSpec[],
+): Promise<FanoutOutcome[]> {
+  const ac = new AbortController();
+  let cancelledAll = false;
+  const runId = ++ui.activeRunId;
+  const clearActive = () => {
+    if (ui.activeOverlay?.runId === runId) ui.activeOverlay = null;
+  };
+  const modeForDisplay = mode ?? 'general';
+  const anyDanger = specs.some(s => s.isDanger);
+  const overallStart = Date.now();
+  const rows: RunRow[] = specs.map(s => ({
+    harness: s.harnessName,
+    startedAt: null,
+    status: 'queued',
+    activity: '',
+    costUsd: null,
+  }));
+  let requestRender: (() => void) | null = null;
+
+  let chipLastPush = 0;
+  const pushChip = () => {
+    if (!ctx.hasUI) return;
+    const now = Date.now();
+    if (now - chipLastPush < 500) return;
+    chipLastPush = now;
+    const theme = ctx.ui.theme;
+    ctx.ui.setStatus(
+      'delegate',
+      theme.fg('accent', '●') + theme.fg('dim', ` ${formatFanoutChip(rows, now - overallStart)}`),
+    );
+  };
+
+  const runOne = async (spec: FanoutSpec, idx: number): Promise<FanoutOutcome> => {
+    const setRow = (patch: Partial<RunRow>) => {
+      rows[idx] = { ...rows[idx], ...patch };
+      requestRender?.();
+      pushChip();
+    };
+    let liveTail = '';
+    const onActivity = (ev: ActivityEvent) => {
+      if (ev.kind === 'tool_input') setRow({ activity: `▶ ${formatToolUse(ev.name, ev.input)}` });
+      else if (ev.kind === 'tool_result')
+        setRow({
+          activity: rows[idx].activity ? `${rows[idx].activity}${ev.isError ? ' ✗' : ' ✓'}` : rows[idx].activity,
+        });
+      else if (ev.kind === 'thinking') setRow({ activity: '💭 thinking…' });
+    };
+    const runState: { error: Error | null } = { error: null };
+    const run = delegate(pi, ctx, {
+      harness: spec.harnessName,
+      task: spec.task,
+      mode,
+      scope: spec.scope,
+      model: spec.model,
+      maxBudgetUsd: spec.budget,
+      sessionId: spec.sessionId,
+      pr: spec.pr,
+      addDirs: spec.addDirs,
+      verify: spec.verify,
+      allowDangerous: spec.allowDangerous === true, // never from config — only a confirmed --allow-dangerous
+      signal: ac.signal,
+      waitForSlot: true,
+      onAcquired: () => setRow({ status: 'running', startedAt: Date.now() }),
+      onStream: t => {
+        liveTail = (liveTail + t).slice(-200);
+        setRow({ activity: `✍ ${liveTail}` });
+      },
+      onActivity,
+    }).catch((err: unknown) => {
+      runState.error = err instanceof Error ? err : new Error(String(err));
+      return null;
+    });
+    const result = await run;
+    const failed = cancelledAll || !result;
+    // On failure keep context on the row: the reason if we have one, else whatever the run was
+    // last doing. Blanking it here would drop the only on-screen hint at *why* it failed.
+    const reason = runState.error ? runState.error.message.split('\n')[0].slice(0, 60) : '';
+    setRow({
+      status: failed ? 'failed' : 'done',
+      activity: failed ? reason || rows[idx].activity : '',
+      costUsd: !failed && result ? result.result.totalCostUsd : null,
+    });
+    return {
+      harnessName: spec.harnessName,
+      result: failed ? null : result,
+      error: runState.error,
+      cancelled: cancelledAll,
+    };
+  };
+
+  const allSettled = Promise.all(specs.map((spec, idx) => runOne(spec, idx)));
+
+  let closeWindow: (() => void) | null = null;
+  let outcomes: FanoutOutcome[];
+  if (ctx.hasUI) {
+    let overlayHandle: OverlayHandle | null = null;
+    let resolveDismiss = (): void => {};
+    const dismissed = new Promise<void>(resolve => {
+      resolveDismiss = () => resolve();
+    });
+    const uiPromise = ctx.ui
+      .custom(
+        (tui, theme, _kb, done) => {
+          requestRender = () => tui.requestRender();
+          closeWindow = () => done(undefined);
+          return multiProgressWindow(tui, theme, {
+            mode: modeForDisplay,
+            startedAt: overallStart,
+            getRows: () => rows,
+            dangerous: anyDanger,
+            onCancel: () => {
+              cancelledAll = true;
+              ac.abort();
+            },
+            onMinimize: () => {
+              overlayHandle?.setHidden(true);
+              overlayHandle?.unfocus();
+            },
+            onDismiss: () => resolveDismiss(),
+          });
+        },
+        {
+          overlay: true,
+          overlayOptions: { width: '70%', maxHeight: '60%', anchor: 'top-center' },
+          onHandle: h => {
+            overlayHandle = h;
+            ui.activeOverlay = { show: () => h.setHidden(false), focus: () => h.focus(), runId };
+            h.focus();
+          },
+        },
+      )
+      .catch(() => {});
+    outcomes = await allSettled;
+    // Cancelling already means "I'm done watching" — skip the linger so the overlay closes
+    // right away instead of sitting on a cancelled board for FANOUT_LINGER_MS.
+    if (cancelledAll) resolveDismiss();
+    // Tear the overlay down after a short linger (or immediately on Esc/m/cancel) — in the
+    // background, so this doesn't delay the outcomes we're about to return (and thus the
+    // injected report). `ui.activeOverlay` stays valid for `/delegate watch` until this settles.
+    void (async () => {
+      const timer = setTimeout(() => resolveDismiss(), FANOUT_LINGER_MS);
+      timer.unref?.();
+      await dismissed;
+      clearTimeout(timer);
+      await closeWhenMounted(() => closeWindow, 2000);
+      await uiPromise;
+      clearActive();
+      ctx.ui.setStatus('delegate', undefined);
+    })();
+  } else {
+    outcomes = await allSettled;
+    clearActive();
+  }
+  return outcomes;
+}
+
+/** `/delegate all …` / `/delegate a,b …` — resolve to detected harnesses, run `delegate()`
+ *  concurrently across all of them in one multi-run overlay (see `runFanoutConcurrent`), batch
+ *  success notifications, and inject one synthesized comparison report ordered by the resolved
+ *  harness list regardless of completion order. */
+export async function runFanoutCommand(
+  pi: ExtensionAPI,
+  ui: RunUiState,
+  ctx: ExtensionContext,
+  parsed: ReturnType<typeof parseDelegateCommand>,
+): Promise<void> {
+  const harnessSpec = parsed.harness as string;
+  const modeForReport = parsed.mode ?? loadConfig().defaultMode;
+  try {
+    const resumeErr = fanoutResumeError(harnessSpec, parsed.sessionId);
+    if (resumeErr) throw new Error(resumeErr);
+    validateDelegateInputs({
+      sessionId: parsed.sessionId,
+      model: parsed.model,
+      pr: parsed.pr,
+      addDirs: parsed.addDirs,
+      cwd: ctx.cwd,
+    });
+    // Headless never honors --allow-dangerous: refuse before even probing harness binaries. (With a
+    // UI the single confirm happens below, once the harness list is actually resolved.)
+    if (parsed.allowDangerous && !ctx.hasUI) {
+      await confirmDangerousCommand(ctx, { harnesses: [harnessSpec], mode: modeForReport, task: parsed.task });
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (ctx.hasUI) ctx.ui.notify(msg, 'error');
+    else process.stderr.write(`${msg}\n`);
+    return;
+  }
+  const detection = await detectAll();
+  const { resolved, unknown, skipped } = resolveHarnessList(harnessSpec, {
+    knownHarnesses: HARNESS_NAMES,
+    aliasOf: resolveHarnessName,
+    isKnown: isKnownHarness,
+    detection,
+  });
+  if (resolved.length === 0) {
+    const msg = `no harness available to fan out to (unknown: ${unknown.join(', ') || '—'}; not installed: ${skipped.join(', ') || '—'})`;
+    if (ctx.hasUI) ctx.ui.notify(msg, 'error');
+    else process.stderr.write(`${msg}\n`);
+    return;
+  }
+
+  const batcher = new NotifyBatcher((text, level) => {
+    if (ctx.hasUI) ctx.ui.notify(text, level);
+    else process.stdout.write(`${text}\n`);
+  });
+
+  // Resolve each harness's task/scope/danger flag up front — cheap and synchronous — so a
+  // harness that can't even start (e.g. mode needs a prompt) fails immediately instead of
+  // occupying a concurrency slot.
+  const specs: FanoutSpec[] = [];
+  const immediateFailures: FanoutRunSummary[] = [];
+  const trusted = isProjectTrusted(ctx);
+  for (const h of resolved) {
+    const templates = loadTemplates(ctx.cwd, h, trusted);
+    const resolvedTaskScope = resolveDefaults(parsed, templates);
+    const template = parsed.mode ? templates.get(parsed.mode) : undefined;
+    if (!resolvedTaskScope) {
+      const message = `mode "${parsed.mode ?? 'general'}" needs a prompt`;
+      immediateFailures.push({ harness: h, ok: false, cost: null, error: message });
+      batcher.failure(`${h}: ${message}`);
+      continue;
+    }
+    const isDanger =
+      template?.permission === 'danger' ||
+      (template?.nativePermission
+        ? ['bypassPermissions', 'danger-full-access', 'danger'].includes(template.nativePermission)
+        : false);
+    specs.push({
+      harnessName: h,
+      task: resolvedTaskScope.task,
+      scope: resolvedTaskScope.scope,
+      model: parsed.model,
+      budget: parsed.budget,
+      sessionId: parsed.sessionId,
+      pr: parsed.pr,
+      addDirs: parsed.addDirs,
+      verify: parsed.verify,
+      isDanger,
+    });
+  }
+
+  // --allow-dangerous: ONE confirm naming every harness that will actually run — never one per
+  // harness, and never a run before it's approved. A decline (or no UI) runs nothing.
+  if (parsed.allowDangerous && specs.length > 0) {
+    try {
+      await confirmDangerousCommand(ctx, {
+        harnesses: specs.map(s => s.harnessName),
+        mode: modeForReport,
+        task: specs[0].task,
+      });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (ctx.hasUI) ctx.ui.notify(msg, 'warning');
+      else process.stderr.write(`${msg}\n`);
+      return;
+    }
+    for (const s of specs) {
+      s.allowDangerous = true;
+      s.isDanger = true; // escalated — the overlay shows the danger banner
+    }
+  }
+
+  const outcomes = specs.length > 0 ? await runFanoutConcurrent(pi, ui, ctx, parsed.mode, specs) : [];
+  const completed: FanoutRunSummary[] = outcomes.map(outcome => {
+    if (outcome.cancelled || !outcome.result) {
+      const message = outcome.error ? outcome.error.message : outcome.cancelled ? 'cancelled' : 'delegation failed';
+      batcher.failure(`${outcome.harnessName}: ${outcome.cancelled ? 'cancelled' : 'failed'} — ${message}`);
+      return { harness: outcome.harnessName, ok: false, cost: null, error: message };
+    }
+    const { content, details, result, verify } = outcome.result;
+    const summary = summarize(content);
+    const metrics = formatMetrics({
+      numTurns: result.numTurns,
+      totalCostUsd: result.totalCostUsd,
+      promptTokens: 0,
+      contextPercent: typeof details.contextPercent === 'number' ? details.contextPercent : null,
+      durationMs: typeof details.durationMs === 'number' ? details.durationMs : null,
+    });
+    batcher.success(`${outcome.harnessName} ${parsed.mode ?? 'general'} — ${metrics}`);
+    return {
+      harness: outcome.harnessName,
+      ok: !result.isError,
+      metrics,
+      cost: result.totalCostUsd,
+      body: summary.text,
+      file: (details.file as string) ?? undefined,
+      sessionId: (details.sessionId as string) ?? undefined,
+      verify,
+    };
+  });
+
+  const runs = orderFanoutResults(resolved, [...immediateFailures, ...completed]);
+  const okCount = runs.filter(r => r.ok).length;
+  const report = buildFanoutReport({ runs, skipped, unknown });
+  injectReport(ctx, {
+    harness: 'all',
+    mode: modeForReport,
+    metrics: `${okCount}/${runs.length} ok`,
+    body: report,
+  });
+  batcher.flush();
+}

package/extensions/harnesses/amp.ts

@@ -65,6 +65,8 @@ function extractAmpText(o: Record<string, unknown>): string | undefined {
 interface AmpHarnessState {
   sessionId?: string;
   costAccum?: number;
+  /** True once any turn_end actually carried a numeric `usage.cost.total` — absent is not $0. */
+  costSeen?: boolean;
   inputAccum?: number;
   outputAccum?: number;
   cacheReadAccum?: number;
@@ -137,11 +139,10 @@ export function parseAmpLine(line: string, state: ParseState): ParseOutcome {
     // real usage lives at message.usage on turn_end (per-turn, not cumulative — see accumulation below)
     if (typeStr === 'turn_end' && isRecord(msg?.usage)) {
       const u = msg.usage as Record<string, unknown>;
-      const cost =
-        isRecord(u.cost) && typeof (u.cost as Record<string, unknown>).total === 'number'
-          ? ((u.cost as Record<string, unknown>).total as number)
-          : 0;
-      hs.costAccum = (hs.costAccum ?? 0) + cost;
+      if (isRecord(u.cost) && typeof (u.cost as Record<string, unknown>).total === 'number') {
+        hs.costAccum = (hs.costAccum ?? 0) + ((u.cost as Record<string, unknown>).total as number);
+        hs.costSeen = true;
+      }
       hs.inputAccum = (hs.inputAccum ?? 0) + (typeof u.input === 'number' ? u.input : 0);
       hs.outputAccum = (hs.outputAccum ?? 0) + (typeof u.output === 'number' ? u.output : 0);
       hs.cacheReadAccum = (hs.cacheReadAccum ?? 0) + (typeof u.cacheRead === 'number' ? u.cacheRead : 0);
@@ -176,7 +177,7 @@ export function parseAmpLine(line: string, state: ParseState): ParseOutcome {
               : state.streamedText || (text ?? ''),
       isError: o.is_error === true || isErrorTurn,
       numTurns: measured ? (hs.turnCount as number) : null,
-      totalCostUsd: measured ? (hs.costAccum as number) : null,
+      totalCostUsd: hs.costSeen ? (hs.costAccum as number) : null,
       sessionId:
         typeof o.session_id === 'string' ? o.session_id : typeof o.id === 'string' ? o.id : (hs.sessionId ?? null),
       stopReason:

package/extensions/harnesses/claude.ts

@@ -156,6 +156,8 @@ export const claudeHarness: Harness = {
     edit: ['acceptEdits'],
     danger: ['bypassPermissions'],
   },
+  // `--max-budget-usd` (see buildArgs) — claude enforces the cap itself.
+  nativeBudget: true,
   // 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

@@ -246,14 +246,22 @@ export const codexHarness: Harness = {
   },
   buildArgs(opts: BuildArgsOpts): string[] {
     const sandbox = opts.nativePermission ?? SANDBOX_MAP[opts.permission] ?? 'workspace-write';
-    const args = opts.resumeSessionId
-      ? ['exec', 'resume', opts.resumeSessionId, opts.prompt, '--json']
-      : ['exec', '--json', opts.prompt, '--sandbox', sandbox];
+    if (opts.resumeSessionId) {
+      // Positionals go after `--` so a session id (or prompt) can never be parsed as a flag —
+      // confirmed live: `codex exec resume --json -- --x "p"` takes `--x` as the session id,
+      // while the same without `--` is a hard "unexpected argument" error. Every flag must
+      // therefore come before the `--`.
+      // `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 below supports either flag.
+      const args = ['exec', 'resume', '--json'];
+      if (opts.model) args.push('--model', opts.model);
+      args.push('--', opts.resumeSessionId, opts.prompt);
+      return args;
+    }
+    const args = ['exec', '--json', opts.prompt, '--sandbox', sandbox];
     if (opts.model) args.push('--model', opts.model);
-    // `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);
+    for (const dir of opts.addDirs ?? []) args.push('--add-dir', dir);
     return args;
   },
   parseLine(line: string, state: ParseState): ParseOutcome {

package/extensions/harnesses/opencode.ts

@@ -55,6 +55,8 @@ function extractOpencodeText(o: Record<string, unknown>): string | undefined {
 interface OpencodeHarnessState {
   sessionId?: string;
   costAccum?: number;
+  /** True once any step_finish actually carried a numeric `cost` — a step without one is not a $0 step. */
+  costSeen?: boolean;
   inputAccum?: number;
   outputAccum?: number;
   cacheReadAccum?: number;
@@ -124,7 +126,10 @@ export function parseOpencodeLine(line: string, state: ParseState): ParseOutcome
     if (typeStr === 'step_finish' && part) {
       const tokens = isRecord(part.tokens) ? (part.tokens as Record<string, unknown>) : null;
       const cache = tokens && isRecord(tokens.cache) ? (tokens.cache as Record<string, unknown>) : null;
-      hs.costAccum = (hs.costAccum ?? 0) + (typeof part.cost === 'number' ? part.cost : 0);
+      if (typeof part.cost === 'number') {
+        hs.costAccum = (hs.costAccum ?? 0) + part.cost;
+        hs.costSeen = true;
+      }
       hs.inputAccum = (hs.inputAccum ?? 0) + (tokens && typeof tokens.input === 'number' ? tokens.input : 0);
       hs.outputAccum = (hs.outputAccum ?? 0) + (tokens && typeof tokens.output === 'number' ? tokens.output : 0);
       hs.cacheReadAccum = (hs.cacheReadAccum ?? 0) + (cache && typeof cache.read === 'number' ? cache.read : 0);
@@ -151,7 +156,8 @@ export function parseOpencodeLine(line: string, state: ParseState): ParseOutcome
             : state.streamedText + (streamedText ?? ''),
       isError: o.is_error === true,
       numTurns: typeof o.num_turns === 'number' ? o.num_turns : measured ? (hs.stepCount as number) : null,
-      totalCostUsd: measured
+      // Only a cost field actually seen counts — steps without one stay unmeasured (null), never $0.
+      totalCostUsd: hs.costSeen
         ? (hs.costAccum as number)
         : typeof o.total_cost_usd === 'number'
           ? o.total_cost_usd
@@ -243,7 +249,12 @@ function translateOpencodeAcpUpdate(update: Record<string, unknown>, state: Pars
       // docs/acp-harness-assessment.md §2 — and, per the same section, this is a running session
       // total already, latched from the *last* usage_update seen, never summed across a series.
       if (typeof update.size === 'number') hs.contextWindow = update.size;
-      if (isRecord(update.cost) && typeof update.cost.amount === 'number') hs.costUsd = update.cost.amount;
+      if (isRecord(update.cost) && typeof update.cost.amount === 'number') {
+        hs.costUsd = update.cost.amount;
+        // surfaced to acp-runner.ts so it can enforce maxBudgetUsd mid-turn, not only once the
+        // session/prompt response arrives (by which point the turn has already finished)
+        return { streamedText, activities, runningCostUsd: update.cost.amount };
+      }
       break;
     default:
       break;

package/extensions/harnesses/types.ts

@@ -46,6 +46,10 @@ export interface ParseOutcome {
   streamedText?: string;
   activities?: ActivityEvent[];
   result?: StreamedResult | null;
+  /** The harness's own running cost total as of this line, when the line reports one mid-turn
+   *  (e.g. an ACP `usage_update`) without being a final result — lets the ACP runner enforce
+   *  `maxBudgetUsd` before the turn ends. Same semantics as `StreamedResult.totalCostUsd`. */
+  runningCostUsd?: number;
 }
 
 export interface StreamParseOutcome {
@@ -95,6 +99,10 @@ export interface Harness {
   /** Normalized -> native CLI arg fragments, used by the 'stdout' transport's buildArgs/nativePermission. */
   permissionMap?: Record<NormalizedPermission, string[]>;
   permissionHint?: (permission: NormalizedPermission) => string[];
+  /** True when `buildArgs` passes `maxBudgetUsd` to a native CLI budget flag (claude's
+   *  `--max-budget-usd`). Otherwise the runners enforce it host-side from the streamed
+   *  `totalCostUsd` — possible only when the harness actually reports cost. */
+  nativeBudget?: boolean;
   /** Which transports this harness's binary actually supports — the ceiling `config.harnesses.<name>.transport`
    *  is validated against (see config.ts's `resolveTransport`), independent of what a user configures.
    *  Omitted -> `[transport ?? 'stdout']` (today's single-transport harnesses). A harness legally offering