@ferris1225/pi-subagents 0.31.0 → 0.32.2

package/src/monitor.ts

@@ -14,12 +14,17 @@ import { stripVTControlCharacters } from "node:util";
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import type { UsageStats } from "./spawn.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";
+
+export function isRunActiveStatus(status: RunStatus): boolean {
+	return status === "queued" || status === "running" || status === "steering" || status === "interrupting";
+}
 
 /** 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),
@@ -44,8 +49,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. */
@@ -83,6 +94,8 @@ export interface RunView {
 export interface RunChainMeta {
 	groupId?: string;
 	relationLabel?: string;
+	isolation?: IsolationMode;
+	forkedFromRunId?: number;
 }
 
 // ---------------------------------------------------------------------------
@@ -311,7 +324,7 @@ export function activityStateLabel(state: ActivityState): string {
  * 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.status !== "running" && run.status !== "steering") return undefined;
 	if (!run.currentTool) {
 		const since = run.lastActivityAt ?? run.startedAt ?? now;
 		if (now - since >= NEEDS_ATTENTION_AFTER_MS) return "needs_attention";
@@ -416,7 +429,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 +447,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 +458,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,6 +478,15 @@ 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);
@@ -520,6 +544,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);
@@ -560,6 +651,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 +683,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":
@@ -607,6 +705,12 @@ export function statusLabel(status: RunStatus): string {
 			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 +719,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",
+		);
+	}
+}