@ferris1225/pi-subagents 4.2.2 → 4.2.5

package/README.md

@@ -127,7 +127,9 @@ main agent inspects the actual changes before calling anything done.
   as a lane wait, not as slot queueing, and its process slot is already released.
 - Setup and integration failures keep the useful patch and worktree, and record
   where they are in `~/.pi/agent/pi-subagents-recovery.json`. Every later session
-  start repeats that notice until you remove the artifacts.
+  start repeats that notice until you remove the artifacts. When the changes had
+  already been applied and only the cleanup failed, the next session start
+  removes the retained copy itself and clears the notice.
 
 ## Threads: resume, stop
 
@@ -313,8 +315,8 @@ that removes it, so this directory does not grow without bound:
 | Path                                       | Holds                                                | Removed                                                          |
 | ------------------------------------------ | ---------------------------------------------------- | ---------------------------------------------------------------- |
 | `pi-subagents.json`                        | Your configuration                                   | Never — it is yours                                              |
-| `pi-subagents-threads.json`                | One record per interrupted thread                     | When the thread settles, or after 30 days                        |
 | `pi-subagents-recovery.json`               | Worktree integration and cleanup failures            | When the retained patch or worktree it points at is gone         |
+| `ferris-pi-subagents/<project>/pi-subagents-threads.json` | One record per interrupted thread     | When the thread settles, or after 30 days                        |
 | `ferris-pi-subagents/<project>/sessions/`  | Retained child sessions that a resume continues from | When the pi session that produced it ends, or its owner is gone  |
 | `ferris-pi-subagents/<project>/worktrees/` | Isolated checkouts for parallel writers              | On integration, or when its owning process is gone               |
 | `ferris-pi-subagents/<project>/results/`   | Full text of truncated results                       | After 7 days, or beyond 50 per project                           |

package/agents/explorer.md

@@ -26,15 +26,12 @@ Thoroughness scales with the task (default medium): quick = targeted lookups in
 
 ## Final response
 
-Return only actionable retrieval results:
+Return only retrieval results, one bare bullet per finding — a single line: path, the fact, nothing else:
 
 ```text
-## Findings
-- `path/to/file.ts:10-50` — fact the caller needs
-## Start Here
-- `path/to/file.ts` — first symbol/section to verify and why
-## Gaps
-- unresolved uncertainty (omit this section when none)
+- `path/to/file.ts:10-50` — the fact
+Start here: `path/to/file.ts` — entry symbol and why (only when the caller could not guess it)
+Gaps: unresolved uncertainty (only when real)
 ```
 
-Do not repeat the task brief, inventory every file opened, paste nonessential code, or narrate search/tool chronology; report only unresolved blockers. Terse and factual: exact paths and line numbers, compressed evidence. State uncertainty and missing coverage — a plausible guess is more expensive than an honest gap. Keep the final response comfortably below the 40-line delivery cap unless the requested findings genuinely require more.
+No preamble or closing summary. Do not repeat the task brief, inventory every file opened, paste nonessential code, or narrate the search; every line must carry a path with a fact or name a gap — delete anything else. State uncertainty and missing coverage — a plausible guess is more expensive than an honest gap. Stay under 15 lines by default; go longer only when the brief genuinely demands a wide survey — the 40-line delivery cap truncates your tail (usually the Gaps) and the caller pays for every line.

package/package.json

@@ -1,55 +1,55 @@
-{
-  "name": "@ferris1225/pi-subagents",
-  "version": "4.2.2",
-  "description": "A managed sub-agent team for pi: specialized roles, pre-commit documentation sync, retained threads, auto-fix chains, model fallback, and Git worktree isolation.",
-  "type": "module",
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  },
-  "keywords": [
-    "pi-package",
-    "pi-extension",
-    "subagent",
-    "sub-agent",
-    "delegation",
-    "code-cleanup",
-    "dead-code"
-  ],
-  "files": [
-    "src",
-    "agents",
-    "README.md",
-    "LICENSE"
-  ],
-  "pi": {
-    "extensions": [
-      "./src/index.ts"
-    ]
-  },
-  "scripts": {
-    "check": "tsc --noEmit",
-    "test": "vitest run tests",
-    "prepack": "npm run check && npm test"
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-agent-core": ">=0.84.4",
-    "@earendil-works/pi-ai": ">=0.84.4",
-    "@earendil-works/pi-coding-agent": ">=0.84.4",
-    "@earendil-works/pi-tui": ">=0.84.4",
-    "typebox": "*"
-  },
-  "devDependencies": {
-    "@earendil-works/pi-agent-core": "^0.84.4",
-    "@earendil-works/pi-ai": "^0.84.4",
-    "@earendil-works/pi-coding-agent": "^0.84.4",
-    "@earendil-works/pi-tui": "^0.84.4",
-    "@types/node": "^22.10.0",
-    "typebox": "^1.3.9",
-    "typescript": "^5.9.0",
-    "vitest": "^4.1.0"
-  },
-  "engines": {
-    "node": ">=22.19.0"
-  }
-}
+{
+  "name": "@ferris1225/pi-subagents",
+  "version": "4.2.5",
+  "description": "A managed sub-agent team for pi: specialized roles, pre-commit documentation sync, retained threads, auto-fix chains, model fallback, and Git worktree isolation.",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "subagent",
+    "sub-agent",
+    "delegation",
+    "code-cleanup",
+    "dead-code"
+  ],
+  "files": [
+    "src",
+    "agents",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "vitest run tests",
+    "prepack": "npm run check && npm test"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": ">=0.84.4",
+    "@earendil-works/pi-ai": ">=0.84.4",
+    "@earendil-works/pi-coding-agent": ">=0.84.4",
+    "@earendil-works/pi-tui": ">=0.84.4",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-agent-core": "^0.84.4",
+    "@earendil-works/pi-ai": "^0.84.4",
+    "@earendil-works/pi-coding-agent": "^0.84.4",
+    "@earendil-works/pi-tui": "^0.84.4",
+    "@types/node": "^22.10.0",
+    "typebox": "^1.3.9",
+    "typescript": "^5.9.0",
+    "vitest": "^4.1.0"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  }
+}

package/src/durable.ts

@@ -1,12 +1,13 @@
 /**
- * Durable thread state: a manifest next to the config that lets interrupted
- * (parked) sub-agent threads survive pi reloads and restarts, plus the durable
- * state root that keeps their retained sessions and isolated worktrees out of
- * the OS temp directory.
+ * Durable thread state: one manifest per project, inside that project's durable
+ * root beside its sessions and worktrees, letting interrupted (parked)
+ * sub-agent threads survive pi reloads and restarts. The durable state root
+ * also keeps their retained sessions and isolated worktrees out of the OS temp
+ * directory.
  *
  * Only parked threads are ever recorded: a thread that settles normally drops
- * its record, so the manifest file exists exactly while unfinished work needs
- * it and disappears on its own. Records are small path/state snapshots, never
+ * its record, so a manifest file exists exactly while unfinished work needs it
+ * and disappears on its own. Records are small path/state snapshots, never
  * full transcripts; the retained Pi session files and worktrees they point at
  * remain the actual context. Writes are atomic (tmp+rename) and serialized
  * through the same withFileMutationQueue as the recovery manifest.
@@ -108,7 +109,15 @@ interface ThreadsManifest {
 	records: ThreadRecord[];
 }
 
-export function getThreadsManifestPath(configPath: string): string {
+/** Each project's manifest lives inside its durable root, beside the sessions
+ * and worktrees its records point at. */
+export function getThreadsManifestPath(configPath: string, cwd: string): string {
+	return join(getProjectRoot(configPath, cwd), THREADS_MANIFEST_FILE_NAME);
+}
+
+/** Location of the pre-per-project global manifest; only read by the
+ * one-time migration that folds it into the project roots. */
+function getLegacyManifestPath(configPath: string): string {
 	return join(dirname(configPath), THREADS_MANIFEST_FILE_NAME);
 }
 
@@ -181,9 +190,9 @@ function normalizeRecord(value: unknown): ThreadRecord | undefined {
 	};
 }
 
-export async function readThreadRecords(configPath: string): Promise<ThreadRecord[]> {
+async function readManifestRecords(path: string): Promise<ThreadRecord[]> {
 	try {
-		const parsed = JSON.parse(await readFile(getThreadsManifestPath(configPath), "utf8")) as {
+		const parsed = JSON.parse(await readFile(path, "utf8")) as {
 			records?: unknown;
 		};
 		if (!Array.isArray(parsed.records)) return [];
@@ -196,8 +205,28 @@ export async function readThreadRecords(configPath: string): Promise<ThreadRecor
 	}
 }
 
-async function writeManifest(configPath: string, records: readonly ThreadRecord[]): Promise<void> {
-	const path = getThreadsManifestPath(configPath);
+/** Manifest paths of every project that has a durable root. */
+function projectManifestPaths(durableRoot: string): string[] {
+	try {
+		return readdirSync(durableRoot, { withFileTypes: true })
+			.filter((entry) => entry.isDirectory() && !entry.isSymbolicLink())
+			.map((entry) => join(durableRoot, entry.name, THREADS_MANIFEST_FILE_NAME));
+	} catch {
+		return [];
+	}
+}
+
+/** Every parked record across all projects, for restore and the state-root
+ * sweeps that must see references from anywhere. */
+export async function readThreadRecords(configPath: string): Promise<ThreadRecord[]> {
+	const manifests = await Promise.all(
+		projectManifestPaths(join(dirname(configPath), PROJECT_ROOTS_DIR_NAME))
+			.map((path) => readManifestRecords(path)),
+	);
+	return manifests.flat();
+}
+
+async function writeManifest(path: string, records: readonly ThreadRecord[]): Promise<void> {
 	if (records.length === 0) {
 		await rm(path, { force: true });
 		return;
@@ -217,26 +246,26 @@ async function writeManifest(configPath: string, records: readonly ThreadRecord[
 }
 
 export async function upsertThreadRecord(configPath: string, record: ThreadRecord): Promise<void> {
-	const path = getThreadsManifestPath(configPath);
+	const path = getThreadsManifestPath(configPath, record.cwd);
 	await withFileMutationQueue(path, async () => {
-		const records = await readThreadRecords(configPath);
+		const records = await readManifestRecords(path);
 		const index = records.findIndex((candidate) => candidate.runId === record.runId);
 		const merged: ThreadRecord = index === -1
 			? record
 			: { ...record, createdAt: records[index]!.createdAt };
 		if (index === -1) records.push(merged);
 		else records[index] = merged;
-		await writeManifest(configPath, records);
+		await writeManifest(path, records);
 	});
 }
 
-export async function removeThreadRecord(configPath: string, runId: number): Promise<void> {
-	const path = getThreadsManifestPath(configPath);
+export async function removeThreadRecord(configPath: string, runId: number, cwd: string): Promise<void> {
+	const path = getThreadsManifestPath(configPath, cwd);
 	await withFileMutationQueue(path, async () => {
-		const records = await readThreadRecords(configPath);
+		const records = await readManifestRecords(path);
 		const next = records.filter((record) => record.runId !== runId);
 		if (next.length === records.length) return;
-		await writeManifest(configPath, next);
+		await writeManifest(path, next);
 	});
 }
 
@@ -334,22 +363,65 @@ export async function pruneThreadRecords(
 	configPath: string,
 	now = Date.now(),
 ): Promise<void> {
-	const path = getThreadsManifestPath(configPath);
-	await withFileMutationQueue(path, async () => {
-		const records = await readThreadRecords(configPath);
-		if (records.length === 0) return;
-		let changed = false;
-		const kept: ThreadRecord[] = [];
-		for (const record of records) {
-			if (now - record.updatedAt <= PARKED_RECORD_MAX_AGE_MS) {
-				kept.push(record);
-				continue;
+	const durableRoot = join(dirname(configPath), PROJECT_ROOTS_DIR_NAME);
+	for (const path of projectManifestPaths(durableRoot)) {
+		await withFileMutationQueue(path, async () => {
+			const records = await readManifestRecords(path);
+			if (records.length === 0) return;
+			let changed = false;
+			const kept: ThreadRecord[] = [];
+			for (const record of records) {
+				if (now - record.updatedAt <= PARKED_RECORD_MAX_AGE_MS) {
+					kept.push(record);
+					continue;
+				}
+				changed = true;
+				await discardRecordArtifacts(record);
 			}
-			changed = true;
-			await discardRecordArtifacts(record);
-		}
-		if (changed) await writeManifest(configPath, kept);
-	});
+			if (changed) await writeManifest(path, kept);
+		});
+	}
+}
+
+/** One-time move of the pre-per-project global manifest beside the config into
+ * the project roots its records belong to, so an upgrade keeps parked work
+ * resumable and pi home is left without a manifest. Existing project records
+ * win over legacy ones; the legacy file is removed only after every group
+ * landed, and an unreadable file stays put for the next boot. */
+export async function migrateLegacyThreadsManifest(configPath: string): Promise<void> {
+	const legacyPath = getLegacyManifestPath(configPath);
+	let records: ThreadRecord[];
+	try {
+		const parsed = JSON.parse(await readFile(legacyPath, "utf8")) as { records?: unknown };
+		if (!Array.isArray(parsed.records)) return;
+		records = parsed.records.flatMap((record) => {
+			const normalized = normalizeRecord(record);
+			return normalized ? [normalized] : [];
+		});
+	} catch {
+		return;
+	}
+	const groups = new Map<string, ThreadRecord[]>();
+	for (const record of records) {
+		const path = getThreadsManifestPath(configPath, record.cwd);
+		const group = groups.get(path);
+		if (group) group.push(record);
+		else groups.set(path, [record]);
+	}
+	let migrated = true;
+	for (const [path, group] of groups) {
+		await withFileMutationQueue(path, async () => {
+			const existing = await readManifestRecords(path);
+			const merged = [...existing];
+			for (const record of group) {
+				if (!merged.some((candidate) => candidate.runId === record.runId)) merged.push(record);
+			}
+			await writeManifest(path, merged);
+		}).catch(() => {
+			migrated = false;
+		});
+	}
+	if (migrated) await rm(legacyPath, { force: true }).catch(() => undefined);
 }
 
 /** Paths a manifest still references; used by the state-root sweep so

package/src/recovery.ts

@@ -5,7 +5,7 @@ import { existsSync } from "node:fs";
 import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { stripVTControlCharacters } from "node:util";
-import type { WorktreeFinalization } from "./worktree.ts";
+import { removeWorktreeGroup, worktreeGroupDir, type WorktreeFinalization } from "./worktree.ts";
 
 export const RECOVERY_MANIFEST_FILE_NAME = "pi-subagents-recovery.json";
 const RECOVERY_MANIFEST_VERSION = 1;
@@ -14,6 +14,8 @@ export interface RecoveryRecord {
 	runId: number;
 	createdAt: number;
 	integrated: boolean;
+	/** Repository a cleanup retry can prune stale worktree metadata against. */
+	originalRoot?: string;
 	worktreePath?: string;
 	patchPath?: string;
 	error?: string;
@@ -37,6 +39,7 @@ function normalizeRecord(value: unknown): RecoveryRecord | undefined {
 		runId: raw.runId,
 		createdAt: raw.createdAt,
 		integrated: raw.integrated === true,
+		...(typeof raw.originalRoot === "string" && raw.originalRoot ? { originalRoot: raw.originalRoot } : {}),
 		...(typeof raw.worktreePath === "string" && raw.worktreePath ? { worktreePath: raw.worktreePath } : {}),
 		...(typeof raw.patchPath === "string" && raw.patchPath ? { patchPath: raw.patchPath } : {}),
 		...(typeof raw.error === "string" && raw.error ? { error: raw.error } : {}),
@@ -105,6 +108,7 @@ export function recoveryRecordFromFinalization(
 		runId,
 		createdAt: now,
 		integrated: finalization.integrated,
+		...(finalization.originalRoot ? { originalRoot: finalization.originalRoot } : {}),
 		...(finalization.worktreePath ? { worktreePath: finalization.worktreePath } : {}),
 		...(finalization.patchPath ? { patchPath: finalization.patchPath } : {}),
 		...(finalization.error ? { error: finalization.error } : {}),
@@ -112,7 +116,10 @@ export function recoveryRecordFromFinalization(
 }
 
 /** Show retained recovery paths on every later session start until the user
- * removes the artifacts. Stale records are pruned automatically. */
+ * removes the artifacts. Records whose changes already landed only need the
+ * worktree group deleted — the step whose failure retained them — so each
+ * session start retries that removal first and forgets records it completes.
+ * Stale records are pruned automatically. */
 export async function announceRecoveryRecords(
 	configPath: string,
 	ctx: {
@@ -123,6 +130,17 @@ export async function announceRecoveryRecords(
 	if (ctx.hasUI === false) return;
 	const records = await readRecoveryRecords(configPath);
 	if (records.length === 0) return;
+	for (const record of records) {
+		if (!record.integrated || !record.worktreePath) continue;
+		const groupDir = worktreeGroupDir(record.worktreePath);
+		if (!groupDir) continue;
+		if (!existsSync(record.worktreePath) && !(record.patchPath ? existsSync(record.patchPath) : false)) continue;
+		await removeWorktreeGroup({
+			originalRoot: record.originalRoot,
+			worktreePath: record.worktreePath,
+			tempDir: groupDir,
+		});
+	}
 	const live = records.filter((record) =>
 		(record.worktreePath ? existsSync(record.worktreePath) : false) ||
 		(record.patchPath ? existsSync(record.patchPath) : false),