@iowarp/clio-coder 0.4.1 → 0.4.3

package/src/interactive/footer/widgets.ts

@@ -368,6 +368,13 @@ function contextComposition(context: ContextEngineFacts): {
 	};
 }
 
+/** The live window after the percent; null when unknown or the row is too narrow to carry it. */
+export function compactContextWindowLabel(context: ContextEngineFacts, width: number): string | null {
+	if (width < 72) return null;
+	const window = finiteNonNegative(context.ledger?.contextWindow ?? context.contextWindow);
+	return window > 0 ? formatFooterTokens(window) : null;
+}
+
 export function compactSecondaryLine(
 	context: ContextEngineFacts,
 	agent: AgentWorkFacts,
@@ -403,6 +410,12 @@ export function compactSecondaryLine(
 	} else {
 		left = buildSegmentedContextBar(theme, barCells, context.contextWindow ?? 0, contextBreakdownForBar(context));
 	}
+	// A percentage alone does not say whether the window is 128k or 1M, so at
+	// widths that can afford it the live window follows the percent. It comes
+	// from the ledger when one is bound (the layer that answered the window is
+	// also the layer that produced the percent) and from the facts otherwise.
+	const windowLabel = compactContextWindowLabel(context, safeWidth);
+	if (windowLabel) left = `${left} ${theme.fg("dim", "of")} ${theme.fg("muted", windowLabel)}`;
 	const maxRightWidth = Math.max(0, safeWidth - visibleWidth(left) - 1);
 	const right = buildMetricStrip(
 		theme,

package/src/interactive/interactive-application.ts

@@ -46,6 +46,7 @@ import type { createMuxBridge } from "./mux-bridge.js";
 import { createOverlayLifecycle, type OverlayLifecycleController, type OverlayState } from "./overlay-lifecycle.js";
 import { interopOverlaySurface } from "./overlays/interop.js";
 import { paneWatchDecision } from "./pane-policy.js";
+import { describePanesLeftBehind } from "./panes-runtime.js";
 import { writeInputWedgeDump } from "./render-trace.js";
 import { settleChatBeforeSessionSwitch } from "./session-switch-settlement.js";
 import { createSessionTranscript } from "./session-transcript.js";
@@ -54,9 +55,10 @@ import type {
 	InitCommandOptions,
 	RunIo,
 	SettingsAreaId,
+	SlashCommandContext,
 	TaskMemorySeedCommandResult,
 } from "./slash-commands.js";
-import { processAutoPacingAllowed, resolveSmoothStreamingMode } from "./stream-pacing-policy.js";
+import { processAutoPacingAllowed } from "./stream-pacing-policy.js";
 import type { TerminalLease } from "./terminal-lease.js";
 import type { createWatchPaneController } from "./watch-pane.js";
 import { createWorkspaceFacts } from "./workspace-facts.js";
@@ -121,6 +123,8 @@ export interface InteractiveDeps {
 	initialNotices?: ReadonlyArray<string>;
 	resources?: ResourcesContract;
 	extensions?: ExtensionsContract;
+	/** `/resources extensions reload` seam; the composition root supplies the coordinator. */
+	reloadExtensions?: SlashCommandContext["reloadExtensions"];
 	interop?: InteropContract;
 	share?: ShareContract;
 	/**
@@ -311,6 +315,8 @@ export interface KeyBindingDeps {
 	requestShutdown: () => void;
 	toggleStatus: () => void;
 	toggleDispatchBoard: () => void;
+	/** `/files` as a key: open the files pane when closed, close it when open. */
+	toggleFilesPane: () => void;
 	openTasks: () => void;
 	openDecisions: () => void;
 	backgroundDispatch: () => void;
@@ -396,6 +402,9 @@ function dispatchInteractiveAction(id: ClioKeybinding, deps: KeyBindingDeps): bo
 		case "clio-coder.dispatchBoard.toggle":
 			deps.toggleDispatchBoard();
 			return true;
+		case "clio-coder.files.toggle":
+			deps.toggleFilesPane();
+			return true;
 		case "clio-coder.tasks.open":
 			deps.openTasks();
 			return true;
@@ -430,6 +439,7 @@ export function routeInteractiveKey(data: string, deps: KeyBindingDeps): boolean
 		"clio-coder.thinking.cycle",
 		"clio-coder.session.tree",
 		"clio-coder.dispatchBoard.toggle",
+		"clio-coder.files.toggle",
 		"clio-coder.tasks.open",
 		"clio-coder.decisions.open",
 		"clio-coder.dispatch.background",
@@ -448,7 +458,7 @@ export function routeInteractiveKey(data: string, deps: KeyBindingDeps): boolean
 }
 
 export async function createInteractiveApplication(deps: InteractiveDeps): Promise<number> {
-	const initialSmoothStreaming = resolveSmoothStreamingMode(deps.getSettings?.().interface.smoothStreaming ?? "off");
+	const initialSmoothStreaming = deps.getSettings?.().interface.smoothStreaming ?? "off";
 	const initialAutoPacingAllowed = processAutoPacingAllowed(false);
 	const lease = deps.terminalLease;
 	const shell =
@@ -606,7 +616,7 @@ export async function createInteractiveApplication(deps: InteractiveDeps): Promi
 					getDraft: () => editor.getText(),
 					setDraft: (text) => editor.setText(text),
 					requestRender: () => tui.requestRender(),
-					notice: (level, text) => notify(level, text, `yazi:${level}`),
+					notice: (level, text) => notify(level, text, `files:${level}`),
 					getCwd: () => process.cwd(),
 					getSettings: () =>
 						deps.getSettings?.().interface.panes.files ?? {
@@ -672,7 +682,7 @@ export async function createInteractiveApplication(deps: InteractiveDeps): Promi
 		appendTranscriptNotice: (level, text) => appendNotice(level, text, busNoticeSink),
 		refreshSettingsOverlay: () => overlayLifecycle.refreshSettingsOverlay(),
 		onConfigHotReload: (settings) => {
-			const mode = resolveSmoothStreamingMode(settings.interface.smoothStreaming);
+			const mode = settings.interface.smoothStreaming;
 			const autoAllowed = processAutoPacingAllowed(shell.hasObservedBackpressure());
 			chatRenderer.setSmoothStreamingMode(mode);
 			shell.setStreamPacingActive(mode === "on" || (mode === "auto" && autoAllowed));
@@ -702,6 +712,7 @@ export async function createInteractiveApplication(deps: InteractiveDeps): Promi
 		settleVisibleFrame: (reason) => chatRenderer.flushAndCommit(reason),
 		...(deps.resources ? { resources: deps.resources } : {}),
 		...(deps.extensions ? { extensions: deps.extensions } : {}),
+		...(deps.reloadExtensions ? { reloadExtensions: deps.reloadExtensions } : {}),
 		...(interopSurface ? { interop: interopSurface } : {}),
 		...(deps.agents ? { agents: deps.agents } : {}),
 		...(deps.share ? { share: deps.share } : {}),
@@ -1056,6 +1067,25 @@ export async function createInteractiveApplication(deps: InteractiveDeps): Promi
 				if (deps.onCycleScopedModelBackward?.() === false) announceEmptyScopedSet();
 			},
 			backgroundActiveDispatch,
+			toggleFilesPane: () => {
+				const panes = deps.panes;
+				if (!panes) {
+					notify(
+						"info",
+						"the files pane is inactive: this session started without panes. Restart with `clio-coder --with-panes`, or set interface.panes.enabled=auto",
+						"files:info",
+					);
+					return;
+				}
+				void panes.files("toggle").then((result) => {
+					if (result.status === "opened") {
+						if (result.paneId !== null)
+							notify("success", `files pane ${result.existing ? "focused" : "opened"}`, "files:open");
+					} else if (result.status === "closed") notify("info", "files pane closed", "files:close");
+					else if (result.status === "missing-binary") notify("warning", result.detail, "files:missing");
+					else notify("warning", result.reason, "files:refused");
+				});
+			},
 		},
 		overlay: overlayLifecycle,
 		refreshFooter: () => footer.refresh(),
@@ -1137,6 +1167,11 @@ export async function createInteractiveApplication(deps: InteractiveDeps): Promi
 		},
 		cancelParkedCalls: (reason) => deps.toolRegistry?.cancelParkedCalls(reason),
 		onShutdown: async () => {
+			// The terminal is already stopped here and the domains have not, so this
+			// is the one moment a plain line about the pane host can both be read
+			// and still see the registry that shutdown is about to forget.
+			const leftBehind = mux && mux.mode !== "none" && mux.available() ? describePanesLeftBehind(mux) : null;
+			if (leftBehind !== null) process.stderr.write(`${leftBehind}\n`);
 			try {
 				if (dumpInputWedgeOnTerminate) process.off("SIGTERM", dumpInputWedgeOnTerminate);
 				await deps.onShutdown();

package/src/interactive/interactive-input-runtime.ts

@@ -21,6 +21,7 @@ export interface InteractiveInputKeyActionDeps {
 	requestShutdown: () => void;
 	toggleStatus: () => void;
 	toggleDispatchBoard: () => void;
+	toggleFilesPane: () => void;
 	openTasks: () => void;
 	openDecisions: () => void;
 	backgroundDispatch: () => void;
@@ -54,6 +55,8 @@ export interface InteractiveInputRuntimeDeps {
 		cycleScopedModelBackward(): void;
 		/** Convert the newest attached dispatch into a detached batch and notice the outcome. */
 		backgroundActiveDispatch(): void;
+		/** Toggle the files pane; the application decides what "inactive" says. */
+		toggleFilesPane(): void;
 	};
 	overlay: {
 		getState(): OverlayState;
@@ -154,6 +157,7 @@ export function createInteractiveInputRuntime(deps: InteractiveInputRuntimeDeps)
 		openTasks: deps.overlay.openTasksOverlayState,
 		openDecisions: deps.overlay.openDecisionsOverlayState,
 		backgroundDispatch: deps.actions.backgroundActiveDispatch,
+		toggleFilesPane: deps.actions.toggleFilesPane,
 		openModelSelector: deps.overlay.openModelOverlayState,
 		openTree: deps.overlay.openTreeOverlayState,
 		cycleScopedModelForward: () => {

package/src/interactive/interactive-presentation.ts

@@ -37,7 +37,7 @@ import { createSlashCommandAutocompleteProvider } from "./slash-autocomplete.js"
 import { parseSlashCommand, type RunIo } from "./slash-commands.js";
 import { createStatusController, type StatusController, type TurnSummary } from "./status/index.js";
 import type { SmoothStreamingMode } from "./stream-pacer.js";
-import { processAutoPacingAllowed, resolveSmoothStreamingMode } from "./stream-pacing-policy.js";
+import { processAutoPacingAllowed } from "./stream-pacing-policy.js";
 import { formatTargetLabel } from "./theme/index.js";
 import { createWelcomeDashboard, type WelcomeDashboardComponent } from "./welcome-dashboard.js";
 import { readWorkerReceiptFacts } from "./worker-receipts.js";
@@ -452,7 +452,7 @@ export function createInteractivePresentation(deps: InteractivePresentationDeps)
 			? {
 					streamIngress: deps.resolveStreamIngress,
 					getSmoothStreamingMode: () => {
-						const mode = resolveSmoothStreamingMode(deps.getSettings?.().interface.smoothStreaming ?? "off");
+						const mode = deps.getSettings?.().interface.smoothStreaming ?? "off";
 						const autoAllowed = processAutoPacingAllowed(deps.hasObservedBackpressure?.() ?? false);
 						deps.onSmoothStreamingMode?.(mode, mode === "on" || (mode === "auto" && autoAllowed));
 						return mode;

package/src/interactive/interactive-slash-runtime.ts

@@ -62,7 +62,7 @@ export interface InteractiveSlashSubmitExpansion {
 	pendingSkillRequests: PendingSkillRequest[];
 }
 
-type SlashChat = Pick<ChatLoop, "getSessionId" | "isStreaming" | "submit">;
+type SlashChat = Pick<ChatLoop, "clearSkillSurface" | "getSessionId" | "isStreaming" | "submit">;
 type SlashChatPanel = Pick<ChatPanel, "appendReplayBlock" | "appendUser" | "clearFoldOverrides">;
 type UserTurnStatus = import("./chat-panel.js").UserTurnStatus;
 type SlashResources = Pick<ResourcesContract, "prompts" | "expandPromptTemplate" | "reload">;
@@ -79,6 +79,7 @@ export interface InteractiveSlashRuntimeDeps {
 	chatPanel: SlashChatPanel;
 	resources?: SlashResources;
 	extensions?: SlashExtensions;
+	reloadExtensions?: SlashCommandContext["reloadExtensions"];
 	interop?: SlashCommandContext["interop"];
 	agents?: SlashAgents;
 	share?: SlashShare;
@@ -388,6 +389,7 @@ export function createInteractiveSlashRuntime(deps: InteractiveSlashRuntimeDeps)
 		listPrompts: () => deps.resources?.prompts(cwd()) ?? { items: [], diagnostics: [] },
 		...(resources ? { expandPromptTemplate: (text: string) => resources.expandPromptTemplate(text, cwd()) } : {}),
 		openSkillsHub: deps.openSkillsHub,
+		clearSkillSurface: () => deps.chat.clearSkillSurface(),
 		listExtensions: () => deps.extensions?.list(cwd(), { all: true }) ?? [],
 		listAgents: () => deps.agents?.listSpecs().filter((spec) => spec.audience !== "internal") ?? [],
 		listDelegationAgents: () => deps.getSettings?.().integrations.externalAgents.entries ?? [],
@@ -566,6 +568,7 @@ export function createInteractiveSlashRuntime(deps: InteractiveSlashRuntimeDeps)
 		openAgents: deps.openAgents,
 		openPrompts: deps.openPrompts,
 		openExtensions: deps.openExtensions,
+		...(deps.reloadExtensions ? { reloadExtensions: deps.reloadExtensions } : {}),
 		...(deps.openInterop ? { openInterop: deps.openInterop } : {}),
 		...(deps.interop ? { interop: deps.interop } : {}),
 		setEditorText: (text) => {

package/src/interactive/overlays/extensions.ts

@@ -10,7 +10,15 @@ export const EXTENSIONS_EMPTY =
 export function openExtensionsOverlay(tui: TUI, ctx: SlashCommandContext, onClose: () => void): OverlayHandle {
 	const list = ctx.listExtensions?.() ?? [];
 	const items: ListOverlayItem[] = list.map((ext) => {
-		const state = !ext.enabled ? "disabled" : ext.effective ? "active" : `shadowed:${ext.overriddenBy ?? "higher"}`;
+		const state = !ext.valid
+			? "invalid"
+			: !ext.compatible
+				? "incompatible"
+				: !ext.enabled
+					? "disabled"
+					: ext.loadable
+						? "active"
+						: `shadowed:${ext.overriddenBy ?? "higher"}`;
 
 		let meta = state;
 		if (state === "active") {

package/src/interactive/overlays/help-reference.ts

@@ -101,6 +101,19 @@ export function openHelpOverlay(
 				"**Tasks versus runs**: `/tasks` shows the agent's plan steps. Fleet runs are concrete delegated worker executions and remain in this board as recent terminal history.",
 			],
 		},
+		{
+			id: "topic-files-pane",
+			label: `${"panes & files".padEnd(30)}The files pane, the logs and shell panes, and what closes them`,
+			group: "Topics",
+			detail: () => [
+				"# Panes & files",
+				"**Where it works**: a session started inside a herdr pane with `clio-coder --with-panes` (or `interface.panes.enabled: auto`). Outside herdr `/files` still works as a full-screen pick that returns to the composer; `/panes open logs|shell` do not.",
+				"**Files pane**: `/files` or the Files toggle key (Alt+E by default) opens the file view below the session and moves the keyboard into it; the same key or command closes it. `/files pick` borrows it for one selection. It is off until `interface.panes.files.enabled` is `true`.",
+				"**Picking**: navigate, select with Space for several, then Ctrl+Y (or Enter in pick mode). The paths land in the composer as `@file` mentions and the keyboard returns to the composer.",
+				"**Logs and shell**: `/panes open logs` follows the newest dispatched run's journal; `/panes open shell` opens a shell in the workspace. A second open focuses the pane that is already there. `/panes close <name|all>` closes them; `/quit` closes the docks it manages (files, workers), leaves a shell or logs pane you opened, and prints which panes it left and how to close them.",
+				"**Engine**: the files pane runs a vendored file manager installed with `clio-coder tools install yazi`; `clio-coder doctor` and `/panes` say whether it resolved.",
+			],
+		},
 		{
 			id: "topic-steering-modes",
 			label: `${"steering modes".padEnd(30)}Interrupt, next slot, or end of turn: when a message lands mid-run`,

package/src/interactive/overlays/settings.ts

@@ -200,7 +200,7 @@ export const SETTINGS_LABELS_BY_ID = {
 	"panes.journal": "Run event journal",
 	"panes.yazi.enabled": "Files pane",
 	"panes.yazi.mode": "Files pane mode",
-	"panes.yazi.profile": "Yazi profile",
+	"panes.yazi.profile": "Files pane profile",
 	"panes.yazi.followCwd": "Follow conversation cwd",
 	"panes.yazi.ratio": "Files dock share",
 	scope: "Model cycle set",
@@ -208,6 +208,7 @@ export const SETTINGS_LABELS_BY_ID = {
 	"modelSelector.favorites": "Pinned favorites",
 	"budget.sessionCeilingUsd": "Session ceiling (USD)",
 	"defaults.maxTokens": "Output budget (tokens)",
+	"context.toolResultMaxBytes": "Tool result cap (bytes)",
 	"budget.concurrency": "Fleet concurrency",
 	"guardrails.turnToolCallBudget": "Turn tool-call budget",
 	"guardrails.workerToolCallCap": "Worker tool-call cap",
@@ -326,6 +327,7 @@ export const SETTINGS_SECTION_ROWS = {
 	budget: [
 		"budget.sessionCeilingUsd",
 		"defaults.maxTokens",
+		"context.toolResultMaxBytes",
 		"budget.concurrency",
 		"guardrails.turnToolCallBudget",
 		"guardrails.workerToolCallCap",
@@ -414,9 +416,10 @@ const SETTINGS_DESCRIPTIONS_BY_ID = {
 	"panes.layout": "What composes itself at interactive boot: nothing, the workers dock, or workers plus files.",
 	"panes.workers.ratio": "Share of the width the workers dock takes, at most half.",
 	"panes.journal": "Whether every dispatched run's event tail is written to disk for `clio-coder fleet view`.",
-	"panes.yazi.enabled": "Whether `/panes open yazi` may open the files pane or one-shot chooser.",
-	"panes.yazi.mode": "Keep Yazi beside the conversation, or close it after one selection.",
-	"panes.yazi.profile": "Use Clio's managed pick profile or leave the operator's Yazi profile untouched.",
+	"panes.yazi.enabled":
+		"Whether `/files`, its key, and `/panes open files` may open the files pane or the one-shot pick.",
+	"panes.yazi.mode": "Keep the files pane beside the conversation, or close it after one selection.",
+	"panes.yazi.profile": "Use Clio's managed, themed engine profile or the operator's own file-manager configuration.",
 	"panes.yazi.followCwd": "Push the conversation directory into an already-open companion pane.",
 	"panes.yazi.ratio": "Share of the height the files dock takes, at most half.",
 	scope: "Alt+J and Alt+K model cycle set.",
@@ -424,6 +427,7 @@ const SETTINGS_DESCRIPTIONS_BY_ID = {
 	"modelSelector.favorites": "Exact target/model refs pinned in /model.",
 	"budget.sessionCeilingUsd": "Per-session cost cap.",
 	"defaults.maxTokens": "Output tokens requested per turn, applied to every target.",
+	"context.toolResultMaxBytes": "Maximum bytes returned from one tool result before the full text spills to scratch.",
 	"budget.concurrency": "Parallel workers allowed during dispatch.",
 	"guardrails.turnToolCallBudget": "Soft per-turn tool-call budget for this chat loop.",
 	"guardrails.workerToolCallCap": "Lifetime ceiling on tool calls one dispatched worker may execute.",
@@ -475,6 +479,8 @@ const SETTINGS_HELP_BY_ID: Partial<Record<EditableSettingId, string>> = {
 		"read-only observes; suggest parks non-read calls; auto-edit edits, dispatches, and runs recognized commands; full-auto runs except command substitution and system-level changes. A confirmation marked exposure=outward parks for you at suggest and auto-edit.",
 	"defaults.maxTokens":
 		"Clamped down to each model's max-output cap and the remaining context window. Set 0 to use per-model caps only.",
+	"context.toolResultMaxBytes":
+		"The 192KB per-turn observation pool remains authoritative. Three full 64KB results consume it, so a fourth finds it filled. Whole number of at least 4096 bytes · default: 65536 (64KB).",
 	"compaction.threshold":
 		"pressure = estimated tokens ÷ context window. Higher keeps more history but risks overflow before a summary runs.",
 	"context.workingSet.enabled":
@@ -487,17 +493,17 @@ const SETTINGS_HELP_BY_ID: Partial<Record<EditableSettingId, string>> = {
 	"context.workingSet.minEvictableTokens":
 		"The floor sweep put marker break-even near 50 tokens; 200 is the churn guard. Whole number, 0 evicts anything · default: 200.",
 	"guardrails.turnToolCallBudget":
-		"Crossing it blocks further calls in the turn with a stop-and-summarize directive, and the hard interrupt ceiling sits a fixed margin above. A backstop against a model spraying unproductive calls, not a routine ceiling: a repo-wide audit legitimately runs dozens. Whole number of at least 1 · default: 60. Env override CLIO_CODER_TURN_TOOL_CALL_BUDGET beats this value.",
+		"Crossing it blocks further calls in the turn with a stop-and-summarize directive, and the hard interrupt ceiling sits a fixed margin above. A backstop against a model spraying unproductive calls, not a routine ceiling: a repo-wide audit legitimately runs dozens. Whole number of at least 1 · default: 60.",
 	"guardrails.workerToolCallCap":
-		"Bounds admitted calls, not attempts: a call the harness refuses never ran and never spends the cap. Dispatch takes the smaller of this and the agent recipe's own budget, so the recipe normally binds. Whole number of at least 1 · default: 150. Env override CLIO_CODER_WORKER_TOOL_CALL_CAP beats this value.",
+		"Bounds admitted calls, not attempts: a call the harness refuses never ran and never spends the cap. Dispatch takes the smaller of this and the agent recipe's own budget, so the recipe normally binds. Whole number of at least 1 · default: 150.",
 	"guardrails.maxDispatchRuns":
-		"Runs leaving the ring also lose their event journal directory. Whole number of at least 1 · default: 1000. Env override CLIO_CODER_MAX_DISPATCH_RUNS beats this value.",
+		"Runs leaving the ring also lose their event journal directory. Whole number of at least 1 · default: 1000.",
 	"guardrails.readMaxBytes":
-		"Clamped up to a 1KB floor at use. Whole number of bytes, at least 1 · default: 51200 (50KB). Env override CLIO_CODER_READ_MAX_BYTES beats this value.",
+		"Clamped up to a 1KB floor at use. Whole number of bytes, at least 1 · default: 51200 (50KB).",
 	"guardrails.observationTurnBudgetBytes":
-		"One pool shared by every observation-producing tool in a turn, so a single verbose tool cannot starve the rest. Whole number of bytes, at least 1 · default: 196608 (192KB). Env override CLIO_CODER_OBSERVATION_TURN_BUDGET_BYTES beats this value.",
+		"One pool shared by every observation-producing tool in a turn, so a single verbose tool cannot starve the rest. Whole number of bytes, at least 1 · default: 196608 (192KB).",
 	"guardrails.internalDispatchTimeoutMs":
-		"Covers the wiki documenter and the bootstrap scout. Continuous output satisfies the heartbeat watchdog and a run mid-generation spends no tool calls, so this is the only guard that ends a degenerate generator. Healthy runs finish in minutes. Whole milliseconds of at least 1 · default: 900000 (15 minutes). Env override CLIO_CODER_INTERNAL_DISPATCH_TIMEOUT_MS beats this value.",
+		"Covers the wiki documenter and the bootstrap scout. Continuous output satisfies the heartbeat watchdog and a run mid-generation spends no tool calls, so this is the only guard that ends a degenerate generator. Healthy runs finish in minutes. Whole milliseconds of at least 1 · default: 900000 (15 minutes).",
 	"retry.streamStallMs":
 		"Measured from the last token received, not from the request, so a slow-but-alive stream is never aborted. The retry then follows the same enabled/maxRetries/delay settings above. Whole milliseconds · default: 180000 (three minutes).",
 	"library.catalog":
@@ -593,14 +599,11 @@ const SETTINGS_VALUE_HELP_BY_ID: Partial<Record<EditableSettingId, Record<string
 		true: "compact automatically before a turn crosses the threshold",
 		false: "context is only compacted when you run /context compact",
 	},
-	// `embedded` is a declared rung with no implementation behind it, and a row
-	// that offered it beside two working values read as a third working value.
-	// It stays selectable, because refusing it outright would break a settings
-	// file that names it, but nothing here lets an operator pick it believing
-	// they will get panes.
+	// `embedded` is a declared rung with no implementation behind it yet; it
+	// runs as `auto` until Clio can own a pane host, and the hint says so.
 	"panes.enabled": {
 		auto: "detect a herdr session and join it as a guest; no pane host, no panes",
-		embedded: "NOT IMPLEMENTED (ships in phase 5): this session gets no panes at all, guest mode included",
+		embedded: "not implemented yet; behaves as auto (guest mode inside herdr) until Clio can own a pane host",
 		off: "never detect or open a pane",
 	},
 	"retry.enabled": {
@@ -1838,6 +1841,9 @@ function buildSettingItems(settings: Readonly<ClioSettings>, options?: BuildSett
 		settingItem("defaults.maxTokens", String(settings.chat.maxOutputTokens), {
 			values: ["0", "4096", "8192", "16384", "32768", "65536", "131072"],
 		}),
+		settingItem("context.toolResultMaxBytes", String(settings.context.toolResultMaxBytes), {
+			values: ["4096", "8192", "16384", "32768", "65536", "131072"],
+		}),
 		settingItem("budget.concurrency", String(settings.fleet.concurrency), {
 			values: ["auto", "1", "2", "4", "8"],
 		}),
@@ -2707,6 +2713,11 @@ function applySettingChange(settings: ClioSettings, id: string, value: string):
 				else settings.fleet.limits.internalRunTimeoutMs = next;
 			});
 			return;
+		case "context.toolResultMaxBytes":
+			applyNonNegativeInteger(value, (next) => {
+				if (next >= 4096) settings.context.toolResultMaxBytes = next;
+			});
+			return;
 		case "context.workingSet.enabled":
 			if (value === "true" || value === "false") settings.context.workingSet.enabled = value === "true";
 			return;

package/src/interactive/panes-runtime.ts

@@ -27,6 +27,7 @@ import type { MuxContract, MuxPaneRecord } from "../domains/mux/index.js";
 import {
 	PANES_PRESETS,
 	type PanesCloseResult,
+	type PanesFilesResult,
 	type PanesInventoryEntry,
 	type PanesOpenResult,
 	type PanesOperations,
@@ -36,6 +37,7 @@ import {
 	type PanesYaziController,
 	type PanesYaziStatus,
 	type PanesZoomResult,
+	resolvePanesPresetId,
 } from "../domains/mux/operations.js";
 import { resolveBinary } from "../tools/executables.js";
 import { type PaneWatchSource, paneWatchDecision } from "./pane-policy.js";
@@ -54,7 +56,16 @@ export interface PanesRuntimeDeps {
 	newestJournalRunId?: () => string | null;
 }
 
-const UNAVAILABLE = "the pane layer is not available in this session";
+/**
+ * Why there is no pane layer, in the operator's terms. Detection already
+ * knows (no `HERDR_ENV`, no socket, a refused rung); repeating that reason
+ * beside the refusal is what turns "unavailable" into a next step, and the
+ * `--with-panes` hint covers the session that never asked for panes.
+ */
+function unavailableReason(mux: MuxContract): string {
+	const reason = mux.detection().reason;
+	return `the pane layer is not available in this session: ${reason}. Start Clio inside a herdr session with \`clio-coder --with-panes\` to get panes`;
+}
 
 /** Fuzzy operator addressing shared by `close` and `zoom`: id, label, purpose; newest first. */
 function matchOwnedPane(owned: ReadonlyArray<MuxPaneRecord>, target: string): MuxPaneRecord | null {
@@ -78,6 +89,27 @@ function inventory(records: ReadonlyArray<MuxPaneRecord>): ReadonlyArray<PanesIn
 	}));
 }
 
+/**
+ * The sentence `/quit` prints about the panes it did not close, or null when
+ * there are none.
+ *
+ * Policy (#272): docks close with the session and utility panes stay. A dock
+ * is a Clio surface (the files pane, the workers watch pane), so it goes the
+ * way a native application's windows go. A pane opened with `/panes open
+ * shell|logs|<argv>` is a terminal the operator may be typing in, and killing
+ * it on quit is the one thing a pane host must never do behind the operator's
+ * back. The next session does not adopt it either, so without this line the
+ * pane simply sat there with nothing naming it. Computed before the mux
+ * domain stops, because shutdown forgets its registry.
+ */
+export function describePanesLeftBehind(mux: Pick<MuxContract, "list" | "docks">): string | null {
+	const dockIds = new Set(mux.docks().map((dock) => dock.paneId));
+	const left = mux.list().filter((record) => !dockIds.has(record.ref.paneId));
+	if (left.length === 0) return null;
+	const named = left.map((record) => `${record.label} (${record.ref.paneId})`).join(", ");
+	return `Clio left ${left.length} ${left.length === 1 ? "pane" : "panes"} open in herdr: ${named}. Utility panes stay when a session ends; the docks closed with it. Next time run \`/panes close all\` before \`/quit\` to take them with you, or close ${left.length === 1 ? "it" : "them"} now with \`herdr pane close <paneId>\`.`;
+}
+
 export function createPanesRuntime(deps: PanesRuntimeDeps): PanesOperations {
 	const probe = deps.resolveBinaryPath ?? resolveBinary;
 	const journalRoot = deps.journalRoot ?? runEventJournalRoot;
@@ -143,7 +175,7 @@ export function createPanesRuntime(deps: PanesRuntimeDeps): PanesOperations {
 	};
 
 	const show = async (target: string, source: PaneWatchSource): Promise<PanesShowResult> => {
-		if (!deps.mux.available()) return { status: "unavailable", reason: UNAVAILABLE };
+		if (!deps.mux.available()) return { status: "unavailable", reason: unavailableReason(deps.mux) };
 		const match = matchRun(target);
 		if (match === null) {
 			// The candidate list is what turns a miss into a next step: it names
@@ -164,7 +196,58 @@ export function createPanesRuntime(deps: PanesRuntimeDeps): PanesOperations {
 		return { status: "watching", runId: match.runId, agentId: match.agentId, opened: watched.opened };
 	};
 
+	/**
+	 * The files pane's open half, shared by `/files`, `/panes open files`, the
+	 * keybinding, and the model tool. The settings gate and the missing-engine
+	 * message live here so every door says the same thing.
+	 */
+	const openFiles = async (once: boolean): Promise<Exclude<PanesFilesResult, { status: "closed" }>> => {
+		const preset = PANES_PRESETS[0];
+		if (!deps.getSettings().interface.panes.files.enabled) {
+			return { status: "refused", reason: "the files pane is disabled by interface.panes.files.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(once ? { once: true } : undefined);
+			if (result.status === "opened") {
+				return { status: "opened", paneId: result.paneId, existing: result.existing };
+			}
+			if (result.status === "missing-binary") {
+				return {
+					status: "missing-binary",
+					binary: result.binary,
+					installHint: preset.installHint,
+					// The engine's own resolution sentence, prefixed with the surface it
+					// serves: an operator who typed `/files` should not have to know the
+					// name of the program to read the answer.
+					detail: `the files pane engine is not available: ${result.detail}`,
+				};
+			}
+			return {
+				status: result.status === "profile-error" ? "refused" : "unavailable",
+				reason: result.reason,
+			};
+		} finally {
+			pendingOpens.delete(pendingId);
+		}
+	};
+
 	return {
+		async files(action): Promise<PanesFilesResult> {
+			if (action === "close") {
+				await yaziController?.close();
+				return { status: "closed" };
+			}
+			if (action === "toggle" && yaziController?.isOpen()) {
+				await yaziController.close();
+				return { status: "closed" };
+			}
+			return openFiles(action === "pick");
+		},
+
 		status(): PanesStatus {
 			const detection = deps.mux.detection();
 			const settings = deps.getSettings();
@@ -201,41 +284,31 @@ export function createPanesRuntime(deps: PanesRuntimeDeps): PanesOperations {
 		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);
+				const presetId = resolvePanesPresetId(request.preset);
+				const preset = presetId === null ? undefined : PANES_PRESETS.find((entry) => entry.id === presetId);
 				if (!preset) {
 					return { status: "refused", reason: `unknown preset: ${request.preset}` };
 				}
-				if (preset.id === "yazi") {
-					if (!deps.getSettings().interface.panes.files.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" };
+				if (preset.id === "files") {
+					const result = await openFiles(request.once === true);
+					if (result.status === "opened") {
+						return { status: "opened", label: preset.id, paneId: result.paneId, existing: result.existing };
 					}
-					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 (result.status === "missing-binary") {
+						return { ...result, preset: preset.id };
 					}
+					return result;
+				}
+				if (!deps.mux.available()) return { status: "unavailable", reason: unavailableReason(deps.mux) };
+				// One pane per preset. A second `/panes open shell` is a request to
+				// see the shell that is already there, not to split the screen again;
+				// the pane host is asked for focus so the operator lands in it.
+				const live = deps.mux.list().find((record) => record.purpose === "utility" && record.label === preset.id);
+				if (live) {
+					await deps.mux.unzoomSelf();
+					await deps.mux.focusPane(live.ref.paneId);
+					return { status: "opened", label: preset.id, paneId: live.ref.paneId, existing: true };
 				}
-				if (!deps.mux.available()) return { status: "unavailable", reason: UNAVAILABLE };
 				const binaryPath = probe(preset.binary);
 				if (binaryPath === null) {
 					return {
@@ -248,7 +321,10 @@ export function createPanesRuntime(deps: PanesRuntimeDeps): PanesOperations {
 				}
 				const argv = presetArgv(preset.id, binaryPath);
 				if (argv === null) {
-					return { status: "refused", reason: `preset ${preset.id} has nothing to show yet` };
+					return {
+						status: "refused",
+						reason: `no dispatched run has written a journal under ${journalRoot()} yet; the logs pane follows the newest run once one starts`,
+					};
 				}
 				const pendingId = beginPendingOpen(preset.id);
 				try {
@@ -259,7 +335,7 @@ export function createPanesRuntime(deps: PanesRuntimeDeps): PanesOperations {
 					pendingOpens.delete(pendingId);
 				}
 			}
-			if (!deps.mux.available()) return { status: "unavailable", reason: UNAVAILABLE };
+			if (!deps.mux.available()) return { status: "unavailable", reason: unavailableReason(deps.mux) };
 			const argv = request.argv ?? [];
 			if (argv.length === 0) return { status: "refused", reason: "nothing to run" };
 			const label = argv[0] ?? "pane";
@@ -274,7 +350,7 @@ export function createPanesRuntime(deps: PanesRuntimeDeps): PanesOperations {
 		},
 
 		async zoom(target: string): Promise<PanesZoomResult> {
-			if (!deps.mux.available()) return { status: "unavailable", reason: UNAVAILABLE };
+			if (!deps.mux.available()) return { status: "unavailable", reason: unavailableReason(deps.mux) };
 			const match = matchOwnedPane(deps.mux.list(), target.trim().length === 0 ? "watch" : target);
 			if (!match) return { status: "not-found", target: target.trim().length === 0 ? "watch" : target };
 			const changed = await deps.mux.zoomPane(match.ref.paneId, "toggle");
@@ -285,7 +361,7 @@ export function createPanesRuntime(deps: PanesRuntimeDeps): PanesOperations {
 		},
 
 		async close(target: string): Promise<PanesCloseResult> {
-			if (!deps.mux.available()) return { status: "unavailable", reason: UNAVAILABLE };
+			if (!deps.mux.available()) return { status: "unavailable", reason: unavailableReason(deps.mux) };
 			const owned = deps.mux.list();
 			if (target === "all") {
 				const labels: string[] = [];