@ferris1225/pi-subagents 0.31.0 → 1.0.0

package/src/monitor.ts

@@ -2,38 +2,28 @@
  * Sub-agent monitor: a module-level singleton store that tracks subagent runs
  * for the current turn.
  *
- * The store notifies subscribers on every mutation so the persistent widget
- * above the editor can re-render. Each run carries timing information
- * (started/ended) plus a concise activity string describing what the run is
- * doing right now ("thinking", "read src/index.ts", ...). Runs are removed
- * as soon as they finish: the tool result is the durable record in the main
- * conversation, so a stale "done" row must not linger in the widget.
+ * The store notifies wait/status consumers on every mutation. Each run carries
+ * timing information plus a concise activity string ("thinking",
+ * "read src/index.ts", ...). Runs are removed after publication; tool results
+ * and the finished-run registry are the durable user-facing records.
  */
 
 import { stripVTControlCharacters } from "node:util";
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { visibleWidth } from "@earendil-works/pi-tui";
 import type { UsageStats } from "./spawn.ts";
+import { redactSensitiveText } from "./trajectory.ts";
+import type { IsolationMode, WorktreeFinalizationStatus } from "./worktree.ts";
 
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
 
-export type RunStatus = "queued" | "running" | "done" | "failed";
+export type RunStatus = "queued" | "running" | "steering" | "interrupting" | "parked" | "done" | "failed";
 
-/** Soft state-awareness signals, complementary to the hard idle-kill: a run may
- * be alive (stdout streaming) yet "stuck thinking" (no tool running for a while),
- * or simply taking a long time. Both are surfaced as widget annotations so the
- * user can tell a healthy busy run from one that needs a nudge. */
-export type ActivityState = "needs_attention" | "active_long_running";
-
-/** A run with no tool running and no activity for this long is "needs attention"
- * (the model may be stuck between turns). Below the idle-kill threshold so the
- * soft signal always fires before the hard kill. */
-export const NEEDS_ATTENTION_AFTER_MS = 60_000;
-/** A run whose total elapsed time exceeds this is "long-running": still active
- * but worth flagging so the user can decide whether to wait or steer. */
-export const ACTIVE_LONG_RUNNING_AFTER_MS = 240_000;
+export function isRunActiveStatus(status: RunStatus): boolean {
+	return status === "queued" || status === "running" || status === "steering" || status === "interrupting";
+}
 
 export interface RunView {
 	id: number;
@@ -44,8 +34,14 @@ export interface RunView {
 	 * are doing, not just their run id. */
 	label?: string;
 	model?: string;
+	/** Primary model ref when the run advanced to another candidate in its pool. */
+	modelFallbackFrom?: string;
 	/** Effective thinking strength this run was launched with (frontmatter/config/global). */
 	thinking?: string;
+	isolation?: IsolationMode;
+	integrationStatus?: "pending" | WorktreeFinalizationStatus;
+	forkedFromRunId?: number;
+	forkChildRunIds?: number[];
 	status: RunStatus;
 	usage: UsageStats;
 	/** Concise current activity ("thinking", "read src/index.ts"); last writer wins. */
@@ -66,15 +62,14 @@ export interface RunView {
 	groupId?: string;
 	/** Human-readable role within a chain, e.g. "fix round 1" or "re-review round 1". */
 	relationLabel?: string;
-	/** Free-form note shown in the widget next to the status label (e.g. "auto-fix chain running"). */
+	/** Free-form orchestration note (e.g. "auto-fix chain running"). */
 	annotation?: string;
-	/** One-line outcome summary of a finished chain run, shown in the widget so
-	 * each auto-fix round reads as what it did: a reviewer reports its verdict
+	/** One-line outcome summary of a finished chain run: a reviewer reports its verdict
 	 * plus key fragments of what it found ("fail · src/index.ts · render()"), a
 	 * worker the fragments of what it changed. Unset for non-chain runs. */
 	summary?: string;
-	/** True when a finished run is intentionally kept in the widget (e.g. an
-	 * auto-fix chain parent whose chain is still running). beginTurn preserves
+	/** True when a finished run remains in monitor state (e.g. an auto-fix
+	 * parent whose chain is still running). beginTurn preserves
 	 * retained runs so they are not swept between turns. */
 	retained?: boolean;
 }
@@ -83,6 +78,8 @@ export interface RunView {
 export interface RunChainMeta {
 	groupId?: string;
 	relationLabel?: string;
+	isolation?: IsolationMode;
+	forkedFromRunId?: number;
 }
 
 // ---------------------------------------------------------------------------
@@ -94,7 +91,7 @@ const TASK_SUMMARY_ELLIPSIS = "…";
 /** Columns reserved at the END of a truncated summary so the distinguishing
  * keywords (paths, symbols, ...) survive; the head gets the rest. */
 const TASK_SUMMARY_TAIL_MAX = 28;
-/** Tail share of a non-default maxWidth (narrow widgets keep a usable tail). */
+/** Tail share of a non-default maxWidth (narrow summaries keep a usable tail). */
 const TASK_SUMMARY_TAIL_SHARE = 0.35;
 const TASK_SUMMARY_TAIL_MIN = 8;
 const TASK_SUMMARY_KEY_SEP = " · ";
@@ -292,63 +289,18 @@ export function formatElapsed(run: RunView, now: number = Date.now()): string {
 	return formatDuration(end - run.startedAt);
 }
 
-/** Strip the provider prefix from a "provider/model-id" reference for compact
- * widget display ("anthropic/claude-sonnet-4" → "claude-sonnet-4"). A bare id is
- * left unchanged. */
-export function compactModelRef(model: string | undefined): string {
-	if (!model) return "";
-	const slash = model.lastIndexOf("/");
-	return slash >= 0 ? model.slice(slash + 1) : model;
-}
-
-/** Human-readable label for a soft activity-state annotation. */
-export function activityStateLabel(state: ActivityState): string {
-	return state === "needs_attention" ? "idle" : "long-running";
-}
-
-/** Derive the soft activity state of a run at render time: needs_attention
- * (no tool running, idle past the threshold) takes priority over
- * active_long_running (total elapsed past its threshold). Both are suppressed
- * for non-running runs. */
-export function deriveActivityState(run: RunView, now: number = Date.now()): ActivityState | undefined {
-	if (run.status !== "running") return undefined;
-	if (!run.currentTool) {
-		const since = run.lastActivityAt ?? run.startedAt ?? now;
-		if (now - since >= NEEDS_ATTENTION_AFTER_MS) return "needs_attention";
-	}
-	if (run.startedAt !== undefined && now - run.startedAt >= ACTIVE_LONG_RUNNING_AFTER_MS) {
-		return "active_long_running";
-	}
-	return undefined;
-}
-
-/** Left/right split a widget line so the right side (status, elapsed) is always
- * visible and the left side (title) clips on overflow instead of pushing it off.
- * `left`/`right` may carry ANSI styling; widths are measured display-column-wise. */
-export function rightAlign(left: string, right: string, width: number): string {
-	const rightWidth = visibleWidth(right);
-	const leftMax = Math.max(0, width - rightWidth - 1);
-	const leftClipped = truncateToWidth(left, leftMax);
-	const gap = Math.max(1, width - visibleWidth(leftClipped) - rightWidth);
-	return truncateToWidth(`${leftClipped}${" ".repeat(gap)}${right}`, width);
-}
-
-/** Concatenate `left` and `right` (no center padding) and clip the combined line
- * to `width`. Unlike {@link rightAlign}, the right side trails the left side
- * instead of being pinned to the far edge, so a short header leaves no gap in
- * the middle. `right` should carry its own leading separator (e.g. ` \u00b7 `);
- * pass an empty string when there is nothing to append. Styled strings are
- * measured by display width. */
-export function compactLine(left: string, right: string, width: number): string {
-	return truncateToWidth(`${left}${right}`, width);
-}
-
 /** Max length of the argument target inside a formatted activity line. */
 export const ACTIVITY_TARGET_MAX = 60;
 
+/** Monitor activity is returned to the parent model and rendered in the terminal,
+ * so treat every live string as untrusted before it reaches store state. */
+function sanitizeActivityText(value: string): string {
+	return redactSensitiveText(value).replace(/\s+/g, " ").trim();
+}
+
 function shortTarget(value: unknown): string {
 	if (typeof value !== "string") return "";
-	const oneLine = value.replace(/\s+/g, " ").trim();
+	const oneLine = sanitizeActivityText(value);
 	// Slice by code point so emoji / CJK-ext never leave a lone surrogate.
 	const chars = [...oneLine];
 	return chars.length > ACTIVITY_TARGET_MAX ? `${chars.slice(0, ACTIVITY_TARGET_MAX - 1).join("")}…` : oneLine;
@@ -397,7 +349,8 @@ export function formatToolActivity(toolName: string, args: unknown): string {
 		default:
 			target = pick("path", "command", "query", "pattern", "url", "file", "task");
 	}
-	return target ? `${toolName} ${target}` : toolName;
+	const safeToolName = sanitizeActivityText(toolName) || "tool";
+	return target ? `${safeToolName} ${target}` : safeToolName;
 }
 
 // ---------------------------------------------------------------------------
@@ -416,7 +369,7 @@ export class MonitorStore {
 		// running) are also preserved — their status is "done" but they must
 		// stay visible until the chain resolves.
 		this.runs = this.runs.filter(
-			(r) => r.status === "queued" || r.status === "running" || r.retained,
+			(r) => isRunActiveStatus(r.status) || r.status === "parked" || r.retained,
 		);
 		this.notify();
 	}
@@ -434,6 +387,8 @@ export class MonitorStore {
 			usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
 			...(meta?.groupId ? { groupId: meta.groupId } : {}),
 			...(meta?.relationLabel ? { relationLabel: meta.relationLabel } : {}),
+			...(meta?.isolation ? { isolation: meta.isolation, integrationStatus: meta.isolation === "worktree" ? "pending" : undefined } : {}),
+			...(meta?.forkedFromRunId !== undefined ? { forkedFromRunId: meta.forkedFromRunId } : {}),
 		});
 		this.notify();
 		return id;
@@ -443,13 +398,13 @@ export class MonitorStore {
 		const run = this.find(id);
 		if (!run) return;
 		run.status = status;
-		if (status === "running") {
+		if (status === "running" || status === "steering" || status === "interrupting") {
 			if (run.startedAt === undefined) run.startedAt = Date.now();
-			// A model-fallback retry after a failed attempt restarts the clock; a
+			// A model-fallback retry or resumed generation restarts the clock; a
 			// stale endedAt would freeze the elapsed display at the first attempt.
 			if (run.endedAt !== undefined) run.endedAt = undefined;
 			run.lastActivityAt = Date.now();
-		} else if ((status === "done" || status === "failed") && run.endedAt === undefined) {
+		} else if ((status === "parked" || status === "done" || status === "failed") && run.endedAt === undefined) {
 			run.endedAt = Date.now();
 		}
 		this.notify();
@@ -463,11 +418,20 @@ export class MonitorStore {
 		this.notify();
 	}
 
+	/** Record the final actual model and primary-to-backup transition. */
+	setModel(id: number, model?: string, fallbackFrom?: string): void {
+		const run = this.find(id);
+		if (!run) return;
+		if (model) run.model = model;
+		run.modelFallbackFrom = fallbackFrom;
+		this.notify();
+	}
+
 	/** Update the run's current one-line activity (what it is doing now). */
 	setActivity(id: number, text: string): void {
 		const run = this.find(id);
 		if (!run) return;
-		run.activity = text;
+		run.activity = sanitizeActivityText(text) || undefined;
 		run.lastActivityAt = Date.now();
 		this.notify();
 	}
@@ -478,9 +442,10 @@ export class MonitorStore {
 	recordToolStart(id: number, toolName: string, activity: string): void {
 		const run = this.find(id);
 		if (!run) return;
+		const safeToolName = sanitizeActivityText(toolName) || "tool";
 		run.toolCount = (run.toolCount ?? 0) + 1;
-		run.currentTool = toolName;
-		run.activity = activity;
+		run.currentTool = safeToolName;
+		run.activity = sanitizeActivityText(activity) || safeToolName;
 		run.lastActivityAt = Date.now();
 		this.notify();
 	}
@@ -492,11 +457,11 @@ export class MonitorStore {
 		if (!run) return;
 		run.currentTool = undefined;
 		run.lastActivityAt = Date.now();
-		if (isError) run.activity = `✗ ${toolName} failed`;
+		if (isError) run.activity = `✗ ${sanitizeActivityText(toolName) || "tool"} failed`;
 		this.notify();
 	}
 
-	/** Set a widget note on the run (e.g. that its auto-fix chain is still running). */
+	/** Set an orchestration note on the run (e.g. auto-fix chain running). */
 	setAnnotation(id: number, text: string): void {
 		const run = this.find(id);
 		if (!run) return;
@@ -512,7 +477,7 @@ export class MonitorStore {
 		this.notify();
 	}
 
-	/** Mark a run as retained (kept in the widget despite being finished). */
+	/** Keep a finished chain step in status state until its group settles. */
 	setRetained(id: number, retained: boolean): void {
 		const run = this.find(id);
 		if (!run) return;
@@ -520,6 +485,73 @@ export class MonitorStore {
 		this.notify();
 	}
 
+	setIsolation(id: number, isolation: IsolationMode, integrationStatus?: "pending" | WorktreeFinalizationStatus): void {
+		const run = this.find(id);
+		if (!run) return;
+		run.isolation = isolation;
+		run.integrationStatus = integrationStatus;
+		this.notify();
+	}
+
+	setForkRelation(sourceRunId: number, childRunId: number): void {
+		const source = this.find(sourceRunId);
+		if (source) {
+			source.forkChildRunIds ??= [];
+			if (!source.forkChildRunIds.includes(childRunId)) source.forkChildRunIds.push(childRunId);
+		}
+		const child = this.find(childRunId);
+		if (child) child.forkedFromRunId = sourceRunId;
+		this.notify();
+	}
+
+	/** Update the objective shown for a queued retarget or resumed generation. */
+	setTask(id: number, task: string): void {
+		const run = this.find(id);
+		if (!run) return;
+		run.task = task;
+		run.label = runLabel(task);
+		this.notify();
+	}
+
+	/** Reuse a stable logical run id for a resumed generation. */
+	restartRun(id: number, agent: string, task: string, model?: string, thinking?: string, isolation?: IsolationMode): void {
+		const run = this.find(id);
+		if (!run) {
+			this.runs.push({
+				id,
+				agent,
+				task,
+				label: runLabel(task),
+				model,
+				thinking,
+				...(isolation ? { isolation, integrationStatus: isolation === "worktree" ? "pending" as const : undefined } : {}),
+				status: "queued",
+				usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+			});
+			this.notify();
+			return;
+		}
+		run.agent = agent;
+		run.task = task;
+		run.label = runLabel(task);
+		run.model = model;
+		run.thinking = thinking;
+		if (isolation) run.isolation = isolation;
+		run.integrationStatus = isolation === "worktree" ? "pending" : undefined;
+		run.status = "queued";
+		run.usage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 };
+		run.activity = undefined;
+		run.toolCount = undefined;
+		run.currentTool = undefined;
+		run.lastActivityAt = undefined;
+		run.startedAt = undefined;
+		run.endedAt = undefined;
+		run.annotation = undefined;
+		run.summary = undefined;
+		run.retained = undefined;
+		this.notify();
+	}
+
 	/** Look up a run by id without removing it. */
 	findRun(id: number): RunView | undefined {
 		return this.find(id);
@@ -533,7 +565,7 @@ export class MonitorStore {
 		this.notify();
 	}
 
-	/** Remove a run (finished runs leave the widget). Returns the removed run. */
+	/** Remove a run after publication. Returns the removed run. */
 	removeRun(id: number): RunView | undefined {
 		const index = this.runs.findIndex((r) => r.id === id);
 		if (index === -1) return undefined;
@@ -560,6 +592,7 @@ export class MonitorStore {
 		if (run.summary) parts.push(run.summary);
 		if (run.model) parts.push(run.model);
 		if (run.thinking) parts.push(`thinking ${run.thinking}`);
+		if (run.isolation === "worktree") parts.push(`worktree ${run.integrationStatus ?? "active"}`);
 		if (usage) parts.push(usage);
 		const elapsed = formatElapsed(run);
 		if (elapsed) parts.push(elapsed);
@@ -591,6 +624,12 @@ export function statusIcon(status: RunStatus, theme: Theme): string {
 	switch (status) {
 		case "running":
 			return theme.fg("accent", "●");
+		case "steering":
+			return theme.fg("accent", "◆");
+		case "interrupting":
+			return theme.fg("warning", "◐");
+		case "parked":
+			return theme.fg("dim", "■");
 		case "done":
 			return theme.fg("success", "✓");
 		case "failed":
@@ -600,13 +639,19 @@ export function statusIcon(status: RunStatus, theme: Theme): string {
 	}
 }
 
-/** User-facing status label shown in the widget. */
+/** User-facing status label used by tool/status rendering. */
 export function statusLabel(status: RunStatus): string {
 	switch (status) {
 		case "queued":
 			return "ready";
 		case "running":
 			return "running";
+		case "steering":
+			return "steering";
+		case "interrupting":
+			return "interrupting";
+		case "parked":
+			return "parked";
 		case "done":
 			return "done";
 		case "failed":
@@ -615,10 +660,13 @@ export function statusLabel(status: RunStatus): string {
 }
 
 /** Theme color matching the status label. */
-export function statusColor(status: RunStatus): "accent" | "success" | "error" | "dim" {
+export function statusColor(status: RunStatus): "accent" | "success" | "error" | "warning" | "dim" {
 	switch (status) {
 		case "running":
+		case "steering":
 			return "accent";
+		case "interrupting":
+			return "warning";
 		case "done":
 			return "success";
 		case "failed":

package/src/prompt.ts

@@ -58,8 +58,9 @@ ${routing ? `Routing:\n${routing}\n` : ""}Dispatch discipline:
 - Delegate only when isolation genuinely pays: a self-contained implementation/fix with its own validation (worker), or a fresh-context review gate (reviewer).
 - When in doubt, start with a direct tool call in the main context; escalate to \`explore\` as soon as the search turns broad or crosses multiple files.
 - For an already-known or trivial target, use a direct search/read tool (e.g. grep/find/read) — do not over-delegate a one-line lookup.
-${hasMultiple ? "- Run INDEPENDENT tasks in parallel: one subagent call with a `tasks` array, and track them with your todo list. Let the automatically resumed main agent launch dependent work only after its prerequisite result arrives (e.g. explore, then worker, then reviewer).\n" : ""}- Brief each sub-agent as self-contained: goal, exact paths, constraints, expected output. It has NO memory of this conversation.
-- Treat delegated agents as leaf workers: do not ask a sub-agent to dispatch another sub-agent; child processes do not have this tool.
+${hasMultiple ? "- Run INDEPENDENT tasks in parallel: one subagent call with a `tasks` array, and track them with your todo list. Parallel worker items default to detached Git worktree isolation; pass `isolation: \"shared\"` only when a worker intentionally needs the caller's live uncommitted tree. Let the automatically resumed main agent launch dependent work only after its prerequisite result arrives (e.g. explore, then worker, then reviewer).\n" : ""}- Single dispatch stays in the shared working tree by default. Use \`isolation: "worktree"\` only for worker/write-capable agents in a Git repository; never request it for explore/reviewer, and never silently retry shared after setup fails.
+- Brief each sub-agent as self-contained: goal, exact paths, constraints, expected output. It has NO memory of this conversation.
+- Treat delegated agents as leaf workers: do not ask a sub-agent to dispatch another sub-agent; child processes do not have this tool. Use \`subagent_control fork\` on a parked/settled retained thread when you need an independent continuation with preserved context and a new run id.
 - Trust but verify: a sub-agent's summary describes intent, not outcome. Check the actual changes/results before reporting work done.
 
 Vision tasks:

package/src/recovery.ts

@@ -0,0 +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",
+		);
+	}
+}