@aeondave/pi-persona 1.15.2

package/src/engine/inproc.ts

@@ -0,0 +1,857 @@
+/**
+ * InProcessEngine (v0.4) — a second `StrategyEngine` backend that runs a sub-agent
+ * IN THIS PROCESS via Pi's `createAgentSession`, instead of spawning `pi --mode
+ * json -p`. Same seam (`run` → `AgentResult`), same stream parser (`stream.ts`
+ * folds the session's `AgentEvent`s), same contract validation. This is what
+ * unlocks live **steering** (`agent.steer`) and drops the per-child spawn.
+ *
+ * Fork-bomb guard: the sub-session must NOT re-activate pi-persona (which would give
+ * the child the `delegate`/`council` tools + turn interception → recursion). We set
+ * `PI_PERSONA_DISABLE` for the duration of session creation (the same flag the child
+ * path passes via env) and exclude the orchestration tools defensively.
+ *
+ * The session factory is injectable (`deps.createSession`) — exactly like the child
+ * engine's `resolveInvocation` — so the whole path is deterministically testable with
+ * a fake session, without a live model. The default builds a real `createAgentSession`.
+ *
+ * This is the DEFAULT backend; `PI_PERSONA_ENGINE=child` opts back to the spawn-based
+ * `ChildProcessEngine`. It drops in behind the seam without touching strategies/UI.
+ */
+
+import { createAgentSession, DefaultResourceLoader, type ModelRegistry, SessionManager, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+
+import type { AgentConfig } from "../agents/agent.ts";
+import type { InProcessBus } from "../bus/inproc.ts";
+import { makeContactSupervisorTool } from "../bus/contact.ts";
+import { makeContactPeerTool } from "../bus/peers.ts";
+import { type ContractDef, contractInstructions, parseAndValidate, pinContract, type PinnedContract } from "../core/contract.ts";
+import { sanitizeDisplayLabel } from "../core/display-label.ts";
+import { assignedIdentityPrompt } from "../core/naming.ts";
+import { attributeInbound } from "../core/fence.ts";
+import { isThinkingLevel, type ThinkingLevel } from "../core/types.ts";
+import { roleHint } from "../orchestration/roster.ts";
+import { type AgentRunSpec, isPositiveFiniteMs, type StrategyEngine } from "../orchestration/sdk.ts";
+import type { AgentResult } from "../orchestration/types.ts";
+import { looksLikeProviderError } from "./errors.ts";
+import { nextChildHandle } from "./handles.ts";
+import { combineSignals } from "./signals.ts";
+import { unknownAgentFailure, unknownContractFailure } from "./spec-preflight.ts";
+import { applyEvent, createStreamState, emptyUsage, type ProgressSnapshot, snapshot } from "./stream.ts";
+
+/** The minimal slice of Pi's AgentSession the engine drives — also the test seam. */
+export interface InProcSession {
+	subscribe(listener: (event: unknown) => void): () => void;
+	prompt(input: string): Promise<void>;
+	agent: { abort(): void; waitForIdle(): Promise<void>; steer(message: unknown): void };
+	dispose(): void;
+}
+
+export interface CreateSessionOptions {
+	model: unknown;
+	modelRegistry: ModelRegistry;
+	/** Cooperative cancellation for resource/session initialization. Pi's loader does not
+	 * currently accept a signal itself, but injected factories can stop promptly and the
+	 * default factory checks it before/after each uncancellable Pi operation. */
+	signal?: AbortSignal;
+	/** The host's canonical runtime (Pi >=0.81); shared so auth/provider registrations survive. */
+	modelRuntime?: unknown;
+	cwd: string;
+	/** Pi's global agent dir (~/.pi/agent) for the sub-agent's resource loader. */
+	agentDir: string;
+	tools?: string[];
+	excludeTools?: string[];
+	thinkingLevel?: ThinkingLevel;
+	/** The agent's persona (its .md) — appended to the base system prompt. */
+	systemPrompt?: string;
+	/** Extra tools injected into the child session (e.g. `contact_supervisor`). */
+	customTools?: ToolDefinition[];
+}
+
+export type CreateInProcSession = (opts: CreateSessionOptions) => Promise<InProcSession>;
+
+/**
+ * Pi 0.81 moved the canonical auth/provider state from the extension-facing
+ * ModelRegistry to a ModelRuntime passed directly to createAgentSession. The
+ * compatibility facade still owns that runtime, but intentionally keeps it
+ * private in its public TypeScript API. Read the runtime only when the expected
+ * methods are present; old Pi versions and test facades then retain the legacy
+ * modelRegistry path.
+ */
+function sharedModelRuntime(registry: ModelRegistry): unknown {
+	const candidate = (registry as unknown as { runtime?: unknown }).runtime;
+	if (!candidate || typeof candidate !== "object") return undefined;
+	const runtime = candidate as { getAuth?: unknown; getModel?: unknown; stream?: unknown };
+	return typeof runtime.getAuth === "function" && typeof runtime.getModel === "function" && typeof runtime.stream === "function"
+		? candidate
+		: undefined;
+}
+
+export interface InProcessDeps {
+	resolveAgent: (name: string) => AgentConfig | undefined;
+	contracts?: (name: string) => ContractDef | undefined;
+	/** The host session's registry — shared so the sub-agent reuses the loader's auth. */
+	modelRegistry: ModelRegistry;
+	cwd: string;
+	/** Pi's global agent dir (~/.pi/agent); defaults to cwd if omitted (tests). */
+	agentDir?: string;
+	/** Per-agent model override (e.g. a persona's configured ensemble models). */
+	modelFor?: (agent: string) => string | undefined;
+	/** The session/loader model — the last-resort fallback when an agent declares none
+	 *  (the child engine gets this for free from `pi -p`'s default; inproc must pass it). */
+	defaultModel?: string;
+	/** Explicit thinking level for the sub-agent (the supervisor's, or a default). */
+	childThinking?: string;
+	/** The shared behavioral layer (docs/SPINE.md), prepended to every leg's prompt. This is the
+	 *  WORKER variant (`prompts/spine.worker.md`), not the supervisor text — a leg runs headless
+	 *  with no user to confirm anything with. Absent/empty (the default) ⇒ the composed prompt is
+	 *  byte-identical to the pre-spine one. */
+	spine?: string;
+	/** Whole-run abort signal (combined with each call's own signal). */
+	signal?: AbortSignal;
+	/** Construction-time progress sink (used when `run` is called without its own). */
+	onProgress?: (snap: ProgressSnapshot) => void;
+	/** Known agent names, for self-correcting unknown-agent errors (mirrors the model path). */
+	listAgents?: () => string[];
+	/** Installed output-contract names (built-in `default` + files) for the self-correcting hint. */
+	listContracts?: () => string[];
+	/** Session factory — defaults to a real `createAgentSession`; injected in tests. */
+	createSession?: CreateInProcSession;
+	/** The semantic comm plane: when present + `coaching`, each child gets a
+	 *  `contact_supervisor` tool bound to this bus so it can reach the supervisor mid-run. */
+	bus?: InProcessBus;
+	/** The supervisor's bus handle (default `"supervisor"`). */
+	supervisorHandle?: string;
+	/** Inject `contact_supervisor` into children (persona `coaching: on`). Default off. */
+	coaching?: boolean;
+	/** Allow a child's `decision`/`interview` to BLOCK for a reply — async runs only.
+	 *  Sync runs hold the supervisor's turn, so blocking would deadlock: keep this false. */
+	allowBlocking?: boolean;
+	/** Persona-level bus capability (`EffectiveCapabilities.canUseBus`). Default true.
+	 *  When false, a spec's `peers` request is ignored (no `contact_peer` tool is bound). */
+	canUseBus?: boolean;
+	/** IDLE window (ms): a session that emits NO events for this long is treated as hung
+	 *  and aborted (mirrors the child engine's idle kill). 0/absent = no watchdog. Stays armed
+	 *  for every child, coaching or not: when it fires, the bus is asked whether THIS child has
+	 *  a live ask outstanding (`bus.hasPendingAskFrom`) — true re-arms the window instead of
+	 *  killing, false means the silence is real (R9). */
+	timeoutMs?: number;
+	/** HARD wall-clock cap (ms): a definite lifetime ceiling, armed ONCE and never reset by
+	 *  events — so it catches a busy-but-non-converging child (a loop that keeps emitting) that
+	 *  the idle watchdog, which any event re-arms, never would. 0/absent = no cap. Applies
+	 *  unconditionally, including to a coaching child legitimately blocked on a reply. */
+	hardTimeoutMs?: number;
+	/** STARTUP deadline (ms): a session that never makes PROGRESS (no completed turn, no tokens,
+	 *  no streamed output) within this window is aborted as a stalled start — the case the idle
+	 *  window is too generous for. The FIRST progress cancels it permanently, so a
+	 *  slow-but-streaming turn is never touched. 0/absent = no startup deadline. Stays armed for
+	 *  every child, same bus consult as the idle window above before it actually cancels (R9).
+	 *
+	 *  CHOOSE THE VALUE FOR THE FIRST PROVIDER ROUND TRIP, not for init alone. Only the child's
+	 *  OWN assistant output counts as progress — pi emits message_start/message_end for the
+	 *  prompt it just delivered too, and stream.ts filters those out — so the window has to
+	 *  cover the whole way to the FIRST provider response. A queued or rate-limited provider, a
+	 *  cold serverless endpoint or a local model doing a long prompt eval can spend minutes
+	 *  there, and this deadline aborts such a leg outright (failureKind "timeout"); the idle
+	 *  watchdog would not, because any event at all re-arms it. */
+	startupTimeoutMs?: number;
+}
+
+// The sub-agent must never re-enter the supervisor's orchestration surface. This is the SECOND
+// line of defense (the first is that a child's whole pi-persona activation short-circuits under
+// PI_PERSONA_DISABLE=1 and registers no tools at all, on either engine — see I2 in
+// docs/ARCHITECTURE.md); nesting depth is capped at 1 structurally, not by a numeric run limit.
+export const ORCHESTRATION_TOOLS = ["delegate", "council", "orchestrate", "flow"];
+
+/** Union a child session's excludeTools with `ORCHESTRATION_TOOLS`, so a delegated leg has no
+ *  tool call that could start a grandchild, however it is asked to — regardless of what the
+ *  agent's own config additionally excludes. */
+export function withOrchestrationToolsExcluded(extra: readonly string[] | undefined): string[] {
+	return [...new Set([...ORCHESTRATION_TOOLS, ...(extra ?? [])])];
+}
+
+/** Preserve the semantic difference between an absent allowlist (Pi defaults) and an explicit
+ * empty one (no tools). Custom communication tools join only a non-empty allowlist; an empty
+ * grant must not quietly grow capabilities during session construction. */
+export function mergeSessionToolAllowlist(tools: readonly string[] | undefined, customNames: readonly string[]): string[] | undefined {
+	if (tools === undefined) return undefined;
+	if (tools.length === 0) return [];
+	return [...new Set([...tools, ...customNames])];
+}
+
+/** Default factory: a real in-process Pi session. The resource loader appends the
+ *  agent's persona to the base system prompt (the in-process `--append-system-prompt`).
+ *  Extensions DO load (so auth providers like pi-claude work) — the fork-bomb guard is
+ *  that pi-persona self-disables under `PI_PERSONA_DISABLE` (set around creation), with
+ *  the orchestration tools excluded as a second line of defense. */
+const createPiSession: CreateInProcSession = async (opts) => {
+	if (opts.signal?.aborted) throw new DOMException("Session initialization aborted", "AbortError");
+	const loader = new DefaultResourceLoader({
+		cwd: opts.cwd,
+		agentDir: opts.agentDir,
+		...(opts.systemPrompt ? { appendSystemPrompt: [opts.systemPrompt] } : {}),
+	});
+	await loader.reload();
+	if (opts.signal?.aborted) throw new DOMException("Session initialization aborted", "AbortError");
+	// If a `tools` allowlist is set, the injected custom tools must be allowed too,
+	// otherwise the allowlist would filter them out of the child's active set.
+	const customNames = (opts.customTools ?? []).map((t) => t.name);
+	const tools = mergeSessionToolAllowlist(opts.tools, customNames);
+	// Forward-compat with the model-runtime migration (pi > 0.80.7). pi <= 0.80.7 reads
+	// `CreateAgentSessionOptions.modelRegistry` to share the host's auth/model registry with the
+	// sub-session; newer pi takes the canonical `modelRuntime` instead. The extension-facing
+	// ModelRegistry keeps that runtime private in its type surface, so `sharedModelRuntime()` above
+	// recovers it only when the runtime shape is present. Passing it is important even when auth is
+	// on disk: native providers and runtime credentials can exist only in the supervisor's memory.
+	// `agentDir` remains a valid fallback for older/standalone SDKs, and the legacy key stays outside
+	// the object literal so current SDK types do not reject it.
+	const sessionOptions: NonNullable<Parameters<typeof createAgentSession>[0]> = {
+		model: opts.model as NonNullable<NonNullable<Parameters<typeof createAgentSession>[0]>["model"]>,
+		sessionManager: SessionManager.inMemory(opts.cwd),
+		resourceLoader: loader,
+		cwd: opts.cwd,
+		agentDir: opts.agentDir,
+		...(opts.modelRuntime !== undefined
+			? { modelRuntime: opts.modelRuntime as NonNullable<NonNullable<Parameters<typeof createAgentSession>[0]>["modelRuntime"]> }
+			: {}),
+		excludeTools: withOrchestrationToolsExcluded(opts.excludeTools),
+		...(tools !== undefined ? { tools } : {}),
+		...(opts.customTools && opts.customTools.length > 0 ? { customTools: opts.customTools } : {}),
+		// `opts.thinkingLevel` is our local ThinkingLevel superset — cast to pi's field type at the
+		// boundary (same rationale as PersonaHost.setThinkingLevel: a `max`-style level only reaches
+		// here on a pi that supports it, and pi clamps an unknown level regardless).
+		...(opts.thinkingLevel
+			? { thinkingLevel: opts.thinkingLevel as NonNullable<NonNullable<Parameters<typeof createAgentSession>[0]>["thinkingLevel"]> }
+			: {}),
+	};
+	(sessionOptions as { modelRegistry?: unknown }).modelRegistry = opts.modelRegistry;
+	const { session } = await createAgentSession(sessionOptions);
+	if (opts.signal?.aborted) {
+		try {
+			session.dispose();
+		} catch {
+			// The initialization cancellation result still owns the lifecycle if disposal throws.
+		}
+		throw new DOMException("Session initialization aborted", "AbortError");
+	}
+	return {
+		subscribe: (l) => session.subscribe(l as Parameters<typeof session.subscribe>[0]),
+		prompt: async (input) => {
+			await session.prompt(input);
+		},
+		agent: {
+			abort: () => session.agent.abort(),
+			waitForIdle: () => session.agent.waitForIdle(),
+			steer: (message) => session.agent.steer(message as Parameters<typeof session.agent.steer>[0]),
+		},
+		dispose: () => session.dispose(),
+	};
+};
+
+/** Resolve a model ref (`provider/id`, or a bare id) to a registry Model. */
+function resolveModel(reg: ModelRegistry, ref: string | undefined): unknown {
+	if (!ref) return undefined;
+	const slash = ref.indexOf("/");
+	if (slash > 0) {
+		const m = reg.find(ref.slice(0, slash), ref.slice(slash + 1));
+		if (m) return m;
+	}
+	return reg.getAll().find((m) => m.id === ref);
+}
+
+// Ref-counted fork-bomb guard: PI_PERSONA_DISABLE stays "1" while ANY sub-session is being
+// built (a parallel strategy builds several at once), restored only when the LAST one finishes.
+// A per-call save/restore around the async `createSession` races: it can clear the guard
+// mid-build (fork-bomb window) or leave it stuck. Increment/decrement never cross the await.
+//
+// PI_PERSONA_LEG rides alongside it as a DEDICATED "this session is a delegated worker leg" marker.
+// PI_PERSONA_DISABLE alone is ambiguous — a user can set it as a kill switch — so a companion
+// extension (e.g. pi-persona-mind) cannot tell a real leg from a disabled supervisor by DISABLE
+// alone. LEG is set ONLY here (and in the child engine), never by a user, so it names a leg exactly.
+let disableDepth = 0;
+let savedDisable: string | undefined;
+let savedLeg: string | undefined;
+function pushDisableGuard(): void {
+	if (disableDepth === 0) {
+		savedDisable = process.env.PI_PERSONA_DISABLE;
+		savedLeg = process.env.PI_PERSONA_LEG;
+	}
+	disableDepth += 1;
+	process.env.PI_PERSONA_DISABLE = "1";
+	process.env.PI_PERSONA_LEG = "1";
+}
+function popDisableGuard(): void {
+	disableDepth -= 1;
+	if (disableDepth === 0) {
+		if (savedDisable === undefined) delete process.env.PI_PERSONA_DISABLE;
+		else process.env.PI_PERSONA_DISABLE = savedDisable;
+		if (savedLeg === undefined) delete process.env.PI_PERSONA_LEG;
+		else process.env.PI_PERSONA_LEG = savedLeg;
+	}
+}
+
+export function makeInProcessEngine(deps: InProcessDeps): StrategyEngine {
+	const createSession = deps.createSession ?? createPiSession;
+	const supervisorHandle = deps.supervisorHandle ?? "supervisor";
+	// Per-run contract pinning (I3), mirroring the child adapter.
+	const pinned = new Map<string, PinnedContract>();
+	const pinnedDef = (name: string): ContractDef | undefined => {
+		const cached = pinned.get(name);
+		if (cached) return cached.def;
+		const def = deps.contracts?.(name);
+		if (!def) return undefined;
+		const fresh = pinContract(def);
+		pinned.set(name, fresh);
+		return fresh.def;
+	};
+
+	// Peer registry — PER ENGINE INSTANCE. buildEngine makes a fresh engine per
+	// delegate/council/flow-phase/async-launch, so this map naturally scopes `contact_peer`
+	// to the members of ONE run: concurrent runs on the same bus never see each other.
+	const peerLabels = new Map<string, string>();
+
+	return {
+		async run(spec: AgentRunSpec, onProgress?, callSignal?, onSteerable?): Promise<AgentResult> {
+			const cfg = deps.resolveAgent(spec.agent);
+			if (!cfg) return unknownAgentFailure(spec.agent, deps.listAgents?.() ?? []);
+			// A requested contract is a runtime guard, not merely prompt decoration. Resolve it
+			// before model/session construction so a missing name can never run unconstrained.
+			const requestedContract = spec.outputContract?.trim();
+			const requestedDef = requestedContract ? pinnedDef(requestedContract) : undefined;
+			if (requestedContract && !requestedDef) return unknownContractFailure(spec.agent, requestedContract, deps.listContracts?.() ?? []);
+
+			const ref = spec.model ?? deps.modelFor?.(spec.agent) ?? cfg.model ?? deps.defaultModel;
+			const model = resolveModel(deps.modelRegistry, ref);
+			if (!model) {
+				const src = spec.model ? "spec" : deps.modelFor?.(spec.agent) ? "agent picker" : cfg.model ? "agent config" : "default";
+				// Make the failure self-correcting: name a few real registry refs (nearest
+				// matches first) so the supervisor's retry can pick a valid model at once.
+				const all = deps.modelRegistry.getAll().map((m) => `${m.provider}/${m.id}`);
+				const frag = (ref ?? "").split("/").pop()?.split(":")[0]?.toLowerCase() ?? "";
+				const near = frag ? all.filter((r) => r.toLowerCase().includes(frag)) : [];
+				const hint = (near.length > 0 ? near : all).slice(0, 5);
+				return {
+					agent: spec.agent,
+					output: "",
+					usage: emptyUsage(),
+					ok: false,
+					error: `[${spec.agent} · ${ref ?? "(no model)"}] model not found in registry (from ${src})${hint.length > 0 ? ` — try e.g.: ${hint.join(", ")}` : ""}`,
+						failureKind: "unknown-model",
+				};
+			}
+			// The canonical provider/id this run resolved to — surfaced on every result (for the
+			// UI/cost) and, on a provider failure, used as the seed of the fallback chain.
+			const rm = model as { provider?: string; id?: string };
+			const resolvedRef = rm.provider && rm.id ? `${rm.provider}/${rm.id}` : ref;
+			const thinkingLevel = isThinkingLevel(deps.childThinking) ? deps.childThinking : undefined;
+			const tools = spec.tools ?? cfg.tools;
+			const excludeTools = cfg.excludeTools;
+
+			// Diagnostic tag: which agent + which model ref + whether it was dynamically
+			// specialised (skills / model / tools override on the spec). Users need this
+			// to tell "the delegate typo'd the model" from "the provider rejected it".
+			const overrides: string[] = [];
+			if (spec.model) overrides.push("model");
+			if (spec.skills && spec.skills.length > 0) overrides.push("skills");
+			if (spec.tools !== undefined) overrides.push("tools");
+			const dyn = overrides.length > 0 ? ` +dyn(${overrides.join(",")})` : "";
+			const tag = `[${spec.agent} · ${ref ?? "(no model)"}${dyn}]`;
+
+			const state = createStreamState();
+			const signal = combineSignals(deps.signal, callSignal);
+
+			// Already cancelled (e.g. a queued async run stopped before its slot came up):
+			// don't build a session or burn a model call — settle as aborted right away.
+			if (signal?.aborted) {
+				return { agent: spec.agent, output: "", usage: emptyUsage(), ok: false, error: `${tag} agent aborted`, ...(resolvedRef ? { modelUsed: resolvedRef } : {}), failureKind: "abort" };
+			}
+
+			const modelRuntime = sharedModelRuntime(deps.modelRegistry);
+			const sessionOpts: CreateSessionOptions = {
+				model,
+				modelRegistry: deps.modelRegistry,
+				...(modelRuntime !== undefined ? { modelRuntime } : {}),
+				cwd: deps.cwd,
+				agentDir: deps.agentDir ?? deps.cwd,
+			};
+			if (tools !== undefined) sessionOpts.tools = tools;
+			if (excludeTools && excludeTools.length > 0) sessionOpts.excludeTools = excludeTools;
+			if (thinkingLevel) sessionOpts.thinkingLevel = thinkingLevel;
+			// The shared behavioral layer (docs/SPINE.md) + the agent's own persona + any
+			// on-the-fly `role` specialisation from the spec. All three reach the session as the
+			// loader's `appendSystemPrompt`, so a leg keeps Pi's full base prompt either way — the
+			// layer adds behavioral consistency, it does not fill a scaffolding gap.
+			const layer = cfg.spine === false ? undefined : deps.spine?.trim();
+			const personaPrompt = [layer, cfg.systemPrompt?.trim(), assignedIdentityPrompt(spec.name), spec.role?.trim()].filter(Boolean).join("\n\n");
+			if (personaPrompt) sessionOpts.systemPrompt = personaPrompt;
+
+			// Comm plane: give this child a `contact_supervisor` tool bound to a unique handle
+			// (persona coaching, §4.9), and/or a `contact_peer` tool when the STRATEGY opted the
+			// run into sibling messaging (`spec.peers`, gated by the persona's `canUseBus`).
+			let childHandle: string | undefined;
+			const wantsPeers = spec.peers === true && (deps.canUseBus ?? true) && deps.bus !== undefined;
+			if (spec.peers === true && !wantsPeers && process.env.PI_PERSONA_DEBUG) {
+				process.stderr.write(`[pi-persona] peers requested for ${spec.agent} but bus/capability unavailable — running without contact_peer\n`);
+			}
+			if (deps.bus && (deps.coaching || wantsPeers)) {
+				childHandle = nextChildHandle(spec.agent);
+				deps.bus.register(supervisorHandle);
+				deps.bus.register(childHandle);
+				const customTools: ToolDefinition[] = [];
+				if (deps.coaching) {
+					customTools.push(
+						makeContactSupervisorTool(deps.bus, childHandle, supervisorHandle, { allowBlocking: deps.allowBlocking ?? false }),
+					);
+				}
+				if (wantsPeers) {
+					const label = spec.name?.trim()
+						? sanitizeDisplayLabel(spec.name, childHandle)
+						: spec.role ? `${childHandle} (${roleHint(spec.role)})` : childHandle;
+					peerLabels.set(childHandle, label);
+					const self = childHandle;
+					customTools.push(
+						makeContactPeerTool(deps.bus, self, {
+							listPeers: () => [...peerLabels.entries()].filter(([h]) => h !== self).map(([h, l]) => ({ handle: h, label: l })),
+						}),
+					);
+				}
+				sessionOpts.customTools = customTools;
+			}
+
+			// The handle is live on the SESSION-LONG bus from here on, while the only unregister sits
+			// in the run's own finally below. Anything that throws before we reach it must release
+			// it, or a phantom peer haunts `intercom list` (collecting dead letters nothing drains)
+			// for the rest of the supervisor's session.
+			let handleReleased = false;
+			const releaseHandle = (): void => {
+				if (!childHandle || handleReleased) return;
+				handleReleased = true;
+				peerLabels.delete(childHandle);
+				deps.bus?.unregister(childHandle);
+			};
+
+			// `agent.abort()` is a cancellation REQUEST, not a settlement guarantee: a provider/tool
+			// can leave both `prompt()` and `waitForIdle()` pending after accepting it. Keep a separate
+			// gate that every abort cause trips, so the engine always reaches its finally-cleanup instead
+			// of retaining the session (and its async semaphore slot) forever. The same gate also settles
+			// an initialization that cannot be interrupted by Pi's current resource-loader API.
+			let releaseAbortGate: () => void = () => {};
+			const abortGate = new Promise<void>((resolve) => {
+				releaseAbortGate = resolve;
+			});
+			let session!: InProcSession;
+			let initializedSession: InProcSession | undefined;
+			let aborted = false;
+			let timedOut = false;
+			let hardTimedOut = false;
+			let startupTimedOut = false;
+			let cancellationRequested = false;
+			const initController = new AbortController();
+			const abortSession = (): void => {
+				const target = initializedSession;
+				try {
+					target?.agent.abort();
+				} catch {
+					// Settlement and dispose must still run when the host abort hook itself throws.
+				} finally {
+					releaseAbortGate();
+				}
+			};
+			const requestCancellation = (kind: "abort" | "idle" | "startup" | "hard"): void => {
+				// Host abort hooks can synchronously emit more events or cancellation signals.
+				// Preserve the first cause and invoke the host abort hook only once.
+				if (cancellationRequested) return;
+				cancellationRequested = true;
+				if (kind === "abort") aborted = true;
+				else if (kind === "idle") timedOut = true;
+				else if (kind === "hard") hardTimedOut = true;
+				else startupTimedOut = true;
+				if (!initController.signal.aborted) initController.abort();
+				abortSession();
+			};
+
+			// Idle watchdog (mirrors the child engine's idle kill): a session that emits no
+			// events for `timeoutMs` is hung (e.g. a stuck provider stream) — without this the
+			// DEFAULT engine would await `waitForIdle()` forever and the run would never settle.
+			// Any event re-arms the clock, so a long-but-active agent is never killed. Stays armed
+			// for every child, coaching or not: when it fires, the bus is consulted first (R9) —
+			// a live pending ask from THIS child re-arms the window instead of killing.
+			const specTimeoutMs = isPositiveFiniteMs(spec.timeoutMs) ? spec.timeoutMs : undefined;
+			const watchdogMs = specTimeoutMs ?? (isPositiveFiniteMs(deps.timeoutMs) ? deps.timeoutMs : 0);
+			let idleTimer: ReturnType<typeof setTimeout> | undefined;
+			const disarmIdle = (): void => {
+				if (idleTimer) {
+					clearTimeout(idleTimer);
+					idleTimer = undefined;
+				}
+			};
+			const armIdle = (): void => {
+				disarmIdle();
+				if (watchdogMs <= 0 || cancellationRequested) return;
+				idleTimer = setTimeout(() => {
+					if (childHandle && deps.bus?.hasPendingAskFrom(childHandle)) {
+						armIdle();
+						return;
+					}
+					requestCancellation("idle");
+				}, watchdogMs);
+				idleTimer.unref?.();
+			};
+
+			// Hard wall-clock cap: armed ONCE, never reset by events — a definite lifetime ceiling
+			// that settles a busy-but-non-converging child (the idle watchdog above never catches).
+			// It starts before session construction, matching the child engine's process lifetime cap.
+			// Applies unconditionally — including to a coaching child legitimately blocked on a reply.
+			const hardMs = isPositiveFiniteMs(deps.hardTimeoutMs) ? deps.hardTimeoutMs : 0;
+			let hardTimer: ReturnType<typeof setTimeout> | undefined;
+			const armHard = (): void => {
+				if (hardMs <= 0 || hardTimer) return;
+				hardTimer = setTimeout(() => requestCancellation("hard"), hardMs);
+				hardTimer.unref?.();
+			};
+			const disarmHard = (): void => {
+				if (hardTimer) {
+					clearTimeout(hardTimer);
+					hardTimer = undefined;
+				}
+			};
+
+			// Startup deadline (mirrors the child engine): one window from construction to the first
+			// real progress (completed turn / tokens / streamed output). Stays armed for every child,
+			// including one that may block on a supervisor reply before ever emitting anything — the
+			// bus consult below re-arms it for as long as that ask is genuinely pending (R9). During
+			// construction there is no session yet, so no ask can possibly be pending: the window
+			// behaves exactly as it always has while initializing.
+			const startupMs = isPositiveFiniteMs(deps.startupTimeoutMs) ? deps.startupTimeoutMs : 0;
+			let startupProgressed = false;
+			let startupTimer: ReturnType<typeof setTimeout> | undefined;
+			const disarmStartup = (): void => {
+				if (startupTimer) {
+					clearTimeout(startupTimer);
+					startupTimer = undefined;
+				}
+			};
+			const armStartup = (): void => {
+				disarmStartup();
+				if (startupMs <= 0) return;
+				startupTimer = setTimeout(() => {
+					if (startupProgressed) return;
+					if (childHandle && deps.bus?.hasPendingAskFrom(childHandle)) {
+						armStartup();
+						return;
+					}
+					requestCancellation("startup");
+				}, startupMs);
+				startupTimer.unref?.();
+			};
+			const noteStartupProgress = (): void => {
+				if (startupProgressed) return;
+				const s = snapshot(state);
+				if (s.turns > 0 || s.tokens > 0 || s.output.length > 0) {
+					startupProgressed = true;
+					disarmStartup();
+				}
+			};
+
+			// The Pi resource loader currently has no cancellation API. `armIdle`/`armHard`/`armStartup`
+			// (below) already start before the factory is invoked and stay held until the factory
+			// promise itself settles, so a timed-out run may return to its semaphore caller while a
+			// late session is disposed and a late rejection is consumed by this handled promise.
+			const onAbort = (): void => requestCancellation("abort");
+			if (signal) {
+				if (signal.aborted) requestCancellation("abort");
+				else signal.addEventListener("abort", onAbort, { once: true });
+			}
+			if (cancellationRequested) {
+				if (signal) signal.removeEventListener("abort", onAbort);
+				releaseHandle();
+				return {
+					agent: spec.agent,
+					output: "",
+					usage: emptyUsage(),
+					ok: false,
+					error: `${tag} agent aborted`,
+					...(resolvedRef ? { modelUsed: resolvedRef } : {}),
+					failureKind: "abort",
+				};
+			}
+
+			const safeDispose = (late: InProcSession): void => {
+				try {
+					late.dispose();
+				} catch {
+					// A late session has no consumer left to report disposal errors to; never turn
+					// cleanup into an unhandled rejection or strand the global guard.
+				}
+			};
+			type InitializationOutcome = { session?: InProcSession; error?: unknown };
+			let initializationSettled = false;
+
+			pushDisableGuard();
+			armHard();
+			armIdle();
+			armStartup();
+			const initialization = Promise.resolve()
+				.then(() => createSession({ ...sessionOpts, signal: initController.signal }))
+				.then(
+					(created) => {
+						if (cancellationRequested) {
+							safeDispose(created);
+							return {};
+						}
+						initializedSession = created;
+						return { session: created };
+					},
+					(error): InitializationOutcome => ({ error }),
+				)
+				.then((outcome) => {
+					initializationSettled = true;
+					// Do not pop this guard at the timeout boundary: the original factory may still
+					// be loading recursive extensions under PI_PERSONA_DISABLE=1.
+					popDisableGuard();
+					return outcome;
+				});
+
+			const initializationOutcome = await Promise.race([
+				initialization,
+				abortGate.then(() => undefined as InitializationOutcome | undefined),
+			]);
+			if (cancellationRequested || !initializationOutcome || !initializationOutcome.session) {
+				if (cancellationRequested && initializedSession) {
+					const cancelledSession = initializedSession;
+					initializedSession = undefined;
+					safeDispose(cancelledSession);
+				}
+				if (signal) signal.removeEventListener("abort", onAbort);
+				disarmIdle();
+				disarmHard();
+				disarmStartup();
+				releaseHandle();
+				if (initializationOutcome && "error" in initializationOutcome && !cancellationRequested) throw initializationOutcome.error;
+				const initError = hardTimedOut
+					? `${tag} agent exceeded the ${hardMs}ms hard cap during session initialization`
+					: timedOut
+						? `${tag} agent timed out during session initialization — no events for ${watchdogMs}ms`
+					: startupTimedOut
+						? `${tag} agent produced no output within the ${startupMs}ms startup window while initializing the session`
+						: `${tag} agent aborted`;
+				const cleanupHint = initializationSettled ? "" : "; initialization cancellation requested, but the host loader may still be unwinding. If initialization keeps hanging, restart Pi and use PI_PERSONA_ENGINE=child";
+				return {
+					agent: spec.agent,
+					output: "",
+					usage: emptyUsage(),
+					ok: false,
+					error: `${initError}${cleanupHint}`,
+					...(resolvedRef ? { modelUsed: resolvedRef } : {}),
+					failureKind: hardTimedOut || timedOut || startupTimedOut ? "timeout" : "abort",
+				};
+			}
+			session = initializationOutcome.session;
+
+			// From here to the run's own try/finally the child is live but its cleanup is not
+			// armed yet: the subscription, the caller-supplied `onSteerable`, and the delivery
+			// bridge's initial flush all run outside it. A throw in any of them must release the
+			// handle AND the session, never leave a phantom peer plus an orphaned live session.
+			let unsub: (() => void) | undefined;
+			let unsubBridge: (() => void) | undefined;
+			let steerable = true;
+			// Calls whose start crossed the progress seam but whose end has not. The tool NAME rides
+			// beside the id because the synthetic close below has to carry it, and stream.ts tracks
+			// only the ids. Mirrors the child engine's `openToolCalls`.
+			const openToolCalls = new Map<string, string>();
+			// One progress tick, routed exactly as the subscription routes them: the per-call sink
+			// takes the AgentProgress shape (no `turns`), else the construction-time sink.
+			const emitProgress = (snap: ProgressSnapshot): void => {
+				if (onProgress) onProgress({ output: snap.output, tokens: snap.tokens, ...(snap.activity ? { activity: snap.activity } : {}), ...(snap.toolEvent ? { toolEvent: snap.toolEvent } : {}) });
+				else if (deps.onProgress) deps.onProgress(snap);
+			};
+			let contractDef: ContractDef | undefined = requestedDef;
+			let task: string;
+			try {
+				unsub = session.subscribe((ev) => {
+					armIdle(); // any event = activity → reset the idle clock
+					const toolEvent = applyEvent(state, ev);
+					// Track the open calls so an abandoned one can be closed once the run settles.
+					if (toolEvent) {
+						if (toolEvent.phase === "start") openToolCalls.set(toolEvent.callId, toolEvent.name);
+						else openToolCalls.delete(toolEvent.callId);
+					}
+					noteStartupProgress(); // first real progress cancels the startup deadline
+					emitProgress(snapshot(state, toolEvent));
+				});
+
+				// Steering: the in-process engine can inject a user message into the running
+				// agent — the v0.4 payoff the one-shot child engine can't do.
+				onSteerable?.((text) => {
+					if (!steerable) return false;
+					const trimmed = text.trim();
+					if (!trimmed) return false;
+					try {
+						session.agent.steer({ role: "user", content: [{ type: "text", text: trimmed }] });
+						return true;
+					} catch {
+						return false;
+					}
+				});
+
+				// Delivery bridge: bus messages addressed to this child are steered into its live
+				// session as fenced, attributed user turns — attribution stays OUTSIDE the fence so
+				// a malicious payload cannot spoof its sender. Serves sibling `contact_peer` sends
+				// AND the supervisor's `intercom send` (previously a dead letter: nothing ever
+				// drained a child inbox). Flush once on subscribe to catch a message that raced
+				// registration (the handle registers before the session finishes building).
+				if (childHandle && deps.bus) {
+					const b = deps.bus;
+					const self = childHandle;
+					const deliver = (): void => {
+						for (const env of b.takeWhere(self, (e) => !e.expectsReply)) {
+							const from = env.from === supervisorHandle ? "your supervisor" : `peer ${peerLabels.get(env.from) ?? env.from}`;
+							// deliver() runs on the initial flush (BEFORE the run's try/finally below) and
+							// inside the bus.onMessage listener (a SENDER's bus.send call stack) — an
+							// uncaught steer() throw here would leak the bus registration/observer, skip
+							// engine.run cleanup, or propagate into the sender's contact_peer call. Drop the
+							// envelope instead; it is lost, not redelivered (mirrors "gone" semantics).
+							try {
+								session.agent.steer({ role: "user", content: [{ type: "text", text: attributeInbound(from, env.text) }] });
+							} catch (e) {
+								if (process.env.PI_PERSONA_DEBUG) {
+									process.stderr.write(`[pi-persona] delivery bridge steer failed for ${self} (envelope from ${env.from} dropped): ${e instanceof Error ? e.message : String(e)}\n`);
+								}
+								continue;
+							}
+							// Transparency tick: surface the delivery on the run's progress line (agent tree).
+							// Mirrors the main subscription's fallback (line ~332): per-call onProgress wins
+							// (AgentProgress — no `turns`), else the construction-time deps.onProgress
+							// (ProgressSnapshot — built from snapshot(state), `turns` included) — the async
+							// launch path (extension.ts) only has the latter.
+							const snap = snapshot(state);
+							const activity = `✉ from ${env.from}`;
+							if (onProgress) onProgress({ output: snap.output, tokens: snap.tokens, activity });
+							else if (deps.onProgress) deps.onProgress({ ...snap, activity });
+						}
+					};
+					unsubBridge = b.onMessage((env) => {
+						if (env.to === self && !env.expectsReply) deliver();
+					});
+					deliver();
+				}
+
+				// The agent's persona is now the session's appended system prompt (see the
+				// resource loader); the user turn carries just the task (+ any skills to load,
+				// + the output-contract format when one is requested — resolved and pinned HERE
+				// so the def that instructs the member is the def that validates it below).
+				const skillsPreamble =
+					spec.skills && spec.skills.length > 0
+						? `Load these skills before starting (use the nearest affine if one is missing): ${spec.skills.join(", ")}.\n\n`
+						: "";
+				const contractTail = contractDef ? `\n\n${contractInstructions(contractDef)}` : "";
+				task = `${skillsPreamble}Task: ${spec.task}${contractTail}`;
+			} catch (e) {
+				disarmIdle();
+				disarmHard();
+				disarmStartup();
+				if (signal) signal.removeEventListener("abort", onAbort);
+				unsubBridge?.();
+				unsub?.();
+				releaseHandle();
+				steerable = false;
+				session.dispose();
+				throw e;
+			}
+
+			// Capture a thrown error (e.g. provider API 400 before any stream event fires,
+			// like model_not_supported) so it survives the finally-cleanup and can be
+			// folded into the AgentResult below. Otherwise the stream state stays empty
+			// and the user sees an opaque "agent failed (unknown)".
+			let thrownError: string | undefined;
+			try {
+				armIdle(); // start the idle clock (reset on every session event)
+				armHard(); // start the lifetime ceiling (never reset)
+				const runToIdle = async (): Promise<void> => {
+					await session.prompt(task);
+					// An abort may have won while prompt() was resolving. Do not start another host wait
+					// after that point; the outer race is already taking us through cleanup.
+					if (!aborted && !timedOut && !hardTimedOut && !startupTimedOut) await session.agent.waitForIdle();
+				};
+				if (aborted || timedOut || hardTimedOut || startupTimedOut) await abortGate;
+				else await Promise.race([runToIdle(), abortGate]);
+			} catch (e) {
+				thrownError = e instanceof Error ? e.message : String(e);
+			} finally {
+				disarmIdle();
+				disarmHard();
+				disarmStartup();
+				if (signal) signal.removeEventListener("abort", onAbort);
+				unsubBridge?.();
+				releaseHandle();
+				unsub?.();
+				steerable = false;
+				session.dispose();
+			}
+
+			const ok =
+				!aborted && !timedOut && !hardTimedOut && !startupTimedOut && !thrownError && state.stopReason !== "error" && state.stopReason !== "aborted";
+			// A session torn down mid-flight (abort, timeout, provider throw) never delivers the
+			// tool_execution_end for whatever it was running: pi emits that end only once the tool has
+			// unwound (a macrotask or more later, e.g. bash killing its tree then awaiting close), by which
+			// time the teardown above has dropped the listener. Close each abandoned call here, as the child
+			// engine's finish() does — otherwise the consumer shows that tool "running" forever and its
+			// telemetry record stays pinned. Two rules keep the synthesis honest:
+			//  * a run that SETTLED NORMALLY is left alone. pi notifies subscribers behind the agent
+			//    (_handleAgentEvent awaits the extension runner before it fans out), so a green run's last
+			//    end can land after waitForIdle() resolved — closing it `failed` would report a tool that
+			//    actually completed as failed. Leaving it open is the older, honest gap.
+			//  * it runs AFTER the teardown and each tick is guarded, because emitProgress calls consumer
+			//    code: inside the finally an onProgress throw skipped the handle release, the unsubscribes
+			//    and dispose(). Dropping the tick mirrors deliver()'s contract for a throwing steer().
+			if (!ok) {
+				for (const [callId, name] of openToolCalls) {
+					try {
+						emitProgress(snapshot(state, { phase: "end", callId, name, failed: true }));
+					} catch {
+						/* the consumer's sink threw; the tick is lost, the run still settles */
+					}
+				}
+			}
+
+			const result: AgentResult = { agent: spec.agent, output: state.output, usage: state.usage, ok, ...(resolvedRef ? { modelUsed: resolvedRef } : {}) };
+			// A timeout/abort is the *cause of death* — label it first (mirrors the child engine).
+			if (timedOut) result.error = `${tag} agent timed out — no events for ${watchdogMs}ms${state.errorMessage ? ` (last error: ${state.errorMessage})` : ""}`;
+			// The deadline cannot tell the two causes apart, so the message names both: claiming
+			// "it never started" would misdirect the operator of a leg that did start and was
+			// simply waiting on a slow first response (mirrors the child engine's wording).
+			else if (startupTimedOut)
+				result.error = `${tag} agent produced no output within the ${startupMs}ms startup window — either it never started (a stalled init) or its first provider response was slower than the window (a queued or rate-limited provider, a cold local model); raise or disable the window with PI_PERSONA_AGENT_STARTUP_MS (0 disables)${state.errorMessage ? ` (last error: ${state.errorMessage})` : ""}`;
+			else if (hardTimedOut) result.error = `${tag} agent exceeded the ${hardMs}ms hard cap${state.errorMessage ? ` (last error: ${state.errorMessage})` : ""}`;
+			else if (aborted) result.error = `${tag} agent aborted`;
+			else if (state.errorMessage) result.error = `${tag} ${state.errorMessage}`;
+			else if (thrownError) result.error = `${tag} ${thrownError}`;
+			else if (!ok) result.error = `${tag} agent failed (${state.stopReason ?? "unknown"})`;
+			// Classify the failure so the fallback decorator can reroute ONLY provider errors,
+			// never an abort/timeout/hard-cap/agent miss. A stream `error` stop reason is pi's
+			// own report of an API failure → provider. A THROWN error is not automatically a
+			// provider fault (bugs and tool failures throw too) — classify by its text.
+			if (!ok)
+				result.failureKind =
+					timedOut || hardTimedOut || startupTimedOut
+						? "timeout"
+						: aborted
+							? "abort"
+							: state.stopReason === "error" || (thrownError !== undefined && looksLikeProviderError(thrownError))
+								? "provider"
+								: "agent";
+
+			if (contractDef) {
+				const v = parseAndValidate(state.output, contractDef);
+				if (v.value) result.structured = v.value;
+				if (!v.ok) {
+					result.ok = false;
+					// The cause of death (timeout/abort/provider) wins over the contract miss —
+					// naming "not valid JSON" over an empty output hides the real failure.
+					if (v.error && result.error === undefined) result.error = v.error;
+					if (result.failureKind === undefined) result.failureKind = "contract";
+				}
+			}
+			return result;
+		},
+	};
+}