@selesai/code 0.13.15 → 0.13.18

package/dist/extensions/pi-subagents/src/runs/background/run-status.ts

@@ -2,12 +2,14 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import { safeTerminalText } from "../../shared/display-text.ts";
+import { getArtifactPaths, getArtifactsDir } from "../../shared/artifacts.ts";
+import { readFleetTranscript } from "../../tui/fleet-transcript.ts";
 import { formatAsyncRunList, formatAsyncRunOutputPath, formatAsyncRunProgressLabel, formatWorkflowStageLine, listAsyncRuns } from "./async-status.ts";
 import { formatAsyncResultTranscript, formatAsyncRunTranscript, formatNestedRunTranscript, inspectSubagentFleet } from "./fleet-view.ts";
 import { formatNestedRunStatusLines } from "../shared/nested-render.ts";
 import { formatModelThinking } from "../../shared/formatters.ts";
 import { formatActivityLabel } from "../../shared/status-format.ts";
-import { DIRS, type AsyncStatus, type Details, type ForegroundResumeRun, type NestedRunSummary, type SteeringStatus, type SubagentState } from "../../shared/types.ts";
+import { DIRS, type AsyncStatus, type Details, type ForegroundRunControl, type ForegroundResumeRun, type NestedRunSummary, type SteeringStatus, type SubagentState } from "../../shared/types.ts";
 import { inspectActiveAsyncCapacityOwner, type ActiveAsyncCapacityInspection } from "./active-async-capacity.ts";
 import { readStatus } from "../../shared/utils.ts";
 import { resolveSubagentIntercomTarget } from "../../intercom/intercom-bridge.ts";
@@ -88,6 +90,7 @@ function formatRunLifecycleDebug(input: { status: AsyncStatus; asyncDir: string;
 		`Run: ${status.runId}`,
 		`Dir: ${asyncDir}`,
 		`Status file: ${path.join(asyncDir, "status.json")}`,
+		status.workflowReceiptPath ? `Workflow receipt: ${status.workflowReceiptPath}` : undefined,
 		`Process terminal file: ${path.join(asyncDir, "process-terminal.json")}`,
 		`Session: ${status.sessionId ?? "unknown"}`,
 		`State: ${status.state}`,
@@ -241,6 +244,54 @@ function formatRememberedForegroundStatus(run: ForegroundResumeRun): string {
 	return lines.join("\n");
 }
 
+/** Request-only snapshot of the same artifact used by Fleet; no session or output fallback. */
+function formatLiveForegroundTranscript(control: ForegroundRunControl, state: SubagentState, options: { index?: number; lines?: number }): string {
+	if (!state.currentSessionId || control.sessionId !== state.currentSessionId) {
+		throw new Error(`Foreground run '${control.runId}' is not owned by the current session.`);
+	}
+	if (options.index !== undefined && (!Number.isInteger(options.index) || options.index < 0)) {
+		throw new Error("Transcript index must be a non-negative integer.");
+	}
+	const children = control.activeChildren
+		? [...control.activeChildren.values()]
+		: control.currentAgent ? [{ index: control.currentIndex ?? 0, agent: control.currentAgent, sessionName: control.sessionName }] : [];
+	const header = [`Run: ${control.runId}`, "State: live foreground"];
+	if (children.length === 0) return `${header.map((line) => safeTerminalText(line)).join("\n")}\nTranscript unavailable: no active foreground child.`;
+	if (options.index === undefined && children.length > 1) {
+		throw new Error(`Transcript view requires index for foreground run '${control.runId}'. Active child indexes: ${children.map((child) => child.index).join(", ")}.`);
+	}
+	const child = options.index === undefined ? children[0]! : children.find((child) => child.index === options.index);
+	if (!child) throw new Error(`Transcript index ${options.index} is not an active foreground child of '${control.runId}'.`);
+	const root = getArtifactsDir(state.parentSessionFile ?? null, control.cwd ?? state.baseCwd, state.artifactDirPreference);
+	const transcriptPath = getArtifactPaths(root, control.runId, child.agent, child.index).transcriptPath;
+	const transcript = readFleetTranscript(transcriptPath, { trustedRoots: [root] });
+	const lineLimit = Number.isFinite(options.lines) ? Math.max(1, Math.min(500, Math.trunc(options.lines!))) : 80;
+	const allLines = transcript.events.flatMap((event) => {
+		const text = event.kind === "tool"
+			? [`Tool: ${event.name} (${event.status})`, event.argsPayload ?? event.args, event.output ?? event.error].filter(Boolean).join("\n")
+			: event.kind === "notice" ? event.text : `${event.kind === "assistant" ? "Assistant" : "Supervisor"}: ${event.text}`;
+		return text.split(/\r?\n/);
+	});
+	let body = allLines.slice(-lineLimit).join("\n");
+	let truncated = transcript.truncated || allLines.length > lineLimit
+		|| transcript.events.some((event) => event.kind === "tool" && event.outputTruncated)
+		|| body.includes("… message truncated");
+	const maxOutputBytes = 32 * 1024;
+	const bytes = Buffer.from(body);
+	if (bytes.length > maxOutputBytes) {
+		// Skip UTF-8 continuation bytes at the beginning of the bounded tail.
+		let start = bytes.length - maxOutputBytes;
+		while ((bytes[start]! & 0xc0) === 0x80) start++;
+		body = bytes.subarray(start).toString("utf-8");
+		truncated = true;
+	}
+	header.push(`Child: ${child.index} (${child.sessionName?.trim() || child.agent})`, `Transcript: ${transcriptPath}`);
+	if (transcript.warning) header.push(`Transcript warning: ${transcript.warning}`);
+	header.push(`Live transcript tail${truncated ? " (tail truncated)" : ""}:`);
+	if (!body) header.push("Transcript unavailable: no readable activity in the bounded artifact tail yet.");
+	return [...header.map((line) => safeTerminalText(line)), body].filter(Boolean).join("\n");
+}
+
 function formatRememberedForegroundTranscript(run: ForegroundResumeRun, options: { index?: number; lines?: number }): string {
 	let index = options.index;
 	if (index !== undefined && !Number.isInteger(index)) throw new Error("Transcript index must be an integer.");
@@ -313,6 +364,12 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 		return inspectSubagentFleet(params, { asyncDirRoot, resultsDir, kill: deps.kill, now: deps.now, state: deps.state, childSafe: Boolean(deps.nested) });
 	}
 	if (!params.id && !params.runId && !params.dir) {
+		if (params.view === "transcript" && deps.state?.currentSessionId) {
+			const controls = [...deps.state.foregroundControls.values()].filter((control) => control.sessionId === currentSessionId);
+			const foreground = controls.find((control) => control.runId === deps.state?.lastForegroundControlId)
+				?? controls.sort((left, right) => right.updatedAt - left.updatedAt)[0];
+			if (foreground) return inspectSubagentStatus({ ...params, id: foreground.runId }, deps);
+		}
 		if (deps.nested) {
 			return {
 				content: [{ type: "text", text: "Child-safe subagent status requires an id when no foreground run is active." }],
@@ -353,6 +410,13 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 		} else if (!params.dir && requestedId) {
 			const resolved = resolveSubagentRunId(requestedId, { asyncDirRoot, resultsDir, state: deps.state, nested: deps.nested });
 			if (resolved?.kind === "foreground") {
+				const control = deps.state?.foregroundControls.get(resolved.id);
+				if (control && deps.state && params.view === "transcript") {
+					return {
+						content: [{ type: "text", text: formatLiveForegroundTranscript(control, deps.state, params) }],
+						details: { mode: "management", results: [] },
+					};
+				}
 				const run = deps.state?.foregroundRuns?.get(resolved.id);
 				if (run) {
 					try {
@@ -423,7 +487,7 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 				const capacity = inspectActiveAsyncCapacityOwner({ runId: diskStatus.runId, sessionId: diskStatus.sessionId, asyncDir }, { rootDir: deps.activeCapacityRoot, liveWorkflowRunIds: new Set(deps.state?.workflowControllers?.keys() ?? []), abandonedSlotReleaseAfterMs: deps.abandonedSlotReleaseAfterMs });
 				return {
 					content: [{ type: "text", text: formatRunLifecycleDebug({ status: diskStatus, asyncDir, sidecarProcessTerminal: sidecar, overlayProcessTerminal: overlay, capacity }) }],
-					details: { mode: "single", results: [], ...((sidecar ?? overlay) ? { lifecycleStatus: { processTerminal: sidecar ?? overlay } } : {}) },
+					details: { mode: "single", results: [], ...(diskStatus.workflowReceiptPath ? { workflowReceiptPath: diskStatus.workflowReceiptPath } : {}), ...((sidecar ?? overlay) ? { lifecycleStatus: { processTerminal: sidecar ?? overlay } } : {}) },
 				};
 			}
 			if (params.view === "transcript") {
@@ -450,7 +514,7 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 				const capacity = inspectActiveAsyncCapacityOwner({ runId: status.runId, sessionId: status.sessionId, asyncDir }, { rootDir: deps.activeCapacityRoot, liveWorkflowRunIds: new Set(deps.state?.workflowControllers?.keys() ?? []), abandonedSlotReleaseAfterMs: deps.abandonedSlotReleaseAfterMs });
 				return {
 					content: [{ type: "text", text: formatRunLifecycleDebug({ status, asyncDir, sidecarProcessTerminal: sidecar, overlayProcessTerminal: overlay, capacity }) }],
-					details: { mode: "single", results: [], ...((sidecar ?? overlay) ? { lifecycleStatus: { processTerminal: sidecar ?? overlay } } : {}) },
+					details: { mode: "single", results: [], ...(status.workflowReceiptPath ? { workflowReceiptPath: status.workflowReceiptPath } : {}), ...((sidecar ?? overlay) ? { lifecycleStatus: { processTerminal: sidecar ?? overlay } } : {}) },
 				};
 			}
 			if (params.view === "transcript") {
@@ -545,7 +609,6 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 			const liveWorkflowControls = status.mode === "workflow" && deps.state?.currentSessionId === status.sessionId && deps.state?.workflowControllers?.has(status.runId)
 				? [...(deps.state?.foregroundControls.values() ?? [])].filter((control) => control.parentWorkflowRunId === status.runId
 					&& control.sessionId === status.sessionId
-					&& Boolean(control.workflowSteeringDir && fs.existsSync(control.workflowSteeringDir))
 					&& (control.activeChildren?.size ?? 0) > 0)
 				: [];
 			let hasExternalJobFollowUpHint = false;
@@ -627,6 +690,7 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 				}
 			}
 			if (nestedWarning) lines.push(`Warning: ${nestedWarning}`);
+			if (status.workflowReceiptPath) lines.push(`Workflow receipt: ${status.workflowReceiptPath}`);
 			if (status.sessionFile) lines.push(`Session: ${status.sessionFile}`);
 			const allExternal = (status.steps?.length ?? 0) > 0 && status.steps!.every((step) => step.runner?.type === "external-cli" || step.runner?.type === "external-job");
 			if (status.state === "running" && !allExternal && status.mode !== "workflow") lines.push(`Steer running child: subagent({ action: "steer", id: "${status.runId}", message: "..." })`);
@@ -640,7 +704,7 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 
 			const workflowChildren = parseWorkflowChildSummary(status.workflowChildren);
 			if (workflowChildren && workflowChildren.workflowRunId !== status.runId) throw new Error("workflowChildren.workflowRunId does not match async status runId.");
-			return { content: [{ type: "text", text: lines.join("\n") }], details: { mode: "single", results: [], ...(status.preflight ? { preflight: status.preflight } : {}), ...(status.workflow?.preflightWarnings?.length ? { preflightWarnings: status.workflow.preflightWarnings } : {}), ...(workflowChildren ? { workflowChildren } : {}), ...(runFanoutBudget ? { runFanoutBudget } : {}), ...(processTerminal ? { lifecycleStatus: { processTerminal } } : {}) } };
+			return { content: [{ type: "text", text: lines.join("\n") }], details: { mode: "single", results: [], ...(status.workflowReceiptPath ? { workflowReceiptPath: status.workflowReceiptPath } : {}), ...(status.preflight ? { preflight: status.preflight } : {}), ...(status.workflow?.preflightWarnings?.length ? { preflightWarnings: status.workflow.preflightWarnings } : {}), ...(workflowChildren ? { workflowChildren } : {}), ...(runFanoutBudget ? { runFanoutBudget } : {}), ...(processTerminal ? { lifecycleStatus: { processTerminal } } : {}) } };
 		}
 	}
 
@@ -681,6 +745,11 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 			const runId = data.runId ?? data.id ?? resolvedId;
 			const lines = [`Run: ${runId}`, data.toolCallId ? `Tool call: ${data.toolCallId}` : undefined, `State: ${status}`, `Result: ${resultPath}`].filter((line): line is string => Boolean(line));
 			if (data.parallelHandoff?.path) lines.push(`Parallel handoff: ${data.parallelHandoff.path}`);
+			const receipt = (data as Record<string, unknown>).workflowReceipt;
+			const receiptPath = receipt && typeof receipt === "object" && !Array.isArray(receipt)
+				? (receipt as Record<string, unknown>).path : undefined;
+			const workflowReceiptPath = typeof receiptPath === "string" && receiptPath ? receiptPath : undefined;
+			if (workflowReceiptPath) lines.push(`Workflow receipt: ${workflowReceiptPath}`);
 			const children = Array.isArray(data.results) ? data.results : data.agent ? [{ agent: data.agent, sessionFile: data.sessionFile }] : [];
 			lines.push(...formatTimeoutRecoveryLines(data.timeoutRecovery, "  "));
 			for (const [index, child] of children.entries()) {
@@ -695,7 +764,7 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 			if (data.summary) lines.push("", data.summary);
 			const workflowChildren = parseWorkflowChildSummary((data as unknown as Record<string, unknown>).workflowChildren);
 			if (workflowChildren && workflowChildren.workflowRunId !== runId) throw new Error("workflowChildren.workflowRunId does not match the result run id.");
-			return { content: [{ type: "text", text: lines.join("\n") }], details: { mode: "single", results: [], ...(workflowChildren ? { workflowChildren } : {}) } };
+			return { content: [{ type: "text", text: lines.join("\n") }], details: { mode: "single", results: [], ...(workflowReceiptPath ? { workflowReceiptPath } : {}), ...(workflowChildren ? { workflowChildren } : {}) } };
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);
 			return {

package/dist/extensions/pi-subagents/src/runs/background/runner-aliases.ts

@@ -0,0 +1,163 @@
+/**
+ * Module aliases for the detached async runner.
+ *
+ * The runner is a plain Node process started through jiti. The child hooks it
+ * loads import pi's host packages (`@selesai/code`,
+ * `pi-agent-core`, `pi-ai`, `pi-tui`, `typebox`), which are peer packages of
+ * this extension and are not installed next to it. pi's own extension loader
+ * aliases those specifiers to the copies shipped inside the installed pi
+ * package; the parent computes the same map and hands it to the runner
+ * through `JITI_ALIAS`, so child sessions and hooks retain host API identity.
+ * Only Pi 0.85.0's missing server exports may come from this extension.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const JITI_ALIAS_ENV = "JITI_ALIAS";
+
+/** Specifiers the runner's import graph may use, with the package and export subpath each resolves to. */
+export const HOST_PEER_ALIASES: ReadonlyArray<{ specifier: string; pkg: string; subpath: string }> = [
+	{ specifier: "@selesai/code", pkg: "@selesai/code", subpath: "." },
+	{ specifier: "@earendil-works/pi-agent-core", pkg: "@earendil-works/pi-agent-core", subpath: "." },
+	{ specifier: "@earendil-works/pi-agent-core/node", pkg: "@earendil-works/pi-agent-core", subpath: "./node" },
+	{ specifier: "@earendil-works/chord", pkg: "@earendil-works/chord", subpath: "." },
+	{ specifier: "@earendil-works/chord/context", pkg: "@earendil-works/chord", subpath: "./context" },
+	{ specifier: "@earendil-works/pi-tui", pkg: "@earendil-works/pi-tui", subpath: "." },
+	{ specifier: "@earendil-works/pi-ai", pkg: "@earendil-works/pi-ai", subpath: "./compat" },
+	{ specifier: "@earendil-works/pi-ai/compat", pkg: "@earendil-works/pi-ai", subpath: "./compat" },
+	{ specifier: "@earendil-works/pi-ai/oauth", pkg: "@earendil-works/pi-ai", subpath: "./oauth" },
+	{ specifier: "@earendil-works/pi-ai/providers/all", pkg: "@earendil-works/pi-ai", subpath: "./providers/all" },
+	{ specifier: "typebox", pkg: "typebox", subpath: "." },
+	{ specifier: "typebox/compile", pkg: "typebox", subpath: "./compile" },
+	{ specifier: "typebox/value", pkg: "typebox", subpath: "./value" },
+];
+
+/** Experimental dependencies accidentally published in exactly Pi 0.85.0. */
+const PI0850_PEER_ALIASES = [
+	{ specifier: "@earendil-works/pi-server", pkg: "@earendil-works/pi-server", subpath: "." },
+	{ specifier: "@earendil-works/pi-server/unix", pkg: "@earendil-works/pi-server", subpath: "./unix" },
+	{ specifier: "@earendil-works/pi-client/unix", pkg: "@earendil-works/pi-client", subpath: "./unix" },
+];
+
+interface PackageManifest {
+	name?: unknown;
+	version?: unknown;
+	main?: unknown;
+	exports?: unknown;
+}
+
+function readManifest(packageDir: string): PackageManifest | undefined {
+	try {
+		return JSON.parse(fs.readFileSync(path.join(packageDir, "package.json"), "utf-8")) as PackageManifest;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Pick the import target of one exports entry (string, conditions object, or array of those). */
+function exportTarget(entry: unknown): string | undefined {
+	if (typeof entry === "string") return entry;
+	if (Array.isArray(entry)) {
+		for (const candidate of entry) {
+			const target = exportTarget(candidate);
+			if (target) return target;
+		}
+		return undefined;
+	}
+	if (entry && typeof entry === "object") {
+		const conditions = entry as Record<string, unknown>;
+		for (const condition of ["import", "node", "default"]) {
+			if (condition in conditions) {
+				const target = exportTarget(conditions[condition]);
+				if (target) return target;
+			}
+		}
+	}
+	return undefined;
+}
+
+/** Resolve `subpath` of the package at `packageDir` through its `exports` map (with `*` patterns) or `main`. */
+export function resolvePackageSubpath(packageDir: string, subpath: string): string | undefined {
+	const manifest = readManifest(packageDir);
+	if (!manifest) return undefined;
+	const exportsField = manifest.exports;
+	if (exportsField !== undefined) {
+		const map: Record<string, unknown> = typeof exportsField === "string" || Array.isArray(exportsField) || (exportsField && typeof exportsField === "object" && !Object.keys(exportsField as object).some((key) => key.startsWith(".")))
+			? { ".": exportsField }
+			: exportsField as Record<string, unknown>;
+		const exact = exportTarget(map[subpath]);
+		if (exact) return path.resolve(packageDir, exact);
+		for (const [pattern, entry] of Object.entries(map)) {
+			const star = pattern.indexOf("*");
+			if (star === -1) continue;
+			const prefix = pattern.slice(0, star);
+			const suffix = pattern.slice(star + 1);
+			if (!subpath.startsWith(prefix) || !subpath.endsWith(suffix) || subpath.length < prefix.length + suffix.length) continue;
+			const target = exportTarget(entry);
+			if (!target) continue;
+			const wildcard = subpath.slice(prefix.length, subpath.length - suffix.length);
+			return path.resolve(packageDir, target.replace("*", wildcard));
+		}
+		return undefined;
+	}
+	if (subpath !== ".") return undefined;
+	return path.resolve(packageDir, typeof manifest.main === "string" && manifest.main.trim() ? manifest.main : "index.js");
+}
+
+/** Find `pkg` as the pi package itself, one of its dependencies, or a sibling in a hoisted install. */
+export function findHostPeerPackageDir(piPackageRoot: string, pkg: string): string | undefined {
+	return findPeerPackageDir(piPackageRoot, pkg, readManifest(piPackageRoot)?.name);
+}
+
+function findPeerPackageDir(piPackageRoot: string, pkg: string, hostName: unknown): string | undefined {
+	if (hostName === pkg) return piPackageRoot;
+	const candidates = [path.join(piPackageRoot, "node_modules", pkg)];
+	let dir = piPackageRoot;
+	for (;;) {
+		const parent = path.dirname(dir);
+		if (parent === dir) break;
+		if (path.basename(parent) === "node_modules" || path.basename(path.dirname(parent)) === "node_modules") {
+			const modulesRoot = path.basename(parent) === "node_modules" ? parent : path.dirname(parent);
+			candidates.push(path.join(modulesRoot, pkg));
+		}
+		candidates.push(path.join(parent, "node_modules", pkg));
+		dir = parent;
+	}
+	return candidates.find((candidate) => readManifest(candidate)?.name === pkg);
+}
+
+/** The alias map the runner needs, or the specifiers that could not be resolved. */
+export function resolveHostPeerAliases(
+	piPackageRoot: string,
+	extensionRoot = fileURLToPath(new URL("../../../", import.meta.url)),
+): { aliases: Record<string, string>; missing: string[]; supplemental: string[] } {
+	const aliases: Record<string, string> = {};
+	const missing: string[] = [];
+	const supplemental: string[] = [];
+	const hostManifest = readManifest(piPackageRoot);
+	const isPi0850 = hostManifest?.version === "0.85.0";
+	const required = isPi0850 ? [...HOST_PEER_ALIASES, ...PI0850_PEER_ALIASES] : HOST_PEER_ALIASES;
+	for (const { specifier, pkg, subpath } of required) {
+		const packageDir = findPeerPackageDir(piPackageRoot, pkg, hostManifest?.name);
+		let target = packageDir ? resolvePackageSubpath(packageDir, subpath) : undefined;
+		// Pi 0.85.0 omitted this runtime dependency. Never replace working host
+		// exports or extend this exact version contract to other peers/hosts.
+		if ((!target || !fs.existsSync(target))
+			&& (specifier === "@earendil-works/pi-server" || specifier === "@earendil-works/pi-server/unix")
+			&& isPi0850
+			&& (!packageDir || readManifest(packageDir)?.version === "0.85.0")) {
+			const localDir = findHostPeerPackageDir(extensionRoot, pkg);
+			if (localDir && readManifest(localDir)?.version === "0.85.0") {
+				const localTarget = resolvePackageSubpath(localDir, subpath);
+				if (localTarget && fs.existsSync(localTarget)) {
+					target = localTarget;
+					supplemental.push(specifier);
+				}
+			}
+		}
+		if (target && fs.existsSync(target)) aliases[specifier] = target;
+		else missing.push(specifier);
+	}
+	return { aliases, missing, supplemental };
+}

package/dist/extensions/pi-subagents/src/runs/background/runner-child-launch.ts

@@ -0,0 +1,86 @@
+/** Native runner construction, separate from its executable entrypoint and attempt loop. */
+import * as path from "node:path";
+import { buildInProcessChildLaunch, type BuildInProcessChildLaunchInput, type InheritedChildRuntime } from "../shared/child-launch.ts";
+import { deriveForkPromptCacheKey } from "../shared/child-tool-plan.ts";
+import { normalizeExtensionBindings } from "../shared/extension-bindings.ts";
+import type { RunnerSubagentStep } from "../shared/parallel-utils.ts";
+import { formatAcceptancePrompt } from "../shared/acceptance.ts";
+import { isAgentContract } from "../shared/agent-contract.ts";
+
+export interface RunnerChildLaunchContext {
+	cwd: string;
+	id: string;
+	flatIndex: number;
+	artifactsDir?: string;
+	childIntercomTarget?: string;
+	orchestratorIntercomTarget?: string;
+	nestedRoute?: BuildInProcessChildLaunchInput["nestedRoute"];
+	runFanoutBudget?: BuildInProcessChildLaunchInput["runFanoutBudget"];
+	capabilityCeiling?: BuildInProcessChildLaunchInput["capabilityCeiling"];
+	inheritedChildRuntime?: InheritedChildRuntime;
+}
+
+export function buildRunnerChildLaunch(step: RunnerSubagentStep, ctx: RunnerChildLaunchContext, attempt: {
+	model?: string;
+	sessionEnabled: boolean;
+	sessionDir?: string;
+	sessionName?: string;
+	structuredOutput?: BuildInProcessChildLaunchInput["structuredOutput"];
+	childWatchdog?: BuildInProcessChildLaunchInput["childWatchdog"];
+	watchdogStatus: NonNullable<BuildInProcessChildLaunchInput["watchdogStatus"]>;
+}) {
+	// Resource-backed system instructions survive SDK split-turn compaction verbatim.
+	const acceptancePrompt = step.effectiveAcceptance
+		? formatAcceptancePrompt(step.effectiveAcceptance, { reportOptional: isAgentContract(step.agentContract), structuredOutput: Boolean(step.structuredOutput?.acceptanceReportPath) })
+		: "";
+	return buildInProcessChildLaunch({
+		parentSessionId: step.parentSessionId,
+		forkCacheKey: step.context === "fork" ? deriveForkPromptCacheKey(step.parentSessionId) : undefined,
+		sessionEnabled: attempt.sessionEnabled,
+		sessionDir: attempt.sessionDir,
+		sessionFile: step.sessionFile,
+		model: attempt.model,
+		inheritProjectContext: step.inheritProjectContext,
+		inheritGlobalContext: step.inheritGlobalContext,
+		inheritSkills: step.inheritSkills,
+		requireReadTool: Boolean(step.skills?.length),
+		tools: step.tools,
+		excludeTools: step.excludeTools,
+		allowNestedSubagents: step.allowNestedSubagents,
+		extensions: step.extensions,
+		subagentOnlyExtensions: step.subagentOnlyExtensions,
+		fast: step.fast,
+		modelCandidates: step.modelCandidates,
+		systemPrompt: acceptancePrompt ? `${step.systemPrompt ?? ""}\n${acceptancePrompt}` : step.systemPrompt ?? "",
+		systemPromptMode: step.systemPromptMode,
+		mcpDirectTools: step.mcpDirectTools,
+		extensionBindings: normalizeExtensionBindings(step.extensionBindings)?.value,
+		capabilityCeiling: step.capabilityCeiling ?? ctx.capabilityCeiling,
+		cwd: step.cwd ?? ctx.cwd,
+		intercomSessionName: ctx.childIntercomTarget,
+		sessionName: attempt.sessionName,
+		orchestratorIntercomTarget: ctx.orchestratorIntercomTarget,
+		runId: ctx.id,
+		childAgentName: step.agent,
+		childIndex: ctx.flatIndex,
+		nestedRoute: ctx.nestedRoute,
+		runFanoutBudget: ctx.runFanoutBudget ? {
+			...ctx.runFanoutBudget,
+			...(step.runFanoutPath ? { parentPath: `${ctx.runFanoutBudget.parentPath ? `${ctx.runFanoutBudget.parentPath}/` : ""}${step.runFanoutPath}` } : {}),
+		} : undefined,
+		structuredOutput: attempt.structuredOutput,
+		toolBudget: step.toolBudget,
+		permissionRules: step.permissionRules,
+		permissionAuditPath: step.permissionRules && ctx.artifactsDir
+			? path.join(ctx.artifactsDir, "permission-audit", `${ctx.id}-${ctx.flatIndex}.jsonl`) : undefined,
+		childWatchdog: attempt.childWatchdog,
+		// registerChildWatchdog returns before reading the sink when unconfigured.
+		...(attempt.childWatchdog ? { watchdogStatus: attempt.watchdogStatus } : {}),
+		waitToolEnabled: step.waitToolEnabled,
+		waitToolDefaultTimeoutMs: step.waitToolDefaultTimeoutMs,
+		thinkingCeiling: step.thinkingCeiling,
+		maxSubagentDepth: step.maxSubagentDepth,
+		inherited: ctx.inheritedChildRuntime,
+		host: "runner",
+	});
+}

package/dist/extensions/pi-subagents/src/runs/background/runner-child-sessions.ts

@@ -0,0 +1,31 @@
+/**
+ * Child session factory for the detached async runner.
+ *
+ * The runner imports `@selesai/code` like the parent does;
+ * the parent aliases that specifier (and the other host peer packages) to the
+ * installed pi package through `JITI_ALIAS` when it spawns the runner, see
+ * `runner-aliases.ts`. Tests replace the factory with a scripted one by
+ * naming a module in the runner config.
+ */
+import * as path from "node:path";
+import { pathToFileURL } from "node:url";
+import { createDefaultChildSessionFactory, type ChildSessionFactory } from "../shared/child-session.ts";
+
+export interface RunnerChildSessionConfig {
+	/** Test seam: module whose default export is a `ChildSessionFactory`, or a function returning one. */
+	childSessionFactoryModule?: string;
+}
+
+function isChildSessionFactory(value: unknown): value is ChildSessionFactory {
+	return Boolean(value) && typeof value === "object" && typeof (value as ChildSessionFactory).create === "function" && typeof (value as ChildSessionFactory).dispose === "function";
+}
+
+export async function loadRunnerChildSessionFactory(config: RunnerChildSessionConfig): Promise<ChildSessionFactory> {
+	if (!config.childSessionFactoryModule) return createDefaultChildSessionFactory();
+	const loaded = await import(pathToFileURL(path.resolve(config.childSessionFactoryModule)).href) as { default?: unknown };
+	const candidate = typeof loaded.default === "function" ? (loaded.default as () => unknown)() : loaded.default;
+	if (!isChildSessionFactory(candidate)) {
+		throw new Error(`Child session factory module '${config.childSessionFactoryModule}' must default-export a ChildSessionFactory or a function returning one.`);
+	}
+	return candidate;
+}

package/dist/extensions/pi-subagents/src/runs/background/scheduled-runs.ts

@@ -14,6 +14,7 @@ import type { ResolvedSubagentCapabilityCeiling } from "../shared/capability-cei
 import { previewSimpleWorkflowRun } from "../../workflows/scripted-workflow.ts";
 import { resolveGitRepositoryIdentity } from "../../workflows/chat-progress.ts";
 import { getConfigDirName } from "../../shared/utils.ts";
+import { normalizeWorktreeBaseRef } from "../shared/worktree.ts";
 
 export const SCHEDULED_RUN_ACTIONS = [
 	"schedule.create",
@@ -39,7 +40,7 @@ export type ScheduleRunState = "running" | "skipped" | "missed" | "completed" |
 export type ScheduleTrigger =
 	| { kind: "once"; at: string; nextRunAt?: string }
 	| { kind: "interval"; every: string; everyMs: number; anchorAt: string; nextRunAt: string };
-export type ScheduleTarget = { workflowScript: string };
+export type ScheduleTarget = { workflowScript: string; baseRef?: string };
 
 export interface ScheduleRecord {
 	schemaVersion: 1;
@@ -281,8 +282,15 @@ function readJson(file: string, label: string): unknown {
 
 function parseScheduleTarget(value: unknown, file: string): ScheduleTarget {
 	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`Schedule record '${file}' has invalid trigger or target.`);
-	const target = value as { workflowScript?: unknown; agent?: unknown; task?: unknown };
-	if (typeof target.workflowScript === "string" && target.workflowScript.trim()) return { workflowScript: target.workflowScript.trim() };
+	const target = value as { workflowScript?: unknown; baseRef?: unknown; agent?: unknown; task?: unknown };
+	if (typeof target.workflowScript === "string" && target.workflowScript.trim()) {
+		try {
+			const baseRef = normalizeWorktreeBaseRef(target.baseRef);
+			return { workflowScript: target.workflowScript.trim(), ...(baseRef === undefined ? {} : { baseRef }) };
+		} catch (error) {
+			throw new Error(`Schedule record '${file}' has an invalid baseRef: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
 	if (target.agent !== undefined || target.task !== undefined) throw new Error(`Schedule record '${file}' uses a removed legacy agent target; recreate it with target.workflowScript.`);
 	throw new Error(`Schedule record '${file}' requires a workflowScript target.`);
 }
@@ -429,9 +437,15 @@ function sanitizeTarget(params: SubagentParamsLike): { target?: ScheduleTarget;
 	if (typeof params.workflowScript !== "string" || !params.workflowScript.trim()) return { error: "schedule.create requires a non-empty workflowScript." };
 	if (params.context === "fork") return { error: "Scheduled runs require fresh context." };
 	if (params.async === false) return { error: "Scheduled runs are always async." };
+	let baseRef: string | undefined;
+	try {
+		baseRef = normalizeWorktreeBaseRef(params.baseRef);
+	} catch (error) {
+		return { error: error instanceof Error ? error.message : String(error) };
+	}
 	const acceptanceErrors = validateExecutionAcceptance(params as Parameters<typeof validateExecutionAcceptance>[0]);
 	if (acceptanceErrors.length) return { error: acceptanceErrors.join(" ") };
-	return { target: { workflowScript: params.workflowScript.trim() } };
+	return { target: { workflowScript: params.workflowScript.trim(), ...(baseRef === undefined ? {} : { baseRef }) } };
 }
 
 function executionParams(schedule: ScheduleRecord): SubagentParamsLike {

package/dist/extensions/pi-subagents/src/runs/background/stale-run-reconciler.ts

@@ -9,6 +9,7 @@ import { resolveEffectiveThinking } from "../../shared/model-info.ts";
 import { normalizeParallelGroups } from "./parallel-groups.ts";
 import { nestedSummaryFromAsyncStatus, projectNestedEvents, resolveNestedAsyncDir, writeNestedEvent, type NestedRoute } from "../shared/nested-events.ts";
 import { assertWorkflowGraphHostSteps } from "../shared/host-step-status.ts";
+import type { RawDrainStatusObserver } from "../shared/readonly-drain-observation.ts";
 
 export type PidLiveness = "alive" | "dead" | "unknown";
 
@@ -352,9 +353,10 @@ export function checkPidLiveness(pid: number, kill: KillFn = process.kill): PidL
 	}
 }
 
-export function reconcileAsyncRun(asyncDir: string, options: ReconcileAsyncRunOptions = {}): ReconcileAsyncRunResult {
+export function reconcileAsyncRun(asyncDir: string, options: ReconcileAsyncRunOptions = {}, observeStatus?: RawDrainStatusObserver): ReconcileAsyncRunResult {
 	const now = options.now?.() ?? Date.now();
 	const status = readStatus(asyncDir);
+	observeStatus?.(status);
 	const startedStatus = !status && options.startedRun ? buildStartedStatus(asyncDir, options.startedRun, now) : undefined;
 	const effectiveStatus = status ?? startedStatus;
 	if (!effectiveStatus) return { status: null, repaired: false };