@iowarp/clio-coder 0.3.8 → 0.3.9

package/src/interactive/mutation-preview.ts

@@ -0,0 +1,295 @@
+/**
+ * Local inspection of the exact mutation a parked `write` or `edit` would make.
+ *
+ * The approval card describes an unlisted argument by type and size, so a
+ * parked write read `content=<string 482 bytes>` and a parked edit read
+ * `edits=<array 3 items>`: the operator authorized bytes they had never seen,
+ * and the only way to read them was the external session ledger (issue #254).
+ *
+ * Two rules shape everything here. The preview is derived from the same
+ * arguments object the decision resumes, and it carries a digest of those
+ * arguments so the bytes on screen are verifiably the bytes being approved.
+ * And the mutation text is process-local: it is built lazily when the operator
+ * asks for it, it is handed only to the overlay body, and it is never placed on
+ * {@link import("./permission-overlay.js").ApprovalRequestView}, which is what
+ * crosses into the transcript, the notices, and the worker seam.
+ */
+
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { ToolNames } from "../core/tool-names.js";
+import { sanitizeCallTargetText, sanitizeMultilineDisplayText } from "../domains/safety/call-target.js";
+import {
+	applyEditsToNormalizedContent,
+	type Edit,
+	generateDiffString,
+	normalizeToLF,
+	stripBom,
+} from "../tools/edit-diff.js";
+import { resolveToCwd } from "../tools/path-utils.js";
+
+export { MUTATION_PREVIEW_KEY } from "./permission-hint.js";
+
+/** Rows of mutation shown at once. Anything longer scrolls, as `/handoff` review does. */
+export const MUTATION_PREVIEW_VISIBLE_ROWS = 16;
+
+/**
+ * Characters of proposed content the preview renders. The diff builder has its
+ * own byte backstop; this bounds the write path, whose payload is a whole file.
+ * Reaching it prints an explicit line naming what was withheld.
+ */
+export const MUTATION_PREVIEW_MAX_CHARS = 262_144;
+
+/**
+ * Facts about a parked mutation that may cross every process boundary: what
+ * kind it is, how big it is, and the digest that binds a preview to it. No part
+ * of the mutation text appears here, which is why this is the shape the
+ * approval view, the transcript row, and any notice may carry.
+ */
+export interface MutationFacts {
+	kind: "write" | "edit";
+	/** Bytes of proposed content (write), or of the replacement text across every edit. */
+	bytes: number;
+	/** Replacements in the edit list. One for a write. */
+	replacements: number;
+	/** Truncated SHA-256 over the exact call arguments this decision applies to. */
+	digest: string;
+}
+
+export interface MutationPreview {
+	facts: MutationFacts;
+	/** What the body is, named honestly on the overlay's first line. */
+	heading: string;
+	/** The complete rendered mutation, already sanitized and one entry per display row. */
+	body: ReadonlyArray<string>;
+	/** A control byte or escape sequence in the payload was neutralized for display. */
+	neutralized: boolean;
+	/** A tab was expanded, so columns are display columns. */
+	tabsExpanded: boolean;
+}
+
+/**
+ * Build the complete preview for the parked call, or explain why it cannot be
+ * built. Never throws: an unreadable file or an edit list that will not apply
+ * is itself something the operator needs to read before deciding.
+ */
+export type MutationInspector = () => MutationPreview;
+
+function canonicalJson(value: unknown): string {
+	if (value === null || value === undefined) return "null";
+	if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+	if (typeof value === "object") {
+		const entries = Object.entries(value as Record<string, unknown>)
+			.filter(([, entry]) => entry !== undefined)
+			.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+		return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`).join(",")}}`;
+	}
+	if (typeof value === "string") return JSON.stringify(value);
+	if (typeof value === "number") return Number.isFinite(value) ? JSON.stringify(value) : "null";
+	if (typeof value === "boolean") return value ? "true" : "false";
+	return "null";
+}
+
+/**
+ * The identity a decision is bound to. Key order and absent optional fields do
+ * not change it, so the same call digests the same way wherever it is read;
+ * anything else about the arguments does, which is the point: a call that
+ * differs from the previewed one cannot inherit its preview.
+ */
+export function callArgumentsDigest(args: Record<string, unknown> | undefined): string {
+	return createHash("sha256")
+		.update(canonicalJson(args ?? {}), "utf8")
+		.digest("hex")
+		.slice(0, 16);
+}
+
+function readEdits(value: unknown): Edit[] | null {
+	if (!Array.isArray(value)) return null;
+	const edits: Edit[] = [];
+	for (const entry of value) {
+		if (!entry || typeof entry !== "object" || Array.isArray(entry)) return null;
+		const record = entry as Record<string, unknown>;
+		if (typeof record.oldText !== "string" || typeof record.newText !== "string") return null;
+		edits.push({ oldText: record.oldText, newText: record.newText });
+	}
+	return edits;
+}
+
+/**
+ * The size-and-digest facts for a parked call, or null when the tool is not a
+ * file mutation or its arguments are not the shape this can describe. The card
+ * keeps rendering its allowlisted target either way.
+ */
+export function mutationFacts(tool: string, args: Record<string, unknown> | undefined): MutationFacts | null {
+	if (!args || typeof args.path !== "string" || args.path.length === 0) return null;
+	if (tool === ToolNames.Write) {
+		if (typeof args.content !== "string") return null;
+		return {
+			kind: "write",
+			bytes: Buffer.byteLength(args.content, "utf8"),
+			replacements: 1,
+			digest: callArgumentsDigest(args),
+		};
+	}
+	if (tool === ToolNames.Edit) {
+		const edits = readEdits(args.edits);
+		if (edits === null || edits.length === 0) return null;
+		const bytes = edits.reduce((total, edit) => total + Buffer.byteLength(edit.newText, "utf8"), 0);
+		return { kind: "edit", bytes, replacements: edits.length, digest: callArgumentsDigest(args) };
+	}
+	return null;
+}
+
+/** `write · 482 B · sha256 3f9a1c22ee04b7d1`, the collapsed card's whole mutation line. */
+export function mutationFactsLine(facts: MutationFacts): string {
+	const shape =
+		facts.kind === "write"
+			? `write ${facts.bytes} B`
+			: `edit ${facts.replacements} replacement${facts.replacements === 1 ? "" : "s"} · ${facts.bytes} B`;
+	return `${shape} · sha256 ${facts.digest}`;
+}
+
+function numberedLines(text: string): string[] {
+	const raw = text.split("\n");
+	const width = String(raw.length).length;
+	return raw.map((line, index) => `${String(index + 1).padStart(width, " ")} ${line}`);
+}
+
+function boundedContent(content: string): { text: string; withheld: number } {
+	if (content.length <= MUTATION_PREVIEW_MAX_CHARS) return { text: content, withheld: 0 };
+	return {
+		text: content.slice(0, MUTATION_PREVIEW_MAX_CHARS),
+		withheld: content.length - MUTATION_PREVIEW_MAX_CHARS,
+	};
+}
+
+function previewFrom(
+	facts: MutationFacts,
+	heading: string,
+	text: string,
+	options: { numbered?: boolean; trailer?: string } = {},
+): MutationPreview {
+	const clean = sanitizeMultilineDisplayText(text);
+	const body = options.numbered ? numberedLines(clean.text) : clean.text.split("\n");
+	if (options.trailer !== undefined) body.push(options.trailer);
+	return {
+		facts,
+		heading,
+		body,
+		neutralized: clean.neutralized,
+		tabsExpanded: clean.tabsExpanded,
+	};
+}
+
+function refusal(facts: MutationFacts, heading: string, reason: string): MutationPreview {
+	return { facts, heading, body: [reason], neutralized: false, tabsExpanded: false };
+}
+
+/**
+ * The requested replacements, rendered as a diff would render them, for the
+ * case where the effective diff cannot be computed. The operator still needs to
+ * read what the model asked for; the heading says this is the request rather
+ * than the effect.
+ */
+function replacementListing(edits: ReadonlyArray<Edit>): string {
+	const blocks: string[] = [];
+	for (const [index, edit] of edits.entries()) {
+		blocks.push(`@@ replacement ${index + 1} of ${edits.length}`);
+		for (const line of normalizeToLF(edit.oldText).split("\n")) blocks.push(`- ${line}`);
+		for (const line of normalizeToLF(edit.newText).split("\n")) blocks.push(`+ ${line}`);
+	}
+	return blocks.join("\n");
+}
+
+function editPreview(facts: MutationFacts, path: string, edits: ReadonlyArray<Edit>, read: (path: string) => string) {
+	let current: string;
+	try {
+		current = read(resolveToCwd(path));
+	} catch (error) {
+		const message = sanitizeCallTargetText(error instanceof Error ? error.message : String(error));
+		return previewFrom(
+			facts,
+			`Requested replacements for ${sanitizeCallTargetText(path)} (the file could not be read: ${message})`,
+			replacementListing(edits),
+		);
+	}
+	try {
+		const { text } = stripBom(current);
+		const applied = applyEditsToNormalizedContent(normalizeToLF(text), edits, path);
+		const diff = generateDiffString(applied.baseContent, applied.newContent);
+		return previewFrom(facts, `Effective diff for ${sanitizeCallTargetText(path)}`, diff.diff);
+	} catch (error) {
+		const message = sanitizeCallTargetText(error instanceof Error ? error.message : String(error));
+		return previewFrom(
+			facts,
+			`Requested replacements for ${sanitizeCallTargetText(path)} (they do not apply: ${message})`,
+			replacementListing(edits),
+		);
+	}
+}
+
+export interface MutationInspectorOptions {
+	/** Reads the current file bytes for an edit's effective diff. Injected so the contract test owns the filesystem. */
+	readFile?: (path: string) => string;
+}
+
+/**
+ * Bind an inspector to one parked call. The returned closure reads the file and
+ * computes the diff only when the operator presses the inspect key, and it
+ * re-derives the digest from the same arguments it renders: a mismatch means
+ * the arguments changed under the decision and the preview refuses rather than
+ * showing bytes that are no longer the ones being approved.
+ */
+export function createMutationInspector(
+	tool: string,
+	args: Record<string, unknown> | undefined,
+	facts: MutationFacts,
+	options: MutationInspectorOptions = {},
+): MutationInspector {
+	const read = options.readFile ?? ((path: string) => readFileSync(path, "utf8"));
+	return () => {
+		const current = mutationFacts(tool, args);
+		if (current === null || current.digest !== facts.digest) {
+			return refusal(
+				facts,
+				"Preview unavailable",
+				`These arguments no longer digest to sha256 ${facts.digest}. Deny this call rather than approving bytes that cannot be shown.`,
+			);
+		}
+		const path = typeof args?.path === "string" ? args.path : "";
+		if (facts.kind === "write") {
+			const content = typeof args?.content === "string" ? args.content : "";
+			const bounded = boundedContent(content);
+			return previewFrom(facts, `Proposed content for ${sanitizeCallTargetText(path)}`, bounded.text, {
+				numbered: true,
+				...(bounded.withheld > 0
+					? { trailer: `… ${bounded.withheld} more characters not shown (preview capped at ${MUTATION_PREVIEW_MAX_CHARS})` }
+					: {}),
+			});
+		}
+		const edits = readEdits(args?.edits) ?? [];
+		return editPreview(facts, path, edits, read);
+	};
+}
+
+/**
+ * The scrolled window of a preview, plus the position line that makes the cut
+ * visible. Mirrors the `/handoff` review overlay so both scrollable inspection
+ * surfaces read the same way.
+ */
+export function mutationPreviewWindow(
+	lines: ReadonlyArray<string>,
+	scroll: number,
+	rows = MUTATION_PREVIEW_VISIBLE_ROWS,
+): { window: ReadonlyArray<string>; position: string | null; maxScroll: number } {
+	const visible = Math.max(1, rows);
+	const maxScroll = Math.max(0, lines.length - visible);
+	const start = Math.max(0, Math.min(scroll, maxScroll));
+	const window = lines.slice(start, start + visible);
+	if (lines.length <= visible) return { window, position: null, maxScroll };
+	return {
+		window,
+		position: `(${start + 1}-${start + window.length} of ${lines.length} lines)`,
+		maxScroll,
+	};
+}

package/src/interactive/overlay-general-openers.ts

@@ -12,6 +12,7 @@ import {
 	proposeMemoryPromotion,
 } from "../domains/memory/index.js";
 import type { ObservabilityContract } from "../domains/observability/index.js";
+import { foregroundStreamUsage } from "../domains/providers/index.js";
 import type { ContextLedger } from "../domains/session/context-ledger.js";
 import type { SessionMeta } from "../domains/session/index.js";
 import { foldSessionArtifacts } from "../domains/session/session-artifacts.js";
@@ -147,6 +148,11 @@ export function createOverlayGeneralOpeners(deps: OverlayGeneralOpenersDeps): Ov
 		deps.transitions.state = "cost";
 		deps.transitions.handle = openCostOverlayFactory(deps.tui, deps.observability, {
 			sessionId: deps.getSessionId?.() ?? null,
+			...(deps.readSessionEntries
+				? {
+						getSessionEntries: () => deps.readSessionEntries?.() ?? [],
+					}
+				: {}),
 		});
 		deps.requestRender();
 	};
@@ -429,10 +435,20 @@ export function createOverlayGeneralOpeners(deps: OverlayGeneralOpenersDeps): Ov
 				};
 				const resolution = deps.dispatch.preview?.(request);
 				if (!resolution) return null;
+				const foregroundHeld =
+					resolution.endpoint === undefined ? 0 : (foregroundStreamUsage()[resolution.endpoint.key] ?? 0);
 				return {
 					targetId: resolution.targetId,
 					wireModelId: resolution.wireModelId,
 					nodeId: resolution.node.id,
+					...(resolution.endpoint !== undefined
+						? {
+								endpoint: {
+									...resolution.endpoint,
+									...(foregroundHeld > 0 ? { foregroundHeld } : {}),
+								},
+							}
+						: {}),
 				};
 			},
 		});

package/src/interactive/overlay-key-routing.ts

@@ -1,5 +1,6 @@
 import type { ClioKeybinding } from "../domains/config/keybindings.js";
 import { isKeyRelease, matchesKey } from "../engine/tui.js";
+import { MUTATION_PREVIEW_KEY } from "./permission-hint.js";
 
 export type OverlayState =
 	| "closed"
@@ -47,6 +48,11 @@ export interface PermissionOverlayKeyDeps {
 	 * the call. Only the deletion keys in `isDraftEditKey` arrive here.
 	 */
 	editDraft?: (data: string) => void;
+	/** Whether this card has a mutation the operator can read locally (issue #254). */
+	canInspectMutation?: () => boolean;
+	isInspectingMutation?: () => boolean;
+	toggleMutationInspection?: () => void;
+	scrollMutationInspection?: (delta: number) => void;
 }
 
 export interface DispatchBoardOverlayKeyDeps {
@@ -85,6 +91,18 @@ function isDraftEditKey(data: string): boolean {
 	return !isKeyRelease(data) && DRAFT_EDIT_KEYS.some((key) => matchesKey(data, key));
 }
 
+/** Rows one page key moves the open mutation. Matches the window the card renders. */
+const MUTATION_PAGE_ROWS = 16;
+
+/** How far a key scrolls the open mutation, or 0 when the key is not a scroll key. */
+function mutationScrollDelta(data: string): number {
+	if (matchesKey(data, "up")) return -1;
+	if (matchesKey(data, "down")) return 1;
+	if (matchesKey(data, "pageUp")) return -MUTATION_PAGE_ROWS;
+	if (matchesKey(data, "pageDown")) return MUTATION_PAGE_ROWS;
+	return 0;
+}
+
 /** Pure permission overlay key router: returns true when the input was consumed. */
 export function routePermissionOverlayKey(data: string, deps: PermissionOverlayKeyDeps): boolean {
 	if (matchesKey(data, "enter") && !isKeyRelease(data)) {
@@ -98,6 +116,26 @@ export function routePermissionOverlayKey(data: string, deps: PermissionOverlayK
 		deps.editDraft(data);
 		return true;
 	}
+	// Reading the mutation is the one thing this dialog does that is not an
+	// answer, so it toggles rather than navigating away: Enter, `s`, and Esc keep
+	// their meanings the whole time the mutation is on screen, and `v` is what
+	// puts it away. A card with nothing local to inspect leaves the key inert.
+	if (
+		matchesKey(data, MUTATION_PREVIEW_KEY) &&
+		!isKeyRelease(data) &&
+		(deps.canInspectMutation?.() ?? false) &&
+		deps.toggleMutationInspection
+	) {
+		deps.toggleMutationInspection();
+		return true;
+	}
+	if ((deps.isInspectingMutation?.() ?? false) && deps.scrollMutationInspection && !isKeyRelease(data)) {
+		const delta = mutationScrollDelta(data);
+		if (delta !== 0) {
+			deps.scrollMutationInspection(delta);
+			return true;
+		}
+	}
 	if (isEscapeKey(data)) {
 		deps.cancelPermission();
 		return true;

package/src/interactive/overlay-lifecycle.ts

@@ -12,6 +12,7 @@ import { createOverlayTransitions } from "./overlay-transitions.js";
 import {
 	createPermissionOverlayBody,
 	PERMISSION_OVERLAY_WIDTH,
+	type PermissionOverlayBodyHandle,
 	permissionOverlayHint,
 	permissionOverlayPlacement,
 	permissionOverlayTitle,
@@ -163,6 +164,12 @@ export interface OverlayLifecycleController {
 	toggleDispatchBoardOverlay(): void;
 	confirmPermission(): void;
 	stopTurnFromPermission(): void;
+	/** Whether the live permission card has a mutation the operator can read here. */
+	canInspectMutation(): boolean;
+	/** Whether that mutation is currently open. */
+	isInspectingMutation(): boolean;
+	toggleMutationInspection(): void;
+	scrollMutationInspection(delta: number): void;
 	cancelAskUser(): void;
 	dispose(): void;
 }
@@ -210,6 +217,16 @@ export function createOverlayLifecycle(deps: OverlayLifecycleRuntimeDeps): Overl
 	} = deps;
 	let overlayPermission: OverlayPermissionLifecycle | null = null;
 	let overlayAskUser: OverlayAskUserLifecycle | null = null;
+	/**
+	 * The live permission card's body, held only while its dialog is on screen.
+	 * The mutation text it can show lives here and nowhere else, so dropping the
+	 * reference when the dialog closes drops the text with it.
+	 */
+	let permissionBody: PermissionOverlayBodyHandle | null = null;
+	const inspectionHint = (): import("./permission-hint.js").PermissionInspectionHint => {
+		if (permissionBody === null || !permissionBody.canInspect()) return "none";
+		return permissionBody.isInspecting() ? "open" : "closed";
+	};
 	const overlayTransitions = createOverlayTransitions({
 		stopDispatchBoardTicker: () => interactiveTickers.stopDispatchBoardTicker(),
 		renderContextIsland: () => interactiveTickers.renderContextIsland(),
@@ -217,7 +234,10 @@ export function createOverlayLifecycle(deps: OverlayLifecycleRuntimeDeps): Overl
 		requestRender: () => tui.requestRender(),
 		cancelPendingAskUser: () => overlayAskUser?.cancelPending() ?? false,
 		finishAuth: (dismiss) => overlayAuth.finish(dismiss),
-		onPermissionOverlayClosed: () => overlayPermission?.onPermissionOverlayClosed(),
+		onPermissionOverlayClosed: () => {
+			permissionBody = null;
+			overlayPermission?.onPermissionOverlayClosed();
+		},
 		onOverlayClosed: () => overlayPermission?.retryPending(),
 	});
 	const closeOverlay = overlayTransitions.close;
@@ -248,17 +268,20 @@ export function createOverlayLifecycle(deps: OverlayLifecycleRuntimeDeps): Overl
 		dispatch: deps.app.dispatch,
 		getAutonomy: () => deps.app.getSettings?.().autonomy ?? "auto-edit",
 		getOverlayState: () => overlayTransitions.state,
-		openPermissionOverlay: (view) => {
+		openPermissionOverlay: (view, inspect) => {
 			if (overlayTransitions.state !== "closed") return false;
 			overlayTransitions.state = "permission-confirm";
-			overlayTransitions.handle = showOverlayFrame(tui, createPermissionOverlayBody(view), {
+			const body = createPermissionOverlayBody(view, inspect);
+			permissionBody = body;
+			overlayTransitions.handle = showOverlayFrame(tui, body, {
 				...permissionOverlayPlacement(tui, editor, footer.view),
 				width: PERMISSION_OVERLAY_WIDTH,
 				title: permissionOverlayTitle(view),
 				tone: permissionOverlayTone(view),
 				// Read per frame: the footer names what Enter does right now, and
-				// that depends on whether the composer holds a draft.
-				footerHint: (innerWidth) => permissionOverlayHint(innerWidth, editor.getText().length > 0),
+				// that depends on whether the composer holds a draft and on whether
+				// the mutation is open.
+				footerHint: (innerWidth) => permissionOverlayHint(innerWidth, editor.getText().length > 0, inspectionHint()),
 			});
 			tui.requestRender();
 			return true;
@@ -464,6 +487,16 @@ export function createOverlayLifecycle(deps: OverlayLifecycleRuntimeDeps): Overl
 			footer.refresh();
 			tui.requestRender();
 		},
+		canInspectMutation: () => permissionBody?.canInspect() ?? false,
+		isInspectingMutation: () => permissionBody?.isInspecting() ?? false,
+		toggleMutationInspection: () => {
+			permissionBody?.toggleInspect();
+			tui.requestRender();
+		},
+		scrollMutationInspection: (delta) => {
+			permissionBody?.scrollInspect(delta);
+			tui.requestRender();
+		},
 		cancelAskUser: overlayAskUser.cancel,
 		dispose: () => {
 			overlayPermission?.dispose();

package/src/interactive/overlay-permission-lifecycle.ts

@@ -11,6 +11,7 @@ import type { PermissionRequiredMeta, ToolRegistry } from "../tools/registry.js"
 import { approvalParkedNotice, autonomyDeniedNotice, workerEscalationNotice } from "./bus-notices.js";
 import type { ToolApprovalStateEvent } from "./chat-loop.js";
 import type { NoticeLevel } from "./command-output.js";
+import { createMutationInspector, type MutationInspector, mutationFacts } from "./mutation-preview.js";
 import type { OverlayState } from "./overlay-key-routing.js";
 import { type ApprovalRequestView, askAxis, describeCallTarget } from "./permission-overlay.js";
 
@@ -43,7 +44,12 @@ export interface OverlayPermissionLifecycleDeps {
 	dispatch: Pick<DispatchContract, "resolveWorkerPermission">;
 	getAutonomy(): string;
 	getOverlayState(): OverlayState;
-	openPermissionOverlay(view: ApprovalRequestView): boolean;
+	/**
+	 * Open the dialog for one parked call. `inspect` carries the complete
+	 * mutation text and is the only channel that does; it is process-local by
+	 * construction, so it is passed here rather than folded into the view.
+	 */
+	openPermissionOverlay(view: ApprovalRequestView, inspect?: MutationInspector): boolean;
 	closeOverlay(): void;
 	appendNotice(level: NoticeLevel, text: string): void;
 	applyApprovalState(event: ToolApprovalStateEvent): void;
@@ -131,6 +137,9 @@ function mainApprovalRequestView(
 			? { kind: "net" as const, ruleId: axisFromDecision.ruleId }
 			: { kind: "autonomy" as const, level: autonomy });
 	const target = describeCallTarget(call.tool, call.args);
+	// Facts only. The mutation text stays in the inspector the overlay opener
+	// gets; this object reaches the transcript row and the approval-state event.
+	const mutation = mutationFacts(call.tool, call.args);
 	return {
 		requestId: meta?.requestId ?? "permission-pending",
 		tool: call.tool,
@@ -144,10 +153,21 @@ function mainApprovalRequestView(
 			: {}),
 		...(call.tool === ToolNames.AskUser ? { exposure: askUserExposure(call.args) } : {}),
 		...(target.length > 0 ? { target } : {}),
+		...(mutation !== null ? { mutation } : {}),
 		...(queueDepth !== undefined && queueDepth > 1 ? { queueDepth } : {}),
 	};
 }
 
+/**
+ * The inspector for a main-agent ask, or undefined when there is nothing local
+ * to read. A worker escalation never gets one: its arguments stay in the
+ * worker, and the card says so rather than implying an inspection it cannot do.
+ */
+function mainMutationInspector(call: ClassifierCall, view: ApprovalRequestView): MutationInspector | undefined {
+	if (view.mutation === undefined) return undefined;
+	return createMutationInspector(call.tool, call.args, view.mutation);
+}
+
 function workerEscalationEntry(payload: PermissionRequestedPayload, autonomy: string): WorkerEscalationEntry | null {
 	if (!isLiveWorkerEscalationRequest(payload) || typeof payload.requestId !== "string") return null;
 	const origin = typeof payload.origin === "string" ? payload.origin : undefined;
@@ -240,7 +260,7 @@ export function createOverlayPermissionLifecycle(deps: OverlayPermissionLifecycl
 				announceParked();
 				return;
 			}
-			if (!deps.openPermissionOverlay(view)) {
+			if (!deps.openPermissionOverlay(view, mainMutationInspector(call, view))) {
 				announceParked();
 				return;
 			}

package/src/interactive/overlay-session-lifecycle.ts

@@ -403,19 +403,83 @@ export function createOverlaySessionLifecycle(deps: OverlaySessionLifecycleDeps)
 		void runHandoffExtraction(session, fromSessionId, verdict.goal);
 	}
 
+	/** Characters of the second round's answer quoted in the terminal refusal. */
+	const HANDOFF_REFUSAL_QUOTE_CHARS = 200;
+
+	/**
+	 * A refusal that says what was asked for and what came back, not only that no
+	 * JSON object arrived. Both rounds are named, so an operator reading it knows
+	 * two model calls were spent and on what.
+	 */
+	function terminalHandoffRefusal(firstReason: string, secondReason: string, secondText: string): string {
+		const answered = secondText.replace(/\s+/g, " ").trim().slice(0, HANDOFF_REFUSAL_QUOTE_CHARS);
+		return [
+			"the extraction round could not produce a handoff record after one repair attempt.",
+			`Asked for: one JSON object with decisions, facts, files, commands, and openQuestions.`,
+			`Round 1: ${firstReason}.`,
+			`Round 2: ${secondReason}.`,
+			`Round 2 returned: ${answered.length > 0 ? answered : "(nothing)"}`,
+		].join(" ");
+	}
+
+	/**
+	 * Extract, then repair once.
+	 *
+	 * A local model that answers with prose around the object, or with nothing
+	 * parseable, used to end `/handoff` outright: every downstream behavior (the
+	 * dropped-path listing, the `e` editor, accept-mints-a-session) was
+	 * unreachable and the operator had paid for the round either way (issue
+	 * #223). Exactly one repair round follows, quoting what came back and what
+	 * the parser objected to, and both rounds bill through the same out-of-turn
+	 * usage store.
+	 */
+	async function extractWithOneRepair(
+		goal: string,
+	): Promise<
+		| { ok: true; parsed: Extract<ReturnType<typeof parseHandoffExtraction>, { ok: true }> }
+		| { ok: false; level: "error" | "warn"; reason: string }
+	> {
+		const first = await deps.chat.extractHandoff(goal);
+		if (first.status !== "answered") {
+			return {
+				ok: false,
+				level: first.status === "failed" ? "error" : "warn",
+				reason: first.status === "aborted" ? "the extraction round was cancelled" : first.reason,
+			};
+		}
+		const parsedFirst = parseHandoffExtraction(first.text);
+		if (parsedFirst.ok) return { ok: true, parsed: parsedFirst };
+
+		const second = await deps.chat.extractHandoff(goal, {
+			repair: { complaint: parsedFirst.reason, previous: first.text },
+		});
+		if (second.status !== "answered") {
+			return {
+				ok: false,
+				level: second.status === "failed" ? "error" : "warn",
+				reason:
+					second.status === "aborted"
+						? "the repair round was cancelled"
+						: `round 1 could not be read (${parsedFirst.reason}); the repair round then failed: ${second.reason}`,
+			};
+		}
+		const parsedSecond = parseHandoffExtraction(second.text);
+		if (parsedSecond.ok) return { ok: true, parsed: parsedSecond };
+		return {
+			ok: false,
+			level: "error",
+			reason: terminalHandoffRefusal(parsedFirst.reason, parsedSecond.reason, second.text),
+		};
+	}
+
 	async function runHandoffExtraction(session: SessionContract, fromSessionId: string, goal: string): Promise<void> {
 		const notice = deps.getSlashNotice();
-		const outcome = await deps.chat.extractHandoff(goal);
-		if (outcome.status !== "answered") {
-			const reason = outcome.status === "aborted" ? "the extraction round was cancelled" : outcome.reason;
-			emitCommandNotice(notice, outcome.status === "failed" ? "error" : "warn", "handoff", reason);
-			return;
-		}
-		const parsed = parseHandoffExtraction(outcome.text);
-		if (!parsed.ok) {
-			emitCommandNotice(notice, "error", "handoff", parsed.reason);
+		const extraction = await extractWithOneRepair(goal);
+		if (!extraction.ok) {
+			emitCommandNotice(notice, extraction.level, "handoff", extraction.reason);
 			return;
 		}
+		const parsed = extraction.parsed;
 		const meta = session.current();
 		const cwd = typeof meta?.cwd === "string" && meta.cwd.length > 0 ? meta.cwd : null;
 		const entries = deps.readStructuredEntries(fromSessionId);