@d3ara1n/pi-subagent 0.9.1 → 0.10.1

package/src/render.ts

@@ -0,0 +1,277 @@
+/**
+ * TUI rendering for the delegate tool: the call row (`delegate <role>`) and the
+ * result view (collapsed and expanded), plus the render-side elapsed-time timer.
+ */
+
+import {
+  getMarkdownTheme,
+  type ThemeColor,
+  type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
+import type { SubagentDetails } from "./types.ts";
+
+// Contextual types derived from ToolDefinition so we don't depend on
+// non-root-exported render types (ToolRenderContext is internal).
+type RenderCallFn = NonNullable<ToolDefinition["renderCall"]>;
+type RenderResultFn = NonNullable<ToolDefinition["renderResult"]>;
+import {
+  buildDisplayItems,
+  formatUsageStats,
+  elapsedSeconds,
+  formatToolCall,
+  statusStyle,
+  formatThinking,
+  renderDisplayItems,
+  isFailedResult,
+} from "./utils.ts";
+
+// ── Elapsed-time animation (render-side timer) ───────────────
+
+/**
+ * Per-row render state slot holding the elapsed-time animation timer.
+ * The handle lives in context.state so it is scoped to one tool row.
+ */
+interface DelegateRenderState {
+  elapsedTimer?: ReturnType<typeof setInterval>;
+}
+
+/**
+ * While a delegate is running, force a TUI repaint every second so the
+ * elapsed time ticks up even when the child process is idle. Uses
+ * context.invalidate() (pi's official re-render hook) rather than pushing
+ * data via onUpdate — the render recomputes elapsed time fresh from Date.now().
+ */
+function ensureElapsedTimer(context: {
+  state: Record<string, unknown>;
+  invalidate?: () => void;
+}): void {
+  const state = context.state as DelegateRenderState;
+  if (state.elapsedTimer) return;
+  if (typeof context.invalidate !== "function") return;
+  state.elapsedTimer = setInterval(() => {
+    try {
+      context.invalidate?.();
+    } catch {
+      /* ignore — invalidate must never break rendering */
+    }
+  }, 1000);
+}
+
+/** Stop the elapsed-time animation once the run reaches a terminal state. */
+function clearElapsedTimer(context: { state: Record<string, unknown> }): void {
+  const state = context.state as DelegateRenderState;
+  if (!state.elapsedTimer) return;
+  clearInterval(state.elapsedTimer);
+  state.elapsedTimer = undefined;
+}
+
+// ── renderCall: what the user sees when the tool is invoked ─────
+
+export const renderDelegateCall: RenderCallFn = (args, theme, _context) => {
+  const roleName = (args as any).role || "...";
+  const text = theme.fg("toolTitle", theme.bold("delegate ")) + theme.fg("accent", roleName);
+  return new Text(text, 0, 0);
+};
+
+// ── renderResult: TUI display when the tool finishes ────────
+
+export const renderDelegateResult: RenderResultFn = (result, { expanded }, theme, context) => {
+  const details = result.details as SubagentDetails | undefined;
+  const isRunning = !!details?.results[0] && details.results[0].exitCode === -1;
+
+  // Tick elapsed time every second while running; stop once terminal.
+  // Placed BEFORE the empty-results early return so every terminal path
+  // (abort, model-resolution failure, catch) still clears the timer —
+  // otherwise the interval leaks a permanent 1 Hz re-render per aborted run.
+  // The timer calls context.invalidate() so the render recomputes elapsed
+  // time fresh from Date.now() without dirtying the data layer.
+  if (isRunning) {
+    ensureElapsedTimer(context);
+  } else {
+    clearElapsedTimer(context);
+  }
+
+  if (!details || details.results.length === 0) {
+    const text = result.content[0];
+    return new Text(text?.type === "text" ? text.text : "(no output)", 0, 0);
+  }
+
+  const r = details.results[0];
+  const isError = !isRunning && isFailedResult(r);
+  const isTimeout = !isRunning && r.stopReason === "timeout";
+  const isBudget = !isRunning && r.stopReason === "budget_exceeded";
+  const isFailedState = isError || isTimeout || isBudget;
+
+  // Status icon. ⏳ running / ⏸ queued (pause) / ⏱ timeout / ⏲ budget / ✗ error / ✓ ok
+  let icon: string;
+  if (isRunning) {
+    icon = r.queued ? theme.fg("warning", "\u23F8") : theme.fg("warning", "\u23F3");
+  } else if (isTimeout) {
+    icon = theme.fg("warning", "\u23F1");
+  } else if (isBudget) {
+    icon = theme.fg("warning", "\u23F2");
+  } else if (isError) {
+    icon = theme.fg("error", "\u2717");
+  } else {
+    icon = theme.fg("success", "\u2713");
+  }
+
+  const displayItems = buildDisplayItems(r.activityLog);
+  const mdTheme = getMarkdownTheme();
+  const fg = theme.fg.bind(theme) as (color: string, text: string) => string;
+
+  // Task preview: first line, truncated to one row (always-visible anchor).
+  const firstLine = r.task.split("\n")[0];
+  const taskPreview = firstLine.length > 70 ? `${firstLine.slice(0, 70)}...` : firstLine;
+  // taskline: indicator prefix while running/queued; bare text once finished.
+  let taskline: string;
+  if (isRunning) {
+    const label = r.queued ? "(queued)" : "(running)";
+    taskline = `${icon} ${theme.fg("dim", label)} ${theme.fg("text", taskPreview)}`;
+  } else {
+    taskline = theme.fg("text", taskPreview);
+  }
+
+  // usage line: elapsed/budget(+grace) prefix + existing stats.
+  const secs = elapsedSeconds(r);
+  const stats = formatUsageStats(r.usage, r.model);
+  const budgetSec = r.budgetMs ? Math.round(r.budgetMs / 1000) : 0;
+  const liveGraceMs = (r.graceMs ?? 0) + (r.pauseStart ? Date.now() - r.pauseStart : 0);
+  const graceSec = Math.round(liveGraceMs / 1000);
+  let timePart: string | null = null;
+  if (secs != null) {
+    timePart =
+      budgetSec > 0
+        ? graceSec > 0
+          ? `${secs}s/${budgetSec}s(+${graceSec}s)`
+          : `${secs}s/${budgetSec}s`
+        : `${secs}s`;
+  }
+  const usageLine = [timePart, stats].filter(Boolean).join(" \u00b7 ");
+
+  // resultline: fixed line on terminal frames — `<icon> <content>` colored by outcome.
+  // success → AI summary, else first line of output (truncated), else a placeholder — never blank.
+  // error/timeout/budget → errorMessage (or a default label).
+  let resultline: string | undefined;
+  if (!isRunning) {
+    if (isFailedState) {
+      const content =
+        r.errorMessage || (isTimeout ? "Timed out" : isBudget ? "Budget exceeded" : "failed");
+      const col: ThemeColor = isTimeout || isBudget ? "warning" : "error";
+      resultline = `${icon} ${theme.fg(col, content)}`;
+    } else {
+      // success fallback chain: summary → output first line → placeholder.
+      const firstLine = r.output.trim().split("\n")[0] ?? "";
+      const preview = firstLine.length > 70 ? `${firstLine.slice(0, 70)}...` : firstLine;
+      const content = r.summary || preview;
+      const col: ThemeColor = content ? "text" : "muted";
+      resultline = `${icon} ${theme.fg(col, content || "(no output)")}`;
+    }
+  }
+
+  if (expanded) {
+    const container = new Container();
+
+    // Header: taskline + resultline (summary on success, error message on failure).
+    container.addChild(new Text(taskline, 0, 0));
+    if (resultline) {
+      container.addChild(new Text(resultline, 0, 0));
+    }
+
+    // Input block: reference files + context char count + task full text,
+    // grouped without inner spacing (they are all subagent input).
+    container.addChild(new Spacer(1));
+    if (r.files) {
+      for (const f of r.files) {
+        container.addChild(new Text(theme.fg("dim", `@${f}`), 0, 0));
+      }
+    }
+    if (r.context) {
+      container.addChild(new Text(theme.fg("dim", `ctx ${r.context.length} chars`), 0, 0));
+    }
+    container.addChild(new Text(theme.fg("dim", r.task), 0, 0));
+
+    // Activity stream (shown while running and after completion).
+    container.addChild(new Spacer(1));
+    const activity = displayItems.filter(
+      (item) => item.type === "toolCall" || item.type === "thinking",
+    );
+    if (activity.length === 0) {
+      const runningLabel = isRunning
+        ? r.queued
+          ? "(queued \u2014 waiting for a concurrency slot...)"
+          : "(waiting for first event...)"
+        : "(none)";
+      container.addChild(new Text(theme.fg("muted", runningLabel), 0, 0));
+    } else {
+      for (const item of activity) {
+        if (item.type === "thinking") {
+          container.addChild(new Text(formatThinking(item.status, fg), 0, 0));
+        } else {
+          const { prefix, color } = statusStyle(item.status, fg);
+          container.addChild(
+            new Text(prefix + formatToolCall(item.name, item.args, color), 0, 0),
+          );
+        }
+      }
+    }
+
+    // Full output (terminal runs only). Always render the slot — show a
+    // placeholder when empty so the user never thinks output was lost.
+    if (!isRunning) {
+      container.addChild(new Spacer(1));
+      if (r.output.trim()) {
+        container.addChild(new Markdown(r.output.trim(), 0, 0, mdTheme));
+        if (r.outputMethod === "compressed") {
+          container.addChild(
+            new Text(
+              theme.fg(
+                "muted",
+                "(output compressed by summary model \u2014 full text in history)",
+              ),
+              0,
+              0,
+            ),
+          );
+        } else if (r.outputMethod === "truncated") {
+          container.addChild(
+            new Text(theme.fg("muted", "(output truncated \u2014 full text in history)"), 0, 0),
+          );
+        }
+      } else {
+        container.addChild(
+          new Text(theme.fg("muted", "(no output \u2014 the run produced no text)"), 0, 0),
+        );
+      }
+    }
+
+    // Usage (with elapsed).
+    if (usageLine) {
+      container.addChild(new Spacer(1));
+      container.addChild(new Text(theme.fg("dim", usageLine), 0, 0));
+    }
+
+    return container;
+  }
+
+  // Collapsed view.
+  let text = taskline;
+  if (!isRunning) {
+    // resultline (shared computation above).
+    if (resultline) text += `\n${resultline}`;
+  } else if (!r.queued) {
+    // Running (not queued): show recent activity only.
+    const activity = displayItems.filter(
+      (item) => item.type === "toolCall" || item.type === "thinking",
+    );
+    if (activity.length === 0) {
+      text += `\n${theme.fg("muted", "(running...)")}`;
+    } else {
+      const rendered = renderDisplayItems(activity, 5, fg);
+      if (rendered) text += `\n${rendered}`;
+    }
+  }
+  if (usageLine) text += `\n${theme.fg("dim", usageLine)}`;
+  return new Text(text, 0, 0);
+};

package/src/roles.ts

@@ -13,10 +13,10 @@ export const BUILTIN_ROLES: Record<string, SubagentRole> = {
     role: "fast",
     fallbackRole: "default",
     description:
-      "READ-ONLY codebase exploration — locate files, grep symbols, trace imports, explain structures. Tools: read, find, grep, glob. NO bash, NO edits, NO web access.",
+      "READ-ONLY codebase exploration — locate files, grep symbols, trace imports, explain structures. Tools: read, find, grep. NO bash, NO edits, NO web access.",
     examples: ["Find where auth middleware is implemented", "Map the routing structure"],
     decisionTrigger: "Task finds or maps code without touch?",
-    tools: ["read", "find", "grep", "glob"],
+    tools: ["read", "find", "grep"],
     systemPrompt: [
       "Fast code explorer. You have READ-ONLY tools only — no commands, no edits.",
       "Grep/find to locate → read key sections only → identify types, interfaces, functions.",
@@ -32,13 +32,13 @@ export const BUILTIN_ROLES: Record<string, SubagentRole> = {
     role: "heavy",
     fallbackRole: "default",
     description:
-      "READ-ONLY code review & analysis — audit code, assess architecture, review diffs. Tools: read, bash, grep, glob. Has bash (git diff/log, test runs). NO edits, NO web access.",
+      "READ-ONLY code review & analysis — audit code, assess architecture, review diffs. Tools: read, bash, grep, find. Has bash (git diff/log, test runs). NO edits, NO web access.",
     examples: [
       "Review the error handling in src/api/ for security issues",
       "Audit this PR diff for performance regressions",
     ],
     decisionTrigger: "Task audits or reviews code quality?",
-    tools: ["read", "bash", "grep", "glob"],
+    tools: ["read", "bash", "grep", "find"],
     systemPrompt: [
       "Senior code reviewer. READ-ONLY — you must NOT modify any file.",
       "bash is for read-only commands only (git diff/log/show, test runs). Never use sed, tee, echo >, or any write command.",
@@ -53,10 +53,10 @@ export const BUILTIN_ROLES: Record<string, SubagentRole> = {
   worker: {
     role: "default",
     description:
-      "the ONLY role that can MODIFY files — edit, write, refactor, fix, implement. Tools: read, bash, edit, write, grep, glob, delegate. Can delegate to explorer/researcher.",
+      "the ONLY role that can MODIFY files — edit, write, refactor, fix, implement. Tools: read, bash, edit, write, grep, find, delegate. Can delegate to explorer/researcher.",
     examples: ["Rename all snake_case fields to camelCase", "Add input validation to POST /login"],
     decisionTrigger: "Task modifies files?",
-    tools: ["read", "bash", "edit", "write", "grep", "glob", "delegate"],
+    tools: ["read", "bash", "edit", "write", "grep", "find", "delegate"],
     subagentRoles: ["explorer", "researcher"],
     systemPrompt: [
       "Implementation worker. Work autonomously — all context is in the task description.",

package/src/spawn.ts

@@ -123,6 +123,8 @@ export async function spawnSubagent(
   task: string,
   options: {
     cwd?: string;
+    /** Thinking level passed to the child pi process when the role defines one. */
+    thinking?: string;
     tools?: string[];
     systemPrompt?: string;
     /** Extra context delivered as a separate channel from the task. */
@@ -163,7 +165,7 @@ export async function spawnSubagent(
   // budget instead of racing the parent's wall clock. `graceMs` is the
   // accumulated paused time — display only; the verdict is always
   // "active elapsed >= budget" (pausing grants no extra active time).
-  const budgetMs = options.timeoutMs ?? 0;
+  const budgetMs = Number.isFinite(options.timeoutMs) ? Math.max(0, options.timeoutMs ?? 0) : 0;
   let activeElapsedAccum = 0; // settled active ms (excludes suspended spans)
   let segmentStart = 0; // wall-clock start of the current active segment; 0 = no active segment
   let isSuspended = false; // true while a child `delegate` call is in flight
@@ -178,12 +180,16 @@ export async function spawnSubagent(
     // Build CLI args
     const args: string[] = ["--mode", "json", "--no-session", "--model", modelRef];
 
+    if (options.thinking) {
+      args.push("--thinking", options.thinking);
+    }
+
     if (options.tools && options.tools.length > 0) {
       args.push("--tools", options.tools.join(","));
     }
 
     // Temp dir for: large-context/task spill files, and as PI_SUBAGENT_TMPDIR
-    // for subagent bash work (e.g. git clone). The system prompt no longer uses it.
+    // for subagent bash work (e.g. git clone).
     tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "pi-subagent-"));
 
     // ── System prompt channel: inline text via --append-system-prompt ──
@@ -269,14 +275,14 @@ export async function spawnSubagent(
     };
 
     let thinkingCounter = 0;
-    // O(1) lookup from toolCallId → activityLog index (was linear find → O(n²) on busy runs)
+    // O(1) lookup from toolCallId → activityLog index.
     const toolCallIndex = new Map<string, number>();
 
     // Kill the child when the configured turn/cost budget is exceeded.
     // Called after each assistant message_end (usage already accumulated).
     const checkBudget = () => {
-      const mt = options.maxTurns ?? 0;
-      const mc = options.maxCost ?? 0;
+      const mt = Number.isFinite(options.maxTurns) ? Math.max(0, options.maxTurns ?? 0) : 0;
+      const mc = Number.isFinite(options.maxCost) ? Math.max(0, options.maxCost ?? 0) : 0;
       if (budgetExceeded || wasTimeout) return;
       if ((mt > 0 && result.usage.turns >= mt) || (mc > 0 && result.usage.cost >= mc)) {
         budgetExceeded = true;
@@ -400,45 +406,55 @@ export async function spawnSubagent(
     childEnv.PI_SUBAGENT_DEPTH = String(options.depth ?? 0);
 
     let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+    let escalationTimer: ReturnType<typeof setTimeout> | undefined;
     let proc: ChildProcess | undefined;
+    let processExited = false;
+    let terminationRequested = false;
+
+    const clearEscalationTimer = () => {
+      if (!escalationTimer) return;
+      clearTimeout(escalationTimer);
+      escalationTimer = undefined;
+    };
 
     // Shared kill helper used by abort, budget, and timeout paths.
-    // Centralizes reason → stopReason mapping and the SIGTERM → 5s → SIGKILL escalation.
-    const escalationTimers: ReturnType<typeof setTimeout>[] = [];
+    // A single termination request sends SIGTERM once. SIGKILL is sent only if
+    // the process has not emitted exit/close after the grace period.
     const killProc = (reason: "abort" | "budget" | "timeout") => {
+      if (terminationRequested || processExited) return;
+      terminationRequested = true;
       if (reason === "abort") wasAborted = true;
       else if (reason === "budget") {
         result.stopReason = "budget_exceeded";
         // Human-readable so the caller/TUI never falls back to raw stderr noise.
-        const mt = options.maxTurns ?? 0;
-        const mc = options.maxCost ?? 0;
+        const mt = Number.isFinite(options.maxTurns) ? Math.max(0, options.maxTurns ?? 0) : 0;
         const why =
           mt > 0 && result.usage.turns >= mt
             ? `${result.usage.turns} turns`
             : `$${result.usage.cost.toFixed(4)}`;
         result.errorMessage = `Budget exceeded (${why}; partial output returned)`;
-      } else if (reason === "timeout") {
+      } else {
         result.stopReason = "timeout";
         wasTimeout = true;
         // Human-readable message so the caller/TUI never falls back to the
         // raw stderr (which is full of TUI teardown escape sequences).
-        const secs = Math.round((options.timeoutMs ?? 0) / 1000);
+        const secs = Math.round(budgetMs / 1000);
         result.errorMessage = `Timed out after ${secs}s (completed ${result.usage.turns} turn${result.usage.turns === 1 ? "" : "s"})`;
       }
+
       try {
-        proc?.kill("SIGTERM");
+        if (!proc || !proc.kill("SIGTERM")) return;
       } catch {
-        /* ignore */
+        return;
       }
-      escalationTimers.push(
-        setTimeout(() => {
-          try {
-            if (proc && !proc.killed) proc.kill("SIGKILL");
-          } catch {
-            /* ignore */
-          }
-        }, 5000),
-      );
+      escalationTimer = setTimeout(() => {
+        if (processExited) return;
+        try {
+          proc?.kill("SIGKILL");
+        } catch {
+          /* ignore */
+        }
+      }, 5000);
     };
 
     /** Pause the active-time clock (called on child `delegate` start). */
@@ -503,9 +519,15 @@ export async function spawnSubagent(
         result.stderr += data.toString();
       });
 
+      p.on("exit", () => {
+        processExited = true;
+        clearEscalationTimer();
+      });
+
       p.on("close", (code, signal) => {
+        processExited = true;
         if (timeoutHandle) clearTimeout(timeoutHandle);
-        for (const t of escalationTimers) clearTimeout(t);
+        clearEscalationTimer();
         if (onAbort && options.signal) options.signal.removeEventListener("abort", onAbort);
         if (buffer.trim()) processLine(buffer);
 
@@ -524,8 +546,9 @@ export async function spawnSubagent(
       });
 
       p.on("error", (err) => {
+        processExited = true;
         if (timeoutHandle) clearTimeout(timeoutHandle);
-        for (const t of escalationTimers) clearTimeout(t);
+        clearEscalationTimer();
         if (onAbort && options.signal) options.signal.removeEventListener("abort", onAbort);
         // Surface the real cause (e.g. ENOENT when pi is not in PATH) instead of "unknown error".
         result.errorMessage = err?.message || String(err);

package/src/types.ts

@@ -4,17 +4,17 @@
 
 /** Configuration for the subagent extension. */
 export interface SubagentConfig {
-  /** Per-subagent timeout in seconds of active time. The clock pauses while the child is inside a nested `delegate` call, so no widening is needed for delegate-capable roles. */
+  /** Per-subagent active-time timeout in seconds. `0` means unlimited; negative values are normalized to `0`. The clock pauses while the child is inside a nested `delegate` call, so no widening is needed for delegate-capable roles. */
   timeout: number;
-  /** Max number of subagents allowed to run concurrently. Extras queue with a TUI hint. */
+  /** Max concurrent subagents. `0` means unlimited; negative values are normalized to `0`. Extras queue with a TUI hint when this is positive. */
   maxConcurrency: number;
-  /** Max subagent nesting depth (the top-level session is depth 0). */
+  /** Max subagent nesting depth (the top-level session is depth 0). `0` means unlimited; negative values are normalized to `0`. */
   maxDepth: number;
-  /** Default turn budget (0 = unlimited). Per-role maxTurns overrides this. */
+  /** Default assistant-turn budget. `0` means unlimited; negative values are normalized to `0`. Per-role maxTurns overrides this. */
   maxTurns: number;
-  /** Default cost budget in USD (0 = unlimited). Per-role maxCost overrides this. */
+  /** Default cumulative cost budget in USD. `0` means unlimited; negative values are normalized to `0`. Per-role maxCost overrides this. */
   maxCost: number;
-  /** Persist each delegate run to .pi/subagent/history/{sessionId}/{id}.json for auditing. */
+  /** Persist each delegate run to ~/.pi/subagent/history/{sessionId}/{id}.json for auditing. */
   history: SubagentHistoryConfig;
   summary: SubagentSummaryConfig;
   /**
@@ -61,11 +61,11 @@ export interface SubagentRole {
   tools: string[];
   /** If this role has `delegate`, restrict which roles it may spawn. undefined = no restriction. */
   subagentRoles?: string[];
-  /** Per-role timeout override in seconds. Falls back to config.timeout when unset. */
+  /** Per-role active-time timeout override in seconds. `0` means unlimited; negative values are normalized to `0`. Falls back to config.timeout when unset. */
   timeout?: number;
-  /** Max assistant turns before the run is killed (0 = use config default; unset = unlimited). */
+  /** Max assistant turns before the run is killed. `0` means unlimited; negative values are normalized to `0`. */
   maxTurns?: number;
-  /** Max cumulative cost (USD) before the run is killed (0 = use config default; unset = unlimited). */
+  /** Max cumulative cost in USD. `0` means unlimited; negative values are normalized to `0`. */
   maxCost?: number;
   /** Fallback pi-model-roles role name when this role's model is unavailable (provider error). Defaults to "default". */
   fallbackRole?: string;

package/src/utils.test.ts

@@ -5,8 +5,8 @@
  *   node --test packages/pi-subagent/src/utils.test.ts
  *
  * These guard the bug fixes introduced during the improvement rounds:
- * path-injection (sanitizeFilename), concurrency/abort/negative-active
- * (AsyncSemaphore), provider-error word list (isProviderError), unknown-tool
+ * path-injection (sanitizeFilename), concurrency/abort/negative-active/unlimited
+ * semantics (AsyncSemaphore), provider-error word list (isProviderError), unknown-tool
  * formatting (previewArgs), output truncation fallback (truncateOutput).
  */
 
@@ -146,6 +146,40 @@ describe("AsyncSemaphore", () => {
     await assert.rejects(p);
     assert.equal((s as any).waiters.length, 0);
   });
+  test("unlimited max (0) never queues or reports capacity", async () => {
+    const s = new AsyncSemaphore(0);
+    assert.equal(s.isLimited, false);
+    assert.equal(s.isAtCapacity, false);
+
+    let acquired = 0;
+    await Promise.all(
+      Array.from({ length: 10 }, () =>
+        s.acquire().then(() => {
+          acquired++;
+        }),
+      ),
+    );
+
+    assert.equal(acquired, 10);
+    assert.equal((s as any).waiters.length, 0);
+    assert.equal(s.isAtCapacity, false);
+  });
+  test("positive max reports capacity and retains FIFO queueing", async () => {
+    const s = new AsyncSemaphore(1);
+    await s.acquire();
+    assert.equal(s.isAtCapacity, true);
+
+    const order: number[] = [];
+    const p1 = s.acquire().then(() => order.push(1));
+    const p2 = s.acquire().then(() => order.push(2));
+    assert.equal((s as any).waiters.length, 2);
+
+    s.release();
+    await p1;
+    s.release();
+    await p2;
+    assert.deepEqual(order, [1, 2]);
+  });
   test("releases queued waiters in FIFO order", async () => {
     const s = new AsyncSemaphore(1);
     await s.acquire();

package/src/utils.ts

@@ -1,9 +1,6 @@
 /**
- * Pure helpers for pi-subagent: formatting, sanitization, formatting helpers,
- * and the concurrency semaphore. No pi-API or I/O dependencies — safe to unit-test.
- *
- * Extracted from index.ts so these can be exercised directly. index.ts imports
- * them; behavior is unchanged.
+ * Pure helpers for pi-subagent: formatting, sanitization, and the concurrency
+ * semaphore. No pi-API or I/O dependencies — safe to unit-test.
  */
 
 import * as os from "node:os";
@@ -222,11 +219,24 @@ export function previewArgs(args: Record<string, unknown>): string {
   return argsStr.length > 50 ? argsStr.slice(0, 50) + "..." : argsStr;
 }
 
+// ── Numeric configuration ─────────────────────────────────────
+
+/** Normalize a finite numeric limit: invalid values use the default; negatives become 0 (unlimited). */
+export function normalizeNonNegativeNumber(value: unknown, fallback: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  return Math.max(0, value);
+}
+
+/** Normalize a count limit to a non-negative integer. */
+export function normalizeNonNegativeInteger(value: unknown, fallback: number): number {
+  return Math.floor(normalizeNonNegativeNumber(value, fallback));
+}
+
 // ── Concurrency gate ───────────────────────────────────────────────
 
 /**
  * Promise-based semaphore capping concurrent subagent spawns.
- * acquire() resolves immediately while under the limit, otherwise queues.
+ * A max of 0 means unlimited concurrency, so acquire() never queues.
  * Pass an AbortSignal to cancel while waiting (rejects and removes the waiter).
  */
 export class AsyncSemaphore {
@@ -234,10 +244,16 @@ export class AsyncSemaphore {
   private waiters: Array<() => void> = [];
   private max: number;
   constructor(max: number) {
-    this.max = max;
+    this.max = normalizeNonNegativeInteger(max, 0);
+  }
+  get isLimited(): boolean {
+    return this.max > 0;
+  }
+  get isAtCapacity(): boolean {
+    return this.isLimited && this.active >= this.max;
   }
   async acquire(signal?: AbortSignal): Promise<void> {
-    if (this.active < this.max) {
+    if (!this.isAtCapacity) {
       this.active++;
       return;
     }
@@ -265,6 +281,7 @@ export class AsyncSemaphore {
   }
   release(): void {
     this.active = Math.max(0, this.active - 1);
+    if (!this.isLimited) return;
     const next = this.waiters.shift();
     if (next) next();
   }
@@ -277,9 +294,10 @@ export class AsyncSemaphore {
  * No widening for delegate-capable roles: the parent's active-time clock
  * pauses while the child is inside a nested `delegate` call, so the base
  * budget is already enough. An explicit roleDef.timeout always wins.
+ * Non-finite values fall back to the base timeout; negative values become 0 (unlimited).
  */
 export function effectiveTimeout(roleDef: SubagentRole, baseTimeoutSec: number): number {
-  return roleDef.timeout ?? baseTimeoutSec;
+  return normalizeNonNegativeNumber(roleDef.timeout, normalizeNonNegativeNumber(baseTimeoutSec, 0));
 }
 
 // ── Output truncation ────────────────────────────────────────