@iowarp/clio-coder 0.4.0 → 0.4.2

package/src/domains/mux/dock-controller.ts

@@ -0,0 +1,365 @@
+/**
+ * Dock geometry and lifecycle: the managed tier of Clio-owned panes.
+ *
+ * A dock is a pane in a fixed position relative to Clio's anchor pane with a
+ * target share of the anchor's axis, a minimum size in cells, and a managed
+ * lifecycle. Two slots exist: `workers` to the right of the anchor and
+ * `files` below it. Ad-hoc utility panes are not docks and are never touched
+ * here.
+ *
+ * The controller owns geometry only. Ownership stays in the pane registry,
+ * error swallowing stays in the contract's `attempt` wrapper: every method
+ * here that talks to the socket may throw a `MuxError`, and the contract is
+ * the layer that turns that into a null/false answer.
+ *
+ * Three rules run through the reconciliation logic:
+ *
+ *   1. A user action is a decision. A resize observed via `layout.updated`
+ *      that does not match what Clio last applied becomes the new target; a
+ *      closed dock stays closed; a moved dock is followed to its new id.
+ *   2. Clio's own corrections must not read as user actions. Every applied
+ *      share is remembered and an observation matching it (or the target)
+ *      within {@link SHARE_EPSILON} is a no-op.
+ *   3. Opening never steals focus. Focus and zoom live on the contract and
+ *      only ever run on explicit request.
+ */
+
+import type { MuxClient } from "./socket-client.js";
+import type { MuxLayoutNode, MuxLog, MuxPaneRef, MuxRect, MuxTabGeometry } from "./types.js";
+
+/** The two managed dock positions. */
+export type DockSlot = "workers" | "files";
+
+export interface DockSpec {
+	slot: DockSlot;
+	direction: "right" | "down";
+	/** Default share of the anchor's axis the dock takes when none is configured. */
+	defaultShare: number;
+	/** Floor in cells (columns for `right`, rows for `down`) below which a dock is useless. */
+	minCells: number;
+}
+
+/**
+ * Fixed per slot rather than heuristic: the workers viewer wants columns, the
+ * file pane wants rows, and a dock that wanders per terminal width would make
+ * the layout feel like weather.
+ */
+export const DOCK_SPECS: Readonly<Record<DockSlot, DockSpec>> = {
+	workers: { slot: "workers", direction: "right", defaultShare: 0.34, minCells: 48 },
+	files: { slot: "files", direction: "down", defaultShare: 0.3, minCells: 12 },
+};
+
+/** A dock may never take more than half the axis, whatever the share asks. */
+export const DOCK_MAX_SHARE = 0.5;
+/** Observed-vs-applied share differences below this are rounding, not a user drag. */
+export const SHARE_EPSILON = 0.02;
+
+export interface DockState {
+	slot: DockSlot;
+	paneId: string;
+	tabId: string;
+	/** Share of the axis the dock should hold; user resizes overwrite it. */
+	targetShare: number;
+	/** What Clio last set, so its own correction is not adopted as a user drag. */
+	lastAppliedShare: number;
+}
+
+/** Wire ratio for a split where the dock is the `second` child: the anchor keeps the rest. */
+export function ratioForDockShare(share: number): number {
+	return 1 - share;
+}
+
+/** Clamps a requested share into (0, DOCK_MAX_SHARE]. */
+export function clampDockShare(share: number): number {
+	if (!Number.isFinite(share) || share <= 0) return DOCK_SPECS.workers.defaultShare;
+	return Math.min(DOCK_MAX_SHARE, share);
+}
+
+/** The axis length in cells a spec's direction measures on a rect. */
+function axisCells(rect: { width: number; height: number }, spec: DockSpec): number {
+	return spec.direction === "right" ? rect.width : rect.height;
+}
+
+/**
+ * Boolean path from the root to the split separating `anchorPaneId` from
+ * `dockPaneId`, plus which side the dock sits on. Null when the tree does not
+ * hold such a split, which is how a stale path is detected after user moves.
+ */
+export function deriveSplitPath(
+	root: MuxLayoutNode,
+	anchorPaneId: string,
+	dockPaneId: string,
+): { path: ReadonlyArray<boolean>; dockIsSecond: boolean; direction: "right" | "down" } | null {
+	const contains = (node: MuxLayoutNode, paneId: string): boolean => {
+		if (node.type === "pane") return node.paneId === paneId;
+		return contains(node.first, paneId) || contains(node.second, paneId);
+	};
+	const walk = (
+		node: MuxLayoutNode,
+		path: boolean[],
+	): { path: boolean[]; dockIsSecond: boolean; direction: "right" | "down" } | null => {
+		if (node.type !== "split") return null;
+		const dockFirst = contains(node.first, dockPaneId);
+		const dockSecond = contains(node.second, dockPaneId);
+		const anchorFirst = contains(node.first, anchorPaneId);
+		const anchorSecond = contains(node.second, anchorPaneId);
+		if (dockFirst && anchorSecond) return { path, dockIsSecond: false, direction: node.direction };
+		if (dockSecond && anchorFirst) return { path, dockIsSecond: true, direction: node.direction };
+		if (dockFirst && anchorFirst) return walk(node.first, [...path, false]);
+		if (dockSecond && anchorSecond) return walk(node.second, [...path, true]);
+		return null;
+	};
+	return walk(root, []);
+}
+
+/** Whether `outer` contains `inner`, cell-inclusive. */
+function containsRect(outer: MuxRect, inner: MuxRect): boolean {
+	return (
+		outer.x <= inner.x &&
+		outer.y <= inner.y &&
+		outer.x + outer.width >= inner.x + inner.width &&
+		outer.y + outer.height >= inner.y + inner.height
+	);
+}
+
+/**
+ * The dock side's observed share at the split separating it from the anchor,
+ * from live geometry. The separating split is the smallest split rect holding
+ * both panes: split rects nest, so that is their lowest common ancestor. Its
+ * live ratio is read directly rather than summing pane cells, because the
+ * anchor's rect stops standing for its whole side the moment the user splits
+ * it for something else, and a cell sum then misreads an untouched dock as a
+ * resize. A separating split on the wrong axis measures nothing.
+ */
+export function observedDockShare(
+	geometry: MuxTabGeometry,
+	spec: DockSpec,
+	anchorPaneId: string,
+	dockPaneId: string,
+): number | null {
+	const anchor = geometry.panes.find((pane) => pane.paneId === anchorPaneId);
+	const dock = geometry.panes.find((pane) => pane.paneId === dockPaneId);
+	if (!anchor || !dock) return null;
+	let separating: MuxTabGeometry["splits"][number] | null = null;
+	for (const split of geometry.splits) {
+		if (!containsRect(split.rect, anchor.rect) || !containsRect(split.rect, dock.rect)) continue;
+		if (!separating || split.rect.width * split.rect.height < separating.rect.width * separating.rect.height) {
+			separating = split;
+		}
+	}
+	if (!separating || separating.direction !== spec.direction) return null;
+	// On opposite sides of the divider, the second child always starts past the
+	// first, so a coordinate compare says which side the dock holds.
+	const dockIsSecond = spec.direction === "right" ? dock.rect.x > anchor.rect.x : dock.rect.y > anchor.rect.y;
+	return dockIsSecond ? 1 - separating.ratio : separating.ratio;
+}
+
+export interface DockOpenPlan {
+	direction: "right" | "down";
+	/** Wire ratio for `pane.split`: the share the anchor keeps. */
+	ratio: number;
+	share: number;
+}
+
+/**
+ * Decides whether a dock fits beside the anchor and with what split ratio,
+ * from the anchor's current rect. Refusal happens here, before any split
+ * reaches the wire, so a too-small terminal never flashes a sliver pane.
+ */
+export function planDockOpen(
+	anchorRect: { width: number; height: number },
+	spec: DockSpec,
+	requestedShare?: number,
+): DockOpenPlan | { refused: string } {
+	const axis = axisCells(anchorRect, spec);
+	if (axis * DOCK_MAX_SHARE < spec.minCells) {
+		return {
+			refused: `the ${spec.slot} dock needs ${spec.minCells} cells and at most half of ${axis} is available`,
+		};
+	}
+	const share = Math.max(clampDockShare(requestedShare ?? spec.defaultShare), spec.minCells / axis);
+	return { direction: spec.direction, ratio: ratioForDockShare(share), share };
+}
+
+export interface DockControllerOptions {
+	client: MuxClient;
+	anchorPaneId: string;
+	log?: MuxLog;
+}
+
+export interface DockController {
+	/** Live dock states, for status output. */
+	states(): ReadonlyArray<DockState>;
+	stateFor(slot: DockSlot): DockState | null;
+	/**
+	 * Splits the anchor for a dock and converges it to its cell floor. Returns
+	 * the new pane, or null when the anchor is too small. Throws MuxError on
+	 * wire failure; the contract's attempt wrapper owns that.
+	 */
+	open(
+		slot: DockSlot,
+		options?: { share?: number; cwd?: string; env?: Readonly<Record<string, string>> },
+	): Promise<MuxPaneRef | null>;
+	/** Record an adopted pane (crash recovery) as this slot's dock. */
+	adopt(slot: DockSlot, ref: MuxPaneRef): void;
+	/** Set a dock's share explicitly, as `/panes` resize does. */
+	resize(slot: DockSlot, share: number): Promise<boolean>;
+	/** Feed a `layout.updated` push; user resizes become the new target. */
+	noteLayoutUpdated(geometry: MuxTabGeometry): void;
+	/** Feed a pane departure; a closed dock is a decision, not a fault. */
+	notePaneGone(paneId: string): void;
+	/** Feed a `pane.moved` id rewrite; the dock is followed to its new id. */
+	notePaneMoved(previousPaneId: string, paneId: string, tabId: string): void;
+	/** Pane ids of every live dock, for the contract's clean-exit sweep. */
+	paneIds(): ReadonlyArray<string>;
+	clear(): void;
+}
+
+export function createDockController(options: DockControllerOptions): DockController {
+	const { client, anchorPaneId } = options;
+	const log = options.log ?? ((): void => undefined);
+	const bySlot = new Map<DockSlot, DockState>();
+
+	/**
+	 * Re-derives the split path from a fresh export and applies a ratio for the
+	 * dock's share. The path is never cached: user splits and moves invalidate
+	 * it silently, and one export per resize is cheap.
+	 */
+	const applyShare = async (state: DockState, share: number): Promise<boolean> => {
+		const tree = await client.layoutExport({ tabId: state.tabId });
+		const derived = deriveSplitPath(tree.root, anchorPaneId, state.paneId);
+		if (!derived) {
+			log("debug", `mux ${state.slot} dock split path is gone from ${state.tabId}; leaving layout alone`);
+			return false;
+		}
+		// After a user move the separating split can run the other axis, and the
+		// share would then set a height where minCells measures columns. Wrong-axis
+		// geometry is declined, not silently applied.
+		if (derived.direction !== DOCK_SPECS[state.slot].direction) {
+			log("debug", `mux ${state.slot} dock split runs ${derived.direction}; declining the wrong-axis resize`);
+			return false;
+		}
+		const ratio = derived.dockIsSecond ? ratioForDockShare(share) : share;
+		await client.layoutSetSplitRatio({ tabId: state.tabId, path: derived.path, ratio });
+		state.targetShare = share;
+		state.lastAppliedShare = share;
+		return true;
+	};
+
+	return {
+		states(): ReadonlyArray<DockState> {
+			return [...bySlot.values()].map((state) => ({ ...state }));
+		},
+
+		stateFor(slot: DockSlot): DockState | null {
+			const state = bySlot.get(slot);
+			return state ? { ...state } : null;
+		},
+
+		async open(slot, openOptions = {}): Promise<MuxPaneRef | null> {
+			const existing = bySlot.get(slot);
+			if (existing) {
+				return { paneId: existing.paneId, tabId: existing.tabId, workspaceId: "" };
+			}
+			const spec = DOCK_SPECS[slot];
+			const geometry = await client.paneLayout(anchorPaneId);
+			const anchorRect = geometry.panes.find((pane) => pane.paneId === anchorPaneId)?.rect;
+			if (!anchorRect) {
+				log("debug", `mux ${slot} dock open found no anchor rect for ${anchorPaneId}`);
+				return null;
+			}
+			const plan = planDockOpen(anchorRect, spec, openOptions.share);
+			if ("refused" in plan) {
+				log("info", `mux ${slot} dock refused: ${plan.refused}`);
+				return null;
+			}
+			const pane = await client.paneSplit({
+				direction: plan.direction,
+				targetPaneId: anchorPaneId,
+				ratio: plan.ratio,
+				focus: false,
+				...(openOptions.cwd !== undefined ? { cwd: openOptions.cwd } : {}),
+				...(openOptions.env ? { env: openOptions.env } : {}),
+			});
+			const state: DockState = {
+				slot,
+				paneId: pane.paneId,
+				tabId: pane.tabId,
+				targetShare: plan.share,
+				lastAppliedShare: plan.share,
+			};
+			bySlot.set(slot, state);
+			// Ratio-at-split lands on the anchor's old rect; prior splits or a
+			// resize since the read can leave the dock under its floor. One
+			// converge pass fixes it; failure to converge is not failure to open.
+			try {
+				const after = await client.paneLayout(anchorPaneId);
+				const dockRect = after.panes.find((entry) => entry.paneId === pane.paneId)?.rect;
+				if (dockRect && axisCells(dockRect, spec) < spec.minCells) {
+					const anchorAfter = after.panes.find((entry) => entry.paneId === anchorPaneId)?.rect;
+					const total = anchorAfter ? axisCells(anchorAfter, spec) + axisCells(dockRect, spec) : 0;
+					if (total > 0) await applyShare(state, Math.min(DOCK_MAX_SHARE, spec.minCells / total));
+				}
+			} catch (error) {
+				log("debug", `mux ${slot} dock converge skipped: ${error instanceof Error ? error.message : String(error)}`);
+			}
+			return { paneId: pane.paneId, tabId: pane.tabId, workspaceId: pane.workspaceId };
+		},
+
+		adopt(slot: DockSlot, ref: MuxPaneRef): void {
+			const spec = DOCK_SPECS[slot];
+			bySlot.set(slot, {
+				slot,
+				paneId: ref.paneId,
+				tabId: ref.tabId,
+				// The surviving pane's actual share is adopted lazily by the next
+				// layout observation; until then the default is the best guess.
+				targetShare: spec.defaultShare,
+				lastAppliedShare: spec.defaultShare,
+			});
+		},
+
+		async resize(slot: DockSlot, share: number): Promise<boolean> {
+			const state = bySlot.get(slot);
+			if (!state) return false;
+			return await applyShare(state, Math.max(clampDockShare(share), 0.01));
+		},
+
+		noteLayoutUpdated(geometry: MuxTabGeometry): void {
+			for (const state of bySlot.values()) {
+				if (state.tabId !== geometry.tabId) continue;
+				const observed = observedDockShare(geometry, DOCK_SPECS[state.slot], anchorPaneId, state.paneId);
+				if (observed === null) continue;
+				if (Math.abs(observed - state.targetShare) <= SHARE_EPSILON) continue;
+				if (Math.abs(observed - state.lastAppliedShare) <= SHARE_EPSILON) continue;
+				// The user dragged the divider. Their ratio is the target now, and a
+				// later terminal resize must not fight them back to the old one.
+				log("debug", `mux ${state.slot} dock resized by the user to ${(observed * 100).toFixed(0)}%`);
+				state.targetShare = observed;
+				state.lastAppliedShare = observed;
+			}
+		},
+
+		notePaneGone(paneId: string): void {
+			for (const [slot, state] of bySlot) {
+				if (state.paneId === paneId) bySlot.delete(slot);
+			}
+		},
+
+		notePaneMoved(previousPaneId: string, paneId: string, tabId: string): void {
+			for (const state of bySlot.values()) {
+				if (state.paneId !== previousPaneId) continue;
+				state.paneId = paneId;
+				state.tabId = tabId;
+			}
+		},
+
+		paneIds(): ReadonlyArray<string> {
+			return [...bySlot.values()].map((state) => state.paneId);
+		},
+
+		clear(): void {
+			bySlot.clear();
+		},
+	};
+}

package/src/domains/mux/extension.ts

@@ -30,7 +30,13 @@ export async function createMuxBundle(
 		...(options.env ? { env: options.env } : {}),
 		log,
 	});
-	log(detection.mode === "none" ? "debug" : "info", `mux mode ${detection.mode}: ${detection.reason}`);
+	// A `none` that nobody asked for is background noise and stays at debug. A
+	// refusal is the operator's own setting being turned down, so it goes to
+	// `warning`, which the orchestrator routes to boot stderr.
+	log(
+		detection.refused ? "warning" : detection.mode === "none" ? "debug" : "info",
+		detection.refused ? `panes refused: ${detection.reason}` : `mux mode ${detection.mode}: ${detection.reason}`,
+	);
 
 	const runtime = createMuxRuntime({ detection, client, log });
 

package/src/domains/mux/index.ts

@@ -26,6 +26,20 @@ export type {
 } from "./contract.js";
 export { createMuxRuntime } from "./contract.js";
 export { detectMux, type MuxDetection, type MuxEnablement, resolveSocketCandidates } from "./detect.js";
+export {
+	clampDockShare,
+	DOCK_MAX_SHARE,
+	DOCK_SPECS,
+	type DockController,
+	type DockSlot,
+	type DockSpec,
+	type DockState,
+	deriveSplitPath,
+	observedDockShare,
+	planDockOpen,
+	ratioForDockShare,
+	SHARE_EPSILON,
+} from "./dock-controller.js";
 export type { MuxDomainOptions } from "./extension.js";
 export { MuxManifest } from "./manifest.js";
 export { createPaneRegistry, type MuxPaneRegistry, paneRecord } from "./pane-registry.js";
@@ -37,12 +51,15 @@ export {
 	type MuxErrorKind,
 	type MuxEvent,
 	type MuxEventKind,
+	type MuxLayoutNode,
+	type MuxLayoutTree,
 	type MuxLog,
 	type MuxMode,
 	type MuxNotificationSound,
 	type MuxPanePurpose,
 	type MuxPaneRecord,
 	type MuxPaneRef,
+	type MuxRect,
 	type MuxReportableAgentState,
 	MuxRequestTimeout,
 	type MuxSelfLocation,
@@ -50,12 +67,15 @@ export {
 	type MuxServerInfo,
 	type MuxSnapshot,
 	type MuxTab,
+	type MuxTabGeometry,
 	muxErrorKind,
 } from "./types.js";
 export { clioCliEntryPath, type ViewerCommandOptions, watchViewerCommand } from "./viewer-command.js";
 export {
 	createYaziEventStream,
+	LEGACY_YAZI_PICK_EVENT,
 	parseYaziEventLine,
+	YAZI_PICK_EVENT,
 	YAZI_STREAM_MAX_BYTES,
 	YAZI_STREAM_POLL_MS,
 	type YaziCdEvent,
@@ -93,4 +113,4 @@ export {
 	type YaziSessionOptions,
 	type YaziSessionSnapshot,
 } from "./yazi/session.js";
-export { renderYaziTheme } from "./yazi/theme.js";
+export { renderHerdrThemeBlock, renderYaziTheme } from "./yazi/theme.js";

package/src/domains/mux/operations.ts

@@ -14,13 +14,19 @@
  * shell-escape territory (spec 4.8, and the risk register's "tool misuse" row).
  */
 
-/** Utility pane presets, in the order `/panes open` lists them. */
+/**
+ * Utility pane presets, in the order `/panes open` lists them.
+ *
+ * The files preset is a Clio Coder surface named for what it does; yazi is
+ * the engine behind it and shows up only in the install command, because
+ * that is the registry id an operator types.
+ */
 export const PANES_PRESETS = [
 	{
-		id: "yazi",
+		id: "files",
 		/** Probed through the toolchain resolution ladder before the pane is split. */
 		binary: "yazi",
-		summary: "file manager rooted at the workspace",
+		summary: "file view rooted at the workspace; picks land in the composer",
 		/** Printed verbatim when the probe finds nothing. */
 		installHint: "clio-coder tools install yazi",
 	},
@@ -42,10 +48,23 @@ export type PanesPresetId = (typeof PANES_PRESETS)[number]["id"];
 
 export const PANES_PRESET_IDS: ReadonlyArray<PanesPresetId> = PANES_PRESETS.map((preset) => preset.id);
 
-export function isPanesPresetId(value: string): value is PanesPresetId {
+function isPanesPresetId(value: string): value is PanesPresetId {
 	return PANES_PRESETS.some((preset) => preset.id === value);
 }
 
+/**
+ * Retired preset spellings that still parse. The files preset shipped as
+ * `yazi` in 0.4.0 and 0.4.1, so an operator's muscle memory and any script
+ * that says `/panes open yazi` keeps working and lands on the same pane.
+ */
+export const PANES_PRESET_ALIASES: Readonly<Record<string, PanesPresetId>> = { yazi: "files" };
+
+/** The canonical preset id for an operator-typed name, or null when it is not a preset. */
+export function resolvePanesPresetId(value: string): PanesPresetId | null {
+	if (isPanesPresetId(value)) return value;
+	return PANES_PRESET_ALIASES[value] ?? null;
+}
+
 /** One pane Clio owns, flattened for display. */
 export interface PanesInventoryEntry {
 	paneId: string;
@@ -61,6 +80,8 @@ export interface PanesInventoryEntry {
 export interface PanesEffectiveSettings {
 	enabled: string;
 	notifications: string;
+	/** Boot composition: off, workers, or cockpit. */
+	layout: string;
 	journal: boolean;
 	yazi: {
 		enabled: boolean;
@@ -70,6 +91,14 @@ export interface PanesEffectiveSettings {
 	};
 }
 
+/** One managed dock's live geometry, flattened for `/panes` status. */
+export interface PanesDockStatus {
+	slot: "workers" | "files";
+	paneId: string;
+	/** Share of the axis the dock currently targets, 0..0.5. */
+	targetShare: number;
+}
+
 /** File-pane return-path state flattened for `/panes` and the model tool. */
 export interface PanesYaziStatus {
 	mode: "companion" | "chooser" | "closed";
@@ -89,6 +118,8 @@ export interface PanesStatus {
 	server: { version: string; protocol: number } | null;
 	settings: PanesEffectiveSettings;
 	yazi: PanesYaziStatus;
+	/** Managed docks with live geometry; empty below the layout tier. */
+	docks: ReadonlyArray<PanesDockStatus>;
 	panes: ReadonlyArray<PanesInventoryEntry>;
 }
 
@@ -109,6 +140,11 @@ export type PanesWatchResult =
  * is: neither the domain nor the tool may import the interactive tree.
  */
 export interface PanesWatchController {
+	/**
+	 * Open (or adopt) the watch pane without retargeting it, for boot
+	 * composition under `interface.panes.layout`. False when the host refused.
+	 */
+	ensureOpen(): Promise<boolean>;
 	/** Point the watch pane at a run, opening or adopting the pane first if needed. */
 	watch(runId: string): Promise<PanesWatchResult>;
 	/** Retarget only; false when no watch pane is open or the write failed. */
@@ -118,11 +154,17 @@ export interface PanesWatchController {
 }
 
 export type PanesOpenResult =
-	| { status: "opened"; label: string; paneId: string | null }
+	/** `existing` is true when the preset already had a live pane and it was focused instead of split again. */
+	| { status: "opened"; label: string; paneId: string | null; existing?: boolean }
 	| { status: "missing-binary"; preset: string; binary: string; installHint: string; detail: string }
 	| { status: "refused"; reason: string }
 	| { status: "unavailable"; reason: string };
 
+export type PanesZoomResult =
+	| { status: "zoomed"; paneId: string; label: string }
+	| { status: "not-found"; target: string }
+	| { status: "unavailable"; reason: string };
+
 export type PanesCloseResult =
 	| { status: "closed"; closed: number; labels: ReadonlyArray<string> }
 	| { status: "not-found"; target: string }
@@ -144,9 +186,21 @@ export interface PanesYaziController {
 		| { status: "profile-error"; reason: string }
 		| { status: "unavailable"; reason: string }
 	>;
+	/** Close the files pane if it is open; false when nothing was open. */
+	close(): Promise<boolean>;
+	/** True while a files pane the host still reports is open. */
+	isOpen(): boolean;
 	status(): Readonly<PanesYaziStatus>;
 }
 
+/** What `/files` and the files keybinding settle to. */
+export type PanesFilesResult =
+	| { status: "opened"; paneId: string | null; existing: boolean }
+	| { status: "closed" }
+	| { status: "missing-binary"; binary: string; installHint: string; detail: string }
+	| { status: "refused"; reason: string }
+	| { status: "unavailable"; reason: string };
+
 /**
  * The operations both callers drive. The tool sees a narrower door: its schema
  * has no argv field at all, and `open` refuses one even if a caller fabricates
@@ -156,7 +210,20 @@ export interface PanesOperations {
 	status(): PanesStatus;
 	show(target: string): Promise<PanesShowResult>;
 	open(request: { preset?: string; argv?: ReadonlyArray<string>; once?: boolean }): Promise<PanesOpenResult>;
+	/**
+	 * Toggle zoom on one Clio-owned pane, matched like `close` (pane id, label
+	 * substring, then purpose; newest first). Zooming steals focus, so this is
+	 * operator-only and never reachable from the model tool.
+	 */
+	zoom(target: string): Promise<PanesZoomResult>;
 	close(target: string): Promise<PanesCloseResult>;
+	/**
+	 * The files pane as one operator verb. `toggle` opens it when closed and
+	 * closes it when open, which is what a keybinding needs; `open` and
+	 * `close` are the explicit halves; `pick` borrows the pane for one
+	 * selection and closes it afterwards.
+	 */
+	files(action: "toggle" | "open" | "close" | "pick"): Promise<PanesFilesResult>;
 	/** Bind the composer-facing Yazi bridge without rebuilding this shared object. */
 	attachYazi(controller: PanesYaziController): () => void;
 	/** Bind the workers-view watch controller; `show` routes runs through it. */

package/src/domains/mux/protocol.ts

@@ -7,14 +7,19 @@
  * adds the worktree family: a herdr old
  * enough to predate them answers `invalid_request`, and the honest response is
  * to take the documented fallback rather than to log a failure per call.
- * (`agent.focus` was gated here too until the per-run focus ladder was
- * removed with the run viewer panes; nothing drives it any more.)
  *
  * The floors are protocol introductions checked against herdr's changelog and
- * then re-verified with `herdr api schema --json` from PATH 0.7.5/protocol 17
- * and pinned 0.8.2/protocol 21. Worktrees arrived in protocol 10; notification.show
- * arrived in 17. Lower one only after checking the schema of
- * the release you are lowering it to.
+ * then re-verified with `herdr api schema --json` on the released artifacts
+ * themselves: 0.7.5 (protocol 17) and the pinned 0.8.2, whose hash-verified
+ * binary speaks protocol 20, not 21. Both schemas carry pane.focus,
+ * layout.export, and layout.set_split_ratio as method constants, so the whole
+ * dock tier floors at 17 alongside notification.show and pane.zoom. (An
+ * earlier attestation put these at 21 after reading a stray dev build that
+ * self-reported "0.8.2" while speaking protocol 21; on the real pin that
+ * floor gated the dock tier off entirely.) Worktrees arrived in protocol 10.
+ * 17 is the oldest schema actually read, not the oldest that might work.
+ * Lower one only after checking the schema of the release you are lowering
+ * it to.
  */
 
 import type { MuxServerInfo } from "./types.js";
@@ -23,6 +28,10 @@ import type { MuxServerInfo } from "./types.js";
 export type MuxGatedMethod =
 	| "notification.show"
 	| "pane.rename"
+	| "pane.focus"
+	| "pane.zoom"
+	| "layout.export"
+	| "layout.set_split_ratio"
 	| "worktree.list"
 	| "worktree.create"
 	| "worktree.open"
@@ -31,6 +40,10 @@ export type MuxGatedMethod =
 export const MUX_METHOD_MIN_PROTOCOL: Readonly<Record<MuxGatedMethod, number>> = {
 	"notification.show": 17,
 	"pane.rename": 17,
+	"pane.focus": 17,
+	"pane.zoom": 17,
+	"layout.export": 17,
+	"layout.set_split_ratio": 17,
 	"worktree.list": 10,
 	"worktree.create": 10,
 	"worktree.open": 10,