feat: pin the agent to a chosen browser profile (#16)

* feat: pin the agent to a chosen browser profile (#15)

Harness tabs were created with a bare Target.createTarget, which places
them in Chrome's defaultBrowserContextId — and that value follows window
focus. Which profile the agent acted as therefore depended on which
browser window the user last clicked, so the same task could run as a
work account on one run and a personal account on the next.

/browser-profile lists the connected browser's profiles as "Name (email)"
and pins one to ~/.pi/agent/browser-harness.json, so the choice outlives
the session. The same picker appears on first browser_setup when nothing
is pinned; with no interactive UI, or on cancel, setup continues with a
note and the previous behavior.

Chrome offers no direct route to another profile: Target.createTarget
rejects a foreign browserContextId, and openerId does not inherit the
opener's context. The window is opened through the browser's own command
line (--profile-directory, handed to the running browser by Chromium's
ProcessSingleton) and identified by a unique file:// sentinel page, since
a bare about:blank#token argument is discarded. Further tabs come from
window.open evaluated with userGesture: true — the only CDP-reachable way
to place a tab in a non-default browser context — correlated by a unique
token so concurrent isolated tabs stay distinct. A failed handshake is
reported, never silently redirected to another profile.

All four tab-creation sites now funnel through cdp/target-factory, so
open_urls and the isolated tabs behind web_search / read_page cannot run
with a different profile's cookies than the visible tabs.

Also fixed along the way: snap Chromium is discovered, Windows uses
%LOCALAPPDATA%, browsers launched with an explicit --user-data-dir are
found, the running browser is chosen by ranking candidates against the
connected user-data-dir rather than taking the first process found, and
an installed-but-closed browser no longer reads as running.

CI runs the profile suites and a real-browser end-to-end test on ubuntu,
macOS, and Windows — profile discovery is the one part of the harness
whose behavior genuinely differs per OS.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix: single-flight harness window creation

Isolated tabs run concurrently (browser_read_page is registered
unserialized), so several could each find "no harness window" and create
one — two blank windows before this feature, two LAUNCHED profile windows
after it. ensureHarnessWindow now shares one in-flight creation per
client.

Sharing introduces a second hazard: freshlyCreated is a claim on the seed
tab, and if every waiter received it, they would all drive the same tab.
Only the caller that started the creation keeps the claim; the rest open
their own tab beside it.

Covered by test/manual/profile-concurrency-test.ts (five concurrent
isolated tabs, pinned and unpinned: distinct targets, one window, correct
profile), wired into CI on Linux only — the coordination is pure JS and
identical across platforms.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix: tilde expansion differs by purpose on Windows

CI on windows-latest caught this: join("~", "x") yields "~\x" there, and
expandTilde only handled "~/".

The two uses are not the same, so they no longer share a helper. The
agent dir stays byte-compatible with pi's own expandTildePath ("~/" only,
every platform) — being more lenient would put the pin file somewhere pi
never looks. $CHROME_USER_DATA_DIR is ours to interpret, so it accepts
"~\" as well, which is what a Windows user would type.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

1 files changed, 108 insertions, 0 deletions

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();