@narumitw/pi-caffeinate 0.28.0 → 0.35.0

package/README.md

@@ -119,11 +119,16 @@ when omitted. The file is read at startup and on `/reload`; run `/reload` after
 running Pi session before using mode commands.
 
 Missing, invalid, or deleted settings default back to `display` mode with quiet mode disabled on
-every supported OS.
-
-Compatibility: older versions used `pi-caffeinate-settings.json`. During the migration window, a
-legacy-only file is automatically migrated to `pi-caffeinate.json` with a warning. If both files
-exist, `pi-caffeinate.json` wins and the legacy file is ignored. The legacy filename is deprecated
+every supported OS. A missing file stays absent until the first successful mode change. Within one Pi process, mode saves run in invocation order, reread the latest valid document, and preserve unknown fields. Malformed
+JSON or an invalid recognized field blocks mode saves until repaired instead of being overwritten.
+A failed save keeps the prior runtime mode; if restarting an active inhibitor fails after publication,
+the extension restores the prior saved mode and inhibitor behavior or reports an explicit rollback
+failure.
+
+Compatibility: older versions used `pi-caffeinate-settings.json`. A legacy-only file remains
+readable with a warning and is never modified automatically; rename it to `pi-caffeinate.json`.
+The first subsequent settings save writes the canonical file. If both files exist,
+`pi-caffeinate.json` wins and the legacy file is ignored. The legacy filename is deprecated
 and will be removed in a future major release.
 
 ### Environment variables

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-caffeinate",
-	"version": "0.28.0",
+	"version": "0.35.0",
 	"description": "Pi extension that keeps the computer awake while the agent is running.",
 	"type": "module",
 	"license": "MIT",
@@ -29,8 +29,8 @@
 		"typecheck": "tsc --noEmit"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "2.5.3",
-		"@earendil-works/pi-coding-agent": "0.80.10",
+		"@biomejs/biome": "2.5.5",
+		"@earendil-works/pi-coding-agent": "0.82.1",
 		"@types/node": "26.1.1",
 		"typescript": "7.0.2"
 	},

package/src/caffeinate.ts

@@ -1,25 +1,19 @@
 import type { ChildProcess } from "node:child_process";
 import process from "node:process";
+import type {
+	ExtensionAPI,
+	ExtensionCommandContext,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
 import { startInhibitorProcess, stopInhibitorProcess } from "./inhibitor-process.js";
-import {
-	formatMode,
-	getInhibitorCommand,
-	type InhibitorCommand,
-	splitCommand,
-	windowsInhibitorScript,
-} from "./inhibitors.js";
+import { formatMode, getInhibitorCommand, type InhibitorCommand } from "./inhibitors.js";
 import {
 	type CaffeinateMode,
+	type CaffeinateSettings,
 	loadSettings,
-	normalizeCaffeinateSettings,
 	saveSettings,
 	settingsFilePath,
 } from "./settings.js";
-import type {
-	ExtensionAPI,
-	ExtensionCommandContext,
-	ExtensionContext,
-} from "@earendil-works/pi-coding-agent";
 
 const STATUS_KEY = "caffeinate";
 const DISABLED_VALUES = new Set(["1", "true", "yes", "on"]);
@@ -61,6 +55,7 @@ interface CaffeinateState {
 	settingsError?: string;
 	settingsNotice?: string;
 	iconWarningShown: boolean;
+	sessionGeneration: number;
 }
 
 const state: CaffeinateState = {
@@ -71,19 +66,24 @@ const state: CaffeinateState = {
 	quiet: false,
 	settingsLoaded: false,
 	iconWarningShown: false,
+	sessionGeneration: 0,
 };
 
 export default function caffeinate(pi: ExtensionAPI) {
 	pi.on("session_start", async (_event, ctx) => {
+		const generation = ++state.sessionGeneration;
 		state.iconWarningShown = false;
 		state.settingsNotice = undefined;
 		warnDeprecatedIcon(ctx);
-		await loadSettingsIntoState(ctx);
+		await loadSettingsIntoState(ctx, generation);
+		if (generation !== state.sessionGeneration) return;
 		updateStatus(ctx);
 	});
 
 	pi.on("agent_start", async (_event, ctx) => {
-		await ensureSettingsLoaded(ctx);
+		const generation = state.sessionGeneration;
+		await ensureSettingsLoaded(ctx, generation);
+		if (generation !== state.sessionGeneration) return;
 		state.activeTurns += 1;
 		startInhibitor(ctx, { notify: !state.quiet });
 	});
@@ -96,28 +96,36 @@ export default function caffeinate(pi: ExtensionAPI) {
 		updateStatus(ctx);
 	});
 
-	pi.on("session_shutdown", (_event, ctx) => {
+	pi.on("session_shutdown", async (_event, ctx) => {
+		state.sessionGeneration += 1;
 		state.activeTurns = 0;
 		stopInhibitor(ctx, "session shutdown", { notify: false });
 		ctx.ui.setStatus(STATUS_KEY, undefined);
+		await modeOperationQueue;
 	});
 
 	pi.registerCommand("caffeinate", {
 		description: "Open pi-caffeinate keep-awake controls",
 		getArgumentCompletions: (prefix) => commandCompletions(prefix),
 		handler: async (args, ctx) => {
-			await ensureSettingsLoaded(ctx);
-			await handleCaffeinateCommand(args, ctx);
+			const generation = state.sessionGeneration;
+			const command = parseCommand(args);
+			if (command === "sleep" || command === "display") {
+				await setModeAfterSettingsLoad(ctx, command, generation);
+				return;
+			}
+			await ensureSettingsLoaded(ctx, generation);
+			if (generation !== state.sessionGeneration) return;
+			await handleCaffeinateCommand(args, ctx, generation);
 		},
 	});
-
 }
 
-async function handleCaffeinateCommand(args: string, ctx: CommandContext) {
+async function handleCaffeinateCommand(args: string, ctx: CommandContext, generation: number) {
 	const command = parseCommand(args);
 	switch (command) {
 		case "menu":
-			await showMenu(ctx);
+			await showMenu(ctx, generation);
 			return;
 		case "help":
 			ctx.ui.notify(buildCommandGuide(), "info");
@@ -126,13 +134,13 @@ async function handleCaffeinateCommand(args: string, ctx: CommandContext) {
 			showStatus(ctx);
 			return;
 		case "mode":
-			await showModeSelector(ctx);
+			await showModeSelector(ctx, generation);
 			return;
 		case "sleep":
-			await setMode(ctx, "sleep");
+			await setMode(ctx, "sleep", generation);
 			return;
 		case "display":
-			await setMode(ctx, "display");
+			await setMode(ctx, "display", generation);
 			return;
 		case "stop":
 			stopCaffeinate(ctx, "manual stop");
@@ -142,7 +150,7 @@ async function handleCaffeinateCommand(args: string, ctx: CommandContext) {
 	ctx.ui.notify(`Unknown /caffeinate command: ${args.trim()}\n\n${buildCommandGuide()}`, "warning");
 }
 
-async function showMenu(ctx: CommandContext) {
+async function showMenu(ctx: CommandContext, generation: number) {
 	if (!ctx.hasUI) {
 		ctx.ui.notify(`${buildCommandGuide()}\n\n${describeState()}`, statusLevel());
 		updateStatus(ctx);
@@ -150,15 +158,16 @@ async function showMenu(ctx: CommandContext) {
 	}
 
 	const choice = await ctx.ui.select("pi-caffeinate controls", Object.values(MENU_OPTIONS));
+	if (generation !== state.sessionGeneration) return;
 	switch (choice) {
 		case MENU_OPTIONS.status:
 			showStatus(ctx);
 			return;
 		case MENU_OPTIONS.sleep:
-			await setMode(ctx, "sleep");
+			await setMode(ctx, "sleep", generation);
 			return;
 		case MENU_OPTIONS.display:
-			await setMode(ctx, "display");
+			await setMode(ctx, "display", generation);
 			return;
 		case MENU_OPTIONS.stop:
 			stopCaffeinate(ctx, "manual stop");
@@ -169,7 +178,7 @@ async function showMenu(ctx: CommandContext) {
 	}
 }
 
-async function showModeSelector(ctx: CommandContext) {
+async function showModeSelector(ctx: CommandContext, generation: number) {
 	if (!ctx.hasUI) {
 		ctx.ui.notify(
 			`Mode selection needs an interactive UI. Run /caffeinate sleep or /caffeinate display.\n\n${describeState()}`,
@@ -183,40 +192,95 @@ async function showModeSelector(ctx: CommandContext) {
 		`pi-caffeinate mode (current: ${formatMode(state.mode)})`,
 		Object.values(MODE_OPTIONS),
 	);
+	if (generation !== state.sessionGeneration) return;
 	if (choice === MODE_OPTIONS.sleep) {
-		await setMode(ctx, "sleep");
+		await setMode(ctx, "sleep", generation);
 		return;
 	}
 	if (choice === MODE_OPTIONS.display) {
-		await setMode(ctx, "display");
+		await setMode(ctx, "display", generation);
 	}
 }
 
-async function setMode(ctx: ExtensionContext, mode: CaffeinateMode) {
+let modeOperationQueue = Promise.resolve();
+
+function setModeAfterSettingsLoad(
+	ctx: ExtensionContext,
+	mode: CaffeinateMode,
+	generation: number,
+): Promise<void> {
+	return enqueueModeOperation(async () => {
+		await ensureSettingsLoaded(ctx, generation);
+		if (generation !== state.sessionGeneration) return;
+		await setModeNow(ctx, mode, generation);
+	});
+}
+
+function setMode(ctx: ExtensionContext, mode: CaffeinateMode, generation: number): Promise<void> {
+	return enqueueModeOperation(() => setModeNow(ctx, mode, generation));
+}
+
+function enqueueModeOperation(operation: () => Promise<void>): Promise<void> {
+	const queued = modeOperationQueue.then(operation);
+	modeOperationQueue = queued.catch(() => undefined);
+	return queued;
+}
+
+async function setModeNow(ctx: ExtensionContext, mode: CaffeinateMode, generation: number) {
+	if (generation !== state.sessionGeneration) return;
 	const previousMode = state.mode;
-	state.mode = mode;
+	const previousQuiet = state.quiet;
+	const restartRequired = Boolean(state.process && previousMode !== mode && !state.command?.custom);
 	state.settingsError = undefined;
 
-	let saved = true;
-	try {
-		await saveSettings({ mode, quiet: state.quiet, updatedAt: Date.now() });
-	} catch (error) {
-		saved = false;
-		state.settingsError = `settings save failed: ${formatError(error)}`;
-		ctx.ui.notify(`pi-caffeinate settings save failed: ${formatError(error)}`, "warning");
+	if (restartRequired) {
+		state.mode = mode;
+		stopInhibitor(ctx, "mode changed", { notify: false });
+		startInhibitor(ctx, { notify: false });
+		if (!state.process) {
+			const applicationError = state.lastError ?? "the inhibitor could not be restarted";
+			state.mode = previousMode;
+			startInhibitor(ctx, { notify: false });
+			const rollbackError = state.process
+				? undefined
+				: (state.lastError ?? "the previous inhibitor could not be restored");
+			state.settingsError = rollbackError
+				? `mode application failed (${applicationError}); runtime rollback failed: ${rollbackError}`
+				: `mode application failed and was rolled back: ${applicationError}`;
+			ctx.ui.notify(`pi-caffeinate ${state.settingsError}`, "warning");
+			updateStatus(ctx);
+			return;
+		}
 	}
 
-	if (state.process && previousMode !== mode && !state.command?.custom) {
-		stopInhibitor(ctx, "mode changed", { notify: false });
-		startInhibitor(ctx, { notify: !state.quiet });
+	let savedSettings: CaffeinateSettings;
+	try {
+		savedSettings = await saveSettings({ mode, updatedAt: Date.now() });
+	} catch (error) {
+		if (generation !== state.sessionGeneration) return;
+		let rollbackError: string | undefined;
+		if (restartRequired) {
+			state.mode = previousMode;
+			state.quiet = previousQuiet;
+			stopInhibitor(ctx, "settings save failed", { notify: false });
+			startInhibitor(ctx, { notify: false });
+			if (!state.process) rollbackError = state.lastError ?? "the prior inhibitor was not restored";
+		}
+		state.settingsError = rollbackError
+			? `settings save failed (${formatError(error)}); runtime rollback failed: ${rollbackError}`
+			: `settings save failed: ${formatError(error)}`;
+		ctx.ui.notify(
+			`pi-caffeinate mode remains ${formatMode(previousMode)}; settings were not saved: ${state.settingsError}`,
+			"warning",
+		);
+		updateStatus(ctx);
+		return;
 	}
 
-	ctx.ui.notify(
-		saved
-			? `pi-caffeinate mode set to ${formatMode(mode)} and saved.`
-			: `pi-caffeinate mode set to ${formatMode(mode)} for this session, but settings were not saved.`,
-		saved ? "info" : "warning",
-	);
+	if (generation !== state.sessionGeneration) return;
+	state.mode = mode;
+	state.quiet = savedSettings.quiet;
+	ctx.ui.notify(`pi-caffeinate mode set to ${formatMode(mode)} and saved.`, "info");
 	updateStatus(ctx);
 }
 
@@ -380,7 +444,9 @@ function describeState() {
 		return lines.join("\n");
 	}
 
-	lines.unshift("pi-caffeinate is idle and will keep the computer awake during the next agent run.");
+	lines.unshift(
+		"pi-caffeinate is idle and will keep the computer awake during the next agent run.",
+	);
 	return lines.join("\n");
 }
 
@@ -393,12 +459,12 @@ function statusModeLabel() {
 	return formatMode(state.mode);
 }
 
-async function ensureSettingsLoaded(ctx: ExtensionContext) {
+async function ensureSettingsLoaded(ctx: ExtensionContext, generation: number) {
 	if (state.disabled || state.settingsLoaded) return;
-	await loadSettingsIntoState(ctx);
+	await loadSettingsIntoState(ctx, generation);
 }
 
-async function loadSettingsIntoState(ctx: ExtensionContext) {
+async function loadSettingsIntoState(ctx: ExtensionContext, generation: number) {
 	if (state.disabled) {
 		state.settingsLoaded = true;
 		state.settingsError = undefined;
@@ -407,6 +473,7 @@ async function loadSettingsIntoState(ctx: ExtensionContext) {
 	}
 
 	const settings = await loadSettings();
+	if (generation !== state.sessionGeneration) return;
 	state.settingsLoaded = true;
 	state.settingsError = undefined;
 	if (settings.notice) {

package/src/inhibitors.ts

@@ -18,7 +18,11 @@ export function getInhibitorCommand(mode: CaffeinateMode): InhibitorCommand | un
 		if (command) return { command, args, description: `custom command (${command})`, custom: true };
 	}
 	if (process.platform === "darwin") {
-		return parentBoundUnixCommand("caffeinate", macCaffeinateArgs(mode), caffeinateDescription(mode));
+		return parentBoundUnixCommand(
+			"caffeinate",
+			macCaffeinateArgs(mode),
+			caffeinateDescription(mode),
+		);
 	}
 	if (process.platform === "linux") {
 		if (isWsl() && commandExists("powershell.exe")) {
@@ -40,7 +44,11 @@ export function getInhibitorCommand(mode: CaffeinateMode): InhibitorCommand | un
 			);
 		}
 		if (commandExists("caffeinate")) {
-			return parentBoundUnixCommand("caffeinate", macCaffeinateArgs(mode), caffeinateDescription(mode));
+			return parentBoundUnixCommand(
+				"caffeinate",
+				macCaffeinateArgs(mode),
+				caffeinateDescription(mode),
+			);
 		}
 	}
 	if (process.platform === "win32") return windowsPowerInhibitorCommand("powershell.exe", mode);
@@ -55,10 +63,21 @@ function caffeinateDescription(mode: CaffeinateMode) {
 	return `caffeinate (${formatMode(mode)})`;
 }
 
-function parentBoundUnixCommand(command: string, args: string[], description: string): InhibitorCommand {
+function parentBoundUnixCommand(
+	command: string,
+	args: string[],
+	description: string,
+): InhibitorCommand {
 	return {
 		command: "sh",
-		args: ["-c", unixParentBoundScript(), "pi-caffeinate-watch", String(process.pid), command, ...args],
+		args: [
+			"-c",
+			unixParentBoundScript(),
+			"pi-caffeinate-watch",
+			String(process.pid),
+			command,
+			...args,
+		],
 		description,
 	};
 }

package/src/settings.ts

@@ -1,8 +1,9 @@
+import { randomUUID } from "node:crypto";
 import { constants } from "node:fs";
-import { access, link, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
+import { access, lstat, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import process from "node:process";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
 const NEW_SETTINGS_FILE = "pi-caffeinate.json";
 const LEGACY_SETTINGS_FILE = "pi-caffeinate-settings.json";
@@ -15,17 +16,23 @@ export interface CaffeinateSettings {
 	updatedAt: number;
 }
 
+export interface SettingsFileOperations {
+	write(path: string, data: string): Promise<void>;
+	rename(source: string, destination: string): Promise<void>;
+}
+
+const DEFAULT_FILE_OPERATIONS: SettingsFileOperations = {
+	write: (path, data) => writeFile(path, data, "utf8").then(() => undefined),
+	rename,
+};
+
 export type SettingsLoadResult =
 	| { kind: "missing"; notice?: string }
 	| { kind: "invalid"; reason: string; notice?: string }
 	| { kind: "loaded"; settings: CaffeinateSettings; notice?: string };
 
-type SettingsMigrationResult = {
-	kind: "migrated" | "failed";
-	notice: string;
-};
-
 export async function loadSettings(): Promise<SettingsLoadResult> {
+	await settingsSaveQueue;
 	const newPath = settingsFilePath();
 	const newSettings = await readSettingsFile(newPath);
 	if (newSettings.kind !== "missing") return withLegacyIgnoredNotice(newSettings);
@@ -39,36 +46,49 @@ export async function loadSettings(): Promise<SettingsLoadResult> {
 	if (legacySettings.kind === "missing") return { kind: "missing" };
 	if (legacySettings.kind === "invalid") return legacySettings;
 
-	const migration = await migrateLegacySettings(legacyPath);
-	if (migration.kind === "failed") {
-		const settingsCreatedDuringMigration = await readSettingsFile(newPath);
-		if (settingsCreatedDuringMigration.kind !== "missing") {
-			return withLegacyIgnoredNotice(settingsCreatedDuringMigration);
-		}
-	}
-	return { ...legacySettings, notice: migration.notice };
+	return {
+		...legacySettings,
+		notice: `Using legacy ${LEGACY_SETTINGS_FILE}; rename it to ${NEW_SETTINGS_FILE}. Future saves write ${NEW_SETTINGS_FILE} without modifying the legacy file.`,
+	};
 }
 
-async function readSettingsFile(filePath: string): Promise<SettingsLoadResult> {
+interface SettingsDocumentResult {
+	result: SettingsLoadResult;
+	document?: Record<string, unknown>;
+}
+
+async function readSettingsDocument(filePath: string): Promise<SettingsDocumentResult> {
 	let text: string;
 	try {
 		text = await readFile(filePath, "utf8");
 	} catch (error) {
-		if (isNodeError(error) && error.code === "ENOENT") return { kind: "missing" };
-		return { kind: "invalid", reason: `${filePath}: ${formatError(error)}` };
+		if (isNodeError(error) && error.code === "ENOENT") return { result: { kind: "missing" } };
+		return { result: { kind: "invalid", reason: `${filePath}: ${formatError(error)}` } };
 	}
 	try {
-		const settings = normalizeCaffeinateSettings(JSON.parse(text) as unknown);
-		if (settings) return { kind: "loaded", settings };
+		const document = JSON.parse(text) as unknown;
+		const settings = normalizeCaffeinateSettings(document);
+		if (settings) {
+			return {
+				result: { kind: "loaded", settings },
+				document: { ...(document as Record<string, unknown>) },
+			};
+		}
 		return {
-			kind: "invalid",
-			reason: `${filePath}: expected { "mode": "sleep" | "display", optional "quiet": boolean }`,
+			result: {
+				kind: "invalid",
+				reason: `${filePath}: expected { "mode": "sleep" | "display", optional "quiet": boolean }`,
+			},
 		};
 	} catch (error) {
-		return { kind: "invalid", reason: `${filePath}: ${formatError(error)}` };
+		return { result: { kind: "invalid", reason: `${filePath}: ${formatError(error)}` } };
 	}
 }
 
+async function readSettingsFile(filePath: string): Promise<SettingsLoadResult> {
+	return (await readSettingsDocument(filePath)).result;
+}
+
 async function withLegacyIgnoredNotice(settings: SettingsLoadResult): Promise<SettingsLoadResult> {
 	if (!(await fileExists(legacySettingsFilePath()))) return settings;
 	return {
@@ -77,30 +97,6 @@ async function withLegacyIgnoredNotice(settings: SettingsLoadResult): Promise<Se
 	};
 }
 
-async function migrateLegacySettings(legacyPath: string): Promise<SettingsMigrationResult> {
-	const newPath = settingsFilePath();
-	try {
-		await link(legacyPath, newPath);
-	} catch (error) {
-		return {
-			kind: "failed",
-			notice: `pi-caffeinate legacy settings migration failed: could not migrate ${legacyPath} to ${newPath}: ${formatError(error)}. The legacy file was used for this session; future saves will write ${NEW_SETTINGS_FILE}.`,
-		};
-	}
-	try {
-		await rm(legacyPath, { force: true });
-	} catch (error) {
-		return {
-			kind: "migrated",
-			notice: `pi-caffeinate settings migrated from ${legacyPath} to ${newPath}, but the legacy file could not be removed: ${formatError(error)}. Delete ${LEGACY_SETTINGS_FILE} after confirming your settings.`,
-		};
-	}
-	return {
-		kind: "migrated",
-		notice: `pi-caffeinate settings migrated from ${legacyPath} to ${newPath}. ${LEGACY_SETTINGS_FILE} is deprecated and will be removed in a future major release.`,
-	};
-}
-
 async function fileExists(filePath: string) {
 	try {
 		await access(filePath, constants.F_OK);
@@ -110,26 +106,75 @@ async function fileExists(filePath: string) {
 	}
 }
 
+async function pathEntryExists(filePath: string) {
+	try {
+		await lstat(filePath);
+		return true;
+	} catch (error) {
+		if (isNodeError(error) && error.code === "ENOENT") return false;
+		throw error;
+	}
+}
+
 export function normalizeCaffeinateSettings(value: unknown): CaffeinateSettings | undefined {
 	if (!value || typeof value !== "object") return undefined;
 	const settings = value as { mode?: unknown; quiet?: unknown; updatedAt?: unknown };
 	if (!isCaffeinateMode(settings.mode)) return undefined;
 	if (settings.quiet !== undefined && typeof settings.quiet !== "boolean") return undefined;
 	if (settings.updatedAt !== undefined && typeof settings.updatedAt !== "number") return undefined;
-	return { mode: settings.mode, quiet: settings.quiet ?? false, updatedAt: settings.updatedAt ?? 0 };
+	return {
+		mode: settings.mode,
+		quiet: settings.quiet ?? false,
+		updatedAt: settings.updatedAt ?? 0,
+	};
 }
 
 function isCaffeinateMode(value: unknown): value is CaffeinateMode {
 	return value === "sleep" || value === "display";
 }
 
-export async function saveSettings(settings: CaffeinateSettings) {
+let settingsSaveQueue: Promise<unknown> = Promise.resolve();
+
+export function saveSettings(
+	settings: Omit<CaffeinateSettings, "quiet"> & { quiet?: boolean },
+	operations: Partial<SettingsFileOperations> = {},
+): Promise<CaffeinateSettings> {
+	const operation = settingsSaveQueue.then(() => saveSettingsNow(settings, operations));
+	settingsSaveQueue = operation.catch(() => undefined);
+	return operation;
+}
+
+async function saveSettingsNow(
+	settings: Omit<CaffeinateSettings, "quiet"> & { quiet?: boolean },
+	operations: Partial<SettingsFileOperations>,
+): Promise<CaffeinateSettings> {
 	const filePath = settingsFilePath();
+	let current = await readSettingsDocument(filePath);
+	const replaceCanonical = current.result.kind !== "missing";
+	if (!replaceCanonical) current = await readSettingsDocument(legacySettingsFilePath());
+	if (current.result.kind === "invalid") {
+		throw new Error(`Cannot save pi-caffeinate settings until you repair ${current.result.reason}`);
+	}
+	const document = current.document ?? {};
+	const quiet =
+		settings.quiet ?? (current.result.kind === "loaded" ? current.result.settings.quiet : false);
+	const nextSettings = { mode: settings.mode, quiet, updatedAt: settings.updatedAt };
+	const nextDocument = {
+		...document,
+		...nextSettings,
+	};
 	await mkdir(dirname(filePath), { recursive: true });
-	const tempFile = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+	const tempFile = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
 	try {
-		await writeFile(tempFile, `${JSON.stringify(settings, null, 2)}\n`, "utf8");
-		await rename(tempFile, filePath);
+		await (operations.write ?? DEFAULT_FILE_OPERATIONS.write)(
+			tempFile,
+			`${JSON.stringify(nextDocument, null, 2)}\n`,
+		);
+		if (!replaceCanonical && (await pathEntryExists(filePath))) {
+			throw new Error(`${NEW_SETTINGS_FILE} was created concurrently; reopen settings and retry.`);
+		}
+		await (operations.rename ?? DEFAULT_FILE_OPERATIONS.rename)(tempFile, filePath);
+		return nextSettings;
 	} catch (error) {
 		await rm(tempFile, { force: true }).catch(() => undefined);
 		throw error;
@@ -145,7 +190,7 @@ function legacySettingsFilePath() {
 }
 
 function agentDir() {
-	return process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
+	return getAgentDir();
 }
 
 function isNodeError(error: unknown): error is NodeJS.ErrnoException {