@explyt/ai-agent 0.1.0-rc.1

package/node_modules/pi-subagents/src/runs/shared/session-lease.ts

@@ -0,0 +1,299 @@
+import { spawnSync } from "node:child_process";
+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.ts";
+import { TEMP_ROOT_DIR } from "../../shared/types.ts";
+
+export const SESSION_LEASES_DIR = path.join(TEMP_ROOT_DIR, "session-leases");
+
+export interface SessionLeaseRequest {
+	sessionFile: string;
+	runId: string;
+	sourceRunId: string;
+	parentSessionId?: string;
+}
+
+export interface SessionLeaseOwner {
+	version: 1;
+	token: string;
+	canonicalSessionFile: string;
+	runId: string;
+	sourceRunId: string;
+	parentSessionId?: string;
+	pid: number;
+	hostname: string;
+	processStartIdentity?: string;
+	writerState: "none" | "spawning" | "running";
+	writerPid?: number;
+	writerProcessStartIdentity?: string;
+	acquiredAt: string;
+	acquiredAtMs: number;
+	updatedAtMs: number;
+}
+
+export interface SessionLeaseHandle {
+	leaseDir: string;
+	owner: SessionLeaseOwner;
+	updateWriter(writer: { state: "none" | "spawning" } | { state: "running"; pid: number }): void;
+	release(): boolean;
+}
+
+export type SessionLeaseState =
+	| { state: "free"; canonicalSessionFile: string; canonicalSessionId: string }
+	| { state: "owned"; canonicalSessionFile: string; canonicalSessionId: string; owner: SessionLeaseOwner }
+	| { state: "unreadable"; canonicalSessionFile: string; canonicalSessionId: string };
+
+interface SessionLeaseOptions {
+	rootDir?: string;
+	now?: () => number;
+	token?: () => string;
+	pid?: number;
+	hostname?: string;
+	processStartIdentity?: string;
+	isProcessAlive?: (pid: number) => boolean | undefined;
+	getProcessStartIdentity?: (pid: number) => string | undefined;
+}
+
+export class SessionLeaseConflictError extends Error {
+	readonly owner?: SessionLeaseOwner;
+
+	constructor(message: string, owner?: SessionLeaseOwner) {
+		super(message);
+		this.name = "SessionLeaseConflictError";
+		this.owner = owner;
+	}
+}
+
+function getProcessStartIdentity(pid: number): string | undefined {
+	if (process.platform === "linux") {
+		try {
+			const stat = fs.readFileSync(`/proc/${pid}/stat`, "utf-8");
+			const commandEnd = stat.lastIndexOf(")");
+			if (commandEnd === -1) return undefined;
+			const fields = stat.slice(commandEnd + 1).trim().split(/\s+/);
+			const startTicks = fields[19];
+			return startTicks ? `linux:${startTicks}` : undefined;
+		} catch {
+			return undefined;
+		}
+	}
+	if (process.platform === "darwin" || process.platform === "freebsd") {
+		const result = spawnSync("/bin/ps", ["-o", "lstart=", "-p", String(pid)], { encoding: "utf-8" });
+		const started = result.status === 0 ? result.stdout.trim() : "";
+		return started ? `${process.platform}:${started}` : undefined;
+	}
+	return undefined;
+}
+
+function processIsAlive(pid: number): boolean | undefined {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException).code;
+		if (code === "ESRCH") return false;
+		if (code === "EPERM") return true;
+		return undefined;
+	}
+}
+
+export function canonicalSessionFilePath(sessionFile: string): string {
+	return fs.realpathSync.native(path.resolve(sessionFile));
+}
+
+export function canonicalSessionId(sessionFile: string): string {
+	const canonical = canonicalSessionFilePath(sessionFile);
+	const key = process.platform === "win32" ? canonical.toLowerCase() : canonical;
+	return createHash("sha256").update(key).digest("hex");
+}
+
+export function sessionLeaseDir(sessionFile: string, rootDir = SESSION_LEASES_DIR): string {
+	return path.join(rootDir, canonicalSessionId(sessionFile));
+}
+
+export function inspectSessionLease(sessionFile: string, rootDir = SESSION_LEASES_DIR): SessionLeaseState {
+	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: unknown): SessionLeaseOwner | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const owner = value as Partial<SessionLeaseOwner>;
+	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 undefined;
+	if (owner.parentSessionId !== undefined && typeof owner.parentSessionId !== "string") return undefined;
+	if (owner.processStartIdentity !== undefined && typeof owner.processStartIdentity !== "string") return undefined;
+	if (owner.writerPid !== undefined && (typeof owner.writerPid !== "number" || !Number.isInteger(owner.writerPid) || owner.writerPid <= 0)) return undefined;
+	if (owner.writerProcessStartIdentity !== undefined && typeof owner.writerProcessStartIdentity !== "string") return undefined;
+	if (owner.writerState === "running" && owner.writerPid === undefined) return undefined;
+	if (owner.writerState !== "running" && (owner.writerPid !== undefined || owner.writerProcessStartIdentity !== undefined)) return undefined;
+	return owner as SessionLeaseOwner;
+}
+
+function readLeaseOwner(leaseDir: string): SessionLeaseOwner | undefined {
+	try {
+		return parseOwner(JSON.parse(fs.readFileSync(path.join(leaseDir, "owner.json"), "utf-8")));
+	} catch {
+		return undefined;
+	}
+}
+
+function conflictMessage(canonicalSessionFile: string, owner: SessionLeaseOwner | undefined): string {
+	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: number,
+	startIdentity: string | undefined,
+	options: Required<Pick<SessionLeaseOptions, "isProcessAlive" | "getProcessStartIdentity">>,
+): boolean {
+	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: SessionLeaseOwner, options: Required<Pick<SessionLeaseOptions, "hostname" | "isProcessAlive" | "getProcessStartIdentity">>): boolean {
+	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: string, owner: SessionLeaseOwner): boolean {
+	const tempDir = `${leaseDir}.candidate-${owner.token}`;
+	fs.mkdirSync(path.dirname(leaseDir), { recursive: true, mode: 0o700 });
+	fs.rmSync(tempDir, { recursive: true, force: true });
+	fs.mkdirSync(tempDir, { mode: 0o700 });
+	try {
+		fs.writeFileSync(path.join(tempDir, "owner.json"), JSON.stringify(owner, null, 2), { encoding: "utf-8", mode: 0o600 });
+		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: SessionLeaseRequest, options: SessionLeaseOptions = {}): SessionLeaseHandle {
+	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: SessionLeaseOwner = {
+		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: SessionLeaseOwner = {
+						...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);
+		}
+		// The per-owner tombstone is retained. Every contender that observed this
+		// stale token targets the same occupied destination, so only the first can
+		// rename it and later contenders cannot move a successor lease by mistake.
+		const tombstone = `${leaseDir}.stale-${existingOwner.token.replace(/[^A-Za-z0-9._-]/g, "-")}`;
+		try {
+			fs.renameSync(leaseDir, tombstone);
+		} catch (error) {
+			const code = (error as NodeJS.ErrnoException).code;
+			if (code === "ENOENT" || fs.existsSync(tombstone)) continue;
+			throw error;
+		}
+	}
+
+	const existingOwner = readLeaseOwner(leaseDir);
+	throw new SessionLeaseConflictError(conflictMessage(canonicalSessionFile, existingOwner), existingOwner);
+}

package/node_modules/pi-subagents/src/runs/shared/single-output.ts

@@ -0,0 +1,235 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { Message } from "@earendil-works/pi-ai";
+import type { OutputMode, SavedOutputReference } from "../../shared/types.ts";
+import { hasMutationToolCapability } from "./completion-guard.ts";
+
+export interface SingleOutputSnapshot {
+	exists: boolean;
+	mtimeMs?: number;
+	size?: number;
+}
+
+/**
+ * Content the child itself sent to the configured output path, taken from its
+ * last `write` tool call whose tool result reports success. Unlike reading the
+ * path from disk, this cannot be polluted by a sibling run writing the same
+ * path (#420); requiring the successful tool result keeps failed, cancelled,
+ * or unanswered write calls from counting as authored output. Returns
+ * undefined when no such write exists (e.g. bash or edit-based construction),
+ * in which case callers must not assume file authorship.
+ */
+export function extractChildWrittenOutput(
+	messages: Message[] | undefined,
+	outputPath: string | undefined,
+	cwd?: string,
+): string | undefined {
+	if (!messages?.length || !outputPath) return undefined;
+	const resolvedTarget = path.resolve(cwd ?? ".", outputPath);
+	const comparableTarget = process.platform === "win32" ? resolvedTarget.toLowerCase() : resolvedTarget;
+	const successfulCallIds = new Set<string>();
+	for (const message of messages) {
+		if (message.role === "toolResult" && message.isError === false && typeof message.toolCallId === "string") {
+			successfulCallIds.add(message.toolCallId);
+		}
+	}
+	let content: string | undefined;
+	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 as Record<string, unknown>
+				: {};
+			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: string | boolean | undefined,
+	defaultOutput: string | undefined,
+): string | false | undefined {
+	if (output === false || output === "false") return false;
+	if (output === true || output === "true") return defaultOutput;
+	if (typeof output === "string" && output.length > 0) return output;
+	return undefined;
+}
+
+export function resolveSingleOutputPath(
+	output: string | boolean | undefined,
+	runtimeCwd: string,
+	requestedCwd?: string,
+	relativeBaseDir?: string,
+): string | undefined {
+	if (typeof output !== "string" || !output || output === "false" || output === "true") return undefined;
+	if (path.isAbsolute(output)) return output;
+	if (relativeBaseDir) return path.resolve(relativeBaseDir, output);
+	const baseCwd = requestedCwd
+		? (path.isAbsolute(requestedCwd) ? requestedCwd : path.resolve(runtimeCwd, requestedCwd))
+		: runtimeCwd;
+	return path.resolve(baseCwd, output);
+}
+
+interface OutputInstructionCapabilities {
+	tools?: string[];
+	mcpDirectTools?: string[];
+}
+
+function formatOutputPathInstruction(outputPath: string, capabilities?: OutputInstructionCapabilities): string {
+	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("\n");
+	return [
+		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("\n");
+}
+
+export function injectSingleOutputInstruction(task: string, outputPath: string | undefined, capabilities?: OutputInstructionCapabilities): string {
+	if (!outputPath) return task;
+	return `${task}\n\n---\n**Output:**\n${formatOutputPathInstruction(outputPath, capabilities)}`;
+}
+
+export function injectOutputPathSystemPrompt(systemPrompt: string, outputPath: string | undefined, capabilities?: OutputInstructionCapabilities): string {
+	if (!outputPath) return systemPrompt;
+	const instruction = `Runtime output path override:\n${formatOutputPathInstruction(outputPath, capabilities)}`;
+	return systemPrompt ? `${systemPrompt}\n\n${instruction}` : instruction;
+}
+
+function countLines(text: string): number {
+	if (!text) return 0;
+	const newlineMatches = text.match(/\r\n|\r|\n/g);
+	return (newlineMatches?.length ?? 0) + (/[\r\n]$/.test(text) ? 0 : 1);
+}
+
+function formatByteSize(bytes: number): string {
+	if (bytes < 1024) return `${bytes} B`;
+	const units = ["KB", "MB", "GB", "TB"];
+	let value = bytes / 1024;
+	let unitIndex = 0;
+	while (value >= 1024 && unitIndex < units.length - 1) {
+		value /= 1024;
+		unitIndex++;
+	}
+	return `${value.toFixed(1)} ${units[unitIndex]}`;
+}
+
+export function formatSavedOutputReference(savedPath: string, fullOutput: string): SavedOutputReference {
+	const absolutePath = path.resolve(savedPath);
+	const bytes = Buffer.byteLength(fullOutput, "utf-8");
+	const lines = countLines(fullOutput);
+	return {
+		path: absolutePath,
+		bytes,
+		lines,
+		message: `Output saved to: ${absolutePath} (${formatByteSize(bytes)}, ${lines} ${lines === 1 ? "line" : "lines"}). Read this file if needed.`,
+	};
+}
+
+export function validateFileOnlyOutputMode(outputMode: OutputMode | undefined, outputPath: string | undefined, context: string): string | undefined {
+	if (outputMode === "file-only" && !outputPath) {
+		return `${context} sets outputMode: "file-only" but does not configure an output file. Set output to a path or use outputMode: "inline".`;
+	}
+	return undefined;
+}
+
+export function captureSingleOutputSnapshot(outputPath: string | undefined): SingleOutputSnapshot | undefined {
+	if (!outputPath) return undefined;
+	try {
+		const stat = fs.statSync(outputPath);
+		return { exists: true, mtimeMs: stat.mtimeMs, size: stat.size };
+	} catch {
+		// The snapshot is advisory; resolveSingleOutput reports concrete read/write failures.
+		return { exists: false };
+	}
+}
+
+function persistSingleOutput(
+	outputPath: string | undefined,
+	fullOutput: string,
+): { savedPath?: string; error?: string } {
+	if (!outputPath) return {};
+	try {
+		fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+		fs.writeFileSync(outputPath, fullOutput, "utf-8");
+		return { savedPath: outputPath };
+	} catch (err) {
+		return { error: err instanceof Error ? err.message : String(err) };
+	}
+}
+
+export function resolveSingleOutput(
+	outputPath: string | undefined,
+	fallbackOutput: string,
+	beforeRun: SingleOutputSnapshot | undefined,
+): { fullOutput: string; savedPath?: string; saveError?: string } {
+	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 as { code?: unknown }).code : undefined;
+		if (code !== "ENOENT" && code !== "ENOTDIR") {
+			return {
+				fullOutput: fallbackOutput,
+				saveError: `Failed to inspect output file: ${error instanceof Error ? error.message : String(error)}`,
+			};
+		}
+	}
+
+	if (changedSinceStart) {
+		try {
+			return { fullOutput: fs.readFileSync(outputPath, "utf-8"), savedPath: outputPath };
+		} catch (error) {
+			return {
+				fullOutput: fallbackOutput,
+				saveError: `Failed to read changed output file: ${error instanceof Error ? error.message : String(error)}`,
+			};
+		}
+	}
+
+	const save = persistSingleOutput(outputPath, fallbackOutput);
+	if (save.savedPath) return { fullOutput: fallbackOutput, savedPath: save.savedPath };
+	return { fullOutput: fallbackOutput, saveError: save.error };
+}
+
+export function finalizeSingleOutput(params: {
+	fullOutput: string;
+	truncatedOutput?: string;
+	outputPath?: string;
+	outputMode?: OutputMode;
+	exitCode: number;
+	savedPath?: string;
+	outputReference?: SavedOutputReference;
+	saveError?: string;
+}): { displayOutput: string; savedPath?: string; outputReference?: SavedOutputReference; saveError?: string } {
+	let displayOutput = params.truncatedOutput || params.fullOutput;
+	if (params.exitCode === 0 && 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 += `\n\n${outputReference.message}`;
+		return { displayOutput, savedPath: params.savedPath, outputReference };
+	}
+	if (params.exitCode === 0 && params.saveError && params.outputPath) {
+		displayOutput += `\n\nOutput file error: ${params.outputPath}\n${params.saveError}`;
+		return { displayOutput, saveError: params.saveError };
+	}
+	return { displayOutput };
+}

package/node_modules/pi-subagents/src/runs/shared/spawn-budget.ts

@@ -0,0 +1,128 @@
+import {
+	resolveMaxSubagentSpawnsPerSession,
+	type ExtensionConfig,
+	type SpawnBudgetSnapshot,
+	type SubagentState,
+} from "../../shared/types.ts";
+
+const MAX_GRANT_HISTORY = 20;
+
+function sessionState(state: SubagentState, config: ExtensionConfig, sessionId: string | null) {
+	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: SubagentState,
+	config: ExtensionConfig,
+	sessionId: string | null = state.currentSessionId,
+): SpawnBudgetSnapshot {
+	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: SpawnBudgetSnapshot): string {
+	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: SpawnBudgetSnapshot): string {
+	return `Spawn budget: ${formatSpawnBudgetSummary(snapshot)}`;
+}
+
+export function preflightSpawnBudget(
+	state: SubagentState,
+	config: ExtensionConfig,
+	sessionId: string | null,
+	requested: number,
+): { snapshot: SpawnBudgetSnapshot; error?: string } {
+	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: SubagentState,
+	config: ExtensionConfig,
+	sessionId: string | null,
+	requested: number,
+): { snapshot: SpawnBudgetSnapshot; error?: string } {
+	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: SubagentState,
+	config: ExtensionConfig,
+	sessionId: string,
+	additional: number,
+): { snapshot: SpawnBudgetSnapshot; error?: string } {
+	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: SubagentState,
+	config: ExtensionConfig,
+	sessionId: string,
+	additional: number,
+	now = Date.now(),
+): { snapshot: SpawnBudgetSnapshot; error?: string } {
+	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) };
+}