@ferris1225/pi-subagents 4.1.18 → 4.1.21

package/src/prompt.ts

@@ -24,56 +24,49 @@ export function buildDelegationDirective(
 	const hasCleaner = agents.some((agent) => agent.name === "cleaner");
 	const hasDocumenter = agents.some((agent) => agent.name === "documenter");
 	const hasReviewer = agents.some((agent) => agent.name === "reviewer");
+	const hasSynthesizer = agents.some((agent) => agent.name === "synthesizer");
 	const codeWriterNames = [
 		...(hasWorker ? ["worker"] : []),
 		...(hasCleaner ? ["cleaner"] : []),
 	];
-	const namedWorktreeTargets = [
-		...(hasWorker ? ["worker"] : []),
-		...(hasCleaner ? ["cleaner"] : []),
-		...(hasDocumenter ? ["documenter"] : []),
-	];
-	const worktreeTargets = namedWorktreeTargets.length === 0
-		? "a"
-		: namedWorktreeTargets.length === 1
-			? `${namedWorktreeTargets[0]} or another`
-			: `${namedWorktreeTargets.slice(0, -1).join(", ")}, ${namedWorktreeTargets.at(-1)}, or another`;
 
 	const dispatchRules = [
-		`Delegate aggressively: child contexts are cheap, yours is scarce. Inline only trivial work — a one-shot lookup, a single focused edit, an answer already in context${hasWorker ? "; default every non-trivial implementation, fix, refactor, or test task to `worker`" : ""}.`,
+		`Delegate aggressively: child contexts are cheap, yours is scarce. Inline only trivial work — a lookup, a single focused edit, an answer already in context${hasWorker ? "; default every non-trivial implementation, fix, refactor, or test task to `worker`" : ""}.`,
 		...(hasExplorer
 			? [
-				"`explorer`: broad or multi-file search. Its findings are leads, never proof — re-read load-bearing files before acting yourself (a child you brief re-verifies). Split a broad question into several parallel explorers with disjoint scopes.",
+				"`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).",
 			]
 			: []),
 		...(hasCleaner
-			? ["`cleaner`: only user-authorized cleanup or dedup; it applies every safe proven cut without per-item approval and is never a gate."]
+			? ["`cleaner`: dispatch for requested cleanup AND proactively when finished work leaves dead code or duplication. Your brief is its edit authorization — every safe proven cut applies without per-item approval; never a gate. Scope: the uncommitted diff, or whatever your brief names (Git range, directory)."]
 			: []),
 		...(hasDocumenter
-			? ["`documenter`: standalone docs/comment work, or syncing real drift a change left — writers already sync what they directly affect."]
+			? ["`documenter`: standalone docs/comment work; dispatch it proactively when a change — yours or a child's — leaves README/docs/comment drift no writer already synced; cheap and may make zero edits."]
 			: []),
 		...(hasReviewer
 			? [
-				`\`reviewer\`: read-only assessments and gates${codeWriterNames.length > 0 ? `; successful ${codeWriterNames.join("/")} runs get one fresh gate, and failing gates are fixed by the reviewer itself in bounded fix/re-review rounds that converge on the fixes (a still-failing gate returns to you)` : ""}. Advisory output has no VERDICT and cannot authorize edits.`,
+				`\`reviewer\`: read-only assessments and gates${codeWriterNames.length > 0 ? `; successful ${codeWriterNames.join("/")} runs get one fresh gate, and failing gates are fixed by the reviewer itself in bounded fix/re-review rounds (a still-failing gate returns to you). Pass \`review: "none"\` for mechanical, low-risk edits you verify yourself; keep the default gate whenever behavior can change` : ""}. Advisory output has no VERDICT and cannot authorize edits.`,
 			]
 			: []),
+		...(hasSynthesizer
+			? ["`synthesizer`: after a wide fan-out, pass the result-artifact paths to one synthesizer and read its brief instead of every result yourself."]
+			: []),
 		`Parallelize by default: map the todo list onto ONE \`tasks\` dispatch. One child owns one deliverable and its files; only genuinely dependent work waits for its prerequisite.`,
 		"Brief each child completely — goal, exact paths, constraints, expected output; it has no conversation memory and cannot delegate. Resume parked threads with `subagent_control resume`.",
-		`Request \`isolation: "worktree"\` only for ${worktreeTargets} write-capable agent in a repo with committed HEAD.`,
 	];
 
 	const handoffRules = [
-		"Dispatch never blocks or ends your turn — keep working; each completion resumes you automatically. Never sleep, poll, or `subagent_wait` to hold the turn.",
+		"Dispatch never blocks or ends your turn — keep working; each completion resumes you automatically. Never sleep or poll for it.",
 		"Results are already shown; add only your conclusion or next action, never a restatement.",
-		"Before declaring the overall task done, `subagent_status` must show no active runs.",
+		"Never declare the overall task done while a dispatched run is still active.",
 	];
 
 	const verificationRules = [
 		"Never report an unrun check as passed; surface unavailable checks and pre-existing failures, and inspect actual changes before reporting completion.",
 		...(hasReviewer
 			? [
-				"A REVIEW_FAIL from a gate you dispatched directly returns its findings to you: fix them inline or via a briefed worker without waiting for the user (ask only for genuinely destructive or scope-changing fixes), then re-verify ONCE. If the gate still fails, report the remaining findings and move on — never loop gate dispatches.",
-				"Multi-model cross-review only when explicitly requested or for high-risk security, unsafe/FFI, persistence-migration, or concurrency changes.",
+				"A REVIEW_FAIL from a gate you dispatched directly returns its findings to you: fix them inline or via a briefed worker without waiting for the user, then re-verify ONCE. If the gate still fails, report the remaining findings and move on — never loop gate dispatches.",
+				"Multi-model cross-review only when explicitly requested or for high-risk security, FFI, migration, or concurrency changes.",
 			]
 			: []),
 		"Commit or push only when explicitly requested, applicable checks pass, and no review finding remains unresolved.",
@@ -82,7 +75,7 @@ export function buildDelegationDirective(
 	return `
 ## Sub-agent delegation (pi-subagents)
 
-\`subagent\` runs isolated leaf Pi child processes in the background; each completion resumes you.
+\`subagent\` runs isolated leaf Pi child processes in the background.
 
 Agents:
 ${catalog}

package/src/recovery.ts

@@ -1,145 +1,145 @@
-/** Durable handoff for worktree integration/cleanup failures across sessions. */
-
-import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
-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";
-
-export const RECOVERY_MANIFEST_FILE_NAME = "pi-subagents-recovery.json";
-const RECOVERY_MANIFEST_VERSION = 1;
-
-export interface RecoveryRecord {
-	runId: number;
-	createdAt: number;
-	integrated: boolean;
-	worktreePath?: string;
-	patchPath?: string;
-	error?: string;
-}
-
-interface RecoveryManifest {
-	version: number;
-	records: RecoveryRecord[];
-}
-
-export function getRecoveryManifestPath(configPath: string): string {
-	return join(dirname(configPath), RECOVERY_MANIFEST_FILE_NAME);
-}
-
-function normalizeRecord(value: unknown): RecoveryRecord | undefined {
-	if (!value || typeof value !== "object") return undefined;
-	const raw = value as Record<string, unknown>;
-	if (typeof raw.runId !== "number" || !Number.isInteger(raw.runId) || raw.runId < 1) return undefined;
-	if (typeof raw.createdAt !== "number" || !Number.isFinite(raw.createdAt)) return undefined;
-	return {
-		runId: raw.runId,
-		createdAt: raw.createdAt,
-		integrated: raw.integrated === true,
-		...(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 } : {}),
-	};
-}
-
-export async function readRecoveryRecords(configPath: string): Promise<RecoveryRecord[]> {
-	try {
-		const parsed = JSON.parse(await readFile(getRecoveryManifestPath(configPath), "utf8")) as {
-			records?: unknown;
-		};
-		if (!Array.isArray(parsed.records)) return [];
-		return parsed.records.flatMap((record) => {
-			const normalized = normalizeRecord(record);
-			return normalized ? [normalized] : [];
-		});
-	} catch {
-		return [];
-	}
-}
-
-function recoveryKey(record: RecoveryRecord): string {
-	return `${record.runId}\0${record.worktreePath ?? ""}\0${record.patchPath ?? ""}\0${record.error ?? ""}`;
-}
-
-async function writeManifest(path: string, records: readonly RecoveryRecord[]): Promise<void> {
-	if (records.length === 0) {
-		await rm(path, { force: true });
-		return;
-	}
-	await mkdir(dirname(path), { recursive: true });
-	const temporaryPath = `${path}.${process.pid}.${Date.now()}.tmp`;
-	try {
-		const manifest: RecoveryManifest = {
-			version: RECOVERY_MANIFEST_VERSION,
-			records: [...records],
-		};
-		await writeFile(temporaryPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
-		await rename(temporaryPath, path);
-	} finally {
-		await rm(temporaryPath, { force: true }).catch(() => undefined);
-	}
-}
-
-/** Merge retained artifacts into the durable manifest. */
-export async function persistRecoveryRecords(
-	configPath: string,
-	records: readonly RecoveryRecord[],
-): Promise<void> {
-	if (records.length === 0) return;
-	const path = getRecoveryManifestPath(configPath);
-	await withFileMutationQueue(path, async () => {
-		const merged = new Map<string, RecoveryRecord>();
-		for (const record of await readRecoveryRecords(configPath)) merged.set(recoveryKey(record), record);
-		for (const record of records) merged.set(recoveryKey(record), record);
-		await writeManifest(path, [...merged.values()]);
-	});
-}
-
-export function recoveryRecordFromFinalization(
-	runId: number,
-	finalization: WorktreeFinalization,
-	now = Date.now(),
-): RecoveryRecord {
-	return {
-		runId,
-		createdAt: now,
-		integrated: finalization.integrated,
-		...(finalization.worktreePath ? { worktreePath: finalization.worktreePath } : {}),
-		...(finalization.patchPath ? { patchPath: finalization.patchPath } : {}),
-		...(finalization.error ? { error: finalization.error } : {}),
-	};
-}
-
-/** Show retained recovery paths on every later session start until the user
- * removes the artifacts. Stale records are pruned automatically. */
-export async function announceRecoveryRecords(
-	configPath: string,
-	ctx: {
-		hasUI?: boolean;
-		ui: { notify(message: string, kind: "info" | "warning" | "error"): void };
-	},
-): Promise<void> {
-	if (ctx.hasUI === false) return;
-	const records = await readRecoveryRecords(configPath);
-	if (records.length === 0) return;
-	const live = records.filter((record) =>
-		(record.worktreePath ? existsSync(record.worktreePath) : false) ||
-		(record.patchPath ? existsSync(record.patchPath) : false),
-	);
-	if (live.length !== records.length) {
-		const path = getRecoveryManifestPath(configPath);
-		await withFileMutationQueue(path, () => writeManifest(path, live)).catch(() => undefined);
-	}
-	for (const record of live) {
-		const paths = [
-			record.worktreePath ? `worktree ${stripVTControlCharacters(record.worktreePath)}` : undefined,
-			record.patchPath ? `patch ${stripVTControlCharacters(record.patchPath)}` : undefined,
-		].filter(Boolean).join(" · ");
-		const reason = record.error ? ` · ${stripVTControlCharacters(record.error)}` : "";
-		ctx.ui.notify(
-			`pi-subagents recovery for run #${record.runId}: ${record.integrated ? "changes were applied but cleanup failed" : "integration failed"}${paths ? ` · retained ${paths}` : ""}${reason}`,
-			"error",
-		);
-	}
-}
+/** Durable handoff for worktree integration/cleanup failures across sessions. */
+
+import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+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";
+
+export const RECOVERY_MANIFEST_FILE_NAME = "pi-subagents-recovery.json";
+const RECOVERY_MANIFEST_VERSION = 1;
+
+export interface RecoveryRecord {
+	runId: number;
+	createdAt: number;
+	integrated: boolean;
+	worktreePath?: string;
+	patchPath?: string;
+	error?: string;
+}
+
+interface RecoveryManifest {
+	version: number;
+	records: RecoveryRecord[];
+}
+
+export function getRecoveryManifestPath(configPath: string): string {
+	return join(dirname(configPath), RECOVERY_MANIFEST_FILE_NAME);
+}
+
+function normalizeRecord(value: unknown): RecoveryRecord | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const raw = value as Record<string, unknown>;
+	if (typeof raw.runId !== "number" || !Number.isInteger(raw.runId) || raw.runId < 1) return undefined;
+	if (typeof raw.createdAt !== "number" || !Number.isFinite(raw.createdAt)) return undefined;
+	return {
+		runId: raw.runId,
+		createdAt: raw.createdAt,
+		integrated: raw.integrated === true,
+		...(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 } : {}),
+	};
+}
+
+export async function readRecoveryRecords(configPath: string): Promise<RecoveryRecord[]> {
+	try {
+		const parsed = JSON.parse(await readFile(getRecoveryManifestPath(configPath), "utf8")) as {
+			records?: unknown;
+		};
+		if (!Array.isArray(parsed.records)) return [];
+		return parsed.records.flatMap((record) => {
+			const normalized = normalizeRecord(record);
+			return normalized ? [normalized] : [];
+		});
+	} catch {
+		return [];
+	}
+}
+
+function recoveryKey(record: RecoveryRecord): string {
+	return `${record.runId}\0${record.worktreePath ?? ""}\0${record.patchPath ?? ""}\0${record.error ?? ""}`;
+}
+
+async function writeManifest(path: string, records: readonly RecoveryRecord[]): Promise<void> {
+	if (records.length === 0) {
+		await rm(path, { force: true });
+		return;
+	}
+	await mkdir(dirname(path), { recursive: true });
+	const temporaryPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+	try {
+		const manifest: RecoveryManifest = {
+			version: RECOVERY_MANIFEST_VERSION,
+			records: [...records],
+		};
+		await writeFile(temporaryPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+		await rename(temporaryPath, path);
+	} finally {
+		await rm(temporaryPath, { force: true }).catch(() => undefined);
+	}
+}
+
+/** Merge retained artifacts into the durable manifest. */
+export async function persistRecoveryRecords(
+	configPath: string,
+	records: readonly RecoveryRecord[],
+): Promise<void> {
+	if (records.length === 0) return;
+	const path = getRecoveryManifestPath(configPath);
+	await withFileMutationQueue(path, async () => {
+		const merged = new Map<string, RecoveryRecord>();
+		for (const record of await readRecoveryRecords(configPath)) merged.set(recoveryKey(record), record);
+		for (const record of records) merged.set(recoveryKey(record), record);
+		await writeManifest(path, [...merged.values()]);
+	});
+}
+
+export function recoveryRecordFromFinalization(
+	runId: number,
+	finalization: WorktreeFinalization,
+	now = Date.now(),
+): RecoveryRecord {
+	return {
+		runId,
+		createdAt: now,
+		integrated: finalization.integrated,
+		...(finalization.worktreePath ? { worktreePath: finalization.worktreePath } : {}),
+		...(finalization.patchPath ? { patchPath: finalization.patchPath } : {}),
+		...(finalization.error ? { error: finalization.error } : {}),
+	};
+}
+
+/** Show retained recovery paths on every later session start until the user
+ * removes the artifacts. Stale records are pruned automatically. */
+export async function announceRecoveryRecords(
+	configPath: string,
+	ctx: {
+		hasUI?: boolean;
+		ui: { notify(message: string, kind: "info" | "warning" | "error"): void };
+	},
+): Promise<void> {
+	if (ctx.hasUI === false) return;
+	const records = await readRecoveryRecords(configPath);
+	if (records.length === 0) return;
+	const live = records.filter((record) =>
+		(record.worktreePath ? existsSync(record.worktreePath) : false) ||
+		(record.patchPath ? existsSync(record.patchPath) : false),
+	);
+	if (live.length !== records.length) {
+		const path = getRecoveryManifestPath(configPath);
+		await withFileMutationQueue(path, () => writeManifest(path, live)).catch(() => undefined);
+	}
+	for (const record of live) {
+		const paths = [
+			record.worktreePath ? `worktree ${stripVTControlCharacters(record.worktreePath)}` : undefined,
+			record.patchPath ? `patch ${stripVTControlCharacters(record.patchPath)}` : undefined,
+		].filter(Boolean).join(" · ");
+		const reason = record.error ? ` · ${stripVTControlCharacters(record.error)}` : "";
+		ctx.ui.notify(
+			`pi-subagents recovery for run #${record.runId}: ${record.integrated ? "changes were applied but cleanup failed" : "integration failed"}${paths ? ` · retained ${paths}` : ""}${reason}`,
+			"error",
+		);
+	}
+}