@iowarp/clio-coder 0.3.8 → 0.4.0

package/src/interactive/overlays/side-question.ts

@@ -112,6 +112,7 @@ export function openSideQuestionOverlay(tui: TUI, options: OpenSideQuestionOverl
 	const handle = showClioOverlayFrame(tui, body, {
 		anchor: "center",
 		width: sideQuestionOverlayWidth(options.columns),
+		markerId: "side-question",
 		title: SIDE_QUESTION_OVERLAY_TITLE,
 		// Esc means two things here and the footer names the live one: it aborts a
 		// round that is still streaming, and it closes one that has settled.

package/src/interactive/overlays/skills-hub.ts

@@ -26,6 +26,7 @@ import type { NoticeLevel } from "../command-output.js";
 import { clioTheme, GLYPH } from "../theme/index.js";
 import type { LibraryInstallConfirmSubject } from "./library-install-confirm.js";
 import { openLibraryInstallConfirmOverlay } from "./library-install-confirm.js";
+import { isLibraryTab, LIBRARY_TABS } from "./library-tabs.js";
 import { type ListOverlayItem, type ListOverlayTab, openListOverlay } from "./list-overlay.js";
 
 /**
@@ -53,23 +54,13 @@ const GROUP_DIAGNOSTICS = "Diagnostics";
 const GROUP_INSTALLED = "Installed";
 const GROUP_AVAILABLE = "Available";
 
-/** The hub's tabs, in the order ←/→ walks them. `skill` is the original view. */
-export const LIBRARY_TABS: ReadonlyArray<{ id: LibraryEntryKind; label: string }> = [
-	{ id: "skill", label: "Skills" },
-	{ id: "agent", label: "Agents" },
-	{ id: "prompt", label: "Prompts" },
-	{ id: "fleet", label: "Fleets" },
-];
+export { isLibraryTab, LIBRARY_TABS };
 
 export const SKILLS_HUB_TITLE = "Skills Hub";
 
 /** Row id prefix for a library row, which is how an action tells the tabs apart. */
 export const LIBRARY_ROW_PREFIX = "library:";
 
-export function isLibraryTab(value: string): value is LibraryEntryKind {
-	return LIBRARY_TABS.some((tab) => tab.id === value);
-}
-
 /** @internal exported for contract tests */
 export const SKILLS_HUB_EMPTY =
 	"no skills installed and no local marketplace configured. install one with `clio-coder skills install <path|github-url>`, or point CLIO_CODER_SKILL_CATALOG_DIR at a skills/ catalog.";
@@ -557,6 +548,7 @@ export function openSkillsHub(tui: TUI, deps: SkillsHubDeps): OverlayHandle {
 	};
 
 	handle = openListOverlay(tui, {
+		markerId: "skills-hub",
 		title: SKILLS_HUB_TITLE,
 		items: [],
 		tabs,

package/src/interactive/overlays/tree-selector.ts

@@ -416,6 +416,7 @@ export function openTreeOverlay(tui: TUI, deps: OpenTreeOverlayDeps): OverlayHan
 	return showClioOverlayFrame(tui, box, {
 		anchor: "center",
 		width: TREE_OVERLAY_WIDTH,
+		markerId: "tree",
 		title: "Session Tree",
 		footerHint: () => view.getHint(),
 	});

package/src/interactive/pane-policy.ts

@@ -0,0 +1,46 @@
+/**
+ * The one decision function for opening a run-watching pane.
+ *
+ * Policy, stated whole: panes are pulled by the operator, never pushed by the
+ * fleet. A dispatch starting, detaching, backgrounding, or failing opens
+ * nothing; the native surfaces (transcript, Alt+W board, footer) already carry
+ * that state, and the v0.3/v0.4 behavior of opening a hidden viewer pane per
+ * dispatch produced panes nobody had asked for. A pane opens only when the
+ * operator names a run: Enter in the workers view, `/panes show`, or the
+ * `panes` tool acting on the conversation's behalf.
+ *
+ * The `dispatch` source is the seam for ever marking a dispatch watchable at
+ * enqueue time. It exists so the decision stays in this one function; today it
+ * always refuses, and any future exception must be argued here, not in a
+ * config key.
+ *
+ * This module is a leaf on purpose: `panes-runtime.ts` is a boundaries seam
+ * whose value closure must stay off the render graph, so the policy cannot
+ * live beside the dispatch board that shares its status vocabulary.
+ */
+
+export type PaneWatchSource = "workers-view" | "slash" | "tool" | "dispatch";
+
+/** Statuses with a live process behind them, in the dispatch board's vocabulary. */
+const WATCHABLE_STATUSES = new Set(["running", "stale", "cancelling", "enqueued", "retrying"]);
+
+export interface PaneWatchRequest {
+	source: PaneWatchSource;
+	/** The run's lifecycle status; anything unrecognized reads as terminal. */
+	runStatus: string;
+}
+
+export type PaneWatchDecision = { open: true } | { open: false; reason: string };
+
+export function paneWatchDecision(request: PaneWatchRequest): PaneWatchDecision {
+	if (request.source === "dispatch") {
+		return { open: false, reason: "dispatches run headless; watch a run from the workers view or /panes show" };
+	}
+	if (!WATCHABLE_STATUSES.has(request.runStatus)) {
+		return {
+			open: false,
+			reason: `run is ${request.runStatus}; use \`clio-coder fleet view <runId>\` for the post-mortem`,
+		};
+	}
+	return { open: true };
+}

package/src/interactive/panes-runtime.ts

@@ -0,0 +1,292 @@
+/**
+ * The one implementation of `PanesOperations`, shared by `/panes` and the
+ * `panes` orchestrator tool.
+ *
+ * Two rules run through it. Presets probe their binary through the toolchain
+ * ladder *before* the pane is split: `openUtilityPane` delivers its command by
+ * sending `exec <argv>` into the pane's shell, so a binary that is not there
+ * kills the pane the instant it appears, and the operator sees a flicker
+ * instead of an install hint (phase 1 report, open question 3). And every
+ * mutation is scoped to panes Clio created, because the contract's registry
+ * refuses anything else.
+ *
+ * `show` targets running dispatches, not panes: it resolves a fuzzy agent id
+ * or run-id prefix against the live dispatch snapshot and points the shared
+ * watch pane at the match, under the one policy decision in
+ * `pane-policy.ts`. There is no per-run pane inventory to search any more.
+ */
+
+import type { ClioSettings } from "../core/config.js";
+import type { DispatchSnapshot } from "../domains/dispatch/contract.js";
+import {
+	newestRunEventJournalRunId,
+	runEventJournalPath,
+	runEventJournalRoot,
+} from "../domains/dispatch/run-event-journal.js";
+import type { MuxContract, MuxPaneRecord } from "../domains/mux/index.js";
+import {
+	PANES_PRESETS,
+	type PanesCloseResult,
+	type PanesInventoryEntry,
+	type PanesOpenResult,
+	type PanesOperations,
+	type PanesShowResult,
+	type PanesStatus,
+	type PanesWatchController,
+	type PanesYaziController,
+	type PanesYaziStatus,
+} from "../domains/mux/operations.js";
+import { resolveBinary } from "../tools/executables.js";
+import { type PaneWatchSource, paneWatchDecision } from "./pane-policy.js";
+
+export interface PanesRuntimeDeps {
+	mux: MuxContract;
+	getSettings: () => Readonly<ClioSettings>;
+	/** Live dispatch state, used to turn a fuzzy agent id into a run id. */
+	getDispatchSnapshot: () => DispatchSnapshot;
+	getCwd: () => string;
+	/** Injection seam for tests; production uses the toolchain ladder. */
+	resolveBinaryPath?: (name: string) => string | null;
+	/** Journal root override for tests. */
+	journalRoot?: () => string;
+	/** Newest run whose journal exists, for the `logs` preset. */
+	newestJournalRunId?: () => string | null;
+}
+
+const UNAVAILABLE = "the pane layer is not available in this session";
+
+function inventory(records: ReadonlyArray<MuxPaneRecord>): ReadonlyArray<PanesInventoryEntry> {
+	return records.map((record) => ({
+		paneId: record.ref.paneId,
+		tabId: record.ref.tabId,
+		purpose: record.purpose,
+		label: record.label,
+		adopted: record.adopted === true,
+	}));
+}
+
+export function createPanesRuntime(deps: PanesRuntimeDeps): PanesOperations {
+	const probe = deps.resolveBinaryPath ?? resolveBinary;
+	const journalRoot = deps.journalRoot ?? runEventJournalRoot;
+	let yaziController: PanesYaziController | null = null;
+	let watchController: PanesWatchController | null = null;
+	let nextPendingOpen = 0;
+	const pendingOpens = new Map<string, PanesInventoryEntry>();
+	const beginPendingOpen = (label: string): string => {
+		nextPendingOpen += 1;
+		const id = `pending:${nextPendingOpen}`;
+		pendingOpens.set(id, {
+			paneId: id,
+			tabId: "pending",
+			purpose: "utility",
+			label,
+			adopted: false,
+			pending: true,
+		});
+		return id;
+	};
+	const closedYaziStatus = (): PanesYaziStatus => ({
+		mode: "closed",
+		paneId: null,
+		paneCwd: null,
+		lastLineAt: null,
+		droppedLines: 0,
+	});
+
+	/**
+	 * Resolve one operator- or model-supplied target to a live dispatched run.
+	 *
+	 * Fuzzy agent id first, then runId prefix, most recent run winning: "the
+	 * tester" is what an operator types; a run id is what a tool call carries.
+	 * Retrying runs count as live; the watch pane shows them coming back.
+	 */
+	const matchRun = (target: string): { runId: string; agentId: string; status: string } | null => {
+		const needle = target.trim().toLowerCase();
+		if (needle.length === 0) return null;
+		const snapshot = deps.getDispatchSnapshot();
+		const live = [
+			...snapshot.running.map((run) => ({ runId: run.runId, agentId: run.agentId, status: "running" })),
+			...snapshot.retrying.map((run) => ({ runId: run.runId, agentId: run.agentId, status: "retrying" })),
+		];
+		// Newest first, so "the tester" means the tester the operator just started.
+		const newestFirst = [...live].reverse();
+		const byAgent = newestFirst.find((run) => run.agentId.toLowerCase().includes(needle));
+		if (byAgent) return byAgent;
+		return newestFirst.find((run) => run.runId.toLowerCase().startsWith(needle)) ?? null;
+	};
+
+	/** argv for one preset, once its binary has been found. */
+	const presetArgv = (presetId: string, binaryPath: string): ReadonlyArray<string> | null => {
+		if (presetId === "shell") return [binaryPath, "-l"];
+		if (presetId === "logs") {
+			const runId = (deps.newestJournalRunId ?? (() => newestRunEventJournalRunId(journalRoot())))();
+			if (runId === null) return null;
+			// `-F` rather than `-f`: the journal is recreated when its run's
+			// directory is pruned, and a viewer following an inode would silently
+			// stop at that point.
+			return [binaryPath, "-n", "200", "-F", runEventJournalPath(runId, journalRoot())];
+		}
+		return null;
+	};
+
+	const show = async (target: string, source: PaneWatchSource): Promise<PanesShowResult> => {
+		if (!deps.mux.available()) return { status: "unavailable", reason: UNAVAILABLE };
+		const match = matchRun(target);
+		if (match === null) {
+			// The candidate list is what turns a miss into a next step: it names
+			// the runs that are actually live right now.
+			const snapshot = deps.getDispatchSnapshot();
+			const candidates = [
+				...new Set([...snapshot.running.map((run) => run.agentId), ...snapshot.retrying.map((run) => run.agentId)]),
+			];
+			return { status: "not-found", target, candidates };
+		}
+		const decision = paneWatchDecision({ source, runStatus: match.status });
+		if (!decision.open) return { status: "refused", reason: decision.reason };
+		if (watchController === null) {
+			return { status: "unavailable", reason: "the watch pane is not wired in this session" };
+		}
+		const watched = await watchController.watch(match.runId);
+		if (watched.status !== "watching") return { status: "unavailable", reason: watched.reason };
+		return { status: "watching", runId: match.runId, agentId: match.agentId, opened: watched.opened };
+	};
+
+	return {
+		status(): PanesStatus {
+			const detection = deps.mux.detection();
+			const panes = deps.getSettings().panes;
+			return {
+				mode: deps.mux.mode,
+				available: deps.mux.available(),
+				reason: detection.reason,
+				socketPath: detection.socketPath,
+				server: detection.server,
+				settings: {
+					enabled: panes.enabled,
+					notifications: panes.notifications,
+					journal: panes.journal,
+					yazi: { ...panes.yazi },
+				},
+				yazi: yaziController?.status() ?? closedYaziStatus(),
+				panes: [...inventory(deps.mux.list()), ...pendingOpens.values()],
+			};
+		},
+
+		show(target: string): Promise<PanesShowResult> {
+			// The slash command and the tool share this implementation; the policy
+			// treats both as operator pull, so the source only matters for logs.
+			return show(target, "slash");
+		},
+
+		async open(request: { preset?: string; argv?: ReadonlyArray<string>; once?: boolean }): Promise<PanesOpenResult> {
+			const cwd = deps.getCwd();
+			if (request.preset !== undefined) {
+				const preset = PANES_PRESETS.find((entry) => entry.id === request.preset);
+				if (!preset) {
+					return { status: "refused", reason: `unknown preset: ${request.preset}` };
+				}
+				if (preset.id === "yazi") {
+					if (!deps.getSettings().panes.yazi.enabled) {
+						return { status: "refused", reason: "the files pane is disabled by panes.yazi.enabled" };
+					}
+					if (!yaziController) {
+						return { status: "unavailable", reason: "the files-pane return path is not ready" };
+					}
+					const pendingId = beginPendingOpen(preset.id);
+					try {
+						const result = await yaziController.open(request.once ? { once: true } : undefined);
+						if (result.status === "opened") {
+							return { status: "opened", label: preset.id, paneId: result.paneId };
+						}
+						if (result.status === "missing-binary") {
+							return {
+								status: "missing-binary",
+								preset: preset.id,
+								binary: result.binary,
+								installHint: preset.installHint,
+								detail: result.detail,
+							};
+						}
+						return {
+							status: result.status === "profile-error" ? "refused" : "unavailable",
+							reason: result.reason,
+						};
+					} finally {
+						pendingOpens.delete(pendingId);
+					}
+				}
+				if (!deps.mux.available()) return { status: "unavailable", reason: UNAVAILABLE };
+				const binaryPath = probe(preset.binary);
+				if (binaryPath === null) {
+					return {
+						status: "missing-binary",
+						preset: preset.id,
+						binary: preset.binary,
+						installHint: preset.installHint,
+						detail: `${preset.binary} was not found (install with \`${preset.installHint}\`)`,
+					};
+				}
+				const argv = presetArgv(preset.id, binaryPath);
+				if (argv === null) {
+					return { status: "refused", reason: `preset ${preset.id} has nothing to show yet` };
+				}
+				const pendingId = beginPendingOpen(preset.id);
+				try {
+					const ref = await deps.mux.openUtilityPane({ argv, cwd, label: preset.id });
+					if (ref === null) return { status: "unavailable", reason: `pane host refused to open ${preset.id}` };
+					return { status: "opened", label: preset.id, paneId: ref.paneId };
+				} finally {
+					pendingOpens.delete(pendingId);
+				}
+			}
+			if (!deps.mux.available()) return { status: "unavailable", reason: UNAVAILABLE };
+			const argv = request.argv ?? [];
+			if (argv.length === 0) return { status: "refused", reason: "nothing to run" };
+			const label = argv[0] ?? "pane";
+			const pendingId = beginPendingOpen(label);
+			try {
+				const ref = await deps.mux.openUtilityPane({ argv, cwd, label });
+				if (ref === null) return { status: "unavailable", reason: `pane host refused to open ${label}` };
+				return { status: "opened", label, paneId: ref.paneId };
+			} finally {
+				pendingOpens.delete(pendingId);
+			}
+		},
+
+		async close(target: string): Promise<PanesCloseResult> {
+			if (!deps.mux.available()) return { status: "unavailable", reason: UNAVAILABLE };
+			const owned = deps.mux.list();
+			if (target === "all") {
+				const labels: string[] = [];
+				// Snapshot first: closing mutates the registry the list came from.
+				for (const record of [...owned]) {
+					if (await deps.mux.closePane(record.ref.paneId)) labels.push(record.label);
+				}
+				return { status: "closed", closed: labels.length, labels };
+			}
+			const needle = target.trim().toLowerCase();
+			const newestFirst = [...owned].reverse();
+			const match =
+				newestFirst.find((record) => record.ref.paneId.toLowerCase() === needle) ??
+				newestFirst.find((record) => record.label.toLowerCase().includes(needle)) ??
+				newestFirst.find((record) => record.purpose === needle);
+			if (!match) return { status: "not-found", target };
+			const closed = await deps.mux.closePane(match.ref.paneId);
+			return closed ? { status: "closed", closed: 1, labels: [match.label] } : { status: "not-found", target };
+		},
+
+		attachYazi(controller: PanesYaziController): () => void {
+			yaziController = controller;
+			return () => {
+				if (yaziController === controller) yaziController = null;
+			};
+		},
+
+		attachWatch(controller: PanesWatchController): () => void {
+			watchController = controller;
+			return () => {
+				if (watchController === controller) watchController = null;
+			};
+		},
+	};
+}

package/src/interactive/permission-hint.ts

@@ -1,5 +1,19 @@
 import type { HintEntry } from "./overlay-frame.js";
 
+/**
+ * The key that opens and closes local inspection of a parked mutation. It lives
+ * here rather than beside the preview builder so the composer rail can name it
+ * without pulling the diff machinery into the Stage 0 boot shell closure.
+ */
+export const MUTATION_PREVIEW_KEY = "v";
+
+/**
+ * Whether this card has a mutation to read, and whether it is open.
+ * `none` covers every ask with nothing local to inspect, including a worker
+ * escalation, whose arguments never leave the worker.
+ */
+export type PermissionInspectionHint = "none" | "closed" | "open";
+
 /**
  * The keys that answer a parked call, as data, so the dialog footer and the
  * composer rail render the same policy at any width.
@@ -16,17 +30,35 @@ import type { HintEntry } from "./overlay-frame.js";
  *
  * Esc says `deny`, not `close`: closing the dialog denies the call, and on the
  * one surface where a misread is a wrong decision about a tool call the key
- * names its effect.
+ * names its effect. It keeps that meaning while the mutation is open, so the
+ * inspect key is what puts the mutation away again.
  *
  * With a draft in the composer, Enter is inert (issue #186): the habitual send
  * key must not resolve toward "allow" on a safety rail. The entry then says so
  * and names the key that clears the draft, which the router passes through.
+ *
+ * A parked `write` or `edit` adds the inspect key (issue #254). It is
+ * droppable, and deliberately so: at 40 columns the four entries do not fit,
+ * and the three keys that answer the call outrank the one that reads it. The
+ * key keeps working at every width; the `/help` Autonomy & safety net topic is
+ * where it is documented for the widths that cannot show it.
  */
-export function permissionHintEntries(composerHasDraft = false): HintEntry[] {
+export function permissionHintEntries(
+	composerHasDraft = false,
+	inspection: PermissionInspectionHint = "none",
+): HintEntry[] {
 	return [
 		composerHasDraft
 			? { key: "Backspace", verb: "clear the draft to allow", short: "clear draft", critical: true }
 			: { key: "Enter", verb: "allow once", short: "allow", critical: true },
+		...(inspection === "none"
+			? []
+			: inspection === "open"
+				? [
+						{ key: "↑↓", verb: "scroll", critical: false },
+						{ key: MUTATION_PREVIEW_KEY, verb: "hide mutation", short: "hide", critical: false },
+					]
+				: [{ key: MUTATION_PREVIEW_KEY, verb: "inspect mutation", short: "inspect", critical: false }]),
 		{ key: "s", verb: "stop turn", short: "stop", critical: true },
 		// With a draft, deny and stop are the only immediate answers, so Esc
 		// outranks the narrowing that would otherwise drop it first.

package/src/interactive/permission-overlay.ts

@@ -6,13 +6,21 @@ import {
 	decisionFactsForPermission,
 } from "../domains/safety/decision-presentation.js";
 import type { Component, OverlayOptions, TUI } from "../engine/tui.js";
+import {
+	MUTATION_PREVIEW_VISIBLE_ROWS,
+	type MutationFacts,
+	type MutationInspector,
+	type MutationPreview,
+	mutationFactsLine,
+	mutationPreviewWindow,
+} from "./mutation-preview.js";
 import { fitHintEntries } from "./overlay-frame.js";
-import { permissionHintEntries } from "./permission-hint.js";
+import { MUTATION_PREVIEW_KEY, type PermissionInspectionHint, permissionHintEntries } from "./permission-hint.js";
 import type { ClioToken } from "./theme/index.js";
 
 export { type AskAxis, askAxis } from "../domains/safety/approval-axis.js";
 export { describeCallTarget, sanitizeCallTargetText } from "../domains/safety/call-target.js";
-export { permissionHintEntries } from "./permission-hint.js";
+export { MUTATION_PREVIEW_KEY, type PermissionInspectionHint, permissionHintEntries } from "./permission-hint.js";
 
 export interface ApprovalRequestView {
 	requestId: string;
@@ -34,6 +42,14 @@ export interface ApprovalRequestView {
 	 * when nothing meaningful is derivable.
 	 */
 	target?: string;
+	/**
+	 * Size and digest facts for a parked `write` or `edit`, and nothing else
+	 * about it. The mutation text is deliberately absent: this view is what
+	 * reaches the transcript row, the parked notice, and the approval-state
+	 * event, so anything on it has already left the overlay. The text itself is
+	 * held by the inspector the overlay opener is given (issue #254).
+	 */
+	mutation?: MutationFacts;
 	queueDepth?: number;
 }
 
@@ -79,11 +95,59 @@ export function permissionOverlayPlacement(
 	};
 }
 
-class PermissionOverlayBody implements Component {
-	constructor(private readonly view: ApprovalRequestView) {}
+/**
+ * The overlay body, plus the inspection state the key router drives. The
+ * preview is built on the first toggle rather than per frame, so the file read
+ * and the diff happen once when the operator asks for them.
+ */
+export interface PermissionOverlayBodyHandle extends Component {
+	/** Whether this card has a mutation the operator can read locally. */
+	canInspect(): boolean;
+	isInspecting(): boolean;
+	toggleInspect(): void;
+	scrollInspect(delta: number): void;
+}
+
+class PermissionOverlayBody implements PermissionOverlayBodyHandle {
+	private preview: MutationPreview | null = null;
+	private scroll = 0;
+	private lastLineCount = 0;
+
+	constructor(
+		private readonly view: ApprovalRequestView,
+		private readonly inspect?: MutationInspector,
+	) {}
+
+	canInspect(): boolean {
+		return this.inspect !== undefined;
+	}
+
+	isInspecting(): boolean {
+		return this.preview !== null;
+	}
+
+	toggleInspect(): void {
+		if (this.inspect === undefined) return;
+		if (this.preview !== null) {
+			this.preview = null;
+			this.scroll = 0;
+			return;
+		}
+		this.preview = this.inspect();
+		this.scroll = 0;
+	}
+
+	scrollInspect(delta: number): void {
+		if (this.preview === null) return;
+		const maxScroll = Math.max(0, this.lastLineCount - MUTATION_PREVIEW_VISIBLE_ROWS);
+		this.scroll = Math.max(0, Math.min(this.scroll + delta, maxScroll));
+	}
 
 	render(width: number): string[] {
-		return permissionOverlayLines(this.view, width);
+		if (this.preview === null) return permissionOverlayLines(this.view, width);
+		const rendered = permissionInspectionLines(this.view, this.preview, width, this.scroll);
+		this.lastLineCount = rendered.wrappedLineCount;
+		return rendered.lines;
 	}
 
 	invalidate(): void {}
@@ -167,14 +231,74 @@ export function permissionOverlayTone(view: ApprovalRequestView): ClioToken {
  * three columns the bottom border spends on `─ ` and the trailing space come
  * off the top, which is what `buildResponsiveHint` does for every other frame.
  */
-export function permissionOverlayHint(innerWidth: number, composerHasDraft = false): string {
-	return fitHintEntries(permissionHintEntries(composerHasDraft), innerWidth - 3);
+export function permissionOverlayHint(
+	innerWidth: number,
+	composerHasDraft = false,
+	inspection: PermissionInspectionHint = "none",
+): string {
+	return fitHintEntries(permissionHintEntries(composerHasDraft, inspection), innerWidth - 3);
+}
+
+/** The tools whose parked call mutates a file, so a card without a preview owes the operator a reason. */
+function isFileMutationTool(tool: string): boolean {
+	return tool === "write" || tool === "edit";
 }
 
 function actionConsequence(presentation: DecisionPresentation, id: "deny" | "stop"): string {
 	return presentation.requiredActions.find((action) => action.id === id)?.consequence ?? "";
 }
 
+/**
+ * Hard wrap for mutation text. Prose wraps on words; a proposed file line and a
+ * diff row do not, because the column a character sits in is part of what the
+ * operator is reading. The continuation marker says the row was folded rather
+ * than cut, which is the difference between a wrap and unmarked truncation.
+ */
+function wrapMutationLine(value: string, max: number): string[] {
+	if (max <= 1) return [value];
+	if (value.length <= max) return [value];
+	const lines: string[] = [];
+	let remaining = value;
+	while (remaining.length > max) {
+		lines.push(`${remaining.slice(0, max - 1)}↩`);
+		remaining = remaining.slice(max - 1);
+	}
+	lines.push(remaining);
+	return lines;
+}
+
+/**
+ * The card with the mutation open. The tool, target, and digest facts stay at
+ * the top so the bytes on screen remain tied to the call they belong to, and
+ * the standing safety prose gives way to the mutation itself: the operator
+ * opened this to read what changes, and the keys that answer the ask are on the
+ * footer throughout.
+ */
+function permissionInspectionLines(
+	view: ApprovalRequestView,
+	preview: MutationPreview,
+	width: number,
+	scroll: number,
+): { lines: string[]; wrappedLineCount: number } {
+	const content = Math.max(8, Math.floor(width));
+	const wrapped = preview.body.flatMap((line) => wrapMutationLine(line, content));
+	const pane = mutationPreviewWindow(wrapped, scroll);
+	const notes: string[] = [];
+	if (preview.neutralized) notes.push("control characters shown as ·");
+	if (preview.tabsExpanded) notes.push("tabs shown as spaces");
+	const lines = [
+		field("Tool: ", `${view.tool} · Action: ${view.actionClass}`, content),
+		...(view.target !== undefined && view.target.length > 0 ? [field("Target: ", view.target, content)] : []),
+		...wrapSentence(`Mutation: ${mutationFactsLine(preview.facts)}`, content),
+		"",
+		...wrapSentence(preview.heading, content),
+		...pane.window,
+		...(pane.position === null ? [] : [pane.position]),
+		...(notes.length > 0 ? [`Rendered safely: ${notes.join(", ")}.`] : []),
+	];
+	return { lines, wrappedLineCount: wrapped.length };
+}
+
 /**
  * The overlay's body, laid out for the width the frame gives it.
  *
@@ -193,6 +317,24 @@ export function permissionOverlayLines(view: ApprovalRequestView, width: number)
 	const lines = [
 		field("Tool: ", `${view.tool} · Action: ${view.actionClass}`, content),
 		...(view.target !== undefined && view.target.length > 0 ? [field("Target: ", view.target, content)] : []),
+		// Size and digest stay on the collapsed card whether or not the operator
+		// opens the mutation, so the decision always carries the identity of the
+		// bytes it applies to.
+		// Wrapped, never ellipsized: at 40 columns the digest is the tail of the
+		// line, and ellipsizing it would drop the one fact that ties the decision
+		// to the bytes it applies to.
+		...(view.mutation !== undefined
+			? [
+					...wrapSentence(`Mutation: ${mutationFactsLine(view.mutation)}`, content),
+					...wrapSentence(`Press ${MUTATION_PREVIEW_KEY} to read it before deciding.`, content),
+				]
+			: []),
+		...(view.mutation === undefined && view.origin.kind === "worker" && isFileMutationTool(view.tool)
+			? wrapSentence(
+					"No local preview: this call's arguments stay inside the worker, so you are approving the target above without inspecting the mutation.",
+					content,
+				)
+			: []),
 		...wrapSentence(`Requested by: ${presentation.requestedByCopy}`, content),
 		...(view.artifact !== undefined
 			? [
@@ -215,6 +357,14 @@ export function permissionOverlayLines(view: ApprovalRequestView, width: number)
 	return lines;
 }
 
-export function createPermissionOverlayBody(view: ApprovalRequestView): Component {
-	return new PermissionOverlayBody(view);
+/**
+ * The overlay body for one parked call. The inspector, when present, is the
+ * only path the mutation text takes: it is never placed on `view`, so nothing
+ * that renders or forwards the view can carry the bytes with it.
+ */
+export function createPermissionOverlayBody(
+	view: ApprovalRequestView,
+	inspect?: MutationInspector,
+): PermissionOverlayBodyHandle {
+	return new PermissionOverlayBody(view, inspect);
 }