brl-subagent 2.4.0 → 2.5.0

package/src/state.ts

@@ -35,6 +35,7 @@ import {
 	CIRCUIT_DEGRADED_THINKING,
 } from "./types";
 import { cleanupRuns } from "./history";
+import { persistRunRecord, type InflightRunKind } from "./run-registry";
 import type { Logger } from "./logging";
 
 // ---------------------------------------------------------------------------
@@ -69,14 +70,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 +92,37 @@ 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.
+ *
+ * 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") display.push(resolved);
+	}
+	return display;
 }
 
 // ---------------------------------------------------------------------------
@@ -194,8 +232,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);
 	}
 
 	// -------------------------------------------------------------------

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}`);

package/src/tui.ts

@@ -14,7 +14,7 @@ import type {
 	ToolRenderResultOptions,
 } from "@earendil-works/pi-coding-agent";
 import { DynamicBorder, getMarkdownTheme } from "@earendil-works/pi-coding-agent";
-import { Container, type SelectItem, SelectList, Spacer, Text, Markdown } from "@earendil-works/pi-tui";
+import { Container, type Component, type SelectItem, SelectList, Spacer, Text, Markdown, matchesKey } from "@earendil-works/pi-tui";
 import type { Api, Model } from "@earendil-works/pi-ai";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import type {
@@ -41,6 +41,7 @@ import {
 	COLLAPSED_OUTPUT_LINES,
 	COLLAPSED_DIFF_FILES_PREVIEW,
 	EXPANDED_HUNKS_PER_FILE,
+	DEFAULT_OUTPUT_CAP_BYTES,
 	formatTokens,
 	formatUsageStats,
 	formatModel,
@@ -49,15 +50,16 @@ import {
 	isSubagentError,
 	isMultiSubagentDetails,
 	isGraphDetails,
+	isUnsettledPartial,
 } from "./types";
 import { buildFileAccessReport, buildSecretsExposureReport, generateComplianceSummary } from "./reports";
 import { extractParamNames } from "./templates";
 import { parseDiff } from "./diff";
 import { formatPresetSummary, getPreset, loadCustomPresets } from "./presets";
-import { formatRunDuration } from "./history";
+import { buildOutputHonestyLines, formatRunDuration } from "./history";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { sweepStaleLiveSubagents, type SessionState } from "./state";
+import { collapseRunsForHistory, sweepStaleLiveSubagents, type SessionState } from "./state";
 import { getAgent } from "./session-manager";
 import { computeSLAMetrics, computeCostTrend, formatSparkline } from "./metrics";
 import { formatElapsed, liveRowName, liveSpinner, formatLiveRowDim } from "./tui-format";
@@ -1088,127 +1090,253 @@ export async function showRunHistory(
 	state: SessionState,
 	persistState: () => void,
 ): Promise<void> {
-	const runs = state.getRunEntries(ctx).reverse();
-
-	if (runs.length === 0) {
-		ctx.ui.notify("No subagent runs recorded yet. Delegate a task to see history.", "info");
-		return;
-	}
-
 	const statusIcon: Record<string, string> = {
 		running: ctx.ui.theme.fg("accent", "◉"),
 		done: ctx.ui.theme.fg("success", "✓"),
 		failed: ctx.ui.theme.fg("error", "✗"),
 	};
 
-	const items: SelectItem[] = runs.map((r) => {
-		const icon = statusIcon[r.status] || "·";
-		const name = r.label || r.task.slice(0, 60);
-		const model = r.model.split("/").pop() || r.model;
-		const when = r.finishedAt ? formatRunDuration(r.durationMs || 0) : "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 };
-	});
+	// Browse loop (issue #260): list → detail → list … until the LIST is exited
+	// with Esc. Closing a detail returns here, not to the /brl-subagent menu.
+	while (true) {
+		// 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));
+
+		if (runs.length === 0) {
+			ctx.ui.notify("No subagent runs recorded yet. Delegate a task to see history.", "info");
+			return;
+		}
 
-	const selectedId = await showSelectList(ctx, "Subagent History", items, 15);
-	if (!selectedId) return;
+		const items: SelectItem[] = runs.map((r) => {
+			const icon = statusIcon[r.status] || "·";
+			const name = r.label || r.task.slice(0, 60);
+			const model = r.model.split("/").pop() || r.model;
+			const when = r.finishedAt ? formatRunDuration(r.durationMs || 0) : "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 };
+		});
 
-	const run = runs.find((r) => r.id === selectedId);
-	if (!run) return;
+		const selectedId = await showSelectList(ctx, "Subagent History", items, 15);
+		if (!selectedId) return; // Esc at the list exits to the menu
 
-	// Mark as seen
-	if (state.markRunSeen(run.id)) {
-		persistState();
-		import("./concurrency").then(({ updateProgressStatus }) => {
-			updateProgressStatus(state, ctx);
-		});
+		const run = runs.find((r) => r.id === selectedId);
+		if (!run) continue; // selected run pruned since listing — re-show the list
+
+		// Mark as seen
+		if (state.markRunSeen(run.id)) {
+			persistState();
+			import("./concurrency").then(({ updateProgressStatus }) => {
+				updateProgressStatus(state, ctx);
+			});
+		}
+
+		await showRunDetail(ctx, run);
 	}
+}
 
-	// Show detail view
-	await ctx.ui.custom<void>((tui, theme, _kb, done) => {
-		const container = new Container();
-		container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+/**
+ * Number of output lines a run-detail viewport shows at once (issue #261):
+ * the stored text can be up to the 100 KB cap, so the panel is height-capped
+ * and scrolled rather than dumped whole (which would push the footer and
+ * header off-screen).
+ */
+const RUN_DETAIL_OUTPUT_VIEWPORT_LINES = 12;
 
-		const statusLabel =
-			run.status === "done" ? "Completed" : run.status === "failed" ? "Failed" : "Running";
-		container.addChild(
-			new Text(
-				theme.fg(
-					"toolTitle",
-					theme.bold(`${run.label || "Subagent"} — ${statusLabel}`),
-				),
-				1,
-				0,
-			),
-		);
-		container.addChild(new Text("", 0, 0));
-		container.addChild(
-			new Text(theme.fg("dim", `Task: ${run.task.slice(0, 200)}`), 1, 0),
-		);
-		container.addChild(
-			new Text(
-				theme.fg("dim", `Model: ${run.model} · Thinking: ${run.thinkingLevel}`),
-				1,
-				0,
-			),
-		);
-		container.addChild(new Text(theme.fg("dim", `Started: ${run.startedAt}`), 1, 0));
-		if (run.finishedAt) {
-			container.addChild(
+/**
+ * Detail view for one settled run (issue #260, #261): ↑/↓ and PgUp/PgDn scroll
+ * the stored output; any OTHER key — including Esc — closes it. The
+ * showRunHistory browse loop re-shows the list on return.
+ *
+ * The output region follows the approval dialog's full-diff view structure
+ * (see `showApprovalDialog.buildDiffView` / `withDiffKeybinding`: a bordered
+ * Container with a title, the content, and a return footer) but adds the
+ * height cap + scroll state that view lacks. Output is wrapped through the
+ * same `Text` component those views use, so wrapping/padding stay consistent.
+ */
+async function showRunDetail(ctx: ExtensionContext, run: SubagentRun): Promise<void> {
+	const outputText = run.fullOutput ?? run.outputSummary ?? "";
+	await ctx.ui.custom<void>((tui, theme, kb, done) => {
+		// First line of the viewport (0 = top). Mutated by scroll keys and
+		// clamped to the wrapped-content length on every render.
+		let scrollTop = 0;
+		// Wrapped output lines for the current width, and the width they were
+		// produced at, so a resize re-wraps and a redraw does not.
+		let wrappedLines: string[] = [];
+		let wrappedWidth = -1;
+
+		const wrapOutput = (width: number): string[] => {
+			if (width === wrappedWidth) return wrappedLines;
+			wrappedLines = new Text(theme.fg("toolOutput", outputText), 1, 0).render(width);
+			wrappedWidth = width;
+			return wrappedLines;
+		};
+
+		const buildOutputSection = (width: number): Container => {
+			const section = new Container();
+			const lines = wrapOutput(width);
+			const total = lines.length;
+			const maxScroll = Math.max(0, total - RUN_DETAIL_OUTPUT_VIEWPORT_LINES);
+			if (scrollTop > maxScroll) scrollTop = maxScroll;
+			if (scrollTop < 0) scrollTop = 0;
+			const from = total === 0 ? 0 : Math.min(scrollTop + 1, total);
+			const to = Math.min(scrollTop + RUN_DETAIL_OUTPUT_VIEWPORT_LINES, total);
+			const indicator =
+				total > RUN_DETAIL_OUTPUT_VIEWPORT_LINES
+					? `  (lines ${from}\u2013${to} of ${total} \u00b7 \u2191\u2193 / PgUp\u00b7PgDn)`
+					: `  (${total} line${total === 1 ? "" : "s"})`;
+
+			section.addChild(
 				new Text(
-					theme.fg(
-						"dim",
-						`Finished: ${run.finishedAt} (${formatRunDuration(run.durationMs || 0)})`,
-					),
+					theme.fg("muted", "\u2500\u2500\u2500 Output \u2500\u2500\u2500") + theme.fg("dim", indicator),
 					1,
 					0,
 				),
 			);
-		}
-		if (run.cost) {
+
+			if (total === 0) {
+				section.addChild(new Text(theme.fg("dim", "(no output recorded)"), 1, 0));
+				return section;
+			}
+
+			// Height-capped viewport: the output was already wrapped to `width`
+			// above, so hand the sliced lines back directly instead of feeding them
+			// through another Text (which would re-wrap at the padded width).
+			const viewport: Component = {
+				render: () => lines.slice(scrollTop, scrollTop + RUN_DETAIL_OUTPUT_VIEWPORT_LINES),
+				invalidate: () => {
+					wrappedWidth = -1;
+				},
+			};
+			section.addChild(viewport);
+			return section;
+		};
+
+		const buildDetailView = (width: number): Container => {
+			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";
 			container.addChild(
 				new Text(
 					theme.fg(
-						"dim",
-						`Cost: $${run.cost.toFixed(4)} · ↑${formatTokens(run.tokensIn || 0)} ↓${formatTokens(run.tokensOut || 0)}`,
+						"toolTitle",
+						theme.bold(`${run.label || "Subagent"} — ${statusLabel}`),
 					),
 					1,
 					0,
 				),
 			);
-		}
-		if (run.errorMessage) {
-			container.addChild(new Spacer(1));
+			container.addChild(new Text("", 0, 0));
 			container.addChild(
-				new Text(theme.fg("error", `Error: ${run.errorMessage}`), 1, 0),
+				new Text(theme.fg("dim", `Task: ${run.task.slice(0, 200)}`), 1, 0),
 			);
-		}
-		if (run.outputSummary) {
-			container.addChild(new Spacer(1));
 			container.addChild(
 				new Text(
-					theme.fg("muted", "\u2500\u2500\u2500 Output Preview \u2500\u2500\u2500"),
+					theme.fg("dim", `Model: ${run.model} · Thinking: ${run.thinkingLevel}`),
 					1,
 					0,
 				),
 			);
-			container.addChild(
-				new Text(theme.fg("toolOutput", run.outputSummary), 1, 0),
-			);
-			if ((run.outputSummary || "").length >= 200) {
-				container.addChild(new Text(theme.fg("dim", "(first 200 characters)"), 1, 0));
+			container.addChild(new Text(theme.fg("dim", `Started: ${run.startedAt}`), 1, 0));
+			if (run.finishedAt) {
+				container.addChild(
+					new Text(
+						theme.fg(
+							"dim",
+							`Finished: ${run.finishedAt} (${formatRunDuration(run.durationMs || 0)})`,
+						),
+						1,
+						0,
+					),
+				);
+			}
+			if (run.cost) {
+				container.addChild(
+					new Text(
+						theme.fg(
+							"dim",
+							`Cost: $${run.cost.toFixed(4)} · ↑${formatTokens(run.tokensIn || 0)} ↓${formatTokens(run.tokensOut || 0)}`,
+						),
+						1,
+						0,
+					),
+				);
+			}
+			if (run.errorMessage) {
+				container.addChild(new Spacer(1));
+				container.addChild(
+					new Text(theme.fg("error", `Error: ${run.errorMessage}`), 1, 0),
+				);
 			}
-		}
 
-		container.addChild(new Spacer(1));
-		container.addChild(new Text(theme.fg("dim", "Press any key to close"), 1, 0));
-		container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+			container.addChild(new Spacer(1));
+			container.addChild(buildOutputSection(width));
+			// Honest disclosures (issue #261): the transcript is the only place the
+			// uncapped text lives, and the cap is stated when it was hit.
+			for (const line of buildOutputHonestyLines(run, DEFAULT_OUTPUT_CAP_BYTES)) {
+				container.addChild(new Text(theme.fg("dim", line), 1, 0));
+			}
+
+			container.addChild(new Spacer(1));
+			container.addChild(
+				new Text(
+					theme.fg("dim", "\u2191\u2193 scroll \u00b7 alt+\u2191\u2193 page \u00b7 any other key to close"),
+					1,
+					0,
+				),
+			);
+			container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+			return container;
+		};
 
 		return {
-			render: (w: number) => container.render(w),
-			invalidate: () => container.invalidate(),
-			handleInput: (_data: string) => done(),
+			render: (w: number) => buildDetailView(w).render(w),
+			invalidate: () => {},
+			handleInput: (data: string) => {
+				// Paging: alt+↑ / alt+↓. Checked BEFORE the plain arrows so an
+				// alt-modified sequence can never be consumed as a line step.
+				// PgUp/PgDn are unusable here: the host binds them to the
+				// alt-screen transcript scroll (`tui.altScreen.pageUp/pageDown`)
+				// and consumes them before a `ctx.ui.custom` overlay sees input —
+				// pi 1.0.2 has no viewport-owner registration for overlays. The
+				// PgUp/PgDn checks below stay for inline mode, where they do
+				// reach the overlay.
+				if (matchesKey(data, "alt+up")) {
+					scrollTop -= RUN_DETAIL_OUTPUT_VIEWPORT_LINES;
+					tui.requestRender();
+					return;
+				}
+				if (matchesKey(data, "alt+down")) {
+					scrollTop += RUN_DETAIL_OUTPUT_VIEWPORT_LINES;
+					tui.requestRender();
+					return;
+				}
+				if (kb.matches(data, "tui.select.up")) {
+					scrollTop -= 1;
+					tui.requestRender();
+					return;
+				}
+				if (kb.matches(data, "tui.select.down")) {
+					scrollTop += 1;
+					tui.requestRender();
+					return;
+				}
+				if (kb.matches(data, "tui.select.pageUp")) {
+					scrollTop -= RUN_DETAIL_OUTPUT_VIEWPORT_LINES;
+					tui.requestRender();
+					return;
+				}
+				if (kb.matches(data, "tui.select.pageDown")) {
+					scrollTop += RUN_DETAIL_OUTPUT_VIEWPORT_LINES;
+					tui.requestRender();
+					return;
+				}
+				done();
+			},
 		};
 	});
 }
@@ -2803,7 +2931,19 @@ export function renderDelegateResult(
 	}
 
 	// Single subagent mode (original)
-	if (!details || details.exitCode === -1) {
+	// Issue #298 (C2): the partial-vs-settled decision lives in ONE place —
+	// `isUnsettledPartial` (src/types.ts) owns the overloaded `exitCode === -1`
+	// disambiguation (the #206 streaming sentinel vs the #295 settled signal
+	// death). Do not re-derive it here; the terminal-status structural ratchet
+	// fails a local copy. A genuine partial (or a result with no details yet)
+	// renders the raw running text; a classified -1 is a settled FAILURE and
+	// takes the verdict branch below (✗ + error line + expanded-transcript
+	// binding), never raw text.
+	//
+	// The leading `!details` is a type-narrowing aid for the settled branch below
+	// (TS cannot narrow through a function call); it is NOT a second copy of the
+	// decision — the predicate owns the no-details case too.
+	if (!details || isUnsettledPartial(details)) {
 		const text = result.content[0];
 		return new Text(text?.type === "text" ? text.text : "(running\u2026)", 0, 0);
 	}