@iowarp/clio-coder 0.3.4 → 0.3.7

package/src/interactive/bus-notices.ts

@@ -187,6 +187,32 @@ export function middlewareHookFailedSessionNotice(payload: unknown, seenBudgetWa
 	return middlewareHookFailedNotice(payload, { noteBudgetWarningSuppression: key !== null });
 }
 
+/** How many failed checks a watchdog notice names before it counts the rest. */
+export const WATCHDOG_NOTICE_CHECK_LIMIT = 3;
+
+/**
+ * The watchdog's finding, as the one transcript line it is allowed.
+ *
+ * A passing report renders nothing: the operator asked for a warning, not a
+ * receipt, and a green line after every mutating turn is noise that trains
+ * people to stop reading the channel. Only the failed checks of the
+ * `verifier-report` contract reach here, and only their names: the evidence
+ * body belongs to the receipt, which the operator can open. Returning null
+ * means the turn passed or the report carried nothing usable.
+ */
+export function watchdogBlockersNotice(checks: ReadonlyArray<{ name: string; passed: boolean }>): BusNotice | null {
+	const failed = checks.filter((check) => !check.passed && check.name.trim().length > 0);
+	if (failed.length === 0) return null;
+	const named = failed.slice(0, WATCHDOG_NOTICE_CHECK_LIMIT).map((check) => check.name.trim());
+	const rest = failed.length - named.length;
+	const more = rest > 0 ? `, and ${rest} more` : "";
+	const blockers = failed.length === 1 ? "blocker" : "blockers";
+	return {
+		level: "warn",
+		text: `[watchdog] ${failed.length} ${blockers} after this turn: ${named.join("; ")}${more}. Nothing was changed or queued.`,
+	};
+}
+
 /**
  * A tool call parked for one-shot approval (sd-01 §3.3). The text names the
  * axis that produced the ask: a safety-net rail asks at every level, while an

package/src/interactive/chat-loop-messages.ts

@@ -7,6 +7,13 @@
 
 import { randomUUID } from "node:crypto";
 import { settingsPath } from "../core/config.js";
+import {
+	addResponseModelIdObservationCount,
+	emptyResponseModelIdObservationCounts,
+	type ResponseModelIdObservation,
+	type ResponseModelIdObservationCounts,
+	responseModelIdObservationFromRecord,
+} from "../core/response-model-id.js";
 import type { PendingSkillRequest, PendingSkillToolPolicy, SkillDeclaredToolPolicy } from "../core/skill-activation.js";
 import { ToolNames } from "../core/tool-names.js";
 import { canonicalJson, sha256 } from "../domains/prompts/hash.js";
@@ -334,6 +341,7 @@ export function createAskUserToolPolicy(activeTools: ReadonlyArray<{ name: strin
 		status: "idle",
 		startedAt: now,
 		updatedAt: now,
+		exposure: "local",
 		rounds: [],
 		decisions: [],
 		inFlight: false,
@@ -356,6 +364,9 @@ export interface RunUsageSummary {
 	apiCalls: number;
 	hadReasoning: boolean;
 	hadUsage: boolean;
+	responseModelIdObservationCounts: ResponseModelIdObservationCounts;
+	lastResponseModelIdObservation: ResponseModelIdObservation;
+	lastDifferingResponseModelId: string | null;
 }
 
 /**
@@ -380,6 +391,9 @@ export function sumRunUsage(messages: ReadonlyArray<AgentMessage>): RunUsageSumm
 		apiCalls: 0,
 		hadReasoning: false,
 		hadUsage: false,
+		responseModelIdObservationCounts: emptyResponseModelIdObservationCounts(),
+		lastResponseModelIdObservation: { state: "not-observed" },
+		lastDifferingResponseModelId: null,
 	};
 	for (const raw of messages) {
 		const message = raw as
@@ -397,8 +411,15 @@ export function sumRunUsage(messages: ReadonlyArray<AgentMessage>): RunUsageSumm
 			  };
 		if (!message || typeof message !== "object") continue;
 		if (message.role !== "assistant") continue;
+		const record = message as unknown as Record<string, unknown>;
 		const usage = message.usage;
 		if (!usage || typeof usage !== "object") continue;
+		summary.lastResponseModelIdObservation = responseModelIdObservationFromRecord(record, "not-observed");
+		addResponseModelIdObservationCount(summary.responseModelIdObservationCounts, summary.lastResponseModelIdObservation);
+		summary.lastDifferingResponseModelId =
+			typeof record.responseModel === "string" && record.responseModel.trim().length > 0
+				? record.responseModel.trim()
+				: null;
 		summary.hadUsage = true;
 		summary.apiCalls += 1;
 		const input = typeof usage.input === "number" ? usage.input : 0;
@@ -459,6 +480,7 @@ export function assistantSessionPayload(
 	const raw = message as unknown as Record<string, unknown>;
 	if (Array.isArray(raw.content)) payload.content = raw.content;
 	if (thinking.length > 0) payload.thinking = thinking;
+	payload.responseModelIdObservation = responseModelIdObservationFromRecord(raw, "not-observed");
 	for (const key of ["usage", "api", "provider", "model", "responseModel", "responseId", "diagnostics"]) {
 		if (raw[key] !== undefined) payload[key] = raw[key];
 	}

package/src/interactive/chat-loop.ts

@@ -17,16 +17,19 @@ import { BusChannels, type RunAbortSource } from "../core/bus-events.js";
 import type { ClioSettings } from "../core/config.js";
 import type { SafeEventBus } from "../core/event-bus.js";
 import type { PendingSkillRequest } from "../core/skill-activation.js";
+import { clioStateDir } from "../core/xdg.js";
 import {
 	createMiddlewareToolChoiceControl,
 	type MiddlewareContract,
 	type MiddlewareToolChoiceControl,
 } from "../domains/middleware/index.js";
 import type { ObservabilityContract } from "../domains/observability/contract.js";
+import type { CostEntryLabel } from "../domains/observability/cost.js";
+import { appendOutOfTurnUsageRow, type OutOfTurnUsageRow } from "../domains/observability/out-of-turn-usage.js";
 import type { PromptsContract } from "../domains/prompts/contract.js";
 import { toContextOverflowError } from "../domains/providers/errors.js";
 import type { ProvidersContract } from "../domains/providers/index.js";
-import { runtimeTargetSnapshot } from "../domains/providers/index.js";
+import { normalizeCostProvenance, runtimeTargetSnapshot, targetRequiresAuth } from "../domains/providers/index.js";
 import type { ProtectedArtifactState } from "../domains/safety/protected-artifacts.js";
 import type { CompactResult } from "../domains/session/compaction/compact.js";
 import type { ContextSnapshot, ContextUsageSnapshot } from "../domains/session/context-accounting.js";
@@ -38,6 +41,7 @@ import { protectedArtifactStateFromSessionEntries } from "../domains/session/pro
 import { isRetryableErrorMessage, type RetrySettings } from "../domains/session/retry.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 } from "../engine/types.js";
 import { resolveSessionTools } from "../tools/agent-tools.js";
 import { finalizeAskUserInterviewForHost } from "../tools/ask-user.js";
@@ -53,7 +57,9 @@ import {
 	toolSignatureFromState,
 } from "./chat-loop-messages.js";
 import { normalizeRetrySettings } from "./chat-loop-policy.js";
+import { runHandoffRound } from "./handoff-round.js";
 import type { ApprovalRequestView } from "./permission-overlay.js";
+import { runSideQuestion, type SideQuestionResult } from "./side-question.js";
 import type { AgentStatusEvent } from "./status/types.js";
 import { createTurnContext } from "./turn-context.js";
 import { createTurnMiddleware } from "./turn-middleware.js";
@@ -184,6 +190,13 @@ export interface ChatSubmitOptions {
 	onAdmitted?: () => void;
 }
 
+/**
+ * Placeholder key a target that needs no auth still has to be handed. Mirrors
+ * the turn runtime's own local fallback, so a `/btw` round against a local
+ * server authenticates exactly the way a turn against it does.
+ */
+const LOCAL_SIDE_QUESTION_API_KEY = "clio-local-target";
+
 /** Closing notice an operator interrupt leaves in the transcript and the ledger. */
 const INTERRUPT_CANCEL_REASON = "[Clio Coder] run interrupted by operator; delivering the new message now.";
 const ENGINE_ACTIVE_PROMPT_ERROR =
@@ -212,6 +225,24 @@ export interface ChatCancelOptions {
 	auditReason?: string;
 }
 
+export interface SideQuestionOptions {
+	/** Cancels the round. Esc and Ctrl+C in the overlay abort through it. */
+	signal?: AbortSignal;
+	/** Streamed answer text so the overlay fills as the provider produces it. */
+	onDelta?: (partialText: string) => void;
+}
+
+/**
+ * How a `/btw` round ended. `refused` is a round that never started (a turn was
+ * in flight, or no orchestrator target is configured); `failed` is a round that
+ * started and the provider rejected.
+ */
+export type SideQuestionOutcome =
+	| { status: "answered"; text: string }
+	| { status: "aborted"; text: string }
+	| { status: "refused"; reason: string }
+	| { status: "failed"; reason: string };
+
 export interface ChatLoop {
 	submit(text: string, options?: ChatSubmitOptions): Promise<void>;
 	steer(text: string): boolean;
@@ -250,6 +281,28 @@ export interface ChatLoop {
 	 * notice so the `/context compact` handler does not have to mirror the logic.
 	 */
 	compact(instructions?: string): 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`,
+	 * labeled as a side question, because money was spent. Refused outright
+	 * while a turn is in flight rather than queued.
+	 */
+	askSideQuestion(question: string, options?: SideQuestionOptions): Promise<SideQuestionOutcome>;
+	/**
+	 * `/handoff`: run the extraction round for a goal against the same target,
+	 * model, and compiled message history, and return its raw JSON answer.
+	 *
+	 * Like a side question this is out of turn: no tools are sent, the message
+	 * history is read and never mutated, and nothing the round produces reaches
+	 * the ledger. Validating, bounding, and reviewing the answer belong to the
+	 * caller; this method only owns the provider call. Refused outright while a
+	 * turn is in flight rather than queued.
+	 */
+	extractHandoff(goal: string, options?: SideQuestionOptions): Promise<SideQuestionOutcome>;
 	/**
 	 * Drop or replace the chat-loop's in-memory state after a session switch
 	 * (/resume, /fork, /new). `leafTurnId` is the id the next user turn
@@ -292,6 +345,20 @@ export interface CreateChatLoopDeps {
 	 */
 	prompts?: PromptsContract;
 	createAgent?: typeof createEngineAgent;
+	/**
+	 * The `/btw` round. Defaults to the real provider call; contracts inject a
+	 * stub so they can assert what a side question does to the session without
+	 * standing up a provider, exactly as `createAgent` does for a turn.
+	 */
+	runSideQuestion?: typeof runSideQuestion;
+	/** The `/handoff` extraction round. Injectable for the same reason. */
+	runHandoffRound?: typeof runHandoffRound;
+	/**
+	 * Append one priced out-of-turn call to the durable out-of-turn usage store.
+	 * Defaults to the real writer under the state dir. Contracts inject a spy so
+	 * they can assert the row was written without touching a real state dir.
+	 */
+	recordOutOfTurnUsageRow?: (row: OutOfTurnUsageRow) => void;
 	/**
 	 * Return the current session's entries for token estimation. The chat-loop
 	 * calls this on every submit so the auto-compaction threshold sees the
@@ -369,6 +436,12 @@ export interface CreateChatLoopDeps {
 	 * composition; the loop owns the buffer the reminder lands in.
 	 */
 	registerDeferredReminderSink?: (sink: (message: string) => 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
+	 * blockers become one transcript notice that never enters model context.
+	 */
+	registerDeferredNoticeSink?: (sink: (text: string) => void) => void;
 	/**
 	 * Host-finalizer seam for branch-anchored interview snapshots. Called once,
 	 * after the ask-user host finalizer has settled the policy and its transcript.
@@ -399,6 +472,8 @@ export function reloadProtectedArtifactsForSession(
 export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 	const listeners = new Set<(event: ChatLoopEvent) => void>();
 	const createAgent = deps.createAgent ?? createEngineAgent;
+	const sideQuestionRound = deps.runSideQuestion ?? runSideQuestion;
+	const handoffRound = deps.runHandoffRound ?? runHandoffRound;
 	const middlewareToolChoice = deps.middlewareToolChoice ?? createMiddlewareToolChoiceControl();
 	const state = createTurnState(deps.getSettings().orchestrator.thinkingLevel ?? "off");
 	const toolStartTimes = new Map<string, number>();
@@ -485,6 +560,7 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 
 	try {
 		deps.registerDeferredReminderSink?.((message) => middleware.injectDeferredReminder(message));
+		deps.registerDeferredNoticeSink?.((text) => middleware.emitDeferredNotice(text));
 	} catch {
 		// A background observer losing its delivery path must not stop the loop
 		// from starting; it simply stays silent.
@@ -549,6 +625,12 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 		emitNotice,
 		toolStartTimes,
 	});
+	// A fresh ledger and footer render before the first submit. Start the same
+	// live capability probe that submit and resume use so those boot surfaces
+	// refresh to the probed model window as soon as provider discovery lands.
+	// The turn runtime coalesces the first submit onto this request, then its
+	// target and model TTL keeps later submits from repeating it.
+	void turnRuntime.ensureLiveCapabilitiesForSelectedModel().catch(() => {});
 
 	// --- bus subscriptions --------------------------------------------------
 
@@ -586,6 +668,102 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 		return null;
 	};
 
+	/**
+	 * Everything an out-of-turn round needs, or the reason it cannot run.
+	 *
+	 * `/btw` and `/handoff` are the two callers. Both read the compiled history
+	 * the next turn would see, both authenticate exactly the way a turn against
+	 * the same target does, and both are refused rather than queued while a turn
+	 * is in flight, so the admission decision is made once here.
+	 */
+	type OutOfTurnPreparation =
+		| { ok: true; runtime: AgentRuntime; apiKey: string | undefined }
+		| { ok: false; reason: string };
+
+	const prepareOutOfTurnRound = async (inFlightRefusal: string, signal?: AbortSignal): Promise<OutOfTurnPreparation> => {
+		if (state.streaming) return { ok: false, reason: inFlightRefusal };
+		let agentRuntime: AgentRuntime | null;
+		try {
+			agentRuntime = turnRuntime.ensureRuntime();
+		} catch (err) {
+			return { ok: false, reason: err instanceof Error ? err.message : String(err) };
+		}
+		if (!agentRuntime) return { ok: false, reason: notConfiguredNotice() };
+		const resolution = agentRuntime.runtimeResolution;
+		try {
+			const apiKey = targetRequiresAuth(resolution.target, resolution.runtime)
+				? (
+						await deps.providers.auth.resolveForTarget(resolution.target, resolution.runtime, signal ? { signal } : undefined)
+					).apiKey
+				: LOCAL_SIDE_QUESTION_API_KEY;
+			return { ok: true, runtime: agentRuntime, apiKey };
+		} catch (err) {
+			return { ok: false, reason: err instanceof Error ? err.message : String(err) };
+		}
+	};
+
+	const writeOutOfTurnUsageRow =
+		deps.recordOutOfTurnUsageRow ?? ((row: OutOfTurnUsageRow): void => appendOutOfTurnUsageRow(clioStateDir(), row));
+
+	/**
+	 * Report an out-of-turn round's provider usage. Money was spent, so `/cost`
+	 * 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
+	 * 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.
+	 */
+	const recordOutOfTurnUsage = (
+		runtime: AgentRuntime,
+		usage: SideQuestionResult["usage"],
+		label: CostEntryLabel,
+	): void => {
+		if (!usage) return;
+		const costProvenance = runtime.runtimeResolution.costProvenance;
+		deps.observability?.recordTokens(
+			runtime.targetId,
+			runtime.wireModelId,
+			usage.totalTokens,
+			usage.costUsd,
+			{
+				input: usage.input,
+				output: usage.output,
+				cacheRead: usage.cacheRead,
+				cacheWrite: usage.cacheWrite,
+				reasoningTokens: usage.reasoning,
+				totalTokens: usage.totalTokens,
+				apiCalls: 1,
+			},
+			costProvenance,
+			undefined,
+			label,
+		);
+		const meta = deps.session?.current() ?? null;
+		writeOutOfTurnUsageRow({
+			label,
+			sessionId: meta?.id ?? null,
+			// The identity the session ledger is filed under, so `usage report
+			// --repo` selects these rows with the same hash it selects ledgers with.
+			repoIdentity: meta ? meta.cwdHash || cwdHash(meta.cwd || process.cwd()) : null,
+			timestamp: new Date().toISOString(),
+			target: runtime.targetId,
+			attributedModelId: runtime.wireModelId,
+			usage: {
+				input: usage.input,
+				output: usage.output,
+				cacheRead: usage.cacheRead,
+				cacheWrite: usage.cacheWrite,
+				reasoning: usage.reasoning,
+				totalTokens: usage.totalTokens,
+				costUsd: usage.costUsd,
+				costProvenance: normalizeCostProvenance(costProvenance),
+			},
+		});
+	};
+
 	const api: ChatLoop = {
 		steer: (text) => queues.steer(text),
 		queueFollowUp: (text) => queues.queueFollowUp(text),
@@ -664,6 +842,7 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 			// 1. Accept the prompt: reset per-turn accounting, freeze the tool
 			// surface, fire turn_start, and assemble the submitted text.
 			state.turnToolCalls = 0;
+			state.turnToolNames = [];
 			state.turnSharedWorkerNote = isWorkerShareNote(text);
 			middlewareToolChoice.reset();
 			if (options.requestContinuation !== true) state.stalledTurnNudgeSpent = false;
@@ -988,6 +1167,12 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 			middlewareToolChoice.reset();
 			state.lastTurnId = leafTurnId;
 			context.resetForSession();
+			// 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
+			// would run runs now, under the same TTL; the footer refreshes on the
+			// provider-health event the probe publishes.
+			void turnRuntime.ensureLiveCapabilitiesForSelectedModel().catch(() => {});
 			state.replayedContextMessages = replayMessages ? [...replayMessages] : [];
 			if (state.runtime) {
 				state.runtime.agent.state.messages = [...state.replayedContextMessages];
@@ -1011,6 +1196,68 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 			middlewareToolChoice.reset();
 		},
 
+		async askSideQuestion(question: string, options: SideQuestionOptions = {}): Promise<SideQuestionOutcome> {
+			const text = question.trim();
+			if (text.length === 0) {
+				return { status: "refused", reason: "a side question needs a question" };
+			}
+			// Never queued. A side question exists to be answered now, beside a run
+			// the operator is watching; holding it until the run settles would
+			// deliver it after the moment it was asked in had passed.
+			const prepared = await prepareOutOfTurnRound(
+				"a turn is in flight; /btw runs beside the session, not in its queue",
+				options.signal,
+			);
+			if (!prepared.ok) return { status: "refused", reason: prepared.reason };
+			let result: SideQuestionResult;
+			try {
+				result = await sideQuestionRound({
+					model: prepared.runtime.agent.state.model,
+					// Read-only: runSideQuestion copies before appending its own
+					// message, so the live agent's history is untouched.
+					messages: prepared.runtime.agent.state.messages,
+					question: text,
+					...(prepared.apiKey !== undefined ? { apiKey: prepared.apiKey } : {}),
+					...(options.signal ? { signal: options.signal } : {}),
+					...(options.onDelta ? { onDelta: options.onDelta } : {}),
+				});
+			} catch (err) {
+				return { status: "failed", reason: err instanceof Error ? err.message : String(err) };
+			}
+			recordOutOfTurnUsage(prepared.runtime, result.usage, "side-question");
+			return result.aborted ? { status: "aborted", text: result.text } : { status: "answered", text: result.text };
+		},
+
+		async extractHandoff(goal: string, options: SideQuestionOptions = {}): Promise<SideQuestionOutcome> {
+			const text = goal.trim();
+			if (text.length === 0) {
+				return { status: "refused", reason: "a handoff needs a goal" };
+			}
+			// Refused, never queued: a handoff describes a session that has stopped
+			// working, and a turn still in flight is about to change what the
+			// document would say.
+			const prepared = await prepareOutOfTurnRound(
+				"a turn is in flight; /handoff cannot summarize a session that is still moving",
+				options.signal,
+			);
+			if (!prepared.ok) return { status: "refused", reason: prepared.reason };
+			let result: SideQuestionResult;
+			try {
+				result = await handoffRound({
+					model: prepared.runtime.agent.state.model,
+					// Read-only, exactly as the side-question round treats it.
+					messages: prepared.runtime.agent.state.messages,
+					goal: text,
+					...(prepared.apiKey !== undefined ? { apiKey: prepared.apiKey } : {}),
+					...(options.signal ? { signal: options.signal } : {}),
+				});
+			} catch (err) {
+				return { status: "failed", reason: err instanceof Error ? err.message : String(err) };
+			}
+			recordOutOfTurnUsage(prepared.runtime, result.usage, "handoff");
+			return result.aborted ? { status: "aborted", text: result.text } : { status: "answered", text: result.text };
+		},
+
 		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

@@ -13,6 +13,7 @@
  * `isTransparentAssistantWrapper`.
  */
 
+import { existsSync } from "node:fs";
 import { ToolNames } from "../core/tool-names.js";
 import { foldWorkingSet } from "../domains/context/working-set/fold.js";
 import { compactionCut } from "../domains/context/working-set/visible.js";
@@ -30,6 +31,13 @@ import type {
 	ThinkingLevelChangeEntry,
 	WorkerRunEntry,
 } from "../domains/session/entries.js";
+import {
+	HANDOFF_NOTE_CUSTOM_TYPE,
+	HANDOFF_SEED_CUSTOM_TYPE,
+	handoffSeedContextText,
+	isHandoffNoteData,
+	isHandoffSeedData,
+} from "../domains/session/handoff.js";
 import { filterEntriesToActivePath } from "../domains/session/tree/active-path.js";
 import {
 	type BashExecutionMessage,
@@ -44,7 +52,7 @@ import type { AgentMessage } from "../engine/types.js";
 import { toolPresentationPolicy } from "../tools/presentation.js";
 import { toolResultPresentationText } from "../tools/result-disposition.js";
 import type { ChatLoopEvent, RetryStatusPayload } from "./chat-loop.js";
-import { isSelfExplainingAbort } from "./chat-loop-messages.js";
+import { isSelfExplainingAbort, toolResultSummary } from "./chat-loop-messages.js";
 import type { ChatPanel } from "./chat-panel.js";
 import { renderBranchSummaryEntry } from "./renderers/branch-summary.js";
 import { renderCompactionSummaryEntry } from "./renderers/compaction-summary.js";
@@ -440,6 +448,7 @@ function richMessageFromEntry(entry: MessageEntry, maxTextChars?: number): Agent
 			"api",
 			"provider",
 			"model",
+			"responseModelIdObservation",
 			"responseModel",
 			"responseId",
 			"diagnostics",
@@ -671,6 +680,19 @@ interface ReplayToolResult {
 	blockReason?: string;
 }
 
+/**
+ * Resolve a replayed offload pointer once, when the ledger row becomes a
+ * display event. Terminal repaints consume the recorded fact and never touch
+ * the filesystem.
+ */
+function replayResultSummary(result: ReplayToolResult): Record<string, unknown> | undefined {
+	const summary = result.resultSummary ?? toolResultSummary(result.result);
+	const offloadPath =
+		typeof summary.offloadPath === "string" && summary.offloadPath.length > 0 ? summary.offloadPath : null;
+	if (offloadPath === null) return result.resultSummary;
+	return { ...summary, offloadFileMissing: !existsSync(offloadPath) };
+}
+
 function extractToolResult(entry: MessageEntry): ReplayToolResult {
 	const payload = entry.payload;
 	const obj = payloadObject(payload);
@@ -780,11 +802,18 @@ function rendersCustomEntry(entry: CustomEntry): boolean {
 	if (entry.display === false) return false;
 	if (entry.customType === "retryStatus") return true;
 	if (entry.customType === "finishContractAdvisory" || entry.customType === "middlewareReminder") return true;
+	if (entry.customType === HANDOFF_SEED_CUSTOM_TYPE || entry.customType === HANDOFF_NOTE_CUSTOM_TYPE) return true;
 	return entry.display === true;
 }
 
 function renderCustomEntry(entry: CustomEntry, width: number): string[] {
 	if (entry.customType === "retryStatus") return renderRetryStatusEntry(entry, width);
+	if (entry.customType === HANDOFF_SEED_CUSTOM_TYPE && isHandoffSeedData(entry.data)) {
+		return wrapTextWithAnsi(styleTaggedNotice(`[handoff] carried from session ${entry.data.fromSessionId}`), width);
+	}
+	if (entry.customType === HANDOFF_NOTE_CUSTOM_TYPE && isHandoffNoteData(entry.data)) {
+		return wrapTextWithAnsi(styleTaggedNotice(`[handoff] handed off to session ${entry.data.toSessionId}`), width);
+	}
 	// "finishContractAdvisory" is the pre-middleware name for the same entry
 	// shape; older session ledgers still carry it.
 	if (entry.customType === "finishContractAdvisory" || entry.customType === "middlewareReminder") {
@@ -1024,7 +1053,15 @@ export function buildReplayAgentMessagesFromTurns(
 			case "skillActivation":
 				appendContextMessage(out, "user", skillActivationContextText(entry), entry.timestamp);
 				break;
+			// The one custom entry that becomes a model message. `/handoff` seeds a
+			// new session with a reviewed document, and the seed is the first thing
+			// the model reads there; it is labelled by its origin session and
+			// carried as data, never as a user turn the operator did not write.
 			case "custom":
+				if (entry.customType === HANDOFF_SEED_CUSTOM_TYPE && isHandoffSeedData(entry.data)) {
+					appendContextMessage(out, "user", handoffSeedContextText(entry.data), entry.timestamp);
+				}
+				break;
 			case "modelChange":
 			case "thinkingLevelChange":
 			case "fileEntry":
@@ -1131,6 +1168,7 @@ export function rehydrateChatPanelFromTurns(
 				}
 				if (entry.role === "tool_result") {
 					const result = extractToolResult(entry);
+					const resultSummary = replayResultSummary(result);
 					const evictedReason = workingSet.evicted.get(entry.turnId)?.reason;
 					const fallbackId = result.id ?? pendingToolIds.pop() ?? null;
 					if (fallbackId) {
@@ -1143,7 +1181,7 @@ export function rehydrateChatPanelFromTurns(
 							result: displayReplayToolResult(result.result, options.unboundedToolBodies === true),
 							isError: result.isError,
 							...(result.durationMs !== undefined ? { durationMs: result.durationMs } : {}),
-							...(result.resultSummary !== undefined ? { resultSummary: result.resultSummary } : {}),
+							...(resultSummary !== undefined ? { resultSummary } : {}),
 							...(result.outcome !== undefined ? { outcome: result.outcome } : {}),
 							...(result.blockReason !== undefined ? { blockReason: result.blockReason } : {}),
 							...(evictedReason !== undefined ? { evictedReason } : {}),
@@ -1157,7 +1195,7 @@ export function rehydrateChatPanelFromTurns(
 									result: displayReplayToolResult(result.result, options.unboundedToolBodies === true),
 									isError: result.isError,
 									...(result.durationMs !== undefined ? { durationMs: result.durationMs } : {}),
-									...(result.resultSummary !== undefined ? { resultSummary: result.resultSummary } : {}),
+									...(resultSummary !== undefined ? { resultSummary } : {}),
 									...(result.outcome === "blocked" ? { outcome: "blocked" as const } : {}),
 									...(result.blockReason !== undefined ? { blockReason: result.blockReason } : {}),
 									...(evictedReason !== undefined ? { evictedReason } : {}),