6 files changed, 997 insertions, 0 deletions
diff --git a/test/manual/profile-concurrency-test.ts b/test/manual/profile-concurrency-test.ts
new file mode 100644
index 0000000..ab792c7
--- /dev/null
+++ b/test/manual/profile-concurrency-test.ts
@@ -0,0 +1,192 @@
+/**
+ * Concurrency regression for harness tab creation, against a real browser.
+ *
+ * browser_read_page is registered unserialized, so several isolated tabs can be
+ * opened at the same moment. Two risks live here:
+ *
+ *   1. Each concurrent caller finding "no harness window" and creating its own
+ *      — two blank windows before profiles existed, two LAUNCHED profile windows
+ *      after. ensureHarnessWindow single-flights per client to prevent it.
+ *   2. Callers sharing that single creation and all claiming the same seed tab.
+ *      Only the caller that started the creation may claim it; the rest must
+ *      open their own tab beside it.
+ *
+ * Runs pinned and unpinned inside a throwaway --user-data-dir.
+ *
+ * Run: npx tsx test/manual/profile-concurrency-test.ts
+ */
+import { spawn, execFileSync } from "node:child_process";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createBrowserClient } from "../../src/client";
+import { closeIsolatedTab, openIsolatedTab } from "../../src/domains/isolated-tab";
+
+const PORT = Number(process.env["PROFILE_CONC_PORT"] ?? 9488);
+const CONCURRENT_TABS = 5;
+
+let passed = 0;
+let failed = 0;
+const check = (cond: boolean, label: string): void => {
+  if (cond) {
+    passed++;
+    console.log(`  ✓ ${label}`);
+  } else {
+    failed++;
+    console.error(`  ✗ ${label}`);
+  }
+};
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+function findBrowser(): string | undefined {
+  const fromEnv = process.env["CHROME_BIN"] ?? process.env["CHROME_PATH"];
+  if (fromEnv && existsSync(fromEnv)) return fromEnv;
+  const candidates: string[] =
+    process.platform === "darwin"
+      ? [
+          "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+          "/Applications/Chromium.app/Contents/MacOS/Chromium",
+        ]
+      : process.platform === "win32"
+        ? [
+            join(process.env["PROGRAMFILES"] ?? "C:\\Program Files", "Google\\Chrome\\Application\\chrome.exe"),
+            join(process.env["LOCALAPPDATA"] ?? "", "Google\\Chrome\\Application\\chrome.exe"),
+          ]
+        : ["/opt/google/chrome/chrome", "/usr/bin/google-chrome", "/usr/bin/chromium", "/usr/bin/chromium-browser"];
+  return candidates.find((c) => c && existsSync(c));
+}
+
+const killTree = (pid: number | undefined): void => {
+  if (pid === undefined) return;
+  if (process.platform === "win32") {
+    try {
+      execFileSync("taskkill.exe", ["/pid", String(pid), "/T", "/F"], { stdio: "ignore" });
+    } catch {
+      // already gone
+    }
+    return;
+  }
+  try {
+    process.kill(-pid, "SIGKILL");
+  } catch {
+    try {
+      process.kill(pid, "SIGKILL");
+    } catch {
+      // already gone
+    }
+  }
+};
+
+async function scenario(exePath: string, label: string, pinned: boolean): Promise<void> {
+  const udd = mkdtempSync(join(tmpdir(), "pi-profile-conc-"));
+  const base = [
+    `--user-data-dir=${udd}`,
+    "--no-first-run",
+    "--no-default-browser-check",
+    "--disable-sync",
+    "--disable-background-networking",
+    "--window-size=600,450",
+  ];
+  const browser = spawn(exePath, [...base, `--remote-debugging-port=${PORT}`, "about:blank"], {
+    detached: true,
+    stdio: "ignore",
+  });
+  browser.unref();
+
+  try {
+    let endpoint: string | undefined;
+    for (let i = 0; i < 60 && !endpoint; i++) {
+      await sleep(500);
+      try {
+        const res = await fetch(`http://127.0.0.1:${PORT}/json/version`);
+        if (res.ok) endpoint = ((await res.json()) as { webSocketDebuggerUrl: string }).webSocketDebuggerUrl;
+      } catch {
+        // not up yet
+      }
+    }
+    if (!endpoint) {
+      check(false, `${label}: browser exposed its DevTools endpoint`);
+      return;
+    }
+
+    if (pinned) {
+      // Materialise the profile the run pins to.
+      spawn(exePath, [...base, "--profile-directory=Profile 2", "about:blank"], {
+        detached: true,
+        stdio: "ignore",
+      }).unref();
+      await sleep(6_000);
+    }
+
+    process.env["BU_CDP_WS"] = endpoint;
+    const client = createBrowserClient({
+      namespace: `conc-${pinned ? "pinned" : "plain"}`,
+      ...(pinned
+        ? { profilePin: { userDataDir: udd, profileDir: "Profile 2", label: "pinned", savedAt: "" } }
+        : {}),
+    });
+
+    const started = await client.start();
+    check(started.success, `${label}: client starts`);
+    if (!started.success) return;
+
+    const results = await Promise.all(Array.from({ length: CONCURRENT_TABS }, () => openIsolatedTab(client)));
+    const tabs = results.flatMap((r) => (r.success ? [r.data] : []));
+    check(tabs.length === CONCURRENT_TABS, `${label}: all ${CONCURRENT_TABS} concurrent tabs opened (${tabs.length})`);
+    check(new Set(tabs.map((t) => t.targetId)).size === tabs.length, `${label}: every tab is a distinct target`);
+
+    const windows = await Promise.all(
+      tabs.map(async (t) => {
+        const r = await client.session().callBrowser("Browser.getWindowForTarget", { targetId: t.targetId });
+        return r.success ? (r.data as { windowId?: number }).windowId : undefined;
+      }),
+    );
+    check(new Set(windows).size === 1, `${label}: all tabs share one window (${new Set(windows).size})`);
+
+    if (pinned) {
+      const contexts = await Promise.all(
+        tabs.map(async (t) => {
+          const r = await client.session().callBrowser("Target.getTargetInfo", { targetId: t.targetId });
+          return r.success
+            ? (r.data as { targetInfo?: { browserContextId?: string } }).targetInfo?.browserContextId
+            : undefined;
+        }),
+      );
+      check(
+        new Set(contexts).size === 1 && contexts[0] === client.profileContextId(),
+        `${label}: every tab is in the pinned profile`,
+      );
+    }
+
+    for (const tab of tabs) await closeIsolatedTab(client, tab);
+    await client.closeOwnedTabs();
+    await client.stop();
+  } finally {
+    killTree(browser.pid);
+    try {
+      rmSync(udd, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 });
+    } catch {
+      // a locked temp dir is not worth failing over
+    }
+  }
+}
+
+async function main(): Promise<void> {
+  const exePath = findBrowser();
+  if (!exePath) {
+    console.error("No Chrome/Chromium found — set CHROME_BIN. Skipping.");
+    process.exit(process.env["CI"] ? 1 : 0);
+  }
+  console.log(`browser: ${exePath}\n`);
+
+  await scenario(exePath, "UNPINNED", false);
+  await scenario(exePath, "PINNED", true);
+
+  console.log(`\n${passed} passed, ${failed} failed`);
+  process.exit(failed === 0 ? 0 : 1);
+}
+
+main().catch((e) => {
+  console.error("profile concurrency test failed:", e);
+  process.exit(1);
+});
diff --git a/test/manual/profile-e2e-test.ts b/test/manual/profile-e2e-test.ts
new file mode 100644
index 0000000..3ac3ac2
--- /dev/null
+++ b/test/manual/profile-e2e-test.ts
@@ -0,0 +1,295 @@
+/**
+ * End-to-end proof of profile pinning, against a REAL browser.
+ *
+ * Runs entirely inside a throwaway --user-data-dir, so the user's own browser
+ * and profiles are never touched. Designed to run on Linux (under xvfb-run),
+ * macOS, and Windows — the three OSes where the launch handshake relies on
+ * Chromium's ProcessSingleton handing our argv to the running browser.
+ *
+ * What it asserts:
+ *   1. two profiles in one browser enumerate from Local State
+ *   2. they surface as DISTINCT browserContextIds over one CDP endpoint
+ *   3. a sentinel launch opens a window in the requested profile and is
+ *      identifiable
+ *   4. tabs spawned afterwards stay in that profile AND that window
+ *   5. a spawned tab is attachable, navigable, and closable
+ *
+ * Run: npx tsx test/manual/profile-e2e-test.ts
+ *      CHROME_BIN=/path/to/chrome npx tsx test/manual/profile-e2e-test.ts
+ */
+import { spawn, execFileSync } from "node:child_process";
+import { mkdtempSync, rmSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import WebSocket from "ws";
+import { listProfiles } from "../../src/profile/list";
+import { openProfileWindow } from "../../src/profile/launch";
+
+const PORT = Number(process.env["PROFILE_E2E_PORT"] ?? 9444);
+
+let passed = 0;
+let failed = 0;
+const check = (cond: boolean, label: string): void => {
+  if (cond) {
+    passed++;
+    console.log(`  ✓ ${label}`);
+  } else {
+    failed++;
+    console.error(`  ✗ ${label}`);
+  }
+};
+
+/** Locate a Chrome/Chromium binary for the host OS. */
+function findBrowser(): string | undefined {
+  const fromEnv = process.env["CHROME_BIN"] ?? process.env["CHROME_PATH"];
+  if (fromEnv && existsSync(fromEnv)) return fromEnv;
+
+  const candidates: string[] =
+    process.platform === "darwin"
+      ? [
+          "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+          "/Applications/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing",
+          "/Applications/Chromium.app/Contents/MacOS/Chromium",
+        ]
+      : process.platform === "win32"
+        ? [
+            join(process.env["PROGRAMFILES"] ?? "C:\\Program Files", "Google\\Chrome\\Application\\chrome.exe"),
+            join(process.env["PROGRAMFILES(X86)"] ?? "C:\\Program Files (x86)", "Google\\Chrome\\Application\\chrome.exe"),
+            join(process.env["LOCALAPPDATA"] ?? "", "Google\\Chrome\\Application\\chrome.exe"),
+          ]
+        : ["/opt/google/chrome/chrome", "/usr/bin/google-chrome", "/usr/bin/chromium", "/usr/bin/chromium-browser"];
+
+  for (const candidate of candidates) {
+    if (candidate && existsSync(candidate)) return candidate;
+  }
+  if (process.platform === "linux") {
+    for (const name of ["google-chrome", "chromium", "chromium-browser"]) {
+      try {
+        const resolved = execFileSync("which", [name], { encoding: "utf8" }).trim();
+        if (resolved) return resolved;
+      } catch {
+        // not on PATH
+      }
+    }
+  }
+  return undefined;
+}
+
+type Cdp = {
+  call: (method: string, params?: Record<string, unknown>, sessionId?: string) => Promise<any>;
+  close: () => void;
+};
+
+async function connectCdp(): Promise<Cdp> {
+  const version = await (await fetch(`http://127.0.0.1:${PORT}/json/version`)).json();
+  const ws = new WebSocket((version as { webSocketDebuggerUrl: string }).webSocketDebuggerUrl, {
+    maxPayload: 64 * 1024 * 1024,
+  });
+  let id = 0;
+  const pending = new Map<number, (v: any) => void>();
+  ws.on("message", (d) => {
+    const m = JSON.parse(d.toString());
+    if (m.id && pending.has(m.id)) {
+      pending.get(m.id)!(m);
+      pending.delete(m.id);
+    }
+  });
+  await new Promise<void>((resolve, reject) => {
+    ws.once("open", () => resolve());
+    ws.once("error", reject);
+  });
+  return {
+    call: (method, params = {}, sessionId) =>
+      new Promise((resolve) => {
+        const myId = ++id;
+        pending.set(myId, resolve);
+        ws.send(JSON.stringify({ id: myId, method, params, ...(sessionId ? { sessionId } : {}) }));
+      }),
+    close: () => ws.close(),
+  };
+}
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+async function waitForEndpoint(deadlineMs = 30_000): Promise<boolean> {
+  const end = Date.now() + deadlineMs;
+  while (Date.now() < end) {
+    try {
+      const res = await fetch(`http://127.0.0.1:${PORT}/json/version`);
+      if (res.ok) return true;
+    } catch {
+      // not up yet
+    }
+    await sleep(500);
+  }
+  return false;
+}
+
+async function main(): Promise<void> {
+  const exePath = findBrowser();
+  if (!exePath) {
+    console.error("No Chrome/Chromium found — set CHROME_BIN. Skipping.");
+    process.exit(process.env["CI"] ? 1 : 0);
+  }
+  console.log(`browser: ${exePath}\n`);
+
+  const udd = mkdtempSync(join(tmpdir(), "pi-profile-e2e-"));
+  const baseArgs = [
+    `--user-data-dir=${udd}`,
+    "--no-first-run",
+    "--no-default-browser-check",
+    "--disable-sync",
+    "--disable-background-networking",
+    "--window-size=600,450",
+  ];
+
+  const browser = spawn(exePath, [...baseArgs, `--remote-debugging-port=${PORT}`, "about:blank"], {
+    detached: true,
+    stdio: "ignore",
+  });
+  browser.unref();
+
+  const cleanup = (): void => {
+    // Chrome spawns a tree of child processes. Leaving any alive keeps the
+    // user-data-dir locked, which on Windows also blocks the directory removal.
+    if (process.platform === "win32") {
+      try {
+        execFileSync("taskkill.exe", ["/pid", String(browser.pid), "/T", "/F"], { stdio: "ignore" });
+      } catch {
+        // already gone
+      }
+    } else {
+      try {
+        // detached:true put the browser in its own process group; the negative
+        // pid signals the whole group.
+        process.kill(-browser.pid!, "SIGKILL");
+      } catch {
+        try {
+          browser.kill("SIGKILL");
+        } catch {
+          // already gone
+        }
+      }
+    }
+    try {
+      rmSync(udd, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 });
+    } catch {
+      // A locked file in a temp dir is not worth failing the run over.
+    }
+  };
+
+  try {
+    if (!(await waitForEndpoint())) {
+      console.error("browser never exposed its DevTools endpoint");
+      cleanup();
+      process.exit(1);
+    }
+
+    // Create a SECOND profile in the same browser by launching into it. The
+    // running instance handles this via ProcessSingleton — the very behaviour
+    // profile pinning depends on.
+    const second = spawn(exePath, [...baseArgs, "--profile-directory=Profile 2", "about:blank"], {
+      detached: true,
+      stdio: "ignore",
+    });
+    second.unref();
+    await sleep(6_000);
+
+    const cdp = await connectCdp();
+    const pageTargets = async (): Promise<any[]> =>
+      ((await cdp.call("Target.getTargets")).result?.targetInfos ?? []).filter((t: any) => t.type === "page");
+    const windowOf = async (targetId: string): Promise<number | undefined> =>
+      (await cdp.call("Browser.getWindowForTarget", { targetId })).result?.windowId;
+
+    // 1. enumeration. Chrome flushes Local State asynchronously — a profile
+    // created seconds ago is not registered yet — so poll rather than read once.
+    let profiles = await listProfiles(udd);
+    const enumDeadline = Date.now() + 30_000;
+    while (Date.now() < enumDeadline && profiles.length < 2) {
+      await sleep(1_000);
+      profiles = await listProfiles(udd);
+    }
+    const dirs = profiles.map((p) => p.dir).sort();
+    check(dirs.includes("Default"), "E1: Default profile enumerated from Local State");
+    check(dirs.includes("Profile 2"), "E1: second profile enumerated from Local State");
+    check(
+      profiles.length >= 2 && profiles.every((p) => /^.+ \(.+\)$/.test(p.label)),
+      "E1: every profile has a 'Name (…)' label",
+    );
+
+    // 2. distinct browser contexts
+    const contexts = new Set((await pageTargets()).map((t) => t.browserContextId));
+    check(contexts.size >= 2, `E2: profiles surface as distinct browserContextIds (${contexts.size} seen)`);
+
+    // 3. sentinel launch into a chosen profile
+    const launched = await openProfileWindow({ exePath, profileDir: "Profile 2", explicitUserDataDir: udd });
+    check(launched.success, "E3: profile window launch dispatched");
+    if (!launched.success) throw new Error(launched.error);
+
+    const deadline = Date.now() + 20_000;
+    let seed: any;
+    while (Date.now() < deadline && !seed) {
+      await sleep(500);
+      seed = (await pageTargets()).find((t) => t.url === launched.data.sentinelUrl);
+    }
+    check(!!seed, "E3: sentinel page identifies the new profile window");
+    if (!seed) throw new Error("sentinel target never appeared");
+    await launched.data.cleanup();
+
+    const seedWindow = await windowOf(seed.targetId);
+    const seedContext = seed.browserContextId;
+    check(typeof seedContext === "string" && seedContext.length > 0, "E3: seed carries the profile's browserContextId");
+
+    // 4. + 5. spawn a tab the way the target factory does
+    const attached = await cdp.call("Target.attachToTarget", { targetId: seed.targetId, flatten: true });
+    const sessionId = attached.result?.sessionId;
+    check(!!sessionId, "E4: seed page in a non-default profile is attachable");
+
+    const token = `pi-e2e-${Date.now()}`;
+    const opened = await cdp.call(
+      "Runtime.evaluate",
+      {
+        expression: `!!window.open('about:blank#${token}', '_blank')`,
+        returnByValue: true,
+        userGesture: true,
+      },
+      sessionId,
+    );
+    check(opened.result?.result?.value === true, "E4: window.open with userGesture is not blocked");
+
+    let spawned: any;
+    const spawnDeadline = Date.now() + 10_000;
+    while (Date.now() < spawnDeadline && !spawned) {
+      await sleep(200);
+      spawned = (await pageTargets()).find((t) => t.url.includes(token));
+    }
+    check(!!spawned, "E4: spawned tab is found by its unique token");
+    if (!spawned) throw new Error("spawned tab never appeared");
+
+    check(spawned.browserContextId === seedContext, "E4: spawned tab stays in the pinned profile");
+    check((await windowOf(spawned.targetId)) === seedWindow, "E4: spawned tab stays in the harness window");
+
+    const attachSpawned = await cdp.call("Target.attachToTarget", { targetId: spawned.targetId, flatten: true });
+    check(!!attachSpawned.result?.sessionId, "E5: spawned tab is attachable");
+    const navigated = await cdp.call(
+      "Page.navigate",
+      { url: "about:blank#navigated" },
+      attachSpawned.result.sessionId,
+    );
+    check(!navigated.error, "E5: spawned tab is navigable");
+    const closed = await cdp.call("Target.closeTarget", { targetId: spawned.targetId });
+    check(closed.result?.success === true, "E5: spawned tab is closable");
+
+    cdp.close();
+  } finally {
+    cleanup();
+  }
+
+  console.log(`\n${passed} passed, ${failed} failed`);
+  process.exit(failed === 0 ? 0 : 1);
+}
+
+main().catch((e) => {
+  console.error("profile e2e test failed:", e);
+  process.exit(1);
+});
diff --git a/test/profile/browser-process-test.ts b/test/profile/browser-process-test.ts
new file mode 100644
index 0000000..29982e5
--- /dev/null
+++ b/test/profile/browser-process-test.ts
@@ -0,0 +1,108 @@
+/**
+ * Unit tests for browser-process parsing and candidate ranking — no browser.
+ *
+ * Ranking exists because a machine can run several Chromium browsers at once.
+ * Picking the wrong one means launching a profile window into a browser the
+ * harness is not connected to: the agent sees nothing, and a browser the user
+ * never pointed us at gets a new window. (That is exactly what happened during
+ * development before ranking existed.)
+ *
+ * Run: npx tsx test/profile/browser-process-test.ts
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { parseUserDataDirFlag, rankBrowserCandidate } from "../../src/profile/browser-process";
+
+let passed = 0;
+let failed = 0;
+const check = (cond: boolean, label: string): void => {
+  if (cond) {
+    passed++;
+    console.log(`  ✓ ${label}`);
+  } else {
+    failed++;
+    console.error(`  ✗ ${label}`);
+  }
+};
+
+function main(): void {
+  // B1: --user-data-dir parsing
+  {
+    check(
+      parseUserDataDirFlag("/opt/google/chrome/chrome --user-data-dir=/tmp/x --foo") === "/tmp/x",
+      "B1: bare value parsed",
+    );
+    check(
+      parseUserDataDirFlag('chrome.exe --user-data-dir="C:\\Users\\Some Name\\Data" --bar') ===
+        "C:\\Users\\Some Name\\Data",
+      "B1: double-quoted value with spaces parsed",
+    );
+    check(
+      parseUserDataDirFlag("chrome --user-data-dir='/home/u/my dir'") === "/home/u/my dir",
+      "B1: single-quoted value parsed",
+    );
+    check(parseUserDataDirFlag("/opt/google/chrome/chrome") === undefined, "B1: absent flag → undefined");
+    check(parseUserDataDirFlag("chrome --user-data-dir=") === undefined, "B1: empty value → undefined");
+  }
+
+  // B2: an explicit --user-data-dir is decisive in both directions
+  {
+    const target = "/tmp/pi-e2e-abc";
+    const match = rankBrowserCandidate({ exePath: "/opt/google/chrome/chrome", explicitUserDataDir: target }, target);
+    const other = rankBrowserCandidate(
+      { exePath: "/opt/google/chrome/chrome", explicitUserDataDir: "/tmp/somewhere-else" },
+      target,
+    );
+    const noFlag = rankBrowserCandidate({ exePath: "/opt/google/chrome/chrome" }, target);
+    check(match > noFlag, "B2: exact user-data-dir match outranks a flagless process");
+    check(other < noFlag, "B2: a DIFFERENT explicit user-data-dir ranks below a flagless process");
+    check(other === 0, "B2: a different explicit dir is disqualified outright");
+  }
+
+  // B3: browser family match decides between flagless processes
+  {
+    const braveDir = join(homedir(), ".config/BraveSoftware/Brave-Browser");
+    const brave = rankBrowserCandidate({ exePath: "/usr/bin/brave-browser" }, braveDir);
+    const chrome = rankBrowserCandidate({ exePath: "/opt/google/chrome/chrome" }, braveDir);
+    check(brave > chrome, "B3: Brave wins for a Brave user-data-dir");
+
+    const chromeDir = join(homedir(), ".config/google-chrome");
+    check(
+      rankBrowserCandidate({ exePath: "/opt/google/chrome/chrome" }, chromeDir) >
+        rankBrowserCandidate({ exePath: "/usr/bin/brave-browser" }, chromeDir),
+      "B3: Chrome wins for a Chrome user-data-dir",
+    );
+
+    const chromiumDir = join(homedir(), ".config/chromium");
+    check(
+      rankBrowserCandidate({ exePath: "/usr/bin/chromium" }, chromiumDir) >
+        rankBrowserCandidate({ exePath: "/opt/google/chrome/chrome" }, chromiumDir),
+      "B3: Chromium is not mistaken for Chrome",
+    );
+  }
+
+  // B4: no preference expressed → every candidate is equally acceptable
+  {
+    check(
+      rankBrowserCandidate({ exePath: "/usr/bin/brave-browser" }) ===
+        rankBrowserCandidate({ exePath: "/opt/google/chrome/chrome" }),
+      "B4: without a target dir, candidates rank equally",
+    );
+  }
+
+  // B5: Windows path comparison ignores case and separator style
+  if (process.platform === "win32") {
+    check(
+      rankBrowserCandidate(
+        { exePath: "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe", explicitUserDataDir: "C:\\Users\\U\\Data" },
+        "c:/users/u/data",
+      ) === 4,
+      "B5 win: case and separator differences still match",
+    );
+  }
+
+  console.log(`\n${passed} passed, ${failed} failed`);
+  process.exit(failed === 0 ? 0 : 1);
+}
+
+main();
diff --git a/test/profile/list-test.ts b/test/profile/list-test.ts
new file mode 100644
index 0000000..ca39b73
--- /dev/null
+++ b/test/profile/list-test.ts
@@ -0,0 +1,156 @@
+/**
+ * Unit tests for profile enumeration — no browser required.
+ *
+ * Builds throwaway user-data-dirs on disk so both tiers (Local State and the
+ * Preferences scan) run against real files.
+ *
+ * Run: npx tsx test/profile/list-test.ts
+ */
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { formatProfileLabel, listProfiles } from "../../src/profile/list";
+
+let passed = 0;
+let failed = 0;
+const check = (cond: boolean, label: string): void => {
+  if (cond) {
+    passed++;
+    console.log(`  ✓ ${label}`);
+  } else {
+    failed++;
+    console.error(`  ✗ ${label}`);
+  }
+};
+
+const roots: string[] = [];
+const makeUdd = (): string => {
+  const dir = mkdtempSync(join(tmpdir(), "pi-profile-test-"));
+  roots.push(dir);
+  return dir;
+};
+const writeLocalState = (udd: string, body: unknown): void =>
+  writeFileSync(join(udd, "Local State"), typeof body === "string" ? body : JSON.stringify(body), "utf8");
+const writeProfileDir = (udd: string, dir: string, prefs?: unknown): void => {
+  mkdirSync(join(udd, dir), { recursive: true });
+  if (prefs !== undefined) writeFileSync(join(udd, dir, "Preferences"), JSON.stringify(prefs), "utf8");
+};
+
+async function main(): Promise<void> {
+  // L1: tier 1 — names, emails, ordering, last-used marker
+  {
+    const udd = makeUdd();
+    writeLocalState(udd, {
+      profile: {
+        last_used: "Profile 1",
+        profiles_order: ["Default", "Profile 1", "Profile 2"],
+        info_cache: {
+          "Profile 2": { name: "Second", user_name: "second@example.com" },
+          Default: { name: "vertexcover.io", user_name: "aman@vertexcover.io" },
+          "Profile 1": { name: "Aman", user_name: "aman@personal.com" },
+        },
+      },
+    });
+    const profiles = await listProfiles(udd);
+    check(profiles.length === 3, "L1: all three profiles listed");
+    check(
+      profiles.map((p) => p.dir).join(",") === "Default,Profile 1,Profile 2",
+      "L1: profiles_order drives ordering, not object key order",
+    );
+    check(profiles[1]?.label === "Aman (aman@personal.com)", "L1: label is 'Name (email)'");
+    check(profiles[1]?.lastUsed === true, "L1: last_used profile is marked");
+    check(profiles[0]?.lastUsed === false, "L1: other profiles are not marked");
+  }
+
+  // L2: profile with no signed-in account falls back to the directory
+  {
+    const udd = makeUdd();
+    writeLocalState(udd, { profile: { info_cache: { "Profile 3": { name: "Work" } } } });
+    const profiles = await listProfiles(udd);
+    check(profiles[0]?.label === "Work (Profile 3)", "L2: no account → 'Name (dir)'");
+    check(profiles[0]?.email === undefined, "L2: email stays undefined");
+  }
+
+  // L3: gaia_name backfills a missing name; ephemeral profiles are skipped
+  {
+    const udd = makeUdd();
+    writeLocalState(udd, {
+      profile: {
+        info_cache: {
+          "Profile 4": { gaia_name: "Aman Kumar", user_name: "gaia@example.com" },
+          "Profile 5": { name: "Ghost", user_name: "ghost@example.com", is_ephemeral: true },
+          "System Profile": { name: "System" },
+        },
+      },
+    });
+    const profiles = await listProfiles(udd);
+    check(profiles.length === 1, "L3: ephemeral and System Profile entries are excluded");
+    check(profiles[0]?.label === "Aman Kumar (gaia@example.com)", "L3: gaia_name backfills a missing name");
+  }
+
+  // L4: unlisted profiles are appended alphabetically after profiles_order
+  {
+    const udd = makeUdd();
+    writeLocalState(udd, {
+      profile: {
+        profiles_order: ["Profile 9"],
+        info_cache: {
+          Default: { name: "D" },
+          "Profile 9": { name: "Nine" },
+          "Profile 3": { name: "Three" },
+        },
+      },
+    });
+    const profiles = await listProfiles(udd);
+    check(
+      profiles.map((p) => p.dir).join(",") === "Profile 9,Default,Profile 3",
+      "L4: ordered entries first, remainder alphabetical",
+    );
+  }
+
+  // L5: corrupt Local State falls through to the Preferences scan
+  {
+    const udd = makeUdd();
+    writeLocalState(udd, "{ this is not json");
+    writeProfileDir(udd, "Default", {
+      profile: { name: "Fallback Name" },
+      account_info: [{ email: "fallback@example.com" }],
+    });
+    writeProfileDir(udd, "Crash Reports"); // no Preferences → not a profile
+    const profiles = await listProfiles(udd);
+    check(profiles.length === 1, "L5: only directories holding Preferences count as profiles");
+    check(profiles[0]?.label === "Fallback Name (fallback@example.com)", "L5: tier 2 reads name + account email");
+  }
+
+  // L6: missing info_cache also falls through to tier 2
+  {
+    const udd = makeUdd();
+    writeLocalState(udd, { profile: { last_used: "Default" } });
+    writeProfileDir(udd, "Profile 1", { profile: { name: "Tier Two" } });
+    const profiles = await listProfiles(udd);
+    check(profiles[0]?.label === "Tier Two (Profile 1)", "L6: missing info_cache → Preferences scan");
+  }
+
+  // L7: nothing readable → empty list, never a throw
+  {
+    const profiles = await listProfiles(join(tmpdir(), "pi-profile-does-not-exist-xyz"));
+    check(profiles.length === 0, "L7: unreadable user-data-dir yields an empty list");
+  }
+
+  // L8: label formatting is total
+  {
+    check(formatProfileLabel("A", "a@b.c", "Default") === "A (a@b.c)", "L8: email wins the brackets");
+    check(formatProfileLabel("A", undefined, "Profile 7") === "A (Profile 7)", "L8: dir fills in without an email");
+    check(formatProfileLabel("A", "", "Profile 7") === "A (Profile 7)", "L8: empty email is treated as absent");
+  }
+
+  for (const root of roots) rmSync(root, { recursive: true, force: true });
+
+  console.log(`\n${passed} passed, ${failed} failed`);
+  process.exit(failed === 0 ? 0 : 1);
+}
+
+main().catch((e) => {
+  console.error("profile list test failed:", e);
+  process.exit(1);
+});
diff --git a/test/profile/paths-test.ts b/test/profile/paths-test.ts
new file mode 100644
index 0000000..1a2c937
--- /dev/null
+++ b/test/profile/paths-test.ts
@@ -0,0 +1,130 @@
+/**
+ * Unit tests for path resolution — runs on Linux, macOS, and Windows in CI.
+ *
+ * Only the branch for the host platform can be exercised, so each assertion is
+ * guarded by process.platform; the CI matrix is what gives all three coverage.
+ *
+ * Run: npx tsx test/profile/paths-test.ts
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+let passed = 0;
+let failed = 0;
+const check = (cond: boolean, label: string): void => {
+  if (cond) {
+    passed++;
+    console.log(`  ✓ ${label}`);
+  } else {
+    failed++;
+    console.error(`  ✗ ${label}`);
+  }
+};
+
+/** Re-import with a fresh module identity so env changes are picked up. */
+const freshImport = async (): Promise<typeof import("../../src/profile/paths")> =>
+  import(`../../src/profile/paths?cache=${Math.random()}`);
+
+const withEnv = async (key: string, value: string | undefined, fn: () => Promise<void>): Promise<void> => {
+  const saved = process.env[key];
+  if (value === undefined) delete process.env[key];
+  else process.env[key] = value;
+  try {
+    await fn();
+  } finally {
+    if (saved === undefined) delete process.env[key];
+    else process.env[key] = saved;
+  }
+};
+
+async function main(): Promise<void> {
+  // A1: agent dir default and override
+  await withEnv("PI_CODING_AGENT_DIR", undefined, async () => {
+    const { agentDir, pinFilePath } = await freshImport();
+    check(agentDir() === join(homedir(), ".pi", "agent"), "A1: default agent dir is ~/.pi/agent");
+    check(pinFilePath() === join(homedir(), ".pi", "agent", "browser-harness.json"), "A1: pin file sits in it");
+  });
+  // pi's own expandTildePath only understands "~/" — never "~\" — so the agent
+  // dir must resolve identically or the pin lands where pi does not look.
+  await withEnv("PI_CODING_AGENT_DIR", "~/custom-agent", async () => {
+    check(
+      (await freshImport()).agentDir() === `${homedir()}/custom-agent`,
+      "A1: '~/' in the agent-dir override expands like pi",
+    );
+  });
+  if (process.platform === "win32") {
+    await withEnv("PI_CODING_AGENT_DIR", "~\\custom-agent", async () => {
+      check(
+        (await freshImport()).agentDir() === "~\\custom-agent",
+        "A1 win: '~\\' is left alone, matching pi's own resolution",
+      );
+    });
+  }
+
+  // A2: platform candidate list
+  await withEnv("CHROME_USER_DATA_DIR", undefined, async () => {
+    const dirs = (await freshImport()).userDataDirCandidates();
+    check(dirs.length > 0, "A2: candidates are non-empty on this platform");
+    check(new Set(dirs).size === dirs.length, "A2: candidate list is de-duplicated");
+
+    if (process.platform === "linux") {
+      check(dirs.includes(join(homedir(), ".config/google-chrome")), "A2 linux: Chrome stable dir present");
+      check(dirs.includes(join(homedir(), "snap/chromium/common/chromium")), "A2 linux: snap Chromium dir present");
+      check(dirs.includes(join(homedir(), ".config/BraveSoftware/Brave-Browser")), "A2 linux: Brave dir present");
+    } else if (process.platform === "darwin") {
+      const support = join(homedir(), "Library", "Application Support");
+      check(dirs.includes(join(support, "Google/Chrome")), "A2 macos: Chrome dir present");
+      check(dirs.includes(join(support, "BraveSoftware/Brave-Browser")), "A2 macos: Brave dir present");
+      check(dirs.includes(join(support, "Microsoft Edge")), "A2 macos: Edge dir present");
+    } else if (process.platform === "win32") {
+      const lad = process.env["LOCALAPPDATA"] ?? join(homedir(), "AppData", "Local");
+      check(dirs.includes(join(lad, "Google/Chrome/User Data")), "A2 win: Chrome dir derives from %LOCALAPPDATA%");
+      check(dirs.includes(join(lad, "Microsoft/Edge/User Data")), "A2 win: Edge dir present");
+    }
+  });
+
+  // A3: %LOCALAPPDATA% redirection is honoured (Windows-only behaviour)
+  if (process.platform === "win32") {
+    await withEnv("LOCALAPPDATA", "D:\\Redirected\\Local", async () => {
+      const dirs = (await freshImport()).userDataDirCandidates();
+      check(
+        dirs.some((d) => d.startsWith("D:\\Redirected\\Local") || d.startsWith("D:/Redirected/Local")),
+        "A3 win: redirected LOCALAPPDATA is used",
+      );
+    });
+  }
+
+  // A4: $CHROME_USER_DATA_DIR override leads the list. This value is ours to
+  // interpret, so both tilde separators are accepted.
+  await withEnv("CHROME_USER_DATA_DIR", join("~", "my-chrome-data"), async () => {
+    const dirs = (await freshImport()).userDataDirCandidates();
+    check(dirs[0] === join(homedir(), "my-chrome-data"), "A4: env override is first and tilde-expanded");
+  });
+  await withEnv("CHROME_USER_DATA_DIR", "~/my-chrome-data", async () => {
+    const dirs = (await freshImport()).userDataDirCandidates();
+    check(dirs[0] === join(homedir(), "my-chrome-data"), "A4: forward-slash tilde expands on every platform");
+  });
+
+  // A5: browser naming
+  {
+    const { browserNameForUserDataDir } = await freshImport();
+    check(browserNameForUserDataDir("/home/u/.config/google-chrome") === "Chrome", "A5: Chrome recognised");
+    check(
+      browserNameForUserDataDir("/home/u/.config/BraveSoftware/Brave-Browser") === "Brave",
+      "A5: Brave recognised",
+    );
+    check(
+      browserNameForUserDataDir("C:\\Users\\u\\AppData\\Local\\Microsoft\\Edge\\User Data") === "Edge",
+      "A5: Edge recognised through Windows separators",
+    );
+    check(browserNameForUserDataDir("/home/u/.config/chromium") === "Chromium", "A5: Chromium beats Chrome");
+  }
+
+  console.log(`\n${passed} passed, ${failed} failed`);
+  process.exit(failed === 0 ? 0 : 1);
+}
+
+main().catch((e) => {
+  console.error("profile paths test failed:", e);
+  process.exit(1);
+});
diff --git a/test/profile/store-test.ts b/test/profile/store-test.ts
new file mode 100644
index 0000000..c881372
--- /dev/null
+++ b/test/profile/store-test.ts
@@ -0,0 +1,116 @@
+/**
+ * Unit tests for the profile pin store — no browser required.
+ *
+ * Redirects pi's agent dir via $PI_CODING_AGENT_DIR so the real
+ * ~/.pi/agent/browser-harness.json is never touched.
+ *
+ * Run: npx tsx test/profile/store-test.ts
+ */
+import { mkdtempSync, mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+let passed = 0;
+let failed = 0;
+const check = (cond: boolean, label: string): void => {
+  if (cond) {
+    passed++;
+    console.log(`  ✓ ${label}`);
+  } else {
+    failed++;
+    console.error(`  ✗ ${label}`);
+  }
+};
+
+const pin = {
+  userDataDir: "/home/u/.config/google-chrome",
+  profileDir: "Profile 1",
+  label: "Aman (aman@example.com)",
+  savedAt: new Date(0).toISOString(),
+};
+
+async function main(): Promise<void> {
+  const sandbox = mkdtempSync(join(tmpdir(), "pi-pin-test-"));
+  process.env["PI_CODING_AGENT_DIR"] = sandbox;
+
+  // Imported after the env override so paths.ts resolves into the sandbox.
+  const { pinFilePath } = await import("../../src/profile/paths");
+  const { readPin, writePin, clearPin } = await import("../../src/profile/store");
+
+  // P1: agent dir honours the env override
+  check(pinFilePath() === join(sandbox, "browser-harness.json"), "P1: pin path follows $PI_CODING_AGENT_DIR");
+
+  // P2: nothing written yet
+  check((await readPin()) === null, "P2: absent file reads as no pin");
+
+  // P3: round trip
+  {
+    const written = await writePin(pin);
+    check(written.success, "P3: write succeeds");
+    const read = await readPin();
+    check(read?.profileDir === "Profile 1", "P3: profileDir round-trips");
+    check(read?.userDataDir === pin.userDataDir, "P3: userDataDir round-trips");
+    check(read?.label === pin.label, "P3: label round-trips");
+  }
+
+  // P4: no temp files survive an atomic write
+  check(readdirSync(sandbox).filter((f) => f.endsWith(".tmp")).length === 0, "P4: write leaves no .tmp files");
+
+  // P5: overwrite replaces rather than appends
+  {
+    await writePin({ ...pin, profileDir: "Default", label: "Work (work@example.com)" });
+    const read = await readPin();
+    check(read?.profileDir === "Default", "P5: second write replaces the first");
+    check(readdirSync(sandbox).filter((f) => f === "browser-harness.json").length === 1, "P5: one pin file on disk");
+  }
+
+  // P6: clear
+  {
+    const cleared = await clearPin();
+    check(cleared.success, "P6: clear succeeds");
+    check((await readPin()) === null, "P6: cleared pin reads as none");
+  }
+
+  // P7: corrupt file degrades to no pin
+  writeFileSync(pinFilePath(), "{ not json at all", "utf8");
+  check((await readPin()) === null, "P7: malformed JSON reads as no pin");
+
+  // P8: unknown schema version is not guessed at
+  writeFileSync(pinFilePath(), JSON.stringify({ version: 99, profile: pin }), "utf8");
+  check((await readPin()) === null, "P8: future version reads as no pin");
+
+  // P9: structurally invalid pin is rejected
+  writeFileSync(pinFilePath(), JSON.stringify({ version: 1, profile: { profileDir: 42 } }), "utf8");
+  check((await readPin()) === null, "P9: wrong field types read as no pin");
+
+  // P10: a missing agent dir is created on write
+  {
+    rmSync(sandbox, { recursive: true, force: true });
+    const written = await writePin(pin);
+    check(written.success, "P10: write recreates a missing agent dir");
+    check((await readPin())?.profileDir === "Profile 1", "P10: pin readable after dir recreation");
+  }
+
+  // P11: an unwritable location surfaces as an error result, not a throw
+  {
+    const blocked = join(sandbox, "blocked");
+    mkdirSync(blocked, { recursive: true });
+    writeFileSync(join(blocked, "browser-harness.json"), "{}", "utf8");
+    // Point the agent dir at a FILE — mkdir/write must fail cleanly.
+    process.env["PI_CODING_AGENT_DIR"] = join(blocked, "browser-harness.json");
+    const { writePin: writeAgain } = await import(`../../src/profile/store?nocache=${Date.now()}`);
+    const written = await writeAgain(pin);
+    check(!written.success, "P11: write into an invalid dir returns an error result");
+    process.env["PI_CODING_AGENT_DIR"] = sandbox;
+  }
+
+  rmSync(sandbox, { recursive: true, force: true });
+
+  console.log(`\n${passed} passed, ${failed} failed`);
+  process.exit(failed === 0 ? 0 : 1);
+}
+
+main().catch((e) => {
+  console.error("profile store test failed:", e);
+  process.exit(1);
+});