@algosuite/vo-mcp 0.2.0-beta.28 → 0.2.0-beta.29

package/dist/cli.js

@@ -1405,7 +1405,7 @@ __export(memory_knowledge_bridge_exports, {
   extractMemoryTitle: () => extractMemoryTitle,
   upsertMemoryFilesAsKnowledge: () => upsertMemoryFilesAsKnowledge
 });
-import { existsSync as existsSync5, readdirSync as readdirSync4, readFileSync as readFileSync7 } from "node:fs";
+import { existsSync as existsSync5, readdirSync as readdirSync4, readFileSync as readFileSync8 } from "node:fs";
 function extractMemoryTitle(fileName, content) {
   const frontmatter = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
   if (frontmatter) {
@@ -1438,7 +1438,7 @@ async function upsertMemoryFilesAsKnowledge(options) {
   const failures = [];
   for (const fileName of files) {
     try {
-      const content = readFileSync7(resolveMemoryFilePath(memoryDir, fileName), "utf8");
+      const content = readFileSync8(resolveMemoryFilePath(memoryDir, fileName), "utf8");
       if (content.length > CONTENT_HARD_LIMIT) {
         failures.push(`${fileName}: ${content.length} chars exceeds the ${CONTENT_HARD_LIMIT} server limit \u2014 split the memory file`);
         continue;
@@ -1503,9 +1503,9 @@ __export(sync_config_exports, {
   isNoopSyncReason: () => isNoopSyncReason,
   runMemorySync: () => runMemorySync
 });
-import { homedir as homedir5 } from "node:os";
-import { join as join7 } from "node:path";
-import { existsSync as existsSync6, mkdirSync as mkdirSync4, readFileSync as readFileSync8, writeFileSync as writeFileSync3, readdirSync as readdirSync5 } from "node:fs";
+import { homedir as homedir6 } from "node:os";
+import { join as join8 } from "node:path";
+import { existsSync as existsSync6, mkdirSync as mkdirSync5, readFileSync as readFileSync9, writeFileSync as writeFileSync4, readdirSync as readdirSync5 } from "node:fs";
 function isToolInput22(v) {
   if (typeof v !== "object" || v === null) return false;
   const o = v;
@@ -1518,7 +1518,7 @@ function deriveProjectSlug(cwd) {
 }
 function getMemoryDir(cwd) {
   const slug = deriveProjectSlug(cwd);
-  return join7(homedir5(), ".claude", "projects", slug, "memory");
+  return join8(homedir6(), ".claude", "projects", slug, "memory");
 }
 async function pullMemory(controlPlaneUrl, token, memoryDir, fetchFn) {
   const url = `${controlPlaneUrl}/api/v1/agent-config/memory/me`;
@@ -1540,10 +1540,10 @@ async function pullMemory(controlPlaneUrl, token, memoryDir, fetchFn) {
     entry,
     filePath: resolveMemoryFilePath(memoryDir, entry.file_name)
   }));
-  mkdirSync4(memoryDir, { recursive: true });
+  mkdirSync5(memoryDir, { recursive: true });
   const files = [];
   for (const { entry, filePath } of writes) {
-    writeFileSync3(filePath, entry.content, "utf8");
+    writeFileSync4(filePath, entry.content, "utf8");
     files.push(entry.file_name);
   }
   return { pulled: data.entries.length, files };
@@ -1554,7 +1554,7 @@ async function pushMemory(controlPlaneUrl, token, memoryDir, sessionId, fetchFn)
   }
   const localFiles = readdirSync5(memoryDir).filter((f) => f.endsWith(".md")).map((f) => ({
     file_name: f,
-    content: readFileSync8(resolveMemoryFilePath(memoryDir, f), "utf8"),
+    content: readFileSync9(resolveMemoryFilePath(memoryDir, f), "utf8"),
     entry_type: f === "MEMORY.md" ? "index" : "topic"
   }));
   if (localFiles.length === 0) {
@@ -1734,9 +1734,9 @@ var init_sync_config = __esm({
 });
 
 // src/cli.ts
-import { homedir as homedir6, hostname } from "node:os";
+import { homedir as homedir7, hostname } from "node:os";
 import { randomUUID as randomUUID5 } from "node:crypto";
-import { join as join10 } from "node:path";
+import { join as join11 } from "node:path";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/server.ts
@@ -5394,9 +5394,324 @@ async function handleReportSessionState(deps, rawInput, _signal) {
 // src/tools/session/spawn-successor.ts
 init_common();
 import { spawn } from "node:child_process";
+import { homedir as homedir5 } from "node:os";
+import { join as join7 } from "node:path";
+import { existsSync as existsSync4, mkdirSync as mkdirSync4, openSync as openSync2, readFileSync as readFileSync7, readdirSync as readdirSync3, statSync as statSync3 } from "node:fs";
+
+// src/swarm/tier-binding.ts
+var SWARM_TIERS = Object.freeze([
+  "tier1_subscription",
+  "tier1_local",
+  "tier2_user_key",
+  "tier3_platform_key",
+  "refused",
+  "unresolved"
+]);
+var TIER_ADMITS_SPAWN = /* @__PURE__ */ new Set([
+  "tier1_subscription",
+  "tier1_local",
+  "tier2_user_key",
+  "tier3_platform_key"
+]);
+var SWARM_TIER_BINDING_ENV = "VO_SWARM_TIER_BINDING";
+var MAX_BOUND_SUBAGENTS = 20;
+function isPositiveCap(cap) {
+  return typeof cap === "number" && Number.isFinite(cap) && cap > 0;
+}
+function unresolvedBinding(swarmId, nowIso, reason) {
+  return {
+    schema_version: 1,
+    swarm_id: swarmId,
+    tier: "unresolved",
+    agent: null,
+    reason,
+    exhausted_agents: [],
+    subagent_budget: 0,
+    spend_cap_usd: null,
+    resolved_at: nowIso
+  };
+}
+function serializeSwarmTierBinding(binding) {
+  return JSON.stringify(binding);
+}
+function parseSwarmTierBinding(raw, nowIso) {
+  if (typeof raw !== "string" || raw.trim().length === 0) {
+    return unresolvedBinding("", nowIso, "no swarm tier binding present in the environment");
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return unresolvedBinding("", nowIso, "swarm tier binding is not valid JSON");
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return unresolvedBinding("", nowIso, "swarm tier binding is not an object");
+  }
+  const o = parsed;
+  const swarmId = typeof o["swarm_id"] === "string" ? o["swarm_id"] : "";
+  if (o["schema_version"] !== 1) {
+    return unresolvedBinding(swarmId, nowIso, "swarm tier binding has an unsupported schema_version");
+  }
+  const tier = o["tier"];
+  if (typeof tier !== "string" || !SWARM_TIERS.includes(tier)) {
+    return unresolvedBinding(swarmId, nowIso, "swarm tier binding names an unknown tier");
+  }
+  const budget = o["subagent_budget"];
+  const cap = o["spend_cap_usd"];
+  const capNum = isPositiveCap(cap) ? cap : null;
+  if (tier === "tier3_platform_key" && capNum === null) {
+    return unresolvedBinding(
+      swarmId,
+      nowIso,
+      "inherited tier3_platform_key binding carries no positive numeric spend cap \u2014 refusing an uncapped platform-billed fan-out"
+    );
+  }
+  return {
+    schema_version: 1,
+    swarm_id: swarmId,
+    tier,
+    agent: typeof o["agent"] === "string" ? o["agent"] : null,
+    reason: typeof o["reason"] === "string" ? o["reason"] : "inherited binding carried no reason",
+    exhausted_agents: Array.isArray(o["exhausted_agents"]) ? o["exhausted_agents"].filter((v) => typeof v === "string") : [],
+    subagent_budget: typeof budget === "number" && Number.isFinite(budget) && budget > 0 ? Math.min(Math.floor(budget), MAX_BOUND_SUBAGENTS) : 0,
+    spend_cap_usd: capNum,
+    resolved_at: typeof o["resolved_at"] === "string" ? o["resolved_at"] : nowIso
+  };
+}
+function inheritSwarmTierBinding(env, nowIso) {
+  return parseSwarmTierBinding(env[SWARM_TIER_BINDING_ENV], nowIso);
+}
+function bindingEnvFragment(binding) {
+  return { [SWARM_TIER_BINDING_ENV]: serializeSwarmTierBinding(binding) };
+}
+function childBindingEnvFragment(binding, allocatedCapUsd = null) {
+  return bindingEnvFragment(childBinding(binding, allocatedCapUsd));
+}
+function admitSubagentSpawn(binding, spawnsSoFar = 0) {
+  if (!TIER_ADMITS_SPAWN.has(binding.tier)) {
+    return { allowed: false, reason: `tier '${binding.tier}' admits no spawn: ${binding.reason}` };
+  }
+  if (binding.tier === "tier3_platform_key" && !isPositiveCap(binding.spend_cap_usd)) {
+    return {
+      allowed: false,
+      reason: `swarm ${binding.swarm_id} is tier3_platform_key with no positive spend cap \u2014 refusing to spend the platform owner's money uncapped`
+    };
+  }
+  if (!Number.isFinite(spawnsSoFar) || spawnsSoFar < 0) {
+    return { allowed: false, reason: "spawn counter is not a finite non-negative number" };
+  }
+  if (spawnsSoFar >= binding.subagent_budget) {
+    return {
+      allowed: false,
+      reason: `swarm ${binding.swarm_id} exhausted its bound subagent budget (${binding.subagent_budget})`
+    };
+  }
+  return { allowed: true, reason: `admitted under tier '${binding.tier}'` };
+}
+function childBinding(binding, allocatedCapUsd = null) {
+  const allocated = isPositiveCap(allocatedCapUsd) ? allocatedCapUsd : null;
+  const parentCap = isPositiveCap(binding.spend_cap_usd) ? binding.spend_cap_usd : null;
+  return {
+    ...binding,
+    subagent_budget: Math.max(0, binding.subagent_budget - 1),
+    // A child never carries more than its parent, whatever the ledger says: a
+    // forged or hand-edited pool cannot inflate a descendant above the binding
+    // it descends from.
+    spend_cap_usd: allocated === null || parentCap === null ? null : Math.min(allocated, parentCap)
+  };
+}
+function agentBindingRefusal(binding, requestedAgent) {
+  const requested = typeof requestedAgent === "string" ? requestedAgent.trim() : "";
+  if (requested.length === 0) return null;
+  if (binding.agent !== null && requested === binding.agent) return null;
+  return `swarm '${binding.swarm_id}' is bound to agent '${binding.agent ?? "none"}' under tier '${binding.tier}'; a caller-supplied agent '${requested}' would move this fan-out onto a different payer \u2014 refusing (the tier is decided once, at admission, and an inherited binding cannot be renegotiated)`;
+}
+
+// src/swarm/successor-launch.ts
+var AGENT_LAUNCH_SHAPES = Object.freeze({
+  claude: {
+    bin: "claude",
+    baseArgs: ["-p", "--permission-mode", "acceptEdits"],
+    enforcesMaxTurns: true,
+    maxTurnsFlag: "--max-turns",
+    windowsShellSafe: true
+  },
+  codex: {
+    bin: "codex",
+    baseArgs: ["exec", "--json", "-c", 'approval_policy="never"', "--sandbox", "workspace-write", "--skip-git-repo-check"],
+    enforcesMaxTurns: false,
+    // `-` makes codex read the prompt from stdin (injection-safe), matching how
+    // codex-runner.mjs already spawns it.
+    trailingArgs: ["-"],
+    // `approval_policy="never"` carries embedded quotes; cmd.exe re-parsing is
+    // unverified, so win32 refuses rather than risking a mangled sandbox flag.
+    windowsShellSafe: false
+  }
+});
+function resolveSuccessorLaunch(input) {
+  const agent = typeof input.agent === "string" ? input.agent.trim() : "";
+  if (!agent) {
+    return { ok: false, reason: "no agent bound for this spawn \u2014 refusing rather than defaulting to claude" };
+  }
+  const shape = AGENT_LAUNCH_SHAPES[agent];
+  if (!shape) {
+    const known = Object.keys(AGENT_LAUNCH_SHAPES).join(", ");
+    return {
+      ok: false,
+      reason: `no known headless launch shape for agent '${agent}' (known: ${known}) \u2014 refusing rather than guessing its argv`
+    };
+  }
+  const wantsMaxTurns = Number.isInteger(input.maxTurns) && input.maxTurns > 0;
+  if (wantsMaxTurns && !shape.enforcesMaxTurns) {
+    return {
+      ok: false,
+      reason: `agent '${agent}' cannot enforce a max_turns cap \u2014 refusing rather than spawning it unbounded`
+    };
+  }
+  const platform = input.platform ?? process.platform;
+  if (platform === "win32" && !shape.windowsShellSafe) {
+    return {
+      ok: false,
+      reason: `agent '${agent}' has an argv whose behaviour under Windows cmd.exe re-parsing is unverified \u2014 refusing rather than emitting a command line that may mean something else`
+    };
+  }
+  const args = [...shape.baseArgs];
+  if (wantsMaxTurns && shape.maxTurnsFlag) {
+    args.push(shape.maxTurnsFlag, String(input.maxTurns));
+  }
+  if (shape.trailingArgs) args.push(...shape.trailingArgs);
+  return { ok: true, agent, bin: shape.bin, args };
+}
+
+// src/swarm/spawn-ledger.ts
+import { mkdirSync as mkdirSync3, openSync, closeSync, readFileSync as readFileSync6, writeFileSync as writeFileSync3 } from "node:fs";
 import { homedir as homedir4 } from "node:os";
 import { join as join6 } from "node:path";
-import { existsSync as existsSync4, mkdirSync as mkdirSync3, openSync, readFileSync as readFileSync6, readdirSync as readdirSync3, statSync as statSync3 } from "node:fs";
+var SWARM_LEDGER_DIR_ENV = "VO_SWARM_LEDGER_DIR";
+function resolveLedgerDir(env) {
+  const override = env[SWARM_LEDGER_DIR_ENV];
+  if (typeof override === "string" && override.trim().length > 0) return override.trim();
+  return join6(homedir4(), ".vo", "swarm-ledger");
+}
+function sanitizeSwarmId(raw) {
+  if (typeof raw !== "string") return null;
+  const id = raw.trim();
+  if (id.length === 0 || id.length > 128) return null;
+  if (!/^[A-Za-z0-9._-]+$/u.test(id)) return null;
+  if (id === "." || id === "..") return null;
+  return id;
+}
+var CEILING_FILE = "ceiling.json";
+function createExclusive(path3, contents) {
+  let fd;
+  try {
+    fd = openSync(path3, "wx");
+  } catch {
+    return false;
+  }
+  try {
+    writeFileSync3(fd, contents, "utf8");
+  } finally {
+    closeSync(fd);
+  }
+  return true;
+}
+function capToCents(cap) {
+  return isPositiveCap(cap) ? Math.round(cap * 100) : 0;
+}
+function readOrRecordLedgerHead(swarmDir, proposedCeiling, proposedCapCents, nowIso) {
+  const path3 = join6(swarmDir, CEILING_FILE);
+  const head = JSON.stringify({
+    ceiling: proposedCeiling,
+    cap_cents: proposedCapCents,
+    recorded_at: nowIso
+  });
+  if (createExclusive(path3, head)) {
+    return { ceiling: proposedCeiling, capCents: proposedCapCents };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync6(path3, "utf8"));
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+  const record = parsed;
+  const recorded = record["ceiling"];
+  if (typeof recorded !== "number" || !Number.isFinite(recorded) || recorded < 1) return null;
+  const recordedCap = record["cap_cents"];
+  const capCents = typeof recordedCap === "number" && Number.isFinite(recordedCap) && recordedCap > 0 ? Math.floor(recordedCap) : 0;
+  return { ceiling: Math.min(Math.floor(recorded), MAX_BOUND_SUBAGENTS), capCents };
+}
+var claimSpawnSlot = ({ swarmId, proposedCeiling, proposedCapUsd, dir, nowIso }) => {
+  const id = sanitizeSwarmId(swarmId);
+  if (id === null) {
+    return {
+      ok: false,
+      reason: `swarm id ${JSON.stringify(swarmId)} is absent or unusable as a ledger key \u2014 refusing a spawn that cannot be counted against a fan-out ceiling`
+    };
+  }
+  const proposed = Number.isFinite(proposedCeiling) ? Math.floor(proposedCeiling) : 0;
+  if (proposed < 1) {
+    return { ok: false, reason: `swarm '${id}' proposes a ceiling of ${proposed} \u2014 no allowance to claim` };
+  }
+  const swarmDir = join6(dir, id);
+  try {
+    mkdirSync3(swarmDir, { recursive: true });
+  } catch (err) {
+    return {
+      ok: false,
+      reason: `swarm '${id}' ledger directory is unwritable (${err instanceof Error ? err.message : String(err)}) \u2014 refusing rather than spawning uncounted`
+    };
+  }
+  const wantedCents = capToCents(proposedCapUsd);
+  const head = readOrRecordLedgerHead(swarmDir, Math.min(proposed, MAX_BOUND_SUBAGENTS), wantedCents, nowIso);
+  if (head === null) {
+    return { ok: false, reason: `swarm '${id}' ledger carries no readable ceiling \u2014 refusing rather than spawning uncounted` };
+  }
+  const { ceiling, capCents } = head;
+  const shareCents = capCents > 0 ? Math.floor(capCents / ceiling) : 0;
+  if (wantedCents > 0 && shareCents < 1) {
+    return {
+      ok: false,
+      reason: `swarm '${id}' has no spend allowance left to debit (recorded pool $${(capCents / 100).toFixed(2)} across a ceiling of ${ceiling} leaves under one cent per spawn) \u2014 refusing a platform-billed spawn it cannot fund`
+    };
+  }
+  for (let slot = 0; slot < ceiling; slot++) {
+    const debitedCents = shareCents;
+    const remainingCents = capCents > 0 ? capCents - (slot + 1) * shareCents : 0;
+    const claimed = createExclusive(
+      join6(swarmDir, `slot-${slot}.json`),
+      JSON.stringify({
+        slot,
+        ceiling,
+        pid: process.pid,
+        claimed_at: nowIso,
+        // The debit record. Durable and atomic with the claim: this file is
+        // created with O_EXCL, so exactly one claimant ever writes this line.
+        cap_cents_pool: capCents,
+        cap_cents_debited: debitedCents,
+        cap_cents_remaining: remainingCents
+      })
+    );
+    if (claimed) {
+      return {
+        ok: true,
+        slot,
+        ceiling,
+        remaining: ceiling - slot - 1,
+        capUsd: debitedCents > 0 ? debitedCents / 100 : null,
+        capRemainingUsd: capCents > 0 ? remainingCents / 100 : null
+      };
+    }
+  }
+  return {
+    ok: false,
+    reason: `swarm '${id}' has spent its whole fan-out ceiling (${ceiling} spawns across every generation) \u2014 refusing`
+  };
+};
+
+// src/tools/session/spawn-successor.ts
 var TOOL_NAME20 = "vo_spawn_successor";
 var MAX_HANDOFF_BYTES = 64e3;
 var inputSchema20 = {
@@ -5417,11 +5732,16 @@ var inputSchema20 = {
     max_turns: {
       type: "number",
       description: "Optional --max-turns bound for the successor."
+    },
+    agent: {
+      type: "string",
+      description: `Which agent to spawn ('claude' | 'codex'). Normally omitted: the agent comes from the swarm tier binding inherited via ${SWARM_TIER_BINDING_ENV}. When a binding IS inherited this may only RESTATE the bound agent \u2014 an agent that contradicts the binding is REFUSED, because a different agent is a different payer and the payer was decided once, at admission.`
     }
   },
   required: [],
   additionalProperties: false
 };
+var RETIRED_COUNTER_INPUT = "spawns_so_far";
 var description20 = "Mode B auto-handoff (roadmap \xA73.4): spawn a DETACHED headless `claude -p` successor with a handoff doc pre-injected into its prompt. Defaults to the newest handoff in ~/.vo/handoffs/. Returns {spawned, pid, log_path, handoff_path}. The successor works under the same gates as any session (ADR-001: verify-before-act, human merge approval) \u2014 this tool never fires autonomously.";
 function isToolInput20(v) {
   if (typeof v !== "object" || v === null) return false;
@@ -5430,12 +5750,18 @@ function isToolInput20(v) {
   if (o["goal"] !== void 0 && typeof o["goal"] !== "string") return false;
   if (o["cwd"] !== void 0 && typeof o["cwd"] !== "string") return false;
   if (o["max_turns"] !== void 0 && typeof o["max_turns"] !== "number") return false;
+  if (o["agent"] !== void 0 && typeof o["agent"] !== "string") return false;
   return true;
 }
-function newestHandoff(dir = join6(homedir4(), ".vo", "handoffs")) {
+function retiredCounterRefusal(v) {
+  if (typeof v !== "object" || v === null) return null;
+  if (!(RETIRED_COUNTER_INPUT in v)) return null;
+  return `\`${RETIRED_COUNTER_INPUT}\` is no longer accepted: a spawn counter supplied by the process being bounded bounds nothing, and an absent one read as zero. The fan-out ceiling is now enforced by the durable per-swarm spawn ledger; remove the field.`;
+}
+function newestHandoff(dir = join7(homedir5(), ".vo", "handoffs")) {
   try {
-    const entries = readdirSync3(dir).filter((f) => f.endsWith(".md")).map((f) => ({ f, m: statSync3(join6(dir, f)).mtimeMs })).sort((a, b) => b.m - a.m);
-    return entries.length > 0 && entries[0] ? join6(dir, entries[0].f) : null;
+    const entries = readdirSync3(dir).filter((f) => f.endsWith(".md")).map((f) => ({ f, m: statSync3(join7(dir, f)).mtimeMs })).sort((a, b) => b.m - a.m);
+    return entries.length > 0 && entries[0] ? join7(dir, entries[0].f) : null;
   } catch {
     return null;
   }
@@ -5479,9 +5805,87 @@ function buildSuccessorArgs(maxTurns) {
   }
   return args;
 }
+function resolveSpawnPlan(env, input, nowIso, platform = process.platform, claim = claimSpawnSlot) {
+  const rawBinding = env[SWARM_TIER_BINDING_ENV];
+  const hasBinding = typeof rawBinding === "string" && rawBinding.trim().length > 0;
+  if (!hasBinding) {
+    const explicit = input.agent?.trim();
+    if (explicit) {
+      const resolved2 = resolveSuccessorLaunch({ agent: explicit, maxTurns: input.max_turns, platform });
+      if (!resolved2.ok) return { ok: false, reason: resolved2.reason, tier: "unbound" };
+      return {
+        ok: true,
+        bin: resolved2.bin,
+        args: resolved2.args,
+        agent: resolved2.agent,
+        tier: "unbound",
+        bound: false,
+        env: {},
+        slot: null,
+        capUsd: null,
+        capRemainingUsd: null
+      };
+    }
+    return {
+      ok: true,
+      bin: "claude",
+      args: buildSuccessorArgs(input.max_turns),
+      agent: "claude",
+      tier: "unbound",
+      bound: false,
+      env: {},
+      slot: null,
+      capUsd: null,
+      capRemainingUsd: null
+    };
+  }
+  const binding = inheritSwarmTierBinding(env, nowIso);
+  const admission = admitSubagentSpawn(binding);
+  if (!admission.allowed) {
+    return { ok: false, reason: admission.reason, tier: binding.tier };
+  }
+  const agentRefusal = agentBindingRefusal(binding, input.agent);
+  if (agentRefusal !== null) return { ok: false, reason: agentRefusal, tier: binding.tier };
+  const resolved = resolveSuccessorLaunch({
+    agent: binding.agent,
+    maxTurns: input.max_turns,
+    platform
+  });
+  if (!resolved.ok) return { ok: false, reason: resolved.reason, tier: binding.tier };
+  const slot = claim({
+    swarmId: binding.swarm_id,
+    proposedCeiling: binding.subagent_budget,
+    // The spend-cap POOL, recorded once per swarm exactly like the ceiling. The
+    // child's cap is DEBITED from it below, not recomputed from this binding.
+    proposedCapUsd: binding.spend_cap_usd,
+    dir: resolveLedgerDir(env),
+    nowIso
+  });
+  if (!slot.ok) return { ok: false, reason: slot.reason, tier: binding.tier };
+  return {
+    ok: true,
+    bin: resolved.bin,
+    args: resolved.args,
+    agent: resolved.agent,
+    tier: binding.tier,
+    bound: true,
+    // Re-export the same TIER with a DECREMENTED budget and the spend cap the
+    // ledger just DEBITED. Exporting the binding verbatim (what this did before
+    // #9312) meant the child re-read the full budget and every generation
+    // restarted at zero. Recomputing the cap from THIS binding (what #9312 did)
+    // bounded a chain but not a tree: three siblings each re-halved the parent's
+    // untouched $50 and walked away with $75 between them.
+    env: childBindingEnvFragment(binding, slot.capUsd),
+    slot: slot.slot,
+    capUsd: slot.capUsd,
+    capRemainingUsd: slot.capRemainingUsd
+  };
+}
 async function handleSpawnSuccessor(_deps, rawInput, _signal, spawnImpl = spawn) {
+  const retired = retiredCounterRefusal(rawInput);
+  if (retired !== null) throw invalidParams(TOOL_NAME20, retired);
   if (!isToolInput20(rawInput)) {
-    throw invalidParams(TOOL_NAME20, "invalid input. Optional: { handoff_path, goal, cwd, max_turns }.");
+    throw invalidParams(TOOL_NAME20, "invalid input. Optional: { handoff_path, goal, cwd, max_turns, agent }.");
   }
   const handoffPath = rawInput.handoff_path?.trim() || newestHandoff();
   if (!handoffPath || !existsSync4(handoffPath)) {
@@ -5494,20 +5898,37 @@ async function handleSpawnSuccessor(_deps, rawInput, _signal, spawnImpl = spawn)
       }
     });
   }
-  const handoff = readFileSync6(handoffPath, "utf8").slice(0, MAX_HANDOFF_BYTES);
+  const handoff = readFileSync7(handoffPath, "utf8").slice(0, MAX_HANDOFF_BYTES);
   const prompt = buildSuccessorPrompt(handoff, rawInput.goal);
-  const logDir = process.env["VO_MCP_SUCCESSOR_LOG_DIR"]?.trim() || join6(homedir4(), ".vo", "successors");
-  mkdirSync3(logDir, { recursive: true });
-  const logPath = join6(logDir, `successor-${Date.now()}.log`);
-  const logFd = openSync(logPath, "a");
-  const child = spawnImpl("claude", buildSuccessorArgs(rawInput.max_turns), {
+  const plan = resolveSpawnPlan(process.env, rawInput, (/* @__PURE__ */ new Date()).toISOString());
+  if (!plan.ok) {
+    return jsonContent({
+      tool: TOOL_NAME20,
+      schema_version: 1,
+      payload: {
+        spawned: false,
+        reason: `swarm tier binding refused this spawn: ${plan.reason}`,
+        tier: plan.tier,
+        handoff_path: handoffPath
+      }
+    });
+  }
+  const logDir = process.env["VO_MCP_SUCCESSOR_LOG_DIR"]?.trim() || join7(homedir5(), ".vo", "successors");
+  mkdirSync4(logDir, { recursive: true });
+  const logPath = join7(logDir, `successor-${Date.now()}.log`);
+  const logFd = openSync2(logPath, "a");
+  const child = spawnImpl(plan.bin, [...plan.args], {
     cwd: rawInput.cwd?.trim() || process.cwd(),
     detached: true,
     stdio: ["pipe", logFd, logFd],
-    // Windows: `claude` is a .cmd shim — needs a shell to resolve. The prompt
-    // goes via STDIN below, never argv, so the shell never sees it.
+    // Windows: the agent CLIs are .cmd shims — they need a shell to resolve.
+    // The prompt goes via STDIN below, never argv, so the shell never sees it.
     shell: process.platform === "win32",
-    windowsHide: true
+    windowsHide: true,
+    // Carry the SAME binding to the child. Without this the successor inherits
+    // no tier and re-resolves its own — which is the split-payer defect one
+    // generation down.
+    ...plan.bound ? { env: { ...process.env, ...plan.env } } : {}
   });
   let spawnError = null;
   child.on("error", (e) => {
@@ -5523,7 +5944,20 @@ async function handleSpawnSuccessor(_deps, rawInput, _signal, spawnImpl = spawn)
   return jsonContent({
     tool: TOOL_NAME20,
     schema_version: 1,
-    payload: spawnError ? { spawned: false, reason: `spawn failed: ${spawnError}`, handoff_path: handoffPath } : { spawned: true, pid: child.pid ?? null, log_path: logPath, handoff_path: handoffPath }
+    payload: spawnError ? { spawned: false, reason: `spawn failed: ${spawnError}`, agent: plan.agent, tier: plan.tier, handoff_path: handoffPath } : {
+      spawned: true,
+      pid: child.pid ?? null,
+      log_path: logPath,
+      handoff_path: handoffPath,
+      agent: plan.agent,
+      tier: plan.tier,
+      tier_bound: plan.bound,
+      ledger_slot: plan.slot,
+      // The debit, surfaced so an operator can reconcile a fan-out's spend
+      // against the pool without reading the ledger directory by hand.
+      ledger_cap_usd: plan.capUsd,
+      ledger_cap_remaining_usd: plan.capRemainingUsd
+    }
   });
 }
 
@@ -5886,11 +6320,11 @@ async function handleHqWhiteboardRead(_deps, rawInput, signal) {
 
 // src/tools/skills/skill-corpus.ts
 import { existsSync as existsSync7, statSync as statSync5 } from "node:fs";
-import { dirname as dirname5, isAbsolute, join as join9, resolve as resolve2 } from "node:path";
+import { dirname as dirname5, isAbsolute, join as join10, resolve as resolve2 } from "node:path";
 
 // ../skill-registry/src/loader.ts
-import { readdirSync as readdirSync6, readFileSync as readFileSync9, statSync as statSync4 } from "node:fs";
-import { join as join8 } from "node:path";
+import { readdirSync as readdirSync6, readFileSync as readFileSync10, statSync as statSync4 } from "node:fs";
+import { join as join9 } from "node:path";
 var InvalidSkillFrontmatterError = class extends Error {
   constructor(skillFile, reason) {
     super(`Invalid frontmatter in ${skillFile}: ${reason}`);
@@ -5943,7 +6377,7 @@ function loadSkillsFromDir(skillsDir) {
   const entries = readdirSync6(skillsDir);
   const skills = [];
   for (const entry of entries) {
-    const entryPath = join8(skillsDir, entry);
+    const entryPath = join9(skillsDir, entry);
     let stat;
     try {
       stat = statSync4(entryPath);
@@ -5951,10 +6385,10 @@ function loadSkillsFromDir(skillsDir) {
       continue;
     }
     if (!stat.isDirectory()) continue;
-    const skillFile = join8(entryPath, "SKILL.md");
+    const skillFile = join9(entryPath, "SKILL.md");
     let raw;
     try {
-      raw = readFileSync9(skillFile, "utf8");
+      raw = readFileSync10(skillFile, "utf8");
     } catch {
       continue;
     }
@@ -6000,7 +6434,7 @@ function resolveSkillsDir(env = process.env, startDir = process.cwd()) {
   }
   let dir = resolve2(startDir);
   for (let i = 0; i < MAX_WALK_UP_LEVELS; i += 1) {
-    const candidate = join9(dir, ".claude", "skills");
+    const candidate = join10(dir, ".claude", "skills");
     if (existsSync7(candidate) && statSync5(candidate).isDirectory()) return candidate;
     const parent = dirname5(dir);
     if (parent === dir) break;
@@ -6362,7 +6796,7 @@ function createServer(options) {
 
 // src/cache/sqlite-cache.ts
 import { createHash as createHash3 } from "node:crypto";
-import { chmodSync as chmodSync3, mkdirSync as mkdirSync5 } from "node:fs";
+import { chmodSync as chmodSync3, mkdirSync as mkdirSync6 } from "node:fs";
 import { dirname as dirname6 } from "node:path";
 import { DatabaseSync } from "node:sqlite";
 
@@ -6408,7 +6842,7 @@ function normalizeString(s) {
 function createSqliteCache(options) {
   const fileBacked = options.dbPath !== ":memory:";
   if (fileBacked) {
-    mkdirSync5(dirname6(options.dbPath), { recursive: true, mode: 448 });
+    mkdirSync6(dirname6(options.dbPath), { recursive: true, mode: 448 });
   }
   const versionNamespace = options.cacheVersionNamespace ?? "";
   const db = new DatabaseSync(options.dbPath);
@@ -7410,7 +7844,7 @@ init_common();
 function defaultCacheDbPath() {
   const env = process.env["VO_MCP_DB_PATH"];
   if (env && env.length > 0) return env;
-  return join10(homedir6(), ".claude", "vo-mcp-cache.db");
+  return join11(homedir7(), ".claude", "vo-mcp-cache.db");
 }
 async function probeEngineVersion() {
   try {
@@ -7561,12 +7995,12 @@ if (process.argv[2] === "login") {
   const sessionId = randomUUID5();
   const appendSyncLog = async (line) => {
     try {
-      const { appendFileSync: appendFileSync2, mkdirSync: mkdirSync6 } = await import("node:fs");
-      const { join: join11 } = await import("node:path");
-      const { homedir: homedir7 } = await import("node:os");
-      const dir = join11(homedir7(), ".claude");
-      mkdirSync6(dir, { recursive: true });
-      appendFileSync2(join11(dir, "vo-mcp-sync.log"), `${line}
+      const { appendFileSync: appendFileSync2, mkdirSync: mkdirSync7 } = await import("node:fs");
+      const { join: join12 } = await import("node:path");
+      const { homedir: homedir8 } = await import("node:os");
+      const dir = join12(homedir8(), ".claude");
+      mkdirSync7(dir, { recursive: true });
+      appendFileSync2(join12(dir, "vo-mcp-sync.log"), `${line}
 `, "utf8");
     } catch {
     }