@iowarp/clio-coder 0.4.0 → 0.4.2

package/src/interactive/turn-runtime.ts

@@ -52,7 +52,7 @@ import type { TurnMiddleware } from "./turn-middleware.js";
 import type { TurnPersistence } from "./turn-persistence.js";
 import type { AgentRuntime, ChatLoopTarget, ChatTurnState } from "./turn-state.js";
 
-const LOCAL_API_KEY_FALLBACK = "clio-local-target";
+const LOCAL_API_KEY_FALLBACK = "clio-coder-local-target";
 
 /**
  * A turn that never started, with a machine-readable reason attached. The
@@ -85,7 +85,7 @@ export class TurnAdmissionError extends Error {
  * same discovery view the planner budgets against, so a model Clio is planning
  * a loaded window for is never announced as absent.
  */
-export function coldModelNotice(
+function coldModelNotice(
 	status: TargetStatus | null | undefined,
 	targetId: string,
 	wireModelId: string,
@@ -183,13 +183,13 @@ export function createTurnRuntime(deps: TurnRuntimeDeps): TurnRuntime {
 
 	const readTarget = (): ChatLoopTarget | null => {
 		const settings = deps.getSettings();
-		const targetId = settings.orchestrator.target?.trim();
-		const wireModelId = settings.orchestrator.model?.trim();
+		const targetId = settings.chat.target?.trim();
+		const wireModelId = settings.chat.model?.trim();
 		if (!targetId || !wireModelId) return null;
 		const resolved = resolveRuntimeTarget(deps.providers, {
 			targetId,
 			wireModelId,
-			requestedThinkingLevel: settings.orchestrator.thinkingLevel ?? "off",
+			requestedThinkingLevel: settings.chat.thinkingLevel ?? "off",
 			use: "orchestrator",
 			requireTools: false,
 			requireOutputBudget: true,
@@ -243,8 +243,8 @@ export function createTurnRuntime(deps: TurnRuntimeDeps): TurnRuntime {
 	const targetProbesInFlight = new Map<string, Promise<void>>();
 	const ensureLiveCapabilitiesForSelectedModel = async (): Promise<void> => {
 		const settings = deps.getSettings();
-		const targetId = settings.orchestrator.target?.trim();
-		const wireModelId = settings.orchestrator.model?.trim();
+		const targetId = settings.chat.target?.trim();
+		const wireModelId = settings.chat.model?.trim();
 		if (!targetId || !wireModelId) return;
 		const target = deps.providers.getTarget(targetId);
 		if (!target) return;
@@ -316,7 +316,7 @@ export function createTurnRuntime(deps: TurnRuntimeDeps): TurnRuntime {
 					const refreshed = resolveRuntimeTarget(deps.providers, {
 						targetId: target.target.id,
 						wireModelId: target.wireModelId,
-						requestedThinkingLevel: deps.getSettings().orchestrator.thinkingLevel ?? "off",
+						requestedThinkingLevel: deps.getSettings().chat.thinkingLevel ?? "off",
 						use: "orchestrator",
 						requireTools: false,
 						requireOutputBudget: true,

package/src/interactive/turn-state.ts

@@ -43,7 +43,7 @@ export interface ChatLoopRunSnapshot {
 	runtimeId: string;
 	runtimeKind: RuntimeDescriptor["kind"];
 	wireModelId: string;
-	autonomy: ClioSettings["autonomy"];
+	autonomy: ClioSettings["safety"]["autonomy"];
 	compiledPromptHash: string | null;
 	staticCompositionHash: string | null;
 	promptSignature: string | null;

package/src/interactive/view/artifacts.ts

@@ -151,7 +151,6 @@ const RECEIPT_REQUIRED_KEYS = [
 	"costUsd",
 	"compiledPromptHash",
 	"staticCompositionHash",
-	"clioVersion",
 	"piMonoVersion",
 	"platform",
 	"nodeVersion",
@@ -255,7 +254,7 @@ export function receiptFilePath(stateDir: string, runId: string): string {
 	return join(stateDir, "receipts", `${runId}.json`);
 }
 
-export function runLedgerPath(stateDir: string): string {
+function runLedgerPath(stateDir: string): string {
 	return join(stateDir, "runs.json");
 }
 
@@ -317,7 +316,7 @@ type ReadLedgerResult = { ok: true; envelope: RunEnvelope } | { ok: false; reaso
  * the same file and ledger row, projected through the shared boundary so the
  * receipt view spells its verdict exactly as the board and the CLI do.
  */
-export function receiptTrustDetail(stateDir: string, runId: string): string {
+function receiptTrustDetail(stateDir: string, runId: string): string {
 	try {
 		const receipt = JSON.parse(readFileSync(receiptFilePath(stateDir, runId), "utf8")) as RunReceipt;
 		const ledger = readRunEnvelope(stateDir, runId);
@@ -335,7 +334,7 @@ function readRunEnvelope(stateDir: string, runId: string): ReadLedgerResult {
 	return { ok: false, reason: runs.length === 0 ? "run ledger not found" : "run not found in ledger" };
 }
 
-export function verifyReceiptFile(stateDir: string, runId: string): ReceiptVerifyResult {
+function verifyReceiptFile(stateDir: string, runId: string): ReceiptVerifyResult {
 	const target = receiptFilePath(stateDir, runId);
 	let raw: string;
 	try {
@@ -358,6 +357,9 @@ export function verifyReceiptFile(stateDir: string, runId: string): ReceiptVerif
 	for (const key of RECEIPT_REQUIRED_KEYS) {
 		if (!(key in r)) return { ok: false, reason: `missing field: ${key}` };
 	}
+	if (!("clioCoderVersion" in r) && !("clioVersion" in r)) {
+		return { ok: false, reason: "missing field: clioCoderVersion" };
+	}
 	if (!isNonEmptyString(r.runId)) {
 		return { ok: false, reason: `runId invalid: ${String(r.runId)}` };
 	}
@@ -413,8 +415,9 @@ export function verifyReceiptFile(stateDir: string, runId: string): ReceiptVerif
 	if (!isIso8601(r.endedAt)) {
 		return { ok: false, reason: `endedAt not ISO-8601: ${String(r.endedAt)}` };
 	}
-	if (typeof r.clioVersion !== "string" || r.clioVersion.length === 0) {
-		return { ok: false, reason: "clioVersion empty" };
+	const clioCoderVersion = r.clioCoderVersion ?? r.clioVersion;
+	if (typeof clioCoderVersion !== "string" || clioCoderVersion.length === 0) {
+		return { ok: false, reason: "clioCoderVersion empty" };
 	}
 	if (!isNonEmptyString(r.piMonoVersion)) {
 		return { ok: false, reason: `piMonoVersion invalid: ${String(r.piMonoVersion)}` };
@@ -453,7 +456,7 @@ export function verifyReceiptFile(stateDir: string, runId: string): ReceiptVerif
 
 const RECEIPT_FILE_FAILURE = /^(?:receipt file not found|read error:)/u;
 const RECEIPT_CONTRACT_FAILURE =
-	/^(?:invalid json:|receipt is not an object|missing field:|runId invalid:|runId mismatch:|agentId invalid:|task invalid:|targetId invalid:|wireModelId invalid:|runtimeId invalid:|runtimeKind invalid:|exitCode out of range:|tokenCount out of range:|inputTokenCount out of range:|outputTokenCount out of range:|cacheReadTokenCount out of range:|cacheWriteTokenCount out of range:|costUsd out of range:|reasoningTokenCount out of range:|startedAt not ISO-8601:|endedAt not ISO-8601:|clioVersion empty|piMonoVersion invalid:|platform invalid:|nodeVersion invalid:|toolCalls out of range:|toolStats\[|compiledPromptHash invalid:|staticCompositionHash invalid:|sessionId invalid:|integrity invalid|execution role invalid|routing intent invalid|route decision invalid)/u;
+	/^(?:invalid json:|receipt is not an object|missing field:|runId invalid:|runId mismatch:|agentId invalid:|task invalid:|targetId invalid:|wireModelId invalid:|runtimeId invalid:|runtimeKind invalid:|exitCode out of range:|tokenCount out of range:|inputTokenCount out of range:|outputTokenCount out of range:|cacheReadTokenCount out of range:|cacheWriteTokenCount out of range:|costUsd out of range:|reasoningTokenCount out of range:|startedAt not ISO-8601:|endedAt not ISO-8601:|clioCoderVersion empty|piMonoVersion invalid:|platform invalid:|nodeVersion invalid:|toolCalls out of range:|toolStats\[|compiledPromptHash invalid:|staticCompositionHash invalid:|sessionId invalid:|integrity invalid|execution role invalid|routing intent invalid|route decision invalid)/u;
 const LEDGER_FAILURE = /^(?:run ledger not found|run not found in ledger|ledger mismatch:)/u;
 
 function receiptIntegrityDigest(value: unknown): string | null {
@@ -586,7 +589,7 @@ function splitLinesCapped(text: string, path?: string, maxLines = VIEW_ARTIFACT_
 	return [...lines.slice(0, maxLines), `[truncated, open file directly${path ? `: ${path}` : ""}]`];
 }
 
-export async function loadJsonFileLines(path: string): Promise<ViewArtifactLoadResult> {
+async function loadJsonFileLines(path: string): Promise<ViewArtifactLoadResult> {
 	let canPrettyPrint = false;
 	try {
 		const info = await stat(path);
@@ -1569,7 +1572,7 @@ export function createDefaultArtifactProviders(deps: ArtifactProviderDeps): Arti
 	];
 }
 
-export function sortViewArtifacts(artifacts: ReadonlyArray<ViewArtifact>): ViewArtifact[] {
+function sortViewArtifacts(artifacts: ReadonlyArray<ViewArtifact>): ViewArtifact[] {
 	return [...artifacts].sort((a, b) => {
 		const time = b.timestamp - a.timestamp;
 		if (time !== 0) return time;

package/src/interactive/view/view-overlay.ts

@@ -141,7 +141,7 @@ function isViewArtifactCategory(value: string): value is ViewArtifactCategory {
 	return VIEW_ARTIFACT_CATEGORY_SET.has(value as ViewArtifactCategory);
 }
 
-export function parseViewFilterQuery(query: string): ViewFilterQuery {
+function parseViewFilterQuery(query: string): ViewFilterQuery {
 	const text = query.trim();
 	if (text.length === 0) return { kind: "text", text };
 	const colon = text.indexOf(":");
@@ -215,7 +215,7 @@ function formatLocalTime(timestamp: number): string {
 	return !Number.isFinite(timestamp) || timestamp <= 0 ? "unknown time" : clockLocal(timestamp);
 }
 
-export function filterViewArtifacts(artifacts: ReadonlyArray<ViewArtifact>, query: string): ViewArtifact[] {
+function filterViewArtifacts(artifacts: ReadonlyArray<ViewArtifact>, query: string): ViewArtifact[] {
 	const parsed = parseViewFilterQuery(query);
 	if (parsed.kind === "category") {
 		const categoryArtifacts = artifacts.filter((artifact) => artifact.category === parsed.category);
@@ -226,11 +226,11 @@ export function filterViewArtifacts(artifacts: ReadonlyArray<ViewArtifact>, quer
 	return fuzzyFilter([...artifacts], parsed.text, broadFilterText);
 }
 
-export function artifactsInCategoryOrder(artifacts: ReadonlyArray<ViewArtifact>): ViewArtifact[] {
+function artifactsInCategoryOrder(artifacts: ReadonlyArray<ViewArtifact>): ViewArtifact[] {
 	return VIEW_ARTIFACT_CATEGORIES.flatMap((category) => artifacts.filter((artifact) => artifact.category === category));
 }
 
-export function initialViewSelection(artifacts: ReadonlyArray<ViewArtifact>, initialFilter = ""): number {
+function initialViewSelection(artifacts: ReadonlyArray<ViewArtifact>, initialFilter = ""): number {
 	const filtered = filterViewArtifacts(artifacts, initialFilter);
 	const first = filtered[0];
 	if (!first) return 0;
@@ -252,7 +252,7 @@ export function initialViewSelection(artifacts: ReadonlyArray<ViewArtifact>, ini
 	return Math.max(0, artifactsInCategoryOrder(filtered).indexOf(selected));
 }
 
-export function nextCategorySelection(
+function nextCategorySelection(
 	artifacts: ReadonlyArray<ViewArtifact>,
 	currentIndex: number,
 	direction: -1 | 1,
@@ -271,7 +271,7 @@ export function nextCategorySelection(
 	return safeCurrent;
 }
 
-export function groupedViewRows(artifacts: ReadonlyArray<ViewArtifact>): RenderedViewRow[] {
+function groupedViewRows(artifacts: ReadonlyArray<ViewArtifact>): RenderedViewRow[] {
 	const rows: RenderedViewRow[] = [];
 	for (const category of VIEW_ARTIFACT_CATEGORIES) {
 		const items = artifacts.filter((artifact) => artifact.category === category);
@@ -334,7 +334,7 @@ function verificationText(state: ViewVerificationState | undefined): string {
 	return `${GLYPH.error} verify fail ${state.detail}`;
 }
 
-export function buildArtifactHeader(
+function buildArtifactHeader(
 	artifact: ViewArtifact | undefined,
 	verification: ViewVerificationState | undefined,
 	width: number,
@@ -361,7 +361,7 @@ export function buildArtifactHeader(
 }
 
 /** Put verification on wrapped rows so a canonical receipt verdict is never reduced to a prefix. */
-export function buildArtifactHeaderLines(
+function buildArtifactHeaderLines(
 	artifact: ViewArtifact | undefined,
 	verification: ViewVerificationState | undefined,
 	width: number,
@@ -384,7 +384,7 @@ export function buildArtifactHeaderLines(
 	];
 }
 
-export function viewFooterHint(focus: ViewPaneFocus, canVerify: boolean, innerWidth?: number): string {
+function viewFooterHint(focus: ViewPaneFocus, canVerify: boolean, innerWidth?: number): string {
 	// One pane at a time means Tab is how the other one is reached, so the
 	// narrow footer states it. The generic elider drops middle entries, and Tab
 	// sits in the middle.
@@ -527,6 +527,7 @@ export class ViewOverlayView implements Component {
 	private renderedContentLines(width: number): string[] {
 		const content = this.content;
 		if (!content) return [];
+		if (content.status === "error") return content.lines.flatMap((line) => wrapTextWithAnsi(line, Math.max(1, width)));
 		if (content.format !== "markdown") return content.lines;
 		if (content.renderedLines && content.renderWidth === width) return content.renderedLines;
 		const md = new Markdown(content.lines.join("\n"), 0, 0, markdownTheme(clioTheme()));
@@ -548,7 +549,9 @@ export class ViewOverlayView implements Component {
 			return this.fixedLines(lines, width, height);
 		}
 		if (this.artifactError) {
-			lines.push(padAnsi(theme.fg("error", this.artifactError), width, ELLIPSIS));
+			lines.push(
+				...wrapTextWithAnsi(theme.fg("error", this.artifactError), Math.max(1, width)).map((line) => padAnsi(line, width)),
+			);
 			return this.fixedLines(lines, width, height);
 		}
 

package/src/interactive/watch-pane.ts

@@ -21,7 +21,7 @@
 import { mkdirSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { type ClioDirs, clioCacheDir, clioConfigDir, clioDataDir, clioStateDir } from "../core/xdg.js";
-import type { MuxContract } from "../domains/mux/index.js";
+import type { MuxContract, MuxPaneRef } from "../domains/mux/index.js";
 import type { PanesWatchController, PanesWatchResult } from "../domains/mux/operations.js";
 import { watchViewerCommand } from "../domains/mux/viewer-command.js";
 
@@ -38,6 +38,12 @@ function watchSelectionPath(stateDir: string = clioStateDir()): string {
 export interface WatchPaneDeps {
 	mux: MuxContract;
 	getCwd: () => string;
+	/**
+	 * Live workers-dock share, read at each open so a `/settings` edit applies
+	 * to the next pane. Absent (tests, minimal wiring) the dock spec's default
+	 * governs.
+	 */
+	getWorkersRatio?: () => number;
 	/** Selection-file override for tests. */
 	selectionPath?: string;
 	/** Resolved-layout override for tests. Production pins this process's four cached roots. */
@@ -78,7 +84,7 @@ export function createWatchPaneController(deps: WatchPaneDeps): PanesWatchContro
 		if (disposed || paneId !== null) return Promise.resolve(true);
 		if (adoptionInFlight !== null) return adoptionInFlight;
 		const attempt = Promise.resolve()
-			.then(() => deps.mux.adoptPane({ purpose: "watch", label: "watch" }))
+			.then(() => deps.mux.adoptPane({ purpose: "watch", label: "watch", dock: "workers" }))
 			.then((adopted) => {
 				if (!disposed && paneId === null && adopted !== null) paneId = adopted.paneId;
 				return true;
@@ -104,11 +110,40 @@ export function createWatchPaneController(deps: WatchPaneDeps): PanesWatchContro
 		}
 	};
 
+	/**
+	 * The one place a watch pane is created: the workers dock slot, split right
+	 * of Clio's pane at the configured share. On a host without the layout tier
+	 * the dock request degrades inside the contract to a plain right split.
+	 */
+	const openPane = (): Promise<MuxPaneRef | null> =>
+		deps.mux.openUtilityPane({
+			argv: command(selectionPath, dirs),
+			cwd: deps.getCwd(),
+			label: "watch",
+			title: "clio-coder watch",
+			purpose: "watch",
+			dock: { slot: "workers", ...(deps.getWorkersRatio ? { share: deps.getWorkersRatio() } : {}) },
+		});
+
 	// Reclaim durable ownership for inventory and navigation immediately. The
 	// scan remains best effort and never opens a replacement pane on its own.
 	void adoptExistingPane();
 
 	return {
+		async ensureOpen(): Promise<boolean> {
+			// Boot composition: the pane exists and parks on the last selection
+			// (the viewer renders "no selection" until one is written). Adoption
+			// first, so a surviving dock is reused rather than doubled.
+			if (disposed) return false;
+			if (paneId !== null) return true;
+			await adoptExistingPane();
+			if (paneId !== null) return true;
+			const opened = await openPane();
+			if (opened === null) return false;
+			paneId = opened.paneId;
+			return true;
+		},
+
 		async watch(runId: string): Promise<PanesWatchResult> {
 			if (!writeSelection(runId)) {
 				return { status: "unavailable", reason: `cannot write the watch selection at ${selectionPath}` };
@@ -117,14 +152,7 @@ export function createWatchPaneController(deps: WatchPaneDeps): PanesWatchContro
 			const scanned = await adoptExistingPane();
 			if (!scanned) await adoptExistingPane();
 			if (paneId !== null) return { status: "watching", runId, paneId, opened: false };
-			const opened = await deps.mux.openUtilityPane({
-				argv: command(selectionPath, dirs),
-				cwd: deps.getCwd(),
-				label: "watch",
-				title: "clio watch",
-				purpose: "watch",
-				direction: "right",
-			});
+			const opened = await openPane();
 			if (opened === null) {
 				return { status: "unavailable", reason: "the pane host refused to open the watch pane" };
 			}

package/src/interactive/welcome-dashboard.ts

@@ -103,7 +103,7 @@ function findCurrentStatus(
 	statuses: ReadonlyArray<TargetStatus>,
 	settings: Readonly<ClioSettings> | undefined,
 ): TargetStatus | null {
-	const targetId = settings?.orchestrator?.target ?? null;
+	const targetId = settings?.chat?.target ?? null;
 	if (!targetId) return null;
 	return statuses.find((status) => status.target.id === targetId) ?? null;
 }
@@ -127,7 +127,7 @@ function selectedModelCapabilities(
 	providers: ProvidersContract,
 ): CapabilityFlags | null {
 	if (!status) return null;
-	const wireModelId = settings?.orchestrator?.model ?? status.target.defaultModel ?? null;
+	const wireModelId = settings?.chat?.model ?? status.target.defaultModel ?? null;
 	const detectedReasoning =
 		wireModelId && typeof providers.getDetectedReasoning === "function"
 			? providers.getDetectedReasoning(status.target.id, wireModelId)
@@ -216,7 +216,7 @@ function handoffFacts(cwd: string): { handoffCount: number; handoffFreshness: st
 	}
 }
 
-export function readWelcomeRepositoryFacts(cwd: string): WelcomeRepositoryFacts {
+function readWelcomeRepositoryFacts(cwd: string): WelcomeRepositoryFacts {
 	const codewiki = readCodewiki(cwd);
 	const wiki = codewiki ? wikiFactsFrom(cwd, wikiStaleness(cwd)) : { wikiPageCount: 0, wikiStatus: NO_WIKI_STATUS };
 	return {
@@ -255,7 +255,7 @@ async function readWelcomeRepositoryFactsAsync(cwd: string): Promise<WelcomeRepo
  * guessed, because it decides whether the Wiki row exists at all and the whole
  * point of a placeholder is that the banner never changes height.
  */
-export function placeholderRepositoryFacts(cwd: string): WelcomeRepositoryFacts {
+function placeholderRepositoryFacts(cwd: string): WelcomeRepositoryFacts {
 	return {
 		clioMdStatus: clioMdStatusFor(cwd),
 		hasCodewiki: existsSync(join(cwd, ".clio-coder", "codewiki.json")),
@@ -269,13 +269,13 @@ export function placeholderRepositoryFacts(cwd: string): WelcomeRepositoryFacts
 	};
 }
 
-export function deriveWelcomeDashboardStats(deps: WelcomeDashboardDeps): WelcomeDashboardStats {
+function deriveWelcomeDashboardStats(deps: WelcomeDashboardDeps): WelcomeDashboardStats {
 	const settings = deps.getSettings?.();
 	const statuses = deps.providers.list();
 	const current = findCurrentStatus(statuses, settings);
 	// Left null when unset; formatTargetLabel owns the one spelling for that.
-	const targetLabel = current?.target.id ?? settings?.orchestrator?.target ?? null;
-	const modelLabel = settings?.orchestrator?.model ?? current?.target.defaultModel ?? null;
+	const targetLabel = current?.target.id ?? settings?.chat?.target ?? null;
+	const modelLabel = settings?.chat?.model ?? current?.target.defaultModel ?? null;
 	const workspace = deps.getWorkspaceSnapshot?.() ?? null;
 	const cwd = workspace?.cwd ?? process.cwd();
 	const currentAvailable = current ? activeStatus(current) : false;
@@ -283,16 +283,16 @@ export function deriveWelcomeDashboardStats(deps: WelcomeDashboardDeps): Welcome
 	const thinkingLevel =
 		resolveModelRuntimeCapabilitiesForProviders(
 			deps.providers,
-			settings?.orchestrator?.target,
-			settings?.orchestrator?.model,
-			settings?.orchestrator?.thinkingLevel ?? "off",
+			settings?.chat?.target,
+			settings?.chat?.model,
+			settings?.chat?.thinkingLevel ?? "off",
 		)?.thinking.display ??
-		settings?.orchestrator?.thinkingLevel ??
+		settings?.chat?.thinkingLevel ??
 		"off";
 
-	const autonomy = settings?.autonomy ?? "auto-edit";
-	const toolProfile = settings?.delegation?.defaults?.toolGovernance ?? "clio-policy";
-	const threshold = settings?.compaction?.threshold;
+	const autonomy = settings?.safety.autonomy ?? "auto-edit";
+	const toolProfile = settings?.integrations.externalAgents?.defaults?.toolGovernance ?? "clio-coder-policy";
+	const threshold = settings?.context.compaction?.threshold;
 	const compactionThreshold =
 		typeof threshold === "number" && Number.isFinite(threshold) ? `${Math.round(threshold * 100)}%` : "80%";
 
@@ -376,7 +376,7 @@ function nextValue(stats: WelcomeDashboardStats): string {
  * route answers, and what the context is ready for. Maturity caveats belong
  * in the README, not in a line the operator reads on every turn.
  */
-export function buildWelcomeDashboardLines(
+function buildWelcomeDashboardLines(
 	stats: WelcomeDashboardStats,
 	width: number,
 	mode: WelcomeDashboardMode = "launchpad",

package/src/interactive/worker-progress.ts

@@ -164,9 +164,9 @@ function isThinkingEvent(event: Record<string, unknown>): boolean {
 	return assistantEvent?.type === "thinking_delta";
 }
 
-/** The action a `clio_tool_start`/`clio_tool_finish` event names, or null when it is neither. */
+/** The action a `clio_coder_tool_start`/`clio_coder_tool_finish` event names, or null when it is neither. */
 function toolEventAction(event: Record<string, unknown>): WorkerAction | null {
-	if (event.type !== "clio_tool_start" && event.type !== "clio_tool_finish") return null;
+	if (event.type !== "clio_coder_tool_start" && event.type !== "clio_coder_tool_finish") return null;
 	const payload = isRecord(event.payload) ? event.payload : null;
 	const tool = nonEmptyString(payload?.tool);
 	if (tool === undefined) return null;
@@ -363,7 +363,7 @@ export function createWorkerProgressFold(): WorkerProgressFold {
 			}
 
 			const action = toolEventAction(event);
-			if (action !== null && event.type === "clio_tool_start") {
+			if (action !== null && event.type === "clio_coder_tool_start") {
 				if (action.toolCallId !== undefined) {
 					const duplicate = pendingActionsById.get(action.toolCallId);
 					if (duplicate !== undefined) removePendingAction(duplicate);
@@ -375,7 +375,7 @@ export function createWorkerProgressFold(): WorkerProgressFold {
 				touch();
 				setPhase("tool");
 				changed = true;
-			} else if (action !== null && event.type === "clio_tool_finish") {
+			} else if (action !== null && event.type === "clio_coder_tool_finish") {
 				// An id is authoritative when both sides carry it. If either side came
 				// from an older or incomplete producer, retain the historical name match.
 				const finished =

package/src/interactive/worker-receipts.ts

@@ -77,7 +77,7 @@ function contractKindFrom(receipt: Record<string, unknown>): WorkerPresentedResu
  * by older versions of Clio are still valid history, so every field is read
  * structurally and a missing one degrades the footer rather than the render.
  */
-export function workerReceiptFacts(receipt: Record<string, unknown>): WorkerReceiptFacts | null {
+function workerReceiptFacts(receipt: Record<string, unknown>): WorkerReceiptFacts | null {
 	const outcome = optionalString(receipt.outcome);
 	if (outcome === undefined) return null;
 	const output = isRecord(receipt.output) ? receipt.output : null;

package/src/interactive/worker-stream.ts

@@ -185,10 +185,7 @@ function finiteNumber(value: unknown): number | undefined {
 	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
 }
 
-export function workerRuntimeKind(
-	runtimeKind: RunKind | undefined,
-	runtimeId: string | undefined,
-): WorkerRunRuntimeKind {
+function workerRuntimeKind(runtimeKind: RunKind | undefined, runtimeId: string | undefined): WorkerRunRuntimeKind {
 	if (runtimeKind === "acp-delegation") return "acp";
 	if (runtimeId === "claude-code") return "claude-code";
 	if (runtimeId === "claude-sdk") return "claude-sdk";

package/src/interactive/yazi-bridge.ts

@@ -25,6 +25,8 @@ export interface YaziBridgeSettings {
 	mode: YaziSessionMode;
 	profile: YaziProfileMode;
 	followCwd: boolean;
+	/** Files-dock share of the height; absent leaves the dock spec's default. */
+	ratio?: number;
 }
 
 export interface YaziMentionBatch {
@@ -50,6 +52,10 @@ export type YaziBridgeOpenResult =
 
 export interface YaziBridge {
 	open(options?: { once?: boolean }): Promise<YaziBridgeOpenResult>;
+	/** Close the files pane and hand focus back to the composer; false when nothing was open. */
+	close(): Promise<boolean>;
+	/** True while the pane host still reports the files pane. */
+	isOpen(): boolean;
 	status(): Readonly<YaziBridgeStatus>;
 	dispose(): void;
 }
@@ -111,7 +117,7 @@ function readOptional(path: string): string {
  * before the TUI lease is released. A missing or below-floor binary therefore
  * leaves the screen intact and returns the shared doctor sentence verbatim.
  */
-export async function runYaziTerminalChooser(options: YaziTerminalChooserOptions): Promise<YaziTerminalChooserResult> {
+async function runYaziTerminalChooser(options: YaziTerminalChooserOptions): Promise<YaziTerminalChooserResult> {
 	const binaries = (options.resolveBinaries ?? resolveYaziBinaries)();
 	if (!binaries.yaziPath) {
 		return { status: "missing-binary", binary: "yazi", detail: binaries.missingYaziDetail };
@@ -217,7 +223,7 @@ function pathKind(path: string): "file" | "directory" | "other" {
 }
 
 /** Format one DDS or chooser batch for the composer without ever submitting it. */
-export function formatYaziMentions(
+function formatYaziMentions(
 	paths: ReadonlyArray<string>,
 	options: {
 		cwd: string;
@@ -310,9 +316,12 @@ export function createYaziBridge(deps: YaziBridgeDeps): YaziBridge {
 		}
 		deps.setDraft(appendDraft(draft, batch.text));
 		deps.requestRender();
+		// The pick is the end of the operator's trip into the files pane, so the
+		// keyboard comes back to the composer without a click.
+		void deps.mux?.focusSelf();
 		deps.notice(
 			"info",
-			`${batch.inserted} ${batch.inserted === 1 ? "path" : "paths"} from the file pane added to the draft`,
+			`${batch.inserted} ${batch.inserted === 1 ? "path" : "paths"} from the files pane added to the draft`,
 		);
 		if (batch.plainPaths > 0) {
 			deps.notice(
@@ -328,7 +337,11 @@ export function createYaziBridge(deps: YaziBridgeDeps): YaziBridge {
 		}
 	};
 
-	const start = async (mode: YaziSessionMode, profileMode: YaziProfileMode): Promise<YaziBridgeOpenResult> => {
+	const start = async (
+		mode: YaziSessionMode,
+		profileMode: YaziProfileMode,
+		dockShare?: number,
+	): Promise<YaziBridgeOpenResult> => {
 		const mux = deps.mux;
 		if (!mux?.available()) return { status: "unavailable", reason: "the pane layer is not available" };
 		generation += 1;
@@ -341,6 +354,7 @@ export function createYaziBridge(deps: YaziBridgeDeps): YaziBridge {
 			mode,
 			profileMode,
 			cwd: deps.getCwd(),
+			...(dockShare === undefined ? {} : { dockShare }),
 			pickToken: token,
 			onEvent: (event: YaziEvent) => {
 				if (disposed || ownGeneration !== generation) return;
@@ -359,6 +373,8 @@ export function createYaziBridge(deps: YaziBridgeDeps): YaziBridge {
 				if (disposed || ownGeneration !== generation) return;
 				paneCwd = choice.cwd;
 				if (choice.paths.length > 0) insert(choice.paths, choice.cwd);
+				// A cancelled pick still ends the trip; the composer gets the keyboard back.
+				else void deps.mux?.focusSelf();
 			},
 			onStopped: () => {
 				if (ownGeneration !== generation) return;
@@ -372,14 +388,18 @@ export function createYaziBridge(deps: YaziBridgeDeps): YaziBridge {
 			return { status: "unavailable", reason: "the file pane was closed while it was opening" };
 		}
 		active = result.session;
+		// An explicit open is a request to go and pick something, so the keyboard
+		// follows the pane. The dock tier itself never steals focus; this is the
+		// one caller entitled to ask.
+		await mux.focusPane(result.session.pane.paneId);
 		if (mode === "companion") {
 			livenessTimer = setTimeout(() => {
 				if (disposed || ownGeneration !== generation || sawLine || active === null) return;
 				const stale = active;
 				active = null;
-				deps.notice("warning", "the file-pane event stream did not start; reopening yazi in chooser mode");
+				deps.notice("warning", "the files pane did not report back in time; reopening it in pick mode");
 				void stale.close().finally(() => {
-					if (!disposed && ownGeneration === generation) void start("chooser", profileMode);
+					if (!disposed && ownGeneration === generation) void start("chooser", profileMode, dockShare);
 				});
 			}, deps.livenessMs ?? YAZI_LIVENESS_MS);
 			livenessTimer.unref();
@@ -387,16 +407,49 @@ export function createYaziBridge(deps: YaziBridgeDeps): YaziBridge {
 		return { status: "opened", mode, paneId: result.session.pane.paneId, existing: false };
 	};
 
+	/**
+	 * The pane host is the authority on whether the pane exists. `active` lags
+	 * it by one event at most, but a caller deciding between open and close
+	 * must not be told a pane is open when herdr already reported it gone.
+	 */
+	const liveSession = (): YaziSession | null => {
+		if (active === null) return null;
+		const mux = deps.mux;
+		if (mux?.available() && !mux.list().some((record) => record.ref.paneId === active?.pane.paneId)) {
+			active = null;
+			return null;
+		}
+		return active;
+	};
+
+	const closeActive = async (): Promise<boolean> => {
+		const session = liveSession();
+		if (session === null) return false;
+		generation += 1;
+		clearLiveness();
+		active = null;
+		await session.close();
+		// Closing the dock the operator was looking at would otherwise leave
+		// focus wherever herdr puts it after a close, which is not the composer.
+		await deps.mux?.focusSelf();
+		return true;
+	};
+
 	return {
 		async open(options = {}): Promise<YaziBridgeOpenResult> {
-			if (disposed) return { status: "unavailable", reason: "the file-pane bridge is closed" };
+			if (disposed) return { status: "unavailable", reason: "the files pane bridge is closed" };
 			const settings = deps.getSettings?.() ?? { mode: "companion", profile: "managed", followCwd: true };
-			if (active) {
+			const existing = liveSession();
+			if (existing) {
 				if (settings.followCwd) {
 					const cwd = deps.getCwd();
-					if (await active.pushCwd(cwd)) paneCwd = cwd;
+					if (await existing.pushCwd(cwd)) paneCwd = cwd;
 				}
-				return { status: "opened", mode: active.mode, paneId: active.pane.paneId, existing: true };
+				// Re-opening an open pane means "take me there": leave any zoom that
+				// hides it and put the keyboard in it.
+				await deps.mux?.unzoomSelf();
+				await deps.mux?.focusPane(existing.pane.paneId);
+				return { status: "opened", mode: existing.mode, paneId: existing.pane.paneId, existing: true };
 			}
 			const mode = options.once || settings.profile === "user" ? "chooser" : settings.mode;
 			if (!deps.mux?.available()) {
@@ -419,7 +472,15 @@ export function createYaziBridge(deps: YaziBridgeDeps): YaziBridge {
 				}
 				return result;
 			}
-			return await start(mode, settings.profile);
+			await deps.mux.unzoomSelf();
+			return await start(mode, settings.profile, settings.ratio);
+		},
+		close(): Promise<boolean> {
+			if (disposed) return Promise.resolve(false);
+			return closeActive();
+		},
+		isOpen(): boolean {
+			return liveSession() !== null;
 		},
 		status(): Readonly<YaziBridgeStatus> {
 			const snapshot = active?.snapshot();