pi-legion 2.0.4 → 3.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-legion",
-  "version": "2.0.4",
+  "version": "3.0.1",
   "description": "Pi Legion v2: recursive centurion trees on headless Pi RPC; shared SQLite WAL legion.db. Four-stage planning/implementing/reviewing/verifying state machine, parent/child/sibling legion_mail, three-layer /legion UI, upward MR trees, squad resume.",
   "type": "module",
   "license": "MIT",
@@ -48,17 +48,6 @@
     "CONTRIBUTING.md",
     "LICENSE"
   ],
-  "scripts": {
-    "typecheck": "tsc --noEmit",
-    "test": "env -u PI_SUBAGENT_ALLOW_NESTED -u PI_SUBAGENT_CHILD -u PI_SUBAGENT_UTILITY_CHILD -u PI_SUBAGENT_MAX_DEPTH -u PI_SUBAGENT_PARENT_PATH -u PI_LEGION_DB -u PI_LEGION_NODE_ID node --experimental-strip-types --test test/unit/*.test.ts",
-    "test:integration": "env -u PI_SUBAGENT_ALLOW_NESTED -u PI_SUBAGENT_CHILD -u PI_SUBAGENT_UTILITY_CHILD -u PI_SUBAGENT_MAX_DEPTH -u PI_SUBAGENT_PARENT_PATH -u PI_LEGION_DB -u PI_LEGION_NODE_ID node --experimental-strip-types --test test/integration/*.test.ts",
-    "test:live": "env -u PI_SUBAGENT_ALLOW_NESTED -u PI_SUBAGENT_CHILD -u PI_SUBAGENT_UTILITY_CHILD -u PI_SUBAGENT_MAX_DEPTH -u PI_SUBAGENT_PARENT_PATH -u PI_LEGION_DB -u PI_LEGION_NODE_ID node --experimental-strip-types --test test/live/*.test.ts",
-    "test:all": "npm run typecheck && npm run test && npm run test:integration",
-    "test:docker": "env -u PI_SUBAGENT_ALLOW_NESTED -u PI_SUBAGENT_CHILD -u PI_SUBAGENT_UTILITY_CHILD -u PI_SUBAGENT_MAX_DEPTH -u PI_SUBAGENT_PARENT_PATH sh -c 'echo \"RPC mainline Docker checks only; legacy Herdr workspace/kind/notification scenarios are archived under test/legacy/docker and require pi-legion v0.16.x\" && bash test/docker/verify-1-child-guard.sh && bash test/docker/verify-2-task-appendix.sh && bash test/docker/verify-3-readonly.sh && bash test/docker/verify-4-acceptance.sh && bash test/docker/verify-5-blocked.sh && bash test/docker/verify-6-cache.sh && bash test/docker/verify-7-budget.sh && bash test/docker/verify-8-verify-command.sh && bash test/docker/verify-9-worktree.sh && bash test/docker/verify-10-fallback.sh && bash test/docker/verify-11-nested-alias.sh'",
-    "prepublishOnly": "npm run typecheck && npm run test && npm run test:integration",
-    "mock-llm": "node --experimental-strip-types test/mock-llm/cli.ts",
-    "test:mock-llm": "env -u PI_SUBAGENT_ALLOW_NESTED -u PI_SUBAGENT_CHILD -u PI_SUBAGENT_UTILITY_CHILD -u PI_SUBAGENT_MAX_DEPTH -u PI_SUBAGENT_PARENT_PATH -u PI_LEGION_DB -u PI_LEGION_NODE_ID node --experimental-strip-types --test test/unit/mock-llm*.test.ts test/integration/mock-llm*.test.ts test/integration/railway-mock-e2e.test.ts"
-  },
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "*",
     "@earendil-works/pi-ai": "*",
@@ -91,5 +80,27 @@
     "@types/node": "^22.0.0",
     "typebox": "^1.3.30",
     "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=22",
+    "pnpm": ">=9"
+  },
+  "devEngines": {
+    "packageManager": {
+      "name": "pnpm",
+      "version": ">=9",
+      "onFail": "error"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "env -u PI_SUBAGENT_ROLE -u PI_SUBAGENT_ACCEPTANCE_ROLE -u PI_SUBAGENT_ALLOW_NESTED -u PI_SUBAGENT_CHILD -u PI_SUBAGENT_UTILITY_CHILD -u PI_SUBAGENT_MAX_DEPTH -u PI_SUBAGENT_PARENT_PATH -u PI_LEGION_DB -u PI_LEGION_NODE_ID node --experimental-strip-types --test test/unit/*.test.ts",
+    "test:integration": "env -u PI_SUBAGENT_ROLE -u PI_SUBAGENT_ACCEPTANCE_ROLE -u PI_SUBAGENT_ALLOW_NESTED -u PI_SUBAGENT_CHILD -u PI_SUBAGENT_UTILITY_CHILD -u PI_SUBAGENT_MAX_DEPTH -u PI_SUBAGENT_PARENT_PATH -u PI_LEGION_DB -u PI_LEGION_NODE_ID node --experimental-strip-types --test test/integration/*.test.ts",
+    "test:live": "env -u PI_SUBAGENT_ROLE -u PI_SUBAGENT_ACCEPTANCE_ROLE -u PI_SUBAGENT_ALLOW_NESTED -u PI_SUBAGENT_CHILD -u PI_SUBAGENT_UTILITY_CHILD -u PI_SUBAGENT_MAX_DEPTH -u PI_SUBAGENT_PARENT_PATH -u PI_LEGION_DB -u PI_LEGION_NODE_ID node --experimental-strip-types --test test/live/*.test.ts",
+    "test:all": "pnpm run typecheck && pnpm run test && pnpm run test:integration",
+    "test:docker": "env -u PI_SUBAGENT_ROLE -u PI_SUBAGENT_ACCEPTANCE_ROLE -u PI_SUBAGENT_ALLOW_NESTED -u PI_SUBAGENT_CHILD -u PI_SUBAGENT_UTILITY_CHILD -u PI_SUBAGENT_MAX_DEPTH -u PI_SUBAGENT_PARENT_PATH sh -c 'echo \"RPC mainline Docker checks only; legacy Herdr workspace/kind/notification scenarios are archived under test/legacy/docker and require pi-legion v0.16.x\" && bash test/docker/verify-1-child-guard.sh && bash test/docker/verify-2-task-appendix.sh && bash test/docker/verify-3-readonly.sh && bash test/docker/verify-4-acceptance.sh && bash test/docker/verify-5-blocked.sh && bash test/docker/verify-6-cache.sh && bash test/docker/verify-7-budget.sh && bash test/docker/verify-8-verify-command.sh && bash test/docker/verify-9-worktree.sh && bash test/docker/verify-10-fallback.sh && bash test/docker/verify-11-nested-alias.sh'",
+    "mock-llm": "node --experimental-strip-types test/mock-llm/cli.ts",
+    "test:mock-llm": "env -u PI_SUBAGENT_ROLE -u PI_SUBAGENT_ACCEPTANCE_ROLE -u PI_SUBAGENT_ALLOW_NESTED -u PI_SUBAGENT_CHILD -u PI_SUBAGENT_UTILITY_CHILD -u PI_SUBAGENT_MAX_DEPTH -u PI_SUBAGENT_PARENT_PATH -u PI_LEGION_DB -u PI_LEGION_NODE_ID node --experimental-strip-types --test test/unit/mock-llm*.test.ts test/integration/mock-llm*.test.ts test/integration/railway-mock-e2e.test.ts",
+    "test:tui-visual": "docker build -q -f test/docker/Dockerfile.tui-sandbox -t ghcr.io/zzjcool/pi-legion/tui-sandbox:latest . >/dev/null && docker run --rm -v $(pwd):/plugin -w /plugin ghcr.io/zzjcool/pi-legion/tui-sandbox:latest bash test/docker/verify-tui-visual.sh"
   }
-}
+}

package/skills/pi-legion/SKILL.md

@@ -93,11 +93,16 @@ Steer, inspect, collect, resume, or retire children with the `subagent` tool:
 ```text
 subagent({ action: "status", name: "worker-0" })
 subagent({ action: "collect", name: "worker-0" })
+subagent({ action: "wait", all: true })
+subagent({ action: "wait", name: "worker-0" })
 subagent({ action: "steer", name: "worker-0", message: "Focus on the parser tests." })
 subagent({ action: "resume", name: "worker-0" })
 subagent({ action: "retire", name: "worker-0" })
 ```
 
+`wait` always needs a target: pass `all: true` for every live child, or `name`
+for one child (mutually exclusive). A bare `action: "wait"` is rejected.
+
 A person can read that same status without a tool call: `/legion status` for
 the tree, `/legion status <name>` for one child.
 

package/src/agents/agents.ts

@@ -18,6 +18,8 @@ import {
 	type AcceptanceConfig,
 	type AcceptanceCriterion,
 	type OnBlockedPolicy,
+	type SpawnMode,
+	SPAWN_MODES,
 	type SystemPromptMode,
 	type ToolBudgetConfig,
 	type TurnBudgetConfig,
@@ -80,9 +82,12 @@ export function resetExtraAgentDirsDeprecationWarnForTests(): void {
 	legacyExtraAgentDirsWarned = false;
 }
 
+/** Split EXTRA_AGENT_DIRS: colon+semicolon (+comma) on POSIX; comma+semicolon on Windows (drive letters). */
+const EXTRA_AGENT_DIRS_SEP = path.delimiter === ";" ? /[,;]/ : /[;:,]/;
+
 function splitExtraAgentDirEntries(raw: string | undefined): string[] {
 	if (!raw) return [];
-	return raw.split(path.delimiter).flatMap((entry) => {
+	return raw.split(EXTRA_AGENT_DIRS_SEP).flatMap((entry) => {
 		const trimmed = entry.trim();
 		return trimmed ? [path.resolve(trimmed)] : [];
 	});
@@ -144,6 +149,12 @@ const VALID_ACCEPTANCE_LEVELS: ReadonlySet<string> = new Set([
 	"verified",
 ]);
 
+const VALID_ACCEPTANCE_ROLES: ReadonlySet<string> = new Set([
+	"read-only",
+	"writer",
+	"unknown",
+]);
+
 /** Raw frontmatter values are `unknown`: a YAML scalar or collection may appear. */
 type AgentFrontmatter = Record<string, unknown>;
 
@@ -165,6 +176,16 @@ function int(value: unknown): number | undefined {
 	return undefined;
 }
 
+function spawnModeOf(value: unknown, filePath: string): SpawnMode | undefined {
+	if (value === undefined || value === null || value === "") return undefined;
+	const raw = typeof value === "string" ? value.trim() : String(value);
+	if ((SPAWN_MODES as readonly string[]).includes(raw)) return raw as SpawnMode;
+	throw new Error(
+		`Agent '${filePath}' has invalid spawnMode '${raw}'; expected one of: ${SPAWN_MODES.join(", ")}.`,
+	);
+}
+
+
 /**
  * Accept `tools: read, bash`, `tools: [read, bash]`, and block-list spellings.
  *
@@ -318,7 +339,7 @@ function parseScalar(raw: string): Scalar {
 	return stripQuotes(value);
 }
 
-function parseAcceptance(value: unknown): AcceptanceConfig | undefined {
+function parseAcceptance(value: unknown, agentName?: string): AcceptanceConfig | undefined {
 	const raw = str(value);
 	if (!raw) return undefined;
 
@@ -340,9 +361,15 @@ function parseAcceptance(value: unknown): AcceptanceConfig | undefined {
 	if (!level || !VALID_ACCEPTANCE_LEVELS.has(level)) return undefined;
 
 	const out: AcceptanceConfig = { level: level as AcceptanceConfig["level"] };
-	const role = str(parsed.role);
-	if (role === "read-only" || role === "writer" || role === "unknown") {
-		out.role = role;
+	// #172: author-facing role strings are case-insensitive; keep hyphenated canonical forms.
+	const role = str(parsed.role)?.toLowerCase();
+	if (role && VALID_ACCEPTANCE_ROLES.has(role)) {
+		out.role = role as AcceptanceConfig["role"];
+	} else if (role) {
+		const who = agentName ? `agent "${agentName}"` : "agent";
+		console.error(
+			`[pi-legion] ${who}: unknown acceptance.role ${JSON.stringify(role)}; expected read-only | writer | unknown.`,
+		);
 	}
 	const criteria = parseCriteria(parsed.criteria);
 	if (criteria) out.criteria = criteria;
@@ -528,7 +555,8 @@ function applyBehaviorFields(config: AgentConfig, fm: AgentFrontmatter): void {
 	setIf(config, "disabled", bool(fm.disabled));
 	setIf(config, "worktree", bool(fm.worktree));
 	setIf(config, "steer", bool(fm.steer));
-	setIf(config, "acceptance", parseAcceptance(fm.acceptance));
+	setIf(config, "spawnMode", spawnModeOf(fm.spawnMode, config.filePath));
+	setIf(config, "acceptance", parseAcceptance(fm.acceptance, config.name));
 	setIf(config, "toolBudget", parseBudget(fm.toolBudget));
 	setIf(config, "turnBudget", parseTurnBudget(fm.turnBudget));
 	// Writers share a checkout with every other parent Pi in this repo.

package/src/agents/context.ts

@@ -1,6 +1,8 @@
 /**
  * Extra prompt context injected by settings: `subagents.parentContext` and
- * `subagents.childContext`.
+ * `subagents.childContext`, plus optional per-team overrides on
+ * `subagents.teams.<name>.parentContext` / `childContext` (see
+ * `resolveTeamContext`).
  *
  * Both keys accept either inline markdown or a file reference in pi's own
  * `@path` form. This exists so machine-specific operating discipline (parallel
@@ -17,6 +19,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import type { SubagentsSettings } from "../shared/types.ts";
 
 export interface ResolvedContext {
 	/** Final markdown text, or undefined when nothing is configured. */
@@ -116,3 +119,82 @@ export function parseContextSetting(
 	const joined = parts.filter(Boolean).join("\n\n").trim();
 	return joined || undefined;
 }
+
+export type ContextKind = "parent" | "child";
+
+const CONTEXT_FIELD: Record<ContextKind, "parentContext" | "childContext"> = {
+	parent: "parentContext",
+	child: "childContext",
+};
+
+/**
+ * Resolve parent or child context for the active team.
+ *
+ * Order (each side independent):
+ * 1. If `teams[activeTeam.name]` exists:
+ *    - `false` → no inject (stop; no global fallthrough)
+ *    - string / string[] → team value only (replace global; `@path` via baseDir)
+ *    - omitted → continue
+ * 2. Global `subagents.parentContext` / `childContext` (already resolved at
+ *    settings load, including convention-file fallthrough)
+ *
+ * Unknown team names and the reserved `default` team (no `teams.default`)
+ * skip step 1 and use global only — matching today's behaviour.
+ *
+ * `baseDir` anchors team-level `@path` when the team field still holds a raw
+ * `@path` / array (programmatic TeamConfig). Settings load resolves team
+ * `@path` against the declaring settings file directory.
+ */
+export function resolveTeamContext(
+	kind: ContextKind,
+	settings: SubagentsSettings,
+	activeTeam: { name: string },
+	baseDir?: string,
+): string | undefined {
+	const field = CONTEXT_FIELD[kind];
+	const teams = settings.teams;
+	const teamConfig =
+		teams && Object.hasOwn(teams, activeTeam.name)
+			? teams[activeTeam.name]
+			: undefined;
+
+	if (teamConfig) {
+		const teamValue = teamConfig[field];
+		if (teamValue === false) return undefined;
+		if (teamValue !== undefined) {
+			return resolveTeamContextValue(
+				teamValue,
+				`teams.${activeTeam.name}.${field}`,
+				baseDir,
+			);
+		}
+	}
+
+	const global = settings[field];
+	if (typeof global !== "string") return undefined;
+	const trimmed = global.trim();
+	return trimmed || undefined;
+}
+
+/**
+ * Resolve a team context field.
+ * Settings load pre-resolves `@path` / arrays to a final string (or keeps
+ * `false`). Plain strings are final markdown. Arrays still need `baseDir`
+ * (programmatic TeamConfig in tests).
+ */
+function resolveTeamContextValue(
+	value: string | string[],
+	field: string,
+	baseDir: string | undefined,
+): string | undefined {
+	if (Array.isArray(value)) {
+		if (baseDir === undefined) {
+			throw new Error(
+				`Subagent settings '${field}' is an array; baseDir is required to resolve it.`,
+			);
+		}
+		return parseContextSetting(value, field, baseDir);
+	}
+	const trimmed = value.trim();
+	return trimmed || undefined;
+}

package/src/agents/overrides.ts

@@ -40,6 +40,7 @@ export const OVERRIDE_FIELDS = [
 	"disabled",
 	"worktree",
 	"steer",
+	"spawnMode",
 	// numbers
 	"timeoutMs",
 	"toolTimeoutMs",

package/src/agents/settings.ts

@@ -16,7 +16,10 @@ import {
 	type ModelScopeConfig,
 	type OnBlockedPolicy,
 	type ScoutGuardSettings,
+	type InProcessLimits,
+	type RpcSettings,
 	type SubagentsSettings,
+	SPAWN_MODES,
 	type TeamConfig,
 	type TeamMember,
 } from "../shared/types.ts";
@@ -481,6 +484,8 @@ export function parseSubagentSettings(
 
 	readJoinFields(input, out, filePath);
 	setIf(out, "scoutGuard", parseScoutGuard(input.scoutGuard, filePath));
+	setIf(out, "inprocess", parseInProcessLimits(input.inprocess, filePath));
+	setIf(out, "rpc", parseRpcSettings(input.rpc, filePath));
 
 	// THE WHITELIST: every key read above must be assigned, or it is silently
 	// discarded. `presets` is the newest key and the easiest to drop here.
@@ -537,6 +542,7 @@ function overrideFieldExpected(field: string): string | undefined {
 	if (["description", "model", "preset", "output", "systemPrompt"].includes(field)) return "a string";
 	if (field === "thinking") return "a string or false";
 	if (field === "kind") return `one of: ${AGENT_KINDS.join(", ")}`;
+	if (field === "spawnMode") return `one of: ${SPAWN_MODES.join(", ")}`;
 	if (field === "onBlocked") return "a valid onBlocked policy";
 	if (field === "systemPromptMode") return "replace or append";
 	if (["inheritProjectContext", "inheritSkills", "inheritExtensions", "defaultProgress", "async", "completionGuard", "allowNestedSubagents", "utility", "disabled", "worktree", "steer"].includes(field)) return "a boolean";
@@ -550,6 +556,7 @@ function isValidOverrideField(field: string, value: unknown): boolean {
 	if (["description", "model", "preset", "output", "systemPrompt"].includes(field)) return typeof value === "string";
 	if (field === "thinking") return typeof value === "string" || value === false;
 	if (field === "kind") return typeof value === "string" && (AGENT_KINDS as readonly string[]).includes(value);
+	if (field === "spawnMode") return typeof value === "string" && (SPAWN_MODES as readonly string[]).includes(value);
 	if (field === "onBlocked") return typeof value === "string" && VALID_ON_BLOCKED_POLICIES.has(value);
 	if (field === "systemPromptMode") return value === "replace" || value === "append";
 	if (["inheritProjectContext", "inheritSkills", "inheritExtensions", "defaultProgress", "async", "completionGuard", "allowNestedSubagents", "utility", "disabled", "worktree", "steer"].includes(field)) return typeof value === "boolean";
@@ -563,6 +570,60 @@ function isStringArray(value: unknown): value is string[] {
 	return Array.isArray(value) && value.every((item) => typeof item === "string");
 }
 
+
+function parseInProcessLimits(
+	value: unknown,
+	filePath: string,
+): InProcessLimits | undefined {
+	if (value === undefined) return undefined;
+	if (!isRecord(value)) {
+		throw new Error(
+			`Subagent settings in '${filePath}' have invalid 'inprocess'; expected an object.`,
+		);
+	}
+	const out: InProcessLimits = {};
+	const maxSpawnsPerSession = positiveInt(
+		value.maxSpawnsPerSession,
+		"inprocess.maxSpawnsPerSession",
+		filePath,
+	);
+	if (maxSpawnsPerSession !== undefined) out.maxSpawnsPerSession = maxSpawnsPerSession;
+	const maxDepth = nonNegativeInt(value.maxDepth, "inprocess.maxDepth", filePath);
+	if (maxDepth !== undefined) out.maxDepth = maxDepth;
+	const maxActive = positiveInt(value.maxActive, "inprocess.maxActive", filePath);
+	if (maxActive !== undefined) out.maxActive = maxActive;
+	const maxChildrenPerNode = nonNegativeInt(
+		value.maxChildrenPerNode,
+		"inprocess.maxChildrenPerNode",
+		filePath,
+	);
+	if (maxChildrenPerNode !== undefined) out.maxChildrenPerNode = maxChildrenPerNode;
+	const waitTimeoutMs = positiveInt(
+		value.waitTimeoutMs,
+		"inprocess.waitTimeoutMs",
+		filePath,
+	);
+	if (waitTimeoutMs !== undefined) out.waitTimeoutMs = waitTimeoutMs;
+	// Unknown keys are ignored (same as other settings blobs).
+	return out;
+}
+
+function parseRpcSettings(
+	value: unknown,
+	filePath: string,
+): RpcSettings | undefined {
+	if (value === undefined) return undefined;
+	if (!isRecord(value)) {
+		throw new Error(
+			`Subagent settings in '${filePath}' have invalid 'rpc'; expected an object.`,
+		);
+	}
+	const out: RpcSettings = {};
+	setIf(out, "approve", requiredBoolean(value.approve, "rpc.approve", filePath));
+	// Unknown keys ignored; v1 does not accept / emit --no-approve.
+	return out;
+}
+
 /** Validate the types of the supported fields in one override object. */
 function parseAgentOverride(
 	value: unknown,
@@ -621,6 +682,15 @@ function parseAgentOverrides(
 				`Subagent settings in '${filePath}' have invalid 'agentOverrides.${name}.utility'; expected a boolean.`,
 			);
 		}
+		if (
+			normalized.spawnMode !== undefined &&
+			(typeof normalized.spawnMode !== "string" ||
+				!(SPAWN_MODES as readonly string[]).includes(normalized.spawnMode))
+		) {
+			throw new Error(
+				`Subagent settings in '${filePath}' have invalid 'agentOverrides.${name}.spawnMode'; expected one of: ${SPAWN_MODES.join(", ")}.`,
+			);
+		}
 		parsed[name] = normalized as AgentOverride;
 	}
 	return parsed;
@@ -645,6 +715,34 @@ function parseTeamMember(
 	return { agent, ...parseAgentOverride(override, field, filePath) };
 }
 
+
+/** Validate team parentContext/childContext; resolve `@path` against settings dir. */
+function parseTeamContextField(
+	value: unknown,
+	field: string,
+	filePath: string,
+	bad: InvalidTeamSetting,
+): string | false | undefined {
+	if (value === undefined) return undefined;
+	if (value === false) return false;
+	try {
+		const resolved = parseContextSetting(value, field, path.dirname(filePath));
+		// Empty after resolve → treat as omitted (fall through at resolve time).
+		// Callers that want "disable" must use false.
+		return resolved;
+	} catch (error) {
+		// parseContextSetting already builds a clear message; rethrow as-is
+		// except for the shape error which we map to the team field wording.
+		if (
+			error instanceof Error &&
+			error.message.includes("expected a non-empty string")
+		) {
+			bad(field, "expected a non-empty string, string array, or false");
+		}
+		throw error;
+	}
+}
+
 /** Validate the named team map and its ordered member references. */
 function parseTeams(
 	value: unknown,
@@ -670,10 +768,25 @@ function parseTeams(
 		if (raw.description !== undefined && typeof raw.description !== "string") {
 			bad(`${field}.description`, "expected a string");
 		}
-		out[name] = {
+		const team: TeamConfig = {
 			...(raw.description !== undefined ? { description: raw.description } : {}),
 			members,
 		};
+		const parentCtx = parseTeamContextField(
+			raw.parentContext,
+			`${field}.parentContext`,
+			filePath,
+			bad,
+		);
+		if (parentCtx !== undefined) team.parentContext = parentCtx;
+		const childCtx = parseTeamContextField(
+			raw.childContext,
+			`${field}.childContext`,
+			filePath,
+			bad,
+		);
+		if (childCtx !== undefined) team.childContext = childCtx;
+		out[name] = team;
 	}
 	return out;
 }
@@ -770,6 +883,14 @@ export function resolveSubagentSettings(
 		out.scoutGuard = { ...(user.scoutGuard ?? {}), ...project.scoutGuard };
 	}
 
+	if (project.inprocess) {
+		out.inprocess = { ...(user.inprocess ?? {}), ...project.inprocess };
+	}
+
+	if (project.rpc) {
+		out.rpc = { ...(user.rpc ?? {}), ...project.rpc };
+	}
+
 	return out;
 }
 

package/src/api.ts

@@ -130,7 +130,12 @@ export type {
 export { Orchestrator, preCreateSessionFile, effectiveMaxDepth } from "./runs/orchestrator.ts";
 export type { BudgetRefusedEvent, CollectResult, OrchestratorDeps } from "./runs/orchestrator.ts";
 export { RpcSupervisor } from "./supervisor/rpc-supervisor.ts";
+export { InProcessSupervisor } from "./supervisor/inprocess-supervisor.ts";
+export { RoutingSupervisor } from "./supervisor/routing-supervisor.ts";
+export { resolveSpawnMode, DEFAULT_SPAWN_MODE, DEFAULT_INPROCESS_MAX_ACTIVE } from "./supervisor/spawn-mode.ts";
 export { InMemoryUIProxy, isExtensionUIRequest } from "./supervisor/ui-proxy.ts";
+export { runInChildContext, currentChildContext } from "./supervisor/child-context.ts";
+export type { ChildLaunchContext } from "./supervisor/child-context.ts";
 export type {
 	ChildHandle,
 	LegionSupervisor,
@@ -142,6 +147,22 @@ export type {
 	SupervisorEvent,
 	UsageSnapshot,
 } from "./supervisor/types.ts";
+export {
+	buildInProcessSessionPlan,
+} from "./supervisor/inprocess-supervisor.ts";
+export type {
+	InProcessSession,
+	InProcessSessionFactory,
+	InProcessSessionFactoryInput,
+	InProcessSessionPlan,
+	InProcessSessionStats,
+	InProcessSupervisorOptions,
+} from "./supervisor/inprocess-supervisor.ts";
+export type {
+	RoutingSupervisorOptions,
+	SupervisorBackend,
+} from "./supervisor/routing-supervisor.ts";
+export type { InProcessLimits, SpawnMode } from "./shared/types.ts";
 export type {
 	ExtensionUIRequest,
 	ExtensionUIResponse,
@@ -216,7 +237,9 @@ export {
 	canUseCachedCollect,
 	formatAlreadyRecycled,
 } from "./extension/recycle.ts";
+/** STATUS_FOOTER_KEY / formatFooterStatus are @deprecated (#192 footer drop); soft-land re-exports. */
 export {
+	activeEntries,
 	applyStatus,
 	createStatusBoard,
 	formatBusyLabel,

package/src/extension/child-guard.ts

@@ -1,12 +1,18 @@
 /**
- * Guards that run inside an RPC child Pi process.
+ * Guards that run inside a child Pi session.
  *
  * The child extension enforces budgets and read-only role protections. A
  * nested dispatch can only use the subagent tool; bash must never access the
  * tree ledger directly.
+ *
+ * Two transports exist (#197): RPC children are separate `pi --mode rpc`
+ * processes (identity arrives via env), in-process children are
+ * `createAgentSession` sessions inside the parent Node process (identity
+ * arrives via the AsyncLocalStorage child context).
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { currentChildContext, type ChildLaunchContext } from "../supervisor/child-context.ts";
 import {
 	budgetExceededReason,
 	childBudgetFromEnv,
@@ -52,7 +58,8 @@ export function blockChildMessage(reason: string): string {
 }
 
 export function isReadOnlyRole(role: string | undefined): boolean {
-	return role === "read-only";
+	// #172: tolerate case/spacing from env-supplied PI_SUBAGENT_ACCEPTANCE_ROLE.
+	return role?.trim().toLowerCase() === "read-only";
 }
 
 export interface ChildGuardEnv {
@@ -310,6 +317,38 @@ export function childGuardEnvFromProcess(env: NodeJS.ProcessEnv = process.env):
 		: {};
 }
 
+/**
+ * Read-only role for an in-process child, from the AsyncLocalStorage child
+ * context injected by the orchestrator.
+ *
+ * Why this is not `process.env`: in-process children share the parent's
+ * `process.env` — they do not get a fresh env of their own. Reading
+ * `PI_SUBAGENT_ACCEPTANCE_ROLE` from env in an in-process child therefore sees
+ * the *parent's* value (or nothing, when the parent is a root session). Either
+ * direction is wrong: a parent `writer` would make a read-only child's write
+ * bans silently disappear, and a parent read-only role would wrongly ban a
+ * `writer` child.
+ */
+export function childGuardEnvFromContext(
+	ctx: ChildLaunchContext | undefined = currentChildContext(),
+): ChildGuardEnv {
+	return ctx?.acceptanceRole ? { acceptanceRole: ctx.acceptanceRole } : {};
+}
+
+/**
+ * Effective child-guard env: the in-process child context wins, env is the
+ * RPC fallback. `childGuardEnvFromProcess` stays authoritative for RPC
+ * children, whose process really does own the env values.
+ */
+export function effectiveChildGuardEnv(
+	ctx: ChildLaunchContext | undefined = currentChildContext(),
+	env: NodeJS.ProcessEnv = process.env,
+): ChildGuardEnv {
+	const fromContext = childGuardEnvFromContext(ctx);
+	if (fromContext.acceptanceRole !== undefined) return fromContext;
+	return childGuardEnvFromProcess(env);
+}
+
 /** Child-only extension: intercept tools; do not register the parent tool. */
 export function registerChildGuard(pi: ExtensionAPI): void {
 	const budget = childBudgetFromEnv();
@@ -326,7 +365,7 @@ export function registerChildGuard(pi: ExtensionAPI): void {
 		}
 		if (event.toolName !== "bash") return;
 		const command = typeof event.input.command === "string" ? event.input.command : "";
-		const reason = forbiddenChildReason(command, childGuardEnvFromProcess());
+		const reason = forbiddenChildReason(command, effectiveChildGuardEnv());
 		if (reason) return { block: true, reason: blockChildMessage(reason) };
 		if (budget.toolTimeoutMs && budget.toolTimeoutMs > 0) {
 			event.input.command = wrapBashWithTimeout(command, budget.toolTimeoutMs);

package/src/extension/legion-commands.ts

@@ -37,6 +37,7 @@ import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import {
 	createLiveOverlay,
 	createLiveOverlayFactory,
+	resolveModalOverlayOptions,
 	type LiveOverlayBackfillCursor,
 	type LiveOverlayBackfillResult,
 	type LiveOverlayListener,
@@ -428,6 +429,11 @@ function openLiveOverlay(
 	nodeId: string,
 	onStop?: (nodeId: string) => void,
 ): void {
+	// #193: the overlay must cover the floating frame only. A full-screen overlay
+	// would make pi-tui discard every host cell (its composite has no transparency
+	// option), so the area around the frame collapsed to the terminal's default
+	// background — the "black modal". Anchoring to the frame rect leaves the rest of
+	// the screen to the host, which paints the chat / /legion view there.
 	const factory = createLiveOverlayFactory(controller, nodeId, {
 		...(onStop ? { onStop } : {}),
 		cwd,
@@ -435,8 +441,9 @@ function openLiveOverlay(
 	});
 	void ui.custom(factory, {
 		overlay: true,
-		// Full-screen host overlay so the viewer paints its own dim mask + floating frame.
-		overlayOptions: { width: "100%", maxHeight: "100%", anchor: "top-left", row: 0, col: 0 },
+		// Percentages (not absolute cells) so pi-tui re-derives the rect from the
+		// current terminal every frame; the frame survives resize.
+		overlayOptions: resolveModalOverlayOptions(),
 		onHandle: (handle) => controller.getCurrent()?.attachOverlayHandle(handle),
 	}).catch((error: unknown) => reportOverlayOpenError(controller, ui, error));
 }