pi-browser-harness 0.8.3 → 0.10.0

package/src/profile/bind.ts

@@ -0,0 +1,138 @@
+/**
+ * Binding the harness session to a pinned profile.
+ *
+ * Sequence, all of it verified against a live browser:
+ *   1. resolve the browser binary and any explicit --user-data-dir
+ *   2. launch a window into the profile, marked with a file:// sentinel
+ *   3. poll Target.getTargets for the sentinel page — its browserContextId IS
+ *      the profile's context, which is otherwise undiscoverable (CDP exposes no
+ *      profile identity)
+ *   4. adopt that page as the harness window, blank it, drop the sentinel file
+ *
+ * If the sentinel never appears the bind FAILS LOUDLY. Falling through to a
+ * normal createTarget would put the agent in the focus-derived default profile
+ * — the exact bug this feature exists to remove — so the caller gets an
+ * actionable error instead.
+ *
+ * The resolved context id is session-scoped state, never persisted: Chrome
+ * mints new context ids on every browser run.
+ */
+
+import type { BrowserClient } from "../client";
+import { type CdpError, cdpError } from "../cdp/errors";
+import { type Result, err, ok } from "../util/result";
+import { detectRunningBrowser, resolveBrowserExecutable } from "./browser-process";
+import { openProfileWindow } from "./launch";
+import type { ProfilePin } from "./store";
+
+/** The launch delegates through ProcessSingleton, so allow for a cold profile. */
+const SEED_DEADLINE_MS = 15_000;
+const SEED_POLL_MS = 500;
+
+type PageTarget = {
+  readonly targetId: string;
+  readonly type: string;
+  readonly url: string;
+  readonly browserContextId?: string;
+};
+
+const pageTargets = async (client: BrowserClient): Promise<ReadonlyArray<PageTarget>> => {
+  const r = await client.session().callBrowser("Target.getTargets");
+  if (!r.success) return [];
+  const data = r.data as { targetInfos: ReadonlyArray<PageTarget> };
+  return data.targetInfos.filter((t) => t.type === "page");
+};
+
+const manualFallbackHint = (pin: ProfilePin): string =>
+  `open a window for "${pin.label}" yourself (browser profile menu → ${pin.profileDir}), then retry. ` +
+  `Run /browser-profile to pick a different profile, or clear the selection to use whichever window is focused.`;
+
+/**
+ * Open (and adopt) a harness window inside the pinned profile. Returns the
+ * seed tab's target id.
+ */
+export const seedProfileWindow = async (
+  client: BrowserClient,
+  pin: ProfilePin,
+): Promise<Result<string, CdpError>> => {
+  // A pin belongs to one user-data-dir. If the harness is now attached to a
+  // different browser, silently seeding the "same" profile name would be wrong.
+  const connectedDir = client.userDataDir();
+  if (connectedDir && connectedDir !== pin.userDataDir) {
+    return err(cdpError(
+      "discovery_failed",
+      `the selected profile "${pin.label}" belongs to ${pin.userDataDir}, but the harness is connected to ${connectedDir}. ` +
+      `Run /browser-profile to choose a profile in the browser you're using.`,
+    ));
+  }
+
+  // Identify the browser by the dir we're connected to. With several Chromium
+  // browsers running, launching into the wrong one would open a window the
+  // harness cannot see — in a browser the user never pointed us at.
+  const targetUserDataDir = connectedDir ?? pin.userDataDir;
+  const running = await detectRunningBrowser(targetUserDataDir);
+  const exePath = await resolveBrowserExecutable(running);
+  if (!exePath) {
+    return err(cdpError(
+      "discovery_failed",
+      `could not locate the browser executable needed to open "${pin.label}" — ${manualFallbackHint(pin)}`,
+    ));
+  }
+
+  const launched = await openProfileWindow({
+    exePath,
+    profileDir: pin.profileDir,
+    // Forward the user-data-dir ONLY when the running browser advertises one.
+    // ProcessSingleton keys on this path: passing the value the target process
+    // itself reports guarantees delegation, whereas supplying a default dir we
+    // reconstructed could differ by case or normalisation and start a SECOND
+    // browser instead.
+    ...(running.explicitUserDataDir ? { explicitUserDataDir: running.explicitUserDataDir } : {}),
+  });
+  if (!launched.success) {
+    return err(cdpError("discovery_failed", `${launched.error} — ${manualFallbackHint(pin)}`));
+  }
+
+  const { sentinelUrl, cleanup } = launched.data;
+  const deadline = Date.now() + SEED_DEADLINE_MS;
+  let seed: PageTarget | undefined;
+  while (Date.now() < deadline && !seed) {
+    await new Promise((r) => setTimeout(r, SEED_POLL_MS));
+    seed = (await pageTargets(client)).find((t) => t.url === sentinelUrl);
+  }
+
+  if (!seed) {
+    await cleanup();
+    return err(cdpError(
+      "timeout",
+      `couldn't open a window in "${pin.label}" automatically — ${manualFallbackHint(pin)}`,
+    ));
+  }
+
+  // The sentinel's context is the profile's context — the only way to learn it.
+  if (seed.browserContextId) client.setProfileContextId(seed.browserContextId);
+
+  const ownership = client.ownership();
+  ownership.setHarnessWindow(seed.targetId);
+  ownership.add(seed.targetId);
+  const win = await client.session().callBrowser("Browser.getWindowForTarget", { targetId: seed.targetId });
+  if (win.success) {
+    const windowId = (win.data as { windowId?: number }).windowId;
+    if (typeof windowId === "number") ownership.setHarnessWindowId(windowId);
+  }
+
+  // Blank the handshake page so the seed tab behaves like any other fresh tab,
+  // then remove the sentinel file. Best-effort: a failure here costs nothing
+  // beyond the placeholder page staying visible.
+  const attached = await client.session().callBrowser("Target.attachToTarget", {
+    targetId: seed.targetId,
+    flatten: true,
+  });
+  if (attached.success) {
+    const sessionId = (attached.data as { sessionId: string }).sessionId;
+    await client.session().callOnTarget("Page.navigate", { url: "about:blank" }, sessionId);
+  }
+  await cleanup();
+
+  return ok(seed.targetId);
+};

package/src/profile/browser-process.ts

@@ -0,0 +1,371 @@
+/**
+ * Identifying the browser process the harness is attached to.
+ *
+ * Two questions, deliberately kept apart:
+ *
+ *   1. Is a Chromium-family browser RUNNING? (`detectRunningBrowser().running`)
+ *      Only live-process evidence may answer this — an installed-but-closed
+ *      browser must read as "not running", which is why the registry lookup
+ *      below is never consulted here.
+ *
+ *   2. Which binary do we invoke to open a window for a chosen profile?
+ *      (`resolveBrowserExecutable()`) Chromium's ProcessSingleton hands a second
+ *      launch's argv to the already-running browser instead of starting another
+ *      one — Windows via WM_COPYDATA (process_singleton_win.cc), Linux and macOS
+ *      via the socket in the user-data-dir (process_singleton_posix.cc, which is
+ *      compiled on macOS too). Here an installed path is a fine fallback.
+ *
+ * Whether the running browser carries an explicit `--user-data-dir` matters:
+ * ProcessSingleton keys on that directory, so passing a path that differs from
+ * the running browser's by case or normalisation would start a SECOND browser
+ * rather than delegating. The flag is forwarded only when the running process
+ * already has one.
+ *
+ * Every probe is best-effort; when nothing can be determined, profile launching
+ * degrades to a clear message rather than guessing.
+ *
+ * Windows note: `wmic` is deliberately unused — Microsoft removed it by default
+ * in Windows 11 24H2 and entirely in 25H2. PowerShell CIM is the supported
+ * replacement, with `tasklist` for liveness and the documented App Paths
+ * registry key for install location.
+ */
+
+import { execFile } from "node:child_process";
+import { access, readFile, readlink } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { browserNameForUserDataDir } from "./paths";
+
+// execFile, not exec: arguments are passed as an array, with no shell involved.
+const run = promisify(execFile);
+const EXEC_TIMEOUT_MS = 5_000;
+
+export type RunningBrowser = {
+  /** True when a Chromium-family browser process is live. */
+  readonly running: boolean;
+  /** Absolute path to the running browser's binary, when determinable. */
+  readonly exePath?: string;
+  /** Value of an explicit --user-data-dir on the running process, if any. */
+  readonly explicitUserDataDir?: string;
+};
+
+/** Chromium-family process names, lowercase, as they appear per platform. */
+const LINUX_COMMS: ReadonlyArray<string> = [
+  "chrome", "chromium", "chromium-browser", "msedge", "microsoft-edge",
+  "google-chrome", "brave", "brave-browser",
+];
+const MAC_BROWSER_NAMES: ReadonlyArray<string> = [
+  "google chrome", "chromium", "microsoft edge", "brave browser",
+];
+const WIN_IMAGE_NAMES: ReadonlyArray<string> = ["chrome.exe", "msedge.exe", "brave.exe"];
+
+/**
+ * Chromium tags every child process with `--type=<role>`; only the browser
+ * process omits it or carries `--type=browser`. Matching the flag (rather than
+ * words like "renderer" anywhere in the string) keeps a user whose install path
+ * contains such a word from being filtered out.
+ */
+const hasChildProcessType = (commandLine: string): boolean => {
+  const lower = commandLine.toLowerCase();
+  return lower.includes("--type=") && !lower.includes("--type=browser");
+};
+
+/**
+ * macOS names its child processes in the executable path itself ("Google Chrome
+ * Helper (Renderer)", crashpad, updaters), so the process NAME must be filtered
+ * too — the same exclusions the previous setup.ts check applied.
+ */
+const isMacChildProcessName = (comm: string): boolean => {
+  const lower = comm.toLowerCase();
+  return (
+    lower.includes("helper") ||
+    lower.includes("renderer") ||
+    lower.includes("crashpad") ||
+    lower.includes(" gpu") ||
+    lower.includes("updater")
+  );
+};
+
+/** One running browser process, as much as the platform will tell us. */
+export type BrowserCandidate = {
+  readonly exePath?: string;
+  readonly explicitUserDataDir?: string;
+};
+
+/** Path comparison that tolerates separator and case differences per platform. */
+const samePath = (a: string, b: string): boolean => {
+  const norm = (p: string): string => {
+    const unified = p.replace(/\\/g, "/").replace(/\/+$/, "");
+    return process.platform === "linux" ? unified : unified.toLowerCase();
+  };
+  return norm(a) === norm(b);
+};
+
+/**
+ * Rank a candidate against the user-data-dir the harness is actually connected
+ * to. Several Chromium browsers can run at once (Chrome plus Brave, or a second
+ * instance on a custom dir), and launching a profile window into the wrong one
+ * would open a window the harness cannot see — while disturbing a browser the
+ * user never pointed us at.
+ */
+export const rankBrowserCandidate = (candidate: BrowserCandidate, preferUserDataDir?: string): number => {
+  if (!preferUserDataDir) return 1;
+  if (candidate.explicitUserDataDir) {
+    // An explicit dir is decisive in both directions: exact match wins, and a
+    // different one means this is definitively another browser instance.
+    return samePath(candidate.explicitUserDataDir, preferUserDataDir) ? 4 : 0;
+  }
+  // No flag: the process uses its default dir. Prefer the one whose executable
+  // belongs to the same browser family as the target directory.
+  const family = browserNameForUserDataDir(preferUserDataDir).toLowerCase();
+  const exe = (candidate.exePath ?? "").toLowerCase();
+  if (!exe) return 1;
+  if (family === "brave" && exe.includes("brave")) return 3;
+  if (family === "edge" && (exe.includes("edge") || exe.includes("msedge"))) return 3;
+  if (family === "chromium" && exe.includes("chromium")) return 3;
+  if (family === "chrome" && exe.includes("chrome") && !exe.includes("chromium")) return 3;
+  return 1;
+};
+
+/** Extract `--user-data-dir=<path>` from a command line, quoted or bare. */
+export const parseUserDataDirFlag = (commandLine: string): string | undefined => {
+  const match = /--user-data-dir=(?:"([^"]*)"|'([^']*)'|(\S+))/.exec(commandLine);
+  if (!match) return undefined;
+  const value = match[1] ?? match[2] ?? match[3];
+  return value && value.length > 0 ? value : undefined;
+};
+
+// ── Linux ──────────────────────────────────────────────────────────────────
+
+const collectLinux = async (): Promise<ReadonlyArray<BrowserCandidate>> => {
+  let pids: string[];
+  try {
+    const { stdout } = await run("ps", ["-A", "-o", "pid=,comm="], { timeout: EXEC_TIMEOUT_MS });
+    pids = stdout
+      .split("\n")
+      .map((line) => line.trim())
+      .flatMap((line) => {
+        const [pid, comm] = line.split(/\s+/, 2);
+        if (!pid || !comm) return [];
+        return LINUX_COMMS.includes(comm.toLowerCase()) ? [pid] : [];
+      });
+  } catch {
+    return [];
+  }
+
+  const candidates: BrowserCandidate[] = [];
+  for (const pid of pids) {
+    let cmdline: string;
+    try {
+      // /proc/<pid>/cmdline is NUL-separated argv.
+      cmdline = (await readFile(`/proc/${pid}/cmdline`, "utf8")).replace(/\0/g, " ").trim();
+    } catch {
+      continue;
+    }
+    if (!cmdline || hasChildProcessType(cmdline)) continue;
+    let exePath: string | undefined;
+    try {
+      exePath = await readlink(`/proc/${pid}/exe`);
+    } catch {
+      // /proc/<pid>/exe is unreadable for processes we don't own; argv[0] is
+      // the next best thing.
+      exePath = cmdline.split(" ")[0];
+    }
+    const explicit = parseUserDataDirFlag(cmdline);
+    candidates.push({
+      ...(exePath ? { exePath } : {}),
+      ...(explicit ? { explicitUserDataDir: explicit } : {}),
+    });
+  }
+  return candidates;
+};
+
+// ── macOS ──────────────────────────────────────────────────────────────────
+
+const collectDarwin = async (): Promise<ReadonlyArray<BrowserCandidate>> => {
+  let lines: string[];
+  try {
+    // BSD ps prints the full executable path for `comm`, unlike Linux.
+    const { stdout } = await run("ps", ["-A", "-ww", "-o", "pid=,comm="], { timeout: EXEC_TIMEOUT_MS });
+    lines = stdout.split("\n").map((l) => l.trim()).filter(Boolean);
+  } catch {
+    return [];
+  }
+
+  const candidates: BrowserCandidate[] = [];
+  for (const line of lines) {
+    const spaceAt = line.indexOf(" ");
+    if (spaceAt < 0) continue;
+    const pid = line.slice(0, spaceAt);
+    const comm = line.slice(spaceAt + 1).trim();
+    const lower = comm.toLowerCase();
+    if (!MAC_BROWSER_NAMES.some((name) => lower.includes(name))) continue;
+    if (isMacChildProcessName(comm)) continue;
+
+    let args = "";
+    try {
+      const { stdout } = await run("ps", ["-ww", "-o", "args=", "-p", pid], { timeout: EXEC_TIMEOUT_MS });
+      args = stdout.trim();
+    } catch {
+      // args are optional — only the --user-data-dir probe needs them
+    }
+    if (args && hasChildProcessType(args)) continue;
+    const explicit = args ? parseUserDataDirFlag(args) : undefined;
+    candidates.push({
+      exePath: comm,
+      ...(explicit ? { explicitUserDataDir: explicit } : {}),
+    });
+  }
+  return candidates;
+};
+
+// ── Windows ────────────────────────────────────────────────────────────────
+
+const POWERSHELL_QUERY = [
+  "$ErrorActionPreference='SilentlyContinue';",
+  "Get-CimInstance Win32_Process",
+  "-Filter \"Name='chrome.exe' or Name='msedge.exe' or Name='brave.exe'\"",
+  "| Select-Object ExecutablePath,CommandLine",
+  "| ConvertTo-Json -Compress",
+].join(" ");
+
+type WinProcess = { ExecutablePath?: string | null; CommandLine?: string | null };
+
+const collectWin32 = async (): Promise<ReadonlyArray<BrowserCandidate>> => {
+  try {
+    const { stdout } = await run(
+      "powershell.exe",
+      ["-NoProfile", "-NonInteractive", "-Command", POWERSHELL_QUERY],
+      { timeout: EXEC_TIMEOUT_MS, windowsHide: true },
+    );
+    const trimmed = stdout.trim();
+    if (trimmed) {
+      const parsed: unknown = JSON.parse(trimmed);
+      // ConvertTo-Json emits an object for a single row, an array for many.
+      const rows: WinProcess[] = Array.isArray(parsed) ? (parsed as WinProcess[]) : [parsed as WinProcess];
+      const candidates = rows
+        .filter((row) => !hasChildProcessType(row.CommandLine ?? ""))
+        .map((row): BrowserCandidate => {
+          const explicit = parseUserDataDirFlag(row.CommandLine ?? "");
+          return {
+            ...(row.ExecutablePath ? { exePath: row.ExecutablePath } : {}),
+            ...(explicit ? { explicitUserDataDir: explicit } : {}),
+          };
+        });
+      if (candidates.length > 0) return candidates;
+    }
+  } catch {
+    // PowerShell missing or blocked by policy — fall through to tasklist.
+  }
+
+  // Liveness-only fallback: tasklist still ships on every supported Windows.
+  // It reveals no path, so the candidate is a bare "something is running".
+  try {
+    const { stdout } = await run("tasklist.exe", [], { timeout: EXEC_TIMEOUT_MS, windowsHide: true });
+    const lower = stdout.toLowerCase();
+    if (WIN_IMAGE_NAMES.some((n) => lower.includes(n))) return [{}];
+  } catch {
+    // best-effort
+  }
+  return [];
+};
+
+/** Installed-browser locations to try when the live process reveals no path. */
+const winInstallCandidates = (): ReadonlyArray<string> => {
+  const roots = [
+    process.env["PROGRAMFILES"],
+    process.env["PROGRAMFILES(X86)"],
+    process.env["LOCALAPPDATA"],
+  ].filter((r): r is string => typeof r === "string" && r.length > 0);
+  const suffixes = [
+    "Google\\Chrome\\Application\\chrome.exe",
+    "Google\\Chrome Beta\\Application\\chrome.exe",
+    "Google\\Chrome SxS\\Application\\chrome.exe",
+    "Chromium\\Application\\chrome.exe",
+    "BraveSoftware\\Brave-Browser\\Application\\brave.exe",
+    "Microsoft\\Edge\\Application\\msedge.exe",
+  ];
+  return roots.flatMap((root) => suffixes.map((suffix) => join(root, suffix)));
+};
+
+/** Query the Shell's App Paths registration for a browser's install location. */
+const winRegistryExecutable = async (): Promise<string | undefined> => {
+  for (const image of WIN_IMAGE_NAMES) {
+    for (const hive of ["HKLM", "HKCU"]) {
+      try {
+        const { stdout } = await run(
+          "reg.exe",
+          ["query", `${hive}\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\App Paths\\${image}`, "/ve"],
+          { timeout: EXEC_TIMEOUT_MS, windowsHide: true },
+        );
+        const match = /REG_[A-Z_]+\s+(.+)$/m.exec(stdout.trim());
+        const path = match?.[1]?.trim();
+        if (path) return path;
+      } catch {
+        // key absent for this browser/hive — try the next
+      }
+    }
+  }
+  return undefined;
+};
+
+// ── Public API ─────────────────────────────────────────────────────────────
+
+/**
+ * Live-process facts about the running Chromium-family browser. `running` is
+ * derived only from process evidence, never from an install location.
+ *
+ * `preferUserDataDir` should be the dir the harness is connected to; with more
+ * than one browser running it decides which process is described.
+ */
+export const detectRunningBrowser = async (preferUserDataDir?: string): Promise<RunningBrowser> => {
+  const candidates =
+    process.platform === "darwin"
+      ? await collectDarwin()
+      : process.platform === "win32"
+        ? await collectWin32()
+        : await collectLinux();
+  if (candidates.length === 0) return { running: false };
+
+  let best = candidates[0] as BrowserCandidate;
+  let bestRank = rankBrowserCandidate(best, preferUserDataDir);
+  for (const candidate of candidates.slice(1)) {
+    const rank = rankBrowserCandidate(candidate, preferUserDataDir);
+    if (rank > bestRank) {
+      best = candidate;
+      bestRank = rank;
+    }
+  }
+
+  return {
+    running: true,
+    ...(best.exePath ? { exePath: best.exePath } : {}),
+    ...(best.explicitUserDataDir ? { explicitUserDataDir: best.explicitUserDataDir } : {}),
+  };
+};
+
+/** True when a Chromium-family browser process is running. */
+export const isBrowserRunning = async (): Promise<boolean> => (await detectRunningBrowser()).running;
+
+/**
+ * The binary to invoke when opening a window for a chosen profile: the running
+ * browser's own executable when known, otherwise a documented install location.
+ * Undefined when nothing usable is found.
+ */
+export const resolveBrowserExecutable = async (running?: RunningBrowser): Promise<string | undefined> => {
+  const detected = running ?? (await detectRunningBrowser());
+  if (detected.exePath) return detected.exePath;
+  if (process.platform !== "win32") return undefined;
+
+  const fromRegistry = await winRegistryExecutable();
+  if (fromRegistry) return fromRegistry;
+  for (const candidate of winInstallCandidates()) {
+    try {
+      await access(candidate);
+      return candidate;
+    } catch {
+      // not installed here
+    }
+  }
+  return undefined;
+};

package/src/profile/command.ts

@@ -0,0 +1,168 @@
+/**
+ * /browser-profile — choose which browser profile the agent works in.
+ *
+ * The selection is durable (see store.ts) and applies immediately: the current
+ * harness tabs are closed and a new window is opened in the chosen profile, so
+ * the agent's next action happens where the user just asked for it rather than
+ * one session later.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { BrowserClient } from "../client";
+import { discoverEndpoint } from "../cdp/discovery";
+import { type Result, err, ok } from "../util/result";
+import { type BrowserProfile, listProfiles } from "./list";
+import { browserNameForUserDataDir, userDataDirCandidates } from "./paths";
+import { pinFor, promptForProfile } from "./picker";
+import { clearPin, readPin, writePin } from "./store";
+
+/**
+ * Which user-data-dir the picker should enumerate: the connected browser's
+ * when known, otherwise a running browser's, otherwise the only installed one
+ * that actually has profiles.
+ */
+export const resolveUserDataDir = async (client: BrowserClient): Promise<Result<string, string>> => {
+  const connected = client.userDataDir();
+  if (connected) return ok(connected);
+
+  const endpoint = await discoverEndpoint();
+  if (endpoint.success && endpoint.data.userDataDir) return ok(endpoint.data.userDataDir);
+
+  const withProfiles: string[] = [];
+  for (const dir of userDataDirCandidates()) {
+    if ((await listProfiles(dir)).length > 0) withProfiles.push(dir);
+  }
+  const only = withProfiles[0];
+  if (withProfiles.length === 1 && only !== undefined) return ok(only);
+  if (withProfiles.length === 0) {
+    return err("No browser profiles found on this machine. Open Chrome, Brave, or Edge and try again.");
+  }
+  return err(
+    `Found profiles for more than one browser (${withProfiles.map(browserNameForUserDataDir).join(", ")}). ` +
+    "Open the browser you want the agent to use, then run /browser-profile again.",
+  );
+};
+
+/** Enumerate profiles for the resolved dir, or explain why we cannot. */
+const loadProfiles = async (
+  client: BrowserClient,
+): Promise<Result<{ userDataDir: string; profiles: ReadonlyArray<BrowserProfile> }, string>> => {
+  const dir = await resolveUserDataDir(client);
+  if (!dir.success) return dir;
+  const profiles = await listProfiles(dir.data);
+  if (profiles.length === 0) {
+    return err(`No profiles found in ${dir.data}. If the browser was just installed, open it once and retry.`);
+  }
+  return ok({ userDataDir: dir.data, profiles });
+};
+
+/**
+ * Re-seed the live session so the new profile takes effect now. Closing the
+ * owned tabs and restarting the client makes start() open a window in the
+ * pinned profile and attach to it.
+ */
+const applyToLiveSession = async (client: BrowserClient): Promise<Result<void, string>> => {
+  if (!client.status().alive) return ok(undefined);
+  await client.closeOwnedTabs();
+  await client.stop();
+  const started = await client.start();
+  if (!started.success) return err(started.error.message);
+  return ok(undefined);
+};
+
+export function registerProfileCommand(pi: ExtensionAPI, client: BrowserClient): void {
+  pi.registerCommand("browser-profile", {
+    description: "Choose which browser profile the agent uses",
+    handler: async (_args, ctx) => {
+      const loaded = await loadProfiles(client);
+      if (!loaded.success) {
+        ctx.ui.notify(loaded.error, "error");
+        return;
+      }
+      if (!ctx.hasUI) {
+        ctx.ui.notify("Profile selection needs an interactive terminal.", "warning");
+        return;
+      }
+
+      const currentPin = client.profilePin() ?? (await readPin());
+      const choice = await promptForProfile(ctx, loaded.data.profiles, currentPin);
+
+      if (choice.kind === "cancelled") {
+        ctx.ui.notify("Profile unchanged.", "info");
+        return;
+      }
+
+      if (choice.kind === "clear") {
+        const cleared = await clearPin();
+        if (!cleared.success) {
+          ctx.ui.notify(cleared.error, "error");
+          return;
+        }
+        client.setProfilePin(null);
+        ctx.ui.notify(
+          "Profile selection cleared. New windows will open in whichever browser profile is focused.",
+          "info",
+        );
+        return;
+      }
+
+      const pin = pinFor(loaded.data.userDataDir, choice.profile);
+      const saved = await writePin(pin);
+      if (!saved.success) {
+        ctx.ui.notify(saved.error, "error");
+        return;
+      }
+      client.setProfilePin(pin);
+
+      const applied = await applyToLiveSession(client);
+      if (!applied.success) {
+        ctx.ui.notify(
+          `Saved ${pin.label}, but switching the open session failed: ${applied.error}`,
+          "warning",
+        );
+        return;
+      }
+      ctx.ui.notify(`Browser profile: ${pin.label} ✓\nSaved — this profile is used until you change it.`, "info");
+    },
+  });
+}
+
+/**
+ * First-run prompt used by setup: pick a profile when none is pinned yet.
+ * Returns a note to append to the setup output; the caller always continues,
+ * because a cancelled or unavailable picker must leave existing behavior intact.
+ */
+export const promptForProfileIfUnset = async (
+  client: BrowserClient,
+  ctx: ExtensionContext | undefined,
+): Promise<string | undefined> => {
+  if (client.profilePin()) return undefined;
+
+  const stored = await readPin();
+  if (stored) {
+    client.setProfilePin(stored);
+    return undefined;
+  }
+  if (!ctx?.hasUI) {
+    return "No browser profile selected — using whichever window is focused. Run /browser-profile to pin one.";
+  }
+
+  const loaded = await loadProfiles(client);
+  if (!loaded.success) return loaded.error;
+
+  const choice = await promptForProfile(
+    ctx,
+    loaded.data.profiles,
+    null,
+    "Select the browser profile the agent should use",
+  );
+  if (choice.kind !== "profile") {
+    return "No browser profile selected — using whichever window is focused. Run /browser-profile to pin one.";
+  }
+
+  const pin = pinFor(loaded.data.userDataDir, choice.profile);
+  const saved = await writePin(pin);
+  if (!saved.success) return saved.error;
+  client.setProfilePin(pin);
+  return `Browser profile: ${pin.label}`;
+};