@narumitw/pi-chrome-devtools 0.28.0 → 0.35.0

package/README.md

@@ -169,11 +169,14 @@ ${PI_CODING_AGENT_DIR:-~/.pi/agent}/pi-chrome-devtools.json
 
 When the file is missing or invalid, the extension preserves Pi's current active-tool policy
 instead of enabling tools by itself. A valid saved selection is restored on Pi startup and
-`/reload`.
-
-Compatibility: older versions used `pi-chrome-devtools-settings.json`. During the migration
-window, a legacy-only file is automatically migrated to `pi-chrome-devtools.json` with a warning.
-If both files exist, `pi-chrome-devtools.json` wins and the legacy file is ignored. The legacy
+`/reload`. A missing file is created by the first successful selection change. Within one Pi process, selection saves run in invocation order, reread the latest valid document, and preserve unknown fields. Malformed JSON
+or invalid recognized fields block the save without replacement; a failed save restores the prior
+Chrome DevTools tool selection while preserving other extensions' current tools.
+
+Compatibility: older versions used `pi-chrome-devtools-settings.json`. A legacy-only file remains
+readable with a warning and is never modified automatically; rename it to
+`pi-chrome-devtools.json`. The first subsequent settings save writes the canonical file. If both
+files exist, `pi-chrome-devtools.json` wins and the legacy file is ignored. The legacy
 filename is deprecated and will be removed in a future major release.
 
 ## 🧠 Use cases

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-chrome-devtools",
-	"version": "0.28.0",
+	"version": "0.35.0",
 	"description": "Pi extension that exposes Chrome DevTools Protocol tools.",
 	"type": "module",
 	"license": "MIT",
@@ -29,11 +29,11 @@
 		"typecheck": "tsc --noEmit"
 	},
 	"dependencies": {
-		"typebox": "^1.3.3"
+		"typebox": "^1.3.8"
 	},
 	"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",
 		"typescript": "7.0.2"
 	},
 	"repository": {

package/src/browser-manager.ts

@@ -1,21 +1,20 @@
-import { spawn, type ChildProcess } from "node:child_process";
+import { type ChildProcess, spawn } from "node:child_process";
 import { constants } from "node:fs";
 import { access, mkdtemp, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { basename, delimiter, isAbsolute, join, resolve } from "node:path";
+import { delimiter, isAbsolute, join, resolve } from "node:path";
 import {
 	BROWSER_SHUTDOWN_WAIT_MS,
+	type BrowserCandidate,
+	type BrowserCandidateDefinition,
 	DEFAULT_ENDPOINT_RETRY_MS,
 	DEFAULT_ENDPOINT_WAIT_MS,
-	DEFAULT_HOST,
 	DEFAULT_HTTP_TIMEOUT_MS,
 	DEVTOOLS_ACTIVE_PORT_FILE,
-	MANAGED_BROWSER_PROFILE_PREFIX,
-	state,
-	type BrowserCandidate,
-	type BrowserCandidateDefinition,
 	type DevToolsPage,
+	MANAGED_BROWSER_PROFILE_PREFIX,
 	type ManagedBrowser,
+	state,
 } from "./runtime.js";
 
 function formatError(error: unknown) {
@@ -128,7 +127,12 @@ async function launchBrowserCandidate(candidate: BrowserCandidate, waitMs: numbe
 		];
 		throwIfBrowserLaunchCancelled();
 		const child = spawn(candidate.resolvedExecutable, args, { shell: false, stdio: "ignore" });
-		const launchedBrowser: ManagedBrowser = { process: child, userDataDir, exited: false, ready: false };
+		const launchedBrowser: ManagedBrowser = {
+			process: child,
+			userDataDir,
+			exited: false,
+			ready: false,
+		};
 		managedBrowser = launchedBrowser;
 		state.managedBrowser = launchedBrowser;
 
@@ -259,7 +263,8 @@ export async function shutdownManagedBrowser(
 		});
 	}
 	await rm(managedBrowser.userDataDir, { recursive: true, force: true }).catch(() => undefined);
-	if (!state.portConfigured && managedBrowser.port === state.port) state.port = state.configuredPort;
+	if (!state.portConfigured && managedBrowser.port === state.port)
+		state.port = state.configuredPort;
 }
 
 function killManagedBrowserProcess(managedBrowser: ManagedBrowser, signal?: NodeJS.Signals) {
@@ -400,9 +405,13 @@ export function launchModeLabel() {
 	if (!isLocalDevToolsHost(state.host)) return "manual remote endpoint";
 	if (!state.autoLaunchEnabled) return "manual; auto-launch disabled";
 	if (state.managedBrowser && !state.managedBrowser.exited) {
-		return state.portConfigured ? "auto-launched on explicit port" : "auto-launched on dynamic port";
+		return state.portConfigured
+			? "auto-launched on explicit port"
+			: "auto-launched on dynamic port";
 	}
-	return state.portConfigured ? "attach first; auto-launch explicit port" : "attach first; auto-launch dynamic port";
+	return state.portConfigured
+		? "attach first; auto-launch explicit port"
+		: "attach first; auto-launch dynamic port";
 }
 
 export function launchAttemptLines() {
@@ -435,7 +444,9 @@ export function launchHint() {
 }
 
 export function browserCandidateHint() {
-	return `Browser candidates: ${browserCandidateDefinitions().map((candidate) => candidate.label).join(", ")}`;
+	return `Browser candidates: ${browserCandidateDefinitions()
+		.map((candidate) => candidate.label)
+		.join(", ")}`;
 }
 
 export function chromeLaunchCommand() {
@@ -475,7 +486,9 @@ function browserCandidateDefinitions(): BrowserCandidateDefinition[] {
 
 function explicitBrowserCandidateDefinition(): BrowserCandidateDefinition[] {
 	if (!state.browserExecutable) return [];
-	return [{ label: "PI_CHROME_DEVTOOLS_BROWSER", executable: state.browserExecutable, source: "env" }];
+	return [
+		{ label: "PI_CHROME_DEVTOOLS_BROWSER", executable: state.browserExecutable, source: "env" },
+	];
 }
 
 function platformBrowserCandidateDefinitions(): BrowserCandidateDefinition[] {

package/src/cdp-client.ts

@@ -1,6 +1,6 @@
 import {
-	ensureDevToolsEndpoint,
 	devToolsEndpoint,
+	ensureDevToolsEndpoint,
 	fetchDevToolsJson,
 	formatPageListItem,
 	launchHint,
@@ -9,8 +9,8 @@ import {
 import {
 	DEFAULT_ENDPOINT_WAIT_MS,
 	DEFAULT_TIMEOUT_MS,
-	state,
 	type DevToolsPage,
+	state,
 } from "./runtime.js";
 
 interface CdpResponse<T = unknown> {

package/src/chrome-devtools.ts

@@ -1,16 +1,16 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { shutdownManagedBrowser } from "./browser-manager.js";
-import { loadSettings } from "./settings.js";
 import { state } from "./runtime.js";
+import { loadSettings } from "./settings.js";
 import {
 	allChromeDevtoolsTools,
 	applyChromeDevtoolsTools,
 	buildCommandGuide,
 	buildQuickstartMessage,
 	buildToolStatusMessage,
-	setSelectedChromeDevtoolsTools,
 	showToolSelector,
 	updateChromeDevtoolsTools,
+	waitForChromeDevtoolsSettings,
 } from "./tool-selector.js";
 import {
 	evaluateTool,
@@ -52,15 +52,18 @@ export default function chromeDevtools(pi: ExtensionAPI) {
 		description: "Open Chrome DevTools help and tool controls",
 		getArgumentCompletions: (prefix) => commandCompletions(prefix),
 		handler: async (args, ctx) => {
-			await handleChromeDevtoolsCommand(pi, args, ctx);
+			const generation = state.sessionGeneration;
+			await handleChromeDevtoolsCommand(pi, args, ctx, generation);
 		},
 	});
 
 	pi.on("session_start", async (_event, ctx) => {
+		const generation = ++state.sessionGeneration;
 		state.shuttingDown = false;
 		state.settingsNotice = undefined;
 		ctx.ui.setStatus(STATUS_KEY, undefined);
 		const settings = await loadSettings();
+		if (generation !== state.sessionGeneration) return;
 		state.settingsNotice = settings.notice;
 		if (settings.notice) ctx.ui.notify(settings.notice, "warning");
 		if (settings.kind === "loaded") {
@@ -73,16 +76,24 @@ export default function chromeDevtools(pi: ExtensionAPI) {
 	});
 
 	pi.on("session_shutdown", async (_event, ctx) => {
+		state.sessionGeneration += 1;
 		ctx.ui.setStatus(STATUS_KEY, undefined);
-		await shutdownManagedBrowser(undefined, { cancelLaunch: true });
+		const browserShutdown = shutdownManagedBrowser(undefined, { cancelLaunch: true });
+		await waitForChromeDevtoolsSettings();
+		await browserShutdown;
 	});
 }
 
-async function handleChromeDevtoolsCommand(pi: ExtensionAPI, args: string, ctx: CommandContext) {
+async function handleChromeDevtoolsCommand(
+	pi: ExtensionAPI,
+	args: string,
+	ctx: CommandContext,
+	generation: number,
+) {
 	const command = parseCommand(args);
 	switch (command) {
 		case "menu":
-			await showMenu(pi, ctx);
+			await showMenu(pi, ctx, generation);
 			return;
 		case "help":
 			ctx.ui.notify(buildCommandGuide(), "info");
@@ -90,9 +101,12 @@ async function handleChromeDevtoolsCommand(pi: ExtensionAPI, args: string, ctx:
 		case "quickstart":
 			ctx.ui.notify(buildQuickstartMessage(), "info");
 			return;
-		case "status":
-			ctx.ui.notify(await buildToolStatusMessage(pi), "info");
+		case "status": {
+			const status = await buildToolStatusMessage(pi);
+			if (generation !== state.sessionGeneration) return;
+			ctx.ui.notify(status, "info");
 			return;
+		}
 		case "tools":
 			await showToolSelector(pi, ctx);
 			return;
@@ -104,20 +118,24 @@ async function handleChromeDevtoolsCommand(pi: ExtensionAPI, args: string, ctx:
 			return;
 	}
 
-	ctx.ui.notify(`Unknown /chrome-devtools command: ${args.trim()}
+	ctx.ui.notify(
+		`Unknown /chrome-devtools command: ${args.trim()}
 
-${buildCommandGuide()}`, "warning");
+${buildCommandGuide()}`,
+		"warning",
+	);
 }
 
-async function showMenu(pi: ExtensionAPI, ctx: CommandContext) {
+async function showMenu(pi: ExtensionAPI, ctx: CommandContext, generation: number) {
 	if (!ctx.hasUI) {
-		ctx.ui.notify(`${buildCommandGuide()}
-
-${await buildToolStatusMessage(pi)}`, "info");
+		const status = await buildToolStatusMessage(pi);
+		if (generation !== state.sessionGeneration) return;
+		ctx.ui.notify(`${buildCommandGuide()}\n\n${status}`, "info");
 		return;
 	}
 
 	const choice = await ctx.ui.select("Chrome DevTools", Object.values(MENU_OPTIONS));
+	if (generation !== state.sessionGeneration) return;
 	switch (choice) {
 		case MENU_OPTIONS.quickstart:
 			ctx.ui.notify(buildQuickstartMessage(), "info");
@@ -125,9 +143,12 @@ ${await buildToolStatusMessage(pi)}`, "info");
 		case MENU_OPTIONS.help:
 			ctx.ui.notify(buildCommandGuide(), "info");
 			return;
-		case MENU_OPTIONS.status:
-			ctx.ui.notify(await buildToolStatusMessage(pi), "info");
+		case MENU_OPTIONS.status: {
+			const status = await buildToolStatusMessage(pi);
+			if (generation !== state.sessionGeneration) return;
+			ctx.ui.notify(status, "info");
 			return;
+		}
 		case MENU_OPTIONS.tools:
 			await showToolSelector(pi, ctx);
 			return;
@@ -174,5 +195,5 @@ export {
 	resolveScreenshotPath,
 	selectAllowedRoot,
 } from "./screenshot.js";
-export { installSettingsFileExclusively, normalizeChromeDevtoolsSettings } from "./settings.js";
+export { normalizeChromeDevtoolsSettings } from "./settings.js";
 export { orderedChromeDevtoolsTools } from "./tool-selector.js";

package/src/render.ts

@@ -1,7 +1,4 @@
-import type {
-	AgentToolResult,
-	ToolRenderResultOptions,
-} from "@earendil-works/pi-coding-agent";
+import type { AgentToolResult, ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
 
 const STATUS_KEY = "chrome-devtools";
 interface StatusContext {
@@ -90,9 +87,7 @@ class PiTextComponent implements RenderComponent {
 			.split(/\r?\n/)
 			.map((line) => {
 				const truncatedLine = truncateLine(line, Math.max(1, width));
-				return this.theme && this.color
-					? this.theme.fg(this.color, truncatedLine)
-					: truncatedLine;
+				return this.theme && this.color ? this.theme.fg(this.color, truncatedLine) : truncatedLine;
 			});
 	}
 }
@@ -101,7 +96,11 @@ function truncateLine(line: string, maxWidth: number) {
 	return Array.from(line).slice(0, maxWidth).join("");
 }
 
-export async function withStatus<T>(ctx: StatusContext, status: string, callback: () => Promise<T>) {
+export async function withStatus<T>(
+	ctx: StatusContext,
+	status: string,
+	callback: () => Promise<T>,
+) {
 	ctx.ui.setStatus(STATUS_KEY, status);
 	try {
 		return await callback();

package/src/runtime.ts

@@ -31,6 +31,7 @@ export interface ChromeDevToolsState {
 	launchPromise?: Promise<void>;
 	lastLaunchAttempt?: BrowserLaunchAttempt;
 	shuttingDown: boolean;
+	sessionGeneration: number;
 	settingsNotice?: string;
 }
 
@@ -82,4 +83,5 @@ export const state: ChromeDevToolsState = {
 	autoLaunchEnabled: process.env.PI_CHROME_DEVTOOLS_AUTO_LAUNCH !== "0",
 	browserExecutable: process.env.PI_CHROME_DEVTOOLS_BROWSER,
 	shuttingDown: false,
+	sessionGeneration: 0,
 };

package/src/screenshot.ts

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { link, lstat, mkdir, mkdtemp, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { lstat, mkdir, realpath, rename, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
@@ -47,7 +47,10 @@ export async function saveScreenshot(
 	};
 }
 
-export function resolveScreenshotPath(savePath: string | undefined, cwd: string): ResolvedScreenshotPath {
+export function resolveScreenshotPath(
+	savePath: string | undefined,
+	cwd: string,
+): ResolvedScreenshotPath {
 	const cwdRoot = resolve(cwd);
 	const tempRoot = resolve(tmpdir());
 
@@ -228,7 +231,9 @@ export function isPathInsideRoot(path: string, root: string) {
 	const normalizedPath = normalizePathForComparison(resolve(path));
 	const normalizedRoot = normalizePathForComparison(resolve(root));
 	if (normalizedPath === normalizedRoot) return true;
-	const rootWithSeparator = normalizedRoot.endsWith(sep) ? normalizedRoot : `${normalizedRoot}${sep}`;
+	const rootWithSeparator = normalizedRoot.endsWith(sep)
+		? normalizedRoot
+		: `${normalizedRoot}${sep}`;
 	return normalizedPath.startsWith(rootWithSeparator);
 }
 

package/src/settings.ts

@@ -1,12 +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 {
-	CHROME_DEVTOOLS_TOOL_NAMES,
-	type ChromeDevToolsToolName,
-} from "./tool-names.js";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { CHROME_DEVTOOLS_TOOL_NAMES, type ChromeDevToolsToolName } from "./tool-names.js";
 
 const NEW_SETTINGS_FILE_NAME = "pi-chrome-devtools.json";
 const LEGACY_SETTINGS_FILE_NAME = "pi-chrome-devtools-settings.json";
@@ -15,17 +12,23 @@ export interface ChromeDevToolsSettings {
 	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: ChromeDevToolsSettings; 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") {
@@ -41,39 +44,50 @@ export async function loadSettings(): Promise<SettingsLoadResult> {
 	if (legacySettings.kind === "missing") return { kind: "missing" };
 	if (legacySettings.kind === "invalid") return legacySettings;
 
-	const migration = await migrateLegacySettings(legacyPath, legacySettings.settings);
-	if (migration.kind === "failed") {
-		const settingsCreatedDuringMigration = await readSettingsFile(newPath);
-		if (settingsCreatedDuringMigration.kind !== "missing") {
-			return withLegacyIgnoredNotice(settingsCreatedDuringMigration);
-		}
-	}
+	return {
+		...legacySettings,
+		notice: `Using legacy ${LEGACY_SETTINGS_FILE_NAME}; rename it to ${NEW_SETTINGS_FILE_NAME}. Future saves write ${NEW_SETTINGS_FILE_NAME} without modifying the legacy file.`,
+	};
+}
 
-	return { ...legacySettings, notice: migration.notice };
+interface SettingsDocumentResult {
+	result: SettingsLoadResult;
+	document?: Record<string, unknown>;
 }
 
-async function readSettingsFile(filePath: string): Promise<SettingsLoadResult> {
+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 parsed = JSON.parse(text) as unknown;
 		const settings = normalizeChromeDevtoolsSettings(parsed);
-		if (settings) return { kind: "loaded", settings };
+		if (settings) {
+			return {
+				result: { kind: "loaded", settings },
+				document: { ...(parsed as Record<string, unknown>) },
+			};
+		}
 		return {
-			kind: "invalid",
-			reason: `${filePath}: expected tools to be an array of Chrome DevTools tool names`,
+			result: {
+				kind: "invalid",
+				reason: `${filePath}: expected tools to be an array of Chrome DevTools tool names`,
+			},
 		};
 	} 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 {
@@ -82,49 +96,6 @@ async function withLegacyIgnoredNotice(settings: SettingsLoadResult): Promise<Se
 	};
 }
 
-export async function installSettingsFileExclusively(filePath: string, contents: string) {
-	await mkdir(dirname(filePath), { recursive: true });
-	const tempFile = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
-	try {
-		await writeFile(tempFile, contents, { encoding: "utf8", flag: "wx" });
-		await link(tempFile, filePath);
-	} finally {
-		await rm(tempFile, { force: true }).catch(() => undefined);
-	}
-}
-
-async function migrateLegacySettings(
-	legacyPath: string,
-	settings: ChromeDevToolsSettings,
-): Promise<SettingsMigrationResult> {
-	const newPath = settingsFilePath();
-	try {
-		await installSettingsFileExclusively(
-			newPath,
-			`${JSON.stringify(settings, null, 2)}\n`,
-		);
-	} catch (error) {
-		return {
-			kind: "failed",
-			notice: `Chrome DevTools 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_NAME}.`,
-		};
-	}
-
-	try {
-		await rm(legacyPath, { force: true });
-	} catch (error) {
-		return {
-			kind: "migrated",
-			notice: `Chrome DevTools settings migrated from ${legacyPath} to ${newPath}, but the legacy file could not be removed: ${formatError(error)}. Delete ${LEGACY_SETTINGS_FILE_NAME} after confirming your settings.`,
-		};
-	}
-
-	return {
-		kind: "migrated",
-		notice: `Chrome DevTools settings migrated from ${legacyPath} to ${newPath}. ${LEGACY_SETTINGS_FILE_NAME} is deprecated and will be removed in a future major release.`,
-	};
-}
-
 async function fileExists(filePath: string) {
 	try {
 		await access(filePath, constants.F_OK);
@@ -134,7 +105,19 @@ async function fileExists(filePath: string) {
 	}
 }
 
-export function normalizeChromeDevtoolsSettings(value: unknown): ChromeDevToolsSettings | undefined {
+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 normalizeChromeDevtoolsSettings(
+	value: unknown,
+): ChromeDevToolsSettings | undefined {
 	if (!value || typeof value !== "object") return undefined;
 	const settings = value as { tools?: unknown; updatedAt?: unknown };
 	if (typeof settings.updatedAt !== "number") return undefined;
@@ -158,13 +141,48 @@ function orderedUniqueChromeDevtoolsTools(tools: readonly ChromeDevToolsToolName
 	return CHROME_DEVTOOLS_TOOL_NAMES.filter((toolName) => selectedTools.has(toolName));
 }
 
-export async function saveSettings(settings: ChromeDevToolsSettings) {
+let settingsSaveQueue = Promise.resolve();
+
+export function saveSettings(
+	settings: ChromeDevToolsSettings,
+	operations: Partial<SettingsFileOperations> = {},
+): Promise<void> {
+	const operation = settingsSaveQueue.then(() => saveSettingsNow(settings, operations));
+	settingsSaveQueue = operation.catch(() => undefined);
+	return operation;
+}
+
+async function saveSettingsNow(
+	settings: ChromeDevToolsSettings,
+	operations: Partial<SettingsFileOperations>,
+): Promise<void> {
 	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 Chrome DevTools settings until you repair ${current.result.reason}`,
+		);
+	}
+	const nextDocument = {
+		...(current.document ?? {}),
+		tools: [...settings.tools],
+		updatedAt: settings.updatedAt,
+	};
 	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_NAME} was created concurrently; reopen settings and retry.`,
+			);
+		}
+		await (operations.rename ?? DEFAULT_FILE_OPERATIONS.rename)(tempFile, filePath);
 	} catch (error) {
 		await rm(tempFile, { force: true }).catch(() => undefined);
 		throw error;
@@ -180,7 +198,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 {
@@ -190,7 +208,3 @@ function isNodeError(error: unknown): error is NodeJS.ErrnoException {
 function formatError(error: unknown) {
 	return error instanceof Error ? error.message : String(error);
 }
-
-function unique<T>(values: T[]) {
-	return Array.from(new Set(values));
-}

package/src/tool-selector.ts

@@ -1,7 +1,6 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import {
 	browserCandidateHint,
-	chromeLaunchCommand,
 	devToolsEndpoint,
 	endpointConfigHint,
 	endpointSourceLabel,
@@ -9,12 +8,9 @@ import {
 	launchHint,
 	launchModeLabel,
 } from "./browser-manager.js";
-import { loadSettings, saveSettings, settingsFilePath } from "./settings.js";
 import { state } from "./runtime.js";
-import {
-	CHROME_DEVTOOLS_TOOL_NAMES,
-	type ChromeDevToolsToolName,
-} from "./tool-names.js";
+import { loadSettings, saveSettings, settingsFilePath } from "./settings.js";
+import { CHROME_DEVTOOLS_TOOL_NAMES, type ChromeDevToolsToolName } from "./tool-names.js";
 
 type CommandContext = ExtensionCommandContext;
 const TOOL_SELECTOR_DONE = "Done";
@@ -43,26 +39,32 @@ interface ToolStatusSummary {
 }
 
 export async function showToolSelector(pi: ExtensionAPI, ctx: CommandContext) {
-	if (!ctx.hasUI) {
-		ctx.ui.notify(
-			`Chrome DevTools tool selection needs an interactive UI.
-
-${await buildToolStatusMessage(pi)}`,
-			"info",
-		);
+	const generation = state.sessionGeneration;
+	if (!ctx.hasUI) return;
+	if (ctx.mode !== "tui") {
+		await showDialogToolSelector(pi, ctx, generation);
 		return;
 	}
 
 	let selectedTools = new Set<ChromeDevToolsToolName>(getActiveChromeDevtoolsTools(pi));
 	let persistQueue = Promise.resolve();
+	let requestedRevision = 0;
+	let requestRender: () => void = () => undefined;
 	const commitSelectedTools = () => {
 		const nextSelectedTools = orderedChromeDevtoolsTools(selectedTools);
-		applyChromeDevtoolsTools(pi, nextSelectedTools);
-		persistQueue = persistQueue.then(() => persistSettings(ctx, nextSelectedTools));
+		const revision = ++requestedRevision;
+		persistQueue = persistQueue.then(async () => {
+			const saved = await transactSelectedTools(pi, ctx, nextSelectedTools, generation);
+			if (!saved && generation === state.sessionGeneration && revision === requestedRevision) {
+				selectedTools = new Set(getActiveChromeDevtoolsTools(pi));
+				requestRender();
+			}
+		});
 	};
 
 	const customResult = await ctx.ui.custom<"closed" | undefined>(
 		(tui, theme, keybindings, done) => {
+			requestRender = () => tui.requestRender();
 			const rows = chromeDevtoolsToolSelectorRows();
 			let selectedIndex = 0;
 			const moveSelection = (delta: number) => {
@@ -144,22 +146,26 @@ ${await buildToolStatusMessage(pi)}`,
 		},
 	);
 
+	if (generation !== state.sessionGeneration) return;
 	if (customResult !== "closed") {
-		await showDialogToolSelector(pi, ctx);
+		await showDialogToolSelector(pi, ctx, generation);
 		return;
 	}
 
 	await persistQueue;
-	ctx.ui.notify(await buildToolStatusMessage(pi), "info");
+	if (generation !== state.sessionGeneration) return;
+	const status = await buildToolStatusMessage(pi);
+	if (generation !== state.sessionGeneration) return;
+	ctx.ui.notify(status, "info");
 }
 
-async function showDialogToolSelector(pi: ExtensionAPI, ctx: CommandContext) {
+async function showDialogToolSelector(pi: ExtensionAPI, ctx: CommandContext, generation: number) {
 	let selectedTools = new Set<ChromeDevToolsToolName>(getActiveChromeDevtoolsTools(pi));
 	while (true) {
 		const rows = chromeDevtoolsToolSelectorRows();
 		const choices = rows.map((row) => formatToolSelectorRow(row, selectedTools));
 		const choice = await ctx.ui.select(toolSelectorTitle(selectedTools), choices);
-		if (!choice) break;
+		if (generation !== state.sessionGeneration || !choice) break;
 
 		const row = rows[choices.indexOf(choice)];
 		if (!row) continue;
@@ -174,10 +180,20 @@ async function showDialogToolSelector(pi: ExtensionAPI, ctx: CommandContext) {
 			selectedTools = new Set();
 		}
 
-		await setSelectedChromeDevtoolsTools(pi, ctx, orderedChromeDevtoolsTools(selectedTools));
+		const saved = await transactSelectedTools(
+			pi,
+			ctx,
+			orderedChromeDevtoolsTools(selectedTools),
+			generation,
+		);
+		if (generation !== state.sessionGeneration) return;
+		if (!saved) selectedTools = new Set(getActiveChromeDevtoolsTools(pi));
 	}
 
-	ctx.ui.notify(await buildToolStatusMessage(pi), "info");
+	if (generation !== state.sessionGeneration) return;
+	const status = await buildToolStatusMessage(pi);
+	if (generation !== state.sessionGeneration) return;
+	ctx.ui.notify(status, "info");
 }
 
 export async function updateChromeDevtoolsTools(
@@ -186,19 +202,75 @@ export async function updateChromeDevtoolsTools(
 	selectedTools: readonly ChromeDevToolsToolName[],
 	action: string,
 ) {
-	await setSelectedChromeDevtoolsTools(pi, ctx, selectedTools);
-	ctx.ui.notify(`Chrome DevTools tools ${action}.
-
-${await buildToolStatusMessage(pi)}`, "info");
+	const generation = state.sessionGeneration;
+	const saved = await transactSelectedTools(pi, ctx, selectedTools, generation);
+	if (!saved || generation !== state.sessionGeneration) return;
+	const status = await buildToolStatusMessage(pi);
+	if (generation !== state.sessionGeneration) return;
+	ctx.ui.notify(`Chrome DevTools tools ${action}.\n\n${status}`, "info");
 }
 
 export async function setSelectedChromeDevtoolsTools(
 	pi: ExtensionAPI,
 	ctx: CommandContext,
 	selectedTools: readonly ChromeDevToolsToolName[],
-) {
-	applyChromeDevtoolsTools(pi, selectedTools);
-	await persistSettings(ctx, selectedTools);
+): Promise<boolean> {
+	return transactSelectedTools(pi, ctx, selectedTools, state.sessionGeneration);
+}
+
+let toolTransactionQueue = Promise.resolve();
+
+export async function waitForChromeDevtoolsSettings(): Promise<void> {
+	await toolTransactionQueue;
+}
+
+function transactSelectedTools(
+	pi: ExtensionAPI,
+	ctx: CommandContext,
+	selectedTools: readonly ChromeDevToolsToolName[],
+	expectedGeneration: number,
+): Promise<boolean> {
+	const operation = toolTransactionQueue.then(() =>
+		transactSelectedToolsNow(pi, ctx, selectedTools, expectedGeneration),
+	);
+	toolTransactionQueue = operation.then(
+		() => undefined,
+		() => undefined,
+	);
+	return operation;
+}
+
+async function transactSelectedToolsNow(
+	pi: ExtensionAPI,
+	ctx: CommandContext,
+	selectedTools: readonly ChromeDevToolsToolName[],
+	expectedGeneration: number,
+): Promise<boolean> {
+	if (expectedGeneration !== state.sessionGeneration) return false;
+	const previousActiveTools = pi.getActiveTools();
+	try {
+		applyChromeDevtoolsTools(pi, selectedTools);
+		await persistSettings(selectedTools);
+		return expectedGeneration === state.sessionGeneration;
+	} catch (error) {
+		let rollbackError: unknown;
+		try {
+			const previousChromeTools = previousActiveTools.filter((name) =>
+				CHROME_DEVTOOLS_TOOL_NAMES.includes(name as ChromeDevToolsToolName),
+			) as ChromeDevToolsToolName[];
+			applyChromeDevtoolsTools(pi, previousChromeTools);
+		} catch (caught) {
+			rollbackError = caught;
+		}
+		if (expectedGeneration !== state.sessionGeneration) return false;
+		ctx.ui.notify(
+			rollbackError
+				? `Chrome DevTools settings save failed: ${formatError(error)}; active-tool rollback failed: ${formatError(rollbackError)}`
+				: `Chrome DevTools settings save failed; active tools restored: ${formatError(error)}`,
+			"warning",
+		);
+		return false;
+	}
 }
 
 export function applyChromeDevtoolsTools(
@@ -328,13 +400,6 @@ function formatPersistedSelection(tools: readonly ChromeDevToolsToolName[]) {
 	return `${tools.length}/${CHROME_DEVTOOLS_TOOL_NAMES.length} selected: ${tools.join(", ")}`;
 }
 
-async function persistSettings(
-	ctx: CommandContext,
-	selectedTools: readonly ChromeDevToolsToolName[],
-) {
-	try {
-		await saveSettings({ tools: [...selectedTools], updatedAt: Date.now() });
-	} catch (error) {
-		ctx.ui.notify(`Chrome DevTools settings save failed: ${formatError(error)}`, "warning");
-	}
+async function persistSettings(selectedTools: readonly ChromeDevToolsToolName[]) {
+	await saveSettings({ tools: [...selectedTools], updatedAt: Date.now() });
 }