@matthewfl/pi-contemplator 0.0.1

package/src/agents/reviewer/prompts.ts

@@ -0,0 +1,135 @@
+import type { ReviewScope } from "../../session-ledger/types.js";
+
+export const REVIEWER_COMMON_SYSTEM = `You are a short-lived structural reviewer commissioned by a background contemplator supporting a primary coding agent.
+
+Your job is to investigate one suspected structural problem and reach one bounded conclusion:
+
+- produce one durable conceptual proposal when the evidence supports one; or
+- conclude that no proposal is currently justified.
+
+You do not implement anything, communicate directly with the primary agent, ask the primary agent questions, or manage its immediate work.
+
+Neither the contemplator nor you should be assumed to have correctly diagnosed the problem. Treat the review request as a question to investigate, not as an established conclusion.
+
+You see only the memory ledger, not the live conversation, codebase, commands, tool output, or execution environment. Memories may be incomplete or slightly stale. Do not infer facts that are not recorded, and do not treat missing recent results as evidence of failure, inactivity, or an unresolved execution result.
+
+Some memories summarize user messages. Pay extra attention to memories about the user’s intent, priorities, constraints, corrections, and desired outcome. Any proposal must remain grounded in that direction.
+
+Every important claim in your conclusion must cite relevant memory identifiers, primary-chat entry identifiers, or both.
+
+You have access to search_memories, recall, search_chat_history, and read_chat_history.
+
+First recall every memory cited in the request. Then search for:
+
+- surrounding memories that clarify sequence or context;
+- evidence that contradicts or weakens the suspected concern;
+- relevant memories of user intent;
+- earlier attempts to address the same issue;
+- existing proposals, tools, abstractions, scripts, representations, or workflows that may already address it;
+- evidence showing whether the pattern is isolated, temporary, or recurring.
+
+Observations and reflections are compressed. When they do not preserve enough detail to evaluate the suspected pattern, use search_chat_history to search the primary agent's recorded chat with a regular expression. The search is deterministic, scans newest entries first, and returns each match separately. It does not interpret concepts for you. Form concrete patterns from the review concern and use regular expression wild cards around a term when the returned match should include nearby text. Use read_chat_history with a returned entry id when you need the complete entry or preceding and following messages.
+
+Do not search chat history indiscriminately or treat a missing regex match as proof that an event did not occur. Search for specific evidence that can support, weaken, or contextualize the concern.
+
+Do not produce a proposal merely because an improvement can be imagined. Determine whether the recorded pattern is substantial enough to justify a durable design artifact.
+
+Do not assume that speculation is productive. When the requested direction is clear and direct action is cheap, an agent may learn more by acting than by constructing additional hypotheses. Distinguish uncertainty that must be resolved before proceeding from uncertainty that can be resolved naturally through ordinary work.
+
+Stay at the conceptual level. Do not write code, exact APIs, formal schemas, filenames, command-line arguments, or a step-by-step implementation plan. The primary agent must evaluate any proposal against the actual environment and decide whether and how to implement it.`;
+
+export const WORKFLOW_REVIEWER_SCOPE = `This is a WORKFLOW review.
+
+Examine how the primary agent is carrying out the work. Your concern is not the internal structure of the product code except where it affects the agent’s ability to investigate, verify, or make progress.
+
+Look for patterns such as:
+
+- repeatedly reconstructing the same information;
+- repeatedly performing similar searches, traces, transformations, comparisons, or manual correlations;
+- reasoning at length about a result that could be observed, executed, queried, or measured directly;
+- using an unnecessarily slow, fragile, expensive, or low-information feedback loop;
+- recreating related one-off utilities instead of preserving and extending an existing capability;
+- repeatedly loading large amounts of context to recover relationships that could be represented compactly;
+- failing to preserve a useful intermediate result for later reuse or review;
+- taking actions that do not produce information relevant to the next decision;
+- working around the absence of a capability instead of addressing that capability gap;
+- producing conclusions that exist only in transient reasoning when an executable or structured artifact would make them reproducible.
+
+Apply a strong bias toward externalizing repeated or uncertain cognitive work into computation, direct observation, or a durable representation.
+
+A cheap, safe executable check is often preferable to mentally simulating its result. If substantially the same nontrivial operation appears a second time, treat that as strong evidence that it may deserve a reusable capability or preserved workflow. Iterating on an existing tool, script, representation, or process is generally preferable to recreating the operation.
+
+Near completion is not a reason to dismiss a workflow improvement. A durable check or representation may expose errors in the original reasoning and make the result easier to reproduce and review.
+
+A workflow proposal may describe a reusable tool, executable check, evaluation mechanism, query, index, trace, diagnostic, structured representation, or repeatable working process.
+
+The conceptual design should explain:
+
+- what recurring work it replaces or improves;
+- how it would conceptually operate;
+- what information or artifacts it would work from and produce, in ordinary planning language;
+- how it could be reused, refined, and extended instead of reinvented;
+- how it would improve evidence quality, reliability, speed, token use, reproducibility, or reviewability.
+
+Do not prescribe a particular implementation technology unless the memories make that constraint strategically important. The design should describe the capability needed, and not take over its implementation.
+
+Use submit_workflow_proposal only when the evidence supports a durable workflow design.`;
+
+export const SOFTWARE_REVIEWER_SCOPE = `This is a SOFTWARE review.
+
+Examine the structure of the software being produced. Your concern is not whether the primary agent’s personal workflow could be faster except where the memories reveal a structural problem in the product itself.
+
+Look for patterns such as:
+
+- repeated special cases reflecting the same underlying concept;
+- several bugs, patches, or workarounds involving the same missing invariant;
+- duplicated behavior, state, or policy that may drift apart;
+- unclear or unstable responsibility boundaries;
+- recurring workarounds caused by an unsuitable model or representation;
+- local changes whose interaction suggests a missing abstraction;
+- complexity caused by representing the problem incorrectly;
+- multiple components independently enforcing what appears to be one shared rule;
+- a design that obscures behavior the user expects to remain stable;
+- repeated fixes that address consequences without representing the underlying condition directly.
+
+A software proposal may describe an abstraction, invariant, responsibility boundary, state model, interface concept, decomposition, normalization, or refactoring direction.
+
+The conceptual design should explain:
+
+- the recurring structural symptom;
+- the underlying concept that may be missing or represented poorly;
+- the proposed responsibilities, relationships, and invariants;
+- what recorded behavior, user intent, and constraints must be preserved;
+- why the design could reduce special cases, duplication, contradictions, or hidden coupling;
+- important tradeoffs and uncertainties.
+
+Do not turn a single untidy implementation detail into an architectural proposal. Prefer a proposal when multiple memories reveal a recurring structure or when one especially consequential design flaw is strongly supported.
+
+Do not prescribe filenames, libraries, exact APIs, code, or an ordered implementation plan. Describe the shape of the software design and leave implementation decisions to the primary agent.
+
+Use submit_software_proposal only when the evidence supports a durable software design.`;
+
+export const REVIEWER_TERMINAL_RULES = `Reach exactly one terminal outcome.
+
+Use the proposal tool available in this review only when the evidence supports a durable structural design.
+
+Use review_concluded_no_proposal when:
+
+- the pattern appears isolated, temporary, or already resolved;
+- the evidence is too incomplete or contradictory;
+- the concern is already addressed by an existing capability, abstraction, or proposal;
+- the improvement would be generic advice rather than a concrete conceptual design;
+- the concern depends too heavily on details unavailable in memory;
+- the evidence does not support the review request’s diagnosis;
+- the likely value does not justify preserving a durable proposal.
+
+A no-proposal conclusion is a valid result. Explain what was examined and, when useful, what new evidence would justify reconsideration.
+
+Produce exactly one terminal tool call. Do not emit ordinary assistant text.`;
+
+/** Assemble only the prompt subset and terminal rules for the requested scope. */
+export function buildReviewerSystemPrompt(scope: ReviewScope): string {
+	const scopedPrompt = scope === "workflow" ? WORKFLOW_REVIEWER_SCOPE : SOFTWARE_REVIEWER_SCOPE;
+
+	return [REVIEWER_COMMON_SYSTEM, scopedPrompt, REVIEWER_TERMINAL_RULES].join("\n\n");
+}

package/src/agents/reviewer/tools.ts

@@ -0,0 +1,84 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { Type } from "@earendil-works/pi-ai";
+import type { Static, TSchema } from "typebox";
+import type { ReviewNoProposal, SoftwareReviewProposal, WorkflowReviewProposal } from "../../session-ledger/types.js";
+
+const prose = (description: string) => Type.String({ minLength: 1, description });
+
+export const WorkflowProposalSchema = Type.Object({
+	title: prose("Short natural-language name for the workflow improvement."),
+	summary: prose("Compact advisory summary suitable for the primary-agent notice."),
+	evidence: prose("Evidence grounded in cited memory or primary-chat entry ids, including relevant contrary evidence."),
+	inefficiency: prose("Recurring expensive, unreliable, or difficult-to-review work."),
+	conceptual_design: prose("High-level planning prose describing the improved capability or process; no code or implementation steps."),
+	inputs: Type.Optional(prose("Ordinary-language inputs, artifacts, context, or questions.")),
+	outputs: Type.Optional(prose("Ordinary-language outputs, evidence, artifacts, or representations.")),
+	integration: Type.Optional(prose("How the primary agent could conceptually reuse, refine, or extend it.")),
+	expected_effect: prose("Expected effect on efficiency, reliability, evidence quality, reproducibility, or reviewability."),
+	uncertainties: prose("Unknowns and tradeoffs the primary agent must evaluate."),
+});
+
+export const SoftwareProposalSchema = Type.Object({
+	title: prose("Short natural-language name for the software design improvement."),
+	summary: prose("Compact advisory summary suitable for the primary-agent notice."),
+	evidence: prose("Evidence grounded in cited memory or primary-chat entry ids, including relevant contrary evidence."),
+	structural_issue: prose("Recurring structural symptom, missing invariant, duplicated concept, or unsuitable boundary."),
+	conceptual_design: prose("High-level design of concepts, responsibilities, relationships, and invariants; no code or implementation steps."),
+	preserved_behavior: prose("User intent, visible behavior, constraints, and semantics to preserve."),
+	expected_effect: prose("Expected reduction in special cases, duplication, contradictions, coupling, or maintenance risk."),
+	uncertainties: prose("Unknowns and tradeoffs the primary agent must evaluate."),
+});
+
+export const NoProposalSchema = Type.Object({
+	reason: prose("Why a durable proposal is not currently justified."),
+	evidence_reviewed: prose("Memories and primary-chat entries examined, with ids, and the evidence supporting this conclusion."),
+	reconsider_if: Type.Optional(prose("Specific future evidence or recurrence that would justify reconsideration.")),
+});
+
+export type WorkflowProposalArgs = Static<typeof WorkflowProposalSchema>;
+export type SoftwareProposalArgs = Static<typeof SoftwareProposalSchema>;
+export type NoProposalArgs = Static<typeof NoProposalSchema>;
+export type ReviewTerminalResult = Omit<WorkflowReviewProposal, "id" | "version" | "reviewRequestId" | "createdAt" | "requestedBy"> | Omit<SoftwareReviewProposal, "id" | "version" | "reviewRequestId" | "createdAt" | "requestedBy"> | Omit<ReviewNoProposal, "id" | "version" | "reviewRequestId" | "createdAt" | "requestedBy">;
+
+function trimOptional(value: string | undefined): string | undefined {
+	const normalized = value?.trim();
+	return normalized || undefined;
+}
+
+function terminalTool<T extends TSchema>(
+	name: string,
+	label: string,
+	description: string,
+	parameters: T,
+	build: (params: Static<T>) => ReviewTerminalResult,
+	onTerminal: (result: ReviewTerminalResult) => void,
+): AgentTool<T> {
+	return {
+		name,
+		label,
+		description,
+		parameters,
+		execute: async (_id, params) => {
+			onTerminal(build(params));
+			return { content: [{ type: "text", text: "Terminal review outcome recorded." }], details: { terminal: true } };
+		},
+	};
+}
+
+export function createWorkflowProposalTool(onTerminal: (result: ReviewTerminalResult) => void): AgentTool<typeof WorkflowProposalSchema> {
+	return terminalTool("submit_workflow_proposal", "Submit workflow proposal", "Record the one durable workflow proposal for this review.", WorkflowProposalSchema, (params: WorkflowProposalArgs) => ({
+		outcome: "proposal", proposalKind: "workflow", scope: "workflow", title: params.title.trim(), summary: params.summary.trim(), evidence: params.evidence.trim(), inefficiency: params.inefficiency.trim(), conceptualDesign: params.conceptual_design.trim(), inputs: trimOptional(params.inputs), outputs: trimOptional(params.outputs), integration: trimOptional(params.integration), expectedEffect: params.expected_effect.trim(), uncertainties: params.uncertainties.trim(),
+	}), onTerminal);
+}
+
+export function createSoftwareProposalTool(onTerminal: (result: ReviewTerminalResult) => void): AgentTool<typeof SoftwareProposalSchema> {
+	return terminalTool("submit_software_proposal", "Submit software proposal", "Record the one durable software design proposal for this review.", SoftwareProposalSchema, (params: SoftwareProposalArgs) => ({
+		outcome: "proposal", proposalKind: "software", scope: "software", title: params.title.trim(), summary: params.summary.trim(), evidence: params.evidence.trim(), structuralIssue: params.structural_issue.trim(), conceptualDesign: params.conceptual_design.trim(), preservedBehavior: params.preserved_behavior.trim(), expectedEffect: params.expected_effect.trim(), uncertainties: params.uncertainties.trim(),
+	}), onTerminal);
+}
+
+export function createNoProposalTool(scope: "workflow" | "software", onTerminal: (result: ReviewTerminalResult) => void): AgentTool<typeof NoProposalSchema> {
+	return terminalTool("review_concluded_no_proposal", "Conclude no proposal", "Record that this review found no durable proposal justified.", NoProposalSchema, (params: NoProposalArgs) => ({
+		outcome: "no_proposal", scope, reason: params.reason.trim(), evidenceReviewed: params.evidence_reviewed.trim(), reconsiderIf: trimOptional(params.reconsider_if),
+	}), onTerminal);
+}

package/src/agents/stream-errors.ts

@@ -0,0 +1,22 @@
+import type { AgentEvent } from "@earendil-works/pi-agent-core";
+import { debugLog } from "../debug-log.js";
+
+/**
+ * Surface LLM failures from an agent-loop event stream.
+ *
+ * When the underlying LLM call fails, the loop ends the stream with a final
+ * assistant message whose stopReason is "error" (or "aborted") — no exception
+ * is thrown. Without this hook the drain loops treat such runs exactly like
+ * "the model chose not to call the tool", which hides the real cause
+ * (rate limits, oversized prompts, auth failures, ...) from the debug log.
+ */
+export function logAgentStreamError(stage: "observer" | "reflector" | "dropper" | "contemplator" | "reviewer", event: AgentEvent): void {
+	if (event.type !== "message_end") return;
+	const message = event.message;
+	if (message.role !== "assistant") return;
+	if (message.stopReason !== "error" && message.stopReason !== "aborted") return;
+	debugLog(`${stage}.stream_error`, {
+		stopReason: message.stopReason,
+		errorMessage: message.errorMessage,
+	});
+}

package/src/clipboard.ts

@@ -0,0 +1,63 @@
+import { spawn } from "node:child_process";
+
+export interface ClipboardCommand {
+	command: string;
+	args: string[];
+}
+
+export type ClipboardCommandRunner = (command: ClipboardCommand, text: string) => Promise<boolean>;
+
+export function getClipboardCommands(platform: NodeJS.Platform = process.platform): ClipboardCommand[] {
+	switch (platform) {
+		case "darwin":
+			return [{ command: "pbcopy", args: [] }];
+		case "win32":
+			return [{ command: "clip", args: [] }];
+		default:
+			return [
+				{ command: "wl-copy", args: [] },
+				{ command: "xclip", args: ["-selection", "clipboard"] },
+				{ command: "xsel", args: ["--clipboard", "--input"] },
+				{ command: "termux-clipboard-set", args: [] },
+			];
+	}
+}
+
+export async function copyTextToClipboard(
+	text: string,
+	runner: ClipboardCommandRunner = runClipboardCommand,
+	commands: ClipboardCommand[] = getClipboardCommands(),
+): Promise<boolean> {
+	for (const command of commands) {
+		if (await runner(command, text)) return true;
+	}
+	return false;
+}
+
+export function runClipboardCommand(command: ClipboardCommand, text: string): Promise<boolean> {
+	return new Promise((resolve) => {
+		let settled = false;
+		let timeout: ReturnType<typeof setTimeout> | undefined;
+
+		const finish = (ok: boolean) => {
+			if (settled) return;
+			settled = true;
+			if (timeout) clearTimeout(timeout);
+			resolve(ok);
+		};
+
+		const child = spawn(command.command, command.args, {
+			stdio: ["pipe", "ignore", "ignore"],
+		});
+
+		timeout = setTimeout(() => {
+			child.kill();
+			finish(false);
+		}, 2_000);
+
+		child.on("error", () => finish(false));
+		child.on("close", (code) => finish(code === 0));
+		child.stdin.on("error", () => undefined);
+		child.stdin.end(text, "utf8");
+	});
+}

package/src/commands/contemplator-view.ts

@@ -0,0 +1,128 @@
+import type { Entry } from "../session-ledger/index.js";
+
+const CONTEMPLATOR_MESSAGE = "om.contemplator.message";
+const CONTEMPLATOR_SUGGESTION = "om.contemplator.suggestion";
+const REVIEW_REQUEST = "om.review.request";
+const REVIEW_RESULT = "om.review.result";
+const DIM = "\x1b[2m";
+const RESET = "\x1b[0m";
+
+type MessagePart = {
+	type?: unknown;
+	text?: unknown;
+	name?: unknown;
+	arguments?: unknown;
+	content?: unknown;
+};
+
+type StoredMessage = {
+	role?: unknown;
+	content?: unknown;
+};
+
+function estimateTokens(value: unknown): number {
+	return Math.max(1, Math.ceil(JSON.stringify(value).length / 4));
+}
+
+function renderValue(value: unknown): string {
+	if (typeof value === "string") return value;
+	if (value === undefined || value === null) return "";
+	return JSON.stringify(value, null, 2);
+}
+
+function renderContent(content: unknown): string {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return renderValue(content);
+	return content
+		.map((part: MessagePart) => {
+			if (part.type === "text") return typeof part.text === "string" ? part.text : "";
+			if (part.type === "toolCall" || part.type === "tool_use" || part.type === "toolUse") {
+				const name = typeof part.name === "string" ? part.name : "unknown tool";
+				const args = part.arguments === undefined ? "" : ` ${renderValue(part.arguments)}`;
+				return `[tool call: ${name}${args}]`;
+			}
+			if (part.type === "toolResult" || part.type === "tool_result") {
+				return `[tool result]\n${renderValue(part.content)}`;
+			}
+			return `[${String(part.type ?? "content")}] ${renderValue(part)}`;
+		})
+		.filter(Boolean)
+		.join("\n");
+}
+
+function renderMessage(message: StoredMessage, compacted: boolean): string {
+	const role = typeof message.role === "string" ? message.role : "unknown";
+	const tokens = estimateTokens(message);
+	const marker = compacted ? " [compacted summary]" : "";
+	return `${DIM}── ${role}${marker} · ~${tokens} tokens ──${RESET}\n${renderContent(message.content) || `${DIM}(empty message)${RESET}`}`;
+}
+
+export function renderContemplator(entries: Entry[]): string {
+	const messages: Array<{ message: StoredMessage; compacted: boolean }> = [];
+	const suggestions: Array<{ suggestion: string; delivered: boolean }> = [];
+	const reviews: Array<{ requestId: string; scope: string; outcome: string; memoryId?: string }> = [];
+	const suggestionIndexByProbeId = new Map<string, number>();
+	for (const entry of entries) {
+		if (entry.customType === CONTEMPLATOR_MESSAGE && entry.data && typeof entry.data === "object") {
+			const data = entry.data as { message?: unknown; compacted?: unknown };
+			if (data.message && typeof data.message === "object") {
+				messages.push({ message: data.message as StoredMessage, compacted: data.compacted === true });
+			}
+		}
+		if (entry.customType === REVIEW_REQUEST && entry.data && typeof entry.data === "object") {
+			const request = (entry.data as { request?: { id?: unknown; scope?: unknown } }).request;
+			if (typeof request?.id === "string" && typeof request.scope === "string") reviews.push({ requestId: request.id, scope: request.scope, outcome: "pending" });
+		}
+		if (entry.customType === REVIEW_RESULT && entry.data && typeof entry.data === "object") {
+			const result = (entry.data as { result?: { reviewRequestId?: unknown; scope?: unknown; outcome?: unknown; id?: unknown } }).result;
+			if (typeof result?.reviewRequestId === "string" && typeof result.scope === "string" && typeof result.outcome === "string") {
+				const existing = reviews.find((review) => review.requestId === result.reviewRequestId);
+				const review = { requestId: result.reviewRequestId, scope: result.scope, outcome: result.outcome, memoryId: typeof result.id === "string" ? result.id : undefined };
+				if (existing) Object.assign(existing, review); else reviews.push(review);
+			}
+		}
+		if (entry.customType === CONTEMPLATOR_SUGGESTION && entry.data && typeof entry.data === "object") {
+			const data = entry.data as { suggestion?: unknown; delivered?: unknown; probeId?: unknown };
+			if (typeof data.suggestion !== "string") continue;
+			const suggestion = { suggestion: data.suggestion, delivered: data.delivered === true };
+			if (typeof data.probeId !== "string") {
+				suggestions.push(suggestion);
+				continue;
+			}
+			const existingIndex = suggestionIndexByProbeId.get(data.probeId);
+			if (existingIndex === undefined) {
+				suggestionIndexByProbeId.set(data.probeId, suggestions.length);
+				suggestions.push(suggestion);
+			} else {
+				suggestions[existingIndex] = suggestion;
+			}
+		}
+	}
+
+	const totalTokens = messages.reduce((total, item) => total + estimateTokens(item.message), 0);
+	const lines = [
+		`${DIM}CONTEMPLATOR · ${messages.length} messages · ~${totalTokens} estimated tokens${RESET}`,
+		"",
+	];
+	if (messages.length === 0) {
+		lines.push(`${DIM}No contemplator messages recorded on this branch.${RESET}`);
+	} else {
+		messages.forEach((item, index) => {
+			if (index > 0) lines.push("");
+			lines.push(renderMessage(item.message, item.compacted));
+		});
+	}
+	if (suggestions.length > 0) {
+		lines.push("", `${DIM}── Probes ──${RESET}`);
+		for (const item of suggestions) lines.push(`${item.delivered ? "[delivered]" : "[pending]"} ${item.suggestion}`);
+	}
+	if (reviews.length > 0) {
+		lines.push("", `${DIM}── Structural reviews ──${RESET}`);
+		for (const review of reviews) lines.push(`[${review.outcome}] ${review.scope} ${review.requestId}${review.memoryId ? ` → [${review.memoryId}]` : ""}`);
+	}
+	return lines.join("\n");
+}
+
+export function stripAnsi(value: string): string {
+	return value.replace(/\x1b\[[0-9;]*m/g, "");
+}

package/src/commands/reviewer-view.ts

@@ -0,0 +1,89 @@
+import type { Entry } from "../session-ledger/index.js";
+
+const REVIEWER_MESSAGE = "om.reviewer.message";
+const REVIEWER_NOTICE = "om.reviewer.notice";
+const REVIEW_RESULT = "om.review.result";
+const DIM = "\x1b[2m";
+const RESET = "\x1b[0m";
+
+type StoredMessage = { role?: unknown; content?: unknown };
+type ContentPart = { type?: unknown; text?: unknown; name?: unknown; arguments?: unknown; content?: unknown };
+
+type ReviewerRun = {
+	requestId: string;
+	scope: string;
+	messages: StoredMessage[];
+	notice?: string;
+	outcome?: string;
+	memoryId?: string;
+};
+
+function renderValue(value: unknown): string {
+	if (typeof value === "string") return value;
+	if (value === undefined || value === null) return "";
+	return JSON.stringify(value, null, 2);
+}
+
+function renderContent(content: unknown): string {
+	if (!Array.isArray(content)) return renderValue(content);
+	return content.map((part: ContentPart) => {
+		if (part.type === "text") return typeof part.text === "string" ? part.text : "";
+		if (part.type === "toolCall" || part.type === "tool_use" || part.type === "toolUse") {
+			return `[tool call: ${typeof part.name === "string" ? part.name : "unknown tool"}${part.arguments === undefined ? "" : ` ${renderValue(part.arguments)}`}]`;
+		}
+		if (part.type === "toolResult" || part.type === "tool_result") return `[tool result]\n${renderValue(part.content)}`;
+		return `[${String(part.type ?? "content")}] ${renderValue(part)}`;
+	}).filter(Boolean).join("\n");
+}
+
+function runFor(runs: Map<string, ReviewerRun>, requestId: string, scope = "unknown"): ReviewerRun {
+	let run = runs.get(requestId);
+	if (!run) {
+		run = { requestId, scope, messages: [] };
+		runs.set(requestId, run);
+	}
+	return run;
+}
+
+/** Render persisted reviewer assistant/tool output and the proposal notice, if one was queued. */
+export function renderReviewer(entries: Entry[]): string {
+	const runs = new Map<string, ReviewerRun>();
+	for (const entry of entries) {
+		if (!entry.data || typeof entry.data !== "object") continue;
+		const data = entry.data as { reviewRequestId?: unknown; scope?: unknown; message?: unknown; content?: unknown; result?: unknown; reviewMemoryId?: unknown };
+		const result = entry.customType === REVIEW_RESULT && data.result && typeof data.result === "object"
+			? data.result as { reviewRequestId?: unknown; scope?: unknown; outcome?: unknown; id?: unknown }
+			: undefined;
+		let requestId: string | undefined;
+		if (typeof data.reviewRequestId === "string") requestId = data.reviewRequestId;
+		else if (typeof result?.reviewRequestId === "string") requestId = result.reviewRequestId;
+		if (!requestId) continue;
+		let scope = "unknown";
+		if (typeof data.scope === "string") scope = data.scope;
+		else if (typeof result?.scope === "string") scope = result.scope;
+		const run = runFor(runs, requestId, scope);
+		if (entry.customType === REVIEWER_MESSAGE && data.message && typeof data.message === "object") run.messages.push(data.message as StoredMessage);
+		if (entry.customType === REVIEWER_NOTICE && typeof data.content === "string") run.notice = data.content;
+		if (result) {
+			if (typeof result.outcome === "string") run.outcome = result.outcome;
+			if (typeof result.id === "string") run.memoryId = result.id;
+		}
+	}
+
+	const lines = [`${DIM}STRUCTURAL REVIEWER · ${runs.size} review run${runs.size === 1 ? "" : "s"}${RESET}`, ""];
+	if (runs.size === 0) {
+		lines.push(`${DIM}No reviewer output recorded on this branch.${RESET}`);
+		return lines.join("\n");
+	}
+	for (const run of runs.values()) {
+		lines.push(`${DIM}── ${run.scope} review ${run.requestId}${run.outcome ? ` · ${run.outcome}` : " · pending"}${run.memoryId ? ` · [${run.memoryId}]` : ""} ──${RESET}`);
+		if (run.messages.length === 0) lines.push(`${DIM}(no assistant output recorded)${RESET}`);
+		for (const message of run.messages) {
+			const role = typeof message.role === "string" ? message.role : "assistant";
+			lines.push(`${DIM}${role}${RESET}\n${renderContent(message.content) || `${DIM}(empty message)${RESET}`}`);
+		}
+		if (run.notice) lines.push(`${DIM}Primary-agent notice queued${RESET}\n${run.notice}`);
+		lines.push("");
+	}
+	return lines.join("\n").trimEnd();
+}