@iowarp/clio-coder 0.4.2 → 0.4.3

package/src/cli/usage.ts

@@ -8,6 +8,7 @@ import {
 } from "../core/response-model-id.js";
 import { clioDataDir, clioStateDir } from "../core/xdg.js";
 import { loadMemoryRecordsSync, type MemoryRecord } from "../domains/memory/index.js";
+import { summarizeFailedCompactionUsage } from "../domains/observability/compaction-usage.js";
 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";
@@ -119,18 +120,32 @@ interface CallOrigins {
 	handoffs: number;
 	prewarms: number;
 	backgroundMemory: number;
+	failedCompaction: number;
 }
 
 function emptyCallOrigins(): CallOrigins {
-	return { rows: 0, sideQuestions: 0, handoffs: 0, prewarms: 0, backgroundMemory: 0 };
+	return { rows: 0, sideQuestions: 0, handoffs: 0, prewarms: 0, backgroundMemory: 0, failedCompaction: 0 };
 }
 
 function turnsOf(origins: CallOrigins): number {
-	return origins.rows - origins.sideQuestions - origins.handoffs - origins.prewarms - origins.backgroundMemory;
+	return (
+		origins.rows -
+		origins.sideQuestions -
+		origins.handoffs -
+		origins.prewarms -
+		origins.backgroundMemory -
+		origins.failedCompaction
+	);
 }
 
 function hasLabelledCall(origins: CallOrigins): boolean {
-	return origins.sideQuestions > 0 || origins.handoffs > 0 || origins.prewarms > 0 || origins.backgroundMemory > 0;
+	return (
+		origins.sideQuestions > 0 ||
+		origins.handoffs > 0 ||
+		origins.prewarms > 0 ||
+		origins.backgroundMemory > 0 ||
+		origins.failedCompaction > 0
+	);
 }
 
 function addOutOfTurnRow(origins: CallOrigins, row: OutOfTurnUsageRow): void {
@@ -138,6 +153,7 @@ function addOutOfTurnRow(origins: CallOrigins, row: OutOfTurnUsageRow): void {
 	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 if (row.label === "failed-compaction") origins.failedCompaction += 1;
 	else origins.handoffs += 1;
 }
 
@@ -148,16 +164,32 @@ function outOfTurnUsageCall(row: OutOfTurnUsageRow): LedgerUsageCall {
 		attributedModelId: row.attributedModelId,
 		requestedModelId: row.attributedModelId,
 		responseModelIdObservation: { state: "not-observed" },
-		input: row.usage.input,
-		output: row.usage.output,
-		cacheRead: row.usage.cacheRead,
-		cacheWrite: row.usage.cacheWrite,
-		reasoningTokens: row.usage.reasoning,
-		totalTokens: row.usage.totalTokens,
-		costUsd: row.usage.costUsd,
+		input: row.usage.input ?? 0,
+		output: row.usage.output ?? 0,
+		cacheRead: row.usage.cacheRead ?? 0,
+		cacheWrite: row.usage.cacheWrite ?? 0,
+		reasoningTokens: row.usage.reasoning ?? 0,
+		totalTokens: row.usage.totalTokens ?? 0,
+		costUsd: row.usage.costUsd ?? 0,
 	};
 }
 
+/** Existing numeric accumulators sum known contributions; the report retains missing coverage. */
+function reportedUsageTotals(totals: UsageTotals, rows: ReadonlyArray<OutOfTurnUsageRow>) {
+	const failedCompaction = summarizeFailedCompactionUsage(rows);
+	if (failedCompaction.calls === 0) return totals;
+	const reported: Record<string, unknown> = { ...totals, knownSubtotals: true, failedCompaction };
+	for (const [field, missing] of Object.entries(failedCompaction.unobservedUsageCalls)) {
+		const key = field === "reasoning" ? "reasoningTokens" : field;
+		if (missing > 0 && reported[key] === 0) reported[key] = null;
+	}
+	return reported;
+}
+
+function usageAmount(value: unknown): string {
+	return typeof value === "number" ? String(value) : "unknown";
+}
+
 function addUsageCall(totals: UsageTotals, call: LedgerUsageCall): void {
 	totals.apiCalls += call.apiCalls ?? 1;
 	totals.input += call.input;
@@ -442,6 +474,8 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 	// session store is gone can still have recorded out-of-turn spend, and
 	// dropping those rows would report money that was spent as nothing at all.
 	const usageMeasurable = presence.sessionsPresent || outOfTurnRows.length > 0;
+	const reportedTotals = reportedUsageTotals(usageTotals, outOfTurnRows);
+	const failedCompaction = summarizeFailedCompactionUsage(outOfTurnRows);
 	const usageRows = [...usageByModel.values()].sort(
 		(a, b) => b.totals.totalTokens - a.totals.totalTokens || a.providerId.localeCompare(b.providerId),
 	);
@@ -533,7 +567,7 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 			emit({
 				kind: "fact",
 				fact: "tokens",
-				...usageTotals,
+				...reportedTotals,
 				...(hasLabelledCall(callOrigins)
 					? {
 							turns: turnsOf(callOrigins),
@@ -541,6 +575,7 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 							handoffs: callOrigins.handoffs,
 							prewarms: callOrigins.prewarms,
 							backgroundMemorySteps: callOrigins.backgroundMemory,
+							...(callOrigins.failedCompaction > 0 ? { failedCompactionCalls: callOrigins.failedCompaction } : {}),
 						}
 					: {}),
 			});
@@ -552,7 +587,12 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 					attributedModelId: row.attributedModelId,
 					requestedModelIds: [...row.requestedModelIds].sort(),
 					responseModelIdObservationCounts: row.responseModelIdObservationCounts,
-					...row.totals,
+					...reportedUsageTotals(
+						row.totals,
+						outOfTurnRows.filter(
+							(call) => call.target === row.providerId && call.attributedModelId === row.attributedModelId,
+						),
+					),
 				});
 			}
 			for (const session of cacheSessions) {
@@ -615,7 +655,7 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 	out(`  audited tool calls in window: ${auditToolCalls.length} (${auditBlocked.length} blocked/denied)`);
 	if (usageMeasurable) {
 		out(
-			`  tokens in window: ${usageTotals.totalTokens} over ${usageTotals.apiCalls} model calls (input ${usageTotals.input}, output ${usageTotals.output}, cache read ${usageTotals.cacheRead}, cache write ${usageTotals.cacheWrite}, reasoning ${usageTotals.reasoningTokens})`,
+			`  tokens in window: ${usageAmount(reportedTotals.totalTokens)} over ${usageTotals.apiCalls} model calls (input ${usageAmount(reportedTotals.input)}, output ${usageAmount(reportedTotals.output)}, cache read ${usageAmount(reportedTotals.cacheRead)}, cache write ${usageAmount(reportedTotals.cacheWrite)}, reasoning ${usageAmount(reportedTotals.reasoningTokens)})`,
 		);
 		if (hasLabelledCall(callOrigins)) {
 			// Only printed when a labelled call is in the window. Over an archive
@@ -629,7 +669,18 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 				out(`  background memory steps in window: ${callOrigins.backgroundMemory}`);
 			}
 		}
-		out(`  provider-reported cost in window: $${usageTotals.costUsd.toFixed(4)}`);
+		if (failedCompaction.calls > 0) {
+			out(
+				`  failed-compaction streams: ${failedCompaction.calls} (${failedCompaction.erroredCalls} errored, ${failedCompaction.abortedCalls} aborted, ${failedCompaction.successfulCalls} completed before the attempt failed)`,
+			);
+			out("  usage figures are known subtotals; missing compaction usage is not zero or a complete spending bound");
+			out(
+				`  errored compaction known cost: ${failedCompaction.erroredKnownUsage.costUsd === null ? "unknown" : `$${failedCompaction.erroredKnownUsage.costUsd.toFixed(4)}`}`,
+			);
+		}
+		out(
+			`  ${failedCompaction.calls > 0 ? "known reported/estimated" : "provider-reported"} cost in window: ${typeof reportedTotals.costUsd === "number" ? `$${reportedTotals.costUsd.toFixed(4)}` : "unknown"}`,
+		);
 	}
 	if (usageRows.length > 0) {
 		out("");
@@ -650,19 +701,27 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 						"tokens",
 						"cost",
 					],
-					...usageRows.map((row) => [
-						row.providerId,
-						row.attributedModelId,
-						[...row.requestedModelIds].sort().join(","),
-						responseModelIdObservationCountsLabel(row.responseModelIdObservationCounts),
-						String(row.totals.apiCalls),
-						String(row.totals.input),
-						String(row.totals.output),
-						String(row.totals.cacheRead),
-						String(row.totals.reasoningTokens),
-						String(row.totals.totalTokens),
-						`$${row.totals.costUsd.toFixed(4)}`,
-					]),
+					...usageRows.map((row) => {
+						const reported = reportedUsageTotals(
+							row.totals,
+							outOfTurnRows.filter(
+								(call) => call.target === row.providerId && call.attributedModelId === row.attributedModelId,
+							),
+						);
+						return [
+							row.providerId,
+							row.attributedModelId,
+							[...row.requestedModelIds].sort().join(","),
+							responseModelIdObservationCountsLabel(row.responseModelIdObservationCounts),
+							String(row.totals.apiCalls),
+							usageAmount(reported.input),
+							usageAmount(reported.output),
+							usageAmount(reported.cacheRead),
+							usageAmount(reported.reasoningTokens),
+							usageAmount(reported.totalTokens),
+							typeof reported.costUsd === "number" ? `$${reported.costUsd.toFixed(4)}` : "unknown",
+						];
+					}),
 				]),
 			),
 		);

package/src/cli/validate-model.ts

@@ -15,9 +15,8 @@ export interface ValidateModelInput {
 	modelId: string;
 	knownModels: ReadonlyArray<string>;
 	/**
-	 * The live list, when one was fetched. It is consulted only when the static
-	 * catalog is empty, so the catalog stays the authority for cloud runtimes
-	 * and the probe becomes the authority where there is nothing else.
+	 * The live list, when one was fetched. Callers provide it only when that
+	 * runtime declares live discovery authoritative for the concrete target.
 	 */
 	live?: LiveModelInventory | undefined;
 	force: boolean;
@@ -50,6 +49,7 @@ function formatUnadvertisedModelReason(modelId: string, live: LiveModelInventory
 
 export function validateModelChoice(input: ValidateModelInput): ValidateModelResult {
 	const { runtimeId, modelId, knownModels, live, force } = input;
+	if (live !== undefined) return validateAgainstLive(modelId, live, force);
 	if (knownModels.length === 0) return validateAgainstLive(modelId, live, force);
 	if (knownModels.includes(modelId)) return { ok: true };
 	if (force) {

package/src/core/config.ts

@@ -525,6 +525,57 @@ function validateLmStudioSettings(
 	return Object.keys(out).length > 0 ? out : undefined;
 }
 
+function validateLiteLLMSettings(
+	issues: Issues,
+	path: string,
+	value: unknown,
+): ClioSettings["targets"][number]["litellm"] | undefined {
+	if (!isPlainObject(value)) {
+		issues.add(path, `expected a map, got ${describe(value)}`);
+		return undefined;
+	}
+	issues.unknownKeys(path, value, ["request"]);
+	const out: NonNullable<ClioSettings["targets"][number]["litellm"]> = {};
+	if ("request" in value) {
+		if (!isPlainObject(value.request)) {
+			issues.add(`${path}.request`, `expected a map, got ${describe(value.request)}`);
+		} else {
+			issues.unknownKeys(`${path}.request`, value.request, [
+				"tags",
+				"sendSessionId",
+				"timeoutSeconds",
+				"streamTimeoutSeconds",
+				"numRetries",
+			]);
+			const request: NonNullable<typeof out.request> = {};
+			if ("tags" in value.request) {
+				const parsed = expectStringArray(issues, `${path}.request.tags`, value.request.tags);
+				if (parsed !== undefined) {
+					const invalidTag = parsed.find((tag) => tag.includes(","));
+					if (invalidTag) issues.add(`${path}.request.tags`, "tags may not contain commas");
+					else if (parsed.length > 0) request.tags = [...new Set(parsed)];
+				}
+			}
+			if ("sendSessionId" in value.request) {
+				const parsed = expectBoolean(issues, `${path}.request.sendSessionId`, value.request.sendSessionId);
+				if (parsed !== undefined) request.sendSessionId = parsed;
+			}
+			for (const key of ["timeoutSeconds", "streamTimeoutSeconds"] as const) {
+				if (key in value.request) {
+					const parsed = expectNumber(issues, `${path}.request.${key}`, value.request[key], { min: 0.001, max: 86_400 });
+					if (parsed !== undefined) request[key] = parsed;
+				}
+			}
+			if ("numRetries" in value.request) {
+				const parsed = expectInteger(issues, `${path}.request.numRetries`, value.request.numRetries, { min: 0, max: 100 });
+				if (parsed !== undefined) request.numRetries = parsed;
+			}
+			if (Object.keys(request).length > 0) out.request = request;
+		}
+	}
+	return Object.keys(out).length > 0 ? out : undefined;
+}
+
 function validateTarget(issues: Issues, path: string, value: unknown): ClioSettings["targets"][number] | null {
 	if (!isPlainObject(value)) {
 		issues.add(path, `expected a map, got ${describe(value)}`);
@@ -542,6 +593,7 @@ function validateTarget(issues: Issues, path: string, value: unknown): ClioSetti
 		"gateway",
 		"pricing",
 		"lmstudio",
+		"litellm",
 		"maxConcurrentRequests",
 	]);
 	const id = "id" in value ? expectString(issues, `${path}.id`, value.id) : undefined;
@@ -593,6 +645,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 ("litellm" in value) {
+		const v = validateLiteLLMSettings(issues, `${path}.litellm`, value.litellm);
+		if (v !== undefined) target.litellm = v;
+	}
 	if ("maxConcurrentRequests" in value) {
 		const v = expectInteger(issues, `${path}.maxConcurrentRequests`, value.maxConcurrentRequests, { min: 1 });
 		if (v !== undefined) target.maxConcurrentRequests = v;

package/src/core/external-diagnostic.ts

@@ -0,0 +1,44 @@
+const REDACTED = "[redacted]";
+
+/**
+ * Sanitize free-form text received from an external process before it crosses
+ * into errors, receipts, transcripts, evidence, or model-catalog snapshots.
+ */
+function redactExternalDiagnostic(input: string): string {
+	return input
+		.replace(/\b(?:authorization|proxy-authorization)\s*:\s*[^\r\n]+/giu, `Authorization: ${REDACTED}`)
+		.replace(/\b(?:set-cookie|cookie)\s*:\s*[^\r\n]+/giu, `Cookie: ${REDACTED}`)
+		.replace(/\bbearer\s+[A-Za-z0-9._~+/-]+=*/giu, `Bearer ${REDACTED}`)
+		.replace(
+			/\b(?:api[_-]?key|access[_-]?token|refresh[_-]?token|token|secret|password)\s*[:=]\s*[^\s,;]+/giu,
+			(match) => {
+				const separator = match.includes(":") ? ":" : "=";
+				return `${match.slice(0, match.indexOf(separator)).trim()}${separator}${REDACTED}`;
+			},
+		)
+		.replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/gu, REDACTED)
+		.replace(
+			/(?:~|\/[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*)\/\.(?:gemini\/antigravity-cli|antigravitycli)(?:\/[^\s]*)?/gu,
+			"[redacted credential path]",
+		)
+		.replace(/https?:\/\/[^\s"'<>]+/giu, (url) => {
+			try {
+				const parsed = new URL(url);
+				if (/(?:auth|oauth|login|signin|callback)/iu.test(parsed.pathname)) return "[redacted authorization URL]";
+				parsed.username = "";
+				parsed.password = "";
+				parsed.search = "";
+				parsed.hash = "";
+				return parsed.toString();
+			} catch {
+				return REDACTED;
+			}
+		});
+}
+
+export function boundedExternalDiagnostic(input: string, maxBytes = 8192): string {
+	const redacted = redactExternalDiagnostic(input).trim();
+	const bytes = Buffer.from(redacted, "utf8");
+	if (bytes.byteLength <= maxBytes) return redacted;
+	return `${bytes.subarray(0, Math.max(0, maxBytes - 32)).toString("utf8")}\n[diagnostic truncated]`;
+}

package/src/core/gateway-routing.ts

@@ -0,0 +1,157 @@
+/**
+ * Durable routing facts reported by an AI gateway for one upstream response.
+ *
+ * The gateway is authoritative for the physical deployment that served an
+ * alias. Clio deliberately records only the host portion of an upstream API
+ * base: LiteLLM deployments may embed paths, query credentials, or user-info
+ * in the configured URL, none of which belongs in a session or sealed receipt.
+ */
+export interface LiteLLMGatewayRoutingObservation {
+	gateway: "litellm";
+	callId?: string;
+	modelGroup?: string;
+	modelName?: string;
+	apiBaseHost?: string;
+	deploymentId?: string;
+	attemptedFallbacks?: number;
+	attemptedRetries?: number;
+	overheadMs?: number;
+	responseDurationMs?: number;
+	version?: string;
+}
+
+export type GatewayRoutingObservation = LiteLLMGatewayRoutingObservation;
+
+/**
+ * Preserve the provider's diagnostic while making Clio's failure policy
+ * explicit and actionable. LiteLLM targets deliberately do not enter Clio's
+ * transient retry ladder: a named route is an operator choice, not permission
+ * to substitute another model behind their back.
+ */
+export function liteLLMRouteFailureMessage(
+	errorMessage: string | null | undefined,
+	targetId: string,
+	modelId: string,
+): string {
+	const providerMessage = errorMessage?.trim() || "LiteLLM request failed.";
+	const advice =
+		`LiteLLM route '${modelId}' on target '${targetId}' failed. ` +
+		"Clio did not retry or substitute another model; select a different route with /model, then resend.";
+	return providerMessage.includes(advice) ? providerMessage : `${providerMessage}\n\n${advice}`;
+}
+
+interface HeaderReader {
+	get(name: string): string | null;
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+	return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+function nonnegativeNumber(value: unknown): number | undefined {
+	if (typeof value === "number" && Number.isFinite(value) && value >= 0) return value;
+	if (typeof value !== "string" || value.trim().length === 0) return undefined;
+	const parsed = Number(value);
+	return Number.isFinite(parsed) && parsed >= 0 ? parsed : undefined;
+}
+
+function nonnegativeInteger(value: unknown): number | undefined {
+	const parsed = nonnegativeNumber(value);
+	return parsed === undefined ? undefined : Math.floor(parsed);
+}
+
+function apiBaseHost(value: unknown): string | undefined {
+	const raw = nonEmptyString(value);
+	if (raw === undefined) return undefined;
+	try {
+		return new URL(raw).host || undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function storedApiBaseHost(value: unknown): string | undefined {
+	const raw = nonEmptyString(value);
+	if (raw === undefined) return undefined;
+	try {
+		return new URL(raw.includes("://") ? raw : `http://${raw}`).host || undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Read LiteLLM's response headers without retaining sensitive API-base data. */
+export function liteLLMGatewayRoutingFromHeaders(headers: HeaderReader): GatewayRoutingObservation | null {
+	const callId = nonEmptyString(headers.get("x-litellm-call-id"));
+	const modelGroup = nonEmptyString(headers.get("x-litellm-model-group"));
+	const modelName = nonEmptyString(headers.get("x-litellm-model-name"));
+	const host = apiBaseHost(headers.get("x-litellm-model-api-base"));
+	const deploymentId = nonEmptyString(headers.get("x-litellm-model-id"));
+	const attemptedFallbacks = nonnegativeInteger(headers.get("x-litellm-attempted-fallbacks"));
+	const attemptedRetries = nonnegativeInteger(headers.get("x-litellm-attempted-retries"));
+	const overheadMs = nonnegativeNumber(headers.get("x-litellm-overhead-duration-ms"));
+	const responseDurationMs = nonnegativeNumber(headers.get("x-litellm-response-duration-ms"));
+	const version = nonEmptyString(headers.get("x-litellm-version"));
+	const observation: GatewayRoutingObservation = {
+		gateway: "litellm",
+		...(callId !== undefined ? { callId } : {}),
+		...(modelGroup !== undefined ? { modelGroup } : {}),
+		...(modelName !== undefined ? { modelName } : {}),
+		...(host !== undefined ? { apiBaseHost: host } : {}),
+		...(deploymentId !== undefined ? { deploymentId } : {}),
+		...(attemptedFallbacks !== undefined ? { attemptedFallbacks } : {}),
+		...(attemptedRetries !== undefined ? { attemptedRetries } : {}),
+		...(overheadMs !== undefined ? { overheadMs } : {}),
+		...(responseDurationMs !== undefined ? { responseDurationMs } : {}),
+		...(version !== undefined ? { version } : {}),
+	};
+	return Object.keys(observation).length > 1 ? observation : null;
+}
+
+/** Parse a live message, persisted session row, or receipt response defensively. */
+export function gatewayRoutingObservationFromRecord(
+	record: Readonly<Record<string, unknown>>,
+): GatewayRoutingObservation | null {
+	const value = record.gatewayRouting;
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return null;
+	const raw = value as Record<string, unknown>;
+	if (raw.gateway !== "litellm") return null;
+	const callId = nonEmptyString(raw.callId);
+	const modelGroup = nonEmptyString(raw.modelGroup);
+	const modelName = nonEmptyString(raw.modelName);
+	const host = storedApiBaseHost(raw.apiBaseHost);
+	const deploymentId = nonEmptyString(raw.deploymentId);
+	const attemptedFallbacks = nonnegativeInteger(raw.attemptedFallbacks);
+	const attemptedRetries = nonnegativeInteger(raw.attemptedRetries);
+	const overheadMs = nonnegativeNumber(raw.overheadMs);
+	const responseDurationMs = nonnegativeNumber(raw.responseDurationMs);
+	const version = nonEmptyString(raw.version);
+	const observation: GatewayRoutingObservation = {
+		gateway: "litellm",
+		...(callId !== undefined ? { callId } : {}),
+		...(modelGroup !== undefined ? { modelGroup } : {}),
+		...(modelName !== undefined ? { modelName } : {}),
+		...(host !== undefined ? { apiBaseHost: host } : {}),
+		...(deploymentId !== undefined ? { deploymentId } : {}),
+		...(attemptedFallbacks !== undefined ? { attemptedFallbacks } : {}),
+		...(attemptedRetries !== undefined ? { attemptedRetries } : {}),
+		...(overheadMs !== undefined ? { overheadMs } : {}),
+		...(responseDurationMs !== undefined ? { responseDurationMs } : {}),
+		...(version !== undefined ? { version } : {}),
+	};
+	return Object.keys(observation).length > 1 ? observation : null;
+}
+
+/** Compact human projection for receipts and operator notices. */
+export function gatewayRoutingObservationLabel(observation: GatewayRoutingObservation): string {
+	const route = [observation.modelGroup, observation.modelName].filter(Boolean).join("->");
+	const destination = [route, observation.apiBaseHost ? `@${observation.apiBaseHost}` : ""].filter(Boolean).join("");
+	const parts = [
+		"gateway=litellm",
+		...(destination ? [`route=${destination}`] : []),
+		...(observation.attemptedFallbacks !== undefined ? [`fallbacks=${observation.attemptedFallbacks}`] : []),
+		...(observation.attemptedRetries !== undefined ? [`retries=${observation.attemptedRetries}`] : []),
+		...(observation.overheadMs !== undefined ? [`overhead_ms=${observation.overheadMs}`] : []),
+	];
+	return parts.join(" ");
+}

package/src/core/safe-exec.ts

@@ -24,6 +24,18 @@ const ENV_ALLOWLIST = [
 	"TMP",
 	"CI",
 	"NO_COLOR",
+	// Platform/session location variables needed by installed local CLIs. These
+	// locate operator-owned state; provider keys and Clio gates are deliberately
+	// absent from this allowlist.
+	"XDG_CONFIG_HOME",
+	"XDG_CACHE_HOME",
+	"XDG_STATE_HOME",
+	"APPDATA",
+	"LOCALAPPDATA",
+	"SYSTEMROOT",
+	"WINDIR",
+	"COMSPEC",
+	"PATHEXT",
 ] as const;
 
 export interface SafeCommandResult {
@@ -49,10 +61,13 @@ export interface RunCommandVectorOptions {
 	env?: Record<string, string>;
 }
 
-export function buildSafeToolEnv(extra: Record<string, string> = {}): NodeJS.ProcessEnv {
+export function buildSafeToolEnv(
+	extra: Record<string, string> = {},
+	source: NodeJS.ProcessEnv = process.env,
+): NodeJS.ProcessEnv {
 	const env: NodeJS.ProcessEnv = {};
 	for (const key of ENV_ALLOWLIST) {
-		const value = process.env[key];
+		const value = source[key];
 		if (value !== undefined) env[key] = value;
 	}
 	for (const [key, value] of Object.entries(extra)) {

package/src/core/skill-activation.ts

@@ -58,6 +58,90 @@ export interface PendingSkillToolPolicy {
 	loadedSkillNames: Set<string>;
 	/** Declared tool policy per successfully loaded skill, recorded by context(scope=skills). */
 	loadedSkillPolicies: Map<string, SkillDeclaredToolPolicy>;
+	/**
+	 * True once this policy is a surface that outlived the turn that armed it.
+	 * The narrowing is identical; the flag exists so a load request the policy
+	 * does not cover reads as "only the operator activates skills" rather than
+	 * claiming a pending request that no longer exists.
+	 */
+	carriedSurface?: boolean;
+	/**
+	 * True when the session's autonomy level lets the model activate an
+	 * installed skill itself instead of emitting the suggestion anchor and
+	 * waiting for `/skill`. Activation is the same per-run policy the operator's
+	 * path produces: skills only ever narrow the tool surface, so this grants
+	 * nothing the level had not already granted. Marketplace (not yet
+	 * installed) skills stay operator-gated at every level.
+	 */
+	modelActivation?: boolean;
+}
+
+/**
+ * The surface that stays armed after an interactive turn ends.
+ *
+ * A skill an operator loaded narrows the tools for the workflow it started,
+ * and a multi-turn workflow (an interview skill asking a question per turn)
+ * is still inside that workflow on the operator's next message. Dropping the
+ * narrowing at turn end handed the workflow back the full surface partway
+ * through, which is how a `bash` call correctly refused in turn one ran in
+ * turn six. Returns undefined when nothing declared a narrowing, which is the
+ * signal to clear whatever surface was armed before.
+ */
+export function armedSkillSurface(policy: PendingSkillToolPolicy | undefined): PendingSkillToolPolicy | undefined {
+	if (!policy) return undefined;
+	const declared = [...policy.loadedSkillPolicies.entries()].filter(
+		([, declaration]) => (declaration.allowedTools?.length ?? 0) > 0 || (declaration.disallowedTools?.length ?? 0) > 0,
+	);
+	if (declared.length === 0) return undefined;
+	return {
+		allowedSkillNames: [...policy.allowedSkillNames],
+		requests: [...policy.requests],
+		loadedSkillNames: new Set(policy.loadedSkillNames),
+		loadedSkillPolicies: new Map(declared),
+		carriedSurface: true,
+	};
+}
+
+/** Skill names contributing a declaration to an armed surface, for the operator notice. */
+export function skillSurfaceNames(policy: PendingSkillToolPolicy | undefined): ReadonlyArray<string> {
+	return policy ? [...policy.loadedSkillPolicies.keys()] : [];
+}
+
+/**
+ * The same names, each tagged with who activated it. A skill the operator
+ * named arrives as a pending request; anything else was activated by the model
+ * under `modelActivation`, and the operator's one line about the surface is
+ * where that distinction has to be visible.
+ */
+export function skillSurfaceLabels(policy: PendingSkillToolPolicy | undefined): ReadonlyArray<string> {
+	if (!policy) return [];
+	return [...policy.loadedSkillPolicies.keys()].map((name) =>
+		policy.requests.some((request) => request.name === name) ? `${name} (operator)` : `${name} (model)`,
+	);
+}
+
+/**
+ * Stamp (or clear) the model-activation grant on the policy this turn runs
+ * under, creating one when nothing else did. Mutates in place so a surface
+ * carried from an earlier turn keeps its identity, and re-stamps every turn so
+ * a level change takes effect on the next message rather than the next skill.
+ */
+export function withModelSkillActivation(
+	policy: PendingSkillToolPolicy | undefined,
+	enabled: boolean,
+): PendingSkillToolPolicy | undefined {
+	if (policy) {
+		policy.modelActivation = enabled;
+		return policy;
+	}
+	if (!enabled) return undefined;
+	return {
+		allowedSkillNames: [],
+		requests: [],
+		loadedSkillNames: new Set<string>(),
+		loadedSkillPolicies: new Map<string, SkillDeclaredToolPolicy>(),
+		modelActivation: true,
+	};
 }
 
 /**
@@ -75,6 +159,8 @@ export interface SkillToolSurfaceViolation {
 	mergedAllowedTools: ReadonlyArray<string> | null;
 	/** Skills whose disallowed-tools name the tool directly. */
 	disallowedBy: ReadonlyArray<string>;
+	/** True when the surface outlived the turn that armed it, which changes the lifetime the block message states. */
+	carriedSurface: boolean;
 }
 
 /**
@@ -98,15 +184,16 @@ export function evaluateSkillToolSurface(
 	if (SKILL_SURFACE_EXEMPT_TOOLS.has(tool)) return null;
 	const entries = [...policy.loadedSkillPolicies.entries()];
 	const skills = entries.map(([name]) => name);
+	const carriedSurface = policy.carriedSurface === true;
 	const disallowedBy = entries
 		.filter(([, declared]) => declared.disallowedTools?.includes(tool) === true)
 		.map(([name]) => name);
-	if (disallowedBy.length > 0) return { skills, mergedAllowedTools: null, disallowedBy };
+	if (disallowedBy.length > 0) return { skills, mergedAllowedTools: null, disallowedBy, carriedSurface };
 	const allowLists = entries.map(([, declared]) => declared.allowedTools);
 	if (allowLists.some((list) => list === undefined || list.length === 0)) return null;
 	const merged = [...new Set(allowLists.flatMap((list) => [...(list ?? [])]))];
 	if (merged.includes(tool)) return null;
-	return { skills, mergedAllowedTools: merged, disallowedBy: [] };
+	return { skills, mergedAllowedTools: merged, disallowedBy: [], carriedSurface };
 }
 
 /**