@ferris1225/pi-subagents 4.3.9 → 4.3.10

package/src/isolation/worktree.ts

@@ -1,8 +1,8 @@
 /**
  * Detached Git worktree isolation for write-capable sub-agents.
  *
- * A handle is created before a child is queued and stays owned by the logical
- * thread across retries, model candidates, and resumes. Finalize
+ * A handle is created in the bounded queue and stays owned by the logical run
+ * across startup retries and model candidates. Finalize
  * is idempotent: it records a binary patch, applies it to the original working
  * tree without touching its index, then removes/prunes the temporary worktree.
  * Failed integration deliberately retains both the worktree and patch.
@@ -17,7 +17,6 @@ import {
 	runCommand,
 	type CommandResult,
 	type CommandRunner,
-	WORKTREE_PATCH_MAX_BYTES,
 } from "./git-command.ts";
 import { writeTempOwnerMarker } from "./temp-hygiene.ts";
 
@@ -25,9 +24,7 @@ export type IsolationMode = "shared" | "worktree";
 
 const WORKTREE_TEMP_DIR_PREFIX = "pi-subagent-worktree-";
 
-/** Short stable identity of one isolated worktree group (the mkdtemp suffix).
- * Continuation generations create a fresh worktree, so the identity
- * visibly changes when the group's filesystem boundary changes. */
+/** Short stable identity of one isolated worktree group (the mkdtemp suffix). */
 export function worktreeGroupId(worktree: Pick<WorktreeIsolation, "tempDir">): string {
 	const base = worktree.tempDir.split(/[\\/]/).filter(Boolean).pop() ?? worktree.tempDir;
 	return base.startsWith(WORKTREE_TEMP_DIR_PREFIX)
@@ -60,9 +57,8 @@ export interface WorktreeCheckpointRef {
 }
 
 /** Persistable projection of one worktree handle: enough to rebuild the
- * handle after a reload or restart. Patch bytes are deliberately omitted —
- * only the checkpoint commit, which lives in the shared repository object
- * store, is needed to seed a continuation. */
+ * handle after a reload or restart. Patch bytes are deliberately omitted;
+ * the checkpoint commit remains in the shared repository as recovery evidence. */
 export interface WorktreeSnapshot {
 	originalCwd: string;
 	originalRoot: string;
@@ -81,11 +77,6 @@ export interface WorktreeCreateOptions {
 	/** Parent directory for the worktree group: the project-scoped durable
 	 * worktrees root, so isolation never lands in the OS temp directory. */
 	tempBaseDir: string;
-	/** Complete source generation checkpoint merged onto the current HEAD. */
-	seedCheckpoint?: WorktreeCheckpoint;
-	/** The seed is already present in the parent checkout, so only later edits
-	 * should be integrated when this continuation settles. */
-	seedIsIntegrated?: boolean;
 }
 
 export type WorktreeFinalizationStatus = "integrated" | "no_changes" | "retained";
@@ -110,17 +101,12 @@ export interface WorktreeIsolation {
 	readonly tempDir: string;
 	readonly patchPath: string;
 	readonly head: string;
-	/** Diff base for final integration; a continuation baseline commit when
-	 * the generation was seeded with already-integrated work. */
+	/** Diff base retained in snapshots so recovery never reapplies integrated work. */
 	readonly integrationBaseHead: string;
 	readonly state: "active" | "finalizing" | WorktreeFinalizationStatus;
-	/** Checkpoint retained after finalization for continuation resumes. */
+	/** Checkpoint retained after finalization for recovery evidence. */
 	getContinuationCheckpoint(): WorktreeCheckpoint | undefined;
-	/** Capture the complete isolated filesystem state for a fresh continuation.
-	 * The synthetic commit lets Git merge an already-committed seed without
-	 * attempting to apply the same patch twice. */
-	snapshotCheckpoint(): Promise<WorktreeCheckpoint>;
-	/** Remove a newly-created continuation that failed before it was dispatched. */
+	/** Remove an unused worktree whose dispatch was cancelled. */
 	discard(): Promise<void>;
 	/** Whether anything is pending against the integration base — the same
 	 * question finalization answers as `hadChanges`, asked before settlement so
@@ -319,8 +305,7 @@ class GitWorktreeIsolation implements WorktreeIsolation {
 	private currentState: WorktreeIsolation["state"] = "active";
 	private finalization?: Promise<WorktreeFinalization>;
 	private discardPromise?: Promise<void>;
-	/** Full workspace checkpoint relative to the generation's starting HEAD,
-	 * retained after cleanup so settled threads can continue safely. */
+	/** Full workspace checkpoint retained for manual recovery. */
 	private continuationCheckpoint?: WorktreeCheckpoint;
 
 	constructor(
@@ -332,8 +317,7 @@ class GitWorktreeIsolation implements WorktreeIsolation {
 		readonly patchPath: string,
 		readonly head: string,
 		private readonly runner: CommandRunner,
-		/** May be a synthetic tree commit representing a seed that the parent
-		 * checkout already contains. Finalization then integrates only new edits. */
+		/** A restored base may represent work already integrated into the parent. */
 		readonly integrationBaseHead: string = head,
 		restored?: {
 			state: WorktreeIsolation["state"];
@@ -354,19 +338,6 @@ class GitWorktreeIsolation implements WorktreeIsolation {
 		return this.continuationCheckpoint ? cloneCheckpoint(this.continuationCheckpoint) : undefined;
 	}
 
-	async snapshotCheckpoint(): Promise<WorktreeCheckpoint> {
-		if (this.continuationCheckpoint) return cloneCheckpoint(this.continuationCheckpoint);
-		if (this.currentState === "no_changes") {
-			return { baseHead: this.head, commit: this.head, patch: Buffer.alloc(0) };
-		}
-		if (!existsSync(this.worktreePath)) {
-			throw new Error(`Cannot snapshot isolated worktree after it was removed: ${this.worktreePath}`);
-		}
-		const snapshot = await this.collectChanges(this.head);
-		this.continuationCheckpoint = await this.createCheckpoint(snapshot.stdout);
-		return cloneCheckpoint(this.continuationCheckpoint);
-	}
-
 	discard(): Promise<void> {
 		if (this.discardPromise) return this.discardPromise;
 		if (this.finalization) {
@@ -385,8 +356,8 @@ class GitWorktreeIsolation implements WorktreeIsolation {
 
 	async hasPendingChanges(): Promise<boolean> {
 		// A settled worktree already recorded the answer; asking Git again after
-		// removal would fail. Diffing the integration base (not HEAD) keeps a
-		// continuation honest: only this generation's own work counts.
+		// removal would fail. Diffing the integration base (not HEAD) excludes
+		// previously integrated work from the recovered run's pending changes.
 		if (this.currentState === "no_changes") return false;
 		if (this.currentState !== "active" || !existsSync(this.worktreePath)) return true;
 		const diff = await this.collectChanges(this.integrationBaseHead);
@@ -633,50 +604,6 @@ export async function createWorktreeIsolation(
 		await mkdir(isolatedCwd, { recursive: true });
 		await linkNodeModules(runner, target.originalRoot, worktreePath);
 
-		let integrationBaseHead = target.head;
-		const checkpoint = options.seedCheckpoint;
-		if (checkpoint && checkpoint.patch.length > WORKTREE_PATCH_MAX_BYTES) {
-			throw new Error(
-				`Isolated checkpoint exceeds the ${WORKTREE_PATCH_MAX_BYTES}-byte patch limit (${checkpoint.patch.length} bytes).`,
-			);
-		}
-		if (checkpoint && checkpoint.patch.length > 0) {
-			// Merge the checkpoint commit with today's HEAD instead of blindly
-			// applying its old patch. If the parent committed generation one after
-			// integration, Git recognizes the equivalent tree and produces HEAD
-			// unchanged; unrelated newer commits are preserved by the three-way merge.
-			const merged = await runGit(
-				runner,
-				worktreePath,
-				["merge-tree", "--write-tree", "--messages", target.head, checkpoint.commit],
-				`Merging isolated checkpoint into continuation ${worktreePath}`,
-			);
-			const mergedTree = merged.stdout.toString("utf8").split(/\r?\n/, 1)[0]?.trim();
-			if (!mergedTree) throw new Error("Git returned no merged continuation tree id.");
-			await runGit(
-				runner,
-				worktreePath,
-				["read-tree", "--reset", "-u", mergedTree],
-				`Materializing isolated checkpoint in ${worktreePath}`,
-			);
-			if (options.seedIsIntegrated) {
-				const commit = await runGit(
-					runner,
-					worktreePath,
-					[
-						"-c", "user.name=pi-subagents",
-						"-c", "user.email=pi-subagents@example.invalid",
-						"commit-tree", mergedTree,
-						"-p", target.head,
-						"-m", "pi-subagents continuation baseline",
-					],
-					`Creating continuation baseline commit in ${worktreePath}`,
-				);
-				integrationBaseHead = commit.stdout.toString("utf8").trim();
-				if (!integrationBaseHead) throw new Error("Git returned no continuation baseline commit id.");
-			}
-		}
-
 		return new GitWorktreeIsolation(
 			target.originalCwd,
 			target.originalRoot,
@@ -686,7 +613,6 @@ export async function createWorktreeIsolation(
 			patchPath,
 			target.head,
 			runner,
-			integrationBaseHead,
 		);
 	} catch (error) {
 		const rollbackErrors: string[] = [];
@@ -795,8 +721,7 @@ export function normalizeWorktreeSnapshot(value: unknown): WorktreeSnapshot | nu
 /** Rebuild a handle from a persisted snapshot. Returns undefined when the
  * on-disk worktree that an active/retained snapshot promises is gone; settled
  * states (integrated/no_changes) intentionally need no filesystem. The
- * restored checkpoint carries no patch bytes — only its commit is consumed by
- * continuation seeds. */
+ * restored checkpoint retains its commit identity without duplicating patch bytes. */
 export async function restoreWorktreeIsolation(
 	snapshot: WorktreeSnapshot,
 	options: { runner?: CommandRunner } = {},

package/src/lifecycle/durable.ts

@@ -43,9 +43,8 @@ const THREADS_MANIFEST_VERSION = 1;
  * win over the age rule. */
 export const PROJECT_ROOT_MAX_AGE_MS = 3 * 24 * 60 * 60 * 1_000;
 
-/** Fixed retention: parked work (which may hold unintegrated changes) stops
- * being resumable after a month. Older manifests may still carry settled
- * records from previous versions; restore discards them on sight. */
+/** Interrupted work retains its recovery record for a month. Older manifests
+ * may still carry settled records; restore discards those on sight. */
 export const PARKED_RECORD_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1_000;
 
 /** Result excerpts are for status display after restore, not full transcripts. */
@@ -84,7 +83,7 @@ export interface ThreadRecord {
 	executionCwd: string;
 	/** Resolved (clamped) level of the last generation. */
 	thinkingLevel?: string;
-	/** Level the dispatch requested; a resume after a restart re-runs at it. */
+	/** Originally requested level, retained with the recovery metadata. */
 	requestedThinkingLevel?: string;
 	isolation: IsolationMode;
 	state: "parked" | "completed" | "failed";
@@ -106,9 +105,8 @@ export function currentBootId(now = Date.now()): number {
 /** Whether a record's `childPids` can still name processes of this boot. Pids
  * are only unique within a boot: after a restart the same number belongs to
  * whatever claimed it, so restore must not signal them. Records written before
- * this field existed carry no boot id and count as unverifiable — leaving a
- * stray child alive costs a resumable session nothing, while killing an
- * unrelated process tree is not recoverable. */
+ * this field existed carry no boot id and count as unverifiable; leaving a
+ * stray child alive is safer than killing an unrelated process tree. */
 export function isCurrentBoot(record: ThreadRecord, now = Date.now()): boolean {
 	if (record.bootId === undefined) return false;
 	return Math.abs(record.bootId - currentBootId(now)) <= BOOT_ID_TOLERANCE_MS;
@@ -375,7 +373,7 @@ function summarizeResult(result: SingleResult): ThreadResultSummary | undefined
 
 /** Project a live thread into its durable record. Only handles whose
  * filesystem is still meaningful are persisted; finalized-and-removed
- * worktrees keep just their checkpoint commit for continuation resumes. */
+ * worktrees keep their checkpoint commit as recovery evidence. */
 export function threadRecordFromThread(
 	thread: SubagentThread,
 	state: "parked" | "completed" | "failed",

package/src/lifecycle/runtime.ts

@@ -1,15 +1,15 @@
 /**
  * Shared per-session runtime state for pi-subagents.
  *
- * The extension registers several tools (subagent, subagent_control/stop)
+ * The extension registers dispatch, read-only status, and destructive stop tools
  * that share the background queue, completion batcher, abort controllers per
  * run, and settled-results store.
  * `createRuntime` builds those once per extension load and hands the same object
  * to every registration site, so state stays in one place without globals.
  */
 
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { PhaseScope, PhaseScopeInput } from "../delegation/phase-scope.ts";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { PhaseScope } from "../delegation/phase-scope.ts";
 import { rmSync } from "node:fs";
 import { resolveSubagentConcurrency, BackgroundTaskQueue } from "../execution/background.ts";
 import {
@@ -23,21 +23,12 @@ import { type ThinkingLevel } from "../configuration/config.ts";
 import { removeThreadRecord, threadRecordFromThread, upsertThreadRecord, type ThreadRecord } from "./durable.ts";
 import { isRunActiveStatus, monitor } from "../presentation/monitor.ts";
 import type { RpcRunControl } from "../execution/rpc-control.ts";
-import type { StartBackgroundInternal } from "./thread-shared.ts";
 import { isFailedResult, type SingleResult } from "../execution/spawn.ts";
 import type { IsolationMode, WorktreeFinalization, WorktreeIsolation } from "../isolation/worktree.ts";
 
-export type ThreadState =
-	| "queued"
-	| "resuming"
-	| "running"
-	| "interrupting"
-	| "parked"
-	| "completed"
-	| "failed"
-	| "stopped";
+export type ThreadState = "queued" | "running" | "interrupting" | "parked" | "completed" | "failed" | "stopped";
 
-export type ThreadLifecycleOperation = "park" | "resume" | "stop" | "settle";
+export type ThreadLifecycleOperation = "stop" | "settle";
 
 export interface SubagentThread {
 	id: number;
@@ -46,53 +37,36 @@ export interface SubagentThread {
 	task: string;
 	phaseId?: string;
 	scope?: PhaseScope;
-	/** Monotonic continuation scope visible while resume preflight is in flight. */
-	admissionScope?: PhaseScope;
 	/** Capability snapshot used by declared-scope admission, including after restore. */
 	writeCapable?: boolean;
 	/** Caller-facing cwd in the original worktree. */
 	cwd: string;
 	/** Actual child cwd (the equivalent path inside an isolated worktree). */
 	executionCwd: string;
-	/** Level actually used, after clamping to the effective model's capability. */
 	thinkingLevel?: ThinkingLevel;
-	/** Level the dispatch asked for, before clamping; replayed on every resume. */
 	requestedThinkingLevel?: ThinkingLevel;
 	isolation: IsolationMode;
 	worktree?: WorktreeIsolation;
-	/** Durable restoration failure that permanently blocks continuation. */
-	resumeUnavailableReason?: string;
 	/** Original durable evidence retained when its worktree handle is unavailable. */
 	restorationRecord?: ThreadRecord;
 	state: ThreadState;
 	control: RpcRunControl;
 	queueController?: AbortController;
-	/** Resolves only after the current generation's child process, isolation
-	 * finalization, and queue work have fully quiesced and released their
-	 * concurrency slot. */
+	/** Resolves after the child, isolation finalization, and queue work fully quiesce. */
 	generationCompletion: Promise<void>;
-	/** Synchronous CAS used by lifecycle controls across their async preflight. */
+	/** Arbitration between asynchronous settlement and destructive stop. */
 	lifecycleVersion: number;
 	lifecycleOperation?: ThreadLifecycleOperation;
 	sessionId?: string;
 	sessionDir?: string;
-	/** Active execution time accumulated across retained resume generations. */
 	elapsedMs: number;
-	/** Most recent generation result, retained for parked destructive-stop output. */
+	/** Terminal or interrupted partial result; independent of the transient monitor row. */
 	lastResult?: SingleResult;
 	/** A destructive stop retires context even if the active child settles later. */
 	retireOnSettle?: boolean;
 	retired?: boolean;
-	/** Installed by dispatch so the control tool can restart the same logical id. */
-	resume: (
-		objective?: string,
-		ctx?: ExtensionContext,
-		metadata?: { scope?: PhaseScopeInput },
-	) => Promise<SingleResult>;
-	/** Dispatch-owned, generation-guarded worktree settlement hook. Its apply
-	 * runs under the canonical original-repository lane. */
+	/** All owners finalize under the same original-repository lane. */
 	finalizeIsolation: (generation: number, result?: SingleResult) => Promise<WorktreeFinalization | undefined>;
-	/** Best-effort shutdown notification for retained integration artifacts. */
 	notifyIsolationFailure?: (finalization: WorktreeFinalization) => void;
 	isolationFailureNotified?: boolean;
 }
@@ -104,9 +78,6 @@ 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;
 	/** Resolves when the load-time durable restore pass has finished. Everything
 	 * that answers "which threads exist" awaits it — the lookup tools, a fresh
 	 * dispatch before it allocates a run id, and the restored-thread notice — so
@@ -140,9 +111,6 @@ export interface SubagentRuntime {
 	registerRunResult: (runId: number, result: SingleResult) => void;
 	/** Logical threads outlive process attempts and completed generations. */
 	threads: Map<number, SubagentThread>;
-	/** 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. */
 	sessionDirs: Set<string>;
 	retainSession: (result: Pick<SingleResult, "sessionDir">) => void;
@@ -242,7 +210,6 @@ export function createRuntime(pi: ExtensionAPI, configPath: string): SubagentRun
 		settledRuns: new Map<number, SingleResult>(),
 		settledListeners: new Map<number, Set<(result: SingleResult) => void>>(),
 		threads: new Map<number, SubagentThread>(),
-		preflightOperations: new Set<Promise<void>>(),
 		sessionDirs: new Set<string>(),
 		retainSession: (result) => {
 			if (result.sessionDir) runtime.sessionDirs.add(result.sessionDir);
@@ -278,11 +245,9 @@ 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 liveStates = new Set(["queued", "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 preflight checks both this version and sessionActive, then
-			// cleans any worktree/session it created before resolving its tracker.
+			// Invalidate pending lifecycle claims synchronously before the first await.
 			// 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) =>
@@ -299,29 +264,21 @@ export function createRuntime(pi: ExtensionAPI, configPath: string): SubagentRun
 				if (thread.lifecycleOperation === "settle") continue;
 				thread.lifecycleOperation = "stop";
 				// Deliberately NOT retireOnSettle: shutdown interrupts to the last
-				// checkpoint but keeps the session/worktree resumable across reload.
+				// checkpoint and preserves session/worktree artifacts for manual recovery.
 				thread.retireOnSettle = false;
 				if (liveStates.has(thread.state)) thread.state = "stopped";
 			}
-			const preflights = [...runtime.preflightOperations];
 			runtime.completionBatcher.dispose();
-			// Held items are dropped exactly like the batcher's abandoned ones: the
-			// session is gone, so there is no window left to deliver them into.
+			// The parent session is gone; no window remains for buffered delivery.
 			heldCompletions = [];
 			compactionInFlight = false;
 			runtime.backgroundQueue.cancelAll();
-			// Await live RPC process-tree cleanup and continuation preflight rollback
-			// before persisting records or releasing ownership maps.
+			// Quiesce child processes and owned queue work before persisting records.
 			await Promise.all([
-				Promise.all(
-					interrupting.map((thread) =>
-						thread.control.stop("Parent session shut down").catch(() => undefined),
-					),
-				),
-				Promise.allSettled(preflights),
+				...interrupting.map((thread) => thread.control.stop("Parent session shut down").catch(() => undefined)),
 				runtime.backgroundQueue.waitForIdle(),
 			]);
-			// Only interrupted (parked) threads stay resumable across reloads:
+			// Only interrupted work keeps recovery artifacts across reloads:
 			// each keeps its durable record and retained artifacts. Settled
 			// threads drop their record — the manifest exists only while
 			// unfinished work needs it — and their sessions are deleted now. A
@@ -332,16 +289,13 @@ export function createRuntime(pi: ExtensionAPI, configPath: string): SubagentRun
 			const records: ThreadRecord[] = [];
 			for (const thread of runtime.threads.values()) {
 				if (thread.retired) continue;
-				if (thread.resumeUnavailableReason) {
-					// Restoration failures retain their durable evidence and session until
-					// an explicit destructive stop retires them.
-					if (thread.restorationRecord) {
-						records.push({
-							...thread.restorationRecord,
-							updatedAt: Date.now(),
-							elapsedMs: thread.elapsedMs,
-						});
-					}
+				if (thread.restorationRecord) {
+					// Keep recovery evidence until an explicit destructive stop retires it.
+					records.push({
+						...thread.restorationRecord,
+						updatedAt: Date.now(),
+						elapsedMs: thread.elapsedMs,
+					});
 					continue;
 				}
 				const previous = previousStates.get(thread.id) ?? thread.state;
@@ -382,7 +336,6 @@ export function createRuntime(pi: ExtensionAPI, configPath: string): SubagentRun
 			// 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();
 			monitor.clear();
 		},