@iowarp/clio-coder 0.3.8 → 0.4.0

package/src/domains/extensions/resources.ts

@@ -33,7 +33,7 @@ export function enabledExtensionResourceRoots(
 ): ExtensionResourceRoot[] {
 	const roots: ExtensionResourceRoot[] = [];
 	for (const entry of listInstalledExtensions(cwd)) {
-		if (!entry.enabled || !entry.effective) continue;
+		if (!entry.enabled || !entry.compatible || !entry.effective) continue;
 		const rel = entry.resources[kind];
 		if (!rel) continue;
 		const full = extensionResourcePath(entry.rootPath, rel);

package/src/domains/extensions/state.ts

@@ -2,6 +2,7 @@ import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, r
 import path from "node:path";
 import { safeResourceWrite } from "../../core/safe-resource-write.js";
 import { clioConfigDir } from "../../core/xdg.js";
+import { evaluateClioCompatibility } from "./compatibility.js";
 import { isRecord, loadManifestFromRoot, trimString } from "./discovery.js";
 import type {
 	ExtensionInstallOptions,
@@ -63,6 +64,8 @@ function installedFromRoot(root: string, scope: ExtensionScope, state: Extension
 	const candidate = loadManifestFromRoot(root);
 	const manifest = candidate.manifest;
 	if (!manifest || !candidate.manifestPath) return null;
+	const clioRange = manifest.compatibility?.clio;
+	const compatible = clioRange === undefined || evaluateClioCompatibility(clioRange).satisfied;
 	return {
 		id: manifest.id,
 		name: manifest.name,
@@ -72,6 +75,7 @@ function installedFromRoot(root: string, scope: ExtensionScope, state: Extension
 		rootPath: root,
 		manifestPath: candidate.manifestPath,
 		enabled: !state.disabled.includes(manifest.id),
+		compatible,
 		effective: false,
 		resources: manifest.resources,
 		diagnostics: candidate.diagnostics,
@@ -102,13 +106,18 @@ export function listInstalledExtensions(cwd = process.cwd(), options: ExtensionL
 		byId.set(entry.id, list);
 	}
 	for (const group of byId.values()) {
-		const winner = [...group].sort((a, b) => scopeRank(a.scope) - scopeRank(b.scope)).at(-1);
+		const winner = group
+			.filter((entry) => entry.compatible)
+			.sort((a, b) => scopeRank(a.scope) - scopeRank(b.scope))
+			.at(-1);
 		for (const entry of group) {
 			entry.effective = entry === winner;
-			if (!entry.effective && winner) entry.overriddenBy = winner.scope;
+			if (entry.compatible && !entry.effective && winner) entry.overriddenBy = winner.scope;
 		}
 	}
-	const all = options.all === true ? entries : entries.filter((entry) => entry.effective);
+	// Incompatible packages remain visible by default so the load refusal and
+	// its version diagnostic cannot disappear with the resources it suppresses.
+	const all = options.all === true ? entries : entries.filter((entry) => entry.effective || !entry.compatible);
 	return all.sort((a, b) => {
 		const id = a.id.localeCompare(b.id);
 		if (id !== 0) return id;

package/src/domains/extensions/types.ts

@@ -36,6 +36,8 @@ export interface InstalledExtension {
 	rootPath: string;
 	manifestPath: string;
 	enabled: boolean;
+	/** Whether this package admits the running Clio version. */
+	compatible: boolean;
 	effective: boolean;
 	resources: ExtensionManifestResources;
 	overriddenBy?: ExtensionScope;

package/src/domains/lifecycle/doctor.ts

@@ -1,5 +1,5 @@
 import { accessSync, chmodSync, constants, type Dirent, existsSync, readdirSync, type Stats, statSync } from "node:fs";
-import { join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import { formatSettingsIssues, readSettings, validateSettingsFile } from "../../core/config.js";
 import { initializeClioHome } from "../../core/init.js";
 import { resolveClioDirs } from "../../core/xdg.js";
@@ -11,6 +11,8 @@ import { fingerprintNativeRuntime } from "../providers/probe/fingerprint.js";
 import type { ProbeContext, ProbeResult, RuntimeDescriptor } from "../providers/types/runtime-descriptor.js";
 import type { TargetDescriptor } from "../providers/types/target-descriptor.js";
 import { loadSkills, type SkillSource } from "../resources/skills/loader.js";
+import { isSessionEntry, type SessionEntry } from "../session/entries.js";
+import { foldPromptCacheTelemetry, hasPromptCacheTelemetry, topExpectedColdReason } from "../session/prompt-cache.js";
 import { readStateInfoResult } from "./state.js";
 import { getVersionInfo } from "./version.js";
 
@@ -208,6 +210,68 @@ function sessionStoreFinding(stateDir: string, stateMetadataPresent: boolean): D
 	return { ok: false, name: "session store", detail: parts.join("; ") };
 }
 
+interface SessionCacheCandidate {
+	entries: SessionEntry[];
+	ledger: string;
+	sessionId: string;
+	updatedAt: number;
+}
+
+/**
+ * Report the latest transcript's durable cache evidence. Current ledgers are
+ * selected explicitly because the session directory also holds diagnostic
+ * JSONL files whose timestamps do not identify the latest conversation.
+ */
+function latestSessionCacheFinding(stateDir: string): DoctorFinding | null {
+	const store = join(stateDir, "sessions");
+	const ledgers: string[] = [];
+	const unlistable: string[] = [];
+	collectSessionLedgers(store, ledgers, unlistable);
+	const candidates: SessionCacheCandidate[] = [];
+	for (const ledger of ledgers) {
+		if (basename(ledger) !== "current.jsonl") continue;
+		let parsed: unknown[];
+		let modifiedAt: number;
+		try {
+			parsed = readSessionFileEntries(ledger, { onWarning: () => {} });
+			modifiedAt = statSync(ledger).mtimeMs;
+		} catch {
+			continue;
+		}
+		const entries = parsed.filter(isSessionEntry);
+		const entryTimes = entries
+			.map((entry) => Date.parse(entry.timestamp))
+			.filter((timestamp) => Number.isFinite(timestamp));
+		candidates.push({
+			entries,
+			ledger,
+			sessionId: basename(dirname(ledger)),
+			updatedAt: entryTimes.length > 0 ? Math.max(...entryTimes) : modifiedAt,
+		});
+	}
+	const latest = candidates.sort(
+		(left, right) => right.updatedAt - left.updatedAt || left.ledger.localeCompare(right.ledger),
+	)[0];
+	if (latest === undefined) return null;
+
+	const telemetry = foldPromptCacheTelemetry(latest.entries);
+	if (!hasPromptCacheTelemetry(telemetry)) {
+		return {
+			ok: true,
+			level: "warn",
+			name: "cache telemetry",
+			detail: `last session ${latest.sessionId}: no prompt-cache telemetry recorded`,
+		};
+	}
+	const counts = telemetry.verdictCounts;
+	const topReason = topExpectedColdReason(telemetry);
+	return {
+		ok: true,
+		name: "cache telemetry",
+		detail: `last session ${latest.sessionId}: hot ${counts.hot} · partial ${counts.partial} · cold ${counts.cold} · small ${counts.small}; top expected reason ${topReason === null ? "none" : `${topReason.reason} (${topReason.count})`}`,
+	};
+}
+
 /**
  * Why the credentials store did not fully parse, read through the same
  * `openAuthStorage` the auth commands use, or null when it is clean. The row
@@ -375,6 +439,10 @@ export function runDoctor(options: DoctorOptions = {}): DoctorFinding[] {
 
 	const sessionStore = sessionStoreFinding(dirs.state, state !== null);
 	if (sessionStore !== null) findings.push(sessionStore);
+	if (sessionStore?.ok) {
+		const cacheTelemetry = latestSessionCacheFinding(dirs.state);
+		if (cacheTelemetry !== null) findings.push(cacheTelemetry);
+	}
 
 	return findings;
 }

package/src/domains/memory/index.ts

@@ -59,6 +59,11 @@ export {
 	type TaskMemoryRenderableClass,
 	type TaskMemorySnapshot,
 } from "./task-bank.js";
+export {
+	type ProposeInjectedTaskMemoryInput,
+	type ProposeInjectedTaskMemoryResult,
+	proposeInjectedTaskMemory,
+} from "./task-bank-promotion.js";
 export {
 	type LegacyTaskMemoryHandoffSnapshot,
 	parseTaskMemoryHandoffSnapshot,
@@ -86,7 +91,6 @@ export {
 	runTaskMemoryPolicy,
 	TASK_MEMORY_POLICY_DEFAULT_TIMEOUT_MS,
 	TASK_MEMORY_POLICY_MAX_OPERATIONS,
-	TASK_MEMORY_POLICY_MODEL_MAX_OUTPUT_TOKENS,
 	type TaskMemoryEnvelope,
 	type TaskMemoryModelClient,
 	type TaskMemoryModelRequest,
@@ -95,8 +99,17 @@ export {
 	type TaskMemoryPolicyInput,
 	type TaskMemoryPolicyReason,
 	type TaskMemoryPolicyResult,
+	type TaskMemoryStepUsage,
 	type TaskMemoryTrajectoryStep,
 } from "./task-memory-policy.js";
+export {
+	emptyTaskMemorySpendSummary,
+	foldTaskMemorySpend,
+	formatTaskMemorySpend,
+	readTaskMemorySpendSummary,
+	type TaskMemorySpendSummary,
+	taskMemoryStepsPath,
+} from "./task-memory-spend.js";
 export {
 	describeTaskMemoryActivity,
 	type TaskMemoryActivityEvent,

package/src/domains/memory/task-bank-promotion.ts

@@ -0,0 +1,64 @@
+/**
+ * The bridge between the session task bank and the durable memory store.
+ *
+ * Through 0.3.9 these were two stores where only one was ever written. The
+ * background plane filled the bank on every step, and nothing but an explicit
+ * `clio-coder memory propose` created a record, so `<dataDir>/memory/records.json`
+ * on the operator's machine did not exist at all: the tier's own output was
+ * discarded with the session that produced it, and the next session's first
+ * step read an empty bank and recorded `bank_empty` (#229).
+ *
+ * A reminder that actually reached the operator is the strongest signal the
+ * tier produces, so its cited entries are proposed here for review. They are
+ * written unapproved, under the repository the session is working in, and
+ * approval stays a separate operator action, exactly as it is for a promotion
+ * made by hand from `/memory`.
+ */
+
+import { canonicalMemoryRepositoryIdentity } from "./operations.js";
+import { proposeMemoryPromotion } from "./promotion.js";
+import type { TaskMemoryEntry } from "./task-bank.js";
+import type { MemoryRecord } from "./types.js";
+
+export interface ProposeInjectedTaskMemoryInput {
+	/** Session the reminder was produced in. Without one there is no provenance to file under. */
+	sessionId: string | null;
+	/** Working directory of that session, used for the repository scope. */
+	cwd: string;
+	entries: ReadonlyArray<TaskMemoryEntry>;
+	now?: Date;
+}
+
+export interface ProposeInjectedTaskMemoryResult {
+	records: MemoryRecord[];
+	/** One message per entry the store refused, for the caller to report. */
+	errors: string[];
+}
+
+export async function proposeInjectedTaskMemory(
+	dataDir: string,
+	input: ProposeInjectedTaskMemoryInput,
+): Promise<ProposeInjectedTaskMemoryResult> {
+	const result: ProposeInjectedTaskMemoryResult = { records: [], errors: [] };
+	const sessionId = input.sessionId;
+	const repository = canonicalMemoryRepositoryIdentity(input.cwd);
+	// No session means no provenance. No canonical repository leaves only global
+	// scope, which broadens applicability to every future session and is a claim
+	// a background step may never make on the operator's behalf.
+	if (sessionId === null || sessionId.length === 0 || repository === null) return result;
+	for (const entry of input.entries) {
+		if (entry.kind === "status") continue;
+		try {
+			const proposal = await proposeMemoryPromotion(
+				dataDir,
+				{ kind: "task-bank-entry", sessionId, evidenceRefs: [`session:${sessionId}`], entry },
+				{ scope: "repo", repository },
+				input.now ?? new Date(),
+			);
+			result.records.push(proposal.record);
+		} catch (error) {
+			result.errors.push(`${entry.id}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	return result;
+}

package/src/domains/memory/task-memory-policy.ts

@@ -1,8 +1,10 @@
+import type { BackendCompletionTimings } from "../../core/cache-telemetry.js";
 import type { ToolResultDigestProvenance } from "../../tools/result-disposition.js";
 import {
 	buildMemoryInterventionUserPrompt,
 	MEMORY_INTERVENTION_SYSTEM_PROMPT,
 } from "../prompts/memory-intervention.js";
+import type { CostProvenance } from "../providers/index.js";
 import { TASK_MEMORY_CONTENT_MAX_CHARS, type TaskMemoryBank, type TaskMemoryRenderableClass } from "./task-bank.js";
 
 export const TASK_MEMORY_POLICY_MAX_OPERATIONS = 8;
@@ -12,21 +14,10 @@ export const TASK_MEMORY_POLICY_MAX_OPERATIONS = 8;
  * directly.
  *
  * This must equal the settings default in `src/core/defaults.ts`; a contract
- * test pins the pair. It read 20000 while the shipped default was 180000, and
- * 20000 is the value measured to have produced 256 timeouts against a route
- * whose completions have a 15s median and an 81s tail. Two numbers for one
- * setting means any path that misses the settings object silently gets the one
- * known to be wrong.
+ * test pins the pair. Two numbers for one setting means any path that misses
+ * the settings object silently gets the one nobody chose.
  */
-export const TASK_MEMORY_POLICY_DEFAULT_TIMEOUT_MS = 180_000;
-/**
- * The envelope itself needs a few hundred tokens. The rest is headroom for a
- * model that reasons despite thinking being requested off: measured preambles on
- * a 9B local route ran past 1,800 tokens before the first `<operations>` byte,
- * and a budget that runs out mid-thought yields an empty response, no bank
- * writes, and no way for the operator to tell that from a deliberate silence.
- */
-export const TASK_MEMORY_POLICY_MODEL_MAX_OUTPUT_TOKENS = 4_000;
+export const TASK_MEMORY_POLICY_DEFAULT_TIMEOUT_MS = 60_000;
 
 export interface TaskMemoryTrajectoryStep {
 	step: number;
@@ -45,10 +36,39 @@ export interface TaskMemoryModelRequest {
 	signal: AbortSignal;
 }
 
+/**
+ * What one memory step cost, as the client that made the call observed it.
+ *
+ * The policy never prices anything itself; it carries this from the client to
+ * the composition root, which is the only layer that knows about the cost
+ * ledger. Without it a memory step was billed by a provider and recorded
+ * nowhere an operator could read: 137,205 tokens over 14 days appeared in no
+ * `/cost` row and in no usage report (#229).
+ */
+export interface TaskMemoryStepUsage {
+	/** Target the step ran against, used as the cost row's provider id. */
+	targetId: string;
+	attributedModelId: string;
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	reasoning: number;
+	totalTokens: number;
+	costUsd: number;
+	costProvenance: CostProvenance;
+	/** Wall time of the model call itself, measured by the client. */
+	durationMs: number;
+	/** Backend prefill facts when the serving runtime reported them (#247). */
+	backend: BackendCompletionTimings | null;
+}
+
 export interface TaskMemoryModelResponse {
 	text: string;
 	inputTokens?: number;
 	outputTokens?: number;
+	/** Provider-reported spend for this call. Absent on clients that report none. */
+	usage?: TaskMemoryStepUsage;
 }
 
 export interface TaskMemoryModelClient {
@@ -87,6 +107,21 @@ export type TaskMemoryPolicyReason =
 	| "all_operations_invalid"
 	/** The request did not answer inside the policy timeout. */
 	| "deadline"
+	/**
+	 * The transport hit its own deadline first and threw. Separated from
+	 * `client_error` because a route that answers too slowly and a route that
+	 * refuses the connection call for opposite responses, and separated from
+	 * `deadline` because it says the abort came from the request rather than
+	 * from the policy's race.
+	 */
+	| "timed_out"
+	/**
+	 * The step would have run on the endpoint the chat target is streaming
+	 * against, so it never started. A single-slot local server queues the memory
+	 * call behind the operator's own turn, or evicts the resident model to serve
+	 * it; neither is a cost a background step may impose.
+	 */
+	| "endpoint_busy"
 	/** The model client threw: unreachable route, auth failure, malformed request. */
 	| "client_error"
 	/** No background role is configured, so the llm tier never ran. */
@@ -99,6 +134,8 @@ export type TaskMemoryPolicyReason =
 	| "no_consumer"
 	/** A step was already in flight, so this boundary's triggers stayed pending. */
 	| "step_in_flight"
+	/** Consecutive model deadlines degraded this session to the free rules tier. */
+	| "llm_timeout_backoff"
 	/** Rules tier: the turn ended with no repeated failure worth reporting. */
 	| "no_repeated_failure"
 	/** Rules tier: compaction reactivation found no knowledge entries to restore. */
@@ -128,6 +165,8 @@ export interface TaskMemoryPolicyInput {
 	trajectory: ReadonlyArray<TaskMemoryTrajectoryStep>;
 	deterministicTrigger: boolean;
 	maxTokens: number;
+	/** Capability-derived completion budget; defaults to the visible reminder budget. */
+	modelMaxTokens?: number;
 	timeoutMs?: number;
 	/** Phase one still applies; phase two is suppressed when another memory reminder already won this boundary. */
 	suppressIntervention?: boolean;
@@ -146,6 +185,8 @@ export interface TaskMemoryPolicyResult {
 	reminder: string | null;
 	inputTokens: number;
 	outputTokens: number;
+	/** Provider-reported spend, when the client reported any. Null on every path that made no call. */
+	usage: TaskMemoryStepUsage | null;
 }
 
 type TaskMemoryOperation =
@@ -208,6 +249,7 @@ export async function runTaskMemoryPolicy(
 	let userPrompt = "";
 	let rawResponse = "";
 	let clientError: string | null = null;
+	let stepUsage: TaskMemoryStepUsage | null = null;
 	// Every exit reports through here so the trace sees the same envelope the
 	// telemetry row summarizes, including the paths that used to throw away both.
 	const settle = (
@@ -223,6 +265,7 @@ export async function runTaskMemoryPolicy(
 			reminder: parts.reminder ?? null,
 			inputTokens: parts.inputTokens ?? 0,
 			outputTokens: parts.outputTokens ?? 0,
+			usage: stepUsage,
 		};
 		try {
 			input.onEnvelope?.({
@@ -250,7 +293,7 @@ export async function runTaskMemoryPolicy(
 		const completion = client.complete({
 			systemPrompt: MEMORY_INTERVENTION_SYSTEM_PROMPT,
 			userPrompt,
-			maxTokens: TASK_MEMORY_POLICY_MODEL_MAX_OUTPUT_TOKENS,
+			maxTokens: positiveInteger(input.modelMaxTokens, input.maxTokens),
 			signal: controller.signal,
 		});
 		const timeout = new Promise<typeof timeoutMarker>((resolve) => {
@@ -263,9 +306,10 @@ export async function runTaskMemoryPolicy(
 			return settle("timeout", "deadline");
 		}
 		rawResponse = typeof response.text === "string" ? response.text : "";
+		stepUsage = response.usage ?? null;
 		const usage = {
-			inputTokens: nonNegativeInteger(response.inputTokens),
-			outputTokens: nonNegativeInteger(response.outputTokens),
+			inputTokens: nonNegativeInteger(response.inputTokens ?? stepUsage?.input),
+			outputTokens: nonNegativeInteger(response.outputTokens ?? stepUsage?.output),
 		};
 		const read = readPolicyStep(rawResponse);
 		if (!read.ok) return settle("malformed", read.reason, { ...usage, droppedOperations: read.dropped });
@@ -293,6 +337,11 @@ export async function runTaskMemoryPolicy(
 		return settle("injected", "intervened", { ...counts, reminder });
 	} catch (error) {
 		clientError = errorMessage(error);
+		// A transport that aborted at its own deadline spent the whole budget and
+		// produced nothing. Reporting it as silence made a step that held a local
+		// server for its full timeout indistinguishable from a model that read the
+		// trajectory and decided there was nothing to say (#229).
+		if (isTimeoutError(error)) return settle("timeout", "timed_out");
 		return settle("silent", "client_error");
 	} finally {
 		if (timer !== undefined) clearTimeout(timer);
@@ -598,6 +647,22 @@ function nonNegativeInteger(value: number | undefined): number {
 	return value !== undefined && Number.isInteger(value) && value >= 0 ? value : 0;
 }
 
+/**
+ * Whether a client failure was the deadline rather than the route.
+ *
+ * The engine surfaces an aborted or timed-out completion as a plain `Error`
+ * carrying the provider's message, so the name and the text are all there is to
+ * read. Both spellings appear: pi-ai raises `AbortError` when the policy's own
+ * signal fires, and the completion wrapper raises `model completion aborted`
+ * when its `timeoutMs` fires first.
+ */
+function isTimeoutError(error: unknown): boolean {
+	const name = error instanceof Error ? error.name : "";
+	if (name === "AbortError" || name === "TimeoutError") return true;
+	const message = error instanceof Error ? error.message : typeof error === "string" ? error : "";
+	return /\b(abort(ed)?|timed out|timeout)\b/iu.test(message);
+}
+
 function errorMessage(error: unknown): string {
 	if (error instanceof Error) return error.message.length > 0 ? error.message : error.name;
 	return typeof error === "string" && error.length > 0 ? error : "an unknown client failure";

package/src/domains/memory/task-memory-spend.ts

@@ -0,0 +1,131 @@
+/**
+ * Lifetime spend and hit rate of the proactive-memory llm tier, folded from the
+ * telemetry ledger the sink already writes.
+ *
+ * The ledger recorded every step's tokens and latency from the day the tier
+ * shipped, and nothing ever read it back: the operator's own file held 60
+ * llm-tier steps, 137,205 tokens, and 1,666 seconds of model time for 6
+ * injections, and no surface said so (#229). `/memory` reads this, so the
+ * question "is the background plane earning its cost" is answered by the
+ * measurement rather than by an impression.
+ */
+
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { clioStateDir } from "../../core/xdg.js";
+import { parseTaskMemoryTelemetryRecord, TASK_MEMORY_TELEMETRY_FILE } from "./task-memory-telemetry.js";
+
+export interface TaskMemorySpendSummary {
+	/** Steps that reached the background model. Rules-tier steps cost nothing and are excluded. */
+	llmSteps: number;
+	/** Llm-tier steps whose reminder reached the visible channel. */
+	injections: number;
+	/** Injections over llm steps, 0 when no llm step has run. */
+	hitRate: number;
+	inputTokens: number;
+	outputTokens: number;
+	totalTokens: number;
+	/** Cumulative llm-tier step latency. */
+	modelMs: number;
+	/** Slowest single llm-tier step, which is what a deadline has to answer for. */
+	slowestStepMs: number;
+	/** Llm-tier steps that spent their whole budget and answered nothing. */
+	timeouts: number;
+	/** Boundaries skipped because the chat endpoint was serving a turn. */
+	endpointBusySkips: number;
+	/** Oldest and newest row in the ledger, so a rate is read against a window. */
+	firstAt: string | null;
+	lastAt: string | null;
+}
+
+export function taskMemoryStepsPath(stateDir: string = clioStateDir()): string {
+	return join(stateDir, "memory", TASK_MEMORY_TELEMETRY_FILE);
+}
+
+export function emptyTaskMemorySpendSummary(): TaskMemorySpendSummary {
+	return {
+		llmSteps: 0,
+		injections: 0,
+		hitRate: 0,
+		inputTokens: 0,
+		outputTokens: 0,
+		totalTokens: 0,
+		modelMs: 0,
+		slowestStepMs: 0,
+		timeouts: 0,
+		endpointBusySkips: 0,
+		firstAt: null,
+		lastAt: null,
+	};
+}
+
+/** Fold parsed telemetry rows. Exported for callers that already hold the rows. */
+export function foldTaskMemorySpend(lines: ReadonlyArray<string>): TaskMemorySpendSummary {
+	const summary = emptyTaskMemorySpendSummary();
+	for (const line of lines) {
+		if (line.trim().length === 0) continue;
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(line) as unknown;
+		} catch {
+			// A truncated tail line is the normal shape of a file being appended to.
+			continue;
+		}
+		const record = parseTaskMemoryTelemetryRecord(parsed);
+		if (record === null) continue;
+		if (summary.firstAt === null || record.at < summary.firstAt) summary.firstAt = record.at;
+		if (summary.lastAt === null || record.at > summary.lastAt) summary.lastAt = record.at;
+		if (record.reason === "endpoint_busy") summary.endpointBusySkips += 1;
+		if (record.tier !== "llm") continue;
+		summary.llmSteps += 1;
+		if (record.decision === "injected") summary.injections += 1;
+		if (record.decision === "timeout") summary.timeouts += 1;
+		summary.inputTokens += record.tokenCost.input;
+		summary.outputTokens += record.tokenCost.output;
+		summary.totalTokens += record.tokenCost.total;
+		summary.modelMs += record.latencyMs;
+		summary.slowestStepMs = Math.max(summary.slowestStepMs, record.latencyMs);
+	}
+	summary.hitRate = summary.llmSteps === 0 ? 0 : summary.injections / summary.llmSteps;
+	return summary;
+}
+
+interface SpendCacheEntry {
+	mtimeMs: number;
+	size: number;
+	summary: TaskMemorySpendSummary;
+}
+
+const spendCache = new Map<string, SpendCacheEntry>();
+
+/**
+ * Read the ledger and fold it, reusing the previous fold while the file has not
+ * moved. `/memory` repaints once a second and the ledger is capped at a
+ * megabyte, so an idle second costs one `stat` rather than a megabyte of JSON.
+ * A missing file is an empty summary: a machine where the llm tier never ran
+ * has nothing to report, which is different from a ledger that failed to open.
+ */
+export function readTaskMemorySpendSummary(stateDir: string = clioStateDir()): TaskMemorySpendSummary {
+	const path = taskMemoryStepsPath(stateDir);
+	try {
+		const info = statSync(path);
+		const cached = spendCache.get(path);
+		if (cached !== undefined && cached.mtimeMs === info.mtimeMs && cached.size === info.size) return cached.summary;
+		const summary = foldTaskMemorySpend(readFileSync(path, "utf8").split("\n"));
+		spendCache.set(path, { mtimeMs: info.mtimeMs, size: info.size, summary });
+		return summary;
+	} catch {
+		return emptyTaskMemorySpendSummary();
+	}
+}
+
+/** Compact operator wording. Empty when the llm tier has never run. */
+export function formatTaskMemorySpend(summary: TaskMemorySpendSummary): string {
+	if (summary.llmSteps === 0) return "";
+	const tokens =
+		summary.totalTokens >= 1_000 ? `${(summary.totalTokens / 1_000).toFixed(1)}k tok` : `${summary.totalTokens} tok`;
+	const seconds = summary.modelMs / 1_000;
+	const time = seconds >= 60 ? `${(seconds / 60).toFixed(1)}m` : `${seconds.toFixed(1)}s`;
+	const rate = `${Math.round(summary.hitRate * 100)}%`;
+	return `spend ${summary.llmSteps} steps · ${tokens} · ${time} · hit ${summary.injections}/${summary.llmSteps} (${rate})`;
+}

package/src/domains/memory/task-memory-status.ts

@@ -1,5 +1,6 @@
 import type { TaskMemorySnapshot } from "./task-bank.js";
 import type { TaskMemoryPolicyDecision, TaskMemoryPolicyReason } from "./task-memory-policy.js";
+import type { TaskMemorySpendSummary } from "./task-memory-spend.js";
 import type {
 	TaskMemoryTelemetryDecision,
 	TaskMemoryTelemetryTier,
@@ -35,6 +36,12 @@ export interface TaskMemoryOperatorStatus {
 	activity: ReadonlyArray<TaskMemoryActivityEvent>;
 	/** True while a detached background memory step is still running. */
 	stepInFlight: boolean;
+	/**
+	 * Lifetime llm-tier spend and hit rate folded from the telemetry ledger. Null
+	 * on a surface that does not read the ledger, which is every surface that
+	 * only needs the live bank.
+	 */
+	spend?: TaskMemorySpendSummary | null;
 }
 
 /**

package/src/domains/memory/task-memory-telemetry.ts

@@ -220,10 +220,13 @@ const REASONS = new Set<TaskMemoryPolicyReason>([
 	"unparseable",
 	"all_operations_invalid",
 	"deadline",
+	"timed_out",
+	"endpoint_busy",
 	"client_error",
 	"no_client",
 	"no_consumer",
 	"step_in_flight",
+	"llm_timeout_backoff",
 	"no_repeated_failure",
 	"bank_empty",
 ]);

package/src/domains/middleware/index.ts

@@ -81,6 +81,7 @@ export {
 	MEMORY_INTERVENTION_REGISTRATION_ID,
 	type MemoryInterventionDeps,
 } from "./memory-intervention.js";
+export { announceMemoryStepEndpoint, type MemoryStepEndpointAnnouncerDeps } from "./memory-step-endpoint.js";
 export { BUILTIN_MIDDLEWARE_RULE_IDS, listMiddlewareRuleDefinitions, listMiddlewareRules } from "./rules.js";
 export type {
 	MiddlewareDiagnostic,