@iowarp/clio-coder 0.4.2 → 0.4.3

package/src/entry/task-memory-lifecycle.ts

@@ -0,0 +1,35 @@
+import { BusChannels } from "../core/bus-events.js";
+import type { SafeEventBus } from "../core/event-bus.js";
+import type { TaskMemoryStepUsage } from "../domains/memory/task-memory-policy.js";
+import type { MemoryInterventionRegistration } from "../domains/middleware/memory-intervention.js";
+import {
+	type RecordBackgroundMemoryStepInput,
+	recordBackgroundMemoryStep,
+} from "../domains/observability/background-memory-usage.js";
+
+/** Explicit navigation owns memory lifetime; ordinary leaf advances and tree reads do not. */
+export function bindTaskMemoryLifecycle(
+	bus: SafeEventBus,
+	memory: Pick<MemoryInterventionRegistration, "reset" | "dispose">,
+): () => void {
+	const unsubscribe = [
+		bus.on(BusChannels.SessionParked, () => memory.reset()),
+		bus.on(BusChannels.SessionResumed, () => memory.reset()),
+		bus.on(BusChannels.SessionTurnSwitched, () => memory.reset()),
+		bus.on(BusChannels.SessionEnd, () => memory.dispose()),
+	];
+	return () => {
+		memory.dispose();
+		for (const off of unsubscribe) off();
+	};
+}
+
+/** The durable row keeps launch identity even when the live cost tracker has moved on. */
+export function captureTaskMemoryUsage(
+	input: Omit<RecordBackgroundMemoryStepInput, "usage">,
+): (usage: TaskMemoryStepUsage, isCurrent: boolean) => void {
+	const { observability, ...origin } = input;
+	return (usage, isCurrent) => {
+		recordBackgroundMemoryStep({ ...origin, usage, observability: isCurrent ? observability : undefined });
+	};
+}

package/src/interactive/chat-loop-messages.ts

@@ -471,11 +471,11 @@ export function backendCacheVerdict(
 	return classifyCacheUsage(input, cacheRead);
 }
 
-/** Per-API-call latency captured from the agent event stream (T3.2). */
+/** Native stream-invocation latency, measured on one monotonic clock. */
 export interface AssistantCallTiming {
-	/** message_start → first assistant delta; null when no delta arrived. */
+	/** Invocation to first assistant output; null when no output arrived. */
 	ttftMs: number | null;
-	/** message_start → message_end for the same assistant API call. */
+	/** Invocation to message_end for the same assistant API call. */
 	apiMs: number;
 }
 
@@ -490,7 +490,16 @@ export function assistantSessionPayload(
 	if (Array.isArray(raw.content)) payload.content = raw.content;
 	if (thinking.length > 0) payload.thinking = thinking;
 	payload.responseModelIdObservation = responseModelIdObservationFromRecord(raw, "not-observed");
-	for (const key of ["usage", "api", "provider", "model", "responseModel", "responseId", "diagnostics"]) {
+	for (const key of [
+		"usage",
+		"api",
+		"provider",
+		"model",
+		"responseModel",
+		"responseId",
+		"gatewayRouting",
+		"diagnostics",
+	]) {
 		if (raw[key] !== undefined) payload[key] = raw[key];
 	}
 	if (failure && !isSelfExplainingAbort({ stopReason: raw.stopReason, errorMessage: raw.errorMessage, text })) {

package/src/interactive/chat-loop.ts

@@ -16,7 +16,14 @@
 import { BusChannels, type RunAbortSource } from "../core/bus-events.js";
 import type { ClioSettings } from "../core/config.js";
 import type { SafeEventBus } from "../core/event-bus.js";
-import type { PendingSkillRequest } from "../core/skill-activation.js";
+import {
+	armedSkillSurface,
+	type PendingSkillRequest,
+	type PendingSkillToolPolicy,
+	skillSurfaceLabels,
+	skillSurfaceNames,
+	withModelSkillActivation,
+} from "../core/skill-activation.js";
 import { clioStateDir } from "../core/xdg.js";
 import {
 	createMiddlewareToolChoiceControl,
@@ -36,6 +43,7 @@ import {
 	runtimeTargetSnapshot,
 	targetRequiresAuth,
 } from "../domains/providers/index.js";
+import { type AutonomyLevel, modelMayActivateSkills } from "../domains/safety/autonomy.js";
 import type { ProtectedArtifactState } from "../domains/safety/protected-artifacts.js";
 import type { CompactResult } from "../domains/session/compaction/compact.js";
 import type { ContextSnapshot, ContextUsageSnapshot } from "../domains/session/context-accounting.js";
@@ -285,6 +293,12 @@ export interface ChatLoop {
 	 * queues the text for the next slot instead.
 	 */
 	interruptRefusal(): string | null;
+	/**
+	 * `/skill off`: drop the tool surface an activated skill armed, so the next
+	 * turn runs with the full surface again. Returns the skill names that were
+	 * armed, or an empty list when nothing was.
+	 */
+	clearSkillSurface(): ReadonlyArray<string>;
 	clearQueuedFollowUps(): string[];
 	queuedMessages(): QueuedMessagesSnapshot;
 	cancel(options?: ChatCancelOptions): void;
@@ -368,6 +382,12 @@ export interface ChatLoop {
 
 export interface CreateChatLoopDeps {
 	getSettings: () => Readonly<ClioSettings>;
+	/**
+	 * The same effective autonomy level registry admission resolves, so the
+	 * skill-activation gate and the tool gate can never disagree. Absent falls
+	 * back to the settings value.
+	 */
+	getAutonomy?: () => AutonomyLevel;
 	providers: ProvidersContract;
 	/**
 	 * Whitelist of target ids that the chat-loop is allowed to drive. The
@@ -622,6 +642,31 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 		emit({ type: "notice", level, surface: "transcript", text, ...(key === undefined ? {} : { key }) });
 	};
 
+	/**
+	 * Carry (or drop) the tool surface a skill declared once the turn that
+	 * loaded it settles, and say so once on the transcript. The operator needs
+	 * to know a narrowing is armed across their next messages, and needs one
+	 * line back when it lifts; the skill-activation ledger entry already
+	 * records provenance, so this is the notice, not a second UI.
+	 */
+	const armSkillSurface = (policy: PendingSkillToolPolicy | undefined, loadedBefore?: ReadonlySet<string>): void => {
+		const previous = skillSurfaceNames(state.activeSkillSurface).join(", ");
+		const next = armedSkillSurface(policy);
+		const current = skillSurfaceNames(next).join(", ");
+		state.activeSkillSurface = next;
+		const activated = skillSurfaceLabels(policy).filter((label) => !loadedBefore?.has(label.split(" ")[0] ?? label));
+		if (activated.length > 0) {
+			emitNotice(
+				current.length > 0
+					? `[Clio Coder] Skill activated: ${activated.join(", ")}. Its tool surface stays armed across your next turns until another skill replaces it or you run /skill off.`
+					: `[Clio Coder] Skill activated: ${activated.join(", ")}. It declares no tool narrowing.`,
+			);
+		}
+		if (current !== previous && current.length === 0 && previous.length > 0) {
+			emitNotice(`[Clio Coder] Skill tool surface cleared: ${previous}. The full tool surface is back.`);
+		}
+	};
+
 	/**
 	 * The same transcript notice every admission exit already emitted, carrying
 	 * the reason the turn never started. Text, level, and surface are unchanged,
@@ -745,6 +790,7 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 		context,
 		middleware,
 		retrySettings,
+		sessionId: () => deps.session?.current()?.id,
 		emit: emitRuntimeEvent,
 		emitNotice,
 		toolStartTimes,
@@ -959,6 +1005,11 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 		steer: (text) => queues.steer(text),
 		queueFollowUp: (text) => queues.queueFollowUp(text),
 		interruptRefusal: () => (state.streaming ? interruptRefusalReason() : null),
+		clearSkillSurface: () => {
+			const cleared = skillSurfaceNames(state.activeSkillSurface);
+			armSkillSurface(undefined);
+			return cleared;
+		},
 		clearQueuedFollowUps: () => queues.clearQueuedMirror().map((entry) => entry.text),
 		queuedMessages: () => queues.queuedMessages(),
 
@@ -1043,7 +1094,18 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 			const images = options.images && options.images.length > 0 ? [...options.images] : undefined;
 			const pendingSkillRequests = options.pendingSkillRequests ?? [];
 			context.addWorkingContextPaths(options.workingContextPaths ?? []);
-			const pendingSkillPolicy = createPendingSkillToolPolicy(pendingSkillRequests);
+			// A skill the operator activated narrows the tools for the workflow
+			// it started, and that workflow outlives the turn it began in. A
+			// fresh /skill this turn replaces the armed surface; otherwise the
+			// armed surface is what this turn runs under.
+			const pendingSkillPolicy = withModelSkillActivation(
+				createPendingSkillToolPolicy(pendingSkillRequests) ?? state.activeSkillSurface,
+				modelMayActivateSkills(deps.getAutonomy?.() ?? deps.getSettings().safety.autonomy),
+			);
+			// What was already loaded when this turn started, so the settle-time
+			// notice names the skills this turn activated and not the ones a
+			// carried surface has been holding since an earlier message.
+			const skillsLoadedBeforeTurn = new Set(pendingSkillPolicy?.loadedSkillNames ?? []);
 			// Resolve the frozen session tool surface before turn_start so intent
 			// middleware sees the exact tools this request can actually call.
 			agentRuntime.agent.state.tools = resolveSessionTools(
@@ -1310,6 +1372,7 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 				}
 				state.currentPendingSkillPolicy = priorPendingSkillPolicy;
 				state.currentAskUserPolicy = priorAskUserPolicy;
+				armSkillSurface(pendingSkillPolicy, skillsLoadedBeforeTurn);
 				state.activeUserTurnId = null;
 				// Safety net for thrown paths where agent_end never delivered;
 				// no-op when the agent_end flush already ran.

package/src/interactive/chat-renderer.ts

@@ -451,6 +451,7 @@ function richMessageFromEntry(entry: MessageEntry, maxTextChars?: number): Agent
 			"responseModelIdObservation",
 			"responseModel",
 			"responseId",
+			"gatewayRouting",
 			"diagnostics",
 			"contextUsageInvalidated",
 		]) {

package/src/interactive/cost-overlay.ts

@@ -46,6 +46,7 @@ export interface CostRow {
 	prewarms: number;
 	/** Calls in this row that were proactive-memory steps on the background target. */
 	backgroundMemory: number;
+	failedCompaction: number;
 	cost: CostAggregate;
 }
 
@@ -79,6 +80,7 @@ export function aggregateCostEntries(entries: ReadonlyArray<CostEntry>): CostRow
 			if (entry.label === "handoff") existing.row.handoffs += 1;
 			if (entry.label === "prewarm") existing.row.prewarms += 1;
 			if (entry.label === "background-memory") existing.row.backgroundMemory += 1;
+			if (entry.label === "failed-compaction") existing.row.failedCompaction += 1;
 			for (const requestedModelId of entry.requestedModelIds) existing.requestedModelIds.add(requestedModelId);
 			addResponseModelIdObservationCounts(
 				existing.responseModelIdObservationCounts,
@@ -103,6 +105,7 @@ export function aggregateCostEntries(entries: ReadonlyArray<CostEntry>): CostRow
 				handoffs: entry.label === "handoff" ? 1 : 0,
 				prewarms: entry.label === "prewarm" ? 1 : 0,
 				backgroundMemory: entry.label === "background-memory" ? 1 : 0,
+				failedCompaction: entry.label === "failed-compaction" ? 1 : 0,
 			},
 			requestedModelIds: new Set(entry.requestedModelIds),
 			responseModelIdObservationCounts: { ...entry.responseModelIdObservationCounts },
@@ -143,6 +146,7 @@ function sumRows(
 			handoffs: acc.handoffs + row.handoffs,
 			prewarms: acc.prewarms + row.prewarms,
 			backgroundMemory: acc.backgroundMemory + row.backgroundMemory,
+			failedCompaction: acc.failedCompaction + row.failedCompaction,
 		}),
 		{
 			runs: 0,
@@ -157,6 +161,7 @@ function sumRows(
 			handoffs: 0,
 			prewarms: 0,
 			backgroundMemory: 0,
+			failedCompaction: 0,
 		},
 	);
 }
@@ -229,13 +234,26 @@ function summaryBlock(
 	return kvBlock([
 		[
 			"turns",
-			formatTokens(totals.runs - totals.sideQuestions - totals.handoffs - totals.prewarms - totals.backgroundMemory),
+			formatTokens(
+				totals.runs -
+					totals.sideQuestions -
+					totals.handoffs -
+					totals.prewarms -
+					totals.backgroundMemory -
+					totals.failedCompaction,
+			),
 		],
 		["model calls", formatTokens(totals.apiCalls)],
 		...(totals.sideQuestions > 0 ? [["side questions", formatTokens(totals.sideQuestions)] as const] : []),
 		...(totals.handoffs > 0 ? [["handoffs", formatTokens(totals.handoffs)] as const] : []),
 		...(totals.prewarms > 0 ? [["pre-warms", formatTokens(totals.prewarms)] as const] : []),
 		...(totals.backgroundMemory > 0 ? [["memory steps", formatTokens(totals.backgroundMemory)] as const] : []),
+		...(totals.failedCompaction > 0
+			? [
+					["failed compaction calls", formatTokens(totals.failedCompaction)] as const,
+					["compaction usage", "known subtotals; missing usage is unknown"] as const,
+				]
+			: []),
 		...(cost === null ? [] : [["cost", cost] as const]),
 		["input", formatTokens(totals.input)],
 		["output", formatTokens(totals.output)],
@@ -255,12 +273,18 @@ function modelBlock(row: CostRow): string[] {
 	return kvBlock([
 		["requested model ids", row.requestedModelIds.join(", ")],
 		["response model id observation", responseModelIdObservationCountsLabel(row.responseModelIdObservationCounts)],
-		["turns", formatTokens(row.runs - row.sideQuestions - row.handoffs - row.prewarms - row.backgroundMemory)],
+		[
+			"turns",
+			formatTokens(
+				row.runs - row.sideQuestions - row.handoffs - row.prewarms - row.backgroundMemory - row.failedCompaction,
+			),
+		],
 		["model calls", formatTokens(row.apiCalls)],
 		...(row.sideQuestions > 0 ? [["side questions", formatTokens(row.sideQuestions)] as const] : []),
 		...(row.handoffs > 0 ? [["handoffs", formatTokens(row.handoffs)] as const] : []),
 		...(row.prewarms > 0 ? [["pre-warms", formatTokens(row.prewarms)] as const] : []),
 		...(row.backgroundMemory > 0 ? [["memory steps", formatTokens(row.backgroundMemory)] as const] : []),
+		...(row.failedCompaction > 0 ? [["failed compaction calls", formatTokens(row.failedCompaction)] as const] : []),
 		...(cost === null ? [] : [["cost", cost] as const]),
 		["input", formatTokens(row.input)],
 		["output", formatTokens(row.output)],

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">;
@@ -389,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 ?? [],

package/src/interactive/renderers/worker-entry.ts

@@ -206,6 +206,36 @@ function researchReport(value: Record<string, unknown>): PresentedContractAnswer
 	return { lines: lines.length === 0 ? ["No findings reported."] : lines, footer: `source ${value.source}` };
 }
 
+function worldKnowledgeReport(value: Record<string, unknown>): PresentedContractAnswer | null {
+	if (
+		(value.discovery !== "performed" &&
+			value.discovery !== "caller-supplied-only" &&
+			value.discovery !== "unavailable") ||
+		!Array.isArray(value.facts) ||
+		!isStringArray(value.synthesis) ||
+		!isStringArray(value.uncertainties) ||
+		!isStringArray(value.followUpVerification)
+	) {
+		return null;
+	}
+	const lines: string[] = [];
+	for (const raw of value.facts) {
+		if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
+		const fact = raw as Record<string, unknown>;
+		const claim = reportString(fact.claim);
+		const evidence = reportString(fact.evidence);
+		if (claim === null || evidence === null || !isStringArray(fact.sources)) return null;
+		lines.push(`- ${claim}`, `  support: ${evidence}`);
+		if (fact.sources.length > 0) lines.push(`  sources: ${fact.sources.join(", ")}`);
+	}
+	if (value.synthesis.length > 0) lines.push("Synthesis:", ...value.synthesis.map((item) => `- ${item}`));
+	if (value.uncertainties.length > 0) lines.push("Uncertainties:", ...value.uncertainties.map((item) => `- ${item}`));
+	if (value.followUpVerification.length > 0) {
+		lines.push("Verify next:", ...value.followUpVerification.map((item) => `- ${item}`));
+	}
+	return { lines: lines.length === 0 ? ["No findings reported."] : lines, footer: `discovery ${value.discovery}` };
+}
+
 function scoutReport(value: Record<string, unknown>): PresentedContractAnswer | null {
 	if (!Array.isArray(value.findings) || typeof value.needsSplit !== "boolean") return null;
 	const lines: string[] = [];
@@ -250,6 +280,8 @@ function presentedContractAnswer(entry: WorkerEntryState): PresentedContractAnsw
 			return verifierReport(value);
 		case "research-report":
 			return researchReport(value);
+		case "world-knowledge-report":
+			return worldKnowledgeReport(value);
 		case "scout-report":
 			return scoutReport(value);
 	}

package/src/interactive/slash-commands.ts

@@ -28,7 +28,7 @@ import type {
 	PromptTemplateExpansion,
 	ResourceList,
 } from "../domains/resources/index.js";
-import { parseSkillCommand } from "../domains/resources/index.js";
+import { parseSkillCommand, SKILL_SURFACE_CLEAR_ARG } from "../domains/resources/index.js";
 import type { ShareImportPlan } from "../domains/share/index.js";
 import type { UserTask } from "../domains/user-tasks/store.js";
 import type { ExtensionReloadOutcome } from "../entry/extension-reload.js";
@@ -118,6 +118,8 @@ type SlashCommandVariant =
 	| { kind: "skill-selector" }
 	| { kind: "resources"; family?: "skills" | "prompts" | "extensions"; tab?: LibraryEntryKind; action?: "reload" }
 	| { kind: "skill-invocation"; text: string }
+	/** `/skill off`: drop the tool surface an activated skill armed for the session. */
+	| { kind: "skill-surface-clear" }
 	| ShareCommandVariant
 	| ArchiveCommandVariant
 	/** `source` is the line the operator typed, echoed above the run's transcript block. */
@@ -595,6 +597,12 @@ export interface SlashCommandContext {
 	 */
 	runContextRecall?: (ref: string) => void;
 	openSkillsHub?: (tab?: LibraryEntryKind) => void;
+	/**
+	 * `/skill off`: drop the tool surface an activated skill armed for the
+	 * session. Returns the names that were armed. Absent on a host with no
+	 * chat loop, where nothing can be armed in the first place.
+	 */
+	clearSkillSurface?: () => ReadonlyArray<string>;
 	listPrompts: () => ResourceList<PromptTemplate>;
 	/**
 	 * Resolve a `/name` against the loaded prompt templates. Absent when the host
@@ -912,9 +920,9 @@ export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
 	},
 	{
 		name: "skill",
-		description: "Open the Skills Hub or invoke a skill",
+		description: "Open the Skills Hub, invoke a skill, or `off` to drop an active skill's tool surface",
 		group: "Work",
-		kinds: ["skill-selector", "skill-invocation"],
+		kinds: ["skill-selector", "skill-invocation", "skill-surface-clear"],
 		args: {
 			positionals: [
 				{ name: "name", required: false },
@@ -926,16 +934,26 @@ export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
 				return { kind: "skill-selector" };
 			}
 			const command = parseSkillCommand(trimmed);
-			if (command) {
-				return { kind: "skill-invocation", text: trimmed };
+			if (!command) return null;
+			// `off` is the one reserved name: an installed skill called `off`
+			// would still be reachable from the hub, and clearing the armed
+			// surface has to stay typeable without a second command.
+			if (command.name === SKILL_SURFACE_CLEAR_ARG && command.args.length === 0) {
+				return { kind: "skill-surface-clear" };
 			}
-			return null;
+			return { kind: "skill-invocation", text: trimmed };
 		},
 		handle(command, ctx) {
 			if (command.kind === "skill-selector") {
 				ctx.openSkillsHub?.();
 			} else if (command.kind === "skill-invocation") {
 				ctx.submitChat(command.text);
+			} else if (command.kind === "skill-surface-clear") {
+				const cleared = ctx.clearSkillSurface?.() ?? [];
+				ctx.notice(
+					"info",
+					cleared.length > 0 ? `Skill tool surface cleared: ${cleared.join(", ")}.` : "No skill tool surface is active.",
+				);
 			}
 		},
 	},

package/src/interactive/theme/labels.ts

@@ -1,23 +1,29 @@
 /**
  * Abbreviate a wire model id for chips and dashboards without amputating a
- * version suffix. Whole dash-separated parts are kept while the joined result
- * stays within 18 characters, so `claude-sonnet-5` and `claude-opus-4-8`
- * survive intact and `qwen3-coder-30b-a3b-instruct` collapses to
- * `qwen3-coder-30b`. A single part longer than 18 characters is hard-clipped.
+ * meaningful placement prefix or version suffix. `dynamo/qwen3.8-27b` remains
+ * visible as selected; only the leaf is shortened when the complete route is
+ * wider than 24 characters.
  */
 export function abbreviateModelId(modelId: string | null | undefined): string {
-	const base = (modelId ?? "").trim().split("/").filter(Boolean).pop() ?? "";
+	const segments = (modelId ?? "").trim().split("/").filter(Boolean);
+	const base = segments.pop() ?? "";
 	if (base.length === 0) return "model";
+	const prefix = segments[0];
+	const maxLeaf = prefix ? Math.max(8, 24 - prefix.length - 1) : 18;
 	const parts = base.split("-").filter((part) => part.length > 0);
-	if (parts.length <= 1) return base.length > 18 ? base.slice(0, 18) : base;
-	const kept: string[] = [];
-	for (const part of parts) {
-		const next = [...kept, part].join("-");
-		if (kept.length > 0 && next.length > 18) break;
-		kept.push(part);
+	let leaf: string;
+	if (parts.length <= 1) leaf = base.length > maxLeaf ? base.slice(0, maxLeaf) : base;
+	else {
+		const kept: string[] = [];
+		for (const part of parts) {
+			const next = [...kept, part].join("-");
+			if (kept.length > 0 && next.length > maxLeaf) break;
+			kept.push(part);
+		}
+		const joined = kept.join("-");
+		leaf = joined.length > maxLeaf ? joined.slice(0, maxLeaf) : joined;
 	}
-	const joined = kept.join("-");
-	return joined.length > 18 ? joined.slice(0, 18) : joined;
+	return prefix ? `${prefix}/${leaf}` : leaf;
 }
 
 export interface TargetLabelOptions {

package/src/interactive/turn-context.ts

@@ -641,8 +641,8 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 		if (!usage || !deps.observability) return;
 		if (usage.totalTokens <= 0 && usage.cost.total <= 0) return;
 		deps.observability.recordTokens(
-			agentRuntime.targetId,
-			agentRuntime.wireModelId,
+			usage.targetId ?? agentRuntime.targetId,
+			usage.modelId ?? agentRuntime.wireModelId,
 			usage.totalTokens,
 			usage.cost.total,
 			{
@@ -654,7 +654,11 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 				totalTokens: usage.totalTokens,
 				apiCalls: Math.max(1, Math.round(usage.apiCalls)),
 			},
-			agentRuntime.runtimeResolution.costProvenance,
+			usage.targetId === undefined && usage.modelId === undefined
+				? agentRuntime.runtimeResolution.costProvenance
+				: usage.cost.total > 0
+					? "estimated"
+					: "unknown",
 		);
 	};
 
@@ -915,8 +919,8 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 		if (!summaryLifecycleStarted) startSummaryLifecycle();
 		deps.bus?.emit(BusChannels.CompactionEnd, { trigger, at: Date.now() });
 
-		// The summarization call spends tokens on the same target the turn would
-		// have. The ledger entry carries its usage for a later reseed; this is the
+		// The checkpoint identifies the selected summary route; older results
+		// fall back to the active chat route. The ledger carries usage for reseed; this is the
 		// live sink, so `/cost` and the footer move the moment /context compact
 		// returns instead of staying byte-identical to before it ran.
 		recordCompactionUsage(agentRuntime, result);

package/src/interactive/turn-recovery.ts

@@ -217,6 +217,14 @@ export function createTurnRecovery(deps: TurnRecoveryDeps): TurnRecovery {
 		text: string,
 		initialFailure: TerminalAssistantFailure,
 	): Promise<boolean> => {
+		// A LiteLLM model id can be a deliberate physical route. Retrying it in
+		// Clio obscures the failure, delays operator recovery, and can multiply
+		// attempts beneath a gateway. Preserve and emit the one terminal failure;
+		// the operator can choose another advertised route with /model.
+		if (agentRuntime.runtimeId === "litellm") {
+			ensureFailureVisibleAndPersisted(initialFailure);
+			return true;
+		}
 		const settings = deps.retrySettings();
 		if (!settings.enabled || settings.maxRetries <= 0) return false;
 		if (initialFailure.stopReason === "aborted" || !isRetryableErrorMessage(initialFailure.errorMessage)) return false;

package/src/interactive/turn-runtime.ts

@@ -8,6 +8,7 @@
 import { performance } from "node:perf_hooks";
 import type { BackendCompletionTimings } from "../core/cache-telemetry.js";
 import type { ClioSettings } from "../core/config.js";
+import { gatewayRoutingObservationFromRecord, gatewayRoutingObservationLabel } from "../core/gateway-routing.js";
 import { attributedModelId } from "../core/response-model-id.js";
 import type { MiddlewareToolChoiceControl } from "../domains/middleware/index.js";
 import type { ObservabilityContract } from "../domains/observability/contract.js";
@@ -130,6 +131,8 @@ export interface TurnRuntimeDeps {
 	context: TurnContext;
 	middleware: TurnMiddleware;
 	retrySettings: () => RetrySettings;
+	/** Stable Clio session id forwarded only to gateway runtimes that understand it. */
+	sessionId?: () => string | undefined;
 	emit: (event: AgentEvent | AssistantDeltaEvent) => void;
 	emitNotice: (text: string) => void;
 	/** Tool-call id to its `performance.now()` start mark; spans only, never an instant. */
@@ -447,6 +450,11 @@ export function createTurnRuntime(deps: TurnRuntimeDeps): TurnRuntime {
 			cleanupSessionResources(state.runtime.agent.sessionId);
 		}
 		let getCurrentAgentSignal: () => AbortSignal | undefined = () => undefined;
+		const gatewaySessionId = target.runtime.id === "litellm" ? deps.sessionId?.() : undefined;
+		// message_start can follow response headers. Keep each invocation's
+		// monotonic anchor before that wait, including custom stream delegates.
+		let apiCallStartedAt: number | null = null;
+		let apiCallFirstDeltaAt: number | null = null;
 		const handle = deps.createAgent({
 			initialState: {
 				systemPrompt: fallbackIdentityPrompt(),
@@ -456,6 +464,11 @@ export function createTurnRuntime(deps: TurnRuntimeDeps): TurnRuntime {
 				messages: priorMessages,
 			},
 			maxRetryDelayMs: deps.retrySettings().maxDelayMs,
+			...(gatewaySessionId ? { sessionId: gatewaySessionId } : {}),
+			onStreamInvocation: () => {
+				apiCallStartedAt = performance.now();
+				apiCallFirstDeltaAt = null;
+			},
 			onPayload: async (payload, currentModel) => {
 				const thinkingPatched = patchProviderThinkingPayload(payload, currentModel, state.currentThinkingLevel);
 				const basePayload = thinkingPatched ?? payload;
@@ -575,10 +588,6 @@ export function createTurnRuntime(deps: TurnRuntimeDeps): TurnRuntime {
 
 		let streamStartedAt: number | null = null;
 		let firstAssistantDeltaAt: number | null = null;
-		// Per-API-call timing (T3.2): one assistant message per provider call,
-		// bounded by message_start/message_end; the first delta marks TTFT.
-		let apiCallStartedAt: number | null = null;
-		let apiCallFirstDeltaAt: number | null = null;
 		// First call of the run is the one whose verdict says whether the
 		// backend reused the session prefix; later calls in a tool loop are
 		// trivially warm.
@@ -669,6 +678,15 @@ export function createTurnRuntime(deps: TurnRuntimeDeps): TurnRuntime {
 			}
 			let publicEvent = enrichedEvent;
 			if (enrichedEvent.type === "message_end" && enrichedEvent.message?.role === "assistant") {
+				const gatewayRouting = gatewayRoutingObservationFromRecord(
+					enrichedEvent.message as unknown as Record<string, unknown>,
+				);
+				if (
+					gatewayRouting !== null &&
+					((gatewayRouting.attemptedFallbacks ?? 0) > 0 || (gatewayRouting.attemptedRetries ?? 0) > 0)
+				) {
+					deps.emitNotice(`[Clio Coder] ${gatewayRoutingObservationLabel(gatewayRouting)}`);
+				}
 				const interruptedUsage = estimatedUsageForInterruptedTurn(enrichedEvent.message, context.promptSideTokens());
 				if (interruptedUsage !== null) {
 					// Persistence records the same estimate, but it does so after the
@@ -718,17 +736,15 @@ export function createTurnRuntime(deps: TurnRuntimeDeps): TurnRuntime {
 			// mediator, a dropped frame) therefore stops suspending the watchdog
 			// at the turn that issued it instead of for the rest of the run.
 			if (publicEvent?.type === "turn_end") toolsInFlight = 0;
-			if (publicEvent?.type === "message_start" && publicEvent.message?.role === "assistant") {
-				apiCallStartedAt = eventClock;
-				apiCallFirstDeltaAt = null;
-			}
 			if (publicEvent?.type === "message_update") {
 				const assistantEvent = publicEvent.assistantMessageEvent as { type?: string; delta?: unknown };
 				const hasDelta =
-					assistantEvent.type === "text_delta" ||
-					assistantEvent.type === "thinking_delta" ||
 					assistantEvent.type === "toolcall_start" ||
-					assistantEvent.type === "toolcall_delta";
+					((assistantEvent.type === "text_delta" ||
+						assistantEvent.type === "thinking_delta" ||
+						assistantEvent.type === "toolcall_delta") &&
+						typeof assistantEvent.delta === "string" &&
+						assistantEvent.delta.length > 0);
 				if (hasDelta && firstAssistantDeltaAt === null) firstAssistantDeltaAt = eventClock;
 				if (hasDelta && apiCallFirstDeltaAt === null) apiCallFirstDeltaAt = eventClock;
 			}

package/src/interactive/turn-state.ts

@@ -127,6 +127,12 @@ export interface ChatTurnState {
 	/** A middleware request_continuation is waiting to resubmit after settle. */
 	pendingRequestContinuation: boolean;
 	currentPendingSkillPolicy: PendingSkillToolPolicy | undefined;
+	/**
+	 * Tool surface an activated skill narrowed, held across the operator's
+	 * later turns. Replaced when the operator activates a different skill,
+	 * cleared by `/skill off`, gone with the session.
+	 */
+	activeSkillSurface: PendingSkillToolPolicy | undefined;
 	currentAskUserPolicy: AskUserToolPolicy | undefined;
 	lastRunSnapshot: ChatLoopRunSnapshot | null;
 }
@@ -153,6 +159,7 @@ export function createTurnState(initialThinkingLevel: ThinkingLevel): ChatTurnSt
 		stalledTurnNudgeSpent: false,
 		pendingRequestContinuation: false,
 		currentPendingSkillPolicy: undefined,
+		activeSkillSurface: undefined,
 		currentAskUserPolicy: undefined,
 		lastRunSnapshot: null,
 	};

package/src/interactive/worker-receipts.ts

@@ -59,6 +59,7 @@ const PRESENTED_RESULT_CONTRACTS: ReadonlyArray<WorkerPresentedResultContract> =
 	"debugger-report",
 	"verifier-report",
 	"research-report",
+	"world-knowledge-report",
 	"scout-report",
 ];