pi-legion 0.16.0 → 2.0.0

package/src/shared/types.ts

@@ -6,7 +6,7 @@
  *   - Additive changes (new optional fields) are allowed.
  *   - Breaking changes require coordinating all modules.
  *
- * Design authority: pi-legion design.md (docs/design.md) (33 measured findings F1-F33).
+ * Design authority: docs/legion-v2-contract.md.
  */
 
 // =============================================================================
@@ -17,7 +17,7 @@ export type AgentScope = "user" | "project" | "both";
 
 export type SystemPromptMode = "replace" | "append";
 
-/** herdr agent kinds we can launch. Mirrors `herdr agent start --kind`. */
+/** Agent kinds parsed from role files; the RPC supervisor accepts only `pi`. */
 export const AGENT_KINDS = [
 	"pi",
 	"claude",
@@ -60,9 +60,6 @@ export type AgentKind = (typeof AGENT_KINDS)[number];
  */
 export type ModelOrigin = "explicit" | "inherited";
 
-/** Where a subagent's pane is placed (design §8.3). */
-export type Placement = "split-down" | "split-right" | "new-tab";
-
 /** What to do when an agent reports `blocked` (design §5.3). */
 export type OnBlockedPolicy = "forward" | "auto-approve" | "notify";
 
@@ -123,6 +120,12 @@ export interface AgentConfig {
 	systemPromptMode: SystemPromptMode;
 	inheritProjectContext: boolean;
 	inheritSkills: boolean;
+	/**
+	 * Load the host's discovered extensions (settings `packages`, project
+	 * extensions) in the child. Default false: children get `--no-extensions`
+	 * plus only explicit `--extension` paths (#43).
+	 */
+	inheritExtensions?: boolean;
 
 	// ── behavior ──
 	output?: string;
@@ -135,15 +138,15 @@ export interface AgentConfig {
 	completionGuard?: boolean;
 	maxSubagentDepth?: number;
 	allowNestedSubagents?: boolean;
+	utility?: boolean;
 	toolBudget?: ToolBudgetConfig;
 	turnBudget?: TurnBudgetConfig;
 	disabled?: boolean;
 	alias?: string[];
 	extraFields?: Record<string, string>;
 
-	// ── herdr-specific ──
+	// ── execution metadata ──
 	kind: AgentKind;
-	placement?: Placement;
 	worktree?: boolean;
 	steer?: boolean;
 	onBlocked?: OnBlockedPolicy;
@@ -283,16 +286,12 @@ export interface NestedPathEntry {
 export const MAX_NESTED_PATH_ENTRIES = 4;
 
 export interface ChildRecord {
-	/** herdr agent name, globally unique among live agents. */
+	/** Supervisor-local child name; unique among live children in this run. */
 	name: string;
-	/** Pane id, or null once recycled (F12: pane is not the durable carrier). */
-	paneId: string | null;
-	/** Owning tab when the child got its own tab (placement: "new-tab"). */
-	tabId?: string;
 	/** ★ resume credential — must persist. */
 	sessionFile: string;
 	sessionId?: string;
-	/** Proves we created this pane (guards against killing others'). */
+	/** Stable per-run child identity; legacy records used a pane owner token. */
 	ownerToken: string;
 
 	// lifecycle
@@ -300,7 +299,7 @@ export interface ChildRecord {
 	spawnedAt: string;
 	retiredAt?: string;
 
-	// outcome (snapshot taken BEFORE recycle — F27)
+	// outcome (snapshot taken before child retirement — F27)
 	execution?: Execution;
 	acceptance?: AcceptanceResult;
 	/**
@@ -321,7 +320,7 @@ export interface ChildRecord {
 	onBlocked?: OnBlockedPolicy;
 	/** Snapshotted at launch; missing `{"ok":…}` on success becomes rejected. */
 	completionGuard?: boolean;
-	/** Isolated git worktree the child's pane used; left on disk after retire. */
+	/** Isolated git worktree used by the child; left on disk after retire. */
 	worktreePath?: string;
 	/** Branch created in that worktree; the child ships via MR, not the parent checkout. */
 	worktreeBranch?: string;
@@ -335,23 +334,8 @@ export interface ChildRecord {
 	/** Model actually started with (resolved + fallback). */
 	model?: string;
 	thinking?: string | false;
-	/**
-	 * Models that were requested but could not be handed to the target CLI's
-	 * `--model` (`nativeModelFor` returns undefined for them), so the child runs
-	 * on the CLI's own default instead.
-	 *
-	 * Only reachable for an INHERITED model — an explicitly chosen one is
-	 * refused before launch (see `Orchestrator.launch`'s `modelOrigin`). This is
-	 * the intended case: a `kind: cursor` role with no model of its own
-	 * inherits the parent's pi-shaped model, which must not be forwarded.
-	 */
+	/** Models that were requested but cannot be represented by the RPC child. */
 	modelDropped?: string[];
-	/**
-	 * Exact text sent with `herdr agent prompt`. Non-pi collect reads the pane,
-	 * which still contains this echo; strip it before extracting a verdict so a
-	 * template `{"ok": true}` in the system prompt cannot attest success.
-	 */
-	promptText?: string;
 }
 
 export interface RunRecord {
@@ -361,15 +345,10 @@ export interface RunRecord {
 	cwd: string;
 
 	herdr: {
-		workspaceId?: string;
-		tabId?: string;
-		tabLabel?: string;
-		/**
-		 * Parent Pi's herdr pane (`HERDR_PANE_ID`). Scopes type-tab labels and
-		 * control-action lookup so two parent sessions in the same repo/Space
-		 * cannot steer or recycle each other's children.
-		 */
-		parentPaneId?: string;
+		/** Current transport marker under the historic run.json key. */
+		supervisor?: "rpc";
+		/** Reserved for M2 tree identity. */
+		node_id?: string;
 	};
 
 	/** Lineage: root → this node. */
@@ -385,159 +364,6 @@ export interface RunRecord {
 	updatedAt: string;
 }
 
-// =============================================================================
-// herdr client (design §9) — thin, testable wrapper over the CLI
-// =============================================================================
-
-export interface HerdrError {
-	code: string;
-	message: string;
-	details?: unknown;
-}
-
-export type HerdrResult<T> =
-	| { ok: true; value: T }
-	| { ok: false; error: HerdrError };
-
-export interface PaneInfo {
-	pane_id: string;
-	tab_id: string;
-	workspace_id: string;
-	agent_status?: string;
-	cwd?: string | null;
-	terminal_title_stripped?: string;
-}
-
-export interface AgentInfo {
-	name?: string | null;
-	pane_id: string;
-	tab_id: string;
-	workspace_id: string;
-	agent: string | null;
-	agent_status: string;
-	cwd?: string | null;
-	agent_session?: { kind: string; source: string; value: string } | null;
-	state_labels?: Record<string, string>;
-	tokens?: unknown;
-}
-
-export interface TabInfo {
-	tab_id: string;
-	workspace_id: string;
-	label?: string | null;
-	pane_count: number;
-}
-
-export interface AgentStartResult {
-	name: string;
-	paneId: string;
-	argv: string[];
-	/** Session path reported by herdr (F1) — absent for non-pi kinds (F7). */
-	sessionPath?: string;
-	agentStatus: string;
-}
-
-export interface ProcessInfo {
-	foregroundProcesses: Array<{
-		argv: string[];
-		cmdline: string;
-		pid: number;
-		name: string;
-		cwd?: string;
-	}>;
-	shellPid?: number;
-}
-
-/** Injectable runner so the client is unit-testable without a live herdr. */
-export type CommandRunner = (
-	args: string[],
-	opts?: { timeoutMs?: number; env?: Record<string, string | undefined> },
-) => Promise<{ stdout: string; stderr: string; code: number }>;
-
-export interface HerdrClient {
-	// ── panes ──
-	paneSplit(opts: {
-		target?: string;
-		current?: boolean;
-		direction: "right" | "down";
-		cwd?: string;
-		env?: Record<string, string>;
-		focus?: boolean;
-	}): Promise<HerdrResult<PaneInfo>>;
-	paneClose(paneId: string): Promise<HerdrResult<void>>;
-	paneRead(
-		paneId: string,
-		opts?: { source?: ReadSource; lines?: number },
-	): Promise<HerdrResult<string>>;
-	paneList(): Promise<HerdrResult<PaneInfo[]>>;
-	paneGet(paneId: string): Promise<HerdrResult<PaneInfo>>;
-	paneProcessInfo(paneId: string): Promise<HerdrResult<ProcessInfo>>;
-	paneReportMetadata(opts: {
-		paneId: string;
-		source: string;
-		displayAgent?: string;
-		title?: string;
-		tokens?: Record<string, string>;
-		/** `idle=waiting 2 subagents` — labels a herdr agent_status from this source. */
-		stateLabel?: { status: string; text: string };
-		/** Auto-expiry so a crashed reporter leaves no stale label. */
-		ttlMs?: number;
-		/** Drop all state-labels set by this source. */
-		clearStateLabels?: boolean;
-	}): Promise<HerdrResult<void>>;
-
-	// ── tabs ──
-	tabCreate(opts: {
-		cwd?: string;
-		label?: string;
-		focus?: boolean;
-		/** Environment for the tab's root pane process (lineage propagation). */
-		env?: Record<string, string>;
-		/** Pin the new tab to this Space (`herdr tab create --workspace`). */
-		workspaceId?: string;
-	}): Promise<HerdrResult<{ tab: TabInfo; rootPaneId: string }>>;
-	tabClose(tabId: string): Promise<HerdrResult<void>>;
-	tabRename(tabId: string, label: string): Promise<HerdrResult<void>>;
-	tabList(workspaceId?: string): Promise<HerdrResult<TabInfo[]>>;
-
-	// ── agents ──
-	agentStart(opts: {
-		name: string;
-		kind: AgentKind;
-		paneId: string;
-		args?: string[];
-		timeoutMs?: number;
-	}): Promise<HerdrResult<AgentStartResult>>;
-	agentPrompt(
-		target: string,
-		text: string,
-		opts?: { wait?: boolean; timeoutMs?: number },
-	): Promise<HerdrResult<AgentInfo>>;
-	agentGet(target: string): Promise<HerdrResult<AgentInfo>>;
-	agentList(): Promise<HerdrResult<AgentInfo[]>>;
-	agentSendKeys(target: string, ...keys: string[]): Promise<HerdrResult<void>>;
-	agentWait(
-		target: string,
-		opts?: { until?: string[]; timeoutMs?: number },
-	): Promise<HerdrResult<void>>;
-
-	// ── meta ──
-	version(): Promise<HerdrResult<string>>;
-	available(): Promise<boolean>;
-
-	// ── integrations ──
-	/** One integration's status, or null when herdr cannot report it. */
-	integrationStatus(target: string): Promise<HerdrResult<string | null>>;
-	/** Install an integration hook (idempotent on reinstall). */
-	integrationInstall(target: string): Promise<HerdrResult<string>>;
-}
-
-export type ReadSource =
-	| "visible"
-	| "recent"
-	| "recent-unwrapped"
-	| "detection";
-
 // =============================================================================
 // Session parsing (design §10)
 // =============================================================================
@@ -566,10 +392,21 @@ export interface ParsedSession {
 	/** True when the last user prompt has no assistant reply (F29 abort signal). */
 	lastTurnMissing: boolean;
 	tornLines: number;
+	/**
+	 * Cumulative model-generation wall time in ms: each completed assistant
+	 * message timestamp minus the preceding user or toolResult timestamp when
+	 * both are known. Tool/idle gaps are excluded. Approximate — session JSONL
+	 * records finished assistant messages, not mid-stream token boundaries.
+	 */
+	generationMs: number;
 }
 
 export interface TurnRecord {
 	userText: string;
+	/** Unix ms timestamp of the user message that opened this turn, when written. */
+	startedAt?: number;
+	/** Unix ms timestamp of the last assistant message in this turn, when written. */
+	endedAt?: number;
 	assistants: Array<{
 		stopReason: StopReason | null;
 		/**
@@ -606,7 +443,6 @@ export interface TurnRecord {
  */
 export interface Handle {
 	name: string;
-	paneId: string | null;
 	sessionFile: string;
 	runId: string;
 	agent: string;
@@ -637,15 +473,64 @@ export interface PresetConfig {
 	thinking?: string | false;
 }
 
+/** @deprecated Transitional herdr.* settings retained until v3. */
 export interface HerdrSettings {
-	defaultPlacement?: Placement;
+	/** @deprecated Parsed for transition compatibility; ignored by RPC v2. */
+	defaultPlacement?: "split-down" | "split-right" | "new-tab";
+	/** @deprecated Legacy concurrency hint; ignored by RPC v2. */
 	maxConcurrentAgents?: number;
+	/** @deprecated Legacy Herdr launch retry setting. */
 	startRetries?: number;
+	/** @deprecated Legacy Herdr launch retry setting. */
 	startRetryBackoffMs?: number;
+	/** @deprecated Legacy session retention setting. */
 	sessionRetentionDays?: number;
+	/** @deprecated Legacy session retention setting. */
 	sessionRetentionMaxBytesPerRun?: number;
 }
 
+export interface LegionPhaseTimeouts {
+	planning?: number;
+	implementing?: number;
+	reviewing?: number;
+	verifying?: number;
+}
+
+/** Settings for the v2 legion tree, incrementally consumed by its milestones. */
+export interface LegionSettings {
+	maxDepth?: number;
+	maxChildrenPerNode?: number;
+	maxActiveNodes?: number;
+	phaseTimeouts?: LegionPhaseTimeouts;
+	verifyCommandTimeoutMs?: number;
+	/** Post-create provisioning for child worktrees: "npm-install" or a shell command. */
+	worktreeBootstrap?: string;
+	worktreeBootstrapTimeoutMs?: number;
+	mailRatePer5Min?: number;
+	usagePollMs?: number;
+	orphanStaleMs?: number;
+}
+
+/** Defaults from the frozen v2 contract §11.4. */
+export const DEFAULT_LEGION_SETTINGS = {
+	maxDepth: 4,
+	maxChildrenPerNode: 8,
+	maxActiveNodes: 30,
+	phaseTimeouts: {
+		planning: 900_000,
+		implementing: 3_600_000,
+		reviewing: 1_800_000,
+		verifying: 900_000,
+	},
+	verifyCommandTimeoutMs: 600_000,
+	// Provisioning is opt-in: no default mode, a generous install budget.
+	worktreeBootstrap: "",
+	worktreeBootstrapTimeoutMs: 600_000,
+	mailRatePer5Min: 10,
+	usagePollMs: 30_000,
+	orphanStaleMs: 90_000,
+} as const satisfies Required<LegionSettings>;
+
 export type AgentOverride = Partial<AgentConfig> & { disabled?: boolean };
 
 export type TeamMember =
@@ -657,6 +542,22 @@ export interface TeamConfig {
 	members: TeamMember[];
 }
 
+/**
+ * Main-session scout guard (issue #17).
+ *
+ * After `threshold` consecutive read-like tool calls with no subagent or
+ * vexillatio dispatch, the parent session gets one follow-up reminder and
+ * then waits `cooldownMs`. Defaults: enabled, threshold 8, cooldown 120000.
+ * `/scout-guard` and `/no-scout-guard` override `enabled` for this session.
+ */
+export interface ScoutGuardSettings {
+	enabled?: boolean;
+	/** Positive integer. Default 8. */
+	threshold?: number;
+	/** Integer >= 0. Default 120000. */
+	cooldownMs?: number;
+}
+
 export interface SubagentsSettings {
 	/**
 	 * Master switch (default true). `false` stops new launches, system-prompt
@@ -711,11 +612,15 @@ export interface SubagentsSettings {
 	disableBuiltins?: boolean;
 	disableThinking?: boolean;
 	maxSubagentSpawnsPerSession?: number;
+	/** @deprecated Transitional herdr.* keys are parsed and ignored by RPC v2. */
 	herdr?: HerdrSettings;
+	legion?: LegionSettings;
 	/** Completion-notice merge mode. Default "smart". */
 	joinMode?: "each" | "smart";
 	/** smart-mode group flush window (ms). Default 10000. */
 	joinFlushMs?: number;
+	/** Main-session recon reminder. Absent fields use scout-guard defaults. */
+	scoutGuard?: ScoutGuardSettings;
 }
 
 /**
@@ -766,6 +671,7 @@ export class SubagentError extends Error {
 export const ErrorCodes = {
 	HERDR_UNAVAILABLE: "HERDR_UNAVAILABLE",
 	DISABLED: "DISABLED",
+	/** @deprecated Legacy Herdr client error retained for API compatibility. */
 	PANE_BUSY: "PANE_BUSY",
 	START_FAILED: "START_FAILED",
 	START_TIMEOUT: "START_TIMEOUT",
@@ -777,6 +683,7 @@ export const ErrorCodes = {
 	NOT_FOUND: "NOT_FOUND",
 	RETIRE_FAILED: "RETIRE_FAILED",
 	INVALID_PARAMS: "INVALID_PARAMS",
+	INSUFFICIENT_MEMORY: "INSUFFICIENT_MEMORY",
 } as const;
 
 // =============================================================================
@@ -784,28 +691,20 @@ export const ErrorCodes = {
 // =============================================================================
 
 export const DEFAULTS = {
-	/** F19/F20: agent_pane_busy race; retry with backoff. */
+	/** @deprecated Legacy Herdr start-retry settings retained by the archived backend. */
 	startRetries: 40,
 	startRetryBackoffMs: 150,
 	/** F8: agent wait covers a turn; generous default. */
 	turnTimeoutMs: 900_000,
 	/** jsonl quiet window before declaring a turn settled. */
 	settleQuietMs: 2_500,
+	/** @deprecated Legacy Herdr concurrency hint retained during migration. */
 	maxConcurrentAgents: 6,
+	/** @deprecated Legacy Herdr session retention setting. */
 	sessionRetentionDays: 7,
-	/** F22: missing binary surfaces as a ~15s timeout. */
+	/** @deprecated Legacy Herdr probe settings; retained for the archived backend. */
 	startTimeoutMs: 45_000,
 	binaryProbeTimeoutMs: 3_000,
-	/**
-	 * Default wall clock for ONE herdr CLI invocation (agent get, pane list,
-	 * tab create, …). Calls that need longer pass their own timeoutMs and are
-	 * NOT capped by this.
-	 *
-	 * Measured (hw 2026-10-09): a fork storm on the host wedged the herdr CLI
-	 * mid-invocation; with no cap, ONE stuck `agent get` froze the whole
-	 * collect/wait chain forever — the parent's `wait`/`collect` tool calls
-	 * never returned (55+ min, no toolResult). Every short control call now
-	 * fails fast with a timeout error the poll loops already tolerate.
-	 */
+	/** @deprecated Legacy Herdr command timeout retained for the archived backend. */
 	commandTimeoutMs: 15_000,
 } as const;

package/src/supervisor/child-memory.ts

@@ -0,0 +1,140 @@
+/**
+ * Child process memory controls.
+ *
+ * A) V8 flags for child pi processes, delivered via NODE_OPTIONS:
+ *    `--max-semi-space-size=1` (smaller young generation) and a soft
+ *    `--max-old-space-size` cap. The host's original NODE_OPTIONS is carried in
+ *    `PI_LEGION_HOST_NODE_OPTIONS` so the child restores it at extension load
+ *    and the flags never leak into bash commands the child runs (tsc /
+ *    npm test inheriting a low heap cap would crash).
+ *
+ * B) Memory gate: refuse a spawn when available memory (minus in-flight
+ *    reservations) is below a floor, instead of letting the host OOM.
+ */
+
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+
+export const CHILD_MAX_OLD_SPACE_ENV = "PI_LEGION_CHILD_MAX_OLD_SPACE_MB";
+export const CHILD_SEMI_SPACE_ENV = "PI_LEGION_CHILD_SEMI_SPACE_MB";
+export const HOST_NODE_OPTIONS_ENV = "PI_LEGION_HOST_NODE_OPTIONS";
+export const MIN_FREE_MEM_ENV = "PI_LEGION_MIN_FREE_MEM_MB";
+export const CHILD_RESERVE_ENV = "PI_LEGION_CHILD_RESERVE_MB";
+
+/** Measured: an idle child is ~100 MB PSS, a long scout session peaks ~160 MB RSS. */
+export const DEFAULT_CHILD_MAX_OLD_SPACE_MB = 1024;
+export const DEFAULT_CHILD_SEMI_SPACE_MB = 1;
+/** Floor of free memory that must remain after reserving the new child. */
+export const DEFAULT_MIN_FREE_MEM_MB = 1024;
+/** Per-child reservation for spawns that are still starting up. */
+export const DEFAULT_CHILD_RESERVE_MB = 160;
+
+function envMb(env: NodeJS.ProcessEnv, key: string, fallback: number): number {
+	const raw = env[key]?.trim();
+	if (!raw) return fallback;
+	const n = Number(raw);
+	return Number.isFinite(n) && n >= 0 ? Math.floor(n) : fallback;
+}
+
+/** Child NODE_OPTIONS: host options + memory flags (each disabled by 0). */
+export function childNodeOptions(env: NodeJS.ProcessEnv = process.env): string | undefined {
+	const host = env.NODE_OPTIONS?.trim() ?? "";
+	const flags: string[] = [];
+	const semi = envMb(env, CHILD_SEMI_SPACE_ENV, DEFAULT_CHILD_SEMI_SPACE_MB);
+	const old = envMb(env, CHILD_MAX_OLD_SPACE_ENV, DEFAULT_CHILD_MAX_OLD_SPACE_MB);
+	if (semi > 0 && !/--max-semi-space-size/.test(host)) flags.push(`--max-semi-space-size=${semi}`);
+	if (old > 0 && !/--max-old-space-size/.test(host)) flags.push(`--max-old-space-size=${old}`);
+	const merged = [host, ...flags].filter(Boolean).join(" ");
+	return merged || undefined;
+}
+
+/** Env entries the supervisor adds to every child pi process. */
+export function childMemoryEnv(env: NodeJS.ProcessEnv = process.env): Record<string, string | undefined> {
+	const nodeOptions = childNodeOptions(env);
+	if (nodeOptions === (env.NODE_OPTIONS?.trim() || undefined)) return {};
+	return { NODE_OPTIONS: nodeOptions, [HOST_NODE_OPTIONS_ENV]: env.NODE_OPTIONS ?? "" };
+}
+
+/**
+ * Called once in the child at extension load: put the host's NODE_OPTIONS back
+ * so tool subprocesses (bash → tsc / npm test) do not inherit the child caps.
+ */
+export function restoreHostNodeOptions(env: NodeJS.ProcessEnv = process.env): void {
+	if (!(HOST_NODE_OPTIONS_ENV in env)) return;
+	const host = env[HOST_NODE_OPTIONS_ENV] ?? "";
+	if (host) env.NODE_OPTIONS = host;
+	else delete env.NODE_OPTIONS;
+	delete env[HOST_NODE_OPTIONS_ENV];
+}
+
+// ── B) memory gate ────────────────────────────────────────────────────
+
+/** Available memory in MB: cgroup limit, /proc/meminfo, macOS vm_stat, os.freemem. */
+export function availableMemoryMb(): number {
+	const candidates: number[] = [];
+	try {
+		const m = /MemAvailable:\s+(\d+)\s+kB/.exec(fs.readFileSync("/proc/meminfo", "utf8"));
+		if (m) candidates.push(Number(m[1]) / 1024);
+	} catch { /* not linux */ }
+	try {
+		const max = fs.readFileSync("/sys/fs/cgroup/memory.max", "utf8").trim();
+		if (max !== "max") {
+			const cur = Number(fs.readFileSync("/sys/fs/cgroup/memory.current", "utf8").trim());
+			const limit = Number(max);
+			if (Number.isFinite(limit) && Number.isFinite(cur)) candidates.push((limit - cur) / (1024 * 1024));
+		}
+	} catch { /* no cgroup v2 limit */ }
+	if (candidates.length === 0 && process.platform === "darwin") {
+		try {
+			const out = execFileSync("vm_stat", { encoding: "utf8", timeout: 2_000 });
+			const page = Number(/page size of (\d+)/.exec(out)?.[1] ?? 4096);
+			const pages = (k: string) => Number(new RegExp(`Pages ${k}:\\s+(\\d+)`).exec(out)?.[1] ?? 0);
+			candidates.push(((pages("free") + pages("inactive") + pages("speculative")) * page) / (1024 * 1024));
+		} catch { /* fall through */ }
+	}
+	if (candidates.length === 0) candidates.push(os.freemem() / (1024 * 1024));
+	return Math.floor(Math.max(0, Math.min(...candidates)));
+}
+
+export interface MemoryGateConfig {
+	minFreeMb: number;
+	reserveMb: number;
+}
+
+export function resolveMemoryGateConfig(env: NodeJS.ProcessEnv = process.env): MemoryGateConfig {
+	return {
+		minFreeMb: envMb(env, MIN_FREE_MEM_ENV, DEFAULT_MIN_FREE_MEM_MB),
+		reserveMb: envMb(env, CHILD_RESERVE_ENV, DEFAULT_CHILD_RESERVE_MB),
+	};
+}
+
+export interface MemoryGateVerdict {
+	ok: boolean;
+	availableMb: number;
+	requiredMb: number;
+	message?: string;
+}
+
+/**
+ * Refuse when `available - reserve × (inFlight + 1) < minFree`. `inFlight`
+ * counts this supervisor's children still starting (their memory is not yet
+ * visible in MemAvailable), so a parallel burst cannot all pass one reading.
+ */
+export function checkMemoryGate(input: { name: string; inFlight: number; config?: MemoryGateConfig; available?: () => number }): MemoryGateVerdict {
+	const config = input.config ?? resolveMemoryGateConfig();
+	if (config.minFreeMb <= 0) return { ok: true, availableMb: -1, requiredMb: 0 };
+	const availableMb = (input.available ?? availableMemoryMb)();
+	const requiredMb = config.minFreeMb + config.reserveMb * (input.inFlight + 1);
+	if (availableMb >= requiredMb) return { ok: true, availableMb, requiredMb };
+	return {
+		ok: false,
+		availableMb,
+		requiredMb,
+		message:
+			`insufficient memory to start subagent ${input.name}: ${availableMb} MB available, ` +
+			`${requiredMb} MB required (${MIN_FREE_MEM_ENV}=${config.minFreeMb} + ${config.reserveMb} MB per starting child × ${input.inFlight + 1}). ` +
+			`Wait for running subagents to finish (or stop some with /legion stop) before retrying; ` +
+			`set ${MIN_FREE_MEM_ENV}=0 to disable this gate.`,
+	};
+}