pi-browser-harness 0.8.3 → 0.10.0

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/cdp/window-binding.ts

@@ -0,0 +1,15 @@
+import type { BrowserClient } from "../client";
+
+/**
+ * Capture the real Chrome windowId of a freshly-created harness window and bind
+ * it as the session's durable window identity. Best-effort: a failed CDP call
+ * leaves the previous binding untouched. Call this on every code path that
+ * spawns a NEW dedicated window (newWindow:true), so the windowId never points
+ * at a window that has since been replaced.
+ */
+export const bindHarnessWindowId = async (client: BrowserClient, targetId: string): Promise<void> => {
+  const r = await client.session().callBrowser("Browser.getWindowForTarget", { targetId });
+  if (!r.success) return;
+  const wid = (r.data as { windowId?: number }).windowId;
+  if (typeof wid === "number") client.ownership().setHarnessWindowId(wid);
+};

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 = {
@@ -16,10 +19,14 @@ export type BrowserClientOptions = {
   readonly initialOwnership?: {
     readonly ownedTargetIds?: ReadonlyArray<string>;
     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;
+    readonly harnessWindowId: number | undefined;
   }) => void;
 };
 
@@ -32,6 +39,9 @@ export type BrowserClient = {
   /** Detach from the current page target (removes the "Chrome is being controlled" banner)
    *  while keeping the transport connection alive. Call on session shutdown. */
   detach(): Promise<void>;
+  /** Close every tab this session owns and clear the window binding. Best-effort —
+   *  used on session shutdown so no stale harness tabs survive. */
+  closeOwnedTabs(): Promise<void>;
   evaluateJs(expression: string, sessionId?: string): Promise<Result<unknown, CdpError>>;
   pageInfo(): Promise<Result<PageInfo | { readonly dialog: DialogInfo }, CdpError>>;
   takeDialog(): DialogInfo | null;
@@ -44,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;
@@ -82,13 +105,16 @@ const parsePageInfoPayload = (v: unknown): Result<PageInfo, CdpError> => {
 
 export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient => {
   const transport = opts.transport ?? createCdpTransport();
-  const ownershipInit: { ownedTargetIds?: ReadonlyArray<string>; harnessWindowTargetId?: string } = {};
+  const ownershipInit: { ownedTargetIds?: ReadonlyArray<string>; harnessWindowTargetId?: string; harnessWindowId?: number } = {};
   if (opts.initialOwnership?.ownedTargetIds !== undefined) {
     ownershipInit.ownedTargetIds = opts.initialOwnership.ownedTargetIds;
   }
   if (opts.initialOwnership?.harnessWindowTargetId !== undefined) {
     ownershipInit.harnessWindowTargetId = opts.initialOwnership.harnessWindowTargetId;
   }
+  if (opts.initialOwnership?.harnessWindowId !== undefined) {
+    ownershipInit.harnessWindowId = opts.initialOwnership.harnessWindowId;
+  }
   const ownership = createOwnershipRegistry(ownershipInit);
   if (opts.onOwnershipChange) {
     const cb = opts.onOwnershipChange;
@@ -96,14 +122,37 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
       cb({
         ownedTargetIds: ownership.list(),
         harnessWindowTargetId: ownership.harnessWindow(),
+        harnessWindowId: ownership.harnessWindowId(),
       });
     });
   }
-  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);
@@ -114,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();
@@ -157,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();
@@ -257,37 +318,33 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
   };
 
   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();
 
-    const params: Record<string, unknown> = { url: "about:blank" };
-    if (hw && live.has(hw)) {
-      // Open as a child of the harness window's seed tab — Chrome places
-      // it in the same window, giving us visual grouping for free.
-      params["openerId"] = hw;
+    // 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 {
-      // Either fresh session or the harness window was closed by the user.
-      // Spawn a new dedicated window.
-      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);
-    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>> => {
@@ -297,6 +354,18 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
     return ok(undefined);
   };
 
+  const closeOwnedTabs = async (): Promise<void> => {
+    // Snapshot first — remove() mutates the list, and targetDestroyed events
+    // may also prune concurrently. Failures are swallowed: a tab the user
+    // already closed, or a dead transport, must not block shutdown.
+    for (const id of ownership.list()) {
+      await session.callBrowser("Target.closeTarget", { targetId: id }).catch(() => {});
+      ownership.remove(id);
+    }
+    ownership.setHarnessWindow(undefined);
+    ownership.setHarnessWindowId(undefined);
+  };
+
   const status = (): DaemonStatus => ({
     alive: transport.state() === "open" && session.current() !== null,
     sessionId: session.current()?.sessionId ?? null,
@@ -314,9 +383,9 @@ 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,
+    ensureAlive, status, start, stop, detach, closeOwnedTabs,
     evaluateJs, pageInfo,
     takeDialog: () => session.takeDialog(),
     listTabs, switchTab, newTab, closeTab,
@@ -325,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;
 };

package/src/daemon/protocol.ts

@@ -133,8 +133,18 @@ export const deserialize = (line: string): WireMessage | null => {
 
 // ── Constants ──────────────────────────────────────────────────────────────────
 
-/** Filesystem path for the daemon's Unix domain socket. */
-export const DAEMON_SOCKET_PATH = "/tmp/pi-browser-daemon.sock";
+/**
+ * IPC endpoint for the daemon.
+ *
+ * On POSIX platforms this is a Unix domain socket path. On Windows, Node's IPC
+ * requires a named pipe of the form `\\.\pipe\<name>` — a Unix path like
+ * `/tmp/…` is not a valid `net` listen/connect target there and causes setup
+ * to fail. See https://nodejs.org/api/net.html#ipc-support.
+ */
+export const DAEMON_SOCKET_PATH =
+  process.platform === "win32"
+    ? "\\\\.\\pipe\\pi-browser-daemon"
+    : "/tmp/pi-browser-daemon.sock";
 
 /**
  * How long the daemon stays alive with zero connected clients before exiting

package/src/daemon/spawn.ts

@@ -19,6 +19,19 @@ import { DAEMON_SOCKET_PATH, serialize, type WireControl } from "./protocol";
 
 const moduleDir = dirname(fileURLToPath(import.meta.url));
 
+const isWindows = process.platform === "win32";
+
+/**
+ * Remove a stale POSIX socket file. On Windows the daemon endpoint is a named
+ * pipe, which is not a filesystem entry and is torn down automatically when the
+ * owning process exits — so there is nothing to unlink, and calling unlink on a
+ * pipe path throws. This is a no-op on Windows.
+ */
+const cleanupStaleSocket = (): void => {
+  if (isWindows) return;
+  unlink(DAEMON_SOCKET_PATH).catch(() => {});
+};
+
 /**
  * Check whether the daemon is running by probing its Unix socket.
  * A file-existence check is unreliable — a crashed daemon leaves a stale socket.
@@ -26,11 +39,15 @@ const moduleDir = dirname(fileURLToPath(import.meta.url));
  * On failure, clean up the stale socket so ensureDaemon can spawn a fresh one.
  */
 export const isDaemonRunning = async (timeoutMs = 2_000): Promise<boolean> => {
-  // If the socket file doesn't exist, the daemon definitely isn't running.
-  try {
-    await access(DAEMON_SOCKET_PATH);
-  } catch {
-    return false;
+  // On POSIX, a missing socket file means the daemon definitely isn't running,
+  // so we can short-circuit. Windows named pipes are not filesystem entries —
+  // access() always fails there — so skip the pre-check and probe directly.
+  if (!isWindows) {
+    try {
+      await access(DAEMON_SOCKET_PATH);
+    } catch {
+      return false;
+    }
   }
 
   return new Promise((resolve) => {
@@ -45,7 +62,7 @@ export const isDaemonRunning = async (timeoutMs = 2_000): Promise<boolean> => {
     const timer = setTimeout(() => {
       sock.destroy();
       // ponytail: stale socket cleanup; ENOENT = already gone, fine
-      unlink(DAEMON_SOCKET_PATH).catch(() => {});
+      cleanupStaleSocket();
       done(false);
     }, timeoutMs);
 
@@ -70,7 +87,7 @@ export const isDaemonRunning = async (timeoutMs = 2_000): Promise<boolean> => {
       clearTimeout(timer);
       sock.destroy();
       // ponytail: connection refused = daemon dead, clean up stale socket
-      unlink(DAEMON_SOCKET_PATH).catch(() => {});
+      cleanupStaleSocket();
       done(false);
     });
 
@@ -96,18 +113,34 @@ export const isDaemonRunning = async (timeoutMs = 2_000): Promise<boolean> => {
 export const spawnDaemon = (): ChildProcess | null => {
   // Resolve the daemon entry point and tsx binary.
   const daemonScript = join(moduleDir, "index.ts");
-  const tsxBin = join(moduleDir, "..", "..", "node_modules", ".bin", "tsx");
 
-  // Use tsx to run the daemon TypeScript source directly.
-  // The spawed process inherits the parent's env so module resolution works.
+  // On Windows, npm installs binaries as `.cmd` shims, not bare executables,
+  // and the npx fallback is `npx.cmd`. A `.cmd` file can only be launched
+  // through a shell (spawning it directly yields EINVAL), so set shell: true
+  // whenever we invoke one.
+  const tsxBinBase = join(moduleDir, "..", "..", "node_modules", ".bin", "tsx");
+  const tsxBin = isWindows ? `${tsxBinBase}.cmd` : tsxBinBase;
+  const hasLocalTsx = existsSync(tsxBin);
+
+  // Use the local tsx binary to run the daemon TypeScript source directly.
+  // The spawned process inherits the parent's env so module resolution works.
   // Fall back to `npx tsx` if the local binary isn't available.
-  const cmd = existsSync(tsxBin) ? tsxBin : "npx";
-  const args = existsSync(tsxBin) ? [daemonScript] : ["tsx", daemonScript];
+  const cmd = hasLocalTsx ? tsxBin : isWindows ? "npx.cmd" : "npx";
+  const args = hasLocalTsx ? [daemonScript] : ["tsx", daemonScript];
+
+  // With shell: true, Node passes the command line to the shell verbatim
+  // without quoting, so any path containing spaces (e.g. C:\Users\Some Name)
+  // would be split into multiple tokens. Wrap each token in double quotes on
+  // Windows to keep space-containing paths intact.
+  const quote = (s: string): string => (isWindows ? `"${s}"` : s);
 
-  const child = spawn(cmd, args, {
+  const child = spawn(quote(cmd), args.map(quote), {
     detached: true,
     stdio: "ignore",
     env: { ...process.env },
+    // `.cmd` shims (local tsx or npx.cmd on Windows) must run via a shell.
+    shell: isWindows,
+    windowsVerbatimArguments: isWindows,
   });
 
   child.unref();

package/src/deep-research.ts

@@ -0,0 +1,41 @@
+/**
+ * Deep research — the /deep-research slash command. An explicit entry point
+ * (alongside the auto-triggering deep-research skill) that kicks off a research
+ * run for a given question.
+ *
+ * The command is thin: it validates a non-empty question and injects a user
+ * message that starts the deep-research flow. The actual orchestration
+ * (decompose → fan out web-search-researcher subagents → synthesize a cited
+ * report) lives in skills/deep-research/SKILL.md, which the injected prompt
+ * triggers. pi.sendUserMessage always starts a turn.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+// ── Shared core: build the prompt that starts a deep-research run ───────────
+
+export function buildDeepResearchPrompt(question: string): string {
+  return (
+    `Do deep research on the following question and produce a cited Markdown report. ` +
+    `Use the deep-research skill: decompose it into sub-questions, fan out web-search-researcher ` +
+    `subagents to research each against the live web, then synthesize a source-cited report file.\n\n` +
+    `Question: ${question}`
+  );
+}
+
+// ── Public: register the /deep-research slash command ──────────────────────
+
+export function registerDeepResearchCommand(pi: ExtensionAPI): void {
+  pi.registerCommand("deep-research", {
+    description: "Research a question on the web and write a cited report",
+    handler: async (args, ctx) => {
+      const question = args.trim();
+      if (question.length === 0) {
+        ctx.ui.notify('Usage: /deep-research <question>. Example: /deep-research "compare CDP vs WebDriver"', "warning");
+        return;
+      }
+      ctx.ui.notify(`Starting deep research: ${question}`, "info");
+      pi.sendUserMessage(buildDeepResearchPrompt(question));
+    },
+  });
+}