@iowarp/clio-coder 0.3.8 → 0.4.0

package/src/engine/provider-payload.ts

@@ -1,4 +1,4 @@
-import { RESPONSE_SCHEMA_RUNTIME_ID } from "../core/response-schema.js";
+import { RESPONSE_SCHEMA_RUNTIME_ID, type ResponseSchemaDialect } from "../core/response-schema.js";
 import type { ThinkingLevel } from "../domains/providers/index.js";
 import type { EngineModel } from "./types.js";
 
@@ -217,6 +217,34 @@ function patchLlamaCppResponseSchemaPayload(
 	};
 }
 
+/**
+ * Apply a JSON-schema response constraint in the dialect the runtime takes.
+ *
+ * Unlike the worker patcher above, this one is for a seam that treats native
+ * enforcement as an optimization: the caller looks the dialect up first and
+ * simply does not call this when there is none, so an unconstrained request
+ * still goes out and the prompt-level instruction carries it (issue #223).
+ * Returns undefined when the payload is not an object, which leaves it alone.
+ */
+export function patchResponseSchemaPayloadForDialect(
+	payload: unknown,
+	dialect: ResponseSchemaDialect,
+	responseSchema: Record<string, unknown>,
+	schemaName: string,
+): unknown | undefined {
+	if (!isRecord(payload)) return undefined;
+	if (dialect === "llamacpp-json-object") {
+		return { ...payload, response_format: { type: "json_object", schema: responseSchema } };
+	}
+	return {
+		...payload,
+		response_format: {
+			type: "json_schema",
+			json_schema: { name: schemaName, strict: true, schema: responseSchema },
+		},
+	};
+}
+
 export interface WorkerPayloadPatchOptions {
 	runtimeId: string;
 	thinkingLevel?: ThinkingLevel;

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

@@ -8,6 +8,7 @@ import { installBusTracer } from "../core/bus-trace.js";
 import { type ClioSettings, readSettings, type SettingsMutator, updateSettings } from "../core/config.js";
 import { DEFAULT_DELEGATION_PERMISSION_TIMEOUT_MS } from "../core/defaults.js";
 import { loadDomains } from "../core/domain-loader.js";
+import type { SafeEventBus } from "../core/event-bus.js";
 import { expandInlineFileReferencesAsync } from "../core/file-references.js";
 import { setGitCommitAttributionEnabled } from "../core/git-commit-attribution.js";
 import { configureGuardrails } from "../core/guardrails.js";
@@ -48,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 {
@@ -63,9 +65,13 @@ import {
 	createTaskMemoryTelemetrySink,
 	createTaskMemoryTrace,
 	loadMemoryRecordsSync,
+	proposeInjectedTaskMemory,
+	readTaskMemorySpendSummary,
 	renderTaskMemoryHandoffSource,
 	seedTaskMemoryFromNewestHandoff,
+	type TaskMemoryEntry,
 	type TaskMemoryModelClient,
+	type TaskMemoryStepUsage,
 	taskMemoryBankSize,
 	taskMemoryHandoffSeedOffer,
 	taskMemoryTracePath,
@@ -88,21 +94,27 @@ import {
 	writeMiddlewareDiagnosticToStderr,
 } from "../domains/middleware/index.js";
 import { createMemoryInterventionRegistration } from "../domains/middleware/memory-intervention.js";
+import { announceMemoryStepEndpoint } from "../domains/middleware/memory-step-endpoint.js";
 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 } from "../domains/observability/index.js";
+import { ObservabilityDomainModule, recordBackgroundMemoryStep } from "../domains/observability/index.js";
 import type { PromptsContract } from "../domains/prompts/contract.js";
 import { createPromptsDomainModule } from "../domains/prompts/index.js";
 import type { ProvidersContract, TargetDescriptor, ThinkingLevel } from "../domains/providers/index.js";
 import {
 	AGENT_ROLE_TOOLS_REQUIRED_REASON,
 	applyModelCapabilityPatch,
+	canonicalEndpointKey,
 	firstRuntimeResolutionError,
+	foregroundStreamUsage,
 	isOrchestratorEligibleRuntime,
+	normalizeCostProvenance,
 	ProvidersDomainModule,
 	refineRuntimeTargetWithModelHints,
+	registerForegroundStream,
 	resolveModelCapabilities,
 	resolveModelRuntimeCapabilitiesForProviders,
 	resolveRuntimeTarget,
@@ -110,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 {
@@ -149,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";
@@ -159,12 +173,13 @@ import {
 	INTERACTIVE_LOOP_BLOCK_BUDGET,
 	readOrchTurnToolCallBudget,
 } from "../engine/loop-guard.js";
-import { openSession, readSessionTailTurns, sessionCurrentPath, sessionPaths } from "../engine/session.js";
+import { cwdHash, openSession, readSessionTailTurns, sessionCurrentPath, sessionPaths } from "../engine/session.js";
 import type { EngineModel } from "../engine/types.js";
 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";
 
@@ -268,6 +283,7 @@ function applyHeadlessSettingsOverlay(
 interface CompactionResolution {
 	model: EngineModel;
 	targetId: string;
+	endpointKey: string | null;
 	apiKey?: string;
 }
 
@@ -310,11 +326,27 @@ export async function resolveApiKeyForTarget(
 	return resolved.apiKey;
 }
 
+/**
+ * The background memory role, resolved to the endpoint it would call.
+ *
+ * The endpoint key is what lets the middleware decline a step that would land
+ * on the same inference scheduler the chat target is streaming against (#229,
+ * #250), and it is the same key dispatch admission counts slots on.
+ */
+interface BackgroundMemoryRoute {
+	client: TaskMemoryModelClient;
+	targetId: string;
+	wireModelId: string;
+	endpointKey: string | null;
+	modelMaxTokens(configuredMaxTokens: number): number;
+}
+
 function createBackgroundMemoryModelClient(
 	providers: ProvidersContract,
 	settings: Readonly<ClioSettings>,
 	timeoutMs: number,
-): TaskMemoryModelClient | null {
+	bus: Pick<SafeEventBus, "emit"> | null,
+): BackgroundMemoryRoute | null {
 	const targetId = settings.background.target?.trim();
 	const wireModelId = settings.background.model?.trim();
 	if (!targetId || !wireModelId) return null;
@@ -343,24 +375,63 @@ function createBackgroundMemoryModelClient(
 	const model = resolved.target.runtime.synthesizeModel(resolved.target.target, resolved.target.wireModelId, kbHit);
 	const refined = refineRuntimeTargetWithModelHints(resolved.target, model, providers.knowledgeBase);
 	applyModelCapabilityPatch(model, refined.capabilities);
+	const costProvenance = normalizeCostProvenance(refined.costProvenance);
+	const endpointKey = canonicalEndpointKey(refined.target);
 	return {
-		async complete(request) {
-			const apiKey = targetRequiresAuth(refined.target, refined.runtime)
-				? (await providers.auth.resolveForTarget(refined.target, refined.runtime, { signal: request.signal })).apiKey
-				: LOCAL_API_KEY_FALLBACK;
-			return completeEngineText({
-				model,
-				systemPrompt: request.systemPrompt,
-				userPrompt: request.userPrompt,
-				maxTokens: request.maxTokens,
-				// Always off, never the operator's chat thinking level. A model that
-				// reasons anyway still works: `completeEngineText` keeps only text
-				// blocks, and the memory output budget leaves room for the preamble.
-				thinkingLevel: "off",
-				signal: request.signal,
-				timeoutMs,
-				...(apiKey === undefined ? {} : { apiKey }),
-			});
+		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
+			// disturbance even when a timeout means the usage sink never sees it.
+			complete: announceMemoryStepEndpoint({ bus, endpointKey, targetId }, async (request) => {
+				const apiKey = targetRequiresAuth(refined.target, refined.runtime)
+					? (await providers.auth.resolveForTarget(refined.target, refined.runtime, { signal: request.signal })).apiKey
+					: LOCAL_API_KEY_FALLBACK;
+				const startedAt = Date.now();
+				const completion = await completeEngineText({
+					model,
+					systemPrompt: request.systemPrompt,
+					userPrompt: request.userPrompt,
+					maxTokens: request.maxTokens,
+					// Always off, never the operator's chat thinking level. A model that
+					// reasons anyway still works: `completeEngineText` keeps only text
+					// blocks, and the memory output budget leaves room for the preamble.
+					thinkingLevel: "off",
+					signal: request.signal,
+					timeoutMs,
+					...(apiKey === undefined ? {} : { apiKey }),
+				});
+				// The step is billed here whatever the policy later decides about the
+				// answer. A model that read a trajectory and chose silence spent the
+				// same prefill as one that produced a reminder.
+				return {
+					text: completion.text,
+					inputTokens: completion.inputTokens,
+					outputTokens: completion.outputTokens,
+					usage: {
+						targetId,
+						attributedModelId: refined.wireModelId,
+						input: completion.usage.input,
+						output: completion.usage.output,
+						cacheRead: completion.usage.cacheRead,
+						cacheWrite: completion.usage.cacheWrite,
+						reasoning: completion.usage.reasoning,
+						totalTokens: completion.usage.totalTokens,
+						costUsd: completion.usage.costUsd,
+						costProvenance,
+						durationMs: Date.now() - startedAt,
+						backend: completion.backend,
+					},
+				};
+			}),
 		},
 	};
 }
@@ -463,7 +534,7 @@ async function resolveCompactionModel(
 	const model = synthesizeOrchestratorModel(providers, target, wireModelId);
 	if (!model) return null;
 	const apiKey = await resolveApiKeyForTarget(target, providers);
-	const resolution: CompactionResolution = { model, targetId };
+	const resolution: CompactionResolution = { model, targetId, endpointKey: canonicalEndpointKey(target) };
 	if (apiKey !== undefined) resolution.apiKey = apiKey;
 	return resolution;
 }
@@ -591,12 +662,21 @@ async function runCompactionFlow(
 	const entries = filterEntriesToActivePath(readSessionEntriesForCompact(meta.id), activeLeafTurnId);
 	if (entries.length === 0) return null;
 
-	const result = await compact({
-		entries,
-		model: resolved.model,
-		...(resolved.apiKey !== undefined ? { apiKey: resolved.apiKey } : {}),
-		...(instructions !== undefined ? { instructions } : {}),
-	});
+	// A compaction summary is a full streamed request against the chat target.
+	// Hold the same canonical endpoint slot as an ordinary turn, /btw round, or
+	// pre-warm so dispatch admission and background memory see its real usage.
+	const releaseEndpointSlot = resolved.endpointKey === null ? () => {} : registerForegroundStream(resolved.endpointKey);
+	let result: CompactResult;
+	try {
+		result = await compact({
+			entries,
+			model: resolved.model,
+			...(resolved.apiKey !== undefined ? { apiKey: resolved.apiKey } : {}),
+			...(instructions !== undefined ? { instructions } : {}),
+		});
+	} finally {
+		releaseEndpointSlot();
+	}
 	if (result.messagesSummarized === 0 || result.summary.length === 0) return null;
 
 	const entry: Omit<CompactionSummaryEntry, "turnId" | "timestamp"> = {
@@ -776,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,
@@ -795,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,
@@ -804,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.
@@ -811,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,
 		],
@@ -873,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
@@ -973,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
@@ -1079,6 +1195,53 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 	// telemetry row says which silence happened; this says what the model wrote.
 	const memoryTracePath = taskMemoryTracePath();
 	const memoryTrace = memoryTracePath === null ? null : createTaskMemoryTrace(memoryTracePath);
+	// The route the last resolved memory client would call, kept so the endpoint
+	// check and the cost row read the same resolution the step itself used.
+	let backgroundMemoryRoute: BackgroundMemoryRoute | null = null;
+	/**
+	 * Account for one background memory step exactly as a `/btw` side question is
+	 * accounted for: the in-process cost tracker under its own label so `/cost`
+	 * shows it while the session lives, and one durable out-of-turn row so
+	 * `clio-coder usage report` can still see it afterwards.
+	 *
+	 * Accounting only. The client wrapper (`announceMemoryStepEndpoint`) holds the
+	 * endpoint slot and publishes the disturbance; it sees the timed-out and
+	 * thrown steps this sink never hears about because their usage stays null.
+	 */
+	const recordBackgroundMemoryUsage = (usage: TaskMemoryStepUsage): void => {
+		const meta = session?.current() ?? null;
+		try {
+			recordBackgroundMemoryStep({
+				usage,
+				stateDir: clioStateDir(),
+				sessionId: meta?.id ?? null,
+				// The identity the session ledger is filed under, so `usage report
+				// --repo` selects these rows with the same hash it selects ledgers with.
+				repoIdentity: meta ? meta.cwdHash || cwdHash(meta.cwd || process.cwd()) : null,
+				...(observability === undefined ? {} : { observability }),
+			});
+		} catch {
+			// Accounting is bookkeeping. Its failure never reaches the memory step.
+		}
+	};
+	const proposeInjectedMemoryEntries = (entries: ReadonlyArray<TaskMemoryEntry>): void => {
+		const meta = session?.current() ?? null;
+		void proposeInjectedTaskMemory(clioDataDir(), {
+			sessionId: meta?.id ?? null,
+			cwd: meta?.cwd || process.cwd(),
+			entries,
+		})
+			.then((result) => {
+				for (const error of result.errors) {
+					process.stderr.write(`[clio:memory] proposed record not written for ${error}\n`);
+				}
+			})
+			.catch((error: unknown) => {
+				process.stderr.write(
+					`[clio:memory] proposed records not written: ${error instanceof Error ? error.message : String(error)}\n`,
+				);
+			});
+	};
 	const memoryIntervention = createMemoryInterventionRegistration({
 		bank: taskMemoryBank,
 		telemetry: createTaskMemoryTelemetrySink(),
@@ -1093,10 +1256,28 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 		},
 		getModelClient: () => {
 			const settings = effectiveSettingsForDispatch?.();
-			return settings === undefined
-				? null
-				: createBackgroundMemoryModelClient(providers, settings, settings.memory.intervention.timeoutMs);
+			backgroundMemoryRoute =
+				settings === undefined
+					? null
+					: 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
+		// registers its stream on the endpoint it streams against, so the two are
+		// compared by the same canonical key dispatch admission counts slots on.
+		backgroundEndpointBusy: () => {
+			const endpointKey = backgroundMemoryRoute?.endpointKey ?? null;
+			if (endpointKey === null) return false;
+			// This runs before the client wrapper registers the admitted step, so the
+			// count contains other requests only and the step cannot refuse itself.
+			return (foregroundStreamUsage()[endpointKey] ?? 0) > 0;
 		},
+		onStepUsage: (usage) => recordBackgroundMemoryUsage(usage),
+		onInjectedEntries: (entries) => proposeInjectedMemoryEntries(entries),
 	});
 	middleware.registerHook(memoryIntervention);
 	const unsubscribeMemoryLoop = bus.on(BusChannels.LoopBlocked, () => memoryIntervention.signalLoop());
@@ -1243,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
 			? {
@@ -1266,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: () => ({
@@ -1411,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 {
@@ -1569,6 +1782,12 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 	}
 
 	const chat = createChatLoop({
+		// The pre-warm holds one slot on its endpoint while it runs, so dispatch
+		// admission (#250) sees it exactly as it sees the orchestrator's own turn.
+		registerPrewarmEndpointSlot: (runtime) => {
+			const key = canonicalEndpointKey(runtime.runtimeResolution.target);
+			return key === null ? null : registerForegroundStream(key);
+		},
 		getSettings: getCurrentSettings,
 		providers,
 		middleware,
@@ -1628,6 +1847,11 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 			: {}),
 		toolRegistry,
 		hasAttachedDispatch: () => dispatchBackground.size() > 0,
+		// The pre-warm buys latency for a person about to type the next turn. A
+		// headless `run` submits its one prompt immediately and an unattended boot
+		// never submits at all, so neither has latency to buy; the ACP surface has
+		// an operator on the other end of the client and keeps it.
+		isLatencySurface: () => interactive || acpMode,
 	});
 
 	// Coordinated shutdown (SIGINT/SIGTERM, TUI quit) must abort any in-flight
@@ -1872,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 } : {}),
@@ -1891,6 +2129,10 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 				bank,
 				activity: memoryIntervention.recentActivity(),
 				stepInFlight: memoryIntervention.stepInFlight(),
+				// Folded from the telemetry ledger, which is durable across sessions,
+				// so `/memory` answers what the tier has cost since it was turned on
+				// rather than what it cost since this process started.
+				spend: readTaskMemorySpendSummary(clioStateDir()),
 			};
 		},
 		getTaskMemorySeedOffer,
@@ -1980,7 +2222,7 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 					},
 				}
 			: {}),
-		onSetThinkingLevel: (level) => {
+		onSetThinkingLevel: (level, scope) => {
 			const current = getCurrentSettings();
 			const nextLevel =
 				resolveModelRuntimeCapabilitiesForProviders(
@@ -1989,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();
@@ -2006,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);
@@ -2023,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),