pi-harness-delegate 0.6.2 → 0.7.1

package/extensions/command.ts

@@ -18,36 +18,176 @@ export interface DelegateCommandArgs {
   pr?: string;
   /** Host-run verification command override (--verify=); takes precedence over the template's. */
   verify?: string;
+  /** Extra directories the harness may access (--add-dir=, repeatable). */
+  addDirs?: string[];
+  /**
+   * `--allow-dangerous` (or `--allow-dangerous=true`): a human asking to run this one invocation
+   * with danger permission. Only ever honored after an interactive confirm in the command handler
+   * — 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>,
   knownHarnesses: ReadonlySet<string> = KNOWN_HARNESSES,
 ): DelegateCommandArgs {
   const flags: Record<string, string> = {};
-  // supports quoted values ("…"/'…') so multi-word flags like --verify="bun test" survive intact
+  const addDirs: string[] = [];
+  const errors: string[] = [];
+  const notices: string[] = [];
+  let allowDangerousBare = false;
+  let budgetWithoutValue = false;
   const rest = raw.replace(
-    /--([a-zA-Z-]+)=(?:"([^"]*)"|'([^']*)'|(\S+))/g,
-    (_m, k: string, dq: string | undefined, sq: string | undefined, bare: string | undefined) => {
-      flags[k] = dq ?? sq ?? bare ?? '';
-      return '';
+    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 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();
 
@@ -55,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])) {
@@ -73,11 +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
+  // 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;
 }
 
@@ -92,6 +239,16 @@ export function isFanoutSpec(harness: string | undefined): boolean {
   return lower === 'all' || lower.includes(',');
 }
 
+/**
+ * A session id belongs to exactly one harness's session store, so resuming "it" across a fan-out
+ * is meaningless — every other harness would either error out or silently start fresh under a
+ * foreign id. Returns the rejection message (null when fine); shared by the tool and command paths.
+ */
+export function fanoutResumeError(harnessSpec: string | undefined, sessionId: string | undefined): string | null {
+  if (!sessionId || !isFanoutSpec(harnessSpec)) return null;
+  return `cannot resume session "${sessionId}" across a fan-out (harness "${harnessSpec}") — a session id belongs to one harness; resume it with that single harness instead (e.g. /delegate --harness=<name> --resume=${sessionId} …)`;
+}
+
 export type HarnessFilterResolution =
   | { kind: 'none' } // no filter word given
   | { kind: 'known'; harness: string } // resolved to its canonical name (aliases/case normalized)

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,11 +133,14 @@ 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;
     }
 
-    activeRuns.set(harness, perHarnessCount + 1);
+    // In-process counters count only this process's own runs — never seed them from
+    // `activeCount()` (which already folds in other processes' registry entries), or a foreign
+    // run gets baked into our local count and outlives that run's own release.
+    activeRuns.set(harness, (activeRuns.get(harness) ?? 0) + 1);
     globalActiveRuns++;
     const runHandle = claim.status === 'acquired' ? claim.handle : null;
     let released = false;