@matthewfl/pi-contemplator 0.0.10 → 0.1.1

package/src/agents/contemplator/prompts.ts

@@ -6,7 +6,7 @@ export function buildContemplatorSystemPrompt(
 
 Neither you nor the primary agent should be assumed to know the correct solution. You are jointly exploring a problem space from different perspectives. The primary agent interacts with the actual environment and carries out the work. You maintain a longer-term view of the reasoning, evidence, assumptions, alternatives, unresolved questions${reviewerEnabled ? ", and recurring structural patterns" : ""} that emerge over time.
 
-You receive incremental observations and reflections produced by other agent loops. Some memories summarize user messages. Pay extra attention to memories about the user’s intent, priorities, constraints, corrections, and desired outcome.
+You receive incremental observations and cited summaries produced by other agent loops. Some memories summarize user messages. Pay extra attention to memories about the user’s intent, priorities, constraints, corrections, and desired outcome.
 
 You see only the memory ledger, not the primary agent’s live activity. Your understanding may be incomplete or slightly stale. Do not infer inactivity, failure, or lack of progress from missing recent results. A result may simply not have reached memory yet.
 
@@ -42,7 +42,7 @@ Do not treat the absence of a recent test result, tool result, or implementation
 
 Do not encourage speculation merely because several possibilities can be imagined. When the user’s direction is clear and action is cheap, safe, and reversible, direct progress may be more informative than further hypothesis formation. Distinguish uncertainty that must be resolved before proceeding from uncertainty that can be resolved naturally by doing the work.
 
-Your other high-value responsibility is reality-checking. Compare recent claims, interpretations, and assumptions with earlier recorded evidence. When a recent claim conflicts with an earlier observation, reflection, user-intent memory, or previously supported conclusion, make the contradiction visible and cite the memories on both sides.
+Your other high-value responsibility is reality-checking. Compare recent claims, interpretations, and assumptions with earlier recorded evidence. When a recent claim conflicts with an earlier observation, summary, user-intent memory, or previously supported conclusion, make the contradiction visible and cite the memories on both sides.
 
 Also look for opportunities to help the primary agent:
 
@@ -72,7 +72,7 @@ A useful probe may ask:
 
 Questions should be grounded in the actual memories rather than generic problem-solving advice.
 
-You have access to search_memories for finding older ${reviewerEnabled ? `observations, reflections, and durable review results` : `observations and reflections`} on the current branch. Use it when the updates provided do not contain enough context, searching with distinctive terms rather than broad questions. Results include memory identifiers that you can cite in a probe${reviewerEnabled ? ` or review request` : ``}.
+You have access to search_memories for finding older ${reviewerEnabled ? `observations, summaries, and durable review results` : `observations and summaries`} on the current branch. Use it when the updates provided do not contain enough context, searching with distinctive terms rather than broad questions. Results include memory identifiers that you can cite in a probe${reviewerEnabled ? ` or review request` : ``}.
 
 You also have recall for recovering exact source context behind a specific memory identifier. Use it when a result is important but compressed.
 
@@ -185,8 +185,8 @@ A good review request should:
 }
 
 ${reviewerEnabled ?
-`Your interventions are asynchronous. Use no more than one intervention per update: either send_probe, request_review, or neither.` :
-`Your probes are delivered asynchronously. Send no more than one probe per update.`}
+`Your interventions are asynchronous. You must finish every update by calling one final-action tool: send_probe, request_review, or no_intervention. This requirement is bookkeeping, not pressure to intervene. no_intervention takes no arguments and is the preferred default whenever no specific, grounded, materially useful intervention is clearly warranted or usefulness is uncertain. Never send a probe merely to satisfy the tool requirement. A valid final-action call ends your turn immediately, so do not plan to add narration afterward. If an intervention tool reports an invalid memory citation, correct it and call the appropriate tool again; the later call replaces the earlier one.` :
+`Your probes are delivered asynchronously. You must finish every update by calling one final-action tool: send_probe or no_intervention. This requirement is bookkeeping, not pressure to intervene. no_intervention takes no arguments and is the preferred default whenever no specific, grounded, materially useful probe is clearly warranted or usefulness is uncertain. Never send a probe merely to satisfy the tool requirement. A valid final-action call ends your turn immediately, so do not plan to add narration afterward. If send_probe reports an invalid memory citation, correct it and call send_probe again; the later call replaces the earlier one.`}
 
 Prioritize:
 
@@ -203,7 +203,7 @@ ${
     : ``
 }
 
-If no specific, grounded, materially useful intervention exists, do not call an intervention tool.`
+If no specific, grounded, materially useful intervention clearly exists, or if its usefulness is uncertain, call the argument-free no_intervention tool.`
     .replace(/\n{3,}/g, "\n\n")
     .trim();
 }

package/src/agents/observer/agent.ts

@@ -1,4 +1,4 @@
-import { agentLoop, type AgentContext, type AgentLoopConfig, type AgentTool } from "@earendil-works/pi-agent-core";
+import { agentLoop, type AgentContext, type AgentLoopConfig, type AgentMessage, type AgentTool } from "@earendil-works/pi-agent-core";
 import type { Message, Model, ModelThinkingLevel } from "@earendil-works/pi-ai";
 import { Type } from "@earendil-works/pi-ai";
 import { streamSimple } from "@earendil-works/pi-ai/compat";
@@ -8,7 +8,7 @@ import { logAgentStreamError } from "../stream-errors.js";
 import { AGENT_LOOP_MAX_TOKENS, boundedMaxTokens } from "../../model-budget.js";
 import { OBSERVER_SYSTEM } from "./prompts.js";
 import { nowTimestamp, truncateRecordContent } from "../../serialize.js";
-import type { Observation, Relevance } from "../../session-ledger/index.js";
+import type { Observation, Relevance, Retention } from "../../session-ledger/index.js";
 import { estimateStringTokens } from "../../tokens.js";
 import type { LlmUsageInput } from "../../runtime.js";
 
@@ -16,7 +16,7 @@ interface RunObserverArgs {
 	model: Model<any>;
 	apiKey: string;
 	headers?: Record<string, string>;
-	priorReflections: string[];
+	priorSummaries?: string[];
 	priorObservations: string[];
 	chunk: string;
 	allowedSourceEntryIds: string[];
@@ -34,6 +34,12 @@ const RelevanceSchema = Type.Union([
 	Type.Literal("critical"),
 ]);
 
+const RetentionSchema = Type.Union([
+	Type.Literal("ephemeral"),
+	Type.Literal("contextual"),
+	Type.Literal("durable"),
+]);
+
 export const OBSERVATION_TIMESTAMP_PATTERN = "^[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}$";
 
 const RecordObservationsSchema = Type.Object({
@@ -48,6 +54,7 @@ const RecordObservationsSchema = Type.Object({
 				description: "Single-line plain prose. No markdown, no tags, no embedded timestamp.",
 			}),
 			relevance: RelevanceSchema,
+			retention: Type.Optional(RetentionSchema),
 			sourceEntryIds: Type.Array(
 				Type.String({ minLength: 1 }),
 				{
@@ -64,6 +71,16 @@ const RecordObservationsSchema = Type.Object({
 
 type RecordObservationsArgs = Static<typeof RecordObservationsSchema>;
 
+/** A terminal provider/agent-loop failure that must not advance observation coverage. */
+export class ObserverStreamError extends Error {
+	readonly stopReason: string;
+	constructor(stopReason: string, errorMessage?: string) {
+		super(`observer stream ended with stopReason "${stopReason}"${errorMessage ? `: ${errorMessage}` : ""}`);
+		this.name = "ObserverStreamError";
+		this.stopReason = stopReason;
+	}
+}
+
 function joinOrEmpty(items: string[]): string {
 	return items.length ? items.join("\n") : "(none yet)";
 }
@@ -86,19 +103,20 @@ export function normalizeSourceEntryIds(
 }
 
 export async function runObserver(args: RunObserverArgs): Promise<Observation[] | undefined> {
-	const { model, apiKey, headers, priorReflections, priorObservations, chunk, allowedSourceEntryIds, signal } = args;
+	const { model, apiKey, headers, priorSummaries = [], priorObservations, chunk, allowedSourceEntryIds, signal } = args;
 	const conversation = chunk.trim();
 	if (!conversation) return undefined;
 
 	const accumulated = new Map<string, Observation>();
+	let rejectedTotal = 0;
+	let doneCalled = false;
 
 	const recordObservations: AgentTool<typeof RecordObservationsSchema> = {
 		name: "record_observations",
 		label: "Record observations",
 		description:
 			"Record a batch of new observations distilled from the conversation chunk. " +
-			"Call this multiple times as you work through the chunk. Stop calling when coverage is complete, " +
-			"then emit a short plain-text confirmation to end the run.",
+			"Call this multiple times as you work through the chunk, then call done alone when coverage is complete.",
 		parameters: RecordObservationsSchema,
 		execute: async (_id, params: RecordObservationsArgs) => {
 			let added = 0;
@@ -121,11 +139,13 @@ export async function runObserver(args: RunObserverArgs): Promise<Observation[]
 					content,
 					timestamp: obs.timestamp,
 					relevance: obs.relevance as Relevance,
+					retention: (obs.retention ?? "contextual") as Retention,
 					sourceEntryIds,
 					tokenCount: estimateStringTokens(content),
 				});
 				added++;
 			}
+			rejectedTotal += rejected;
 			const rejectedPart = rejected > 0
 				? ` ${rejected} observation${rejected === 1 ? "" : "s"} rejected for missing or invalid sourceEntryIds.`
 				: "";
@@ -134,74 +154,111 @@ export async function runObserver(args: RunObserverArgs): Promise<Observation[]
 				(duplicates > 0 ? `(${duplicates} duplicate${duplicates === 1 ? "" : "s"} skipped).` : ".") +
 				rejectedPart +
 				` Total so far this run: ${accumulated.size}. ` +
-				`Continue if the chunk still has uncovered content; otherwise stop calling the tool and emit a short plain-text confirmation.`;
+				`Continue if the chunk still has uncovered content; otherwise call done alone.`;
 			return { content: [{ type: "text", text: ack }], details: { added, duplicates, rejected, total: accumulated.size } };
 		},
 	};
 
+	const doneTool: AgentTool<any> = {
+		name: "done",
+		label: "Done",
+		description: "Confirm that the entire provided conversation chunk has been inspected and all useful new observations have been recorded. Call alone, including when there is nothing new to record.",
+		parameters: Type.Object({}),
+		execute: async () => {
+			doneCalled = true;
+			return { content: [{ type: "text", text: "Observer coverage confirmed." }], details: {}, terminate: true };
+		},
+	};
+
 	const now = nowTimestamp();
 	const userText = `Current local time: ${now}
 
-CURRENT REFLECTIONS:
-${joinOrEmpty(priorReflections)}
+CURRENT SUMMARIES:
+${joinOrEmpty(priorSummaries)}
 
 CURRENT OBSERVATIONS:
 ${joinOrEmpty(priorObservations)}
 
-Compress the following new conversation chunk into observations by calling record_observations one or more times. Do not restate facts already present in current reflections or current observations. Prefer inline conversation timestamps when assigning times; fall back to the current local time above only if no message timestamp applies. Stop calling the tool and reply with a short plain-text confirmation once the chunk is fully covered.
+Compress the following new conversation chunk into observations by calling record_observations one or more times. Do not restate facts already present in current summaries or current observations. Prefer inline conversation timestamps when assigning times; fall back to the current local time above only if no message timestamp applies. When the chunk is fully covered, call done alone. If the chunk contains no useful new information, call done without calling record_observations.
 
 NEW CONVERSATION CHUNK:
 ${conversation}`;
 
-	const prompts: Message[] = [
-		{
-			role: "user",
-			content: [{ type: "text", text: userText }],
-			timestamp: Date.now(),
-		},
-	];
-
-	const context: AgentContext = {
-		systemPrompt: OBSERVER_SYSTEM,
-		messages: [],
-		tools: [recordObservations as AgentTool<any>],
+	const initialPrompt: Message = {
+		role: "user",
+		content: [{ type: "text", text: userText }],
+		timestamp: Date.now(),
 	};
 
 	const reasoning = (model as { reasoning?: unknown }).reasoning;
 	const thinkingLevel = args.thinkingLevel ?? "low";
 	const effectiveMaxTurns = args.maxTurns && args.maxTurns > 0 ? args.maxTurns : undefined;
 	let turnCount = 0;
-	const config: AgentLoopConfig = {
+	const baseConfig: AgentLoopConfig = {
 		model,
 		apiKey,
 		headers,
 		maxTokens: boundedMaxTokens(model, AGENT_LOOP_MAX_TOKENS),
 		convertToLlm: (msgs) => msgs as Message[],
 		toolExecution: "sequential",
+		shouldStopAfterTurn: () => {
+			turnCount++;
+			return doneCalled || (effectiveMaxTurns !== undefined && turnCount >= effectiveMaxTurns);
+		},
 		...(reasoning && thinkingLevel !== "off" ? { reasoning: thinkingLevel } : {}),
-		...(effectiveMaxTurns !== undefined
-			? {
-				shouldStopAfterTurn: () => {
-					turnCount++;
-					return turnCount >= effectiveMaxTurns;
-				},
-			}
-			: {}),
 	};
 
 	const loop = args.agentLoop ?? agentLoop;
-	const stream = loop(prompts, context, config, signal, streamSimple);
-	for await (const event of stream) {
-		// Drain events; the tool's execute already collects records.
-		logAgentStreamError("observer", event);
-	}
-	const result = await stream.result();
-	if (args.recordUsage) {
+	const history: AgentMessage[] = [];
+	let terminalFailure: { stopReason: string; errorMessage?: string } | undefined;
+	const runInvocation = async (prompt: Message): Promise<void> => {
+		const context: AgentContext = {
+			systemPrompt: OBSERVER_SYSTEM,
+			messages: history.slice(),
+			tools: [recordObservations as AgentTool<any>, doneTool],
+		};
+		const stream = loop([prompt], context, baseConfig, signal, streamSimple);
+		for await (const event of stream) {
+			logAgentStreamError("observer", event);
+			const message = (event as { message?: { role?: string; stopReason?: string; errorMessage?: string } }).message;
+			if (message?.role === "assistant" && ["error", "aborted", "length"].includes(message.stopReason ?? "")) {
+				terminalFailure = { stopReason: message.stopReason!, errorMessage: message.errorMessage };
+			}
+		}
+		const result = await stream.result();
+		if (!Array.isArray(result)) return;
+		history.push(...result);
 		for (const message of result) {
-			if (message.role === "assistant" && message.usage) args.recordUsage(message.usage);
+			if (message.role === "assistant" && ["error", "aborted", "length"].includes(message.stopReason ?? "")) {
+				terminalFailure = { stopReason: message.stopReason, errorMessage: message.errorMessage };
+			}
+			if (args.recordUsage && message.role === "assistant" && message.usage) args.recordUsage(message.usage);
 		}
+	};
+
+	await runInvocation(initialPrompt);
+	if (accumulated.size === 0 && !doneCalled && !terminalFailure && rejectedTotal === 0) {
+		const reminder: Message = {
+			role: "user",
+			content: [{ type: "text", text: `You stopped without confirming coverage. Observations recorded so far: ${accumulated.size}. If the chunk is fully covered, call done now. Otherwise call record_observations for anything still missing, then call done.` }],
+			timestamp: Date.now(),
+		};
+		await runInvocation(reminder);
 	}
 
+	// Accepted observations remain useful even if the model neglected the final
+	// confirmation. Zero-observation coverage is advanced only by an explicit
+	// done call; failures, truncation, malformed records, and repeated prose do
+	// not silently discard the source chunk.
+	if (accumulated.size === 0 && terminalFailure) {
+		throw new ObserverStreamError(terminalFailure.stopReason, terminalFailure.errorMessage);
+	}
+	if (accumulated.size === 0 && rejectedTotal > 0) {
+		throw new ObserverStreamError("invalid_observations", `${rejectedTotal} proposed observation${rejectedTotal === 1 ? " was" : "s were"} rejected`);
+	}
+	if (accumulated.size === 0 && !doneCalled) {
+		throw new ObserverStreamError("incomplete", "observer stopped twice without recording observations or calling done");
+	}
 	if (accumulated.size === 0) return undefined;
 	return Array.from(accumulated.values());
 }

package/src/agents/observer/prompts.ts

@@ -2,29 +2,30 @@ export const OBSERVER_SYSTEM = `You are the observation agent for a coding assis
 
 These records are the ONLY information the assistant will have about past interactions once the raw conversation is compacted out of context. Anything you do not capture here will be forgotten. Anything you distort here will be remembered wrong. Take this seriously.
 
-Your job is to compress a chunk of recent conversation into timestamped, rated observations by calling the record_observations tool. The observations you emit — together with the reflections crystallized from them — are the assistant's ONLY memory of this session after the raw conversation falls out of context.
+Your job is to compress a chunk of recent conversation into timestamped observations with separate relevance and retention judgments by calling the record_observations tool. The observations you emit — together with cited summaries compressed from them — are the assistant's ONLY memory of this session after the raw conversation falls out of context.
 
 You receive:
-- Current reflections (long-lived facts already crystallized).
+- Current summaries (compressed memories already recorded).
 - Current observations (already-recorded observations, each shown as "[id] YYYY-MM-DD HH:MM [relevance] content").
 - A new chunk of conversation with source entry labels and inline message timestamps. Each source block starts with "[Source entry id: <id>]" followed by content formatted as "[User @ YYYY-MM-DD HH:MM]:", "[Assistant @ ...]:", "[Tool result for <name> @ ...]:", custom messages, or branch summaries.
 - A current local time fallback for observations that have no obvious message timestamp.
 
 How you work:
-1. Read reflections and current observations so you know what is already captured.
+1. Read summaries and current observations so you know what is already captured.
 2. Read the conversation chunk and identify what new information it contains.
 3. Call record_observations with a batch covering part (or all) of the chunk.
 4. Read the progress receipt. If content remains uncovered, call again. You may call the tool many times.
-5. When the chunk is fully covered, STOP calling the tool and reply with a brief plain-text confirmation (one short sentence). That ends the run.
+5. When the chunk is fully covered, call done alone. If there is no useful new information, call done without calling record_observations. Prose does not confirm coverage.
 
 What to emit:
-- Produce NEW observations for the new chunk only. Do not restate facts already present in reflections or current observations unless something has materially changed.
+- Produce NEW observations for the new chunk only. Do not restate facts already present in summaries or current observations unless something has materially changed.
 - Use the timestamp from the relevant conversation message. Fall back to current local time ONLY when no message timestamp applies.
 - For every observation, include sourceEntryIds: the smallest exact set of "[Source entry id: ...]" ids that directly support the observation.
 - Never invent source entry ids. Use only ids printed in the chunk. If an observation spans multiple turns or tool results, include every supporting source entry id.
+- For every observation, choose retention independently from relevance. Recording the observation correctly comes first; never skip useful evidence because retention is uncertain.
 - Observations with missing, empty, or invalid sourceEntryIds will be rejected and not recorded, so do not call record_observations until you can cite valid source ids.
 - Group repeated similar tool calls into a single observation rather than one per call.
-- Skip routine, low-information events. It is fine to emit zero observations if the chunk carries no new information — in that case, simply do not call the tool and end with a plain-text confirmation.
+- Skip routine, low-information events. It is fine to emit zero observations if the chunk carries no new information — in that case, do not call record_observations and call done alone. Ignoring a chunk or replying in prose does not mark it covered.
 
 Observation content rules:
 
@@ -57,7 +58,7 @@ Use precise action verbs. Replace vague verbs with ones that clarify the nature
 Frame state changes as supersession so the old state is explicit.
   BAD:  User prefers React Query now.
   GOOD: User will use React Query (switching from SWR).
-Why this matters: without supersession framing, the reflector may crystallize both the old and the new as equally valid preferences.
+Why this matters: without supersession framing, a later summary may preserve both the old and the new as equally valid preferences.
 
 Mark concrete completions explicitly.
 Use "completed:", "resolved:", "confirmed working", or similar phrasing so future runs know not to redo the work.
@@ -73,7 +74,7 @@ If a single message contains multiple independent facts, intents, or events, emi
   GOOD: User started a new job. + User will move to a new apartment next week.
   BAD:  Assistant recommended Lucia, NextAuth, and Clerk for auth, and user chose Lucia.
   GOOD: Assistant recommended auth libraries: Lucia (session-based, minimal), NextAuth (OAuth-heavy, Next-native), Clerk (hosted, paid). + User chose Lucia.
-Why this matters: a future query like "which auth library did the user pick?" can match a single-fact observation cleanly; a compound observation hides the decision inside a recommendation list.
+Why this matters: a future query like "which auth library did the user pick?" can match a single-fact observation cleanly; a compound observation hides the decision inside a recommendation list and makes safe summarization harder.
 
 Group repeated similar tool calls into a single observation rather than one per call.
   BAD:  Agent viewed src/auth.ts. Agent viewed src/users.ts. Agent viewed src/routes.ts.
@@ -104,10 +105,18 @@ Relevance levels (pick one per observation; this field drives future dropping):
 - critical: user assertions about identity, role, or persistent preferences; explicit corrections ("no, don't do X"); concrete completions that future runs MUST NOT redo. These are highest-resistance, load-bearing observations and require the strongest evidence before leaving active memory. Why this matters: if a "critical" item is lost, the assistant may redo finished work, contradict a correction, or misrepresent who the user is.
 - high: non-trivial technical decisions, architectural direction, unresolved blockers, key constraints. Worth keeping across many compactions.
 - medium: task-level context that helps within the current work but isn't durable. The default when you are unsure between medium and high.
-- low: routine tool-call acks, repetitive status updates, content trivially re-derivable from recent messages. The dropper will drop these first.
+- low: routine tool-call acks, repetitive status updates, content trivially re-derivable from recent messages. The summarizer considers relevance together with retention, age, and later evidence.
 
 Do NOT default to "critical" or "high". Most observations are medium or low. Reserve "critical" for things that would cause real damage if forgotten.
 
+Retention horizons (pick one independently from relevance):
+
+- ephemeral: likely useful for only the next few steps; intermediate attempts, routine outputs, temporary readings, and local status.
+- contextual: useful while related work continues or may soon resume; exact errors, hypotheses, partial state, subsystem details, and unresolved local choices. Use this when uncertain.
+- durable: likely useful across context changes; persistent preferences, constraints, corrections, decisions, rationale, reusable findings, and significant outcomes.
+
+A critical exact blocker can be contextual; a medium stable preference can be durable. Retention is a hint for summarizer sampling and judgment, never an instruction for code to remove anything automatically. Notice factual transitions—replacement, abandonment, resolution, moving away from a subject, resuming it, or invalidating an old result—but record the transition as ordinary evidence rather than commands to the summarizer.
+
   BAD:  relevance=critical for "Agent ran tests and they passed."
   GOOD: relevance=low for "Agent ran tests and they passed." (routine; captured by a completion observation if it matters)
 
@@ -116,4 +125,4 @@ Do NOT default to "critical" or "high". Most observations are medium or low. Res
 
 Timestamp format: "YYYY-MM-DD HH:MM" (local time, 24-hour, to the minute). This goes in the timestamp field, not the content.
 
-Remember: these observations are the assistant's ONLY memory of this chunk once the raw messages fall out of context. Make them count.`;
+Remember: these observations are the assistant's ONLY memory of this chunk once the raw messages fall out of context. Make them count. Always finish by calling done alone.`;

package/src/agents/reviewer/agent.ts

@@ -4,6 +4,7 @@ import { streamSimple } from "@earendil-works/pi-ai/compat";
 import { hashId } from "../../ids.js";
 import { boundedMaxTokens, REVIEWER_TOTAL_TOKEN_LIMIT } from "../../model-budget.js";
 import type { LlmUsageInput } from "../../runtime.js";
+import { recallMemorySources } from "../../session-ledger/recall.js";
 import type { Entry, ReviewResult, StructuralReviewRequest } from "../../session-ledger/types.js";
 import { createRecallAgentTool } from "../../tools/recall-observation.js";
 import { createSearchMemoriesAgentTool } from "../../tools/search-memories.js";
@@ -94,18 +95,30 @@ function budgetExhaustedResult(request: StructuralReviewRequest): ReviewResult {
 
 export async function runStructuralReview(args: RunStructuralReviewArgs): Promise<ReviewResult | undefined> {
 	let terminal: ReviewTerminalResult | undefined;
-	const acceptTerminal = (candidate: ReviewTerminalResult): void => {
+	let warnedTerminal: ReviewTerminalResult | undefined;
+	const acceptTerminal = (candidate: ReviewTerminalResult, missingReferenceIds: string[]) => {
 		if (terminal) throw new Error("A structural reviewer may make only one terminal tool call.");
+		const overwritten = warnedTerminal !== undefined;
+		if (missingReferenceIds.length > 0) {
+			warnedTerminal = candidate;
+			return { terminal: false, overwritten };
+		}
 		terminal = candidate;
+		warnedTerminal = undefined;
+		return { terminal: true, overwritten };
+	};
+	const referenceExists = (id: string): boolean => {
+		const branch = args.getBranch();
+		return branch.some((entry) => entry.id === id) || recallMemorySources(branch, id).status === "found";
 	};
 	const searchMemories = createSearchMemoriesAgentTool(args.getBranch);
 	const recall = createRecallAgentTool(args.getBranch);
 	const searchChatHistory = createSearchChatHistoryAgentTool(args.getBranch);
 	const readChatHistory = createReadChatHistoryAgentTool(args.getBranch);
 	const scopeTool = args.request.scope === "workflow"
-		? createWorkflowProposalTool(acceptTerminal)
-		: createSoftwareProposalTool(acceptTerminal);
-	const noProposal = createNoProposalTool(args.request.scope, acceptTerminal);
+		? createWorkflowProposalTool(acceptTerminal, referenceExists)
+		: createSoftwareProposalTool(acceptTerminal, referenceExists);
+	const noProposal = createNoProposalTool(args.request.scope, acceptTerminal, referenceExists);
 	const tools = [
 		searchMemories as AgentTool<any>,
 		recall as AgentTool<any>,
@@ -179,6 +192,13 @@ export async function runStructuralReview(args: RunStructuralReviewArgs): Promis
 		// assistant usage that the real stream wrapper did not already account for.
 		const reportedOutputTokens = assistantOutputTokens(assistants);
 		totalOutputTokens += Math.max(0, reportedOutputTokens - streamedOutputTokens);
+		// A warned terminal call deliberately leaves shouldStopAfterTurn false so
+		// the reviewer can search/recall and replace it. If the reviewer instead
+		// ends its turn, honor the staged outcome exactly as the warning promised.
+		if (!terminal && warnedTerminal) {
+			terminal = warnedTerminal;
+			warnedTerminal = undefined;
+		}
 		return totalOutputTokens - iterationStartTokens;
 	};
 

package/src/agents/reviewer/prompts.ts

@@ -28,7 +28,7 @@ First recall every memory cited in the request. Then search for:
 - 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.
+Observations and summaries 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.
 

package/src/agents/reviewer/tools.ts

@@ -1,6 +1,7 @@
 import type { AgentTool } from "@earendil-works/pi-agent-core";
 import { Type } from "@earendil-works/pi-ai";
 import type { Static, TSchema } from "typebox";
+import { memoryReferenceIds } from "../../memory-citations.js";
 import type { ReviewNoProposal, SoftwareReviewProposal, WorkflowReviewProposal } from "../../session-ledger/types.js";
 
 const prose = (description: string) => Type.String({ minLength: 1, description });
@@ -39,19 +40,26 @@ 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">;
+export type TerminalWriteResult = { terminal: boolean; overwritten: boolean };
+export type ReviewTerminalWriter = (result: ReviewTerminalResult, missingReferenceIds: string[]) => TerminalWriteResult;
 
 function trimOptional(value: string | undefined): string | undefined {
 	const normalized = value?.trim();
 	return normalized || undefined;
 }
 
+function citedIds(params: Record<string, unknown>): string[] {
+	return memoryReferenceIds(Object.values(params).filter((value): value is string => typeof value === "string").join("\n"));
+}
+
 function terminalTool<T extends TSchema>(
 	name: string,
 	label: string,
 	description: string,
 	parameters: T,
 	build: (params: Static<T>) => ReviewTerminalResult,
-	onTerminal: (result: ReviewTerminalResult) => void,
+	onTerminal: ReviewTerminalWriter,
+	referenceExists: (id: string) => boolean,
 ): AgentTool<T> {
 	return {
 		name,
@@ -59,26 +67,33 @@ function terminalTool<T extends TSchema>(
 		description,
 		parameters,
 		execute: async (_id, params) => {
-			onTerminal(build(params));
-			return { content: [{ type: "text", text: "Terminal review outcome recorded." }], details: { terminal: true } };
+			const missingReferenceIds = citedIds(params as Record<string, unknown>).filter((id) => !referenceExists(id));
+			const write = onTerminal(build(params), missingReferenceIds);
+			if (missingReferenceIds.length === 0) {
+				return { content: [{ type: "text", text: "Terminal review outcome recorded." }], details: { terminal: true, overwritten: write.overwritten, missingReferenceIds } };
+			}
+			const warnings = missingReferenceIds.map((id) => `WARNING: memory or primary-chat entry ${id} not found; use search_memories and recall, or search_chat_history and read_chat_history, to find the correct reference.`);
+			if (write.overwritten) warnings.push("WARNING: overwriting the prior review outcome; only the latest outcome will be delivered.");
+			warnings.push(`You can call ${name} again to replace this review, or end your turn and it will be delivered as-is.`);
+			return { content: [{ type: "text", text: warnings.join("\n") }], details: { terminal: false, replaceable: true, overwritten: write.overwritten, missingReferenceIds } };
 		},
 	};
 }
 
-export function createWorkflowProposalTool(onTerminal: (result: ReviewTerminalResult) => void): AgentTool<typeof WorkflowProposalSchema> {
+export function createWorkflowProposalTool(onTerminal: ReviewTerminalWriter, referenceExists: (id: string) => boolean = () => true): 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);
+	}), onTerminal, referenceExists);
 }
 
-export function createSoftwareProposalTool(onTerminal: (result: ReviewTerminalResult) => void): AgentTool<typeof SoftwareProposalSchema> {
+export function createSoftwareProposalTool(onTerminal: ReviewTerminalWriter, referenceExists: (id: string) => boolean = () => true): 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);
+	}), onTerminal, referenceExists);
 }
 
-export function createNoProposalTool(scope: "workflow" | "software", onTerminal: (result: ReviewTerminalResult) => void): AgentTool<typeof NoProposalSchema> {
+export function createNoProposalTool(scope: "workflow" | "software", onTerminal: ReviewTerminalWriter, referenceExists: (id: string) => boolean = () => true): 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);
+	}), onTerminal, referenceExists);
 }

package/src/agents/stream-errors.ts

@@ -10,7 +10,7 @@ import { debugLog } from "../debug-log.js";
  * "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 {
+export function logAgentStreamError(stage: "observer" | "summarizer" | "contemplator" | "reviewer", event: AgentEvent): void {
 	if (event.type !== "message_end") return;
 	const message = event.message;
 	if (message.role !== "assistant") return;