pi-legion 2.0.4 → 3.0.0

package/src/runs/orchestrator.ts

@@ -12,13 +12,13 @@ import * as path from "node:path";
 import { modelCandidates } from "../agents/model-resolution.ts";
 import { DEFAULT_TEAM, TEAM_ENV, type ActiveTeam } from "../agents/teams.ts";
 import type { LegionSettings } from "../shared/types.ts";
-import { LEGION_DB_ENV, LEGION_IDENTITY_ENV_KEYS, LEGION_NODE_ID_ENV, legionIdentityEnv } from "./args.ts";
+import { LEGION_IDENTITY_ENV_KEYS, legionIdentityEnv } from "./args.ts";
 import type { DatabaseSync } from "../legion/db.ts";
 import type { RunStore } from "./store.ts";
 import type { LegionEventBus, LegionProcessEventType } from "../extension/event-bus.ts";
 import { appendEvent } from "../legion/events.ts";
 import { withLaunchBudget, type LegionBudgetLimits } from "../legion/budget.ts";
-import { getChildByName, getNode, insertNode, nodeIdForChild, sanitizeNodeSlug, type LegionNode, updateNode, LIVE_CHILD_STATUSES } from "../legion/nodes.ts";
+import { getChildByName, getNode, insertNode, nodeIdForChild, sanitizeNodeSlug, type LegionNode, updateNode } from "../legion/nodes.ts";
 import { upsertUsage } from "../legion/usage.ts";
 import { evaluatePhaseTransition, isLegionPhase, isTerminalPhase } from "../legion/state-machine.ts";
 import { CHILD_ACCEPTANCE_ROLE_ENV, CHILD_ROLE_ENV } from "../extension/child-guard.ts";
@@ -54,11 +54,13 @@ import {
 	type NestedPathEntry,
 	type RetireOptions,
 	type RunRecord,
+	type SpawnMode,
 	SubagentError,
 	type Usage,
 } from "../shared/types.ts";
 import { RpcSupervisor } from "../supervisor/rpc-supervisor.ts";
 import type { LegionSupervisor, SettleResult, SpawnInput } from "../supervisor/types.ts";
+import { isInProcessSpawn, resolveSpawnMode } from "../supervisor/spawn-mode.ts";
 import type { PendingUIRequest, UIProxy } from "../supervisor/ui-proxy.ts";
 import { nativeModelFor } from "./kind.ts";
 import { applyVerification, type VerifyRunner } from "./acceptance.ts";
@@ -107,6 +109,11 @@ export interface OrchestratorDeps {
 	worktreeBootstrapTimeoutMs?: number;
 	team?: ActiveTeam;
 	childContext?: string;
+	/**
+	 * When true, RPC child argv includes `--approve` (`subagents.rpc.approve`).
+	 * Default false / omitted.
+	 */
+	rpcApprove?: boolean;
 	onBudgetRefused?: (event: BudgetRefusedEvent) => void;
 }
 
@@ -132,9 +139,20 @@ const CHILD_ENV = "PI_SUBAGENT_CHILD";
 const POLL_INTERVAL_MS = 500;
 
 function parseDepthCeiling(raw: string | undefined): number | undefined {
-	if (raw === undefined || !/^\d+$/.test(raw.trim())) return undefined;
-	const value = Number(raw.trim());
-	return Number.isInteger(value) && value >= 0 ? value : undefined;
+	// Genuinely unset / blank → no env ceiling (settings + hard cap still apply).
+	if (raw === undefined) return undefined;
+	const t = raw.trim();
+	if (t === "") return undefined;
+	// #173: illegal values fail closed to leaf-only (0), matching contract :361 —
+	// never widen to the hard cap via `undefined` → +Infinity.
+	if (!/^\d+$/.test(t)) {
+		console.error(
+			`[pi-legion] ${MAX_DEPTH_ENV}=${JSON.stringify(t)} is not a non-negative integer; treating as 0 (leaf only).`,
+		);
+		return 0;
+	}
+	const value = Number(t);
+	return Number.isInteger(value) && value >= 0 ? value : 0;
 }
 
 /** Root/process ceiling: inherited env, settings, and the saturated path cap. */
@@ -234,6 +252,7 @@ export class Orchestrator {
 	private readonly worktreeBootstrapTimeoutMs?: number;
 	private readonly team?: ActiveTeam;
 	private readonly childContext?: string;
+	private readonly rpcApprove: boolean;
 	private readonly onBudgetRefused?: (event: BudgetRefusedEvent) => void;
 	private readonly legion?: OrchestratorLegionContext;
 	private readonly requestedDepthCap?: number;
@@ -267,6 +286,7 @@ export class Orchestrator {
 		this.worktreeBootstrapTimeoutMs = deps.worktreeBootstrapTimeoutMs;
 		this.team = deps.team;
 		this.childContext = deps.childContext?.trim() || undefined;
+		this.rpcApprove = deps.rpcApprove === true;
 		this.onBudgetRefused = deps.onBudgetRefused;
 		this.legion = deps.legion;
 	}
@@ -341,11 +361,24 @@ export class Orchestrator {
 		const depthCeiling = input.utility
 			? parent.depth + 1
 			: Math.min(legion.settings?.maxDepth ?? this.maxDepthValue, MAX_NESTED_PATH_ENTRIES);
-		const liveStatuses = LIVE_CHILD_STATUSES.map(() => "?").join(", ");
-		const childCount = Number(legion.db.prepare(`SELECT COUNT(*) AS count FROM nodes WHERE parent_id = ? AND status IN (${liveStatuses})`).get(legion.nodeId, ...LIVE_CHILD_STATUSES)?.count ?? 0);
-		const maxChildren = previous ? Math.max(legion.settings?.maxChildrenPerNode ?? 8, childCount + 1) : legion.settings?.maxChildrenPerNode;
+		// Resume must NOT inflate maxChildrenPerNode (#180). Retired nodes free
+		// slots (#142); turning one live again re-charges the fanout cap — same
+		// gate as a fresh launch. activeReservation below still covers the node's
+		// own maxActiveNodes slot when it is already starting/running.
+		const maxChildren = legion.settings?.maxChildrenPerNode ?? 8;
 		const activeReservation = previous && (previous.status === "starting" || previous.status === "running") ? 1 : 0;
-		const limits: LegionBudgetLimits = { maxDepth: depthCeiling, maxChildrenPerNode: maxChildren, maxActiveNodes: (legion.settings?.maxActiveNodes ?? 30) + activeReservation };
+		// In-process children use subagents.inprocess.* only — do not spend RPC legion.* slots (#197).
+		const limits: LegionBudgetLimits = isInProcessSpawn(input.agent)
+			? {
+					maxDepth: MAX_NESTED_PATH_ENTRIES,
+					maxChildrenPerNode: Number.MAX_SAFE_INTEGER,
+					maxActiveNodes: Number.MAX_SAFE_INTEGER,
+			  }
+			: {
+					maxDepth: depthCeiling,
+					maxChildrenPerNode: maxChildren,
+					maxActiveNodes: (legion.settings?.maxActiveNodes ?? 30) + activeReservation,
+			  };
 		const gate = withLaunchBudget(legion.db, { parentId: legion.nodeId, depth: parent.depth + 1, nodeId: input.nodeId }, () => {
 			if (previous) {
 				updateNode(legion.db, input.nodeId, { status: "starting", sessionFile: input.sessionFile, worktreePath: input.worktreePath ?? previous.worktreePath, model: input.model ?? previous.model, team: team && team !== DEFAULT_TEAM ? team : previous.team }, this.now);
@@ -520,10 +553,6 @@ export class Orchestrator {
 		const ledgerPrevious = nodeId ? getNode(this.legion!.db, nodeId) : null;
 		const previous = this.children.get(name) ?? (ledgerPrevious ? this.childFromNode(name, ledgerPrevious) : undefined);
 		if (previous && !this.children.has(name)) this.children.set(name, previous);
-		// A utility dispatch is a hard leaf, not a nested command-chain launch.
-		// The frozen contract therefore skips assertWithinBudgets entirely.
-		if (!input.utilityDispatch) this.assertWithinBudgets(Boolean(previous));
-		if (this.supervisor.isAlive(name)) throw new SubagentError(`child is already alive: ${name}`, ErrorCodes.NAME_TAKEN);
 		const models = this.planModelCandidates({
 			agent: input.agent,
 			...(input.model !== undefined ? { model: input.model } : {}),
@@ -542,6 +571,53 @@ export class Orchestrator {
 					launch: input.worktree,
 					parentInWorktree: isInsideChildWorktree(this.cwd),
 				});
+		// Spawn-mode arbitration (contract D2). `resolveSpawnMode` only reports the
+		// configured intent; the launch context decides whether an OMITTED mode can
+		// actually run in-process. An omitted mode falls back to rpc when this
+		// launch needs worktree isolation (a hard requirement of the in-process
+		// backend). An explicit value is never downgraded (invariant I6) — a bad
+		// explicit combination still throws below.
+		// `kind !== "pi"` is NOT re-tested here: the early guard above (before this
+		// arbitration) already refuses it, so such a clause would be dead code.
+		const explicitMode = input.agent.spawnMode !== undefined;
+		const mode: SpawnMode =
+			!explicitMode && worktree === true
+				? "rpc"
+				: resolveSpawnMode(input.agent);
+		const inProcess = mode === "inprocess";
+		// Downstream must see the arbitrated result, otherwise RoutingSupervisor
+		// re-resolves the omitted field to `inprocess` on its own and throws
+		// "cannot combine with worktree: true" — the arbitration would be moot.
+		// `worktree` is normalized too: a role card that pins `worktree: true`
+		// (e.g. `agents/worker.md`) keeps that raw value even when THIS launch
+		// resolved to no isolation (`parentRole === "centurion"`, an explicit
+		// `launch({ worktree: false })`, or the nested-worktree suppression), and
+		// leaking it makes `{spawnMode:"inprocess", worktree:true}` reach
+		// routing-supervisor.ts:79 / inprocess-supervisor.ts:342, which reject it
+		// with INVALID_PARAMS. That shape is exactly the "centurion dispatches
+		// worker" production path, so it must be normalized to `worktree: false`.
+		// The `&& worktree` short-circuit keeps the rpc path returning the
+		// original object (invariant I3: zero diff on the RPC backend).
+		// reserveNode() and SpawnInput.agent below both receive this clone.
+		const agent: AgentConfig = mode === input.agent.spawnMode && worktree
+			? input.agent
+			: { ...input.agent, spawnMode: mode, ...(worktree ? {} : { worktree: false }) };
+		// A utility dispatch is a hard leaf, not a nested command-chain launch.
+		// In-process children use subagents.inprocess.* budgets (never RPC keys).
+		if (!input.utilityDispatch && !inProcess) this.assertWithinBudgets(Boolean(previous));
+		if (this.supervisor.isAlive(name)) throw new SubagentError(`child is already alive: ${name}`, ErrorCodes.NAME_TAKEN);
+		// Only an EXPLICIT inprocess can reach this: the arbitration above already
+		// routed every omitted-mode launch that needs a worktree to rpc, so I1
+		// (explicit inprocess + worktree stays a loud throw) holds. This replaces
+		// the old gate, which inspected the raw `worktree` fields and therefore
+		// rejected callers that explicitly overrode a worktree role with
+		// `launch({ worktree: false })` — that override now wins as it should.
+		if (inProcess && worktree) {
+			throw new SubagentError(
+				`spawnMode "inprocess" cannot use worktree isolation for '${name}'`,
+				ErrorCodes.INVALID_PARAMS,
+			);
+		}
 		let worktreePath = previous?.worktreePath;
 		let worktreeBranch = previous?.worktreeBranch;
 		let createdWorktree = false;
@@ -588,7 +664,7 @@ export class Orchestrator {
 			preCreateSessionFile(sessionFile);
 			if (this.legion && nodeId) {
 				const reservationRunId = createdRunId ?? (previous ? ledgerPrevious?.runId : undefined) ?? this.legion.runId;
-				reservedNode = this.reserveNode({ nodeId, name, agent: input.agent, task: input.task, sessionFile, runId: reservationRunId, team: input.team, worktreePath, model: models.candidates[0], utility: Boolean(input.utilityDispatch && input.agent.utility) });
+				reservedNode = this.reserveNode({ nodeId, name, agent, task: input.task, sessionFile, runId: reservationRunId, team: input.team, worktreePath, model: models.candidates[0], utility: Boolean(input.utilityDispatch && input.agent.utility) });
 				reserved = true;
 				parentReservationCreated = await this.persistParentReservation({ nodeId, name, agent: input.agent, sessionFile, ...(models.candidates[0] ? { model: models.candidates[0] } : {}), ...(worktreePath ? { worktreePath } : {}) });
 			}
@@ -604,7 +680,7 @@ export class Orchestrator {
 				const spawnInput: SpawnInput = {
 					name,
 					task: input.task,
-					agent: input.agent,
+					agent,
 					sessionFile,
 					tempDir,
 					cwd: worktreePath ?? this.cwd,
@@ -616,6 +692,34 @@ export class Orchestrator {
 					...(input.agent.allowNestedSubagents !== undefined && !input.agent.utility ? { allowNestedSubagents: input.agent.allowNestedSubagents } : {}),
 					...(worktreeBranch ? { worktreeBranch } : {}),
 					...(this.childContext ? { childContext: this.childContext } : {}),
+					...(this.rpcApprove ? { approve: true } : {}),
+					// D5: in-process children cannot inherit lineage through env (they share
+					// the parent's process.env and would read the PARENT's identity, or none
+					// at the root). Hand the arbitrator a real identity scope instead. Only
+					// the in-process backend consumes it; RPC lineage stays on env (I3).
+					//
+					// `stripLegionIdentity` (vexillatio) must mask lineage on BOTH
+					// channels: the env keys are deleted above, so the context must not
+					// hand back the same identity through ALS. Keep the scope (so the
+					// child still knows it is not the root) but omit node/db lineage.
+					...(inProcess && this.legion
+						? {
+								childLaunchContext: {
+									...(!input.stripLegionIdentity && nodeId ? { nodeId } : {}),
+									...(input.stripLegionIdentity
+										? {}
+										: { parentNodeId: this.legion.nodeId, dbPath: this.legion.dbPath }),
+									// The nested path is lineage too: LEGION_IDENTITY_ENV_KEYS
+									// strips PI_SUBAGENT_PARENT_PATH on the rpc side, so the
+									// in-process channel must not hand it back.
+									...(input.stripLegionIdentity ? {} : { parentPath: this.childPath(name) }),
+									...(agent.acceptance?.role ? { acceptanceRole: agent.acceptance.role } : {}),
+									allowNested: input.agent.allowNestedSubagents === true && !input.agent.utility,
+									utility: Boolean(input.utilityDispatch && input.agent.utility),
+									spawnMode: "inprocess" as const,
+								},
+							}
+						: {}),
 				};
 				try {
 					result = await this.supervisor.spawnChild(spawnInput);
@@ -1128,7 +1232,12 @@ export class Orchestrator {
 		if (opts?.cause === "session-shutdown" && this.supervisor.isAlive(name)) {
 			child.execution = attributeParentSessionShutdown(child.execution ?? deriveOutcome(parsed), parsed);
 		}
-		if (this.supervisor.isAlive(name)) await this.supervisor.retire(name);
+		if (this.supervisor.isAlive(name)) {
+			await this.supervisor.retire(
+				name,
+				opts?.graceful === false ? { graceful: false } : {},
+			);
+		}
 		if (child.nodeId && this.legion) {
 			if (child.execution && child.execution.status !== "unknown" && child.execution.status !== "running") {
 				this.recordSettled(child, child.execution);

package/src/shared/output-cap.ts

@@ -11,12 +11,12 @@
 export const DEFAULT_MAX_OUTPUT_BYTES = 8 * 1024 * 1024;
 export const MAX_OUTPUT_BYTES_ENV = "PI_LEGION_MAX_OUTPUT_BYTES";
 
-/** Resolve the per-stream cap from env; garbage / <=0 → default. */
+/** Resolve the per-stream cap from env; garbage / floored < 1 → default (#174). */
 export function resolveMaxOutputBytes(env: NodeJS.ProcessEnv = process.env): number {
 	const raw = env[MAX_OUTPUT_BYTES_ENV]?.trim();
 	if (!raw) return DEFAULT_MAX_OUTPUT_BYTES;
 	const n = Number(raw);
-	return Number.isFinite(n) && n > 0 ? Math.floor(n) : DEFAULT_MAX_OUTPUT_BYTES;
+	return Number.isFinite(n) && n >= 1 ? Math.floor(n) : DEFAULT_MAX_OUTPUT_BYTES;
 }
 
 export interface CappedOutput {

package/src/shared/session.ts

@@ -327,7 +327,8 @@ const SESSION_CACHE_MAX_ENTRIES = 64;
 export function resolveSessionMaxLineBytes(env: NodeJS.ProcessEnv = process.env): number {
 	const raw = env[SESSION_MAX_LINE_BYTES_ENV]?.trim();
 	const n = raw ? Number(raw) : NaN;
-	return Number.isFinite(n) && n > 0 ? Math.floor(n) : DEFAULT_SESSION_MAX_LINE_BYTES;
+	// #174: require floored value >= 1 — (0,1) must not become cap=0.
+	return Number.isFinite(n) && n >= 1 ? Math.floor(n) : DEFAULT_SESSION_MAX_LINE_BYTES;
 }
 
 interface SessionParseState {

package/src/shared/types.ts

@@ -46,6 +46,11 @@ export const AGENT_KINDS = [
 
 export type AgentKind = (typeof AGENT_KINDS)[number];
 
+/** How Legion launches a child session: omit → `inprocess` (with automatic rpc fallback when the agent needs a worktree or `kind !== "pi"`). */
+export const SPAWN_MODES = ["rpc", "inprocess"] as const;
+export type SpawnMode = (typeof SPAWN_MODES)[number];
+
+
 /**
  * How the model a child starts with was chosen.
  *
@@ -149,6 +154,15 @@ export interface AgentConfig {
 	kind: AgentKind;
 	worktree?: boolean;
 	steer?: boolean;
+	/**
+	 * Launch backend for this role. Omit → `inprocess` (createAgentSession in
+	 * the parent Node process), with automatic rpc fallback when the resolved
+	 * spawn needs a worktree (`worktree: true`, the writer/centurion default)
+	 * or `kind !== "pi"`. An explicit `inprocess` + `worktree: true` is still
+	 * refused with `INVALID_PARAMS` — the fallback only applies to the implicit
+	 * default, never to an explicit request.
+	 */
+	spawnMode?: SpawnMode;
 	onBlocked?: OnBlockedPolicy;
 
 	// ── provenance ──
@@ -252,6 +266,12 @@ export interface Execution {
  */
 export interface RetireOptions {
 	cause?: "session-shutdown";
+	/**
+	 * When false, skip graceful stdin-close and escalate via retire hardening
+	 * (SIGTERM → SIGKILL + descendant sweep). Default / omitted = graceful.
+	 * Used by `subagent({ action: "stop", force: true })` (#179).
+	 */
+	graceful?: boolean;
 }
 
 export interface Usage {
@@ -548,6 +568,19 @@ export type TeamMember =
 export interface TeamConfig {
 	description?: string;
 	members: TeamMember[];
+	/**
+	 * Same forms as `subagents.parentContext` (inline / `@path` / array).
+	 * Replaces the global parent context for this team; `false` disables
+	 * parent injection without falling through to global/convention.
+	 * Omitted → fall back to global `subagents.parentContext` (or convention).
+	 */
+	parentContext?: string | string[] | false;
+	/**
+	 * Same forms as `subagents.childContext`. Replaces the global child
+	 * context for this team; `false` disables child injection (no fallthrough).
+	 * Omitted → fall back to global `subagents.childContext` (or convention).
+	 */
+	childContext?: string | string[] | false;
 }
 
 /**
@@ -566,6 +599,37 @@ export interface ScoutGuardSettings {
 	cooldownMs?: number;
 }
 
+
+/**
+ * Concurrency / depth / wait limits for the in-process supervisor (#197).
+ * Keys are independent of RPC / legion.* budgets — never fall back to those.
+ *
+ * Defaults mirror `legion.*` when the whole `inprocess` block is absent:
+ * `maxDepth: 4` / `maxChildrenPerNode: 8` / `maxActive: 30`. With an explicit
+ * block that omits `maxActive`, `maxActive` is 8. `maxSpawnsPerSession` and
+ * `waitTimeoutMs` have no default (unlimited).
+ */
+export interface InProcessLimits {
+	maxSpawnsPerSession?: number;
+	maxDepth?: number;
+	maxActive?: number;
+	maxChildrenPerNode?: number;
+	waitTimeoutMs?: number;
+}
+
+/**
+ * RPC-child spawn knobs (#193). Opt-in only — default stays no `--approve`.
+ * v1 does not emit `--no-approve`.
+ */
+export interface RpcSettings {
+	/**
+	 * When true, child `pi --mode rpc` argv includes `--approve` so project
+	 * `.pi/settings.json` / project resources / extension discovery can load
+	 * without a prior `/trust` decision. Default false (omit the flag).
+	 */
+	approve?: boolean;
+}
+
 export interface SubagentsSettings {
 	/**
 	 * Master switch (default true). `false` stops new launches, system-prompt
@@ -629,6 +693,16 @@ export interface SubagentsSettings {
 	joinFlushMs?: number;
 	/** Main-session recon reminder. Absent fields use scout-guard defaults. */
 	scoutGuard?: ScoutGuardSettings;
+	/**
+	 * Limits for `spawnMode: "inprocess"` children only (#197).
+	 * RPC path never reads these keys.
+	 */
+	inprocess?: InProcessLimits;
+	/**
+	 * RPC-child spawn options (#193). Default omits `--approve`; set
+	 * `rpc.approve: true` to append it. Not an inherit-parent-trust channel.
+	 */
+	rpc?: RpcSettings;
 }
 
 /**

package/src/supervisor/child-context.ts

@@ -0,0 +1,90 @@
+/**
+ * In-process child identity channel (#197 / spawn-default-inprocess-v3 D5).
+ *
+ * An in-process child session shares the host's `process.env`: it sees the
+ * *parent's* values, not an empty environment. So env cannot carry lineage
+ * identity for it — `PI_SUBAGENT_CHILD` is empty at the root and the child
+ * would be mistaken for another root. Identity therefore travels through an
+ * AsyncLocalStorage scope instead.
+ *
+ * Why the store lives on `globalThis` under `Symbol.for(...)`:
+ * `jiti` may re-evaluate this module with `moduleCache: false` (the extension
+ * host does exactly that for a child's `--extension` load). A module-level
+ * `const store = new AsyncLocalStorage()` would be a *different* instance on
+ * every re-evaluation, so a value written by one module instance would be
+ * invisible to the other — the store would look empty and identity would be
+ * silently lost. `Symbol.for` is registry-backed and `globalThis` survives
+ * module re-evaluation (measured: `childMod.store === shared` after jiti
+ * reload). Do not replace this with a module-level constant.
+ *
+ * Security property: AsyncLocalStorage does NOT cross a `spawn()` boundary, so
+ * a real subprocess (`bash npm test`, a nested `pi` CLI, …) can never inherit
+ * this identity. The env channel lacked exactly that isolation (see the
+ * healthy-ghost-nodes incident). Never re-introduce an env fallback here.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { NestedPathEntry, SpawnMode } from "../shared/types.ts";
+
+/** Lineage identity of one in-process child session. Never routed via process.env. */
+export interface ChildLaunchContext {
+	/** Legion node id of this child session (undefined for a root-level in-process child). */
+	nodeId?: string;
+	/** Parent legion node id. */
+	parentNodeId?: string;
+	/** Absolute path to legion.db. */
+	dbPath?: string;
+	/**
+	 * The caller's nested path segments, so the child's orchestrator can continue it.
+	 * Same shape as the RPC lineage path (`NestedPathEntry`), not bare strings.
+	 */
+	parentPath?: NestedPathEntry[];
+	/** The role's `acceptance.role` (read-only / writer / …). */
+	acceptanceRole?: string;
+	/** Whether this child may spawn children of its own (maps to allowNestedSubagents). */
+	allowNested: boolean;
+	/** Utility hard leaf. */
+	utility: boolean;
+	/** Spawn backend of this child, so the child's doctor/diagnostics can self-report. */
+	spawnMode: SpawnMode;
+}
+
+const STORE_KEY = Symbol.for("pi-legion.child-context.als");
+
+/** Symbol-indexed view of globalThis so the store survives module re-evaluation. */
+type StoreHolder = {
+	[key: symbol]: AsyncLocalStorage<ChildLaunchContext> | undefined;
+};
+
+// SAFETY: `globalThis` is an object, so a `Symbol.for`-keyed property on it is
+// readable; the only invariant TypeScript cannot check is that whoever wrote
+// that slot first stored an AsyncLocalStorage under this exact symbol key. Both
+// sides of that contract live in this file, so the slot type is authoritative.
+const store = ((globalThis as unknown as StoreHolder)[STORE_KEY] ??=
+	new AsyncLocalStorage<ChildLaunchContext>());
+
+/** Run `fn` under `ctx`; everything awaited inside (tool execution included) inherits it. */
+export function runInChildContext<T>(
+	ctx: ChildLaunchContext,
+	fn: () => Promise<T>,
+): Promise<T> {
+	return store.run(ctx, fn);
+}
+
+/** Identity of the current child session; undefined in the root process/session. */
+export function currentChildContext(): ChildLaunchContext | undefined {
+	return store.getStore();
+}
+
+/**
+ * Run `fn` outside any child identity (REV2-7).
+ *
+ * Parent-side callbacks are reached synchronously from inside a child's await
+ * chain — an `onEvent` listener is the case in point. Letting such a callback
+ * observe the child's identity makes host code believe it *is* the child (and
+ * inherit the child's spawn permissions). Anything leaving the child's own
+ * execution path must step out of the scope first.
+ */
+export function runOutsideChildContext<T>(fn: () => T): T {
+	return store.exit(fn);
+}

package/src/supervisor/child-memory.ts

@@ -25,16 +25,35 @@ 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;
+/**
+ * Empirically: old-space below ~8 MB fails to start on Node v20/v24 (rc 133/134/139).
+ * Clamp positive values up to this floor (#175); `0` remains the disable sentinel.
+ */
+export const MIN_CHILD_MAX_OLD_SPACE_MB = 16;
 /** 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 {
+function envMb(
+	env: NodeJS.ProcessEnv,
+	key: string,
+	fallback: number,
+	minPositive?: 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;
+	if (!Number.isFinite(n) || n < 0) return fallback;
+	if (n === 0) return 0; // 0 = disabled
+	const floored = Math.floor(n);
+	if (minPositive !== undefined && floored < minPositive) {
+		console.error(
+			`[pi-legion] ${key}=${raw} is below the usable minimum ${minPositive} MB; using ${minPositive}.`,
+		);
+		return minPositive;
+	}
+	return floored;
 }
 
 /** Child NODE_OPTIONS: host options + memory flags (each disabled by 0). */
@@ -42,7 +61,12 @@ export function childNodeOptions(env: NodeJS.ProcessEnv = process.env): string |
 	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);
+	const old = envMb(
+		env,
+		CHILD_MAX_OLD_SPACE_ENV,
+		DEFAULT_CHILD_MAX_OLD_SPACE_MB,
+		MIN_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(" ");

package/src/supervisor/inprocess-depth.ts

@@ -0,0 +1,71 @@
+/**
+ * Process-local nesting depth for in-process children (#197).
+ * Independent of RPC / PI_SUBAGENT_* depth env.
+ *
+ * The store lives on `globalThis` under `Symbol.for(...)` rather than in a
+ * module-level `const store = new AsyncLocalStorage()`: jiti may re-evaluate
+ * this module with `moduleCache: false`, and each re-evaluation would create a
+ * fresh, empty store — the depth would silently reset to 0 in a re-loaded
+ * module instance and the nesting limit would be bypassed. `globalThis` +
+ * `Symbol.for` keeps one instance across module re-evaluation (measured:
+ * `childMod.store === shared` after a jiti reload).
+ *
+ * Depth is also *not* inherited by real subprocesses: AsyncLocalStorage does
+ * not cross `spawn()`. Only in-process children (same JS process) accumulate.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+const STORE_KEY = Symbol.for("pi-legion.inprocess-depth.als");
+
+/** Symbol-indexed view of globalThis so the store survives module re-evaluation. */
+type StoreHolder = {
+	[key: symbol]: AsyncLocalStorage<number> | undefined;
+};
+
+// SAFETY: `globalThis` is an object, so a `Symbol.for`-keyed property on it is
+// readable; the invariant TypeScript cannot check is that the slot holds a
+// number-depth AsyncLocalStorage. Both writer and reader of that slot are in
+// this file, so the declared slot type is authoritative.
+const store = ((globalThis as unknown as StoreHolder)[STORE_KEY] ??=
+	new AsyncLocalStorage<number>());
+
+/** Current in-process nesting depth (0 at the host session). */
+export function inProcessDepth(): number {
+	return store.getStore() ?? 0;
+}
+
+/** Run `fn` at depth = current + 1. */
+export function runAtInProcessChildDepth<T>(fn: () => T): T {
+	return store.run(inProcessDepth() + 1, fn);
+}
+
+/** Run async `fn` at depth = current + 1. */
+export async function runAtInProcessChildDepthAsync<T>(
+	fn: () => Promise<T>,
+): Promise<T> {
+	return store.run(inProcessDepth() + 1, fn);
+}
+
+/**
+ * Run async `fn` at an absolute depth (REV2-1).
+ *
+ * `runAtInProcessChildDepthAsync` computes `current + 1`, which is right only
+ * while the caller is itself nested. The Orchestrator drives every turn after
+ * the first from the **root** chain (`orchestrator.ts` `prompt`/`followUp`), so
+ * there `inProcessDepth()` is 0 and `current + 1` would always be 1 — the
+ * recorded nesting would collapse and `maxDepth` could never fire, allowing
+ * unbounded recursion across generations. Dispatching with the child's own
+ * recorded depth (its `spawnDepth`) restores the real nesting level.
+ */
+export async function runAtAbsoluteDepth<T>(
+	depth: number,
+	fn: () => Promise<T>,
+): Promise<T> {
+	return store.run(depth, fn);
+}
+
+/** @internal */
+export function resetInProcessDepthForTests(): void {
+	// AsyncLocalStorage has no global clear; tests should avoid leaking across awaits.
+}