pi-legion 3.0.0 → 3.0.3

package/src/extension/runtime.ts

@@ -12,6 +12,7 @@ import {
 	formatCompletionNotice,
 	formatGroupedNotice,
 	collectFailureInput,
+	type CompletionNotice,
 	type SendMessageApi,
 } from "./notify.ts";
 import {
@@ -19,6 +20,7 @@ import {
 	DEFAULT_JOIN_MODE,
 	JoinCoordinator,
 	type JoinConfig,
+	type JoinSchedulerHandle,
 } from "./join.ts";
 import {
 	createStatusBoard,
@@ -144,12 +146,48 @@ export interface SessionRuntimeDeps {
 	) => () => void;
 	/** Batching config; applied via setJoinConfig right after construction. */
 	joinConfig?: JoinConfig;
+	/** Injectable timer for the MAX_PENDING_AGE_MS overflow (tests fire it manually); default = unref'd setTimeout. */
+	scheduleNoticeOverflow?: (ms: number, fn: () => void) => JoinSchedulerHandle;
 }
 
 const DEFAULT_REFRESH_MS = 500;
+/**
+ * Hard cap on how long a completion notice may stay hidden behind a live
+ * parent agent run (D-B). 80s = 2× the (1+3)×10s that the old join window
+ * could reach while a busy parent kept extending it. Past this the notice is
+ * force-sent even though the run is still going: reverting to the old
+ * "queued as a followUp" behaviour after 80s is better than hiding it forever.
+ */
+export const MAX_PENDING_AGE_MS = 80_000;
 /** Fallback per-child timeout for wait(); index.ts passes the role value. */
 const DEFAULT_WAIT_TIMEOUT_MS = DEFAULTS.turnTimeoutMs;
 
+/** Default timer for the MAX_PENDING_AGE_MS overflow (unref'd, like join's). */
+function defaultNoticeOverflow(
+	ms: number,
+	fn: () => void,
+): JoinSchedulerHandle {
+	const id = setTimeout(fn, ms);
+	id.unref?.();
+	return { cancel: () => clearTimeout(id) };
+}
+
+/** A completion notice held because the parent agent run is still active (D-A). */
+interface QueuedNotice {
+	notice: CompletionNotice;
+	triggerTurn: boolean;
+	enqueuedAt: number;
+}
+
+export interface NoticeQueueStats {
+	/** Notices currently held. */
+	pending: number;
+	/** now() - enqueuedAt of the oldest held notice; 0 when empty. */
+	oldestAgeMs: number;
+	/** Lifetime count of MAX_PENDING_AGE_MS overflows that forced a send (D-B observability). */
+	forcedFlushes: number;
+}
+
 /** A wait() promise that must settle by the deadline. */
 class WaitTimeoutError extends Error {}
 const WAIT_INTERRUPTED = Symbol("wait interrupted");
@@ -181,8 +219,21 @@ export interface LiveChildStatusInput {
 		usage?: { input: number; output: number; cost: number } | null;
 	};
 	acceptance?: { status: string; level?: string };
+	/**
+	 * Backend the child was actually spawned on (#209). Absent for records written
+	 * before run.json carried it, and for tree-only fallbacks — renders `unknown`,
+	 * never a guessed `rpc`.
+	 */
+	spawnMode?: string;
 	/** RPC process is still running. */
 	alive: boolean;
+	/**
+	 * Run-dir ownership verdict (#209-3), from `owner.json`.
+	 * `alive` is this process's in-memory child registry, which never contains
+	 * a child launched by another session — so a foreign record must be judged
+	 * by the owner marker instead. Only consulted when `alive` is false.
+	 */
+	owner?: "live" | "dead" | "unknown";
 	now?: number;
 }
 
@@ -245,6 +296,12 @@ function formatExecutionStatusLine(
 	return `${label}: ${execution.status}${execution.reason ? ` (${execution.reason})` : ""}`;
 }
 
+/** One-line ownership verdict appended to a status block (#209-3). */
+function ownerLine(owner: "live" | "dead" | "unknown"): string {
+	if (owner === "dead") return "owner: dead (pid gone)";
+	return `owner: ${owner}`;
+}
+
 /**
  * Status text for one child (`/legion status <name>` and `subagent status`).
  *
@@ -257,7 +314,15 @@ function formatExecutionStatusLine(
  */
 export function renderLiveChildStatus(input: LiveChildStatusInput): string {
 	const stale = persistedSnapshotIsStale(input);
-	const state = stale ? "working" : input.state;
+	// #209-3: a persisted `working` snapshot whose run-dir owner pid is gone is
+	// dead, not working. `stale` (alive process + retired/failed snapshot) keeps
+	// owning the opposite direction, so the two never fight over one record.
+	const ownerDead = input.owner === "dead" && !input.alive;
+	const state = stale
+		? "working"
+		: ownerDead && input.state === "working"
+			? "failed"
+			: input.state;
 	const execution = stale
 		? { status: "running", reason: "rpc child alive", usage: input.execution?.usage }
 		: input.execution;
@@ -268,9 +333,11 @@ export function renderLiveChildStatus(input: LiveChildStatusInput): string {
 		const age = lastJsonlEventAgeMs(input.sessionFile, input.now ?? Date.now());
 		lines.push(formatAliveQuiet(age));
 	}
+	// After the liveness lead: who owns the run dir, and whether that pid is gone.
+	if (input.owner !== undefined) lines.push(ownerLine(input.owner));
 	// Quiet age first; path metadata after snapshots so old store lines stay below.
 	const meta = [
-		"supervisor=rpc",
+		`supervisor=${input.spawnMode ?? "unknown"}`,
 		`session=${input.sessionFile}`,
 	];
 	if (execution) {
@@ -356,6 +423,12 @@ export interface SessionRuntime {
 	statusTui(): WidgetTui | undefined;
 	/** Forward join config to the internal coordinator (settings wiring). */
 	setJoinConfig(config: JoinConfig): void;
+	/** Parent agent run started (pi `agent_start`): hold completion notices until settle (D-A/D-C). */
+	notifyParentRunStart(): void;
+	/** Parent agent run settled (pi `agent_settled`): send every held notice now, then repaint (D-A/D-D). */
+	notifyParentSettled(): void;
+	/** Introspection seam for tests/doctor: deferred-notice queue state (D-B observability). */
+	noticeQueueStats(): NoticeQueueStats;
 	/**
 	 * Explicit wait: suppress auto-notify on the targets via consumedByTool
 	 * and aggregate their results. A timeout restores auto-notify.
@@ -400,6 +473,92 @@ export function createSessionRuntime(deps: SessionRuntimeDeps): SessionRuntime {
 		mode: DEFAULT_JOIN_MODE,
 		flushMs: DEFAULT_FLUSH_MS,
 	};
+
+	// Run-scoped completion outbox (D-A). The host only drains
+	// `agent.followUpQueue` inside a live run, so a `followUp` sent while the
+	// parent run is active sits invisible until the user types again. When a
+	// run is active we therefore hold the formatted notice here and burst it
+	// out on `agent_settled` (D-D). This is the ONLY deferral point: the join
+	// window above batches stragglers and never waits on a busy parent (D-I).
+	//
+	// D-H: the default is `false`, so a host (or a test) that never signals a
+	// run start keeps today's immediate-send behaviour byte for byte.
+	let parentRunActive = false;
+	const outbox: QueuedNotice[] = [];
+	let outboxTimer: JoinSchedulerHandle | undefined;
+	let forcedFlushes = 0;
+
+	const armOutboxTimer = (): void => {
+		if (outboxTimer || outbox.length === 0 || disposed) return;
+		const oldest = outbox[0]!;
+		const delay = Math.max(0, oldest.enqueuedAt + MAX_PENDING_AGE_MS - now());
+		// `live` proves this callback is the CURRENT arm. A cancelled-but-still-
+		// invoked timer (a zombie queued before the cancel landed) must be a strict
+		// no-op: otherwise it would clear the live timer's handle and force-send a
+		// notice that is nowhere near its cap.
+		//
+		// A boolean — not a closure over the handle — because an injected scheduler
+		// is free to invoke the callback synchronously, before the `const` binding
+		// is initialized (TDZ). `live` is assigned above the call, so it is always
+		// safe to read from inside the callback.
+		let live = true;
+		const handle: JoinSchedulerHandle = (deps.scheduleNoticeOverflow ?? defaultNoticeOverflow)(delay, () => {
+			if (!live) return;
+			live = false;
+			outboxTimer = undefined;
+			if (outbox.length === 0) return;
+			const next = outbox[0]!;
+			if (now() < next.enqueuedAt + MAX_PENDING_AGE_MS) {
+				// Fired while the oldest notice is still younger than the cap (a
+				// coarse timer or a backwards clock step). Never force-send early:
+				// re-arm for the remaining age instead.
+				armOutboxTimer();
+				return;
+			}
+			forcedFlushes += 1;
+			flushOutbox();
+		});
+		outboxTimer = {
+			cancel: () => {
+				live = false;
+				handle.cancel();
+			},
+		};
+	};
+
+	// FIFO, one message per notice: the grouped shape belongs to the join layer.
+	// N held notices = N host `_runAgentPrompt` calls; the common case is 1 per
+	// run, so the batch is not merged into a synthetic grouped notice.
+	const flushOutbox = (): void => {
+		outboxTimer?.cancel();
+		outboxTimer = undefined;
+		if (outbox.length === 0) return;
+		// One splice: anything enqueued by a re-entrant send belongs to the next
+		// batch, so a settle can never double-deliver what it already flushed.
+		const batch = outbox.splice(0);
+		for (const item of batch) {
+			// A rejected send is dropped, not requeued (same as before).
+			deliverCompletion(
+				{ sendMessage: deps.sendMessage },
+				item.notice,
+				item.triggerTurn,
+			);
+		}
+	};
+
+	/** The single completion exit: send now, or hold until the run settles. */
+	const sendCompletionNotice = (
+		notice: CompletionNotice,
+		triggerTurn: boolean,
+	): void => {
+		if (!parentRunActive) {
+			deliverCompletion({ sendMessage: deps.sendMessage }, notice, triggerTurn);
+			return;
+		}
+		outbox.push({ notice, triggerTurn, enqueuedAt: now() });
+		armOutboxTimer();
+	};
+
 	const join = new JoinCoordinator({
 		deliver: (batch) => {
 			if (disposed) return;
@@ -415,8 +574,7 @@ export function createSessionRuntime(deps: SessionRuntimeDeps): SessionRuntime {
 				batch.length === 1 &&
 				(joinConfig.mode === "each" || join.allSettled(first.runId))
 			) {
-				deliverCompletion(
-					{ sendMessage: deps.sendMessage },
+				sendCompletionNotice(
 					formatCompletionNotice(first.input),
 					first.triggerTurn,
 				);
@@ -435,8 +593,7 @@ export function createSessionRuntime(deps: SessionRuntimeDeps): SessionRuntime {
 						!batch.some((e) => e.name === job.name),
 				)
 				.map((job) => job.name);
-			deliverCompletion(
-				{ sendMessage: deps.sendMessage },
+			sendCompletionNotice(
 				formatGroupedNotice({
 					runId: first.runId,
 					entries: batch.map((e) => ({ ...e.input, status: e.status })),
@@ -867,6 +1024,10 @@ export function createSessionRuntime(deps: SessionRuntimeDeps): SessionRuntime {
 					job.notified = false;
 					job.consumedByTool = false;
 					join.addPending(job.runId, job.name);
+					// Repaint before the new watch takes over so the panel cannot
+					// hold the old row's final second. watch() repaints too; this is
+					// an idempotent second guarantee.
+					refreshUi();
 					runtime.watch(name, opts);
 				};
 				try {
@@ -914,6 +1075,9 @@ export function createSessionRuntime(deps: SessionRuntimeDeps): SessionRuntime {
 					}
 					job.state = "awaiting";
 					job.settledAt = now();
+					// Repaint immediately: the row flips to a terminal state here, and
+					// waiting for the 500ms sampler leaves a phantom "working" row.
+					refreshUi();
 					if (!job.consumedByTool && !job.notified) {
 						job.notified = true;
 						join.onTerminal({
@@ -959,6 +1123,7 @@ export function createSessionRuntime(deps: SessionRuntimeDeps): SessionRuntime {
 					}
 					job.state = "awaiting";
 					job.settledAt = now();
+					refreshUi();
 					if (!job.consumedByTool && !job.notified) {
 						job.notified = true;
 						// Collect failures join the batch too, as a failed entry.
@@ -1157,6 +1322,25 @@ export function createSessionRuntime(deps: SessionRuntimeDeps): SessionRuntime {
 			join.setConfig(config);
 		},
 
+		notifyParentRunStart() {
+			parentRunActive = true;
+		},
+
+		notifyParentSettled() {
+			parentRunActive = false;
+			flushOutbox();
+			refreshUi();
+		},
+
+		noticeQueueStats(): NoticeQueueStats {
+			const oldest = outbox[0];
+			return {
+				pending: outbox.length,
+				oldestAgeMs: oldest ? Math.max(0, now() - oldest.enqueuedAt) : 0,
+				forcedFlushes,
+			};
+		},
+
 		async wait(names, opts = {}) {
 			return Promise.all(
 				names.map((name) =>
@@ -1194,6 +1378,12 @@ export function createSessionRuntime(deps: SessionRuntimeDeps): SessionRuntime {
 			jobs.clear();
 			finished.clear();
 			join.dispose();
+			// Shutdown drops held notices unsent: the child's session file survives,
+			// so `collect` can still recover the result from disk. The `finished`
+			// cache does NOT survive — it was cleared two statements up.
+			outboxTimer?.cancel();
+			outboxTimer = undefined;
+			outbox.length = 0;
 			if (timer) clearInterval(timer);
 			timer = undefined;
 			for (const unsubscribe of busUnsubscribers) unsubscribe();
@@ -1289,6 +1479,13 @@ function statusEntryFromNode(
 		activity?.turnStartedAt,
 		activity?.turnEndedAt,
 	);
+	// An in-process child has no tracked job for its whole first run: spawnChild()
+	// awaits the whole agent run, so the job (and its sessionFile plumbing in
+	// statusEntryFromJob) does not exist yet. The node row does carry the session
+	// file, so parse it directly — otherwise the ledger only has a tokens_out row
+	// after settle and the token rate reads 0 for the agent's entire lifetime.
+	const live = node.sessionFile ? progressFromSessionFile(node.sessionFile) : {};
+	const tokensOut = live.tokensOut ?? node.tokensOut;
 	return {
 		name: node.name,
 		agent: node.role,
@@ -1300,8 +1497,9 @@ function statusEntryFromNode(
 		...(node.phase ? { phase: node.phase } : {}),
 		...(node.kind ? { kind: node.kind } : {}),
 		...(node.model ? { model: node.model } : {}),
-		...(node.tokensTotal ? { tokensTotal: node.tokensTotal } : {}),
-		...(node.tokensOut ? { tokensOut: node.tokensOut } : {}),
+		...(live.usageTotal ? { tokensTotal: live.usageTotal } : node.tokensTotal ? { tokensTotal: node.tokensTotal } : {}),
+		...(tokensOut ? { tokensOut } : {}),
+		...(live.generationMs ? { generationMs: live.generationMs } : {}),
 		...(activity?.turn !== undefined ? { turns: activity.turn } : {}),
 		...(activity?.turnStartedAt !== undefined ? { currentTurnStartedAt: activity.turnStartedAt } : {}),
 		...(activity?.turnEndedAt !== undefined ? { currentTurnEndedAt: activity.turnEndedAt } : {}),

package/src/extension/spawn-hints.ts

@@ -3,12 +3,16 @@
  * so `/legion doctor` / `subagent action=diagnose` can show what just broke.
  */
 
+import type { SpawnMode } from "../shared/types.ts";
+
 export interface SpawnFailureRecord {
 	ts: number;
 	name: string;
 	message: string;
 	stderr?: string;
 	hadNoExtensions?: boolean;
+	/** When known, doctor / hints can avoid RPC-only advice for inprocess (#212). */
+	spawnMode?: SpawnMode;
 }
 
 const MAX_FAILURES = 8;
@@ -29,21 +33,35 @@ export function clearSpawnFailures(): void {
 }
 
 const MODEL_NOT_FOUND =
-	/Model\s+"[^"]+"\s+not found|No models available|Use --list-models/i;
+	/Model\s+"[^"]+"\s+not found|No models available|Use --list-models|Unknown provider|inprocess model resolve failed/i;
 
 export function looksLikeMissingModel(stderr: string | undefined): boolean {
 	return Boolean(stderr && MODEL_NOT_FOUND.test(stderr));
 }
 
+/** Inprocess children have no argv; point at models.json / role extensions (#212). */
+export const INPROCESS_MODEL_HINT =
+	"Hint: default spawnMode is `inprocess` — children resolve models via ModelRuntime, " +
+	"not a `--no-extensions` argv.\n" +
+	"Fix: declare the provider statically in `models.json` (agent dir / project), " +
+	"list the extension under the role's `extensions:` frontmatter, or set " +
+	"`inheritExtensions: true` / `PI_LEGION_CHILD_INHERIT_EXTENSIONS=1`. " +
+	"Run `/legion doctor` or `subagent action=diagnose`.";
+
 /**
- * When a child dies because its model/provider is invisible under
- * `--no-extensions`, point at the escape hatches and `/legion doctor`.
+ * When a child dies because its model/provider is invisible, point at the
+ * right escape hatch for the spawn backend (`rpc` argv vs `inprocess`).
  */
 export function spawnFailureHint(input: {
 	stderr?: string;
 	args?: readonly string[];
+	/** Prefer this when known; inprocess never gets argv / CHILD_EXTENSIONS advice (#212). */
+	spawnMode?: SpawnMode;
 }): string | undefined {
 	if (!looksLikeMissingModel(input.stderr)) return undefined;
+	if (input.spawnMode === "inprocess") {
+		return INPROCESS_MODEL_HINT;
+	}
 	const noExt = input.args?.includes("--no-extensions") ?? true;
 	if (!noExt) {
 		return (
@@ -67,13 +85,16 @@ export function withSpawnFailureHint(message: string, input: {
 	stderr?: string;
 	args?: readonly string[];
 	name?: string;
+	spawnMode?: SpawnMode;
 }): string {
 	const hint = spawnFailureHint(input);
 	recordSpawnFailure({
 		name: input.name ?? "?",
 		message,
 		stderr: input.stderr,
-		hadNoExtensions: input.args?.includes("--no-extensions"),
+		hadNoExtensions:
+			input.spawnMode === "inprocess" ? false : input.args?.includes("--no-extensions"),
+		spawnMode: input.spawnMode,
 	});
 	return hint ? `${message}\n\n${hint}` : message;
 }

package/src/runs/orchestrator.ts

@@ -74,9 +74,13 @@ import { provisionWorktree } from "./provision.ts";
 
 export interface BudgetRefusedEvent {
 	type: "budget_refused";
-	requestedMaxDepth: number;
-	effectiveMaxDepth: number;
 	reason: string;
+	/** Present for maxDepth hard-cap warnings. */
+	requestedMaxDepth?: number;
+	/** Present for maxDepth hard-cap warnings. */
+	effectiveMaxDepth?: number;
+	/** Role name when reason is `worktree_denied_non_centurion` (#214). */
+	agent?: string;
 }
 
 export interface OrchestratorLegionContext {
@@ -128,7 +132,15 @@ export interface CollectResult {
 }
 
 export const COLLECT_GRACE_EXTENSIONS = 2;
-/** Shown when the launch-time collect budget elapses and the child is still in-turn. */
+/**
+ * Shown when this collect() call's budget elapses and the child is still in-turn.
+ *
+ * The "cumulative since launch" wording below is legacy: `collect()` starts its
+ * deadline from the moment it is called (`orchestrator.ts` `let deadline = ...`),
+ * not from launch. The literal is user-visible and asserted in integration tests,
+ * so D6 of `docs/contracts/vexillatio-nonblocking-launch-v1.md` deliberately left
+ * it untouched; do not read it as the actual budget origin.
+ */
 export const COLLECT_DEADLINE_REASON = "collect deadline (cumulative since launch) exceeded; child still alive";
 /** Shown when a live child's session ends on an OpenAI/GPT connection blip. */
 export const TRANSIENT_CONNECTION_REASON = "transient connection error; RPC child still alive";
@@ -257,6 +269,7 @@ export class Orchestrator {
 	private readonly legion?: OrchestratorLegionContext;
 	private readonly requestedDepthCap?: number;
 	private depthWarningEmitted = false;
+	private worktreeDeniedWarningEmitted = false;
 	private spawned = 0;
 	private readonly children = new Map<string, ChildRecord>();
 	private readonly nameCounter = new Map<string, number>();
@@ -524,6 +537,26 @@ export class Orchestrator {
 		this.onBudgetRefused?.(event);
 	}
 
+	/**
+	 * #214: only `name === "centurion"` may hold worktree isolation.
+	 * Non-centurion requests warn once per run (like warnDepthCap) and are
+	 * forced to false — never thrown.
+	 */
+	private warnWorktreeDenied(agentName: string): void {
+		if (this.worktreeDeniedWarningEmitted) return;
+		this.worktreeDeniedWarningEmitted = true;
+		const event: BudgetRefusedEvent = {
+			type: "budget_refused",
+			reason: "worktree_denied_non_centurion",
+			agent: agentName,
+		};
+		console.warn(
+			`[pi-legion] worktree denied for non-centurion role '${agentName}'; forced worktree: false. ` +
+				`Fix the role card (set worktree: false) or dispatch a centurion for isolated parallel writers.`,
+		);
+		this.onBudgetRefused?.(event);
+	}
+
 	async launch(input: {
 		agent: AgentConfig;
 		task: string;
@@ -562,8 +595,18 @@ export class Orchestrator {
 		let sessionFile = previous?.sessionFile ?? this.sessionFileFor(name);
 		const tempDir = this.runDir;
 		const parentRole = this.legion ? getNode(this.legion.db, this.legion.nodeId)?.role : undefined;
-		const worktree = this.legion && input.agent.name === "centurion"
-			? true
+		const isCenturion = input.agent.name === "centurion";
+		// #214 D4: only centurion may hold worktree. Legion path still forces
+		// centurion→true and centurion-parent→member false; non-centurion
+		// requests from any source are demoted below (D1: warn, never throw).
+		let worktree = isCenturion
+			? (this.legion
+				? true
+				: resolveLaunchWorktree({
+					roleDefault: input.agent.worktree,
+					launch: input.worktree,
+					parentInWorktree: isInsideChildWorktree(this.cwd),
+				}))
 			: this.legion && parentRole === "centurion"
 				? false
 				: resolveLaunchWorktree({
@@ -571,6 +614,10 @@ export class Orchestrator {
 					launch: input.worktree,
 					parentInWorktree: isInsideChildWorktree(this.cwd),
 				});
+		if (!isCenturion && worktree === true) {
+			this.warnWorktreeDenied(input.agent.name);
+			worktree = false;
+		}
 		// 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
@@ -614,7 +661,7 @@ export class Orchestrator {
 		// `launch({ worktree: false })` — that override now wins as it should.
 		if (inProcess && worktree) {
 			throw new SubagentError(
-				`spawnMode "inprocess" cannot use worktree isolation for '${name}'`,
+				`spawnMode "inprocess" cannot use worktree isolation for '${name}'; set worktree: false`,
 				ErrorCodes.INVALID_PARAMS,
 			);
 		}
@@ -656,7 +703,8 @@ export class Orchestrator {
 						? this.depth + 1
 						: Math.min(this.maxDepthValue, this.depth + roleDepth, MAX_NESTED_PATH_ENTRIES),
 					nodeId,
-					herdr: { supervisor: "rpc", node_id: nodeId },
+					// #209: the run record carries the ARBITRATED backend, not a literal.
+					herdr: { supervisor: mode, node_id: nodeId },
 				});
 				createdRunId = run.runId;
 				sessionFile = this.legion.runStore.sessionFileFor(run.runId, name);
@@ -740,6 +788,8 @@ export class Orchestrator {
 				previous.acceptance = undefined;
 				previous.outputFile = undefined;
 				previous.model = startedModel;
+				// A resume re-arbitrates the backend; keep the record truthful (#209).
+				previous.spawnMode = mode;
 				this.children.set(name, previous);
 			}
 			const child = previous ?? this.recordChild({
@@ -747,6 +797,7 @@ export class Orchestrator {
 				...(nodeId ? { nodeId } : {}),
 				agent: input.agent,
 				sessionFile: result.sessionFile,
+				spawnMode: mode,
 				...(startedModel ? { model: startedModel } : {}),
 				...(input.thinking !== undefined ? { thinking: input.thinking } : input.agent.thinking !== undefined ? { thinking: input.agent.thinking } : {}),
 				...(worktreePath ? { worktreePath } : {}),
@@ -762,6 +813,8 @@ export class Orchestrator {
 				agent: input.agent.name,
 				kind: input.agent.kind,
 				child,
+				// #209: callers render this instead of assuming the RPC backend.
+				spawnMode: mode,
 			};
 		} catch (error) {
 			if (spawned) await this.supervisor.retire(name).catch(() => {});
@@ -843,6 +896,8 @@ export class Orchestrator {
 		nodeId?: string;
 		agent: AgentConfig;
 		sessionFile: string;
+		/** Arbitrated spawn backend (#209); persisted so later operators see the truth. */
+		spawnMode: SpawnMode;
 		model?: string;
 		thinking?: string | false;
 		worktreePath?: string;
@@ -862,6 +917,7 @@ export class Orchestrator {
 			...(input.agent.completionGuard ? { completionGuard: true } : {}),
 			...(input.model ? { model: input.model } : {}),
 			...(input.thinking !== undefined ? { thinking: input.thinking } : {}),
+			spawnMode: input.spawnMode,
 			...(input.worktreePath ? { worktreePath: input.worktreePath } : {}),
 			...(input.worktreeBranch ? { worktreeBranch: input.worktreeBranch } : {}),
 		};
@@ -954,9 +1010,23 @@ export class Orchestrator {
 		}
 		if (opts.signal?.aborted) return abortedSnapshot();
 		parsed = parseSessionFile(child.sessionFile);
+		// #227 D5: a child whose process is gone cannot produce another message.
+		// When its last turn already ended with a terminal assistant message there
+		// is nothing left to wait for, so finish the completed turn here.
+		//
+		// This is defensive rather than an observable behaviour fix: the
+		// collect-deadline branch below is already gated on `isAlive(name)`, so a
+		// dead child never received the `running` snapshot. Keeping the guard makes
+		// the intent explicit instead of relying on that coincidence — see D5 and
+		// the disclosure in the #227 contract.
+		if (wait === "timeout" && !this.supervisor.isAlive(name) && isLastTurnComplete(parsed)) {
+			return this.finishCollect(child, parsed, deriveOutcome(parsed), deadline);
+		}
 		let execution = deriveOutcome(parsed);
 		if (wait === "timeout" && this.supervisor.isAlive(name) && !isLastTurnComplete(parsed)) {
-			// `timeoutMs` is the budget from launch, not the length of this status check.
+			// `timeoutMs` is measured from THIS collect call, not from the launch (D6).
+			// The constant's "cumulative since launch" wording is legacy; see its
+			// docstring for why it was left as-is.
 			execution = { ...execution, status: "running", reason: COLLECT_DEADLINE_REASON };
 		} else if (wait === "gone" && parsed.turns.length === 0) {
 			execution = { status: "aborted", reason: "RPC child exited before writing session JSONL", model: child.model ?? null };

package/src/runs/worktree.ts

@@ -1,10 +1,11 @@
 /**
  * Per-child git worktree isolation.
  *
- * Writer roles default to `worktree: true`. Each child gets its own branch
- * under the run directory (`git worktree add -b`) so concurrent parent Pis
- * do not share a dirty checkout. The child commits there and opens an MR;
- * retire leaves the tree on disk (same rationale as keeping the session file).
+ * Only the `centurion` role may hold `worktree: true` (#214 / contract §9).
+ * Squad members work in-place inside the centurion subtree (or parent cwd).
+ * When isolation is granted, the child gets its own branch under the run
+ * directory (`git worktree add -b`); retire leaves the tree on disk (same
+ * rationale as keeping the session file).
  */
 
 import { execFileSync } from "node:child_process";