pi-cohort 7.1.1 → 7.2.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [7.2.0] - 2026-10-11
+
+### Changed
+
+- Children and detached coordinators launch with the originating parent's Node/Pi paths instead of `PATH`; revival keeps that runtime across parent installations. Run records and nested state use durable profile storage without automatic age expiry. Legacy records remain inspectable in their original paths, but revival requires a recorded original runtime and an available session file; missing installations require restoration or a new run. (#19)
+
+## [7.1.2] - 2026-09-29
+
+### Fixed
+
+- `typebox` moves from `dependencies` to an optional `peerDependencies: "*"` entry, which silences pi's "Host-provided extension packages must be declared in peerDependencies" startup warning and removes the second typebox copy from consumer installs. The detached async runner keeps working without its own copy: `spawnRunner` now passes pi's own `typebox`, `typebox/compile`, and `typebox/value` files to the bare jiti child through `JITI_ALIAS`, the same alias map pi's extension loader applies in-process, so the `Cannot find module 'typebox/compile'` crash from [#9](https://github.com/jjuraszek/pi-cohort/issues/9) stays fixed.
+
 ## [7.1.1] - 2026-09-24
 
 ### Changed

package/README.md

@@ -39,6 +39,8 @@ pi install npm:pi-cohort
 
 That is the only required step.
 
+Children and detached coordinators use the originating parent's resolved Node executable and Pi entry path directly, bypassing `PATH`. Revival keeps that original runtime even when requested from a different parent installation. Custom hosts whose entry cannot be identified as the installed Pi package's declared CLI are unsupported. These paths are not a version lock: replacing Node or Pi in place changes what runs. If the original installation is removed, restore it at the recorded paths or start a new run; there is no fallback to the current parent's installation. Legacy records without an original runtime identity remain inspectable but cannot be revived - start a new run.
+
 ## Execution backend extension API
 
 External execution backends are currently unsupported on Windows, for both foreground and background runs. Native execution remains supported.
@@ -155,6 +157,10 @@ Full reference: agent/chain authoring in [doc/agents-and-chains.md](doc/agents-a
 
 Most installs need zero configuration. Full env/JSON reference: [doc/configuration.md](doc/configuration.md).
 
+Run history lives under the pinned profile's `pi-cohort/` root and has no automatic age expiry. Status listings can grow without bound as history accumulates. To remove history manually, delete only a terminal top-level run directory after confirming its entire subtree has stopped; never delete queued or running state, individual nested records, or shared route files. This removes that directory's status and resume lookup, not separately stored session files or shared routes. Keep those sessions if you need their context; deleting a run directory is not a complete session purge. Storage details: [doc/observability.md](doc/observability.md#files-logs-and-observability).
+
+A queued start that never publishes running status stays unresolved: pi-cohort does not automatically recover or revive it. Start a new run instead.
+
 Parent extension CLI flags (e.g. pi-lens's `--no-autofix`) are forwarded into spawned children by default, so subagents inherit the same tooling behavior you launched with; toggle with [`forwardParentFlags`](doc/configuration.md#forwardparentflags).
 
 Optional companions:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cohort",
-  "version": "7.1.1",
+  "version": "7.2.0",
   "description": "Delegate Pi work to focused child agents: code review, scouting, implementation, parallel audits, saved chains, and background jobs.",
   "author": "Jacek Juraszek",
   "license": "MIT",
@@ -40,8 +40,8 @@
   "scripts": {
     "check:agents-core": "node scripts/check-agents-core.mjs",
     "test": "npm run test:unit",
-    "test:unit": "node --test test/unit/*.test.ts",
-    "test:integration": "node --import ./test/support/register-loader.mjs --test test/integration/*.test.ts",
+    "test:unit": "node --import ./test/support/isolate-test-env.mjs --test test/unit/*.test.ts",
+    "test:integration": "node --import ./test/support/isolate-test-env.mjs --import ./test/support/register-loader.mjs --test test/integration/*.test.ts",
     "test:all": "npm run check:agents-core && npm run test:unit && npm run test:integration"
   },
   "pi": {
@@ -64,7 +64,8 @@
     "@earendil-works/pi-agent-core": "*",
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": ">=0.85.0",
-    "@earendil-works/pi-tui": "*"
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-agent-core": {
@@ -78,16 +79,19 @@
     },
     "@earendil-works/pi-tui": {
       "optional": true
+    },
+    "typebox": {
+      "optional": true
     }
   },
   "dependencies": {
-    "jiti": "^2.7.0",
-    "typebox": "^1.3.11"
+    "jiti": "^2.7.0"
   },
   "devDependencies": {
     "@earendil-works/pi-agent-core": "^0.85.0",
     "@earendil-works/pi-ai": "^0.85.0",
     "@earendil-works/pi-coding-agent": "^0.85.0",
-    "@earendil-works/pi-tui": "^0.85.0"
+    "@earendil-works/pi-tui": "^0.85.0",
+    "typebox": "^1.3.11"
   }
 }

package/src/execution-backend/child-host-controller.ts

@@ -7,18 +7,20 @@ import { ChildHostFrameDecoder, encodeChildHostMessage, type ChildHostMessage }
 import { PI_COHORT_CHILD_HOST_CONFIG } from "./child-host-runtime.ts";
 import { ensureJitiCliPath } from "../runs/shared/jiti-cli.ts";
 import type { ExecutionBackend, ExecutionBackendLease } from "./types.ts";
+import { getPiSpawnCommand, PiRuntimeLaunchError, type PiRuntimeIdentity } from "../runs/shared/pi-spawn.ts";
 
 export interface ChildHostAttempt { readonly attemptId: string; readonly command: string; readonly args: readonly string[]; readonly cwd: string; readonly environment: Readonly<Record<string, string>>; }
 export interface ChildHostExit { readonly status: number | null; readonly signal: string | null; }
 export interface ChildHostController { readonly lease: ExecutionBackendLease; readonly ready: Promise<void>; startAttempt(attempt: ChildHostAttempt): Promise<ChildHostExit>; shutdown(): Promise<void>; releaseObserver(): Promise<void>; }
-export interface ChildHostControllerOptions { readonly backend: ExecutionBackend; readonly runId: string; readonly childId: string; readonly cwd: string; readonly title?: string; readonly signal: AbortSignal; }
-export interface ChildHostControllerDependencies { readonly fs?: typeof fs; readonly ensureJiti?: () => string | undefined; readonly childHostCommand?: () => { command: string; args: readonly string[] }; readonly platform?: NodeJS.Platform; readonly createServer?: typeof net.createServer; }
+export interface ChildHostControllerOptions { readonly runtime: PiRuntimeIdentity; readonly backend: ExecutionBackend; readonly runId: string; readonly childId: string; readonly cwd: string; readonly title?: string; readonly signal: AbortSignal; }
+export interface ChildHostControllerDependencies { readonly fs?: typeof fs; readonly ensureJiti?: (root: string) => string | undefined; readonly childHostCommand?: () => { command: string; args: readonly string[] }; readonly platform?: NodeJS.Platform; readonly createServer?: typeof net.createServer; }
 
 const HOST_ENVIRONMENT_KEYS = ["PATH", "HOME", "TMPDIR", "SystemRoot"] as const;
-function childHostCommand(ensureJiti: () => string | undefined): { command: string; args: readonly string[] } {
-	const jiti = ensureJiti();
-	if (!jiti) throw new Error("upstream jiti for TypeScript execution could not be found; ensure package dependencies are installed");
-	return { command: process.execPath, args: [jiti, path.resolve(path.dirname(fileURLToPath(import.meta.url)), "child-host-runtime.ts")] };
+function childHostCommand(runtime: PiRuntimeIdentity, ensureJiti: (root: string) => string | undefined): { command: string; args: readonly string[] } {
+	getPiSpawnCommand([], runtime);
+	const jiti = ensureJiti(runtime.piPackageRoot);
+	if (!jiti) throw new PiRuntimeLaunchError(`jiti for selected Pi installation ${runtime.piPackageRoot} could not be found`);
+	return { command: runtime.nodeExecPath, args: [jiti, path.resolve(path.dirname(fileURLToPath(import.meta.url)), "child-host-runtime.ts")] };
 }
 function disconnected(phase: string): Error { return new Error(`child host disconnected ${phase}`); }
 function aborted(): Error { return new Error("child host launch aborted"); }
@@ -90,7 +92,7 @@ export async function createChildHostController(options: ChildHostControllerOpti
 					}
 					if (message.kind === "attempt_started" && active?.attemptId === message.attemptId && !active.started) { active.started = true; continue; }
 					if (message.kind === "attempt_spawn_error" && active?.attemptId === message.attemptId) {
-						const pending = active; active = undefined; pending.reject(new Error("child host attempt spawn error")); continue;
+						const pending = active; active = undefined; pending.reject(new PiRuntimeLaunchError(`child host attempt spawn error for ${options.runtime.nodeExecPath} ${options.runtime.piEntryPath}`)); continue;
 					}
 					if (message.kind === "attempt_exited" && active?.attemptId === message.attemptId && active.started) {
 						const pending = active; active = undefined; pending.resolve({ status: message.status, signal: message.signal }); continue;
@@ -115,9 +117,9 @@ export async function createChildHostController(options: ChildHostControllerOpti
 		await new Promise<void>((resolve, reject) => server!.listen(socketPath!, () => resolve()).once("error", reject));
 		fileSystem.chmodSync(socketPath, 0o600);
 		if (options.signal.aborted) throw aborted();
-		const host = dependencies.childHostCommand?.() ?? childHostCommand(dependencies.ensureJiti ?? ensureJitiCliPath);
 		const environment: Record<string, string> = { [PI_COHORT_CHILD_HOST_CONFIG]: configPath };
 		for (const key of HOST_ENVIRONMENT_KEYS) if (process.env[key]) environment[key] = process.env[key]!;
+		const host = dependencies.childHostCommand?.() ?? childHostCommand(options.runtime, dependencies.ensureJiti ?? ensureJitiCliPath);
 		lease = await options.backend.launch({
 			command: host.command,
 			args: host.args,

package/src/extension/doctor.ts

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { discoverAgentsAll, type AgentSource } from "../agents/agents.ts";
+import type { PiRuntimeIdentity } from "../runs/shared/pi-spawn.ts";
 import { isAsyncAvailable } from "../runs/background/async-execution.ts";
 import { discoverAvailableSkills, type SkillSource } from "../agents/skills.ts";
 import {
@@ -20,12 +21,14 @@ interface DoctorPaths {
 }
 
 interface DoctorDeps {
-	isAsyncAvailable: () => boolean;
+	isAsyncAvailable: (runtime: PiRuntimeIdentity) => boolean;
 	discoverAgentsAll: typeof discoverAgentsAll;
 	discoverAvailableSkills: typeof discoverAvailableSkills;
 }
 
 interface DoctorReportInput {
+	runtime?: PiRuntimeIdentity;
+	runtimeError?: string;
 	cwd: string;
 	config: ExtensionConfig;
 	state: SubagentState;
@@ -189,7 +192,8 @@ export function buildDoctorReport(input: DoctorReportInput): string {
 		"",
 		"Runtime",
 		`- cwd: ${input.cwd}`,
-		lineFromCheck("async support", () => `- async support: ${deps.isAsyncAvailable() ? "available" : "unavailable"}`),
+		...(input.runtimeError ? [`- runtime capture: failed - ${input.runtimeError}`] : input.runtime ? [] : ["- runtime capture: not available"]),
+		lineFromCheck("async support", () => `- async support: ${input.runtime && deps.isAsyncAvailable(input.runtime) ? "available" : "unavailable"}`),
 		...formatSessionLines(input),
 		"",
 		"Filesystem",

package/src/extension/fanout-child.ts

@@ -10,7 +10,7 @@ import { readNestedControlRequests, resolveNestedRouteFromEnv, writeNestedContro
 import { SubagentParams } from "./schemas.ts";
 import { loadConfig } from "./config.ts";
 import { deriveForwardedFlags } from "../runs/shared/forward-flags.ts";
-import type { Details, SubagentState } from "../shared/types.ts";
+import { RUN_STATE_ROOT_DIR, type Details, type SubagentState } from "../shared/types.ts";
 import { emptyGrandTotal } from "./grand-total.ts";
 
 function getSubagentSessionRoot(parentSessionFile: string | null): string {
@@ -19,7 +19,7 @@ function getSubagentSessionRoot(parentSessionFile: string | null): string {
 		const sessionsDir = path.dirname(parentSessionFile);
 		return path.join(sessionsDir, baseName);
 	}
-	return fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-session-"));
+	return path.join(RUN_STATE_ROOT_DIR, "sessions");
 }
 
 function expandTilde(p: string): string {

package/src/extension/index.ts

@@ -43,6 +43,7 @@ import {
 	type Details,
 	type SubagentState,
 	ASYNC_DIR,
+	RUN_STATE_ROOT_DIR,
 	DEFAULT_ARTIFACT_CONFIG,
 	GRAND_TOTAL_STATUS_KEY,
 	RESULTS_DIR,
@@ -68,7 +69,7 @@ export { loadConfig } from "./config.ts";
  * If parent session is ~/.pi/agent/sessions/abc123.jsonl,
  * returns ~/.pi/agent/sessions/abc123/ as the base.
  * Callers add runId to create the actual session root: abc123/{runId}/
- * Falls back to a unique temp directory if no parent session.
+ * Without a parent, uses the durable sessions base; callers append the run UUID.
  */
 function getSubagentSessionRoot(parentSessionFile: string | null): string {
 	if (parentSessionFile) {
@@ -76,19 +77,19 @@ function getSubagentSessionRoot(parentSessionFile: string | null): string {
 		const sessionsDir = path.dirname(parentSessionFile);
 		return path.join(sessionsDir, baseName);
 	}
-	return fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-session-"));
+	return path.join(RUN_STATE_ROOT_DIR, "sessions");
 }
 
 function expandTilde(p: string): string {
 	return p.startsWith("~/") ? path.join(os.homedir(), p.slice(2)) : p;
 }
 
-/** Create a directory and verify it is actually accessible. */
-function ensureAccessibleDir(dirPath: string): void {
+function ensureAccessibleDir(dirPath: string, durable = false): void {
 	mkdirWithEpermRetry(dirPath);
 	try {
 		fs.accessSync(dirPath, fs.constants.R_OK | fs.constants.W_OK);
-	} catch {
+	} catch (error) {
+		if (durable) throw error;
 		try {
 			fs.rmSync(dirPath, { recursive: true, force: true });
 		} catch {
@@ -255,8 +256,9 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		}
 	}
 
+	ensureAccessibleDir(RUN_STATE_ROOT_DIR, true);
 	ensureAccessibleDir(RESULTS_DIR);
-	ensureAccessibleDir(ASYNC_DIR);
+	ensureAccessibleDir(ASYNC_DIR, true);
 	cleanupOldChainDirs();
 
 	const config = loadConfig();

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,9 +13,10 @@ 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 { ensureJitiCliPath } from "../shared/jiti-cli.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";
 import { resolveChildCwd } from "../../shared/utils.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;
 }
 
 /**
@@ -145,7 +149,7 @@ export function isAsyncAvailable(): boolean {
  * Falls back to ignored stdio if the log file cannot be opened; the parent always
  * closes its copy of the fd, on every exit path.
  */
-export function spawnDetachedWithLog(command: string, args: string[], cwd: string, asyncDir: string, spawnImpl: typeof spawn = spawn): { pid?: number; error?: string } {
+export function spawnDetachedWithLog(command: string, args: string[], cwd: string, asyncDir: string, spawnImpl: typeof spawn = spawn, env?: NodeJS.ProcessEnv): { pid?: number; error?: string } {
 	let fd: number | undefined;
 	try {
 		try {
@@ -156,6 +160,7 @@ export function spawnDetachedWithLog(command: string, args: string[], cwd: strin
 		}
 		const proc = spawnImpl(command, args, {
 			cwd,
+			env,
 			detached: true,
 			stdio: fd === undefined ? "ignore" : ["ignore", fd, fd],
 			windowsHide: true,
@@ -183,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 } = {},
+	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()) {
@@ -209,7 +215,122 @@ export function spawnRunner(
 	fs.writeFileSync(cfgPath, JSON.stringify(cfg));
 	const runner = path.join(path.dirname(fileURLToPath(import.meta.url)), "subagent-runner.ts");
 
-	return spawnDetachedWithLog(process.execPath, [jitiCliPath, runner, cfgPath], cwd, asyncDir, deps.spawnImpl ?? spawn);
+	const aliases = (deps.hostAliases ?? resolveHostModuleAliases)(cfg.runtime.piPackageRoot);
+	const env = Object.keys(aliases).length > 0
+		? { ...process.env, JITI_ALIAS: JSON.stringify(aliases) }
+		: { ...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;
+
+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;
+	}
 }
 
 /**
@@ -239,6 +360,7 @@ class AsyncStartValidationError extends Error {}
 export function executeAsyncChain(
 	id: string,
 	params: AsyncChainParams,
+	writeStart: NestedStartWriter = writeNestedEvent,
 ): AsyncExecutionResult {
 	const {
 		chain,
@@ -298,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 {
@@ -480,7 +603,7 @@ export function executeAsyncChain(
 
 	let spawnResult: { pid?: number; error?: string } = {};
 	try {
-		spawnResult = spawnRunner(
+		spawnResult = publishAndSpawnRunner(
 			{
 				id,
 				steps,
@@ -491,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,
@@ -515,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);
@@ -550,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,
@@ -623,6 +723,7 @@ export function executeAsyncChain(
 export function executeAsyncSingle(
 	id: string,
 	params: AsyncSingleParams,
+	writeStart: NestedStartWriter = writeNestedEvent,
 ): AsyncExecutionResult {
 	const {
 		agent,
@@ -657,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 {
@@ -681,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: [
@@ -722,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,
@@ -744,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);
@@ -755,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,