brl-subagent 2.5.0 → 2.5.2

package/src/tui.ts

@@ -32,11 +32,13 @@ import type {
 	UsageStats,
 	FileDiff,
 	CompletionNotifyMode,
+	RecoveryMode,
 } from "./types";
 import {
 	THINKING_LEVELS,
 	NAV_FOOTER,
 	COMPLETION_NOTIFY_MODES,
+	RECOVERY_MODES,
 	TASK_PREVIEW_MAX_LENGTH,
 	COLLAPSED_OUTPUT_LINES,
 	COLLAPSED_DIFF_FILES_PREVIEW,
@@ -51,6 +53,7 @@ import {
 	isMultiSubagentDetails,
 	isGraphDetails,
 	isUnsettledPartial,
+	isInterruptedRun,
 } from "./types";
 import { buildFileAccessReport, buildSecretsExposureReport, generateComplianceSummary } from "./reports";
 import { extractParamNames } from "./templates";
@@ -59,10 +62,11 @@ import { formatPresetSummary, getPreset, loadCustomPresets } from "./presets";
 import { buildOutputHonestyLines, formatRunDuration } from "./history";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { collapseRunsForHistory, sweepStaleLiveSubagents, type SessionState } from "./state";
+import { collapseRunsForHistory, retryableRuns, sweepStaleLiveSubagents, type SessionState } from "./state";
 import { getAgent } from "./session-manager";
+import { visibleRunEntriesForSession } from "./recovery-surface";
 import { computeSLAMetrics, computeCostTrend, formatSparkline } from "./metrics";
-import { formatElapsed, liveRowName, liveSpinner, formatLiveRowDim } from "./tui-format";
+import { formatElapsed, liveRowName, liveSpinner, formatLiveRowDim, runHistoryStatus, runHistoryStatusLabel, buildRetryOfferMessage, runDisplayName } from "./tui-format";
 import {
 	renderTranscriptMessages,
 	type TranscriptLineStyle,
@@ -336,6 +340,32 @@ export async function showCompletionNotifySelector(
 	onConfigChanged(ctx, `Completion notify mode set to ${result}`);
 }
 
+/**
+ * Option B U3 (D4): recovery posture selector. Modeled on the completionNotify
+ * selector; `RECOVERY_MODES` excludes "auto" by construction.
+ */
+export async function showRecoverySelector(
+	ctx: ExtensionContext,
+	state: SessionState,
+	onConfigChanged: (ctx: ExtensionContext, msg: string) => void,
+): Promise<void> {
+	const modeDescriptions: Record<RecoveryMode, string> = {
+		offer: "Surface interrupted runs (Run History row + one boot notice) - default",
+		off: "Do not surface interrupted runs",
+	};
+	const items: SelectItem[] = RECOVERY_MODES.map((mode) => ({
+		value: mode,
+		label: mode,
+		description: modeDescriptions[mode],
+	}));
+
+	const result = await showSelectList(ctx, "Recovery Posture", items, 5);
+	if (!result) return;
+
+	state.config.recovery = result as RecoveryMode;
+	onConfigChanged(ctx, `Recovery posture set to ${result}`);
+}
+
 // ---------------------------------------------------------------------------
 // E4: SLA tracking configuration
 // ---------------------------------------------------------------------------
@@ -938,6 +968,13 @@ export function getConfigMenuItems(state: SessionState): SelectItem[] {
 					? "Wake only on failed/stopped"
 					: "Never wake (passive delivery)",
 		},
+		{
+			value: "recovery",
+			label: "Set Recovery Posture",
+			description: state.config.recovery === "offer"
+				? "Surface interrupted runs (default)"
+				: "Do not surface interrupted runs",
+		},
 
 		{
 			value: "historyentries",
@@ -1085,6 +1122,17 @@ export async function showConfigMenu(
 // Run history viewer
 // ---------------------------------------------------------------------------
 
+/**
+ * U3 Fix A: the recovery visibility bridge wired for a TUI surface. Session
+ * run entries UNIONED with synthetic durable interrupted records the session
+ * has never seen (a genuine fresh boot), deduped by id. Both the history list
+ * and the retry menu read THIS, so they can never disagree about an interrupted
+ * run that exists only in the durable registry.
+ */
+function recoverableRunEntries(ctx: ExtensionContext, state: SessionState): SubagentRun[] {
+	return visibleRunEntriesForSession(state.getRunEntries(ctx), getAgent);
+}
+
 export async function showRunHistory(
 	ctx: ExtensionContext,
 	state: SessionState,
@@ -1094,6 +1142,7 @@ export async function showRunHistory(
 		running: ctx.ui.theme.fg("accent", "◉"),
 		done: ctx.ui.theme.fg("success", "✓"),
 		failed: ctx.ui.theme.fg("error", "✗"),
+		interrupted: ctx.ui.theme.fg("warning", "◌"),
 	};
 
 	// Browse loop (issue #260): list → detail → list … until the LIST is exited
@@ -1102,7 +1151,7 @@ export async function showRunHistory(
 		// One row per SETTLED run (issue #259): collapse each run's spawn+terminal
 		// entry pair to its terminal-preferred record; in-flight runs are omitted
 		// (the live monitor owns running state).
-		const runs = collapseRunsForHistory(state.getRunEntries(ctx));
+		const runs = collapseRunsForHistory(recoverableRunEntries(ctx, state));
 
 		if (runs.length === 0) {
 			ctx.ui.notify("No subagent runs recorded yet. Delegate a task to see history.", "info");
@@ -1110,10 +1159,15 @@ export async function showRunHistory(
 		}
 
 		const items: SelectItem[] = runs.map((r) => {
-			const icon = statusIcon[r.status] || "·";
-			const name = r.label || r.task.slice(0, 60);
+			const status = runHistoryStatus(r);
+			const icon = statusIcon[status] || "·";
+			const name = runDisplayName(r);
 			const model = r.model.split("/").pop() || r.model;
-			const when = r.finishedAt ? formatRunDuration(r.durationMs || 0) : "running...";
+			const when = r.finishedAt
+				? formatRunDuration(r.durationMs || 0)
+				: status === "interrupted"
+					? "interrupted"
+					: "running...";
 			const cost = r.cost ? ` $${r.cost.toFixed(4)}` : "";
 			const desc = `${r.thinkingLevel} · ${model} · ${when}${cost}`;
 			return { value: r.id, label: `${icon} ${name}`, description: desc };
@@ -1218,8 +1272,7 @@ async function showRunDetail(ctx: ExtensionContext, run: SubagentRun): Promise<v
 			const container = new Container();
 			container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
 
-			const statusLabel =
-				run.status === "done" ? "Completed" : run.status === "failed" ? "Failed" : "Running";
+			const statusLabel = runHistoryStatusLabel(run);
 			container.addChild(
 				new Text(
 					theme.fg(
@@ -1993,32 +2046,59 @@ export async function showDashboard(
 // Retry menu
 // ---------------------------------------------------------------------------
 
-export async function showRetryMenu(ctx: ExtensionContext, state: SessionState): Promise<void> {
-	const failedRuns = state.getRunEntries(ctx).filter((r) => r.status === "failed").reverse();
+export async function showRetryMenu(
+	ctx: ExtensionContext,
+	state: SessionState,
+	// U3 (D5): the abandon action is injected by the extension entry point (it
+	// owns the session-manager/registry wiring). Omitted in read-only contexts.
+	onAbandon?: (id: string) => void | Promise<void>,
+): Promise<void> {
+	// U3 (D3): failed AND unresolved interrupted runs share this surface, one row
+	// per run, built on the same terminal-preferred collapse the history uses.
+	const candidates = retryableRuns(recoverableRunEntries(ctx, state));
 
-	if (failedRuns.length === 0) {
-		ctx.ui.notify("No failed subagent runs to retry.", "info");
+	if (candidates.length === 0) {
+		ctx.ui.notify("No failed or interrupted subagent runs to retry.", "info");
 		return;
 	}
 
-	const items: SelectItem[] = failedRuns.map((r) => {
-		const name = r.label || r.task.slice(0, 60);
+	const items: SelectItem[] = candidates.map((r) => {
+		const interrupted = isInterruptedRun(r);
+		const name = runDisplayName(r);
 		const model = r.model.split("/").pop() || r.model;
-		const err = r.errorMessage ? r.errorMessage.slice(0, 40) : "error";
+		const err = r.errorMessage ? r.errorMessage.slice(0, 40) : interrupted ? "interrupted" : "error";
 		return {
 			value: r.id,
-			label: `✗ ${name}`,
-			description: `${model} · ${err}`,
+			label: `${interrupted ? "◌" : "✗"} ${name}`,
+			description: `${interrupted ? "interrupted · " : ""}${model} · ${err}`,
 		};
 	});
 
-	const selectedId = await showSelectList(ctx, "Retry Failed Run", items, 10);
+	const selectedId = await showSelectList(ctx, "Retry Failed or Interrupted Run", items, 10);
 	if (!selectedId) return;
 
-	ctx.ui.notify(
-		`Ask the LLM to retry: "Use delegate_task to retry failed run ${selectedId.slice(0, 8)}..."`,
-		"info",
-	);
+	const run = candidates.find((r) => r.id === selectedId);
+	if (!run) return;
+
+	if (isInterruptedRun(run) && onAbandon) {
+		const action = await showSelectList(
+			ctx,
+			"Interrupted Run",
+			[
+				{ value: "retry", label: "Retry", description: "Re-dispatch with its recorded params (retryRunId)" },
+				{ value: "abandon", label: "Abandon", description: "Finalize as stopped and prune its session file" },
+			],
+			5,
+		);
+		if (!action) return;
+		if (action === "abandon") {
+			await onAbandon(run.id);
+			ctx.ui.notify(`Abandoned interrupted run ${run.id.slice(0, 8)}.`, "info");
+			return;
+		}
+	}
+
+	ctx.ui.notify(buildRetryOfferMessage(run), "info");
 }
 
 // ---------------------------------------------------------------------------

package/src/types.ts

@@ -22,6 +22,15 @@ export type CompletionNotifyMode = (typeof COMPLETION_NOTIFY_MODES)[number];
 
 export const DEFAULT_COMPLETION_NOTIFY: CompletionNotifyMode = "all";
 
+// Option B U3 (D4): boot recovery posture. "offer" surfaces interrupted runs
+// (Run History row + one boot notice); "off" silences the notice and marks
+// newly dispatched runs so they are never offered. "auto" is deliberately NOT
+// a member (U4 territory), enforced by RECOVERY_MODES being the shape guard.
+export const RECOVERY_MODES = ["offer", "off"] as const;
+export type RecoveryMode = (typeof RECOVERY_MODES)[number];
+
+export const DEFAULT_RECOVERY: RecoveryMode = "offer";
+
 export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
 
 export const THINKING_LEVELS: ThinkingLevel[] = ["off", "minimal", "low", "medium", "high", "xhigh"];
@@ -238,6 +247,9 @@ export interface SubagentState {
 	// state, "failed" wakes only on failed/stopped, "off" never wakes (still
 	// delivers passively at the next user prompt).
 	completionNotify: CompletionNotifyMode;
+	// Option B U3 (D4): recovery posture for the session. Applies to newly
+	// dispatched runs (snapshotted per run) and to the boot notice.
+	recovery: RecoveryMode;
 	maxHistoryEntries: number; // 0 = unlimited
 	sessionCostLimit: number; // 0 = unlimited
 	perTaskCostEstimate: number; // 0 = no estimate, use default
@@ -327,6 +339,9 @@ export interface SubagentRun {
 	interruptedAt?: string;
 	owner?: ProcessOwner;
 	childMarker?: string;
+	// Option B U3 (D4): the recovery posture in force when this run was
+	// dispatched. Additive: a pre-U3 record lacks it and reads as "offer".
+	recoveryPosture?: RecoveryMode;
 	startedAt: string;
 	finishedAt?: string;
 	durationMs?: number;
@@ -707,7 +722,7 @@ export const RESERVED_NAME_PATTERN = /^__.*__$/;
 export const RESERVED_COMMAND_NAMES = new Set([
 	"model", "thinking", "concurrency", "depth", "history", "monitor",
 	"preset", "retry", "reset", "priority", "templates", "dashboard", "approval",
- "costlimit", "historyentries", "sla", "completionnotify",
+ "costlimit", "historyentries", "sla", "completionnotify", "recovery",
 	"graph", "sla-stats", "compliance",
 ]);
 
@@ -735,6 +750,13 @@ export interface BackgroundAgent {
 	finalOutput?: string;
 	/** @internal — session reference for live monitor polling */
 	_sessionRef?: import('@earendil-works/pi-coding-agent').AgentSession;
+	/**
+	 * @internal — Option B U2: the on-disk session file for this run, captured
+	 * from `SessionManager.getSessionFile()` at spawn. Used by the settle path to
+	 * prune the EXACT per-run directory. Live-only: stripped by `persistAgent`,
+	 * never a persisted record field (D4).
+	 */
+	_sessionFile?: string;
 	// Option B U1 (D3/D4): additive durability identity, mirroring SubagentRun.
 	// Background records carry dispatchId/owner/attempt. `childMarker` is
 	// declared for round-trip tolerance with the run-record/agent-record JSON
@@ -746,6 +768,9 @@ export interface BackgroundAgent {
 	interruptedAt?: string;
 	owner?: ProcessOwner;
 	childMarker?: string;
+	// Option B U3 (D4): the recovery posture at dispatch, mirrored from the
+	// run record. Additive (absent reads as "offer").
+	recoveryPosture?: RecoveryMode;
 }
 
 // ---------------------------------------------------------------------------
@@ -1010,6 +1035,11 @@ export function isSubagentStateShape(value: unknown): value is SubagentState {
 		if (!COMPLETION_NOTIFY_MODES.includes(v.completionNotify as CompletionNotifyMode)) return false;
 	}
 
+	// recovery must be one of RECOVERY_MODES if present ("auto" is rejected)
+	if (v.recovery !== undefined) {
+		if (!RECOVERY_MODES.includes(v.recovery as RecoveryMode)) return false;
+	}
+
 	// maxHistoryEntries must be a non-negative number if present
 	if (v.maxHistoryEntries !== undefined) {
 		if (typeof v.maxHistoryEntries !== "number" || v.maxHistoryEntries < 0) return false;
@@ -1045,9 +1075,25 @@ export function isSubagentRunShape(value: unknown): value is SubagentRun {
 	if (typeof v.id !== "string") return false;
 	if (typeof v.task !== "string") return false;
 	if (!["running", "done", "failed"].includes(v.status as string)) return false;
+	// U3 (D4): a malformed snapshot is rejected like any other bad field; an
+	// absent one is fine (pre-U3 records) and reads as "offer" via the helper.
+	if (v.recoveryPosture !== undefined) {
+		if (!RECOVERY_MODES.includes(v.recoveryPosture as RecoveryMode)) return false;
+	}
 	return true;
 }
 
+/**
+ * Option B U3 (D4): the recovery posture recorded for a run. Absent (pre-U3
+ * records) or an unrecognized value reads as the default "offer" — the
+ * additive-field contract (no migration).
+ */
+export function runRecoveryPosture(
+	run: Pick<SubagentRun, "recoveryPosture">,
+): RecoveryMode {
+	return run.recoveryPosture === "off" ? "off" : DEFAULT_RECOVERY;
+}
+
 /**
  * Option B U1 (D3): the ONE interrupted-state predicate. Status deliberately
  * stays "running" (a new status value would be dropped by old readers and
@@ -1059,6 +1105,25 @@ export function isInterruptedRun(run: SubagentRun): boolean {
 	return run.status === "running" && !!run.interruptedAt;
 }
 
+/**
+ * Fix B (item 2): TRUE when a terminal run record represents an ABORT rather
+ * than a genuine failure. Abandon writes the store's ONLY stopped-outcome
+ * shape — `failed` + `stopReason`/`errorCategory` "aborted" (D5 mapping) — and
+ * a user `stop_subagent` writes the same. Failure tallies (SLA) must exclude
+ * these. The run record carries no dedicated "abandoned" marker and D5 forbids
+ * adding one, so a user-ABANDONED run and a user-STOPPED run are
+ * indistinguishable here; both are treated as non-failures.
+ */
+export function isAbortedRun(
+	run: Pick<SubagentRun, "stopReason" | "errorCategory" | "originalParams">,
+): boolean {
+	return (
+		run.stopReason === "aborted" ||
+		run.errorCategory === "aborted" ||
+		run.originalParams?.errorCategory === "aborted"
+	);
+}
+
 /**
  * Type guard: checks if a value is a valid MultiSubagentDetails shape.
  */

package/src/unit-run.ts

@@ -27,8 +27,9 @@ import type {
 	SubagentRun,
 	SubagentToolOptions,
 	Priority,
+	RecoveryMode,
 } from "./types";
-import { getFinalOutput, classifyError } from "./types";
+import { getFinalOutput, classifyError, DEFAULT_RECOVERY } from "./types";
 import { snapshotOriginalParams } from "./params";
 import { currentProcessOwner } from "./recovery";
 import { capOutput, stripAnsi, buildCrashResult } from "./sanitize";
@@ -106,6 +107,9 @@ export function createUnitRun(
 	stepModel: { provider: string; id: string },
 	priorityFloor: Priority,
 	presetName?: string,
+	// U3 (D4): the session recovery posture at dispatch. Optional so existing
+	// callers/tests stay valid; production passes `state.config.recovery`.
+	recoveryPosture: RecoveryMode = DEFAULT_RECOVERY,
 ): { runId: string; run: SubagentRun } {
 	const runId = crypto.randomUUID();
 	const run: SubagentRun = {
@@ -131,6 +135,9 @@ export function createUnitRun(
 		attempt: 1,
 		owner: currentProcessOwner(),
 		childMarker: crypto.randomUUID(),
+		// U3 (D4): snapshot the posture so the boot notice/offer reads what was
+		// in force at dispatch.
+		recoveryPosture,
 		// The execution-shape fields (background/gitMode/approvalMode/force) are
 		// deliberately omitted: a fan-out unit retries as a SINGLE run, so it must
 		// not inherit the fan-out's background-ness. A retry that wants background