@duckmind/dm-windows-x64 0.61.5 → 0.62.1

package/extensions/dm-subagents/src/runs/shared/session-lease.js

@@ -0,0 +1,225 @@
+import { createHash, randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { createAtomicJsonWriter } from "../../shared/atomic-json.js";
+import { TEMP_ROOT_DIR } from "../../shared/types.js";
+export const SESSION_LEASES_DIR = path.join(TEMP_ROOT_DIR, "session-leases");
+
+export class SessionLeaseConflictError extends Error {
+  owner;
+  constructor(message, owner) {
+    super(message);
+    this.name = "SessionLeaseConflictError";
+    this.owner = owner;
+  }
+}
+function getProcessStartIdentity(pid) {
+  if (process.platform === "linux") {
+    try {
+      const stat = fs.readFileSync(`/proc/${pid}/stat`, "utf-8");
+      const commandEnd = stat.lastIndexOf(")");
+      if (commandEnd === -1)
+        return;
+      const fields = stat.slice(commandEnd + 1).trim().split(/\s+/);
+      const startTicks = fields[19];
+      return startTicks ? `linux:${startTicks}` : undefined;
+    } catch {
+      return;
+    }
+  }
+  return;
+}
+function processIsAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    const code = error.code;
+    if (code === "ESRCH")
+      return false;
+    if (code === "EPERM")
+      return true;
+    return;
+  }
+}
+export function canonicalSessionFilePath(sessionFile) {
+  return fs.realpathSync.native(path.resolve(sessionFile));
+}
+export function canonicalSessionId(sessionFile) {
+  const canonical = canonicalSessionFilePath(sessionFile);
+  const key = process.platform === "win32" ? canonical.toLowerCase() : canonical;
+  return createHash("sha256").update(key).digest("hex");
+}
+export function sessionLeaseDir(sessionFile, rootDir = SESSION_LEASES_DIR) {
+  return path.join(rootDir, canonicalSessionId(sessionFile));
+}
+export function inspectSessionLease(sessionFile, rootDir = SESSION_LEASES_DIR) {
+  const canonicalSessionFile = canonicalSessionFilePath(sessionFile);
+  const canonicalSessionIdValue = canonicalSessionId(canonicalSessionFile);
+  const leaseDir = path.join(rootDir, canonicalSessionIdValue);
+  if (!fs.existsSync(leaseDir))
+    return { state: "free", canonicalSessionFile, canonicalSessionId: canonicalSessionIdValue };
+  const owner = readLeaseOwner(leaseDir);
+  return owner ? { state: "owned", canonicalSessionFile, canonicalSessionId: canonicalSessionIdValue, owner } : { state: "unreadable", canonicalSessionFile, canonicalSessionId: canonicalSessionIdValue };
+}
+function parseOwner(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return;
+  const owner = value;
+  if (owner.version !== 1 || typeof owner.token !== "string" || typeof owner.canonicalSessionFile !== "string" || typeof owner.runId !== "string" || typeof owner.sourceRunId !== "string" || typeof owner.pid !== "number" || !Number.isInteger(owner.pid) || owner.pid <= 0 || typeof owner.hostname !== "string" || owner.writerState !== "none" && owner.writerState !== "spawning" && owner.writerState !== "running" || typeof owner.acquiredAt !== "string" || typeof owner.acquiredAtMs !== "number" || typeof owner.updatedAtMs !== "number")
+    return;
+  if (owner.parentSessionId !== undefined && typeof owner.parentSessionId !== "string")
+    return;
+  if (owner.processStartIdentity !== undefined && typeof owner.processStartIdentity !== "string")
+    return;
+  if (owner.writerPid !== undefined && (typeof owner.writerPid !== "number" || !Number.isInteger(owner.writerPid) || owner.writerPid <= 0))
+    return;
+  if (owner.writerProcessStartIdentity !== undefined && typeof owner.writerProcessStartIdentity !== "string")
+    return;
+  if (owner.writerState === "running" && owner.writerPid === undefined)
+    return;
+  if (owner.writerState !== "running" && (owner.writerPid !== undefined || owner.writerProcessStartIdentity !== undefined))
+    return;
+  return owner;
+}
+function readLeaseOwner(leaseDir) {
+  try {
+    return parseOwner(JSON.parse(fs.readFileSync(path.join(leaseDir, "owner.json"), "utf-8")));
+  } catch {
+    return;
+  }
+}
+function conflictMessage(canonicalSessionFile, owner) {
+  if (!owner) {
+    return `Direct revival of session '${canonicalSessionFile}' is blocked by an existing lease with unreadable owner metadata. Refusing to reclaim it without proof that the owner is stale.`;
+  }
+  const parent = owner.parentSessionId ? `, parent session '${owner.parentSessionId}'` : "";
+  return `Direct revival of session '${canonicalSessionFile}' is already owned by run '${owner.runId}' (source run '${owner.sourceRunId}'${parent}, pid ${owner.pid} on ${owner.hostname}). Wait for that revival to finish or start a separate continuation without reusing this session file.`;
+}
+function processDemonstrablyGone(pid, startIdentity, options) {
+  const alive = options.isProcessAlive(pid);
+  if (alive === false)
+    return true;
+  if (alive !== true || !startIdentity)
+    return false;
+  const currentIdentity = options.getProcessStartIdentity(pid);
+  return currentIdentity !== undefined && currentIdentity !== startIdentity;
+}
+function demonstrablyStale(owner, options) {
+  if (owner.hostname !== options.hostname)
+    return false;
+  if (!processDemonstrablyGone(owner.pid, owner.processStartIdentity, options))
+    return false;
+  if (owner.writerState === "spawning")
+    return false;
+  if (owner.writerState === "none")
+    return true;
+  return owner.writerPid !== undefined && processDemonstrablyGone(owner.writerPid, owner.writerProcessStartIdentity, options);
+}
+function createLeaseDirectory(leaseDir, owner) {
+  const tempDir = `${leaseDir}.candidate-${owner.token}`;
+  fs.mkdirSync(path.dirname(leaseDir), { recursive: true, mode: 448 });
+  fs.rmSync(tempDir, { recursive: true, force: true });
+  fs.mkdirSync(tempDir, { mode: 448 });
+  try {
+    fs.writeFileSync(path.join(tempDir, "owner.json"), JSON.stringify(owner, null, 2), { encoding: "utf-8", mode: 384 });
+    try {
+      fs.renameSync(tempDir, leaseDir);
+      return true;
+    } catch (error) {
+      if (fs.existsSync(leaseDir))
+        return false;
+      throw error;
+    }
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+export function acquireSessionLease(request, options = {}) {
+  const canonicalSessionFile = canonicalSessionFilePath(request.sessionFile);
+  const rootDir = options.rootDir ?? SESSION_LEASES_DIR;
+  const leaseDir = sessionLeaseDir(canonicalSessionFile, rootDir);
+  const now = options.now ?? Date.now;
+  const pid = options.pid ?? process.pid;
+  const hostname = options.hostname ?? os.hostname();
+  const getIdentity = options.getProcessStartIdentity ?? getProcessStartIdentity;
+  const processStartIdentity = options.processStartIdentity ?? getIdentity(pid) ?? (pid === process.pid ? `runtime:${Math.round(Date.now() - process.uptime() * 1000)}` : undefined);
+  const acquiredAtMs = now();
+  const owner = {
+    version: 1,
+    token: options.token?.() ?? randomUUID(),
+    canonicalSessionFile,
+    runId: request.runId,
+    sourceRunId: request.sourceRunId,
+    ...request.parentSessionId ? { parentSessionId: request.parentSessionId } : {},
+    pid,
+    hostname,
+    ...processStartIdentity ? { processStartIdentity } : {},
+    writerState: "none",
+    acquiredAt: new Date(acquiredAtMs).toISOString(),
+    acquiredAtMs,
+    updatedAtMs: acquiredAtMs
+  };
+  const staleOptions = {
+    hostname,
+    isProcessAlive: options.isProcessAlive ?? processIsAlive,
+    getProcessStartIdentity: getIdentity
+  };
+  for (let attempt = 0;attempt < 4; attempt++) {
+    if (createLeaseDirectory(leaseDir, owner)) {
+      const writeOwner = createAtomicJsonWriter();
+      return {
+        leaseDir,
+        owner,
+        updateWriter(writer) {
+          const currentOwner = readLeaseOwner(leaseDir);
+          if (!currentOwner || currentOwner.token !== owner.token) {
+            throw new Error(`Session revival lease ownership changed for run '${owner.runId}'.`);
+          }
+          const writerProcessStartIdentity = writer.state === "running" ? getIdentity(writer.pid) : undefined;
+          const nextOwner = {
+            ...owner,
+            writerState: writer.state,
+            ...writer.state === "running" ? { writerPid: writer.pid } : {},
+            ...writerProcessStartIdentity ? { writerProcessStartIdentity } : {},
+            updatedAtMs: now()
+          };
+          delete nextOwner.writerPid;
+          delete nextOwner.writerProcessStartIdentity;
+          if (writer.state === "running") {
+            nextOwner.writerPid = writer.pid;
+            if (writerProcessStartIdentity)
+              nextOwner.writerProcessStartIdentity = writerProcessStartIdentity;
+          }
+          writeOwner(path.join(leaseDir, "owner.json"), nextOwner);
+          delete owner.writerPid;
+          delete owner.writerProcessStartIdentity;
+          Object.assign(owner, nextOwner);
+        },
+        release() {
+          const currentOwner = readLeaseOwner(leaseDir);
+          if (!currentOwner || currentOwner.token !== owner.token)
+            return false;
+          fs.rmSync(leaseDir, { recursive: true, force: true });
+          return !fs.existsSync(leaseDir);
+        }
+      };
+    }
+    const existingOwner = readLeaseOwner(leaseDir);
+    if (!existingOwner || !demonstrablyStale(existingOwner, staleOptions)) {
+      throw new SessionLeaseConflictError(conflictMessage(canonicalSessionFile, existingOwner), existingOwner);
+    }
+    const tombstone = `${leaseDir}.stale-${existingOwner.token.replace(/[^A-Za-z0-9._-]/g, "-")}`;
+    try {
+      fs.renameSync(leaseDir, tombstone);
+    } catch (error) {
+      const code = error.code;
+      if (code === "ENOENT" || fs.existsSync(tombstone))
+        continue;
+      throw error;
+    }
+  }
+  const existingOwner = readLeaseOwner(leaseDir);
+  throw new SessionLeaseConflictError(conflictMessage(canonicalSessionFile, existingOwner), existingOwner);
+}

package/extensions/dm-subagents/src/runs/shared/single-output.js

@@ -1,5 +1,45 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { hasMutationToolCapability } from "./completion-guard.js";
+function missingFileStatError(error) {
+  const code = error?.code;
+  return code === "ENOENT" || code === "ENOTDIR";
+}
+function snapshotFromStatError(error) {
+  if (missingFileStatError(error))
+    return { exists: false };
+  return { exists: false, error: error instanceof Error ? error.message : String(error) };
+}
+export function extractChildWrittenOutput(messages, outputPath, cwd) {
+  if (!messages?.length || !outputPath)
+    return;
+  const resolvedTarget = path.resolve(cwd ?? ".", outputPath);
+  const comparableTarget = process.platform === "win32" ? resolvedTarget.toLowerCase() : resolvedTarget;
+  const successfulCallIds = new Set;
+  for (const message of messages) {
+    if (message.role === "toolResult" && message.isError === false && typeof message.toolCallId === "string") {
+      successfulCallIds.add(message.toolCallId);
+    }
+  }
+  let content;
+  for (const message of messages) {
+    if (message.role !== "assistant")
+      continue;
+    for (const part of message.content) {
+      if (part.type !== "toolCall" || part.name !== "write" || !successfulCallIds.has(part.id))
+        continue;
+      const args = typeof part.arguments === "object" && part.arguments !== null && !Array.isArray(part.arguments) ? part.arguments : {};
+      if (typeof args.path !== "string" || typeof args.content !== "string")
+        continue;
+      const resolvedWritePath = path.resolve(cwd ?? ".", args.path);
+      const comparableWritePath = process.platform === "win32" ? resolvedWritePath.toLowerCase() : resolvedWritePath;
+      if (comparableWritePath !== comparableTarget)
+        continue;
+      content = args.content;
+    }
+  }
+  return content;
+}
 export function normalizeSingleOutputOverride(output, defaultOutput) {
   if (output === false || output === "false")
     return false;
@@ -19,28 +59,52 @@ export function resolveSingleOutputPath(output, runtimeCwd, requestedCwd, relati
   const baseCwd = requestedCwd ? path.isAbsolute(requestedCwd) ? requestedCwd : path.resolve(runtimeCwd, requestedCwd) : runtimeCwd;
   return path.resolve(baseCwd, output);
 }
-function formatOutputPathInstruction(outputPath) {
+function formatOutputPathInstruction(outputPath, capabilities) {
+  const delivery = !capabilities || hasMutationToolCapability(capabilities.tools, capabilities.mcpDirectTools) ? `Write your findings to exactly this path: ${outputPath}` : [
+    "Return the complete artifact in your final response.",
+    `The runtime will persist it to exactly this path: ${outputPath}`,
+    "Do not call contact_supervisor merely because no write-capable tool is available."
+  ].join(`
+`);
   return [
-    `Write your findings to exactly this path: ${outputPath}`,
+    delivery,
     "This path is authoritative for this run.",
     "Ignore any other output filename or output path mentioned elsewhere, including output destinations in the base agent prompt, system prompt, or task instructions."
   ].join(`
 `);
 }
-export function injectSingleOutputInstruction(task, outputPath) {
+export function requestedOutputPathFromTask(task) {
+  for (const line of task.split(/\r?\n/).reverse()) {
+    const match = line.match(/^\s*(?:Write your findings to(?: exactly this path)?:|The runtime will persist it to exactly this path:)\s*(.+?)\s*$/i);
+    if (!match?.[1])
+      continue;
+    const requested = match[1].trim();
+    return requested.startsWith("`") && requested.endsWith("`") ? requested.slice(1, -1) : requested;
+  }
+  return;
+}
+export function outputPathMappingFromTask(task, savedPath) {
+  const requestedPath = requestedOutputPathFromTask(task);
+  if (!requestedPath || !savedPath)
+    return;
+  if (path.isAbsolute(requestedPath) && path.normalize(requestedPath) === path.normalize(savedPath))
+    return;
+  return { requestedPath, savedPath };
+}
+export function injectSingleOutputInstruction(task, outputPath, capabilities) {
   if (!outputPath)
     return task;
   return `${task}
 
 ---
 **Output:**
-${formatOutputPathInstruction(outputPath)}`;
+${formatOutputPathInstruction(outputPath, capabilities)}`;
 }
-export function injectOutputPathSystemPrompt(systemPrompt, outputPath) {
+export function injectOutputPathSystemPrompt(systemPrompt, outputPath, capabilities) {
   if (!outputPath)
     return systemPrompt;
   const instruction = `Runtime output path override:
-${formatOutputPathInstruction(outputPath)}`;
+${formatOutputPathInstruction(outputPath, capabilities)}`;
   return systemPrompt ? `${systemPrompt}
 
 ${instruction}` : instruction;
@@ -80,20 +144,60 @@ export function validateFileOnlyOutputMode(outputMode, outputPath, context) {
   }
   return;
 }
+export function resolveSingleOutputClaimPath(outputPath) {
+  let existing = path.resolve(outputPath);
+  const missingSegments = [];
+  while (!fs.existsSync(existing)) {
+    missingSegments.unshift(path.basename(existing));
+    const parent = path.dirname(existing);
+    if (parent === existing)
+      break;
+    existing = parent;
+  }
+  return path.join(fs.realpathSync(existing), ...missingSegments);
+}
+function outputClaimError(outputPath, expectedClaimPath) {
+  if (expectedClaimPath && resolveSingleOutputClaimPath(outputPath) !== expectedClaimPath)
+    return "Output path changed after it was claimed.";
+  return;
+}
 export function captureSingleOutputSnapshot(outputPath) {
   if (!outputPath)
     return;
   try {
     const stat = fs.statSync(outputPath);
     return { exists: true, mtimeMs: stat.mtimeMs, size: stat.size };
-  } catch {
-    return { exists: false };
+  } catch (error) {
+    return snapshotFromStatError(error);
+  }
+}
+function inspectSingleOutputChange(outputPath, beforeRun) {
+  if (beforeRun?.error)
+    return { changed: false, error: beforeRun.error };
+  try {
+    const stat = fs.statSync(outputPath);
+    return {
+      changed: !beforeRun?.exists || stat.mtimeMs !== beforeRun.mtimeMs || stat.size !== beforeRun.size
+    };
+  } catch (error) {
+    if (missingFileStatError(error))
+      return { changed: false };
+    return { changed: false, error: error instanceof Error ? error.message : String(error) };
   }
 }
-function persistSingleOutput(outputPath, fullOutput) {
+export function hasSingleOutputChangedSinceSnapshot(outputPath, beforeRun) {
+  if (!outputPath)
+    return;
+  const inspected = inspectSingleOutputChange(outputPath, beforeRun);
+  return inspected.error ? undefined : inspected.changed;
+}
+function persistSingleOutput(outputPath, fullOutput, expectedClaimPath) {
   if (!outputPath)
     return {};
   try {
+    const claimError = outputClaimError(outputPath, expectedClaimPath);
+    if (claimError)
+      return { error: claimError, fatalError: true };
     fs.mkdirSync(path.dirname(outputPath), { recursive: true });
     fs.writeFileSync(outputPath, fullOutput, "utf-8");
     return { savedPath: outputPath };
@@ -101,23 +205,20 @@ function persistSingleOutput(outputPath, fullOutput) {
     return { error: err instanceof Error ? err.message : String(err) };
   }
 }
-export function resolveSingleOutput(outputPath, fallbackOutput, beforeRun) {
+export function resolveSingleOutput(outputPath, fallbackOutput, beforeRun, expectedClaimPath) {
   if (!outputPath)
     return { fullOutput: fallbackOutput };
-  let changedSinceStart = false;
-  try {
-    const stat = fs.statSync(outputPath);
-    changedSinceStart = !beforeRun?.exists || stat.mtimeMs !== beforeRun.mtimeMs || stat.size !== beforeRun.size;
-  } catch (error) {
-    const code = error && typeof error === "object" && "code" in error ? error.code : undefined;
-    if (code !== "ENOENT" && code !== "ENOTDIR") {
-      return {
-        fullOutput: fallbackOutput,
-        saveError: `Failed to inspect output file: ${error instanceof Error ? error.message : String(error)}`
-      };
-    }
+  const claimError = outputClaimError(outputPath, expectedClaimPath);
+  if (claimError)
+    return { fullOutput: fallbackOutput, saveError: claimError, fatalError: true };
+  const changedSinceStart = inspectSingleOutputChange(outputPath, beforeRun);
+  if (changedSinceStart.error) {
+    return {
+      fullOutput: fallbackOutput,
+      saveError: `Failed to inspect output file: ${changedSinceStart.error}`
+    };
   }
-  if (changedSinceStart) {
+  if (changedSinceStart.changed) {
     try {
       return { fullOutput: fs.readFileSync(outputPath, "utf-8"), savedPath: outputPath };
     } catch (error) {
@@ -127,19 +228,20 @@ export function resolveSingleOutput(outputPath, fallbackOutput, beforeRun) {
       };
     }
   }
-  const save = persistSingleOutput(outputPath, fallbackOutput);
+  const save = persistSingleOutput(outputPath, fallbackOutput, expectedClaimPath);
   if (save.savedPath)
     return { fullOutput: fallbackOutput, savedPath: save.savedPath };
-  return { fullOutput: fallbackOutput, saveError: save.error };
+  return { fullOutput: fallbackOutput, saveError: save.error, ...save.fatalError ? { fatalError: true } : {} };
 }
 export function finalizeSingleOutput(params) {
   let displayOutput = params.truncatedOutput || params.fullOutput;
-  if (params.exitCode === 0 && params.savedPath) {
+  if ((params.exitCode === 0 || params.preserveSavedOutput) && params.savedPath) {
     const outputReference = params.outputReference ?? formatSavedOutputReference(params.savedPath, params.fullOutput);
     if (params.outputMode === "file-only") {
       return { displayOutput: outputReference.message, savedPath: params.savedPath, outputReference };
     }
-    displayOutput += `
+    if (!displayOutput.includes(outputReference.message))
+      displayOutput += `
 
 ${outputReference.message}`;
     return { displayOutput, savedPath: params.savedPath, outputReference };

package/extensions/dm-subagents/src/runs/shared/spawn-budget.js

@@ -0,0 +1,95 @@
+import {
+  resolveMaxSubagentSpawnsPerSession
+} from "../../shared/types.js";
+const MAX_GRANT_HISTORY = 20;
+function sessionState(state, config, sessionId) {
+  let counters = state.subagentSpawns;
+  if (!counters || counters.sessionId !== sessionId) {
+    counters = {
+      sessionId,
+      count: 0,
+      configuredLimit: resolveMaxSubagentSpawnsPerSession(config.maxSubagentSpawnsPerSession) ?? null,
+      granted: 0,
+      grantHistory: []
+    };
+    state.subagentSpawns = counters;
+  }
+  if (counters.configuredLimit === undefined) {
+    counters.configuredLimit = resolveMaxSubagentSpawnsPerSession(config.maxSubagentSpawnsPerSession) ?? null;
+  }
+  counters.granted ??= 0;
+  counters.grantHistory ??= [];
+  return counters;
+}
+export function getSpawnBudgetSnapshot(state, config, sessionId = state.currentSessionId) {
+  const counters = sessionState(state, config, sessionId);
+  const configuredLimit = counters.configuredLimit ?? null;
+  const granted = configuredLimit === null ? 0 : counters.granted ?? 0;
+  const limit = configuredLimit === null ? null : configuredLimit + granted;
+  return {
+    used: counters.count,
+    configuredLimit,
+    granted,
+    limit,
+    remaining: limit === null ? null : Math.max(0, limit - counters.count),
+    grantRemaining: configuredLimit === null ? null : Math.max(0, configuredLimit - granted),
+    grantHistory: [...counters.grantHistory ?? []]
+  };
+}
+export function formatSpawnBudgetSummary(snapshot) {
+  if (snapshot.limit === null)
+    return "unlimited";
+  return `${snapshot.used}/${snapshot.limit} used, ${snapshot.remaining} remaining (configured ${snapshot.configuredLimit}; granted ${snapshot.granted}; grant allowance ${snapshot.grantRemaining})`;
+}
+export function formatSpawnBudget(snapshot) {
+  return `Spawn budget: ${formatSpawnBudgetSummary(snapshot)}`;
+}
+export function preflightSpawnBudget(state, config, sessionId, requested) {
+  const snapshot = getSpawnBudgetSnapshot(state, config, sessionId);
+  if (requested <= 0 || snapshot.limit === null || requested <= (snapshot.remaining ?? 0))
+    return { snapshot };
+  return {
+    snapshot,
+    error: `Subagent spawn limit reached for this session (${snapshot.used}/${snapshot.limit} used, ${requested} requested). ${snapshot.remaining} remaining; the declared run cannot fit, so no children were started. Grant budget explicitly from the root interactive session or start a new session.`
+  };
+}
+export function reserveSpawnBudget(state, config, sessionId, requested) {
+  const checked = preflightSpawnBudget(state, config, sessionId, requested);
+  if (checked.error || requested <= 0 || checked.snapshot.limit === null)
+    return checked;
+  state.subagentSpawns.count += requested;
+  return { snapshot: getSpawnBudgetSnapshot(state, config, sessionId) };
+}
+export function preflightSpawnBudgetGrant(state, config, sessionId, additional) {
+  const snapshot = getSpawnBudgetSnapshot(state, config, sessionId);
+  if (!Number.isInteger(additional) || additional <= 0) {
+    return { snapshot, error: "action='grant-spawn-budget' requires additional to be a positive integer." };
+  }
+  if (snapshot.configuredLimit === null || snapshot.limit === null) {
+    return { snapshot, error: "The current session has no configured spawn cap, so it does not need a budget grant." };
+  }
+  if (additional > (snapshot.grantRemaining ?? 0)) {
+    return {
+      snapshot,
+      error: `Spawn budget grant rejected: ${additional} requested but only ${snapshot.grantRemaining} of the original configured limit remains grantable.`
+    };
+  }
+  return { snapshot };
+}
+export function grantSpawnBudget(state, config, sessionId, additional, now = Date.now()) {
+  const checked = preflightSpawnBudgetGrant(state, config, sessionId, additional);
+  if (checked.error)
+    return checked;
+  const before = checked.snapshot;
+  if (before.limit === null) {
+    return { snapshot: before, error: "The current session has no configured spawn cap, so it does not need a budget grant." };
+  }
+  const counters = state.subagentSpawns;
+  counters.granted = (counters.granted ?? 0) + additional;
+  const limit = before.limit + additional;
+  counters.grantHistory = [
+    ...counters.grantHistory ?? [],
+    { sessionId, amount: additional, grantedAt: now, previousLimit: before.limit, limit }
+  ].slice(-MAX_GRANT_HISTORY);
+  return { snapshot: getSpawnBudgetSnapshot(state, config, sessionId) };
+}