@iowarp/clio-coder 0.3.1 → 0.3.2

package/src/core/settings-layers.ts

@@ -21,7 +21,16 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { parse as parseYaml } from "yaml";
-import { type ClioSettings, settingsPath, validateSettings } from "./config.js";
+import {
+	applySettingsDelta,
+	type ClioSettings,
+	type SettingsIssue,
+	type SettingsMutator,
+	SettingsValidationError,
+	settingsPath,
+	updateSavedSettingsDocument,
+	validateSettings,
+} from "./config.js";
 
 export type SettingsOrigin = "built-in" | "user" | "project" | "project.local" | "cli";
 
@@ -29,6 +38,7 @@ export interface SettingsLayerIssue {
 	origin: SettingsOrigin;
 	path: string;
 	message: string;
+	kind?: SettingsIssue["kind"];
 }
 
 export interface SettingsLayerInfo {
@@ -45,6 +55,9 @@ export interface LayeredSettings {
 	layers: SettingsLayerInfo[];
 }
 
+const STRICT_USER_ISSUES = Symbol("strict-user-issues");
+type InternalLayeredSettings = LayeredSettings & { [STRICT_USER_ISSUES]: SettingsIssue[] };
+
 // Keys whose presence in a project layer means a credential leaked into a
 // committed file. `auth` carries target headers and api keys; the rest cover
 // stray secrets. Stripped from project layers with a diagnostic.
@@ -54,6 +67,18 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
+function deepEquals(a: unknown, b: unknown): boolean {
+	if (a === b) return true;
+	if (Array.isArray(a) || Array.isArray(b)) {
+		if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+		return a.every((entry, index) => deepEquals(entry, b[index]));
+	}
+	if (!isRecord(a) || !isRecord(b)) return false;
+	const keys = Object.keys(a);
+	if (keys.length !== Object.keys(b).length) return false;
+	return keys.every((key) => key in b && deepEquals(a[key], b[key]));
+}
+
 interface RawLayer {
 	origin: SettingsOrigin;
 	path: string;
@@ -62,16 +87,33 @@ interface RawLayer {
 
 function readRawLayer(origin: SettingsOrigin, path: string, issues: SettingsLayerIssue[]): RawLayer {
 	if (!existsSync(path)) return { origin, path, blob: undefined };
+	let text: string;
+	try {
+		text = readFileSync(path, "utf8");
+	} catch (err) {
+		issues.push({
+			origin,
+			path: "(root)",
+			message: `unreadable: ${err instanceof Error ? err.message : String(err)}`,
+			kind: "unreadable",
+		});
+		return { origin, path, blob: undefined };
+	}
 	let parsed: unknown;
 	try {
-		parsed = parseYaml(readFileSync(path, "utf8"));
+		parsed = parseYaml(text);
 	} catch (err) {
-		issues.push({ origin, path, message: `invalid YAML: ${err instanceof Error ? err.message : String(err)}` });
+		issues.push({
+			origin,
+			path: "(root)",
+			message: `invalid YAML: ${err instanceof Error ? err.message : String(err)}`,
+			kind: "syntax",
+		});
 		return { origin, path, blob: undefined };
 	}
 	if (parsed === null || parsed === undefined) return { origin, path, blob: {} };
 	if (!isRecord(parsed)) {
-		issues.push({ origin, path, message: "settings file must be a mapping at the root" });
+		issues.push({ origin, path: "(root)", message: "settings file must be a mapping at the root" });
 		return { origin, path, blob: undefined };
 	}
 	return { origin, path, blob: parsed };
@@ -146,22 +188,20 @@ export interface ReadLayeredSettingsOptions {
 	userPath?: string;
 }
 
-/**
- * Read and layer settings for `cwd`, returning the validated effective settings
- * plus per-leaf source attribution. Never throws: validation issues and layer
- * problems are returned, and the effective settings always validate (invalid
- * merges fall back to the schema defaults for the offending keys).
- */
-export function readLayeredSettings(cwd: string, options: ReadLayeredSettingsOptions = {}): LayeredSettings {
-	const issues: SettingsLayerIssue[] = [];
-	const userFile = options.userPath ?? settingsPath();
+interface PreparedLayers {
+	projectFile: string;
+	localFile: string;
+	projectRaw: RawLayer;
+	localRaw: RawLayer;
+	project: RawLayer;
+	local: RawLayer;
+}
+
+function prepareProjectLayers(cwd: string, issues: SettingsLayerIssue[]): PreparedLayers {
 	const projectFile = join(cwd, ".clio-coder", "settings.yaml");
 	const localFile = join(cwd, ".clio-coder", "settings.local.yaml");
-
-	const user = readRawLayer("user", userFile, issues);
 	const projectRaw = readRawLayer("project", projectFile, issues);
 	const localRaw = readRawLayer("project.local", localFile, issues);
-
 	const project: RawLayer = {
 		...projectRaw,
 		blob:
@@ -176,24 +216,118 @@ export function readLayeredSettings(cwd: string, options: ReadLayeredSettingsOpt
 				? undefined
 				: (stripCredentials(localRaw.blob, "project.local", "", issues) as Record<string, unknown>),
 	};
+	return { projectFile, localFile, projectRaw, localRaw, project, local };
+}
 
-	const { merged, sources } = mergeLayersWithSources([user, project, local]);
+function validateLayerStack(
+	user: RawLayer,
+	prepared: PreparedLayers,
+	issues: SettingsLayerIssue[],
+): { settings: ClioSettings; sources: Record<string, SettingsOrigin> } {
+	const { merged, sources } = mergeLayersWithSources([user, prepared.project, prepared.local]);
 	const validation = validateSettings(merged);
 	for (const issue of validation.issues) {
 		issues.push({ origin: settingsSourceFor(sources, issue.path), path: issue.path, message: issue.message });
 	}
+	return { settings: validation.settings, sources };
+}
+
+/**
+ * Read and layer settings for `cwd`, returning the validated effective settings
+ * plus per-leaf source attribution. Never throws: validation issues and layer
+ * problems are returned, and the effective settings always validate (invalid
+ * merges fall back to the schema defaults for the offending keys).
+ */
+export function readLayeredSettings(cwd: string, options: ReadLayeredSettingsOptions = {}): LayeredSettings {
+	const issues: SettingsLayerIssue[] = [];
+	const userFile = options.userPath ?? settingsPath();
+	const user = readRawLayer("user", userFile, issues);
+	const prepared = prepareProjectLayers(cwd, issues);
+	const { settings, sources } = validateLayerStack(user, prepared, issues);
 
+	const strictUserIssues =
+		user.blob === undefined
+			? []
+			: validateSettings(user.blob).issues.map((issue) => ({
+					path: issue.path,
+					message: issue.message,
+					...(issue.kind ? { kind: issue.kind } : {}),
+				}));
 	return {
-		settings: validation.settings,
+		settings,
 		sources,
 		issues,
 		layers: [
 			{ origin: "built-in", path: "(defaults)", present: true },
 			{ origin: "user", path: userFile, present: user.blob !== undefined },
-			{ origin: "project", path: projectFile, present: projectRaw.blob !== undefined },
-			{ origin: "project.local", path: localFile, present: localRaw.blob !== undefined },
+			{ origin: "project", path: prepared.projectFile, present: prepared.projectRaw.blob !== undefined },
+			{ origin: "project.local", path: prepared.localFile, present: prepared.localRaw.blob !== undefined },
 		],
-	};
+		[STRICT_USER_ISSUES]: strictUserIssues,
+	} as InternalLayeredSettings;
+}
+
+/**
+ * Read the complete effective stack once while retaining settings.yaml's
+ * strict launch gate. Project-layer issues remain diagnostics, matching the
+ * established best-effort workspace overlay contract.
+ */
+export function readStrictLayeredSettings(cwd: string, options: ReadLayeredSettingsOptions = {}): LayeredSettings {
+	const layered = readLayeredSettings(cwd, options) as InternalLayeredSettings;
+	const reportedUserIssues = layered.issues
+		.filter((issue) => issue.origin === "user")
+		.map(({ path, message, kind }): SettingsIssue => ({ path, message, ...(kind ? { kind } : {}) }));
+	const userIssues = [...reportedUserIssues, ...layered[STRICT_USER_ISSUES]].filter(
+		(issue, index, all) =>
+			all.findIndex(
+				(candidate) =>
+					candidate.path === issue.path && candidate.message === issue.message && candidate.kind === issue.kind,
+			) === index,
+	);
+	if (userIssues.length > 0) throw new SettingsValidationError(userIssues);
+	return layered;
+}
+
+/**
+ * Atomically persist a mutation of the effective workspace settings into the
+ * user layer. The candidate user document is re-layered with the same project
+ * files before it is written. This preserves references to project-only
+ * targets while refusing a mutation that a higher-precedence project leaf
+ * would silently override.
+ */
+export function updateLayeredSettings(cwd: string, mutate: SettingsMutator): ClioSettings {
+	let committed: ClioSettings | null = null;
+	updateSavedSettingsDocument((saved) => {
+		const userValidation = validateSettings(saved);
+		if (userValidation.issues.length > 0) throw new SettingsValidationError(userValidation.issues);
+		const issues: SettingsLayerIssue[] = [];
+		const prepared = prepareProjectLayers(cwd, issues);
+		const user: RawLayer = {
+			origin: "user",
+			path: settingsPath(),
+			blob: isRecord(saved) ? saved : {},
+		};
+		const before = validateLayerStack(user, prepared, issues).settings;
+		const candidate = structuredClone(before);
+		const next = mutate(candidate) ?? candidate;
+		const candidateValidation = validateSettings(JSON.parse(JSON.stringify(next)));
+		if (candidateValidation.issues.length > 0) throw new SettingsValidationError(candidateValidation.issues);
+
+		const nextSaved = applySettingsDelta(saved, before, candidateValidation.settings);
+		const finalIssues: SettingsLayerIssue[] = [];
+		const final = validateLayerStack(
+			{ origin: "user", path: settingsPath(), blob: isRecord(nextSaved) ? nextSaved : {} },
+			prepared,
+			finalIssues,
+		).settings;
+		if (!deepEquals(final, candidateValidation.settings)) {
+			throw new Error("a higher-precedence project setting prevents this settings update");
+		}
+		committed = final;
+		return nextSaved;
+	});
+	if (committed === null) throw new Error("layered settings update did not commit");
+	return committed;
 }
 
 /**

package/src/core/skill-activation.ts

@@ -7,7 +7,7 @@ export type PendingSkillRequestSource = "slash-command" | "selector" | "marketpl
  * reminder, and the operator-gate denial all cite this exact line so the
  * model learns a single protocol.
  */
-export const SKILL_SUGGESTION_ANCHOR = "Suggested skill: /skill:<name>";
+export const SKILL_SUGGESTION_ANCHOR = "Suggested skill: /skill <name>";
 
 /**
  * The part of the anchor a real reply keeps once `<name>` is substituted.

package/src/core/startup-timer.ts

@@ -15,13 +15,13 @@ export class StartupTimer {
 	private readonly start = performance.now();
 	private readonly marks: Mark[] = [];
 
-	constructor() {
-		traceBoot("boot start");
+	constructor(private readonly trace: (phase: string) => void = traceBoot) {
+		this.trace("boot start");
 	}
 
 	mark(name: string): void {
 		this.marks.push({ name, at: performance.now() - this.start });
-		traceBoot(name);
+		this.trace(name);
 	}
 
 	snapshot(): { totalMs: number; marks: ReadonlyArray<Mark> } {

package/src/core/state-file-lock.ts

@@ -1,6 +1,7 @@
 import { closeSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, utimesSync, writeSync } from "node:fs";
 import { hostname } from "node:os";
 import { dirname } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
 import { processAlive, processBirthToken } from "./process-identity.js";
 
 /**
@@ -36,6 +37,8 @@ export const FILE_LOCK_ACQUIRE_TIMEOUT_MS = 20_000;
 export interface StateFileLockOptions {
 	/** Acquisition budget. Default `FILE_LOCK_ACQUIRE_TIMEOUT_MS`. */
 	timeoutMs?: number;
+	/** Cancel an asynchronous lock wait and never enter or commit its critical section. */
+	signal?: AbortSignal;
 	/**
 	 * `run-unlocked` runs `fn` anyway when the lock cannot be taken. Residency
 	 * mutations need it: serializing them is an optimization and must never fail
@@ -158,9 +161,11 @@ export function withStateFileLockSync<T>(targetPath: string, fn: () => T, option
 	const timeoutMs = options.timeoutMs ?? FILE_LOCK_ACQUIRE_TIMEOUT_MS;
 	let held = false;
 	try {
+		options.signal?.throwIfAborted();
 		mkdirSync(dirname(lockPath), { recursive: true });
 		const deadlineMs = Date.now() + timeoutMs;
 		for (let attempt = 1; !tryAcquire(lockPath); attempt += 1) {
+			options.signal?.throwIfAborted();
 			if (Date.now() > deadlineMs) throw timeoutError(lockPath, timeoutMs);
 			// Atomics.wait rather than a timer: the callers of this variant are
 			// inside host APIs that cannot yield.
@@ -168,6 +173,7 @@ export function withStateFileLockSync<T>(targetPath: string, fn: () => T, option
 		}
 		held = true;
 	} catch (err) {
+		options.signal?.throwIfAborted();
 		if (options.onAcquireFailure !== "run-unlocked") throw err;
 	}
 	try {
@@ -186,15 +192,21 @@ export async function withStateFileLock<T>(
 	const timeoutMs = options.timeoutMs ?? FILE_LOCK_ACQUIRE_TIMEOUT_MS;
 	let held = false;
 	try {
+		options.signal?.throwIfAborted();
 		mkdirSync(dirname(lockPath), { recursive: true });
 		const deadlineMs = Date.now() + timeoutMs;
 		for (let attempt = 1; !tryAcquire(lockPath); attempt += 1) {
+			options.signal?.throwIfAborted();
 			if (Date.now() > deadlineMs) throw timeoutError(lockPath, timeoutMs);
 			const base = backoffMs(attempt);
-			await new Promise((resolve) => setTimeout(resolve, base + Math.floor(Math.random() * base)));
+			const delayMs = base + Math.floor(Math.random() * base);
+			if (options.signal) await sleep(delayMs, undefined, { signal: options.signal });
+			else await sleep(delayMs);
 		}
 		held = true;
+		options.signal?.throwIfAborted();
 	} catch (err) {
+		options.signal?.throwIfAborted();
 		if (options.onAcquireFailure !== "run-unlocked") throw err;
 	}
 	const stopRefresh = held ? startRefresh(lockPath) : null;

package/src/core/termination.ts

@@ -9,6 +9,12 @@
  * hanging hook cannot block the TUI from exiting. The cap is 500ms by
  * default and can be overridden via CLIO_CODER_SHUTDOWN_HOOK_MS for tests.
  * Timed-out hooks are logged and shutdown continues to the next hook.
+ *
+ * Every diagnostic here is written after the TUI has stopped: the interactive
+ * controller stops the terminal before it calls shutdown(), and the signal path
+ * stops it from a drain hook, which precedes persist. The renderer is gone, so
+ * a diagnostic goes to stderr and is wrapped to the terminal width so it does
+ * not overrun the frame the TUI just handed back.
  */
 
 import { BusChannels } from "./bus-events.js";
@@ -27,6 +33,46 @@ const SIGNAL_EXIT_CODES: Partial<Record<NodeJS.Signals, number>> = {
 	SIGTERM: 143,
 };
 
+/**
+ * Break `text` into lines no wider than `width` columns, at spaces where
+ * possible and mid-word when a single token is wider than the terminal.
+ */
+export function wrapToWidth(text: string, width: number): string[] {
+	if (!Number.isFinite(width) || width < 1) return [text];
+	const lines: string[] = [];
+	let current = "";
+	for (const word of text.split(/\s+/).filter((w) => w.length > 0)) {
+		let token = word;
+		while (token.length > width) {
+			if (current) {
+				lines.push(current);
+				current = "";
+			}
+			lines.push(token.slice(0, width));
+			token = token.slice(width);
+		}
+		if (!current) current = token;
+		else if (current.length + 1 + token.length <= width) current = `${current} ${token}`;
+		else {
+			lines.push(current);
+			current = token;
+		}
+	}
+	if (current) lines.push(current);
+	return lines.length > 0 ? lines : [""];
+}
+
+/**
+ * Emit a shutdown notice on stderr, wrapped to the terminal width when stderr
+ * or stdout is a TTY. Off a TTY the text goes out unwrapped, since a log
+ * consumer wants one record per line.
+ */
+export function writeShutdownNotice(text: string): void {
+	const width = process.stderr.columns ?? process.stdout.columns;
+	const lines = width === undefined ? [text] : wrapToWidth(text, width);
+	process.stderr.write(`${lines.join("\n")}\n`);
+}
+
 export function resolveShutdownHookBudgetMs(): number {
 	const raw = process.env.CLIO_CODER_SHUTDOWN_HOOK_MS;
 	if (raw === undefined) return DEFAULT_SHUTDOWN_HOOK_MS;
@@ -72,6 +118,8 @@ class TerminationCoordinator {
 	private readonly persistHooks: Hook[] = [];
 	private exitCode = 0;
 	private started = false;
+	private drained = false;
+	private readonly pendingNotices: string[] = [];
 	private signalHandler: ((signal: NodeJS.Signals) => void) | null = null;
 
 	getPhase(): TerminationPhase {
@@ -116,6 +164,8 @@ class TerminationCoordinator {
 		log("drain:start");
 		await this.runHooks(this.drainHooks, "drain", budgetMs, log);
 		log("drain:end");
+		this.drained = true;
+		this.flushNotices();
 		bus.emit(BusChannels.ShutdownDrained, {});
 
 		this.phase = "terminating";
@@ -142,13 +192,13 @@ class TerminationCoordinator {
 			if (!hook) continue;
 			const t0 = process.hrtime.bigint();
 			const completed = await runWithBudget(hook, budgetMs, (err) => {
-				console.error("[clio:termination] hook failed:", err);
+				const message = err instanceof Error ? err.message : String(err);
+				writeShutdownNotice(`[clio:termination] ${phase}[${i}] failed: ${message}`);
+				if (err instanceof Error && err.stack) log(err.stack);
 			});
 			const dt = Number(process.hrtime.bigint() - t0) / 1e6;
 			if (!completed) {
-				process.stderr.write(
-					`[clio:termination] ${phase}[${i}] exceeded ${budgetMs}ms budget; abandoning and continuing shutdown\n`,
-				);
+				writeShutdownNotice(`[clio:termination] ${phase}[${i}] exceeded ${budgetMs}ms budget; shutdown continues`);
 			}
 			log(`  ${phase}[${i}] ${dt.toFixed(1)}ms${completed ? "" : " (timed out)"}`);
 		}
@@ -163,7 +213,7 @@ class TerminationCoordinator {
 	installSignalHandlers(): void {
 		if (this.signalHandler) return;
 		const handler = (signal: NodeJS.Signals): void => {
-			process.stderr.write(`\nClio Coder: received ${signal}, shutting down...\n`);
+			this.notice(`Clio Coder: received ${signal}, shutting down...`);
 			void this.shutdown(SIGNAL_EXIT_CODES[signal] ?? 143);
 		};
 		this.signalHandler = handler;
@@ -172,6 +222,29 @@ class TerminationCoordinator {
 		process.once("SIGHUP", handler);
 	}
 
+	/**
+	 * Report something the operator should read after the process is gone,
+	 * such as which signal ended it. Nothing here knows whether a TUI is on
+	 * screen, but it does know that the terminal teardown is a drain hook: so
+	 * until drain has finished the notice is held, and the moment it has, the
+	 * notice goes to the terminal the TUI just handed back. Written straight
+	 * away once drain is over, which is the case for a re-armed SIGINT arriving
+	 * mid-shutdown. A second SIGTERM or SIGHUP inside the drain window takes
+	 * Node's default action and the held notice dies with the process; that
+	 * window is bounded by the per-hook budget and the shell reports the kill.
+	 */
+	notice(text: string): void {
+		if (this.drained) {
+			writeShutdownNotice(text);
+			return;
+		}
+		this.pendingNotices.push(text);
+	}
+
+	private flushNotices(): void {
+		for (const text of this.pendingNotices.splice(0)) writeShutdownNotice(text);
+	}
+
 	/**
 	 * Hand SIGINT to a foreground owner and return the call that takes it back.
 	 *

package/src/domains/config/classify.ts

@@ -21,7 +21,14 @@ export interface ConfigDiff {
 	restartRequired: string[];
 }
 
-const HOT_RELOAD_FIELDS = new Set<string>(["theme", "keybindings", "autonomy", "modelSelector"]);
+const HOT_RELOAD_FIELDS = new Set<string>([
+	"theme",
+	"keybindings",
+	"autonomy",
+	"modelSelector",
+	"terminal.smoothStreaming",
+	"attribution.gitCommits",
+]);
 
 const NEXT_TURN_FIELDS = new Set<string>([
 	"identity",
@@ -52,7 +59,12 @@ const NEXT_TURN_FIELDS = new Set<string>([
 	"retry",
 ]);
 
-const RESTART_REQUIRED_FIELDS = new Set<string>(["budget.concurrency", "runtimePlugins"]);
+const RESTART_REQUIRED_FIELDS = new Set<string>([
+	"budget.concurrency",
+	"runtimePlugins",
+	"terminal.tuiMode",
+	"terminal.fullscreenScrollbar",
+]);
 
 function matchesPrefix(path: string, fields: Set<string>): boolean {
 	if (fields.has(path)) return true;
@@ -67,8 +79,8 @@ export function diffSettings(prev: ClioSettings, next: ClioSettings): ConfigDiff
 	const diff: ConfigDiff = { hotReload: [], nextTurn: [], restartRequired: [] };
 	for (const p of changed) {
 		if (matchesPrefix(p, HOT_RELOAD_FIELDS)) diff.hotReload.push(p);
-		else if (matchesPrefix(p, NEXT_TURN_FIELDS)) diff.nextTurn.push(p);
 		else if (matchesPrefix(p, RESTART_REQUIRED_FIELDS)) diff.restartRequired.push(p);
+		else if (matchesPrefix(p, NEXT_TURN_FIELDS)) diff.nextTurn.push(p);
 		else {
 			// Unknown field falls back to restartRequired to fail closed.
 			diff.restartRequired.push(p);

package/src/domains/config/extension.ts

@@ -1,7 +1,8 @@
 import { BusChannels, type ConfigChangePayload } from "../../core/bus-events.js";
-import { type ClioSettings, formatSettingsFailure, readSettings, updateSettings } from "../../core/config.js";
+import { type ClioSettings, formatSettingsFailure } from "../../core/config.js";
 import type { DomainBundle, DomainContext, DomainExtension } from "../../core/domain-loader.js";
-import { readLayeredSettings } from "../../core/settings-layers.js";
+import { setGitCommitAttributionEnabled } from "../../core/git-commit-attribution.js";
+import { readStrictLayeredSettings, updateLayeredSettings } from "../../core/settings-layers.js";
 import { assertAgentIdNamespace } from "./agent-namespace.js";
 import { type ChangeKind, diffSettings } from "./classify.js";
 import type { ConfigContract } from "./contract.js";
@@ -13,7 +14,10 @@ interface NativeAgentNamespace {
 	list(): ReadonlyArray<{ id: string }>;
 }
 
-export function createConfigBundle(context: DomainContext): DomainBundle<ConfigContract> {
+export function createConfigBundle(
+	context: DomainContext,
+	initialSettings?: Readonly<ClioSettings>,
+): DomainBundle<ConfigContract> {
 	let watcher: ConfigWatcher | null = null;
 	let snapshot: ClioSettings | null = null;
 	let reloadFailure: string | null = null;
@@ -62,10 +66,9 @@ export function createConfigBundle(context: DomainContext): DomainBundle<ConfigC
 	function onWatcherFire(): void {
 		let next: ClioSettings;
 		try {
-			// readSettings keeps the strict throw-on-invalid-user-settings gate; the
-			// layered read then overlays project .clio-coder/settings(.local).yaml.
-			readSettings();
-			next = readLayeredSettings(process.cwd()).settings;
+			// One file read keeps the strict user-settings gate while workspace
+			// overlays retain their established best-effort diagnostics.
+			next = readStrictLayeredSettings(process.cwd()).settings;
 		} catch (err) {
 			// The rejection is the whole effect: `snapshot` is untouched, so the
 			// session keeps running on the last good settings.
@@ -81,6 +84,7 @@ export function createConfigBundle(context: DomainContext): DomainBundle<ConfigC
 		}
 		publishReloadFailure(null);
 		snapshot = next;
+		setGitCommitAttributionEnabled(next.attribution.gitCommits);
 		if (!prev) return;
 		const diff = diffSettings(prev, next);
 		if (diff.hotReload.length > 0) dispatch("hotReload", { diff, settings: next });
@@ -90,8 +94,9 @@ export function createConfigBundle(context: DomainContext): DomainBundle<ConfigC
 
 	const extension: DomainExtension = {
 		async start() {
-			readSettings();
-			snapshot = readLayeredSettings(process.cwd()).settings;
+			if (initialSettings) snapshot = structuredClone(initialSettings);
+			else snapshot = readStrictLayeredSettings(process.cwd()).settings;
+			setGitCommitAttributionEnabled(snapshot.attribution.gitCommits);
 			watcher = startConfigWatcher(() => onWatcherFire());
 		},
 		async stop() {
@@ -114,11 +119,12 @@ export function createConfigBundle(context: DomainContext): DomainBundle<ConfigC
 			const candidate = structuredClone(previous);
 			mutate(candidate);
 			assertAgentNamespace(candidate);
-			// updateSettings writes the user layer; re-layer so project overlays
-			// stay applied in the refreshed snapshot.
-			updateSettings(mutate);
-			const normalized = readLayeredSettings(process.cwd()).settings;
+			// Apply the effective-view delta to the user document under one lock,
+			// then validate it with the project layers before writing. In particular,
+			// a route may name a target supplied only by this workspace.
+			const normalized = updateLayeredSettings(process.cwd(), mutate);
 			snapshot = normalized;
+			setGitCommitAttributionEnabled(normalized.attribution.gitCommits);
 			const diff = diffSettings(previous, normalized);
 			if (diff.hotReload.length > 0) dispatch("hotReload", { diff, settings: normalized });
 			if (diff.nextTurn.length > 0) dispatch("nextTurn", { diff, settings: normalized });

package/src/domains/config/index.ts

@@ -7,6 +7,16 @@ export const ConfigDomainModule: DomainModule = {
 	createExtension: createConfigBundle,
 };
 
+/** Bind the one strict startup snapshot without changing other command paths. */
+export function createConfigDomainModule(
+	initialSettings: Readonly<import("../../core/config.js").ClioSettings>,
+): DomainModule {
+	return {
+		manifest: ConfigManifest,
+		createExtension: (context) => createConfigBundle(context, initialSettings),
+	};
+}
+
 export { assertAgentIdNamespace } from "./agent-namespace.js";
 export { type ChangeKind, type ConfigDiff, diffSettings } from "./classify.js";
 export type { ConfigContract } from "./contract.js";