@iowarp/clio-coder 0.3.3 → 0.3.6

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

@@ -14,6 +14,7 @@
 
 import type { AgentAudience } from "../domains/agents/spec.js";
 import type { ConfigDiff } from "../domains/config/classify.js";
+import type { RunToolBudgetEnvelope } from "../domains/dispatch/budget-envelope.js";
 import type {
 	DispatchRequestOrigin,
 	RunKind,
@@ -61,6 +62,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 +255,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;
 }
 
 // ---------------------------------------------------------------------------
@@ -466,6 +481,8 @@ export interface DispatchRunIdentity {
 	wireModelId: string;
 	runtimeId: string;
 	runtimeKind: RunKind;
+	/** Admitted invocation budget provenance for native workers. */
+	budget?: RunToolBudgetEnvelope | undefined;
 	/** Fleet node id the run was placed on; absent renders as the local node. */
 	node?: string | undefined;
 	/** Review/compete gate role and cycle, for fleet board badges. */
@@ -727,6 +744,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)}`);

package/src/core/defaults.ts

@@ -4,6 +4,7 @@
  * exist. Users edit the file directly or through TUI overlays.
  */
 
+import { DEFAULT_WORKING_SET_SETTINGS } from "../domains/context/working-set/defaults.js";
 import type { TargetDescriptor } from "../domains/providers/types/target-descriptor.js";
 import type { AutonomyLevel } from "../domains/safety/autonomy.js";
 import { GUARDRAIL_DEFAULTS, type GuardrailValues } from "./guardrails.js";
@@ -98,6 +99,32 @@ export interface CompactionSettings {
 	systemPrompt?: string;
 }
 
+/**
+ * Working-set layer settings (`context.workingSet`). The layer decides which
+ * tool-result bodies and thinking blocks leave the model's working set when
+ * pressure crosses `compaction.threshold`; it records evictions as ledger
+ * entries and never rewrites history. Defaults and prose live in
+ * src/domains/context/working-set/defaults.ts.
+ *
+ *   - enabled: master switch. Off skips eviction and goes straight to summary
+ *     compaction (the legacy destructive mask is only reachable through
+ *     CLIO_CODER_LEGACY_MASK=1).
+ *   - policy: candidate selection rule set.
+ *   - target: used/window ratio an applied event batches down to.
+ *   - protectLastTurns: recent user turns whose observations are never evicted.
+ *   - minEvictableTokens: results below this estimate are never evicted; the
+ *     marker would cost more than it saves.
+ */
+export type WorkingSetPolicyId = "age-horizon" | "structural-v1";
+
+export interface WorkingSetSettings {
+	enabled: boolean;
+	policy: WorkingSetPolicyId;
+	target: number;
+	protectLastTurns: number;
+	minEvictableTokens: number;
+}
+
 /**
  * Transient provider retry controls for the interactive chat loop. These are
  * intentionally small and mirror the session retry helper defaults. Dispatched
@@ -357,6 +384,9 @@ export const DEFAULT_SETTINGS = {
 		threshold: 0.8,
 		excludeLastTurns: 6,
 	} as CompactionSettings,
+	context: {
+		workingSet: DEFAULT_WORKING_SET_SETTINGS,
+	},
 	retry: {
 		enabled: true,
 		maxRetries: 3,
@@ -610,9 +640,9 @@ keybindings: {}
 #   auto              master switch for the pre-request compaction trigger.
 #                     Manual /context compact always runs the LLM summary.
 #   threshold         pressure = estimated_tokens / context_window. Crossing
-#                     it masks stale tool observations first, then runs a
-#                     full LLM summary if pressure stays above the threshold.
-#   excludeLastTurns  recent user turns protected from observation masking.
+#                     it evicts from the working set first, then runs a full
+#                     LLM summary if pressure stays above the threshold.
+#   excludeLastTurns  recent turns protected only by the temporary legacy mask.
 #   model             optional pattern (e.g. provider/summary-model-id) for a
 #                     dedicated summarization model. Absent ⇒ orchestrator target.
 #   systemPrompt      optional path to a prompt-override file.
@@ -623,6 +653,23 @@ compaction:
   # model: provider/summary-model-id
   # systemPrompt: ~/.config/clio-coder/prompts/compaction.md
 
+# Non-destructive working-set eviction before summary compaction.
+#   enabled             false skips eviction and goes directly to the summary stage.
+#   policy              structural-v1 evicts by what the session did since
+#                       (re-reads, edits, resolved failures, consumed listings)
+#                       and falls back to age only under pressure;
+#                       age-horizon is the previous age-based selection.
+#   target              pressure ratio an applied eviction batches down to.
+#   protectLastTurns    recent user turns whose observations remain in the working set.
+#   minEvictableTokens  entries below this estimate remain in the working set.
+context:
+  workingSet:
+    enabled: true
+    policy: structural-v1
+    target: 0.6
+    protectLastTurns: 6
+    minEvictableTokens: 200
+
 # Transient provider/stream retry controls for interactive chat.
 # Retryable errors include overloads, rate limits, 5xx responses, network
 # resets, and timeouts. Context overflow uses compaction recovery instead.