@iowarp/clio-coder 0.3.9 → 0.4.0

package/src/engine/claude/sdk-module.ts

@@ -0,0 +1,98 @@
+/**
+ * Lazy loader for the optional `@anthropic-ai/claude-agent-sdk` package.
+ *
+ * The SDK's platform package ships a 224MB proprietary binary, so it lives in
+ * `optionalDependencies` and a default install skips it under
+ * `npm install --omit=optional`. Nothing may import it at module scope: boot,
+ * `doctor`, and every non-Claude runtime have to work on an install that never
+ * fetched it. The one value the runtime needs (`query`) is reached through the
+ * dynamic import below, at the moment a `claude-sdk` run actually starts, and a
+ * missing package surfaces as a typed error naming the package and the install
+ * command instead of an ESM resolution stack.
+ */
+import type { query } from "@anthropic-ai/claude-agent-sdk";
+
+/** The optional package this module resolves. */
+export const CLAUDE_AGENT_SDK_PACKAGE = "@anthropic-ai/claude-agent-sdk";
+
+/**
+ * Version the checkout pins in `optionalDependencies`. A contract test keeps
+ * the two in step so the install command quoted in the diagnostic never drifts
+ * from the version the runtime was built against.
+ */
+export const CLAUDE_AGENT_SDK_VERSION = "0.3.186";
+
+/** Exact command an operator can paste to make the Claude SDK runtime usable. */
+export const CLAUDE_AGENT_SDK_INSTALL_COMMAND = `npm install ${CLAUDE_AGENT_SDK_PACKAGE}@${CLAUDE_AGENT_SDK_VERSION}`;
+
+/** The slice of the SDK surface the worker runtime calls. */
+export interface ClaudeAgentSdkModule {
+	query: typeof query;
+}
+
+/** Thrown when a `claude-sdk` run starts on an install that omitted the optional package. */
+export class ClaudeAgentSdkUnavailableError extends Error {
+	readonly code = "CLAUDE_AGENT_SDK_UNAVAILABLE";
+	readonly packageName = CLAUDE_AGENT_SDK_PACKAGE;
+	readonly installCommand = CLAUDE_AGENT_SDK_INSTALL_COMMAND;
+
+	constructor(cause?: unknown) {
+		super(
+			`The claude-sdk runtime needs the optional package ${CLAUDE_AGENT_SDK_PACKAGE}, which is not installed. ` +
+				`Install it with \`${CLAUDE_AGENT_SDK_INSTALL_COMMAND}\` (or reinstall clio-coder without \`--omit=optional\`), ` +
+				`then select the target again. Every other runtime works without it.`,
+			cause === undefined ? undefined : { cause },
+		);
+		this.name = "ClaudeAgentSdkUnavailableError";
+	}
+}
+
+/** Resolution failures that mean "the package is not on disk" rather than "the package is broken". */
+const MISSING_MODULE_CODES: ReadonlySet<string> = new Set([
+	"ERR_MODULE_NOT_FOUND",
+	"MODULE_NOT_FOUND",
+	"ERR_PACKAGE_PATH_NOT_EXPORTED",
+]);
+
+function isMissingModuleError(error: unknown): boolean {
+	const code = (error as { code?: unknown } | null)?.code;
+	return typeof code === "string" && MISSING_MODULE_CODES.has(code);
+}
+
+export type ClaudeAgentSdkLoader = () => Promise<ClaudeAgentSdkModule>;
+
+// The literal specifier is what keeps the SDK's types available here; the tsup
+// `external` entry keeps esbuild from bundling it and leaves this as a real
+// runtime `import()`.
+const realLoader: ClaudeAgentSdkLoader = async () => await import("@anthropic-ai/claude-agent-sdk");
+
+let loader: ClaudeAgentSdkLoader = realLoader;
+let cached: ClaudeAgentSdkModule | null = null;
+
+/**
+ * Swap the import used by {@link loadClaudeAgentSdk}. The absence of a 224MB
+ * optional package cannot be staged inside a normal test process, so the
+ * contract test intercepts the import here; passing `null` restores the real
+ * one and clears the cache.
+ */
+export function setClaudeAgentSdkLoader(next: ClaudeAgentSdkLoader | null): void {
+	loader = next ?? realLoader;
+	cached = null;
+}
+
+/**
+ * Resolve the SDK, or fail with {@link ClaudeAgentSdkUnavailableError}. A load
+ * error that is not a resolution failure (a broken install, a throwing module
+ * top level) propagates unchanged, so a real fault is never mislabeled as an
+ * absent package.
+ */
+export async function loadClaudeAgentSdk(): Promise<ClaudeAgentSdkModule> {
+	if (cached) return cached;
+	try {
+		cached = await loader();
+		return cached;
+	} catch (error) {
+		if (isMissingModuleError(error)) throw new ClaudeAgentSdkUnavailableError(error);
+		throw error;
+	}
+}

package/src/engine/claude/sdk-runtime.ts

@@ -1,15 +1,18 @@
-import {
-	type CanUseTool,
-	type EffortLevel,
-	type HookCallback,
-	type Options,
-	type PermissionMode,
-	type PermissionResult,
+// Types only. `@anthropic-ai/claude-agent-sdk` is an optional dependency, so
+// nothing here may reach it at module scope; the one value this runtime calls
+// (`query`) comes from the lazy loader in ./sdk-module.js at run time.
+import type {
+	CanUseTool,
+	EffortLevel,
+	HookCallback,
+	Options,
+	PermissionMode,
+	PermissionResult,
 	query,
-	type SDKMessage,
-	type SDKResultMessage,
-	type SDKUserMessage,
-	type ThinkingConfig,
+	SDKMessage,
+	SDKResultMessage,
+	SDKUserMessage,
+	ThinkingConfig,
 } from "@anthropic-ai/claude-agent-sdk";
 
 import { readClioVersion } from "../../core/package-root.js";
@@ -19,6 +22,7 @@ import { isReserveAdmittedTool, resolveDeliveryTools } from "../loop-guard.js";
 import type { AgentEvent, AgentMessage, Usage } from "../types.js";
 import type { WorkerEventEmit, WorkerRunHandle, WorkerRunInput, WorkerRunResult } from "../worker-runtime.js";
 import { createWorkerSafety } from "../worker-tools.js";
+import { loadClaudeAgentSdk } from "./sdk-module.js";
 import { isClaudeCodeSessionId } from "./session-id.js";
 import {
 	type ClaudeToolPermissionDecision,
@@ -607,6 +611,10 @@ export function startClaudeSdkWorkerRun(input: WorkerRunInput, emit: WorkerEvent
 
 		emit({ type: "agent_start" } as AgentEvent);
 		try {
+			// First touch of the optional SDK. An install that omitted it fails
+			// here with a typed diagnostic naming the package and the install
+			// command, and lands in the catch below as an ordinary run failure.
+			const { query } = await loadClaudeAgentSdk();
 			queryHandle = query({ prompt: buildClaudeSdkPrompt(input), options });
 			for await (const sdkMessage of queryHandle) {
 				if (sdkMessage.type === "system" && (sdkMessage as { subtype?: string }).subtype === "init") {

package/src/engine/tui-primitives.ts

@@ -0,0 +1,21 @@
+/**
+ * The terminal-engine primitives a non-interactive surface needs, kept in a
+ * module of its own rather than behind ./tui.js.
+ *
+ * ./tui.js is the interactive layer's barrel: it carries the instrumented
+ * renderer and SelectList, and every consumer of it also pulls the interactive
+ * theme. A CLI command that only measures text and paints an alternate screen
+ * needs none of that, and reaching it through the barrel is not free. An edge
+ * from outside src/interactive/ to ./tui.js, static or dynamic, gives that
+ * module a reachability set the theme modules do not share, so the bundler
+ * peels it into a chunk of its own. That chunk lands in the Stage 0 instant
+ * shell closure, which tests/contracts/instant-shell-import-graph.test.ts holds
+ * to six chunks. Everything re-exported here is a pass-through to the external
+ * terminal engine, which is not bundled and so adds no chunk at all.
+ *
+ * The engine-boundary rule (rule1 in tests/boundaries/check-boundaries.ts) keeps
+ * terminal-engine value imports inside src/engine/, which is why this seam lives
+ * here and not in src/cli/.
+ */
+
+export { ProcessTerminal, TuiAltScreen, truncateToWidth } from "@earendil-works/pi-tui";

package/src/engine/tui.ts

@@ -18,6 +18,7 @@ export type {
 	MarkdownTheme,
 	OverlayHandle,
 	OverlayOptions,
+	OverlayUnfocusOptions,
 	ScrollViewScrollbar,
 	SelectItem,
 	SelectListLayoutOptions,

package/src/engine/worker-runtime.ts

@@ -9,7 +9,6 @@
  * own worker runners before pi-agent model synthesis.
  */
 
-import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { validateSettingsFile } from "../core/config.js";
 import {
@@ -29,6 +28,7 @@ import {
 	resultContractRepairMessages,
 	validateResultContract,
 } from "../domains/agents/result-contract.js";
+import { nodeResultContractFilesystem } from "../domains/agents/result-contract-filesystem.js";
 import type { AgentProduct } from "../domains/agents/spec.js";
 import type { MiddlewareSnapshot } from "../domains/middleware/index.js";
 import { createMiddlewareToolChoiceControl } from "../domains/middleware/index.js";
@@ -258,18 +258,7 @@ function terminalContractViolation(
 		// Repair rounds judge shape and grounding only. Network posture belongs to
 		// the orchestrator's sealed validation, which runs again on the receipt.
 		networkAllowed: true,
-		filesystem: {
-			readFile(filePath) {
-				try {
-					return readFileSync(filePath, "utf8");
-				} catch {
-					return null;
-				}
-			},
-			pathExists(filePath) {
-				return existsSync(filePath);
-			},
-		},
+		filesystem: nodeResultContractFilesystem(),
 	});
 	return validation.conformance === "pass" ? null : (validation.reason ?? "invalid result");
 }

package/src/entry/boot-options.ts

@@ -26,6 +26,8 @@ export interface BootOptions {
 	terminalLease?: TerminalLease;
 	/** Strict effective settings snapshot shared by preflight, Stage 0, and hydration. */
 	startupSettings?: Readonly<ClioSettings>;
+	/** `--with-panes` / `--no-panes`. The flag beats `panes.enabled` in both directions. */
+	panes?: "with" | "without";
 	headless?: {
 		prompt: string;
 		images?: ReadonlyArray<ImageContent>;

package/src/entry/orchestrator.ts

@@ -49,6 +49,7 @@ import { createDispatchDedupRegistration } from "../domains/dispatch/dedup.js";
 import { agentRoleFactsResolver } from "../domains/dispatch/execution-role.js";
 import { readGateDecisionArtifacts, readPendingGateDecisions } from "../domains/dispatch/gate-decisions.js";
 import { createDispatchDomainModule } from "../domains/dispatch/index.js";
+import { configureRunEventJournal } from "../domains/dispatch/run-event-journal.js";
 import { type ExtensionsContract, ExtensionsDomainModule } from "../domains/extensions/index.js";
 import { type InteropContract, InteropDomainModule } from "../domains/interop/index.js";
 import {
@@ -97,6 +98,7 @@ import { announceMemoryStepEndpoint } from "../domains/middleware/memory-step-en
 import { createTaskBoardReminderRegistration } from "../domains/middleware/task-board-reminder.js";
 import { createTaskNudgeRegistration } from "../domains/middleware/task-nudge.js";
 import { createWatchdogRegistration } from "../domains/middleware/watchdog.js";
+import type { MuxContract } from "../domains/mux/index.js";
 import type { ObservabilityContract } from "../domains/observability/index.js";
 import { ObservabilityDomainModule, recordBackgroundMemoryStep } from "../domains/observability/index.js";
 import type { PromptsContract } from "../domains/prompts/contract.js";
@@ -120,6 +122,7 @@ import {
 	targetRequiresAuth,
 	VALID_THINKING_LEVELS,
 } from "../domains/providers/index.js";
+import { memoryInterventionModelMaxTokens } from "../domains/providers/model-runtime-capabilities.js";
 import { getRuntimeRegistry } from "../domains/providers/registry.js";
 import { registerBuiltinRuntimes } from "../domains/providers/runtimes/builtins.js";
 import {
@@ -159,6 +162,7 @@ import {
 import { createTaskBoardStore } from "../domains/session/task-board.js";
 import { filterEntriesToActivePath } from "../domains/session/tree/active-path.js";
 import { type ShareContract, ShareDomainModule } from "../domains/share/index.js";
+import { ToolchainDomainModule } from "../domains/toolchain/index.js";
 import { createUserTasksStore } from "../domains/user-tasks/store.js";
 import { type AcpSafeSettingsPatch, type AcpSafeSettingsSnapshot, serveClioAcpAgent } from "../engine/acp/server.js";
 import { createStdioServerTransport } from "../engine/acp/transport.js";
@@ -175,6 +179,7 @@ import { createChatLoop } from "../interactive/chat-loop.js";
 import { type RunIo, startInteractive } from "../interactive/index.js";
 import { buildModelReplayAgentMessagesFromTurns } from "../interactive/model-session-replay.js";
 import type { BootOptions } from "./boot-options.js";
+import { resolvePanesEnablement } from "./panes-activation.js";
 
 export type { BootOptions, HeadlessSamplingOverrides } from "./boot-options.js";
 
@@ -333,6 +338,7 @@ interface BackgroundMemoryRoute {
 	targetId: string;
 	wireModelId: string;
 	endpointKey: string | null;
+	modelMaxTokens(configuredMaxTokens: number): number;
 }
 
 function createBackgroundMemoryModelClient(
@@ -375,6 +381,12 @@ function createBackgroundMemoryModelClient(
 		targetId,
 		wireModelId: refined.wireModelId,
 		endpointKey,
+		modelMaxTokens: (configuredMaxTokens) =>
+			memoryInterventionModelMaxTokens({
+				configuredMaxTokens,
+				thinkingMechanism: refined.modelRuntime.thinking.mechanism,
+				modelMaxTokens: refined.capabilityDecisions.maxTokens,
+			}),
 		client: {
 			// Wrapped at the layer that knows a request left the process: the step
 			// holds endpoint capacity while it is out and publishes the cache
@@ -844,6 +856,19 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 	let effectiveSettingsForDispatch: (() => Readonly<ClioSettings>) | null = null;
 	let protectedArtifactStateForDispatch: (() => ProtectedArtifactState) | null = null;
 
+	// Panes are an interactive-surface projection. Headless, ACP, and worker boots
+	// gate detection off so they never resolve a socket path or open a descriptor.
+	// This mirrors the `interactive` predicate computed after the domains load.
+	const muxInteractive = !options.headless && options.acp === undefined && process.env.CLIO_CODER_INTERACTIVE === "1";
+	// The rung is settled before the config contract loads, off the settings the
+	// interactive entry point already read strictly (`src/cli/clio.ts:31`) and
+	// the `--with-panes` / `--no-panes` flag, which wins in both directions. This
+	// is why `panes.enabled` is a restart-scoped row: the decision runs once,
+	// here. An inactive rung loads nothing: the whole extension, mux domain
+	// included, lives behind the dynamic import below.
+	const muxEnablement = resolvePanesEnablement(options.panes, options.startupSettings?.panes.enabled);
+	const withPanes = muxInteractive && muxEnablement !== "off" ? await import("./with-panes.js") : null;
+
 	const result = await loadDomains(
 		[
 			options.startupSettings ? createConfigDomainModule(options.startupSettings) : ConfigDomainModule,
@@ -863,6 +888,7 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 			ShareDomainModule,
 			createContextDomainModule({ noContextFiles: options.noContextFiles === true }),
 			ProvidersDomainModule,
+			ToolchainDomainModule,
 			SafetyDomainModule,
 			createPromptsDomainModule({
 				noContextFiles: options.noContextFiles === true,
@@ -872,6 +898,16 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 			SessionDomainModule,
 			ObservabilityDomainModule,
 			SchedulingDomainModule,
+			...(withPanes
+				? [
+						withPanes.createMuxDomainModule({
+							enabled: muxEnablement,
+							log: (level, message) => {
+								if (level === "warning") bootStderr(`[mux] ${message}\n`);
+							},
+						}),
+					]
+				: []),
 			// Dispatch resolves worker targets through the session's effective
 			// settings view once it exists (assigned below, after the config
 			// contract loads); until then it falls back to the shared snapshot.
@@ -879,6 +915,11 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 				getSettings: () => effectiveSettingsForDispatch?.(),
 				getProtectedArtifactState: () => protectedArtifactStateForDispatch?.() ?? { artifacts: [] },
 				autonomyOverride: options.headless?.autonomy !== undefined,
+				// The domain owns the durable journal here, not the dispatch
+				// tool's event registry: `/run`, a watchdog run, and a model
+				// dispatch all have to leave the same transcript behind, and only
+				// the last of the three ever reaches that registry.
+				journalRunEvents: true,
 			}),
 			LifecycleDomainModule,
 		],
@@ -941,6 +982,7 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 	const resources = result.getContract<ResourcesContract>("resources");
 	const extensions = result.getContract<ExtensionsContract>("extensions");
 	const share = result.getContract<ShareContract>("share");
+	const mux = result.getContract<MuxContract>("mux");
 	const contextDomain = result.getContract<ContextContract>("context");
 	const interop = result.getContract<InteropContract>("interop");
 	// Boot detection resolves paths only: no `--version` subprocess and no skill
@@ -1041,7 +1083,13 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 	// Guardrail policy (tool-call budgets, tool byte caps, dispatch ledger cap)
 	// resolves settings-first with env as emergency override; install the
 	// settings section before any guard registration or tool reads it.
-	configureGuardrails((config?.get() ?? readSettings()).guardrails);
+	const resolvedSettings = config?.get() ?? readSettings();
+	configureGuardrails(resolvedSettings.guardrails);
+
+	// The run event journal resolves the same way for the same reason: the sink
+	// sits on the dispatch event path, where reading settings.yaml would be both
+	// a cost and a throw site, so the composition root installs the value once.
+	configureRunEventJournal(resolvedSettings.panes.journal);
 
 	// Guard registrations on the middleware contract, in order: loop guard,
 	// protected artifacts (last among guards so it absorbs protect_path effects
@@ -1214,6 +1262,8 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 					: createBackgroundMemoryModelClient(providers, settings, settings.memory.intervention.timeoutMs, bus);
 			return backgroundMemoryRoute?.client ?? null;
 		},
+		getModelMaxTokens: (configuredMaxTokens) =>
+			backgroundMemoryRoute?.modelMaxTokens(configuredMaxTokens) ?? configuredMaxTokens,
 		// A single-slot local server serves one request at a time, so a memory step
 		// started while the operator's turn is streaming either waits behind it or
 		// makes the server swap the resident model out to answer. The chat loop
@@ -1374,6 +1424,19 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 	// Operator-initiated backgrounding is a TUI affordance: the registry is the
 	// one object the dispatch tool and the keypress both hold.
 	const dispatchBackground = createDispatchBackgroundRegistry();
+	// One `PanesOperations` instance drives both the `panes` tool and the
+	// `/panes` slash command, so the model and the operator cannot be told
+	// different things about the same pane. It also owns the no-mux Yazi chooser,
+	// while model tool registration below remains gated on a live pane host.
+	const panes =
+		withPanes && mux
+			? withPanes.createPanesRuntime({
+					mux,
+					getSettings: () => getCurrentSettings(),
+					getDispatchSnapshot: () => dispatch.snapshot(),
+					getCwd: () => process.cwd(),
+				})
+			: null;
 	registerAllTools(toolRegistry, {
 		...(session
 			? {
@@ -1397,6 +1460,11 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 		// provenance and compete winner handling agree with the approval surface.
 		getAutonomy: resolveEffectiveAutonomy,
 		...(interactive ? { dispatchBackground } : {}),
+		...(mux ? { competeMuxWorktrees: mux } : {}),
+		// Registered only when a pane host answered detection, so the tool is
+		// absent from the prompt on a machine with none rather than present and
+		// always refusing.
+		...(panes && mux?.mode !== "none" ? { panes } : {}),
 		getCostCeilingUsd: () => result.getContract<SchedulingContract>("scheduling")?.ceilingUsd() ?? 0,
 		...(config ? { getWorkerRosters: () => config.get().workers.rosters } : {}),
 		getSkillLoaderOptions: () => ({
@@ -1542,6 +1610,20 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 			mutateSaved?.(saved);
 		});
 	};
+	/**
+	 * A routing change at the scope the operator chose. "session" moves the live
+	 * route and leaves settings.yaml alone, so a swap that points at a dead
+	 * endpoint dies with the session that made it; "global" is the historical
+	 * write-through. Nothing on this path writes durably without a scope.
+	 */
+	const applyRoutingAtScope = (patch: RoutingPatch, scope: "session" | "global"): void => {
+		if (scope === "global") {
+			updateSessionRouting(patch);
+			return;
+		}
+		applyRoutingPatch(sessionRouting, patch);
+		bumpSessionState();
+	};
 	const readAcpSafeSettings = (): AcpSafeSettingsSnapshot => {
 		const settings = getCurrentSettings();
 		return {
@@ -2014,6 +2096,20 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 		...(extensions ? { extensions } : {}),
 		...(interop ? { interop } : {}),
 		...(share ? { share } : {}),
+		...(mux ? { mux } : {}),
+		...(panes ? { panes } : {}),
+		...(panes ? { attachYaziBridge: (bridge) => panes.attachYazi(bridge) } : {}),
+		// The interactive surface never imports the panes glue itself; the
+		// factories arrive only on an active boot, through the same dynamic
+		// import that loaded the mux domain.
+		...(withPanes
+			? {
+					createMuxBridge: withPanes.createMuxBridge,
+					createYaziBridge: withPanes.createYaziBridge,
+					createWatchPane: withPanes.createWatchPaneController,
+				}
+			: {}),
+		...(panes ? { attachWatchPane: (controller) => panes.attachWatch(controller) } : {}),
 		toolRegistry,
 		...(session ? { session } : {}),
 		...(session ? { readSessionEntries: readCurrentSessionEntries } : {}),
@@ -2126,7 +2222,7 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 					},
 				}
 			: {}),
-		onSetThinkingLevel: (level) => {
+		onSetThinkingLevel: (level, scope) => {
 			const current = getCurrentSettings();
 			const nextLevel =
 				resolveModelRuntimeCapabilitiesForProviders(
@@ -2135,7 +2231,7 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 					current.orchestrator.model,
 					level,
 				)?.thinking.effectiveLevel ?? "off";
-			updateSessionRouting({ orchestrator: { thinkingLevel: nextLevel } });
+			applyRoutingAtScope({ orchestrator: { thinkingLevel: nextLevel } }, scope ?? "global");
 		},
 		onCycleThinking: () => {
 			const current = getCurrentSettings();
@@ -2152,7 +2248,7 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 			);
 			updateSessionRouting({ orchestrator: { thinkingLevel: nextLevel } });
 		},
-		onSelectModel: ({ target, model }) => {
+		onSelectModel: ({ target, model }, scope) => {
 			const registry = getRuntimeRegistry();
 			const settings = getCurrentSettings();
 			const descriptor = settings.targets.find((e) => e.id === target);
@@ -2169,7 +2265,9 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 					);
 				}
 			}
-			updateSessionRouting({ orchestrator: { target, model } });
+			applyRoutingAtScope({ orchestrator: { target, model } }, scope);
+			// Recents live in the state dir, not settings.yaml, and are how a swap
+			// stays reachable in the picker. A session-scoped swap still earns one.
 			rememberRecentModel(`${target}/${model}`, getCurrentSettings().modelSelector.recentLimit);
 		},
 		writeSettings: (next) => applySettingsBlob(next),

package/src/entry/panes-activation.ts

@@ -0,0 +1,31 @@
+/**
+ * Whether this boot activates the panes extension.
+ *
+ * The decision is made here, before any panes module loads, because the whole
+ * point of the activation model is that a plain boot never pays for the
+ * extension: no socket probe, no guest-mode detection, and none of the mux
+ * domain's code in the import closure. The orchestrator dynamically imports
+ * `src/entry/with-panes.ts` only when this resolves to an active rung, and a
+ * built-graph contract test (tests/contracts/instant-shell-import-graph.test.ts)
+ * pins that the default boot chunk carries no mux domain code.
+ *
+ * Precedence: the command-line flag wins in both directions, then the
+ * `panes.enabled` setting, then the shipped default of `off`.
+ */
+
+/** Mirrors `MuxEnablement` in src/domains/mux/detect.ts without importing it. */
+export type PanesEnablement = "auto" | "embedded" | "off";
+
+export function resolvePanesEnablement(
+	flag: "with" | "without" | undefined,
+	setting: PanesEnablement | undefined,
+): PanesEnablement {
+	if (flag === "without") return "off";
+	if (flag === "with") {
+		// `--with-panes` on a settings file that names `embedded` honors the
+		// stronger setting; on `off` or absent settings it activates guest
+		// detection, which is the flag's promise.
+		return setting === "embedded" ? "embedded" : "auto";
+	}
+	return setting ?? "off";
+}

package/src/entry/with-panes.ts

@@ -0,0 +1,20 @@
+/**
+ * The panes extension's composition surface.
+ *
+ * This is the one module that statically imports panes-only code: the mux
+ * domain (socket client, contract, yazi session machinery) and the interactive
+ * glue built on it. The orchestrator imports it dynamically, and only when
+ * `resolvePanesEnablement` (src/entry/panes-activation.ts) says the extension
+ * is active, so a plain `clio-coder` boot never loads any of it. The built
+ * import graph is pinned by tests/contracts/instant-shell-import-graph.test.ts:
+ * the default boot chunk must carry no mux domain code.
+ *
+ * Everything re-exported here is a value the orchestrator wires; types cross
+ * the seam as type-only imports at the call sites and cost nothing.
+ */
+
+export { createMuxDomainModule } from "../domains/mux/index.js";
+export { createMuxBridge } from "../interactive/mux-bridge.js";
+export { createPanesRuntime } from "../interactive/panes-runtime.js";
+export { createWatchPaneController } from "../interactive/watch-pane.js";
+export { createYaziBridge } from "../interactive/yazi-bridge.js";

package/src/interactive/context-overlay.ts

@@ -330,6 +330,7 @@ export function openContextOverlay(
 	const handle = showClioOverlayFrame(tui, text, {
 		anchor: "center",
 		width: CONTEXT_OVERLAY_WIDTH,
+		markerId: "context-view",
 		title: "Context Window",
 		footerHint: buildHint([]),
 	});

package/src/interactive/cost-overlay.ts

@@ -374,6 +374,8 @@ export function openCostOverlay(
 	const handle = showClioOverlayFrame(tui, body, {
 		anchor: "center",
 		width: COST_OVERLAY_WIDTH,
+		// Not derived from the title: that one carries the session id.
+		markerId: "cost",
 		title: sessionId && sessionId.length > 0 ? `Session usage (${sessionId})` : "Session usage",
 		footerHint: buildHint([]),
 	});

package/src/interactive/council-grid.ts

@@ -14,6 +14,7 @@
  */
 
 import { truncateToWidth, wrapTextWithAnsi } from "../engine/tui.js";
+import { COUNCIL_SYNTHESIS_LABEL } from "./council.js";
 import {
 	type ClioTheme,
 	type ClioToken,
@@ -38,9 +39,6 @@ export const COUNCIL_COLUMN_GUTTER = 2;
 /** Rows of a member's bounded answer tail a column shows before it defers to `/view`. */
 export const COUNCIL_ANSWER_ROWS = 4;
 
-/** The label the coordinator gives the synthesis run of every council group. */
-export const COUNCIL_SYNTHESIS_LABEL = "synthesis";
-
 /** One council run as the board draws it: the roster facts plus the run's presentation. */
 export interface CouncilMemberView {
 	runId: string;

package/src/interactive/council.ts

@@ -26,6 +26,17 @@ export type CouncilSynthesisMode = (typeof COUNCIL_SYNTHESIS_MODES)[number];
 /** Rounds the dispatch tool admits. The command enforces the same bound where the operator typed it. */
 export const COUNCIL_MAX_ROUNDS = 3;
 
+/**
+ * The label the coordinator gives the synthesis run of every council group.
+ *
+ * It lives here rather than beside the board layout that draws it because it is
+ * council vocabulary, not presentation: the share path compares against it to
+ * decide whether a run seals the whole council or one voice, and that path must
+ * stay off the render module graph. See the header of
+ * `src/interactive/slash-commands.ts` for the closure budget that depends on it.
+ */
+export const COUNCIL_SYNTHESIS_LABEL = "synthesis";
+
 export function isCouncilSynthesisMode(value: string): value is CouncilSynthesisMode {
 	return COUNCIL_SYNTHESIS_MODES.some((mode) => mode === value);
 }