pi-legion 3.0.0 → 3.0.3

package/src/supervisor/inprocess-supervisor.ts

@@ -8,7 +8,9 @@
  * Does NOT use RpcClient. Process-tree / SIG retire is skipped.
  */
 
+import { statSync } from "node:fs";
 import { formatChildTask } from "../extension/child-guard.ts";
+import { parseSessionFile } from "../shared/session.ts";
 import {
 	applyThinkingSuffix,
 	childInheritsExtensions,
@@ -22,7 +24,9 @@ import {
 	DEFAULT_LEGION_SETTINGS,
 } from "../shared/types.ts";
 import {
+	POLL_INTERVAL_MS,
 	DEFAULT_INPROCESS_MAX_ACTIVE,
+	DEFAULT_INPROCESS_SPAWN_START_TIMEOUT_MS,
 } from "./spawn-mode.ts";
 import {
 	type ChildLaunchContext,
@@ -199,7 +203,25 @@ export interface InProcessSupervisorOptions {
 	limits?: InProcessLimits;
 	/** Resolve limits dynamically (settings reload). Wins over static `limits`. */
 	getLimits?: () => InProcessLimits | undefined;
+	/**
+	 * Diagnostics for a child the supervisor could not use. Two cases:
+	 *  - a spawn refused before any session existed (budget / limits), and
+	 *  - since #227, a child whose **first turn failed at runtime** (the prompt
+	 *    was rejected after `spawnChild` already returned its handle).
+	 */
 	onSpawnRefused?: (message: string) => void;
+	/**
+	 * Called at most once per spawn when the child had still not accepted its
+	 * first prompt when `spawnStartTimeoutMs` elapsed (#227 D1). Not an error:
+	 * the handle was returned anyway.
+	 */
+	onSpawnDelayed?: (message: string) => void;
+	/**
+	 * How long to wait for first-prompt acceptance before returning anyway.
+	 * Defaults to `DEFAULT_INPROCESS_SPAWN_START_TIMEOUT_MS`; tests inject a
+	 * short value instead of waiting 15s.
+	 */
+	spawnStartTimeoutMs?: number;
 }
 
 interface EventSubscription {
@@ -213,6 +235,29 @@ interface SettleWaiter {
 	cleanup?: () => void;
 }
 
+/**
+ * Shared hand-off between the first turn's drain and the acceptance gate
+ * (#227 D1a).
+ *
+ * The drain is the only place that learns *how* the prompt ended, while the gate
+ * is the only place that knows whether the turn had been accepted by then.
+ * `rejected` is set by the drain; `released` is set by the gate once
+ * `spawnChild` has committed to returning a handle for this child — after that
+ * point a failure is a runtime failure (D2), never a spawn failure.
+ */
+interface FirstTurnGate {
+	/** The prompt rejected. */
+	rejected?: { message: string };
+	/** `spawnChild` is returning a handle; the failure is no longer a spawn error. */
+	released: boolean;
+	/**
+	 * The D2 runtime-failure bookkeeping has run for `rejected`. Exactly-once:
+	 * a rejection can be recorded before the gate commits (so the drain defers)
+	 * and still need applying afterwards.
+	 */
+	applied?: boolean;
+}
+
 type ChildState = "starting" | "running" | "idle" | "retiring" | "exited" | "retired";
 
 interface ChildRecord {
@@ -232,6 +277,12 @@ interface ChildRecord {
 	abortedPending: boolean;
 	spawnDepth: number;
 	parentKey: string;
+	/**
+	 * Failure surfaced by an `error` event during the current turn (#227 D3).
+	 * Cleared when the next turn starts and consumed by the next `agent_settled`,
+	 * which is the only place it becomes visible (as `SettleResult.reason`).
+	 */
+	pendingFailure?: string;
 	/** Identity reused by every later dispatch into this child (tools inherit it). */
 	context: ChildLaunchContext;
 }
@@ -294,6 +345,135 @@ function recordOf(value: unknown): Record<string, unknown> | null {
 		: null;
 }
 
+/** Human-readable text for a rejected prompt / emitted `error` payload. */
+function failureMessage(error: unknown): string {
+	if (error instanceof Error) return error.message;
+	const record = recordOf(error);
+	if (record) {
+		// SDK `error` events carry the failing assistant message under `error`
+		// (or a bare `message`), and that message holds the provider text.
+		const nested = recordOf(record.error) ?? recordOf(record.message);
+		const text = nested?.errorMessage ?? record.message ?? record.error;
+		if (typeof text === "string" && text.trim() !== "") return text;
+	}
+	return String(error);
+}
+
+/**
+ * Provider registrations an extension queued during loading (#209-1).
+ *
+ * Structurally typed on purpose: this file reaches the SDK through a dynamic
+ * `import()` (no static SDK type imports), so only the three arrays the drain
+ * touches are declared — and `unknown` for the payloads, which are just
+ * forwarded to the model runtime.
+ */
+export interface ExtensionRegistrationQueues {
+	pendingProviderRegistrations: Array<{
+		name: string;
+		config: unknown;
+		extensionPath?: string;
+	}>;
+	pendingNativeProviderRegistrations: Array<{
+		provider: unknown;
+		extensionPath?: string;
+	}>;
+	pendingVirtualModelRegistrations: Array<{
+		definition: unknown;
+		extensionPath?: string;
+	}>;
+}
+
+/** Minimal `ModelRuntime` surface the drain needs (structurally typed). */
+export interface ModelRuntimeLike {
+	registerProvider(name: string, config: unknown): void;
+	registerNativeProvider(provider: unknown): void;
+	registerVirtualModel(definition: unknown): void;
+	/** Must reset the *synchronous* catalog snapshot the resolver reads. */
+	refresh(options?: { allowNetwork?: boolean }): Promise<unknown>;
+}
+
+/** The `{ type, message }` diagnostic shape the SDK's runtime APIs return. */
+export interface DiagnosticLike {
+	type: "info" | "warning" | "error";
+	message: string;
+}
+
+function registrationDiagnostic(
+	what: string,
+	extensionPath: string | undefined,
+	error: unknown,
+): DiagnosticLike {
+	const message = error instanceof Error ? error.message : String(error);
+	return {
+		type: "error",
+		message: `Extension "${extensionPath ?? "<unknown>"}" failed to register ${what}: ${message}`,
+	};
+}
+
+/**
+ * Drain extension provider registrations into a `ModelRuntime` (#209-1).
+ *
+ * `DefaultResourceLoader.reload()` really does load and execute the extension
+ * files, but before the extension runner binds, `pi.registerProvider()` and
+ * friends only push onto `runtime.pending*Registrations`. Nothing in Legion
+ * binds that runner for a child session, so the queues were never consumed and
+ * an extension-provided provider (e.g. `pi-any-endpoint`) was invisible.
+ *
+ * Consuming the queues alone is not enough: `registerProvider()` kicks off its
+ * catalog refresh fire-and-forget (`void this.refresh(...)`) while
+ * `resolveCliModel()` reads the *synchronous* `getModels()` snapshot. The
+ * awaited offline refresh below is what makes the extension's self-discovered
+ * catalog land in that snapshot (`allowNetwork: false` — `pi-any-endpoint`
+ * reads offline `stored.models`, so no network is involved).
+ *
+ * Failures are collected as diagnostics and never thrown: a broken extension
+ * must not fail the child spawn. Queues are emptied either way so a retry does
+ * not replay them onto the next runtime.
+ */
+export async function drainExtensionRegistrations(
+	resourceLoader: { getExtensions(): { runtime: ExtensionRegistrationQueues } },
+	modelRuntime: ModelRuntimeLike,
+): Promise<DiagnosticLike[]> {
+	const diagnostics: DiagnosticLike[] = [];
+	const { runtime } = resourceLoader.getExtensions();
+
+	for (const { name, config, extensionPath } of runtime.pendingProviderRegistrations) {
+		try {
+			modelRuntime.registerProvider(name, config);
+		} catch (error) {
+			diagnostics.push(
+				registrationDiagnostic(`provider "${name}"`, extensionPath, error),
+			);
+		}
+	}
+	runtime.pendingProviderRegistrations = [];
+
+	for (const { provider, extensionPath } of runtime.pendingNativeProviderRegistrations) {
+		try {
+			modelRuntime.registerNativeProvider(provider);
+		} catch (error) {
+			diagnostics.push(
+				registrationDiagnostic("native provider", extensionPath, error),
+			);
+		}
+	}
+	runtime.pendingNativeProviderRegistrations = [];
+
+	for (const { definition, extensionPath } of runtime.pendingVirtualModelRegistrations) {
+		try {
+			modelRuntime.registerVirtualModel(definition);
+		} catch (error) {
+			diagnostics.push(
+				registrationDiagnostic("virtual model", extensionPath, error),
+			);
+		}
+	}
+	runtime.pendingVirtualModelRegistrations = [];
+
+	await modelRuntime.refresh({ allowNetwork: false });
+	return diagnostics;
+}
+
 async function defaultSessionFactory(
 	input: InProcessSessionFactoryInput,
 ): Promise<InProcessSession> {
@@ -336,6 +516,24 @@ async function defaultSessionFactory(
 	const resourceLoader = new DefaultResourceLoader(loaderOptions);
 	await resourceLoader.reload();
 
+	// #209-1: the extension files above were loaded and executed, but their
+	// provider registrations are still sitting in `runtime.pending*Registrations`
+	// (they only take effect once an extension runner binds, which a child
+	// session without `createAgentSessionServices()` never does). Drain them into
+	// the runtime handed to `createAgentSession` so extension-provided providers
+	// are resolvable by both the `--model` resolve below and the session itself.
+	const modelRuntime = await ModelRuntime.create();
+	for (const diagnostic of await drainExtensionRegistrations(
+		resourceLoader,
+		modelRuntime,
+	)) {
+		if (diagnostic.type === "error") {
+			// Non-fatal by design (same as the SDK): the spawn only fails if the
+			// model itself cannot be resolved.
+			console.warn(`[pi-legion] inprocess child '${input.name}': ${diagnostic.message}`);
+		}
+	}
+
 	// D7 — the transcript must land on the file the Orchestrator pre-created
 	// (`orchestrator.ts` `preCreateSessionFile`). With `SessionManager.inMemory()`
 	// `getSessionFile()` returns undefined and nothing is ever written, so
@@ -347,11 +545,16 @@ async function defaultSessionFactory(
 		cwd: plan.cwd,
 		sessionManager: SessionManager.open(input.sessionFile, undefined, plan.cwd),
 		resourceLoader,
+		// Injected unconditionally — including when `plan.modelRef` is empty. Left
+		// out, `createAgentSession` would build its own runtime and be blind to
+		// the extension providers drained above all over again.
+		modelRuntime,
 		...(plan.tools ? { tools: plan.tools } : {}),
 	};
 
 	if (plan.modelRef) {
-		const modelRuntime = await ModelRuntime.create();
+		// Same runtime instance as the drain: its snapshot is the one that
+		// contains the extension-registered providers.
 		const resolved = resolveCliModel({
 			cliModel: plan.modelRef,
 			...(plan.modelProvider ? { cliProvider: plan.modelProvider } : {}),
@@ -364,7 +567,6 @@ async function defaultSessionFactory(
 				ErrorCodes.START_FAILED,
 			);
 		}
-		createOptions.modelRuntime = modelRuntime;
 		createOptions.model = resolved.model;
 		if (resolved.thinkingLevel && isThinkingLevel(resolved.thinkingLevel)) {
 			createOptions.thinkingLevel = resolved.thinkingLevel;
@@ -389,6 +591,8 @@ export class InProcessSupervisor implements LegionSupervisor {
 	private readonly sessionFactory: InProcessSessionFactory;
 	private readonly getLimits: () => InProcessLimits | undefined;
 	private readonly onSpawnRefused?: (message: string) => void;
+	private readonly onSpawnDelayed?: (message: string) => void;
+	private readonly spawnStartTimeoutMs: number;
 	readonly uiProxy: UIProxy;
 	private spawnCount = 0;
 
@@ -398,6 +602,9 @@ export class InProcessSupervisor implements LegionSupervisor {
 		this.getLimits = options.getLimits
 			?? (() => options.limits);
 		this.onSpawnRefused = options.onSpawnRefused;
+		this.onSpawnDelayed = options.onSpawnDelayed;
+		this.spawnStartTimeoutMs =
+			options.spawnStartTimeoutMs ?? DEFAULT_INPROCESS_SPAWN_START_TIMEOUT_MS;
 	}
 
 	/**
@@ -445,7 +652,7 @@ export class InProcessSupervisor implements LegionSupervisor {
 		}
 		if (input.agent.worktree === true) {
 			throw new SubagentError(
-				`spawnMode "inprocess" cannot use worktree isolation for '${input.name}'; use spawnMode "rpc" or set worktree: false`,
+				`spawnMode "inprocess" cannot use worktree isolation for '${input.name}'; set worktree: false`,
 				ErrorCodes.INVALID_PARAMS,
 			);
 		}
@@ -486,6 +693,11 @@ export class InProcessSupervisor implements LegionSupervisor {
 				// inside it, so every tool the child executes during that turn
 				// inherits the child's context instead of seeing the root's.
 				runInChildContext(registration.context, async () => {
+					// #227 D1: the acceptance baseline is the transcript size at the
+					// moment *this spawn* starts (a missing file counts as 0), so a
+					// line the factory or a previous turn already wrote cannot pass
+					// for this child having accepted the prompt.
+					const baselineSize = this.sessionFileSize(registration.sessionFile);
 					const session = await this.sessionFactory({
 						name: input.name,
 						cwd: input.cwd,
@@ -508,21 +720,34 @@ export class InProcessSupervisor implements LegionSupervisor {
 					);
 					registration.state = "idle";
 					this.spawnCount += 1;
+					// `beginTurn` must precede the prompt (R2): the turn's events are
+					// already streaming by the time this frame yields.
 					this.beginTurn(registration);
-					await session.prompt(
-						formatChildTask(input.task, {
-							allowNested: input.allowNestedSubagents === true,
-							...(input.worktreeBranch
-								? { worktreeBranch: input.worktreeBranch }
-								: {}),
-						}),
+					// #227 D1/D2: start the first turn and hand it to a background
+					// drain instead of awaiting the whole agent run here. The drain is
+					// created *inside* this ALS scope on purpose, so every later
+					// continuation (and any tool promise it settles) still runs at the
+					// child's identity and nesting depth (R1).
+					const gate: FirstTurnGate = { released: false };
+					const promptSettled = this.drainFirstTurn(
+						registration,
+						session.prompt(
+							formatChildTask(input.task, {
+								allowNested: input.allowNestedSubagents === true,
+								...(input.worktreeBranch
+									? { worktreeBranch: input.worktreeBranch }
+									: {}),
+							}),
+						),
+						gate,
+					);
+					// Return once the child has *accepted* the turn, not when it ends.
+					await this.awaitFirstTurnAccepted(
+						registration,
+						baselineSize,
+						promptSettled,
+						gate,
 					);
-					if (!this.isAlive(input.name)) {
-						throw new SubagentError(
-							`in-process session ended after its first prompt: ${input.name}`,
-							ErrorCodes.START_FAILED,
-						);
-					}
 					return {
 						name: registration.name,
 						sessionFile: registration.sessionFile,
@@ -538,6 +763,195 @@ export class InProcessSupervisor implements LegionSupervisor {
 		}
 	}
 
+	/** Bytes in the child transcript so far; a missing file counts as 0 (#227 D1). */
+	private sessionFileSize(sessionFile: string): number {
+		try {
+			return statSync(sessionFile).size;
+		} catch {
+			return 0;
+		}
+	}
+
+	/**
+	 * Has this child accepted the prompt? True once its transcript holds a user
+	 * turn *and* has grown past the pre-spawn baseline (`F7`: the SDK appends the
+	 * user message before running the agent).
+	 *
+	 * Contract F7 forbids using `isLastTurnComplete` here: while the prompt is
+	 * merely accepted the last turn legitimately has a user message and no
+	 * assistant yet, so that predicate would contradict itself.
+	 */
+	private firstTurnAccepted(child: ChildRecord, baselineSize: number): boolean {
+		if (this.sessionFileSize(child.sessionFile) <= baselineSize) return false;
+		return parseSessionFile(child.sessionFile).turns.length > 0;
+	}
+
+	/**
+	 * Resolve when the child has accepted the first prompt, when the prompt has
+	 * already settled (it then certainly was accepted — a fast turn is done and
+	 * waiting for the bound would only add latency), or when the start bound
+	 * elapses (#227 D1). The bound is never an error: the caller returns its
+	 * handle either way and is told once through `onSpawnDelayed`.
+	 */
+	private awaitFirstTurnAccepted(
+		child: ChildRecord,
+		baselineSize: number,
+		promptSettled: Promise<void>,
+		gate: FirstTurnGate,
+	): Promise<void> {
+		const deadline = Date.now() + this.spawnStartTimeoutMs;
+		return new Promise((resolve, reject) => {
+			let timer: NodeJS.Timeout | undefined;
+			let done = false;
+			/**
+			 * Commit to returning a handle for this child. From here on the drain
+			 * treats a later failure as a runtime failure (D2), not a spawn error.
+			 */
+			const finish = (delayed: boolean): void => {
+				if (done) return;
+				done = true;
+				gate.released = true;
+				if (timer) {
+					clearTimeout(timer);
+					timer = undefined;
+				}
+				// A rejection recorded before this commit still has to become the
+				// visible runtime failure (D2): the drain deferred it because the
+				// spawn had not yet committed to returning a handle.
+				this.applyFirstTurnFailure(child, gate);
+				if (delayed) {
+					this.onSpawnDelayed?.(
+						`in-process child '${child.name}' did not accept its first prompt within ` +
+							`${this.spawnStartTimeoutMs}ms; returning the handle anyway (its first turn ` +
+							"keeps running in the background)",
+					);
+				}
+				resolve();
+			};
+			/**
+			 * #227 D1a: the prompt failed and nothing was accepted, so this child
+			 * never started. Returning a handle here would let `Orchestrator.launch`
+			 * believe the spawn succeeded and silently disable the `fallbackModels`
+			 * chain (`canFallbackStart` only reacts to a thrown SubagentError). Fail
+			 * the spawn instead; the caller's existing catch rolls the child back.
+			 */
+			const fail = (message: string): void => {
+				done = true;
+				if (timer) {
+					clearTimeout(timer);
+					timer = undefined;
+				}
+				reject(new SubagentError(message, ErrorCodes.START_FAILED));
+			};
+			const tick = (): void => {
+				if (done) return;
+				if (this.firstTurnAccepted(child, baselineSize)) return finish(false);
+				if (gate.rejected) return fail(gate.rejected.message);
+				const remaining = deadline - Date.now();
+				if (remaining <= 0) return finish(true);
+				// Reuse the shared poll cadence, but never oversleep the bound.
+				timer = setTimeout(tick, Math.min(POLL_INTERVAL_MS, remaining));
+			};
+			/**
+			 * The prompt settled. `drainFirstTurn` reports the rejection through
+			 * `gate` and then resolves, so this is the one place that decides
+			 * between "spawn succeeded" and "spawn failed" (#227 D1a).
+			 *
+			 * A plain `finish(false)` here would be exactly the regression: a
+			 * pre-acceptance reject would read as a successful spawn.
+			 */
+			const onSettled = (): void => {
+				if (done) return;
+				// Accepted at any point → the turn ran, so a failure is a runtime
+				// failure (D2) and `spawnChild` still returns its handle.
+				if (this.firstTurnAccepted(child, baselineSize)) return finish(false);
+				// Rejected without ever being accepted → the child never started.
+				// Report it as a spawn failure so `canFallbackStart` can retry.
+				if (gate.rejected) return fail(gate.rejected.message);
+				// Prompt resolved but no user line is visible yet (a fake whose
+				// transcript is not on disk, or a write still in flight): the turn
+				// ended, so there is nothing left to wait for.
+				finish(false);
+			};
+			// `drainFirstTurn` deliberately resolves rather than rejects, and the
+			// second handler keeps a throwing diagnostic callback from becoming an
+			// unhandled rejection on a promise nobody awaits.
+			void promptSettled.then(onSettled, onSettled);
+			tick();
+		});
+	}
+
+	/**
+	 * Detach the first turn's completion from `spawnChild` (#227 D2).
+	 *
+	 * Resolves (never rejects) once the prompt settles, so both callers can
+	 * await it without risking an unhandled rejection.
+	 */
+	private drainFirstTurn(
+		child: ChildRecord,
+		prompt: Promise<unknown>,
+		gate: FirstTurnGate,
+	): Promise<void> {
+		return prompt.then(
+			() => {
+				// Normal completion. `agent_settled` already carried the turn state
+				// (the SDK emits it in the run's `finally`, before this resolves), so
+				// only a child that died mid-turn needs reconciling here.
+				if (!this.isAlive(child.name) && child.turnActive) {
+					child.turnActive = false;
+				}
+			},
+			(error: unknown) => {
+				const message = failureMessage(error);
+				// #227 D1a: publish the failure for the acceptance gate *first*, so
+				// the gate can turn a pre-acceptance reject into a spawn failure.
+				gate.rejected = { message };
+				// Until `spawnChild` commits to returning a handle, this is a spawn
+				// failure: the caller's catch runs `rollbackSpawn` + rethrow, and it
+				// owns the waiter/diagnostic reporting. Doing it here as well would
+				// report twice and leave state on a child that is being torn down.
+				if (!gate.released) return;
+				this.applyFirstTurnFailure(child, gate);
+			},
+		);
+	}
+
+	/**
+	 * Turn a rejected first prompt into the visible runtime failure (#227 D2).
+	 *
+	 * Exactly-once per rejection, because it can be reached from two places: the
+	 * drain (the usual path, after `spawnChild` committed to a handle) and
+	 * `awaitFirstTurnAccepted`'s `finish()` (a prompt that rejected before the
+	 * gate committed and then had its turn accepted anyway).
+	 *
+	 * Never `rollbackSpawn` here: the handle was already handed to the caller,
+	 * and rollback would `children.delete` it out from under them.
+	 */
+	private applyFirstTurnFailure(child: ChildRecord, gate: FirstTurnGate): void {
+		const message = gate.rejected?.message;
+		if (message === undefined || gate.applied) return;
+		gate.applied = true;
+		child.turnActive = false;
+		if (child.state !== "retiring") child.state = "idle";
+		const result: SettleResult = {
+			settled: false,
+			abnormal: false,
+			reason: `child turn failed: ${message}`,
+		};
+		child.lastTurnResult = result;
+		this.resolveWaiters(child, result);
+		// #227 D2: the callback's semantics now also cover a child failing at
+		// runtime, not just a refused spawn.
+		this.onSpawnRefused?.(message);
+		// ...and leave a machine-readable trace for D3's settle mapping, so the
+		// failure survives a later `agent_settled` rather than only living in the
+		// transient `lastTurnResult`.
+		this.handleSessionEvent(child, {
+			type: "error",
+			message: `child turn failed: ${message}`,
+		});
+	}
+
 	async prompt(name: string, text: string): Promise<void> {
 		const child = this.requireChild(name);
 		await this.dispatch(child, "prompt", text);
@@ -806,8 +1220,11 @@ export class InProcessSupervisor implements LegionSupervisor {
 	}
 
 	private beginTurn(child: ChildRecord): void {
+		// "clear first, set later" (R2): a stale result from a previous turn must
+		// never satisfy the `waitSettled` fast path for the new one.
 		child.lastTurnResult = undefined;
 		child.exitResult = undefined;
+		child.pendingFailure = undefined;
 		child.turnActive = true;
 		child.state = "running";
 	}
@@ -873,12 +1290,28 @@ export class InProcessSupervisor implements LegionSupervisor {
 			child.abortedPending = this.eventContainsAbort(event, child.abortedPending);
 			return;
 		}
+		if (event.type === "error") {
+			// #227 D3: `error` used to fall through to the bottom `return` and be
+			// dropped entirely (F8), so a failed child looked identical to a clean
+			// one once `agent_settled` landed. Remember it and let the settle below
+			// turn it into a visible fact. Deliberately NOT read from ALS: an
+			// `error` can arrive on the drain chain, outside this child's scope.
+			child.pendingFailure = failureMessage(event);
+			return;
+		}
 		if (event.type !== "agent_settled") return;
 		const result: SettleResult = {
 			settled: true,
 			abnormal: false,
 			aborted: child.abortedPending,
 		};
+		// Only surface `reason` when there is a recorded failure: adding it
+		// unconditionally would change the shape every clean settle returns, and
+		// `aborted` stays the sole stop-reason signal (no invented stopReason).
+		if (!result.aborted && child.pendingFailure) {
+			result.reason = child.pendingFailure;
+		}
+		child.pendingFailure = undefined;
 		child.abortedPending = false;
 		child.turnActive = false;
 		child.lastTurnResult = result;

package/src/supervisor/routing-supervisor.ts

@@ -78,7 +78,7 @@ export class RoutingSupervisor implements LegionSupervisor {
 			}
 			if (input.agent.worktree === true) {
 				throw new SubagentError(
-					`spawnMode "inprocess" cannot combine with worktree: true for '${input.name}'`,
+					`spawnMode "inprocess" cannot combine with worktree: true for '${input.name}'; set worktree: false`,
 					ErrorCodes.INVALID_PARAMS,
 				);
 			}

package/src/supervisor/spawn-mode.ts

@@ -19,6 +19,31 @@ export const DEFAULT_SPAWN_MODE: SpawnMode = "inprocess";
 /** Safe default for `inprocess.maxActive` when the inprocess block is set without it. */
 export const DEFAULT_INPROCESS_MAX_ACTIVE = 8;
 
+/**
+ * How long `InProcessSupervisor.spawnChild` waits for the child to *accept* the
+ * first prompt before returning anyway (#227 D1).
+ *
+ * The acceptance signal itself is the child transcript gaining its first user
+ * line (`F7`: the SDK appends the user message before it runs the agent), so
+ * this bound only covers a child that never writes one — a stuck session factory
+ * or a provider that swallows the prompt. Hitting it is **not** an error: the
+ * spawn still owns a live session and returns a handle, and the caller is told
+ * once through `onSpawnDelayed`.
+ */
+export const DEFAULT_INPROCESS_SPAWN_START_TIMEOUT_MS = 15_000;
+
+/**
+ * Poll cadence for the spawn-acceptance check (#227 D1).
+ *
+ * CONTRACT ERRATUM (#227, `vexillatio-nonblocking-launch-v1.md` §D1): that line
+ * says the constant already lives in `src/shared/types.ts`; it never did. The
+ * only pre-existing `POLL_INTERVAL_MS` is module-private in
+ * `src/runs/orchestrator.ts` (a Worker B file this change must not touch), so
+ * the same 500 ms cadence is exported from here instead of inventing a second
+ * value. Parent session to record this erratum in the contract document.
+ */
+export const POLL_INTERVAL_MS = 500;
+
 export function resolveSpawnMode(
 	agent: Pick<AgentConfig, "spawnMode"> | undefined,
 ): SpawnMode {