brl-subagent 2.3.7 → 2.3.8

package/src/notify-completion.ts

@@ -26,6 +26,7 @@ import type {
 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";
@@ -80,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);
 }
 
 /**

package/src/session-manager.ts

@@ -2,7 +2,7 @@ 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, ErrorCategory } from './types';
-import { EMPTY_USAGE, CUSTOM_ENTRY_TYPES, classifyError, classifyTerminalOutcome, isSubagentError, isProviderError, SUBAGENT_ABORTED_MESSAGE } 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';
@@ -274,23 +274,6 @@ function defaultTerminalMessage(stopReason: string | undefined): string {
   }
 }
 
-/**
- * Issue #179 (C1 fix): a failed run entry/result must carry a terminal reason
- * that AGREES with its status — never undefined, never "stop". Any reason the
- * classifier already treats as a failure (error / length / toolUse / deferred
- * / pending / aborted) is coherent and kept; a missing or success reason is
- * coerced to the honest failure reason derived from the classified category.
- */
-function coherentFailureReason(
-  stopReason: string | undefined,
-  errorCategory: ErrorCategory | undefined,
-): string {
-  if (stopReason && classifyTerminalOutcome(stopReason).status !== 'completed') {
-    return stopReason;
-  }
-  return errorCategory === 'aborted' ? 'aborted' : 'error';
-}
-
 /**
  * Extract the final assistant text from a session's messages.
  * Falls back to the LAST assistant message with non-empty text content — the
@@ -558,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
@@ -610,13 +593,15 @@ export async function spawnBackgroundSession(
               })
             : 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(
-            terminal?.stopReason ?? agent.result?.stopReason,
-            errorCategory,
-          )
-        : terminal?.stopReason ?? agent.result?.stopReason;
+        ? coherentFailureReason(rawStopReason, errorCategory)
+        : rawStopReason;
     const entry: SubagentRun = {
       ...run,
       status,
@@ -628,7 +613,7 @@ export async function spawnBackgroundSession(
       // 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(stopReason),
+      finalTurnError: isProviderError(rawStopReason),
       errorMessage: error,
       finishedAt: new Date().toISOString(),
       durationMs: Date.now() - startedAtMs,
@@ -944,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;

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/tui.ts

@@ -1710,7 +1710,7 @@ export async function showAgentDetail(
 						// path persists it), mirroring the background path's
 						// `agent?.finalOutput` fallback.
 						const runOutput =
-							cachedTail || state.findRunById(ctx, agentId)?.fullOutput || "";
+							cachedTail || state.findTerminalRunById(ctx, agentId)?.fullOutput || "";
 						const tailLines = runOutput.split("\n").filter(Boolean).slice(-10);
 						if (tailLines.length > 0) {
 							container.addChild(new Spacer(1));

package/src/types.ts

@@ -808,6 +808,27 @@ export function classifyTerminalOutcome(
 	}
 }
 
+/**
+ * Issue #179 (C1 fix): a failed run entry/result must carry a terminal reason
+ * that AGREES with its status — never undefined, never "stop". Any reason the
+ * classifier already treats as a failure (error / length / toolUse / deferred
+ * / pending / aborted) is coherent and kept; a missing or success reason is
+ * coerced to the honest failure reason derived from the classified category.
+ *
+ * Issue #187: lives here (not session-manager) so BOTH the background
+ * finalize (session-manager.ts) and the foreground finalize (history.ts) apply
+ * the SAME rule through one implementation instead of two copies.
+ */
+export function coherentFailureReason(
+	stopReason: string | undefined,
+	errorCategory: ErrorCategory | undefined,
+): string {
+	if (stopReason && classifyTerminalOutcome(stopReason).status !== "completed") {
+		return stopReason;
+	}
+	return errorCategory === "aborted" ? "aborted" : "error";
+}
+
 export function formatModel(m: { provider: string; id: string } | undefined): string {
 	return m ? `${m.provider}/${m.id}` : "Not set (will use main agent\u2019s model)";
 }