pi-legion 2.0.3 → 3.0.0

package/src/extension/legion-doctor.ts

@@ -55,6 +55,12 @@ import { ALLOW_NESTED_ENV } from "./budget.ts";
 import { IDLE_STOP_HINT, IDLE_STOP_HINT_SHORT } from "./legion-stop.ts";
 import type { AgentConfig } from "../shared/types.ts";
 import { recentSpawnFailures, type SpawnFailureRecord } from "./spawn-hints.ts";
+import {
+	formatSessionErrorTitle,
+	sessionErrorsLogPath,
+	summarizeSessionErrors,
+	type SessionErrorSummary,
+} from "./session-errors.ts";
 
 /**
  * Canonical slash surface. `/legion help` and the doctor Tools section both
@@ -68,6 +74,7 @@ export const LEGION_SLASH_HELP_LINES = [
 	"/legion on | /legion off — enable/disable subagents for this session (status is shown after each run)",
 	"/scout-guard | /no-scout-guard — session override for the main-session scout guard",
 	"/legion summary [--all] [<name>]",
+	"/legion timing [--json] [<name>] — wall / generation / other timing for children",
 	"/legion doctor [section]",
 	"/legion stop [name|all]",
 	"/legion --tree | /legion <node>",
@@ -83,6 +90,7 @@ export const DOCTOR_SECTIONS = [
 	"tools",
 	"storage",
 	"runtime",
+	"errors",
 	"next",
 ] as const;
 
@@ -169,6 +177,8 @@ export interface DoctorOptions {
 	runtime?: DoctorRuntimeSnapshot;
 	/** Limit to these sections (plus always `next` when issues exist). */
 	sections?: readonly DoctorSection[];
+	/** Injected session-error summary (tests); defaults to reading storeRoot log. */
+	sessionErrors?: SessionErrorSummary;
 }
 
 function readJson(file: string): unknown {
@@ -647,8 +657,20 @@ export function runLegionDoctor(options: DoctorOptions = {}): DoctorReport {
 	}
 
 	const storeRoot = options.storeRoot ?? (options.cwd ? path.join(options.cwd, ".pi-subagents") : undefined);
+	const sessionErrors = options.sessionErrors ?? summarizeSessionErrors({ storeRoot });
 	const orphans = storeRoot ? scanOrphanTemps(storeRoot) : undefined;
 	const hygieneLast = storeRoot ? readHygieneLast(storeRoot) : undefined;
+	if (sessionErrors.total > 0) {
+		issues.push({
+			severity: "info",
+			code: "SESSION_ERRORS",
+			section: "errors",
+			message: `${sessionErrors.total} session error(s) recorded (see Errors section / log).`,
+			fix: sessionErrors.logPath
+				? `Inspect ${sessionErrors.logPath}`
+				: "Re-run after a tool failure to populate the session-errors log under .pi-subagents/.",
+		});
+	}
 	if (orphans && orphans.orphanDead > 0) {
 		issues.push({
 			severity: "info",
@@ -698,6 +720,7 @@ export function runLegionDoctor(options: DoctorOptions = {}): DoctorReport {
 		const errN = issues.filter((i) => i.severity === "error").length;
 		const warnN = issues.filter((i) => i.severity === "warning").length;
 		push(`- status: ${errN ? "FAIL" : warnN ? "WARN" : "OK"} (${errN} error(s), ${warnN} warning(s))`);
+		push(`- session errors: ${sessionErrors.total}${sessionErrors.logPath ? ` (log ${homeize(sessionErrors.logPath, home)})` : ""}`);
 		push(`- child --no-extensions: ${noExtensions ? "yes" : "no"}; inherit: ${inheritGlobal ? "yes" : "no"}`);
 		push(`- models host/child: ${hostModels.length}/${childModels.length}`);
 		push(`- live children: ${runtime.liveJobs?.length ?? "(unknown — pass runtime)"}`);
@@ -862,6 +885,38 @@ export function runLegionDoctor(options: DoctorOptions = {}): DoctorReport {
 		push("");
 	}
 
+	if (want(selected, "errors")) {
+		push("## Session errors");
+		push(`- count: ${sessionErrors.total}`);
+		const codes = Object.entries(sessionErrors.byCode)
+			.sort((a, b) => b[1] - a[1])
+			.map(([code, n]) => `${code}=${n}`)
+			.join(", ");
+		if (codes) push(`- by code: ${codes}`);
+		const logPath = sessionErrors.logPath ?? sessionErrorsLogPath(storeRoot);
+		if (logPath) {
+			push(`- log: ${homeize(logPath, home)} (${formatBytes(sessionErrors.logBytes)})`);
+		} else {
+			push("- log: (no storeRoot — errors stay in-process only until a tool runs with a cwd)");
+		}
+		if (sessionErrors.total === 0) {
+			push("(none recorded)");
+		} else {
+			push("### Recent");
+			for (const row of sessionErrors.recent) {
+				push(`- ${formatSessionErrorTitle(row)}`);
+			}
+			if (sessionErrors.large || sessionErrors.truncated) {
+				push("");
+				push(
+					`Summary only — full journal at ${homeize(logPath ?? "(unset)", home)}. ` +
+					"Open that file for the complete history (doctor never dumps the whole log here).",
+				);
+			}
+		}
+		push("");
+	}
+
 	if (want(selected, "runtime")) {
 		push("## Session / runtime");
 		const jobs = runtime.liveJobs ?? [];

package/src/extension/legion-stop.ts

@@ -89,8 +89,12 @@ export function stopCompletions(prefix: string, jobs: readonly StopJob[], nodes:
 export interface StopDeps {
 	jobs(): readonly StopJob[];
 	nodes(): readonly StopNode[];
-	/** Graceful retire via the subagent `stop` action; resolves to its summary text. */
-	stop(params: { name?: string; all?: boolean }): Promise<{ ok: boolean; text: string }>;
+	/**
+	 * Retire via the subagent `stop` action; resolves to its summary text.
+	 * Nova follow-up (#179): `/legion stop --force` may pass `force: true`
+	 * (hard retire). Default remains graceful.
+	 */
+	stop(params: { name?: string; all?: boolean; force?: boolean }): Promise<{ ok: boolean; text: string }>;
 	notify(message: string, type: "info" | "warning" | "error"): void;
 }
 

package/src/extension/playbook.ts

@@ -10,8 +10,8 @@ export const PARENT_PLAYBOOK = [
 	'   One child:  subagent({ agent: "<role>", task: "...", name?: "scout-a" })  // optional name= registers that handle (not auto scout-N)',
 	"   Parallel:   subagent({ tasks: [{ agent, task }, { agent, task }] })",
 	"2. Prefer tasks[] for independent parallel work. Child processes are headless RPC children; no pane or tab is created.",
-	"3. Then return control. A completion message wakes this session when idle; if it is still working, the notice waits until the current turn ends. Use `wait` when you need blocking results, and `collect` to inspect a child's session JSONL. Esc / wait interrupt only ends the parent turn's wait — children keep running and settle still notifies; only an explicit `stop` or session exit retires them. A wait interrupted by Esc returns `interrupted (parent turn ended; children still running)`. In `pi --print` or JSON mode, session shutdown waits for live async children to settle (up to each child's turn timeout) before retiring them. Use same-turn `wait`/`collect` or `async: false` when that print turn must include the child's result.",
-	"4. Later control is only through `subagent({ action, name, message })`; use `stop` to gracefully retire one child or all tracked children. If a child exits oddly (Model not found, missing tools, memory refused, …), call `subagent({ action: \"diagnose\" })` or ask the user to run `/legion doctor` / `/legion doctor models` — children use `--no-extensions`, so provider packages must be passed explicitly. Do not tell a child to message or prompt the parent directly.",
+	"3. Then return control. A completion message wakes this session when idle; if it is still working, the notice waits until the current turn ends. Use `wait` with `name` or `all: true` when you need blocking results, and `collect` to inspect a child's session JSONL. Esc / wait interrupt only ends the parent turn's wait — children keep running and settle still notifies; only an explicit `stop` or session exit retires them. A wait interrupted by Esc returns `interrupted (parent turn ended; children still running)`. In `pi --print` or JSON mode, session shutdown waits for live async children to settle (up to each child's turn timeout) before retiring them. Use same-turn `wait`/`collect` or `async: false` when that print turn must include the child's result.",
+	"4. Later control is only through `subagent({ action, name?, message? })`; `status` with no name (or `all: true`) overviews live children, with `name` for one child; use `stop` to gracefully retire one child or all tracked children (`force: true` for hard retire when soft stop is insufficient). A `wait` timeout does not stop children — the result lists decisions (`extend` / `steer_again` / `stop` / `force_stop`) for the parent to choose. If a child exits oddly (Model not found, missing tools, memory refused, …), call `subagent({ action: \"diagnose\" })` or ask the user to run `/legion doctor` / `/legion doctor models` — children use `--no-extensions`, so provider packages must be passed explicitly. Do not tell a child to message or prompt the parent directly.",
 	"5. A collect timeout with a live RPC child is a progress signal, not a verdict. Check status or session JSONL before deciding to steer or resume.",
 	"6. Isolation is YOUR call. Pass `worktree: true` when another parent may write this repo or the child must ship via MR; pass `worktree: false` to share the checkout. Omit it for the role default.",
 	"7. Launch with `verify: [\"npm run typecheck\", \"npm test\"]` when the project has a mechanical verifier. The extension runs those commands itself in the child worktree at collect time; the child does not need to paste test output.",
@@ -23,7 +23,7 @@ export const TOOL_DESCRIPTION = [
 	PARENT_PLAYBOOK,
 	"Roles: the system prompt lists every loaded role. Prefer the matching role over doing that work yourself.",
 	"Launch is async by default. Outcomes come from the child session JSONL. In non-interactive `pi --print` / JSON mode, shutdown waits for those children before retiring them; pass `async: false` or call `wait`/`collect` in the same turn to fold the result into the print output.",
-	"Actions: launch (default), continue, steer, resume, status, collect, wait, list, retire, stop, diagnose. `diagnose` prints the Legion doctor report (host vs child extensions/providers/models/memory). `wait` is event-driven: it returns when a child settles, times out, or the parent turn is interrupted; Esc does not retire children — use `stop` (or exit the session) to retire them.",
+	"Actions: launch (default), continue, steer, resume, status, collect, wait, list, retire, stop, diagnose. `status` with no name (or `all: true`) returns a live-children overview; with `name` returns that one child (unknown → NOT_FOUND). `diagnose` prints the Legion doctor report (host vs child extensions/providers/models/memory). `wait` REQUIRES `name` or `all: true` (mutually exclusive); it is event-driven and returns when a child settles, times out, or the parent turn is interrupted; a timeout leaves children running and returns structured decisions for the parent. Esc does not retire children — use `stop` / `stop`+`force:true` (or exit the session) to retire them. Example: `subagent({ action: \"wait\", all: true })` or `subagent({ action: \"wait\", name: \"worker-0\" })`.",
 ].join(" ");
 
 /** Split shell commands into sequential chunks while preserving old helper API. */

package/src/extension/runtime.ts

@@ -24,9 +24,11 @@ import {
 	createStatusBoard,
 	type StatusStripStyle,
 	type StatusVizSnapshot,
+	activeEntries,
 	formatBusyLabel,
 	type StatusEntry,
 	type StatusUi,
+	type WidgetTui,
 } from "../tui/status.ts";
 import { progressFromSessionFile } from "../shared/progress.ts";
 import { isTransientConnectionFailure } from "../shared/session.ts";
@@ -112,7 +114,11 @@ export interface LegionTreeIdentity {
 
 export interface SessionRuntimeDeps {
 	sendMessage: SendMessageApi["sendMessage"];
-	emitBusy?: (active: boolean, label?: string) => void;
+	/**
+	 * Raise/clear parent busy. When active, `children` lists live child slugs for
+	 * hierarchical OSC ids (`legion/<slug>`). Cleared with `active=false`.
+	 */
+	emitBusy?: (active: boolean, label?: string, children?: readonly string[]) => void;
 	now?: () => number;
 	refreshMs?: number;
 	/** Shared extension-lifetime bus; all visual refreshes are driven through it. */
@@ -300,6 +306,13 @@ export interface WaitResult {
 	snapshot?: CollectSnapshot;
 	/** Still running when the timeout fired. */
 	stillRunning?: boolean;
+	/**
+	 * True when this wait hit its per-child timeout (vs a non-terminal
+	 * collect snapshot). Used by waitAction to label status `wait_timeout`.
+	 */
+	timedOut?: boolean;
+	/** Wall-clock ms since the tracked job was spawned (for parent decide UX). */
+	elapsedMs?: number;
 	/** The parent turn ended while this wait was pending; children still running. */
 	interrupted?: boolean;
 	/** Not tracked live and no finished cache (pre-validated upstream). */
@@ -339,8 +352,8 @@ export interface SessionRuntime {
 	refreshUi(): void;
 	/** Live visualization data (nodes + token-rate sampler) for the /legion view. */
 	vizSnapshot(): StatusVizSnapshot;
-	/** TUI hosting the status widget (unknown shape; used for overlay/focus checks). */
-	statusTui(): unknown;
+	/** TUI hosting the status widget (used for overlay/focus checks). */
+	statusTui(): WidgetTui | undefined;
 	/** Forward join config to the internal coordinator (settings wiring). */
 	setJoinConfig(config: JoinConfig): void;
 	/**
@@ -532,14 +545,15 @@ export function createSessionRuntime(deps: SessionRuntimeDeps): SessionRuntime {
 
 	const syncBusy = (list: StatusEntry[] = entries()): void => {
 		const label = formatBusyLabel(list);
+		const children = activeEntries(list).map((entry) => entry.name);
 		if (label !== undefined) {
-			deps.emitBusy?.(true, label);
+			deps.emitBusy?.(true, label, children);
 			busyRaised = true;
 			return;
 		}
 		if (busyRaised) {
 			busyRaised = false;
-			deps.emitBusy?.(false);
+			deps.emitBusy?.(false, undefined, []);
 		}
 	};
 
@@ -736,7 +750,11 @@ export function createSessionRuntime(deps: SessionRuntimeDeps): SessionRuntime {
 					job.notified = false;
 					runtime.watch(name);
 				}
-				return { name, stillRunning: true };
+				return {
+					name,
+					stillRunning: true,
+					elapsedMs: Math.max(0, now() - job.spawnedAt),
+				};
 			}
 			if (jobs.get(name) === job) {
 				try {
@@ -752,7 +770,12 @@ export function createSessionRuntime(deps: SessionRuntimeDeps): SessionRuntime {
 				// The watch is still in flight and shares this collect promise —
 				// restore auto-notify or the result would never surface.
 				job.consumedByTool = false;
-				return { name, stillRunning: true };
+				return {
+					name,
+					stillRunning: true,
+					timedOut: true,
+					elapsedMs: Math.max(0, now() - job.spawnedAt),
+				};
 			}
 			throw error;
 		} finally {
@@ -1151,8 +1174,10 @@ export function createSessionRuntime(deps: SessionRuntimeDeps): SessionRuntime {
 				await Promise.all(pending.map(async (job) => {
 					try {
 						await ensureCollect(job);
+						return true;
 					} catch {
 						// The watch records the failure; shutdown still retires the child.
+						return false;
 					}
 				}));
 				// The watch continuation shares this collect and must observe
@@ -1178,7 +1203,7 @@ export function createSessionRuntime(deps: SessionRuntimeDeps): SessionRuntime {
 			board.clear();
 			if (busyRaised) {
 				busyRaised = false;
-				deps.emitBusy?.(false);
+				deps.emitBusy?.(false, undefined, []);
 			}
 		},
 	};
@@ -1186,6 +1211,17 @@ export function createSessionRuntime(deps: SessionRuntimeDeps): SessionRuntime {
 	return runtime;
 }
 
+
+/** Latest visible activity ms across tree / session / turn clocks. */
+function latestActivityAt(...candidates: Array<number | undefined>): number | undefined {
+	let best: number | undefined;
+	for (const value of candidates) {
+		if (value === undefined || !Number.isFinite(value)) continue;
+		best = best === undefined ? value : Math.max(best, value);
+	}
+	return best;
+}
+
 function statusEntryFromJob(
 	job: TrackedJob,
 	identity?: LegionTreeIdentity,
@@ -1203,6 +1239,12 @@ function statusEntryFromJob(
 				: executionStatus === "failed" || executionStatus === "truncated" || executionStatus === undefined ? "failed"
 					: "retired";
 	const finishedAt = terminalNode ? node.updatedAt : job.settledAt;
+	const lastActivityAt = latestActivityAt(
+		node?.updatedAt,
+		live.currentTurnStartedAt,
+		live.currentTurnEndedAt,
+		finishedAt,
+	);
 	return {
 		name: job.name,
 		agent: job.agent,
@@ -1229,6 +1271,7 @@ function statusEntryFromJob(
 			? { tokensOut: live.tokensOut }
 			: node?.tokensOut ? { tokensOut: node.tokensOut } : {}),
 		...(live.generationMs ? { generationMs: live.generationMs } : {}),
+		...(lastActivityAt !== undefined ? { lastActivityAt } : {}),
 		...(identity ? {
 			nodeId: identity.nodeId,
 			parentId: identity.parentId,
@@ -1241,6 +1284,11 @@ function statusEntryFromNode(
 	node: TreeNodeSnapshot,
 	activity?: NodeActivity,
 ): StatusEntry {
+	const lastActivityAt = latestActivityAt(
+		node.updatedAt,
+		activity?.turnStartedAt,
+		activity?.turnEndedAt,
+	);
 	return {
 		name: node.name,
 		agent: node.role,
@@ -1258,6 +1306,7 @@ function statusEntryFromNode(
 		...(activity?.turnStartedAt !== undefined ? { currentTurnStartedAt: activity.turnStartedAt } : {}),
 		...(activity?.turnEndedAt !== undefined ? { currentTurnEndedAt: activity.turnEndedAt } : {}),
 		...(activity?.tools.length ? { lastTools: activity.tools } : {}),
+		...(lastActivityAt !== undefined ? { lastActivityAt } : {}),
 		nodeId: node.id,
 		parentId: node.parentId,
 		depth: node.depth,

package/src/extension/scout-guard.ts

@@ -49,6 +49,12 @@ export interface ScoutGuardDeps {
 	 */
 	schedule?: (run: () => void) => void;
 	env?: NodeJS.ProcessEnv;
+	/**
+	 * When false, subagent/vexillatio launch is forbidden (session `/legion off`
+	 * or `subagents.enabled: false`). Scout-guard must not nag to dispatch.
+	 * Defaults to always-enabled when omitted.
+	 */
+	subagentsEnabled?: (cwd: string) => boolean;
 }
 
 const READ_HEADS = new Set([
@@ -94,6 +100,11 @@ export function scoutGuardReminder(threshold: number): string {
 	return `连续 ${threshold} 次文件类调用且未派发 subagent——若这是侦察工作，请停下来拆 scout（规则：侦察必须并行）。`;
 }
 
+/** One-liner while subagents cannot launch (#182). */
+export function scoutGuardPausedNotice(): string {
+	return "subagent 已禁用，scout-guard 暂停";
+}
+
 export function resolveScoutGuardConfig(
 	settings: ScoutGuardSettings | undefined,
 	sessionEnabled: boolean | undefined,
@@ -187,6 +198,8 @@ export function registerScoutGuard(pi: ExtensionAPI, deps: ScoutGuardDeps = {}):
 	const schedule = deps.schedule ?? deferScoutReminder;
 	let sessionEnabled: boolean | undefined;
 	let state = initialScoutGuardState();
+	/** At most one pause notice per continuous subagents-disabled period (#182). */
+	let pausedNoticeSent = false;
 
 	const readConfig = (cwd: string): ResolvedScoutGuardConfig => {
 		try {
@@ -224,9 +237,34 @@ export function registerScoutGuard(pi: ExtensionAPI, deps: ScoutGuardDeps = {}):
 	});
 
 	pi.on("tool_call", (event, ctx) => {
-		const config = readConfig(ctx?.cwd || process.cwd());
+		const cwd = ctx?.cwd || process.cwd();
+		const config = readConfig(cwd);
 		// Disabled is a full bypass: do not count, reset, cool down, or notify.
 		if (!config.enabled) return;
+		// #182: when subagents cannot launch, the "拆 scout" nag is misleading.
+		const canDispatch = deps.subagentsEnabled?.(cwd) ?? true;
+		if (!canDispatch) {
+			if (!pausedNoticeSent) {
+				pausedNoticeSent = true;
+				const content = scoutGuardPausedNotice();
+				schedule(() => {
+					try {
+						pi.sendMessage(
+							{ customType: SCOUT_GUARD_NOTIFY_TYPE, content, display: true },
+							{ triggerTurn: false, deliverAs: "followUp" },
+						);
+					} catch {
+						// Parent session may already be gone.
+					}
+				});
+			}
+			return;
+		}
+		if (pausedNoticeSent) {
+			// Re-enabled: allow a fresh pause notice next time, and start clean.
+			pausedNoticeSent = false;
+			state = initialScoutGuardState();
+		}
 		const kind = classifyScoutToolCall(event.toolName, event.input);
 		const next = stepScoutGuard(state, kind, config, now());
 		state = next.state;

package/src/extension/session-errors.ts

@@ -0,0 +1,191 @@
+/**
+ * Session-level error journal for `/legion doctor` (#160).
+ *
+ * Tool validation failures and other observable agent-side errors append to a
+ * JSONL log under storeRoot so they survive beyond a single turn. Doctor reads
+ * a summary (counts + recent one-liners) and prints the log path when the file
+ * is large — never dumps the whole log into the terminal.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export const SESSION_ERRORS_FILE = "session-errors.jsonl";
+
+/** Soft cap: doctor summarizes and points at the path past this size. */
+export const SESSION_ERRORS_LARGE_BYTES = 32 * 1024;
+
+/** Keep at most this many recent lines when rotating the on-disk log. */
+export const SESSION_ERRORS_MAX_LINES = 500;
+
+/** In-process ring shown even when storeRoot is unset. */
+const MEMORY_RING = 32;
+
+export interface SessionErrorRecord {
+	ts: number;
+	code: string;
+	message: string;
+	tool?: string;
+	action?: string;
+}
+
+let defaultStoreRoot: string | undefined;
+let defaultTool: string | undefined;
+let defaultAction: string | undefined;
+const recent: SessionErrorRecord[] = [];
+
+export function configureSessionErrors(opts: {
+	storeRoot?: string;
+	tool?: string;
+	action?: string;
+}): void {
+	if (opts.storeRoot) defaultStoreRoot = opts.storeRoot;
+	if (opts.tool !== undefined) defaultTool = opts.tool;
+	if (opts.action !== undefined) defaultAction = opts.action;
+}
+
+/** Test helper. */
+export function clearSessionErrors(): void {
+	recent.length = 0;
+	defaultStoreRoot = undefined;
+	defaultTool = undefined;
+	defaultAction = undefined;
+}
+
+export function recentSessionErrors(): readonly SessionErrorRecord[] {
+	return recent;
+}
+
+export function sessionErrorsLogPath(storeRoot?: string): string | undefined {
+	const root = storeRoot ?? defaultStoreRoot;
+	return root ? path.join(root, SESSION_ERRORS_FILE) : undefined;
+}
+
+function pushMemory(entry: SessionErrorRecord): void {
+	recent.unshift(entry);
+	if (recent.length > MEMORY_RING) recent.length = MEMORY_RING;
+}
+
+function appendToLog(storeRoot: string, entry: SessionErrorRecord): void {
+	const file = path.join(storeRoot, SESSION_ERRORS_FILE);
+	try {
+		fs.mkdirSync(storeRoot, { recursive: true });
+		fs.appendFileSync(file, `${JSON.stringify(entry)}\n`, "utf8");
+		rotateIfNeeded(file);
+	} catch {
+		/* best-effort — doctor still sees the in-memory ring */
+	}
+}
+
+function rotateIfNeeded(file: string): void {
+	try {
+		const raw = fs.readFileSync(file, "utf8");
+		const lines = raw.split("\n").filter((line) => line.trim().length > 0);
+		if (lines.length <= SESSION_ERRORS_MAX_LINES) return;
+		const kept = lines.slice(-SESSION_ERRORS_MAX_LINES);
+		fs.writeFileSync(file, `${kept.join("\n")}\n`, "utf8");
+	} catch {
+		/* ignore */
+	}
+}
+
+/**
+ * Record one session error. Prefer an explicit storeRoot; otherwise use the
+ * last configureSessionErrors() root (set on tool execute / session_start).
+ */
+export function recordSessionError(
+	entry: Omit<SessionErrorRecord, "ts"> & { ts?: number; storeRoot?: string },
+): SessionErrorRecord {
+	const record: SessionErrorRecord = {
+		ts: entry.ts ?? Date.now(),
+		code: entry.code,
+		message: entry.message,
+		tool: entry.tool ?? defaultTool,
+		action: entry.action ?? defaultAction,
+	};
+	pushMemory(record);
+	const root = entry.storeRoot ?? defaultStoreRoot;
+	if (root) appendToLog(root, record);
+	return record;
+}
+
+export interface SessionErrorSummary {
+	total: number;
+	byCode: Record<string, number>;
+	recent: SessionErrorRecord[];
+	logPath?: string;
+	logBytes: number;
+	large: boolean;
+	/** True when the on-disk log has more rows than we show inline. */
+	truncated: boolean;
+}
+
+function readLogRecords(logPath: string): SessionErrorRecord[] {
+	try {
+		const raw = fs.readFileSync(logPath, "utf8");
+		const out: SessionErrorRecord[] = [];
+		for (const line of raw.split("\n")) {
+			const trimmed = line.trim();
+			if (!trimmed) continue;
+			try {
+				const parsed = JSON.parse(trimmed) as SessionErrorRecord;
+				if (parsed && typeof parsed.message === "string") out.push(parsed);
+			} catch {
+				/* skip bad lines */
+			}
+		}
+		return out;
+	} catch {
+		return [];
+	}
+}
+
+/**
+ * Build a doctor-facing summary. Prefer on-disk log when present; fall back to
+ * the in-memory ring. Never returns the full log body — only recent titles.
+ */
+export function summarizeSessionErrors(opts?: {
+	storeRoot?: string;
+	/** How many recent one-liners to include (default 5). */
+	recentLimit?: number;
+	largeBytes?: number;
+}): SessionErrorSummary {
+	const recentLimit = opts?.recentLimit ?? 5;
+	const largeBytes = opts?.largeBytes ?? SESSION_ERRORS_LARGE_BYTES;
+	const logPath = sessionErrorsLogPath(opts?.storeRoot);
+	let logBytes = 0;
+	let disk: SessionErrorRecord[] = [];
+	if (logPath) {
+		try {
+			logBytes = fs.statSync(logPath).size;
+			disk = readLogRecords(logPath);
+		} catch {
+			logBytes = 0;
+			disk = [];
+		}
+	}
+	const source = disk.length > 0 ? disk : [...recent].reverse();
+	const byCode: Record<string, number> = {};
+	for (const row of source) {
+		byCode[row.code] = (byCode[row.code] ?? 0) + 1;
+	}
+	const recentSlice = source.slice(-recentLimit).reverse();
+	return {
+		total: source.length,
+		byCode,
+		recent: recentSlice,
+		logPath,
+		logBytes,
+		large: logBytes >= largeBytes,
+		truncated: source.length > recentLimit,
+	};
+}
+
+/** One-line title for doctor output. */
+export function formatSessionErrorTitle(row: SessionErrorRecord): string {
+	const when = new Date(row.ts).toISOString();
+	const where = [row.tool, row.action].filter(Boolean).join("/");
+	const head = where ? `${where} ` : "";
+	const msg = row.message.trim().replace(/\s+/g, " ").slice(0, 160);
+	return `${when} [${row.code}] ${head}${msg}`;
+}