pi-cohort 7.1.2 → 7.2.0

package/src/runs/shared/jiti-cli.ts

@@ -1,10 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { createRequire } from "node:module";
-import { resolvePiPackageRoot } from "./pi-spawn.ts";
-
-const require = createRequire(import.meta.url);
-const piPackageRoot = resolvePiPackageRoot();
 
 function resolveJitiCliFromPackageJson(packageJsonPath: string): string | undefined {
 	if (!fs.existsSync(packageJsonPath)) return undefined;
@@ -24,45 +20,18 @@ function resolveJitiCliFromPackageJson(packageJsonPath: string): string | undefi
 	return undefined;
 }
 
-function hostResolveCandidates(specifier: string): Array<() => string | undefined> {
-	return [
-		() => require.resolve(specifier),
-		() => piPackageRoot
-			? createRequire(path.join(piPackageRoot, "package.json")).resolve(specifier)
-			: undefined,
-		() => {
-			if (!process.argv[1]) return undefined;
-			const piEntry = fs.realpathSync(process.argv[1]);
-			return createRequire(piEntry).resolve(specifier);
-		},
-	];
-}
-
-function resolveJitiCliPath(): string | undefined {
+function resolveJitiCliPath(piPackageRoot: string): string | undefined {
+	const require = createRequire(path.join(piPackageRoot, "package.json"));
 	const candidates = [
-		...hostResolveCandidates("jiti/package.json"),
-		() => piPackageRoot ? path.join(piPackageRoot, "node_modules", "jiti", "package.json") : undefined,
+		() => require.resolve("jiti/package.json"),
+		() => path.join(piPackageRoot, "node_modules", "jiti", "package.json"),
 	];
 	for (const candidate of candidates) {
 		try {
-			const packageJsonPath = candidate();
-			if (!packageJsonPath) continue;
-			const cliPath = resolveJitiCliFromPackageJson(packageJsonPath);
+			const cliPath = resolveJitiCliFromPackageJson(candidate());
 			if (cliPath) return cliPath;
 		} catch {
-			// Candidate not available in this install, continue probing.
-		}
-	}
-	return undefined;
-}
-
-function resolveFromHost(specifier: string): string | undefined {
-	for (const candidate of hostResolveCandidates(specifier)) {
-		try {
-			const resolved = candidate();
-			if (resolved) return resolved;
-		} catch {
-			// Candidate not available in this install, continue probing.
+			// Package exports may hide package.json; try the selected install's layout.
 		}
 	}
 	return undefined;
@@ -72,25 +41,25 @@ function resolveFromHost(specifier: string): string | undefined {
 // under the bare jiti CLI, so it gets the same map through JITI_ALIAS.
 const HOST_ALIASED_SPECIFIERS = ["typebox", "typebox/compile", "typebox/value"];
 
-export function resolveHostModuleAliases(): Record<string, string> {
+export function resolveHostModuleAliases(piPackageRoot: string): Record<string, string> {
+	const require = createRequire(path.join(piPackageRoot, "package.json"));
 	const aliases: Record<string, string> = {};
 	for (const specifier of HOST_ALIASED_SPECIFIERS) {
-		const resolved = resolveFromHost(specifier);
-		if (resolved) aliases[specifier] = resolved;
+		try {
+			aliases[specifier] = require.resolve(specifier);
+		} catch (cause) {
+			throw new Error(`Cannot resolve required alias ${specifier} from selected Pi installation ${piPackageRoot}`, { cause });
+		}
 	}
 	return aliases;
 }
 
-export function createJitiCliResolver(deps: { resolve?: () => string | undefined; exists?: (p: string) => boolean } = {}): () => string | undefined {
+export function createJitiCliResolver(deps: { resolve?: (piPackageRoot: string) => string | undefined; exists?: (p: string) => boolean } = {}): (piPackageRoot: string) => string | undefined {
 	const resolve = deps.resolve ?? resolveJitiCliPath;
 	const exists = deps.exists ?? ((p: string) => fs.existsSync(p));
-	let cached = resolve();
-	return () => {
-		if (cached && exists(cached)) return cached;
-		cached = resolve();
-		if (cached && exists(cached)) return cached;
-		cached = undefined;
-		return undefined;
+	return (piPackageRoot) => {
+		const cliPath = resolve(piPackageRoot);
+		return cliPath && exists(cliPath) ? cliPath : undefined;
 	};
 }
 

package/src/runs/shared/nested-events.ts

@@ -3,6 +3,8 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import {
 	ASYNC_DIR,
+	LEGACY_ASYNC_DIR,
+	RUN_STATE_ROOT_DIR,
 	RESULTS_DIR,
 	TEMP_ROOT_DIR,
 	type AsyncJobState,
@@ -25,9 +27,11 @@ import {
 	SUBAGENT_PARENT_ROOT_RUN_ID_ENV,
 	SUBAGENT_PARENT_RUN_ID_ENV,
 } from "./pi-args.ts";
+import { parsePiRuntime } from "./pi-spawn.ts";
 import { writeAtomicJson } from "../../shared/atomic-json.ts";
 
-export const NESTED_EVENTS_DIR = path.join(TEMP_ROOT_DIR, "nested-subagent-events");
+export const NESTED_EVENTS_DIR = path.join(RUN_STATE_ROOT_DIR, "nested-subagent-events");
+const LEGACY_NESTED_EVENTS_DIR = path.join(TEMP_ROOT_DIR, "nested-subagent-events");
 const ROUTE_FILE = "route.json";
 const REGISTRY_FILE = "registry.json";
 const MAX_EVENT_BYTES = 64 * 1024;
@@ -92,8 +96,19 @@ function assertSafeId(label: string, value: string): void {
 }
 
 function containedPath(base: string, candidate: string): boolean {
-	const resolvedBase = path.resolve(base);
-	const resolvedCandidate = path.resolve(candidate);
+	const lexicalBase = path.resolve(base);
+	const lexicalCandidate = path.resolve(candidate);
+	if (lexicalCandidate !== lexicalBase && !lexicalCandidate.startsWith(`${lexicalBase}${path.sep}`)) return false;
+	const canonical = (value: string): string => {
+		const resolved = path.resolve(value);
+		try { return fs.realpathSync(resolved); } catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+			const parent = path.dirname(resolved);
+			return parent === resolved ? resolved : path.join(canonical(parent), path.basename(resolved));
+		}
+	};
+	const resolvedBase = canonical(base);
+	const resolvedCandidate = canonical(candidate);
 	return resolvedCandidate === resolvedBase || resolvedCandidate.startsWith(`${resolvedBase}${path.sep}`);
 }
 
@@ -104,8 +119,9 @@ function commonRouteRoot(route: Pick<NestedRoute, "eventSink" | "controlInbox">)
 function validateRouteShape(route: NestedRoute): void {
 	assertSafeId("rootRunId", route.rootRunId);
 	assertSafeId("capabilityToken", route.capabilityToken);
-	if (!containedPath(NESTED_EVENTS_DIR, route.eventSink)) throw new Error("Nested event sink is outside the subagent nested event root.");
-	if (!containedPath(NESTED_EVENTS_DIR, route.controlInbox)) throw new Error("Nested control inbox is outside the subagent nested event root.");
+	const root = [NESTED_EVENTS_DIR, LEGACY_NESTED_EVENTS_DIR].find((base) => containedPath(base, route.eventSink));
+	if (!root) throw new Error("Nested event sink is outside the subagent nested event root.");
+	if (!containedPath(root, route.controlInbox)) throw new Error("Nested control inbox is outside the subagent nested event root.");
 	if (commonRouteRoot(route) !== path.dirname(path.resolve(route.controlInbox))) throw new Error("Nested event sink and control inbox must share one route root.");
 }
 
@@ -158,11 +174,12 @@ export function resolveNestedParentAddressFromEnv(env: NodeJS.ProcessEnv = proce
 }
 
 export function resolveNestedAsyncDir(rootRunId: string, run: NestedRunSummary): string | undefined {
-	if (!run.asyncDir) return undefined;
+	if (!run.asyncDir || !isSafeNestedId(rootRunId) || !isSafeNestedId(run.id)) return undefined;
 	const resolved = path.resolve(run.asyncDir);
-	const nestedRoot = path.resolve(TEMP_ROOT_DIR, "nested-subagent-runs", rootRunId, run.id);
-	const relative = path.relative(nestedRoot, resolved);
-	return resolved === nestedRoot || (!relative.startsWith("..") && !path.isAbsolute(relative)) ? resolved : undefined;
+	return [RUN_STATE_ROOT_DIR, TEMP_ROOT_DIR].some((base) => {
+		const root = path.join(base, "nested-subagent-runs");
+		return containedPath(root, resolved) && containedPath(path.join(root, rootRunId, run.id), resolved);
+	}) ? resolved : undefined;
 }
 
 function clampNumber(value: unknown): number | undefined {
@@ -190,7 +207,7 @@ function sanitizeState(value: unknown, fallback: NestedRunState): NestedRunState
 		: fallback;
 }
 
-function sanitizeStep(input: unknown, depth: number): NestedStepSummary | undefined {
+function sanitizeStep(input: unknown, depth: number, privateOrigin = false): NestedStepSummary | undefined {
 	if (!input || typeof input !== "object") return undefined;
 	const raw = input as Record<string, unknown>;
 	const agent = stringValue(raw.agent, 128);
@@ -212,22 +229,33 @@ function sanitizeStep(input: unknown, depth: number): NestedStepSummary | undefi
 		...(clampNumber(raw.startedAt) !== undefined ? { startedAt: clampNumber(raw.startedAt) } : {}),
 		...(clampNumber(raw.endedAt) !== undefined ? { endedAt: clampNumber(raw.endedAt) } : {}),
 		...(stringValue(raw.error, 1024) ? { error: stringValue(raw.error, 1024) } : {}),
-		...(depth < MAX_DEPTH && Array.isArray(raw.children) ? { children: raw.children.map((child) => sanitizeSummary(child, depth + 1)).filter((child): child is NestedRunSummary => Boolean(child)).slice(0, MAX_CHILDREN) } : {}),
+		...(depth < MAX_DEPTH && Array.isArray(raw.children) ? { children: raw.children.map((child) => sanitizeInternalSummary(child, depth + 1, privateOrigin)).filter((child): child is NestedRunSummary => Boolean(child)).slice(0, MAX_CHILDREN) } : {}),
 	};
 }
 
 export function sanitizeSummary(input: unknown, depth = 0): NestedRunSummary | undefined {
+	return sanitizeInternalSummary(input, depth, false);
+}
+
+function sanitizeInternalSummary(input: unknown, depth = 0, privateOrigin = true): NestedRunSummary | undefined {
 	if (!input || typeof input !== "object") return undefined;
 	const raw = input as Record<string, unknown>;
 	if (!isSafeNestedId(raw.id) || !isSafeNestedId(raw.parentRunId)) return undefined;
+	let runtime: NestedRunSummary["runtime"];
+	try {
+		if ("runtime" in raw) runtime = parsePiRuntime(raw.runtime, "nested origin");
+	} catch { return undefined; }
+	if ("sessionRoot" in raw && (typeof raw.sessionRoot !== "string" || !path.isAbsolute(raw.sessionRoot))) return undefined;
 	const pathParts = sanitizeNestedPath(raw.path);
 	const steps = Array.isArray(raw.steps)
-		? raw.steps.map((step) => sanitizeStep(step, depth + 1)).filter((step): step is NestedStepSummary => Boolean(step)).slice(0, MAX_STEPS)
+		? raw.steps.map((step) => sanitizeStep(step, depth + 1, privateOrigin)).filter((step): step is NestedStepSummary => Boolean(step)).slice(0, MAX_STEPS)
 		: undefined;
 	const totalTokens = sanitizeTokenUsage(raw.totalTokens);
 	const totalCost = typeof raw.totalCost === "number" && Number.isFinite(raw.totalCost) ? raw.totalCost : undefined;
 	return {
 		id: raw.id,
+		...(privateOrigin && runtime ? { runtime } : {}),
+		...(privateOrigin && typeof raw.sessionRoot === "string" ? { sessionRoot: raw.sessionRoot } : {}),
 		parentRunId: raw.parentRunId,
 		...(clampNumber(raw.parentStepIndex) !== undefined ? { parentStepIndex: clampNumber(raw.parentStepIndex) } : {}),
 		...(stringValue(raw.parentAgent, 128) ? { parentAgent: stringValue(raw.parentAgent, 128) } : {}),
@@ -260,7 +288,7 @@ export function sanitizeSummary(input: unknown, depth = 0): NestedRunSummary | u
 		...(clampNumber(raw.lastUpdate) !== undefined ? { lastUpdate: clampNumber(raw.lastUpdate) } : {}),
 		...(stringValue(raw.error, 1024) ? { error: stringValue(raw.error, 1024) } : {}),
 		...(steps && steps.length > 0 ? { steps } : {}),
-		...(depth < MAX_DEPTH && Array.isArray(raw.children) ? { children: raw.children.map((child) => sanitizeSummary(child, depth + 1)).filter((child): child is NestedRunSummary => Boolean(child)).slice(0, MAX_CHILDREN) } : {}),
+		...(depth < MAX_DEPTH && Array.isArray(raw.children) ? { children: raw.children.map((child) => sanitizeInternalSummary(child, depth + 1, privateOrigin)).filter((child): child is NestedRunSummary => Boolean(child)).slice(0, MAX_CHILDREN) } : {}),
 	};
 }
 
@@ -279,7 +307,7 @@ function parseRecord(content: string, route: NestedRoute): NestedEventRecord | u
 	if (!isSafeNestedId(raw.parentRunId)) return undefined;
 	const ts = clampNumber(raw.ts);
 	if (ts === undefined) return undefined;
-	const child = sanitizeSummary(raw.child);
+	const child = sanitizeInternalSummary(raw.child);
 	if (!child || child.id === route.rootRunId) return undefined;
 	const routedChild: NestedRunSummary = {
 		...child,
@@ -322,7 +350,24 @@ function mergeSummary(existing: NestedRunSummary | undefined, event: NestedEvent
 	if (incomingUpdate < existingUpdate) return existing;
 	if (terminal(existing.state) && !terminal(incoming.state)) return existing;
 	if (terminal(existing.state) && terminal(incoming.state) && incomingUpdate === existingUpdate) return existing;
-	return { ...existing, ...incoming, state: incoming.state, lastUpdate: Math.max(existingUpdate, incomingUpdate) };
+	const preserveOrigins = (summary: NestedRunSummary): NestedRunSummary => {
+		const known = findNestedRun([existing], summary.id);
+		return {
+			...summary,
+			...(known?.runtime && known.sessionRoot ? { runtime: known.runtime, sessionRoot: known.sessionRoot } : {}),
+			...(summary.children ? { children: summary.children.map(preserveOrigins) } : {}),
+			...(summary.steps ? { steps: summary.steps.map((step) => ({
+				...step,
+				...(step.children ? { children: step.children.map(preserveOrigins) } : {}),
+			})) } : {}),
+		};
+	};
+	return {
+		...existing,
+		...preserveOrigins(incoming),
+		state: incoming.state,
+		lastUpdate: Math.max(existingUpdate, incomingUpdate),
+	};
 }
 
 function attachChild(children: NestedRunSummary[], event: NestedEventRecord): NestedRunSummary[] {
@@ -367,14 +412,19 @@ export function findNestedRouteForRootId(rootRunId: string): NestedRoute | undef
 	assertSafeId("rootRunId", rootRunId);
 	let entries: string[];
 	try {
-		entries = fs.readdirSync(NESTED_EVENTS_DIR);
+		entries = [NESTED_EVENTS_DIR, LEGACY_NESTED_EVENTS_DIR].flatMap((base) => {
+			try { return fs.readdirSync(base).map((entry) => path.join(base, entry)); } catch (error) {
+				if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+				throw error;
+			}
+		});
 	} catch (error) {
 		if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
 		throw error;
 	}
 	for (const entry of entries) {
-		if (!entry.startsWith(`${rootRunId}-`)) continue;
-		const routeRoot = path.join(NESTED_EVENTS_DIR, entry);
+		if (!path.basename(entry).startsWith(`${rootRunId}-`)) continue;
+		const routeRoot = entry;
 		try {
 			const metadata = JSON.parse(fs.readFileSync(path.join(routeRoot, ROUTE_FILE), "utf-8")) as { rootRunId?: unknown; capabilityToken?: unknown };
 			if (metadata.rootRunId !== rootRunId || typeof metadata.capabilityToken !== "string") continue;
@@ -393,9 +443,18 @@ export function findNestedRouteForRootId(rootRunId: string): NestedRoute | undef
 	return undefined;
 }
 
-export function projectNestedRegistryForRoot(rootRunId: string): NestedRegistry | undefined {
+export function isLegacyNestedRoute(route: NestedRoute): boolean {
+	validateRouteShape(route);
+	return containedPath(LEGACY_NESTED_EVENTS_DIR, route.eventSink);
+}
+
+export interface NestedProjectionOptions {
+	readOnlyLegacy?: boolean;
+}
+
+export function projectNestedRegistryForRoot(rootRunId: string, options: NestedProjectionOptions = {}): NestedRegistry | undefined {
 	const route = findNestedRouteForRootId(rootRunId);
-	return route ? projectNestedEvents(route) : undefined;
+	return route ? projectNestedEvents(route, options) : undefined;
 }
 
 export function findNestedRun(children: NestedRunSummary[] | undefined, id: string): NestedRunSummary | undefined {
@@ -444,14 +503,19 @@ function collectScopedNestedRuns(children: NestedRunSummary[] | undefined, scope
 function listNestedRoutes(): NestedRoute[] {
 	let entries: string[];
 	try {
-		entries = fs.readdirSync(NESTED_EVENTS_DIR);
+		entries = [NESTED_EVENTS_DIR, LEGACY_NESTED_EVENTS_DIR].flatMap((base) => {
+			try { return fs.readdirSync(base).map((entry) => path.join(base, entry)); } catch (error) {
+				if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+				throw error;
+			}
+		});
 	} catch (error) {
 		if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
 		throw error;
 	}
 	const routes: NestedRoute[] = [];
 	for (const entry of entries) {
-		const routeRoot = path.join(NESTED_EVENTS_DIR, entry);
+		const routeRoot = entry;
 		try {
 			const metadata = JSON.parse(fs.readFileSync(path.join(routeRoot, ROUTE_FILE), "utf-8")) as { rootRunId?: unknown; capabilityToken?: unknown };
 			if (typeof metadata.rootRunId !== "string" || typeof metadata.capabilityToken !== "string") continue;
@@ -470,20 +534,29 @@ function listNestedRoutes(): NestedRoute[] {
 	return routes;
 }
 
-export function findNestedRunMatchesById(id: string, options: { prefix?: boolean; scope?: NestedRunResolutionScope } = {}): NestedRunMatch[] {
+export function findNestedRunMatchesById(id: string, options: { prefix?: boolean; scope?: NestedRunResolutionScope } & NestedProjectionOptions = {}): NestedRunMatch[] {
 	assertSafeId("id", id);
 	const matches: NestedRunMatch[] = [];
+	const persistentIds = new Set<string>();
+	const authorityId = (route: NestedRoute, run: NestedRunSummary) => JSON.stringify([route.rootRunId, route.capabilityToken, run.id]);
 	for (const route of options.scope?.routes ?? listNestedRoutes()) {
 		try {
-			const registry = projectNestedEvents(route);
+			const registry = projectNestedEvents(route, options);
+			const persistent = containedPath(NESTED_EVENTS_DIR, route.eventSink);
+			if (persistent) {
+				// Shadow before descendant filtering so stale legacy scope cannot revive a moved run.
+				for (const run of collectNestedRuns(registry.children)) persistentIds.add(authorityId(route, run));
+			}
 			for (const run of collectScopedNestedRuns(registry.children, options.scope?.descendantOf)) {
-				if (options.prefix ? run.id.startsWith(id) : run.id === id) matches.push({ rootRunId: route.rootRunId, route, run });
+				if (options.prefix ? run.id.startsWith(id) : run.id === id) {
+					matches.push({ rootRunId: route.rootRunId, route, run });
+				}
 			}
 		} catch {
 			continue;
 		}
 	}
-	return matches;
+	return matches.filter(({ route, run }) => !containedPath(LEGACY_NESTED_EVENTS_DIR, route.eventSink) || !persistentIds.has(authorityId(route, run)));
 }
 
 export function findNestedRunById(id: string): { rootRunId: string; run: NestedRunSummary } | undefined {
@@ -498,7 +571,7 @@ export function readNestedRegistry(route: NestedRoute): NestedRegistry {
 		return {
 			rootRunId: route.rootRunId,
 			updatedAt: typeof parsed.updatedAt === "number" ? parsed.updatedAt : 0,
-			children: Array.isArray(parsed.children) ? parsed.children.map((child) => sanitizeSummary(child)).filter((child): child is NestedRunSummary => Boolean(child)) : [],
+			children: Array.isArray(parsed.children) ? parsed.children.map((child) => sanitizeInternalSummary(child)).filter((child): child is NestedRunSummary => Boolean(child)) : [],
 			processedEvents: Array.isArray(parsed.processedEvents) ? parsed.processedEvents.filter((item): item is string => typeof item === "string") : [],
 		};
 	} catch (error) {
@@ -507,7 +580,7 @@ export function readNestedRegistry(route: NestedRoute): NestedRegistry {
 	}
 }
 
-export function projectNestedEvents(route: NestedRoute): NestedRegistry {
+export function projectNestedEvents(route: NestedRoute, options: NestedProjectionOptions = {}): NestedRegistry {
 	validateRouteShape(route);
 	let registry = readNestedRegistry(route);
 	const seen = new Set(registry.processedEvents);
@@ -542,7 +615,7 @@ export function projectNestedEvents(route: NestedRoute): NestedRegistry {
 		// Parent projection is the only writer to this sidecar registry. Child and
 		// runner processes only create immutable event files, so parent status.json
 		// remains owned by the existing runner writer and is never rewritten here.
-		writeAtomicJson(registryPath(route), registry);
+		if (!options.readOnlyLegacy || !isLegacyNestedRoute(route)) writeAtomicJson(registryPath(route), registry);
 	}
 	return registry;
 }
@@ -809,7 +882,7 @@ export function nestedArtifactEnv(rootRunId: string, parentRunId: string): Recor
 
 export function isTopLevelAsyncDir(asyncDir: string): boolean {
 	const resolved = path.resolve(asyncDir);
-	return containedPath(ASYNC_DIR, resolved) && !containedPath(path.join(TEMP_ROOT_DIR, "nested-subagent-runs"), resolved);
+	return [ASYNC_DIR, LEGACY_ASYNC_DIR].some((root) => containedPath(root, resolved));
 }
 
 export function nestedResultsPath(rootRunId: string, id: string): string {

package/src/runs/shared/pi-spawn.ts

@@ -6,15 +6,15 @@ export const PI_CODING_AGENT_PACKAGE = "@earendil-works/pi-coding-agent";
 
 export function findPiPackageRootFromEntry(entryPoint: string): string | undefined {
 	let dir = path.dirname(entryPoint);
-	while (dir !== path.dirname(dir)) {
+	while (true) {
 		const packageJsonPath = path.join(dir, "package.json");
 		if (fs.existsSync(packageJsonPath)) {
 			const pkg = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8")) as { name?: unknown };
 			if (pkg.name === PI_CODING_AGENT_PACKAGE) return dir;
 		}
+		if (dir === path.dirname(dir)) return undefined;
 		dir = path.dirname(dir);
 	}
-	return undefined;
 }
 
 export function resolveInstalledPiPackageRoot(): string | undefined {
@@ -26,90 +26,98 @@ export function resolvePiPackageRoot(): string | undefined {
 		const entry = process.argv[1];
 		return entry ? findPiPackageRootFromEntry(fs.realpathSync(entry)) : undefined;
 	} catch {
-		// process.argv[1] probing is best-effort; callers can fall back to PATH/package resolution.
+		// Non-launch package inspection is best-effort.
 		return undefined;
 	}
 }
 
-export interface PiSpawnDeps {
-	platform?: NodeJS.Platform;
-	execPath?: string;
-	argv1?: string;
-	existsSync?: (filePath: string) => boolean;
-	readFileSync?: (filePath: string, encoding: "utf-8") => string;
-	resolvePackageJson?: () => string;
-	resolvePackageEntry?: () => string;
-	piPackageRoot?: string;
+export interface PiRuntimeIdentity {
+	readonly nodeExecPath: string;
+	readonly piEntryPath: string;
+	readonly piPackageRoot: string;
 }
 
-interface PiSpawnCommand {
-	command: string;
-	args: string[];
-}
-
-function isRunnableNodeScript(filePath: string, existsSync: (filePath: string) => boolean): boolean {
-	if (!existsSync(filePath)) return false;
-	return /\.(?:mjs|cjs|js)$/i.test(filePath);
+export class PiRuntimeLaunchError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "PiRuntimeLaunchError";
+	}
 }
 
-function normalizePath(filePath: string): string {
-	return path.isAbsolute(filePath) ? filePath : path.resolve(filePath);
+function canonicalPath(value: string | undefined, source: string): string {
+	if (!value) throw new PiRuntimeLaunchError(`${source}: runtime path was not recorded`);
+	try {
+		return fs.realpathSync.native(value);
+	} catch (error) {
+		throw new PiRuntimeLaunchError(`${source} ${value}: ${String(error)}`);
+	}
 }
 
-export function resolveWindowsPiCliScript(deps: PiSpawnDeps = {}): string | undefined {
-	const existsSync = deps.existsSync ?? fs.existsSync;
-	const readFileSync = deps.readFileSync ?? ((filePath, encoding) => fs.readFileSync(filePath, encoding));
-	const argv1 = deps.argv1 ?? process.argv[1];
-
-	if (argv1) {
-		const argvPath = normalizePath(argv1);
-		if (isRunnableNodeScript(argvPath, existsSync)) {
-			return argvPath;
+function owningPackageRoot(entry: string): string {
+	let dir = path.dirname(entry);
+	while (true) {
+		const manifest = path.join(dir, "package.json");
+		if (fs.existsSync(manifest)) {
+			try {
+				const pkg = JSON.parse(fs.readFileSync(manifest, "utf-8"));
+				if (pkg?.name !== PI_CODING_AGENT_PACKAGE) {
+					throw new PiRuntimeLaunchError(`${entry}: owning package ${manifest} is not ${PI_CODING_AGENT_PACKAGE}`);
+				}
+				const bin = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.pi;
+				if (typeof bin !== "string" || !bin) {
+					throw new PiRuntimeLaunchError(`${manifest}: missing declared Pi bin for ${entry}`);
+				}
+				if (canonicalPath(path.resolve(dir, bin), "Declared Pi bin") !== entry) {
+					throw new PiRuntimeLaunchError(`${entry}: does not match declared Pi bin in ${manifest}`);
+				}
+				return dir;
+			} catch (error) {
+				if (error instanceof PiRuntimeLaunchError) throw error;
+				throw new PiRuntimeLaunchError(`${manifest} for ${entry}: ${String(error)}`);
+			}
 		}
+		if (dir === path.dirname(dir)) throw new PiRuntimeLaunchError(`${entry}: no owning ${PI_CODING_AGENT_PACKAGE} package`);
+		dir = path.dirname(dir);
 	}
+}
 
+function checkAvailability(file: string, executable: boolean): void {
 	try {
-		const resolvePackageJson = deps.resolvePackageJson ?? (() => {
-			const root = deps.piPackageRoot ?? resolvePiPackageRoot();
-			if (root) return path.join(root, "package.json");
-			const packageRoot = deps.resolvePackageEntry
-				? findPiPackageRootFromEntry(deps.resolvePackageEntry())
-				: resolveInstalledPiPackageRoot();
-			if (!packageRoot) throw new Error(`Could not resolve ${PI_CODING_AGENT_PACKAGE} package root`);
-			return path.join(packageRoot, "package.json");
-		});
-		const packageJsonPath = resolvePackageJson();
-		const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8")) as {
-			bin?: string | Record<string, string>;
-		};
-		const binField = packageJson.bin;
-		const binPath = typeof binField === "string"
-			? binField
-			: binField?.pi ?? Object.values(binField ?? {})[0];
-		if (!binPath) return undefined;
-		const candidate = path.resolve(path.dirname(packageJsonPath), binPath);
-		if (isRunnableNodeScript(candidate, existsSync)) {
-			return candidate;
-		}
-	} catch {
-		// Windows CLI resolution is optional; falling back to `pi` lets PATH handle execution.
-		return undefined;
+		if (!fs.statSync(file).isFile()) throw new Error("not a file");
+		fs.accessSync(file, executable ? fs.constants.X_OK : fs.constants.R_OK);
+	} catch (error) {
+		throw new PiRuntimeLaunchError(`${file}: ${String(error)}`);
 	}
+}
 
-	return undefined;
+export function capturePiRuntime(deps: { execPath?: string; argv1?: string } = {}): PiRuntimeIdentity {
+	const nodeExecPath = canonicalPath(deps.execPath ?? process.execPath, "Node executable");
+	const piEntryPath = canonicalPath(deps.argv1 ?? process.argv[1], "Pi entry");
+	checkAvailability(nodeExecPath, true);
+	checkAvailability(piEntryPath, false);
+	const piPackageRoot = canonicalPath(owningPackageRoot(piEntryPath), "Pi package root");
+	return { nodeExecPath, piEntryPath, piPackageRoot };
 }
 
-export function getPiSpawnCommand(args: string[], deps: PiSpawnDeps = {}): PiSpawnCommand {
-	const platform = deps.platform ?? process.platform;
-	if (platform === "win32") {
-		const piCliPath = resolveWindowsPiCliScript(deps);
-		if (piCliPath) {
-			return {
-				command: deps.execPath ?? process.execPath,
-				args: [piCliPath, ...args],
-			};
+export function parsePiRuntime(value: unknown, source: string): PiRuntimeIdentity {
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		throw new PiRuntimeLaunchError(`${source}: original runtime was not recorded; a new run is required`);
+	}
+	const record = value as Record<string, unknown>;
+	for (const field of ["nodeExecPath", "piEntryPath", "piPackageRoot"] as const) {
+		if (typeof record[field] !== "string" || !record[field] || !path.isAbsolute(record[field])) {
+			throw new PiRuntimeLaunchError(`${source}: invalid runtime ${field} ${String(record[field])}; a new run is required`);
 		}
 	}
+	return { nodeExecPath: record.nodeExecPath as string, piEntryPath: record.piEntryPath as string, piPackageRoot: record.piPackageRoot as string };
+}
 
-	return { command: "pi", args };
+export function getPiSpawnCommand(args: string[], runtime: PiRuntimeIdentity): { command: string; args: string[] } {
+	checkAvailability(runtime.nodeExecPath, true);
+	checkAvailability(runtime.piEntryPath, false);
+	const root = owningPackageRoot(runtime.piEntryPath);
+	if (root !== runtime.piPackageRoot) {
+		throw new PiRuntimeLaunchError(`${runtime.piEntryPath}: owning package ${root} does not match ${runtime.piPackageRoot}`);
+	}
+	return { command: runtime.nodeExecPath, args: [runtime.piEntryPath, ...args] };
 }

package/src/shared/agent-dir.ts

@@ -0,0 +1,12 @@
+import * as os from "node:os";
+import * as path from "node:path";
+
+export function getAgentDir(): string {
+	const configured = process.env.PI_CODING_AGENT_DIR;
+	if (configured === "~") return os.homedir();
+	if (configured?.startsWith("~/")) return path.join(os.homedir(), configured.slice(2));
+	return configured || path.join(os.homedir(), ".pi", "agent");
+}
+
+export const PINNED_AGENT_DIR = path.resolve(getAgentDir());
+export const PINNED_AGENT_DIR_OVERRIDE = process.env.PI_CODING_AGENT_DIR ? PINNED_AGENT_DIR : undefined;

package/src/shared/atomic-json.ts

@@ -9,7 +9,18 @@ export function writeAtomicJson(filePath: string, payload: object): void {
 	);
 	try {
 		fs.writeFileSync(tempPath, JSON.stringify(payload, null, 2), "utf-8");
-		fs.renameSync(tempPath, filePath);
+		for (let retries = 0; ; retries++) {
+			try {
+				fs.renameSync(tempPath, filePath);
+				break;
+			} catch (error) {
+				const code = (error as NodeJS.ErrnoException | null)?.code;
+				if (process.platform !== "win32" || !["EPERM", "EACCES", "EBUSY"].includes(code ?? "") || retries >= 5) {
+					throw error;
+				}
+				Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50);
+			}
+		}
 	} finally {
 		fs.rmSync(tempPath, { force: true });
 	}

package/src/shared/fork-context.ts

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import * as path from "node:path";
 import { SessionManager } from "@earendil-works/pi-coding-agent";
 
 type SubagentExecutionContext = "fresh" | "fork";
@@ -11,6 +12,7 @@ interface ForkableSessionManager {
 }
 
 interface ForkContextResolverOptions {
+	sessionDirForIndex?: (index: number) => string;
 	openSession?: (path: string, sessionDir?: string) => { createBranchedSession(leafId: string): string | undefined };
 }
 
@@ -57,7 +59,10 @@ export function createForkContextResolver(
 				if (!fs.existsSync(parentSessionFile)) {
 					throw new Error(`Parent session file does not exist: ${parentSessionFile}. Pi has not persisted enough history to fork yet.`);
 				}
-				const sourceManager = openSession(parentSessionFile, sessionDir);
+				const destination = options.sessionDirForIndex?.(index);
+				if (destination) fs.mkdirSync(destination, { recursive: true });
+				const assignedDir = destination ? fs.realpathSync.native(destination) : undefined;
+				const sourceManager = openSession(parentSessionFile, destination ?? sessionDir);
 				const sessionFile = sourceManager.createBranchedSession(leafId);
 				if (!sessionFile) {
 					throw new Error("Session manager did not return a forked session file.");
@@ -65,8 +70,15 @@ export function createForkContextResolver(
 				if (!fs.existsSync(sessionFile)) {
 					throw new Error(`Session manager returned a forked session file that does not exist: ${sessionFile}`);
 				}
-				cachedSessionFiles.set(index, sessionFile);
-				return sessionFile;
+				if (assignedDir) {
+					const relative = path.relative(assignedDir, fs.realpathSync.native(sessionFile));
+					if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+						throw new Error(`Forked session file is outside assigned session directory: ${sessionFile}`);
+					}
+				}
+				const resolvedFile = assignedDir ? fs.realpathSync.native(sessionFile) : sessionFile;
+				cachedSessionFiles.set(index, resolvedFile);
+				return resolvedFile;
 			} catch (error) {
 				const cause = error instanceof Error ? error : new Error(String(error));
 				throw new Error(`Failed to create forked subagent session: ${cause.message}`, { cause });