gentle-pi 3.2.0 → 3.3.0

package/lib/agents-view.ts

@@ -1,5 +1,6 @@
 import { Key, matchesKey, truncateToWidth, visibleWidth, type Component, type TuiMouseEvent, type TuiMouseEventResult } from "@earendil-works/pi-tui";
 import { measureAgentsViewLayout, type AgentsViewLayout } from "./agents-view-layout.ts";
+import { HOVER_ROLE, paintHoverable } from "./shell-hover.ts";
 import { emptyThread, isFinished, TASK_STATUS, type TaskRecord, type TaskStore, type TaskThread, type ThreadItem } from "./agents-protocol.ts";
 import { renderThreadItem, type AgentsThreadTheme } from "./agents-thread-view.ts";
 import { formatElapsed } from "./agents-widget.ts";
@@ -42,7 +43,7 @@ const ROLE = {
 	FRAME: "border",
 	TITLE: "customMessageLabel",
 	SELECTED: "accent",
-	HOVER: "warning",
+	HOVER: HOVER_ROLE,
 	NAME: "text",
 	NAME_IDLE: "muted",
 	META: "dim",
@@ -69,7 +70,7 @@ const GLYPH_ROLE: Record<string, string> = {
 	[TASK_STATUS.CANCELLED]: "dim",
 	[TASK_STATUS.TIMED_OUT]: "error",
 };
-export const SESSION_FINISHED_TTL_MS = 15 * 60_000;
+const MAX_FINISHED_PER_SESSION = 200;
 const SCOPE_LABEL: Record<ViewScope, string> = { [VIEW_SCOPE.SESSION]: "this session", [VIEW_SCOPE.ALL]: "all sessions" };
 const SCOPE_KEY: Record<ViewScope, string> = { [VIEW_SCOPE.SESSION]: "all sessions", [VIEW_SCOPE.ALL]: "this session" };
 const EMPTY_LIST = "no tasks yet";
@@ -428,7 +429,8 @@ export class AgentsView {
 
 	private counts(): string {
 		const active = this.tasks.filter((task) => !isFinished(task.status)).length;
-		return `${active} active`;
+		const finished = this.tasks.length - active;
+		return `${active} active · ${finished} finished`;
 	}
 
 	private actionableTask(): TaskRecord | undefined {
@@ -470,8 +472,12 @@ export class AgentsView {
 	}
 
 	private inScope(task: TaskRecord, _now: number): boolean {
-		return !isFinished(task.status) && (task.parentSessionId === this.deps.sessionId
-			|| (this.scope === VIEW_SCOPE.ALL && this.remoteThreads.has(task.id)));
+		// A local task (this session's own, active or finished history) always
+		// belongs; refreshTasks() is the single authority on which finished ones
+		// survive its own retention cap. A remote (presence) task never keeps
+		// history -- it drops out of scope the moment it finishes.
+		if (task.parentSessionId === this.deps.sessionId) return true;
+		return !isFinished(task.status) && this.scope === VIEW_SCOPE.ALL && this.remoteThreads.has(task.id);
 	}
 
 	private directoryRoot(): boolean {
@@ -534,8 +540,19 @@ export class AgentsView {
 	}
 
 	private refreshTasks(): void {
-		this.tasks = this.deps.store.list().filter((task) => task.parentSessionId === this.deps.sessionId
-			&& !isFinished(task.status) && (this.deps.isLocalTask?.(task) ?? true));
+		// Finished history bypasses isLocalTask: that dep exists to keep an
+		// unrelated task resolveTask pulled in on demand (e.g. `subagent_result`
+		// for an id from another session) out of the live panel, never to hide
+		// this session's own finished subagents -- those belong here whether
+		// they were restored on resume or just finished live.
+		const local = this.deps.store.list().filter((task) => task.parentSessionId === this.deps.sessionId
+			&& (isFinished(task.status) || (this.deps.isLocalTask?.(task) ?? true)));
+		const active = local.filter((task) => !isFinished(task.status));
+		const finished = local
+			.filter((task) => isFinished(task.status))
+			.sort((a, b) => (b.endedAt ?? 0) - (a.endedAt ?? 0))
+			.slice(0, MAX_FINISHED_PER_SESSION);
+		this.tasks = [...active, ...finished];
 		if (this.scope === VIEW_SCOPE.ALL) this.tasks.push(...this.peers.flatMap((group) => group.tasks));
 		const groups = this.sessionGroups();
 		const present = new Set(groups.map((group) => group.id));
@@ -564,7 +581,15 @@ export class AgentsView {
 			group.tasks.push(task);
 		}
 		for (const group of groups.values()) {
-			group.tasks.sort((a, b) => b.createdAt - a.createdAt || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+			// Active tasks first (newest created), then finished ones as history
+			// (newest ended first) -- a task never reorders within its own group
+			// just because it finished.
+			group.tasks.sort((a, b) => {
+				const finishedRank = Number(isFinished(a.status)) - Number(isFinished(b.status));
+				if (finishedRank !== 0) return finishedRank;
+				if (isFinished(a.status)) return (b.endedAt ?? 0) - (a.endedAt ?? 0);
+				return b.createdAt - a.createdAt || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+			});
 		}
 		if (this.scope === VIEW_SCOPE.ALL) {
 			const localId = `session:${this.deps.sessionId}`;
@@ -637,16 +662,18 @@ export class AgentsView {
 		const theme = this.deps.theme;
 		this.taskRegion(row).render(this.pointerLayout?.listWidth ?? 1);
 		const selected = entry.id === this.selectedRow()?.id;
-		const hovered = entry.id === this.hoveredId;
-		const emphasis = selected ? ROLE.SELECTED : hovered ? ROLE.HOVER : undefined;
-		const marker = emphasis ? theme.fg(emphasis, selected ? "▸" : "▹") : " ";
+		// Selection always outranks hover; the shared hover painter only
+		// applies once selection is ruled out.
+		const hovered = !selected && entry.id === this.hoveredId;
+		const markerRole = selected ? ROLE.SELECTED : hovered ? ROLE.HOVER : undefined;
+		const marker = markerRole ? theme.fg(markerRole, selected ? "▸" : "▹") : " ";
 		if (entry.kind === "heading") {
 			const state = this.isExpanded(entry.group) ? "▾" : "▸";
-			return `${marker}${theme.fg(emphasis ?? ROLE.SELECTED, state)} ${theme.fg(emphasis ?? ROLE.NAME_IDLE, this.groupHeading(entry.group))}`;
+			return `${marker}${paintHoverable(theme, state, hovered, ROLE.SELECTED)} ${paintHoverable(theme, this.groupHeading(entry.group), hovered, selected ? ROLE.SELECTED : ROLE.NAME_IDLE)}`;
 		}
 		const task = entry.task;
 		const glyph = theme.fg(GLYPH_ROLE[task.status] ?? ROLE.META, GLYPH[task.status] ?? "?");
-		const name = theme.fg(emphasis ?? ROLE.NAME_IDLE, `Subagent ${task.agent}`);
+		const name = paintHoverable(theme, `Subagent ${task.agent}`, hovered, selected ? ROLE.SELECTED : ROLE.NAME_IDLE);
 		const time = task.startedAt === null ? "" : theme.fg(ROLE.META, formatElapsed((task.endedAt ?? this.deps.now()) - task.startedAt));
 		return `${marker} ${theme.fg(ROLE.META, "└")} ${glyph} ${name}  ${time}`;
 	}
@@ -756,7 +783,7 @@ export class AgentsView {
 			actions.push({ x: 2 + visibleWidth(text), width: label.length, region: control.region });
 			control.region.render(label.length);
 			const hovered = (control.region === this.followRegion && this.hoveredControl === "follow") || (control.region === this.openRegion && this.hoveredControl === "open");
-			text += this.deps.theme.fg(!control.enabled ? ROLE.META : hovered ? ROLE.HOVER : ROLE.KEY, label);
+			text += control.enabled ? paintHoverable(this.deps.theme, label, hovered, ROLE.KEY) : this.deps.theme.fg(ROLE.META, label);
 		}
 		if (required > width) {
 			const more = this.actionRegion("more", () => {

package/lib/agents-widget.ts

@@ -29,7 +29,28 @@ interface Columns {
 	name: number;
 	task: number;
 	meta: number;
-	fullMetrics: boolean;
+	// Columnar rows give each surviving metadata field its own fixed,
+	// right-aligned column sized to the widest value among shown tasks, so
+	// model·effort, tokens, cost, and elapsed line up vertically across rows.
+	// A narrow card may have dropped some of those columns and still be
+	// columnar; false means the clipped single-string fallback.
+	columnar: boolean;
+	// Populated only when columnar is true.
+	metaWidths?: MetaColumnWidths;
+}
+
+interface MetaFields {
+	exec: string;
+	tokens: string;
+	cost: string;
+	elapsed: string;
+}
+
+interface MetaColumnWidths {
+	exec: number;
+	tokens: number;
+	cost: number;
+	elapsed: number;
 }
 
 const LOOK: Record<TaskStatus, StatusLook> = {
@@ -150,11 +171,48 @@ function executionLabel(task: TaskRecord, width = Infinity): string {
 	return clip(model, width - visibleWidth(suffix)) + suffix;
 }
 
-function meta(task: TaskRecord, now: number, fullMetrics: boolean): string {
-	if (task.status === TASK_STATUS.QUEUED) return "queued";
-	if (!fullMetrics) return executionLabel(task);
-	const parts = [executionLabel(task), task.tokens > 0 ? formatTokens(task.tokens) : "", task.cost > 0 ? `$${task.cost.toFixed(2)}` : "", elapsed(task, now)];
-	return parts.filter((part) => part.length > 0).join(" · ");
+// Narrow (non-columnar) rows keep the single-string contract: a queued
+// task shows the bare word, everything else shows its exec label.
+function narrowMetaText(task: TaskRecord): string {
+	return task.status === TASK_STATUS.QUEUED ? "queued" : executionLabel(task);
+}
+
+// Queued rows carry no model, token, or cost data yet, so every field but
+// elapsed stays blank — and elapsed itself becomes the literal word "queued"
+// rather than the empty string startedAt === null would otherwise produce.
+function metaFields(task: TaskRecord, now: number): MetaFields {
+	if (task.status === TASK_STATUS.QUEUED) return { exec: "", tokens: "", cost: "", elapsed: "queued" };
+	return {
+		exec: executionLabel(task),
+		tokens: task.tokens > 0 ? formatTokens(task.tokens) : "",
+		cost: task.cost > 0 ? `$${task.cost.toFixed(2)}` : "",
+		elapsed: elapsed(task, now),
+	};
+}
+
+function metaColumnWidths(tasks: readonly TaskRecord[], now: number): MetaColumnWidths {
+	const fields = tasks.map((task) => metaFields(task, now));
+	const widest = (pick: (field: MetaFields) => string) => Math.max(0, ...fields.map((field) => visibleWidth(pick(field))));
+	return { exec: widest((field) => field.exec), tokens: widest((field) => field.tokens), cost: widest((field) => field.cost), elapsed: widest((field) => field.elapsed) };
+}
+
+// A column whose widest value is empty across every shown task (e.g. no task
+// carries a cost yet) is dropped entirely, together with its separator —
+// exactly like the old joined string dropped an empty field, but decided once
+// for the whole card rather than per row, so the remaining columns still align.
+function metaTotalWidth(widths: MetaColumnWidths): number {
+	const active = [widths.exec, widths.tokens, widths.cost, widths.elapsed].filter((width) => width > 0);
+	return active.reduce((sum, width) => sum + width, 0) + Math.max(0, active.length - 1) * visibleWidth(" · ");
+}
+
+function metaRowText(task: TaskRecord, now: number, widths: MetaColumnWidths): string {
+	const fields = metaFields(task, now);
+	const parts: string[] = [];
+	if (widths.exec > 0) parts.push(fields.exec.padStart(widths.exec));
+	if (widths.tokens > 0) parts.push(fields.tokens.padStart(widths.tokens));
+	if (widths.cost > 0) parts.push(fields.cost.padStart(widths.cost));
+	if (widths.elapsed > 0) parts.push(fields.elapsed.padStart(widths.elapsed));
+	return parts.join(" · ");
 }
 
 function taskText(task: TaskRecord): string {
@@ -163,27 +221,40 @@ function taskText(task: TaskRecord): string {
 	return task.label;
 }
 
-// Narrow cards give up the task and usage columns before execution metadata.
+// Narrow cards degrade per column, decided once for the whole card so the
+// surviving columns keep lining up: the task text goes first, then the
+// model·effort label, then tokens, then cost. Elapsed is the one value the
+// reader cannot rebuild from anything else on screen, so it is the last to go
+// (gentle-shell#1143). Only when even elapsed alone does not fit does the row
+// fall back to the clipped single-string label.
 function columns(tasks: readonly TaskRecord[], inner: number, now: number): Columns {
 	const name = Math.max(0, Math.min(NAME_MAX, inner - 3, Math.max(...tasks.map((task) => visibleWidth(task.agent)))));
 	const fixed = 1 + GLYPH_GAP.length + name + COLUMN_GAP.length;
-	const metaWidth = (fullMetrics: boolean) => Math.max(...tasks.map((task) => visibleWidth(meta(task, now, fullMetrics))));
-	const full = metaWidth(true);
+	const metaWidths = metaColumnWidths(tasks, now);
+	const full = metaTotalWidth(metaWidths);
 	const task = inner - fixed - full - COLUMN_GAP.length;
-	if (task >= TASK_MIN) return { inner, name, meta: full, task, fullMetrics: true };
-	return { inner, name, meta: Math.max(0, Math.min(inner - fixed, metaWidth(false))), task: 0, fullMetrics: false };
+	if (task >= TASK_MIN) return { inner, name, meta: full, task, columnar: true, metaWidths };
+	let widths = metaWidths;
+	for (const drop of ["exec", "tokens", "cost"] as const) {
+		if (metaTotalWidth(widths) <= inner - fixed) break;
+		widths = { ...widths, [drop]: 0 };
+	}
+	const meta = metaTotalWidth(widths);
+	if (meta > 0 && meta <= inner - fixed) return { inner, name, meta, task: 0, columnar: true, metaWidths: widths };
+	const narrow = Math.max(0, ...tasks.map((task) => visibleWidth(narrowMetaText(task))));
+	return { inner, name, meta: Math.max(0, Math.min(inner - fixed, narrow)), task: 0, columnar: false };
 }
 
 function row(task: TaskRecord, theme: CardTheme, cols: Columns, now: number, allowMetadataRow: boolean): string[] {
 	const look = LOOK[task.status];
 	const name = clip(task.agent, cols.name);
 	const head = `${theme.fg(look.role, look.glyph)}${GLYPH_GAP}${theme.fg(NAME_ROLE, name)}${" ".repeat(cols.name - visibleWidth(name))}`;
-	const metadata = cols.fullMetrics ? meta(task, now, true) : task.status === TASK_STATUS.QUEUED ? clip("queued", cols.meta) : executionLabel(task, cols.meta);
+	const metadata = cols.columnar && cols.metaWidths ? metaRowText(task, now, cols.metaWidths) : task.status === TASK_STATUS.QUEUED ? clip("queued", cols.meta) : executionLabel(task, cols.meta);
 	const tail = theme.fg(META_ROLE, " ".repeat(Math.max(0, cols.meta - visibleWidth(metadata))) + metadata);
 	if (cols.inner < 3) return [theme.fg(look.role, clip(look.glyph, cols.inner))];
 	// The scrollable sidebar can preserve identity and execution metadata on
 	// separate rows. The height-capped above-editor widget keeps its row budget.
-	if (allowMetadataRow && cols.task === 0 && task.status !== TASK_STATUS.QUEUED && visibleWidth(executionLabel(task)) > cols.meta) {
+	if (allowMetadataRow && !cols.columnar && cols.task === 0 && task.status !== TASK_STATUS.QUEUED && visibleWidth(executionLabel(task)) > cols.meta) {
 		return [head, theme.fg(META_ROLE, executionLabel(task, cols.inner))];
 	}
 	if (cols.task === 0) return [`${head}${" ".repeat(Math.max(0, cols.inner - visibleWidth(head) - visibleWidth(tail)))}${tail}`];

package/lib/command-palette-catalog.ts

@@ -25,6 +25,7 @@ export const COMMAND_PALETTE_CATALOG: readonly CommandPaletteCatalogGroup[] = [
 			{ command: "gentle:persona", label: "Switch persona" },
 			{ command: "gentle:review-mode", label: "Review mode (receipt-driven development)" },
 			{ command: "gentle:background-subagents", label: "Background subagents" },
+			{ command: "gentle:double-esc-cancel", label: "Require double Esc to cancel" },
 			{ command: "gentle:telemetry", label: "Telemetry" },
 			{ command: "gentle:banner", label: "Startup banner" },
 			{ command: "gentle:banner-color", label: "Banner color" },

package/lib/double-esc-cancel-policy.ts

@@ -0,0 +1,138 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { gentlePiConfigHome } from "./agent-home.ts";
+
+// ---------------------------------------------------------------------------
+// Double-esc-cancel policy — global file > env > default off (issue #1163)
+//
+// Deliberately global-only (no project-file layer, unlike
+// background-subagents): this preference changes what a keypress does while
+// the agent is working, and a per-project override for a personal habit like
+// this would make the same key do two different things depending on which
+// repo happens to be open. Otherwise mirrors the resolution shape of
+// lib/background-subagents-policy.ts, minus that project-file layer.
+// ---------------------------------------------------------------------------
+
+export type DoubleEscCancelPolicy = "on" | "off";
+
+/** Which of the three sources decided the effective policy. */
+export type DoubleEscCancelSource = "global_file" | "environment" | "default";
+
+export interface DoubleEscCancelResolution {
+	policy: DoubleEscCancelPolicy;
+	source: DoubleEscCancelSource;
+	/** The deciding file was present but failed the strict decode. */
+	malformed: boolean;
+	globalFile: string;
+	globalFileExists: boolean;
+	/** The raw env value, reported even when it is unrecognized and inert. */
+	envValue: string | undefined;
+}
+
+export interface LoadDoubleEscCancelOptions {
+	/** Override the config home directory (used in tests to avoid touching ~/.pi). */
+	gentlePiConfigHome?: string;
+	/** Override the environment lookup (used in tests). */
+	env?: Record<string, string | undefined>;
+}
+
+export const DOUBLE_ESC_CANCEL_SCHEMA = "gentle-pi.double-esc-cancel/v1";
+export const DOUBLE_ESC_CANCEL_FILE = "double-esc-cancel.json";
+
+// Pi's own idle double-Esc (empty editor -> /tree or /fork, interactive-mode.js
+// `lastEscapeTime`) uses a 500ms window. Canceling a running turn throws away
+// in-flight work and is harder to undo than switching prompts, so this
+// confirmation deliberately gets double that time to land the second press.
+export const DOUBLE_ESC_CANCEL_WINDOW_MS = 1000;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Strict decode of {"schema":"gentle-pi.double-esc-cancel/v1","policy":"on"|"off"}.
+ * Any malformed shape (bad JSON, wrong schema, unknown keys, invalid policy)
+ * returns undefined so the caller fails closed to "off".
+ */
+export function parseDoubleEscCancelPolicyFile(raw: string): DoubleEscCancelPolicy | undefined {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return undefined;
+	}
+	if (!isRecord(parsed)) return undefined;
+	if (parsed.schema !== DOUBLE_ESC_CANCEL_SCHEMA) return undefined;
+	if (parsed.policy !== "on" && parsed.policy !== "off") return undefined;
+	if (Object.keys(parsed).length !== 2) return undefined;
+	return parsed.policy;
+}
+
+/**
+ * Resolve the double-esc-cancel policy AND the source that decided it.
+ *
+ * Resolution order (first hit wins):
+ *   1. Global file `${configHome}/double-esc-cancel.json`
+ *      (configHome honors GENTLE_PI_CONFIG_HOME, default ~/.pi/gentle-ai)
+ *   2. Env var GENTLE_PI_DOUBLE_ESC_CANCEL ("on" | "off")
+ *   3. Default "off"
+ *
+ * A present-but-malformed file fails closed to "off" instead of falling
+ * through to the env var, and stays attributed to that file: "off decided
+ * by a broken global file" and "off by default" are different situations,
+ * and only the first one is a mistake to fix.
+ */
+export function resolveDoubleEscCancelPolicy(
+	options: LoadDoubleEscCancelOptions = {},
+): DoubleEscCancelResolution {
+	const env = options.env ?? process.env;
+	const envValue = env.GENTLE_PI_DOUBLE_ESC_CANCEL;
+	let globalFile = "";
+	try {
+		const configHome = options.gentlePiConfigHome ?? gentlePiConfigHome(env);
+		globalFile = join(configHome, DOUBLE_ESC_CANCEL_FILE);
+		const globalFileExists = existsSync(globalFile);
+		if (globalFileExists) {
+			let decoded: DoubleEscCancelPolicy | undefined;
+			try {
+				decoded = parseDoubleEscCancelPolicyFile(readFileSync(globalFile, "utf8"));
+			} catch {
+				// Unreadable is indistinguishable from unusable at this layer, and
+				// both must fail closed on the file that claimed the decision.
+				decoded = undefined;
+			}
+			return decoded === undefined
+				? { policy: "off", source: "global_file", malformed: true, globalFile, globalFileExists, envValue }
+				: { policy: decoded, source: "global_file", malformed: false, globalFile, globalFileExists, envValue };
+		}
+		if (envValue === "on" || envValue === "off") {
+			return { policy: envValue, source: "environment", malformed: false, globalFile, globalFileExists, envValue };
+		}
+		return { policy: "off", source: "default", malformed: false, globalFile, globalFileExists, envValue };
+	} catch {
+		return { policy: "off", source: "default", malformed: false, globalFile, globalFileExists: false, envValue };
+	}
+}
+
+/**
+ * The effective policy alone, for callers that do not report a source.
+ * It delegates so the loader and the resolver can never disagree.
+ */
+export function loadDoubleEscCancelPolicy(options: LoadDoubleEscCancelOptions = {}): DoubleEscCancelPolicy {
+	return resolveDoubleEscCancelPolicy(options).policy;
+}
+
+/**
+ * Write the global policy file, creating the config home when needed.
+ * Used by both `/gentle:double-esc-cancel enable` and `... disable`.
+ */
+export function writeDoubleEscCancelPolicy(
+	policy: DoubleEscCancelPolicy,
+	options: { gentlePiConfigHome?: string } = {},
+): string {
+	const configHome = options.gentlePiConfigHome ?? gentlePiConfigHome();
+	const path = join(configHome, DOUBLE_ESC_CANCEL_FILE);
+	mkdirSync(configHome, { recursive: true });
+	writeFileSync(path, `${JSON.stringify({ schema: DOUBLE_ESC_CANCEL_SCHEMA, policy }, null, 2)}\n`);
+	return path;
+}

package/lib/inprocess-reviewer.ts

@@ -0,0 +1,260 @@
+// In-process reviewer completion (gentle-ai#4611; gentle-pi#311 P1).
+//
+// The relay child this module replaced ran a locked-down `pi --print` process
+// with extension discovery disabled, which dropped extension-registered
+// providers ("Model not found") and stripped env-provided API keys; its env
+// allowlist required per-provider manual configuration and Go roles had no
+// parity with it. This module is that transport's replacement for a single
+// reviewer completion: it resolves
+// the caller's "provider/id" selection through pi's live model registry,
+// authenticates through the registry's own resolver, and completes exactly
+// one frozen prompt as a single user message — no systemPrompt, no tools, no
+// session, no extension hooks.
+//
+// Every I/O seam is injected (`registry`, `complete`, `now`), so this module
+// runs under tests with no network and no pi process. gentle-pi#311 P2 wires
+// this into the lens relay (lib/review-host-relay.ts); P3 wires the provider
+// role vectors. This file stays a pure completion, never invoked from here.
+
+import type { Api, AssistantMessage, Context, Model, ProviderHeaders, SimpleStreamOptions, TextContent, ThinkingLevel } from "@earendil-works/pi-ai";
+import type { completeSimple } from "@earendil-works/pi-ai/compat";
+import { SAFE_MODEL_ID_PATTERN } from "./model-routing-authority.ts";
+
+// ---------------------------------------------------------------------------
+// Registry seam — a structural subset of pi's live ModelRegistry
+// (@earendil-works/pi-coding-agent core/model-registry.ts). Only `find` and
+// `getApiKeyAndHeaders` are needed here; the real registry's resolved auth
+// carries extra optional fields (`baseUrl`, `env`) that this narrower shape
+// simply ignores.
+// ---------------------------------------------------------------------------
+
+export interface InProcessReviewerRegistry {
+	find(provider: string, modelId: string): Model<Api> | undefined;
+	getApiKeyAndHeaders(model: Model<Api>): Promise<
+		| { readonly ok: true; readonly apiKey?: string; readonly headers?: ProviderHeaders }
+		| { readonly ok: false; readonly error: string }
+	>;
+}
+
+export const INPROCESS_REVIEWER_FAILURE = {
+	SELECTION_INVALID: "selection-invalid",
+	MODEL_NOT_FOUND: "model-not-found",
+	AUTH_UNAVAILABLE: "auth-unavailable",
+	THINKING_INVALID: "thinking-invalid",
+	TOOL_CALL_ATTEMPTED: "tool-call-attempted",
+	EMPTY_OUTPUT: "empty-output",
+	OUTPUT_TOO_LARGE: "output-too-large",
+	TIMED_OUT: "timed-out",
+	ABORTED: "aborted",
+	PROVIDER_FAILED: "provider-failed",
+} as const;
+export type InProcessReviewerFailureCode = (typeof INPROCESS_REVIEWER_FAILURE)[keyof typeof INPROCESS_REVIEWER_FAILURE];
+
+export interface InProcessReviewerRequest {
+	/** "provider/id" from models.json routing; already validated by SAFE_MODEL_ID_PATTERN upstream, re-validated here. */
+	readonly selection: string;
+	/** Routing thinking label: off | minimal | low | medium | high | xhigh | max. Omitted is treated as "off". */
+	readonly thinking?: string;
+	/** Frozen Go-materialized prompt bytes, submitted verbatim as the one user message. */
+	readonly prompt: Buffer;
+	readonly timeoutMs: number;
+	readonly signal?: AbortSignal;
+	/** e.g. "review-risk" — only used to name the routing config key in refusal messages. */
+	readonly routingKey: string;
+}
+
+export type InProcessReviewerOutcome =
+	| { readonly kind: "text"; readonly text: string; readonly reviewerModel: string }
+	| { readonly kind: "refused"; readonly code: InProcessReviewerFailureCode; readonly message: string; readonly evidence?: Record<string, unknown> };
+
+export interface InProcessReviewerDeps {
+	readonly registry: InProcessReviewerRegistry;
+	readonly complete: typeof completeSimple;
+	/** Test seam for the single user message's timestamp; defaults to Date.now. */
+	readonly now?: () => number;
+}
+
+// No existing bound covers the reviewer's completion text: the child this
+// module replaced returned its extracted text unbounded. 4 MiB matches this
+// repo's established convention for this class of bound (lib/session-changes.ts
+// MAX_SESSION_BYTES, lib/provider-contract-bundle.ts MAX_FILE_BYTES).
+export const INPROCESS_REVIEWER_OUTPUT_MAX_BYTES = 4 * 1024 * 1024;
+
+// pi-ai's `SimpleStreamOptions.reasoning` accepts every routing label except
+// "off" (`ThinkingLevel = "minimal" | "low" | "medium" | "high" | "xhigh" |
+// "max"`), and pi-ai itself clamps a level to what the selected model
+// supports through its `thinkingLevelMap`. The label is therefore forwarded
+// verbatim: the routing config owns the choice and the library owns the
+// per-provider mapping, so this module never second-guesses either.
+const THINKING_LABELS = new Set<ThinkingLevel>(["minimal", "low", "medium", "high", "xhigh", "max"]);
+const ERROR_EXCERPT_MAX_CHARS = 512;
+
+function parseSelection(selection: string): { provider: string; modelId: string } | undefined {
+	if (typeof selection !== "string" || selection.length === 0 || !SAFE_MODEL_ID_PATTERN.test(selection)) return undefined;
+	const separatorIndex = selection.indexOf("/");
+	if (separatorIndex <= 0 || separatorIndex === selection.length - 1) return undefined;
+	return { provider: selection.slice(0, separatorIndex), modelId: selection.slice(separatorIndex + 1) };
+}
+
+type ReasoningResolution = { readonly ok: true; readonly reasoning?: ThinkingLevel } | { readonly ok: false };
+
+/**
+ * "off" (or an omitted label) omits `reasoning` entirely; every other pi-ai
+ * level is forwarded verbatim; an unrecognized label is a typed refusal. A model with
+ * `reasoning === false` never receives the field, regardless of the label —
+ * checked last so an unknown label is still refused even for a non-reasoning
+ * model, instead of silently passing validation because it would be dropped
+ * anyway.
+ */
+function resolveReasoning(thinking: string | undefined, model: Model<Api>): ReasoningResolution {
+	if (thinking === undefined || thinking === "off") return { ok: true };
+	if (!THINKING_LABELS.has(thinking as ThinkingLevel)) return { ok: false };
+	return model.reasoning === false ? { ok: true } : { ok: true, reasoning: thinking as ThinkingLevel };
+}
+
+function sanitizeErrorExcerpt(error: unknown): string {
+	const raw = error instanceof Error ? error.message : String(error);
+	const collapsed = raw.replace(/\s+/g, " ").trim();
+	return collapsed.length <= ERROR_EXCERPT_MAX_CHARS ? collapsed : `${collapsed.slice(0, ERROR_EXCERPT_MAX_CHARS - 1)}…`;
+}
+
+function refuse(code: InProcessReviewerFailureCode, message: string, evidence?: Record<string, unknown>): InProcessReviewerOutcome {
+	return { kind: "refused", code, message, ...(evidence === undefined ? {} : { evidence }) };
+}
+
+function isTextContent(part: { type?: unknown }): part is TextContent {
+	return part.type === "text";
+}
+
+/**
+ * Runs one reviewer completion in-process: resolve the model, authenticate,
+ * map the routing thinking label, and complete exactly one frozen prompt as
+ * a single user message. Never retries, never falls back to another model,
+ * never reads process.env — every seam is injected through `deps`.
+ */
+export async function runInProcessReviewer(request: InProcessReviewerRequest, deps: InProcessReviewerDeps): Promise<InProcessReviewerOutcome> {
+	const parsed = parseSelection(request.selection);
+	if (parsed === undefined) {
+		return refuse(
+			INPROCESS_REVIEWER_FAILURE.SELECTION_INVALID,
+			`Invalid model selection ${JSON.stringify(request.selection)} for ${request.routingKey}; expected the "provider/id" shape.`,
+		);
+	}
+
+	const model = deps.registry.find(parsed.provider, parsed.modelId);
+	if (model === undefined) {
+		return refuse(
+			INPROCESS_REVIEWER_FAILURE.MODEL_NOT_FOUND,
+			`No model matches selection ${JSON.stringify(request.selection)} configured for ${request.routingKey}; assign ${request.routingKey} a model that the interactive pi's model list actually shows.`,
+		);
+	}
+
+	const auth = await deps.registry.getApiKeyAndHeaders(model);
+	// Negation narrowing (`!auth.ok`) does not eliminate the `ok: true` arm of
+	// this discriminated union under this project's `strict: false` tsconfig;
+	// an explicit `=== false` comparison narrows correctly in both directions.
+	if (auth.ok === false) {
+		return refuse(
+			INPROCESS_REVIEWER_FAILURE.AUTH_UNAVAILABLE,
+			`No credentials available for provider ${JSON.stringify(parsed.provider)} (used by ${request.routingKey}): ${auth.error}`,
+		);
+	}
+
+	const reasoning = resolveReasoning(request.thinking, model);
+	if (reasoning.ok === false) {
+		return refuse(
+			INPROCESS_REVIEWER_FAILURE.THINKING_INVALID,
+			`Unknown thinking level ${JSON.stringify(request.thinking)} for ${request.routingKey}; use one of off, minimal, low, medium, high, xhigh, max.`,
+		);
+	}
+
+	// The caller's own signal (if any) and a floor timeout race together:
+	// whichever fires first aborts the completion. The catch branch below
+	// tells them apart by which underlying signal actually fired, never by
+	// inspecting the thrown error's shape, which providers are free to vary.
+	const timeoutSignal = AbortSignal.timeout(request.timeoutMs);
+	const combinedSignal = request.signal === undefined ? timeoutSignal : AbortSignal.any([request.signal, timeoutSignal]);
+
+	const context: Context = {
+		messages: [
+			{
+				role: "user",
+				content: [{ type: "text", text: request.prompt.toString("utf8") }],
+				timestamp: (deps.now ?? Date.now)(),
+			},
+		],
+	};
+	const options: SimpleStreamOptions = {
+		signal: combinedSignal,
+		timeoutMs: request.timeoutMs,
+		...(auth.apiKey === undefined ? {} : { apiKey: auth.apiKey }),
+		...(auth.headers === undefined ? {} : { headers: auth.headers }),
+		...(reasoning.reasoning === undefined ? {} : { reasoning: reasoning.reasoning }),
+	};
+
+	// An abort is classified by which signal actually fired, never by the
+	// error's shape or the message's text, and the same classification serves
+	// both settlement paths: a provider may reject on abort, or — the pi-ai
+	// provider convention — resolve an AssistantMessage with `stopReason:
+	// "aborted"` carrying whatever text streamed before the cut. Either way a
+	// fired signal is a timeout or a caller abort, never empty or usable output.
+	const abortRefusal = (): InProcessReviewerOutcome | undefined => {
+		if (timeoutSignal.aborted) {
+			return refuse(INPROCESS_REVIEWER_FAILURE.TIMED_OUT, `Reviewer completion for ${request.routingKey} exceeded its ${request.timeoutMs}ms bound.`);
+		}
+		if (request.signal?.aborted === true) {
+			return refuse(INPROCESS_REVIEWER_FAILURE.ABORTED, `Reviewer completion for ${request.routingKey} was aborted by the caller.`);
+		}
+		return undefined;
+	};
+
+	let assistant: AssistantMessage;
+	try {
+		assistant = await deps.complete(model, context, options);
+	} catch (error) {
+		return abortRefusal() ?? refuse(INPROCESS_REVIEWER_FAILURE.PROVIDER_FAILED, `Reviewer completion failed for ${request.routingKey}: ${sanitizeErrorExcerpt(error)}`);
+	}
+
+	const resolvedAbort = abortRefusal();
+	if (resolvedAbort !== undefined) return resolvedAbort;
+	if (assistant.stopReason === "aborted") {
+		// No signal of ours fired, so the provider cut the completion on its
+		// own: that is a provider failure, and its partial text is not a review.
+		return refuse(
+			INPROCESS_REVIEWER_FAILURE.PROVIDER_FAILED,
+			`Reviewer completion failed for ${request.routingKey}: the provider reported an aborted completion (${assistant.errorMessage ?? "no provider message"}).`,
+		);
+	}
+
+	if (assistant.stopReason === "error") {
+		return refuse(
+			INPROCESS_REVIEWER_FAILURE.PROVIDER_FAILED,
+			`Reviewer completion failed for ${request.routingKey}: ${assistant.errorMessage ?? "unknown provider error"}`,
+		);
+	}
+	if (assistant.content.some((part) => part.type === "toolCall")) {
+		return refuse(
+			INPROCESS_REVIEWER_FAILURE.TOOL_CALL_ATTEMPTED,
+			`Reviewer attempted a tool call for ${request.routingKey}; the in-process reviewer completion must answer in text only.`,
+		);
+	}
+
+	const text = assistant.content.filter(isTextContent).map((part) => part.text).join("");
+	if (text.length === 0) {
+		return refuse(
+			INPROCESS_REVIEWER_FAILURE.EMPTY_OUTPUT,
+			`Reviewer produced no text for ${request.routingKey} (stopReason: ${assistant.stopReason}).`,
+			{ stopReason: assistant.stopReason, ...(assistant.errorMessage === undefined ? {} : { errorMessage: assistant.errorMessage }) },
+		);
+	}
+
+	const textBytes = Buffer.byteLength(text, "utf8");
+	if (textBytes > INPROCESS_REVIEWER_OUTPUT_MAX_BYTES) {
+		return refuse(
+			INPROCESS_REVIEWER_FAILURE.OUTPUT_TOO_LARGE,
+			`Reviewer output for ${request.routingKey} exceeds the ${INPROCESS_REVIEWER_OUTPUT_MAX_BYTES}-byte bound (received ${textBytes} bytes).`,
+		);
+	}
+
+	return { kind: "text", text, reviewerModel: `${model.provider}/${model.id}` };
+}