@iowarp/clio-coder 0.4.0 → 0.4.1

package/src/domains/middleware/marketplace-offer.ts

@@ -0,0 +1,339 @@
+import { randomUUID } from "node:crypto";
+import {
+	SKILL_INSTALL_OFFER_OPTION_NEVER,
+	SKILL_INSTALL_OFFER_OPTION_NOT_NOW,
+	SKILL_INSTALL_OFFER_OPTION_PROJECT,
+	SKILL_INSTALL_OFFER_OPTION_USER,
+} from "../../core/skill-activation.js";
+import { ToolNames } from "../../core/tool-names.js";
+import type { MarketplaceSkill } from "../resources/skills/marketplace.js";
+import {
+	assertPromotionInstallSource,
+	declineKey,
+	matchMarketplaceSkills,
+	type PromotionMatch,
+	readPromotionDeclines,
+	recordPromotionNeverDecline,
+} from "../resources/skills/promotion.js";
+import type { AutonomyLevel } from "../safety/autonomy.js";
+import type { MiddlewareHookRegistration } from "./runtime.js";
+import { isSubstantiveUserTurn } from "./skills-reminder.js";
+import { type MiddlewareEffect, type MiddlewareHookInput, metadataNumber } from "./types.js";
+
+/**
+ * Marketplace self-promotion offer. When the operator's request needs
+ * expertise no installed skill covers and the local marketplace has a match,
+ * this registration teaches the model to put one tight ask_user question to
+ * the operator; the after_tool observer then acts on the answer — a consented
+ * install runs harness-side through the injected installer, "Not now" is a
+ * session-only decline, and "Never offer this skill" persists.
+ *
+ * Firing is need-driven, not count-budgeted: any substantive turn whose text
+ * matches an uninstalled, undeclined marketplace skill may fire, but each
+ * skill is offered at most once per session so a repeated request never
+ * becomes a nag. Detection is the local lexical matcher in
+ * resources/skills/promotion.ts — no request text leaves the machine.
+ *
+ * At full-auto the offer collapses into an autonomous install, but ONLY from
+ * Clio's own marketplace: every promotion-flow install (consented or
+ * autonomous) passes `assertPromotionInstallSource`, the hard runtime gate
+ * that rejects public registries in code rather than prompt text.
+ *
+ * Coordinator-only by wiring: this registration is created in the
+ * orchestrator entry and never in a dispatch worker's loop, so workers can
+ * neither see nor trigger offers.
+ */
+
+export const MARKETPLACE_OFFER_REGISTRATION_ID = "observer.marketplace-offer";
+
+export interface MarketplaceOfferInstallResult {
+	path: string;
+	/** The source the skill was fetched from; surfaced so an autonomous install stays auditable. */
+	sourceUrl: string;
+	/** Normalized content hash of what was written; the integrity record the consent overlay would have shown. */
+	installedHash: string;
+}
+
+export interface MarketplaceOfferDeps {
+	/** Installed skill names the matcher must exclude. */
+	listInstalledSkillNames(): ReadonlyArray<string>;
+	/** The local marketplace lookup (catalog + index); already local-only. */
+	listMarketplaceEntries(): ReadonlyArray<MarketplaceSkill>;
+	/** The session's effective autonomy at evaluation time. */
+	getAutonomy(): AutonomyLevel;
+	/** Perform the install; the registration gates the source before calling. */
+	installEntry(entry: MarketplaceSkill, scope: "user" | "project"): MarketplaceOfferInstallResult;
+	/** Decline persistence; defaults to the promotion module's config-dir store. Keyed by name+version. */
+	declines?: {
+		readNever(): Readonly<Record<string, string>>;
+		recordNever(name: string, version?: string): void;
+	};
+	/** Per-offer binding tag source; injectable for deterministic tests. Defaults to a random id. */
+	newOfferTag?: () => string;
+}
+
+const NO_EFFECTS: ReadonlyArray<MiddlewareEffect> = [];
+
+/**
+ * The tag the model must echo verbatim in its ask_user question so the harness
+ * binds the answer to this specific offer and nothing else. The tag lives only
+ * in a system reminder (a trusted channel), so prompt-injected user or file
+ * content cannot forge it onto an unrelated question.
+ */
+export function offerBindingTag(offerTag: string): string {
+	return `[clio-install:${offerTag}]`;
+}
+
+export function marketplaceOfferReminder(entry: MarketplaceSkill, offerTag: string): string {
+	return (
+		`[Marketplace] This request may need expertise no installed skill covers. The local marketplace has ` +
+		`"${entry.name}" (not installed): ${entry.description} ` +
+		`First check the installed side with context(scope="skills"); if ${entry.name} is genuinely the right fit ` +
+		`and nothing installed serves, ask the operator with ask_user (mode=single_question, header "Install skill") ` +
+		`whether to install ${entry.name}, offering exactly these options in this order: ` +
+		`"${SKILL_INSTALL_OFFER_OPTION_PROJECT}", "${SKILL_INSTALL_OFFER_OPTION_USER}", ` +
+		`"${SKILL_INSTALL_OFFER_OPTION_NOT_NOW}", "${SKILL_INSTALL_OFFER_OPTION_NEVER}". ` +
+		`Include the exact tag ${offerBindingTag(offerTag)} verbatim in that question's text so the harness can bind ` +
+		`the answer to this offer; the harness acts only on an answer carrying this tag. ` +
+		`Then continue the task in the same turn. The harness handles the answer; never install or load a skill yourself. ` +
+		`If it is not actually needed, do not mention it.`
+	);
+}
+
+export function marketplaceAutoInstallReminder(entry: MarketplaceSkill, result: MarketplaceOfferInstallResult): string {
+	// Full-auto skips the operator's yes/no, never the integrity record. The
+	// consent overlay states the source and the SHA-256 of what it writes; the
+	// autonomous path computes the same hash and must surface it here, so an
+	// install nobody was asked about is still traceable to its source and bytes.
+	return (
+		`[Marketplace] Installed skill "${entry.name}" from Clio's own local marketplace (full-auto) to ${result.path}. ` +
+		`Source ${result.sourceUrl}, sha256 ${result.installedHash}. ${entry.description} ` +
+		`It is installed but not active — activation stays operator-gated. If it fits this task, ` +
+		`suggest /skill ${entry.name} to the operator; never load it yourself.`
+	);
+}
+
+interface AnswerLike {
+	question: string;
+	answer: string;
+	options?: ReadonlyArray<string>;
+}
+
+function answersFromDetails(details: Readonly<Record<string, unknown>> | undefined): AnswerLike[] {
+	const raw = details?.answers;
+	if (!Array.isArray(raw)) return [];
+	return raw.filter(
+		(entry): entry is AnswerLike =>
+			typeof entry === "object" &&
+			entry !== null &&
+			typeof (entry as AnswerLike).question === "string" &&
+			typeof (entry as AnswerLike).answer === "string",
+	);
+}
+
+/** The offer option this answer chose, matched by exact label in options or by label substring in the one-line answer. */
+function chosenOfferOption(answer: AnswerLike): string | null {
+	const labels = [
+		SKILL_INSTALL_OFFER_OPTION_PROJECT,
+		SKILL_INSTALL_OFFER_OPTION_USER,
+		SKILL_INSTALL_OFFER_OPTION_NOT_NOW,
+		SKILL_INSTALL_OFFER_OPTION_NEVER,
+	];
+	for (const label of labels) {
+		if (answer.options?.includes(label)) return label;
+	}
+	for (const label of labels) {
+		if (answer.answer.includes(label)) return label;
+	}
+	return null;
+}
+
+export function createMarketplaceOfferRegistration(deps: MarketplaceOfferDeps): MiddlewareHookRegistration {
+	const declines = deps.declines ?? {
+		readNever: () => readPromotionDeclines().never,
+		recordNever: (name: string, version?: string) => recordPromotionNeverDecline(name, version),
+	};
+	const newOfferTag = deps.newOfferTag ?? (() => randomUUID());
+	// Per-session state, reset on a session id change (same adoption rule as
+	// the skills reminder: a fresh session's opening turn fires with a null id
+	// that the created session then fills in).
+	let lastSeenSessionId: string | null | undefined;
+	let offeredNames = new Set<string>();
+	let sessionDeclines = new Set<string>();
+	// Discovery parses and hashes every installed/catalog SKILL.md. On a real
+	// home with 31 entries per side that cost 36-92ms on every turn_start, while
+	// the lexical match itself stayed below 2ms. Inventory is stable within a
+	// session except for installs, so keep one session snapshot and revalidate
+	// installed names only when cached data is about to produce an offer.
+	let installedNamesCache: Set<string> | null = null;
+	let marketplaceEntriesCache: ReadonlyArray<MarketplaceSkill> | null = null;
+	// The offer put to the operator, consumed by the ask_user after_tool
+	// observer. Each offer carries a unique binding tag the model must echo in
+	// its question; the observer acts only on an answer whose question carries
+	// that tag, so an unrelated (or prompt-injected) ask_user answer can never
+	// bind the pending offer.
+	let pendingOffer: { entry: MarketplaceSkill; tag: string } | null = null;
+
+	const trackSession = (input: MiddlewareHookInput): void => {
+		const sessionId = input.sessionId ?? null;
+		if (lastSeenSessionId === undefined || (lastSeenSessionId === null && sessionId !== null)) {
+			lastSeenSessionId = sessionId;
+			return;
+		}
+		if (sessionId !== lastSeenSessionId) {
+			lastSeenSessionId = sessionId;
+			offeredNames = new Set<string>();
+			sessionDeclines = new Set<string>();
+			pendingOffer = null;
+			installedNamesCache = null;
+			marketplaceEntriesCache = null;
+		}
+	};
+
+	const bestMatch = (text: string): PromotionMatch | null => {
+		const installedWasCached = installedNamesCache !== null;
+		let never: Readonly<Record<string, string>>;
+		try {
+			installedNamesCache ??= new Set(deps.listInstalledSkillNames());
+			marketplaceEntriesCache ??= deps.listMarketplaceEntries();
+			never = declines.readNever();
+		} catch {
+			return null;
+		}
+		// offeredNames caps to one offer per skill per session, regardless of
+		// version. Declines are version-scoped: a "never"/"not now" on one catalog
+		// version does not suppress a later version of the same skill.
+		const declinedKeys = new Set<string>([...Object.keys(never), ...sessionDeclines]);
+		const findMatch = (): PromotionMatch | null =>
+			matchMarketplaceSkills(
+				text,
+				marketplaceEntriesCache ?? [],
+				new Set<string>([...(installedNamesCache ?? []), ...offeredNames]),
+			).find((candidate) => !declinedKeys.has(declineKey(candidate.entry.name, candidate.entry.version))) ?? null;
+		let match = findMatch();
+		if (match && installedWasCached) {
+			// A skills-hub or external install can happen after the session snapshot.
+			// Pay the installed-tree refresh only on the rare path that would surface
+			// an offer, then match again so an already-installed skill is never nagged.
+			try {
+				installedNamesCache = new Set(deps.listInstalledSkillNames());
+			} catch {
+				return null;
+			}
+			match = findMatch();
+		}
+		return match;
+	};
+
+	const installGated = (entry: MarketplaceSkill, scope: "user" | "project"): MarketplaceOfferInstallResult => {
+		assertPromotionInstallSource(entry);
+		const result = deps.installEntry(entry, scope);
+		installedNamesCache?.add(entry.name);
+		return result;
+	};
+
+	const evaluateAskUserAnswers = (input: MiddlewareHookInput): ReadonlyArray<MiddlewareEffect> => {
+		const offer = pendingOffer;
+		if (!offer) return NO_EFFECTS;
+		const marker = offerBindingTag(offer.tag);
+		if (input.toolResultDetails?.cancelled === true) {
+			// A cancelled interview carries no question text, so it cannot be
+			// attributed to this offer. Do not bind it: an unrelated cancel must
+			// not decline our offer, and the offer stays armed for a later answer.
+			return NO_EFFECTS;
+		}
+		for (const answer of answersFromDetails(input.toolResultDetails)) {
+			// The answer binds only when its question carries this offer's tag.
+			if (!answer.question.includes(marker)) continue;
+			const option = chosenOfferOption(answer);
+			if (option === null) continue;
+			pendingOffer = null;
+			const offerKey = declineKey(offer.entry.name, offer.entry.version);
+			if (option === SKILL_INSTALL_OFFER_OPTION_NOT_NOW) {
+				sessionDeclines.add(offerKey);
+				return NO_EFFECTS;
+			}
+			if (option === SKILL_INSTALL_OFFER_OPTION_NEVER) {
+				sessionDeclines.add(offerKey);
+				try {
+					declines.recordNever(offer.entry.name, offer.entry.version);
+				} catch {
+					// Persistence failure degrades to a session decline.
+				}
+				return NO_EFFECTS;
+			}
+			const scope = option === SKILL_INSTALL_OFFER_OPTION_USER ? "user" : "project";
+			try {
+				const result = installGated(offer.entry, scope);
+				return [
+					{
+						kind: "annotate_tool_result",
+						severity: "info",
+						message:
+							`[Marketplace] Installed skill "${offer.entry.name}" (${scope} scope) to ${result.path}. ` +
+							`It is installed but not active; the operator activates it with /skill ${offer.entry.name}.`,
+					},
+				];
+			} catch (error) {
+				sessionDeclines.add(offerKey);
+				return [
+					{
+						kind: "annotate_tool_result",
+						severity: "warn",
+						message: `[Marketplace] Install of "${offer.entry.name}" failed: ${
+							error instanceof Error ? error.message : String(error)
+						}. Continue the task without it.`,
+					},
+				];
+			}
+		}
+		return NO_EFFECTS;
+	};
+
+	return {
+		id: MARKETPLACE_OFFER_REGISTRATION_ID,
+		description:
+			"offers an uninstalled marketplace skill via ask_user when the request matches it; consented installs run gated to Clio's own marketplace, declines are remembered",
+		hooks: ["turn_start", "after_tool"],
+		evaluate(input): ReadonlyArray<MiddlewareEffect> {
+			trackSession(input);
+			// The offer is deliberately NOT cleared at turn_end. The reminder asks
+			// the model to put the ask_user question in the same turn, but it often
+			// defers a turn; clearing here dropped that deferred answer on the floor,
+			// so the operator's "Install" installed nothing and the model got no
+			// signal to correct a likely success claim. The offer now stays armed
+			// until a tag-carrying answer binds it, a newer offer replaces it, or the
+			// session ends — safe because only a tagged answer can bind (see H4).
+			if (input.hook === "after_tool") {
+				return input.toolName === ToolNames.AskUser ? evaluateAskUserAnswers(input) : NO_EFFECTS;
+			}
+			if (input.hook !== "turn_start") return NO_EFFECTS;
+			if (!isSubstantiveUserTurn(input.text)) return NO_EFFECTS;
+			// The operator already chose a skill for this turn; an offer on top of
+			// that choice is noise.
+			const pendingSkillRequests = metadataNumber(input, "pendingSkillRequests");
+			if (pendingSkillRequests !== null && pendingSkillRequests > 0) return NO_EFFECTS;
+			const match = bestMatch(input.text ?? "");
+			if (!match) return NO_EFFECTS;
+			offeredNames.add(match.entry.name);
+			if (deps.getAutonomy() === "full-auto") {
+				try {
+					const result = installGated(match.entry, "project");
+					return [
+						{
+							kind: "inject_reminder",
+							severity: "info",
+							message: marketplaceAutoInstallReminder(match.entry, result),
+						},
+					];
+				} catch {
+					// Gate refusal or install failure: fall back to the consent offer
+					// so the operator still hears about the match.
+				}
+			}
+			const tag = newOfferTag();
+			pendingOffer = { entry: match.entry, tag };
+			return [{ kind: "inject_reminder", severity: "info", message: marketplaceOfferReminder(match.entry, tag) }];
+		},
+	};
+}

package/src/domains/middleware/runtime.ts

@@ -102,7 +102,7 @@ export type MiddlewareDiagnosticSink = (diagnostic: MiddlewareDiagnostic) => voi
 export function writeMiddlewareDiagnosticToStderr(diagnostic: MiddlewareDiagnostic): void {
 	if (diagnostic.kind === "hook_failed") {
 		process.stderr.write(
-			`[clio:middleware] registration '${diagnostic.registrationId}' failed on '${diagnostic.hook}': ${diagnostic.message}\n`,
+			`[clio-coder:middleware] registration '${diagnostic.registrationId}' failed on '${diagnostic.hook}': ${diagnostic.message}\n`,
 		);
 		return;
 	}
@@ -115,7 +115,7 @@ export function writeMiddlewareDiagnosticToStderr(diagnostic: MiddlewareDiagnost
 			? ` (slow on ${stats.overCount}/${stats.window} recent ${diagnostic.hook} calls, p95 ${stats.p95Ms.toFixed(1)}ms)`
 			: "";
 	process.stderr.write(
-		`[clio:middleware] registration '${diagnostic.registrationId}' exceeded budget on '${diagnostic.hook}': ` +
+		`[clio-coder:middleware] registration '${diagnostic.registrationId}' exceeded budget on '${diagnostic.hook}': ` +
 			`${diagnostic.elapsedMs.toFixed(1)}ms > ${diagnostic.budgetMs}ms${trend}\n`,
 	);
 }

package/src/domains/mux/contract.ts

@@ -8,7 +8,7 @@
  * fallback value rather than rejecting.
  *
  * Two ownership rules run through the whole file. Clio acts only on panes it
- * created, tracked in `pane-registry.ts` and tagged with the `clio_owner`
+ * created, tracked in `pane-registry.ts` and tagged with the `clio_coder_owner`
  * metadata token so `clio doctor` can find orphans. The one documented
  * exception is Clio's own hosting pane in guest mode, which `reportSelf`
  * writes to under SA-3 of the v0.4.0 cycle plan.
@@ -25,6 +25,7 @@
 
 import type { DomainContract } from "../../core/domain-loader.js";
 import type { MuxDetection } from "./detect.js";
+import { createDockController, type DockController, type DockSlot, type DockState } from "./dock-controller.js";
 import { createPaneRegistry, type MuxPaneRegistry, paneRecord } from "./pane-registry.js";
 import { muxSupportsMethod } from "./protocol.js";
 import type {
@@ -46,12 +47,15 @@ import {
 } from "./types.js";
 
 /** Metadata source for everything Clio's pane layer writes. */
-const METADATA_SOURCE = "clio:mux";
+const METADATA_SOURCE = "clio-coder:mux";
 /** Agent-authority source for Clio's own hosting pane, per SA-3. */
-const SELF_AGENT_SOURCE = "clio:coder";
+const SELF_AGENT_SOURCE = "clio-coder:coder";
 /** Token every Clio-created pane carries so orphans are findable. */
-const OWNER_TOKEN_KEY = "clio_owner";
-const OWNER_TOKEN_VALUE = "clio:mux";
+const OWNER_TOKEN_KEY = "clio_coder_owner";
+const OWNER_TOKEN_VALUE = "clio-coder:mux";
+/** Old-host cleanup bridge; ownership readers retain this indefinitely. */
+const LEGACY_OWNER_TOKEN_KEY = "clio_owner";
+const LEGACY_OWNER_TOKEN_VALUE = "clio:mux";
 /** herdr caps a metadata token value at 80 characters. */
 const TOKEN_VALUE_MAX = 80;
 /** How long `available()` stays false after a transport failure before probing again. */
@@ -71,6 +75,13 @@ export interface MuxOpenUtilityPaneRequest {
 	 * such as Yazi reopen `/dev/tty` for their interface when stdout is not a tty.
 	 */
 	stdoutPath?: string;
+	/**
+	 * Managed placement: the pane becomes this slot's dock, split from the
+	 * anchor with the slot's direction and sized to `share` of the axis
+	 * (clamped, cell-floored). Requires the layout tier (protocol 17); below
+	 * the floor the request degrades to a plain split and `direction` applies.
+	 */
+	dock?: { slot: DockSlot; share?: number };
 }
 
 export interface MuxNotifyRequest {
@@ -99,7 +110,19 @@ export interface MuxContract extends DomainContract {
 	 * This is what stops a restarted session's Enter-in-the-workers-view from
 	 * opening a second watch pane beside the surviving one.
 	 */
-	adoptPane(request: { purpose: MuxPanePurpose; label: string }): Promise<MuxPaneRef | null>;
+	adoptPane(request: { purpose: MuxPanePurpose; label: string; dock?: DockSlot }): Promise<MuxPaneRef | null>;
+	/**
+	 * Focus one Clio-created pane, switching the user's view to it (pane.focus
+	 * moves the focused tab too). Explicit-request only; refuses foreign panes
+	 * and servers below the pane.focus floor.
+	 */
+	focusPane(paneId: string): Promise<boolean>;
+	/** Zoom one Clio-created pane on, off, or toggled. Zooming steals focus; same rule as focusPane. */
+	zoomPane(paneId: string, mode: "on" | "off" | "toggle"): Promise<boolean>;
+	/** Set a dock's share of its axis. False when the slot has no dock or the tier is absent. */
+	resizeDock(slot: DockSlot, share: number): Promise<boolean>;
+	/** Live dock geometry states, for `/panes` status. */
+	docks(): ReadonlyArray<DockState>;
 	notify(request: MuxNotifyRequest): Promise<void>;
 	/** Optional compete storage route. Protocol-gated with a native Git fallback at the caller. */
 	worktreeCreate(request: MuxWorktreeCreateRequest): Promise<MuxWorktreeCreatedResult | null>;
@@ -147,11 +170,25 @@ function token(value: string | undefined | null): string | null {
 	return value.length > TOKEN_VALUE_MAX ? value.slice(0, TOKEN_VALUE_MAX) : value;
 }
 
+function hasOwnedPaneToken(tokens: Readonly<Record<string, string>>): boolean {
+	return tokens[OWNER_TOKEN_KEY] === OWNER_TOKEN_VALUE || tokens[LEGACY_OWNER_TOKEN_KEY] === LEGACY_OWNER_TOKEN_VALUE;
+}
+
 export function createMuxRuntime(options: MuxRuntimeOptions): MuxRuntime {
 	const { detection, client } = options;
 	const log = options.log ?? ((): void => undefined);
 	const now = options.now ?? Date.now;
 	const registry = createPaneRegistry();
+	const anchorPaneId = detection.self.paneId;
+	/**
+	 * The managed dock tier needs an anchor to split from and the protocol-17
+	 * layout methods to converge with. Absent either, dock requests degrade to
+	 * plain utility splits and the rest of the tier answers false/empty.
+	 */
+	const docks: DockController | null =
+		client !== null && anchorPaneId !== null && muxSupportsMethod(detection.server, "layout.export")
+			? createDockController({ client, anchorPaneId, log })
+			: null;
 
 	let healthy = client !== null;
 	let probeHealthAt = 0;
@@ -201,11 +238,30 @@ export function createMuxRuntime(options: MuxRuntimeOptions): MuxRuntime {
 			paneId,
 			source: METADATA_SOURCE,
 			...(title === undefined ? {} : { title }),
-			tokens: { [OWNER_TOKEN_KEY]: OWNER_TOKEN_VALUE, ...tokens },
+			tokens: {
+				[OWNER_TOKEN_KEY]: OWNER_TOKEN_VALUE,
+				[LEGACY_OWNER_TOKEN_KEY]: LEGACY_OWNER_TOKEN_VALUE,
+				...tokens,
+			},
 		});
 	};
 
 	const onEvent = (event: MuxEvent): void => {
+		if (event.kind === "layout.updated") {
+			docks?.noteLayoutUpdated(event.geometry);
+			return;
+		}
+		if (event.kind === "pane.moved") {
+			// herdr rewrites the pane id on a move; the registry and dock state
+			// follow it so ownership is not lost to the user reorganizing.
+			const held = registry.forget(event.previousPaneId);
+			if (held) {
+				registry.record({ ...held, ref: { paneId: event.paneId, tabId: event.tabId, workspaceId: event.workspaceId } });
+				docks?.notePaneMoved(event.previousPaneId, event.paneId, event.tabId);
+			}
+			return;
+		}
+		docks?.notePaneGone(event.paneId);
 		const dropped = registry.forget(event.paneId);
 		if (dropped) {
 			log("debug", `mux pane ${event.paneId} left on ${event.kind}; dropped from the registry`);
@@ -231,38 +287,57 @@ export function createMuxRuntime(options: MuxRuntimeOptions): MuxRuntime {
 		},
 
 		async openUtilityPane(request: MuxOpenUtilityPaneRequest): Promise<MuxPaneRef | null> {
+			// Idempotence for docks: a slot that already has a pane answers with it.
+			const dockSlot = request.dock?.slot;
+			if (dockSlot && docks) {
+				const existing = docks.stateFor(dockSlot);
+				const held = existing ? registry.byPaneId(existing.paneId) : null;
+				if (held) return held.ref;
+			}
 			return await attempt(
 				"openUtilityPane",
 				async (live) => {
-					const anchor = detection.self.paneId ?? (await live.paneCurrent()).paneId;
-					const pane = await live.paneSplit({
-						direction: request.direction ?? "right",
-						targetPaneId: anchor,
-						cwd: request.cwd,
-						focus: false,
-						...(request.env ? { env: request.env } : {}),
-					});
-					const ref: MuxPaneRef = { paneId: pane.paneId, tabId: pane.tabId, workspaceId: pane.workspaceId };
+					let ref: MuxPaneRef;
+					if (request.dock && docks) {
+						const placed = await docks.open(request.dock.slot, {
+							...(request.dock.share === undefined ? {} : { share: request.dock.share }),
+							cwd: request.cwd,
+							...(request.env ? { env: request.env } : {}),
+						});
+						// A refusal (anchor too small) is an answer, not a failure.
+						if (placed === null) return null;
+						ref = placed;
+					} else {
+						const anchor = anchorPaneId ?? (await live.paneCurrent()).paneId;
+						const pane = await live.paneSplit({
+							direction: request.direction ?? "right",
+							targetPaneId: anchor,
+							cwd: request.cwd,
+							focus: false,
+							...(request.env ? { env: request.env } : {}),
+						});
+						ref = { paneId: pane.paneId, tabId: pane.tabId, workspaceId: pane.workspaceId };
+					}
 					const purpose = request.purpose ?? "utility";
 					registry.record(paneRecord(ref, { purpose, label: request.label, openedAt: now() }));
 					const title = request.title;
 					const titleSupported = title !== undefined && muxSupportsMethod(detection.server, "pane.rename");
 					if (titleSupported) {
 						try {
-							await live.paneRename(pane.paneId, title);
+							await live.paneRename(ref.paneId, title);
 						} catch {
 							// Presentation is optional. A server that advertises the floor but
 							// lacks or refuses rename must not strand an otherwise healthy pane.
 						}
 					}
 					// The `role` token is what adoptPane finds again after a restart.
-					await tagOwner(live, pane.paneId, { role: token(purpose) }, titleSupported ? title : undefined);
+					await tagOwner(live, ref.paneId, { role: token(purpose) }, titleSupported ? title : undefined);
 					if (request.argv.length > 0) {
 						// herdr has no argv parameter on pane.split, so the command goes in
 						// through the pane's shell. `exec` replaces the shell so the pane
 						// exits with the program and emits pane.exited for reconciliation.
 						const redirect = request.stdoutPath ? ` > ${shellQuote([request.stdoutPath])}` : "";
-						await live.paneSendText(pane.paneId, `exec ${shellQuote(request.argv)}${redirect}\n`);
+						await live.paneSendText(ref.paneId, `exec ${shellQuote(request.argv)}${redirect}\n`);
 					}
 					return ref;
 				},
@@ -280,13 +355,18 @@ export function createMuxRuntime(options: MuxRuntimeOptions): MuxRuntime {
 				async (live) => {
 					await live.paneClose(paneId);
 					registry.forget(paneId);
+					// Dock state must fall with the registry entry, not ride on the async
+					// pane.closed push: if the event subscription failed at start(), no
+					// push ever comes, and a slot pointing at a dead pane makes every
+					// later dock open return the corpse.
+					docks?.notePaneGone(paneId);
 					return true;
 				},
 				false,
 			);
 		},
 
-		async adoptPane(request: { purpose: MuxPanePurpose; label: string }): Promise<MuxPaneRef | null> {
+		async adoptPane(request: { purpose: MuxPanePurpose; label: string; dock?: DockSlot }): Promise<MuxPaneRef | null> {
 			const existing = registry.byPurpose(request.purpose);
 			if (existing) return existing.ref;
 			return await attempt(
@@ -294,7 +374,7 @@ export function createMuxRuntime(options: MuxRuntimeOptions): MuxRuntime {
 				async (live) => {
 					const snapshot = await live.snapshot();
 					for (const pane of snapshot.panes) {
-						if (pane.tokens[OWNER_TOKEN_KEY] !== OWNER_TOKEN_VALUE) continue;
+						if (!hasOwnedPaneToken(pane.tokens)) continue;
 						if (pane.tokens.role !== request.purpose) continue;
 						if (registry.owns(pane.paneId)) continue;
 						// Another workspace's pane belongs to another session's screen;
@@ -304,6 +384,9 @@ export function createMuxRuntime(options: MuxRuntimeOptions): MuxRuntime {
 						registry.record(
 							paneRecord(ref, { purpose: request.purpose, label: request.label, openedAt: now(), adopted: true }),
 						);
+						// Crash recovery for a dock: the surviving pane takes the slot back so
+						// geometry management resumes instead of a second dock opening.
+						if (request.dock && docks) docks.adopt(request.dock, ref);
 						log("info", `mux adopted a ${request.purpose} pane left open by a previous session`);
 						return ref;
 					}
@@ -313,6 +396,44 @@ export function createMuxRuntime(options: MuxRuntimeOptions): MuxRuntime {
 			);
 		},
 
+		async focusPane(paneId: string): Promise<boolean> {
+			// Ownership first: focusing the user's own panes stays off the table
+			// even though the wire allows it.
+			if (!registry.owns(paneId)) return false;
+			if (!muxSupportsMethod(detection.server, "pane.focus")) return false;
+			return await attempt(
+				"focusPane",
+				async (live) => {
+					await live.paneFocus(paneId);
+					return true;
+				},
+				false,
+			);
+		},
+
+		async zoomPane(paneId: string, mode: "on" | "off" | "toggle"): Promise<boolean> {
+			if (!registry.owns(paneId)) return false;
+			if (!muxSupportsMethod(detection.server, "pane.zoom")) return false;
+			return await attempt(
+				"zoomPane",
+				async (live) => {
+					const result = await live.paneZoom(paneId, mode);
+					// A toggle always changes state; on/off report false when already there.
+					return result.changed;
+				},
+				false,
+			);
+		},
+
+		async resizeDock(slot: DockSlot, share: number): Promise<boolean> {
+			if (!docks) return false;
+			return await attempt("resizeDock", () => docks.resize(slot, share), false);
+		},
+
+		docks(): ReadonlyArray<DockState> {
+			return docks?.states() ?? [];
+		},
+
 		async notify(request: MuxNotifyRequest): Promise<void> {
 			if (!muxSupportsMethod(detection.server, "notification.show")) {
 				log("debug", `mux notify skipped, server protocol is below the notification.show floor: ${request.title}`);
@@ -404,9 +525,17 @@ export function createMuxRuntime(options: MuxRuntimeOptions): MuxRuntime {
 			subscription?.close();
 			subscription = null;
 			paneGoneHandlers.clear();
-			// Pane ownership is server-side and intentionally survives process
-			// shutdown. Keep the local snapshot too so the contract itself proves
-			// shutdown tears down sockets, never panes.
+			// Docks close with the session: a native application takes its windows
+			// with it. A crash never reaches this method, which is exactly what
+			// leaves dock panes behind for the next session's adoption path.
+			// Unmanaged utility panes are the operator's and stay open.
+			if (client && docks) {
+				for (const paneId of docks.paneIds()) {
+					await client.paneClose(paneId).catch(() => undefined);
+					registry.forget(paneId);
+				}
+				docks.clear();
+			}
 			if (client) await client.close().catch(() => undefined);
 		},
 	};
@@ -414,12 +543,15 @@ export function createMuxRuntime(options: MuxRuntimeOptions): MuxRuntime {
 	const start = async (): Promise<void> => {
 		if (detection.mode === "none" || client === null) return;
 		try {
-			subscription = await client.subscribe(["pane.closed", "pane.exited"], onEvent, {
+			const kinds: ("pane.closed" | "pane.exited" | "pane.moved" | "layout.updated")[] = ["pane.closed", "pane.exited"];
+			if (docks) kinds.push("pane.moved", "layout.updated");
+			subscription = await client.subscribe(kinds, onEvent, {
 				onResync: (snapshot) => {
 					// A reconnect means events were missed. The snapshot is the authority
 					// on which panes still exist, so anything Clio thinks it owns that is
 					// absent from it is gone.
 					const dropped = registry.reconcile(snapshot.panes.map((pane) => pane.paneId));
+					for (const record of dropped) docks?.notePaneGone(record.ref.paneId);
 					if (dropped.length > 0) {
 						log("info", `mux reconciled ${dropped.length} pane(s) closed while the socket was down`);
 					}