pi-cohort 7.1.2 → 7.2.1

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

@@ -3,7 +3,8 @@
  */
 
 import { spawn } from "node:child_process";
-import * as fs from "node:fs";
+import { PINNED_AGENT_DIR_OVERRIDE } from "../../shared/agent-dir.ts";
+import fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -12,8 +13,9 @@ import type { AgentConfig } from "../../agents/agents.ts";
 import { applyThinkingSuffix } from "../shared/pi-args.ts";
 import { injectSingleOutputInstruction, normalizeSingleOutputOverride, resolveParallelTaskOutputPath, resolveSingleOutputPath, validateFileOnlyOutputMode } from "../shared/single-output.ts";
 import { buildChainInstructions, isDynamicParallelStep, isParallelStep, resolveStepBehavior, suppressProgressForReadOnlyTask, writeInitialProgressFile, type ChainStep, type ResolvedStepBehavior, type SequentialStep, type StepOverrides } from "../../shared/settings.ts";
-import type { RunnerStep } from "../shared/parallel-utils.ts";
-import { resolvePiPackageRoot } from "../shared/pi-spawn.ts";
+import { writeAtomicJson } from "../../shared/atomic-json.ts";
+import { isDynamicRunnerGroup, isParallelGroup, type RunnerStep } from "../shared/parallel-utils.ts";
+import { getPiSpawnCommand, PiRuntimeLaunchError, type PiRuntimeIdentity } from "../shared/pi-spawn.ts";
 import { ensureJitiCliPath, resolveHostModuleAliases } from "../shared/jiti-cli.ts";
 export { createJitiCliResolver } from "../shared/jiti-cli.ts";
 import { buildSkillInjection, normalizeSkillInput, resolveSkillsWithFallback } from "../../agents/skills.ts";
@@ -39,14 +41,14 @@ import {
 	RESULTS_DIR,
 	SUBAGENT_ASYNC_STARTED_EVENT,
 	TEMP_ROOT_DIR,
+	RUN_STATE_ROOT_DIR,
 	getAsyncConfigPath,
 	resolveChildMaxSubagentDepth,
 } from "../../shared/types.ts";
 import { nestedResultsPath, resolveInheritedNestedRouteFromEnv, resolveNestedParentAddressFromEnv, writeNestedEvent } from "../shared/nested-events.ts";
 
-const piPackageRoot = resolvePiPackageRoot();
-
 interface AsyncExecutionContext {
+	runtime: PiRuntimeIdentity;
 	pi: ExtensionAPI;
 	cwd: string;
 	currentSessionId: string;
@@ -73,6 +75,7 @@ interface AsyncChainParams {
 	sessionRoot?: string;
 	chainSkills?: string[];
 	sessionFilesByFlatIndex?: (string | undefined)[];
+	originSessionRoot?: string;
 	dynamicFanoutMaxItems?: number;
 	maxSubagentDepth: number;
 	worktreeSetupHook?: string;
@@ -103,6 +106,7 @@ interface AsyncSingleParams {
 	shareEnabled: boolean;
 	sessionRoot?: string;
 	sessionFile?: string;
+	originSessionRoot?: string;
 	skills?: string[];
 	output?: string | boolean;
 	outputMode?: "inline" | "file-only";
@@ -136,8 +140,8 @@ export function formatAsyncStartedMessage(headline: string): string {
 /**
  * Check if jiti is available for async execution
  */
-export function isAsyncAvailable(): boolean {
-	return ensureJitiCliPath() !== undefined;
+export function isAsyncAvailable(runtime: PiRuntimeIdentity): boolean {
+	return ensureJitiCliPath(runtime.piPackageRoot) !== undefined;
 }
 
 /**
@@ -184,18 +188,19 @@ export function spawnDetachedWithLog(command: string, args: string[], cwd: strin
  * Spawn the async runner process
  */
 export function spawnRunner(
-	cfg: object,
+	cfg: { runtime: PiRuntimeIdentity },
 	suffix: string,
 	cwd: string,
 	asyncDir: string,
-	deps: { ensureJiti?: () => string | undefined; spawnImpl?: typeof spawn; hostAliases?: () => Record<string, string> } = {},
+	deps: { ensureJiti?: (root: string) => string | undefined; spawnImpl?: typeof spawn; hostAliases?: (root: string) => Record<string, string> } = {},
 ): { pid?: number; error?: string } {
 	const ensureJiti = deps.ensureJiti ?? ensureJitiCliPath;
-	const jitiCliPath = ensureJiti();
+	const jitiCliPath = ensureJiti(cfg.runtime.piPackageRoot);
 	if (!jitiCliPath) {
-		return { error: "upstream jiti for TypeScript execution could not be found; ensure package dependencies are installed" };
+		throw new PiRuntimeLaunchError(`Cannot resolve jiti from selected Pi installation ${cfg.runtime.piPackageRoot}`);
 	}
 
+	getPiSpawnCommand([], cfg.runtime);
 	try {
 		const cwdStats = fs.statSync(cwd);
 		if (!cwdStats.isDirectory()) {
@@ -210,12 +215,122 @@ export function spawnRunner(
 	fs.writeFileSync(cfgPath, JSON.stringify(cfg));
 	const runner = path.join(path.dirname(fileURLToPath(import.meta.url)), "subagent-runner.ts");
 
-	const aliases = (deps.hostAliases ?? resolveHostModuleAliases)();
+	const aliases = (deps.hostAliases ?? resolveHostModuleAliases)(cfg.runtime.piPackageRoot);
 	const env = Object.keys(aliases).length > 0
 		? { ...process.env, JITI_ALIAS: JSON.stringify(aliases) }
-		: process.env;
+		: { ...process.env };
+	if (PINNED_AGENT_DIR_OVERRIDE) env.PI_CODING_AGENT_DIR = PINNED_AGENT_DIR_OVERRIDE;
+
+	return spawnDetachedWithLog(cfg.runtime.nodeExecPath, [jitiCliPath, runner, cfgPath], cwd, asyncDir, deps.spawnImpl ?? spawn, env);
+}
+
+type NestedStartWriter = (...args: Parameters<typeof writeNestedEvent>) => void | boolean;
 
-	return spawnDetachedWithLog(process.execPath, [jitiCliPath, runner, cfgPath], cwd, asyncDir, deps.spawnImpl ?? spawn, env);
+function publishAndSpawnRunner(
+	cfg: { runtime: PiRuntimeIdentity; id: string; steps: RunnerStep[]; sessionId: string; sessionDir: string; resultMode: SubagentRunMode; [key: string]: unknown },
+	suffix: string,
+	cwd: string,
+	asyncDir: string,
+	origin: { route?: NestedRouteInfo; address?: ReturnType<typeof resolveNestedParentAddressFromEnv>; sessionFile?: string; sessionFiles?: string[]; sessionRoot?: string },
+	writeStart: NestedStartWriter,
+): { pid?: number; error?: string } {
+	const parallelGroups: Array<{ start: number; count: number; stepIndex: number }> = [];
+	const steps: object[] = [];
+	for (const [stepIndex, step] of cfg.steps.entries()) {
+		const leaves = isParallelGroup(step) ? step.parallel : isDynamicRunnerGroup(step) ? [step.parallel] : [step];
+		if (isParallelGroup(step) || isDynamicRunnerGroup(step)) parallelGroups.push({ start: steps.length, count: leaves.length, stepIndex });
+		for (const leaf of leaves) {
+			steps.push({
+				agent: isDynamicRunnerGroup(step) ? `expand:${leaf.agent}` : leaf.agent,
+				phase: isDynamicRunnerGroup(step) ? step.phase ?? leaf.phase : leaf.phase,
+				label: isDynamicRunnerGroup(step) ? step.label ?? leaf.label ?? `Dynamic fanout (${step.collect.as})` : leaf.label,
+				outputName: isDynamicRunnerGroup(step) ? step.collect.as : leaf.outputName,
+				structured: isDynamicRunnerGroup(step) ? Boolean(step.collect.outputSchema) : leaf.structured,
+				status: "pending",
+				...(isDynamicRunnerGroup(step) ? {} : {
+					sessionFile: leaf.sessionFile,
+					skills: leaf.skills,
+					model: leaf.model,
+					thinking: leaf.thinking,
+					attemptedModels: leaf.modelCandidates && leaf.modelCandidates.length > 0 ? leaf.modelCandidates : leaf.model ? [leaf.model] : undefined,
+				}),
+				recentTools: [],
+				recentOutput: [],
+			});
+		}
+	}
+	let preparationError: unknown;
+	try {
+		fs.mkdirSync(cfg.sessionDir, { recursive: true });
+		cfg.sessionDir = fs.realpathSync.native(cfg.sessionDir);
+	} catch (error) {
+		preparationError = error;
+	}
+	const statusPath = path.join(asyncDir, "status.json");
+	const now = Date.now();
+	const status = {
+		runId: cfg.id, runtime: cfg.runtime, sessionId: cfg.sessionId,
+		state: "queued", mode: cfg.resultMode, cwd, currentStep: 0, chainStepCount: cfg.steps.length,
+		startedAt: now, lastUpdate: now, lastActivityAt: now, outputFile: path.join(asyncDir, "output-0.log"), steps, parallelGroups, workflowGraph: cfg.workflowGraph,
+		artifactsDir: cfg.artifactsDir, sessionDir: cfg.sessionDir,
+	};
+	writeAtomicJson(statusPath, status);
+	try {
+		if (preparationError) throw preparationError;
+		let sessionRoot = cfg.sessionDir;
+		if (origin.sessionRoot !== undefined) {
+			if (!origin.sessionFile && !origin.sessionFiles?.length) throw new Error("Origin session root requires a reused session file.");
+			if (!path.isAbsolute(origin.sessionRoot)) throw new Error("Origin session root must be absolute.");
+			let stat: fs.Stats;
+			try {
+				stat = fs.statSync(origin.sessionRoot);
+			} catch {
+				throw new Error("Origin session root must exist.");
+			}
+			if (!stat.isDirectory()) throw new Error("Origin session root must be a directory.");
+			sessionRoot = fs.realpathSync.native(origin.sessionRoot);
+			if (sessionRoot !== origin.sessionRoot) throw new Error("Origin session root must be canonical and cannot be retargeted.");
+		}
+		const effectiveFiles = origin.sessionFiles ?? (origin.sessionFile ? [origin.sessionFile] : []);
+		if (origin.sessionRoot) {
+			const contains = (candidate: string) => {
+				const relative = path.relative(sessionRoot, candidate);
+				return relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+			};
+			if (origin.sessionFiles && !contains(cfg.sessionDir)) throw new Error("Runner session directory is outside origin session root.");
+			for (const file of effectiveFiles) {
+				if (!fs.existsSync(file)) throw new Error("Reused session file must be an existing regular .jsonl file.");
+				const stat = fs.lstatSync(file);
+				if (!stat.isFile() || stat.isSymbolicLink() || path.extname(file) !== ".jsonl") throw new Error("Reused session file must be a regular .jsonl file.");
+				if (!contains(fs.realpathSync.native(file))) throw new Error("Reused session file is outside origin session root.");
+			}
+		}
+		if (origin.route && origin.address) {
+			if (effectiveFiles.some(file => fs.existsSync(file)) && !origin.sessionRoot) throw new Error("Origin session root is required for a reused nested session.");
+			const firstLeaf = isParallelGroup(cfg.steps[0]) ? cfg.steps[0].parallel[0] : isDynamicRunnerGroup(cfg.steps[0]) ? cfg.steps[0].parallel : cfg.steps[0];
+			const agents = cfg.steps.flatMap(step => isParallelGroup(step) ? step.parallel.map(leaf => leaf.agent) : isDynamicRunnerGroup(step) ? [step.parallel.agent] : [step.agent]);
+			try {
+				if (writeStart(origin.route, {
+					type: "subagent.nested.started", ts: now,
+					parentRunId: origin.address.parentRunId, parentStepIndex: origin.address.parentStepIndex,
+					child: {
+						id: cfg.id, ...origin.address, asyncDir, sessionId: cfg.sessionId, capabilityToken: origin.route.capabilityToken,
+						runtime: cfg.runtime, sessionRoot, mode: cfg.resultMode, state: "queued",
+						agent: firstLeaf?.agent, agents, chainStepCount: cfg.steps.length, parallelGroups,
+						startedAt: now, lastUpdate: now,
+					},
+				}) === false) throw new Error("Nested origin stamp was refused.");
+			} catch (error) {
+				throw new Error(`Failed to stamp nested origin: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+			}
+		}
+		const result = spawnRunner(cfg, suffix, cwd, asyncDir);
+		if (result.error) throw new Error(result.error);
+		return result;
+	} catch (error) {
+		writeAtomicJson(statusPath, { ...status, state: "failed", error: error instanceof Error ? error.message : String(error), lastUpdate: Date.now() });
+		throw error;
+	}
 }
 
 /**
@@ -245,6 +360,7 @@ class AsyncStartValidationError extends Error {}
 export function executeAsyncChain(
 	id: string,
 	params: AsyncChainParams,
+	writeStart: NestedStartWriter = writeNestedEvent,
 ): AsyncExecutionResult {
 	const {
 		chain,
@@ -304,10 +420,11 @@ export function executeAsyncChain(
 	const inheritedNestedRoute = resolveInheritedNestedRouteFromEnv();
 	const nestedAddress = inheritedNestedRoute ? resolveNestedParentAddressFromEnv() : undefined;
 	const asyncDir = inheritedNestedRoute
-		? path.join(TEMP_ROOT_DIR, "nested-subagent-runs", inheritedNestedRoute.rootRunId, id)
+		? path.join(RUN_STATE_ROOT_DIR, "nested-subagent-runs", inheritedNestedRoute.rootRunId, id)
 		: path.join(ASYNC_DIR, id);
 	try {
-		fs.mkdirSync(asyncDir, { recursive: true });
+		fs.mkdirSync(path.dirname(asyncDir), { recursive: true });
+		fs.mkdirSync(asyncDir);
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
 		return {
@@ -486,7 +603,7 @@ export function executeAsyncChain(
 
 	let spawnResult: { pid?: number; error?: string } = {};
 	try {
-		spawnResult = spawnRunner(
+		spawnResult = publishAndSpawnRunner(
 			{
 				id,
 				steps,
@@ -497,11 +614,10 @@ export function executeAsyncChain(
 				artifactsDir: artifactConfig.enabled ? artifactsDir : undefined,
 				artifactConfig,
 				share: shareEnabled,
-				sessionDir: sessionRoot ? path.join(sessionRoot, `async-${id}`) : undefined,
+				sessionDir: path.join(sessionRoot ?? path.join(RUN_STATE_ROOT_DIR, "sessions"), `async-${id}`),
 				asyncDir,
 				sessionId: ctx.currentSessionId,
-				piPackageRoot,
-				piArgv1: process.argv[1],
+				runtime: ctx.runtime,
 				forwardedFlags,
 				worktreeSetupHook,
 				worktreeSetupHookTimeoutMs,
@@ -521,6 +637,15 @@ export function executeAsyncChain(
 			id,
 			runnerCwd,
 			asyncDir,
+			{
+				route: inheritedNestedRoute,
+				address: nestedAddress,
+				sessionFiles: steps
+					.flatMap(step => isParallelGroup(step) ? step.parallel : isDynamicRunnerGroup(step) ? [step.parallel] : [step])
+					.flatMap(step => step.sessionFile ? [step.sessionFile] : []),
+				sessionRoot: params.originSessionRoot,
+			},
+			writeStart,
 		);
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
@@ -556,37 +681,6 @@ export function executeAsyncChain(
 				flatStepStart++;
 			}
 		}
-		if (inheritedNestedRoute && nestedAddress) {
-			const now = Date.now();
-			try {
-				writeNestedEvent(inheritedNestedRoute, {
-					type: "subagent.nested.started",
-					ts: now,
-					parentRunId: nestedAddress.parentRunId,
-					parentStepIndex: nestedAddress.parentStepIndex,
-					child: {
-						id,
-						parentRunId: nestedAddress.parentRunId,
-						parentStepIndex: nestedAddress.parentStepIndex,
-						depth: nestedAddress.depth,
-						path: nestedAddress.path,
-						asyncDir,
-						pid: spawnResult.pid,
-						ownerState: "live",
-						mode: resultMode,
-						state: "running",
-						agent: firstAgents[0],
-						agents: flatAgents,
-						chainStepCount: chain.length,
-						parallelGroups,
-						startedAt: now,
-						lastUpdate: now,
-					},
-				});
-			} catch (error) {
-				console.error("Failed to emit nested async start event:", error);
-			}
-		}
 		ctx.pi.events.emit(SUBAGENT_ASYNC_STARTED_EVENT, {
 			id,
 			pid: spawnResult.pid,
@@ -629,6 +723,7 @@ export function executeAsyncChain(
 export function executeAsyncSingle(
 	id: string,
 	params: AsyncSingleParams,
+	writeStart: NestedStartWriter = writeNestedEvent,
 ): AsyncExecutionResult {
 	const {
 		agent,
@@ -663,10 +758,11 @@ export function executeAsyncSingle(
 	const inheritedNestedRoute = resolveInheritedNestedRouteFromEnv();
 	const nestedAddress = inheritedNestedRoute ? resolveNestedParentAddressFromEnv() : undefined;
 	const asyncDir = inheritedNestedRoute
-		? path.join(TEMP_ROOT_DIR, "nested-subagent-runs", inheritedNestedRoute.rootRunId, id)
+		? path.join(RUN_STATE_ROOT_DIR, "nested-subagent-runs", inheritedNestedRoute.rootRunId, id)
 		: path.join(ASYNC_DIR, id);
 	try {
-		fs.mkdirSync(asyncDir, { recursive: true });
+		fs.mkdirSync(path.dirname(asyncDir), { recursive: true });
+		fs.mkdirSync(asyncDir);
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
 		return {
@@ -687,7 +783,7 @@ export function executeAsyncSingle(
 	const model = applyThinkingSuffix(resolveModelCandidate(primaryRaw, availableModels, ctx.currentModelProvider), thinking);
 	let spawnResult: { pid?: number; error?: string } = {};
 	try {
-		spawnResult = spawnRunner(
+		spawnResult = publishAndSpawnRunner(
 			{
 				id,
 				steps: [
@@ -728,11 +824,10 @@ export function executeAsyncSingle(
 				artifactsDir: artifactConfig.enabled ? artifactsDir : undefined,
 				artifactConfig,
 				share: shareEnabled,
-				sessionDir: sessionRoot ? path.join(sessionRoot, `async-${id}`) : undefined,
+				sessionDir: path.join(sessionRoot ?? path.join(RUN_STATE_ROOT_DIR, "sessions"), `async-${id}`),
 				asyncDir,
 				sessionId: ctx.currentSessionId,
-				piPackageRoot,
-				piArgv1: process.argv[1],
+				runtime: ctx.runtime,
 				forwardedFlags,
 				worktreeSetupHook,
 				worktreeSetupHookTimeoutMs,
@@ -750,6 +845,8 @@ export function executeAsyncSingle(
 			id,
 			runnerCwd,
 			asyncDir,
+			{ route: inheritedNestedRoute, address: nestedAddress, sessionFile, sessionRoot: params.originSessionRoot },
+			writeStart,
 		);
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
@@ -761,36 +858,6 @@ export function executeAsyncSingle(
 	}
 
 	if (spawnResult.pid) {
-		if (inheritedNestedRoute && nestedAddress) {
-			const now = Date.now();
-			try {
-				writeNestedEvent(inheritedNestedRoute, {
-					type: "subagent.nested.started",
-					ts: now,
-					parentRunId: nestedAddress.parentRunId,
-					parentStepIndex: nestedAddress.parentStepIndex,
-					child: {
-						id,
-						parentRunId: nestedAddress.parentRunId,
-						parentStepIndex: nestedAddress.parentStepIndex,
-						depth: nestedAddress.depth,
-						path: nestedAddress.path,
-						asyncDir,
-						pid: spawnResult.pid,
-						ownerState: "live",
-						mode: "single",
-						state: "running",
-						agent,
-						agents: [agent],
-						chainStepCount: 1,
-						startedAt: now,
-						lastUpdate: now,
-					},
-				});
-			} catch (error) {
-				console.error("Failed to emit nested async start event:", error);
-			}
-		}
 		ctx.pi.events.emit(SUBAGENT_ASYNC_STARTED_EVENT, {
 			id,
 			pid: spawnResult.pid,

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

@@ -140,7 +140,10 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 				try {
 					emitNewControlEvents(job);
 					reconcileNestedDescendants();
-					const reconciliation = reconcileAsyncRun(job.asyncDir, {
+					const stored = readStatus(job.asyncDir);
+					const reconciliation = stored && stored.state !== "running" && stored.state !== "queued"
+						? { status: stored }
+						: reconcileAsyncRun(job.asyncDir, {
 						resultsDir,
 						kill: options.kill,
 						now: options.now,

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

@@ -1,7 +1,12 @@
-import * as fs from "node:fs";
+import fs from "node:fs";
 import * as path from "node:path";
-import { ASYNC_DIR, RESULTS_DIR, type AsyncStatus } from "../../shared/types.ts";
+import { ASYNC_DIR, LEGACY_ASYNC_DIR, RESULTS_DIR, type AsyncStatus } from "../../shared/types.ts";
 import { reconcileAsyncRun } from "./stale-run-reconciler.ts";
+import { parsePiRuntime, type PiRuntimeIdentity } from "../shared/pi-spawn.ts";
+
+export function isLegacyAsyncDir(asyncDir: string): boolean {
+	try { assertInsideRoot(LEGACY_ASYNC_DIR, asyncDir, "Async run directory"); return true; } catch { return false; }
+}
 
 export interface AsyncResumeParams {
 	id?: string;
@@ -11,7 +16,7 @@ export interface AsyncResumeParams {
 }
 
 export interface AsyncResumeDeps {
-	asyncDirRoot?: string;
+	asyncDirRoot?: string | readonly string[];
 	resultsDir?: string;
 	kill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean;
 	now?: () => number;
@@ -19,6 +24,7 @@ export interface AsyncResumeDeps {
 
 export type AsyncResumeTarget = {
 	kind: "revive";
+	runtime: PiRuntimeIdentity;
 	runId: string;
 	asyncDir?: string;
 	state: AsyncStatus["state"];
@@ -29,6 +35,7 @@ export type AsyncResumeTarget = {
 };
 
 interface AsyncResultFile {
+	runtime?: unknown;
 	id?: string;
 	runId?: string;
 	agent?: string;
@@ -82,6 +89,7 @@ function validateResultFile(value: unknown, resultPath: string): AsyncResultFile
 	const success = data.success;
 	if (success !== undefined && typeof success !== "boolean") throw new Error(`Invalid async result file '${resultPath}': success must be a boolean.`);
 	return {
+		runtime: data.runtime,
 		id: validateOptionalString(data, "id", resultPath),
 		runId: validateOptionalString(data, "runId", resultPath),
 		agent: validateOptionalString(data, "agent", resultPath),
@@ -124,9 +132,16 @@ function assertRunId(value: string | undefined, field: "id" | "runId"): string |
 	return value;
 }
 
+function canonicalPath(value: string): string {
+	const resolved = path.resolve(value);
+	if (fs.existsSync(resolved)) return fs.realpathSync(resolved);
+	const parent = path.dirname(resolved);
+	return parent === resolved ? resolved : path.join(canonicalPath(parent), path.basename(resolved));
+}
+
 function assertInsideRoot(root: string, target: string, label: string): void {
-	const rootPath = path.resolve(root);
-	const targetPath = path.resolve(target);
+	const rootPath = canonicalPath(root);
+	const targetPath = canonicalPath(target);
 	const relative = path.relative(rootPath, targetPath);
 	if (relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative))) return;
 	throw new Error(`${label} must be inside ${rootPath}.`);
@@ -146,22 +161,34 @@ function exactResultPath(resultsDir: string, runId: string): string | null {
 	return fs.existsSync(resultPath) ? resultPath : null;
 }
 
-export function findAsyncRunPrefixMatches(prefix: string, asyncDirRoot: string, resultsDir: string): Array<{ id: string; location: AsyncRunLocation }> {
+export function winningAsyncRunEntries(asyncDirRoot: string | readonly string[], prefix = ""): Array<{ id: string; root: string; asyncDir: string }> {
+	const winners = new Map<string, { id: string; root: string; asyncDir: string }>();
+	for (const root of typeof asyncDirRoot === "string" ? [asyncDirRoot] : asyncDirRoot) {
+		for (const id of prefixedRunIds(root, prefix)) {
+			if (!winners.has(id)) winners.set(id, { id, root, asyncDir: path.join(path.resolve(root), id) });
+		}
+	}
+	return [...winners.values()].sort((a, b) => a.id.localeCompare(b.id));
+}
+
+export function findAsyncRunPrefixMatches(prefix: string, asyncDirRoot: string | readonly string[], resultsDir: string): Array<{ id: string; location: AsyncRunLocation }> {
 	const requestedId = assertRunId(prefix, "id");
 	if (!requestedId) return [];
-	const asyncRoot = path.resolve(asyncDirRoot);
+	const entries = winningAsyncRunEntries(asyncDirRoot, requestedId);
+	const byId = new Map(entries.map((entry) => [entry.id, entry]));
 	const resultRoot = path.resolve(resultsDir);
 	const matchingIds = [...new Set([
-		...prefixedRunIds(asyncRoot, requestedId),
+		...byId.keys(),
 		...prefixedRunIds(resultRoot, requestedId, ".json"),
 	])].sort();
 	return matchingIds.map((id) => {
-		const asyncDir = path.join(asyncRoot, id);
-		assertInsideRoot(asyncRoot, asyncDir, "Async run directory");
+		const entry = byId.get(id);
+		const asyncDir = entry?.asyncDir;
+		if (entry) assertInsideRoot(entry.root, entry.asyncDir, "Async run directory");
 		return {
 			id,
 			location: {
-				asyncDir: fs.existsSync(asyncDir) ? asyncDir : null,
+				asyncDir: asyncDir && fs.existsSync(asyncDir) ? asyncDir : null,
 				resultPath: exactResultPath(resultRoot, id),
 				resolvedId: id,
 			},
@@ -169,7 +196,28 @@ export function findAsyncRunPrefixMatches(prefix: string, asyncDirRoot: string,
 	});
 }
 
-export function resolveAsyncRunLocation(params: AsyncResumeParams, asyncDirRoot: string, resultsDir: string): AsyncRunLocation {
+export function resolveAsyncRunLocation(params: AsyncResumeParams, asyncDirRoot: string | readonly string[], resultsDir: string): AsyncRunLocation {
+	if (typeof asyncDirRoot !== "string") {
+		if (params.dir) {
+			for (const root of asyncDirRoot) {
+				try { assertInsideRoot(root, params.dir, "Async run directory"); } catch { continue; }
+				return resolveAsyncRunLocation(params, root, resultsDir);
+			}
+			throw new Error("Async run directory must be inside an authorized async root.");
+		}
+		const id = assertRunId(params.id, "id") ?? assertRunId(params.runId, "runId");
+		if (!id) return { asyncDir: null, resultPath: null };
+		const exact = winningAsyncRunEntries(asyncDirRoot, id).find((entry) => entry.id === id);
+		if (exact) {
+			assertInsideRoot(exact.root, exact.asyncDir, "Async run directory");
+			return { asyncDir: exact.asyncDir, resultPath: exactResultPath(resultsDir, id), resolvedId: id };
+		}
+		const resultPath = exactResultPath(resultsDir, id);
+		if (resultPath) return { asyncDir: null, resultPath, resolvedId: id };
+		const matches = findAsyncRunPrefixMatches(id, asyncDirRoot, resultsDir);
+		if (matches.length > 1) throw new Error(`Ambiguous async run id prefix '${id}' matched: ${matches.map((match) => match.id).join(", ")}. Provide a longer id.`);
+		return matches[0]?.location ?? { asyncDir: null, resultPath: null, resolvedId: id };
+	}
 	const asyncRoot = path.resolve(asyncDirRoot);
 	const resultRoot = path.resolve(resultsDir);
 	const requestedId = assertRunId(params.id, "id") ?? assertRunId(params.runId, "runId");
@@ -234,23 +282,50 @@ function validateResumeSessionFile(runId: string, sessionFile: string): string {
 }
 
 export function resolveAsyncResumeTarget(params: AsyncResumeParams, deps: AsyncResumeDeps = {}): AsyncResumeTarget {
-	const asyncDirRoot = deps.asyncDirRoot ?? ASYNC_DIR;
+	const asyncDirRoot = deps.asyncDirRoot ?? [ASYNC_DIR, LEGACY_ASYNC_DIR];
 	const resultsDir = deps.resultsDir ?? RESULTS_DIR;
 	const location = resolveAsyncRunLocation(params, asyncDirRoot, resultsDir);
 	if (!location.asyncDir && !location.resultPath) {
 		throw new Error("Async run not found. Provide id or dir.");
 	}
 
-	const reconciliation = location.asyncDir
-		? reconcileAsyncRun(location.asyncDir, { resultsDir, kill: deps.kill, now: deps.now })
-		: undefined;
-	const status = reconciliation?.status ?? null;
+	const statusPath = location.asyncDir ? path.join(location.asyncDir, "status.json") : undefined;
+	let status: AsyncStatus | null = null;
+	if (statusPath) {
+		let present = false;
+		try {
+			fs.lstatSync(statusPath);
+			present = true;
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+				throw new Error(`Failed to inspect async status file '${statusPath}': ${getErrorMessage(error)}`, { cause: error });
+			}
+		}
+		if (present) {
+			let value: unknown;
+			try {
+				value = JSON.parse(fs.readFileSync(statusPath, "utf-8"));
+			} catch (error) {
+				throw new Error(`Failed to read or parse async status file '${statusPath}': ${getErrorMessage(error)}`, { cause: error });
+			}
+			status = ensureObject(value, statusPath) as unknown as AsyncStatus;
+		}
+	}
+	if (status && (status.state === "queued" || status.state === "running") && location.asyncDir && !isLegacyAsyncDir(location.asyncDir)) {
+		status = reconcileAsyncRun(location.asyncDir, { resultsDir, kill: deps.kill, now: deps.now }).status ?? status;
+	}
 	validateStatusForResume(status, location.asyncDir ? path.join(location.asyncDir, "status.json") : "status.json");
 	const result = location.resultPath ? readResultFile(location.resultPath) : undefined;
+	const runtime = parsePiRuntime(status ? status.runtime : result?.runtime, statusPath ?? location.resultPath ?? "Async run");
+	if (status && result?.runtime !== undefined) {
+		const other = parsePiRuntime(result.runtime, location.resultPath!);
+		if (runtime.nodeExecPath !== other.nodeExecPath || runtime.piEntryPath !== other.piEntryPath || runtime.piPackageRoot !== other.piPackageRoot) throw new Error("Async status and result runtime identities conflict; a new run is required.");
+	}
 	const runId = status?.runId ?? result?.runId ?? result?.id ?? location.resolvedId ?? (location.asyncDir ? path.basename(location.asyncDir) : "unknown");
 	const state = status?.state ?? (result ? resultState(result) : undefined);
 	if (!state) throw new Error(`Status file not found for async run '${runId}'.`);
 
+	if (state === "queued") throw new Error(`Async run '${runId}' is queued and cannot be revived before startup.`);
 	const statusSteps = status?.steps ?? [];
 	const resultSteps = result?.results ?? [];
 	const stepCount = statusSteps.length || resultSteps.length || (result?.agent ? 1 : 0);
@@ -288,6 +363,7 @@ export function resolveAsyncResumeTarget(params: AsyncResumeParams, deps: AsyncR
 
 	return {
 		kind: "revive",
+		runtime,
 		runId,
 		asyncDir: location.asyncDir ?? undefined,
 		state,

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

@@ -2,9 +2,10 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { formatDuration, formatModelThinking, formatTokens, shortenPath } from "../../shared/formatters.ts";
 import { formatActivityLabel, formatParallelOutcome } from "../../shared/status-format.ts";
-import { type ActivityState, type AsyncJobStep, type AsyncParallelGroupStatus, type AsyncStatus, type NestedRunSummary, type SubagentRunMode, type TokenUsage } from "../../shared/types.ts";
+import { RESULTS_DIR, type ActivityState, type AsyncJobStep, type AsyncParallelGroupStatus, type AsyncStatus, type NestedRunSummary, type SubagentRunMode, type TokenUsage } from "../../shared/types.ts";
+import { isLegacyAsyncDir, resolveAsyncRunLocation, winningAsyncRunEntries } from "./async-resume.ts";
 import { readStatus } from "../../shared/utils.ts";
-import { attachRootChildrenToSteps, findNestedRouteForRootId, projectNestedRegistryForRoot } from "../shared/nested-events.ts";
+import { attachRootChildrenToSteps, findNestedRouteForRootId, isLegacyNestedRoute, projectNestedRegistryForRoot } from "../shared/nested-events.ts";
 import { formatNestedRunStatusLines } from "../shared/nested-render.ts";
 import { flatToLogicalStepIndex, normalizeParallelGroups } from "./parallel-groups.ts";
 import { readRunnerLogTail, reconcileAsyncRun, reconcileNestedAsyncDescendants } from "./stale-run-reconciler.ts";
@@ -133,7 +134,7 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
 	let nestedChildren: NestedRunSummary[] = [];
 	if (nestedWarnings.length === 0) {
 		try {
-			nestedChildren = projectNestedRegistryForRoot(status.runId || path.basename(asyncDir))?.children ?? [];
+			nestedChildren = projectNestedRegistryForRoot(status.runId || path.basename(asyncDir), { readOnlyLegacy: true })?.children ?? [];
 		} catch (error) {
 			nestedWarnings.push(`Nested status unavailable: ${getErrorMessage(error)}`);
 		}
@@ -242,10 +243,10 @@ function summarizePreStatusCrash(asyncDir: string, now: number): AsyncRunSummary
 	};
 }
 
-export function listAsyncRuns(asyncDirRoot: string, options: AsyncRunListOptions = {}): AsyncRunSummary[] {
-	let entries: string[];
+export function listAsyncRuns(asyncDirRoot: string | readonly string[], options: AsyncRunListOptions = {}): AsyncRunSummary[] {
+	let entries: ReturnType<typeof winningAsyncRunEntries>;
 	try {
-		entries = fs.readdirSync(asyncDirRoot).filter((entry) => isAsyncRunDir(asyncDirRoot, entry));
+		entries = winningAsyncRunEntries(asyncDirRoot);
 	} catch (error) {
 		if (isNotFoundError(error)) return [];
 		throw new Error(`Failed to list async runs in '${asyncDirRoot}': ${getErrorMessage(error)}`, {
@@ -256,8 +257,10 @@ export function listAsyncRuns(asyncDirRoot: string, options: AsyncRunListOptions
 	const allowedStates = options.states ? new Set(options.states) : undefined;
 	const runs: AsyncRunSummary[] = [];
 	for (const entry of entries) {
-		const asyncDir = path.join(asyncDirRoot, entry);
-		const reconciliation = options.reconcile === false
+		const asyncDir = resolveAsyncRunLocation({ id: entry.id }, entry.root, options.resultsDir ?? RESULTS_DIR).asyncDir;
+		if (!asyncDir || !isAsyncRunDir(entry.root, entry.id)) continue;
+		const stored = readStatus(asyncDir);
+		const reconciliation = options.reconcile === false || isLegacyAsyncDir(asyncDir) || (stored && stored.state !== "running" && stored.state !== "queued")
 			? undefined
 			: reconcileAsyncRun(asyncDir, { resultsDir: options.resultsDir, kill: options.kill, now: options.now });
 		const status = (reconciliation?.status ?? readStatus(asyncDir)) as (AsyncStatus & { cwd?: string }) | null;
@@ -269,7 +272,7 @@ export function listAsyncRuns(asyncDirRoot: string, options: AsyncRunListOptions
 		const nestedWarnings: string[] = [];
 		try {
 			const nestedRoute = findNestedRouteForRootId(status.runId || path.basename(asyncDir));
-			if (nestedRoute) reconcileNestedAsyncDescendants(nestedRoute, { resultsDir: options.resultsDir, kill: options.kill, now: options.now });
+			if (nestedRoute && !isLegacyAsyncDir(asyncDir) && !isLegacyNestedRoute(nestedRoute)) reconcileNestedAsyncDescendants(nestedRoute, { resultsDir: options.resultsDir, kill: options.kill, now: options.now });
 		} catch (error) {
 			nestedWarnings.push(`Nested status unavailable: ${getErrorMessage(error)}`);
 		}