brl-subagent 2.3.6 → 2.3.7

package/AGENT.md

@@ -2,6 +2,12 @@
 
 > The `delegate_task` prompt guidelines are a derived summary of this file; if they disagree, this file wins.
 
+> **Naming:** deliberately `AGENT.md`, **not** `AGENTS.md`. This is *not* a pi
+> context file — it is read on demand via the extension's `delegate_task`
+> guidance, not auto-loaded into the system prompt. Renaming it would change
+> nothing for users (a package directory is not in pi's context-file lookup
+> chain) while adding its full contents to every session run inside this repo.
+
 This file is the authoritative reference for how the brl-subagent extension behaves
 and how you (the conductor) should judge a delegation. Read it when planning
 delegation-heavy work.

package/README.md

@@ -2,7 +2,7 @@
 
 > Multi-agent orchestration for [pi](https://github.com/earendil-works/pi) — chain, parallel, and dependency-graph delegation to isolated subagents with per-step model routing, preset-driven tool scoping, thinking-level control, and background execution with live monitoring, real abort, and per-agent timeouts.
 
-**Version:** 2.3.6 · **Author:** Azmeen Afandi / [Beeroo Labs](https://beeroolabs.com) · **License:** MIT
+**Version:** 2.3.7 · **Author:** Azmeen Afandi / [Beeroo Labs](https://beeroolabs.com) · **License:** MIT
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brl-subagent",
-  "version": "2.3.6",
+  "version": "2.3.7",
   "description": "Subagent extension for pi with configurable model and thinking mode via selection UI",
   "keywords": [
     "pi-package"
@@ -35,10 +35,10 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "^0.85.1",
-    "@earendil-works/pi-ai": "^0.85.1",
-    "@earendil-works/pi-coding-agent": "^0.85.1",
-    "@earendil-works/pi-tui": "^0.85.1",
+    "@earendil-works/pi-agent-core": "^0.86.0",
+    "@earendil-works/pi-ai": "^0.86.0",
+    "@earendil-works/pi-coding-agent": "^0.86.0",
+    "@earendil-works/pi-tui": "^0.86.0",
     "jiti": "^2.7.0",
     "typebox": "^1.3.25",
     "typescript": "^5.9.3",

package/src/index.ts

@@ -39,6 +39,7 @@ import {
 	EMPTY_USAGE,
 	getFinalOutput,
 	isSubagentError,
+	countSubagentOutcomes,
 	classifyError,
 	MAX_CHAIN_STEPS,
 	MAX_PARALLEL_TASKS,
@@ -102,7 +103,7 @@ import {
 	renderDelegateCall,
 	renderDelegateResult,
 } from "./tui";
-import { createLogger, type Logger } from "./logging";
+import { createLogger, setLogCwd, type Logger } from "./logging";
 import { Intercom } from "./messaging";
 import * as eventBus from "./event-bus";
 import {
@@ -110,7 +111,6 @@ import {
 	resolveDelivery,
 	sendCompletionNotification,
 	markTerminalSeen,
-	normalizeCompletionStatus,
 	resolveRunEntry,
 } from "./notify-completion";
 
@@ -796,7 +796,7 @@ export default function (pi: ExtensionAPI) {
 				previousOutput = getFinalOutput(result.messages);
 			}
 
-			chainSuccess = chainResults.every((r) => r.exitCode === 0);
+			chainSuccess = countSubagentOutcomes(chainResults).failed === 0;
 
 			// Compute aggregated totals
 			const totalInput = chainResults.reduce(
@@ -1203,11 +1203,8 @@ export default function (pi: ExtensionAPI) {
 			}
 
 			// Emit progress update
-			const completed = results.filter(Boolean).length;
-			const succeeded = results.filter(
-				(r) => r && r.exitCode === 0,
-			).length;
-			const failed = completed - succeeded;
+			const { succeeded, failed } = countSubagentOutcomes(results);
+			const completed = succeeded + failed;
 
 			const partialDetails: ParallelDetails = {
 				mode: "parallel",
@@ -1306,8 +1303,7 @@ export default function (pi: ExtensionAPI) {
 			(s, r) => s + r.usage.turns,
 			0,
 		);
-		const succeeded = finalResults.filter((r) => r.exitCode === 0).length;
-		const failed = finalResults.length - succeeded;
+		const { succeeded, failed } = countSubagentOutcomes(finalResults);
 
 		const parallelDetails: ParallelDetails = {
 			mode: "parallel",
@@ -1810,9 +1806,7 @@ export default function (pi: ExtensionAPI) {
 			const totalCost = allResults.reduce((s, r) => s + r.usage.cost, 0);
 			const totalTurns = allResults.reduce((s, r) => s + r.usage.turns, 0);
 
-			chainSuccess = allResults.every(
-				(r) => r.exitCode === 0 && r.stopReason !== "error" && r.stopReason !== "aborted",
-			);
+			chainSuccess = countSubagentOutcomes(allResults).failed === 0;
 
 			const graphDetails: GraphDetails = {
 				mode: "graph",
@@ -2320,48 +2314,10 @@ export default function (pi: ExtensionAPI) {
 				}, { deliverAs: "followUp" });
 			}
 
-			// F1: Sanitize task input — skip for chain/parallel modes
-			const hasChain = params.chain && params.chain.length > 0;
-			const hasParallel = params.tasks && params.tasks.length > 0;
-			const hasGraph = params.graph && params.graph.length > 0;
-			if (!hasChain && !hasParallel && !hasGraph) {
-				// task is optional per the schema; single mode requires it. When absent,
-				// feed "" to the sanitizer — same rejection path ("Task must not be
-				// empty.") as when task was a required field.
-				const taskResult = sanitizeTask(params.task ?? "");
-				if (!taskResult.ok) {
-					log.warn("Task rejected by sanitizer", { error: taskResult.error });
-					return {
-						content: [{ type: "text" as const, text: `Invalid task: ${taskResult.error}` }],
-						details: undefined,
-						isError: true,
-					};
-				}
-				params.task = taskResult.value;
-			}
-
-			// Handle retryRunId
-			if (params.retryRunId) {
-				const runEntry = state.findRunById(ctx, params.retryRunId);
-				if (runEntry) {
-					params = resolveRetryParams(params, runEntry);
-				} else {
-					// Issue #98: a silent no-op here made retries of background runs
-					// (which previously never wrote run entries) start as FRESH runs
-					// with no signal to the caller. Fail loudly instead.
-					log.warn("Retry run ID not found", { retryRunId: params.retryRunId });
-					return {
-						content: [{
-							type: "text" as const,
-							text: `Retry run ID not found: ${params.retryRunId}. The run may have been pruned, or it was a background run created before the run-entry fix (issue #98). Pass the run's agent ID — for background runs the agent ID and run ID are now the same.`,
-						}],
-						details: undefined,
-						isError: true,
-					};
-				}
-			}
-
-			// Handle template resolution
+			// Handle template resolution — MUST run before the single-mode sanitize
+			// block below: a template ASSIGNS params.task, so resolving first lets the
+			// sanitizer validate the real resolved body (a template-only call has no
+			// task yet) and lets mode detection see a non-empty task (issue #175).
 			if (params.template) {
 				const templateEntry = state.config.templates.find((t) => t.name === params.template);
 				if (!templateEntry) {
@@ -2393,7 +2349,34 @@ export default function (pi: ExtensionAPI) {
 				}
 
 				const tv = resolved.value;
-				// Use resolved template fields as defaults, explicitly provided params override
+				// Issue #175 review (fix 4): template-wins silently replaces a
+				// supplied `task`. If that task would itself have failed sanitization
+				// (e.g. over-length), the caller gets no signal — pre-#175 `dev`
+				// rejected it. Warn (never reject — #99/#110 precedent, same
+				// pi.sendMessage channel as the unknown-param warning) so both the LLM
+				// and the human see the ignored task. Emitted ONLY when the supplied
+				// task actually fails sanitization: a valid task alongside a template
+				// is the intended template-wins override (issue #57), not noise.
+				if (params.task !== undefined) {
+					const suppliedTask = sanitizeTask(params.task);
+					if (!suppliedTask.ok) {
+						log.warn("delegate_task: supplied task ignored because a template was given", {
+							template: params.template,
+							error: suppliedTask.error,
+						});
+						pi.sendMessage({
+							customType: "delegate-notification",
+							content: `delegate_task: the supplied 'task' was ignored because a template ('${params.template}') was given. The task would otherwise have been rejected: ${suppliedTask.error}`,
+							display: true,
+							details: { template: params.template, rejectedTask: suppliedTask.error },
+						}, { deliverAs: "followUp" });
+					}
+				}
+				// Issue #175 review (fix direction item 4): this assignment is
+				// UNCONDITIONAL — the resolved template task replaces any supplied
+				// `task` (template-wins, issue #57); it is NOT a default the caller can
+				// override. The fields below, by contrast, ARE defaults: an explicitly
+				// provided param wins over the template's value.
 				params.task = tv.task;
 				if (tv.preset && !params.preset) params.preset = tv.preset;
 				if (tv.thinkingLevel && !params.thinkingLevel) params.thinkingLevel = tv.thinkingLevel;
@@ -2405,6 +2388,53 @@ export default function (pi: ExtensionAPI) {
 				if (tv.inheritSystemPrompt !== undefined && params.inheritSystemPrompt === undefined) params.inheritSystemPrompt = tv.inheritSystemPrompt;
 			}
 
+			// Handle retryRunId — MUST run after template resolution and before the
+			// single-mode sanitize block. resolveRetryParams assigns params.task from
+			// the recorded run, so the sanitizer must see the retried body (a
+			// retry-only call has no task yet). It MUST run AFTER template resolution:
+			// resolveRetryParams returns a fresh object that DROPS `template`, so
+			// resolving templates first keeps a combined template + retryRunId call
+			// from silently disabling template resolution (issue #175 review).
+			if (params.retryRunId) {
+				const runEntry = state.findRunById(ctx, params.retryRunId);
+				if (runEntry) {
+					params = resolveRetryParams(params, runEntry);
+				} else {
+					// Issue #98: a silent no-op here made retries of background runs
+					// (which previously never wrote run entries) start as FRESH runs
+					// with no signal to the caller. Fail loudly instead.
+					log.warn("Retry run ID not found", { retryRunId: params.retryRunId });
+					return {
+						content: [{
+							type: "text" as const,
+							text: `Retry run ID not found: ${params.retryRunId}. The run may have been pruned, or it was a background run created before the run-entry fix. Pass the run's agent ID — for background runs the agent ID and run ID are now the same.`,
+						}],
+						details: undefined,
+						isError: true,
+					};
+				}
+			}
+
+			// F1: Sanitize task input — skip for chain/parallel/graph modes
+			const hasChain = params.chain && params.chain.length > 0;
+			const hasParallel = params.tasks && params.tasks.length > 0;
+			const hasGraph = params.graph && params.graph.length > 0;
+			if (!hasChain && !hasParallel && !hasGraph) {
+				// task is optional per the schema; single mode requires it. When absent,
+				// feed "" to the sanitizer — same rejection path ("Task must not be
+				// empty.") as when task was a required field.
+				const taskResult = sanitizeTask(params.task ?? "");
+				if (!taskResult.ok) {
+					log.warn("Task rejected by sanitizer", { error: taskResult.error });
+					return {
+						content: [{ type: "text" as const, text: `Invalid task: ${taskResult.error}` }],
+						details: undefined,
+						isError: true,
+					};
+				}
+				params.task = taskResult.value;
+			}
+
 			// P1+P2+P10: Mode detection — graph > chain > parallel > single
 			const isChain = hasChain;
 			const isParallel = hasParallel;
@@ -3681,6 +3711,9 @@ export default function (pi: ExtensionAPI) {
 	pi.on("session_start", async (_event, ctx) => {
 		// Issue #147: capture the session context for the completion-push subscriber.
 		sessionCtx = ctx;
+		// Issue #179 (D6): createLogger ran at module load with no cwd — point
+		// the shared file sink at this session's cwd now that it exists.
+		setLogCwd(ctx.cwd);
 		// Load built-in presets
 		const presetsDir = pkgPath("presets");
 		state.builtinPresets = loadBuiltinPresets(presetsDir, log);
@@ -3787,7 +3820,10 @@ export default function (pi: ExtensionAPI) {
 			const knob = state.config.completionNotify ?? "all";
 			const run = resolveRunEntry(state.getRunEntries(ctx), id);
 			const message = buildCompletionMessage(agent, run);
-			const delivery = resolveDelivery(normalizeCompletionStatus(agent.status), knob);
+			// Issue #179 (D2): resolve delivery from the CLASSIFIED notification
+			// status, not the raw agent status — otherwise a run whose completion
+			// the builder downgraded to failed would still be delivered as a success.
+			const delivery = resolveDelivery(message.details.status, knob);
 			sendCompletionNotification(pi, message, delivery);
 		} catch (err) {
 			log.warn(`completion-push handler failed for ${id}`, {

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,7 @@ import type {
 } from "./types";
 import { truncateTail } from "./transcript-tail";
 import { formatRunDuration } from "./history";
+import { classifyTerminalOutcome } from "./types";
 
 /** Terminal statuses the completion message can carry. */
 export type CompletionStatus = "completed" | "failed" | "stopped";
@@ -35,6 +36,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 +62,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
@@ -128,23 +131,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 +184,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, 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,56 @@ 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';
+  }
+}
+
+/**
+ * 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
@@ -531,29 +584,51 @@ 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;
+    const stopReason =
+      status === "failed"
+        ? coherentFailureReason(
+            terminal?.stopReason ?? agent.result?.stopReason,
+            errorCategory,
+          )
+        : terminal?.stopReason ?? agent.result?.stopReason;
     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(stopReason),
       errorMessage: error,
       finishedAt: new Date().toISOString(),
       durationMs: Date.now() - startedAtMs,
@@ -570,6 +645,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 +668,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;
   };
 
@@ -895,7 +989,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 +1026,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 +1103,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 +1118,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 +1162,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 +1177,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/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 },
 			);
 		}

package/src/transcript.ts

@@ -19,8 +19,9 @@ export function __setOutputDir(dir: string): void {
  * Ensure output directory exists
  */
 function ensureOutputDir(): void {
-  // F6 (issue #29): transcripts contain the full subagent conversation — the
-  // dir must be owner-only (0o700) so other local users cannot list the files.
+  // F6 (issue #29): transcripts may hold task/steering text — the dir must be
+  // owner-only (0o700) so other local users cannot list the files. NOTE: the
+  // transcript is NOT the full conversation (see appendEntry below).
   mkdirSync(OUTPUT_DIR, { recursive: true, mode: 0o700 });
 }
 
@@ -52,8 +53,9 @@ export function startTranscript(agentId: string, task: string): string {
     metadata: { task },
   };
   
-  // F6 (issue #29): transcripts hold the full conversation — append
-  // owner-only (0o600) on file CREATE (mode is not retroactive).
+  // F6 (issue #29): append owner-only (0o600) on file CREATE (mode is not
+  // retroactive). The file holds the system start entry plus any steering
+  // entries appended below — NOT the full conversation.
   appendFileSync(path, JSON.stringify(entry) + '\n', { encoding: 'utf-8', mode: 0o600 });
   return path;
 }
@@ -79,8 +81,11 @@ export function appendEntry(
     metadata,
   };
   
-  // F6 (issue #29): transcripts hold the full conversation — append
-  // owner-only (0o600) on file CREATE (mode is not retroactive).
+  // F6 (issue #29): append owner-only (0o600) on file CREATE (mode is not
+  // retroactive). NOTE (D5 / issue #179): this is NOT a conversation recorder —
+  // the only caller is steering (steerAgent), so the transcript holds the
+  // system start entry and steering lines. Do NOT describe it as the full
+  // conversation without actually recording one.
   appendFileSync(path, JSON.stringify(entry) + '\n', { encoding: 'utf-8', mode: 0o600 });
 }
 

package/src/tui.ts

@@ -2190,10 +2190,7 @@ function renderSubTaskSummary(
 	},
 	maxLines: number,
 ): string {
-	const isError =
-		result.exitCode !== 0 ||
-		result.stopReason === "error" ||
-		result.stopReason === "aborted";
+	const isError = isSubagentError(result);
 	const icon = isError
 		? theme.fg("error", "\u2717")
 		: theme.fg("success", "\u2713");
@@ -2213,12 +2210,7 @@ function renderCollapsedChain(
 	details: ChainDetails,
 	theme: Theme,
 ): string {
-	const allSucceeded = details.results.every(
-		(r) =>
-			r.exitCode === 0 &&
-			r.stopReason !== "error" &&
-			r.stopReason !== "aborted",
-	);
+	const allSucceeded = details.results.every((r) => !isSubagentError(r));
 	const icon = allSucceeded
 		? theme.fg("success", "\u2713")
 		: theme.fg("error", "\u2717");
@@ -2226,10 +2218,7 @@ function renderCollapsedChain(
 	let text = `${icon} ${theme.fg("toolTitle", theme.bold("chain"))} ${theme.fg("muted", `${details.completedSteps}/${details.totalSteps} steps${stoppedEarly}`)}`;
 
 	for (const r of details.results) {
-		const isErr =
-			r.exitCode !== 0 ||
-			r.stopReason === "error" ||
-			r.stopReason === "aborted";
+		const isErr = isSubagentError(r);
 		const statusIcon = isErr
 			? theme.fg("error", "\u2717")
 			: theme.fg("success", "\u2713");
@@ -2263,10 +2252,7 @@ function renderCollapsedParallel(
 	let text = `${icon} ${theme.fg("toolTitle", theme.bold("parallel"))} ${theme.fg("muted", `${details.succeeded}/${details.failed}/${details.results.length} total`)}`;
 
 	for (const r of details.results) {
-		const isErr =
-			r.exitCode !== 0 ||
-			r.stopReason === "error" ||
-			r.stopReason === "aborted";
+		const isErr = isSubagentError(r);
 		const statusIcon = isErr
 			? theme.fg("error", "\u2717")
 			: theme.fg("success", "\u2713");
@@ -2312,10 +2298,7 @@ function renderExpandedChain(
 	container.addChild(new Spacer(1));
 
 	for (const r of details.results) {
-		const isErr =
-			r.exitCode !== 0 ||
-			r.stopReason === "error" ||
-			r.stopReason === "aborted";
+		const isErr = isSubagentError(r);
 		const statusIcon = isErr
 			? theme.fg("error", "\u2717")
 			: theme.fg("success", "\u2713");
@@ -2397,10 +2380,7 @@ function renderExpandedParallel(
 	container.addChild(new Spacer(1));
 
 	for (const r of details.results) {
-		const isErr =
-			r.exitCode !== 0 ||
-			r.stopReason === "error" ||
-			r.stopReason === "aborted";
+		const isErr = isSubagentError(r);
 		const statusIcon = isErr
 			? theme.fg("error", "\u2717")
 			: theme.fg("success", "\u2713");
@@ -2774,12 +2754,7 @@ function renderCollapsedGraph(
 ): string {
 	const totalTasks = details.waves.reduce((s, w) => s + w.tasks.length, 0);
 	const allSucceeded = details.waves.every((w) =>
-		w.tasks.every(
-			(r) =>
-				r.exitCode === 0 &&
-				r.stopReason !== "error" &&
-				r.stopReason !== "aborted",
-		),
+		w.tasks.every((r) => !isSubagentError(r)),
 	);
 	const icon = allSucceeded
 		? theme.fg("success", "\u2713")
@@ -2790,22 +2765,16 @@ function renderCollapsedGraph(
 	const wavesToRender = details.waves.slice(0, maxWavesToShow);
 
 	for (const wave of wavesToRender) {
-		const waveOk = wave.tasks.every(
-			(r) =>
-				r.exitCode === 0 &&
-				r.stopReason !== "error" &&
-				r.stopReason !== "aborted",
-		);
+		const waveOk = wave.tasks.every((r) => !isSubagentError(r));
 		const waveIcon = waveOk
 			? theme.fg("success", "\u2713")
 			: theme.fg("error", "\u2717");
 		const modeLabel = wave.parallel ? "parallel" : "serial";
 		const taskLabels = wave.tasks.map((r) => {
 			const label = r.label || r.task.slice(0, 30);
-			const taskIcon =
-				r.exitCode === 0 && r.stopReason !== "error" && r.stopReason !== "aborted"
-					? theme.fg("success", "\u2713")
-					: theme.fg("error", "\u2717");
+			const taskIcon = !isSubagentError(r)
+				? theme.fg("success", "\u2713")
+				: theme.fg("error", "\u2717");
 			return `${taskIcon} ${theme.fg("dim", label)}`;
 		});
 		text += `
@@ -2843,12 +2812,7 @@ function renderExpandedGraph(
 	container.addChild(new Spacer(1));
 
 	for (const wave of details.waves) {
-		const waveOk = wave.tasks.every(
-			(r) =>
-				r.exitCode === 0 &&
-				r.stopReason !== "error" &&
-				r.stopReason !== "aborted",
-		);
+		const waveOk = wave.tasks.every((r) => !isSubagentError(r));
 		const waveIcon = waveOk
 			? theme.fg("success", "\u2713")
 			: theme.fg("error", "\u2717");
@@ -2862,10 +2826,7 @@ function renderExpandedGraph(
 		);
 
 		for (const r of wave.tasks) {
-			const isErr =
-				r.exitCode !== 0 ||
-				r.stopReason === "error" ||
-				r.stopReason === "aborted";
+			const isErr = isSubagentError(r);
 			const statusIcon = isErr
 				? theme.fg("error", "\u2717")
 				: theme.fg("success", "\u2713");

package/src/types.ts

@@ -43,7 +43,14 @@ export type ErrorCategory =
 	| "aborted"
 	| "exit_error"
 	| "crash"
-	| "unknown";
+	| "unknown"
+	// Issue #179: additive terminal-reason categories. "truncated" = the model
+	// hit its output/context limit (stopReason "length"); "incomplete" = the
+	// agent stopped mid-turn without a terminal answer (stopReason
+	// "toolUse"/"deferred"/"pending"). Existing consumers treat categories as
+	// string keys (metrics/SLA breakdown), so both are additive.
+	| "truncated"
+	| "incomplete";
 
 // Issue #120 (Review round): single source of truth for the user-abort stamp.
 // Used by the abort handler (runner.ts), the stopped/aborted settlement paths
@@ -58,6 +65,17 @@ export const SUBAGENT_ABORTED_MESSAGE = "Subagent aborted by user";
  */
 export function classifyError(result: SubagentResult): ErrorCategory {
 	if (result.stopReason === "aborted") return "aborted";
+	// Issue #179: a terminal stopReason with no terminal answer is a failure in
+	// its own right — classify it before the message/exitCode fallbacks so the
+	// honest category wins (length → "truncated"; mid-turn → "incomplete").
+	if (result.stopReason === "length") return "truncated";
+	if (
+		result.stopReason === "toolUse" ||
+		result.stopReason === "deferred" ||
+		result.stopReason === "pending"
+	) {
+		return "incomplete";
+	}
 
 	const msg = (result.errorMessage ?? "").toLowerCase();
 	const err = (result.stderr ?? "").toLowerCase();
@@ -226,6 +244,27 @@ export interface SubagentRun {
 	id: string;
 	task: string;
 	label?: string;
+	/**
+	 * Issue #179 (D1/D2): terminal stopReason of the final assistant turn
+	 * ("stop" | "error" | "aborted" | "length" | "toolUse" | "deferred" |
+	 * "pending"). Recorded on the finalized entry so consumers can tell a real
+	 * success from a resolved-but-failed run.
+	 */
+	stopReason?: string;
+	/**
+	 * Issue #179 (D1/D2): classified error category at the TOP level. The legacy
+	 * `originalParams.errorCategory` is kept populated for back-compat (metrics,
+	 * retry snapshot), but new consumers should prefer this field.
+	 */
+	errorCategory?: ErrorCategory;
+	/**
+	 * Issue #179 (D3): assistant turns folded from the session usage. 0 means the
+	 * run burned nothing ("did nothing"); > 0 with `finalTurnError` means it did
+	 * work and then died.
+	 */
+	turns?: number;
+	/** Issue #179 (D3): whether the final assistant turn was a provider error. */
+	finalTurnError?: boolean;
 	// Issue #98: background run entries carry the agent description (the label
 	// the caller passed at spawn) — kept separate from `label` for symmetry
 	// with the background agent record.
@@ -665,9 +704,108 @@ export function getFinalOutput(messages: Array<Record<string, unknown>>): string
 }
 
 export function isSubagentError(result: SubagentResult): boolean {
-	return result.exitCode !== 0
-		|| result.stopReason === "error"
-		|| result.stopReason === "aborted";
+	if (result.exitCode !== 0) return true;
+	// Issue #179: a resolved-but-failed terminal reason is still an error. This
+	// is the foreground terminal-status derivation (finalizeRunRecord) — the
+	// background path classifies via classifyTerminalOutcome below.
+	return result.stopReason === "error"
+		|| result.stopReason === "aborted"
+		|| result.stopReason === "length"
+		|| result.stopReason === "toolUse"
+		|| result.stopReason === "deferred"
+		|| result.stopReason === "pending";
+}
+
+/**
+ * Issue #179 (review ratchet): the NARROWER question — was the terminal turn a
+ * provider/model error specifically?
+ *
+ * This is distinct from `isSubagentError` (did the run fail at all): a `length`,
+ * `toolUse`, `deferred` or `pending` ending is a FAILED RUN but NOT a provider
+ * error, and callers asking this narrower question want only `"error"`.
+ *
+ * Named so the literal has exactly one home — a consistency ratchet test fails if
+ * any other module compares `stopReason` against a failure reason directly, which
+ * is how the private copies of the wider predicate silently desynced.
+ */
+export function isProviderError(stopReason: string | undefined): boolean {
+	return stopReason === "error";
+}
+
+/**
+ * Issue #179 (C1 fix): tally subtask outcomes by the SHARED failure predicate.
+ * Deriving success from `exitCode === 0` alone mislabels a truncated or
+ * mid-turn run (a resolved prompt with stopReason length/toolUse/deferred/
+ * pending, exitCode 0) as a success — the exact "failure displayed as a
+ * success" defect. Every aggregate (parallel succeeded/failed, chain/graph
+ * success, the TUI verdicts) must route through isSubagentError so a future
+ * widening of the predicate cannot silently desync a private copy.
+ */
+export function countSubagentOutcomes(
+	results: ReadonlyArray<SubagentResult | undefined>,
+): { succeeded: number; failed: number } {
+	let succeeded = 0;
+	let failed = 0;
+	for (const r of results) {
+		if (!r) continue;
+		if (isSubagentError(r)) failed++;
+		else succeeded++;
+	}
+	return { succeeded, failed };
+}
+
+// ---------------------------------------------------------------------------
+// Issue #179: terminal outcome classification
+// ---------------------------------------------------------------------------
+
+/** Terminal status a settled run can take. */
+export type TerminalStatus = "completed" | "failed" | "stopped";
+
+export interface TerminalOutcome {
+	status: TerminalStatus;
+	errorCategory?: ErrorCategory;
+}
+
+/**
+ * Issue #179 (D1): classify a run's terminal outcome from its final assistant
+ * stopReason. This is the settle-time counterpart to classifyError/isSubagentError
+ * and REUSES classifyError for every failure reason (single taxonomy).
+ *
+ * | stopReason               | status    | errorCategory              |
+ * |--------------------------|-----------|----------------------------|
+ * | stop / undefined         | completed | —                          |
+ * | aborted                  | stopped   | aborted                    |
+ * | error                    | failed    | from classifyError         |
+ * | length                   | failed    | truncated                  |
+ * | toolUse/deferred/pending | failed    | incomplete                 |
+ */
+export function classifyTerminalOutcome(
+	stopReason: string | undefined,
+	errorMessage?: string,
+	extra?: { stderr?: string; exitCode?: number },
+): TerminalOutcome {
+	switch (stopReason) {
+		case "aborted":
+			return { status: "stopped", errorCategory: "aborted" };
+		case "error":
+		case "length":
+		case "toolUse":
+		case "deferred":
+		case "pending":
+			return {
+				status: "failed",
+				errorCategory: classifyError({
+					messages: [],
+					usage: { ...EMPTY_USAGE },
+					exitCode: extra?.exitCode ?? 0,
+					stderr: extra?.stderr ?? "",
+					errorMessage,
+					stopReason,
+				}),
+			};
+		default:
+			return { status: "completed" };
+	}
 }
 
 export function formatModel(m: { provider: string; id: string } | undefined): string {