pi-subagents 0.48.0 → 0.49.0

package/src/extension/tool-description.ts

@@ -8,24 +8,25 @@ const CUSTOM_TOOL_DESCRIPTION_MAX_BYTES = 50 * 1024;
 
 export const SUBAGENT_SAFETY_GUIDANCE = `SAFETY-CRITICAL SUBAGENT GUIDANCE:
 • Use { action: "list" } before execution and only run executable/non-disabled agents.
-• Keep execution and management separate: omit action for workflowScript execution; use action only for management/control.
-• Async/background runs are the default. Use async:false only when a blocking foreground result is needed. Do not sleep or poll status just to wait; use subagent_wait only when the current request must finish in this turn.
+• Keep execution and management separate: omit action for structured single-child or workflowScript execution; use action only for management/control.
+• Async/background runs are the default. Use async:false only when a blocking foreground result is needed. After an async launch, continue independent work only until its next dependency barrier; consume the result before work that depends on it. Do not sleep or poll status just to wait; use subagent_wait only when the current request must finish in this turn.
 • Ordinary child subagents are not orchestrators. Only explicitly configured fanout children may use the child-safe subagent tool, still bounded by depth/session limits.
 • Keep one writer for the same cwd/worktree. Use fresh-context read-only reviewers for independent review, then have the parent synthesize and apply fixes.
-• Async runs expose asyncId/asyncDir with status.json, events.jsonl, output logs, and status via { action: "status", id }. Include output paths and residual risks when reporting results.`;
+• Async runs expose asyncId/asyncDir with status.json, events.jsonl, output logs, status via { action: "status", id }, and lifecycle diagnostics via { action: "debug.run", id }. Include output paths and residual risks when reporting results.`;
 
-export const FULL_SUBAGENT_TOOL_DESCRIPTION = `Run subagents only through { workflowScript }; omit action. Use action only for management/control actions.
+export const FULL_SUBAGENT_TOOL_DESCRIPTION = `Run one child with { agent, task? }; use { workflowScript } for orchestration. Omit action for execution. Use action only for management/control actions.
 
 EXECUTION:
 • Before executing, use { action: "list" } and run only executable/non-disabled configured agents.
-• WORKFLOW SCRIPT: { workflowScript: "return runs.run('main', {agent:'worker', task:'...'})" }. Every execution is a workflow. Use stable-key runs.run for one child and runs.all for parallel children; ordinary JavaScript provides sequence, branching, filtering, retries, and aggregation. workflowScript is an ordinary JavaScript statement body, so use an explicit return for a useful result. For task text with Markdown fences or shell blocks, build quoted lines instead of nesting raw template literals: \`const task=["Run:","\`\`\`bash","npm test","\`\`\`"].join("\\n")\`. Scripts start asynchronously by default; pass async:false only for a small foreground run. Same-repo foreground workflows default to a live in-chat card; set chatProgress to auto, off, or live-card to control that projection. Workflow-level child controls default onto each runs.run launch, and explicit child fields override them. Use await prompts.render("package:name" | "user:name" | "project:name", vars?) for reusable plain task text, then pass the result explicitly as task. Use {action:"children.list"} to list up to 10 completed retained children from this parent session, then continue one with runs.run(key, {resume:"run-id", task:"follow-up"}); resume and agent are mutually exclusive, resume keeps the stored agent/model/tool contract, workflow resumes wait for completed output, and loops must continue from each latest returned runId. For repository mutation lanes, set worktree:true on the workflow or individual runs.run/runs.all item for managed isolation; each parallel child gets a separate worktree and handoff artifact. A workflow usageBudget is enforced once across the workflow. Available globals are runs.run, runs.all, runs.status, runs.ref/refs, prompts.render, emit, console, and standard JavaScript only. Workflows get async state.get(key) and state.set(key, JSONValue) through their automatic or explicit mission; mission:false workflows do not have a state global. Scripts cannot access filesystem, shell, arbitrary Pi tools, or host globals.
+• SINGLE CHILD: { agent:"worker", task:"..." }. This structured form starts exactly one child through the workflow runtime. Workflow-level fields such as model, context, cwd, worktree, output, budgets, acceptance, and async remain defaults for that child. Do not combine agent/task with action or workflowScript.
+• WORKFLOW SCRIPT: { workflowScript: "return runs.run('main', {agent:'worker', task:'...'})" }. Use stable-key runs.run for one child and runs.all for parallel children; ordinary JavaScript provides sequence, branching, filtering, retries, and aggregation. workflowScript is an ordinary JavaScript statement body, so use an explicit return for a useful result. For task text with Markdown fences or shell blocks, build quoted lines instead of nesting raw template literals: \`const task=["Run:","\`\`\`bash","npm test","\`\`\`"].join("\\n")\`. Scripts start asynchronously by default; pass async:false only for a small foreground run. Same-repo foreground workflows default to a live in-chat card; set chatProgress to auto, off, or live-card to control that projection. Workflow-level child controls default onto each runs.run launch, and explicit child fields override them. Use await prompts.render("package:name" | "user:name" | "project:name", vars?) for reusable plain task text, then pass the result explicitly as task. Use {action:"children.list"} to list up to 10 completed retained children from this parent session, then continue one with runs.run(key, {resume:"run-id", task:"follow-up"}); resume and agent are mutually exclusive, resume keeps the stored agent/model/tool contract, workflow resumes wait for completed output, and loops must continue from each latest returned runId. For repository mutation lanes, set worktree:true on the workflow or individual runs.run/runs.all item for managed isolation; each parallel child gets a separate worktree and handoff artifact. A workflow usageBudget is enforced once across the workflow. Available globals are runs.run, runs.all, runs.status, runs.ref/refs, prompts.render, emit, console, and standard JavaScript only. Workflows get async state.get(key) and state.set(key, JSONValue) through their automatic or explicit mission; mission:false workflows do not have a state global. Scripts cannot access filesystem, shell, arbitrary Pi tools, or host globals.
 • Sequential example: { workflowScript: "const a = await runs.run('analyze', {agent:'agent-a', task:'Analyze the request'}); return (await runs.run('plan', {agent:'agent-b', task:'Plan from: '+a.output})).output" }
 • Parallel example: { workflowScript: "const [a,b] = await runs.all([{key:'correctness',agent:'agent-a',task:'Review correctness'},{key:'tests',agent:'agent-b',task:'Review tests'}]); return {correctness:a.output,tests:b.output}" }
 • Optional context is "fresh" or "fork". timeoutMs/maxRuntimeMs apply to foreground and async workflows; foreground workflows default to 30 minutes and async workflows have no default timeout. Omit acceptance for reviewer/read-only calls; evidence levels end at verified, and acceptance.review.required requests independent writer review.
 • Durable mission attachment is automatic by default. Use missionId to attach an existing mission, mission:{...} to override auto-create, or mission:false for ephemeral work. A mission object needs exactly one non-empty title or summary; objective and labels are optional. goal may only be true and requires budget:{tokens}.
 
 MANAGEMENT / CONTROL (use action; omit execution fields):
-• list, get, models, guide, children.list, create, update, delete, eject, disable, enable, reset, doctor, grant-spawn-budget, worktree.discard, refine/refine.show/refine.rollback, mission.create/list/show/update/resolve-decision/attach-run/close, inspector.open/status/close, project.open/status/close, and watchdog actions remain available. Use {action:"guide", topic:"overview"} for packaged current-version help; topics are overview, workflows, agents, missions, observability, tool-reference, configuration, models, watchdog, and extension-api.
+• list, get, models, guide, children.list, create, update, delete, eject, disable, enable, reset, status, debug.run, doctor, grant-spawn-budget, worktree.discard, refine/refine.show/refine.rollback, mission.create/list/show/update/resolve-decision/attach-run/close, inspector.open/status/close, project.open/status/close, and watchdog actions remain available. Use {action:"guide", topic:"overview"} for packaged current-version help; topics are overview, workflows, agents, missions, observability, tool-reference, configuration, models, watchdog, and extension-api.
 • status, interrupt, stop, resume, and steer manage live or persisted runs. Use status view:"fleet" for an overview or view:"transcript" with id and optional index to tail output.
 • { action: "append-step", id: "...", step: {agent:"agent-c", task:"Use {previous}"} } appends one step to an already-running durable legacy chain. step is control-only, not an execution mode.
 • approve-checkpoint and reject-checkpoint decide a paused durable legacy chain checkpoint.
@@ -33,10 +34,11 @@ MANAGEMENT / CONTROL (use action; omit execution fields):
 
 ${SUBAGENT_SAFETY_GUIDANCE}`;
 
-export const COMPACT_SUBAGENT_TOOL_DESCRIPTION = `Run subagents only through { workflowScript }; omit action. Use action only for management/control actions.
+export const COMPACT_SUBAGENT_TOOL_DESCRIPTION = `Run one child with { agent, task? }; use { workflowScript } for orchestration. Omit action for execution. Use action only for management/control actions.
 
 EXECUTE:
 • Call { action:"list" } first and use only executable/non-disabled agents.
+• SINGLE {agent:"worker",task:"..."} starts exactly one child through the workflow runtime. Workflow-level fields remain child defaults. Do not combine agent/task with action or workflowScript.
 • SCRIPT {workflowScript:"return runs.run('main', {agent:'worker', task:'...'})"}. Use stable-key runs.run for one child and runs.all for parallel work. Use await prompts.render("package:name" | "user:name" | "project:name", vars?) for reusable task text and pass it explicitly to runs.run. Use {action:"children.list"} for the last 10 retained children in this parent session, then runs.run(key,{resume:"run-id",task:"follow-up"}) to continue one with its stored contract; workflow resumes wait for completion and loops continue from the latest returned runId. Workflows get async state.get/state.set through their automatic or explicit mission; mission:false does not. Scripts are ordinary JavaScript statement bodies; use explicit return for a useful result. For task text with Markdown fences or shell blocks, build quoted lines instead of nesting raw template literals: \`const task=["Run:","\`\`\`bash","npm test","\`\`\`"].join("\\n")\`. Use JavaScript for sequence, branching, retries, and aggregation. For repository mutation lanes, use worktree:true on the workflow or runs.run/runs.all item for managed isolation. Scripts start async by default; async:false is the foreground escape hatch and auto-enables a same-repo live chat card unless chatProgress is off.
 • Example: {workflowScript:"const [a,b]=await runs.all([{key:'a',agent:'agent-a',task:'Implement A',worktree:true},{key:'b',agent:'agent-b',task:'Implement B',worktree:true}]); return [a.output,b.output]"}
 • context can be fresh or fork. timeoutMs/maxRuntimeMs apply to foreground and async workflows; foreground workflows default to 30 minutes and async workflows have no default timeout. Omit acceptance for reviewer/read-only calls.
@@ -47,7 +49,7 @@ MANAGE / CONTROL:
 • A mission object needs exactly one non-empty title or summary; objective and labels are optional. goal may only be true and requires budget:{tokens}.
 
 ASYNC / SAFETY:
-• Omitted async detaches background work. Do not sleep or poll merely to wait; use subagent_wait only when this turn must receive results.
+• Omitted async detaches background work. Continue independent work only until its next dependency barrier; consume the result before work that depends on it. Do not sleep or poll merely to wait; use subagent_wait only when this turn must receive results.
 • Ordinary children are not orchestrators. Keep one writer per cwd/worktree and use fresh read-only reviewers for independent checks.
 • Status and artifacts live under asyncId/asyncDir with status.json, events.jsonl, output logs, and {action:"status",id:"..."}.`;
 

package/src/inspectors/herdr/actions.ts

@@ -10,6 +10,7 @@ import { writeAtomicJson } from "../../shared/atomic-json.ts";
 import { DIRS, type Details, type SubagentState } from "../../shared/types.ts";
 import { readStatus } from "../../shared/utils.ts";
 import { resolveSubagentRunId } from "../../runs/background/run-id-resolver.ts";
+import { resolveNodeExecutable } from "../../shared/node-executable.ts";
 import { createHerdrClient, detectHerdr, type HerdrClient, type HerdrErrorCode, type HerdrResult } from "./client.ts";
 
 export const HERDR_INSPECTOR_ACTIONS = ["inspector.open", "inspector.status", "inspector.close"] as const;
@@ -45,6 +46,7 @@ interface InspectorDeps {
 	client?: HerdrClient;
 	missions?: MissionStoreConfig;
 	authorityPolicy?: AuthorityPolicyConfig;
+	sessionRoots?: string[];
 	cwd: string;
 	signal?: AbortSignal;
 	now?: () => Date;
@@ -89,8 +91,8 @@ function shellQuote(value: string): string {
 	return `'${value.replaceAll("'", "'\\''")}'`;
 }
 
-function inspectorCommand(input: { runnerPath: string; asyncDir: string; runId: string; index?: number; missionPath?: string; allowSteer: boolean; allowStop: boolean }): string {
-	const args = [process.execPath, input.runnerPath, "--async-dir", input.asyncDir, "--run-id", input.runId, "--allow-steer", String(input.allowSteer), "--allow-stop", String(input.allowStop)];
+function inspectorCommand(input: { runnerPath: string; asyncDir: string; runId: string; index?: number; missionPath?: string; allowSteer: boolean; allowStop: boolean; sessionRoots: string[] }): string {
+	const args = [resolveNodeExecutable(), input.runnerPath, "--async-dir", input.asyncDir, "--run-id", input.runId, "--allow-steer", String(input.allowSteer), "--allow-stop", String(input.allowStop), "--session-roots", JSON.stringify(input.sessionRoots)];
 	if (input.index !== undefined) args.push("--index", String(input.index));
 	if (input.missionPath) args.push("--mission-path", input.missionPath);
 	return `${process.platform === "win32" ? "& " : ""}${args.map(shellQuote).join(" ")}`;
@@ -114,6 +116,12 @@ function pathWithin(base: string, candidate: string): boolean {
 	return resolvedCandidate === resolvedBase || resolvedCandidate.startsWith(`${resolvedBase}${path.sep}`);
 }
 
+function herdrSessionRoots(target: { runId: string }, deps: InspectorDeps): string[] {
+	const roots = deps.sessionRoots ?? deps.state?.trustedSessionRoots ?? [];
+	const job = deps.state?.asyncJobs.get(target.runId) ?? deps.state?.fleetJobs?.get(target.runId);
+	return [...new Set([...roots, ...(job?.sessionRoot ? [job.sessionRoot] : [])])];
+}
+
 function isTrustedAsyncDir(asyncDir: string, deps: InspectorDeps): boolean {
 	try {
 		if (fs.lstatSync(asyncDir).isSymbolicLink() || !fs.statSync(asyncDir).isDirectory()) return false;
@@ -204,6 +212,7 @@ export async function handleHerdrInspectorAction(action: HerdrInspectorAction, p
 		missionPath: mission?.path,
 		allowSteer: resolveAuthorityDecision({ action: "steerRun", policy: deps.authorityPolicy }) === "auto",
 		allowStop: resolveAuthorityDecision({ action: "stopRun", policy: deps.authorityPolicy }) === "auto",
+		sessionRoots: herdrSessionRoots(target, deps),
 	});
 	const started = await client.run(["pane", "run", paneId, command], { timeoutMs: 15_000, signal: deps.signal });
 	if (started.ok === false) {

package/src/inspectors/herdr/inspector-runner.ts

@@ -17,6 +17,7 @@ export interface RunnerOptions {
 	refreshMs: number;
 	allowSteer?: boolean;
 	allowStop?: boolean;
+	sessionRoots: string[];
 }
 
 function readMission(filePath: string | undefined): MissionRecord | undefined {
@@ -24,7 +25,7 @@ function readMission(filePath: string | undefined): MissionRecord | undefined {
 	try { return parseMissionRecord(JSON.parse(fs.readFileSync(filePath, "utf-8")), filePath); } catch { return undefined; }
 }
 
-export function formatInspectorDashboard(input: { status: AsyncStatus; asyncDir: string; index?: number; mission?: MissionRecord; allowSteer?: boolean; allowStop?: boolean }): string {
+export function formatInspectorDashboard(input: { status: AsyncStatus; asyncDir: string; index?: number; mission?: MissionRecord; allowSteer?: boolean; allowStop?: boolean; sessionRoots?: string[] }): string {
 	const { status, asyncDir, mission } = input;
 	const lines = [
 		`pi-subagents inspector for ${status.runId}`,
@@ -37,7 +38,7 @@ export function formatInspectorDashboard(input: { status: AsyncStatus; asyncDir:
 		if (open.length) lines.push(`Open decisions: ${open.map((decision) => `${decision.id}: ${decision.title}`).join(" | ")}`);
 		lines.push("");
 	}
-	lines.push(formatAsyncRunTranscript(status, asyncDir, { index: input.index, lines: 60 }));
+	lines.push(formatAsyncRunTranscript(status, asyncDir, { index: input.index, lines: 60, sessionRoots: input.sessionRoots }));
 	const controls = [input.allowSteer === false ? undefined : "steer <message>", input.allowStop === false ? undefined : "stop", "status"].filter(Boolean);
 	lines.push("", `Controls: ${controls.join(" | ")}`, "Supervisor replies remain in the parent Pi session (subagent_supervisor/intercom).");
 	return lines.join("\n");
@@ -57,6 +58,17 @@ function parseArgs(argv: string[]): RunnerOptions {
 	const indexRaw = values.get("--index");
 	const childIndex = indexRaw === undefined ? undefined : Number(indexRaw);
 	if (childIndex !== undefined && (!Number.isInteger(childIndex) || childIndex < 0)) throw new Error("--index must be a non-negative integer.");
+	const sessionRootsRaw = values.get("--session-roots");
+	let sessionRoots: string[] = [];
+	if (sessionRootsRaw !== undefined) {
+		try {
+			const parsed = JSON.parse(sessionRootsRaw) as unknown;
+			if (!Array.isArray(parsed) || parsed.some((root) => typeof root !== "string")) throw new Error();
+			sessionRoots = parsed;
+		} catch {
+			throw new Error("--session-roots must be a JSON array of strings.");
+		}
+	}
 	const refreshRaw = values.get("--refresh-ms");
 	const refreshMs = refreshRaw === undefined ? 1_500 : Number(refreshRaw);
 	if (!Number.isInteger(refreshMs) || refreshMs < 250) throw new Error("--refresh-ms must be an integer >= 250.");
@@ -65,6 +77,7 @@ function parseArgs(argv: string[]): RunnerOptions {
 		runId,
 		...(childIndex !== undefined ? { index: childIndex } : {}),
 		...(values.get("--mission-path") ? { missionPath: path.resolve(values.get("--mission-path")!) } : {}),
+		sessionRoots,
 		refreshMs,
 		allowSteer: values.get("--allow-steer") !== "false",
 		allowStop: values.get("--allow-stop") !== "false",
@@ -115,7 +128,7 @@ export function runInspector(argv = process.argv.slice(2)): void {
 			process.stdout.write(`\x1b[2J\x1b[Hpi-subagents inspector\n\nLifecycle status for ${options.runId} is unavailable.\n`);
 			return;
 		}
-		process.stdout.write(`\x1b[2J\x1b[H${formatInspectorDashboard({ status, asyncDir: options.asyncDir, index: options.index, mission: readMission(options.missionPath), allowSteer: options.allowSteer, allowStop: options.allowStop })}${notice ? `\n\n${notice}` : ""}\n> `);
+		process.stdout.write(`\x1b[2J\x1b[H${formatInspectorDashboard({ status, asyncDir: options.asyncDir, index: options.index, mission: readMission(options.missionPath), allowSteer: options.allowSteer, allowStop: options.allowStop, sessionRoots: options.sessionRoots })}${notice ? `\n\n${notice}` : ""}\n> `);
 		if (isTerminal(status) && timer) {
 			clearInterval(timer);
 			timer = undefined;

package/src/intercom/intercom-bridge.ts

@@ -51,6 +51,8 @@ export interface IntercomBridgeDiagnostic {
 
 interface ResolveIntercomBridgeInput {
 	config: ExtensionConfig["intercomBridge"];
+	/** Per-run config replaces the global config when supplied. */
+	override?: IntercomBridgeConfig;
 	context: "fresh" | "fork" | undefined;
 	orchestratorTarget?: string;
 	cwd?: string;
@@ -143,7 +145,7 @@ export function diagnoseIntercomBridge(input: ResolveIntercomBridgeInput): Inter
 }
 
 export function resolveIntercomBridge(input: ResolveIntercomBridgeInput): IntercomBridgeState {
-	const config = resolveIntercomBridgeConfig(input.config);
+	const config = resolveIntercomBridgeConfig(input.override !== undefined ? input.override : input.config);
 	const mode = config.mode;
 	const orchestratorTarget = input.orchestratorTarget?.trim();
 	const agentDir = path.resolve(input.agentDir ?? defaultAgentDir());

package/src/missions/store.ts

@@ -2,7 +2,6 @@ import { createHash, randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { getProjectSubagentsDir } from "../shared/artifacts.ts";
 import { writePrivateAtomicJson } from "../shared/atomic-json.ts";
 import { getAgentDir } from "../shared/utils.ts";
 import {
@@ -259,6 +258,11 @@ function expandConfiguredPath(value: string, projectRoot: string): string {
 	return path.isAbsolute(expanded) ? path.normalize(expanded) : path.resolve(projectRoot, expanded);
 }
 
+function projectMissionDirectory(agentDir: string, projectRoot: string): string {
+	const projectKey = createHash("sha256").update(projectRoot).digest("hex");
+	return path.join(agentDir, "missions", "projects", projectKey);
+}
+
 export function validateMissionStoreConfig(value: unknown, label = "config.missions"): MissionStoreConfig | undefined {
 	if (value === undefined) return undefined;
 	const input = asObject(value, label);
@@ -289,12 +293,13 @@ export function resolveMissionStoreLocation(input: {
 	agentDir?: string;
 }): MissionStoreLocation {
 	const projectRoot = path.resolve(input.projectRoot);
+	const agentDir = input.agentDir ?? getAgentDir();
 	const missionDir = input.config?.directory
 		? expandConfiguredPath(input.config.directory, projectRoot)
-		: path.join(getProjectSubagentsDir(projectRoot), "missions");
+		: projectMissionDirectory(agentDir, projectRoot);
 	const globalIndexDir = input.config?.globalIndexDir
 		? expandConfiguredPath(input.config.globalIndexDir, projectRoot)
-		: path.join(input.agentDir ?? getAgentDir(), "missions", "index");
+		: path.join(agentDir, "missions", "index");
 	return {
 		projectRoot,
 		missionDir,

package/src/runs/background/active-async-capacity.ts

@@ -39,6 +39,18 @@ interface CapacityOptions {
 	afterSlotRename?: (releasedDir: string) => void;
 }
 
+export type ActiveAsyncCapacityReleaseVerdict =
+	| { state: "releasable"; reason: string }
+	| { state: "retained"; reason: string }
+	| { state: "not-owned"; reason: string };
+
+export interface ActiveAsyncCapacityInspection {
+	owner?: ActiveAsyncCapacityOwnerV1;
+	relation: "current" | "source" | "none";
+	slotDir?: string;
+	release: ActiveAsyncCapacityReleaseVerdict;
+}
+
 export class ActiveAsyncCapacityError extends Error {
 	readonly snapshot: ActiveAsyncCapacitySnapshot;
 
@@ -160,55 +172,100 @@ function terminalState(state: AsyncStatus["state"]): boolean {
 	return state !== "queued" && state !== "running" && state !== "paused";
 }
 
-function runnerCanRelease(owner: ActiveAsyncCapacityOwnerV1, status: AsyncStatus): boolean {
-	if (!owner.runnerProcessInstanceId
-		|| status.sessionId !== owner.ownerSessionId
-		|| status.runId !== owner.runId
-		|| !terminalState(status.state)) return false;
+function runnerReleaseVerdict(owner: ActiveAsyncCapacityOwnerV1, status: AsyncStatus | null): ActiveAsyncCapacityReleaseVerdict {
+	if (!status) return { state: "retained", reason: "status file is missing or unreadable" };
+	if (!owner.runnerProcessInstanceId) return { state: "retained", reason: "runner process identity has not been recorded" };
+	if (status.sessionId !== owner.ownerSessionId) return { state: "retained", reason: `status session ${status.sessionId ?? "unknown"} does not match owner session ${owner.ownerSessionId}` };
+	if (status.runId !== owner.runId) return { state: "retained", reason: `status run ${status.runId} does not match owner run ${owner.runId}` };
+	if (!terminalState(status.state)) return { state: "retained", reason: `run is still ${status.state}` };
 	if (status.processTerminal?.state === "not-started"
 		&& status.processTerminal.runId === owner.runId
 		&& status.processTerminal.runnerProcessInstanceId === owner.runnerProcessInstanceId
 		&& typeof status.error === "string"
-		&& status.error) return true;
+		&& status.error) return { state: "releasable", reason: "run failed before child startup completed" };
 	const proof = readProcessTerminal(owner.asyncDir, {
 		runId: owner.runId,
 		runnerProcessInstanceId: owner.runnerProcessInstanceId,
 	});
 	return proof?.state === "observed"
 		&& proof.runId === owner.runId
-		&& proof.runnerProcessInstanceId === owner.runnerProcessInstanceId;
+		&& proof.runnerProcessInstanceId === owner.runnerProcessInstanceId
+		? { state: "releasable", reason: "matching observed process-terminal proof is present" }
+		: { state: "retained", reason: `process-terminal proof is ${proof?.state ?? "missing"}` };
 }
 
-function workflowCanRelease(owner: ActiveAsyncCapacityOwnerV1, status: AsyncStatus, liveWorkflowRunIds: ReadonlySet<string>): boolean {
-	if (status.sessionId !== owner.ownerSessionId
-		|| status.runId !== owner.runId
-		|| status.mode !== "workflow"
-		|| !terminalState(status.state)
-		|| liveWorkflowRunIds.has(owner.runId)) return false;
+function workflowReleaseVerdict(owner: ActiveAsyncCapacityOwnerV1, status: AsyncStatus | null, liveWorkflowRunIds: ReadonlySet<string>): ActiveAsyncCapacityReleaseVerdict {
+	if (!status) return { state: "retained", reason: "status file is missing or unreadable" };
+	if (status.sessionId !== owner.ownerSessionId) return { state: "retained", reason: `status session ${status.sessionId ?? "unknown"} does not match owner session ${owner.ownerSessionId}` };
+	if (status.runId !== owner.runId) return { state: "retained", reason: `status run ${status.runId} does not match owner run ${owner.runId}` };
+	if (status.mode !== "workflow") return { state: "retained", reason: `status mode is ${status.mode}, not workflow` };
+	if (!terminalState(status.state)) return { state: "retained", reason: `workflow is still ${status.state}` };
+	if (liveWorkflowRunIds.has(owner.runId)) return { state: "retained", reason: "workflow controller is still live" };
 	for (const step of status.steps ?? []) {
-		if (step.status === "pending" || step.status === "running" || step.status === "paused") return false;
-		if (typeof step.async !== "boolean") return false;
+		const label = step.workflowKey ?? step.agent;
+		if (step.status === "pending" || step.status === "running" || step.status === "paused") return { state: "retained", reason: `workflow child ${label} is still ${step.status}` };
+		if (typeof step.async !== "boolean") return { state: "retained", reason: `workflow child ${label} is missing async classification` };
 		if (!step.async) continue;
-		if (!step.runId) return false;
+		if (!step.runId) return { state: "retained", reason: `async workflow child ${label} is missing run id` };
 		const childDir = path.join(path.dirname(owner.asyncDir), step.runId);
-		if (!fs.existsSync(childDir)) return false;
+		if (!fs.existsSync(childDir)) return { state: "retained", reason: `async workflow child ${label} directory is missing` };
 		const childStatus = readStatus(childDir);
-		if (!childStatus || !terminalState(childStatus.state) || !childStatus.processTerminal?.runnerProcessInstanceId) return false;
+		if (!childStatus) return { state: "retained", reason: `async workflow child ${label} status is missing or unreadable` };
+		if (!terminalState(childStatus.state)) return { state: "retained", reason: `async workflow child ${label} is still ${childStatus.state}` };
+		if (!childStatus.processTerminal?.runnerProcessInstanceId) return { state: "retained", reason: `async workflow child ${label} has no runner process identity` };
 		const proof = readProcessTerminal(childDir, {
 			runId: step.runId,
 			runnerProcessInstanceId: childStatus.processTerminal.runnerProcessInstanceId,
 		});
-		if (proof?.state !== "observed" || proof.runId !== step.runId) return false;
+		if (proof?.state !== "observed" || proof.runId !== step.runId) return { state: "retained", reason: `async workflow child ${label} process-terminal proof is ${proof?.state ?? "missing"}` };
 	}
-	return true;
+	return { state: "releasable", reason: "workflow is terminal, controller is gone, and async children have observed proof" };
 }
 
-function ownerCanRelease(owner: ActiveAsyncCapacityOwnerV1, liveWorkflowRunIds: ReadonlySet<string>): boolean {
+function ownerReleaseVerdict(owner: ActiveAsyncCapacityOwnerV1, liveWorkflowRunIds: ReadonlySet<string>): ActiveAsyncCapacityReleaseVerdict {
 	const status = readStatus(owner.asyncDir);
-	if (!status) return false;
 	return owner.kind === "runner"
-		? runnerCanRelease(owner, status)
-		: workflowCanRelease(owner, status, liveWorkflowRunIds);
+		? runnerReleaseVerdict(owner, status)
+		: workflowReleaseVerdict(owner, status, liveWorkflowRunIds);
+}
+
+function capacitySessionDirs(rootDir: string, sessionId?: string): string[] {
+	if (sessionId) return [sessionDir(sessionId, rootDir)];
+	try {
+		return fs.readdirSync(rootDir, { withFileTypes: true })
+			.filter((entry) => entry.isDirectory())
+			.map((entry) => path.join(rootDir, entry.name));
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+		throw error;
+	}
+}
+
+export function inspectActiveAsyncCapacityOwner(
+	input: { runId: string; sessionId?: string; asyncDir?: string },
+	options: CapacityOptions & { liveWorkflowRunIds?: ReadonlySet<string> } = {},
+): ActiveAsyncCapacityInspection {
+	const rootDir = options.rootDir ?? ACTIVE_ASYNC_CAPACITY_DIR;
+	const liveWorkflowRunIds = options.liveWorkflowRunIds ?? new Set<string>();
+	for (const poolDir of capacitySessionDirs(rootDir, input.sessionId)) {
+		for (const dir of occupiedSlots(poolDir)) {
+			const owner = readOwner(dir);
+			if (!owner) continue;
+			const sameRun = owner.runId === input.runId || (input.asyncDir !== undefined && path.resolve(owner.asyncDir) === path.resolve(input.asyncDir));
+			const sourceRun = owner.sourceRunId === input.runId;
+			if (!sameRun && !sourceRun) continue;
+			if (sourceRun && !sameRun) {
+				return {
+					owner,
+					relation: "source",
+					slotDir: dir,
+					release: { state: "not-owned", reason: `slot was transferred to ${owner.runId}` },
+				};
+			}
+			return { owner, relation: "current", slotDir: dir, release: ownerReleaseVerdict(owner, liveWorkflowRunIds) };
+		}
+	}
+	return { relation: "none", release: { state: "not-owned", reason: "no active-capacity slot records this run" } };
 }
 
 export function reconcileActiveAsyncCapacity(
@@ -225,7 +282,7 @@ export function reconcileActiveAsyncCapacity(
 			|| owner.ownerSessionId !== sessionId
 			|| owner.ownerSessionKey !== activeAsyncCapacitySessionKey(sessionId)
 			|| path.basename(dir) !== `slot-${owner.slot}`
-			|| !ownerCanRelease(owner, liveWorkflowRunIds)) continue;
+			|| ownerReleaseVerdict(owner, liveWorkflowRunIds).state !== "releasable") continue;
 		removeOwnedSlot(dir, owner, options);
 	}
 	return snapshotFor(sessionId, limit, rootDir);

package/src/runs/background/async-execution.ts

@@ -19,6 +19,7 @@ import { buildChainInstructions, isCheckpointStep, isDynamicParallelStep, isPara
 import type { RunnerStep } from "../shared/parallel-utils.ts";
 import type { ContextMode } from "../shared/context-mode.ts";
 import { resolvePiPackageRoot } from "../shared/pi-spawn.ts";
+import { resolveNodeExecutable } from "../../shared/node-executable.ts";
 import { buildSkillInjection, normalizeSkillInput, resolveSkillsWithFallback } from "../../agents/skills.ts";
 import { buildAgentMemoryInjection } from "../../agents/agent-memory.ts";
 import { PI_CODING_AGENT_PACKAGE_ROOT_ENV, PROMPT_REDACTED, resolveChildCwd } from "../../shared/utils.ts";
@@ -37,6 +38,7 @@ import {
 	type AsyncStatus,
 	type ArtifactConfig,
 	type Details,
+	type IntercomBridgeConfig,
 	type JsonSchemaObject,
 	type MaxOutputConfig,
 	type NestedRouteInfo,
@@ -187,6 +189,8 @@ interface AsyncSingleParams {
 	/** Raw caller-facing goal used only by the started event. */
 	goal?: string;
 	agentConfig: AgentConfig;
+	/** Agent contract before per-run bridge injection, used only for recovery persistence. */
+	recoveryAgentConfig?: AgentConfig;
 	ctx: AsyncExecutionContext;
 	cwd?: string;
 	maxOutput?: MaxOutputConfig;
@@ -214,6 +218,7 @@ interface AsyncSingleParams {
 	worktreeSetupHookTimeoutMs?: number;
 	worktreeBaseDir?: string;
 	controlConfig?: ResolvedControlConfig;
+	intercomBridge?: IntercomBridgeConfig;
 	controlIntercomTarget?: string;
 	childIntercomTarget?: (agent: string, index: number) => string | undefined;
 	nestedRoute?: NestedRouteInfo;
@@ -299,27 +304,6 @@ export function isAsyncAvailable(): boolean {
 	return jitiCliPath !== undefined;
 }
 
-function isNodeExecutableName(execPath: string): boolean {
-	const basename = path.basename(execPath).toLowerCase();
-	return basename === "node" || basename === "node.exe" || basename === "nodejs" || basename === "nodejs.exe";
-}
-
-function canUseCurrentNodeExecutable(execPath: string): boolean {
-	try {
-		fs.accessSync(execPath, process.platform === "win32" ? fs.constants.F_OK : fs.constants.X_OK);
-		return true;
-	} catch {
-		return false;
-	}
-}
-
-function resolveAsyncRunnerNodeCommand(): string {
-	if (isNodeExecutableName(process.execPath) && canUseCurrentNodeExecutable(process.execPath)) {
-		return process.execPath;
-	}
-	return process.platform === "win32" ? "node.exe" : "node";
-}
-
 export function resolveAsyncRunnerLogPaths(cfg: object): { stdoutPath: string; stderrPath: string } | undefined {
 	const asyncDir = typeof (cfg as { asyncDir?: unknown }).asyncDir === "string"
 		? (cfg as { asyncDir: string }).asyncDir
@@ -486,7 +470,7 @@ function spawnRunner(cfg: object, suffix: string, cwd: string, onProcessTerminal
 	const launchConfig = { ...cfg, runnerProcessInstanceId };
 	fs.writeFileSync(cfgPath, JSON.stringify(launchConfig));
 	const runner = path.join(path.dirname(fileURLToPath(import.meta.url)), "subagent-runner.ts");
-	const nodeCommand = resolveAsyncRunnerNodeCommand();
+	const nodeCommand = resolveNodeExecutable();
 	const launchForStartup = launchConfig as typeof launchConfig & { asyncDir?: unknown; id?: unknown; sessionId?: unknown; revivalLease?: unknown };
 	const launchAsyncDir = typeof launchForStartup.asyncDir === "string" ? launchForStartup.asyncDir : undefined;
 	const launchRunId = typeof launchForStartup.id === "string" ? launchForStartup.id : suffix;
@@ -1251,6 +1235,7 @@ export function executeAsyncChain(
 			workflowGraph,
 			cwd: runnerCwd,
 			asyncDir,
+			...(sessionRoot ? { sessionRoot } : {}),
 			...(params.timeoutMs !== undefined ? { timeoutMs: params.timeoutMs, deadlineAt } : {}),
 			...(initialTurnBudget ? { turnBudget: initialTurnBudget } : {}),
 			...(initialUsageBudget ? { usageBudget: initialUsageBudget } : {}),
@@ -1451,6 +1436,7 @@ export function executeAsyncSingle(
 		async: true,
 		agentContract: params.agentContract,
 	});
+	const recoveryAgentConfig = params.recoveryAgentConfig ?? agentConfig;
 	const recoveryDescriptor: SteeringRecoveryDescriptor = {
 		version: 1,
 		launchContractDigest,
@@ -1462,30 +1448,31 @@ export function executeAsyncSingle(
 		...(sessionFile ? { sessionFile } : {}),
 		cwd: runnerCwd,
 		...(model ? { model } : {}),
-		...(agentConfig.fallbackModels ? { fallbackModels: [...agentConfig.fallbackModels] } : {}),
+		...(recoveryAgentConfig.fallbackModels ? { fallbackModels: [...recoveryAgentConfig.fallbackModels] } : {}),
 		...(effectiveThinking ? { thinking: resolveEffectiveThinking(model, effectiveThinking) } : {}),
-		...(agentConfig.tools ? { tools: [...agentConfig.tools] } : {}),
-		...(agentConfig.extensions ? { extensions: [...agentConfig.extensions] } : {}),
-		...(agentConfig.subagentOnlyExtensions ? { subagentOnlyExtensions: [...agentConfig.subagentOnlyExtensions] } : {}),
-		...(agentConfig.mcpDirectTools ? { mcpDirectTools: [...agentConfig.mcpDirectTools] } : {}),
-		...(agentConfig.systemPrompt ? { systemPrompt: agentConfig.systemPrompt } : {}),
-		systemPromptMode: agentConfig.systemPromptMode,
-		inheritProjectContext: agentConfig.inheritProjectContext,
-		inheritSkills: agentConfig.inheritSkills,
+		...(recoveryAgentConfig.tools ? { tools: [...recoveryAgentConfig.tools] } : {}),
+		...(recoveryAgentConfig.extensions ? { extensions: [...recoveryAgentConfig.extensions] } : {}),
+		...(recoveryAgentConfig.subagentOnlyExtensions ? { subagentOnlyExtensions: [...recoveryAgentConfig.subagentOnlyExtensions] } : {}),
+		...(recoveryAgentConfig.mcpDirectTools ? { mcpDirectTools: [...recoveryAgentConfig.mcpDirectTools] } : {}),
+		...(recoveryAgentConfig.systemPrompt ? { systemPrompt: recoveryAgentConfig.systemPrompt } : {}),
+		systemPromptMode: recoveryAgentConfig.systemPromptMode,
+		inheritProjectContext: recoveryAgentConfig.inheritProjectContext,
+		inheritSkills: recoveryAgentConfig.inheritSkills,
 		...(resolvedSkills.length ? { skills: resolvedSkills.map((skill) => skill.name) } : {}),
-		...(agentConfig.skillPath ? { skillPath: [...agentConfig.skillPath] } : {}),
-		...(agentConfig.filePath ? { agentFilePath: agentConfig.filePath } : {}),
-		...(agentConfig.completionGuard !== undefined ? { completionGuard: agentConfig.completionGuard } : {}),
-		...(agentConfig.memory ? { memory: { ...agentConfig.memory } } : {}),
+		...(recoveryAgentConfig.skillPath ? { skillPath: [...recoveryAgentConfig.skillPath] } : {}),
+		...(recoveryAgentConfig.filePath ? { agentFilePath: recoveryAgentConfig.filePath } : {}),
+		...(recoveryAgentConfig.completionGuard !== undefined ? { completionGuard: recoveryAgentConfig.completionGuard } : {}),
+		...(recoveryAgentConfig.memory ? { memory: { ...recoveryAgentConfig.memory } } : {}),
 		...(outputPath ? { outputPath } : {}),
 		outputMode,
 		...(params.structuredOutputSchema ? { structuredOutputSchema: params.structuredOutputSchema } : {}),
 		...(params.acceptance !== undefined ? { acceptance: params.acceptance } : {}),
 		...(controlConfig ? { controlConfig } : {}),
+		...(params.intercomBridge !== undefined ? { intercomBridge: params.intercomBridge } : {}),
 		...(deadlineAt !== undefined ? { absoluteDeadlineAt: deadlineAt } : {}),
 		...(initialTurnBudget ? { initialTurnBudget: { maxTurns: initialTurnBudget.maxTurns, graceTurns: initialTurnBudget.graceTurns } } : {}),
 		...(resolvedToolBudget.budget ? { initialToolBudget: resolvedToolBudget.budget } : {}),
-		maxSubagentDepth: resolveChildMaxSubagentDepth(maxSubagentDepth, agentConfig.maxSubagentDepth),
+		maxSubagentDepth: resolveChildMaxSubagentDepth(maxSubagentDepth, recoveryAgentConfig.maxSubagentDepth),
 		...(maxOutput ? { maxOutput } : {}),
 		share: shareEnabled,
 		...(resolvedSessionDir ? { sessionDir: resolvedSessionDir } : {}),
@@ -1654,6 +1641,7 @@ export function executeAsyncSingle(
 			goal: (params.goal ?? task).trim() ? PROMPT_REDACTED : undefined,
 			cwd: runnerCwd,
 			asyncDir,
+			...(sessionRoot ? { sessionRoot } : {}),
 			launchContractDigest,
 			launchResolvedExtensions,
 			...(params.parentWorkflowRunId ? { parentWorkflowRunId: params.parentWorkflowRunId } : {}),

package/src/runs/background/async-job-tracker.ts

@@ -557,10 +557,13 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 		const agents = firstGroupCount && firstGroupCount > 0
 			? rawAgents?.slice(0, firstGroupCount)
 			: rawAgents;
+		const sessionRoot = state.liveAsyncSessionRoots?.get(info.id);
+		state.liveAsyncSessionRoots?.delete(info.id);
 		state.asyncJobs.set(info.id, {
 			asyncId: info.id,
 			asyncDir,
 			...(typeof info.cwd === "string" ? { cwd: path.resolve(info.cwd) } : {}),
+			...(sessionRoot ? { sessionRoot } : {}),
 			status: "queued",
 			pid: typeof info.pid === "number" ? info.pid : undefined,
 			...(typeof info.sessionId === "string" ? { sessionId: info.sessionId } : {}),
@@ -637,6 +640,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 		state.asyncJobs.clear();
 		state.fleetJobs?.clear();
 		state.foregroundControls?.clear();
+		state.liveAsyncSessionRoots?.clear();
 		state.lastForegroundControlId = null;
 		state.resultFileCoalescer.clear();
 		if (ctx?.hasUI) {

package/src/runs/background/async-resume.ts

@@ -307,7 +307,7 @@ export function readAsyncRecoveryDescriptor(asyncDir: string | undefined): Steer
 		"version", "launchContractDigest", "sourceRunId", "agentContract", "agent", "sessionFile", "cwd", "model", "fallbackModels", "thinking", "tools", "extensions",
 		"subagentOnlyExtensions", "mcpDirectTools", "systemPrompt", "systemPromptMode", "inheritProjectContext", "inheritSkills", "skills",
 		"skillPath", "agentFilePath", "completionGuard", "memory", "outputPath", "outputMode", "structuredOutputSchema", "acceptance", "sessionDir", "artifactConfig",
-		"artifactsDir", "maxOutput", "controlConfig", "absoluteDeadlineAt", "initialTurnBudget", "initialToolBudget", "maxSubagentDepth", "share", "capabilityCeiling",
+		"artifactsDir", "maxOutput", "controlConfig", "intercomBridge", "absoluteDeadlineAt", "initialTurnBudget", "initialToolBudget", "maxSubagentDepth", "share", "capabilityCeiling",
 		"launchResolvedExtensions", "runFanoutBudget",
 	]);
 	for (const field of Object.keys(parsed)) {
@@ -374,6 +374,16 @@ export function readAsyncRecoveryDescriptor(asyncDir: string | undefined): Steer
 		if (artifact.includeTranscript !== undefined && typeof artifact.includeTranscript !== "boolean") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': artifactConfig.includeTranscript must be a boolean.`);
 		if (!Number.isInteger(artifact.cleanupDays) || (artifact.cleanupDays as number) < 0) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': artifactConfig.cleanupDays must be a non-negative integer.`);
 	}
+	if (parsed.intercomBridge !== undefined) {
+		if (!parsed.intercomBridge || typeof parsed.intercomBridge !== "object" || Array.isArray(parsed.intercomBridge)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': intercomBridge must be an object.`);
+		const bridge = parsed.intercomBridge as Record<string, unknown>;
+		for (const field of Object.keys(bridge)) {
+			if (field !== "mode" && field !== "instructionFile" && field !== "resultDelivery") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': intercomBridge.${field} is not supported.`);
+		}
+		if (bridge.mode !== undefined && bridge.mode !== "off" && bridge.mode !== "fork-only" && bridge.mode !== "always") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': intercomBridge.mode is invalid.`);
+		if (bridge.instructionFile !== undefined && typeof bridge.instructionFile !== "string") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': intercomBridge.instructionFile must be a string.`);
+		if (bridge.resultDelivery !== undefined && typeof bridge.resultDelivery !== "boolean") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': intercomBridge.resultDelivery must be a boolean.`);
+	}
 	if (parsed.controlConfig !== undefined) {
 		if (!parsed.controlConfig || typeof parsed.controlConfig !== "object" || Array.isArray(parsed.controlConfig)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': controlConfig must be an object.`);
 		const control = parsed.controlConfig as Record<string, unknown>;