pi-feats 0.1.2 → 0.1.4

package/extensions/browser-harness/profile/bind.ts

@@ -0,0 +1,90 @@
+import type { BrowserClient } from "../client";
+import type { ResultOf } from "../cdp/commands";
+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";
+
+const SEED_DEADLINE_MS = 15_000;
+const SEED_POLL_MS = 500;
+
+type PageTarget = ResultOf<"Target.getTargets">["targetInfos"][number];
+
+const pageTargets = async (client: BrowserClient): Promise<ReadonlyArray<PageTarget>> => {
+  const r = await client.session().callBrowser("Target.getTargets");
+  if (!r.success) return [];
+  return r.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.`;
+
+export const seedProfileWindow = async (
+  client: BrowserClient,
+  pin: ProfilePin,
+): Promise<Result<string, CdpError>> => {
+  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.`,
+    ));
+  }
+
+  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,
+    // ProcessSingleton keys on the user-data-dir path, so forward only the value the running browser reports: a reconstructed one may differ by case and start a SECOND browser.
+    ...(running.explicitUserDataDir ? { explicitUserDataDir: running.explicitUserDataDir } : {}),
+  });
+  if (!launched.success) {
+    return err(cdpError("discovery_failed", `${launched.error} — ${manualFallbackHint(pin)}`));
+  }
+
+  const { sentinelUrl, cleanup, kill } = 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) {
+    kill();
+    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().windowId(seed.targetId);
+  if (win.success) ownership.setHarnessWindowId(win.data);
+
+  const attached = await client.session().attach(seed.targetId);
+  if (attached.success) {
+    await client.session().callOnTarget("Page.navigate", { url: "about:blank" }, attached.data);
+  }
+  await cleanup();
+
+  return ok(seed.targetId);
+};

package/extensions/browser-harness/profile/browser-process.ts

@@ -0,0 +1,320 @@
+// `running` is derived only from live-process evidence: an installed-but-closed browser must read as "not running".
+// `wmic` is deliberately unused — Microsoft removed it by default in Windows 11 24H2 and entirely in 25H2, so PowerShell CIM plus tasklist replace it.
+
+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 { Type } from "typebox";
+import { Compile } from "typebox/compile";
+import { parseJson } from "../schemas/parse";
+import { browserNameForUserDataDir } from "./paths";
+
+const run = promisify(execFile);
+const EXEC_TIMEOUT_MS = 5_000;
+
+export type RunningBrowser = {
+  readonly running: boolean;
+  readonly exePath?: string;
+  readonly explicitUserDataDir?: string;
+};
+
+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"];
+
+// Match the `--type=` flag, not words like "renderer" anywhere in the string, or an install path containing one is 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, so the process NAME must be filtered too.
+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")
+  );
+};
+
+export type BrowserCandidate = {
+  readonly exePath?: string;
+  readonly explicitUserDataDir?: string;
+};
+
+// A package upgrade under a running browser makes `/proc/<pid>/exe` read "… (deleted)", which fails to spawn with ENOENT unless the marker comes off.
+const DELETED_SUFFIX = " (deleted)";
+
+export const stripDeletedSuffix = (path: string): string | undefined =>
+  path.endsWith(DELETED_SUFFIX) && path.length > DELETED_SUFFIX.length
+    ? path.slice(0, -DELETED_SUFFIX.length)
+    : undefined;
+
+const exists = async (path: string): Promise<boolean> => {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+export const spawnableExePath = async (raw: string): Promise<string | undefined> => {
+  if (raw.length === 0) return undefined;
+  if (await exists(raw)) return raw;
+  const stripped = stripDeletedSuffix(raw);
+  if (stripped && (await exists(stripped))) return stripped;
+  return undefined;
+};
+
+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);
+};
+
+export const rankBrowserCandidate = (candidate: BrowserCandidate, preferUserDataDir?: string): number => {
+  if (!preferUserDataDir) return 1;
+  if (candidate.explicitUserDataDir) {
+    return samePath(candidate.explicitUserDataDir, preferUserDataDir) ? 4 : 0;
+  }
+  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;
+};
+
+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;
+};
+
+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 {
+      cmdline = (await readFile(`/proc/${pid}/cmdline`, "utf8")).replace(/\0/g, " ").trim();
+    } catch {
+      continue;
+    }
+    if (!cmdline || hasChildProcessType(cmdline)) continue;
+    let link: string | undefined;
+    try {
+      link = await readlink(`/proc/${pid}/exe`);
+    } catch {}
+    // Chrome rewrites its argv to the bare executable path, so argv[0] is the live install location when /proc/<pid>/exe is unreadable or stale.
+    const exePath =
+      (link ? await spawnableExePath(link) : undefined) ??
+      (await spawnableExePath(cmdline.split(" ")[0] ?? ""));
+    const explicit = parseUserDataDirFlag(cmdline);
+    candidates.push({
+      ...(exePath ? { exePath } : {}),
+      ...(explicit ? { explicitUserDataDir: explicit } : {}),
+    });
+  }
+  return candidates;
+};
+
+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 {}
+    if (args && hasChildProcessType(args)) continue;
+    const explicit = args ? parseUserDataDirFlag(args) : undefined;
+    candidates.push({
+      exePath: comm,
+      ...(explicit ? { explicitUserDataDir: explicit } : {}),
+    });
+  }
+  return candidates;
+};
+
+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(" ");
+
+const WinProcessSchema = Type.Object(
+  {
+    ExecutablePath: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+    CommandLine: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+  },
+  { additionalProperties: true },
+);
+
+const WinProcessesSchema = Type.Union([WinProcessSchema, Type.Array(WinProcessSchema)]);
+
+const winProcessesValidator = Compile(WinProcessesSchema);
+
+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 = parseJson(trimmed, winProcessesValidator);
+      if (parsed.success) {
+        const rows = Array.isArray(parsed.data) ? parsed.data : [parsed.data];
+        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 {}
+
+  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 {}
+  return [];
+};
+
+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)));
+};
+
+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 {}
+    }
+  }
+  return undefined;
+};
+
+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 };
+
+  const [first, ...rest] = candidates;
+  if (!first) return { running: false };
+  let best = first;
+  let bestRank = rankBrowserCandidate(best, preferUserDataDir);
+  for (const candidate of rest) {
+    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 } : {}),
+  };
+};
+
+export const isBrowserRunning = async (): Promise<boolean> => (await detectRunningBrowser()).running;
+
+export const resolveBrowserExecutable = async (running?: RunningBrowser): Promise<string | undefined> => {
+  const detected = running ?? (await detectRunningBrowser());
+  const usable = detected.exePath ? await spawnableExePath(detected.exePath) : undefined;
+  if (usable) return usable;
+  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 {}
+  }
+  return undefined;
+};

package/extensions/browser-harness/profile/command.ts

@@ -0,0 +1,189 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/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 { clearPin, type ProfilePin, readPin, writePin } from "./store";
+
+// `ctx.ui.select` resolves to undefined both on Escape and in non-interactive modes, so "no answer" must mean "change nothing".
+
+const CLEAR_SELECTION_LABEL = "— Clear selection (use whichever window is focused) —";
+
+type ProfileChoice =
+  | { readonly kind: "profile"; readonly profile: BrowserProfile }
+  | { readonly kind: "clear" }
+  | { readonly kind: "cancelled" };
+
+const disambiguate = (profiles: ReadonlyArray<BrowserProfile>): ReadonlyArray<string> => {
+  const counts = new Map<string, number>();
+  for (const p of profiles) counts.set(p.label, (counts.get(p.label) ?? 0) + 1);
+  return profiles.map((p) => ((counts.get(p.label) ?? 0) > 1 ? `${p.label} [${p.dir}]` : p.label));
+};
+
+const promptForProfile = async (
+  ctx: ExtensionContext,
+  profiles: ReadonlyArray<BrowserProfile>,
+  currentPin: ProfilePin | null,
+  title = "Select browser profile",
+): Promise<ProfileChoice> => {
+  if (!ctx.hasUI || profiles.length === 0) return { kind: "cancelled" };
+
+  const labels = disambiguate(profiles);
+  const rows = labels.map((label, i) => {
+    const isPinned = currentPin?.profileDir === profiles[i]?.dir;
+    return isPinned ? `✓ ${label}` : `  ${label}`;
+  });
+  const options = [...rows, CLEAR_SELECTION_LABEL];
+
+  const answer = await ctx.ui.select(title, options);
+  if (answer === undefined) return { kind: "cancelled" };
+  if (answer === CLEAR_SELECTION_LABEL) return { kind: "clear" };
+
+  const index = options.indexOf(answer);
+  const profile = index >= 0 ? profiles[index] : undefined;
+  if (!profile) return { kind: "cancelled" };
+  return { kind: "profile", profile };
+};
+
+const pinFor = (userDataDir: string, profile: BrowserProfile): ProfilePin => ({
+  userDataDir,
+  profileDir: profile.dir,
+  label: profile.label,
+  savedAt: new Date().toISOString(),
+});
+
+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.",
+  );
+};
+
+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 });
+};
+
+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");
+    },
+  });
+}
+
+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}`;
+};

package/extensions/browser-harness/profile/launch.ts

@@ -0,0 +1,80 @@
+// CDP cannot open a window in another profile, so this goes through the command line: ProcessSingleton hands the argv to the running browser.
+// The sentinel must ride on a real `file://` URL — Chrome discards a bare `about:blank#token` argument and opens chrome://newtab instead.
+
+import { spawn, type ChildProcess } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { type Result, err, ok } from "../util/result";
+
+export type ProfileWindowRequest = {
+  readonly exePath: string;
+  readonly profileDir: string;
+  readonly explicitUserDataDir?: string;
+};
+
+export type ProfileWindowHandle = {
+  readonly sentinelUrl: string;
+  readonly cleanup: () => Promise<void>;
+  readonly kill: () => void;
+};
+
+const SENTINEL_HTML = (token: string): string =>
+  `<!doctype html><meta charset="utf-8"><title>${token}</title>` +
+  `<body style="font:14px system-ui;padding:2rem;color:#555">pi browser harness — opening this profile…</body>`;
+
+export const openProfileWindow = async (
+  req: ProfileWindowRequest,
+): Promise<Result<ProfileWindowHandle, string>> => {
+  const token = `pi-harness-${randomUUID()}`;
+  const file = join(tmpdir(), `${token}.html`);
+  try {
+    await writeFile(file, SENTINEL_HTML(token), "utf8");
+  } catch (e) {
+    return err(`could not write the profile handshake page: ${e instanceof Error ? e.message : String(e)}`);
+  }
+
+  const sentinelUrl = pathToFileURL(file).href;
+  const args: string[] = [];
+  if (req.explicitUserDataDir) args.push(`--user-data-dir=${req.explicitUserDataDir}`);
+  args.push(`--profile-directory=${req.profileDir}`, "--new-window", sentinelUrl);
+
+  let child: ChildProcess;
+  try {
+    child = spawn(req.exePath, args, { detached: true, stdio: "ignore" });
+  } catch (e) {
+    await rm(file, { force: true }).catch(() => {});
+    return err(`could not launch ${req.exePath}: ${e instanceof Error ? e.message : String(e)}`);
+  }
+
+  // spawn() reports a bad binary asynchronously as an 'error' event rather than throwing; unhandled, an ENOENT looked like the 15s sentinel timeout.
+  const spawnFailure = await new Promise<string | undefined>((resolve) => {
+    child.once("spawn", () => resolve(undefined));
+    child.once("error", (e: Error) => resolve(e.message));
+  });
+  // A later 'error' event with no listener would throw, so keep one attached for the detached launcher's lifetime.
+  child.on("error", () => {});
+  child.unref();
+
+  if (spawnFailure) {
+    await rm(file, { force: true }).catch(() => {});
+    return err(`could not launch ${req.exePath}: ${spawnFailure}`);
+  }
+
+  let live: ChildProcess | null = child;
+
+  return ok({
+    sentinelUrl,
+    cleanup: async () => {
+      await rm(file, { force: true }).catch(() => {});
+    },
+    kill: () => {
+      if (live) {
+        try { live.kill("SIGTERM"); } catch {}
+        live = null;
+      }
+    },
+  });
+};