pi-legion 2.0.3 → 3.0.0

package/src/shared/timing-breakdown.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared wall/gen/other math for `/legion timing` (#150) and the TUI timing panel (#151).
+ * Zero schema — callers supply wall_ms and generation_ms (null = no turn data → other —).
+ */
+export interface TimingBreakdown {
+	wall_ms: number;
+	generation_ms: number | null;
+	/** max(0, wall − gen); null when generation_ms is null. Coarse bucket, not wait/tool. */
+	other_ms: number | null;
+}
+
+/** Pure breakdown: other = max(0, wall − gen); gen absent → other —. */
+export function breakdown(
+	wall_ms: number,
+	generation_ms: number | null,
+): TimingBreakdown {
+	return {
+		wall_ms,
+		generation_ms,
+		other_ms:
+			generation_ms === null ? null : Math.max(0, wall_ms - generation_ms),
+	};
+}

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.
+}