@ferris1225/pi-subagents 4.2.1 → 4.2.4

package/README.md

@@ -53,7 +53,7 @@ directly when you want exact control.
 
 | Agent         | Access    | Best for                                                                                                                                                                                                   |
 | ------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `explorer`    | Read-only | Broad search, unfamiliar-area mapping, symbol and dependency tracing. Returns a retrieval index — never proof.                                                                                              |
+| `explorer`    | Read-only | Broad search, unfamiliar-area mapping, symbol and dependency tracing. Returns a retrieval index — never proof. A single artifact the main agent must fully absorb (one issue, one spec) stays an inline read. |
 | `executor`    | Full      | The default route for any non-trivial, self-contained task: implementation, fixes, refactors, tests, evidence-first cleanup, docs/comment sync, or merging a fan-out's results into one brief — carried through verification and a result-only handoff. |
 
 Custom roles join them with a Markdown file (see [Custom agents](#custom-agents)).
@@ -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
 

package/agents/explorer.md

@@ -12,7 +12,7 @@ You are an explorer agent: a fast, read-only reconnaissance specialist. You inve
 ## Hard constraints
 
 - You are READ-ONLY. Never create, edit, or delete files; never run mutating commands. Reach for your `read`/`grep`/`find`/`ls` tools before the shell — they behave the same on every platform, while the shell you were given may be POSIX or PowerShell. Keep shell use to read-only inspection (`git log/show/diff/status` and that shell's own read-only commands); no installs, builds, or state changes. Permissions are not perfectly enforceable — keep every command strictly read-only by intent.
-- Every finding is a retrieval lead, never sufficient proof for deletion, security claims, public/API compatibility, persistence, or other load-bearing decisions. The caller must re-read load-bearing files before acting on your results.
+- Every finding is a retrieval lead, never sufficient proof for deletion, security claims, public/API compatibility, persistence, or other load-bearing decisions. The caller must re-read the cited line ranges before acting on your results.
 
 ## Workflow
 
@@ -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.1",
-  "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.4",
+  "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/prompt.ts

@@ -24,9 +24,10 @@ export function buildDelegationDirective(
 
 	const dispatchRules = [
 		`Delegate aggressively: child contexts are cheap, yours is scarce. Inline only trivial work — a lookup, a single focused edit, an answer already in context${hasExecutor ? "; default every non-trivial delegated task (implementation, fix, refactor, test, cleanup, docs sync, result merging) to `executor`" : ""}.`,
+		"A single artifact you must fully absorb yourself (one issue, one spec) is inline work — delegation saves search, not that read.",
 		...(hasExplorer
 			? [
-				"`explorer`: split a broad question into parallel explorers with disjoint scopes. Its findings are leads, never proof — re-read load-bearing files before acting yourself (a child you brief re-verifies).",
+				"`explorer`: split a broad question into parallel explorers with disjoint scopes. Its findings are leads, never proof — re-read the cited line ranges before acting on them (a child you brief re-verifies).",
 			]
 			: []),
 		...(hasExecutor
@@ -45,7 +46,7 @@ export function buildDelegationDirective(
 	];
 
 	const verificationRules = [
-		"Never report an unrun check as passed; surface unavailable checks and pre-existing failures, and inspect actual changes before reporting completion.",
+		"Never report an unrun check as passed; surface unavailable checks and pre-existing failures, and inspect the actual diff before reporting completion.",
 		"Commit or push only when explicitly requested and applicable checks pass.",
 	];
 

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),