@ferris1225/pi-subagents 4.1.7 → 4.1.9

package/src/runtime.ts

@@ -10,7 +10,7 @@
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { rmSync } from "node:fs";
-import { BackgroundTaskQueue } from "./background.ts";
+import { BackgroundTaskQueue, MAX_CONCURRENT_SUBAGENTS } from "./background.ts";
 import {
 	completionGroupTriggersTurn,
 	createCompletionBatcher,
@@ -19,29 +19,25 @@ import {
 	type CompletionBatcher,
 	type CompletionMessageItem,
 } from "./completion.ts";
-import { loadConfigSync, type ThinkingLevel } from "./config.ts";
+import { type ThinkingLevel } from "./config.ts";
+import { threadRecordFromThread, upsertThreadRecord, type ThreadRecord } from "./durable.ts";
 import { isRunActiveStatus, monitor } from "./monitor.ts";
-import {
-	persistRecoveryRecords,
-	recoveryRecordFromFinalization,
-	type RecoveryRecord,
-} from "./recovery.ts";
 import type { RpcRunControl } from "./rpc-run.ts";
-import type { SingleResult } from "./spawn.ts";
+import type { StartBackgroundInternal } from "./thread-lifecycle.ts";
+import { isFailedResult, type SingleResult } from "./spawn.ts";
 import type { IsolationMode, WorktreeFinalization, WorktreeIsolation } from "./worktree.ts";
 
 export type ThreadState =
 	| "queued"
 	| "resuming"
 	| "running"
-	| "steering"
 	| "interrupting"
 	| "parked"
 	| "completed"
 	| "failed"
 	| "stopped";
 
-export type ThreadLifecycleOperation = "park" | "resume" | "fork" | "stop" | "settle";
+export type ThreadLifecycleOperation = "park" | "resume" | "stop" | "settle";
 
 export interface SubagentThread {
 	id: number;
@@ -54,6 +50,8 @@ export interface SubagentThread {
 	executionCwd: string;
 	thinkingLevel?: ThinkingLevel;
 	isolation: IsolationMode;
+	/** Report-only reviewer dispatch: verdicts never chain into auto-fix. */
+	advisoryReview: boolean;
 	worktree?: WorktreeIsolation;
 	state: ThreadState;
 	control: RpcRunControl;
@@ -74,15 +72,8 @@ export interface SubagentThread {
 	/** A destructive stop retires context even if the active child settles later. */
 	retireOnSettle?: boolean;
 	retired?: boolean;
-	/** Abort the active generation to a stable checkpoint and wait until its
-	 * queue work has published that checkpoint and released its slot. */
-	park: () => Promise<"queued" | "active">;
 	/** Installed by dispatch so the control tool can restart the same logical id. */
 	resume: (objective?: string, ctx?: ExtensionContext) => Promise<SingleResult>;
-	/** Create a new logical thread from this thread's retained Pi session branch. */
-	fork: (objective?: string, ctx?: ExtensionContext) => Promise<SingleResult>;
-	forkedFromRunId?: number;
-	forkChildRunIds: number[];
 	/** Dispatch-owned, generation-guarded worktree settlement hook. Its apply
 	 * runs under the canonical original-repository lane. */
 	finalizeIsolation: (generation: number, result?: SingleResult) => Promise<WorktreeFinalization | undefined>;
@@ -98,6 +89,13 @@ export interface SubagentRuntime {
 	getActiveTools: () => string[];
 	/** False after session_shutdown; guards delivery and queue work. */
 	sessionActive: boolean;
+	/** The process-wide background dispatcher. Set at tool registration so
+	 * threads restored from the durable manifest can resume before any dispatch. */
+	dispatcher?: StartBackgroundInternal;
+	/** Run ids restored from the durable manifest at load; consumed by the
+	 * one-time session-start notice. */
+	restoredRunIds: number[];
+	restoredNotified: boolean;
 	/** Deliver a batch of completion messages to the main window, waking it only
 	 * when the batch needs a turn. */
 	sendCompletionGroup: (items: CompletionMessageItem[]) => void;
@@ -111,7 +109,7 @@ export interface SubagentRuntime {
 	registerRunResult: (runId: number, result: SingleResult) => void;
 	/** Logical threads outlive process attempts and completed generations. */
 	threads: Map<number, SubagentThread>;
-	/** Resume/fork setup that has claimed a thread but has not yet enqueued its
+	/** Resume setup that has claimed a thread but has not yet enqueued its
 	 * next generation. Shutdown invalidates these claims and waits for cleanup. */
 	preflightOperations: Set<Promise<void>>;
 	/** Every session directory retained for this parent session, including
@@ -124,16 +122,15 @@ export interface SubagentRuntime {
 }
 
 export function createRuntime(pi: ExtensionAPI, configPath: string): SubagentRuntime {
-	// Init-time decisions need the config synchronously; the full (migrating)
-	// async load runs per tool call.
-	const initialConfig = loadConfigSync(configPath);
-	const backgroundQueue = new BackgroundTaskQueue(initialConfig.maxConcurrency);
+	const backgroundQueue = new BackgroundTaskQueue(MAX_CONCURRENT_SUBAGENTS);
 
 	const runtime: SubagentRuntime = {
 		configPath,
 		backgroundQueue,
 		getActiveTools: () => pi.getActiveTools(),
 		sessionActive: true,
+		restoredRunIds: [],
+		restoredNotified: false,
 		sendCompletionGroup: (items) => {
 			if (!runtime.sessionActive || items.length === 0) return;
 			// A result arriving for one run does not mean sibling runs are done.
@@ -206,61 +203,86 @@ export function createRuntime(pi: ExtensionAPI, configPath: string): SubagentRun
 			if (!runtime.sessionActive) return;
 			runtime.sessionActive = false;
 			const shutdownThreads = [...runtime.threads.values()];
+			const liveStates = new Set(["queued", "resuming", "running", "interrupting"]);
+			const previousStates = new Map(shutdownThreads.map((thread) => [thread.id, thread.state] as const));
 			// Invalidate every lifecycle claim synchronously before the first await.
-			// Resume/fork preflight checks both this version and sessionActive, then
+			// Resume preflight checks both this version and sessionActive, then
 			// cleans any worktree/session it created before resolving its tracker.
+			// A generation already inside its settlement keeps its own claim: it
+			// finalizes its worktree and persists its terminal record itself.
+			const interrupting = shutdownThreads.filter((thread) =>
+				!thread.retired &&
+				thread.lifecycleOperation !== "settle" &&
+				liveStates.has(thread.state),
+			);
 			for (const thread of shutdownThreads) {
 				thread.lifecycleVersion++;
+				if (thread.retired) {
+					thread.lifecycleOperation = "stop";
+					continue;
+				}
+				if (thread.lifecycleOperation === "settle") continue;
 				thread.lifecycleOperation = "stop";
-				thread.retired = true;
-				thread.retireOnSettle = true;
-				thread.state = "stopped";
+				// Deliberately NOT retireOnSettle: shutdown interrupts to the last
+				// checkpoint but keeps the session/worktree resumable across reload.
+				thread.retireOnSettle = false;
+				if (liveStates.has(thread.state)) thread.state = "stopped";
 			}
 			const preflights = [...runtime.preflightOperations];
 			runtime.completionBatcher.dispose();
 			runtime.backgroundQueue.cancelAll();
 			// Await live RPC process-tree cleanup and continuation preflight rollback
-			// before removing sessions/worktrees or clearing ownership maps.
+			// before persisting records or releasing ownership maps.
 			await Promise.all([
 				Promise.all(
-					shutdownThreads.map((thread) =>
+					interrupting.map((thread) =>
 						thread.control.stop("Parent session shut down").catch(() => undefined),
 					),
 				),
 				Promise.allSettled(preflights),
 				runtime.backgroundQueue.waitForIdle(),
 			]);
-			// Parked work owns no queue task, so shutdown is its final settlement.
-			// Active/stopped tasks may already have finalized; the handle and callback
-			// are idempotent and generation-guarded.
-			const recoveryRecords: RecoveryRecord[] = [];
+			// Persist one record per non-retired thread, then keep exactly the
+			// artifacts those records reference. A thread whose settlement finished
+			// during the wait above already wrote its own terminal record; the
+			// lastResult-derived state below matches it.
+			const records: ThreadRecord[] = [];
 			for (const thread of runtime.threads.values()) {
-				const finalization = await thread.finalizeIsolation(thread.generation).catch(() => undefined);
-				if (finalization?.status === "retained") {
-					recoveryRecords.push(recoveryRecordFromFinalization(thread.id, finalization));
-					if (!thread.isolationFailureNotified) {
-						thread.isolationFailureNotified = true;
-						try {
-							thread.notifyIsolationFailure?.(finalization);
-						} catch {
-							/* the parent UI may already be shutting down */
-						}
-					}
+				if (thread.retired) continue;
+				const previous = previousStates.get(thread.id) ?? thread.state;
+				let state: "parked" | "completed" | "failed";
+				if (previous === "completed" || previous === "failed") {
+					state = previous;
+				} else if (thread.lifecycleOperation === "settle" && thread.lastResult) {
+					state = isFailedResult(thread.lastResult) ? "failed" : "completed";
+				} else {
+					state = "parked";
 				}
+				records.push(threadRecordFromThread(thread, state));
 			}
-			// Persist before tearing down the old runtime. A /new, /resume, or quit
-			// must not make the only recovery paths unreachable.
-			await persistRecoveryRecords(runtime.configPath, recoveryRecords).catch(() => undefined);
-			runtime.settledRuns.clear();
-			runtime.settledListeners.clear();
-			runtime.runControllers.clear();
+			await Promise.all(
+				records.map((record) => upsertThreadRecord(runtime.configPath, record).catch(() => undefined)),
+			);
+			// Retained-failure recovery records are persisted by the finalization
+			// itself; shutdown only drops sessions no record claims anymore.
+			const referenced = new Set(
+				records.flatMap((record) =>
+					[record.sessionDir, record.worktree?.tempDir].filter(Boolean) as string[],
+				),
+			);
 			for (const sessionDir of runtime.sessionDirs) {
+				if (referenced.has(sessionDir)) continue;
 				try {
 					rmSync(sessionDir, { recursive: true, force: true });
 				} catch {
-					/* best-effort */
+					/* best-effort; the state-root sweep catches leftovers later */
 				}
 			}
+			runtime.settledRuns.clear();
+			runtime.settledListeners.clear();
+			runtime.runControllers.clear();
+			// sessionDirs entries still referenced by records stay owned by the
+			// manifest; the next process re-registers them at restore.
 			runtime.sessionDirs.clear();
 			runtime.preflightOperations.clear();
 			runtime.threads.clear();

package/src/session-fork.ts

@@ -2,7 +2,7 @@
 
 import { SessionManager } from "@earendil-works/pi-coding-agent";
 import { existsSync } from "node:fs";
-import { mkdtemp, rm } from "node:fs/promises";
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
@@ -43,12 +43,17 @@ export async function forkRetainedSession(options: {
 	targetCwd?: string;
 	sessionDir: string;
 	sessionId: string;
+	/** Parent directory for the cloned branch. Defaults to the OS temp dir;
+	 * dispatch passes the durable state root. */
+	targetRoot?: string;
 }): Promise<ForkedSession> {
 	const sourceSessionFile = await findRetainedSessionFile(
 		options.sessionDir,
 		options.sessionId,
 	);
-	const sessionDir = await mkdtemp(join(tmpdir(), "pi-subagent-session-fork-"));
+	const root = options.targetRoot ?? tmpdir();
+	await mkdir(root, { recursive: true });
+	const sessionDir = await mkdtemp(join(root, "pi-subagent-session-fork-"));
 	try {
 		// Supplying the new directory makes createBranchedSession write there.
 		// cwdOverride rewrites the cloned header so a settled isolated session can

package/src/setup.ts

@@ -13,13 +13,9 @@ import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import {
 	AGENT_SCOPE_VALUES,
 	BUILTIN_AGENT_NAMES,
-	CLEANER_DEFAULTED_FEATURE,
-	DOCUMENTER_DEFAULTED_FEATURE,
 	DEFAULT_CONFIG,
 	DEFAULT_ENABLED_AGENTS,
 	DEFAULT_IDLE_TIMEOUT_SEC,
-	DEFAULT_MAX_CONCURRENCY,
-	DEFAULT_MAX_FIX_ROUNDS,
 	DEFAULT_THINKING_LEVEL,
 	type AgentScope,
 	type SubagentsConfig,
@@ -243,8 +239,6 @@ async function pickInjection(ctx: ExtensionCommandContext, current: boolean): Pr
 	return choice.startsWith("On");
 }
 
-const CONCURRENCY_STEPS = [1, 2, 3, 4, 6, 8, 12, 16];
-const FIX_ROUNDS_STEPS = [0, 1, 2, 3, 5];
 const IDLE_TIMEOUT_STEPS = [0, 30, 60, 90, 120, 180, 300, 600];
 
 async function pickCount(
@@ -299,22 +293,6 @@ async function runFullSetup(ctx: ExtensionCommandContext, configPath: string, ba
 	if (injection === undefined) return false;
 	const scope = await pickScope(ctx, base.agentScope);
 	if (scope === undefined) return false;
-	const maxConcurrency = await pickCount(
-		ctx,
-		"Max sub-agents running at once?",
-		CONCURRENCY_STEPS,
-		base.maxConcurrency,
-		DEFAULT_MAX_CONCURRENCY,
-	);
-	if (maxConcurrency === undefined) return false;
-	const maxFixRounds = await pickCount(
-		ctx,
-		"Reviewer worker-fix rounds? (0 = no automatic fixes)",
-		FIX_ROUNDS_STEPS,
-		base.maxFixRounds,
-		DEFAULT_MAX_FIX_ROUNDS,
-	);
-	if (maxFixRounds === undefined) return false;
 	const idleTimeoutSec = await pickCount(
 		ctx,
 		"Idle timeout in seconds? (0 = disabled)",
@@ -333,16 +311,7 @@ async function runFullSetup(ctx: ExtensionCommandContext, configPath: string, ba
 		maxResultLines: base.maxResultLines,
 		proactiveInjection: injection,
 		agentScope: scope,
-		maxConcurrency,
-		maxFixRounds,
 		idleTimeoutSec,
-		// Full setup is an explicit decision point: mark role-enable migrations as
-		// processed so the user's saved selection is kept as-is.
-		announcedFeatures: [...new Set([
-			...base.announcedFeatures,
-			CLEANER_DEFAULTED_FEATURE,
-			DOCUMENTER_DEFAULTED_FEATURE,
-		])],
 	};
 	await saveConfig(next, configPath);
 	ctx.ui.notify(`pi-subagents configured with Auto thinking. Saved to ${configPath}`, "info");
@@ -357,8 +326,6 @@ async function updateRuntimeSetting(
 		const choice = await ctx.ui.select("Runtime setting", [
 			"Proactive injection",
 			"Agent scope",
-			"Max concurrency",
-			"Reviewer worker-fix rounds",
 			"Idle timeout",
 		]);
 		if (choice === undefined) return undefined;
@@ -371,14 +338,6 @@ async function updateRuntimeSetting(
 			const value = await pickScope(ctx, config.agentScope);
 			if (value === undefined) continue;
 			next.agentScope = value;
-		} else if (choice.startsWith("Max concurrency")) {
-			const value = await pickCount(ctx, "Max sub-agents running at once?", CONCURRENCY_STEPS, config.maxConcurrency, DEFAULT_MAX_CONCURRENCY);
-			if (value === undefined) continue;
-			next.maxConcurrency = value;
-		} else if (choice.startsWith("Reviewer")) {
-			const value = await pickCount(ctx, "Reviewer worker-fix rounds?", FIX_ROUNDS_STEPS, config.maxFixRounds, DEFAULT_MAX_FIX_ROUNDS);
-			if (value === undefined) continue;
-			next.maxFixRounds = value;
 		} else {
 			const value = await pickCount(ctx, "Idle timeout in seconds?", IDLE_TIMEOUT_STEPS, config.idleTimeoutSec, DEFAULT_IDLE_TIMEOUT_SEC);
 			if (value === undefined) continue;

package/src/spawn.ts

@@ -10,7 +10,7 @@
 
 import { createHash, randomUUID } from "node:crypto";
 import { type Dirent, mkdirSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { mkdtemp, rm } from "node:fs/promises";
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, join, resolve } from "node:path";
 import type { Message } from "@earendil-works/pi-ai";
@@ -202,7 +202,7 @@ export function writeResultArtifact(output: string, agentName: string, cwd?: str
 }
 
 export function isFailedResult(result: SingleResult): boolean {
-	if (result.parked) return false;
+
 	return result.exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted";
 }
 
@@ -272,7 +272,7 @@ export function isRetryableStartupFailure(result: SingleResult, durationMs: numb
 }
 
 export function formatStartupRetryExhaustedError(model: string, attempts: number): string {
-	return `Subagent failed to start after ${attempts} attempt${attempts === 1 ? "" : "s"} on ${model}: the child failed before its initial RPC prompt was dispatched and produced no model, tool, output, or usage activity. This is typically a concurrent pi startup race (several sub-agents starting at once). Retry the dispatch, or temporarily lower maxConcurrency in /subagents-setup.`;
+	return `Subagent failed to start after ${attempts} attempt${attempts === 1 ? "" : "s"} on ${model}: the child failed before its initial RPC prompt was dispatched and produced no model, tool, output, or usage activity. This is typically a concurrent pi startup race (several sub-agents starting at once). Retry the dispatch, or dispatch fewer sub-agents at once.`;
 }
 
 export async function waitForStartupRetry(delayMs: number, signal?: AbortSignal): Promise<boolean> {
@@ -308,12 +308,12 @@ async function waitForControlledRetry(
 ): Promise<boolean> {
 	let remaining = normalizeStartupRetryDelay(delayMs);
 	while (remaining > 0) {
-		if (control?.isParkRequested() || control?.isStopRequested()) return false;
+		if (control?.isStopRequested()) return false;
 		const slice = Math.min(remaining, 50);
 		if (!(await waitForStartupRetry(slice, signal))) return false;
 		remaining -= slice;
 	}
-	return !signal?.aborted && !control?.isParkRequested() && !control?.isStopRequested();
+	return !signal?.aborted && !control?.isStopRequested();
 }
 
 export function getResultOutput(result: SingleResult): string {
@@ -330,6 +330,12 @@ export function buildResumePrompt(task: string, reason: string): string {
 	return `You are resuming an earlier sub-agent session after ${reason}. Your earlier work — searches, reads, edits, and reasoning — is preserved in this session's history above; review it before acting. Current objective: ${task}. Pick up exactly where you left off and finish it. Do NOT redo searches, reads, or edits you already completed unless a step clearly failed. Continue now.`;
 }
 
+/** Create a fresh private session directory under the given root. */
+export async function createSessionDir(root: string = tmpdir()): Promise<string> {
+	await mkdir(root, { recursive: true });
+	return mkdtemp(join(root, "pi-subagent-session-"));
+}
+
 export function buildFallbackResumeReason(fromModel?: string): string {
 	return fromModel
 		? `the selected model (${fromModel}) failed at the model/provider level, so the current main model is continuing`
@@ -349,6 +355,10 @@ export interface RunSingleOptions {
 	startupRetryDelaysMs?: readonly number[];
 	sessionDir?: string;
 	sessionId?: string;
+	/** Parent directory for a fresh session directory. Defaults to the OS temp
+	 * dir; dispatch passes the durable state root so retained sessions survive
+	 * reloads and restarts. */
+	sessionRoot?: string;
 	/** Initial RPC prompt. Kept under the old name to limit caller churn. */
 	stdinText?: string;
 	/** Refresh parent-derived tools immediately before every startup retry and
@@ -366,7 +376,7 @@ export interface RunSingleOptions {
 
 function controlledDisposition(options: RunSingleOptions, base?: SingleResult): SingleResult | undefined {
 	const control = options.control;
-	if (!control?.isParkRequested() && !control?.isStopRequested()) return undefined;
+	if (!control?.isStopRequested()) return undefined;
 	const result: SingleResult = base ?? {
 		agent: options.agentName,
 		task: control.getObjective(),
@@ -380,23 +390,14 @@ function controlledDisposition(options: RunSingleOptions, base?: SingleResult):
 		sessionDir: options.sessionDir,
 	};
 	result.task = control.getObjective();
-	if (control.isParkRequested()) {
-		result.parked = true;
-		result.exitCode = 0;
-		result.stopReason = undefined;
-		result.errorMessage = undefined;
-	} else {
-		result.parked = undefined;
-		result.exitCode = 1;
-		result.stopReason = "aborted";
-		result.errorMessage = control.getStopMessage();
-	}
+	result.exitCode = 1;
+	result.stopReason = "aborted";
+	result.errorMessage = control.getStopMessage();
 	return result;
 }
 
 function signalAbortDisposition(options: RunSingleOptions, base: SingleResult): SingleResult | undefined {
 	if (!options.signal?.aborted) return undefined;
-	base.parked = undefined;
 	base.exitCode = 1;
 	base.stopReason = "aborted";
 	base.errorMessage = "Subagent was aborted";
@@ -459,8 +460,17 @@ export async function runSingleAgentWithMainFallback(
 	const startupDelays = customStartupDelays ?? SUBAGENT_STARTUP_RETRY_DELAYS_MS;
 
 	const sessionId = options.sessionId ?? randomUUID();
-	const sessionDir = options.sessionDir ?? (await mkdtemp(join(tmpdir(), "pi-subagent-session-")));
+	const sessionDir = options.sessionDir ?? (await createSessionDir(options.sessionRoot));
 	const baseOptions: RunSingleOptions = { ...options, sessionDir, sessionId };
+	if (!options.sessionDir) {
+		// Surface the fresh session immediately so the dispatching thread can
+		// persist a durable checkpoint before the child settles.
+		try {
+			options.onLive?.({ kind: "session", sessionId, sessionDir });
+		} catch {
+			/* never throw from event handling */
+		}
+	}
 
 	const dispatchFailure = async (error: unknown): Promise<SingleResult> => {
 		const errorMessage = error instanceof Error ? error.message : String(error);
@@ -489,14 +499,7 @@ export async function runSingleAgentWithMainFallback(
 		let retries = 0;
 		for (let attempt = 0; ; attempt++) {
 			const immediate = controlledDisposition(opts);
-			if (immediate) {
-				if (immediate.parked && !options.sessionDir && !sessionExists(sessionDir, sessionId)) {
-					await rm(sessionDir, { recursive: true, force: true }).catch(() => undefined);
-					immediate.sessionId = undefined;
-					immediate.sessionDir = undefined;
-				}
-				return immediate;
-			}
+			if (immediate) return immediate;
 			const start = Date.now();
 			try {
 				const attemptOptions = opts.resolveAgentForAttempt
@@ -510,7 +513,7 @@ export async function runSingleAgentWithMainFallback(
 			const durationMs = Date.now() - start;
 			const controlled = controlledDisposition(opts, lastResult);
 			if (controlled) return controlled;
-			if (lastResult.parked || lastResult.stopReason === "aborted") return lastResult;
+			if (lastResult.stopReason === "aborted") return lastResult;
 			if (!isRetryableStartupFailure(lastResult, durationMs)) {
 				if (retries > 0 && !isFailedResult(lastResult)) lastResult.startupRetries = retries;
 				return lastResult;
@@ -627,7 +630,7 @@ export async function runSingleAgentWithMainFallback(
 		}
 
 		result = await runWithStartupRetry(candidateOptions);
-		if (result.parked || result.stopReason === "aborted") return finish(result);
+		if (result.stopReason === "aborted") return finish(result);
 		if (!isModelLevelFailure(result)) return finish(result);
 		// Any model-level failure advances immediately to the sole fallback (the
 		// current main model). Retain selected-attempt tool diagnostics and usage;