@sayknow-cli/coding-agent 0.4.7 → 0.5.1

package/src/config/settings.ts

@@ -13,6 +13,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import * as util from "node:util";
 import {
 	getAgentDbPath,
 	getAgentDir,
@@ -43,6 +44,7 @@ import {
 	atomicYamlPathHash,
 	type CasReceipt,
 	deleteByPath,
+	enqueueAtomicYamlOperation,
 	reserveAtomicYamlUpdateSlot,
 	setByPath,
 } from "./atomic-yaml-patch";
@@ -364,6 +366,7 @@ export class Settings implements NotificationSettingsReader {
 	/** Pending debounced ordinary save; its queue slot is reserved immediately. */
 	#saveTimer?: NodeJS.Timeout;
 	#savePromise?: Promise<void>;
+	#changeListeners = new Set<(path: SettingPath) => void>();
 	#pendingSaveSlot?: PendingSaveSlot;
 
 	/** Legacy fallback migration warnings emitted once per settings instance. */
@@ -374,6 +377,8 @@ export class Settings implements NotificationSettingsReader {
 	/** A newer config schema must never be rewritten by legacy migrations. */
 	#futureSchemaVersion = false;
 	#hasMalformedConfigRoot = false;
+	/** YAML syntax was unrecoverable, so the loaded defaults are read-only until config.yml is repaired. */
+	#hasRecoveredConfigSyntax = false;
 	#hasInvalidNotificationConfiguration = false;
 	#notificationValidationGeneration = 0;
 	/** Notification subtree fingerprint from the last raw durable config read. */
@@ -385,7 +390,7 @@ export class Settings implements NotificationSettingsReader {
 	private constructor(options: SettingsOptions = {}) {
 		this.#cwd = path.normalize(options.cwd ?? getProjectDir());
 		this.#agentDir = path.normalize(options.agentDir ?? getAgentDir());
-		this.#configPath = options.inMemory ? null : path.join(this.#agentDir, "config.yml");
+		this.#configPath = options.inMemory ? null : path.resolve(this.#agentDir, "config.yml");
 		this.#persist = !options.inMemory;
 
 		if (options.overrides) {
@@ -523,6 +528,16 @@ export class Settings implements NotificationSettingsReader {
 		return structuredClone(this.#schemaReport);
 	}
 
+	onChanged(listener: (path: SettingPath) => void): () => void {
+		this.#changeListeners.add(listener);
+		return () => this.#changeListeners.delete(listener);
+	}
+
+	/** Whether durable settings mutations are permitted for the loaded configuration. */
+	canWriteDurableConfig(): boolean {
+		return !this.#persist || !this.#hasRecoveredConfigSyntax;
+	}
+
 	/**
 	 * Set a setting value (sync).
 	 * Updates global settings and reserves its background persistence slot before
@@ -533,6 +548,7 @@ export class Settings implements NotificationSettingsReader {
 			this.unset(path);
 			return;
 		}
+		this.#assertDurableConfigWritable();
 		this.#set(path, value, true);
 	}
 
@@ -556,6 +572,7 @@ export class Settings implements NotificationSettingsReader {
 
 		const hook = SETTING_HOOKS[path];
 		if (hook) hook(value, prev);
+		for (const listener of this.#changeListeners) listener(path);
 	}
 
 	/**
@@ -563,6 +580,7 @@ export class Settings implements NotificationSettingsReader {
 	 * `undefined` value. Defaults/project settings become visible immediately.
 	 */
 	unset<P extends SettingPath>(path: P): void {
+		this.#assertDurableConfigWritable();
 		const prev = this.get(path);
 		const patch: SettingsPatch = {
 			path,
@@ -580,6 +598,7 @@ export class Settings implements NotificationSettingsReader {
 
 		const hook = SETTING_HOOKS[path];
 		if (hook) hook(this.get(path), prev);
+		for (const listener of this.#changeListeners) listener(path);
 	}
 
 	/**
@@ -587,6 +606,7 @@ export class Settings implements NotificationSettingsReader {
 	 * {@link set}, canonical state and hooks change only after the rename succeeds.
 	 */
 	async commitAtomicBatch(patches: readonly SettingsAtomicPatch[]): Promise<CasReceipt> {
+		this.#assertDurableConfigWritable();
 		if (!this.#persist || !this.#configPath) {
 			const notificationValidationGuard = this.#notificationValidationRestoreGuard();
 			const changes = new Map<string, { before: unknown; beforeHash: string; afterHash: string }>();
@@ -687,13 +707,16 @@ export class Settings implements NotificationSettingsReader {
 		}));
 		for (const entry of revisions) this.#pathRevisions.set(entry.patch.path, entry.revision);
 
+		const commit = applyAtomicYamlPatches(this.#configPath, durablePatches, {
+			validateRoot: (root, currentPatches) =>
+				this.#rejectAtomicNotificationRepairForMalformedRoot(currentPatches, root),
+			onRestored: restoredPatches =>
+				this.#applyRestoredDurableBatch(revisions, restoredPatches, notificationValidationGuard),
+		});
+		const failureRefresh = this.#reserveAtomicFailureRefresh(commit);
 		try {
-			const receipt = await applyAtomicYamlPatches(this.#configPath, durablePatches, {
-				validateRoot: (root, currentPatches) =>
-					this.#rejectAtomicNotificationRepairForMalformedRoot(currentPatches, root),
-				onRestored: restoredPatches =>
-					this.#applyRestoredDurableBatch(revisions, restoredPatches, notificationValidationGuard),
-			});
+			const receipt = await commit;
+			await failureRefresh;
 			const appliedNotificationMutation = this.#applyDurableBatch(revisions);
 			this.#recordNotificationValidationBatchApply(notificationValidationGuard, appliedNotificationMutation);
 			return receipt;
@@ -704,6 +727,7 @@ export class Settings implements NotificationSettingsReader {
 					else this.#pathRevisions.set(entry.patch.path, entry.previousRevision);
 				}
 			}
+			await failureRefresh;
 			if (this.#modified.size > 0 && !this.#pendingSaveSlot) this.#queueSave();
 			throw error;
 		}
@@ -715,6 +739,7 @@ export class Settings implements NotificationSettingsReader {
 			current: Readonly<RawSettings>,
 		) => Promise<readonly SettingsAtomicPatch[]> | readonly SettingsAtomicPatch[],
 	): Promise<CasReceipt> {
+		this.#assertDurableConfigWritable();
 		if (!this.#persist || !this.#configPath) {
 			const patches = await buildPatches(structuredClone(this.#global));
 			return this.commitAtomicBatch(patches);
@@ -723,38 +748,41 @@ export class Settings implements NotificationSettingsReader {
 		this.#releasePendingSaveSlot();
 		let revisions: DurableBatchRevision[] = [];
 		const notificationValidationGuard = this.#notificationValidationRestoreGuard();
+		const commit = applyAtomicYamlPatchesWithCurrent(
+			this.#configPath,
+			async current => {
+				const patches = await buildPatches(structuredClone(current));
+				const durablePatches: AtomicYamlPatch[] = patches.map(patch => {
+					if (!isAtomicSettingsPath(patch.path)) {
+						throw new Error(`Unknown setting path for atomic batch: ${patch.path}`);
+					}
+					if (patch.op === "unset") return { path: patch.path, op: "unset" };
+					if (patch.value === undefined) {
+						throw new TypeError(
+							`Settings set patch for ${patch.path} cannot carry undefined; use unset instead.`,
+						);
+					}
+					return { path: patch.path, op: "set", value: structuredClone(patch.value) };
+				});
+				revisions = durablePatches.map(patch => ({
+					patch,
+					revision: ++this.#nextRevision,
+					previousRevision: this.#pathRevisions.get(patch.path),
+				}));
+				for (const entry of revisions) this.#pathRevisions.set(entry.patch.path, entry.revision);
+				return durablePatches;
+			},
+			{
+				validateRoot: (root, currentPatches) =>
+					this.#rejectAtomicNotificationRepairForMalformedRoot(currentPatches, root),
+				onRestored: restoredPatches =>
+					this.#applyRestoredDurableBatch(revisions, restoredPatches, notificationValidationGuard),
+			},
+		);
+		const failureRefresh = this.#reserveAtomicFailureRefresh(commit);
 		try {
-			const receipt = await applyAtomicYamlPatchesWithCurrent(
-				this.#configPath,
-				async current => {
-					const patches = await buildPatches(structuredClone(current));
-					const durablePatches: AtomicYamlPatch[] = patches.map(patch => {
-						if (!isAtomicSettingsPath(patch.path)) {
-							throw new Error(`Unknown setting path for atomic batch: ${patch.path}`);
-						}
-						if (patch.op === "unset") return { path: patch.path, op: "unset" };
-						if (patch.value === undefined) {
-							throw new TypeError(
-								`Settings set patch for ${patch.path} cannot carry undefined; use unset instead.`,
-							);
-						}
-						return { path: patch.path, op: "set", value: structuredClone(patch.value) };
-					});
-					revisions = durablePatches.map(patch => ({
-						patch,
-						revision: ++this.#nextRevision,
-						previousRevision: this.#pathRevisions.get(patch.path),
-					}));
-					for (const entry of revisions) this.#pathRevisions.set(entry.patch.path, entry.revision);
-					return durablePatches;
-				},
-				{
-					validateRoot: (root, currentPatches) =>
-						this.#rejectAtomicNotificationRepairForMalformedRoot(currentPatches, root),
-					onRestored: restoredPatches =>
-						this.#applyRestoredDurableBatch(revisions, restoredPatches, notificationValidationGuard),
-				},
-			);
+			const receipt = await commit;
+			await failureRefresh;
 			const appliedNotificationMutation = this.#applyDurableBatch(revisions);
 			this.#recordNotificationValidationBatchApply(notificationValidationGuard, appliedNotificationMutation);
 			return receipt;
@@ -765,6 +793,7 @@ export class Settings implements NotificationSettingsReader {
 					else this.#pathRevisions.set(entry.patch.path, entry.previousRevision);
 				}
 			}
+			await failureRefresh;
 			if (this.#modified.size > 0 && !this.#pendingSaveSlot) this.#queueSave();
 			throw error;
 		}
@@ -819,6 +848,15 @@ export class Settings implements NotificationSettingsReader {
 			}
 		}
 		await this.#refreshDurableSettings();
+		if (this.#modified.size > 0 && !this.#pendingSaveSlot) {
+			this.#queueSave();
+			this.#releasePendingSaveSlot();
+			try {
+				await this.#savePromise;
+			} catch {
+				// Keep dirty state for a later explicit flush or mutation.
+			}
+		}
 	}
 
 	/** Like {@link flush}, but reports a durable save failure to the caller. */
@@ -826,8 +864,20 @@ export class Settings implements NotificationSettingsReader {
 		this.#releasePendingSaveSlot();
 		if (this.#modified.size > 0 && !this.#pendingSaveSlot) this.#queueSave();
 		this.#releasePendingSaveSlot();
-		await this.#savePromise;
+		let saveError: unknown;
+		try {
+			await this.#savePromise;
+		} catch (error) {
+			saveError = error;
+		}
 		await this.#refreshDurableSettings();
+		if (this.#modified.size > 0 && !this.#pendingSaveSlot) {
+			this.#queueSave();
+			this.#releasePendingSaveSlot();
+			await this.#savePromise;
+			return;
+		}
+		if (saveError !== undefined) throw saveError;
 	}
 
 	async cloneForCwd(cwd: string): Promise<Settings> {
@@ -841,15 +891,23 @@ export class Settings implements NotificationSettingsReader {
 			inMemory: !this.#persist,
 		});
 		cloned.#storage = this.#storage;
+		cloned.#schemaReport = structuredClone(this.#schemaReport);
+		cloned.#schemaMigrationPending = this.#schemaMigrationPending;
 		cloned.#futureSchemaVersion = this.#futureSchemaVersion;
-
+		cloned.#hasMalformedConfigRoot = this.#hasMalformedConfigRoot;
+		cloned.#hasRecoveredConfigSyntax = this.#hasRecoveredConfigSyntax;
+		cloned.#hasInvalidNotificationConfiguration = this.#hasInvalidNotificationConfiguration;
+		cloned.#notificationValidationGeneration = this.#notificationValidationGeneration;
 		cloned.#global = structuredClone(this.#global);
 		cloned.#rawNotificationConfig = structuredClone(this.#rawNotificationConfig);
 		cloned.#durableRawNotificationConfig = structuredClone(this.#durableRawNotificationConfig);
 		cloned.#durableNotificationFingerprint = this.#durableNotificationFingerprint;
 		cloned.#project = this.#persist ? await cloned.#loadProjectSettings() : structuredClone(this.#project);
 		cloned.#overrides = structuredClone(this.#overrides);
-		await cloned.#normalizeAfterLoad();
+		if (cloned.#hasRecoveredConfigSyntax) {
+			cloned.#sanitizeModelSelectorRecords();
+			cloned.#rebuildMerged();
+		} else await cloned.#normalizeAfterLoad();
 		cloned.#fireAllHooks();
 		return cloned;
 	}
@@ -941,6 +999,7 @@ export class Settings implements NotificationSettingsReader {
 	}
 
 	setGlobalModelRole(role: ModelRole | string, modelId: ModelSelectorValue | undefined): void {
+		this.#assertDurableConfigWritable();
 		const revision = ++this.#nextRevision;
 		const patch: SettingsPatch = {
 			path: "modelRoles",
@@ -974,13 +1033,27 @@ export class Settings implements NotificationSettingsReader {
 	}
 
 	#replaceGlobalWithDurable(current: RawSettings): void {
+		const previous = new Map<SettingPath, unknown>();
+		for (const settingPath of Object.keys(SETTINGS_SCHEMA) as SettingPath[]) {
+			previous.set(settingPath, structuredClone(this.get(settingPath)));
+		}
 		this.#global = current;
 		for (const patch of this.#pendingPatchesInGenerationOrder()) {
 			applySettingsPatch(this.#global, { ...patch, value: structuredClone(patch.value) });
-			this.#applyNotificationMutationToRaw(patch.path, patch.value);
+			if (this.#rawNotificationConfig !== undefined) {
+				this.#applyNotificationMutationToRaw(patch.path, patch.value);
+			}
 		}
 		this.#rebuildMerged();
 		this.#recomputeNotificationValidationFromRaw();
+		for (const settingPath of Object.keys(SETTINGS_SCHEMA) as SettingPath[]) {
+			const previousValue = previous.get(settingPath);
+			const nextValue = this.get(settingPath);
+			if (util.isDeepStrictEqual(previousValue, nextValue)) continue;
+			const hook = SETTING_HOOKS[settingPath];
+			if (hook) hook(nextValue, previousValue);
+			for (const listener of this.#changeListeners) listener(settingPath);
+		}
 	}
 	/**
 	 * Set an agent model override while keeping any live runtime override aligned.
@@ -1074,60 +1147,97 @@ export class Settings implements NotificationSettingsReader {
 		}
 	}
 
-	async #loadYaml(filePath: string): Promise<RawSettings> {
+	#resetYamlLoadState(): void {
 		this.#hasMalformedConfigRoot = false;
+		this.#hasRecoveredConfigSyntax = false;
 		this.#hasInvalidNotificationConfiguration = false;
+		this.#schemaReport = { issues: [], valid: true };
+		this.#schemaMigrationPending = false;
+		this.#futureSchemaVersion = false;
 		this.#captureRawNotificationConfig({});
-		try {
-			const content = await Bun.file(filePath).text();
-			const parsed = YAML.parse(content);
-			if (parsed === undefined) return {};
-			if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-				this.#hasMalformedConfigRoot = true;
-				this.#captureRawNotificationConfig(undefined);
-				return {};
-			}
-			const parsedRaw = parsed as RawSettings;
-			if (filePath === this.#configPath) this.#captureRawNotificationConfig(parsedRaw);
-			if (filePath === this.#configPath) {
-				try {
-					parseNotificationSettingsSnapshot(parsedRaw);
-				} catch (error) {
-					if (!(error instanceof Error) || error.message !== "skc_notify_daemon_invalid_configuration")
-						throw error;
-					this.#hasInvalidNotificationConfiguration = true;
-				}
-			}
-			this.#futureSchemaVersion =
-				filePath === this.#configPath &&
-				typeof parsedRaw.configSchemaVersion === "number" &&
-				parsedRaw.configSchemaVersion > CONFIG_SCHEMA_VERSION;
+	}
 
-			const configSchemaVersion = parsedRaw.configSchemaVersion;
-			if (
-				filePath === this.#configPath &&
-				(typeof configSchemaVersion !== "number" || configSchemaVersion < CONFIG_SCHEMA_VERSION)
-			) {
-				this.#schemaMigrationPending = true;
-			}
-			const migrated = this.#migrateRawSettings(parsedRaw);
-			const reconciled = reconcileSettingsSchema(migrated);
-			if (typeof configSchemaVersion === "number" && configSchemaVersion > CONFIG_SCHEMA_VERSION) {
-				reconciled.report.issues.push({
-					path: "configSchemaVersion",
-					kind: "pending-migration",
-					detail: `Configuration requires schema version ${configSchemaVersion}.`,
-				});
-			}
-			this.#schemaReport = reconciled.report;
-			return reconciled.settings;
+	async #loadYaml(filePath: string): Promise<RawSettings> {
+		let content: string;
+		try {
+			content = await Bun.file(filePath).text();
 		} catch (error) {
 			if (isEnoent(error)) {
-				this.#captureRawNotificationConfig({});
+				this.#resetYamlLoadState();
 				return {};
 			}
 			throw error;
 		}
+		this.#resetYamlLoadState();
+		if (content.trim() === "") return {};
+		let parsed: unknown;
+		try {
+			parsed = YAML.parse(content);
+		} catch {
+			this.#hasRecoveredConfigSyntax = true;
+			this.#hasMalformedConfigRoot = true;
+			this.#schemaReport = {
+				valid: false,
+				issues: [
+					{
+						path: "config.yml",
+						kind: "invalid",
+						detail: "Configuration YAML syntax is invalid; repair config.yml before changing settings.",
+					},
+				],
+			};
+			this.#captureRawNotificationConfig(undefined);
+			return {};
+		}
+		if (parsed === undefined) return {};
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+			this.#hasMalformedConfigRoot = true;
+			this.#schemaReport = {
+				valid: false,
+				issues: [
+					{
+						path: "config.yml",
+						kind: "invalid",
+						detail: "Configuration root must be a YAML mapping.",
+					},
+				],
+			};
+			this.#captureRawNotificationConfig(undefined);
+			return {};
+		}
+		const parsedRaw = parsed as RawSettings;
+		if (filePath === this.#configPath) this.#captureRawNotificationConfig(parsedRaw);
+		if (filePath === this.#configPath) {
+			try {
+				parseNotificationSettingsSnapshot(parsedRaw);
+			} catch (error) {
+				if (!(error instanceof Error) || error.message !== "skc_notify_daemon_invalid_configuration") throw error;
+				this.#hasInvalidNotificationConfiguration = true;
+			}
+		}
+		this.#futureSchemaVersion =
+			filePath === this.#configPath &&
+			typeof parsedRaw.configSchemaVersion === "number" &&
+			parsedRaw.configSchemaVersion > CONFIG_SCHEMA_VERSION;
+
+		const configSchemaVersion = parsedRaw.configSchemaVersion;
+		if (
+			filePath === this.#configPath &&
+			(typeof configSchemaVersion !== "number" || configSchemaVersion < CONFIG_SCHEMA_VERSION)
+		) {
+			this.#schemaMigrationPending = true;
+		}
+		const migrated = this.#migrateRawSettings(parsedRaw);
+		const reconciled = reconcileSettingsSchema(migrated);
+		if (typeof configSchemaVersion === "number" && configSchemaVersion > CONFIG_SCHEMA_VERSION) {
+			reconciled.report.issues.push({
+				path: "configSchemaVersion",
+				kind: "pending-migration",
+				detail: `Configuration requires schema version ${configSchemaVersion}.`,
+			});
+		}
+		this.#schemaReport = reconciled.report;
+		return reconciled.settings;
 	}
 
 	async #loadProjectSettings(): Promise<RawSettings> {
@@ -1520,7 +1630,7 @@ export class Settings implements NotificationSettingsReader {
 	// ─────────────────────────────────────────────────────────────────────────
 
 	#queueSave(): void {
-		if (!this.#persist || !this.#configPath) return;
+		if (!this.#persist || !this.#configPath || this.#hasRecoveredConfigSyntax) return;
 
 		const currentSlot = this.#pendingSaveSlot;
 		if (currentSlot && !currentSlot.captured && !currentSlot.released) {
@@ -1587,25 +1697,33 @@ export class Settings implements NotificationSettingsReader {
 					this.#recomputeNotificationValidationFromRaw();
 				},
 			};
-		}).then(() => undefined);
-		this.#savePromise = save;
-		void save.catch(error => {
-			logger.warn("Settings: background save failed", { error: String(error) });
-			for (const patch of captured) {
-				const key = settingsPatchKey(patch);
-				if (this.#modified.get(key)?.generation === patch.generation) this.#modified.set(key, patch);
-			}
-			if (durableBeforeWrite) {
-				this.#global = durableBeforeWrite;
-				this.#captureRawNotificationConfig(durableBeforeWrite);
-				for (const patch of this.#pendingPatchesInGenerationOrder()) {
-					applySettingsPatch(this.#global, { ...patch, value: structuredClone(patch.value) });
-					this.#applyNotificationMutationToRaw(patch.path, patch.value);
+		})
+			.then(() => undefined)
+			.catch(async error => {
+				logger.warn("Settings: background save failed", { error: String(error) });
+				for (const patch of captured) {
+					const key = settingsPatchKey(patch);
+					if (this.#modified.get(key)?.generation === patch.generation) this.#modified.set(key, patch);
 				}
-				this.#rebuildMerged();
-				this.#recomputeNotificationValidationFromRaw();
-			}
-		});
+				if (durableBeforeWrite) {
+					this.#global = durableBeforeWrite;
+					this.#captureRawNotificationConfig(durableBeforeWrite);
+					for (const patch of this.#pendingPatchesInGenerationOrder()) {
+						applySettingsPatch(this.#global, { ...patch, value: structuredClone(patch.value) });
+						this.#applyNotificationMutationToRaw(patch.path, patch.value);
+					}
+					this.#rebuildMerged();
+					this.#recomputeNotificationValidationFromRaw();
+				}
+				try {
+					await this.#refreshDurableSettings();
+				} catch (refreshError) {
+					logger.warn("Settings: refresh after background save failure failed", { error: String(refreshError) });
+				}
+				throw error;
+			});
+		this.#savePromise = save;
+		void save.catch(() => {});
 		this.#armSaveTimer(slot);
 	}
 
@@ -1709,13 +1827,41 @@ export class Settings implements NotificationSettingsReader {
 		return applicable.some(patch => isNotificationSettingsPath(patch.path));
 	}
 
-	async #refreshDurableSettings(): Promise<void> {
-		if (!this.#persist || !this.#configPath) return;
+	#reserveAtomicFailureRefresh(commit: Promise<unknown>): Promise<void> {
+		if (!this.#persist || !this.#configPath) return Promise.resolve();
+		return enqueueAtomicYamlOperation(this.#configPath, async canonicalPath => {
+			try {
+				await commit;
+				return;
+			} catch {
+				// The original commit error remains authoritative. Recovery failures
+				// are diagnostic only and must not replace it.
+			}
+			try {
+				await this.#refreshDurableSettingsUnderQueue(canonicalPath);
+			} catch (refreshError) {
+				logger.warn("Settings: refresh after atomic batch failure failed", { error: String(refreshError) });
+			}
+		});
+	}
+	async #refreshDurableSettingsUnderQueue(canonicalPath: string): Promise<void> {
 		const previousFingerprint = this.#durableNotificationFingerprint;
-		const current = await this.#loadYaml(this.#configPath);
+		const current = await this.#loadYaml(canonicalPath);
 		if (previousFingerprint !== this.#durableNotificationFingerprint) this.#notificationValidationGeneration++;
 		this.#replaceGlobalWithDurable(current);
 	}
+	async #refreshDurableSettings(): Promise<void> {
+		if (!this.#persist || !this.#configPath) return;
+		await enqueueAtomicYamlOperation(this.#configPath, canonicalPath =>
+			this.#refreshDurableSettingsUnderQueue(canonicalPath),
+		);
+	}
+	#assertDurableConfigWritable(): void {
+		if (this.canWriteDurableConfig()) return;
+		throw new Error(
+			"Cannot change settings while config.yml has invalid YAML syntax. Repair config.yml and reload settings.",
+		);
+	}
 
 	// ─────────────────────────────────────────────────────────────────────────
 	// Utilities