@narumitw/pi-caffeinate 0.31.0 → 0.38.0

package/README.md

@@ -59,7 +59,8 @@ If no supported inhibitor is available, the extension stays loaded and reports t
 /caffeinate
 ```
 
-Opens keep-awake controls. In non-interactive sessions, it prints command usage and status.
+Opens standard keep-awake controls in TUI or RPC mode. Print and JSON modes reject the interactive
+menu observably; use the direct `status`, `sleep`, `display`, `stop`, or `help` routes instead.
 
 ```text
 /caffeinate display
@@ -83,7 +84,7 @@ Shows whether an inhibitor is active, unavailable, disabled, or idle. The status
 /caffeinate mode
 ```
 
-Opens an interactive selector for the keep-awake mode.
+Opens the standard keep-awake mode selector in TUI or RPC mode. Escape closes the selector.
 
 ```text
 /caffeinate stop
@@ -119,11 +120,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.31.0",
+	"version": "0.38.0",
 	"description": "Pi extension that keeps the computer awake while the agent is running.",
 	"type": "module",
 	"license": "MIT",
@@ -38,5 +38,8 @@
 		"type": "git",
 		"url": "https://github.com/narumiruna/pi-extensions",
 		"directory": "extensions/pi-caffeinate"
+	},
+	"dependencies": {
+		"@narumitw/pi-tui-kit": "<1"
 	}
 }

package/src/caffeinate.ts

@@ -5,9 +5,16 @@ import type {
 	ExtensionCommandContext,
 	ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
+import { defineMenu, runMenu } from "@narumitw/pi-tui-kit";
 import { startInhibitorProcess, stopInhibitorProcess } from "./inhibitor-process.js";
 import { formatMode, getInhibitorCommand, type InhibitorCommand } from "./inhibitors.js";
-import { type CaffeinateMode, loadSettings, saveSettings, settingsFilePath } from "./settings.js";
+import {
+	type CaffeinateMode,
+	type CaffeinateSettings,
+	loadSettings,
+	saveSettings,
+	settingsFilePath,
+} from "./settings.js";
 
 const STATUS_KEY = "caffeinate";
 const DISABLED_VALUES = new Set(["1", "true", "yes", "on"]);
@@ -49,6 +56,8 @@ interface CaffeinateState {
 	settingsError?: string;
 	settingsNotice?: string;
 	iconWarningShown: boolean;
+	sessionGeneration: number;
+	menuController: AbortController;
 }
 
 const state: CaffeinateState = {
@@ -59,19 +68,26 @@ const state: CaffeinateState = {
 	quiet: false,
 	settingsLoaded: false,
 	iconWarningShown: false,
+	sessionGeneration: 0,
+	menuController: new AbortController(),
 };
 
 export default function caffeinate(pi: ExtensionAPI) {
 	pi.on("session_start", async (_event, ctx) => {
+		const generation = ++state.sessionGeneration;
+		replaceMenuController("Caffeinate session replaced");
 		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 });
 	});
@@ -84,27 +100,37 @@ 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.menuController.abort(new DOMException("Caffeinate session shut down", "AbortError"));
 		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");
@@ -113,13 +139,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");
@@ -129,81 +155,163 @@ async function handleCaffeinateCommand(args: string, ctx: CommandContext) {
 	ctx.ui.notify(`Unknown /caffeinate command: ${args.trim()}\n\n${buildCommandGuide()}`, "warning");
 }
 
-async function showMenu(ctx: CommandContext) {
-	if (!ctx.hasUI) {
-		ctx.ui.notify(`${buildCommandGuide()}\n\n${describeState()}`, statusLevel());
-		updateStatus(ctx);
-		return;
-	}
+async function showMenu(ctx: CommandContext, generation: number) {
+	await runCaffeinateMenu(ctx, generation, "main");
+}
 
-	const choice = await ctx.ui.select("pi-caffeinate controls", Object.values(MENU_OPTIONS));
-	switch (choice) {
-		case MENU_OPTIONS.status:
-			showStatus(ctx);
-			return;
-		case MENU_OPTIONS.sleep:
-			await setMode(ctx, "sleep");
-			return;
-		case MENU_OPTIONS.display:
-			await setMode(ctx, "display");
-			return;
-		case MENU_OPTIONS.stop:
-			stopCaffeinate(ctx, "manual stop");
-			return;
-		case MENU_OPTIONS.help:
-			ctx.ui.notify(buildCommandGuide(), "info");
-			return;
-	}
+async function showModeSelector(ctx: CommandContext, generation: number) {
+	await runCaffeinateMenu(ctx, generation, "mode");
 }
 
-async function showModeSelector(ctx: CommandContext) {
+async function runCaffeinateMenu(ctx: CommandContext, generation: number, start: "main" | "mode") {
 	if (!ctx.hasUI) {
-		ctx.ui.notify(
-			`Mode selection needs an interactive UI. Run /caffeinate sleep or /caffeinate display.\n\n${describeState()}`,
-			statusLevel(),
+		throw new Error(
+			start === "mode"
+				? "Mode selection requires TUI or RPC mode. Use /caffeinate sleep or /caffeinate display."
+				: `The pi-caffeinate menu requires TUI or RPC mode.\n\n${buildCommandGuide()}\n\n${describeState()}`,
 		);
-		updateStatus(ctx);
-		return;
 	}
+	type Screen = "main" | "mode";
+	type Action = "display" | "sleep" | "status" | "stop" | "help";
+	const menu = defineMenu<undefined, Screen, Action>({
+		start,
+		screens: {
+			main: () => ({
+				kind: "actions",
+				title: "pi-caffeinate controls",
+				lines: describeState().split("\n"),
+				items: Object.entries(MENU_OPTIONS).map(([id, label]) => ({
+					id,
+					label,
+					action: id as Action,
+				})),
+				hint: "close",
+			}),
+			mode: () => ({
+				kind: "actions",
+				title: `pi-caffeinate mode (current: ${formatMode(state.mode)})`,
+				items: Object.entries(MODE_OPTIONS).map(([id, label]) => ({
+					id,
+					label,
+					action: id as Action,
+				})),
+				hint: "close",
+			}),
+		},
+		actions: {
+			display: async () => {
+				await setMode(ctx, "display", generation);
+				return { kind: "close" };
+			},
+			sleep: async () => {
+				await setMode(ctx, "sleep", generation);
+				return { kind: "close" };
+			},
+			status: async () => {
+				showStatus(ctx);
+				return { kind: "close" };
+			},
+			stop: async () => {
+				stopCaffeinate(ctx, "manual stop");
+				return { kind: "close" };
+			},
+			help: async () => {
+				ctx.ui.notify(buildCommandGuide(), "info");
+				return { kind: "close" };
+			},
+		},
+	});
+	await runMenu(ctx, menu, {
+		getState: () => undefined,
+		signal: state.menuController.signal,
+		isCurrent: () => generation === state.sessionGeneration,
+	});
+}
 
-	const choice = await ctx.ui.select(
-		`pi-caffeinate mode (current: ${formatMode(state.mode)})`,
-		Object.values(MODE_OPTIONS),
-	);
-	if (choice === MODE_OPTIONS.sleep) {
-		await setMode(ctx, "sleep");
-		return;
-	}
-	if (choice === MODE_OPTIONS.display) {
-		await setMode(ctx, "display");
-	}
+function replaceMenuController(reason: string) {
+	state.menuController.abort(new DOMException(reason, "AbortError"));
+	state.menuController = new AbortController();
+}
+
+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));
 }
 
-async function setMode(ctx: ExtensionContext, mode: CaffeinateMode) {
+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);
 }
 
@@ -382,12 +490,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;
@@ -396,6 +504,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/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,6 +106,16 @@ 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 };
@@ -127,13 +133,48 @@ 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;
@@ -149,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 {