@nredd/pi-subagents 0.22.0-nredd.5 → 0.22.0-nredd.7

package/src/index.ts

@@ -48,6 +48,7 @@ import { checkModelScope, isScopeModelsEnabled, setScopeModelsEnabled } from "./
 import { getMaxSubagentDepth, setMaxSubagentDepth } from "./nested-tools.js";
 import { createOutputFilePath, ensureOutputFile, getOutputTranscriptDefault, sessionTaskDir, setOutputTranscriptDefault, streamToOutputFile, writeInitialEntry } from "./output-file.js";
 import { getPackageAgentsGate, getPackageWorkflowsGate, invalidatePackageCache, isProjectTrusted, packageNameForPath, setPackageAgentsGate, setPackageWorkflowsGate, setProjectTrusted } from "./package-resources.js";
+import { getBudgetPolicy, setBudgetPolicy } from "./process-budget.js";
 import { checkAdmission, describeBlock, mayPark, modelRef, QUOTA_RESTART_GRACE_MS } from "./quota-admission.js";
 import { SubagentScheduler } from "./schedule.js";
 import { resolveStorePath, ScheduleStore } from "./schedule-store.js";
@@ -336,6 +337,20 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
   // injected as scoped custom tools by the existing manager instead.
   if (inChildSessionContext()) return;
 
+  // A factory throw is only a load warning. Check shared-state compatibility
+  // before registering anything, and make an incompatible reload fail the
+  // bind through the host's fatal session_start path instead of loading half
+  // an extension (or continuing without the process-wide budget).
+  const StartupError = hostStartupErrorClass();
+  try {
+    getBudgetPolicy();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (!StartupError) throw new Error(message + " This host also lacks ExtensionStartupError; upgrade pi before retrying.", { cause: error });
+    pi.on("session_start", async () => { throw new StartupError(message, { cause: error }); });
+    return;
+  }
+
   // ---- Register custom notification renderer ----
   // Core collapses a custom message to this renderer's first line and draws the
   // ▸/▾ gutter itself; see ui/notification-view.ts.
@@ -377,7 +392,6 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
   // Strict agent files fail a bind by throwing the host's `ExtensionStartupError`
   // from `session_start`. A host without that class would silently degrade to
   // warnings, so refuse here, before any project agent definition is read.
-  const StartupError = hostStartupErrorClass();
   if (strictAgentFiles && !StartupError) {
     throw new Error(
       "[pi-subagents] strictAgentFiles requires a pi host that exports ExtensionStartupError, which this host lacks. " +
@@ -1683,6 +1697,13 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
     return name.replace(/-\d{8}$/, "");
   }
 
+  /** The "queued" line of a background result; names the process budget only when it is on. */
+  const queuedPositionLine = (): string => {
+    const { maxActive } = getBudgetPolicy();
+    const budget = maxActive > 0 ? `, ${maxActive} process-wide` : "";
+    return `Position: queued (max ${manager.getMaxConcurrent()} concurrent${budget})\n`;
+  };
+
   // Apply persisted settings on startup and emit `subagents:settings_loaded`.
   // Global + project merged; missing → defaults; corrupt file emits a warning
   // to stderr and falls back to defaults.
@@ -1690,6 +1711,7 @@ function activateSubagents(pi: ExtensionAPI, options: SubagentsExtensionOptions)
     {
       setMaxConcurrent: (n) => manager.setMaxConcurrent(n),
       setMaxConcurrentForeground: (n) => manager.setMaxConcurrentForeground(n),
+      setBudgetPolicy,
       setDefaultMaxTurns,
       setGraceTurns,
       setDefaultJoinMode,
@@ -2092,9 +2114,6 @@ Terse command-style prompts produce shallow, generic work.
         modelName,
         modelId,
         thinking,
-        // Only set where the agent file outranked the caller, so the surfaces can
-        // disclose a parameter that was accepted but could not take effect (#182).
-        requestedThinking: resolvedConfig.overridden?.thinking,
         // Explicit value only — the default fallback would just add noise.
         // Normalize so `0` (unlimited) doesn't surface as a misleading "max turns: 0".
         maxTurns: normalizeMaxTurns(resolvedConfig.maxTurns),
@@ -2206,19 +2225,21 @@ Terse command-style prompts produce shallow, generic work.
         // a background spawn. Previously run_in_background was silently ignored
         // on resume (this branch returned before the background branch below),
         // so a resumed agent always blocked the main loop until it finished.
+        // A detached resume hands control back while the record stays
+        // "running", and parallel tool calls can resume one agent twice in a
+        // turn, so nothing stops the model from resuming an agent mid-run.
+        // manager.resume() refuses that on both paths (it would orphan the live
+        // run's abort controller); say why here, where the model can act on it,
+        // instead of letting it read as a generic failure.
+        if (existing.status === "running" || existing.status === "queued") {
+          return textResult(
+            `Agent "${params.resume}" is still ${existing.status} — it can only be resumed once its current run finishes.\n` +
+            `Use steer_subagent to send it a message mid-run, or get_subagent_result to wait for it.`,
+          );
+        }
+
         if (runInBackground) {
           const id = existing.id;
-          // A detached resume hands control back while the record stays
-          // "running", so nothing stops the model from resuming the same agent
-          // again mid-run. manager.resume() refuses that (it would orphan the
-          // live run's abort controller); say why here, where the model can act
-          // on it, instead of letting it read as a generic failure.
-          if (existing.status === "running" || existing.status === "queued") {
-            return textResult(
-              `Agent "${params.resume}" is still ${existing.status} — it can only be resumed once its current run finishes.\n` +
-              `Use steer_subagent to send it a message mid-run, or get_subagent_result to wait for it.`,
-            );
-          }
 
           const record = await startBackgroundResume(ctx, existing, params.prompt, {
             outputTranscript,
@@ -2235,7 +2256,7 @@ Terse command-style prompts produce shallow, generic work.
             `Agent ID: ${id}\n` +
             `Type: ${existing.type}\n` +
             (record.outputFile ? `Output file: ${record.outputFile}\n` : "") +
-            (isQueued ? `Position: queued (max ${manager.getMaxConcurrent()} concurrent)\n` : "") +
+            (isQueued ? queuedPositionLine() : "") +
             `\nYou will be notified when this agent completes.\n` +
             `Use get_subagent_result to retrieve full results, or steer_subagent to send it messages.`,
             { ...detailBaseFor(record), toolUses: record.toolUses, tokens: "", durationMs: 0, status: "background" as const, agentId: id },
@@ -2292,7 +2313,7 @@ Terse command-style prompts produce shallow, generic work.
           `Type: ${displayName}\n` +
           `Description: ${params.description}\n` +
           (record?.outputFile ? `Output file: ${record.outputFile}\n` : "") +
-          (isQueued ? `Position: queued (max ${manager.getMaxConcurrent()} concurrent)\n` : "") +
+          (isQueued ? queuedPositionLine() : "") +
           `\nYou will be notified when this agent completes.\n` +
           `Use get_subagent_result to retrieve full results, or steer_subagent to send it messages.\n` +
           `Do not duplicate this agent's work.`,
@@ -3838,6 +3859,8 @@ Write the file using the write tool. Only write the file, nothing else.`;
       // goes away. undefined is dropped by JSON.stringify.
       fallbackSubagent: getFallbackSubagent(),
       // Global-only (see loadSettings): never written into the project file.
+      maxActiveSubagents: undefined,
+      nestedSubagentReserve: undefined,
       modelAliases: undefined,
       agentModels: undefined,
       reportUsage: isReportUsageEnabled(),

package/src/invocation-config.ts

@@ -143,16 +143,6 @@ export function resolveAgentInvocationConfig(
   runInBackground: boolean;
   isolated: boolean;
   isolation?: IsolationMode;
-  /**
-   * Caller thinking levels an agent file's frontmatter outranked, so surfaces
-   * can say "(asked X)" instead of presenting the effective value as requested.
-   * `model` deliberately does not behave this way: an explicit `Agent` model is
-   * an intentional dispatch choice and takes precedence over an agent default.
-   *
-   * `max_turns` is deliberately absent: no surface renders a requested-vs-
-   * effective turn limit, so recording one would be dead data.
-   */
-  overridden?: { thinking?: ThinkingLevel };
 } {
   // Precedence first, collapse second — reversing these loses the veto, since
   // an agent file's "off" only outranks a caller's "worktree" while it is still
@@ -160,10 +150,6 @@ export function resolveAgentInvocationConfig(
   const requested = agentConfig?.isolation ?? params.isolation;
   const isolation = requested === "worktree" && opts?.worktreeAllowed !== false ? "worktree" : undefined;
 
-  const overriddenThinking = agentConfig?.thinking != null && params.thinking != null
-    && agentConfig.thinking !== params.thinking
-    ? params.thinking as ThinkingLevel
-    : undefined;
   return {
     // A frontmatter model is a portable default, not a policy boundary. An
     // explicit model on the Agent call must win so an orchestrator can select a
@@ -171,16 +157,16 @@ export function resolveAgentInvocationConfig(
     // it, the global `agentModels` setting outranks the definition's own default.
     modelInput: params.model ?? configuredAgentModel(opts?.agentType ?? agentConfig?.name ?? "", agentConfig?.model),
     modelFromParams: params.model != null,
-    thinking: (agentConfig?.thinking ?? params.thinking) as ThinkingLevel | undefined,
+    // A specialist's frontmatter is a reusable default, not a policy boundary:
+    // an explicit dispatch chooses the effort for this run. Pi still clamps the
+    // selected level to the resolved model, and agent-manager records that
+    // requested-versus-effective difference after the session starts.
+    thinking: (params.thinking ?? agentConfig?.thinking) as ThinkingLevel | undefined,
     maxTurns: agentConfig?.maxTurns ?? params.max_turns,
     inheritContext: agentConfig?.inheritContext ?? params.inherit_context ?? false,
     runInBackground: agentConfig?.runInBackground ?? params.run_in_background ?? opts?.defaultRunInBackground ?? false,
     isolated: agentConfig?.isolated ?? params.isolated ?? false,
     isolation,
-    // Undefined rather than an empty object when nothing was overridden: callers
-    // spread this into the invocation snapshot, and an always-present key would
-    // put `requestedThinking: undefined` on every record.
-    overridden: overriddenThinking ? { thinking: overriddenThinking } : undefined,
   };
 }
 

package/src/nested-tools.ts

@@ -221,6 +221,15 @@ export function createNestedSubagentTools(context: NestedToolContext): ToolDefin
         if (!ownsRecord(existing, context.parentAgentId)) {
           return textResult(`Nested agent not found or not owned by this parent: "${params.resume}".`, true);
         }
+        // Two resumes of one child in the same turn (parallel tool calls) would
+        // run two prompts on one session; the manager refuses the second, and
+        // this says why instead of a generic failure.
+        if (existing.status === "running" || existing.status === "queued") {
+          return textResult(
+            `Nested agent "${params.resume}" is still ${existing.status}; it can only be resumed once its current run finishes.`,
+            true,
+          );
+        }
         // Frontmatter authoritative, as on the spawn path; the manager falls
         // back to the limit the child was spawned with, then the default.
         const resumed = await context.manager.resume(params.resume, params.prompt, signal, {

package/src/process-budget.ts

@@ -0,0 +1,343 @@
+/**
+ * process-budget.ts -- one ceiling on running subagents for the whole pi process.
+ *
+ * `maxConcurrent` and `maxConcurrentForeground` are per `AgentManager`, and
+ * there can be more than one manager per process: `/new`, `/resume`, `/fork`
+ * and `/reload` activate a fresh one and leave the previous manager alive until
+ * its background agents finish. (Subagent sessions do not activate this
+ * extension; nested children run in the parent's manager.) Those pools also
+ * exempt nested children, workflow children, scheduled jobs and resumes. The budget is the one count all of them share, kept on `globalThis`
+ * under `Symbol.for` so every manager and every module instance (a `/reload`
+ * loads a fresh copy of this file) sees the same state.
+ *
+ * Scope is the PROCESS, not the machine: two pi processes each get their own
+ * budget. It bounds running agents, not CPU, memory or commands.
+ *
+ * Every run holds one lease from the moment it is admitted until it actually
+ * settles. A parent keeps its lease while it waits on a child: releasing it
+ * around a nested call would be wrong, because pi runs a turn's tool calls in
+ * parallel and the parent's other tools are still executing.
+ *
+ * Holding parent leases is what makes a plain cap deadlock: twelve parents
+ * each waiting on a child that can never start. The reserve prevents it. With
+ * `L` the policy's `maxDepth` (one value for the whole process, NOT a branch's
+ * own cap) and `limit(j) = maxActive - nestedReserve * (L - j)`, a run at depth
+ * `d` is admitted only while, for EVERY level `j` from `d` to `L`,
+ *
+ *   active at depth <= j      < limit(j)
+ *
+ * (`j = L` is the plain `active < maxActive`). So with `maxActive: 12,
+ * nestedReserve: 2, L: 2`, at most ten top-level runs hold slots at once, and
+ * the last two only ever go to depth-2 children. Every admission keeps
+ * `count(<= j) <= limit(j)` for all `j`, releases only lower counts, and
+ * policy changes that could break it wait for an idle process (see
+ * `setBudgetPolicy`). Suppose every holder is a parent blocked on a child and
+ * `k < L` is the deepest level holding any: then `active = count(<= k) <=
+ * limit(k) < limit(k + 1) <= maxActive`, so a depth-`k+1` child fits at every
+ * level. Leaves (depth `L`) never wait on anyone, so they finish. That needs
+ * `limit` strictly increasing and `limit(1) >= 1` -- `isCoherent` -- and a run
+ * deeper than `L` refused outright (`assertWithinBudgetDepth`), since nothing
+ * reserves a slot for it. Top-level, workflow and scheduled runs all count as
+ * depth 1.
+ *
+ * Waiters are served first-come-first-served among the ELIGIBLE: a deeper
+ * waiter may pass a shallower one whose threshold is not met, which is what the
+ * reserve is for. Without that, a root at the head of the line would block the
+ * child that its own siblings are waiting on.
+ */
+
+const BUDGET_KEY = Symbol.for("pi-subagents:process-budget");
+
+/** Bumped on any incompatible change to `BudgetState`'s shape. */
+const BUDGET_VERSION = 2;
+
+/**
+ * Queued starts the budget will hold while it is enabled. Only a bound on
+ * memory and on runaway fan-out -- a full queue fails the spawn with
+ * `BUDGET_QUEUE_FULL_ERROR` instead of parking work nobody will see start.
+ */
+export const MAX_PENDING_SUBAGENTS = 128;
+
+export const DEFAULT_BUDGET_POLICY: Readonly<BudgetPolicy> = {
+  maxActive: 0,
+  nestedReserve: 2,
+  maxDepth: 2,
+};
+
+export interface BudgetPolicy {
+  /** Process-wide ceiling on running subagents. `0` = off (counted, never enforced). */
+  maxActive: number;
+  /** Slots held back per nesting level below a run, so children can always start. */
+  nestedReserve: number;
+  /**
+   * The deepest level the reserve covers: the GLOBAL `maxSubagentDepth`, so a
+   * project file cannot reshape a process-wide policy. A deeper run is refused.
+   */
+  maxDepth: number;
+}
+
+/** One admitted run. Released exactly once; later releases are no-ops. */
+export interface BudgetLease {
+  readonly depth: number;
+  released: boolean;
+}
+
+/** A start waiting for admission. */
+export interface BudgetWaiter {
+  /** Nesting depth of the run: top-level = 1. */
+  depth: number;
+  /** Local conditions the owner also needs (its own pool limits). */
+  ready: () => boolean;
+  /** Takes ownership of the lease. Must not throw; a throw is swallowed and the lease released. */
+  grant: (lease: BudgetLease) => void;
+}
+
+interface BudgetState {
+  version: number;
+  policy: BudgetPolicy;
+  /** A tightening change, applied once no lease is active (`setBudgetPolicy`). */
+  pendingPolicy: BudgetPolicy | undefined;
+  active: Set<BudgetLease>;
+  waiters: BudgetWaiter[];
+  pumping: boolean;
+  repump: boolean;
+}
+
+export const BUDGET_QUEUE_FULL_ERROR =
+  `Subagent queue is full (${MAX_PENDING_SUBAGENTS} waiting for the process-wide maxActiveSubagents limit). `
+  + "Wait for running agents to finish, or do the work directly.";
+
+function freshState(): BudgetState {
+  return {
+    version: BUDGET_VERSION,
+    policy: { ...DEFAULT_BUDGET_POLICY },
+    pendingPolicy: undefined,
+    active: new Set(),
+    waiters: [],
+    pumping: false,
+    repump: false,
+  };
+}
+
+/**
+ * The process's budget state. An incompatible version (a `/reload` onto a
+ * build that changed the shape) refuses budget operations until pi restarts.
+ * Never fork the state: two private counts could each admit the whole cap.
+ */
+function state(): BudgetState {
+  const g = globalThis as Record<symbol, unknown>;
+  const existing = g[BUDGET_KEY] as BudgetState | undefined;
+  if (existing === undefined) {
+    const created = freshState();
+    g[BUDGET_KEY] = created;
+    return created;
+  }
+  if (existing.version === BUDGET_VERSION) return existing;
+  throw new Error(
+    `[pi-subagents] Incompatible process budget v${String(existing.version)} already loaded (this build uses v${String(BUDGET_VERSION)}). `
+    + "Restart pi before starting more subagents; no private budget will be created.",
+  );
+}
+
+/** The deepest level `policy` reserves for; nesting off still means one level. */
+const topLevel = (policy: BudgetPolicy): number => Math.max(1, policy.maxDepth);
+
+/**
+ * How many runs at depth <= `level` may hold leases before a run at `level` or
+ * shallower has to wait. No floor: `isCoherent` keeps it at least one.
+ */
+export function admissionLimit(policy: BudgetPolicy, level: number): number {
+  if (policy.maxActive <= 0) return Number.POSITIVE_INFINITY;
+  return policy.maxActive - policy.nestedReserve * (topLevel(policy) - level);
+}
+
+/**
+ * Whether `policy` is deadlock-free: off, or `limit` strictly increasing from
+ * at least one at depth 1 -- a reserve of one or more, and room for one
+ * top-level run after reserving for every level below it.
+ */
+export function isCoherent(policy: BudgetPolicy): boolean {
+  if (policy.maxActive <= 0 || topLevel(policy) === 1) return true;
+  return policy.nestedReserve >= 1 && admissionLimit(policy, 1) >= 1;
+}
+
+/** Every level's limit is at least what it was, so no held lease can block a child that fit before. */
+function relaxes(from: BudgetPolicy, to: BudgetPolicy): boolean {
+  if (to.maxActive <= 0) return true;
+  if (from.maxActive <= 0 || topLevel(from) !== topLevel(to)) return false;
+  for (let level = 1; level <= topLevel(to); level++) {
+    if (admissionLimit(to, level) < admissionLimit(from, level)) return false;
+  }
+  return true;
+}
+
+export function getBudgetPolicy(): BudgetPolicy {
+  return { ...state().policy };
+}
+
+/**
+ * Replace the policy. Last writer wins: every activation in the process
+ * shares it. An incoherent policy is refused with a warning. A change that
+ * could strand a waiting child -- turning the budget on, lowering a limit,
+ * changing `maxDepth` -- is held until no lease is active, since running
+ * parents were admitted under the old limits; turning it off or raising
+ * limits applies at once.
+ */
+export function setBudgetPolicy(next: BudgetPolicy): void {
+  const policy: BudgetPolicy = {
+    maxActive: Math.max(0, Math.floor(next.maxActive)),
+    nestedReserve: Math.max(0, Math.floor(next.nestedReserve)),
+    maxDepth: Math.max(0, Math.floor(next.maxDepth)),
+  };
+  if (!isCoherent(policy)) {
+    console.warn(
+      `[pi-subagents] Ignoring maxActiveSubagents ${String(policy.maxActive)} with nestedSubagentReserve ${String(policy.nestedReserve)} `
+      + `at maxSubagentDepth ${String(policy.maxDepth)}: it could deadlock. Nesting needs a reserve of at least 1 and `
+      + "maxActiveSubagents >= nestedSubagentReserve * (maxSubagentDepth - 1) + 1.",
+    );
+    return;
+  }
+  const s = state();
+  if (s.active.size === 0 || relaxes(s.policy, policy)) {
+    s.policy = policy;
+    s.pendingPolicy = undefined;
+    pumpBudget();
+  } else {
+    s.pendingPolicy = policy;
+    console.warn(
+      `[pi-subagents] Process budget change deferred until all running subagents settle: `
+      + `maxActiveSubagents=${String(policy.maxActive)}, nestedSubagentReserve=${String(policy.nestedReserve)}, `
+      + `maxSubagentDepth=${String(policy.maxDepth)}. The previous policy remains in force; continuous work can delay this indefinitely.`,
+    );
+  }
+}
+
+/** The policy waiting for the process to go idle, if any. For diagnostics and tests. */
+export function getPendingBudgetPolicy(): BudgetPolicy | undefined {
+  const pending = state().pendingPolicy;
+  return pending === undefined ? undefined : { ...pending };
+}
+
+/**
+ * Throw when the budget is on and a run at `depth` is deeper than its policy
+ * reserves for: it could wait forever behind its own ancestors. Pass/fail is
+ * fixed for the run's life, since `maxDepth` changes only while idle.
+ */
+export function assertWithinBudgetDepth(depth: number): void {
+  const { policy } = state();
+  if (policy.maxActive > 0 && depth > topLevel(policy)) {
+    throw new Error(
+      `Nested subagent at depth ${String(depth)} exceeds the process budget's depth ${String(topLevel(policy))} `
+      + "(global maxSubagentDepth). Complete the task directly.",
+    );
+  }
+}
+
+/** Running leases and waiting starts, for diagnostics and tests. */
+export function budgetUsage(): { active: number; pending: number; maxActive: number } {
+  const s = state();
+  return { active: s.active.size, pending: s.waiters.length, maxActive: s.policy.maxActive };
+}
+
+function admits(s: BudgetState, depth: number): boolean {
+  const { policy } = s;
+  if (policy.maxActive <= 0) return true;
+  const top = topLevel(policy);
+  const level = Math.max(1, depth);
+  if (level > top) return false;
+  // Leases deeper than `top` cannot exist while it is on; clamp so they still count in the total.
+  const atDepth = new Array<number>(top + 1).fill(0);
+  for (const lease of s.active) atDepth[Math.min(top, Math.max(1, lease.depth))]++;
+  let atOrAbove = 0;
+  for (let j = 1; j <= top; j++) {
+    atOrAbove += atDepth[j];
+    if (j >= level && atOrAbove >= admissionLimit(policy, j)) return false;
+  }
+  return true;
+}
+
+function newLease(s: BudgetState, depth: number): BudgetLease {
+  const lease: BudgetLease = { depth, released: false };
+  s.active.add(lease);
+  return lease;
+}
+
+/**
+ * Take a lease now, or undefined when this depth is at its limit or an earlier
+ * eligible waiter has first claim. Completion listeners can spawn synchronously
+ * between release and drain; re-entrant grant callbacks can do the same.
+ */
+export function tryAcquireBudget(depth: number): BudgetLease | undefined {
+  const s = state();
+  if (!admits(s, depth) || s.waiters.some(waiter => admits(s, waiter.depth) && waiter.ready())) return undefined;
+  return newLease(s, depth);
+}
+
+/** Whether another waiter fits. Always true while the budget is off. */
+export function budgetHasPendingRoom(): boolean {
+  const s = state();
+  return s.policy.maxActive <= 0 || s.waiters.length < MAX_PENDING_SUBAGENTS;
+}
+
+/** Join the queue. Returns a cancel function; cancelling a granted waiter is a no-op. */
+export function enqueueBudget(waiter: BudgetWaiter): () => void {
+  state().waiters.push(waiter);
+  return () => {
+    const s = state();
+    const i = s.waiters.indexOf(waiter);
+    if (i !== -1) s.waiters.splice(i, 1);
+  };
+}
+
+/**
+ * Give a lease back. Idempotent; does not pump, so callers keep their own
+ * ordering. The last release applies a held policy change.
+ */
+export function releaseBudget(lease: BudgetLease | undefined): void {
+  if (lease === undefined || lease.released) return;
+  lease.released = true;
+  const s = state();
+  s.active.delete(lease);
+  if (s.active.size === 0 && s.pendingPolicy !== undefined) {
+    s.policy = s.pendingPolicy;
+    s.pendingPolicy = undefined;
+  }
+}
+
+/**
+ * Admit every waiter that fits, earliest first, re-scanning after each grant
+ * because a grant changes the counts (`ready()` reads the owner's pools).
+ * Re-entrant calls from inside a grant are folded into the running loop.
+ */
+export function pumpBudget(): void {
+  const s = state();
+  if (s.pumping) {
+    s.repump = true;
+    return;
+  }
+  s.pumping = true;
+  try {
+    do {
+      s.repump = false;
+      for (;;) {
+        const i = s.waiters.findIndex(w => admits(s, w.depth) && w.ready());
+        if (i === -1) break;
+        const [waiter] = s.waiters.splice(i, 1);
+        const lease = newLease(s, waiter.depth);
+        try {
+          waiter.grant(lease);
+        } catch {
+          releaseBudget(lease);
+        }
+      }
+    } while (s.repump);
+  } finally {
+    s.pumping = false;
+  }
+}
+
+/** Test-only: forget all leases and waiters and restore the default policy. */
+export function resetBudgetForTests(): void {
+  const g = globalThis as Record<symbol, unknown>;
+  g[BUDGET_KEY] = freshState();
+}

package/src/schedule.ts

@@ -357,7 +357,11 @@ export class SubagentScheduler {
     // Terminal states: completed/steered = success; error/aborted/stopped = error.
     // awaitStartup first: with isolation: "worktree" the run promise only exists
     // once the repo copy is made, and a failed copy rejects here.
-    manager.awaitStartup(agentId)
+    // The start gate comes first: `bypassQueue` skips the pool but not the
+    // process budget (`maxActiveSubagents`), so a fired job can sit "queued"
+    // with no startup and no promise yet, and would otherwise finalize at once.
+    Promise.resolve(manager.getRecord(agentId)?.startGate)
+      .then(() => manager.awaitStartup(agentId))
       .then(() => manager.getRecord(agentId)?.promise)
       .then(() => {
         const r = manager.getRecord(agentId);

package/src/settings.ts

@@ -7,6 +7,7 @@ import { dirname, join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { NO_FALLBACK } from "./agent-types.js";
 import { readEnterpriseLocalManifest } from "./enterprise-local.js";
+import { type BudgetPolicy, DEFAULT_BUDGET_POLICY } from "./process-budget.js";
 import type { AgentMentionMode, JoinMode, ViewerMarkdownMode, WidgetMode } from "./types.js";
 
 export interface SubagentsSettings {
@@ -33,6 +34,30 @@ export interface SubagentsSettings {
    * several blocking resumes in one message can still exceed the limit.
    */
   maxConcurrentForeground?: number;
+  /**
+   * Process-wide ceiling on running subagents, across every manager in this pi
+   * process: top-level, nested, workflow, scheduled, RPC and mention spawns,
+   * and resumes, in the root session and in sessions a `/new`, `/resume`,
+   * `/fork` or `/reload` left running. `0` = off, the default. The process,
+   * not the machine: two pi processes each get their own. See
+   * `process-budget.ts`.
+   *
+   * Global configuration only, like `modelAliases`: a project file's value is
+   * ignored with a warning. Shared by every activation in the process, so the
+   * last one to apply its settings wins. A change that tightens it waits until
+   * no subagent in the process holds a slot (`setBudgetPolicy`).
+   */
+  maxActiveSubagents?: number;
+  /**
+   * Slots of `maxActiveSubagents` held back per nesting level below a run, so
+   * parents that keep their slot while they wait can never starve their own
+   * children. Defaults to `2`; with the global `maxSubagentDepth: 2` that
+   * leaves `maxActiveSubagents - 2` for top-level runs. With nesting on it
+   * must be at least `1`, and `maxActiveSubagents` at least
+   * `nestedSubagentReserve * (maxSubagentDepth - 1) + 1`; a budget that
+   * breaks either is ignored with a warning, since it could deadlock.
+   */
+  nestedSubagentReserve?: number;
   /**
    * 0 = unlimited — the extension's single source of truth for that convention:
    * `normalizeMaxTurns()` in agent-runner.ts treats 0 → `undefined`, and the
@@ -357,6 +382,8 @@ export type ToolDescriptionMode = "full" | "compact" | "custom";
 export interface SettingsAppliers {
   setMaxConcurrent: (n: number) => void;
   setMaxConcurrentForeground: (n: number) => void;
+  /** The process budget, from `loadBudgetPolicy`: global configuration only. */
+  setBudgetPolicy: (policy: BudgetPolicy) => void;
   setDefaultMaxTurns: (n: number) => void;
   setGraceTurns: (n: number) => void;
   setDefaultJoinMode: (mode: JoinMode) => void;
@@ -442,6 +469,20 @@ function sanitize(raw: unknown): SubagentsSettings {
   ) {
     out.maxConcurrentForeground = r.maxConcurrentForeground as number;
   }
+  if (
+    Number.isInteger(r.maxActiveSubagents) &&
+    (r.maxActiveSubagents as number) >= 0 &&
+    (r.maxActiveSubagents as number) <= MAX_CONCURRENT_CEILING
+  ) {
+    out.maxActiveSubagents = r.maxActiveSubagents as number;
+  }
+  if (
+    Number.isInteger(r.nestedSubagentReserve) &&
+    (r.nestedSubagentReserve as number) >= 0 &&
+    (r.nestedSubagentReserve as number) <= MAX_CONCURRENT_CEILING
+  ) {
+    out.nestedSubagentReserve = r.nestedSubagentReserve as number;
+  }
   if (
     Number.isInteger(r.defaultMaxTurns) &&
     (r.defaultMaxTurns as number) >= 0 &&
@@ -617,16 +658,47 @@ function readSettingsFile(path: string): SubagentsSettings {
 export function loadSettings(cwd: string = process.cwd()): SubagentsSettings {
   // Aliases pick the provider a subagent runs on, so they are machine
   // configuration: a cloned repo's project file must not redirect them.
-  const { modelAliases: projectModelAliases, agentModels: projectAgentModels, ...project } = readSettingsFile(projectPath(cwd));
+  const {
+    modelAliases: projectModelAliases,
+    agentModels: projectAgentModels,
+    maxActiveSubagents: projectMaxActive,
+    nestedSubagentReserve: projectReserve,
+    ...project
+  } = readSettingsFile(projectPath(cwd));
   if (projectModelAliases !== undefined) {
     console.warn("[pi-subagents] Ignoring modelAliases in project .pi/subagents.json: aliases are read from trusted global configuration only.");
   }
   if (projectAgentModels !== undefined) {
     console.warn("[pi-subagents] Ignoring agentModels in project .pi/subagents.json: per-agent models are read from trusted global configuration only.");
   }
+  // The process budget spans every session in the process, so no one
+  // project's file may set it, least of all a cloned one lifting the cap.
+  if (projectMaxActive !== undefined || projectReserve !== undefined) {
+    console.warn("[pi-subagents] Ignoring maxActiveSubagents/nestedSubagentReserve in project .pi/subagents.json: the process-wide budget is read from global configuration only.");
+  }
+  return { ...trustedSettings(), ...project };
+}
+
+/** Global settings with the enterprise manifest over them: the layer a project file cannot touch. */
+function trustedSettings(): SubagentsSettings {
   const enterprise = readEnterpriseLocalManifest()?.subagents;
   const enterpriseSettings = enterprise === undefined ? {} : sanitize(enterprise);
-  return { ...readSettingsFile(globalPath()), ...enterpriseSettings, ...project };
+  return { ...readSettingsFile(globalPath()), ...enterpriseSettings };
+}
+
+/**
+ * The process budget's policy, from trusted configuration only -- including
+ * its depth, the GLOBAL `maxSubagentDepth`: a project file may still change
+ * how deep its own sessions nest, but not what the process-wide reserve
+ * covers. A missing key means its default, so removing the cap turns it off.
+ */
+export function loadBudgetPolicy(): BudgetPolicy {
+  const trusted = trustedSettings();
+  return {
+    maxActive: trusted.maxActiveSubagents ?? DEFAULT_BUDGET_POLICY.maxActive,
+    nestedReserve: trusted.nestedSubagentReserve ?? DEFAULT_BUDGET_POLICY.nestedReserve,
+    maxDepth: trusted.maxSubagentDepth ?? DEFAULT_BUDGET_POLICY.maxDepth,
+  };
 }
 
 /**
@@ -706,6 +778,7 @@ export function applyAndEmitLoaded(
 ): SubagentsSettings {
   const settings = loadSettings(cwd);
   applySettings(settings, appliers);
+  appliers.setBudgetPolicy(loadBudgetPolicy());
   emit("subagents:settings_loaded", { settings });
   return settings;
 }