brl-subagent 2.4.0 → 2.5.1

package/src/session-manager.ts

@@ -1,9 +1,9 @@
 // Purpose: Background execution: SDK sessions (`createAgentSession`), agent records, timeouts, steering, and settle paths.
 import { randomUUID } from 'crypto';
-import { join } from 'path';
-import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'fs';
-import type { BackgroundAgent, AgentStatus, GitMode, SubagentResult, SubagentRun, ThinkingLevel, SubagentToolOptions, UsageStats, ErrorCategory } from './types';
-import { EMPTY_USAGE, CUSTOM_ENTRY_TYPES, classifyError, classifyTerminalOutcome, isProviderError, coherentFailureReason, SUBAGENT_ABORTED_MESSAGE } from './types';
+import { basename, dirname, join, resolve } from 'path';
+import { mkdirSync, writeFileSync, readFileSync, readdirSync, existsSync, rmSync } from 'fs';
+import type { BackgroundAgent, AgentStatus, GitMode, RecoveryMode, SubagentResult, SubagentRun, ThinkingLevel, SubagentToolOptions, UsageStats, ErrorCategory } from './types';
+import { EMPTY_USAGE, classifyError, classifyTerminalOutcome, isProviderError, coherentFailureReason, SUBAGENT_ABORTED_MESSAGE } from './types';
 import { accumulateUsage } from './runner';
 import * as eventBus from './event-bus';
 import * as transcript from './transcript';
@@ -11,8 +11,11 @@ import { createEvent } from './event-bus';
 import { assertSafeAgentId, sanitizeErrorMessage } from './sanitize';
 import { wrapTask } from './prompt';
 import { createLogger } from './logging';
-import { getCurrentBranch, createWorkBranch, captureDiff, switchToBranch, deleteBranch, hasUncommittedChanges, getRepoRoot, commitAll, captureWorkingDiff } from './git';
+import { getCurrentBranch, getHeadState, restoreHead, createWorkBranch, captureDiff, deleteBranch, hasUncommittedChanges, getRepoRoot, commitAll, captureWorkingDiff } from './git';
+import type { HeadState } from './git';
 import { normalizeTimeout, DEFAULT_BACKGROUND_DEADLINE_MS } from './validate';
+import { currentProcessOwner } from './recovery';
+import { persistRunRecord } from './run-registry';
 
 const log = createLogger('brl-subagent');
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
@@ -75,6 +78,90 @@ function ensureStorageDir(): void {
   mkdirSync(STORAGE_DIR, { recursive: true, mode: 0o700 });
 }
 
+// ---------------------------------------------------------------------------
+// Option B U2 (D1/D2): file-backed background sessions + retention.
+//
+// Background runs are persisted by the SDK's SessionManager-created files, one
+// per-run directory BESIDE the agent records (`.pi/subagents/sessions/<id>/`).
+// The directory NAME is the run→file mapping — no new record field is needed,
+// and no resume/re-drive/UI logic lives here (that is U3/U4). The per-run dir is
+// removed when the run reaches a TERMINAL state; a run marked interrupted (U1's
+// boot scan, D3) KEEPS its file until it is resolved by a later unit.
+//
+// Boundaries (stated once, referenced by the PR): no resume (U4); no UI/notice/
+// abandon (U3); background is in-process only; a session file has a single
+// writer (the settled run's own process).
+//
+// D5 measurement (one week of use):
+//   du -sh .pi/subagents/sessions
+//   find .pi/subagents/sessions -name '*.jsonl' | wc -l
+// The expected steady state is EMPTY between runs (terminal runs prune their
+// dir) plus one dir per currently-interrupted run — a non-empty count of
+// settled runs means a prune path regressed. There is no runtime metric.
+// ---------------------------------------------------------------------------
+
+/** Subdirectory of the agent-record store that holds per-run session dirs. */
+const SESSIONS_SUBDIR = 'sessions';
+
+/**
+ * The per-run session directory for `id`: `<STORAGE_DIR>/sessions/<id>`.
+ * The id is validated first — this path is fed to SessionManager.create() and
+ * to rmSync(), so a traversal id must never reach either.
+ */
+export function backgroundSessionDir(id: string): string {
+  assertSafeAgentId(id);
+  return join(STORAGE_DIR, SESSIONS_SUBDIR, id);
+}
+
+/**
+ * Remove ONE per-run session directory. Defensive by construction: the target
+ * must look like `<...>/sessions/<id>` (basename === id, parent basename ===
+ * 'sessions') before rmSync runs, so a caller can never delete a path outside
+ * the sessions tree. Idempotent (force: true); best-effort (never throws).
+ */
+function pruneSessionDir(id: string, dir: string): void {
+  try {
+    assertSafeAgentId(id);
+  } catch {
+    log.error(`Refusing to prune session dir for invalid id: ${id}`);
+    return;
+  }
+  const target = resolve(dir);
+  if (basename(target) !== id || basename(dirname(target)) !== SESSIONS_SUBDIR) {
+    log.error(`Refusing to prune session dir outside ${SESSIONS_SUBDIR}/: ${target}`);
+    return;
+  }
+  try {
+    rmSync(target, { recursive: true, force: true });
+  } catch (err) {
+    // Pruning is hygiene — it must never break execution or a settle path.
+    log.warn(`Failed to prune session dir for ${id}`, {
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+}
+
+/**
+ * U2 (D2): remove the persisted session for a finalized/abandoned background
+ * run. Validated (throws on an unsafe id) and idempotent — a missing directory
+ * is a success. Exposed for U3's abandon action to reuse; the internal settle
+ * path prunes the CAPTURED directory instead so a mid-run STORAGE_DIR change
+ * (tests swap it per case) can never mis-target.
+ *
+ * U3 (D5) documented boundary — abandon after a STORAGE_DIR change: this
+ * PUBLIC helper recomputes the root from the CURRENT STORAGE_DIR, so if the
+ * root moved between the spawn and the abandon it prunes the new root (a
+ * no-op when nothing lives there) and leaves the old-root session dir behind
+ * as debris. That is prod-safe today (only tests swap the root; production
+ * uses one root per process), so U3 does NOT try to track the captured dir
+ * across sessions — the run's `_sessionFile` is live-only process state and is
+ * not persisted (D4). Debris, if any, is bounded and inspectable under the old
+ * root.
+ */
+export function pruneBackgroundSession(id: string): void {
+  pruneSessionDir(id, backgroundSessionDir(id));
+}
+
 /**
  * Persist agent record to disk
  */
@@ -85,15 +172,17 @@ function persistAgent(agent: BackgroundAgent): void {
   try {
     assertSafeAgentId(agent.id);
   } catch {
-    console.error(`[brl-subagent] Refusing to persist agent with invalid id: ${agent.id}`);
+    log.error(`Refusing to persist agent with invalid id: ${agent.id}`);
     return;
   }
   ensureStorageDir();
   const filePath = join(STORAGE_DIR, `${agent.id}.json`);
   // Strip live/non-serializable fields before stringify — `_sessionRef` holds the
   // ENTIRE live pi session graph (1.4MB+ for an empty session, and uninitialized
-  // getters like Theme can make JSON.stringify throw).
-  const { _sessionRef, ...persistable } = agent;
+  // getters like Theme can make JSON.stringify throw). `_sessionFile` (U2) is the
+  // on-disk session path — live-only bookkeeping for precise pruning, never a
+  // persisted record field (D4).
+  const { _sessionRef, _sessionFile, ...persistable } = agent;
   try {
     // F6 (issue #29): records contain task, error, result.messages (full
     // conversation) and finalOutput — write owner-only (0o600) so other local
@@ -102,7 +191,7 @@ function persistAgent(agent: BackgroundAgent): void {
     writeFileSync(filePath, JSON.stringify(persistable, null, 2), { encoding: 'utf-8', mode: 0o600 });
   } catch (err) {
     // Log but never throw — persistence must not break execution
-    console.error(`[brl-subagent] Failed to persist agent ${agent.id}:`, err);
+    log.error(`Failed to persist agent ${agent.id}`, { error: err instanceof Error ? err.message : String(err) });
   }
 }
 
@@ -136,6 +225,54 @@ export function getAgent(id: string): BackgroundAgent | null {
   return agents.get(id) || loadAgent(id);
 }
 
+/**
+ * Option B U1: every agent record persisted on disk (cross-session — the
+ * `.pi/subagents/` store survives a process death; the conductor's session run
+ * entries do not). Boot recovery does NOT use this: it sources candidates from
+ * the durable run registry and reads background records ONE at a time by id
+ * (`recoverInflightRuns`'s `readAgentRecord`), precisely to avoid parsing the
+ * whole store; production has no caller for this sweep. Unreadable/corrupt
+ * files and unsafe ids are skipped, never thrown.
+ */
+export function listPersistedAgents(): BackgroundAgent[] {
+  let files: string[];
+  try {
+    if (!existsSync(STORAGE_DIR)) return [];
+    files = readdirSync(STORAGE_DIR);
+  } catch {
+    return [];
+  }
+  const records: BackgroundAgent[] = [];
+  for (const file of files) {
+    if (!file.endsWith('.json')) continue;
+    const id = file.slice(0, -'.json'.length);
+    try {
+      assertSafeAgentId(id);
+    } catch {
+      continue;
+    }
+    const record = loadAgent(id);
+    if (record) records.push(record);
+  }
+  return records;
+}
+
+/**
+ * Option B U1 (D3): read-modify-write the interrupted mark onto a persisted
+ * agent record. Idempotent: an already-marked record is returned unchanged.
+ * Returns null when the record does not exist.
+ */
+export function markAgentInterrupted(id: string, interruptedAt: string): BackgroundAgent | null {
+  const agent = getAgent(id);
+  if (!agent) return null;
+  if (!agent.interruptedAt) {
+    agent.interruptedAt = interruptedAt;
+    agents.set(id, agent);
+    persistAgent(agent);
+  }
+  return agent;
+}
+
 /**
  * Update agent status
  */
@@ -320,15 +457,13 @@ export async function steerAgent(id: string, message: string): Promise<Backgroun
 }
 
 /**
- * Get transcript path for an agent
+ * Get transcript path for an agent.
+ *
+ * Issue #276: the format lives in `transcript-path.ts` (the single source).
+ * This re-export preserves the historical `session-manager.getTranscriptPath`
+ * surface for `index.ts`'s dynamic import and the existing tests.
  */
-export function getTranscriptPath(id: string): string {
-  // F24: reachable with LLM-controlled ids (get_agent_result). Throw on invalid
-  // ids — the tool caller surfaces it as an error. (Defense in depth: getAgent
-  // already validated before this is reached with a live agent.)
-  assertSafeAgentId(id);
-  return join('.pi', 'output', `agent-${id}.jsonl`);
-}
+export { transcriptPath as getTranscriptPath } from './transcript-path';
 
 /**
  * Spawn a background session using pi's session API
@@ -359,6 +494,15 @@ export async function spawnBackgroundSession(
     /** Issue #114: per-unit priority — recorded on the run entry + agent record
      *  so the drill-in header and history carry it (absent → no segment). */
     priority?: string;
+    /** Option B U1: durability identity. A retry inherits the original's
+     *  dispatchId and records resumeOf/attempt; a fresh dispatch omits them. */
+    dispatchId?: string;
+    resumeOf?: string;
+    attempt?: number;
+    /** Option B U3 (D4): recovery posture at dispatch — snapshotted onto the
+     *  agent record + run entry so the boot notice reads the posture the run
+     *  was actually dispatched under. Absent reads as "offer". */
+    recoveryPosture?: RecoveryMode;
   }
 ): Promise<BackgroundAgent> {
   // Serialize access to pi API to prevent concurrent import races
@@ -388,8 +532,16 @@ export async function spawnBackgroundSession(
     }
   }
   
-  // Create session manager for this background agent
-  const sessionManager = SessionManager.inMemory(effectiveCwd);
+  // Create the session manager for this background agent. U2 (D1): an explicit
+  // per-run sessionDir is REQUIRED — `inMemory` persists nothing (no post-hoc
+  // inspection, no U4 resume) and the SDK default (`~/.pi/agent/sessions/<cwd-key>/`,
+  // passed as `undefined`) would scatter our runs into the global store. The
+  // directory lives beside the agent record: `.pi/subagents/sessions/<id>/`.
+  const sessionManager = SessionManager.create(effectiveCwd, backgroundSessionDir(id));
+  // Capture the exact path the SDK will write. The settle path derives the
+  // prune target from THIS (not from a freshly-computed STORAGE_DIR path) so a
+  // change of STORAGE_DIR between spawn and settle cannot mis-target the delete.
+  const sessionFile: string | undefined = sessionManager.getSessionFile();
   const settingsManager = SettingsManager.create(effectiveCwd);
 
   // E20: Inject the subagent prompt into the session's system prompt.
@@ -469,6 +621,13 @@ export async function spawnBackgroundSession(
   // Set session name
   session.setSessionName(`background-${id.slice(0, 8)}`);
   
+  // Option B U1: durability identity. Background runs have no child process
+  // (the session is in-process), so there is no childMarker — only the owner
+  // identity that a boot scan uses to tell a live conductor from a dead one.
+  const dispatchId = params.dispatchId ?? generateUUID();
+  const attempt = params.attempt ?? 1;
+  const owner = currentProcessOwner();
+
   // Create agent record
   const agent: BackgroundAgent = {
     id,
@@ -481,6 +640,15 @@ export async function spawnBackgroundSession(
     model: params.model || 'unknown',
     thinkingLevel: params.thinkingLevel || 'medium',
     priority: params.priority,
+    dispatchId,
+    resumeOf: params.resumeOf,
+    attempt,
+    owner,
+    // Option B U3 (D4): per-run recovery posture snapshot. Additive — absent
+    // reads as "offer" via `runRecoveryPosture`/the notice collector.
+    recoveryPosture: params.recoveryPosture,
+    // U2: live-only pointer to this run's session file (stripped before persist).
+    _sessionFile: sessionFile,
   };
   
   agents.set(id, agent);
@@ -506,13 +674,27 @@ export async function spawnBackgroundSession(
     priority: params.priority,
     startedAt: new Date().toISOString(),
     originalParams: params.originalParams,
+    dispatchId,
+    resumeOf: params.resumeOf,
+    attempt,
+    owner,
+    recoveryPosture: params.recoveryPosture,
   };
-  pi.appendEntry(CUSTOM_ENTRY_TYPES.run, run);
+  persistRunRecord(pi, run, "background");
 
   // Issue #98: keep the session run entry in lockstep with the agent record —
   // every terminal branch that flips agent.status also finalizes the run entry
   // ("done"/"failed"). The guard keeps the entry single-finalized even when a
   // settle handler throws after finalizing (markTerminalBestEffort catch-all).
+  //
+  // U2 (D2) retention: this is the SINGLE terminal choke point for a background
+  // run — git-setup refusal, a synchronous prompt throw, the .then completed /
+  // provider-failed / aborted branches, the .catch stopped / failed branches and
+  // the markTerminalBestEffort catch-all ALL land here exactly once (the
+  // runFinalized guard). Pruning here therefore covers every settle path. The
+  // index.ts poller crash notices are NOT settlements (they flip only the live
+  // UI state and leave the run/agent record to this settle); an interrupted run
+  // (U1 boot-scan mark) never reaches this function and KEEPS its file (D3).
   let runFinalized = false;
   const finalizeRunEntry = (
     status: "done" | "failed",
@@ -521,6 +703,15 @@ export async function spawnBackgroundSession(
   ): void => {
     if (runFinalized) return;
     runFinalized = true;
+    // U2 (D2): drop the persisted session now that the run is terminal. Done
+    // FIRST (before the run-entry write below) so a persist throw cannot leave
+    // a terminal run's session file behind. Interrupted runs keep theirs.
+    if (!agent.interruptedAt) {
+      pruneSessionDir(
+        id,
+        agent._sessionFile ? dirname(agent._sessionFile) : backgroundSessionDir(id),
+      );
+    }
     const usage = agent.result?.usage ?? EMPTY_USAGE;
     const finalOutput = agent.finalOutput ?? "";
     // Issue #179 (D1/D2): the classifier's explicit category wins (it knows the
@@ -576,7 +767,7 @@ export async function spawnBackgroundSession(
           ? { ...(run.originalParams ?? {}), errorCategory }
           : run.originalParams,
     };
-    pi.appendEntry(CUSTOM_ENTRY_TYPES.run, entry);
+    persistRunRecord(pi, entry);
     // Issue #179 (D6): the explicit settle line — the log's job is to record the
     // CLASSIFIED OUTCOME, which cwd alone can never convey.
     log.info("Background run settled", {
@@ -661,9 +852,14 @@ export async function spawnBackgroundSession(
   // hard failure — never spawn an unisolated background agent that was asked
   // for isolation (fail-loud, same principle as foreground's fallback but
   // background cannot warn-and-continue safely).
-  let originalBranch: string | undefined;
+  let headState: HeadState | undefined;
   let workBranchName: string | undefined;
   let releaseGitLock: (() => void) | undefined;
+  // Idempotency guard for cleanupWorkBranch: it must be safe to call from both
+  // the normal settle path and the catch-all that runs when a settle step
+  // throws FIRST (before its own cleanup call). Without this the second call
+  // would re-restore/re-delete and log spurious warnings.
+  let gitCleanupDone = false;
   const gitCwd = params.cwd ?? ctx.cwd;
   if (params.gitMode === 'branch') {
     // C2: serialize the FULL branch lifecycle per repo. The spawnQueue only
@@ -696,13 +892,13 @@ export async function spawnBackgroundSession(
           'requesting background gitMode=branch isolation'
         );
       }
-      originalBranch = getCurrentBranch(gitCwd);
-      const branchResult = createWorkBranch(gitCwd, originalBranch);
+      headState = getHeadState(gitCwd);
+      const branchResult = createWorkBranch(gitCwd, headState.sha);
       if (branchResult.ok) {
         workBranchName = branchResult.branch;
         log.info('Created work branch for background agent', {
           branch: workBranchName,
-          base: originalBranch,
+          base: headState.branch,
           agentId: id,
         });
       } else {
@@ -740,7 +936,8 @@ export async function spawnBackgroundSession(
   // uncommitted edits would leak into the base working tree on switch —
   // commitAll first makes the diff real and the switch clean.
   const cleanupWorkBranch = (): { gitBranch?: string; gitDiff?: string } => {
-    if (!workBranchName || !originalBranch) return {};
+    if (gitCleanupDone || !workBranchName || !headState) return {};
+    gitCleanupDone = true;
     const info: { gitBranch?: string; gitDiff?: string } = { gitBranch: workBranchName };
     // The lock MUST be released on every exit path — early returns included.
     try {
@@ -778,7 +975,7 @@ export async function spawnBackgroundSession(
             if (workingDiff) info.gitDiff = workingDiff;
           }
         }
-        const diffResult = captureDiff(gitCwd, originalBranch);
+        const diffResult = captureDiff(gitCwd, headState.sha);
         if (diffResult.ok && diffResult.diff.trim()) {
           // Merge committed + working diffs — either can exist alone.
           info.gitDiff = info.gitDiff
@@ -789,9 +986,12 @@ export async function spawnBackgroundSession(
         log.warn(`captureDiff failed for background agent ${id}`, { error: (err as Error).message });
       }
       try {
-        switchToBranch(gitCwd, originalBranch);
+        const restoreResult = restoreHead(gitCwd, headState);
+        if (!restoreResult.ok) {
+          log.warn(`restoreHead failed for background agent ${id}`, { error: restoreResult.error });
+        }
       } catch (err) {
-        log.warn(`switchToBranch failed for background agent ${id}`, { error: (err as Error).message });
+        log.warn(`restoreHead failed for background agent ${id}`, { error: (err as Error).message });
       }
       try {
         deleteBranch(gitCwd, workBranchName);
@@ -812,6 +1012,11 @@ export async function spawnBackgroundSession(
   // terminal so no zombie 'running' record survives; never rethrow.
   const markTerminalBestEffort = (fallback: AgentStatus): void => {
     try {
+      // Issue #53 / review C: this catch-all fires when a settle handler step
+      // threw — possibly BEFORE the branch's own cleanupWorkBranch() call. Run
+      // it here too (idempotent) so a throw can never bypass branch teardown
+      // and strand the work branch in the repo working tree.
+      cleanupWorkBranch();
       // Issue #31 (PR #76 review): this catch-all fires when a settle handler
       // threw — either BEFORE the branch's own capture (ref still live: capture
       // now, it is the last chance to record the session's output) or AFTER it

package/src/state.ts

@@ -17,6 +17,7 @@ import type {
 	ThinkingLevel,
 	ApprovalMode,
 	CompletionNotifyMode,
+	RecoveryMode,
 	CircuitBreakerState,
 	Priority,
 } from "./types";
@@ -24,17 +25,21 @@ import type { TranscriptMessage } from "./transcript-tail";
 import {
 	isSubagentStateShape,
 	isSubagentRunShape,
+	isInterruptedRun,
 	CUSTOM_ENTRY_TYPES,
 	MAX_RUN_HISTORY_ENTRIES,
 	DEFAULT_MAX_SUBAGENT_DEPTH,
 	DEFAULT_SESSION_COST_LIMIT,
 	DEFAULT_COMPLETION_NOTIFY,
 	COMPLETION_NOTIFY_MODES,
+	DEFAULT_RECOVERY,
+	RECOVERY_MODES,
 	MAX_CONSECUTIVE_FAILURES,
 	CIRCUIT_BREAKER_RESET_MS,
 	CIRCUIT_DEGRADED_THINKING,
 } from "./types";
 import { cleanupRuns } from "./history";
+import { persistRunRecord, type InflightRunKind } from "./run-registry";
 import type { Logger } from "./logging";
 
 // ---------------------------------------------------------------------------
@@ -69,14 +74,21 @@ export const STALE_FINALIZE_GRACE_MS = POLLER_TICK_MS + 1000;
 
 /**
  * Terminal-preferring run-entry lookup — the ONE implementation of the
- * preference rule.
+ * preference rule. Recovery's `dedupeRunEntriesById` delegates here, so the
+ * boot scan and every display/retry lookup agree by construction.
  *
  * Each run writes TWO custom entries sharing its id, in append order: a spawn
  * entry (status "running", carrying `originalParams`) FIRST, then the final
  * entry (status "done"/"failed", stamped with fullOutput/cost/duration) at
- * settle. Prefer the terminal entry; when none is terminal yet, fall back to
- * the first match (the pre-finalize spawn shape). Returns undefined when no
- * entry matches.
+ * settle. Preference, in order:
+ *
+ *   1. a TERMINAL entry (status !== "running") — the run is resolved;
+ *   2. among non-terminal entries, one carrying the D3 `interruptedAt` mark —
+ *      append-only stores keep the original spawn entry forever, so the marked
+ *      clone is the authoritative RECOVERED state U3's shared lookup reads;
+ *   3. otherwise the first match (the pre-finalize spawn shape).
+ *
+ * Returns undefined when no entry matches.
  */
 export function resolveTerminalRunEntry(
 	entries: SubagentRun[],
@@ -84,7 +96,57 @@ export function resolveTerminalRunEntry(
 ): SubagentRun | undefined {
 	const matching = entries.filter((r) => r.id === id);
 	if (matching.length === 0) return undefined;
-	return matching.find((r) => r.status !== "running") ?? matching[0];
+	return (
+		matching.find((r) => r.status !== "running") ??
+		matching.find((r) => r.interruptedAt) ??
+		matching[0]
+	);
+}
+
+/**
+ * Run-history display projection (issue #259): ONE record per SETTLED run.
+ *
+ * Each run appends two entries sharing its id — a spawn entry (status
+ * "running") first, then the terminal entry at settle — so a raw entry list
+ * renders every run twice and the spawn row shows a stale "running" forever.
+ * This collapses each id to its terminal-preferred entry via the ONE shared
+ * rule (`resolveTerminalRunEntry`). Runs still in flight (spawn entry, no
+ * terminal entry yet) are omitted: live state belongs to the monitor. U3 (D1)
+ * carves ONE exception — an INTERRUPTED run (running + `interruptedAt`, per
+ * `isInterruptedRun`) is surfaced, because the human must see it to recover or
+ * abandon it.
+ *
+ * Ordering is preserved from `entries`; callers pass `getRunEntries` output
+ * (newest-first via `cleanupRuns`), which stays the single ordering authority —
+ * no re-sort is performed here.
+ */
+export function collapseRunsForHistory(entries: SubagentRun[]): SubagentRun[] {
+	const display: SubagentRun[] = [];
+	const seen = new Set<string>();
+	for (const entry of entries) {
+		if (seen.has(entry.id)) continue;
+		seen.add(entry.id);
+		const resolved = resolveTerminalRunEntry(entries, entry.id);
+		if (resolved && (resolved.status !== "running" || isInterruptedRun(resolved))) {
+			display.push(resolved);
+		}
+	}
+	return display;
+}
+
+/**
+ * U3 (D3): the retry surface's candidate projection — settled FAILED runs plus
+ * unresolved INTERRUPTED runs, one row per id. Built on the SAME
+ * terminal-preferred collapse the history list uses, so the two surfaces can
+ * never disagree about which record represents a run. The retry offer reuses
+ * the existing `retryRunId` machinery (recorded params restored by
+ * `resolveRetryParams`), so an interrupted run is recoverable without any new
+ * delegate_task parameter.
+ */
+export function retryableRuns(entries: SubagentRun[]): SubagentRun[] {
+	return collapseRunsForHistory(entries).filter(
+		(r) => r.status === "failed" || isInterruptedRun(r),
+	);
 }
 
 // ---------------------------------------------------------------------------
@@ -158,6 +220,7 @@ export class SessionState {
 			gitMode: "none",
 			approvalMode: "writes",
 			completionNotify: DEFAULT_COMPLETION_NOTIFY,
+			recovery: DEFAULT_RECOVERY,
 			maxHistoryEntries: MAX_RUN_HISTORY_ENTRIES,
 			sessionCostLimit: DEFAULT_SESSION_COST_LIMIT,
 			perTaskCostEstimate: 0,
@@ -183,6 +246,7 @@ export class SessionState {
 			gitMode: this.config.gitMode,
 			approvalMode: this.config.approvalMode,
 			completionNotify: this.config.completionNotify,
+			recovery: this.config.recovery,
 			maxHistoryEntries: this.config.maxHistoryEntries,
 			sessionCostLimit: this.config.sessionCostLimit,
 			perTaskCostEstimate: this.config.perTaskCostEstimate,
@@ -194,8 +258,14 @@ export class SessionState {
 		});
 	}
 
-	persistRun(pi: ExtensionAPI, run: SubagentRun): void {
-		pi.appendEntry(CUSTOM_ENTRY_TYPES.run, run);
+	/**
+	 * Persist a run record through the ONE choke point (`persistRunRecord`),
+	 * which appends the session entry AND mirrors the record into the durable
+	 * in-flight registry. `kind` is supplied at dispatch; terminal writes clear
+	 * the registry entry.
+	 */
+	persistRun(pi: ExtensionAPI, run: SubagentRun, kind?: InflightRunKind): void {
+		persistRunRecord(pi, run, kind);
 	}
 
 	// -------------------------------------------------------------------
@@ -244,6 +314,9 @@ export class SessionState {
 			COMPLETION_NOTIFY_MODES.includes(data.completionNotify as CompletionNotifyMode)
 				? data.completionNotify
 				: DEFAULT_COMPLETION_NOTIFY;
+		this.config.recovery = RECOVERY_MODES.includes(data.recovery as RecoveryMode)
+			? data.recovery
+			: DEFAULT_RECOVERY;
 		if (data.maxHistoryEntries !== undefined) this.config.maxHistoryEntries = data.maxHistoryEntries;
 		if (data.sessionCostLimit !== undefined) this.config.sessionCostLimit = data.sessionCostLimit;
 		if (data.perTaskCostEstimate !== undefined) this.config.perTaskCostEstimate = data.perTaskCostEstimate;
@@ -533,6 +606,7 @@ export class SessionState {
 		this.config.gitMode = "none";
 		this.config.approvalMode = "writes";
 		this.config.completionNotify = DEFAULT_COMPLETION_NOTIFY;
+		this.config.recovery = DEFAULT_RECOVERY;
 		this.config.maxHistoryEntries = MAX_RUN_HISTORY_ENTRIES;
 		this.config.sessionCostLimit = DEFAULT_SESSION_COST_LIMIT;
 		this.config.perTaskCostEstimate = 0;

package/src/transcript-path.ts

@@ -0,0 +1,41 @@
+// Purpose: The single declaration of the transcript path format — filesystem (`join`) and display (POSIX) forms.
+import { join } from "node:path";
+import { assertSafeAgentId } from "./sanitize";
+
+/**
+ * The transcript directory, relative to the project root. This is the ONE
+ * declaration of the format; every other module derives its path from here
+ * rather than re-inlining `.pi/output` in a template string (issue #276).
+ */
+export const TRANSCRIPT_DIR = ".pi/output";
+
+/**
+ * Filesystem path to an agent's transcript: `<dir>/agent-<id>.jsonl`.
+ *
+ * SECURITY (F24): the id is validated through `assertSafeAgentId` BEFORE it
+ * reaches `path.join` — join does NOT sanitize `../` or absolute segments, so
+ * a traversal id would otherwise escape `dir`. Keep this chokepoint for every
+ * filesystem caller (`transcript.ts`, the `get_agent_result` re-export).
+ *
+ * `dir` is a parameter so `transcript.ts` can forward its mutable test-only
+ * `OUTPUT_DIR`; production callers take the `TRANSCRIPT_DIR` default.
+ */
+export function transcriptPath(agentId: string, dir: string = TRANSCRIPT_DIR): string {
+  assertSafeAgentId(agentId);
+  return join(dir, `agent-${agentId}.jsonl`);
+}
+
+/**
+ * Display form of the transcript path: `<TRANSCRIPT_DIR>/agent-<id>.jsonl`,
+ * always with forward slashes so the rendered panel is identical on every
+ * platform.
+ *
+ * This is deliberately format-only: it does NOT call `assertSafeAgentId` and
+ * must never throw. It is called during TUI rendering (`tui.ts` →
+ * `buildOutputHonestyLines`) from a stored run record, where a throw would
+ * break the panel. Display text is POSIX while filesystem access uses `join` —
+ * the two forms intentionally differ (settled in issue #276).
+ */
+export function transcriptDisplayPath(agentId: string): string {
+  return `${TRANSCRIPT_DIR}/agent-${agentId}.jsonl`;
+}

package/src/transcript.ts

@@ -1,12 +1,17 @@
 // Purpose: JSONL transcript recording for every agent run (`.pi/output/agent-<id>.jsonl`).
-import { join } from 'path';
 import { mkdirSync, appendFileSync, readFileSync, existsSync } from 'fs';
 import type { TranscriptEntry, TranscriptEntryType } from './types';
-import { assertSafeAgentId } from './sanitize';
+import { transcriptPath, TRANSCRIPT_DIR } from './transcript-path';
+import { createLogger } from './logging';
+
+// Issue #265: route the settle-path warning through the logger (file-only by
+// default) instead of a raw console.warn that corrupts the pi TUI.
+const log = createLogger('brl-subagent');
 
 // Output directory — overridable for tests (issue #52): unit tests must NOT
-// write into the real repo .pi/ dir; the setter is test-only.
-let OUTPUT_DIR = '.pi/output';
+// write into the real repo .pi/ dir; the setter is test-only. Defaults to the
+// single-sourced TRANSCRIPT_DIR (issue #276).
+let OUTPUT_DIR = TRANSCRIPT_DIR;
 
 /**
  * TEST-ONLY: point the transcript output at an alternate directory.
@@ -30,13 +35,9 @@ function ensureOutputDir(): void {
  * Get transcript file path for an agent
  */
 export function getTranscriptPath(agentId: string): string {
-  // F24: single chokepoint for every transcript file path. All internal callers
-  // (startTranscript/appendEntry/getTranscript/completeTranscript) pass
-  // generateUUID() ids, but get_agent_result feeds LLM-controlled ids in via
-  // getTranscript. path.join does not sanitize "../" or absolute segments, so
-  // throw on anything that is not a UUID before it reaches the filesystem.
-  assertSafeAgentId(agentId);
-  return join(OUTPUT_DIR, `agent-${agentId}.jsonl`);
+  // Issue #276: the format and the F24 `assertSafeAgentId` chokepoint live in
+  // transcript-path.ts; here we only forward the mutable test-only OUTPUT_DIR.
+  return transcriptPath(agentId, OUTPUT_DIR);
 }
 
 /**
@@ -118,7 +119,7 @@ export function completeTranscript(agentId: string, status: string): void {
   // appending — that invariant is load-bearing for caller validation).
   const path = getTranscriptPath(agentId);
   if (!existsSync(path)) {
-    console.warn(`[brl-subagent] completeTranscript: transcript missing for agent ${agentId} — skipping completion entry`);
+    log.warn(`completeTranscript: transcript missing for agent ${agentId} — skipping completion entry`);
     return;
   }
   appendEntry(agentId, 'system', `Transcript completed: ${status}`);