@iowarp/clio-coder 0.3.8 → 0.3.9

package/src/cli/trace.ts

@@ -4,12 +4,15 @@ import { resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { clioStatePath } from "../core/xdg.js";
 import {
+	DEFAULT_TRACE_RETENTION_POLICY,
+	resolveTraceRetentionPolicy,
 	TRACE_EVENT_POLL_LIMIT,
 	type TraceEventRow,
 	type TracePhaseRow,
 	type TraceProcessRow,
 	TraceReader,
 	type TraceRunRow,
+	TraceStore,
 	traceDatabasePath,
 } from "../domains/observability/trace-store.js";
 
@@ -18,11 +21,15 @@ const HELP = `Usage:
   clio-coder trace phases <runId> [--db PATH]
   clio-coder trace tail <runId> [--follow] [--db PATH]
   clio-coder trace procs <runId> [--db PATH]
+  clio-coder trace prune [--max-age-days N] [--max-bytes N] [--db PATH] [--json]
   clio-coder trace sql <SELECT query> [--db PATH]
   clio-coder trace ui [--db PATH] [--port N]        source checkout only
 
 The viewer ships with the repository, not the npm package, so from an installed
 Clio the subcommands above are the way in. They read the same database.
+Pruning keeps ${DEFAULT_TRACE_RETENTION_POLICY.maxAgeDays} days and at most ${DEFAULT_TRACE_RETENTION_POLICY.maxBytes} bytes by default. Set
+CLIO_CODER_TRACE_RETENTION_DAYS or CLIO_CODER_TRACE_MAX_BYTES to change the automatic
+policy; prune flags override those values for one command.
 `;
 
 interface ParsedTraceArgs {
@@ -34,6 +41,8 @@ interface ParsedTraceArgs {
 	limit: number;
 	port: number;
 	json: boolean;
+	maxAgeDays: number | undefined;
+	maxBytes: number | undefined;
 }
 
 function parseTraceArgs(args: string[]): ParsedTraceArgs {
@@ -44,11 +53,19 @@ function parseTraceArgs(args: string[]): ParsedTraceArgs {
 	let limit = 50;
 	let port = 0;
 	let json = false;
+	let maxAgeDays: number | undefined;
+	let maxBytes: number | undefined;
 	for (let index = 0; index < args.length; index += 1) {
 		const arg = args[index];
 		if (arg === "--follow") follow = true;
 		else if (arg === "--json") json = true;
-		else if (arg === "--db" || arg === "--limit" || arg === "--port") {
+		else if (
+			arg === "--db" ||
+			arg === "--limit" ||
+			arg === "--port" ||
+			arg === "--max-age-days" ||
+			arg === "--max-bytes"
+		) {
 			const value = args[index + 1];
 			if (value === undefined) throw new Error(`${arg} requires a value`);
 			index += 1;
@@ -56,20 +73,25 @@ function parseTraceArgs(args: string[]): ParsedTraceArgs {
 				db = resolve(value);
 				dbExplicit = true;
 			} else if (arg === "--limit") limit = parseInteger(value, "--limit", 1, 500);
-			else port = parseInteger(value, "--port", 0, 65_535);
+			else if (arg === "--port") port = parseInteger(value, "--port", 0, 65_535);
+			else if (arg === "--max-age-days") maxAgeDays = parseInteger(value, arg, 1, 36_500);
+			else maxBytes = parseInteger(value, arg, 1024 * 1024, Number.MAX_SAFE_INTEGER);
 		} else if (arg?.startsWith("--db=")) {
 			db = resolve(arg.slice(5));
 			dbExplicit = true;
 		} else if (arg?.startsWith("--limit=")) limit = parseInteger(arg.slice(8), "--limit", 1, 500);
 		else if (arg?.startsWith("--port=")) port = parseInteger(arg.slice(7), "--port", 0, 65_535);
+		else if (arg?.startsWith("--max-age-days=")) maxAgeDays = parseInteger(arg.slice(15), "--max-age-days", 1, 36_500);
+		else if (arg?.startsWith("--max-bytes="))
+			maxBytes = parseInteger(arg.slice(12), "--max-bytes", 1024 * 1024, Number.MAX_SAFE_INTEGER);
 		else if (arg?.startsWith("-")) throw new Error(`unknown trace flag: ${arg}`);
 		else if (arg !== undefined) positional.push(arg);
 	}
-	return { positional, db, dbExplicit, follow, limit, port, json };
+	return { positional, db, dbExplicit, follow, limit, port, json, maxAgeDays, maxBytes };
 }
 
 /** Every subcommand `trace` answers to. Anything else is a usage error. */
-const TRACE_COMMANDS = new Set(["runs", "phases", "tail", "procs", "sql", "ui"]);
+const TRACE_COMMANDS = new Set(["runs", "phases", "tail", "procs", "prune", "sql", "ui"]);
 
 /** The subcommands whose first positional is a run id. */
 const TRACE_COMMANDS_NEEDING_RUN_ID = new Set(["phases", "tail", "procs"]);
@@ -132,6 +154,7 @@ export async function runTraceCommand(args: string[]): Promise<number> {
 	// the operator typed is a different claim, so a --db that is not there stays
 	// an error and says which path it means.
 	if (!existsSync(parsed.db)) return missingDatabase(parsed);
+	if (command === "prune") return runTracePrune(parsed);
 
 	let reader: TraceReader;
 	try {
@@ -189,6 +212,42 @@ export async function runTraceCommand(args: string[]): Promise<number> {
 	}
 }
 
+function runTracePrune(parsed: ParsedTraceArgs): number {
+	let policy: ReturnType<typeof resolveTraceRetentionPolicy>;
+	try {
+		policy = resolveTraceRetentionPolicy({
+			...(parsed.maxAgeDays === undefined ? {} : { maxAgeDays: parsed.maxAgeDays }),
+			...(parsed.maxBytes === undefined ? {} : { maxBytes: parsed.maxBytes }),
+		});
+	} catch (error) {
+		process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+		return 1;
+	}
+	let store: TraceStore;
+	try {
+		store = new TraceStore(parsed.db, { retention: policy });
+	} catch (error) {
+		process.stderr.write(`trace database: ${error instanceof Error ? error.message : String(error)}\n`);
+		return 1;
+	}
+	try {
+		const result = store.prune(policy);
+		if (parsed.json) {
+			process.stdout.write(`${JSON.stringify({ policy, ...result }, null, 2)}\n`);
+		} else {
+			process.stdout.write(
+				`trace prune: removed ${result.runsRemoved.toLocaleString("en-US")} runs and ${result.rowsRemoved.toLocaleString("en-US")} rows; reclaimed ${result.bytesRemoved.toLocaleString("en-US")} bytes; VACUUM ${result.vacuumed ? "ran" : "not needed"}; protected ${result.protectedRuns.toLocaleString("en-US")} live runs\n`,
+			);
+		}
+		return 0;
+	} catch (error) {
+		process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+		return 1;
+	} finally {
+		store.close();
+	}
+}
+
 async function tail(reader: TraceReader, runId: string, follow: boolean): Promise<void> {
 	let cursor = 0;
 	let idleTerminalPolls = 0;

package/src/cli/usage.ts

@@ -12,9 +12,12 @@ import { readEvidenceIndex } from "../domains/observability/evidence-index.js";
 import { type OutOfTurnUsageRow, readOutOfTurnUsageRows } from "../domains/observability/out-of-turn-usage.js";
 import { loadSkills } from "../domains/resources/index.js";
 import {
+	foldPromptCacheTelemetry,
+	hasPromptCacheTelemetry,
 	type LedgerUsageCall,
 	ledgerUsageCalls,
 	listSessionLedgerRefs,
+	type PromptCacheTelemetry,
 	parseSessionEntries,
 	readAuditRows,
 } from "../domains/session/index.js";
@@ -69,6 +72,8 @@ interface SessionUsage {
 	entriesInWindow: number;
 	/** Completed API calls this session recorded in the window, one per call. */
 	usageCalls: LedgerUsageCall[];
+	/** Backend prompt-cache facts persisted on assistant calls in the window. */
+	promptCache: PromptCacheTelemetry;
 }
 
 /** Per-call usage folded over one grouping (a model, or the whole window). */
@@ -102,32 +107,37 @@ function addResponseModelIdObservation(counts: ResponseModelIdObservationCounts,
 
 /**
  * How the folded calls split between the session's own turns and the rounds
- * that were billed beside it. A `/btw` side question and a `/handoff` round are
- * real spend and belong in the token and cost totals, but neither is a turn:
- * they never entered the session. `turns` therefore subtracts them from the
- * folded row count, which is exactly what the `/cost` overlay does.
+ * that were billed beside it. A `/btw` side question, a `/handoff` round, a
+ * session pre-warm, and a proactive-memory step are real spend and belong in
+ * the token and cost totals, but none of them is a turn: they never entered
+ * the session. `turns` therefore subtracts them from the folded row count,
+ * which is exactly what the `/cost` overlay does.
  */
 interface CallOrigins {
 	rows: number;
 	sideQuestions: number;
 	handoffs: number;
+	prewarms: number;
+	backgroundMemory: number;
 }
 
 function emptyCallOrigins(): CallOrigins {
-	return { rows: 0, sideQuestions: 0, handoffs: 0 };
+	return { rows: 0, sideQuestions: 0, handoffs: 0, prewarms: 0, backgroundMemory: 0 };
 }
 
 function turnsOf(origins: CallOrigins): number {
-	return origins.rows - origins.sideQuestions - origins.handoffs;
+	return origins.rows - origins.sideQuestions - origins.handoffs - origins.prewarms - origins.backgroundMemory;
 }
 
 function hasLabelledCall(origins: CallOrigins): boolean {
-	return origins.sideQuestions > 0 || origins.handoffs > 0;
+	return origins.sideQuestions > 0 || origins.handoffs > 0 || origins.prewarms > 0 || origins.backgroundMemory > 0;
 }
 
 function addOutOfTurnRow(origins: CallOrigins, row: OutOfTurnUsageRow): void {
 	origins.rows += 1;
 	if (row.label === "side-question") origins.sideQuestions += 1;
+	else if (row.label === "prewarm") origins.prewarms += 1;
+	else if (row.label === "background-memory") origins.backgroundMemory += 1;
 	else origins.handoffs += 1;
 }
 
@@ -435,6 +445,9 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 	const usageRows = [...usageByModel.values()].sort(
 		(a, b) => b.totals.totalTokens - a.totals.totalTokens || a.providerId.localeCompare(b.providerId),
 	);
+	const cacheSessions = sessions
+		.filter((session) => hasPromptCacheTelemetry(session.promptCache))
+		.sort((a, b) => a.sessionId.localeCompare(b.sessionId));
 
 	const approvedMemory = memoryRecords.filter((record) => record.approved && record.rejectedAt === undefined);
 	const pendingMemory = memoryRecords.filter((record) => !record.approved && record.rejectedAt === undefined);
@@ -515,8 +528,8 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 		emit({ kind: "fact", fact: "audit-tool-calls", value: auditToolCalls.length, blocked: auditBlocked.length });
 		if (usageMeasurable) {
 			// The origin split is emitted only when something out of turn was
-			// recorded, so a report over an archive with no `/btw` or `/handoff`
-			// round in it stays byte-identical to what it printed before.
+			// recorded, so a report over an archive with no `/btw`, `/handoff`, or
+			// pre-warm round in it stays byte-identical to what it printed before.
 			emit({
 				kind: "fact",
 				fact: "tokens",
@@ -526,6 +539,8 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 							turns: turnsOf(callOrigins),
 							sideQuestions: callOrigins.sideQuestions,
 							handoffs: callOrigins.handoffs,
+							prewarms: callOrigins.prewarms,
+							backgroundMemorySteps: callOrigins.backgroundMemory,
 						}
 					: {}),
 			});
@@ -540,6 +555,15 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 					...row.totals,
 				});
 			}
+			for (const session of cacheSessions) {
+				emit({
+					kind: "fact",
+					fact: "session-cache",
+					sessionId: session.sessionId,
+					uncachedPrefillTokens: session.promptCache.uncachedPrefillTokens,
+					verdictCounts: session.promptCache.verdictCounts,
+				});
+			}
 		}
 		for (const [tool, totals] of topTools) emit({ kind: "fact", fact: "top-tool", tool, ...totals });
 		for (const [shape, count] of topShapes) {
@@ -600,6 +624,10 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 			out(`  turns in window: ${turnsOf(callOrigins)}`);
 			if (callOrigins.sideQuestions > 0) out(`  side questions in window: ${callOrigins.sideQuestions}`);
 			if (callOrigins.handoffs > 0) out(`  handoffs in window: ${callOrigins.handoffs}`);
+			if (callOrigins.prewarms > 0) out(`  pre-warms in window: ${callOrigins.prewarms}`);
+			if (callOrigins.backgroundMemory > 0) {
+				out(`  background memory steps in window: ${callOrigins.backgroundMemory}`);
+			}
 		}
 		out(`  provider-reported cost in window: $${usageTotals.costUsd.toFixed(4)}`);
 	}
@@ -639,6 +667,27 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 			),
 		);
 	}
+	if (cacheSessions.length > 0) {
+		out("");
+		out("  prompt cache by session (from backend timings and persisted verdicts)");
+		process.stdout.write(
+			indent(
+				formatColumns([
+					["session", "uncached prefill", "hot/partial/cold/small"],
+					...cacheSessions.map((session) => [
+						session.sessionId,
+						session.promptCache.uncachedPrefillTokens === null ? "n/a" : String(session.promptCache.uncachedPrefillTokens),
+						[
+							session.promptCache.verdictCounts.hot,
+							session.promptCache.verdictCounts.partial,
+							session.promptCache.verdictCounts.cold,
+							session.promptCache.verdictCounts.small,
+						].join("/"),
+					]),
+				]),
+			),
+		);
+	}
 	if (topTools.length > 0) {
 		out("");
 		out("  top tools (from receipt toolStats)");
@@ -865,6 +914,9 @@ async function readSessions(
 		}
 		const parsedEntries = parseSessionEntries(raw, ref.path);
 		diagnostics.malformedSessionLines += parsedEntries.errors.length;
+		const accountingEntries = parsedEntries.entries.filter(
+			(entry) => entry.kind === "modelChange" || inWindow(entry.timestamp, windowStart, windowEnd),
+		);
 		const usage: SessionUsage = {
 			sessionId: ref.sessionId,
 			cwdHash: ref.cwdHash,
@@ -874,11 +926,8 @@ async function readSessions(
 			// modelChange rows are kept regardless of the window: they carry no
 			// usage of their own, and dropping the ones that predate the window
 			// would attribute in-window calls to the wrong target.
-			usageCalls: ledgerUsageCalls(
-				parsedEntries.entries.filter(
-					(entry) => entry.kind === "modelChange" || inWindow(entry.timestamp, windowStart, windowEnd),
-				),
-			),
+			usageCalls: ledgerUsageCalls(accountingEntries),
+			promptCache: foldPromptCacheTelemetry(accountingEntries),
 		};
 		for (const entry of parsedEntries.entries) {
 			if (!inWindow(entry.timestamp, windowStart, windowEnd)) continue;

package/src/core/bus-events.ts

@@ -51,6 +51,7 @@ export const BusChannels = {
 	ToolBudgetExceeded: "safety.toolBudgetExceeded",
 	ProviderHealth: "provider.health",
 	RuntimeNotice: "runtime.notice",
+	ResidencyMutation: "residency.mutation",
 	DispatchScopeNotice: "dispatch.scopeNotice",
 	DispatchEnqueued: "dispatch.enqueued",
 	DispatchStarted: "dispatch.started",
@@ -64,6 +65,7 @@ export const BusChannels = {
 	ContextWarning: "context.warning",
 	ContextPruned: "context.pruned",
 	ContextRecalled: "context.recalled",
+	MemoryStepCompleted: "memory.stepCompleted",
 	AgentStatusChanged: "agent.status.changed",
 	RunAborted: "run.aborted",
 	BudgetAlert: "budget.alert",
@@ -100,6 +102,28 @@ export interface RuntimeNoticePayload {
 	detail?: Record<string, number | string | boolean>;
 }
 
+/**
+ * One completed proactive-memory model step, published on
+ * {@link BusChannels.MemoryStepCompleted}. It carries the endpoint the step
+ * called and nothing about what the step decided: the only consumer is the
+ * turn context, which stamps an expected-cold reason when a step ran between
+ * turns on the endpoint the chat target streams against.
+ */
+export interface MemoryStepCompletedPayload {
+	endpointKey: string;
+	targetId: string;
+}
+
+/** A successful model load or eviction on one residency-managed endpoint. */
+export interface ResidencyMutationPayload {
+	targetKey: string;
+	targetId: string;
+	runtimeId: string;
+	model: string;
+	operation: "load" | "evict";
+	at: number;
+}
+
 /**
  * Window-resolution warning published on {@link BusChannels.ContextWarning}.
  * Emitted on transitions only: `warning` carries the text when a warning
@@ -133,7 +157,7 @@ export type DispatchScopeNoticePayload =
 	  };
 
 export type ContextActivityKind = "context-init" | "context-clear" | "context-refresh" | "context-wiki" | "compaction";
-export type ContextActivityPhase = "scan" | "codewiki" | "generate" | "clio-md" | "state" | "done";
+export type ContextActivityPhase = "scan" | "codewiki" | "generate" | "clio-md" | "state" | "compact" | "done";
 export type ContextActivityStatus = "started" | "running" | "completed" | "failed";
 
 /** Structured progress for context operations. Interactive renders this as a live context island. */
@@ -505,6 +529,8 @@ export interface DispatchRunIdentity {
 	wireModelId: string;
 	runtimeId: string;
 	runtimeKind: RunKind;
+	/** Canonical inference scheduler and its resolved request-slot bound. */
+	endpoint?: { key: string; label: string; limit: number } | undefined;
 	/** Admitted invocation budget provenance for native workers. */
 	budget?: RunToolBudgetEnvelope | undefined;
 	/** Fleet node id the run was placed on; absent renders as the local node. */
@@ -761,6 +787,7 @@ export type BusPayloadMap = {
 	[BusChannels.ToolBudgetExceeded]: ToolBudgetExceededPayload;
 	[BusChannels.ProviderHealth]: ProviderHealthPayload;
 	[BusChannels.RuntimeNotice]: RuntimeNoticePayload;
+	[BusChannels.ResidencyMutation]: ResidencyMutationPayload;
 	[BusChannels.DispatchScopeNotice]: DispatchScopeNoticePayload;
 	[BusChannels.DispatchEnqueued]: DispatchEnqueuedPayload;
 	[BusChannels.DispatchStarted]: DispatchStartedPayload;
@@ -774,6 +801,7 @@ export type BusPayloadMap = {
 	[BusChannels.ContextWarning]: ContextWarningPayload;
 	[BusChannels.ContextPruned]: ContextPrunedPayload;
 	[BusChannels.ContextRecalled]: ContextRecalledPayload;
+	[BusChannels.MemoryStepCompleted]: MemoryStepCompletedPayload;
 	[BusChannels.AgentStatusChanged]: AgentStatusChangedPayload;
 	[BusChannels.RunAborted]: RunAbortedPayload;
 	[BusChannels.BudgetAlert]: BudgetAlertPayload;

package/src/core/cache-telemetry.ts

@@ -0,0 +1,42 @@
+/** Cache classification for one backend completion call. */
+export type BackendCacheVerdict = "hot" | "partial" | "cold" | "small";
+
+/** Backend timing source that directly reports local prefill work. */
+export type BackendTimingsSource = "llamacpp-timings" | "lmstudio-timings";
+
+/** Normalized prefill and prediction timings reported by the serving backend. */
+export interface BackendCompletionTimings {
+	promptTokens: number;
+	cachedTokens: number | null;
+	predictedTokens: number;
+	promptMs: number;
+	predictedMs: number;
+	source: BackendTimingsSource;
+}
+
+/** Per-session call counts grouped by backend cache verdict. */
+export interface CacheVerdictCounts {
+	hot: number;
+	partial: number;
+	cold: number;
+	small: number;
+}
+
+export function emptyCacheVerdictCounts(): CacheVerdictCounts {
+	return { hot: 0, partial: 0, cold: 0, small: 0 };
+}
+
+/** Return newly evaluated prefill tokens when the backend reports cache reads. */
+export function uncachedPrefillTokens(backend: BackendCompletionTimings | null | undefined): number | null {
+	if (backend === null || backend === undefined || backend.cachedTokens === null) return null;
+	if (
+		!Number.isFinite(backend.promptTokens) ||
+		backend.promptTokens < 0 ||
+		!Number.isFinite(backend.cachedTokens) ||
+		backend.cachedTokens < 0 ||
+		backend.cachedTokens > backend.promptTokens
+	) {
+		return null;
+	}
+	return backend.promptTokens - backend.cachedTokens;
+}

package/src/core/config.ts

@@ -521,6 +521,7 @@ function validateTarget(issues: Issues, path: string, value: unknown): ClioSetti
 		"gateway",
 		"pricing",
 		"lmstudio",
+		"maxConcurrentRequests",
 	]);
 	const id = "id" in value ? expectString(issues, `${path}.id`, value.id) : undefined;
 	const runtime = "runtime" in value ? expectString(issues, `${path}.runtime`, value.runtime) : undefined;
@@ -566,6 +567,10 @@ function validateTarget(issues: Issues, path: string, value: unknown): ClioSetti
 		const v = validateLmStudioSettings(issues, `${path}.lmstudio`, value.lmstudio);
 		if (v !== undefined) target.lmstudio = v;
 	}
+	if ("maxConcurrentRequests" in value) {
+		const v = expectInteger(issues, `${path}.maxConcurrentRequests`, value.maxConcurrentRequests, { min: 1 });
+		if (v !== undefined) target.maxConcurrentRequests = v;
+	}
 	return target;
 }
 
@@ -1004,6 +1009,7 @@ const TOP_LEVEL_KEYS = [
 	"keybindings",
 	"compaction",
 	"context",
+	"prewarm",
 	"retry",
 	"guardrails",
 ] as const;
@@ -1589,6 +1595,18 @@ export function validateSettings(raw: unknown): SettingsValidationResult {
 		}
 	}
 
+	if ("prewarm" in raw) {
+		if (!isPlainObject(raw.prewarm)) {
+			issues.add("prewarm", `expected a map, got ${describe(raw.prewarm)}`);
+		} else {
+			issues.unknownKeys("prewarm", raw.prewarm, ["enabled"]);
+			if ("enabled" in raw.prewarm) {
+				const v = expectBoolean(issues, "prewarm.enabled", raw.prewarm.enabled);
+				if (v !== undefined) settings.prewarm.enabled = v;
+			}
+		}
+	}
+
 	if ("retry" in raw) {
 		if (!isPlainObject(raw.retry)) {
 			issues.add("retry", `expected a map, got ${describe(raw.retry)}`);

package/src/core/defaults.ts

@@ -151,6 +151,21 @@ export interface WorkingSetSettings {
 	minEvictableTokens: number;
 }
 
+/**
+ * Prompt pre-warm settings (`prewarm`). On a local server prefill is the cost,
+ * and the prefix the next turn will send is fully known before the operator
+ * types anything: at session start, after a resume rebuilds the message array,
+ * and after a compaction settles. Clio sends that prefix to the backend right
+ * then so the slot's prefix cache already holds it when the real turn arrives.
+ *
+ *   - enabled: master switch. The feature is off on every tier but
+ *     `local-native` whatever this says, and off for workers and headless runs,
+ *     because it buys latency for an operator watching a local server.
+ */
+export interface PrewarmSettings {
+	enabled: boolean;
+}
+
 /**
  * Transient provider retry controls for the interactive chat loop. These are
  * intentionally small and mirror the session retry helper defaults. Dispatched
@@ -354,11 +369,15 @@ export const DEFAULT_SETTINGS = {
 			everyNTools: 10,
 			windowSteps: 8,
 			maxTokens: 400,
-			// A memory step runs detached from the turn that triggered it, so a
-			// generous deadline costs no interactive latency. Measured steps on a
-			// small local route ranged past two minutes, and a deadline shorter than
-			// the model discards finished work as a timeout.
-			timeoutMs: 180_000,
+			// A memory step runs detached from the turn that triggered it, but it
+			// runs on a real inference endpoint that the operator's own turns and
+			// dispatched workers also queue against. The operator's ledger over 14
+			// days recorded 60 llm-tier steps spending 1,666 seconds of model time
+			// for 6 injections, with one step holding a local server for 102.5
+			// seconds to answer nothing. The deadline is what a turn boundary can
+			// actually wait for; a step that runs past it is recorded as timed out
+			// rather than spending the remaining minutes unobserved.
+			timeoutMs: 30_000,
 		},
 	},
 	watchdog: { enabled: false } as WatchdogSettings,
@@ -444,6 +463,9 @@ export const DEFAULT_SETTINGS = {
 	context: {
 		workingSet: DEFAULT_WORKING_SET_SETTINGS,
 	},
+	prewarm: {
+		enabled: true,
+	} as PrewarmSettings,
 	retry: {
 		enabled: true,
 		maxRetries: 3,
@@ -539,7 +561,7 @@ memory:
     everyNTools: 10
     windowSteps: 8
     maxTokens: 400
-    timeoutMs: 180000
+    timeoutMs: 30000
 
 # Opt-in turn-end watchdog. When enabled, a turn that changed the tree is
 # reviewed by one read-only verifier run briefed with the turn's coalesced diff
@@ -751,6 +773,14 @@ context:
     protectLastTurns: 6
     minEvictableTokens: 200
 
+# Prompt pre-warm. At session start, after a resume rebuilds the message array,
+# and after a compaction settles, Clio sends the prefix the next turn would send
+# (minus your text) so a local server has already prefilled it when you press
+# Enter. Local-native targets only, interactive sessions only, and never while a
+# turn or a dispatch is running.
+prewarm:
+  enabled: true
+
 # Transient provider/stream retry controls for interactive chat.
 # Retryable errors include overloads, rate limits, 5xx responses, network
 # resets, and timeouts. Context overflow uses compaction recovery instead.

package/src/core/endpoint-key.ts

@@ -0,0 +1,27 @@
+/**
+ * Canonical identity of an OpenAI-compatible inference endpoint: normalized
+ * HTTP scheme, lower-cased host, normalized port, and normalized base path with
+ * a conventional terminal `/v1` mount stripped. Credentials, query, and
+ * fragment do not participate. Host aliases are not resolved, so
+ * `localhost` and `127.0.0.1` stay distinct. Shared by dispatch capacity and
+ * residency locking so both speak the same key for one server.
+ */
+export function canonicalEndpointUrl(raw: string | null | undefined): string | null {
+	if (!raw?.trim()) return null;
+	try {
+		const url = new URL(raw.trim().replace(/^ws:/u, "http:").replace(/^wss:/u, "https:"));
+		url.protocol = url.protocol.toLowerCase();
+		if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+		url.hostname = url.hostname.toLowerCase();
+		url.username = "";
+		url.password = "";
+		url.hash = "";
+		url.search = "";
+		let path = url.pathname.replace(/\/{2,}/gu, "/").replace(/\/$/u, "");
+		if (path.endsWith("/v1")) path = path.slice(0, -3);
+		url.pathname = path || "/";
+		return url.toString().replace(/\/$/u, "");
+	} catch {
+		return null;
+	}
+}

package/src/core/residency-target-key.ts

@@ -0,0 +1,25 @@
+import { canonicalEndpointUrl } from "./endpoint-key.js";
+
+/** Runtime families whose model residency Clio can actively mutate. */
+export type ResidencyRuntimeId = "llamacpp" | "lmstudio" | "ollama-native";
+
+const RESIDENCY_RUNTIME_IDS: ReadonlySet<string> = new Set<ResidencyRuntimeId>([
+	"llamacpp",
+	"lmstudio",
+	"ollama-native",
+]);
+
+export function residencyTargetKey(runtimeId: ResidencyRuntimeId, baseUrl: string): string;
+export function residencyTargetKey(runtimeId: string, baseUrl: string | null | undefined): string | null;
+/** Stable key for one residency-managed server endpoint: its canonical URL. */
+export function residencyTargetKey(runtimeId: string, baseUrl: string | null | undefined): string | null {
+	if (!RESIDENCY_RUNTIME_IDS.has(runtimeId) || typeof baseUrl !== "string") return null;
+	// The key is the canonical endpoint itself, without a runtime prefix, so the
+	// residency lock and dispatch capacity name one server the same way (#250).
+	// A base url the canonical form refuses, such as one written without a
+	// scheme, still gets a key: callers store this in `ResidencyAdapter.targetKey`,
+	// which is a `string`, and dispatch capacity has no key for that target
+	// either, so there is nothing to agree with and nothing to gain by dropping
+	// the lock the reconciler serializes on.
+	return canonicalEndpointUrl(baseUrl) ?? baseUrl;
+}

package/src/core/response-schema.ts

@@ -11,11 +11,45 @@ export const RESPONSE_SCHEMA_MAX_SERIALIZED_BYTES = 64 * 1024;
  * `schema` key, and returns HTTP 200 with unconstrained JSON, so widening this
  * to the api family would convert a clean refusal into a silent
  * non-enforcement. lmstudio declares `structuredOutputs: "json-schema"`
- * truthfully and is still excluded here, because Clio has no dialect for its
- * transport. Widen this only together with a dialect for the runtime added.
+ * truthfully and is still excluded here, because the worker seam has no
+ * dialect for its transport. Widen this only together with a dialect for the
+ * runtime added; {@link responseSchemaDialectFor} is where the out-of-turn
+ * seam did exactly that (issue #223).
  */
 export const RESPONSE_SCHEMA_RUNTIME_ID = "llamacpp";
 
+/** The runtime that takes the standard OpenAI `json_schema` response format. */
+export const OPENAI_SCHEMA_RUNTIME_ID = "lmstudio";
+
+/**
+ * How a runtime spells a JSON-schema response constraint on the wire.
+ *
+ * `llamacpp-json-object` is llama-server's own `response_format: { type:
+ * "json_object", schema }`, which it compiles into a sampler grammar.
+ * `openai-json-schema` is the standard `response_format: { type:
+ * "json_schema", json_schema: { name, strict, schema } }` that LM Studio
+ * implements.
+ */
+export type ResponseSchemaDialect = "llamacpp-json-object" | "openai-json-schema";
+
+/**
+ * The dialect this runtime takes, or null when Clio has none for it and the
+ * request has to go unconstrained.
+ *
+ * Deliberately a name check, for the reason {@link RESPONSE_SCHEMA_RUNTIME_ID}
+ * gives: a generic OpenAI-compatible gateway answers HTTP 200 to a spelling it
+ * does not implement and returns unconstrained JSON, so a capability flag would
+ * turn a known non-enforcement into a silent one. This is the out-of-turn
+ * seam's table; the worker seam keeps the narrower
+ * {@link runtimeSpeaksResponseSchemaDialect} check, because a worker that
+ * cannot enforce a contract must refuse admission rather than degrade.
+ */
+export function responseSchemaDialectFor(runtimeId: string): ResponseSchemaDialect | null {
+	if (runtimeId === RESPONSE_SCHEMA_RUNTIME_ID) return "llamacpp-json-object";
+	if (runtimeId === OPENAI_SCHEMA_RUNTIME_ID) return "openai-json-schema";
+	return null;
+}
+
 /** Whether this runtime speaks the dialect above. Transport shape, not capability. */
 export function runtimeSpeaksResponseSchemaDialect(runtime: { id: string; kind: string; apiFamily: string }): boolean {
 	return (

package/src/domains/config/classify.ts

@@ -61,6 +61,9 @@ const NEXT_TURN_FIELDS = new Set<string>([
 	"delegation",
 	"compaction",
 	"context",
+	// The pre-warm reads its setting when a trigger fires, and every trigger sits
+	// on a turn boundary, so a change takes effect before the next turn runs.
+	"prewarm",
 	"retry",
 ]);