@iowarp/clio-coder 0.3.8 → 0.4.0

package/src/interactive/turn-persistence.ts

@@ -5,6 +5,7 @@
  * append advances `state.lastTurnId`.
  */
 
+import type { BackendCompletionTimings } from "../core/cache-telemetry.js";
 import type { ClioSettings } from "../core/config.js";
 import type { MiddlewareToolChoiceControl } from "../domains/middleware/index.js";
 import type { ObservabilityContract } from "../domains/observability/contract.js";
@@ -39,7 +40,7 @@ export interface TurnPersistenceDeps {
 	/** Remove a queued-mirror entry once the engine injects it. */
 	removeQueuedMirrorEntry: (text: string) => void;
 	/** Prompt-cache record for a persisted assistant call (T3.2 + cold stamp). */
-	promptCachePayloadForAssistant: (usage: Usage) => Record<string, unknown>;
+	promptCachePayloadForAssistant: (usage: Usage, backend?: BackendCompletionTimings) => Record<string, unknown>;
 	/**
 	 * Prompt-side tokens the live context accounting holds for the turn in
 	 * flight. Used only to record what an interrupted call is known to have
@@ -228,7 +229,8 @@ export function createTurnPersistence(deps: TurnPersistenceDeps): TurnPersistenc
 		if (timing) payload.timing = timing;
 		const usage = (message as { usage?: Usage }).usage;
 		if (usage && typeof usage === "object") {
-			payload.promptCache = deps.promptCachePayloadForAssistant(usage);
+			const backendTimings = (message as { backendTimings?: BackendCompletionTimings }).backendTimings;
+			payload.promptCache = deps.promptCachePayloadForAssistant(usage, backendTimings);
 		}
 		// A cancelled turn's provider usage is the object the stream started with
 		// and never updated. Record what the call is known to have spent instead of
@@ -278,8 +280,16 @@ export function createTurnPersistence(deps: TurnPersistenceDeps): TurnPersistenc
 
 		appendQueuedUserTurn(message: AgentMessage): void {
 			if (message?.role !== "user") return;
-			const text = extractUserText(message).trim();
-			if (text.length === 0) return;
+			// Byte-exact. Trimming here wrote a second, shortened row that the
+			// assistant then parented to, so the model's parent turn disagreed with
+			// the expansion the operator actually submitted: `/raw   bar` produced a
+			// correct 5-byte row and a 3-byte one, and the 3-byte one won (issue
+			// #244). Only the emptiness test reads the trimmed form, and the
+			// echo/mirror lookups match on the same bytes the engine was given, so a
+			// payload with edge whitespace is recognized as the echo it is instead
+			// of being persisted a second time.
+			const text = extractUserText(message);
+			if (text.trim().length === 0) return;
 			if (deps.consumePersistedEcho(text)) return;
 			deps.removeQueuedMirrorEntry(text);
 			if (!deps.session) return;

package/src/interactive/turn-prewarm.ts

@@ -0,0 +1,364 @@
+/**
+ * Pre-warm ownership: when the prefix is sent, what stops it, and what it
+ * records. The round itself lives in `prewarm.ts`.
+ *
+ * Three moments hand the backend a prefix the operator has not paid for yet:
+ * the session prompt compiling at session start, a resume rebuilding the
+ * message array, and a compaction settling. All three leave a known prefix and
+ * an operator who is reading rather than waiting on a turn. Everything else is
+ * a refusal: another tier, a turn in flight, a running dispatch, a surface with
+ * nobody watching.
+ */
+
+import { BusChannels } from "../core/bus-events.js";
+import type { ClioSettings } from "../core/config.js";
+import type { SafeEventBus } from "../core/event-bus.js";
+import type { ProvidersContract } from "../domains/providers/index.js";
+import type { SessionContract } from "../domains/session/contract.js";
+import type { Usage } from "../engine/types.js";
+import { type PrewarmTrigger, prewarmPromptTokens, runPrewarmRound } from "./prewarm.js";
+import type { TurnContext } from "./turn-context.js";
+import type { AgentRuntime, ChatTurnState } from "./turn-state.js";
+
+/** Why a pre-warm did not run. Returned for contracts; never shown to the operator. */
+export type PrewarmSkipReason =
+	| "disabled"
+	| "surface"
+	| "turn-active"
+	| "dispatch-active"
+	| "tier"
+	| "unresolved"
+	| "superseded";
+
+export type PrewarmOutcome = { ran: true; trigger: PrewarmTrigger } | { ran: false; reason: PrewarmSkipReason };
+
+export interface TurnPrewarmDeps {
+	state: ChatTurnState;
+	getSettings: () => Readonly<ClioSettings>;
+	providers: ProvidersContract;
+	session?: SessionContract | undefined;
+	context: TurnContext;
+	bus?: SafeEventBus | undefined;
+	/**
+	 * True on a surface where a person is about to type the next turn. False for
+	 * headless `run`: the pre-warm buys latency an unattended run never spends.
+	 * Workers never reach here at all; they do not build a chat loop.
+	 */
+	isLatencySurface: () => boolean;
+	/** True while a submit owns, or is about to own, the turn state machine. */
+	isTurnActive: () => boolean;
+	/**
+	 * True while an attached dispatch is running. Detached runs are counted from
+	 * the bus instead, so a composition without this predicate still stands down
+	 * for the worker traffic the bus reports.
+	 */
+	hasActiveDispatch: () => boolean;
+	/** Resolve the runtime and credentials the next turn would use, or a refusal. */
+	prepareRuntime: (
+		signal: AbortSignal,
+	) => Promise<{ ok: true; runtime: AgentRuntime; apiKey: string | undefined } | { ok: false; reason: string }>;
+	/** Freeze the session tool surface onto the agent, exactly as a submit does. */
+	applySessionTools: (runtime: AgentRuntime) => void;
+	/** Report the round's provider usage under its own `/cost` label. */
+	recordUsage: (runtime: AgentRuntime, usage: Usage | null) => void;
+	/**
+	 * Claim one in-flight request on the runtime's endpoint for the duration of
+	 * the round, returning the release handle. This is the seam brief 06 (#250)
+	 * fills: on a merged tree the chat loop passes
+	 *
+	 *   (runtime) => {
+	 *     const key = canonicalEndpointKey(runtime.runtimeResolution.target);
+	 *     return key === null ? null : registerForegroundStream(key);
+	 *   }
+	 *
+	 * from `src/domains/providers/index.ts`, so endpoint capacity counts the
+	 * pre-warm the same way it counts the orchestrator's streaming turn. Until
+	 * then it is absent and `dispatchActive()` stands in with a blanket skip.
+	 */
+	registerEndpointSlot?: (runtime: AgentRuntime) => (() => void) | null;
+	/** Test seam. Production uses the real provider round. */
+	runPrewarm?: typeof runPrewarmRound;
+	/**
+	 * Whether a submit aborts the round's request. Defaults to the measured
+	 * backend behavior; see {@link ABORT_ROUND_ON_SUBMIT}.
+	 */
+	abortRoundOnSubmit?: boolean;
+}
+
+export interface TurnPrewarm {
+	/**
+	 * Queue a pre-warm for the next tick. Repeated calls before it fires collapse
+	 * onto one round: boot and a boot-time resume both land in the same tick, and
+	 * warming the pre-resume history would be work thrown away.
+	 */
+	schedule(trigger: PrewarmTrigger): void;
+	/** Stop an in-flight or queued pre-warm. The operator's turn owns the slot now. */
+	cancel(): void;
+	/** Resolves once nothing is queued or in flight. For contracts and shutdown. */
+	settled(): Promise<PrewarmOutcome | null>;
+	dispose(): void;
+}
+
+/**
+ * Whether a submit aborts the in-flight pre-warm's HTTP request, or only stops
+ * treating it as the current one.
+ *
+ * Measured against the operator's llama.cpp router, build `b226-2115b73d8`,
+ * Qwen3.8-27B, `--parallel 1`: aborting the request 1.5 s into a 47,620-token
+ * prefill did not cancel the server's work. The server finished prefilling, so
+ * the prefix did survive the abort, and the very next request read 47,596 of
+ * 47,620 tokens from cache and spent 927 ms in prompt. That request also waited
+ * 89.5 s of wall clock for the abandoned one to finish, on a server that serves
+ * one slot. Letting the pre-warm complete instead cost 89.3 s plus a 1.3 s turn:
+ * the same wall clock, arrived at honestly.
+ *
+ * The abort therefore frees no slot and saves the operator no time on this
+ * backend. All it does is discard the usage and timings of prefill the server
+ * performed, which is spend the ledger should carry. So a submit detaches the
+ * round: Clio stops calling it the current pre-warm and never waits on it, and
+ * it still records what it cost. Set this true for a backend that honors
+ * cancellation, where dropping the request genuinely releases the slot.
+ */
+const ABORT_ROUND_ON_SUBMIT = false;
+
+export function createTurnPrewarm(deps: TurnPrewarmDeps): TurnPrewarm {
+	const round = deps.runPrewarm ?? runPrewarmRound;
+	const abortOnSubmit = deps.abortRoundOnSubmit ?? ABORT_ROUND_ON_SUBMIT;
+	let pendingTrigger: PrewarmTrigger | null = null;
+	let timer: ReturnType<typeof setTimeout> | null = null;
+	let active: AbortController | null = null;
+	// Rounds a submit or a session switch let go of. Their result is still
+	// recorded, but it no longer describes the prefix the next turn will send, so
+	// it never reaches the `/context` line.
+	const detached = new WeakSet<AbortController>();
+	let inFlight: Promise<PrewarmOutcome | null> = Promise.resolve(null);
+	// Dispatch traffic Clio can see without an endpoint registry: the run
+	// lifecycle the bus already publishes. `hasActiveDispatch` covers the attached
+	// calls the composition root holds; this covers detached ones. Both are the
+	// stand-in for #250's per-endpoint slot accounting.
+	let dispatchesInFlight = 0;
+	const unsubscribeDispatch = [
+		deps.bus?.on(BusChannels.DispatchStarted, () => {
+			dispatchesInFlight += 1;
+		}) ?? null,
+		...[BusChannels.DispatchCompleted, BusChannels.DispatchFailed].map(
+			(channel) =>
+				deps.bus?.on(channel, () => {
+					dispatchesInFlight = Math.max(0, dispatchesInFlight - 1);
+				}) ?? null,
+		),
+	];
+	const dispatchActive = (): boolean => dispatchesInFlight > 0 || deps.hasActiveDispatch();
+
+	const admissionRefusal = (): PrewarmSkipReason | null => {
+		if (deps.getSettings().prewarm?.enabled === false) return "disabled";
+		if (!deps.isLatencySurface()) return "surface";
+		if (deps.state.streaming || deps.isTurnActive()) return "turn-active";
+		// Fleet interaction. Without per-endpoint slot accounting a pre-warm cannot
+		// know whether a worker is already occupying the server it would warm, so
+		// it stands down whenever any dispatch is outstanding. `registerEndpointSlot`
+		// is the other half: the round claims a slot on its endpoint while its
+		// request is out, so capacity sees it. Once that registry answers here too,
+		// this blanket skip narrows to "the endpoint is at its bound".
+		if (dispatchActive()) return "dispatch-active";
+		// The tier is settled from configuration before anything is resolved. The
+		// resolved runtime is checked again below, but asking here means a target
+		// that was never eligible costs no capability probe, no agent, and no
+		// notice from either.
+		const targetId = deps.getSettings().orchestrator?.target?.trim();
+		const runtimeId = targetId ? deps.providers.getTarget(targetId)?.runtime : undefined;
+		if (runtimeId === undefined || deps.providers.getRuntime(runtimeId)?.tier !== "local-native") return "tier";
+		return null;
+	};
+
+	const runOnce = async (trigger: PrewarmTrigger, controller: AbortController): Promise<PrewarmOutcome> => {
+		const refusal = admissionRefusal();
+		if (refusal) return { ran: false, reason: refusal };
+
+		const prepared = await deps.prepareRuntime(controller.signal);
+		if (!prepared.ok) return { ran: false, reason: "unresolved" };
+		const runtime = prepared.runtime;
+		if (deps.providers.getRuntime(runtime.runtimeId)?.tier !== "local-native") {
+			// Off on every other tier regardless of the setting. A cloud provider
+			// caches by exact prefix on its own schedule and bills the request; a
+			// pre-warm there is spend without a latency win.
+			return { ran: false, reason: "tier" };
+		}
+
+		deps.applySessionTools(runtime);
+		await deps.context.ensureSessionPrompt(runtime);
+
+		// Re-check after the awaits: a submit or a dispatch may have started while
+		// the prompt compiled, and the pre-warm must never be the request the
+		// operator's turn queues behind.
+		const lateRefusal = admissionRefusal();
+		if (lateRefusal) return { ran: false, reason: lateRefusal };
+		if (detached.has(controller) || controller.signal.aborted) return { ran: false, reason: "superseded" };
+
+		// The claim is taken before the request goes out and released in the
+		// finally, including on the detach path, because the request the server is
+		// still finishing is the one occupying the slot.
+		const releaseEndpointSlot = deps.registerEndpointSlot?.(runtime) ?? null;
+		let result: Awaited<ReturnType<typeof round>>;
+		try {
+			result = await round({
+				model: runtime.agent.state.model,
+				state: {
+					systemPrompt: runtime.agent.state.systemPrompt,
+					messages: runtime.agent.state.messages,
+					tools: runtime.agent.state.tools,
+					thinkingLevel: runtime.agent.state.thinkingLevel ?? "off",
+				},
+				...(prepared.apiKey !== undefined ? { apiKey: prepared.apiKey } : {}),
+				signal: controller.signal,
+			});
+		} finally {
+			releaseEndpointSlot?.();
+		}
+
+		// The prefill the server did is spend whatever the operator did next, so a
+		// let-go round is recorded exactly like a completed one. Only the
+		// `/context` line is withheld: it answers "is the prefix the next turn
+		// wants already resident", and a detached round is no longer about that
+		// prefix.
+		const wasDetached = detached.has(controller) || controller.signal.aborted;
+		const promptTokens = prewarmPromptTokens(result);
+		if (!wasDetached) {
+			deps.context.notePrewarm({
+				tokens: promptTokens,
+				ms: result.timing.apiMs,
+				aborted: result.aborted,
+			});
+		}
+		deps.recordUsage(runtime, result.usage);
+
+		try {
+			deps.session?.appendEntry({
+				kind: "custom",
+				customType: "prewarm",
+				// Never a model message and never a rendered transcript block: a
+				// pre-warm is a fact about the backend, not something the session said.
+				display: false,
+				parentTurnId: deps.state.lastTurnId,
+				data: {
+					trigger,
+					target: runtime.targetId,
+					model: runtime.wireModelId,
+					promptTokens,
+					aborted: result.aborted,
+					detached: wasDetached,
+					timing: result.timing,
+					promptCache: {
+						input: result.usage?.input ?? 0,
+						cacheRead: result.usage?.cacheRead ?? 0,
+						cacheWrite: result.usage?.cacheWrite ?? 0,
+						...(result.backend ? { backend: { ...result.backend } } : {}),
+					},
+					...(result.errorMessage ? { error: result.errorMessage } : {}),
+				},
+			});
+		} catch {
+			// The ledger entry is diagnostics. A session that refuses it must not
+			// turn an optimization into a failure.
+		}
+		return { ran: true, trigger };
+	};
+
+	/**
+	 * Let go of the round in flight. On a backend that honors cancellation this
+	 * also aborts the request; see {@link ABORT_ROUND_ON_SUBMIT} for why the
+	 * measured one does not.
+	 */
+	const releaseActiveRound = (): void => {
+		const controller = active;
+		if (controller === null) return;
+		detached.add(controller);
+		if (abortOnSubmit) controller.abort();
+		active = null;
+	};
+
+	const fire = (): void => {
+		timer = null;
+		const trigger = pendingTrigger;
+		pendingTrigger = null;
+		if (trigger === null) return;
+		const controller = new AbortController();
+		active = controller;
+		const previous = inFlight;
+		inFlight = previous
+			.catch(() => null)
+			.then(() => runOnce(trigger, controller))
+			.catch(() => null)
+			.finally(() => {
+				if (active === controller) active = null;
+			});
+	};
+
+	return {
+		schedule(trigger: PrewarmTrigger): void {
+			// A newer trigger describes a newer prefix; the older round is no longer
+			// warming history this session has.
+			releaseActiveRound();
+			pendingTrigger = trigger;
+			if (timer !== null) return;
+			// Ref'd on purpose, same reasoning as `settled()` below: the timer is due
+			// in 0 ms, so it holds the event loop for one tick at most, and a Node 22
+			// loop that drains past a due unref'd timer would otherwise never start
+			// the round a test or caller is already awaiting.
+			timer = setTimeout(fire, 0);
+		},
+
+		cancel(): void {
+			pendingTrigger = null;
+			if (timer !== null) {
+				clearTimeout(timer);
+				timer = null;
+			}
+			releaseActiveRound();
+		},
+
+		settled(): Promise<PrewarmOutcome | null> {
+			// One hop past the scheduling tick so a caller that just scheduled a
+			// round waits for that round rather than for the previous one. The timer
+			// is deliberately ref'd, unlike the scheduling timer above: the caller is
+			// awaiting this promise, so the event loop must stay alive for the one
+			// tick that lets the scheduled round start. Node 22 drains the loop past
+			// a due unref'd timer when nothing else holds it, which left this promise
+			// pending forever and cancelled every later test in the lane; Node 24
+			// happens to fire the due timer first, which is why the hang never
+			// reproduced on a 24.x development machine.
+			return new Promise((resolve) => {
+				setTimeout(() => {
+					resolve(inFlight.catch(() => null));
+				}, 0);
+			});
+		},
+
+		dispose(): void {
+			for (const unsubscribe of unsubscribeDispatch) unsubscribe?.();
+			pendingTrigger = null;
+			if (timer !== null) {
+				clearTimeout(timer);
+				timer = null;
+			}
+			// Shutdown always aborts: the process is going away, and a socket held
+			// open for a round nobody will read is not a latency question.
+			active?.abort();
+			active = null;
+		},
+	};
+}
+
+/**
+ * Subscribe the pre-warm to compaction settling. A summary or an eviction moves
+ * the byte prefix, so the next turn is known to be cold, and the operator is
+ * usually reading the summary rather than typing. The idle guard inside
+ * `schedule` is what keeps this from firing for the auto-compaction a submit
+ * runs on its way to the provider.
+ */
+export function subscribePrewarmToCompaction(bus: SafeEventBus | undefined, prewarm: TurnPrewarm): () => void {
+	const unsubscribe = bus?.on(BusChannels.CompactionEnd, () => {
+		prewarm.schedule("compaction");
+	});
+	return () => unsubscribe?.();
+}

package/src/interactive/turn-queues.ts

@@ -83,14 +83,17 @@ export function createTurnQueues(deps: TurnQueuesDeps): TurnQueues {
 	// works. The former per-steer transcript notice duplicated the panel and
 	// left a permanent line for a transient state.
 	const enqueue = (text: string, kind: QueuedMessageKind): boolean => {
-		const trimmed = text.trim();
-		if (trimmed.length === 0 || !state.streaming || !state.runtime) return false;
+		// The payload crosses to the model exactly as it was submitted; only the
+		// emptiness test reads a trimmed copy. A queued turn that shortened its own
+		// text here would land in the ledger disagreeing with the expansion that
+		// produced it, which is the same defect the persisted echo had (issue #244).
+		if (text.trim().length === 0 || !state.streaming || !state.runtime) return false;
 		const message = {
 			role: "user",
-			content: trimmed,
+			content: text,
 			timestamp: Date.now(),
 		} as AgentMessage;
-		queuedMirror.push({ text: trimmed, kind });
+		queuedMirror.push({ text, kind });
 		if (kind === "steer") {
 			state.runtime.agent.steer(message);
 		} else {

package/src/interactive/turn-runtime.ts

@@ -6,6 +6,7 @@
  */
 
 import { performance } from "node:perf_hooks";
+import type { BackendCompletionTimings } from "../core/cache-telemetry.js";
 import type { ClioSettings } from "../core/config.js";
 import { attributedModelId } from "../core/response-model-id.js";
 import type { MiddlewareToolChoiceControl } from "../domains/middleware/index.js";
@@ -192,6 +193,10 @@ export function createTurnRuntime(deps: TurnRuntimeDeps): TurnRuntime {
 			use: "orchestrator",
 			requireTools: false,
 			requireOutputBudget: true,
+			// A resumed session already knows what this backend had open; without
+			// it the first turn budgets against the probed server-wide figure and
+			// corrects only once discovery reports a loaded window (issue #227).
+			knownLoadedContextWindow: context.rememberedLoadedContextWindow(targetId, wireModelId),
 		});
 		if (!resolved.ok) {
 			const failure = resolved.diagnostics.find((entry) => entry.severity === "error") ?? resolved.diagnostics[0];
@@ -315,6 +320,7 @@ export function createTurnRuntime(deps: TurnRuntimeDeps): TurnRuntime {
 						use: "orchestrator",
 						requireTools: false,
 						requireOutputBudget: true,
+						knownLoadedContextWindow: context.rememberedLoadedContextWindow(target.target.id, target.wireModelId),
 					});
 					if (!refreshed.ok) return;
 					const liveModel = state.runtime.agent.state.model;
@@ -850,7 +856,8 @@ export function createTurnRuntime(deps: TurnRuntimeDeps): TurnRuntime {
 				if (isAssistant && usage && typeof usage === "object" && runFirstCallVerdict === null) {
 					const input = typeof usage.input === "number" ? usage.input : 0;
 					const cacheRead = typeof usage.cacheRead === "number" ? usage.cacheRead : 0;
-					runFirstCallVerdict = backendCacheVerdict(input, cacheRead);
+					const backendTimings = (enrichedEvent.message as { backendTimings?: BackendCompletionTimings }).backendTimings;
+					runFirstCallVerdict = backendCacheVerdict(input, cacheRead, backendTimings);
 				}
 				if (usage) {
 					context.reconcileUsage(usage);

package/src/interactive/turn-state.ts

@@ -53,6 +53,13 @@ export interface ChatLoopRunSnapshot {
 	cwd: string;
 }
 
+/**
+ * What a consumed prompt is doing before it owns the stream. `compacting` is
+ * the sub-state that made the defect visible, because it is the one that lasts
+ * long enough for an operator to conclude the keystroke was lost.
+ */
+export type TurnPreparationPhase = "idle" | "preparing" | "compacting";
+
 export interface ChatTurnState {
 	/** Live agent runtime; built or hot-swapped by turn-runtime. */
 	runtime: AgentRuntime | null;
@@ -60,6 +67,20 @@ export interface ChatTurnState {
 	lastTurnId: string | null;
 	/** True while a submit is in flight. */
 	streaming: boolean;
+	/**
+	 * Where a consumed prompt is between the editor and the live stream.
+	 *
+	 * The editor is cleared and the prompt painted into the transcript before
+	 * admission, and everything from the capability probe through pre-submit
+	 * compaction to the prompt compile happens after that and before
+	 * `streaming`. With nothing naming that window the composer went straight
+	 * back to `MESSAGE` and the footer still read the previous turn as done, so
+	 * a 77-second compaction was indistinguishable from a dropped Enter
+	 * (issue #251).
+	 */
+	turnPreparation: TurnPreparationPhase;
+	/** When the current preparation window opened, for its elapsed counter. */
+	turnPreparationSince: number;
 	/** Thinking level the active request runs under; read by onPayload. */
 	currentThinkingLevel: ThinkingLevel;
 	/** Provider context rebuilt on session switch, consumed by the next runtime build. */
@@ -115,6 +136,8 @@ export function createTurnState(initialThinkingLevel: ThinkingLevel): ChatTurnSt
 		runtime: null,
 		lastTurnId: null,
 		streaming: false,
+		turnPreparation: "idle",
+		turnPreparationSince: 0,
 		currentThinkingLevel: initialThinkingLevel,
 		replayedContextMessages: [],
 		activeUserTurnId: null,

package/src/interactive/view/artifacts.ts

@@ -5,12 +5,14 @@ import type { DispatchContract } from "../../domains/dispatch/contract.js";
 import { isReceiptIntegrity, verifyReceiptIntegrity } from "../../domains/dispatch/receipt-integrity.js";
 import type { RunEnvelope, RunReceipt } from "../../domains/dispatch/types.js";
 import { evidenceDirectory, inspectEvidence, listEvidenceOverviews } from "../../domains/evidence/store.js";
-import { formatTrustSummaryLine } from "../../domains/evidence/trust-projection.js";
+import { formatTrustSummaryLine, trustStateWord } from "../../domains/evidence/trust-projection.js";
 import {
 	inspectRunReceiptTrustStatus,
 	type ReceiptIntegrityOutcome,
 	retiredReceiptIntegrity,
 	retiredReceiptIntegrityReason,
+	TRUST_STATUS_AXES,
+	type TrustStatusAxis,
 } from "../../domains/evidence/trust-status.js";
 import type { EvidenceFinding, EvidenceOverview, EvidenceSource } from "../../domains/evidence/types.js";
 import { type AccountabilitySummary, readAccountabilitySummary } from "../../domains/observability/index.js";
@@ -113,6 +115,20 @@ const JSON_PRETTY_MAX_BYTES = 10 * 1024 * 1024;
 
 export type ReceiptVerifyResult = ReceiptIntegrityOutcome;
 
+export interface ReceiptVerificationCheck {
+	name: string;
+	ok: boolean;
+	evidence: string;
+}
+
+export type ReceiptVerificationReport = ReceiptIntegrityOutcome & {
+	receiptPath: string;
+	sealedDigest: string | null;
+	trustSummary: string | null;
+	compromised: boolean;
+	checks: ReceiptVerificationCheck[];
+};
+
 /**
  * What a verify action reports. `retired` marks a seal this build does not
  * verify because its integrity version was retired: not a pass, and not the
@@ -435,6 +451,98 @@ export function verifyReceiptFile(stateDir: string, runId: string): ReceiptVerif
 	return verifyReceiptIntegrity(r as unknown as RunReceipt, ledger.envelope);
 }
 
+const RECEIPT_FILE_FAILURE = /^(?:receipt file not found|read error:)/u;
+const RECEIPT_CONTRACT_FAILURE =
+	/^(?:invalid json:|receipt is not an object|missing field:|runId invalid:|runId mismatch:|agentId invalid:|task invalid:|targetId invalid:|wireModelId invalid:|runtimeId invalid:|runtimeKind invalid:|exitCode out of range:|tokenCount out of range:|inputTokenCount out of range:|outputTokenCount out of range:|cacheReadTokenCount out of range:|cacheWriteTokenCount out of range:|costUsd out of range:|reasoningTokenCount out of range:|startedAt not ISO-8601:|endedAt not ISO-8601:|clioVersion empty|piMonoVersion invalid:|platform invalid:|nodeVersion invalid:|toolCalls out of range:|toolStats\[|compiledPromptHash invalid:|staticCompositionHash invalid:|sessionId invalid:|integrity invalid|execution role invalid|routing intent invalid|route decision invalid)/u;
+const LEDGER_FAILURE = /^(?:run ledger not found|run not found in ledger|ledger mismatch:)/u;
+
+function receiptIntegrityDigest(value: unknown): string | null {
+	if (!isRecord(value) || value.algorithm !== "sha256" || !isNonEmptyString(value.digest)) return null;
+	return `sha256:${value.digest}`;
+}
+
+function trustCheckEvidence(status: ReturnType<typeof inspectRunReceiptTrustStatus>["status"], axis: string): string {
+	const entry = status[axis as keyof typeof status];
+	if (typeof entry !== "object" || entry === null || !("state" in entry)) return "canonical trust projection";
+	if (entry.state === "absent") return `reason=${entry.reason}`;
+	const refs = entry.artifacts.map((artifact) => `${artifact.kind}:${artifact.id}`);
+	return refs.length > 0 ? refs.join(", ") : `${entry.authority.kind}:${entry.authority.id}`;
+}
+
+function compromisedTrustAxes(status: ReturnType<typeof inspectRunReceiptTrustStatus>["status"]): TrustStatusAxis[] {
+	return TRUST_STATUS_AXES.filter((axis) => {
+		const state = status[axis].state;
+		if (axis === "artifactIntegrity") return state === "failed";
+		if (axis === "validationGrounding") return state === "failed" || state === "ungrounded";
+		if (axis === "independentReview") return state === "failed" || state === "not_independent";
+		if (axis === "contextProvenance") return state === "invalid";
+		if (axis === "autonomyEnforcement") return state === "bypassed";
+		return false;
+	});
+}
+
+/** Actionable `/view verify` report without changing the low-level verifier contract. */
+export function verifyReceiptFileReport(stateDir: string, runId: string): ReceiptVerificationReport {
+	const receiptPath = receiptFilePath(stateDir, runId);
+	const result = verifyReceiptFile(stateDir, runId);
+	let receipt: RunReceipt | null = null;
+	try {
+		receipt = JSON.parse(readFileSync(receiptPath, "utf8")) as RunReceipt;
+	} catch {
+		// The verifier's named file or JSON check below retains the actionable error.
+	}
+	const sealedDigest = receiptIntegrityDigest(receipt?.integrity);
+	const ledger = readRunEnvelope(stateDir, runId);
+	const inspection = receipt === null ? null : inspectRunReceiptTrustStatus(receipt, ledger.ok ? ledger.envelope : null);
+	const trustSummary = inspection === null ? null : formatTrustSummaryLine(inspection.status);
+	const compromiseAxes = inspection === null ? [] : compromisedTrustAxes(inspection.status);
+	const checks: ReceiptVerificationCheck[] = [];
+
+	if (!result.ok && RECEIPT_FILE_FAILURE.test(result.reason)) {
+		checks.push({ name: "receipt file", ok: false, evidence: `${receiptPath}: ${result.reason}` });
+	} else {
+		checks.push({ name: "receipt file", ok: true, evidence: receiptPath });
+		if (!result.ok && (RECEIPT_CONTRACT_FAILURE.test(result.reason) || result.retired !== undefined)) {
+			checks.push({ name: "receipt contract", ok: false, evidence: result.reason });
+		} else {
+			checks.push({
+				name: "receipt contract",
+				ok: true,
+				evidence: `current integrity v${receipt?.integrity.version ?? "unknown"}`,
+			});
+			if (!result.ok && LEDGER_FAILURE.test(result.reason)) {
+				checks.push({ name: "run ledger", ok: false, evidence: result.reason });
+			} else {
+				checks.push({ name: "run ledger", ok: true, evidence: `run ${runId} fields match` });
+				checks.push({
+					name: "sealed digest",
+					ok: result.ok,
+					evidence: result.ok ? `${sealedDigest ?? "digest unavailable"} matches receipt and ledger` : result.reason,
+				});
+			}
+		}
+	}
+
+	if (inspection !== null) {
+		for (const axis of compromiseAxes) {
+			checks.push({
+				name: `trust ${axis}`,
+				ok: false,
+				evidence: `${trustStateWord(axis, inspection.status[axis].state)}; ${trustCheckEvidence(inspection.status, axis)}`,
+			});
+		}
+	}
+
+	return {
+		...result,
+		receiptPath,
+		sealedDigest,
+		trustSummary,
+		compromised: compromiseAxes.length > 0,
+		checks,
+	};
+}
+
 function pushCapped(lines: string[], line: string, maxLines: number): boolean {
 	if (lines.length >= maxLines) return false;
 	lines.push(line);