brl-subagent 2.3.7 → 2.3.9

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

@@ -23,7 +23,7 @@ import type {
 } from "./types";
 import { resolveThinkingLevel } from "./types";
 import { getAllPresets, getPreset } from "./presets";
-import { autoRoutePreset } from "./router";
+import { classifyTask } from "./router";
 import { normalizeTimeout } from "./validate";
 import type { SessionState } from "./state";
 import type { Logger } from "./logging";
@@ -49,7 +49,7 @@ export const KNOWN_DELEGATE_KEYS = new Set([
 	"outputFile", "label", "model", "timeout", "cwd", "tools",
 	"excludeTools", "noBuiltinTools", "preset", "template", "params",
 	"retryRunId", "gitMode", "retryOnTimeout", "approvalMode", "background",
-	"priority", "chain", "tasks", "graph",
+	"priority", "chain", "tasks", "graph", "force",
 ] as const);
 
 /**
@@ -76,6 +76,11 @@ export function findUnknownParams(
  * degrade retries of that path.
  * NOTE: the schema's `params` (template slots) key is intentionally NOT
  * snapshotted — it is a template-resolution input, not a retry override.
+ * The execution-shape keys (background, gitMode, approvalMode, force) ARE
+ * snapshotted: omitting them is the known failure mode of this design, since
+ * resolveRetryParams rebuilds a fresh literal and a key missing here is both
+ * unrestored AND discarded when passed explicitly on a retry call. Records
+ * written before this change simply lack the keys (additive, undefined-safe).
  */
 export function snapshotOriginalParams(params: {
 	systemPrompt?: string;
@@ -90,6 +95,10 @@ export function snapshotOriginalParams(params: {
 	excludeTools?: string[];
 	noBuiltinTools?: boolean;
 	preset?: string;
+	background?: boolean;
+	gitMode?: string;
+	approvalMode?: string;
+	force?: boolean;
 }): Record<string, unknown> {
 	return {
 		systemPrompt: params.systemPrompt,
@@ -104,6 +113,10 @@ export function snapshotOriginalParams(params: {
 		excludeTools: params.excludeTools,
 		noBuiltinTools: params.noBuiltinTools,
 		preset: params.preset,
+		background: params.background,
+		gitMode: params.gitMode,
+		approvalMode: params.approvalMode,
+		force: params.force,
 	};
 }
 
@@ -124,6 +137,12 @@ export function resolveSubagentParams(
 		gitMode?: string;
 		approvalMode?: string;
 		template?: string;
+		/**
+		 * Capability-block override: carried here so the validation call sites
+		 * (which receive the resolved params) can forward it to validatePreTask.
+		 * Resolution itself ignores it.
+		 */
+		force?: boolean;
 	},
 	state: SessionState,
 	ctx: ExtensionContext,
@@ -133,6 +152,9 @@ export function resolveSubagentParams(
 	resolvedApprovalMode: ApprovalMode;
 	resolvedPreset?: SubagentPreset;
 	autoRoutedPreset?: SubagentPreset; // set only when autoRoutePreset chose it
+	/** Set only when auto-route chose the preset: the keyword that matched —
+	 * the evidence the dispatch result surfaces (auto-route transparency). */
+	autoRouteKeyword?: string;
 } {
 	// E2: Auto-route to best preset only when the conductor expressed NO
 	// explicit preference — an explicit preset, template, or tool
@@ -140,17 +162,19 @@ export function resolveSubagentParams(
 	// that must win over keyword-based routing (issue #57).
 	let resolvedPreset = params.preset;
 	let wasAutoRouted = false;
+	let routeKeyword: string | undefined;
 	const hasExplicitToolPreference =
 		params.tools !== undefined ||
 		params.excludeTools !== undefined ||
 		params.noBuiltinTools !== undefined;
 	if (!resolvedPreset && !params.template && !hasExplicitToolPreference) {
 		const allPresets = getAllPresets(state.builtinPresets, state.customPresets);
-		const suggested = autoRoutePreset(params.task, allPresets);
-		if (suggested) {
-			resolvedPreset = suggested;
+		const matched = classifyTask(params.task, allPresets);
+		if (matched) {
+			resolvedPreset = matched.preset;
 			wasAutoRouted = true;
-			log.info("Auto-routed task to preset", { preset: suggested });
+			routeKeyword = matched.keyword;
+			log.info("Auto-routed task to preset", { preset: matched.preset, keyword: matched.keyword });
 		}
 	}
 
@@ -221,5 +245,6 @@ export function resolveSubagentParams(
 		resolvedApprovalMode,
 		resolvedPreset: preset,
 		autoRoutedPreset,
+		autoRouteKeyword: autoRoutedPreset ? routeKeyword : undefined,
 	};
 }

package/src/prelude.ts

@@ -0,0 +1,206 @@
+/**
+ * Shared guard/validation prelude for delegation modes (issue #201).
+ *
+ * delegate_task's mode handlers each open with the same prelude shape:
+ *
+ *   1. session cost gate — perTaskEstimate fallback ($0.05) →
+ *      checkCostLimit → the verbatim "Cannot delegate: session cost limit
+ *      reached …" rejection;
+ *   2. approvalMode 'always' rejection (background paths only) — the verbatim
+ *      "Cannot spawn background agent with approvalMode 'always' …";
+ *   3. cwd → outputFile → H1 pre-task validation — the same "Invalid cwd:" /
+ *      "Invalid outputFile:" / joined-errors messages, optionally
+ *      unit-prefixed (`Task 2 ("two"): …`) for per-unit loops.
+ *
+ * Each helper returns the rejection ToolResult when the gate trips and
+ * `undefined` when it passes, so call sites keep their original gate order:
+ *
+ *     const err = gateSessionCost({ … });
+ *     if (err) return err;
+ *
+ * Exception: runPreTaskValidation returns a { error?, warnings } outcome —
+ * `error` follows the same `if (outcome.error) return outcome.error` shape,
+ * and `warnings` must be surfaced in the returned tool result:
+ *
+ *     const pre = runPreTaskValidation({ … });
+ *     if (pre.error) return pre.error;
+ *
+ * Messages are byte-identical to the pre-extraction copies (the suites pin
+ * them); the parameters absorb only the real differences between sites — the
+ * cost-gate log label and unit count, and the H1 log label / unit prefix /
+ * extra log fields.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ApprovalMode, ToolResult } from "./types";
+import type { SessionState } from "./state";
+import type { Logger } from "./logging";
+import { validateCwd, validateOutputFile } from "./sanitize";
+import { validatePreTask, type ValidateConfig } from "./validate";
+
+/** The standard rejection result shape shared by these gates. */
+function rejection(text: string): ToolResult<undefined> {
+	return {
+		content: [{ type: "text" as const, text }],
+		details: undefined,
+		isError: true,
+	};
+}
+
+// ── Gate 1: session cost ────────────────────────────────────────────────
+
+/**
+ * Session cost gate (R5 / W6): falls back to the $0.05 per-unit estimate,
+ * checks the whole dispatch (units × estimate) against the session limit, and
+ * returns the verbatim rejection result when it would be exceeded.
+ *
+ * This module holds the codebase's SINGLE `checkCostLimit(perTaskEstimate * …)`
+ * site — the duplication that shape caused a mutation-target-drift incident
+ * (issue #201).
+ */
+export function gateSessionCost(input: {
+	state: SessionState;
+	ctx: ExtensionContext;
+	log: Logger;
+	/** Number of units this dispatch would spawn (1 for single-task modes). */
+	units: number;
+	/** e.g. "Parallel delegation" → log line "Parallel delegation rejected: session cost limit reached". */
+	label: string;
+}): ToolResult<undefined> | undefined {
+	const { state, ctx, log, units, label } = input;
+	const perTaskEstimate =
+		state.config.perTaskCostEstimate > 0
+			? state.config.perTaskCostEstimate
+			: 0.05;
+	if (state.checkCostLimit(perTaskEstimate * units, ctx)) {
+		const currentTotal = state.getSessionTotalCost(ctx);
+		const limit = state.config.sessionCostLimit;
+		log.warn(`${label}: session cost limit reached`, {
+			currentTotal,
+			estimatedCost: perTaskEstimate * units,
+			limit,
+		});
+		return rejection(
+			`Cannot delegate: session cost limit reached ` +
+			`($${currentTotal.toFixed(4)} spent of $${limit.toFixed(2)} limit). ` +
+			`Increase the limit via /brl-subagent costlimit or set to 0 for unlimited.`,
+		);
+	}
+	return undefined;
+}
+
+// ── Gate 2: approvalMode 'always' in background ─────────────────────────
+
+/**
+ * Background paths (single spawn and fan-out) reject approvalMode 'always'
+ * before spawning: there is no interactive dialog to approve the diff, so
+ * 'always' cannot work — reject loudly instead of running unattended with
+ * write access (W5, issue #28). Verbatim message, pinned by the suites.
+ */
+export function rejectApprovalAlwaysInBackground(
+	approvalMode: ApprovalMode,
+): ToolResult<undefined> | undefined {
+	if (approvalMode !== "always") return undefined;
+	return rejection(
+		`Cannot spawn background agent with approvalMode 'always': background agents run unattended ` +
+		`and cannot present the approval dialog. Use approvalMode 'auto' (default) or 'writes'.`,
+	);
+}
+
+// ── Gate 3a: cwd (+ outputFile) target validation ───────────────────────
+
+export type DelegationTargetsResult =
+	| { ok: true; cwd: string; outputFile: string | undefined }
+	| { ok: false; error: ToolResult<undefined> };
+
+/**
+ * Validate the dispatch's target cwd, then — when `outputFile` is given — the
+ * outputFile path (F1), returning both resolved values on success. `prefix`
+ * (a per-unit label like `Task 2 ("two")`) is prepended as `${prefix}: ` to
+ * the rejection messages; omit it for the unprefixed single-unit messages.
+ *
+ * Note: the foreground parallel mode historically validates only the cwd
+ * here (no outputFile step) — it simply passes no outputFile.
+ */
+export function validateDelegationTargets(input: {
+	ctx: ExtensionContext;
+	effectiveCwd: string;
+	/** Raw outputFile to path-validate; the step is skipped when omitted. */
+	outputFile?: string;
+	/** Unit prefix for the rejection messages, e.g. `Task 2 ("two")`. */
+	prefix?: string;
+}): DelegationTargetsResult {
+	const prefix = input.prefix ? `${input.prefix}: ` : "";
+
+	const cwdResult = validateCwd(input.effectiveCwd, input.ctx.cwd);
+	if (!cwdResult.ok) {
+		return { ok: false, error: rejection(`${prefix}Invalid cwd: ${cwdResult.error}`) };
+	}
+
+	let outputFile: string | undefined;
+	if (input.outputFile) {
+		const ofResult = validateOutputFile(input.outputFile, cwdResult.value);
+		if (!ofResult.ok) {
+			return { ok: false, error: rejection(`${prefix}Invalid outputFile: ${ofResult.error}`) };
+		}
+		outputFile = ofResult.value;
+	}
+
+	return { ok: true, cwd: cwdResult.value, outputFile };
+}
+
+// ── Gate 3b: H1 pre-task validation ─────────────────────────────────────
+
+/** Outcome of one pre-task validation: the rejection (hard failure) and/or
+ * the warnings the caller must surface in the tool result. */
+export interface PreTaskValidationOutcome {
+	/** Rejection result when validation failed (hard errors); undefined when it passed. */
+	error?: ToolResult<undefined>;
+	/** Validation warnings — surfaced in the returned tool result, not just logged. */
+	warnings: string[];
+}
+
+/**
+ * Render validation warnings for a tool result: one labelled, bulleted
+ * block. Empty input renders the empty string so results stay
+ * byte-identical when there is nothing to say.
+ */
+export function formatValidationWarnings(warnings: string[]): string {
+	if (warnings.length === 0) return "";
+	return `\n\n[pre-task validation warnings]\n` + warnings.map((w) => `- ${w}`).join("\n");
+}
+
+/**
+ * Run validatePreTask (H1) with the site's exact input, warn on warnings,
+ * and return the rejection outcome (joined errors) on hard failure.
+ * `label` names the site in the warn logs ("Parallel pre-task validation
+ * warnings" / "Background fan-out …" / "Background …"); `prefix` is
+ * prepended as `${prefix}: ` to the hard-failure message; `logContext` adds
+ * site fields to both warn entries (the fan-out adds the task index).
+ * The returned warnings are for RESULT surfacing — the log.warn calls stay
+ * regardless (a warning must reach both the log and the conductor).
+ */
+export function runPreTaskValidation(input: {
+	log: Logger;
+	preTask: ValidateConfig;
+	label: string;
+	/** Unit prefix for the rejection message, e.g. `Task 2 ("two")`. */
+	prefix?: string;
+	/** Extra structured fields merged into the warn entries. */
+	logContext?: Record<string, unknown>;
+}): PreTaskValidationOutcome {
+	const { log, preTask, label, prefix, logContext } = input;
+	const validation = validatePreTask(preTask);
+	if (validation.warnings.length > 0) {
+		log.warn(`${label} pre-task validation warnings`, { ...logContext, warnings: validation.warnings });
+	}
+	if (!validation.valid) {
+		const errText = validation.errors.join("; ");
+		log.warn(`${label} pre-task validation failed`, { ...logContext, errors: validation.errors });
+		return {
+			error: rejection(prefix ? `${prefix}: ${errText}` : errText),
+			warnings: validation.warnings,
+		};
+	}
+	return { warnings: validation.warnings };
+}

package/src/prompt.ts

@@ -52,7 +52,7 @@ export const SUBAGENT_INSTRUCTIONS =
  * - runner.ts (foreground subprocess: `-p` argument)
  * - session-manager.ts (background session: `session.prompt`)
  *
- * Deliberately applied AFTER {previous}/{otherId} substitution so substituted
+ * Deliberately applied AFTER {previous}/{<nodeId>} substitution so substituted
  * output (which may itself contain untrusted text) lands inside the fence.
  *
  * FIDELITY TRADEOFF (accepted, documented per PR #46 review M2): embedded

package/src/router.ts

@@ -105,15 +105,25 @@ function escapeRegExp(s: string): string {
 // Router
 // ---------------------------------------------------------------------------
 
+/** One auto-route decision: the selected preset AND the keyword that
+ * matched — the evidence the dispatch result must show (transparency). */
+export interface AutoRouteDecision {
+	/** The preset name selected. */
+	preset: string;
+	/** The classification keyword whose match selected the preset. */
+	keyword: string;
+}
+
 /**
- * Auto-classify a task description to the best preset personality.
+ * Auto-classify a task description to the best preset personality, returning
+ * the preset AND the matched keyword (evidence for the dispatch result).
  * Uses case-insensitive keyword matching, checked in priority order.
- * Returns the first matching preset name, or undefined if no match.
+ * Returns the first match, or undefined if no rule matches.
  */
-export function autoRoutePreset(
+export function classifyTask(
 	task: string,
 	presets: SubagentPreset[],
-): string | undefined {
+): AutoRouteDecision | undefined {
 	if (!task || task.trim().length === 0) return undefined;
 
 	const lower = task.toLowerCase();
@@ -124,10 +134,21 @@ export function autoRoutePreset(
 
 		for (const keyword of rule.keywords) {
 			if (keywordMatches(lower, keyword)) {
-				return rule.preset;
+				return { preset: rule.preset, keyword };
 			}
 		}
 	}
 
 	return undefined;
 }
+
+/**
+ * Auto-classify a task description to the best preset personality.
+ * Thin wrapper over classifyTask — preset name only, no evidence.
+ */
+export function autoRoutePreset(
+	task: string,
+	presets: SubagentPreset[],
+): string | undefined {
+	return classifyTask(task, presets)?.preset;
+}

package/src/runner.ts

@@ -245,7 +245,13 @@ function emitSubagentUpdate(
 				text: getFinalOutputFn(result.messages) || "(running...)",
 			},
 		],
-		details: { ...result },
+		// Issue #206: this is a STREAMING partial, not a verdict —
+		// isSubagentError is a settled-result predicate (a mid-run stopReason
+		// such as "toolUse" is not an error until the run actually ends), so
+		// stamping the unsettled sentinel (exitCode: -1) keeps the renderer on
+		// its running branch until the real result lands. The accumulator
+		// (`result` itself) is untouched — its exitCode stays the real code.
+		details: { ...result, exitCode: -1 },
 	});
 }
 

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';
@@ -10,7 +10,7 @@ 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, commitAll, captureWorkingDiff } from './git';
+import { getCurrentBranch, createWorkBranch, captureDiff, switchToBranch, deleteBranch, hasUncommittedChanges, getRepoRoot, commitAll, captureWorkingDiff } from './git';
 
 const log = createLogger('brl-subagent');
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
@@ -20,7 +20,10 @@ import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-a
 var spawnQueue: Promise<void> = Promise.resolve();
 
 // C2: per-repo locks serializing the FULL gitMode=branch lifecycle (setup →
-// settle → teardown). Keyed by cwd because different repos don't conflict.
+// settle → teardown). Keyed by the resolved repository root, falling back to
+// the cwd path for directories that are not inside a repository — different
+// repos don't conflict, but different directories of one repo DO share a
+// working tree and must serialize (issue #224).
 const gitBranchLocks = new Map<string, Promise<void>>();
 
 /**
@@ -274,23 +277,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 +544,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 +596,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 +616,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,
@@ -739,16 +727,18 @@ export async function spawnBackgroundSession(
     // would read the first's work branch as its base and both teardowns would
     // fight over the shared working tree (stranding the repo on an orphan
     // branch). The lock is released in cleanupWorkBranch (or on setup throw).
-    const prev = gitBranchLocks.get(gitCwd) ?? Promise.resolve();
+    // Key: resolved repository root, cwd fallback for non-repo paths (#224).
+    const lockKey = getRepoRoot(gitCwd) ?? gitCwd;
+    const prev = gitBranchLocks.get(lockKey) ?? Promise.resolve();
     let release!: () => void;
     const gate = new Promise<void>(r => { release = r; });
     const entry = prev.then(() => gate);
-    gitBranchLocks.set(gitCwd, entry);
+    gitBranchLocks.set(lockKey, entry);
     await prev;
     releaseGitLock = () => {
       // Delete the map entry ONLY if we are still the head of the chain — a
       // queued spawn behind us replaced the entry with its own.
-      if (gitBranchLocks.get(gitCwd) === entry) gitBranchLocks.delete(gitCwd);
+      if (gitBranchLocks.get(lockKey) === entry) gitBranchLocks.delete(lockKey);
       release();
     };
 
@@ -944,7 +934,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));