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, 223 insertions, 0 deletions

diff --git a/src/cdp/target-factory.ts b/src/cdp/target-factory.ts
new file mode 100644
index 0000000..25c43a6
--- /dev/null
+++ b/src/cdp/target-factory.ts
@@ -0,0 +1,223 @@
+/**
+ * The single place harness tabs and windows are created.
+ *
+ * Every tab the harness opens must land in the pinned profile, so all creation
+ * paths (client.newTab, browser_open_urls, isolated tabs for web_search /
+ * read_page) funnel through here. A missed call site would silently act in
+ * another profile — with that profile's cookies and logins.
+ *
+ * Two mechanisms, chosen by whether a profile is pinned:
+ *
+ *   unpinned — `Target.createTarget`, exactly as before: `newWindow: true` for
+ *              a fresh dedicated window, `openerId` for siblings inside it.
+ *
+ *   pinned   — the window comes from a command-line launch into the profile
+ *              (see profile/launch.ts), and further tabs come from
+ *              `window.open(..., '_blank')` evaluated in an owned page with
+ *              `userGesture: true`. That is the only CDP-reachable way to place
+ *              a tab in a non-default browser context: createTarget rejects a
+ *              foreign browserContextId outright, and `openerId` does NOT
+ *              inherit the opener's context (verified — it lands in the
+ *              focus-derived default context, in a different window).
+ *              window.open keeps both the context and the window, recursively.
+ *
+ * Correlation: window.open returns no target id, so each spawn carries a unique
+ * `about:blank#pi-<uuid>` token and the new target is found by that token.
+ * Set-difference polling would be wrong here — isolated tabs run concurrently
+ * (browser_read_page is registered unserialized).
+ */
+
+import { randomUUID } from "node:crypto";
+import type { BrowserClient } from "../client";
+import { type Result, err, ok } from "../util/result";
+import { type CdpError, cdpError } from "./errors";
+
+/** How long to wait for a window.open-spawned target to appear. */
+const SPAWN_DEADLINE_MS = 8_000;
+const SPAWN_POLL_MS = 100;
+
+export type HarnessWindow = {
+  /** Target id of the window's seed tab. */
+  readonly targetId: string;
+  /**
+   * True when this call created the window. The seed tab is then a blank tab
+   * the caller may use directly, instead of opening a second one.
+   */
+  readonly freshlyCreated: boolean;
+};
+
+type PageTarget = {
+  readonly targetId: string;
+  readonly type: string;
+  readonly url: string;
+  readonly browserContextId?: string;
+};
+
+const listPageTargets = async (client: BrowserClient): Promise<Result<ReadonlyArray<PageTarget>, CdpError>> => {
+  const r = await client.session().callBrowser("Target.getTargets");
+  if (!r.success) return r;
+  const data = r.data as { targetInfos: ReadonlyArray<PageTarget> };
+  return ok(data.targetInfos.filter((t) => t.type === "page"));
+};
+
+/** A CDP session id for driving `targetId`, reusing the active one when possible. */
+const sessionForTarget = async (client: BrowserClient, targetId: string): Promise<Result<string, CdpError>> => {
+  const current = client.current();
+  if (current?.targetId === targetId) return ok(current.sessionId);
+  const attached = await client.session().callBrowser("Target.attachToTarget", { targetId, flatten: true });
+  if (!attached.success) return attached;
+  return ok((attached.data as { sessionId: string }).sessionId);
+};
+
+/**
+ * Spawn a tab from `openerTargetId` via window.open, so it inherits the
+ * opener's profile and window, and return its target id.
+ */
+const spawnTabViaOpener = async (
+  client: BrowserClient,
+  openerTargetId: string,
+): Promise<Result<string, CdpError>> => {
+  const session = await sessionForTarget(client, openerTargetId);
+  if (!session.success) return session;
+
+  const token = `pi-${randomUUID()}`;
+  // userGesture: true is what gets this past the popup blocker.
+  const opened = await client.session().callOnTarget(
+    "Runtime.evaluate",
+    {
+      expression: `!!window.open('about:blank#${token}', '_blank')`,
+      returnByValue: true,
+      userGesture: true,
+    },
+    session.data,
+  );
+  if (!opened.success) return opened;
+  const result = opened.data as { result?: { value?: unknown } };
+  if (result.result?.value !== true) {
+    return err(cdpError(
+      "invalid_response",
+      "the browser blocked window.open in the pinned profile's window — the page may have navigated away; retry, or run /browser-profile to re-seed",
+      "Runtime.evaluate",
+    ));
+  }
+
+  const deadline = Date.now() + SPAWN_DEADLINE_MS;
+  while (Date.now() < deadline) {
+    const targets = await listPageTargets(client);
+    if (targets.success) {
+      const spawned = targets.data.find((t) => t.url.includes(token));
+      if (spawned) return ok(spawned.targetId);
+    }
+    await new Promise((r) => setTimeout(r, SPAWN_POLL_MS));
+  }
+  return err(cdpError("timeout", `the tab opened in the pinned profile did not report back within ${SPAWN_DEADLINE_MS}ms`));
+};
+
+/**
+ * In-flight window creation, per client. Isolated tabs run concurrently
+ * (browser_read_page is registered unserialized), so two of them starting at
+ * once would otherwise each find "no harness window" and create one — two blank
+ * windows before, and two launched profile windows now. Callers share the first
+ * call's result instead.
+ */
+const inFlight = new WeakMap<BrowserClient, Promise<Result<HarnessWindow, CdpError>>>();
+
+/**
+ * The harness window for this session, creating it when absent.
+ *
+ * Reuses a live owned tab when one exists — including after the user closed the
+ * original seed — so reconnects don't scatter windows.
+ */
+export const ensureHarnessWindow = async (client: BrowserClient): Promise<Result<HarnessWindow, CdpError>> => {
+  const pending = inFlight.get(client);
+  if (pending) {
+    const shared = await pending;
+    // `freshlyCreated` is a claim on the seed tab, and only the caller that
+    // started the creation may hold it. Everyone waiting on the same window
+    // must open a tab of their own beside it, or two callers would drive the
+    // very same tab.
+    return shared.success ? ok({ targetId: shared.data.targetId, freshlyCreated: false }) : shared;
+  }
+  const attempt = ensureHarnessWindowUncoordinated(client).finally(() => inFlight.delete(client));
+  inFlight.set(client, attempt);
+  return attempt;
+};
+
+const ensureHarnessWindowUncoordinated = async (
+  client: BrowserClient,
+): Promise<Result<HarnessWindow, CdpError>> => {
+  const targets = await listPageTargets(client);
+  if (!targets.success) return targets;
+  const live = new Set(targets.data.map((t) => t.targetId));
+
+  const ownership = client.ownership();
+  const pinnedCtx = client.profileContextId();
+  // A tab may only be reused when we can prove which profile it is in. With a
+  // pin set but no context resolved yet — a fresh connection, or a browser that
+  // restarted — the recorded tabs cannot be verified, so we seed a new window
+  // rather than risk adopting one from the wrong profile. (Sessions close their
+  // owned tabs on shutdown, so this is the normal, no-cost case.)
+  const canReuse = client.profilePin() === null || pinnedCtx !== undefined;
+  const inPinnedProfile = (targetId: string): boolean => {
+    if (!pinnedCtx) return true;
+    const info = targets.data.find((t) => t.targetId === targetId);
+    return info?.browserContextId === pinnedCtx;
+  };
+
+  if (canReuse) {
+    const harnessWindow = ownership.harnessWindow();
+    if (harnessWindow && live.has(harnessWindow) && inPinnedProfile(harnessWindow)) {
+      return ok({ targetId: harnessWindow, freshlyCreated: false });
+    }
+    const survivor = ownership.list().find((id) => live.has(id) && inPinnedProfile(id));
+    if (survivor) {
+      ownership.setHarnessWindow(survivor);
+      return ok({ targetId: survivor, freshlyCreated: false });
+    }
+  }
+
+  const seeded = client.profilePin()
+    ? await client.seedPinnedProfileWindow()
+    : await createDedicatedWindow(client);
+  if (!seeded.success) return seeded;
+  return ok({ targetId: seeded.data, freshlyCreated: true });
+};
+
+/** Unpinned path: a fresh dedicated window, exactly as the harness always did. */
+const createDedicatedWindow = async (client: BrowserClient): Promise<Result<string, CdpError>> => {
+  const created = await client.session().callBrowser("Target.createTarget", { url: "about:blank", newWindow: true });
+  if (!created.success) return created;
+  const { targetId } = created.data as { targetId: string };
+  const ownership = client.ownership();
+  ownership.setHarnessWindow(targetId);
+  ownership.add(targetId);
+  const win = await client.session().callBrowser("Browser.getWindowForTarget", { targetId });
+  if (win.success) {
+    const windowId = (win.data as { windowId?: number }).windowId;
+    if (typeof windowId === "number") ownership.setHarnessWindowId(windowId);
+  }
+  return ok(targetId);
+};
+
+/**
+ * Open a harness-owned tab beside `openerTargetId`, in the same window and —
+ * when a profile is pinned — the same profile. The tab is registered as owned.
+ */
+export const openHarnessTab = async (
+  client: BrowserClient,
+  openerTargetId: string,
+): Promise<Result<string, CdpError>> => {
+  const spawned = client.profileContextId()
+    ? await spawnTabViaOpener(client, openerTargetId)
+    : await (async (): Promise<Result<string, CdpError>> => {
+        const created = await client.session().callBrowser("Target.createTarget", {
+          url: "about:blank",
+          openerId: openerTargetId,
+        });
+        if (!created.success) return created;
+        return ok((created.data as { targetId: string }).targetId);
+      })();
+  if (!spawned.success) return spawned;
+  client.ownership().add(spawned.data);
+  return ok(spawned.data);
+};