@iowarp/clio-coder 0.3.2 → 0.3.4

package/src/cli/evidence.ts

@@ -1,6 +1,6 @@
 import { InvalidIdError } from "../core/safe-id.js";
 import { clioDataDir, clioStateDir } from "../core/xdg.js";
-import type { EvidenceOverview, EvidenceRunProvenance } from "../domains/evidence/index.js";
+import type { CanonicalTrustStatus, EvidenceOverview, EvidenceRunProvenance } from "../domains/evidence/index.js";
 import {
 	buildEvalEvidence,
 	buildEvidence,
@@ -178,7 +178,7 @@ function renderEvidence(
 	input: Awaited<ReturnType<typeof inspectEvidence>>,
 	provenance: ReadonlyArray<EvidenceRunProvenance> = [],
 ): void {
-	const { overview, findings } = input;
+	const { overview, findings, trustStatus } = input;
 	process.stdout.write(`evidence: ${overview.evidenceId}\n`);
 	process.stdout.write(`source: ${formatSource(overview)}\n`);
 	process.stdout.write(`generated: ${overview.generatedAt}\n`);
@@ -188,6 +188,13 @@ function renderEvidence(
 	process.stdout.write(`blocked tools: ${overview.totals.blockedToolCalls}\n`);
 	process.stdout.write(`tags: ${formatList(overview.tags)}\n`);
 	process.stdout.write(`findings: ${findings.length}\n`);
+	if (trustStatus.projection === "historical_format") {
+		process.stdout.write("trust status: unavailable (historical bundle without canonical projection)\n");
+	} else {
+		for (const run of trustStatus.runs) {
+			process.stdout.write(`trust ${run.runId}: ${formatTrustStatus(run.status)}\n`);
+		}
+	}
 	// Provenance is printed only for runs whose receipts carry it, so a legacy
 	// bundle prints nothing new here.
 	for (const { runId, view } of provenance) {
@@ -197,6 +204,17 @@ function renderEvidence(
 	process.stdout.write(`files: ${formatList(overview.files)}\n`);
 }
 
+function formatTrustStatus(status: CanonicalTrustStatus): string {
+	return [
+		`artifactIntegrity=${status.artifactIntegrity.state}`,
+		`validationGrounding=${status.validationGrounding.state}`,
+		`independentReview=${status.independentReview.state}`,
+		`contextProvenance=${status.contextProvenance.state}`,
+		`autonomyEnforcement=${status.autonomyEnforcement.state}`,
+		`completionEvidence=${status.completionEvidence.state}`,
+	].join(" ");
+}
+
 function renderEvidenceList(overviews: ReadonlyArray<EvidenceOverview>): void {
 	process.stdout.write(`${overviews.length} evidence artifacts\n`);
 	if (overviews.length === 0) return;

package/src/cli/index.ts

@@ -52,6 +52,8 @@ Usage:
   clio-coder context wiki [--update] [--status] [--depth auto|simple|medium|detailed] [--target <id>] [--model <id>]
   clio-coder context reset [--all] [--yes]  clear accumulated project context artifacts
   clio-coder context index [--json]  build the codewiki index without model calls
+  clio-coder context replay --sessions <path>...  compare working-set policies over Clio ledgers
+  clio-coder context working-set --session <id|path>  inspect one session's working-set state
   clio-coder uninstall            remove all Clio Coder state; --remove-binary also unlinks the launcher
   clio-coder upgrade              upgrade Clio Coder and run pending migrations
   clio-coder agents               list discovered agent recipes
@@ -63,6 +65,7 @@ Usage:
   clio-coder trace                query or view the durable dispatch trace mirror
   clio-coder extensions           install, list, enable, disable, or remove extension packages
   clio-coder skills               list, inspect, validate, or install skills
+  clio-coder verifiers            discover, author, validate, edit, or dry-run project checks
   clio-coder docs [topic]         serve the HTML docs of a source checkout on 127.0.0.1 (--no-open to skip browser)
   clio-coder dev <command>        harness instruments; run 'clio-coder dev' for the list
   clio-coder --help, -h           this message
@@ -243,6 +246,7 @@ const COMMAND_HANDLERS = new Map<string, CommandHandler>([
 	["ext", extensionsCommand],
 	["fleet", async (subArgs) => (await import("./fleet.js")).runFleetCommand(subArgs)],
 	["skills", async (subArgs) => (await import("./skills.js")).runSkillsCommand(subArgs)],
+	["verifiers", async (subArgs) => (await import("./verifiers.js")).runVerifiersCommand(subArgs)],
 	["docs", async (subArgs) => (await import("./docs.js")).runDocsCommand(subArgs)],
 	["share", async (subArgs) => (await import("./share.js")).runShareCommand(subArgs)],
 	["export", async (subArgs) => (await import("./share.js")).runExportCommand(subArgs)],

package/src/cli/verifiers.ts

@@ -0,0 +1,325 @@
+import { SAFE_EXEC_DEFAULT_TIMEOUT_MS } from "../core/safe-exec.js";
+import {
+	createVerifierDraft,
+	discoverVerifierAuthoring,
+	previewVerifierDraft,
+	runVerifierAuthoringWorkflow,
+	type VerifierRevision,
+} from "../tools/verify/authoring.js";
+import { loadProjectVerifierCatalog, PROJECT_VERIFIER_CATALOG_RELATIVE_PATH } from "../tools/verify/catalog.js";
+import { verifyTool } from "../tools/verify/index.js";
+import { printError, printOk } from "./argv.js";
+
+const HELP = `Project verifier authoring
+
+Usage:
+  clio-coder verifiers discover
+  clio-coder verifiers author [--exclude <id>] [--rename <old>=<new>] [--dry-run <id>] [--yes]
+  clio-coder verifiers validate
+  clio-coder verifiers dry-run <id>
+  clio-coder verifiers add --id <id> --description <text> --command <json-argv> [fields] [--yes]
+  clio-coder verifiers edit <id> [--description <text>] [--command <json-argv>] [fields] [--yes]
+  clio-coder verifiers rename <old> <new> [--yes]
+  clio-coder verifiers remove <id> [--yes]
+
+Fields:
+  --cwd <path>            repository-relative working directory (default .)
+  --timeout-ms <number>   bounded timeout in milliseconds (default 120000)
+  --tags <a,b>            comma-separated catalog tags
+
+Discovery and every preview are read-only. Mutating commands write only with
+--yes after printing the exact argv, cwd, timeout, tags, source provenance, and
+effective execution authority. dry-run invokes the production verify path.
+`;
+
+const VALUE_OPTIONS = new Set([
+	"--id",
+	"--description",
+	"--command",
+	"--cwd",
+	"--timeout-ms",
+	"--tags",
+	"--exclude",
+	"--rename",
+	"--dry-run",
+]);
+
+interface ParsedAuthoringArgs {
+	yes: boolean;
+	help: boolean;
+	positional: string[];
+	values: Map<string, string[]>;
+	error?: string;
+}
+
+function parseAuthoringArgs(argv: ReadonlyArray<string>): ParsedAuthoringArgs {
+	const positional: string[] = [];
+	const values = new Map<string, string[]>();
+	let yes = false;
+	let help = false;
+	for (let index = 0; index < argv.length; index += 1) {
+		const arg = argv[index];
+		if (arg === "--yes") {
+			yes = true;
+			continue;
+		}
+		if (arg === "--help" || arg === "-h") {
+			help = true;
+			continue;
+		}
+		if (arg?.startsWith("--") === true) {
+			if (!VALUE_OPTIONS.has(arg)) return { yes, help, positional, values, error: `unknown option: ${arg}` };
+			const value = argv[index + 1];
+			if (value === undefined || value.startsWith("--")) {
+				return { yes, help, positional, values, error: `${arg} requires a value` };
+			}
+			const prior = values.get(arg) ?? [];
+			prior.push(value);
+			values.set(arg, prior);
+			index += 1;
+			continue;
+		}
+		if (arg !== undefined) positional.push(arg);
+	}
+	return { yes, help, positional, values };
+}
+
+function oneValue(parsed: ParsedAuthoringArgs, option: string): string | undefined {
+	return parsed.values.get(option)?.at(-1);
+}
+
+function parseCommand(value: string | undefined): string[] | Error {
+	if (value === undefined) return new Error("--command is required and must be a JSON argv array");
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(value) as unknown;
+	} catch (error) {
+		return new Error(`--command must be valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (!Array.isArray(parsed) || parsed.length === 0 || parsed.some((entry) => typeof entry !== "string")) {
+		return new Error("--command must be a non-empty JSON string array");
+	}
+	return parsed as string[];
+}
+
+function parseTimeout(value: string | undefined): number | Error {
+	if (value === undefined) return SAFE_EXEC_DEFAULT_TIMEOUT_MS;
+	const parsed = Number(value);
+	if (!Number.isInteger(parsed) || parsed <= 0) return new Error("--timeout-ms must be a positive integer");
+	return parsed;
+}
+
+function tags(value: string | undefined): string[] {
+	return value === undefined
+		? []
+		: value
+				.split(",")
+				.map((tag) => tag.trim())
+				.filter((tag) => tag.length > 0);
+}
+
+function requiredValue(parsed: ParsedAuthoringArgs, option: string): string | Error {
+	const value = oneValue(parsed, option);
+	return value === undefined || value.length === 0 ? new Error(`${option} is required`) : value;
+}
+
+function authorRevisions(parsed: ParsedAuthoringArgs): VerifierRevision[] | Error {
+	const revisions: VerifierRevision[] = [];
+	for (const id of parsed.values.get("--exclude") ?? []) revisions.push({ kind: "remove", id });
+	for (const rename of parsed.values.get("--rename") ?? []) {
+		const separator = rename.indexOf("=");
+		if (separator <= 0 || separator === rename.length - 1) {
+			return new Error("--rename must use <old>=<new>");
+		}
+		revisions.push({ kind: "rename", id: rename.slice(0, separator), newId: rename.slice(separator + 1) });
+	}
+	return revisions;
+}
+
+function addRevision(parsed: ParsedAuthoringArgs): VerifierRevision | Error {
+	const id = requiredValue(parsed, "--id");
+	if (id instanceof Error) return id;
+	const description = requiredValue(parsed, "--description");
+	if (description instanceof Error) return description;
+	const command = parseCommand(oneValue(parsed, "--command"));
+	if (command instanceof Error) return command;
+	const timeoutMs = parseTimeout(oneValue(parsed, "--timeout-ms"));
+	if (timeoutMs instanceof Error) return timeoutMs;
+	return {
+		kind: "add",
+		check: {
+			id,
+			description,
+			command,
+			cwd: oneValue(parsed, "--cwd") ?? ".",
+			timeoutMs,
+			tags: tags(oneValue(parsed, "--tags")),
+		},
+	};
+}
+
+function editRevision(parsed: ParsedAuthoringArgs): VerifierRevision | Error {
+	const id = parsed.positional[1];
+	if (id === undefined) return new Error("edit requires a check ID");
+	const changes: Extract<VerifierRevision, { kind: "edit" }>["changes"] = {};
+	const description = oneValue(parsed, "--description");
+	if (description !== undefined) changes.description = description;
+	const commandValue = oneValue(parsed, "--command");
+	if (commandValue !== undefined) {
+		const command = parseCommand(commandValue);
+		if (command instanceof Error) return command;
+		changes.command = command;
+	}
+	const cwd = oneValue(parsed, "--cwd");
+	if (cwd !== undefined) changes.cwd = cwd;
+	const timeoutValue = oneValue(parsed, "--timeout-ms");
+	if (timeoutValue !== undefined) {
+		const timeoutMs = parseTimeout(timeoutValue);
+		if (timeoutMs instanceof Error) return timeoutMs;
+		changes.timeoutMs = timeoutMs;
+	}
+	const tagValue = oneValue(parsed, "--tags");
+	if (tagValue !== undefined) changes.tags = tags(tagValue);
+	if (Object.keys(changes).length === 0) return new Error("edit requires at least one changed field");
+	return { kind: "edit", id, changes };
+}
+
+function mutationRevision(parsed: ParsedAuthoringArgs): VerifierRevision | Error {
+	const command = parsed.positional[0];
+	if (command === "add") return addRevision(parsed);
+	if (command === "edit") return editRevision(parsed);
+	if (command === "rename") {
+		const id = parsed.positional[1];
+		const newId = parsed.positional[2];
+		if (id === undefined || newId === undefined) return new Error("rename requires <old> and <new> IDs");
+		return { kind: "rename", id, newId };
+	}
+	if (command === "remove") {
+		const id = parsed.positional[1];
+		if (id === undefined) return new Error("remove requires a check ID");
+		return { kind: "remove", id };
+	}
+	return new Error(`unknown verifiers command: ${command ?? "(none)"}`);
+}
+
+function printDryRun(id: string, result: Awaited<ReturnType<typeof verifyTool.run>>): number {
+	if (result.kind === "error") {
+		printError(`dry-run '${id}' failed: ${result.message}`);
+		return 1;
+	}
+	process.stdout.write(`Dry run '${id}':\n${result.output}${result.output.endsWith("\n") ? "" : "\n"}`);
+	return 0;
+}
+
+async function executeWorkflow(
+	parsed: ParsedAuthoringArgs,
+	options: { includeProposals: boolean; revisions: VerifierRevision[] },
+): Promise<number> {
+	let printedPreview = false;
+	const dryRunCheckIds = parsed.values.get("--dry-run") ?? [];
+	const result = await runVerifierAuthoringWorkflow({
+		includeProposals: options.includeProposals,
+		initialRevisions: options.revisions,
+		confirmed: parsed.yes,
+		decide(context) {
+			process.stdout.write(`${context.preview}\n`);
+			printedPreview = true;
+			if (!parsed.yes || (context.draft.checks.length === 0 && options.revisions.length === 0)) {
+				return { kind: "reject" };
+			}
+			return { kind: "confirm", dryRunCheckIds };
+		},
+	});
+	if (result.status === "invalid") {
+		if (!printedPreview && result.preview !== undefined) process.stdout.write(`${result.preview}\n`);
+		printError(result.reason);
+		if (result.wrote && result.path !== undefined) {
+			process.stderr.write(`  ${result.path} was written; repair or remove it before running a check.\n`);
+		}
+		return 1;
+	}
+	if (result.status === "rejected") {
+		if (!parsed.yes) {
+			process.stdout.write("Review complete. Nothing changed; rerun the same command with --yes to write this preview.\n");
+		} else {
+			process.stdout.write(
+				"Nothing changed because the preview contains no catalog checks. Package checks remain active; unsupported commands can be added with `clio-coder verifiers add`.\n",
+			);
+		}
+		return 0;
+	}
+	printOk(`wrote ${result.path}; production parser accepted the catalog`);
+	let code = 0;
+	for (const dryRun of result.dryRuns) code = Math.max(code, printDryRun(dryRun.id, dryRun.result));
+	return code;
+}
+
+async function discoverCommand(): Promise<number> {
+	const discovery = discoverVerifierAuthoring();
+	if (!discovery.ok) {
+		printError(discovery.reason);
+		process.stderr.write(`${discovery.manualEntry}\n`);
+		return 1;
+	}
+	process.stdout.write(`${previewVerifierDraft(createVerifierDraft(discovery))}\n`);
+	return 0;
+}
+
+function validateCommand(): number {
+	const loaded = loadProjectVerifierCatalog(process.cwd());
+	if (!loaded.ok) {
+		printError(`production catalog parser rejected ${loaded.reason}`);
+		return 1;
+	}
+	if (loaded.source === null) {
+		process.stdout.write(`No ${PROJECT_VERIFIER_CATALOG_RELATIVE_PATH} exists. Run \`clio-coder verifiers author\`.\n`);
+		return 0;
+	}
+	printOk(
+		`production catalog parser accepted ${PROJECT_VERIFIER_CATALOG_RELATIVE_PATH} (${loaded.source.checks.length} check${loaded.source.checks.length === 1 ? "" : "s"})`,
+	);
+	return 0;
+}
+
+export async function runVerifiersCommand(argv: string[]): Promise<number> {
+	const parsed = parseAuthoringArgs(argv);
+	if (parsed.error !== undefined) {
+		printError(parsed.error);
+		process.stderr.write(HELP);
+		return 2;
+	}
+	if (parsed.help || parsed.positional.length === 0) {
+		process.stdout.write(HELP);
+		return 0;
+	}
+	const command = parsed.positional[0];
+	if (command === "discover") return discoverCommand();
+	if (command === "validate") return validateCommand();
+	if (command === "dry-run") {
+		const id = parsed.positional[1];
+		if (id === undefined) {
+			printError("dry-run requires a check ID");
+			return 2;
+		}
+		return printDryRun(id, await verifyTool.run({ check: id }));
+	}
+	if (command === "author") {
+		const revisions = authorRevisions(parsed);
+		if (revisions instanceof Error) {
+			printError(revisions.message);
+			return 2;
+		}
+		return executeWorkflow(parsed, { includeProposals: true, revisions });
+	}
+	if (["add", "edit", "rename", "remove"].includes(command ?? "")) {
+		const revision = mutationRevision(parsed);
+		if (revision instanceof Error) {
+			printError(revision.message);
+			return 2;
+		}
+		return executeWorkflow(parsed, { includeProposals: false, revisions: [revision] });
+	}
+	printError(`unknown verifiers command: ${command}`);
+	process.stderr.write(HELP);
+	return 2;
+}

package/src/core/bash-exec.ts

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { StringDecoder } from "node:string_decoder";
 import { AI_AGENT_NAME } from "./agent-environment.js";
 import {
 	gitCommitAttributionEnabled,
@@ -28,6 +29,8 @@ export interface BashCommandResult {
 	aborted: boolean;
 	timedOut: boolean;
 	outputCapped: boolean;
+	/** Exact bytes retained from stdout and stderr, never above the hard cap. */
+	outputBytes: number;
 }
 
 export interface BashCommandProgress {
@@ -151,6 +154,9 @@ export async function runBashCommand(command: string, options: RunBashCommandOpt
 		let killSent = false;
 		let stdout = "";
 		let stderr = "";
+		const stdoutDecoder = new StringDecoder("utf8");
+		const stderrDecoder = new StringDecoder("utf8");
+		let decodersFinished = false;
 		let outputBytes = 0;
 		let outputCapped = false;
 		let updateTimer: ReturnType<typeof setTimeout> | null = null;
@@ -164,6 +170,16 @@ export async function runBashCommand(command: string, options: RunBashCommandOpt
 			stdio: ["ignore", "pipe", "pipe"],
 		});
 
+		const finishDecoders = (): void => {
+			if (decodersFinished) return;
+			decodersFinished = true;
+			// A hard byte cap may bisect a multibyte code point. Discard the
+			// decoder's incomplete suffix instead of manufacturing U+FFFD.
+			if (outputCapped) return;
+			stdout += stdoutDecoder.end();
+			stderr += stderrDecoder.end();
+		};
+
 		const emitUpdate = (): void => {
 			if (options.onUpdate === undefined || !updateDirty) return;
 			updateDirty = false;
@@ -250,24 +266,20 @@ export async function runBashCommand(command: string, options: RunBashCommandOpt
 
 		const appendChunk = (target: "stdout" | "stderr", chunk: Buffer): void => {
 			if (outputCapped) return;
-			outputBytes += chunk.byteLength;
-			if (outputBytes > BASH_HARD_CAP_BYTES) {
-				// Keep the bytes seen so far (including this chunk's prefix would
-				// overshoot memory, so append the remaining budget) and stop the
-				// child. Truncation for display is tail-biased downstream.
-				const remaining = BASH_HARD_CAP_BYTES - (outputBytes - chunk.byteLength);
-				if (remaining > 0) {
-					const slice = chunk.subarray(0, remaining).toString("utf8");
-					if (target === "stdout") stdout += slice;
-					else stderr += slice;
-				}
+			const remaining = BASH_HARD_CAP_BYTES - outputBytes;
+			const accepted = chunk.byteLength <= remaining ? chunk : chunk.subarray(0, Math.max(0, remaining));
+			outputBytes += accepted.byteLength;
+			if (accepted.byteLength > 0) {
+				const decoded = target === "stdout" ? stdoutDecoder.write(accepted) : stderrDecoder.write(accepted);
+				if (target === "stdout") stdout += decoded;
+				else stderr += decoded;
+			}
+			if (accepted.byteLength < chunk.byteLength) {
 				outputCapped = true;
 				scheduleUpdate();
 				killChild();
 				return;
 			}
-			if (target === "stdout") stdout += chunk.toString("utf8");
-			else stderr += chunk.toString("utf8");
 			scheduleUpdate();
 		};
 
@@ -278,6 +290,7 @@ export async function runBashCommand(command: string, options: RunBashCommandOpt
 			settled = true;
 			if (timeoutId) clearTimeout(timeoutId);
 			clearKillGraceTimer();
+			finishDecoders();
 			finishUpdates();
 			options.signal?.removeEventListener("abort", onAbort);
 			resolve({
@@ -289,6 +302,7 @@ export async function runBashCommand(command: string, options: RunBashCommandOpt
 				aborted,
 				timedOut,
 				outputCapped,
+				outputBytes,
 			});
 		});
 		child.on("close", (code, signalName) => {
@@ -296,6 +310,7 @@ export async function runBashCommand(command: string, options: RunBashCommandOpt
 			settled = true;
 			if (timeoutId) clearTimeout(timeoutId);
 			clearKillGraceTimer();
+			finishDecoders();
 			finishUpdates();
 			options.signal?.removeEventListener("abort", onAbort);
 			const error =
@@ -307,7 +322,17 @@ export async function runBashCommand(command: string, options: RunBashCommandOpt
 							code: code ?? undefined,
 							signal: signalName ?? undefined,
 						} as NodeJS.ErrnoException);
-			resolve({ error, stdout, stderr, exitCode: code, signal: signalName, aborted, timedOut, outputCapped });
+			resolve({
+				error,
+				stdout,
+				stderr,
+				exitCode: code,
+				signal: signalName,
+				aborted,
+				timedOut,
+				outputCapped,
+				outputBytes,
+			});
 		});
 	});
 }

package/src/core/bus-events.ts

@@ -61,6 +61,7 @@ export const BusChannels = {
 	ContextActivity: "context.activity",
 	ContextWarning: "context.warning",
 	ContextPruned: "context.pruned",
+	ContextRecalled: "context.recalled",
 	AgentStatusChanged: "agent.status.changed",
 	RunAborted: "run.aborted",
 	BudgetAlert: "budget.alert",
@@ -253,21 +254,34 @@ export function isRunAbortedPayload(value: unknown): value is RunAbortedPayload
 	return true;
 }
 
-/** Payload published on {@link BusChannels.ContextPruned} after compaction reclaims tokens. */
+/** Payload published on {@link BusChannels.ContextPruned} after projected or summarized context shrinks. */
 export interface ContextPrunedPayload {
-	stage: "mask_observations" | "llm_summary";
+	stage: "mask_observations" | "working_set" | "llm_summary";
 	tokensBefore: number;
 	tokensAfter: number;
 	trigger: string;
 	snapshotIdBefore: string | null;
 	snapshotIdAfter: string;
 	at: number;
-	/** Used/window ratio at trigger time; mask stage only. */
+	/** Used/window ratio at trigger time; working-set and legacy-mask stages only. */
 	pressure?: number | null;
+	/** Legacy destructive-mask count. */
 	maskedObservations?: number;
-	/** Thinking blocks stripped from stale assistant messages; mask stage only. */
+	/** Thinking blocks stripped from stale assistant messages; legacy mask only. */
 	maskedThinkingBlocks?: number;
 	maskedThinkingChars?: number;
+	/** Working-set policy that selected an applied eviction event. */
+	policyId?: string;
+	/** Number of working-set units evicted by the event. */
+	evictedItems?: number;
+}
+
+/** Payload published on {@link BusChannels.ContextRecalled} after an exact working-set recall. */
+export interface ContextRecalledPayload {
+	ref: string;
+	trigger: "tool" | "operator";
+	tokensReadmitted: number;
+	at: number;
 }
 
 // ---------------------------------------------------------------------------
@@ -727,6 +741,7 @@ export type BusPayloadMap = {
 	[BusChannels.ContextActivity]: ContextActivityPayload;
 	[BusChannels.ContextWarning]: ContextWarningPayload;
 	[BusChannels.ContextPruned]: ContextPrunedPayload;
+	[BusChannels.ContextRecalled]: ContextRecalledPayload;
 	[BusChannels.AgentStatusChanged]: AgentStatusChangedPayload;
 	[BusChannels.RunAborted]: RunAbortedPayload;
 	[BusChannels.BudgetAlert]: BudgetAlertPayload;

package/src/core/config.ts

@@ -968,6 +968,7 @@ const TOP_LEVEL_KEYS = [
 	"delegation",
 	"keybindings",
 	"compaction",
+	"context",
 	"retry",
 	"guardrails",
 ] as const;
@@ -1405,6 +1406,59 @@ export function validateSettings(raw: unknown): SettingsValidationResult {
 		}
 	}
 
+	if ("context" in raw) {
+		if (!isPlainObject(raw.context)) {
+			issues.add("context", `expected a map, got ${describe(raw.context)}`);
+		} else {
+			issues.unknownKeys("context", raw.context, ["workingSet"]);
+			if ("workingSet" in raw.context) {
+				if (!isPlainObject(raw.context.workingSet)) {
+					issues.add("context.workingSet", `expected a map, got ${describe(raw.context.workingSet)}`);
+				} else {
+					const workingSet = raw.context.workingSet;
+					issues.unknownKeys("context.workingSet", workingSet, [
+						"enabled",
+						"policy",
+						"target",
+						"protectLastTurns",
+						"minEvictableTokens",
+					]);
+					if ("enabled" in workingSet) {
+						const v = expectBoolean(issues, "context.workingSet.enabled", workingSet.enabled);
+						if (v !== undefined) settings.context.workingSet.enabled = v;
+					}
+					if ("policy" in workingSet) {
+						const v = expectEnum(issues, "context.workingSet.policy", workingSet.policy, [
+							"age-horizon",
+							"structural-v1",
+						] as const);
+						if (v !== undefined) settings.context.workingSet.policy = v;
+					}
+					if ("target" in workingSet) {
+						const v = expectNumber(issues, "context.workingSet.target", workingSet.target);
+						if (v !== undefined && (v <= 0 || v >= 1)) {
+							issues.add("context.workingSet.target", `expected a number > 0 and < 1, got ${v}`);
+						} else if (v !== undefined) {
+							settings.context.workingSet.target = v;
+						}
+					}
+					if ("protectLastTurns" in workingSet) {
+						const v = expectInteger(issues, "context.workingSet.protectLastTurns", workingSet.protectLastTurns, {
+							min: 1,
+						});
+						if (v !== undefined) settings.context.workingSet.protectLastTurns = v;
+					}
+					if ("minEvictableTokens" in workingSet) {
+						const v = expectInteger(issues, "context.workingSet.minEvictableTokens", workingSet.minEvictableTokens, {
+							min: 0,
+						});
+						if (v !== undefined) settings.context.workingSet.minEvictableTokens = v;
+					}
+				}
+			}
+		}
+	}
+
 	if ("retry" in raw) {
 		if (!isPlainObject(raw.retry)) {
 			issues.add("retry", `expected a map, got ${describe(raw.retry)}`);