pi-browser-harness 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-browser-harness",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Browser control extension for pi — navigate, click, type, screenshot, and extract data from real Chrome via CDP",
   "keywords": [
     "pi-package",

package/skills/pi-browser-harness/SKILL.md

@@ -54,6 +54,21 @@ connects to Chrome, and opens a test tab. The user sees a single "Allow Remote
 Debugging" prompt the first time. After that, all sessions reuse the same connection.
 `browser_setup` is idempotent — safe to call even when already connected.
 
+## Browser profile
+
+Every harness tab opens in one chosen browser profile, which determines the logins,
+cookies, and extensions you're working with. The user picks it once via
+`/browser-profile`; the choice persists across sessions in `~/.pi/agent/`.
+
+The first `browser_setup` in a fresh install shows that picker, so the tool may pause
+briefly on user input — this is expected, and the result appears in the tool output as
+`Browser profile: <name> (<email>)`.
+
+If setup reports `couldn't open a window in "…" automatically`, the harness could not
+open the pinned profile's window. Tell the user to open that profile from their browser's
+profile menu and retry, or to run `/browser-profile` to choose another. Never work around
+it by opening tabs elsewhere — a different profile means different accounts.
+
 ## Connection
 
 You're attached to the user's real Chrome — never launch your own. If auth is required, stop and ask the user. If `browser_page_info` returns a dialog, handle it first with `browser_handle_dialog`.

package/src/cdp/discovery.ts

@@ -1,61 +1,24 @@
 import { readFile, stat } from "node:fs/promises";
-import { homedir } from "node:os";
 import { join } from "node:path";
 import { connect as netConnect } from "node:net";
 import { request as httpRequest } from "node:http";
 import { type Result, err, ok } from "../util/result";
+import { userDataDirCandidates } from "../profile/paths";
 import { type CdpError, cdpError } from "./errors";
 
 const PORT_PROBE_DEADLINE_MS = 30_000;
 const PORT_PROBE_INTERVAL_MS = 1_000;
 
-const profileDirs = (): ReadonlyArray<string> => {
-  const home = homedir();
-  return [
-    // macOS — Chrome (all channels), Chromium, Brave, Edge
-    join(home, "Library/Application Support/Google/Chrome"),
-    join(home, "Library/Application Support/Google/Chrome Beta"),
-    join(home, "Library/Application Support/Google/Chrome Dev"),
-    join(home, "Library/Application Support/Google/Chrome Canary"),
-    join(home, "Library/Application Support/Chromium"),
-    join(home, "Library/Application Support/BraveSoftware/Brave-Browser"),
-    join(home, "Library/Application Support/BraveSoftware/Brave-Browser-Beta"),
-    join(home, "Library/Application Support/BraveSoftware/Brave-Browser-Nightly"),
-    join(home, "Library/Application Support/BraveSoftware/Brave-Browser-Dev"),
-    join(home, "Library/Application Support/Microsoft Edge"),
-    join(home, "Library/Application Support/Microsoft Edge Beta"),
-    join(home, "Library/Application Support/Microsoft Edge Dev"),
-    join(home, "Library/Application Support/Microsoft Edge Canary"),
-    // Linux — Chrome (all channels), Chromium, Brave, Edge
-    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"),
-    // Linux 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"),
-    // Windows — Chrome, Chromium, Brave, Edge
-    join(home, "AppData/Local/Google/Chrome/User Data"),
-    join(home, "AppData/Local/Google/Chrome Beta/User Data"),
-    join(home, "AppData/Local/Google/Chrome Dev/User Data"),
-    join(home, "AppData/Local/Google/Chrome SxS/User Data"),
-    join(home, "AppData/Local/Chromium/User Data"),
-    join(home, "AppData/Local/BraveSoftware/Brave-Browser/User Data"),
-    join(home, "AppData/Local/BraveSoftware/Brave-Browser-Beta/User Data"),
-    join(home, "AppData/Local/Microsoft/Edge/User Data"),
-    join(home, "AppData/Local/Microsoft/Edge Beta/User Data"),
-    join(home, "AppData/Local/Microsoft/Edge Dev/User Data"),
-    join(home, "AppData/Local/Microsoft/Edge SxS/User Data"),
-  ];
+/**
+ * A live CDP endpoint plus, when discovery went through a DevToolsActivePort
+ * file, the user-data-dir that file lives in. That directory is the browser's
+ * profile registry (`Local State`) — Chromium writes DevToolsActivePort to
+ * chrome::DIR_USER_DATA — so it is what profile selection enumerates.
+ * Undefined when the endpoint came from BU_CDP_WS or a bare port probe.
+ */
+export type CdpEndpoint = {
+  readonly wsUrl: string;
+  readonly userDataDir?: string;
 };
 
 const probePort = (port: number): Promise<Result<void, CdpError>> =>
@@ -144,10 +107,20 @@ const fallbackPorts = (): ReadonlyArray<number> => {
   return Array.from(ports);
 };
 
-type Candidate = { readonly port: number; readonly path: string; readonly mtimeMs: number };
+type Candidate = {
+  readonly port: number;
+  readonly path: string;
+  readonly mtimeMs: number;
+  /** The user-data-dir whose DevToolsActivePort produced this candidate. */
+  readonly userDataDir: string;
+};
 
-export const discoverWsUrl = async (): Promise<Result<string, CdpError>> => {
-  const dirs = profileDirs();
+/**
+ * Locate a live CDP endpoint, reporting the user-data-dir it belongs to when
+ * that is knowable. `discoverWsUrl` is the URL-only view of the same walk.
+ */
+export const discoverEndpoint = async (): Promise<Result<CdpEndpoint, CdpError>> => {
+  const dirs = userDataDirCandidates();
 
   // Phase 1: collect every readable DevToolsActivePort candidate up front,
   // rather than committing to the first one found. A single browser writes one
@@ -190,7 +163,7 @@ export const discoverWsUrl = async (): Promise<Result<string, CdpError>> => {
     // a Result error. Skip such entries.
     const portNum = Number(port);
     if (!Number.isInteger(portNum) || portNum <= 0 || portNum >= 65536) continue;
-    candidates.push({ port: portNum, path, mtimeMs });
+    candidates.push({ port: portNum, path, mtimeMs, userDataDir: base });
   }
 
   // Phase 2: no readable candidate — probe well-known ports directly. Covers
@@ -201,7 +174,9 @@ export const discoverWsUrl = async (): Promise<Result<string, CdpError>> => {
     for (const port of fallbackPorts()) {
       if (!(await isPortLive(port))) continue;
       const live = await queryLiveWsUrl(port);
-      if (live) return ok(live);
+      // No DevToolsActivePort file was involved, so the user-data-dir behind
+      // this endpoint is unknown — profile selection stays unavailable.
+      if (live) return ok({ wsUrl: live });
     }
     const permHint = readErrors.length > 0
       ? `\n\nDevToolsActivePort reads were denied (${readErrors.join(", ")}); if you're running in a sandbox, grant read access to those files or set BU_CDP_WS / BU_CDP_PORTS to bypass file discovery.`
@@ -232,7 +207,7 @@ export const discoverWsUrl = async (): Promise<Result<string, CdpError>> => {
   // /json/version. Some browsers disable that HTTP endpoint when remote
   // debugging is toggled only via chrome://inspect (rather than a launch flag),
   // so fall back to the WS path written in DevToolsActivePort.
-  let lastErr: Result<string, CdpError> | null = null;
+  let lastErr: Result<CdpEndpoint, CdpError> | null = null;
   for (const c of ordered) {
     const ready = await waitForPort(c.port);
     if (!ready.success) {
@@ -240,7 +215,7 @@ export const discoverWsUrl = async (): Promise<Result<string, CdpError>> => {
       continue;
     }
     const liveUrl = await queryLiveWsUrl(c.port);
-    return ok(liveUrl ?? `ws://127.0.0.1:${c.port}${c.path}`);
+    return ok({ wsUrl: liveUrl ?? `ws://127.0.0.1:${c.port}${c.path}`, userDataDir: c.userDataDir });
   }
 
   // Every discovered candidate was stale/unreachable. Before giving up, try the
@@ -250,8 +225,17 @@ export const discoverWsUrl = async (): Promise<Result<string, CdpError>> => {
   for (const port of fallbackPorts()) {
     if (byPort.has(port) || !(await isPortLive(port))) continue;
     const liveUrl = await queryLiveWsUrl(port);
-    if (liveUrl) return ok(liveUrl);
+    if (liveUrl) return ok({ wsUrl: liveUrl });
   }
 
   return lastErr ?? err(cdpError("discovery_failed", "no live DevTools endpoint among discovered candidates"));
 };
+
+/**
+ * URL-only view of {@link discoverEndpoint}, kept as the stable entry point for
+ * callers that don't care which user-data-dir answered.
+ */
+export const discoverWsUrl = async (): Promise<Result<string, CdpError>> => {
+  const endpoint = await discoverEndpoint();
+  return endpoint.success ? ok(endpoint.data.wsUrl) : endpoint;
+};

package/src/cdp/session.ts

@@ -45,9 +45,21 @@ export type CdpSession = {
   drainConsoleBuffer(filter: ConsoleFilter): ConsoleDrainResult;
 };
 
+/**
+ * Supplies the seed tab when attachFirstPage finds no owned tab to attach to.
+ * Injected by the client so that seeding goes through the target factory —
+ * which, with a profile pinned, opens the window inside that profile. Without
+ * it, attachFirstPage's own `Target.createTarget` would land in whichever
+ * profile currently has focus.
+ *
+ * The provider is responsible for its own ownership bookkeeping.
+ */
+export type SeedTargetProvider = () => Promise<Result<string, CdpError>>;
+
 export const createCdpSession = (
   transport: CdpTransport,
   ownership?: OwnershipRegistry,
+  createSeedTarget?: SeedTargetProvider,
 ): CdpSession => {
   let sessionId: string | null = null;
   let targetId: string | null = null;
@@ -246,6 +258,13 @@ export const createCdpSession = (
         const ownedLive = ownership.list().filter((id) => allPages.some((p) => p.targetId === id));
         pickTargetId = ownedLive[0];
       }
+      if (!pickTargetId && createSeedTarget) {
+        // Delegated seeding (see SeedTargetProvider): the provider creates the
+        // window in the right profile and records ownership itself.
+        const seeded = await createSeedTarget();
+        if (!seeded.success) return seeded;
+        pickTargetId = seeded.data;
+      }
       if (!pickTargetId) {
         const createParams: Record<string, unknown> = { url: "about:blank" };
         if (ownership) createParams["newWindow"] = true;

package/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);
+};

package/src/client.ts

@@ -1,12 +1,15 @@
 import { type Result, err, ok } from "./util/result";
 import { safeJs } from "./util/js-template";
 import { type Mutex, createMutex } from "./util/mutex";
-import { discoverWsUrl } from "./cdp/discovery";
+import { discoverEndpoint } from "./cdp/discovery";
 import { type CdpError, cdpError } from "./cdp/errors";
 import type { CdpTransport } from "./cdp/transport";
 import { createCdpTransport } from "./cdp/transport";
 import { type CdpSession, createCdpSession } from "./cdp/session";
 import { type OwnershipRegistry, createOwnershipRegistry } from "./cdp/ownership";
+import { ensureHarnessWindow, openHarnessTab } from "./cdp/target-factory";
+import { seedProfileWindow } from "./profile/bind";
+import type { ProfilePin } from "./profile/store";
 import type { DaemonStatus, DialogInfo, PageInfo, TabInfo } from "./cdp/types";
 
 export type BrowserClientOptions = {
@@ -18,6 +21,8 @@ export type BrowserClientOptions = {
     readonly harnessWindowTargetId?: string;
     readonly harnessWindowId?: number;
   };
+  /** Profile to pin this session to, loaded from the durable pin store. */
+  readonly profilePin?: ProfilePin | null;
   readonly onOwnershipChange?: (snapshot: {
     readonly ownedTargetIds: ReadonlyArray<string>;
     readonly harnessWindowTargetId: string | undefined;
@@ -49,6 +54,19 @@ export type BrowserClient = {
   current(): { readonly sessionId: string; readonly targetId: string } | null;
   session(): CdpSession;
   transport(): CdpTransport;
+  /** User-data-dir of the connected browser, when discovery could determine it.
+   *  Undefined for BU_CDP_WS / bare-port connections, where profile selection
+   *  is unavailable. */
+  userDataDir(): string | undefined;
+  /** The profile this session is pinned to, or null when unpinned. */
+  profilePin(): ProfilePin | null;
+  setProfilePin(pin: ProfilePin | null): void;
+  /** browserContextId of the pinned profile, once a window has identified it.
+   *  Session-scoped: Chrome re-mints context ids on every browser run. */
+  profileContextId(): string | undefined;
+  setProfileContextId(contextId: string | undefined): void;
+  /** Open and adopt a window inside the pinned profile. Returns its seed tab. */
+  seedPinnedProfileWindow(): Promise<Result<string, CdpError>>;
   /** Returns the shared async mutex that serialized browser tools must acquire
    *  before performing mutations. Observation tools should not use this. */
   mutationMutex(): Mutex;
@@ -108,11 +126,33 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
       });
     });
   }
-  const session = createCdpSession(transport, ownership);
+  // The seed provider routes attachFirstPage's fallback through the target
+  // factory, so a pinned profile is honoured on every path that can create the
+  // harness window.
+  const session = createCdpSession(transport, ownership, async () => {
+    const window = await ensureHarnessWindow(api);
+    return window.success ? ok(window.data.targetId) : window;
+  });
   const mutationMutex = createMutex();
   let lastHealth = 0;
   let pageCaches = new Map<string, { readonly info: PageInfo; readonly at: number }>();
   let remote: BrowserClientOptions["remote"] | null = opts.remote ?? null;
+  let userDataDir: string | undefined;
+  let profilePin: ProfilePin | null = opts.profilePin ?? null;
+  let profileContextId: string | undefined;
+
+  /**
+   * With a profile pinned, the harness window must exist BEFORE anything
+   * attaches: session.attachFirstPage() would otherwise fall back to a bare
+   * Target.createTarget, which lands in the focus-derived default profile.
+   * Seeding first means attachFirstPage always finds an owned tab to attach to.
+   */
+  const seedIfPinned = async (): Promise<Result<void, CdpError>> => {
+    if (!profilePin) return ok(undefined);
+    const window = await ensureHarnessWindow(api);
+    if (!window.success) return window;
+    return ok(undefined);
+  };
 
   const start = async (): Promise<Result<void, CdpError>> => {
     if (transport.state() === "open" && session.current()) return ok(undefined);
@@ -123,15 +163,23 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
     } else if (envUrl) {
       wsUrl = envUrl;
     } else {
-      const discovered = await discoverWsUrl();
+      const discovered = await discoverEndpoint();
       if (!discovered.success) return discovered;
-      wsUrl = discovered.data;
+      wsUrl = discovered.data.wsUrl;
+      userDataDir = discovered.data.userDataDir;
     }
     const connected = await transport.connect(wsUrl, { timeoutMs: 10_000 });
     if (!connected.success) return connected;
     if (!remote) {
       remote = { cdpUrl: wsUrl, browserId: wsUrl.split("/").pop() ?? "unknown" };
     }
+    // A fresh browser run invalidates any context id resolved earlier.
+    profileContextId = undefined;
+    const seeded = await seedIfPinned();
+    if (!seeded.success) {
+      await transport.close();
+      return seeded;
+    }
     const attached = await session.attachFirstPage();
     if (!attached.success) {
       await transport.close();
@@ -166,6 +214,10 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
       expression: "1", returnByValue: true,
     }, { timeoutMs: 2_000 });
     if (!jsProbe.success && jsProbe.error.kind === "session_not_found") {
+      // Re-seed first when pinned: if the user closed every harness tab,
+      // attachFirstPage would mint a window in the focus-derived profile.
+      const seeded = await seedIfPinned();
+      if (!seeded.success) return seeded;
       const reattached = await session.attachFirstPage();
       if (reattached.success) {
         pageCaches.clear();
@@ -265,60 +317,34 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
     return ok(undefined);
   };
 
-  // Ask Chrome for the real windowId hosting a target. Undefined on failure —
-  // callers treat the window binding as best-effort.
-  const getWindowId = async (targetId: string): Promise<number | undefined> => {
-    const r = await session.callBrowser("Browser.getWindowForTarget", { targetId });
-    if (!r.success) return undefined;
-    const wid = (r.data as { windowId?: number }).windowId;
-    return typeof wid === "number" ? wid : undefined;
-  };
-
   const newTab = async (url?: string): Promise<Result<string, CdpError>> => {
-    // Verify the recorded harness window still exists. Querying the live
-    // target list also gives listTabs's reconciliation a chance to run.
+    // Reconcile ownership against live targets before deciding where to open.
     const tabsResult = await listTabs(true);
     if (!tabsResult.success) return tabsResult;
-    const live = new Set(tabsResult.data.map((t) => t.targetId));
-    const hw = ownership.harnessWindow();
-    // Pick an opener that keeps us inside the harness window. Prefer the seed
-    // tab; if the user closed it but other owned tabs survive, reuse one of
-    // those instead of spawning a second window (avoids window scatter).
-    const opener = hw && live.has(hw)
-      ? hw
-      : ownership.list().find((id) => live.has(id));
 
-    const params: Record<string, unknown> = { url: "about:blank" };
-    if (opener) {
-      // Open as a child of an owned tab — Chrome places it in the same window,
-      // giving us visual grouping for free and keeping the session single-window.
-      params["openerId"] = opener;
+    // ensureHarnessWindow reuses the seed tab, falls back to any surviving
+    // owned tab, and only then creates a window — which, when a profile is
+    // pinned, means launching one inside that profile.
+    const window = await ensureHarnessWindow(api);
+    if (!window.success) return window;
+    // A freshly created window IS the new tab; opening another would leave a
+    // stray blank tab behind.
+    let tabId: string;
+    if (window.data.freshlyCreated) {
+      tabId = window.data.targetId;
     } else {
-      // Fresh session, or the whole harness window was closed by the user.
-      // Spawn a new dedicated window and rebind to it.
-      params["newWindow"] = true;
+      const opened = await openHarnessTab(api, window.data.targetId);
+      if (!opened.success) return opened;
+      tabId = opened.data;
     }
-    const created = await session.callBrowser("Target.createTarget", params);
-    if (!created.success) return created;
-    const c = created.data as { targetId: string };
 
-    if (params["newWindow"]) {
-      ownership.setHarnessWindow(c.targetId);
-      const wid = await getWindowId(c.targetId);
-      if (wid !== undefined) ownership.setHarnessWindowId(wid);
-    } else if (opener && opener !== hw) {
-      // Re-seeded onto a surviving owned tab; keep the seed pointer live.
-      ownership.setHarnessWindow(opener);
-    }
-    ownership.add(c.targetId);
-
-    const switched = await switchTab(c.targetId);
+    const switched = await switchTab(tabId);
     if (!switched.success) return switched;
     if (url && url !== "about:blank") {
       const nav = await session.call("Page.navigate", { url });
       if (!nav.success) return nav;
     }
-    return ok(c.targetId);
+    return ok(tabId);
   };
 
   const closeTab = async (targetId: string): Promise<Result<void, CdpError>> => {
@@ -357,7 +383,7 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
     await transport.request("Target.detachFromTarget", { sessionId: cur.sessionId }, { sessionId: null });
   };
 
-  return {
+  const api: BrowserClient = {
     namespace: opts.namespace,
     ensureAlive, status, start, stop, detach, closeOwnedTabs,
     evaluateJs, pageInfo,
@@ -368,6 +394,24 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
     current: () => session.current(),
     session: () => session,
     transport: () => transport,
+    userDataDir: () => userDataDir,
+    profilePin: () => profilePin,
+    setProfilePin: (pin) => {
+      profilePin = pin;
+      // The old profile's context no longer describes where tabs should go.
+      profileContextId = undefined;
+    },
+    profileContextId: () => profileContextId,
+    setProfileContextId: (contextId) => {
+      profileContextId = contextId;
+    },
+    seedPinnedProfileWindow: async () => {
+      if (!profilePin) {
+        return err(cdpError("discovery_failed", "no browser profile is selected — run /browser-profile"));
+      }
+      return seedProfileWindow(api, profilePin);
+    },
     mutationMutex: () => mutationMutex,
   };
+  return api;
 };