@iowarp/clio-coder 0.3.7 → 0.3.9

package/src/domains/lifecycle/doctor.ts

@@ -1,13 +1,18 @@
 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";
 import { readSessionFileEntries, type SessionJsonlWarning } from "../../engine/session.js";
 import { detectInteropAgents, interopAgentKind, resolveOnPath } from "../interop/index.js";
-import { openAuthStorage } from "../providers/auth/index.js";
+import { openAuthStorage, resolveAuthTarget, targetRequiresAuth } from "../providers/auth/index.js";
+import { credentialsPresent } from "../providers/credentials.js";
 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";
 
@@ -205,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
@@ -372,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;
 }
@@ -534,3 +605,139 @@ export async function runDoctorRuntimeChecks(): Promise<DoctorFinding[]> {
 	);
 	return results.filter((finding): finding is DoctorFinding => finding !== null);
 }
+
+/** One configured model pointer at a target, named the way settings.yaml spells it. */
+interface ConfiguredModelRole {
+	role: string;
+	model: string;
+}
+
+function configuredModelRoles(
+	settings: ReturnType<typeof readSettings>,
+	target: TargetDescriptor,
+): ConfiguredModelRole[] {
+	const roles: ConfiguredModelRole[] = [];
+	if (target.defaultModel) roles.push({ role: "defaultModel", model: target.defaultModel });
+	if (settings.orchestrator.target === target.id && settings.orchestrator.model) {
+		roles.push({ role: "orchestrator.model", model: settings.orchestrator.model });
+	}
+	if (settings.background.target === target.id && settings.background.model) {
+		roles.push({ role: "background.model", model: settings.background.model });
+	}
+	if (settings.workers.default.target === target.id && settings.workers.default.model) {
+		roles.push({ role: "workers.default.model", model: settings.workers.default.model });
+	}
+	return roles;
+}
+
+/**
+ * Per-request budget for the model sweep. A target that does not answer in
+ * this time falls back to the list configure recorded, so a black-holed
+ * remote costs doctor a bounded wait rather than the probe's full timeout.
+ */
+const DOCTOR_MODEL_PROBE_TIMEOUT_MS = 2_500;
+
+async function doctorProbeContext(target: TargetDescriptor, runtime: RuntimeDescriptor): Promise<ProbeContext> {
+	const ctx: ProbeContext = { credentialsPresent: credentialsPresent(), httpTimeoutMs: DOCTOR_MODEL_PROBE_TIMEOUT_MS };
+	if (!targetRequiresAuth(target, runtime)) return ctx;
+	try {
+		const resolution = await openAuthStorage().resolveForTarget(resolveAuthTarget(target, runtime), {
+			includeFallback: false,
+		});
+		if (resolution.apiKey) ctx.authToken = resolution.apiKey;
+	} catch {
+		// The probe reports its own missing-auth failure; the wireModels fallback covers the check.
+	}
+	return ctx;
+}
+
+/** What the target advertises now, or null when it could not be asked. */
+async function probeAdvertisedModels(
+	target: TargetDescriptor,
+	runtime: RuntimeDescriptor,
+): Promise<{ advertised: string[]; resident: string[] } | null> {
+	if (runtime.kind !== "http" || typeof runtime.probe !== "function" || !target.url) return null;
+	let probe: ProbeResult;
+	try {
+		probe = await runtime.probe(target, await doctorProbeContext(target, runtime));
+	} catch {
+		return null;
+	}
+	if (!probe.ok || !probe.models || probe.models.length === 0) return null;
+	const advertised = [...probe.models];
+	const resident: string[] = [];
+	for (const [id, status] of Object.entries(probe.modelStates ?? {})) {
+		if (!advertised.includes(id)) advertised.push(id);
+		if (status.state === "loaded" || status.state === "loading") resident.push(id);
+	}
+	return { advertised, resident };
+}
+
+/**
+ * Model sweep: every model pointer settings.yaml aims at a target with no
+ * static catalog is checked against what that target advertises. The live
+ * list wins when the target answers; the `wireModels` list configure recorded
+ * stands in when it does not, so an unreachable server still gets the
+ * placeholder id it was saved with called out. A target with neither list is
+ * a WARN, not a pass, because nothing was verified. Network-bound like the
+ * runtime sweep, so it is not part of the synchronous `runDoctor()` core.
+ */
+export async function runDoctorModelChecks(): Promise<DoctorFinding[]> {
+	let settings: ReturnType<typeof readSettings>;
+	try {
+		settings = readSettings();
+	} catch {
+		return [];
+	}
+	if (settings.targets.length === 0) return [];
+	// Every runtime descriptor and the model catalog sit behind these two
+	// imports. They are loaded here, not at module load, so a doctor run on a
+	// home with no targets (the `--fix` seed every CLI test starts from) pays
+	// nothing for a sweep it has nothing to do.
+	const [{ getRuntimeRegistry }, { registerBuiltinRuntimes }, { listKnownModelsForRuntime }] = await Promise.all([
+		import("../providers/registry.js"),
+		import("../providers/runtimes/builtins.js"),
+		import("../providers/support.js"),
+	]);
+	const registry = getRuntimeRegistry();
+	// doctor never loads the providers domain, so the registry is empty here
+	// unless another command in this process filled it.
+	if (registry.list().length === 0) registerBuiltinRuntimes(registry);
+	const results = await Promise.all(
+		settings.targets.map(async (target): Promise<DoctorFinding | null> => {
+			const runtime = registry.get(target.runtime);
+			if (!runtime) return null;
+			// Cloud runtimes are validated against their catalog at configure time.
+			if (listKnownModelsForRuntime(runtime.id).length > 0) return null;
+			const roles = configuredModelRoles(settings, target);
+			if (roles.length === 0) return null;
+			const live = await probeAdvertisedModels(target, runtime);
+			const recorded = target.wireModels ?? [];
+			if (live === null && recorded.length === 0) {
+				return {
+					ok: true,
+					level: "warn",
+					name: `model ${target.id}`,
+					detail: `${roles.map((entry) => `${entry.role} '${entry.model}'`).join(", ")} could not be verified: the target did not answer and configure recorded no model list; run \`clio-coder targets --probe\` once it is up`,
+				};
+			}
+			const advertised = live ? live.advertised : recorded;
+			const source = live ? `advertised by ${target.url ?? target.id} now` : "recorded by configure at last save";
+			const missing = roles.filter((entry) => !advertised.includes(entry.model));
+			if (missing.length === 0) {
+				return {
+					ok: true,
+					name: `model ${target.id}`,
+					detail: `${roles.map((entry) => `${entry.role} '${entry.model}'`).join(", ")} ${source}`,
+				};
+			}
+			const resident = live && live.resident.length > 0 ? live.resident.join(", ") : live ? "none" : "unknown";
+			return {
+				ok: false,
+				name: `model ${target.id}`,
+				detail: `${missing.map((entry) => `${entry.role} '${entry.model}'`).join(", ")} not ${source} (${advertised.length} ids). Resident instances: ${resident}. Re-run \`clio-coder configure --id ${target.id} --model <advertised id>\`; \`clio-coder targets --probe\` lists them`,
+			};
+		}),
+	);
+	return results.filter((finding): finding is DoctorFinding => finding !== null);
+}

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,
@@ -95,8 +100,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,13 +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;
+export const TASK_MEMORY_POLICY_DEFAULT_TIMEOUT_MS = 30_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
@@ -45,10 +44,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 +115,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. */
@@ -146,6 +189,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 +253,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 +269,7 @@ export async function runTaskMemoryPolicy(
 			reminder: parts.reminder ?? null,
 			inputTokens: parts.inputTokens ?? 0,
 			outputTokens: parts.outputTokens ?? 0,
+			usage: stepUsage,
 		};
 		try {
 			input.onEnvelope?.({
@@ -263,9 +310,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 +341,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 +651,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,6 +220,8 @@ const REASONS = new Set<TaskMemoryPolicyReason>([
 	"unparseable",
 	"all_operations_invalid",
 	"deadline",
+	"timed_out",
+	"endpoint_busy",
 	"client_error",
 	"no_client",
 	"no_consumer",

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,