pi-legion 3.0.0 → 3.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-legion",
-  "version": "3.0.0",
+  "version": "3.0.3",
   "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",
@@ -49,14 +49,13 @@
     "LICENSE"
   ],
   "scripts": {
-    "preinstall": "node -e \"const ua=process.env.npm_config_user_agent||'';if(!ua.includes('pnpm')){console.error('Use pnpm to install dependencies (see CONTRIBUTING.md).');process.exit(1)}\"",
     "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:all": "node --run typecheck && node --run test && node --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'",
-    "prepublishOnly": "pnpm run typecheck && pnpm run test && pnpm run test:integration",
+    "prepublishOnly": "node --run typecheck && node --run test && node --run test:integration",
     "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"
@@ -94,9 +93,7 @@
     "typebox": "^1.3.30",
     "typescript": "^5.6.0"
   },
-  "packageManager": "pnpm@9.15.9",
   "engines": {
-    "node": ">=22",
-    "pnpm": ">=9"
+    "node": ">=22"
   }
 }

package/src/agents/agents.ts

@@ -559,11 +559,11 @@ function applyBehaviorFields(config: AgentConfig, fm: AgentFrontmatter): void {
 	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.
-	// Default them onto an isolated worktree so they ship via MR instead.
-	if (config.worktree === undefined && config.acceptance?.role === "writer") {
-		config.worktree = true;
-	}
+	// #214 / contract §9: only centurion holds worktree isolation. Writers no
+	// longer auto-default to worktree:true — members work in-place; parallel
+	// isolated writers are N root-dispatched centurions. Explicit worktree:true
+	// on a non-centurion is still demoted at launch (warn once / force false).
+	// centurion.md pins worktree:true itself; no auto-default here.
 }
 
 /** Transitional blocked-policy frontmatter retained for approval handling. */

package/src/api.ts

@@ -132,7 +132,12 @@ export type { BudgetRefusedEvent, CollectResult, OrchestratorDeps } from "./runs
 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 {
+	resolveSpawnMode,
+	DEFAULT_SPAWN_MODE,
+	DEFAULT_INPROCESS_MAX_ACTIVE,
+	DEFAULT_INPROCESS_SPAWN_START_TIMEOUT_MS,
+} 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";

package/src/extension/auto-doctor.ts

@@ -71,6 +71,7 @@ function readSettings(): unknown {
 export function buildAutoDoctorSnippet(kind: AutoDoctorKind, opts?: {
 	cwd?: string;
 	name?: string;
+	spawnMode?: "rpc" | "inprocess";
 }): string {
 	const settings = readSettings();
 	const report = runLegionDoctor({
@@ -80,6 +81,7 @@ export function buildAutoDoctorSnippet(kind: AutoDoctorKind, opts?: {
 		probeModels: false,
 		expectedModels: expectedModelsFromSettings(settings),
 		sections: [...SECTIONS[kind]],
+		spawnMode: opts?.spawnMode,
 		// Failures already recorded by the caller; doctor will pick them up.
 	});
 	let body = report.text.trim();
@@ -108,25 +110,41 @@ export function enrichFailureWithAutoDoctor(
 		cwd?: string;
 		/** When false, skip recording into the recent-failure ring. Default true. */
 		record?: boolean;
+		/** Prefer inprocess hints when known (#212). */
+		spawnMode?: "rpc" | "inprocess";
 	} = {},
 ): string {
 	const kind = classifyFailure({ message, stderr: input.stderr, code: input.code });
+	// Infer rpc when argv shows --no-extensions and caller did not tag spawnMode (#212).
+	const spawnMode =
+		input.spawnMode ??
+		(input.args?.includes("--no-extensions") ? "rpc" as const : undefined);
 	if (input.record !== false) {
 		recordSpawnFailure({
 			name: input.name ?? "?",
 			message,
 			stderr: input.stderr,
-			hadNoExtensions: input.args?.includes("--no-extensions"),
+			hadNoExtensions:
+				spawnMode === "inprocess" ? false : input.args?.includes("--no-extensions"),
+			spawnMode,
 		});
 	}
 	if (!kind) return message;
 
 	const parts = [message];
-	const hint = spawnFailureHint({ stderr: input.stderr ?? message, args: input.args });
+	const hint = spawnFailureHint({
+		stderr: input.stderr ?? message,
+		args: input.args,
+		spawnMode,
+	});
 	if (hint) parts.push("", hint);
 
 	try {
-		parts.push("", buildAutoDoctorSnippet(kind, { cwd: input.cwd, name: input.name }));
+		parts.push("", buildAutoDoctorSnippet(kind, {
+			cwd: input.cwd,
+			name: input.name,
+			spawnMode,
+		}));
 	} catch (error) {
 		parts.push(
 			"",

package/src/extension/join.ts

@@ -18,9 +18,12 @@
  *     the whole buffer now (the common "all children done" path).
  *  3. Otherwise buffer it; the window starts at the FIRST onTerminal.
  *
- * Window expiry: if the parent is mid-turn (parentBusy) and we have not
- * already extended MAX_BUSY_EXTENSIONS times, open another flushMs window;
- * otherwise flush what is buffered. Pending members survive — a straggler
+ * Window expiry: flush what is buffered, once. The window exists only to
+ * collect stragglers from one batch — it is NEVER extended because the parent
+ * session happens to be busy. A turn-level busy signal was the wrong predictor
+ * (the parent is busy for the whole tool loop by definition) and it stacked a
+ * second delay on top of the runtime's run-scoped outbox, which is the single
+ * place a completion may be held. Pending members survive — a straggler
  * finishing later starts a fresh batch of its own.
  */
 
@@ -34,14 +37,10 @@ export type JoinMode = "each" | "smart";
 
 export const DEFAULT_JOIN_MODE: JoinMode = "smart";
 export const DEFAULT_FLUSH_MS = 10_000;
-/** Max times a busy parent extends a window (total ≤ (1+3)×flushMs). */
-export const MAX_BUSY_EXTENSIONS = 3;
 
 export interface JoinConfig {
 	mode: JoinMode;
 	flushMs: number;
-	/** Reports whether the parent is mid-turn; absent means "never busy". */
-	parentBusy?: () => boolean;
 }
 
 /** Default: smart mode with a ten-second window. */
@@ -76,7 +75,6 @@ interface Group {
 	/** Names tracked but not yet terminal (blocked members are excluded). */
 	pending: Set<string>;
 	buffered: BufferedEntry[];
-	extensions: number;
 	timer?: JoinSchedulerHandle;
 }
 
@@ -162,7 +160,6 @@ export class JoinCoordinator {
 			return;
 		}
 		if (!group.timer) {
-			group.extensions = 0;
 			group.timer = this.scheduleFn(this.config.flushMs, () => {
 				this.onWindowExpired(entry.runId);
 			});
@@ -190,7 +187,7 @@ export class JoinCoordinator {
 	private ensureGroup(runId: string): Group {
 		let group = this.groups.get(runId);
 		if (!group) {
-			group = { pending: new Set(), buffered: [], extensions: 0 };
+			group = { pending: new Set(), buffered: [] };
 			this.groups.set(runId, group);
 		}
 		return group;
@@ -200,14 +197,6 @@ export class JoinCoordinator {
 		const group = this.groups.get(runId);
 		if (!group || this.disposed) return;
 		group.timer = undefined;
-		const busy = this.config.parentBusy?.() ?? false;
-		if (busy && group.extensions < MAX_BUSY_EXTENSIONS) {
-			group.extensions += 1;
-			group.timer = this.scheduleFn(this.config.flushMs, () => {
-				this.onWindowExpired(runId);
-			});
-			return;
-		}
 		this.flush(runId);
 	}
 

package/src/extension/legion-doctor.ts

@@ -53,8 +53,12 @@ import {
 } from "../runs/verify-queue.ts";
 import { ALLOW_NESTED_ENV } from "./budget.ts";
 import { IDLE_STOP_HINT, IDLE_STOP_HINT_SHORT } from "./legion-stop.ts";
-import type { AgentConfig } from "../shared/types.ts";
-import { recentSpawnFailures, type SpawnFailureRecord } from "./spawn-hints.ts";
+import type { AgentConfig, SpawnMode } from "../shared/types.ts";
+import { resolveSpawnMode } from "../supervisor/spawn-mode.ts";
+import {
+	recentSpawnFailures,
+	type SpawnFailureRecord,
+} from "./spawn-hints.ts";
 import {
 	formatSessionErrorTitle,
 	sessionErrorsLogPath,
@@ -179,6 +183,11 @@ export interface DoctorOptions {
 	sections?: readonly DoctorSection[];
 	/** Injected session-error summary (tests); defaults to reading storeRoot log. */
 	sessionErrors?: SessionErrorSummary;
+	/**
+	 * Override resolved spawn backend for diagnosis (#212).
+	 * When omitted, uses `resolveSpawnMode(sampleAgent)` (default inprocess).
+	 */
+	spawnMode?: SpawnMode;
 }
 
 function readJson(file: string): unknown {
@@ -345,6 +354,23 @@ function sampleAgentConfig(agent?: AgentConfig): AgentConfig {
 	);
 }
 
+
+/** Fix text for inprocess model/provider gaps — never recommends PI_LEGION_CHILD_EXTENSIONS (#212). */
+export function inprocessModelFix(): string {
+	return (
+		"Declare the provider statically in models.json (agent dir / project), " +
+		"or set role frontmatter extensions: […] / inheritExtensions: true."
+	);
+}
+
+/** RPC-only fix that exports PI_LEGION_CHILD_EXTENSIONS when paths are known. */
+function rpcChildExtensionsFix(providerExtHome: readonly string[]): string | undefined {
+	if (providerExtHome.length) {
+		return `export ${CHILD_EXTENSIONS_ENV}=${providerExtHome.join(",")}`;
+	}
+	return `Add the provider package extension path to ${CHILD_EXTENSIONS_ENV}, or set role extensions: / inheritExtensions: true.`;
+}
+
 function previewChildArgv(agent: AgentConfig, env: NodeJS.ProcessEnv): string[] {
 	const dir = fs.mkdtempSync(path.join(os.tmpdir(), "legion-doctor-"));
 	try {
@@ -506,9 +532,18 @@ export function runLegionDoctor(options: DoctorOptions = {}): DoctorReport {
 
 	const inheritGlobal = childInheritsExtensions({}, env);
 	const extras = childExtraExtensions(env);
-	const sample = sampleAgentConfig(options.sampleAgent);
-	const argv = previewChildArgv(sample, env);
-	const noExtensions = argv.includes("--no-extensions");
+	const sample = sampleAgentConfig(
+		options.spawnMode && options.sampleAgent
+			? { ...options.sampleAgent, spawnMode: options.spawnMode }
+			: options.spawnMode
+				? { ...sampleAgentConfig(), spawnMode: options.spawnMode }
+				: options.sampleAgent,
+	);
+	const spawnMode: SpawnMode = resolveSpawnMode(sample);
+	const isInprocess = spawnMode === "inprocess";
+	// Argv preview is RPC-shaped; only meaningful when default/sample backend is rpc (#212).
+	const argv = isInprocess ? [] : previewChildArgv(sample, env);
+	const noExtensions = isInprocess ? false : argv.includes("--no-extensions");
 	const explicitExts = argv.flatMap((a, i) => (a === "--extension" ? [argv[i + 1]!] : []));
 
 	const probe = options.probeModels !== false;
@@ -556,7 +591,10 @@ export function runLegionDoctor(options: DoctorOptions = {}): DoctorReport {
 	].filter((ext, i, all) => all.indexOf(ext) === i);
 	const providerExtHome = providerExtPaths.map((ext) => homeize(ext, home));
 
-	if (!inheritGlobal && noExtensions && hostModels.length > 0 && childModels.length === 0) {
+	// CHILD_NO_MODELS / CHILD_FEWER_MODELS come from the RPC CLI probe
+	// (`pi --no-extensions --list-models`). Skip them when default backend is
+	// inprocess — that probe is a false lead for ModelRuntime children (#212).
+	if (!isInprocess && !inheritGlobal && noExtensions && hostModels.length > 0 && childModels.length === 0) {
 		issues.push({
 			severity: "error",
 			code: "CHILD_NO_MODELS",
@@ -564,11 +602,9 @@ export function runLegionDoctor(options: DoctorOptions = {}): DoctorReport {
 			message:
 				`Host has ${hostModels.length} model(s) but a child with --no-extensions sees none. ` +
 				`Providers are registered by host packages that children no longer load (#43).`,
-			fix: providerExtHome.length
-				? `export ${CHILD_EXTENSIONS_ENV}=${providerExtHome.join(",")}`
-				: `Add the provider package extension path to ${CHILD_EXTENSIONS_ENV}, or set role extensions: / inheritExtensions: true.`,
+			fix: rpcChildExtensionsFix(providerExtHome),
 		});
-	} else if (!inheritGlobal && noExtensions && hostModels.length > childModels.length && childModels.length > 0) {
+	} else if (!isInprocess && !inheritGlobal && noExtensions && hostModels.length > childModels.length && childModels.length > 0) {
 		issues.push({
 			severity: "warning",
 			code: "CHILD_FEWER_MODELS",
@@ -578,18 +614,19 @@ export function runLegionDoctor(options: DoctorOptions = {}): DoctorReport {
 	}
 
 	const expected = options.expectedModels ?? [];
-	const missing = inheritGlobal
+	// Inprocess shares host discovery after extension drain — compare roster to host.
+	const missing = inheritGlobal || isInprocess
 		? expected.filter((m) => !modelMatches(m, hostModels))
 		: expected.filter((m) => !modelMatches(m, childModels));
-	if (missing.length > 0 && (childModels.length === 0 || !inheritGlobal)) {
+	if (missing.length > 0 && (isInprocess || childModels.length === 0 || !inheritGlobal)) {
 		issues.push({
 			severity: "error",
 			code: "TEAM_MODELS_MISSING",
 			section: "models",
-			message: `Team/roster model(s) invisible to children: ${missing.join(", ")}`,
-			fix: providerExtHome.length
-				? `export ${CHILD_EXTENSIONS_ENV}=${providerExtHome.join(",")}`
-				: undefined,
+			message: isInprocess
+				? `Team/roster model(s) not visible on the host registry (inprocess resolves via ModelRuntime): ${missing.join(", ")}`
+				: `Team/roster model(s) invisible to children: ${missing.join(", ")}`,
+			fix: isInprocess ? inprocessModelFix() : rpcChildExtensionsFix(providerExtHome),
 		});
 	}
 
@@ -625,16 +662,30 @@ export function runLegionDoctor(options: DoctorOptions = {}): DoctorReport {
 	}
 
 	const failures = options.failures ?? recentSpawnFailures();
-	if (failures.some((f) => f.hadNoExtensions !== false && /not found|No models/i.test(f.stderr ?? f.message))) {
-		issues.push({
-			severity: "error",
-			code: "RECENT_MODEL_SPAWN_FAIL",
-			section: "spawn",
-			message: "A recent child spawn failed with a model/provider error under --no-extensions.",
-			fix: providerExtHome.length
-				? `export ${CHILD_EXTENSIONS_ENV}=${providerExtHome.join(",")}`
-				: undefined,
-		});
+	const modelFailRe = /not found|No models|Unknown provider|inprocess model resolve failed/i;
+	const recentModelFails = failures.filter((f) => modelFailRe.test(f.stderr ?? f.message));
+	if (recentModelFails.length > 0) {
+		// Default backend (or tagged failure) decides the fix — never recommend
+		// PI_LEGION_CHILD_EXTENSIONS for inprocess (#212).
+		const treatAsInprocess =
+			isInprocess || recentModelFails.every((f) => f.spawnMode === "inprocess");
+		if (treatAsInprocess) {
+			issues.push({
+				severity: "error",
+				code: "RECENT_MODEL_SPAWN_FAIL",
+				section: "spawn",
+				message: "A recent inprocess child spawn failed to resolve a model/provider.",
+				fix: inprocessModelFix(),
+			});
+		} else if (recentModelFails.some((f) => f.hadNoExtensions !== false)) {
+			issues.push({
+				severity: "error",
+				code: "RECENT_MODEL_SPAWN_FAIL",
+				section: "spawn",
+				message: "A recent child spawn failed with a model/provider error under --no-extensions.",
+				fix: rpcChildExtensionsFix(providerExtHome),
+			});
+		}
 	}
 
 	const gate = resolveMemoryGateConfig(env);
@@ -721,8 +772,14 @@ export function runLegionDoctor(options: DoctorOptions = {}): DoctorReport {
 		const warnN = issues.filter((i) => i.severity === "warning").length;
 		push(`- status: ${errN ? "FAIL" : warnN ? "WARN" : "OK"} (${errN} error(s), ${warnN} warning(s))`);
 		push(`- session errors: ${sessionErrors.total}${sessionErrors.logPath ? ` (log ${homeize(sessionErrors.logPath, home)})` : ""}`);
-		push(`- child --no-extensions: ${noExtensions ? "yes" : "no"}; inherit: ${inheritGlobal ? "yes" : "no"}`);
-		push(`- models host/child: ${hostModels.length}/${childModels.length}`);
+		push(`- spawnMode (sample/default): ${spawnMode}`);
+		if (isInprocess) {
+			push(`- child backend: inprocess (ModelRuntime; no --no-extensions argv); inherit: ${inheritGlobal ? "yes" : "no"}`);
+			push(`- models host (inprocess uses host registry after extension drain): ${hostModels.length}`);
+		} else {
+			push(`- child --no-extensions: ${noExtensions ? "yes" : "no"}; inherit: ${inheritGlobal ? "yes" : "no"}`);
+			push(`- models host/child: ${hostModels.length}/${childModels.length}`);
+		}
 		push(`- live children: ${runtime.liveJobs?.length ?? "(unknown — pass runtime)"}`);
 		push(`- free memory: ${availableMb} MB (gate min ${gate.minFreeMb})`);
 		if (storeRoot) push(`- store: ${homeize(storeRoot, home)}`);
@@ -731,8 +788,13 @@ export function runLegionDoctor(options: DoctorOptions = {}): DoctorReport {
 
 	if (want(selected, "extensions")) {
 		push("## Extensions");
+		push(`- spawnMode (sample/default): ${spawnMode}`);
 		push(`- inheritExtensions (env/role default): ${inheritGlobal ? "yes (loads all host extensions)" : "no"}`);
-		push(`- child argv includes --no-extensions: ${noExtensions ? "yes" : "no"}`);
+		if (isInprocess) {
+			push("- child argv --no-extensions: n/a (inprocess has no child argv)");
+		} else {
+			push(`- child argv includes --no-extensions: ${noExtensions ? "yes" : "no"}`);
+		}
 		push(`- ${CHILD_INHERIT_EXTENSIONS_ENV}=${env[CHILD_INHERIT_EXTENSIONS_ENV] ?? "(unset)"}`);
 		push(`- ${CHILD_EXTENSIONS_ENV}=${env[CHILD_EXTENSIONS_ENV] ?? "(unset)"}`);
 		push(`- extra extension paths: ${extras.length ? extras.map((p) => homeize(p, home)).join(", ") : "(none)"}`);
@@ -763,10 +825,19 @@ export function runLegionDoctor(options: DoctorOptions = {}): DoctorReport {
 
 	if (want(selected, "models")) {
 		push("## Models / providers");
+		push(`- spawnMode (sample/default): ${spawnMode}`);
 		push(`- host (normal discovery): ${hostModels.length}`);
-		push(`- child (--no-extensions): ${childModels.length}`);
-		if (hostModels.length && childModels.length === 0) {
-			push("- child sees NO models — providers come from host packages that `--no-extensions` skips.");
+		if (isInprocess) {
+			push("- child probe (`pi --no-extensions --list-models`): skipped as doctor signal for inprocess (#212)");
+			push(`- rpc-shaped probe count (informational only): ${childModels.length}`);
+			if (hostModels.length === 0) {
+				push("- host sees NO models — declare providers in models.json or load provider extensions for inprocess.");
+			}
+		} else {
+			push(`- child (--no-extensions): ${childModels.length}`);
+			if (hostModels.length && childModels.length === 0) {
+				push("- child sees NO models — providers come from host packages that `--no-extensions` skips.");
+			}
 		}
 		if (restoring.length) {
 			push("- packages that restore models when passed via `--extension`:");
@@ -786,11 +857,18 @@ export function runLegionDoctor(options: DoctorOptions = {}): DoctorReport {
 
 	if (want(selected, "spawn")) {
 		push("## Spawn");
-		push(`### Sample child argv (${sample.name})`);
-		push("```");
-		push(argv.join(" "));
-		push("```");
-		push(`- explicit --extension count: ${explicitExts.length}`);
+		push(`- spawnMode (sample/default): ${spawnMode}`);
+		if (isInprocess) {
+			push(`### Sample child (${sample.name}) — inprocess`);
+			push("- no child argv (ModelRuntime + additionalExtensionPaths from role/env)");
+			push("- do not treat `pi --no-extensions --list-models` as the primary diagnosis for inprocess (#212)");
+		} else {
+			push(`### Sample child argv (${sample.name})`);
+			push("```");
+			push(argv.join(" "));
+			push("```");
+			push(`- explicit --extension count: ${explicitExts.length}`);
+		}
 		push(`- nested spawn env ${ALLOW_NESTED_ENV}=${env[ALLOW_NESTED_ENV] ?? "(unset)"}`);
 		push(`- runtime.allowNestedEnv: ${runtime.allowNestedEnv ?? "(unknown)"}`);
 		push(`- roles with allowNestedSubagents: ${
@@ -954,9 +1032,18 @@ export function runLegionDoctor(options: DoctorOptions = {}): DoctorReport {
 		push("");
 		push("## Next steps (actionable)");
 		const steps: string[] = [];
-		if (providerExtHome.length && issues.some((i) => i.code === "CHILD_NO_MODELS" || i.code === "TEAM_MODELS_MISSING" || i.code === "RECENT_MODEL_SPAWN_FAIL")) {
+		const modelIssue = issues.some((i) =>
+			i.code === "CHILD_NO_MODELS" || i.code === "TEAM_MODELS_MISSING" || i.code === "RECENT_MODEL_SPAWN_FAIL",
+		);
+		if (modelIssue && isInprocess) {
+			steps.push(
+				"Inprocess: declare the provider in models.json, or set role extensions: […] / inheritExtensions: true — then restart pi (#212).",
+			);
+		} else if (modelIssue && providerExtHome.length) {
 			steps.push(`export ${CHILD_EXTENSIONS_ENV}=${providerExtHome.join(",")}  # then restart pi`);
 			steps.push(`# or role frontmatter extensions: […] / inheritExtensions: true (more RAM)`);
+		} else if (modelIssue) {
+			steps.push(`# set role frontmatter extensions: […] / inheritExtensions: true, or export ${CHILD_EXTENSIONS_ENV}=<paths>`);
 		}
 		steps.push(...roleToolGateNextSteps(issues));
 		if (issues.some((i) => i.code === "MEMORY_GATE_WOULD_REFUSE")) {

package/src/extension/legion-tools.ts

@@ -253,7 +253,13 @@ export class LegionPostman {
 			this.eventBus?.emit(event);
 			reported.add(node.id);
 			this.sendRootMessage(
-				`Legion orphan detected: ${node.id} (${node.role}, status=${node.status}) has no active supervisor and no heartbeat for ${Math.max(0, timestamp - node.updatedAt)}ms. Resume requires CEO approval.`,
+				// The notice can be delivered long after detection: it is queued through
+				// `subagent-notify` and the outbox flushes at `MAX_PENDING_AGE_MS` or at
+				// `agent_settled`. A stale `staleMs` alone therefore reads as "detected
+				// just now" when the value can be tens of minutes old, which makes a
+				// replayed notice look like a fresh detection. Stamp the detection time
+				// so a late delivery is self-evident.
+				`Legion orphan detected at ${new Date(timestamp).toISOString()}: ${node.id} (${node.role}, status=${node.status}) has no active supervisor and no heartbeat for ${Math.max(0, timestamp - node.updatedAt)}ms. Resume requires CEO approval.`,
 			);
 		}
 	}

package/src/extension/playbook.ts

@@ -13,7 +13,7 @@ export const PARENT_PLAYBOOK = [
 	"3. Then return control. A completion message wakes this session when idle; if it is still working, the notice waits until the current turn ends. Use `wait` with `name` or `all: true` when you need blocking results, and `collect` to inspect a child's session JSONL. Esc / wait interrupt only ends the parent turn's wait — children keep running and settle still notifies; only an explicit `stop` or session exit retires them. A wait interrupted by Esc returns `interrupted (parent turn ended; children still running)`. In `pi --print` or JSON mode, session shutdown waits for live async children to settle (up to each child's turn timeout) before retiring them. Use same-turn `wait`/`collect` or `async: false` when that print turn must include the child's result.",
 	"4. Later control is only through `subagent({ action, name?, message? })`; `status` with no name (or `all: true`) overviews live children, with `name` for one child; use `stop` to gracefully retire one child or all tracked children (`force: true` for hard retire when soft stop is insufficient). A `wait` timeout does not stop children — the result lists decisions (`extend` / `steer_again` / `stop` / `force_stop`) for the parent to choose. If a child exits oddly (Model not found, missing tools, memory refused, …), call `subagent({ action: \"diagnose\" })` or ask the user to run `/legion doctor` / `/legion doctor models` — children use `--no-extensions`, so provider packages must be passed explicitly. Do not tell a child to message or prompt the parent directly.",
 	"5. A collect timeout with a live RPC child is a progress signal, not a verdict. Check status or session JSONL before deciding to steer or resume.",
-	"6. Isolation is YOUR call. Pass `worktree: true` when another parent may write this repo or the child must ship via MR; pass `worktree: false` to share the checkout. Omit it for the role default.",
+	"6. Isolation belongs to centurion. For N parallel isolated writers, dispatch N centurions (each owns one worktree); members stay `worktree: false` in-process. Passing `worktree: true` on a non-centurion warns once and is forced false.",
 	"7. Launch with `verify: [\"npm run typecheck\", \"npm test\"]` when the project has a mechanical verifier. The extension runs those commands itself in the child worktree at collect time; the child does not need to paste test output.",
 	"Utility agents (`utility: true`, e.g. scout) can be dispatched by ANY role via the separate `vexillatio` tool — read-only helpers, always leaf, no depth budget. The `subagent` tool stays for the command chain (worker/centurion).",
 	"Forbidden: direct bash access to legion.db, hand-launching child Pi processes, or using herdr pane/tab/agent commands for dispatch.",