pi-browser-harness 0.10.2 → 0.12.0

package/src/profile/command.ts

@@ -1,27 +1,59 @@
-/**
- * /browser-profile — choose which browser profile the agent works in.
- *
- * The selection is durable (see store.ts) and applies immediately: the current
- * harness tabs are closed and a new window is opened in the chosen profile, so
- * the agent's next action happens where the user just asked for it rather than
- * one session later.
- */
-
 import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
 import type { BrowserClient } from "../client";
 import { discoverEndpoint } from "../cdp/discovery";
 import { type Result, err, ok } from "../util/result";
 import { type BrowserProfile, listProfiles } from "./list";
 import { browserNameForUserDataDir, userDataDirCandidates } from "./paths";
-import { pinFor, promptForProfile } from "./picker";
-import { clearPin, readPin, writePin } from "./store";
-
-/**
- * Which user-data-dir the picker should enumerate: the connected browser's
- * when known, otherwise a running browser's, otherwise the only installed one
- * that actually has profiles.
- */
-export const resolveUserDataDir = async (client: BrowserClient): Promise<Result<string, string>> => {
+import { clearPin, type ProfilePin, readPin, writePin } from "./store";
+
+// `ctx.ui.select` resolves to undefined both on Escape and in non-interactive modes, so "no answer" must mean "change nothing".
+
+const CLEAR_SELECTION_LABEL = "— Clear selection (use whichever window is focused) —";
+
+type ProfileChoice =
+  | { readonly kind: "profile"; readonly profile: BrowserProfile }
+  | { readonly kind: "clear" }
+  | { readonly kind: "cancelled" };
+
+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));
+};
+
+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 };
+};
+
+const pinFor = (userDataDir: string, profile: BrowserProfile): ProfilePin => ({
+  userDataDir,
+  profileDir: profile.dir,
+  label: profile.label,
+  savedAt: new Date().toISOString(),
+});
+
+const resolveUserDataDir = async (client: BrowserClient): Promise<Result<string, string>> => {
   const connected = client.userDataDir();
   if (connected) return ok(connected);
 
@@ -43,7 +75,6 @@ export const resolveUserDataDir = async (client: BrowserClient): Promise<Result<
   );
 };
 
-/** Enumerate profiles for the resolved dir, or explain why we cannot. */
 const loadProfiles = async (
   client: BrowserClient,
 ): Promise<Result<{ userDataDir: string; profiles: ReadonlyArray<BrowserProfile> }, string>> => {
@@ -56,11 +87,6 @@ const loadProfiles = async (
   return ok({ userDataDir: dir.data, profiles });
 };
 
-/**
- * Re-seed the live session so the new profile takes effect now. Closing the
- * owned tabs and restarting the client makes start() open a window in the
- * pinned profile and attach to it.
- */
 const applyToLiveSession = async (client: BrowserClient): Promise<Result<void, string>> => {
   if (!client.status().alive) return ok(undefined);
   await client.closeOwnedTabs();
@@ -127,11 +153,6 @@ export function registerProfileCommand(pi: ExtensionAPI, client: BrowserClient):
   });
 }
 
-/**
- * First-run prompt used by setup: pick a profile when none is pinned yet.
- * Returns a note to append to the setup output; the caller always continues,
- * because a cancelled or unavailable picker must leave existing behavior intact.
- */
 export const promptForProfileIfUnset = async (
   client: BrowserClient,
   ctx: ExtensionContext | undefined,

package/src/profile/launch.ts

@@ -1,19 +1,5 @@
-/**
- * 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.
- */
+// CDP cannot open a window in another profile, so this goes through the command line: ProcessSingleton hands the argv to the running browser.
+// The sentinel must ride on a real `file://` URL — Chrome discards a bare `about:blank#token` argument and opens chrome://newtab instead.
 
 import { spawn, type ChildProcess } from "node:child_process";
 import { randomUUID } from "node:crypto";
@@ -24,23 +10,13 @@ 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>;
   readonly kill: () => void;
 };
@@ -49,10 +25,6 @@ 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>> => {
@@ -69,29 +41,39 @@ export const openProfileWindow = async (
   if (req.explicitUserDataDir) args.push(`--user-data-dir=${req.explicitUserDataDir}`);
   args.push(`--profile-directory=${req.profileDir}`, "--new-window", sentinelUrl);
 
-  let child: ChildProcess | null = null;
+  let child: ChildProcess;
   try {
-    // No shell: arguments are passed as an array, so profile names and paths
-    // containing spaces survive intact on every platform.
     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)}`);
   }
 
+  // spawn() reports a bad binary asynchronously as an 'error' event rather than throwing; unhandled, an ENOENT looked like the 15s sentinel timeout.
+  const spawnFailure = await new Promise<string | undefined>((resolve) => {
+    child.once("spawn", () => resolve(undefined));
+    child.once("error", (e: Error) => resolve(e.message));
+  });
+  // A later 'error' event with no listener would throw, so keep one attached for the detached launcher's lifetime.
+  child.on("error", () => {});
+  child.unref();
+
+  if (spawnFailure) {
+    await rm(file, { force: true }).catch(() => {});
+    return err(`could not launch ${req.exePath}: ${spawnFailure}`);
+  }
+
+  let live: ChildProcess | null = child;
+
   return ok({
     sentinelUrl,
     cleanup: async () => {
       await rm(file, { force: true }).catch(() => {});
     },
     kill: () => {
-      if (child) {
-        try { child.kill("SIGTERM"); } catch {}
-        child = null;
+      if (live) {
+        try { live.kill("SIGTERM"); } catch {}
+        live = null;
       }
     },
   });

package/src/profile/list.ts

@@ -1,76 +1,46 @@
-/**
- * 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";
+import { Type } from "typebox";
+import { Compile } from "typebox/compile";
+import { parseJson } from "../schemas/parse";
 
 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 JsonObject = Type.Record(Type.String(), Type.Unknown());
+
+const jsonObjectValidator = Compile(JsonObject);
+
 const readJsonFile = async (path: string): Promise<Record<string, unknown> | null> => {
+  let raw: string;
   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>;
+    raw = await readFile(path, "utf8");
   } 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 parsed = parseJson(raw, jsonObjectValidator);
+  return parsed.success ? parsed.data : null;
 };
 
 const asRecord = (v: unknown): Record<string, unknown> | null =>
-  typeof v === "object" && v !== null && !Array.isArray(v) ? (v as Record<string, unknown>) : null;
+  jsonObjectValidator.Check(v) ? v : 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));
@@ -93,7 +63,6 @@ const buildProfile = (
   };
 };
 
-/** 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 [];
@@ -111,8 +80,7 @@ const listFromLocalState = async (userDataDir: string): Promise<ReadonlyArray<Br
     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.
+    // Ephemeral (guest-like) profiles vanish when their window closes, so they can never be a durable pin.
     if (entry["is_ephemeral"] === true) continue;
     entries.push({ dir, entry });
   }
@@ -123,16 +91,12 @@ const listFromLocalState = async (userDataDir: string): Promise<ReadonlyArray<Br
   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 {
@@ -149,7 +113,7 @@ const listFromPreferencesScan = async (userDataDir: string): Promise<ReadonlyArr
   const profiles: BrowserProfile[] = [];
   for (const dir of candidates) {
     const prefs = await readJsonFile(join(userDataDir, dir, "Preferences"));
-    if (!prefs) continue; // not a profile directory
+    if (!prefs) continue;
     const profileNode = asRecord(prefs["profile"]);
     const name = profileNode ? asString(profileNode["name"]) : undefined;
     const accounts = prefs["account_info"];
@@ -160,10 +124,6 @@ const listFromPreferencesScan = async (userDataDir: string): Promise<ReadonlyArr
   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;

package/src/profile/paths.ts

@@ -1,92 +1,37 @@
-/**
- * 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`).
- */
+// pi's `getAgentDir()` is replicated rather than imported: a runtime import of the host package does not resolve for extensions installed via `pi install npm:...`.
 
 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.
- */
+// Deliberately mirrors pi's expandTildePath (never `~\…`) rather than improving on it, or the pin lands 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));
 
@@ -135,9 +80,7 @@ export const userDataDirCandidates = (): ReadonlyArray<string> => {
       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"),
@@ -145,15 +88,9 @@ export const userDataDirCandidates = (): ReadonlyArray<string> => {
     );
   }
 
-  // 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);

package/src/profile/store.ts

@@ -1,34 +1,18 @@
-/**
- * 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.
- */
+// A `browserContextId` is deliberately NOT persisted: Chrome mints fresh context ids per browser run, so a stored one could point into the wrong profile.
 
 import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { dirname } from "node:path";
+import { Type } from "typebox";
+import { Compile } from "typebox/compile";
+import { parseJson } from "../schemas/parse";
 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;
 };
 
@@ -39,28 +23,27 @@ type PinFile = {
 
 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 : "",
-  };
-};
+const PinFileSchema = Type.Object(
+  {
+    version: Type.Literal(CURRENT_VERSION),
+    profile: Type.Union([
+      Type.Object(
+        {
+          userDataDir: Type.String({ minLength: 1 }),
+          profileDir: Type.String({ minLength: 1 }),
+          label: Type.Optional(Type.Unknown()),
+          savedAt: Type.Optional(Type.Unknown()),
+        },
+        { additionalProperties: true },
+      ),
+      Type.Null(),
+    ]),
+  },
+  { additionalProperties: true },
+);
+
+const pinFileValidator = Compile(PinFileSchema);
 
-/**
- * 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 {
@@ -68,21 +51,19 @@ export const readPin = async (): Promise<ProfilePin | null> => {
   } 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;
-  }
+  const parsed = parseJson(raw, pinFileValidator);
+  if (!parsed.success) return null;
+  const profile = parsed.data.profile;
+  if (profile === null) return null;
+  const { userDataDir, profileDir, label, savedAt } = profile;
+  return {
+    userDataDir,
+    profileDir,
+    label: typeof label === "string" && label.length > 0 ? label : profileDir,
+    savedAt: typeof savedAt === "string" ? savedAt : "",
+  };
 };
 
-/**
- * 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`;
@@ -98,8 +79,6 @@ const writePinFile = async (profile: ProfilePin | null): Promise<Result<void, st
   }
 };
 
-/** 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);