@ferris1225/pi-subagents 4.1.13 → 4.1.16

package/src/temp-hygiene.ts

@@ -164,31 +164,3 @@ export function sweepOrphanTempDirs(
 	return removed;
 }
 
-/** Remove state-root directories no manifest record references. Fresh
- * directories (a run just created but not yet recorded) are protected by the
- * age cap, since the sweep only runs at extension load before new work. */
-export function sweepUnreferencedState(
-	stateRoot: string,
-	referencedPaths: ReadonlySet<string>,
-	options: SweepOptions = {},
-): number {
-	const now = options.now ?? Date.now();
-	const maxAgeMs = options.unmarkedMaxAgeMs ?? UNREFERENCED_STATE_MAX_AGE_MS;
-	const pathKey = (path: string): string => (process.platform === "win32" ? path.toLowerCase() : path);
-	const referenced = new Set([...referencedPaths].map(pathKey));
-	let entries: Dirent[];
-	try {
-		entries = readdirSync(stateRoot, { withFileTypes: true });
-	} catch {
-		return 0;
-	}
-	let removed = 0;
-	for (const entry of entries) {
-		if (!entry.isDirectory() || entry.isSymbolicLink()) continue;
-		const path = join(stateRoot, entry.name);
-		if (referenced.has(pathKey(path))) continue;
-		const ageMs = directoryAgeMs(entry, stateRoot, now);
-		if (ageMs !== undefined && ageMs > maxAgeMs && removeDir(path)) removed++;
-	}
-	return removed;
-}

package/src/thread-lifecycle.ts

@@ -12,7 +12,7 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { existsSync } from "node:fs";
 import { rm } from "node:fs/promises";
 import { realpath } from "node:fs/promises";
-import { resolve } from "node:path";
+import { join, resolve } from "node:path";
 import {
 	discoverAgents,
 	isWriteCapableAgent,
@@ -27,10 +27,9 @@ import {
 	type ThinkingLevel,
 } from "./config.ts";
 import {
-	getStateRoot,
 	readThreadRecords,
-	referencedDurablePaths,
 	removeThreadRecord,
+	pruneStaleProjectRoots,
 	pruneThreadRecords,
 	restoredResultFromSummary,
 	threadRecordFromThread,
@@ -42,6 +41,7 @@ import {
 	failedStartResult,
 	formatCompletionBlock,
 	modelLevelTakeoverNote,
+	reviewFailFollowUpNote,
 	queuedResult,
 } from "./format.ts";
 import {
@@ -66,6 +66,7 @@ import type { SubagentRuntime, SubagentThread, ThreadState } from "./runtime.ts"
 import { forkRetainedSession } from "./session-fork.ts";
 import {
 	buildResumePrompt,
+	getProjectRoot,
 	getResultOutput,
 	RpcRunControl,
 	isFailedResult,
@@ -81,7 +82,6 @@ import {
 	isProcessAlive,
 	killProcessTree,
 	sweepOrphanTempDirs,
-	sweepUnreferencedState,
 } from "./temp-hygiene.ts";
 import {
 	createWorktreeIsolation,
@@ -220,16 +220,19 @@ export function ownsResumeReservation(
 	);
 }
 
-/** Fire-and-forget durable checkpoint write. The live session keeps working
- * when the manifest is unwritable; only cross-reload resume is degraded. */
+/** Fire-and-forget durable checkpoint. Parked threads stay resumable across
+ * reloads; a settled thread drops its record so the manifest only exists
+ * while unfinished work needs it. The live session keeps working when the
+ * manifest is unwritable; only cross-reload resume is degraded. */
 export function persistThreadCheckpoint(
 	runtime: SubagentRuntime,
 	thread: SubagentThread,
 	state: "parked" | "completed" | "failed",
 ): void {
-	void upsertThreadRecord(runtime.configPath, threadRecordFromThread(thread, state)).catch(
-		() => undefined,
-	);
+	const write = state === "parked"
+		? upsertThreadRecord(runtime.configPath, threadRecordFromThread(thread, state))
+		: removeThreadRecord(runtime.configPath, thread.id);
+	void write.catch(() => undefined);
 }
 
 const WORKTREE_ISOLATION_INSTRUCTIONS =
@@ -246,27 +249,6 @@ export function isWorktreeCapableAgent(agent: AgentConfig): boolean {
 	return isWriteCapableAgent(agent);
 }
 
-/** A direct reviewer otherwise cannot infer enabled-role availability from its
- * isolated task. Managed internal gates receive the same contract in their
- * generated briefs. Advisory reviews still emit neither machine marker. */
-function withEnabledDocumenterReviewContract(agent: AgentConfig): AgentConfig {
-	return {
-		...agent,
-		systemPrompt: `${agent.systemPrompt.trimEnd()}\n\nRuntime workflow context: documenter is enabled. In gate reviews, documentation drift is non-gating: emit DOCUMENTATION: NEEDED with ## Documentation notes, or DOCUMENTATION: CLEAN when no sync is needed. Advisory reviews still emit neither VERDICT nor DOCUMENTATION markers.`.trim(),
-	};
-}
-
-/** The dispatcher explicitly requested a report-only review: forbid the gate
- * markers at the source and (in dispatch) refuse to chain on them anyway. */
-function withAdvisoryReviewContract(agent: AgentConfig): AgentConfig {
-	return {
-		...agent,
-		systemPrompt: `${agent.systemPrompt.trimEnd()}
-
-Runtime workflow context: this dispatch is advisory. Report findings only; do not emit VERDICT or DOCUMENTATION markers — the runtime will not act on them.`.trim(),
-	};
-}
-
 export interface DispatchEnvironment {
 	ctx: ExtensionContext;
 	config: SubagentsConfig;
@@ -296,7 +278,6 @@ export interface StartBackgroundOptions {
 	environment?: DispatchEnvironment;
 	seed?: SessionSeed;
 	resumeReservation?: ResumeReservation;
-	advisoryReview?: boolean;
 }
 
 export type StartBackgroundInternal = (
@@ -421,20 +402,11 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 		const runCtx = baseEnvironment.ctx;
 		const runConfig = baseEnvironment.config;
 		const runAgents = baseEnvironment.agents;
-		const stateRoot = getStateRoot(runtime.configPath);
 		const discoveredAgent = runAgents.find((candidate) => candidate.name === agentName);
 		if (!discoveredAgent) return failedStartResult(agentName, task, `Unknown agent: "${agentName}".`);
 		const resolveLiveAgentTools = (candidate: AgentConfig): AgentConfig =>
 			resolveAgentTools({ ...candidate, tools: discoveredAgent.tools }, runtime.getActiveTools());
-		const resolvedAgent = resolveLiveAgentTools(discoveredAgent);
-		const advisoryReview = startOptions.advisoryReview ?? existingThread?.advisoryReview ?? false;
-		const agent = agentName === "reviewer"
-			? advisoryReview
-				? withAdvisoryReviewContract(resolvedAgent)
-				: runAgents.some((candidate) => candidate.name === "documenter")
-					? withEnabledDocumenterReviewContract(resolvedAgent)
-					: resolvedAgent
-			: resolvedAgent;
+		const agent = resolveLiveAgentTools(discoveredAgent);
 		if (isolation === "worktree" && !isWorktreeCapableAgent(agent)) {
 			return {
 				...failedStartResult(agentName, task, `Agent "${agentName}" is read-only; worktree isolation is available only to write-capable agents such as worker, cleaner, or documenter.`),
@@ -443,6 +415,9 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 		}
 
 		const originalCwd = resolve(cwd ?? runCtx.cwd);
+		const projectRoot = getProjectRoot(runtime.configPath, originalCwd);
+		const sessionsRoot = join(projectRoot, "sessions");
+		const worktreesRoot = join(projectRoot, "worktrees");
 		const previousWorktree = existingThread?.worktree;
 		let worktree = seed?.worktree ?? previousWorktree;
 		if (isolation === "worktree") {
@@ -455,7 +430,7 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 			}
 			if (!worktree) {
 				try {
-					worktree = await createWorktreeIsolation(originalCwd, { tempBaseDir: stateRoot });
+					worktree = await createWorktreeIsolation(originalCwd, { tempBaseDir: worktreesRoot });
 				} catch (error) {
 					return {
 						...failedStartResult(agentName, task, error instanceof Error ? error.message : String(error)),
@@ -528,7 +503,6 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 			thread.executionCwd = executionCwd;
 			thread.thinkingLevel = thinkingLevel;
 			thread.isolation = isolation;
-			thread.advisoryReview = advisoryReview;
 			thread.worktree = worktree;
 			thread.state = "queued";
 			thread.control = control;
@@ -552,7 +526,6 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 				executionCwd,
 				thinkingLevel,
 				isolation,
-				advisoryReview,
 				worktree,
 				state: "queued",
 				control,
@@ -576,10 +549,7 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 		const workflowAvailability = workflowAgentAvailability(runAgents);
 		const reserveManagedLane =
 			isolation === "shared" && canStartManagedWorkflow(agent, workflowAvailability);
-		// Assigned once enqueue returns; only read after the generation's first
-		// await, so the managed-continuation slot suspension always sees it.
-		let generationController: AbortController | undefined;
-		const runGeneration = async (backgroundSignal: AbortSignal): Promise<void> => {
+		const runGeneration = async (backgroundSignal: AbortSignal, controller: AbortController): Promise<void> => {
 				if (runtime.threads.get(runId)?.generation !== generation) return;
 				// Model/thinking config may have changed while this generation sat
 				// queued behind the concurrency limit. Re-resolve the route at actual
@@ -615,7 +585,7 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 							control,
 							makeDetails: makeDetails("single", true),
 							idleTimeoutMs: activeIdleTimeoutMs,
-							sessionRoot: stateRoot,
+							sessionRoot: sessionsRoot,
 							...(priorSessionId && priorSessionDir
 								? {
 									sessionId: priorSessionId,
@@ -670,20 +640,20 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 				if (thread.lifecycleOperation === "stop") return;
 
 				// A shutdown can win in the microtask gap after the top-level RPC
-				// settles. Do not launch an obsolete documenter/reviewer or replace the
+				// settles. Do not launch an obsolete downstream gate or replace the
 				// stable top-level session with an aborted downstream attempt.
 				if (backgroundSignal.aborted || lifecycleInterrupted() || !runtime.sessionActive) return;
 
 				if (thread.retireOnSettle) runtime.retireThreadSession(thread);
 				let workflowOutcome: ManagedWorkflowOutcome | undefined;
-				const workflowPlan = getManagedWorkflowPlan(result, workflowAvailability, thread.advisoryReview);
+				const workflowPlan = getManagedWorkflowPlan(result, workflowAvailability);
 					if (workflowPlan && runtime.sessionActive) {
 						// The continuation is runtime-initiated (gate review,
 						// documentation sync): release this generation's
 						// concurrency slot so managed chains never starve manual
 						// dispatches. Cancellation and quiescence guarantees are
 						// unchanged — the task stays abortable and awaited.
-						runtime.backgroundQueue.suspend(generationController);
+						runtime.backgroundQueue.suspend(controller);
 						thread.state = "running";
 						// The stable parent row now represents workflow ownership, not whichever
 						// model stage ran most recently. Internal rows own their exact role/model/
@@ -799,7 +769,10 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 							: undefined;
 						const needsFullFinal = failed || (lastStep.result.agent === "reviewer" && finalVerdict !== "pass");
 						if (needsFullFinal) {
-							block += `\n\n${formatCompletionBlock(result, runConfig.maxResultLines, originalCwd)}`;
+							block += `\n\n${formatCompletionBlock(result, runConfig.maxResultLines, { resultRoot: projectResultsRoot(runtime.configPath, result.projectCwd ?? originalCwd) })}`;
+						}
+						if (finalVerdict === "fail") {
+							block += `\n\n${reviewFailFollowUpNote()}`;
 						}
 						if (modelLevel) block += `\n\n${modelLevelTakeoverNote(result, { runId })}`;
 						runtime.sendCompletionGroup([{
@@ -815,8 +788,10 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 					const completion: CompletionMessageItem = {
 						agent: result.agent,
 						block: modelLevel
-							? `${formatCompletionBlock(result, runConfig.maxResultLines, result.projectCwd ?? originalCwd)}\n\n${modelLevelTakeoverNote(result, { runId })}`
-							: formatCompletionBlock(result, runConfig.maxResultLines, result.projectCwd ?? originalCwd),
+							? `${formatCompletionBlock(result, runConfig.maxResultLines, { resultRoot: projectResultsRoot(runtime.configPath, result.projectCwd ?? originalCwd) })}\n\n${modelLevelTakeoverNote(result, { runId })}`
+							: result.agent === "reviewer" && reviewVerdict(getResultOutput(result)) === "fail"
+								? `${formatCompletionBlock(result, runConfig.maxResultLines, { resultRoot: projectResultsRoot(runtime.configPath, result.projectCwd ?? originalCwd) })}\n\n${reviewFailFollowUpNote()}`
+								: formatCompletionBlock(result, runConfig.maxResultLines, { resultRoot: projectResultsRoot(runtime.configPath, result.projectCwd ?? originalCwd) }),
 						triggerTurn: completionTriggersTurn(result, runConfig.notifyOnReviewPass),
 						usage: result.usage,
 					};
@@ -837,13 +812,21 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 				}
 			};
 		const queuedGeneration = reserveManagedLane
-			? async (backgroundSignal: AbortSignal): Promise<void> => {
-				await runInManagedRepositoryLane(
-					originalCwd,
-					() => runGeneration(backgroundSignal),
-					backgroundSignal,
-				);
-			}
+			? async (backgroundSignal: AbortSignal, controller: AbortController): Promise<void> => {
+					// This task may spend its whole life waiting for the repository
+					// lane (every shared write-capable generation serializes on it).
+					// Holding a process slot while only waiting let a batch of shared
+					// writers park the entire pool and starve independent read-only
+					// dispatches that could have started immediately, so the slot is
+					// released up front; the lane itself still serializes same-repo
+					// writers, and abort/quiesce guarantees are unchanged.
+					runtime.backgroundQueue.suspend(controller);
+					await runInManagedRepositoryLane(
+						originalCwd,
+						() => runGeneration(backgroundSignal, controller),
+						backgroundSignal,
+					);
+				}
 			: runGeneration;
 		const queueController = runtime.backgroundQueue.enqueue(
 			queuedGeneration,
@@ -915,7 +898,7 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 						runtime.sendCompletionGroup([
 							{
 								agent: crashed.agent,
-								block: formatCompletionBlock(crashed, runConfig.maxResultLines, crashed.projectCwd ?? originalCwd),
+								block: formatCompletionBlock(crashed, runConfig.maxResultLines, { resultRoot: projectResultsRoot(runtime.configPath, crashed.projectCwd ?? originalCwd) }),
 								triggerTurn: true,
 								usage: crashed.usage,
 							},
@@ -929,7 +912,6 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 				}
 			},
 		);
-		generationController = queueController;
 		thread.queueController = queueController;
 		thread.generationCompletion = runtime.backgroundQueue.waitForTask(queueController);
 		runtime.runControllers.set(runId, queueController);
@@ -946,7 +928,9 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 export function installThreadLifecycle(thread: SubagentThread, deps: ThreadLifecycleDeps): void {
 	const { runtime, startBackground } = deps;
 	const runId = thread.id;
-	const stateRoot = getStateRoot(runtime.configPath);
+	const projectRoot = getProjectRoot(runtime.configPath, thread.cwd);
+	const sessionsRoot = join(projectRoot, "sessions");
+	const worktreesRoot = join(projectRoot, "worktrees");
 
 	thread.notifyIsolationFailure = (finalization) => {
 		const paths = [finalization.worktreePath, finalization.patchPath].filter(Boolean).join(" · ");
@@ -1081,7 +1065,7 @@ export function installThreadLifecycle(thread: SubagentThread, deps: ThreadLifec
 		return createWorktreeIsolation(thread.cwd, {
 			seedCheckpoint,
 			seedIsIntegrated,
-			tempBaseDir: stateRoot,
+			tempBaseDir: worktreesRoot,
 		});
 	};
 
@@ -1169,7 +1153,7 @@ export function installThreadLifecycle(thread: SubagentThread, deps: ThreadLifec
 						targetCwd: continuationWorktree.cwd,
 						sessionDir: previousSessionDir,
 						sessionId: previousSessionId,
-						targetRoot: stateRoot,
+						targetRoot: sessionsRoot,
 					});
 					runtime.sessionDirs.add(clonedSession.sessionDir);
 					if (!ownsResumeReservation(runtime, thread, reservation)) {
@@ -1275,6 +1259,11 @@ async function discardRestoredRecord(runtime: SubagentRuntime, record: ThreadRec
 	await removeThreadRecord(runtime.configPath, record.runId).catch(() => undefined);
 }
 
+/** Project-scoped <projectRoot>/results for a completion's artifacts. */
+export function projectResultsRoot(configPath: string, cwd: string | undefined): string {
+	return join(getProjectRoot(configPath, cwd), "results");
+}
+
 function createRestoredThread(
 	runtime: SubagentRuntime,
 	record: ThreadRecord,
@@ -1290,7 +1279,6 @@ function createRestoredThread(
 		executionCwd: record.executionCwd,
 		...(record.thinkingLevel ? { thinkingLevel: record.thinkingLevel as ThinkingLevel } : {}),
 		isolation: record.isolation,
-		advisoryReview: false,
 		worktree,
 		state,
 		control: new RpcRunControl(record.task, record.generation),
@@ -1320,15 +1308,20 @@ function createRestoredThread(
 	return thread;
 }
 
-/** Rebuild parked and settled threads from the durable manifest after a reload
- * or restart. Orphaned children recorded by the previous process are killed
- * first; records whose retained session vanished drop out with their
- * artifacts. Returns the restored run ids. */
+/** Rebuild interrupted (parked) threads from the durable manifest after a
+ * reload or restart. Orphaned children recorded by the previous process are
+ * killed first; records whose retained session vanished — and settled records
+ * left by older versions, which hold no work worth resuming — drop out with
+ * their artifacts. Returns the restored run ids. */
 export async function restoreDurableThreads(runtime: SubagentRuntime): Promise<number[]> {
 	const records = await readThreadRecords(runtime.configPath);
 	const restoredIds: number[] = [];
 	for (const record of records) {
 		if (runtime.threads.has(record.runId) || monitor.findRun(record.runId)) continue;
+		if (record.state !== "parked") {
+			await discardRestoredRecord(runtime, record);
+			continue;
+		}
 		// A child orphaned by reload/crash may still hold the retained session.
 		// The on-disk session checkpoint is what survives; kill the writer.
 		for (const pid of record.childPids) {
@@ -1348,33 +1341,29 @@ export async function restoreDurableThreads(runtime: SubagentRuntime): Promise<n
 		// A worktree thread whose isolated filesystem is gone cannot continue its
 		// isolation invariant; surface it as failed instead of pretending.
 		const state: ThreadState = worktree
-			? record.state
+			? "parked"
 			: record.isolation === "worktree" && record.worktree
 				? "failed"
-				: record.state;
+				: "parked";
 		const thread = createRestoredThread(runtime, record, worktree, state);
 		runtime.threads.set(record.runId, thread);
 		runtime.sessionDirs.add(record.sessionDir!);
-		if (state === "parked") {
-			monitor.restoreRun({
-				id: record.runId,
-				agent: record.agentName,
-				task: record.task,
-				status: "parked",
-				elapsedMs: record.elapsedMs,
-				isolation: record.isolation,
-				...(record.worktree
-					? {
-						integrationStatus: record.worktree.state === "active"
-							? ("pending" as const)
-							: record.worktree.state,
-						...(worktree ? { worktreeId: worktreeGroupId(worktree) } : {}),
-					}
-					: {}),
-			});
-		} else if (thread.lastResult) {
-			runtime.registerRunResult(record.runId, thread.lastResult);
-		}
+		monitor.restoreRun({
+			id: record.runId,
+			agent: record.agentName,
+			task: record.task,
+			status: "parked",
+			elapsedMs: record.elapsedMs,
+			isolation: record.isolation,
+			...(record.worktree
+				? {
+					integrationStatus: record.worktree.state === "active"
+						? ("pending" as const)
+						: record.worktree.state,
+					...(worktree ? { worktreeId: worktreeGroupId(worktree) } : {}),
+				}
+				: {}),
+		});
 		restoredIds.push(record.runId);
 	}
 	return restoredIds;
@@ -1400,11 +1389,8 @@ export async function bootstrapDurableState(runtime: SubagentRuntime): Promise<v
 		/* temp hygiene is best-effort */
 	}
 	try {
-		sweepUnreferencedState(
-			getStateRoot(runtime.configPath),
-			referencedDurablePaths(await readThreadRecords(runtime.configPath)),
-		);
+		await pruneStaleProjectRoots(runtime.configPath);
 	} catch {
-		/* state hygiene is best-effort */
+		/* project-root hygiene is best-effort */
 	}
 }