pi-harness-delegate 0.7.0 → 0.7.2

package/README.md

@@ -160,7 +160,17 @@ All frontmatter keys (one `key: value` per line; only `name` is required):
 | `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.
+**Native escape hatch:** if you need a harness-specific permission not covered by the normalized set, put the native value in `permission:` (e.g. `permission: ask` in a `devin/` template) — it is passed to that harness as-is. Legacy `permissionMode:`/`sandbox:` keys only map onto the normalized tiers (`plan` → `readonly`, `bypassPermissions` → `danger`, anything else → `edit`).
+
+Native values are checked against a per-harness **allowlist** of readonly/edit-equivalent modes; anything else — the harness's own danger mode *or a value not on the list* — is treated as `danger` and needs `allowDangerous` / `--allow-dangerous` (fail closed). Once confirmed, an unlisted value still runs as declared rather than being swapped for the harness's danger mode.
+
+| Harness | Native values treated as non-danger |
+| --- | --- |
+| `claude` | `plan`, `acceptEdits`, `manual`, `default` (`auto`, `dontAsk`, `bypassPermissions` → danger) |
+| `codex` | `read-only`, `workspace-write` |
+| `opencode` | `plan`, `build` (custom agents, `build --auto` → danger) |
+| `amp`/`omp` | `always-ask`, `write` |
+| `devin` | `plan`, `accept-edits`, `ask` (`smart`, `bypass` → danger) |
 
 **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.
 
@@ -247,7 +257,7 @@ Config lives as a key inside pi's own `~/.pi/agent/settings.json` rather than a
 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 (the reported cost still includes prior turns).
+- **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
@@ -267,6 +277,7 @@ One deliberate, narrow exception: pi's own `Usage` (the footer/session token+cos
 - `/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.
+- External content in the delegated prompt — the `git diff` for `diff`, the `gh pr diff` body for `pr`/`--pr`, and `gh`'s error output if the PR can't be fetched — is wrapped in an **untrusted-data block**: a backtick fence longer than any backtick run inside it, between `BEGIN/END UNTRUSTED DATA <nonce>` markers with a fresh random nonce, plus an instruction that the content is data to analyze, not instructions. A malicious PR can't close the block early or forge its end marker, and the PR is named in the prompt only as `owner/repo#n`/`#n`, never by its raw URL. A free-text `--scope` (e.g. `src/a.ts, src/b`, or a template's `defaultScope`) is delimited the same way between `BEGIN/END SCOPE <nonce>` markers, but framed as a restriction the harness must honor — it can narrow the task, never add to it. Your own task text stays the instruction and isn't fenced. This is a mitigation, not a guarantee — models can still be swayed by injected text.
 
 Review what the harness is asked to do before granting broad permissions.
 

package/extensions/acp-runner.ts

@@ -28,6 +28,7 @@ import {
   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. */
@@ -66,6 +67,37 @@ 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 {
@@ -92,7 +124,14 @@ interface PendingRequest {
   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.
@@ -112,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 = '';
@@ -129,9 +172,8 @@ export function runAcpHarness(opts: RunHarnessOptions): Promise<HarnessResult> {
     // 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>();
@@ -145,6 +187,14 @@ export function runAcpHarness(opts: RunHarnessOptions): Promise<HarnessResult> {
       const ttft = firstTokenAt !== null ? firstTokenAt - startAt : r.ttftMs;
       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,
@@ -261,6 +311,7 @@ export function runAcpHarness(opts: RunHarnessOptions): Promise<HarnessResult> {
       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');
@@ -285,24 +336,9 @@ export function runAcpHarness(opts: RunHarnessOptions): Promise<HarnessResult> {
       // 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;
@@ -370,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
@@ -398,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;
       }
@@ -428,7 +464,7 @@ 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;

package/extensions/command.ts

@@ -26,20 +26,91 @@ export interface DelegateCommandArgs {
    * — never inherited from config, never applied headless. Absent unless explicitly true.
    */
   allowDangerous?: boolean;
+  /** Flag values that were given but are unusable (e.g. `--budget=0`) — the handler reports these
+   *  and runs nothing, rather than silently dropping the flag. Absent when there are none. */
+  errors?: string[];
+  /** Non-fatal heads-ups the handler shows before running — e.g. a recognized `--flag=` that sat
+   *  inside a double-quoted span and so was kept as prompt text, not applied. Absent when none. */
+  notices?: string[];
 }
 
 export type ClaudeCommandArgs = DelegateCommandArgs;
 
-const KNOWN_HARNESSES = new Set(['claude', 'codex', 'opencode', 'amp', 'omp']);
+/**
+ * The flag set every `/delegate`-family command accepts after the harness — the single source for
+ * the `/delegate` description, its usage warning, and every alias command's (`/claude`, `/omp`, …)
+ * description, so the hints can't drift from what `parseDelegateCommand` actually parses.
+ */
+export const COMMAND_FLAGS_HINT =
+  '[--mode=review|plan|implement|security-audit|docs|general] [--model=…] [--scope=diff|pr|paths] [--pr=<n|url>] [--budget=<usd>] [--verify=<cmd>] [--resume=<id>] [--add-dir=<path>] [--allow-dangerous] <prompt>';
+
+/** Usage line for `/delegate` itself. */
+export function delegateUsage(): string {
+  return `/delegate [--harness=claude|codex|opencode|amp|devin|all|<a,b>] ${COMMAND_FLAGS_HINT}`;
+}
+
+/** Usage line for an alias command (`/claude`, `/omp`, …) — same flags, harness fixed. */
+export function aliasUsage(command: string): string {
+  return `/${command} ${COMMAND_FLAGS_HINT}`;
+}
 
-/** True when `word` is `all`, a single known harness/alias, or a comma-separated list of them. */
+const KNOWN_HARNESSES = new Set(['claude', 'codex', 'opencode', 'amp', 'omp', 'devin']);
+const HARNESS_ALIASES: Readonly<Record<string, string>> = { omp: 'amp' };
+
+/** True when `word` is `all`, a single known harness/alias, or a comma-separated list of them
+ *  (a stray empty element, e.g. the trailing comma in `claude,`, is ignored). */
 function looksLikeHarnessSpec(word: string, knownHarnesses: ReadonlySet<string>): boolean {
   const lower = word.toLowerCase();
   if (lower === 'all' || knownHarnesses.has(lower)) return true;
+  if (!lower.includes(',')) return false;
   const parts = lower.split(',').filter(Boolean);
-  return parts.length > 1 && parts.every(p => knownHarnesses.has(p));
+  return parts.length > 0 && parts.every(p => knownHarnesses.has(p));
+}
+
+/**
+ * Normalize a harness spec the same way whether it came from `--harness=` or the first word:
+ * lowercased, empty list elements dropped (`claude,` -> `claude`, `,` -> none), and a single name
+ * alias-normalized (`omp` -> `amp`). A real list / `all` is left for `resolveHarnessList`.
+ */
+function normalizeHarnessSpec(spec: string): string | undefined {
+  const parts = spec
+    .toLowerCase()
+    .split(',')
+    .map(p => p.trim())
+    .filter(Boolean);
+  if (parts.length === 0) return undefined;
+  if (parts.length === 1) return HARNESS_ALIASES[parts[0]] ?? parts[0];
+  return parts.join(',');
 }
 
+/**
+ * One pass over the raw command: a backticked or double-quoted prose span is skipped verbatim (so
+ * `explain "--mode=x"` or `` `--allow-dangerous` `` in the prompt is never eaten as a flag); a
+ * `--key=value` (value bare, "double" or 'single' quoted, or empty) or bare `--allow-dangerous` /
+ * `--budget` token that starts a word is a flag. Every other `--word` stays in the text untouched.
+ */
+const FLAG_OR_PROSE = /`[^`]*`|"[^"]*"|(^|\s)--([a-zA-Z][a-zA-Z-]*)(?:=(?:"([^"]*)"|'([^']*)'|(\S*))|(?=\s|$))/g;
+
+/** Every flag `parseDelegateCommand` acts on — used to notice one stranded inside quoted prose. */
+const RECOGNIZED_FLAGS = new Set([
+  'harness',
+  'mode',
+  'model',
+  'scope',
+  'budget',
+  'resume',
+  'pr',
+  'verify',
+  'add-dir',
+  'allow-dangerous',
+]);
+
+/** A recognized flag token starting a word inside a prose span (quote/backtick counts as a word start). */
+const FLAG_IN_PROSE = /(?:^|[\s"`])--([a-zA-Z][a-zA-Z-]*)(?==|[\s"`]|$)/g;
+
+/** Prose spans as FLAG_OR_PROSE pairs them; whatever delimiter is left over afterwards is unmatched. */
+const PROSE_SPAN = /`[^`]*`|"[^"]*"/g;
+
 export function parseDelegateCommand(
   raw: string,
   knownModes: ReadonlySet<string>,
@@ -47,27 +118,76 @@ export function parseDelegateCommand(
 ): DelegateCommandArgs {
   const flags: Record<string, string> = {};
   const addDirs: string[] = [];
-  // supports quoted values ("…"/'…') so multi-word flags like --verify="bun test" survive intact
-  let rest = raw.replace(
-    /--([a-zA-Z-]+)=(?:"([^"]*)"|'([^']*)'|(\S+))/g,
-    (_m, k: string, dq: string | undefined, sq: string | undefined, bare: string | undefined) => {
+  const errors: string[] = [];
+  const notices: string[] = [];
+  let allowDangerousBare = false;
+  let budgetWithoutValue = false;
+  const rest = raw.replace(
+    FLAG_OR_PROSE,
+    (
+      m: string,
+      lead: string | undefined,
+      k: string | undefined,
+      dq: string | undefined,
+      sq: string | undefined,
+      bare: string | undefined,
+    ) => {
+      if (k === undefined) {
+        // quoted/backticked prose — left alone. A double-quoted span holding a recognized flag is
+        // most likely an accident (`fix "bug --budget=5 and "more`): say so instead of dropping it
+        // silently. Backticks are the deliberate "this is literal" marker, so they stay quiet.
+        if (m.startsWith('"')) {
+          for (const [, name] of m.matchAll(FLAG_IN_PROSE)) {
+            if (!RECOGNIZED_FLAGS.has(name)) continue;
+            notices.push(
+              `--${name} inside double quotes was kept as prompt text, not applied — move it outside the quotes to use it as a flag`,
+            );
+          }
+        }
+        return m;
+      }
+      const hasValue = dq !== undefined || sq !== undefined || bare !== undefined;
+      if (!hasValue) {
+        // bare boolean flag: only `--allow-dangerous`. A bare `--budget` (e.g. the space form
+        // `--budget 5`) is an explicit cap we can't honor — an error, never silently "no cap".
+        // Any other bare `--word` is prose.
+        if (k === 'budget') {
+          budgetWithoutValue = true;
+          return m;
+        }
+        if (k !== 'allow-dangerous') return m;
+        allowDangerousBare = true;
+        return lead ?? '';
+      }
       const value = dq ?? sq ?? bare ?? '';
       // --add-dir is the one repeatable flag — every occurrence is kept, in order
       if (k === 'add-dir') {
         if (value) addDirs.push(value);
       } else flags[k] = value;
-      return '';
+      return lead ?? '';
     },
   );
-  // bare boolean flag(s): `--allow-dangerous` with no `=value`. Run after the `--key=value` pass, so
-  // a quoted flag value (e.g. --verify="echo --allow-dangerous") is already gone and can't match.
-  let allowDangerousBare = false;
-  rest = rest.replace(/(^|\s)--allow-dangerous(?=\s|$)/g, (_m, lead: string) => {
-    allowDangerousBare = true;
-    return lead;
-  });
 
-  let harness = flags.harness?.toLowerCase();
+  // An unmatched `"` or backtick makes the pairing above a guess: in `fix "x --verify="echo ok"` the
+  // stray quote pairs with the flag's own opening quote, so the real flag is eaten as prose and
+  // whatever followed it is parsed as flags instead. Text before the first delimiter is outside any
+  // span however the quotes pair, so only a flag-shaped token at or after it is in play; when one
+  // is, refuse rather than guess — the result must not depend on quote parity.
+  const strayDelimiter = /["`]/.test(rest.replace(PROSE_SPAN, ''));
+  const firstDelimiter = raw.search(/["`]/);
+  const ambiguous = strayDelimiter && firstDelimiter >= 0 && /--[a-zA-Z]/.test(raw.slice(firstDelimiter));
+  if (ambiguous) {
+    errors.push(
+      'unbalanced " or ` in the command — flags around it can\'t be told apart from prompt text; close the quote (or remove it) and try again',
+    );
+  }
+  if (budgetWithoutValue && flags.budget === undefined) {
+    errors.push(
+      '--budget needs a value: use --budget=<usd> (or wrap the text in backticks if it is part of the prompt)',
+    );
+  }
+
+  let harness = flags.harness !== undefined ? normalizeHarnessSpec(flags.harness) : undefined;
   let mode = flags.mode;
   let task = rest.trim();
 
@@ -75,9 +195,7 @@ export function parseDelegateCommand(
   const words = task.split(/\s+/).filter(Boolean);
   let idx = 0;
   if (!harness && words[idx] && looksLikeHarnessSpec(words[idx], knownHarnesses)) {
-    harness = words[idx].toLowerCase();
-    // single-name alias normalization only — a list/`all` is resolved later by resolveHarnessList
-    if (harness === 'omp') harness = 'amp';
+    harness = normalizeHarnessSpec(words[idx]);
     idx++;
   }
   if (!mode && words[idx] && knownModes.has(words[idx])) {
@@ -93,14 +211,20 @@ export function parseDelegateCommand(
   if (flags.scope) out.scope = flags.scope;
   if (flags.budget !== undefined) {
     const budget = Number(flags.budget);
-    if (Number.isFinite(budget) && budget > 0) out.budget = budget;
+    // an explicit spend cap that can't be honored is an error, never silently "no cap"
+    if (flags.budget.trim() !== '' && Number.isFinite(budget) && budget > 0) out.budget = budget;
+    else errors.push(`--budget must be a positive number of USD (got "${flags.budget}")`);
   }
   if (flags.resume) out.sessionId = flags.resume;
   if (flags.pr) out.pr = flags.pr;
   if (flags.verify) out.verify = flags.verify;
   if (addDirs.length > 0) out.addDirs = addDirs;
   // `=true` is tolerated; any other explicit value (`=false`, `=yes`, …) means off — fail closed
-  if (allowDangerousBare || flags['allow-dangerous']?.toLowerCase() === 'true') out.allowDangerous = true;
+  // never grant danger off an ambiguous parse — the error above stops the run anyway, but fail closed
+  if (!ambiguous && (allowDangerousBare || flags['allow-dangerous']?.toLowerCase() === 'true'))
+    out.allowDangerous = true;
+  if (errors.length > 0) out.errors = errors;
+  if (notices.length > 0) out.notices = [...new Set(notices)];
   return out;
 }
 

package/extensions/concurrency.ts

@@ -39,6 +39,29 @@ export interface AcquireSlotOptions {
   /** Aborts a `wait: true` poll early. */
   signal?: AbortSignal;
   pollIntervalMs?: number;
+  /** Source of the poll jitter (see `pollDelayMs`) — injectable so tests stay deterministic. */
+  random?: () => number;
+  /** How a poll waits (default: an abortable `setTimeout`) — injectable so tests can observe the
+   *  actual delay each poll is given. */
+  sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+
+/** Max extra delay added to each poll, as a fraction of `pollIntervalMs`. */
+export const POLL_JITTER_FRACTION = 0.25;
+
+/**
+ * One poll's wait: `pollIntervalMs` plus up to `POLL_JITTER_FRACTION` of it, at random. Without the
+ * jitter, every waiter of a fan-out (all launched in the same tick) re-checks in lockstep, so they
+ * keep hitting `acquireRunWithinLimits`'s write-then-recheck together — exactly the tight multi-way
+ * race that makes contenders all back off at once (a transient under-admission). Spreading the
+ * re-checks out breaks the lockstep. Pure given `random`.
+ */
+export function pollDelayMs(pollIntervalMs: number, random: () => number = Math.random): number {
+  // a non-finite draw (NaN would otherwise survive the clamp and make setTimeout fire at 0ms, i.e.
+  // a hot poll loop) gets no jitter
+  const raw = random();
+  const r = Number.isFinite(raw) ? Math.min(1, Math.max(0, raw)) : 0;
+  return pollIntervalMs + Math.floor(pollIntervalMs * POLL_JITTER_FRACTION * r);
 }
 
 function abortError(): Error {
@@ -77,21 +100,31 @@ function sleep(ms: number, signal?: AbortSignal): Promise<void> {
  * 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;
+  const {
+    harness,
+    mode,
+    config,
+    wait,
+    signal,
+    pollIntervalMs = 200,
+    random = Math.random,
+    sleep: sleepFn = sleep,
+  } = opts;
+  const pause = () => sleepFn(pollDelayMs(pollIntervalMs, random), signal);
   for (;;) {
     if (signal?.aborted) throw abortError();
     const maxGlobal = getMaxConcurrent(config);
     const globalCount = activeCount();
     if (maxGlobal > 0 && globalCount >= maxGlobal) {
       if (!wait) throw new ConcurrencyLimitError('another delegate run is already in progress (global limit)');
-      await sleep(pollIntervalMs, signal);
+      await pause();
       continue;
     }
     const perHarnessLimit = getMaxConcurrent(config, harness);
     const perHarnessCount = activeCount(harness);
     if (perHarnessLimit > 0 && perHarnessCount >= perHarnessLimit) {
       if (!wait) throw new ConcurrencyLimitError(`another ${harness} run is already in progress`);
-      await sleep(pollIntervalMs, signal);
+      await pause();
       continue;
     }
 
@@ -100,7 +133,7 @@ export async function acquireSlot(opts: AcquireSlotOptions): Promise<() => void>
       // 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);
+      await pause();
       continue;
     }
 

package/extensions/config.ts

@@ -109,6 +109,34 @@ export function defaultDelegateConfig(): DelegateConfig {
   };
 }
 
+function isObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null;
+}
+
+/** `maxConcurrent.perHarness` from raw settings: only non-negative numeric entries survive.
+ *  Undefined when the value isn't an object or no entry is valid. */
+export function parsePerHarness(raw: unknown): Record<string, number> | undefined {
+  if (!isObject(raw)) return undefined;
+  const ph: Record<string, number> = {};
+  for (const [k, v] of Object.entries(raw)) {
+    if (typeof v === 'number' && v >= 0) ph[k] = v;
+  }
+  return Object.keys(ph).length > 0 ? ph : undefined;
+}
+
+/** `maxConcurrent` from raw settings (shared by the `delegate` and legacy `claudeDelegate` keys):
+ *  a non-negative number, or `{global?, perHarness?}` with at least one valid part. Undefined
+ *  means "not configured / invalid — keep the default". */
+export function parseMaxConcurrent(raw: unknown): DelegateConfig['maxConcurrent'] | undefined {
+  if (typeof raw === 'number') return raw >= 0 ? raw : undefined;
+  if (!isObject(raw)) return undefined;
+  const out: { global?: number; perHarness?: Record<string, number> } = {};
+  if (typeof raw.global === 'number' && raw.global >= 0) out.global = raw.global;
+  const perHarness = parsePerHarness(raw.perHarness);
+  if (perHarness) out.perHarness = perHarness;
+  return out.global !== undefined || out.perHarness ? out : undefined;
+}
+
 /**
  * Only the top-level settings whose effective value differs from the built-in default.
  *
@@ -185,20 +213,8 @@ export function loadConfigWithSource(): ConfigLoadResult {
           if (typeof v === 'string' && v) cfg.modelAliases[k] = v;
         }
       }
-      if (typeof c.maxConcurrent === 'number' && c.maxConcurrent >= 0) cfg.maxConcurrent = c.maxConcurrent;
-      else if (c.maxConcurrent && typeof c.maxConcurrent === 'object') {
-        const obj = c.maxConcurrent as { global?: unknown; perHarness?: unknown };
-        const out: { global?: number; perHarness?: Record<string, number> } = {};
-        if (typeof obj.global === 'number' && obj.global >= 0) out.global = obj.global;
-        if (obj.perHarness && typeof obj.perHarness === 'object') {
-          const ph: Record<string, number> = {};
-          for (const [k, v] of Object.entries(obj.perHarness as Record<string, unknown>)) {
-            if (typeof v === 'number' && v >= 0) ph[k] = v;
-          }
-          if (Object.keys(ph).length > 0) out.perHarness = ph;
-        }
-        if (out.global !== undefined || out.perHarness) cfg.maxConcurrent = out;
-      }
+      const legacyMaxConcurrent = parseMaxConcurrent(c.maxConcurrent);
+      if (legacyMaxConcurrent !== undefined) cfg.maxConcurrent = legacyMaxConcurrent;
       if (typeof c.maxTranscripts === 'number' && c.maxTranscripts >= 0) cfg.maxTranscripts = c.maxTranscripts;
       if (c.harnesses && typeof c.harnesses === 'object') {
         for (const [k, v] of Object.entries(c.harnesses)) {
@@ -225,20 +241,8 @@ export function loadConfigWithSource(): ConfigLoadResult {
         if (typeof v === 'string' && v) cfg.modelAliases[k] = v;
       }
     }
-    if (typeof d.maxConcurrent === 'number' && d.maxConcurrent >= 0) cfg.maxConcurrent = d.maxConcurrent;
-    else if (d.maxConcurrent && typeof d.maxConcurrent === 'object') {
-      const obj = d.maxConcurrent as { global?: unknown; perHarness?: unknown };
-      const out: { global?: number; perHarness?: Record<string, number> } = {};
-      if (typeof obj.global === 'number' && obj.global >= 0) out.global = obj.global;
-      if (obj.perHarness && typeof obj.perHarness === 'object') {
-        const ph: Record<string, number> = {};
-        for (const [k, v] of Object.entries(obj.perHarness as Record<string, unknown>)) {
-          if (typeof v === 'number' && v >= 0) ph[k] = v;
-        }
-        if (Object.keys(ph).length > 0) out.perHarness = ph;
-      }
-      if (out.global !== undefined || out.perHarness) cfg.maxConcurrent = out;
-    }
+    const maxConcurrent = parseMaxConcurrent(d.maxConcurrent);
+    if (maxConcurrent !== undefined) cfg.maxConcurrent = maxConcurrent;
     if (typeof d.maxTranscripts === 'number' && d.maxTranscripts >= 0) cfg.maxTranscripts = d.maxTranscripts;
     if (d.harnesses && typeof d.harnesses === 'object') {
       for (const [k, v] of Object.entries(d.harnesses)) {
@@ -454,12 +458,10 @@ export function resolveTransport(cfg: DelegateConfig, harnessName: string, harne
 
 export function getMaxConcurrent(cfg: DelegateConfig, harness?: string): number {
   if (typeof cfg.maxConcurrent === 'number') return cfg.maxConcurrent;
-  // if object shape {global, perHarness}
-  const mc = cfg.maxConcurrent as unknown as { global?: number; perHarness?: Record<string, number> };
-  if (harness && mc.perHarness && typeof mc.perHarness[harness] === 'number') {
-    const v = mc.perHarness[harness];
-    if (typeof v === 'number') return v;
-  }
+  // object shape {global, perHarness} — narrowed by the number check above
+  const mc = cfg.maxConcurrent;
+  const perHarness = harness ? mc.perHarness?.[harness] : undefined;
+  if (typeof perHarness === 'number') return perHarness;
   if (typeof mc.global === 'number') return mc.global;
   return 1;
 }