@iowarp/clio-coder 0.5.0 → 0.5.2

package/src/interactive/chat-loop.ts

@@ -1,7 +1,14 @@
+import type { LiveBudgetView } from "../domains/context/budget/live-view.js";
 import type { WorkerContextSnapshot } from "../domains/context/worker/contract.js";
 import { captureWorkerContext } from "../domains/context/worker/snapshot.js";
-import { replaceEngineMessages } from "../engine/agent.js";
+import type { MemoryPromptRequest } from "../domains/memory/prompt-cache.js";
+import type { MemoryInterventionRegistration } from "../domains/middleware/memory-intervention.js";
+import { estimateAgentMessageTokens } from "../domains/session/context-accounting.js";
+import { createContinuityPersistencePorts } from "../domains/session/continuity/ports.js";
+import { continuityReplayText, resolveContinuityProjection } from "../domains/session/continuity/projection.js";
+import { continueEngineWithoutInput, replaceEngineMessages } from "../engine/agent.js";
 import { isLockedSynthesisFallbackOnly, lockedSynthesisRepromptMessages } from "../engine/loop-guard.js";
+import { ContinuityController } from "./continuity-controller.js";
 /**
  * The chat loop: one turn's state machine.
  *
@@ -31,6 +38,8 @@ import {
 } from "../core/skill-activation.js";
 import { snapshotTurnConstraints, type TurnConstraints } from "../core/turn-constraints.js";
 import { clioStateDir } from "../core/xdg.js";
+import type { BudgetInspection } from "../domains/context/budget/inspection.js";
+import { requestFits } from "../domains/context/budget/request-fit.js";
 import {
 	createMiddlewareToolChoiceControl,
 	type MiddlewareContract,
@@ -52,8 +61,7 @@ import {
 import { type AutonomyLevel, modelMayActivateSkills } from "../domains/safety/autonomy.js";
 import type { ProtectedArtifactState } from "../domains/safety/protected-artifacts.js";
 import type { CompactInput, CompactResult } from "../domains/session/compaction/compact.js";
-import type { ContextSnapshot, ContextUsageSnapshot } from "../domains/session/context-accounting.js";
-import { ceilChars, snapshotInputTokens } from "../domains/session/context-accounting.js";
+import type { ContextSnapshot } from "../domains/session/context-accounting.js";
 import type { ContextLedger } from "../domains/session/context-ledger.js";
 import type { SessionContract } from "../domains/session/contract.js";
 import {
@@ -67,7 +75,6 @@ import { protectedArtifactStateFromSessionEntries } from "../domains/session/pro
 import { isRetryableErrorMessage, type RetrySettings } from "../domains/session/retry.js";
 import { filterEntriesToActivePath } from "../domains/session/tree/active-path.js";
 import { createEngineAgent } from "../engine/agent.js";
-import { resolveReservedOutputTokens } from "../engine/apis/output-budget.js";
 import { cwdHash } from "../engine/session.js";
 import type { AgentEvent, AgentMessage, ImageContent, Usage } from "../engine/types.js";
 import { resolveSessionTools } from "../tools/agent-tools.js";
@@ -90,7 +97,7 @@ import type { ApprovalRequestView } from "./permission-overlay.js";
 import type { runPrewarmRound } from "./prewarm.js";
 import { runSideQuestion, type SideQuestionResult, sideQuestionUsage } from "./side-question.js";
 import type { AgentStatusEvent } from "./status/types.js";
-import { createTurnContext } from "./turn-context.js";
+import { createTurnContext, type LiveContextUsage } from "./turn-context.js";
 import { createTurnMiddleware } from "./turn-middleware.js";
 import { createTurnPersistence } from "./turn-persistence.js";
 import { createTurnPrewarm, type PrewarmOutcome, subscribePrewarmToCompaction } from "./turn-prewarm.js";
@@ -338,7 +345,7 @@ export interface ChatLoop {
 	turnPreparation(): { phase: TurnPreparationPhase; since: number };
 	/** Fires on every preparation transition, including back to `idle`. */
 	onTurnPreparation(handler: (phase: TurnPreparationPhase) => void): () => void;
-	contextUsage(): ContextUsageSnapshot;
+	contextUsage(): LiveContextUsage;
 	/**
 	 * Categorized context-window ledger for the `/context` overlay: where every
 	 * occupied token lives (system prompt, tools, agents, skills, memory,
@@ -346,6 +353,21 @@ export interface ChatLoop {
 	 * estimate with the current turn's prompt segment manifest.
 	 */
 	contextLedger(): ContextLedger;
+	/**
+	 * The published live budget for the next request: one immutable view with
+	 * the effective window, the structural accounting, the real output
+	 * reservation, headroom, pressure, and an opaque revision every consumer
+	 * quotes. A pure read of what the producer last published; it never rescans
+	 * the conversation, calls a model, persists anything, or triggers reduction.
+	 */
+	liveBudget(): LiveBudgetView;
+	inspectLiveBudget(): BudgetInspection;
+	/**
+	 * Republish the live budget before making a decision from it, for a consumer
+	 * that may be observing results appended since the last publication. The
+	 * only thing it mutates is the accounting cache.
+	 */
+	refreshLiveBudget(): LiveBudgetView;
 	/**
 	 * Force-run the compaction flow for the current session, swap the agent's
 	 * in-memory `state.messages` for a single bridge message carrying the
@@ -356,13 +378,15 @@ export interface ChatLoop {
 	 * notice so the `/context compact` handler does not have to mirror the logic.
 	 */
 	compact(instructions?: string): Promise<void>;
+	requestSelfCompact(note: unknown, toolCallId: string, signal?: AbortSignal): Promise<string>;
+	recoverHandoff(handoffId: string, action: "reduce" | "deliver"): Promise<void>;
 	/**
 	 * `/btw`: answer one side question against the session's active target,
 	 * model, and compiled message history without starting a turn.
 	 *
 	 * Nothing this produces reaches the session ledger, the transcript, the
 	 * context ledger, or the footer token counters; the message history is read,
-	 * never mutated. The round's provider usage is still reported to `/cost`,
+	 * never mutated. The round's provider usage is still reported to `/usage`,
 	 * labeled as a side question, because money was spent. Refused outright
 	 * while a turn is in flight rather than queued.
 	 */
@@ -404,6 +428,7 @@ export interface ChatLoop {
 }
 
 export interface CreateChatLoopDeps {
+	memoryCommitBridge?: MemoryInterventionRegistration | undefined;
 	interactiveGuidance?: boolean;
 	getSettings: () => Readonly<ClioSettings>;
 	/**
@@ -470,7 +495,15 @@ export interface CreateChatLoopDeps {
 	autoCompact?: (
 		instructions?: string,
 		trigger?: CompactionTrigger,
-		budget?: Pick<CompactInput, "keepRecentTokens" | "preserveUserTurnId" | "skillContextState" | "signal">,
+		budget?: Pick<
+			CompactInput,
+			| "keepRecentTokens"
+			| "preserveUserTurnId"
+			| "skillContextState"
+			| "signal"
+			| "beforeSummaryCall"
+			| "checkpointForSummary"
+		>,
 	) => Promise<CompactResult | null>;
 	/** Optional observability sink for orchestrator chat token usage. */
 	observability?: ObservabilityContract;
@@ -519,7 +552,7 @@ export interface CreateChatLoopDeps {
 	 * compiler injects via the memory dynamic fragment. Optional so unit
 	 * tests omit it when memory is irrelevant.
 	 */
-	getMemorySection?: () => string;
+	getMemorySection?: (request: MemoryPromptRequest) => string;
 	getReadySkillCount?: () => number;
 	/** Structured, redacted task-bank export supplied only to an explicit context-handoff skill request. */
 	getTaskMemoryHandoffSource?: () => string;
@@ -528,7 +561,7 @@ export interface CreateChatLoopDeps {
 	 * observers produce after their turn boundary closed. Called once during
 	 * composition; the loop owns the buffer the reminder lands in.
 	 */
-	registerDeferredReminderSink?: (sink: (message: string) => void) => void;
+	registerDeferredReminderSink?: (sink: (message: string, isCurrent?: () => boolean) => void) => void;
 	/**
 	 * The same seam for findings that are for the operator rather than the model.
 	 * The watchdog uses it: its run settles after the turn it reviewed, and its
@@ -780,6 +813,7 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 	});
 
 	const middleware = createTurnMiddleware({
+		memoryContentGuard: deps.memoryCommitBridge?.isContentCurrent,
 		state,
 		middleware: deps.middleware,
 		session: deps.session,
@@ -789,7 +823,9 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 	});
 
 	try {
-		deps.registerDeferredReminderSink?.((message) => middleware.injectDeferredReminder(message));
+		deps.registerDeferredReminderSink?.((message, isCurrent) =>
+			middleware.injectDeferredReminder(message, "advisory", isCurrent),
+		);
 		deps.registerDeferredNoticeSink?.((text) => middleware.emitDeferredNotice(text));
 	} catch {
 		// A background observer losing its delivery path must not stop the loop
@@ -809,11 +845,126 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 		readSessionEntries: deps.readSessionEntries,
 		autoCompact: deps.autoCompact,
 		getMemorySection: deps.getMemorySection,
+		memoryCommitBridge: deps.memoryCommitBridge,
 		getReadySkillCount: deps.getReadySkillCount,
+		getPendingHandoff: () => {
+			const sessionId = deps.session?.current()?.id;
+			if (!sessionId) return null;
+			const fold = resolveContinuityProjection({
+				entries: filterEntriesToActivePath(deps.readSessionEntries?.() ?? [], state.lastTurnId ?? undefined),
+				sessionId,
+			}).current;
+			return fold?.identity && fold.phase !== "acknowledged"
+				? {
+						id: fold.identity.handoffId,
+						preparedAt: fold.policy ? new Date(fold.policy.preparedAtMs).toISOString() : null,
+						sourceRevision: fold.identity.sourceRevision,
+					}
+				: null;
+		},
+		getLastOutcome: () => {
+			const sessionId = deps.session?.current()?.id;
+			if (!sessionId) return null;
+			const fold = resolveContinuityProjection({
+				entries: filterEntriesToActivePath(deps.readSessionEntries?.() ?? [], state.lastTurnId ?? undefined),
+				sessionId,
+			}).current;
+			return fold?.identity ? { outcome: fold.phase, at: null, detail: fold.commit?.outcome ?? null } : null;
+		},
 		middleware,
 		emitNotice,
 	});
 
+	let continuityReplayInstalled = false;
+	const continuity = new ContinuityController({
+		captureOrigin: () => {
+			continuityReplayInstalled = false;
+			const session = deps.session;
+			const meta = session?.current();
+			const runtime = state.runtime;
+			const leaf = state.lastTurnId;
+			const operator = state.activeUserTurnId;
+			if (!session || !meta || !runtime || !leaf || !operator || context.inspectLiveBudget().status !== "available") {
+				throw new Error("Self-compaction requires a native runtime and a persisted operator turn.");
+			}
+			const revision = context.navigationRevision();
+			const route = `${deps.getSettings().chat.target}/${deps.getSettings().chat.model}`;
+			return {
+				sessionId: meta.id,
+				leafTurnId: leaf,
+				initiatingTurnId: operator,
+				sourceRevision: context.refreshLiveBudget().revision,
+				ports: createContinuityPersistencePorts({
+					session,
+					origin: {
+						sessionId: meta.id,
+						cwdHash: meta.cwdHash,
+						stillCurrent: () =>
+							context.navigationRevision() === revision &&
+							state.runtime === runtime &&
+							state.activeUserTurnId === operator &&
+							`${deps.getSettings().chat.target}/${deps.getSettings().chat.model}` === route,
+					},
+				}),
+			};
+		},
+		entries: () => filterEntriesToActivePath(deps.readSessionEntries?.() ?? [], state.lastTurnId ?? undefined),
+		leaf: () => state.lastTurnId,
+		admitNote: (accepted) => {
+			const view = context.refreshLiveBudget();
+			if (!view.breakdown || view.historical) return false;
+			const messages = state.runtime?.agent.state.messages ?? [];
+			const operator = [...messages].reverse().find((message) => message.role === "user");
+			const note = continuityReplayText({
+				note: accepted.note,
+				handoffId: "pending",
+				commitId: "pending",
+				originSessionId: view.sessionId ?? "",
+				phase: "prepared",
+				authority: "execution",
+			});
+			// Include the complete skill messages and tool receipts already in the
+			// protected suffix. The final guard still prices the actual replay.
+			const protectedSkills = messages
+				.filter((message) => message.role === "toolResult" && message.toolName === "context")
+				.reduce((sum, message) => sum + estimateAgentMessageTokens(message), 0);
+			const floor =
+				view.breakdown.systemPromptTokens +
+				view.breakdown.toolSchemaTokens +
+				protectedSkills +
+				(operator ? estimateAgentMessageTokens(operator) : 0) +
+				estimateAgentMessageTokens({ role: "assistant", content: [{ type: "text", text: note }] }) +
+				512;
+			return requestFits(floor, view.outputReserveTokens, view.effectiveWindow);
+		},
+		fits: () => {
+			const view = context.refreshLiveBudget();
+			return requestFits(view.inputTokens, view.outputReserveTokens, view.effectiveWindow);
+		},
+		inputTokens: () => context.refreshLiveBudget().inputTokens ?? 0,
+		reduce: async (hooks, signal) => {
+			if (!state.runtime) throw new Error("Native runtime was detached.");
+			continuityReplayInstalled = await context.runAutoCompact(
+				state.runtime,
+				true,
+				undefined,
+				"overflow",
+				undefined,
+				undefined,
+				signal,
+				hooks,
+			);
+		},
+		installReplay: () => {
+			if (state.runtime && !continuityReplayInstalled) {
+				context.refreshAgentMessagesFromSession(state.runtime);
+				continuityReplayInstalled = true;
+			}
+		},
+		onCommit: (commitId, outcome) => context.notifyMemoryCommit(commitId, "continuity", outcome),
+		notice: emitNotice,
+	});
+
 	const persistence = createTurnPersistence({
 		state,
 		session: deps.session,
@@ -851,6 +1002,8 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 		knownTargets: deps.knownTargets,
 		observability: deps.observability,
 		createAgent,
+		continuity,
+		hasQueuedSteering: () => queues.queuedMessages().steer.length > 0,
 		middlewareToolChoice,
 		persistence,
 		context,
@@ -967,12 +1120,12 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 		deps.recordOutOfTurnUsageRow ?? ((row: OutOfTurnUsageRow): void => appendOutOfTurnUsageRow(clioStateDir(), row));
 
 	/**
-	 * Report an out-of-turn round's provider usage. Money was spent, so `/cost`
+	 * Report an out-of-turn round's provider usage. Money was spent, so `/usage`
 	 * says so under its own label; turn persistence, the working-set ledger,
 	 * compaction inputs, and the footer counters never see it.
 	 *
 	 * The same call is also appended to the out-of-turn usage store under the
-	 * state dir. That store exists because `/cost` only knows what this process
+	 * state dir. That store exists because `/usage` only knows what this process
 	 * spent: the round appends nothing to the session JSONL by design, so an
 	 * archive reader such as `clio-coder usage report` had no record of the
 	 * spend at all once the process exited. The session ledger stays untouched.
@@ -1174,6 +1327,11 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 			const pendingSkillRequests =
 				state.currentTurnConstraints?.skills === "disabled" ? [] : (options.pendingSkillRequests ?? []);
 			context.addWorkingContextPaths(options.workingContextPaths ?? []);
+			context.prepareMemoryTurn(agentRuntime, {
+				taskText: text,
+				continuation: options.requestContinuation === true,
+				images,
+			});
 			// A skill the operator activated narrows the tools for the workflow
 			// it started, and that workflow outlives the turn it began in. A
 			// fresh /skill this turn replaces the armed surface; otherwise the
@@ -1205,7 +1363,7 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 			// the user message: persisted in the ledger, no hidden prompt
 			// machinery.
 			middleware.fireTurnStart(agentRuntime, text, pendingSkillRequests.length, options.requestContinuation === true);
-			const reminderBlock = middleware.flushPendingReminders();
+			const reminderProjection = middleware.takePendingReminderProjection();
 			// Pending skill requests are plain visible text in the user message
 			// itself: persisted in the ledger, no hidden prompt machinery.
 			const skillPreamble = pendingSkillRequestPreamble(pendingSkillRequests);
@@ -1218,9 +1376,9 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 					// the explicitly requested skill turn.
 				}
 			}
-			const submittedText = [reminderBlock, skillPreamble, taskMemoryHandoffSource, text]
-				.filter((part) => part.length > 0)
-				.join("\n\n");
+			const composeSubmittedText = () =>
+				[reminderProjection(), skillPreamble, taskMemoryHandoffSource, text].filter((part) => part.length > 0).join("\n\n");
+			let submittedText = composeSubmittedText();
 
 			// 2. Pre-submit auto-compaction trigger
 			const forceNow = process.env.CLIO_CODER_FORCE_COMPACT === "1";
@@ -1236,6 +1394,7 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 
 			// 3. Ensure the session prompt (compiles only on explicit events)
 			const compiledPrompt = await context.ensureSessionPrompt(agentRuntime);
+			submittedText = composeSubmittedText();
 
 			// 4. Preflight overflow check, before the user turn is committed.
 			// A blocked request must not leave a dangling user entry that the
@@ -1252,63 +1411,27 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 					toolSignature,
 				});
 
-			const effectiveWindow = agentRuntime.runtimeResolution.contextWindowDetails.effectiveContextWindow;
-			const outputForInput = (inputTokens: number): number =>
-				resolveReservedOutputTokens(agentRuntime.runtimeResolution.capabilityDecisions.maxTokens, {
-					api: agentRuntime.agent.state.model?.api ?? "",
-					contextWindow: effectiveWindow,
-					inputTokens,
-				});
-			const pendingInputTokens = ceilChars(submittedText.length);
 			let turnSnapshot = captureTurnSnapshot("pending");
-			// The snapshot prices the prompt at chars/4. When the provider has
-			// already attested a larger prompt for this conversation, that figure
-			// is what the request will actually cost, so the overflow guard reads
-			// the higher of the two (issue #227). Both already carry the pending
-			// user text and the tool schema estimate.
-			const budgetedPromptTokens = (snapshot: ContextSnapshot): number =>
-				Math.max(
-					snapshotInputTokens(snapshot) + pendingInputTokens,
-					context.liveContextEstimate(agentRuntime, submittedText).tokens,
-				);
-			const inputEstimate = budgetedPromptTokens(turnSnapshot);
-			const reservedOutput = outputForInput(inputEstimate);
-			const totalEstimate = inputEstimate + reservedOutput;
-
-			if (effectiveWindow > 0 && totalEstimate > effectiveWindow) {
-				emitNotice(
-					`[Clio Coder] Estimated request size ${totalEstimate} tokens (input ${totalEstimate - reservedOutput} + output budget ${reservedOutput}) exceeds the effective context window of ${effectiveWindow} tokens. Running compaction before sending...`,
-				);
+			let admission = context.refreshLiveBudget(submittedText);
+			if (!requestFits(admission.inputTokens, admission.outputReserveTokens, admission.effectiveWindow)) {
 				setTurnPreparation("compacting");
-				let compactionFailure: string | undefined;
-				const compacted = await context
+				let failure: string | undefined;
+				await context
 					.runAutoCompact(agentRuntime, true, undefined, "overflow", submittedText, pendingSkillPolicy)
 					.catch((error: unknown) => {
-						compactionFailure = error instanceof Error ? error.message : String(error);
-						return false;
+						failure = error instanceof Error ? error.message : String(error);
 					})
 					.finally(endPreparationCompaction);
-				if (!compacted) {
+				submittedText = composeSubmittedText();
+				admission = context.refreshLiveBudget(submittedText);
+				if (!requestFits(admission.inputTokens, admission.outputReserveTokens, admission.effectiveWindow)) {
 					emitAdmissionNotice(
-						`[Clio Coder] Request exceeds the context window and compaction could not reclaim enough space.${compactionFailure ? ` ${compactionFailure}.` : ""} Trim the prompt or reduce active tools.`,
+						`[Clio Coder] Request exceeds the available context window (input ${admission.inputTokens ?? "unknown"} + output ${admission.outputReserveTokens ?? "unknown"}, window ${admission.effectiveWindow ?? "unknown"}).${failure ? ` ${failure}` : ""} Trim the prompt or reduce active tools.`,
 						"context-window-exceeded",
 					);
 					return;
 				}
-				context.refreshAgentMessagesFromSession(agentRuntime);
 				turnSnapshot = captureTurnSnapshot("pending");
-				const postInputEstimate = budgetedPromptTokens(turnSnapshot);
-				const postTotalEstimate = postInputEstimate + outputForInput(postInputEstimate);
-				if (postTotalEstimate > effectiveWindow) {
-					emitAdmissionNotice(
-						`[Clio Coder] Request still exceeds the effective window after compaction (${postTotalEstimate} > ${effectiveWindow}). Request blocked.`,
-						"context-window-exceeded",
-					);
-					return;
-				}
-				emitNotice(
-					`[Clio Coder] Context budget check passed post-compaction (${postTotalEstimate} <= ${effectiveWindow}). Proceeding.`,
-				);
 			}
 
 			// 5. Append the user turn, then stamp and persist the snapshot.
@@ -1322,6 +1445,8 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 				text,
 				options.display?.text,
 			);
+			context.installMemoryRestoration(agentRuntime, submittedText);
+			context.commitMemoryTurn(agentRuntime);
 			// An interrupt was submitted while a run was active, so no caller drew
 			// it in the transcript; render it here, after the cancel notice and the
 			// cancelled run's leftovers, which is the order the ledger has.
@@ -1509,6 +1634,7 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 		},
 
 		cancel(options?: ChatCancelOptions): void {
+			continuity.cancel();
 			const wasStreaming = state.streaming;
 			context.cancelCompaction();
 			recovery.cancelRetryCountdown();
@@ -1581,10 +1707,15 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 		contextUsage: () => context.contextUsage(),
 		currentTurnConstraints: () => state.currentTurnConstraints,
 		contextLedger: () => context.contextLedger(),
+		liveBudget: () => context.liveBudget(),
+		inspectLiveBudget: () => context.inspectLiveBudget(),
+		refreshLiveBudget: () => context.refreshLiveBudget(),
 		whenSettled: () => activeSubmit,
 		whenPrewarmSettled: () => prewarm.settled(),
 
 		resetForSession(leafTurnId: string | null, replayMessages?: ReadonlyArray<AgentMessage>): void {
+			continuity.cancel();
+			void continuity.pause();
 			state.currentTurnConstraints = undefined;
 			if (state.runtime) {
 				state.runtime.agent.abort();
@@ -1597,7 +1728,10 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 			middlewareToolChoice.reset();
 			state.lastTurnId = leafTurnId;
 			state.lastRunSnapshot = null;
-			context.resetForSession();
+			// The incoming leaf is the advisory branch identity for the new session.
+			// Ordinary appends advance `state.lastTurnId` from here without re-arming
+			// an advisory; arriving here at all is the navigation that does.
+			context.resetForSession(leafTurnId);
 			// The resumed ledger renders before the first new turn (issue #189),
 			// and the window it renders against should be the probed one rather
 			// than the catalog's, so the live capability probe the first submit
@@ -1704,6 +1838,28 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 			return result.aborted ? { status: "aborted", text: result.text } : { status: "answered", text: result.text };
 		},
 
+		requestSelfCompact: (note, toolCallId, signal) => continuity.request(note, toolCallId, signal),
+		async recoverHandoff(handoffId, action) {
+			if (state.streaming || state.turnPreparation !== "idle")
+				throw new Error("Wait for the current turn to settle before recovery.");
+			const runtime = turnRuntime.ensureRuntime();
+			if (!runtime) throw new Error("No native runtime is configured.");
+			state.activeInterruptReason = null;
+			if (!state.activeUserTurnId) {
+				const operator = [...filterEntriesToActivePath(deps.readSessionEntries?.() ?? [], state.lastTurnId ?? undefined)]
+					.reverse()
+					.find((entry) => entry.kind === "message" && entry.role === "user");
+				state.activeUserTurnId = operator?.turnId ?? null;
+			}
+			state.streaming = true;
+			try {
+				await continuity.recover(handoffId, action);
+				await continueEngineWithoutInput(runtime.agent);
+			} finally {
+				state.streaming = false;
+				await continuity.pause();
+			}
+		},
 		async compact(instructions?: string): Promise<void> {
 			// Session check runs BEFORE orchestrator-configuration so a fresh
 			// TUI with nothing configured still reports the actionable "no

package/src/interactive/chat-renderer.ts

@@ -365,6 +365,48 @@ export interface RehydrateChatPanelOptions {
 	 * every failure, so a session whose receipts are gone still replays.
 	 */
 	readWorkerReceipt?: WorkerReceiptReader;
+	/**
+	 * Already-rendered continuity blocks, in order, from
+	 * `continuityReplayBlocks`. Each is emitted verbatim exactly once and never
+	 * routed through `appendContextMessage`, whose trim and replay cap would
+	 * crop an accepted note; §4 forbids trimming, normalizing or regenerating
+	 * accepted text. Resolving which blocks these are needs the session and fork
+	 * facts a renderer does not have, so the caller supplies the finished text
+	 * and this module only places it.
+	 */
+	continuityBlocks?: ReadonlyArray<string>;
+}
+
+/**
+ * The active-path slice a replay works from, **before** the compaction cut.
+ *
+ * Exported because the continuity fold needs exactly this array: evidence for a
+ * transaction routinely sits older than the cut, and `selectReplayEntries`
+ * would both drop it and renumber every surviving position. A caller that
+ * resolves a projection folds this, then renders, so the two agree on one
+ * ordered input.
+ */
+export function activeEntriesBeforeCompactionCut(
+	turns: ReadonlyArray<SessionEntry>,
+	options: RehydrateChatPanelOptions = {},
+	/**
+	 * Whether to apply `uptoTurnId`'s positional truncation.
+	 *
+	 * Display replay always does. Continuity does not, unless the selection is a
+	 * genuine historical cut, because `uptoTurnId` carries two different meanings
+	 * through one option: a live `/tree` switch passes it to stop the transcript
+	 * at the selected message, and a historical fork passes it to describe a
+	 * moment that really had no later records. Truncating for the first case
+	 * physically discards a pause, a delivery or an acknowledgement anchored
+	 * after the selected message, and a fold cannot restore a record it was never
+	 * shown: leaving a `historical` flag false does not undo a cut already made.
+	 * The branch selection honors the leaf either way; only the positional cut
+	 * is conditional.
+	 */
+	truncateAtSelection = true,
+): SessionEntry[] {
+	const active = filterEntriesToActivePath(turns, options.activeLeafTurnId ?? options.uptoTurnId);
+	return truncateAtSelection ? truncateAtTurn(active, options.uptoTurnId) : active;
 }
 
 function extractTurnText(payload: unknown): string {
@@ -1105,15 +1147,23 @@ export function buildReplayAgentMessagesFromTurns(
 ): AgentMessage[] {
 	const out = createOrderedReplaySink();
 	const seenToolCalls = new Set<string>();
-	const activeEntries = truncateAtTurn(
-		filterEntriesToActivePath(turns, options.activeLeafTurnId ?? options.uptoTurnId),
-		options.uptoTurnId,
-	);
+	const activeEntries = activeEntriesBeforeCompactionCut(turns, options);
 	const skillState = latestSkillContextState(activeEntries);
-	const evidence = truncateAtTurn(
-		filterEntriesToActivePath(options.skillContextEntries ?? turns, options.activeLeafTurnId ?? options.uptoTurnId),
-		options.uptoTurnId,
-	);
+	// One emission point for the continuity blocks, tracked by a flag rather than
+	// by counting occurrences: the note has to appear exactly once whether the
+	// replay window holds a carrying summary, an eviction-only commit, or
+	// neither. `selectReplayEntries` keeps at most one compaction summary, so
+	// the in-loop emission below cannot fire twice.
+	let continuityEmitted = false;
+	const emitContinuity = (timestamp: string): void => {
+		if (continuityEmitted) return;
+		continuityEmitted = true;
+		// Verbatim. The accepted note is agent-authored handoff text and is
+		// carried as data; it is never presented as an operator turn and never
+		// passes through the trimming/truncating context helper.
+		for (const block of options.continuityBlocks ?? []) out.push(makeTextMessage("user", block, timestamp));
+	};
+	const evidence = activeEntriesBeforeCompactionCut(options.skillContextEntries ?? turns, options);
 	const verified = captureSkillContext(evidence, skillState);
 	for (const entry of selectReplayEntries(turns, options)) {
 		switch (entry.kind) {
@@ -1181,6 +1231,10 @@ export function buildReplayAgentMessagesFromTurns(
 						for (const block of skill.content) out.push(makeTextMessage("user", block.text, entry.timestamp));
 					}
 				}
+				// The reduction boundary is where the handoff happened, so the note
+				// sits directly after the summary that replaced the history it
+				// describes, whether or not this summary is the one that carried it.
+				emitContinuity(entry.timestamp);
 				break;
 			case "skillActivation":
 				if (entry.activation.runId !== undefined || (skillState && !skillState.activationRefs.includes(entry.turnId)))
@@ -1213,9 +1267,20 @@ export function buildReplayAgentMessagesFromTurns(
 			// entries themselves never become messages.
 			case "contextEviction":
 			case "contextRecall":
+			// Continuity records are bookkeeping. The chain and the commit payload
+			// never become model messages; the one thing that reaches the model is
+			// the accepted note, projected once through `continuityBlocks`. Handling
+			// each commit here instead would emit a copy per record and would still
+			// miss a commit that sits before the cut.
+			case "handoffTransaction":
+			case "continuityCommit":
 				break;
 		}
 	}
+	// No compaction summary in the replay window: an eviction-only or
+	// continuity-only outcome still has a note to carry, so it lands at the end
+	// of the replayed history rather than being dropped.
+	emitContinuity(activeEntries[activeEntries.length - 1]?.timestamp ?? new Date(0).toISOString());
 	out.flush();
 	return out.messages;
 }
@@ -1412,6 +1477,21 @@ export function rehydrateChatPanelFromTurns(
 				chatPanel.applyWorkerState(state);
 				break;
 			}
+			// One bounded provenance line each. The transcript says a handoff
+			// happened and where it stands; the note itself is rendered once,
+			// below, under its own label, rather than once per record.
+			case "handoffTransaction":
+				appendReplayLine(
+					chatPanel,
+					`[continuity] ${entry.event.phase} handoff=${entry.identity.handoffId} seq=${entry.transition.sequence} attempt=${entry.transition.attempt}`,
+				);
+				break;
+			case "continuityCommit":
+				appendReplayLine(
+					chatPanel,
+					`[continuity] commit handoff=${entry.continuity.identity.handoffId} outcome=${entry.continuity.commit.outcome} tokens=${entry.continuity.commit.tokensBefore}->${entry.continuity.commit.tokensAfter}`,
+				);
+				break;
 			case "label":
 			case "taskLedger":
 			case "decisionLedger":
@@ -1420,6 +1500,17 @@ export function rehydrateChatPanelFromTurns(
 				break;
 		}
 	}
+	// The transcript shows the note as what it is: assistant-authored handoff
+	// text, labelled, never rendered as an operator turn.
+	//
+	// This is a presentation view, not the durable text. The panel wraps to its
+	// width and strips terminal control sequences, so a rendered line is not
+	// byte-identical to the note; §12 permits an export transformation exactly
+	// when it is labelled, and the exact bytes stay in the ledger and in the
+	// model replay the same blocks feed.
+	for (const block of options.continuityBlocks ?? []) {
+		for (const line of block.split("\n")) appendReplayLine(chatPanel, line);
+	}
 	for (const pendingId of pendingToolIds) {
 		chatPanel.applyEvent({
 			type: "tool_execution_end",