@iowarp/clio-coder 0.3.2 → 0.3.4

package/skills/meta/clio-test/references/harness.md

@@ -1,18 +1,20 @@
 # Clio test harness reference
 
-How to drive the real Clio binary, a mock provider, and the ACP surface in
-tests. All of this is non-interactive — there is no pty harness in v0.2.2.
+How to drive the real Clio binary, a mock provider, the ACP surface, and a
+real pseudo-terminal in tests. Every model here is a stub; these are machinery
+tests. A run against a real model is `benchmarks/internal/SKILL.md`.
 
 ## Contents
 - The spawn harness (`runCli`, `makeScratchHome`)
 - Mocking a provider (OpenAI-compatible SSE fixture)
 - ACP over JSON-RPC/stdio
+- The PTY (`openPty`, `runInPty`)
 - One-off probes (no test file)
 
 ## The spawn harness
 
-`tests/harness/spawn.ts` is the only harness. It spawns `node dist/cli/index.js`,
-so **build first** (or keep `npm run dev` running) before `test:smoke`.
+`tests/harness/spawn.ts` spawns `node dist/cli/index.js` with piped stdio, so
+**build first** (or keep `npm run dev` running) before running smoke.
 
 ```ts
 import { makeScratchHome, runCli } from "../harness/spawn.js";
@@ -76,11 +78,38 @@ client (see `createJsonRpcProcessClient` in the smoke test): `initialize` →
 non-spec discriminator breaks strict clients like Zed, so the smoke test asserts
 every emitted variant is in the v1 set.
 
+## The PTY
+
+Piped stdio reports no terminal width and no TTY, so the TUI refuses to start
+and every width-sensitive path collapses to 80 columns. `tests/harness/pty.ts`
+opens a real pseudo-terminal through `node-pty` (a devDependency, never
+shipped):
+
+```ts
+import { openPty, runInPty, stripAnsi, visibleLines } from "../harness/pty.js";
+
+// Scripted: type on a schedule, stop when the output matches, bounded by a timeout.
+const run = await runInPty(process.execPath, [CLI], { cols: 120, rows: 40, cwd, env,
+  readyWhen: /ctx /, input: [{ afterMs: 200, data: "/quit\r" }], until: /bye/, timeoutMs: 20_000 });
+
+// Controllable: write, resize, pause output, wait for a matcher, wait for exit.
+const session = await openPty(process.execPath, [CLI], { cols: 140, rows: 44, cwd, env });
+await session.waitForOutput((out) => /ctx /.test(stripAnsi(out)), 30_000);
+session.write("/quit\r");
+await session.waitForExit(10_000);
+```
+
+Use it only for what a pipe cannot show: width, raw mode, SIGINT through a
+terminal, the alternate-screen and keyboard-protocol teardown. The three
+suites that need it are `tests/smoke/tui-width-matrix.test.ts`,
+`instant-shell-pty.test.ts`, and `render-trace-pty.test.ts`. Anything else
+belongs on `runCli`.
+
 ## One-off probes (no test file)
 
 To poke at Clio without writing a permanent test, drop a throwaway script in
-`/tmp` and run it with tsx. Delete it when done — never leave probes under
-`tests/` or `scripts/`.
+your scratch directory and run it with tsx. Delete it when done — never leave
+probes under `tests/`, `scripts/`, or `benchmarks/`.
 
 ```ts
 // /tmp/probe.ts

package/skills/meta/clio-test/references/test-map.md

@@ -1,4 +1,4 @@
-# Where Clio's tests live (v0.2.2)
+# Where Clio's tests live
 
 Three layers under `tests/`. Add a new test next to the closest existing file;
 create a new file only for a genuinely new domain cluster.
@@ -7,10 +7,17 @@ create a new file only for a genuinely new domain cluster.
 
 | Layer | Path | Runner | Build needed |
 |---|---|---|---|
-| contracts | `tests/contracts/*.test.ts` | `node --import tsx --test` | no (imports `src`) |
-| smoke | `tests/smoke/*.test.ts` | `node --import tsx --test` | **yes** (spawns `dist/`) |
-| boundaries | `tests/boundaries/*.test.ts` | `node --import tsx --test` | no |
-| harness (not a test) | `tests/harness/spawn.ts` | imported by smoke | — |
+| contracts | `tests/contracts/*.test.ts` | `npm run test:file -- <glob>` (tsx + scratch root) | no (imports `src`) |
+| smoke | `tests/smoke/*.test.ts` | `npm run test:file -- <glob>` | **yes** (spawns `dist/`) |
+| boundaries | `tests/boundaries/check-boundaries.ts` | `npm run lint` (hygiene) | no |
+| harness (not tests) | `tests/harness/*.ts` | imported by contracts and smoke | — |
+
+The harness modules: `spawn.ts` (run the built CLI with pipes), `scratch-env.ts`
+(isolated Clio home), `pty.ts` (a real pseudo-terminal), `openai-compat-fixture.ts`
+and `fake-lmstudio-server.ts` (stub providers), `fake-ssh.ts` (stub fleet node),
+`clock.ts` (steppable clock), plus dispatch, receipt, and module-graph helpers.
+Everything under `tests/` stubs the model. Real-model runs are
+`benchmarks/internal/` and never run under `npm test`.
 
 ## Contract test files
 
@@ -33,18 +40,21 @@ create a new file only for a genuinely new domain cluster.
 | Area | File |
 |---|---|
 | non-interactive CLI + ACP-over-stdio end-to-end | `tests/smoke/cli.test.ts` |
-| import boundary rules (rule1/2/3) | `tests/boundaries/boundaries.test.ts` |
-| boundary checker implementation | `tests/boundaries/check-boundaries.ts` |
+| the package as installed from `npm pack` | `tests/smoke/pack-install.test.ts` |
+| TUI at real terminal sizes, NO_COLOR, Ctrl-C teardown (PTY) | `tests/smoke/tui-width-matrix.test.ts` |
+| instant shell before hydration, SIGTERM through the lease (PTY) | `tests/smoke/instant-shell-pty.test.ts` |
+| committed-frame render trace under PTY backpressure (PTY) | `tests/smoke/render-trace-pty.test.ts` |
+| import boundary rules (rule1/2/3), run under `npm run lint` | `tests/boundaries/check-boundaries.ts` |
 
 ## Running a subset
 
 ```bash
 # all contracts
-node --import tsx --test 'tests/contracts/**/*.test.ts'
+npm run test:file -- 'tests/contracts/**/*.test.ts'
 # one file
-node --import tsx --test tests/contracts/skills.test.ts
+npm run test:file -- tests/contracts/skills.test.ts
 # only it.only / describe.only within a file
-node --import tsx --test --test-only tests/contracts/skills.test.ts
+npm run test:file -- --test-only tests/contracts/skills.test.ts
 ```
 
 ## Writing tests

package/skills/registry.yaml

@@ -61,8 +61,8 @@ skills:
     sha256: 386ebfdac9379ebf5630fa7a9af259bb45f473f7d3d679b0a7ef4164f5fc4dea
   - name: clio-test
     path: meta/clio-test
-    version: 0.1.3
-    sha256: 99683ea7d7bf5bf57788e58ee6c66e01a4e30ec8d3d7d0a1f8b2b85caff4ae5a
+    version: 0.1.4
+    sha256: 90ca1fe7660cd8c3d835801883ebd55d2d17cb652b8585b28ddb82aec642336e
   - name: credentials
     path: meta/credentials
     version: 0.1.2

package/skills/skill-marketplace.json

@@ -109,7 +109,7 @@
 			"name": "clio-test",
 			"description": "Use when writing or modifying Clio Coder's own source under src/, or verifying a change end-to-end against the real test harness. Covers the three real layers (contracts / smoke / boundaries), choosing which to run for a given change, the mock-provider and ACP-over-stdio harness, and the hot-reload dev loop for picking up latest code. Activate on any src/ edit, before declaring a change verified, or when asked whether Clio still works.",
 			"sourceUrl": "https://github.com/iowarp/clio-coder/tree/main/skills/meta/clio-test",
-			"version": "0.1.3",
+			"version": "0.1.4",
 			"audit": "pass",
 			"category": "meta"
 		},

package/src/cli/context-working-set.ts

@@ -0,0 +1,513 @@
+import { execFileSync } from "node:child_process";
+import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { assertSafeId } from "../core/safe-id.js";
+import { clioStatePath } from "../core/xdg.js";
+import { DEFAULT_WORKING_SET_SETTINGS } from "../domains/context/working-set/defaults.js";
+import { foldWorkingSet } from "../domains/context/working-set/fold.js";
+import { buildPathIndex } from "../domains/context/working-set/path-index.js";
+import { resolveWorkingSetPolicy } from "../domains/context/working-set/policies/index.js";
+import { makeOraclePolicy, makeRandomPolicy, nonePolicy } from "../domains/context/working-set/replay/controls.js";
+import { loadClioTraces, type ReplayLoadCascade } from "../domains/context/working-set/replay/load-clio.js";
+import { aggregateReplayMetrics, type ReplayMeasurement } from "../domains/context/working-set/replay/metrics.js";
+import { buildReferenceGraph, type ReferenceGraph } from "../domains/context/working-set/replay/reference-graph.js";
+import {
+	type ReplayPolicyResult,
+	type ReplayReportInput,
+	renderReplayJson,
+	renderReplayMarkdown,
+} from "../domains/context/working-set/replay/report.js";
+import { replayTrace } from "../domains/context/working-set/replay/runner.js";
+import { generateSyntheticCorpora, SYNTHETIC_CORPORA } from "../domains/context/working-set/replay/synthetic.js";
+import type { Trace } from "../domains/context/working-set/replay/trace.js";
+import { parseSessionEntries } from "../domains/session/archive-readers.js";
+import { DEFAULT_KEEP_RECENT_TOKENS } from "../domains/session/compaction/defaults.js";
+import { filterEntriesToActivePath } from "../domains/session/tree/active-path.js";
+
+const REPLAY_HELP = `Usage:
+  clio-coder context replay (--sessions <path>... | --synthetic <corpus>...) [options]
+
+Options:
+  --sessions <path>... Clio session directories, sessions roots, or ledger JSONL files
+  --synthetic <ids>   comma-separated procedural corpora: ${SYNTHETIC_CORPORA.map((spec) => spec.id).join(",")}
+  --policies <ids>    comma-separated none,random,age-horizon,structural-v1,oracle
+  --budgets <tokens>  comma-separated budgets (default: 16000,32000,64000)
+  --threshold <ratio> pressure threshold (default: 0.8)
+  --target <ratio>    post-eviction pressure target (default: 0.6)
+  --protect-last-turns <n>
+                      protected recent turns (default: ${DEFAULT_WORKING_SET_SETTINGS.protectLastTurns})
+  --min-evictable-tokens <n>
+                      minimum tool-result body tokens (default: ${DEFAULT_WORKING_SET_SETTINGS.minEvictableTokens})
+  --seed <integer>    deterministic random-policy seed (default: 0)
+  --no-filter         include every readable transcript
+  --json <path>       write the stable JSON report
+  --md <path>         write Markdown instead of printing it
+`;
+
+const WORKING_SET_HELP = `Usage:
+  clio-coder context working-set --session <id|path>
+
+Print the durable working-set fold and path-index summary for one Clio session.
+`;
+
+/**
+ * Conservative stand-in for replay's summary paraphrase. Five recorded local
+ * compactions price at 405, 405, 968, 981, and 1,124 tokens; 1,500 sits above
+ * that observed range. The replay README records the sample and sensitivity.
+ */
+const REPLAY_SUMMARY_TOKENS = 1_500;
+
+const POLICY_IDS = ["none", "random", "age-horizon", "structural-v1", "oracle"] as const;
+type ReplayPolicyId = (typeof POLICY_IDS)[number];
+
+class CliUsageError extends Error {}
+
+interface ReplayArgs {
+	sessions: string[];
+	policies: ReplayPolicyId[];
+	budgets: number[];
+	threshold: number;
+	target: number;
+	protectLastTurns: number;
+	minEvictableTokens: number;
+	seed: number;
+	synthetic: string[];
+	noFilter: boolean;
+	jsonPath?: string;
+	markdownPath?: string;
+}
+
+function commaValues(value: string, flag: string): string[] {
+	const values = value
+		.split(",")
+		.map((entry) => entry.trim())
+		.filter((entry) => entry.length > 0);
+	if (values.length === 0) throw new CliUsageError(`${flag} requires at least one value`);
+	return [...new Set(values)];
+}
+
+function numberValue(value: string, flag: string): number {
+	const parsed = Number(value);
+	if (!Number.isFinite(parsed)) throw new CliUsageError(`${flag} requires a finite number`);
+	return parsed;
+}
+
+function requiredValue(args: ReadonlyArray<string>, index: number, flag: string): string {
+	const value = args[index + 1];
+	if (value === undefined || value.startsWith("--")) throw new CliUsageError(`${flag} requires a value`);
+	return value;
+}
+
+function policyResolves(id: ReplayPolicyId): boolean {
+	if (id === "none" || id === "random" || id === "oracle") return true;
+	try {
+		resolveWorkingSetPolicy(id);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function defaultPolicies(): ReplayPolicyId[] {
+	return POLICY_IDS.filter(policyResolves);
+}
+
+function parseReplayArgs(args: ReadonlyArray<string>): ReplayArgs {
+	const parsed: ReplayArgs = {
+		sessions: [],
+		policies: defaultPolicies(),
+		budgets: [16_000, 32_000, 64_000],
+		threshold: 0.8,
+		target: 0.6,
+		protectLastTurns: DEFAULT_WORKING_SET_SETTINGS.protectLastTurns,
+		minEvictableTokens: DEFAULT_WORKING_SET_SETTINGS.minEvictableTokens,
+		seed: 0,
+		synthetic: [],
+		noFilter: false,
+	};
+	let policiesExplicit = false;
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index];
+		if (arg === "--no-filter") {
+			parsed.noFilter = true;
+			continue;
+		}
+		if (arg === "--sessions") {
+			let consumed = 0;
+			while (index + 1 < args.length && !args[index + 1]?.startsWith("--")) {
+				parsed.sessions.push(args[index + 1] as string);
+				index += 1;
+				consumed += 1;
+			}
+			if (consumed === 0) throw new CliUsageError("--sessions requires at least one path");
+			continue;
+		}
+		if (
+			arg === "--policies" ||
+			arg === "--budgets" ||
+			arg === "--synthetic" ||
+			arg === "--threshold" ||
+			arg === "--target" ||
+			arg === "--protect-last-turns" ||
+			arg === "--min-evictable-tokens" ||
+			arg === "--seed"
+		) {
+			const value = requiredValue(args, index, arg);
+			index += 1;
+			if (arg === "--policies") {
+				const values = commaValues(value, arg);
+				const unknown = values.filter((entry) => !(POLICY_IDS as ReadonlyArray<string>).includes(entry));
+				if (unknown.length > 0) throw new CliUsageError(`unknown replay policy: ${unknown.join(", ")}`);
+				parsed.policies = values as ReplayPolicyId[];
+				policiesExplicit = true;
+			} else if (arg === "--budgets") {
+				parsed.budgets = commaValues(value, arg).map((entry) => {
+					const budget = numberValue(entry, arg);
+					if (!Number.isInteger(budget) || budget <= 0) {
+						throw new CliUsageError("--budgets values must be positive integers");
+					}
+					return budget;
+				});
+			} else if (arg === "--synthetic") {
+				const values = commaValues(value, arg);
+				const known = SYNTHETIC_CORPORA.map((spec) => spec.id);
+				const unknown = values.filter((entry) => !known.includes(entry));
+				if (unknown.length > 0) throw new CliUsageError(`unknown synthetic corpus: ${unknown.join(", ")}`);
+				parsed.synthetic = values;
+			} else if (arg === "--threshold") {
+				parsed.threshold = numberValue(value, arg);
+				if (parsed.threshold <= 0 || parsed.threshold > 1) {
+					throw new CliUsageError("--threshold must be greater than 0 and at most 1");
+				}
+			} else if (arg === "--target") {
+				parsed.target = numberValue(value, arg);
+				if (parsed.target <= 0 || parsed.target >= 1) {
+					throw new CliUsageError("--target must be greater than 0 and less than 1");
+				}
+			} else if (arg === "--protect-last-turns") {
+				parsed.protectLastTurns = numberValue(value, arg);
+				if (!Number.isInteger(parsed.protectLastTurns) || parsed.protectLastTurns < 1) {
+					throw new CliUsageError("--protect-last-turns must be an integer at least 1");
+				}
+			} else if (arg === "--min-evictable-tokens") {
+				parsed.minEvictableTokens = numberValue(value, arg);
+				if (!Number.isInteger(parsed.minEvictableTokens) || parsed.minEvictableTokens < 0) {
+					throw new CliUsageError("--min-evictable-tokens must be a non-negative integer");
+				}
+			} else {
+				parsed.seed = numberValue(value, arg);
+				if (!Number.isInteger(parsed.seed)) throw new CliUsageError("--seed must be an integer");
+			}
+			continue;
+		}
+		if (arg === "--json" || arg === "--md") {
+			const value = requiredValue(args, index, arg);
+			index += 1;
+			if (arg === "--json") parsed.jsonPath = value;
+			else parsed.markdownPath = value;
+			continue;
+		}
+		throw new CliUsageError(`unknown flag ${arg}`);
+	}
+	if (parsed.sessions.length === 0 && parsed.synthetic.length === 0) {
+		throw new CliUsageError("--sessions or --synthetic is required");
+	}
+	if (parsed.target >= parsed.threshold) throw new CliUsageError("--target must be less than --threshold");
+	if (policiesExplicit) {
+		const unavailable = parsed.policies.filter((id) => !policyResolves(id));
+		if (unavailable.length > 0) {
+			throw new CliUsageError(`replay policy is not available in this build: ${unavailable.join(", ")}`);
+		}
+	}
+	return parsed;
+}
+
+function policyForTrace(id: ReplayPolicyId, graph: ReferenceGraph, seed: number) {
+	if (id === "none") return nonePolicy;
+	if (id === "random") return makeRandomPolicy(seed);
+	if (id === "oracle") return makeOraclePolicy(graph);
+	return resolveWorkingSetPolicy(id);
+}
+
+function gitSha(): string | null {
+	try {
+		return execFileSync("git", ["rev-parse", "HEAD"], {
+			cwd: process.cwd(),
+			encoding: "utf8",
+			stdio: ["ignore", "pipe", "ignore"],
+		}).trim();
+	} catch {
+		return null;
+	}
+}
+
+function exactCommandLine(): string[] {
+	return [process.execPath, ...process.execArgv, ...process.argv.slice(1)];
+}
+
+async function writeOutput(path: string, contents: string): Promise<string> {
+	const output = resolve(path);
+	await mkdir(dirname(output), { recursive: true });
+	await writeFile(output, contents, "utf8");
+	return output;
+}
+
+function cascadeLine(cascade: ReplayLoadCascade): string {
+	const filtered = Object.entries(cascade.filtered)
+		.map(([stage, count]) => `${stage}=${count}`)
+		.join(" ");
+	return `cascade found=${cascade.found} unreadable=${cascade.unreadable} ${filtered} kept=${cascade.kept}`;
+}
+
+export async function runContextReplayCommand(args: string[]): Promise<number> {
+	if (args.includes("--help") || args.includes("-h")) {
+		process.stdout.write(REPLAY_HELP);
+		return 0;
+	}
+	let parsed: ReplayArgs;
+	try {
+		parsed = parseReplayArgs(args);
+	} catch (error) {
+		process.stderr.write(
+			`clio-coder context replay: ${error instanceof Error ? error.message : String(error)}\n${REPLAY_HELP}`,
+		);
+		return 2;
+	}
+	try {
+		const ledgers = await loadClioTraces(parsed.sessions, { filter: parsed.noFilter ? false : {} });
+		const synthetic = generateSyntheticCorpora(parsed.synthetic);
+		const loaded = {
+			traces: [...ledgers.traces, ...synthetic.traces],
+			cascade: {
+				found: ledgers.cascade.found + synthetic.cascade.found,
+				unreadable: ledgers.cascade.unreadable,
+				filtered: ledgers.cascade.filtered,
+				kept: ledgers.cascade.kept + synthetic.cascade.kept,
+			},
+		};
+		if (loaded.traces.length === 0) {
+			process.stderr.write(`clio-coder context replay: no traces to replay (${cascadeLine(loaded.cascade)})\n`);
+			return 1;
+		}
+		const indexed = loaded.traces.map((trace) => {
+			const index = buildPathIndex(trace.entries, { cwd: trace.cwd });
+			return { trace, index, graph: buildReferenceGraph(trace, index) };
+		});
+		const settings = {
+			...DEFAULT_WORKING_SET_SETTINGS,
+			target: parsed.target,
+			protectLastTurns: parsed.protectLastTurns,
+			minEvictableTokens: parsed.minEvictableTokens,
+		};
+		const results: ReplayPolicyResult[] = [];
+		for (const budgetTokens of parsed.budgets) {
+			for (const policyId of parsed.policies) {
+				const measurements: ReplayMeasurement[] = indexed.map(({ trace, index, graph }) => ({
+					trace,
+					index,
+					graph,
+					replay: replayTrace(trace, policyForTrace(policyId, graph, parsed.seed), {
+						policyId,
+						budgetTokens,
+						threshold: parsed.threshold,
+						target: parsed.target,
+						settings,
+						seed: parsed.seed,
+						summaries: { keepRecentTokens: DEFAULT_KEEP_RECENT_TOKENS, summaryTokens: REPLAY_SUMMARY_TOKENS },
+					}),
+				}));
+				results.push({ budgetTokens, policyId, metrics: aggregateReplayMetrics(measurements) });
+			}
+		}
+		const report: ReplayReportInput = {
+			config: {
+				policies: parsed.policies,
+				budgets: parsed.budgets,
+				threshold: parsed.threshold,
+				target: parsed.target,
+				seed: parsed.seed,
+				corpus: [...(parsed.sessions.length > 0 ? ["ledgers"] : []), ...parsed.synthetic],
+				filter: parsed.noFilter ? "none" : "default",
+				settings,
+			},
+			cascade: loaded.cascade,
+			results,
+			gitSha: gitSha(),
+			commandLine: exactCommandLine(),
+		};
+		const markdown = renderReplayMarkdown(report);
+		if (parsed.markdownPath === undefined) process.stdout.write(markdown);
+		else {
+			const path = await writeOutput(parsed.markdownPath, markdown);
+			process.stdout.write(`${cascadeLine(loaded.cascade)}\nmarkdown ${path}\n`);
+		}
+		if (parsed.jsonPath !== undefined) {
+			const path = await writeOutput(parsed.jsonPath, renderReplayJson(report));
+			process.stdout.write(`json ${path}\n`);
+		}
+		return 0;
+	} catch (error) {
+		process.stderr.write(`clio-coder context replay failed: ${error instanceof Error ? error.message : String(error)}\n`);
+		return 1;
+	}
+}
+
+async function sessionPath(value: string): Promise<string> {
+	const candidate = resolve(value);
+	try {
+		const facts = await stat(candidate);
+		if (facts.isDirectory()) return join(candidate, "current.jsonl");
+		if (facts.isFile()) return candidate;
+	} catch {
+		// A non-path value is resolved as a validated session id below.
+	}
+	try {
+		assertSafeId(value, "session");
+	} catch (error) {
+		throw new CliUsageError(error instanceof Error ? error.message : String(error));
+	}
+	const sessionsRoot = join(clioStatePath(), "sessions");
+	let cwdHashes: string[];
+	try {
+		cwdHashes = await readdir(sessionsRoot);
+	} catch {
+		throw new Error(`session not found: ${value}`);
+	}
+	for (const cwdHash of cwdHashes.sort()) {
+		const current = join(sessionsRoot, cwdHash, value, "current.jsonl");
+		try {
+			if ((await stat(current)).isFile()) return current;
+		} catch {
+			// Continue across repositories until the id is found.
+		}
+	}
+	throw new Error(`session not found: ${value}`);
+}
+
+async function pinnedLeafForSession(source: string): Promise<string | undefined> {
+	try {
+		const raw = await readFile(join(dirname(source), "meta.json"), "utf8");
+		const value = JSON.parse(raw) as unknown;
+		if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+		const pinned = (value as Record<string, unknown>).pinnedLeafTurnId;
+		return typeof pinned === "string" && pinned.length > 0 ? pinned : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+async function sessionCwdForSession(source: string): Promise<string | null> {
+	try {
+		const raw = await readFile(join(dirname(source), "meta.json"), "utf8");
+		const value = JSON.parse(raw) as unknown;
+		if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+		const cwd = (value as Record<string, unknown>).cwd;
+		return typeof cwd === "string" && cwd.length > 0 ? cwd : null;
+	} catch {
+		return null;
+	}
+}
+
+function formatWorkingSet(trace: Trace): string {
+	const view = foldWorkingSet(trace.entries);
+	const index = buildPathIndex(trace.entries, { cwd: trace.cwd });
+	const graph = buildReferenceGraph(trace, index);
+	const evictedTokens = [...view.evicted.values()].reduce((sum, state) => sum + state.tokensFreed, 0);
+	const churn = view.itemsEvicted === 0 ? "n/a" : (view.recalls / view.itemsEvicted).toFixed(3);
+	const opCounts = new Map<string, number>();
+	for (const observation of index.observations) {
+		opCounts.set(observation.op, (opCounts.get(observation.op) ?? 0) + 1);
+	}
+	const rewrittenPaths = new Set<string>();
+	for (const edge of graph.edges) {
+		if (edge.kind !== "file_rewrite") continue;
+		const path = index.byRef.get(edge.from)?.path;
+		if (path) rewrittenPaths.add(path);
+	}
+	const lines = [
+		`session: ${trace.id}`,
+		`source: ${trace.source}`,
+		"working set:",
+		`  policy: ${view.lastPolicyId ?? "none"}`,
+		`  eviction events: ${view.evictionEvents}`,
+		`  evicted refs: ${view.evicted.size}`,
+		`  items evicted: ${view.itemsEvicted}`,
+		`  evicted tokens: ${evictedTokens}`,
+		`  recalls: ${view.recalls}`,
+		`  churn: ${churn}`,
+		"  refs:",
+		...([...view.evicted.entries()].length === 0
+			? ["    none"]
+			: [...view.evicted.entries()]
+					.sort(([a], [b]) => a.localeCompare(b))
+					.map(([ref, state]) => `    ${ref} reason=${state.reason} by=${state.by ?? "-"} tokens=${state.tokensFreed}`)),
+		"path index:",
+		`  observations: ${index.observations.length}`,
+		`  ops: ${
+			[...opCounts.entries()]
+				.sort(([a], [b]) => a.localeCompare(b))
+				.map(([op, count]) => `${op}=${count}`)
+				.join(", ") || "none"
+		}`,
+		`  paths with rewrites: ${rewrittenPaths.size}`,
+		...[...rewrittenPaths].sort().map((path) => `    ${path}`),
+		"",
+	];
+	return lines.join("\n");
+}
+
+export async function runContextWorkingSetCommand(args: string[]): Promise<number> {
+	if (args.includes("--help") || args.includes("-h")) {
+		process.stdout.write(WORKING_SET_HELP);
+		return 0;
+	}
+	let session: string | undefined;
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index];
+		if (arg === "--session") {
+			try {
+				session = requiredValue(args, index, arg);
+			} catch (error) {
+				process.stderr.write(
+					`clio-coder context working-set: ${error instanceof Error ? error.message : String(error)}\n${WORKING_SET_HELP}`,
+				);
+				return 2;
+			}
+			index += 1;
+			continue;
+		}
+		process.stderr.write(`clio-coder context working-set: unknown flag ${arg}\n${WORKING_SET_HELP}`);
+		return 2;
+	}
+	if (session === undefined) {
+		process.stderr.write(`clio-coder context working-set: --session is required\n${WORKING_SET_HELP}`);
+		return 2;
+	}
+	try {
+		const source = await sessionPath(session);
+		const raw = await readFile(source, "utf8");
+		const parsed = parseSessionEntries(raw, source);
+		if (parsed.errors.length > 0) throw new Error(parsed.errors.join("; "));
+		const entries = filterEntriesToActivePath(parsed.entries, await pinnedLeafForSession(source));
+		const cwd = await sessionCwdForSession(source);
+		process.stdout.write(
+			formatWorkingSet({
+				id: basename(dirname(source)),
+				source,
+				cwd,
+				entries,
+				turnCount: buildPathIndex(entries, { cwd }).turnCount,
+			}),
+		);
+		return 0;
+	} catch (error) {
+		if (error instanceof CliUsageError) {
+			process.stderr.write(`clio-coder context working-set: ${error.message}\n${WORKING_SET_HELP}`);
+			return 2;
+		}
+		process.stderr.write(
+			`clio-coder context working-set failed: ${error instanceof Error ? error.message : String(error)}\n`,
+		);
+		return 1;
+	}
+}

package/src/cli/context.ts

@@ -10,6 +10,8 @@ const HELP = `Usage:
                     [--target <id>] [--model <id>] [--thinking off|low|medium|high]
   clio-coder context reset [--all] [--yes]
   clio-coder context index [--json]
+  clio-coder context replay --sessions <path>... [options]
+  clio-coder context working-set --session <id|path>
 
 Project context commands:
   clio-coder context              show project context status (CLIO-CODER.md, preload, codewiki)
@@ -18,6 +20,8 @@ Project context commands:
   clio-coder context wiki         generate or inspect the agent-authored Markdown wiki
   clio-coder context reset        clear accumulated project context artifacts
   clio-coder context index        build the codewiki index without model calls
+  clio-coder context replay       compare working-set policies over Clio ledgers
+  clio-coder context working-set  inspect one session's working-set fold and path index
 `;
 
 function printWikiProgress(event: BootstrapProgressEvent): void {
@@ -313,6 +317,10 @@ export async function runContextCommand(args: string[]): Promise<number> {
 			return (await import("./context-clear.js")).runContextClearCommand(rest);
 		case "index":
 			return (await import("./context-index.js")).runContextIndexCommand(rest);
+		case "replay":
+			return (await import("./context-working-set.js")).runContextReplayCommand(rest);
+		case "working-set":
+			return (await import("./context-working-set.js")).runContextWorkingSetCommand(rest);
 		default:
 			process.stderr.write(`clio-coder context: unknown subcommand ${verb}\n`);
 			process.stdout.write(HELP);