@iowarp/clio-coder 0.3.8 → 0.4.0

package/src/cli/verifiers-inspect.ts

@@ -0,0 +1,347 @@
+/**
+ * Fixed machine-readable projection of this project's verification checks.
+ *
+ * `verifiers discover` renders an authoring preview and `verifiers validate`
+ * prints one sentence, so neither is a transport a GUI host can invoke. This
+ * command takes no identifier and no flag beyond `--json`, writes nothing, and
+ * runs no check: `verifiers dry-run` executes the production verify path and is
+ * a deliberate operator action, not something a browser refresh should trigger.
+ *
+ * What crosses is the shape of the check plane: which checks exist, where each
+ * was declared, which toolchain it drives, whether its argv is fixed, and
+ * whether the project catalog parses at all.
+ *
+ * What does not cross is the argv itself. A catalog check's `command` is an
+ * exact argument vector whose entries the schema permits to be absolute paths,
+ * so no width of projection makes it safe, and the executable is therefore
+ * classified against a closed set of toolchains rather than quoted. That is the
+ * same call trace event payloads and process command lines got: count and
+ * classify instead of projecting less. The declared `cwd`, the source file
+ * path, and every discovery diagnostic stay host-side for the same reason.
+ */
+
+import { isProjectVerifierCheckId } from "../core/verification-scripts.js";
+import {
+	type AuthoringCheck,
+	discoverVerifierAuthoring,
+	type VerifierProposalAuthority,
+	type VerifierSignalKind,
+} from "../tools/verify/authoring.js";
+import { loadProjectVerifierCatalog, PROJECT_VERIFIER_CATALOG_RELATIVE_PATH } from "../tools/verify/catalog.js";
+
+/** Wire bound on the emitted check list, independent of the catalog's own 128-check cap. */
+export const MAX_VERIFIERS_INSPECT_CHECKS = 64;
+
+const TAG_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
+const REJECTION_LOCATION_PATTERN = /^(root|checks\[\d{1,3}\])(\.[a-zA-Z]{1,32}(\[\d{1,3}\])?)?$/;
+
+/**
+ * Where a check was declared, and therefore how much of it the operator wrote.
+ *
+ * The domain's own `AuthoringCheck.state` also carries `manual`, which only the
+ * interactive authoring flow mints. Discovery cannot produce it, so it is not in
+ * this set: carrying a value this read can never emit would state a distinction
+ * it never establishes.
+ */
+export const VERIFIER_ORIGINS = ["package-script", "catalog", "proposed"] as const;
+export type VerifierOrigin = (typeof VERIFIER_ORIGINS)[number];
+
+/**
+ * The toolchain a check drives, classified from `command[0]`.
+ *
+ * The catalog schema already guarantees the executable is a single token and
+ * refuses every shell, so this is a classification over a constrained value
+ * rather than a redaction of an arbitrary one. `other` is a real answer: the
+ * operator still learns a check exists and how it is bound, just not which
+ * program outside this list it starts.
+ */
+export const VERIFIER_RUNNERS = [
+	"npm",
+	"pnpm",
+	"yarn",
+	"bun",
+	"deno",
+	"node",
+	"cargo",
+	"go",
+	"make",
+	"just",
+	"cmake",
+	"ctest",
+	"ninja",
+	"python",
+	"pytest",
+	"uv",
+	"tox",
+	"nox",
+	"dotnet",
+	"gradle",
+	"maven",
+	"rake",
+	"swift",
+	"other",
+] as const;
+export type VerifierRunner = (typeof VERIFIER_RUNNERS)[number];
+
+const RUNNER_ALIASES = new Map<string, VerifierRunner>([
+	["python3", "python"],
+	["python2", "python"],
+	["py", "python"],
+	["mvn", "maven"],
+	["gradlew", "gradle"],
+	["mvnw", "maven"],
+	["npx", "npm"],
+	["pnpx", "pnpm"],
+	["go-test", "go"],
+]);
+
+/** Why discovery could not enumerate the check plane at all. */
+export const VERIFIER_BLOCKS = ["catalog-rejected", "id-collision", "unclassified"] as const;
+export type VerifierBlock = (typeof VERIFIER_BLOCKS)[number];
+
+/**
+ * Why the production parser refused the project catalog.
+ *
+ * The parser's diagnostics quote the offending value, the workspace path, and
+ * the schema cap that was passed, so the sentence itself never crosses. The
+ * classification says what went wrong and `rejectedAt` says where, which is the
+ * pair an operator needs to find the line without being handed its contents.
+ */
+export const VERIFIER_REJECTIONS = [
+	"unreadable",
+	"invalid-yaml",
+	"unsupported-version",
+	"unknown-field",
+	"missing-field",
+	"duplicate-id",
+	"shell-command",
+	"too-large",
+	"invalid-cwd",
+	"invalid-value",
+	"unclassified",
+] as const;
+export type VerifierRejection = (typeof VERIFIER_REJECTIONS)[number];
+
+export interface VerifiersInspectCheck {
+	readonly id: string;
+	readonly description: string;
+	readonly origin: VerifierOrigin;
+	/** The declaration the harness read this check out of. */
+	readonly signal: VerifierSignalKind;
+	readonly authority: VerifierProposalAuthority;
+	/** The toolchain `command[0]` starts. The arguments themselves stay host-side. */
+	readonly runner: VerifierRunner;
+	/** How many arguments follow the executable, so an operator can see a bare invocation from a long one. */
+	readonly argumentCount: number;
+	/** True when the check runs at the repository root. A subdirectory's name does not cross. */
+	readonly runsAtRepositoryRoot: boolean;
+	/**
+	 * True when verify fixes argv, cwd, and timeout through safe-exec.
+	 *
+	 * A package-script check runs npm with the declared script name and may
+	 * accept explicit extra argv, so it is the one origin whose effective
+	 * command is not pinned by the declaration. That is a trust difference and
+	 * the reason this is reported rather than left to be inferred.
+	 */
+	readonly argvFixed: boolean;
+	readonly timeoutMs: number;
+	readonly tags: readonly string[];
+}
+
+export interface VerifiersInspectSnapshot {
+	readonly version: 1;
+	readonly generatedAt: string;
+	/** Whether the project catalog file exists at all. Its path stays host-side. */
+	readonly catalogPresent: boolean;
+	/** Whether the production parser accepted it; null when there is nothing to parse. */
+	readonly catalogValid: boolean | null;
+	readonly rejection: VerifierRejection | null;
+	/** The schema location the rejection named, such as `checks[3].command[0]`. */
+	readonly rejectedAt: string | null;
+	/** Whether the check plane could be enumerated. */
+	readonly discovery: "complete" | "blocked";
+	readonly blockedBy: VerifierBlock | null;
+	readonly checks: readonly VerifiersInspectCheck[];
+	readonly checksTruncated: boolean;
+	/** How many discovery diagnostics were raised. Each one quotes a path, so the text stays host-side. */
+	readonly diagnosticCount: number;
+}
+
+/**
+ * A codepoint scan rather than a regex, because the whole point is the control
+ * range and a character class over it is exactly what a linter refuses.
+ */
+function hasControlCharacter(value: string): boolean {
+	for (const character of value) {
+		const code = character.codePointAt(0) ?? 0;
+		if (code <= 0x1f || code === 0x7f) return true;
+	}
+	return false;
+}
+
+function runnerOf(executable: string | undefined): VerifierRunner {
+	if (executable === undefined) return "other";
+	const separator = Math.max(executable.lastIndexOf("/"), executable.lastIndexOf("\\"));
+	const base = executable
+		.slice(separator + 1)
+		.toLowerCase()
+		.replace(/\.(exe|cmd|bat|ps1)$/u, "");
+	const alias = RUNNER_ALIASES.get(base);
+	if (alias !== undefined) return alias;
+	return (VERIFIER_RUNNERS as ReadonlyArray<string>).includes(base) ? (base as VerifierRunner) : "other";
+}
+
+function rejectionMessage(reason: string): string {
+	const prefix = `${PROJECT_VERIFIER_CATALOG_RELATIVE_PATH}: `;
+	return reason.startsWith(prefix) ? reason.slice(prefix.length) : reason;
+}
+
+function rejectionLocation(message: string): string | null {
+	const match = /^(?:root|checks\[\d{1,3}\])(?:\.[a-zA-Z]{1,32}(?:\[\d{1,3}\])?)?/u.exec(message);
+	const candidate = match?.[0];
+	if (candidate === undefined) return null;
+	return REJECTION_LOCATION_PATTERN.test(candidate) ? candidate : null;
+}
+
+/**
+ * Classify the parser's sentence instead of quoting it.
+ *
+ * The order is the discriminating one, not the declaration one: a cap failure
+ * is a cap failure wherever it happened, and the cwd bucket is guarded on the
+ * location so a NUL byte in an argv entry does not read as a bad directory.
+ */
+function classifyRejection(reason: string): { rejection: VerifierRejection; rejectedAt: string | null } {
+	const message = rejectionMessage(reason);
+	const rejectedAt = rejectionLocation(message);
+	const has = (fragment: string): boolean => message.includes(fragment);
+	const rejection: VerifierRejection = has("invalid YAML")
+		? "invalid-yaml"
+		: has("cannot read catalog") || has("must be a regular file") || has("must resolve inside the workspace root")
+			? "unreadable"
+			: has("unsupported version")
+				? "unsupported-version"
+				: has("has unknown field(s)")
+					? "unknown-field"
+					: has(" is required")
+						? "missing-field"
+						: has("duplicates '") || has("contains duplicate tag")
+							? "duplicate-id"
+							: has("may not invoke shell executable") ||
+									has("must be one executable token") ||
+									has("shell command strings are not allowed")
+								? "shell-command"
+								: has("exceeds the")
+									? "too-large"
+									: rejectedAt?.endsWith(".cwd") === true
+										? "invalid-cwd"
+										: has("must be") || has("must match") || has("must not contain") || has("uses reserved")
+											? "invalid-value"
+											: "unclassified";
+	return { rejection, rejectedAt };
+}
+
+function classifyBlock(reason: string): VerifierBlock {
+	if (reason.includes(`${PROJECT_VERIFIER_CATALOG_RELATIVE_PATH}: `)) return "catalog-rejected";
+	if (reason.includes("duplicate declared check id ")) return "id-collision";
+	return "unclassified";
+}
+
+/**
+ * Re-enforce the shapes the catalog schema already guarantees.
+ *
+ * The ids and tags reaching here came through the production parser, so this is
+ * belt and braces rather than the first line of defence. It is worth the lines
+ * because a package.json script name is not held to the catalog's id rule, and
+ * because whatever wrote the declaration, the strings that cross carry no path,
+ * quote, space, or control byte.
+ */
+function projectCheck(check: AuthoringCheck): VerifiersInspectCheck | null {
+	// `manual` is only minted inside the interactive authoring flow, so a check
+	// carrying it here means this read was handed a draft rather than a discovery.
+	if (check.state === "manual") return null;
+	if (!isProjectVerifierCheckId(check.id) || check.id.length > 64) return null;
+	if (check.description.trim() !== check.description || check.description.length === 0) return null;
+	if (hasControlCharacter(check.description) || check.description.length > 512) return null;
+	const tags = check.tags.filter((tag) => TAG_PATTERN.test(tag) && tag.length <= 32);
+	if (tags.length !== check.tags.length) return null;
+	const origin: VerifierOrigin =
+		check.state === "active" ? "package-script" : check.state === "existing" ? "catalog" : "proposed";
+	return {
+		id: check.id,
+		description: check.description,
+		origin,
+		signal: check.provenance.kind,
+		authority: check.provenance.authority,
+		runner: runnerOf(check.command[0]),
+		argumentCount: Math.max(check.command.length - 1, 0),
+		runsAtRepositoryRoot: check.cwd === ".",
+		argvFixed: origin !== "package-script",
+		timeoutMs: check.timeoutMs,
+		tags,
+	};
+}
+
+const ORIGIN_RANK: Record<VerifierOrigin, number> = { "package-script": 0, catalog: 1, proposed: 2 };
+
+export function verifiersInspectSnapshot(
+	now: () => number = Date.now,
+	workspaceRoot: string = process.cwd(),
+): VerifiersInspectSnapshot {
+	const generatedAt = new Date(now()).toISOString();
+	// The catalog is loaded on its own rather than inferred from discovery,
+	// because discovery also fails on an id collision between package.json and
+	// the catalog, and "your catalog is broken" and "two declarations claim the
+	// same id" are different operator states with different repairs.
+	const catalog = loadProjectVerifierCatalog(workspaceRoot);
+	const catalogPresent = catalog.ok ? catalog.source !== null : true;
+	const classified = catalog.ok ? null : classifyRejection(catalog.reason);
+	const discovery = discoverVerifierAuthoring(workspaceRoot);
+	const base = {
+		version: 1,
+		generatedAt,
+		catalogPresent,
+		catalogValid: catalog.ok ? (catalog.source === null ? null : true) : false,
+		rejection: classified?.rejection ?? null,
+		rejectedAt: classified?.rejectedAt ?? null,
+	} as const;
+	if (!discovery.ok) {
+		return {
+			...base,
+			discovery: "blocked",
+			blockedBy: classifyBlock(discovery.reason),
+			checks: [],
+			checksTruncated: false,
+			diagnosticCount: 0,
+		};
+	}
+	const projected = [...discovery.activeChecks, ...discovery.existingChecks, ...discovery.proposals]
+		.map(projectCheck)
+		.filter((check): check is VerifiersInspectCheck => check !== null)
+		.sort((left, right) =>
+			ORIGIN_RANK[left.origin] !== ORIGIN_RANK[right.origin]
+				? ORIGIN_RANK[left.origin] - ORIGIN_RANK[right.origin]
+				: left.id < right.id
+					? -1
+					: left.id > right.id
+						? 1
+						: 0,
+		);
+	const checks = projected.slice(0, MAX_VERIFIERS_INSPECT_CHECKS);
+	return {
+		...base,
+		discovery: "complete",
+		blockedBy: null,
+		checks,
+		checksTruncated: checks.length < projected.length,
+		diagnosticCount: discovery.diagnostics.length,
+	};
+}
+
+export function runVerifiersInspect(args: ReadonlyArray<string>): number {
+	if (args.length !== 1 || args[0] !== "--json") {
+		process.stderr.write("clio-coder verifiers inspect: usage: clio-coder verifiers inspect --json\n");
+		return 2;
+	}
+	process.stdout.write(`${JSON.stringify(verifiersInspectSnapshot(), null, 2)}\n`);
+	return 0;
+}

package/src/cli/verifiers.ts

@@ -9,11 +9,13 @@ import {
 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";
+import { runVerifiersInspect } from "./verifiers-inspect.js";
 
 const HELP = `Project verifier authoring
 
 Usage:
   clio-coder verifiers discover
+  clio-coder verifiers inspect --json
   clio-coder verifiers author [--exclude <id>] [--rename <old>=<new>] [--dry-run <id>] [--yes]
   clio-coder verifiers validate
   clio-coder verifiers dry-run <id>
@@ -30,6 +32,10 @@ Fields:
 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.
+
+inspect is the fixed machine-readable read a GUI host may run. It takes no other
+argument, runs no check, and carries no argv, cwd, source path, or diagnostic
+text: the toolchain each check drives is classified, and the arguments stay here.
 `;
 
 const VALUE_OPTIONS = new Set([
@@ -282,6 +288,9 @@ function validateCommand(): number {
 }
 
 export async function runVerifiersCommand(argv: string[]): Promise<number> {
+	// Routed before the authoring parser so the fixed read stays exactly fixed. No
+	// authoring flag can reach it, and no flag it does not name can be spent on it.
+	if (argv[0] === "inspect") return runVerifiersInspect(argv.slice(1));
 	const parsed = parseAuthoringArgs(argv);
 	if (parsed.error !== undefined) {
 		printError(parsed.error);

package/src/core/bus-events.ts

@@ -51,6 +51,7 @@ export const BusChannels = {
 	ToolBudgetExceeded: "safety.toolBudgetExceeded",
 	ProviderHealth: "provider.health",
 	RuntimeNotice: "runtime.notice",
+	ResidencyMutation: "residency.mutation",
 	DispatchScopeNotice: "dispatch.scopeNotice",
 	DispatchEnqueued: "dispatch.enqueued",
 	DispatchStarted: "dispatch.started",
@@ -64,6 +65,7 @@ export const BusChannels = {
 	ContextWarning: "context.warning",
 	ContextPruned: "context.pruned",
 	ContextRecalled: "context.recalled",
+	MemoryStepCompleted: "memory.stepCompleted",
 	AgentStatusChanged: "agent.status.changed",
 	RunAborted: "run.aborted",
 	BudgetAlert: "budget.alert",
@@ -100,6 +102,28 @@ export interface RuntimeNoticePayload {
 	detail?: Record<string, number | string | boolean>;
 }
 
+/**
+ * One completed proactive-memory model step, published on
+ * {@link BusChannels.MemoryStepCompleted}. It carries the endpoint the step
+ * called and nothing about what the step decided: the only consumer is the
+ * turn context, which stamps an expected-cold reason when a step ran between
+ * turns on the endpoint the chat target streams against.
+ */
+export interface MemoryStepCompletedPayload {
+	endpointKey: string;
+	targetId: string;
+}
+
+/** A successful model load or eviction on one residency-managed endpoint. */
+export interface ResidencyMutationPayload {
+	targetKey: string;
+	targetId: string;
+	runtimeId: string;
+	model: string;
+	operation: "load" | "evict";
+	at: number;
+}
+
 /**
  * Window-resolution warning published on {@link BusChannels.ContextWarning}.
  * Emitted on transitions only: `warning` carries the text when a warning
@@ -133,7 +157,7 @@ export type DispatchScopeNoticePayload =
 	  };
 
 export type ContextActivityKind = "context-init" | "context-clear" | "context-refresh" | "context-wiki" | "compaction";
-export type ContextActivityPhase = "scan" | "codewiki" | "generate" | "clio-md" | "state" | "done";
+export type ContextActivityPhase = "scan" | "codewiki" | "generate" | "clio-md" | "state" | "compact" | "done";
 export type ContextActivityStatus = "started" | "running" | "completed" | "failed";
 
 /** Structured progress for context operations. Interactive renders this as a live context island. */
@@ -444,6 +468,8 @@ export interface PermissionRequestedPayload {
 	/** Sanitized one-line preview of the call's object (command, path, or compact args). */
 	target?: string | undefined;
 	timeoutMs?: number | undefined;
+	/** Admitted timeout fallback, so the operator surface can name what an expired ask became. */
+	fallback?: "deny" | "fail" | undefined;
 	escalation?: boolean | undefined;
 }
 
@@ -462,6 +488,8 @@ export interface PermissionResolvedPayload {
 	actionClass?: string | undefined;
 	reason?: string | undefined;
 	requestedBy?: string | undefined;
+	/** Effective fallback applied to an expired worker escalation. */
+	fallback?: "deny" | "fail" | undefined;
 	at?: number | undefined;
 }
 
@@ -505,6 +533,8 @@ export interface DispatchRunIdentity {
 	wireModelId: string;
 	runtimeId: string;
 	runtimeKind: RunKind;
+	/** Canonical inference scheduler and its resolved request-slot bound. */
+	endpoint?: { key: string; label: string; limit: number } | undefined;
 	/** Admitted invocation budget provenance for native workers. */
 	budget?: RunToolBudgetEnvelope | undefined;
 	/** Fleet node id the run was placed on; absent renders as the local node. */
@@ -761,6 +791,7 @@ export type BusPayloadMap = {
 	[BusChannels.ToolBudgetExceeded]: ToolBudgetExceededPayload;
 	[BusChannels.ProviderHealth]: ProviderHealthPayload;
 	[BusChannels.RuntimeNotice]: RuntimeNoticePayload;
+	[BusChannels.ResidencyMutation]: ResidencyMutationPayload;
 	[BusChannels.DispatchScopeNotice]: DispatchScopeNoticePayload;
 	[BusChannels.DispatchEnqueued]: DispatchEnqueuedPayload;
 	[BusChannels.DispatchStarted]: DispatchStartedPayload;
@@ -774,6 +805,7 @@ export type BusPayloadMap = {
 	[BusChannels.ContextWarning]: ContextWarningPayload;
 	[BusChannels.ContextPruned]: ContextPrunedPayload;
 	[BusChannels.ContextRecalled]: ContextRecalledPayload;
+	[BusChannels.MemoryStepCompleted]: MemoryStepCompletedPayload;
 	[BusChannels.AgentStatusChanged]: AgentStatusChangedPayload;
 	[BusChannels.RunAborted]: RunAbortedPayload;
 	[BusChannels.BudgetAlert]: BudgetAlertPayload;

package/src/core/cache-telemetry.ts

@@ -0,0 +1,42 @@
+/** Cache classification for one backend completion call. */
+export type BackendCacheVerdict = "hot" | "partial" | "cold" | "small";
+
+/** Backend timing source that directly reports local prefill work. */
+export type BackendTimingsSource = "llamacpp-timings" | "lmstudio-timings";
+
+/** Normalized prefill and prediction timings reported by the serving backend. */
+export interface BackendCompletionTimings {
+	promptTokens: number;
+	cachedTokens: number | null;
+	predictedTokens: number;
+	promptMs: number;
+	predictedMs: number;
+	source: BackendTimingsSource;
+}
+
+/** Per-session call counts grouped by backend cache verdict. */
+export interface CacheVerdictCounts {
+	hot: number;
+	partial: number;
+	cold: number;
+	small: number;
+}
+
+export function emptyCacheVerdictCounts(): CacheVerdictCounts {
+	return { hot: 0, partial: 0, cold: 0, small: 0 };
+}
+
+/** Return newly evaluated prefill tokens when the backend reports cache reads. */
+export function uncachedPrefillTokens(backend: BackendCompletionTimings | null | undefined): number | null {
+	if (backend === null || backend === undefined || backend.cachedTokens === null) return null;
+	if (
+		!Number.isFinite(backend.promptTokens) ||
+		backend.promptTokens < 0 ||
+		!Number.isFinite(backend.cachedTokens) ||
+		backend.cachedTokens < 0 ||
+		backend.cachedTokens > backend.promptTokens
+	) {
+		return null;
+	}
+	return backend.promptTokens - backend.cachedTokens;
+}

package/src/core/config.ts

@@ -521,6 +521,7 @@ function validateTarget(issues: Issues, path: string, value: unknown): ClioSetti
 		"gateway",
 		"pricing",
 		"lmstudio",
+		"maxConcurrentRequests",
 	]);
 	const id = "id" in value ? expectString(issues, `${path}.id`, value.id) : undefined;
 	const runtime = "runtime" in value ? expectString(issues, `${path}.runtime`, value.runtime) : undefined;
@@ -566,6 +567,10 @@ function validateTarget(issues: Issues, path: string, value: unknown): ClioSetti
 		const v = validateLmStudioSettings(issues, `${path}.lmstudio`, value.lmstudio);
 		if (v !== undefined) target.lmstudio = v;
 	}
+	if ("maxConcurrentRequests" in value) {
+		const v = expectInteger(issues, `${path}.maxConcurrentRequests`, value.maxConcurrentRequests, { min: 1 });
+		if (v !== undefined) target.maxConcurrentRequests = v;
+	}
 	return target;
 }
 
@@ -1004,6 +1009,8 @@ const TOP_LEVEL_KEYS = [
 	"keybindings",
 	"compaction",
 	"context",
+	"prewarm",
+	"panes",
 	"retry",
 	"guardrails",
 ] as const;
@@ -1589,6 +1596,66 @@ export function validateSettings(raw: unknown): SettingsValidationResult {
 		}
 	}
 
+	if ("prewarm" in raw) {
+		if (!isPlainObject(raw.prewarm)) {
+			issues.add("prewarm", `expected a map, got ${describe(raw.prewarm)}`);
+		} else {
+			issues.unknownKeys("prewarm", raw.prewarm, ["enabled"]);
+			if ("enabled" in raw.prewarm) {
+				const v = expectBoolean(issues, "prewarm.enabled", raw.prewarm.enabled);
+				if (v !== undefined) settings.prewarm.enabled = v;
+			}
+		}
+	}
+
+	if ("panes" in raw) {
+		if (!isPlainObject(raw.panes)) {
+			issues.add("panes", `expected a map, got ${describe(raw.panes)}`);
+		} else {
+			// `agents` and `keepFailed` are retired: pane-opening is no longer a
+			// per-dispatch policy (src/interactive/pane-policy.ts holds the one
+			// decision). They stay accepted-and-ignored so a settings file written
+			// against an older release keeps passing the strict boot gate.
+			issues.unknownKeys("panes", raw.panes, ["enabled", "agents", "keepFailed", "notifications", "journal", "yazi"]);
+			if ("enabled" in raw.panes) {
+				const v = expectEnum(issues, "panes.enabled", raw.panes.enabled, ["auto", "embedded", "off"] as const);
+				if (v !== undefined) settings.panes.enabled = v;
+			}
+			if ("notifications" in raw.panes) {
+				const v = expectEnum(issues, "panes.notifications", raw.panes.notifications, ["failures", "all", "off"] as const);
+				if (v !== undefined) settings.panes.notifications = v;
+			}
+			if ("journal" in raw.panes) {
+				const v = expectBoolean(issues, "panes.journal", raw.panes.journal);
+				if (v !== undefined) settings.panes.journal = v;
+			}
+			if ("yazi" in raw.panes) {
+				if (!isPlainObject(raw.panes.yazi)) {
+					issues.add("panes.yazi", `expected a map, got ${describe(raw.panes.yazi)}`);
+				} else {
+					const yazi = raw.panes.yazi;
+					issues.unknownKeys("panes.yazi", yazi, ["enabled", "mode", "profile", "followCwd"]);
+					if ("enabled" in yazi) {
+						const v = expectBoolean(issues, "panes.yazi.enabled", yazi.enabled);
+						if (v !== undefined) settings.panes.yazi.enabled = v;
+					}
+					if ("mode" in yazi) {
+						const v = expectEnum(issues, "panes.yazi.mode", yazi.mode, ["companion", "chooser"] as const);
+						if (v !== undefined) settings.panes.yazi.mode = v;
+					}
+					if ("profile" in yazi) {
+						const v = expectEnum(issues, "panes.yazi.profile", yazi.profile, ["managed", "user"] as const);
+						if (v !== undefined) settings.panes.yazi.profile = v;
+					}
+					if ("followCwd" in yazi) {
+						const v = expectBoolean(issues, "panes.yazi.followCwd", yazi.followCwd);
+						if (v !== undefined) settings.panes.yazi.followCwd = v;
+					}
+				}
+			}
+		}
+	}
+
 	if ("retry" in raw) {
 		if (!isPlainObject(raw.retry)) {
 			issues.add("retry", `expected a map, got ${describe(raw.retry)}`);