pi-browser-harness 0.8.3 → 0.10.0

package/src/profile/launch.ts

@@ -0,0 +1,90 @@
+/**
+ * Opening a browser window for a chosen profile.
+ *
+ * CDP cannot do this: `Target.createTarget` rejects another profile's
+ * browserContextId ("Failed to find browser context with id"), and a bare
+ * createTarget lands in `defaultBrowserContextId`, which follows window focus.
+ * The only way in is the browser's own command line — Chromium's
+ * ProcessSingleton hands a second launch's argv to the running browser, which
+ * "does what it would have done", i.e. opens a window in `--profile-directory`.
+ *
+ * The window is then identified by a unique `file://` sentinel page. That
+ * matters: a bare `about:blank#token` argument is discarded by Chrome (it opens
+ * chrome://newtab instead), so the token has to ride on a real URL. Polling for
+ * the sentinel URL — rather than diffing the target list — also keeps
+ * identification correct when the user opens tabs at the same moment.
+ */
+
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { type Result, err, ok } from "../util/result";
+
+export type ProfileWindowRequest = {
+  /** Browser binary to invoke. */
+  readonly exePath: string;
+  /** Profile subdirectory, e.g. "Profile 1". */
+  readonly profileDir: string;
+  /**
+   * Only set when the RUNNING browser was launched with an explicit
+   * --user-data-dir. ProcessSingleton keys on this path, so passing one that
+   * differs by case or normalisation would start a second browser instead of
+   * delegating to the running one.
+   */
+  readonly explicitUserDataDir?: string;
+};
+
+export type ProfileWindowHandle = {
+  /** file:// URL that will appear as the new window's page target. */
+  readonly sentinelUrl: string;
+  /** Remove the sentinel file. Safe to call more than once. */
+  readonly cleanup: () => Promise<void>;
+};
+
+const SENTINEL_HTML = (token: string): string =>
+  `<!doctype html><meta charset="utf-8"><title>${token}</title>` +
+  `<body style="font:14px system-ui;padding:2rem;color:#555">pi browser harness — opening this profile…</body>`;
+
+/**
+ * Ask the running browser to open a window in `profileDir`, marked with a
+ * unique sentinel page the caller can then find over CDP.
+ */
+export const openProfileWindow = async (
+  req: ProfileWindowRequest,
+): Promise<Result<ProfileWindowHandle, string>> => {
+  const token = `pi-harness-${randomUUID()}`;
+  const file = join(tmpdir(), `${token}.html`);
+  try {
+    await writeFile(file, SENTINEL_HTML(token), "utf8");
+  } catch (e) {
+    return err(`could not write the profile handshake page: ${e instanceof Error ? e.message : String(e)}`);
+  }
+
+  const sentinelUrl = pathToFileURL(file).href;
+  const args: string[] = [];
+  if (req.explicitUserDataDir) args.push(`--user-data-dir=${req.explicitUserDataDir}`);
+  args.push(`--profile-directory=${req.profileDir}`, "--new-window", sentinelUrl);
+
+  try {
+    // No shell: arguments are passed as an array, so profile names and paths
+    // containing spaces survive intact on every platform.
+    const child = spawn(req.exePath, args, { detached: true, stdio: "ignore" });
+    child.unref();
+    // The launcher process exits as soon as the running browser takes over the
+    // command line; an error here means the binary itself could not be started.
+    child.on("error", () => {});
+  } catch (e) {
+    await rm(file, { force: true }).catch(() => {});
+    return err(`could not launch ${req.exePath}: ${e instanceof Error ? e.message : String(e)}`);
+  }
+
+  return ok({
+    sentinelUrl,
+    cleanup: async () => {
+      await rm(file, { force: true }).catch(() => {});
+    },
+  });
+};

package/src/profile/list.ts

@@ -0,0 +1,171 @@
+/**
+ * Browser profile enumeration.
+ *
+ * A Chromium user-data-dir registers its profiles in `Local State` under the
+ * JSON key `profile.info_cache`, with `profile.profiles_order` giving the
+ * user's own ordering and `profile.last_used` naming the active one. Those
+ * keys are declared in Chromium's pref_names.h with no platform BUILDFLAG, so
+ * the layout is identical on Linux, macOS, and Windows (the C++ constant is
+ * now `kProfileAttributes`; the on-disk key never changed).
+ *
+ * Enumeration is two-tier so a Chromium fork or a future schema change cannot
+ * blank the list:
+ *   tier 1 — `Local State` → `profile.info_cache` (authoritative: display
+ *            names, accounts, ordering)
+ *   tier 2 — scan subdirectories holding a `Preferences` file and read
+ *            `profile.name` + `account_info[0].email`
+ *
+ * Nothing here throws: an unreadable or malformed file yields an empty list so
+ * callers degrade to the harness's pre-existing behavior.
+ */
+
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+export type BrowserProfile = {
+  /** Profile subdirectory name, e.g. "Default" or "Profile 1". */
+  readonly dir: string;
+  /** Display name as shown in the browser's profile menu. */
+  readonly name: string;
+  /** Signed-in account address, when the profile has one. */
+  readonly email?: string;
+  /** Picker label — "Name (email)", or "Name (dir)" with no account. */
+  readonly label: string;
+  /** True for the profile the browser reports as last used. */
+  readonly lastUsed: boolean;
+};
+
+/** Directories inside a user-data-dir that are not user profiles. */
+const NON_PROFILE_DIRS: ReadonlySet<string> = new Set([
+  "System Profile",
+  "Guest Profile",
+]);
+
+/**
+ * Picker label. The bracketed half is the account address when there is one,
+ * and the profile directory otherwise, so every row keeps the same shape.
+ */
+export const formatProfileLabel = (name: string, email: string | undefined, dir: string): string =>
+  `${name} (${email && email.length > 0 ? email : dir})`;
+
+const readJsonFile = async (path: string): Promise<Record<string, unknown> | null> => {
+  try {
+    const raw = await readFile(path, "utf8");
+    const parsed: unknown = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+    return parsed as Record<string, unknown>;
+  } catch {
+    // Missing file, permission error, or malformed JSON — the caller falls
+    // back to the next tier, and ultimately to an empty list.
+    return null;
+  }
+};
+
+const asRecord = (v: unknown): Record<string, unknown> | null =>
+  typeof v === "object" && v !== null && !Array.isArray(v) ? (v as Record<string, unknown>) : null;
+
+const asString = (v: unknown): string | undefined =>
+  typeof v === "string" && v.length > 0 ? v : undefined;
+
+/**
+ * Order profiles the way the browser does: `profiles_order` first (in its own
+ * sequence), then anything unlisted, alphabetically.
+ */
+const orderDirs = (dirs: ReadonlyArray<string>, order: ReadonlyArray<string>): ReadonlyArray<string> => {
+  const known = order.filter((d) => dirs.includes(d));
+  const rest = dirs.filter((d) => !known.includes(d)).sort((a, b) => a.localeCompare(b));
+  return [...known, ...rest];
+};
+
+const buildProfile = (
+  dir: string,
+  name: string | undefined,
+  email: string | undefined,
+  lastUsed: boolean,
+): BrowserProfile => {
+  const displayName = name ?? dir;
+  return {
+    dir,
+    name: displayName,
+    ...(email !== undefined ? { email } : {}),
+    label: formatProfileLabel(displayName, email, dir),
+    lastUsed,
+  };
+};
+
+/** Tier 1 — `Local State` → `profile.info_cache`. */
+const listFromLocalState = async (userDataDir: string): Promise<ReadonlyArray<BrowserProfile>> => {
+  const localState = await readJsonFile(join(userDataDir, "Local State"));
+  if (!localState) return [];
+  const profileNode = asRecord(localState["profile"]);
+  if (!profileNode) return [];
+  const infoCache = asRecord(profileNode["info_cache"]);
+  if (!infoCache) return [];
+
+  const rawOrder = profileNode["profiles_order"];
+  const order = Array.isArray(rawOrder) ? rawOrder.filter((v): v is string => typeof v === "string") : [];
+  const lastUsed = asString(profileNode["last_used"]);
+
+  const entries: Array<{ dir: string; entry: Record<string, unknown> }> = [];
+  for (const [dir, value] of Object.entries(infoCache)) {
+    if (NON_PROFILE_DIRS.has(dir)) continue;
+    const entry = asRecord(value);
+    if (!entry) continue;
+    // Ephemeral (guest-like) profiles vanish when their window closes — never
+    // offer one as a durable pin.
+    if (entry["is_ephemeral"] === true) continue;
+    entries.push({ dir, entry });
+  }
+
+  const ordered = orderDirs(entries.map((e) => e.dir), order);
+  const byDir = new Map(entries.map((e) => [e.dir, e.entry]));
+
+  return ordered.flatMap((dir) => {
+    const entry = byDir.get(dir);
+    if (!entry) return [];
+    // `name` is the user-visible profile name; `gaia_name` is the Google
+    // account's own display name and is the better fallback when a profile
+    // still carries an auto-generated name like "Person 1".
+    const name = asString(entry["name"]) ?? asString(entry["gaia_name"]);
+    const email = asString(entry["user_name"]);
+    return [buildProfile(dir, name, email, dir === lastUsed)];
+  });
+};
+
+/** Tier 2 — directory scan, reading each profile's own `Preferences`. */
+const listFromPreferencesScan = async (userDataDir: string): Promise<ReadonlyArray<BrowserProfile>> => {
+  let dirents;
+  try {
+    dirents = await readdir(userDataDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const candidates = dirents
+    .filter((d) => d.isDirectory() && !NON_PROFILE_DIRS.has(d.name))
+    .map((d) => d.name)
+    .sort((a, b) => a.localeCompare(b));
+
+  const profiles: BrowserProfile[] = [];
+  for (const dir of candidates) {
+    const prefs = await readJsonFile(join(userDataDir, dir, "Preferences"));
+    if (!prefs) continue; // not a profile directory
+    const profileNode = asRecord(prefs["profile"]);
+    const name = profileNode ? asString(profileNode["name"]) : undefined;
+    const accounts = prefs["account_info"];
+    const firstAccount = Array.isArray(accounts) ? asRecord(accounts[0]) : null;
+    const email = firstAccount ? asString(firstAccount["email"]) : undefined;
+    profiles.push(buildProfile(dir, name, email, false));
+  }
+  return profiles;
+};
+
+/**
+ * Every selectable profile in a user-data-dir, best-effort. Returns an empty
+ * array when the directory is unreadable or holds no profiles.
+ */
+export const listProfiles = async (userDataDir: string): Promise<ReadonlyArray<BrowserProfile>> => {
+  const fromLocalState = await listFromLocalState(userDataDir);
+  if (fromLocalState.length > 0) return fromLocalState;
+  return listFromPreferencesScan(userDataDir);
+};

package/src/profile/paths.ts

@@ -0,0 +1,166 @@
+/**
+ * Filesystem locations for browser profile discovery and pin persistence.
+ *
+ * Two independent path families live here:
+ *
+ *   1. Chromium user-data-dir candidates, per platform and channel. A
+ *      user-data-dir holds `Local State` (the profile registry) and
+ *      `DevToolsActivePort`; individual profiles are subdirectories of it
+ *      (`Default`, `Profile 1`, …).
+ *      Reference: https://chromium.googlesource.com/chromium/src/+/HEAD/docs/user_data_dir.md
+ *
+ *   2. pi's agent config dir, where the profile pin is stored.
+ *
+ * On the agent dir: pi exports `getAgentDir()` from
+ * `@mariozechner/pi-coding-agent`, but importing it would be a RUNTIME import
+ * of the host package. Extensions installed via `pi install npm:...` do not
+ * get pi resolvable from their own node_modules (verified: the installed
+ * tree's `@mariozechner/` directory is empty), which is why every other import
+ * in this codebase is `import type` and erased at build time. So the three
+ * lines of `getAgentDir()` are replicated here instead — env var first, then
+ * `~/.pi/agent` (pi's dist/config.js: `PI_CODING_AGENT_DIR`, CONFIG_DIR_NAME
+ * `.pi`).
+ */
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// ── pi agent config dir ────────────────────────────────────────────────────
+
+/** pi's env override for the agent dir (APP_NAME.toUpperCase() + "_CODING_AGENT_DIR"). */
+const ENV_AGENT_DIR = "PI_CODING_AGENT_DIR";
+
+/**
+ * Expand a leading `~` exactly as pi's expandTildePath does — `~` and `~/…`
+ * only, never `~\…`, on every platform. This deliberately mirrors pi rather
+ * than improving on it: the pin has to land in the directory pi itself resolves
+ * from the same variable, so being more lenient here would put the file
+ * somewhere pi does not look.
+ */
+const expandTildePiCompatible = (path: string): string => {
+  if (path === "~") return homedir();
+  if (path.startsWith("~/")) return homedir() + path.slice(1);
+  return path;
+};
+
+/**
+ * Tilde expansion for values this package interprets on its own. Windows users
+ * write `~\dir` as naturally as `~/dir`, and no compatibility constraint
+ * applies, so both are accepted.
+ */
+const expandTildeLenient = (path: string): string => {
+  if (path === "~") return homedir();
+  if (path.startsWith("~/") || path.startsWith("~\\")) return join(homedir(), path.slice(2));
+  return path;
+};
+
+/** pi's agent config directory — `$PI_CODING_AGENT_DIR` or `~/.pi/agent`. */
+export const agentDir = (): string => {
+  const fromEnv = process.env[ENV_AGENT_DIR];
+  if (fromEnv) return expandTildePiCompatible(fromEnv);
+  return join(homedir(), ".pi", "agent");
+};
+
+/** Where the selected-profile pin is persisted. */
+export const pinFilePath = (): string => join(agentDir(), "browser-harness.json");
+
+// ── Chromium user-data-dir candidates ──────────────────────────────────────
+
+/**
+ * Windows resolves its per-user data root from %LOCALAPPDATA%, which can be
+ * redirected on roaming / managed accounts. Fall back to the conventional
+ * layout only when the variable is absent.
+ */
+const localAppData = (): string => process.env["LOCALAPPDATA"] ?? join(homedir(), "AppData", "Local");
+
+/**
+ * Every known default user-data-dir for Chromium-family browsers on the
+ * current platform. Order is stable but carries no priority — callers probe
+ * all of them.
+ *
+ * Includes paths the harness previously missed: snap Chromium (the default
+ * Chromium on Ubuntu) and the Linux-only `$CHROME_USER_DATA_DIR` override
+ * documented in user_data_dir.md.
+ */
+export const userDataDirCandidates = (): ReadonlyArray<string> => {
+  const home = homedir();
+  const dirs: string[] = [];
+
+  // A user-set override wins a spot at the front regardless of platform.
+  const envOverride = process.env["CHROME_USER_DATA_DIR"];
+  if (envOverride) dirs.push(expandTildeLenient(envOverride));
+
+  if (process.platform === "darwin") {
+    const support = join(home, "Library", "Application Support");
+    dirs.push(
+      join(support, "Google/Chrome"),
+      join(support, "Google/Chrome Beta"),
+      join(support, "Google/Chrome Dev"),
+      join(support, "Google/Chrome Canary"),
+      join(support, "Chromium"),
+      join(support, "BraveSoftware/Brave-Browser"),
+      join(support, "BraveSoftware/Brave-Browser-Beta"),
+      join(support, "BraveSoftware/Brave-Browser-Nightly"),
+      join(support, "BraveSoftware/Brave-Browser-Dev"),
+      join(support, "Microsoft Edge"),
+      join(support, "Microsoft Edge Beta"),
+      join(support, "Microsoft Edge Dev"),
+      join(support, "Microsoft Edge Canary"),
+    );
+  } else if (process.platform === "win32") {
+    const lad = localAppData();
+    dirs.push(
+      join(lad, "Google/Chrome/User Data"),
+      join(lad, "Google/Chrome Beta/User Data"),
+      join(lad, "Google/Chrome Dev/User Data"),
+      join(lad, "Google/Chrome SxS/User Data"),
+      join(lad, "Chromium/User Data"),
+      join(lad, "BraveSoftware/Brave-Browser/User Data"),
+      join(lad, "BraveSoftware/Brave-Browser-Beta/User Data"),
+      join(lad, "Microsoft/Edge/User Data"),
+      join(lad, "Microsoft/Edge Beta/User Data"),
+      join(lad, "Microsoft/Edge Dev/User Data"),
+      join(lad, "Microsoft/Edge SxS/User Data"),
+    );
+  } else {
+    dirs.push(
+      join(home, ".config/google-chrome"),
+      join(home, ".config/google-chrome-beta"),
+      join(home, ".config/google-chrome-unstable"),
+      join(home, ".config/chromium"),
+      join(home, ".config/chromium-browser"),
+      join(home, ".config/BraveSoftware/Brave-Browser"),
+      join(home, ".config/BraveSoftware/Brave-Browser-Beta"),
+      join(home, ".config/BraveSoftware/Brave-Browser-Nightly"),
+      join(home, ".config/microsoft-edge"),
+      join(home, ".config/microsoft-edge-beta"),
+      join(home, ".config/microsoft-edge-dev"),
+      // snap (Ubuntu's default Chromium) — confined to ~/snap/<pkg>/common
+      join(home, "snap/chromium/common/chromium"),
+      // flatpak
+      join(home, ".var/app/org.chromium.Chromium/config/chromium"),
+      join(home, ".var/app/com.google.Chrome/config/google-chrome"),
+      join(home, ".var/app/com.brave.Browser/config/BraveSoftware/Brave-Browser"),
+      join(home, ".var/app/com.microsoft.Edge/config/microsoft-edge"),
+    );
+  }
+
+  // De-duplicate while preserving order — an env override may repeat a default.
+  return Array.from(new Set(dirs));
+};
+
+/**
+ * Human-readable browser name for a user-data-dir, used to disambiguate the
+ * picker when more than one browser is installed. Falls back to the directory
+ * name, which is already descriptive for every path we generate.
+ */
+export const browserNameForUserDataDir = (userDataDir: string): string => {
+  const p = userDataDir.replace(/\\/g, "/");
+  const has = (needle: string): boolean => p.toLowerCase().includes(needle);
+  if (has("brave")) return "Brave";
+  if (has("edge")) return "Edge";
+  if (has("chromium")) return "Chromium";
+  if (has("chrome")) return "Chrome";
+  const last = p.split("/").filter(Boolean).pop();
+  return last ?? userDataDir;
+};

package/src/profile/picker.ts

@@ -0,0 +1,73 @@
+/**
+ * The profile picker, shared by /browser-profile and first-run setup so both
+ * show the user exactly the same list.
+ *
+ * Rendering rules:
+ *   - one row per profile, labelled "Name (email)" — or "Name (Profile 3)" when
+ *     the profile has no signed-in account, so every row keeps its shape
+ *   - the pinned profile is marked with a check
+ *   - a final row clears the selection, since a pin must be undoable
+ *
+ * `ctx.ui.select` resolves to undefined when the user presses Escape AND in
+ * non-interactive modes (pi's print/RPC UI context returns undefined for every
+ * dialog), so callers must treat "no answer" as "change nothing".
+ */
+
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { BrowserProfile } from "./list";
+import type { ProfilePin } from "./store";
+
+export const CLEAR_SELECTION_LABEL = "— Clear selection (use whichever window is focused) —";
+
+export type ProfileChoice =
+  | { readonly kind: "profile"; readonly profile: BrowserProfile }
+  | { readonly kind: "clear" }
+  | { readonly kind: "cancelled" };
+
+/**
+ * Two profiles can legitimately share a name and account (the same person
+ * signed into two profiles). Labels must stay distinct or the selection cannot
+ * be mapped back, so a repeated label gains its directory.
+ */
+const disambiguate = (profiles: ReadonlyArray<BrowserProfile>): ReadonlyArray<string> => {
+  const counts = new Map<string, number>();
+  for (const p of profiles) counts.set(p.label, (counts.get(p.label) ?? 0) + 1);
+  return profiles.map((p) => ((counts.get(p.label) ?? 0) > 1 ? `${p.label} [${p.dir}]` : p.label));
+};
+
+/**
+ * Show the picker and report what the user chose. Returns "cancelled" when
+ * there is no UI or the user dismissed the dialog.
+ */
+export const promptForProfile = async (
+  ctx: ExtensionContext,
+  profiles: ReadonlyArray<BrowserProfile>,
+  currentPin: ProfilePin | null,
+  title = "Select browser profile",
+): Promise<ProfileChoice> => {
+  if (!ctx.hasUI || profiles.length === 0) return { kind: "cancelled" };
+
+  const labels = disambiguate(profiles);
+  const rows = labels.map((label, i) => {
+    const isPinned = currentPin?.profileDir === profiles[i]?.dir;
+    return isPinned ? `✓ ${label}` : `  ${label}`;
+  });
+  const options = [...rows, CLEAR_SELECTION_LABEL];
+
+  const answer = await ctx.ui.select(title, options);
+  if (answer === undefined) return { kind: "cancelled" };
+  if (answer === CLEAR_SELECTION_LABEL) return { kind: "clear" };
+
+  const index = options.indexOf(answer);
+  const profile = index >= 0 ? profiles[index] : undefined;
+  if (!profile) return { kind: "cancelled" };
+  return { kind: "profile", profile };
+};
+
+/** Build the durable pin for a chosen profile. */
+export const pinFor = (userDataDir: string, profile: BrowserProfile): ProfilePin => ({
+  userDataDir,
+  profileDir: profile.dir,
+  label: profile.label,
+  savedAt: new Date().toISOString(),
+});

package/src/profile/store.ts

@@ -0,0 +1,105 @@
+/**
+ * Durable persistence for the selected browser profile.
+ *
+ * The pin must outlive session termination, so it cannot live in pi's session
+ * entries (`pi.appendEntry`, see src/state.ts) — those die with the session.
+ * It is a small JSON file in pi's agent config dir instead, shared by every
+ * project on the machine.
+ *
+ * The pin deliberately stores only `{ userDataDir, profileDir }`. A
+ * `browserContextId` is NOT persisted: Chrome mints fresh context ids on every
+ * browser run, so a stored one would be a stale pointer at best and a pointer
+ * into the wrong profile at worst. The context is re-resolved on each connect.
+ *
+ * Every read failure degrades to "no pin" rather than throwing — a corrupt
+ * file must never break browser control.
+ */
+
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { dirname } from "node:path";
+import { type Result, err, ok } from "../util/result";
+import { pinFilePath } from "./paths";
+
+export type ProfilePin = {
+  /** User-data-dir the profile belongs to — guards against browser switches. */
+  readonly userDataDir: string;
+  /** Profile subdirectory, e.g. "Profile 1". */
+  readonly profileDir: string;
+  /** Label captured at selection time, for display without a disk re-read. */
+  readonly label: string;
+  /** ISO timestamp of the selection. */
+  readonly savedAt: string;
+};
+
+type PinFile = {
+  readonly version: 1;
+  readonly profile: ProfilePin | null;
+};
+
+const CURRENT_VERSION = 1;
+
+const parsePin = (value: unknown): ProfilePin | null => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+  const o = value as Record<string, unknown>;
+  const userDataDir = o["userDataDir"];
+  const profileDir = o["profileDir"];
+  const label = o["label"];
+  const savedAt = o["savedAt"];
+  if (typeof userDataDir !== "string" || userDataDir.length === 0) return null;
+  if (typeof profileDir !== "string" || profileDir.length === 0) return null;
+  return {
+    userDataDir,
+    profileDir,
+    label: typeof label === "string" && label.length > 0 ? label : profileDir,
+    savedAt: typeof savedAt === "string" ? savedAt : "",
+  };
+};
+
+/**
+ * The persisted pin, or null when nothing is pinned, the file is missing, or
+ * it cannot be parsed. A file written by a newer version is treated as "no
+ * pin" rather than guessed at.
+ */
+export const readPin = async (): Promise<ProfilePin | null> => {
+  let raw: string;
+  try {
+    raw = await readFile(pinFilePath(), "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null) return null;
+    const file = parsed as Record<string, unknown>;
+    if (file["version"] !== CURRENT_VERSION) return null;
+    return parsePin(file["profile"]);
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Replace the pin atomically: a sibling temp file plus rename, so a crash
+ * mid-write can never leave a half-written pin behind.
+ */
+const writePinFile = async (profile: ProfilePin | null): Promise<Result<void, string>> => {
+  const target = pinFilePath();
+  const tmp = `${target}.${randomUUID()}.tmp`;
+  const payload: PinFile = { version: CURRENT_VERSION, profile };
+  try {
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(tmp, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+    await rename(tmp, target);
+    return ok(undefined);
+  } catch (e) {
+    await unlink(tmp).catch(() => {});
+    return err(`could not save profile selection to ${target}: ${e instanceof Error ? e.message : String(e)}`);
+  }
+};
+
+/** Persist the selected profile. */
+export const writePin = (pin: ProfilePin): Promise<Result<void, string>> => writePinFile(pin);
+
+/** Clear the selection, restoring the harness's unpinned behavior. */
+export const clearPin = (): Promise<Result<void, string>> => writePinFile(null);