@ferris1225/pi-subagents 0.29.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),
@@ -39,9 +44,19 @@ export interface RunView {
 	id: number;
 	agent: string;
 	task: string;
+	/** Short content label derived from the task (paths/symbols), shown next to
+	 * the agent name so concurrent same-agent runs are told apart by what they
+	 * 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. */
@@ -79,6 +94,8 @@ export interface RunView {
 export interface RunChainMeta {
 	groupId?: string;
 	relationLabel?: string;
+	isolation?: IsolationMode;
+	forkedFromRunId?: number;
 }
 
 // ---------------------------------------------------------------------------
@@ -228,6 +245,28 @@ export function formatTaskSummary(task: string, maxWidth: number = TASK_SUMMARY_
 	return `${takeGraphemes(segments, headMax)}${TASK_SUMMARY_ELLIPSIS}${tailGraphemes(segments, tailMax)}`;
 }
 
+/** Max display width of a run's content label. */
+export const RUN_LABEL_MAX = 32;
+
+/**
+ * Short content label for a run, derived from its task: the single most
+ * distinguishing fragment (path, quoted phrase, symbol) so concurrent same-agent
+ * runs are told apart by WHAT they do, not just their run id. A long path keeps
+ * its tail (the filename is the recognisable part); a task with no recognizable
+ * fragment falls back to a head slice of its prose. Grapheme-safe.
+ */
+export function runLabel(task: string): string {
+	const fragment = extractKeyFragments(task)[0];
+	const src = fragment ?? stripVTControlCharacters(task).replace(/\s+/g, " ").trim();
+	if (visibleWidth(src) <= RUN_LABEL_MAX) return src;
+	const chars = [...graphemeSegmenter.segment(src)].map((s) => s.segment);
+	// A path/symbol fragment keeps its tail (filename/symbol is recognisable);
+	// a prose fallback keeps its head.
+	return fragment
+		? `${TASK_SUMMARY_ELLIPSIS}${tailGraphemes(chars, RUN_LABEL_MAX - 1)}`
+		: `${takeGraphemes(chars, RUN_LABEL_MAX - 1)}${TASK_SUMMARY_ELLIPSIS}`;
+}
+
 function formatTokens(count: number): string {
 	if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
 	if (count >= 1_000) return `${(count / 1_000).toFixed(1)}k`;
@@ -285,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";
@@ -390,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();
 	}
@@ -401,12 +440,15 @@ export class MonitorStore {
 			id,
 			agent,
 			task,
+			label: runLabel(task),
 			model,
 			thinking,
 			status: "queued",
 			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;
@@ -416,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();
@@ -436,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);
@@ -493,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);
@@ -533,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);
@@ -564,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":
@@ -580,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":
@@ -588,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,14 +58,21 @@ ${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:
 - Judge whether a delegated task may require viewing images (frontend screenshots, mockups, design files, visual regression comparisons). If it might, pass \`vision: true\` in the subagent call and give the sub-agent the exact image paths — it reads them with its read tool.
 - \`vision: true\` runs the sub-agent on the vision-capable model configured in /subagents-setup; when none is configured it falls back to the main session's current model. Do not skip the flag because the agent's default model looks fast/cheap — a non-vision model cannot see the images.
 
+Result handoff (do not re-state):
+- A sub-agent's result arrives as a message that is already shown to the user. Do NOT restate, paraphrase, or re-summarize its findings in your reply — that just burns tokens duplicating what is already visible. The user can read the result above.
+- Reply only with what you ADD: your own conclusion, the next action you are taking, or a one-line acknowledgement. When the result already answers the user, a single sentence is enough — then end your turn or proceed.
+- Read the result and act on it (verify, continue, commit). Keep your own output short.
+- A result arriving does NOT mean all work is finished: sub-agents run in the background and siblings may still be active (a delivery names any still-running runs). Do not report the overall task complete until no runs are active — call subagent_status to confirm before saying Done.
+
 Review & verification:
 - Never report an unrun check as passed; report it as unavailable or as a pre-existing failure.
 ${hasReviewer ? "- For non-trivial diffs, run one fresh read-only `reviewer` sub-agent before reporting done. Fix only concrete blockers and re-review at most once.\n- Use multi-model cross-review only when explicitly requested or for genuinely high-risk changes (security, unsafe/FFI, persistence-migration, concurrency). Reviewers are read-only; only the main agent edits.\n" : ""}- Commit or push only when explicitly requested, applicable checks pass, and no accepted blockers remain.`;

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