brl-subagent 2.3.6 → 2.3.8

package/src/logging.ts

@@ -8,6 +8,9 @@
  *   const log = createLogger("runner", cwd);
  *   log.info("Subagent started", { model, thinkingLevel });
  *   log.error("Subagent failed", { error: err.message });
+ *
+ * Module-load callers pass no cwd; they call setLogCwd(ctx.cwd) once the
+ * session starts and all loggers share <cwd>/.pi/subagent-logs/brl-subagent.log.
  */
 
 import * as fs from "node:fs";
@@ -24,6 +27,12 @@ const MAX_LOG_SIZE = 5 * 1024 * 1024;
 /** Maximum number of rotated log files to keep */
 const MAX_LOG_FILES = 5;
 
+/**
+ * The single log file every logger writes to (issue #179). The JSON entry body
+ * already carries its `prefix`, so one shared file stays readable.
+ */
+const LOG_FILE_NAME = "brl-subagent.log";
+
 /** Log levels in order of verbosity */
 const LOG_LEVELS: Record<LogLevel, number> = {
 	debug: 0,
@@ -50,23 +59,33 @@ export function setLogLevel(level: LogLevel): void {
 	minLevel = level;
 }
 
+// Issue #179 (D6): createLogger() runs at MODULE LOAD (index.ts,
+// session-manager.ts) where the session cwd does not exist yet. The cwd is set
+// later from the session_start hook (ctx.cwd). All logger instances share this
+// module-level value so every entry lands in ONE
+// `<cwd>/.pi/subagent-logs/brl-subagent.log`.
+let logCwd: string | undefined;
+
+/**
+ * Point file logging at a session cwd (or clear it with undefined). Called from
+ * the session-start hook so module-load loggers can write once a cwd exists.
+ */
+export function setLogCwd(cwd: string | undefined): void {
+	logCwd = cwd;
+}
+
+function resolveLogDir(): string | undefined {
+	return logCwd ? path.join(logCwd, ".pi", "subagent-logs") : undefined;
+}
+
 /**
  * Create a logger for a specific module.
- * Logs are written to `.pi/subagent-logs/<prefix>.log` relative to `cwd`.
+ * Logs are written to `<cwd>/.pi/subagent-logs/brl-subagent.log` relative to the
+ * session cwd (set via setLogCwd or the optional `cwd` arg).
  */
 export function createLogger(prefix: string, cwd?: string): Logger {
-	const logDir = cwd ? path.join(cwd, ".pi", "subagent-logs") : undefined;
-
-	// Ensure log directory exists — owner-only (0o700) so other local users
-	// cannot list log files (F6 / issue #29). File writes below already use
-	// 0o600.
-	if (logDir) {
-		try {
-			fs.mkdirSync(logDir, { recursive: true, mode: 0o700 });
-		} catch {
-			// Can't create log dir — fall back to console-only logging
-		}
-	}
+	// Compat: an explicit cwd argument still sets the shared location eagerly.
+	if (cwd) logCwd = cwd;
 
 	function log(level: LogLevel, message: string, data?: Record<string, unknown>): void {
 		if (LOG_LEVELS[level] < LOG_LEVELS[minLevel]) return;
@@ -86,10 +105,15 @@ export function createLogger(prefix: string, cwd?: string): Logger {
 		const consoleMethod = level === "error" ? console.error : level === "warn" ? console.warn : console.log;
 		consoleMethod(`[${prefix}] ${level.toUpperCase()}: ${message}`);
 
-		// File output
+		// File output — resolved on each call because the cwd may be set after
+		// createLogger ran (module load) but before the first entry.
+		const logDir = resolveLogDir();
 		if (logDir) {
 			try {
-				const logFile = path.join(logDir, `${prefix}.log`);
+				// Owner-only (0o700) so other local users cannot list log files
+				// (F6 / issue #29); the file writes below already use 0o600.
+				fs.mkdirSync(logDir, { recursive: true, mode: 0o700 });
+				const logFile = path.join(logDir, LOG_FILE_NAME);
 				rotateIfNeeded(logFile);
 				fs.appendFileSync(logFile, line + "\n", { encoding: "utf-8", mode: 0o600 });
 			} catch {

package/src/notify-completion.ts

@@ -25,6 +25,8 @@ import type {
 } from "./types";
 import { truncateTail } from "./transcript-tail";
 import { formatRunDuration } from "./history";
+import { classifyTerminalOutcome } from "./types";
+import { resolveTerminalRunEntry } from "./state";
 
 /** Terminal statuses the completion message can carry. */
 export type CompletionStatus = "completed" | "failed" | "stopped";
@@ -35,6 +37,8 @@ export interface CompletionMessageDetails {
 	status: CompletionStatus;
 	errorCategory: string;
 	errorMessage?: string;
+	/** Issue #179 (D2): the terminal stopReason behind the classified status. */
+	stopReason?: string;
 	costUsd?: number;
 	tokensIn?: number;
 	tokensOut?: number;
@@ -59,12 +63,12 @@ const DEDUPE_CAP = 200;
 
 /**
  * Soft directive appended to the content (D3): the conductor should process
- * the completion silently unless action is needed; on failure apply the retry
- * taxonomy (re-dispatch ≠ retry; Rule 18 governs terminations — ask the user
- * before terminating anything).
+ * the completion silently unless action is needed. If the run failed, it
+ * should investigate the cause before re-dispatching rather than re-issuing an
+ * identical task — any re-issue is confirmed with the user first.
  */
 const COMPLETION_DIRECTIVE =
-	"Process this completion silently unless action is needed. If the run failed, apply the retry taxonomy: a re-dispatch is not a retry, and Rule 18 governs terminations — ask the user before terminating anything.";
+	"Process this completion silently unless action is needed. If the run failed, investigate before re-dispatching — do not re-issue an identical task without confirming the cause with the user.";
 
 /**
  * Normalize a BackgroundAgent status to a terminal status word. The subscriber
@@ -77,24 +81,17 @@ export function normalizeCompletionStatus(status: AgentStatus): CompletionStatus
 }
 
 /**
- * Resolve the finalized entry for a run id among the raw getRunEntries list.
- *
- * Each background run writes TWO custom entries sharing the same id and
- * startedAt: a spawn entry (status "running") and a final entry (status
- * "done"/"failed", stamped by finalizeRunRecord). The raw list preserves
- * append order — the spawn entry comes FIRST (verified empirically) — so a
- * plain `.find(r => r.id === id)` matches the spawn entry and never sees the
- * stamped errorCategory/cost/duration/tokens. Prefer the terminal entry
- * (status !== "running"); when none is terminal yet, fall back to the
- * matching spawn entry (the pre-finalize stopped-run shape).
+ * Resolve the finalized (terminal-preferring) entry for a run id among the raw
+ * getRunEntries list. Thin delegate to the shared `resolveTerminalRunEntry`
+ * rule in src/state.ts (the core module owns the preference rule; see there
+ * for the two-entry spawn/final append order). Kept under this name for the
+ * completion wake path and its existing tests.
  */
 export function resolveRunEntry(
 	entries: SubagentRun[],
 	id: string,
 ): 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 resolveTerminalRunEntry(entries, id);
 }
 
 /**
@@ -128,23 +125,50 @@ export function buildCompletionMessage(
 	agent: BackgroundAgent,
 	run: SubagentRun | undefined,
 ): CompletionMessagePayload {
-	const status = normalizeCompletionStatus(agent.status);
+	let status = normalizeCompletionStatus(agent.status);
+	// Issue #179 (D2): the notification category must NEVER default to success
+	// merely because `agent.status === "completed"`. The SDK resolves a mid-run
+	// provider death, so the run entry is the authoritative classified reason —
+	// downgrade a stale "completed" when the run says otherwise.
+	if (status === "completed" && run) {
+		const outcome = classifyTerminalOutcome(run.stopReason, run.errorMessage);
+		if (outcome.status !== "completed") {
+			status = outcome.status;
+		} else if (run.status === "failed") {
+			status = "failed";
+		}
+	}
 	// BackgroundAgent has no `label` field — the caller's label is `description`
 	// (set from params.description at spawn). Fall back to the id.
 	const label = agent.description || agent.id;
 	// completed → "success"; failed/stopped → classified category from the run
 	// record (finalizeRunEntry stamps it), falling back to "unknown".
 	const errorCategory =
-		status === "completed" ? "success" : (run?.originalParams?.errorCategory ?? "unknown");
+		status === "completed"
+			? "success"
+			: (run?.errorCategory ?? run?.originalParams?.errorCategory ?? "unknown");
 	const durationMs = run?.durationMs;
 	const costUsd = run?.cost;
 	const tokensIn = run?.tokensIn;
 	const tokensOut = run?.tokensOut;
+	const stopReason = run?.stopReason;
 	const errorMessage = status === "completed" ? undefined : agent.error ?? run?.errorMessage;
 
 	const summary = buildSummaryLine(label, agent.id, status, durationMs, costUsd, errorCategory);
-	const tail = truncateTail(agent.finalOutput ?? run?.fullOutput ?? "", 15);
+	// Issue #179 (C1 fix): truncateTail keeps the LAST 15 lines, but the failure
+	// headline is PREPENDED to the stored output — long earlier-turn prose would
+	// otherwise push the failure reason out of the notified body. Peel it off
+	// before tailing and re-add it as its own part so the reason is never
+	// truncated away.
+	const stored = agent.finalOutput ?? run?.fullOutput ?? "";
+	const headline = status === "completed" ? undefined : errorMessage;
+	const body =
+		headline && stored.startsWith(headline)
+			? stored.slice(headline.length).replace(/^\n+/, "")
+			: stored;
+	const tail = truncateTail(body, 15);
 	const parts = [summary];
+	if (headline) parts.push(headline);
 	if (tail) parts.push(tail);
 	parts.push(COMPLETION_DIRECTIVE);
 	const content = parts.join("\n\n");
@@ -154,6 +178,7 @@ export function buildCompletionMessage(
 		status,
 		errorCategory,
 		...(errorMessage ? { errorMessage } : {}),
+		...(stopReason ? { stopReason } : {}),
 		...(costUsd !== undefined ? { costUsd } : {}),
 		...(tokensIn !== undefined ? { tokensIn } : {}),
 		...(tokensOut !== undefined ? { tokensOut } : {}),

package/src/runner.ts

@@ -27,6 +27,7 @@ import {
 	SIGKILL_GRACE_MS,
 	TEMP_FILE_MODE,
 	MAX_TEMP_DIR_AGE_MS,
+	isProviderError,
 	classifyError,
 	SUBAGENT_ABORTED_MESSAGE,
 } from "./types";
@@ -666,7 +667,7 @@ export function parseSubagentLine(
 function countModelErrorTurns(messages: Array<Record<string, unknown>>): number {
 	let count = 0;
 	for (const msg of messages) {
-		if (msg.role === "assistant" && msg.stopReason === "error") count++;
+		if (msg.role === "assistant" && isProviderError(msg.stopReason as string | undefined)) count++;
 	}
 	return count;
 }

package/src/session-manager.ts

@@ -1,8 +1,8 @@
 import { randomUUID } from 'crypto';
 import { join } from 'path';
 import { mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync } from 'fs';
-import type { BackgroundAgent, AgentStatus, GitMode, SubagentResult, SubagentRun, ThinkingLevel, SubagentToolOptions, UsageStats } from './types';
-import { EMPTY_USAGE, CUSTOM_ENTRY_TYPES, classifyError, SUBAGENT_ABORTED_MESSAGE } from './types';
+import type { BackgroundAgent, AgentStatus, GitMode, SubagentResult, SubagentRun, ThinkingLevel, SubagentToolOptions, UsageStats, ErrorCategory } from './types';
+import { EMPTY_USAGE, CUSTOM_ENTRY_TYPES, classifyError, classifyTerminalOutcome, isSubagentError, isProviderError, coherentFailureReason, SUBAGENT_ABORTED_MESSAGE } from './types';
 import { accumulateUsage } from './runner';
 import * as eventBus from './event-bus';
 import * as transcript from './transcript';
@@ -230,7 +230,10 @@ export function setAgentResult(id: string, result: SubagentResult): BackgroundAg
   if (!agent) return null;
   
   agent.result = result;
-  agent.status = result.exitCode === 0 ? 'completed' : 'failed';
+  // Issue #179 (D1): honor the full terminal reason (stopReason error/aborted/
+  // length/incomplete), not exitCode alone — a mid-run provider death resolves
+  // with exitCode 0 and was previously recorded as 'completed'.
+  agent.status = isSubagentError(result) ? 'failed' : 'completed';
   agent.completedAt = Date.now();
   
   agents.set(id, agent);
@@ -238,6 +241,39 @@ export function setAgentResult(id: string, result: SubagentResult): BackgroundAg
   return agent;
 }
 
+/**
+ * Issue #179 (D4): when a run ends in a failure, the prose extracted by
+ * extractFinalOutput may come from an EARLIER turn — the failing turn carries
+ * no text of its own. Prefixing the failure reason makes the output honest
+ * instead of a plausible-looking success narrative.
+ */
+export function buildFailureHeadline(reason: string, output: string): string {
+  const trimmed = output.trim();
+  return trimmed ? `${reason}\n\n${trimmed}` : reason;
+}
+
+/**
+ * Issue #179 (D3/D4): a run that ended without a terminal answer must still
+ * record WHY. When the provider supplied no message, synthesize one from the
+ * stopReason so the run entry never claims a failure with an empty reason.
+ */
+function defaultTerminalMessage(stopReason: string | undefined): string {
+  switch (stopReason) {
+    case 'error':
+      return 'Run ended with a provider error (stopReason "error")';
+    case 'length':
+      return 'Run ended early: output length limit reached (stopReason "length")';
+    case 'toolUse':
+      return 'Run ended mid-turn without a final answer (stopReason "toolUse")';
+    case 'deferred':
+      return 'Run ended deferred without a final answer (stopReason "deferred")';
+    case 'pending':
+      return 'Run ended while still pending (stopReason "pending")';
+    default:
+      return 'Run ended without completing';
+  }
+}
+
 /**
  * Extract the final assistant text from a session's messages.
  * Falls back to the LAST assistant message with non-empty text content — the
@@ -505,7 +541,7 @@ export async function spawnBackgroundSession(
   
   // Issue #98: background runs must be retry-able — persist a session run
   // entry at spawn (id == agent id, so retryRunId: <agent-id> resolves via
-  // state.findRunById → getRunEntries). The entry lives in the same session
+  // state.findSpawnRunById → getRunEntries). The entry lives in the same session
   // custom-entry store the foreground path writes to (state.persistRun); the
   // background path previously never wrote there, so retries silently no-oped.
   const startedAtMs = agent.startedAt; // reuse the agent record's start clock
@@ -531,29 +567,53 @@ export async function spawnBackgroundSession(
   // ("done"/"failed"). The guard keeps the entry single-finalized even when a
   // settle handler throws after finalizing (markTerminalBestEffort catch-all).
   let runFinalized = false;
-  const finalizeRunEntry = (status: "done" | "failed", error?: string): void => {
+  const finalizeRunEntry = (
+    status: "done" | "failed",
+    error?: string,
+    terminal?: { stopReason?: string; errorCategory?: ErrorCategory },
+  ): void => {
     if (runFinalized) return;
     runFinalized = true;
     const usage = agent.result?.usage ?? EMPTY_USAGE;
     const finalOutput = agent.finalOutput ?? "";
-    // Issue #120 (Track 1): stamp the honest errorCategory on the background run
-    // record the same way the foreground path does (index.ts sets
-    // run.originalParams.errorCategory = classifyError(result)). Previously the
-    // background entry never carried a category, so background failures were
-    // invisible to the SLA errorCategoryBreakdown and to failure diagnostics.
+    // Issue #179 (D1/D2): the classifier's explicit category wins (it knows the
+    // terminal stopReason); otherwise fall back to the legacy message-based
+    // classification (refused spawns, sync throws, preflight rejections, the
+    // catch-all) so no failure is ever left uncategorized.
     const errorCategory =
-      status === "failed" && error
-        ? classifyError({
-            messages: [],
-            usage: { ...EMPTY_USAGE },
-            exitCode: 1,
-            stderr: "",
-            errorMessage: error,
-          })
+      status === "failed"
+        ? terminal?.errorCategory ??
+          (error
+            ? classifyError({
+                messages: [],
+                usage: { ...EMPTY_USAGE },
+                exitCode: 1,
+                stderr: "",
+                errorMessage: error,
+              })
+            : undefined)
         : undefined;
+    // Issue #187: capture the RAW terminal reason BEFORE coercion. `finalTurnError`
+    // means "the final turn was a PROVIDER error" (isProviderError); deriving it
+    // from the COERCED reason would turn a missing/success reason into 'error' and
+    // mislabel a non-provider failure (hard-cap timeout, spawn throw) as one.
+    const rawStopReason = terminal?.stopReason ?? agent.result?.stopReason;
+    const stopReason =
+      status === "failed"
+        ? coherentFailureReason(rawStopReason, errorCategory)
+        : rawStopReason;
     const entry: SubagentRun = {
       ...run,
       status,
+      // Issue #179 (D2): the run entry carries the CLASSIFIED reason, not just
+      // an opaque error string.
+      stopReason,
+      errorCategory,
+      // Issue #179 (D3): work volume + terminal-error signal. `turns`/`tokensOut`
+      // are already in the usage data; recording them here makes "did nothing"
+      // (turns 0) explicit versus "did work then died" (turns > 0, error).
+      turns: usage.turns,
+      finalTurnError: isProviderError(rawStopReason),
       errorMessage: error,
       finishedAt: new Date().toISOString(),
       durationMs: Date.now() - startedAtMs,
@@ -570,6 +630,17 @@ export async function spawnBackgroundSession(
           : run.originalParams,
     };
     pi.appendEntry(CUSTOM_ENTRY_TYPES.run, 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", {
+      agentId: id,
+      status,
+      stopReason,
+      turns: usage.turns,
+      tokensOut: usage.output,
+      errorCategory,
+      error: error ?? null,
+    });
   };
 
   // Start transcript for this agent
@@ -582,8 +653,16 @@ export async function spawnBackgroundSession(
   // final output while the session is still live, THEN release the ref — the
   // capture must always precede the release or the output dies with the
   // session graph. Single helper for all four settlement paths.
-  const captureAndReleaseSession = (): void => {
-    setAgentFinalOutput(id, extractFinalOutput(session));
+  //
+  // Issue #179 (D4): an optional failureHeadline is prepended when the run did
+  // NOT complete — the extracted prose may come from an earlier turn, so it
+  // must not be presented as the run's output unqualified.
+  const captureAndReleaseSession = (failureHeadline?: string): void => {
+    const output = extractFinalOutput(session);
+    setAgentFinalOutput(
+      id,
+      failureHeadline ? buildFailureHeadline(failureHeadline, output) : output,
+    );
     agent._sessionRef = undefined;
   };
 
@@ -850,7 +929,7 @@ export async function spawnBackgroundSession(
     cleanupWorkBranch();
     // Issue #98 (review F1): a synchronous prompt() throw never reaches the
     // settle handlers — finalize the run entry so no zombie 'running' entry
-    // survives (findRunById would otherwise resolve and retry a run that
+    // survives (findSpawnRunById would otherwise resolve and retry a run that
     // never started).
     finalizeRunEntry('failed', sanitizeErrorMessage((err as Error).message, effectiveCwd));
     throw err;
@@ -895,7 +974,8 @@ export async function spawnBackgroundSession(
       //   1. stopAgent pre-set status to 'stopped' before calling abort();
       //   2. the last assistant message carries stopReason "aborted".
       const lastAssistant = [...(session.messages ?? [])].reverse().find(m => m.role === 'assistant');
-      const aborted = agent.status === 'stopped' || lastAssistant?.stopReason === 'aborted';
+      const terminalStopReason = lastAssistant?.stopReason;
+      const aborted = agent.status === 'stopped' || terminalStopReason === 'aborted';
       if (aborted) {
         // Session was aborted — mark stopped. If stopAgent already flipped the
         // status (pre-set 'stopped' + completedAt + event + transcript), only
@@ -931,13 +1011,70 @@ export async function spawnBackgroundSession(
         // (stop_subagent) sets no error, so fall back to the honest user-abort
         // stamp (→ 'aborted') instead of the old ambiguous 'Aborted or timed out'.
         recordSessionUsage();
-        finalizeRunEntry('failed', agent.error ?? SUBAGENT_ABORTED_MESSAGE);
+        finalizeRunEntry('failed', agent.error ?? SUBAGENT_ABORTED_MESSAGE, {
+          stopReason:
+            terminalStopReason && terminalStopReason !== 'stop'
+              ? terminalStopReason
+              : 'aborted',
+        });
         // Issue #31: capture the final output while the session is still
         // live, then release the ref on the terminal path (memory retention;
         // the poller treats a nulled ref on a terminal agent as expected).
         captureAndReleaseSession();
         return;
       }
+      // Issue #179 (D1/D2): prompt() RESOLVED — but a resolved prompt is NOT
+      // proof of success. The SDK's runWithLifecycle catches a mid-run provider
+      // death internally and resolves with an assistant message carrying
+      // stopReason "error"; the completion branch below would record it as a
+      // false success (exitCode 0, no category). Classify the terminal outcome
+      // from the last assistant message + the session error, reusing
+      // classifyError for the provider-error case.
+      const providerErrorMessage =
+        lastAssistant?.errorMessage ?? session.state?.errorMessage;
+      const outcome = classifyTerminalOutcome(terminalStopReason, providerErrorMessage);
+
+      if (outcome.status === 'failed') {
+        // Mid-run provider death / truncation / incomplete turn.
+        agent.status = 'failed';
+        agent.completedAt = Date.now();
+        const sanitizedError = sanitizeErrorMessage(
+          providerErrorMessage ?? defaultTerminalMessage(terminalStopReason),
+          effectiveCwd,
+        );
+        agent.error = sanitizedError;
+        const gitInfo = cleanupWorkBranch();
+        agent.result = {
+          ...(agent.result ?? {}),
+          exitCode: 1,
+          messages: agent.result?.messages ?? [],
+          stderr: agent.result?.stderr ?? '',
+          usage: agent.result?.usage ?? EMPTY_USAGE,
+          stopReason: terminalStopReason,
+          errorMessage: sanitizedError,
+          errorCategory: outcome.errorCategory,
+          ...(gitInfo.gitBranch
+            ? { gitBranch: gitInfo.gitBranch, gitDiff: gitInfo.gitDiff }
+            : {}),
+        } as SubagentResult;
+        // Issue #31: capture the final output while the session is still live.
+        // Issue #179 (D4): surface the failure as the HEADLINE — the extracted
+        // prose may come from an earlier turn, so it must not be presented as an
+        // unqualified success narrative.
+        captureAndReleaseSession(sanitizedError);
+        // Issue #122: fold the real usage (turns/tokens) the run burned.
+        recordSessionUsage();
+        agents.set(id, agent);
+        persistAgent(agent);
+        finalizeRunEntry('failed', sanitizedError, {
+          stopReason: terminalStopReason,
+          errorCategory: outcome.errorCategory,
+        });
+        transcript.completeTranscript(id, 'failed');
+        eventBus.emit(eventBus.createEvent('subagent:failed', id, { error: sanitizedError }));
+        return;
+      }
+
       // Session completed
       agent.status = 'completed';
       agent.completedAt = Date.now();
@@ -951,6 +1088,7 @@ export async function spawnBackgroundSession(
           messages: [],
           stderr: '',
           usage: agent.result?.usage ?? EMPTY_USAGE,
+          stopReason: terminalStopReason ?? 'stop',
           gitBranch: gitInfo.gitBranch,
           gitDiff: gitInfo.gitDiff,
         } as SubagentResult;
@@ -965,7 +1103,7 @@ export async function spawnBackgroundSession(
       agents.set(id, agent);
       persistAgent(agent);
       // Issue #98: mirror the agent-record flip in the session run entry.
-      finalizeRunEntry('done');
+      finalizeRunEntry('done', undefined, { stopReason: terminalStopReason ?? 'stop' });
       transcript.completeTranscript(id, 'completed');
       eventBus.emit(eventBus.createEvent('subagent:completed', id, {}));
     } catch (err) {
@@ -1009,7 +1147,9 @@ export async function spawnBackgroundSession(
         // agent.error ('Timed out...' → 'timeout'); a user cancel has no error
         // and stamps 'Subagent aborted by user' (→ 'aborted').
         recordSessionUsage();
-        finalizeRunEntry('failed', agent.error ?? SUBAGENT_ABORTED_MESSAGE);
+        finalizeRunEntry('failed', agent.error ?? SUBAGENT_ABORTED_MESSAGE, {
+          stopReason: 'aborted',
+        });
         // Issue #31: the stopped path is terminal too — capture + release.
         captureAndReleaseSession();
         transcript.completeTranscript(id, 'stopped');
@@ -1022,29 +1162,36 @@ export async function spawnBackgroundSession(
       // result errorMessage, and the subagent:failed event (DRY, PR #63 review).
       const sanitizedError = sanitizeErrorMessage(err.message, effectiveCwd);
       agent.error = sanitizedError;
-      if (gitInfo.gitBranch) {
-        agent.result = {
-          ...(agent.result ?? {}),
-          exitCode: 1,
-          messages: [],
-          stderr: '',
-          usage: agent.result?.usage ?? EMPTY_USAGE,
-          errorMessage: sanitizedError,
-          gitBranch: gitInfo.gitBranch,
-          gitDiff: gitInfo.gitDiff,
-        } as SubagentResult;
-      }
+      // Issue #179: record the failure on the result UNCONDITIONALLY (not only
+      // on the git-diff path) so a failed run never persists exitCode 0.
+      agent.result = {
+        ...(agent.result ?? {}),
+        exitCode: 1,
+        messages: agent.result?.messages ?? [],
+        stderr: agent.result?.stderr ?? '',
+        usage: agent.result?.usage ?? EMPTY_USAGE,
+        // Issue #179 (C1 fix): a genuine preflight/run failure always carries
+        // the failure reason — never leave the result with an undefined
+        // stopReason that downstream display/aggregate paths read as success.
+        stopReason: 'error',
+        errorMessage: sanitizedError,
+        ...(gitInfo.gitBranch
+          ? { gitBranch: gitInfo.gitBranch, gitDiff: gitInfo.gitDiff }
+          : {}),
+      } as SubagentResult;
       // Issue #31: capture the final output while the session is still live,
       // then release the ref before the branch's persist — the persisted
       // record is consistent and the live session graph is freed.
-      captureAndReleaseSession();
+      // Issue #179 (D4): lead with the failure reason (the prose may be from an
+      // earlier turn).
+      captureAndReleaseSession(sanitizedError);
       // Issue #122: fold any assistant turns the preflight/run did produce —
       // usually none (auth/model rejection) → honest zeros, never a crash.
       recordSessionUsage();
       agents.set(id, agent);
       persistAgent(agent);
       // Issue #98: mirror the agent-record flip in the session run entry.
-      finalizeRunEntry('failed', sanitizedError);
+      finalizeRunEntry('failed', sanitizedError, { stopReason: 'error' });
       transcript.completeTranscript(id, 'failed');
       eventBus.emit(eventBus.createEvent('subagent:failed', id, { error: sanitizedError }));
     } catch (err) {

package/src/state.ts

@@ -62,6 +62,30 @@ const POLLER_TICK_MS = 2000;
  */
 export const STALE_FINALIZE_GRACE_MS = POLLER_TICK_MS + 1000;
 
+// ---------------------------------------------------------------------------
+// Run-entry lookup contract (issue #185)
+// ---------------------------------------------------------------------------
+
+/**
+ * Terminal-preferring run-entry lookup — the ONE implementation of the
+ * preference rule.
+ *
+ * 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.
+ */
+export function resolveTerminalRunEntry(
+	entries: SubagentRun[],
+	id: string,
+): 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];
+}
+
 // ---------------------------------------------------------------------------
 // SessionState — session-bound mutable state
 // ---------------------------------------------------------------------------
@@ -282,10 +306,26 @@ export class SessionState {
 		return cleanupRuns(runs, this.config.maxHistoryEntries);
 	}
 
-	findRunById(ctx: ExtensionContext, id: string): SubagentRun | undefined {
+	/**
+	 * Spawn-oriented lookup: the FIRST entry matching `id`. Runs append the
+	 * spawn entry (status "running", carrying `originalParams`) before the
+	 * final entry, so retry resolution — which reads `originalParams` via
+	 * resolveRetryParams — must use THIS lookup, not the terminal-preferring
+	 * one.
+	 */
+	findSpawnRunById(ctx: ExtensionContext, id: string): SubagentRun | undefined {
 		return this.getRunEntries(ctx).find((r) => r.id === id);
 	}
 
+	/**
+	 * Terminal-preferring lookup: the finalized entry (status !== "running") when
+	 * present, else the first match. Use for fields stamped at settle — `status`,
+	 * `fullOutput`, `cost`, `durationMs`, `errorCategory`.
+	 */
+	findTerminalRunById(ctx: ExtensionContext, id: string): SubagentRun | undefined {
+		return resolveTerminalRunEntry(this.getRunEntries(ctx), id);
+	}
+
 	// -------------------------------------------------------------------
 	// Live subagent tracking
 	// -------------------------------------------------------------------
@@ -569,7 +609,7 @@ export function sweepStaleLiveSubagents(
 		} else {
 			// No agent record — foreground run or a removed record. A foreground
 			// run is live only while its run entry says 'running'.
-			const runStatus = state.getRunEntries(session.ctx).find((r) => r.id === id)?.status;
+			const runStatus = state.findTerminalRunById(session.ctx, id)?.status;
 			if (runStatus !== "running" && state.finalizeStaleLiveSubagent(id)) {
 				finalized++;
 			}

package/src/templates.ts

@@ -407,7 +407,7 @@ export function validateTemplatePresetRefs(
 			dangling++;
 			log?.warn(
 				`Template "${template.name}" references preset "${template.preset}" which does not exist ` +
-				"— delegation will run preset-less with auto-route suppressed (issue #81)",
+				"— delegation will run preset-less with auto-route suppressed",
 				{ template: template.name, preset: template.preset },
 			);
 		}