waygraph 0.16.0 → 0.16.1

package/dist/live/auto-session/files.d.ts

@@ -0,0 +1,44 @@
+export interface SessionMeta {
+    sessionId: string;
+    socketPath: string;
+    pid: number;
+    projectDir: string;
+    startedAt: string;
+    headless: boolean;
+}
+export declare function sessionDir(projectDir: string): string;
+export declare function metaPath(projectDir: string, sessionId: string): string;
+/** Global index so session control works even when cwd ≠ the project that spawned the session. */
+export declare function globalMetaPath(sessionId: string): string;
+export declare function isPidAlive(pid: number): boolean;
+/**
+ * Deliberately NOT under the project directory (unlike meta/log files) -
+ * a real bug found while proving out openspec/changes/waygraph-map's own
+ * "waypack" loading claim: a project loaded through a consumer's own deeply
+ * nested `node_modules/<pkg>` path can push the socket's absolute path past
+ * the OS's AF_UNIX `sun_path` limit (~108 bytes on Linux), failing with
+ * `listen EINVAL`. A short, fixed-location directory sidesteps this
+ * regardless of how deep `projectDir` itself is nested. `sessionId` alone
+ * (8 hex chars, `generateSessionId()`) is enough to keep this collision-safe
+ * across every project on the machine sharing this one flat directory - the
+ * same randomness space this package already relied on per-project.
+ */
+export declare function socketDir(): string;
+export declare function socketPathFor(sessionId: string): string;
+export declare function logPathFor(projectDir: string, sessionId: string): string;
+export declare function generateSessionId(): string;
+export declare function readSessionMeta(projectDir: string, sessionId: string): SessionMeta | null;
+/**
+ * Resolve session metadata from a project hint (cwd) or the global registry.
+ * Fixes "session unreachable" when the agent calls status/send from a different
+ * directory or pane than the one that ran `pilot start`.
+ */
+export declare function resolveSessionMeta(sessionId: string, projectDirHint?: string): SessionMeta | null;
+export declare function writeGlobalSessionMeta(meta: SessionMeta): void;
+export declare function removeSessionFiles(projectDir: string, sessionId: string): void;
+/** Stop one detached session (SIGTERM + cleanup metadata/socket). */
+export declare function stopBrowserSession(projectDir: string, sessionId: string): boolean;
+/** Stop every live session registered for a project. */
+export declare function stopAllBrowserSessions(projectDir: string): number;
+/** Live browser sessions for a project (metadata + socket + pid still present). */
+export declare function listBrowserSessions(projectDir: string): SessionMeta[];

package/dist/live/auto-session/files.js

@@ -0,0 +1,145 @@
+// Where a detached session lives on disk: its metadata (per project, plus a global copy keyed by id), its short
+// socket path under the OS temp folder, its log; and listing, resolving and stopping sessions by id.
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+export function sessionDir(projectDir) {
+    return join(projectDir, ".waygraph-auto");
+}
+export function metaPath(projectDir, sessionId) {
+    return join(sessionDir(projectDir), `${sessionId}.json`);
+}
+/** Global index so session control works even when cwd ≠ the project that spawned the session. */
+export function globalMetaPath(sessionId) {
+    return join(socketDir(), `${sessionId}.meta.json`);
+}
+export function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Deliberately NOT under the project directory (unlike meta/log files) -
+ * a real bug found while proving out openspec/changes/waygraph-map's own
+ * "waypack" loading claim: a project loaded through a consumer's own deeply
+ * nested `node_modules/<pkg>` path can push the socket's absolute path past
+ * the OS's AF_UNIX `sun_path` limit (~108 bytes on Linux), failing with
+ * `listen EINVAL`. A short, fixed-location directory sidesteps this
+ * regardless of how deep `projectDir` itself is nested. `sessionId` alone
+ * (8 hex chars, `generateSessionId()`) is enough to keep this collision-safe
+ * across every project on the machine sharing this one flat directory - the
+ * same randomness space this package already relied on per-project.
+ */
+export function socketDir() {
+    return join(tmpdir(), "waygraph-auto");
+}
+export function socketPathFor(sessionId) {
+    return join(socketDir(), `${sessionId}.sock`);
+}
+export function logPathFor(projectDir, sessionId) {
+    return join(sessionDir(projectDir), `${sessionId}.log`);
+}
+export function generateSessionId() {
+    return randomBytes(4).toString("hex");
+}
+export function readSessionMeta(projectDir, sessionId) {
+    const p = metaPath(projectDir, sessionId);
+    if (!existsSync(p))
+        return null;
+    try {
+        return JSON.parse(readFileSync(p, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve session metadata from a project hint (cwd) or the global registry.
+ * Fixes "session unreachable" when the agent calls status/send from a different
+ * directory or pane than the one that ran `pilot start`.
+ */
+export function resolveSessionMeta(sessionId, projectDirHint) {
+    if (projectDirHint) {
+        const local = readSessionMeta(projectDirHint, sessionId);
+        if (local)
+            return local;
+    }
+    const globalPath = globalMetaPath(sessionId);
+    if (existsSync(globalPath)) {
+        try {
+            return JSON.parse(readFileSync(globalPath, "utf-8"));
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+export function writeGlobalSessionMeta(meta) {
+    mkdirSync(socketDir(), { recursive: true });
+    writeFileSync(globalMetaPath(meta.sessionId), JSON.stringify(meta, null, 2));
+}
+export function removeSessionFiles(projectDir, sessionId) {
+    for (const p of [
+        metaPath(projectDir, sessionId),
+        globalMetaPath(sessionId),
+        socketPathFor(sessionId),
+    ]) {
+        try {
+            rmSync(p, { force: true });
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+/** Stop one detached session (SIGTERM + cleanup metadata/socket). */
+export function stopBrowserSession(projectDir, sessionId) {
+    const meta = resolveSessionMeta(sessionId, projectDir);
+    if (!meta)
+        return false;
+    try {
+        process.kill(meta.pid, "SIGTERM");
+    }
+    catch {
+        /* already gone */
+    }
+    removeSessionFiles(meta.projectDir, sessionId);
+    return true;
+}
+/** Stop every live session registered for a project. */
+export function stopAllBrowserSessions(projectDir) {
+    const sessions = listBrowserSessions(projectDir);
+    for (const meta of sessions) {
+        stopBrowserSession(meta.projectDir, meta.sessionId);
+    }
+    return sessions.length;
+}
+/** Live browser sessions for a project (metadata + socket + pid still present). */
+export function listBrowserSessions(projectDir) {
+    const dir = sessionDir(projectDir);
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const f of readdirSync(dir)) {
+        if (!f.endsWith(".json"))
+            continue;
+        const id = f.slice(0, -".json".length);
+        const meta = readSessionMeta(projectDir, id);
+        if (!meta)
+            continue;
+        if (!existsSync(socketPathFor(id)))
+            continue;
+        if (!isPidAlive(meta.pid)) {
+            removeSessionFiles(projectDir, id);
+            continue;
+        }
+        out.push(meta);
+    }
+    return out.sort((a, b) => a.startedAt.localeCompare(b.startedAt));
+}

package/dist/live/auto-session/helpers.d.ts

@@ -1,7 +1,8 @@
+import type { PilotHighlightFixtures } from "../../demo/overlay/pilot/fixtures.js";
 import type { StubPhaseResult } from "../../engine/stub/stub.js";
-import type { ExploreMenu } from "../auto/explore.js";
 import type { BlockEntry } from "../../manifest/project.js";
-import type { PickResult } from "../auto/auto.js";
+import type { ExploreMenu } from "../auto/explore.js";
+import type { PickResult } from "../auto/menu.js";
 /** True when a stub-phase result actually carries authored content worth keeping. */
 export declare function stubPhaseHasContent(r: StubPhaseResult): boolean;
 /** One available move in a session snapshot: a Block and the Checkpoint it leads to. */
@@ -211,4 +212,6 @@ export interface StorageSnapshot {
     serviceWorkers: string[];
     serviceWorkerRegistrations: ServiceWorkerRegistrationInfo[];
 }
+/** What a highlight call paints, in a few words, for the session's activity line. */
+export declare function describeHighlight(fixtures: PilotHighlightFixtures): string;
 export {};

package/dist/live/auto-session/helpers.js

@@ -1,3 +1,4 @@
+// The session's shared shapes and pure helpers: snapshots, picks, trace / console entries, DOM walking, stub files.
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 /** True when a stub-phase result actually carries authored content worth keeping. */
@@ -146,3 +147,19 @@ export function stubFilePath(kind) {
     return join(packageRoot, "assets", "stubs", names[kind]);
 }
 export const CONSOLE_LOG_MAX_ENTRIES = 200;
+/** What a highlight call paints, in a few words, for the session's activity line. */
+export function describeHighlight(fixtures) {
+    if (fixtures.clear === true)
+        return "clear";
+    return ([
+        fixtures.rings?.length ? `${fixtures.rings.length} ring(s)` : null,
+        fixtures.todos?.length ? `${fixtures.todos.length} todo(s)` : null,
+        fixtures.zoom && fixtures.zoom > 1.001 ? `zoom ${fixtures.zoom}` : null,
+        fixtures.device
+            ? `device ${typeof fixtures.device === "string" ? fixtures.device : fixtures.device.preset || "custom"}`
+            : null,
+        fixtures.rings?.some((r) => r.focus) ? "focus" : null,
+    ]
+        .filter(Boolean)
+        .join(", ") || "fixtures");
+}

package/dist/live/auto-session/inspect.d.ts

@@ -0,0 +1,4 @@
+import type { BrowserContext, Page } from "@playwright/test";
+import type { InspectDomOptions, InspectDomResult, StorageSnapshot } from "./helpers.js";
+export declare function inspectDom(page: Page, opts: InspectDomOptions): Promise<InspectDomResult>;
+export declare function inspectStorage(page: Page, context: BrowserContext): Promise<StorageSnapshot>;

package/dist/live/auto-session/inspect.js

@@ -0,0 +1,75 @@
+import { showPilotActivity, showPilotVision } from "../../demo/overlay/pilot/shell.js";
+import { ignorePageGone } from "../../engine/page-gone.js";
+import { FULL_MODE_DEFAULT_DEPTH, FULL_MODE_MAX_NODES, FULL_MODE_MAX_TEXT_LENGTH, walkFullDom } from "./helpers.js";
+export async function inspectDom(page, opts) {
+    const mode = opts.mode ?? "aria";
+    const ariaOptions = opts.depth !== undefined ? { mode: "ai", depth: opts.depth } : { mode: "ai" };
+    if (opts.selector) {
+        const locator = page.locator(opts.selector).first();
+        if ((await locator.count()) === 0) {
+            return { ok: false, error: `no element matches selector "${opts.selector}"` };
+        }
+        await showPilotVision(page, opts.selector, `dom (${mode}): ${opts.selector}`, "orange");
+        if (mode === "full") {
+            const caps = {
+                depth: opts.depth ?? FULL_MODE_DEFAULT_DEPTH,
+                maxNodes: FULL_MODE_MAX_NODES,
+                maxTextLength: FULL_MODE_MAX_TEXT_LENGTH,
+            };
+            const { tree, truncated } = await locator.evaluate(walkFullDom, caps);
+            return { ok: true, snapshot: { mode: "full", selector: opts.selector, truncated, tree } };
+        }
+        const tree = await locator.ariaSnapshotJSON(ariaOptions);
+        return { ok: true, snapshot: { mode: "aria", selector: opts.selector, truncated: false, tree } };
+    }
+    await showPilotActivity(page, `Running (Dom): ${mode}, whole page`);
+    if (mode === "full") {
+        // page.evaluate only ships the one function passed to it - it can't
+        // reach another named function by closure. Routing the whole-page case
+        // through the same `html` Locator lets both cases share one
+        // self-contained walkFullDom instead of two near-duplicate callbacks.
+        const caps = {
+            depth: opts.depth ?? FULL_MODE_DEFAULT_DEPTH,
+            maxNodes: FULL_MODE_MAX_NODES,
+            maxTextLength: FULL_MODE_MAX_TEXT_LENGTH,
+        };
+        const { tree, truncated } = await page.locator("html").first().evaluate(walkFullDom, caps);
+        return { ok: true, snapshot: { mode: "full", truncated, tree } };
+    }
+    const tree = await page.ariaSnapshotJSON(ariaOptions);
+    return { ok: true, snapshot: { mode: "aria", truncated: false, tree } };
+}
+export async function inspectStorage(page, context) {
+    const [localStorageEntries, sessionStorageEntries] = await page.evaluate(() => [
+        Object.entries(window.localStorage),
+        Object.entries(window.sessionStorage),
+    ]);
+    const cookies = await context.cookies();
+    const workers = context.serviceWorkers();
+    const registrations = await page
+        .evaluate(async () => {
+        if (!("serviceWorker" in navigator))
+            return [];
+        const regs = await navigator.serviceWorker.getRegistrations();
+        return regs.map((r) => ({
+            scope: r.scope,
+            ...(r.active?.scriptURL ? { activeUrl: r.active.scriptURL } : {}),
+            ...(r.active?.state ? { state: r.active.state } : {}),
+        }));
+    })
+        .catch(ignorePageGone);
+    return {
+        localStorage: Object.fromEntries(localStorageEntries),
+        sessionStorage: Object.fromEntries(sessionStorageEntries),
+        cookies: cookies.map((c) => ({
+            name: c.name,
+            value: c.value,
+            domain: c.domain,
+            path: c.path,
+            httpOnly: c.httpOnly,
+            secure: c.secure,
+        })),
+        serviceWorkers: workers.map((w) => w.url()),
+        serviceWorkerRegistrations: registrations ?? [],
+    };
+}

package/dist/live/auto-session/ipc.d.ts

@@ -1,14 +1,7 @@
-import { AutoSession } from "./auto-session.js";
-import { type AutoSessionInit, type SessionSnapshot, type InspectDomOptions, type DomSnapshot, type TraceStep, type ApplyPathResult, type ConsoleLogEntry, type StorageSnapshot, type StubFileKind } from "./helpers.js";
 import type { PilotHighlightFixtures } from "../../demo/overlay/pilot/fixtures.js";
-export interface SessionMeta {
-    sessionId: string;
-    socketPath: string;
-    pid: number;
-    projectDir: string;
-    startedAt: string;
-    headless: boolean;
-}
+import { AutoSession } from "./auto-session.js";
+import { SessionMeta } from "./files.js";
+import { type ApplyPathResult, type AutoSessionInit, type ConsoleLogEntry, type DomSnapshot, type InspectDomOptions, type SessionSnapshot, type StorageSnapshot, type StubFileKind, type TraceStep } from "./helpers.js";
 export type StatusOrSendResponse = {
     ok: true;
     snapshot: SessionSnapshot;
@@ -54,12 +47,6 @@ export type HighlightResponse = {
     ok: false;
     error: string;
 };
-/**
- * Resolve session metadata from a project hint (cwd) or the global registry.
- * Fixes "session unreachable" when the agent calls status/send from a different
- * directory or pane than the one that ran `pilot start`.
- */
-export declare function resolveSessionMeta(sessionId: string, projectDirHint?: string): SessionMeta | null;
 /**
  * Client-side: sends one request to a running session and returns its
  * response. Reports a stale/unreachable session as an error within
@@ -137,12 +124,6 @@ export declare function runAutoServeCommand(init: AutoSessionInit, sessionId: st
  * than re-implementing that resolution here.
  */
 export declare function spawnDetachedSession(init: AutoSessionInit, readyTimeoutMs?: number): Promise<SessionMeta>;
-/** Stop one detached session (SIGTERM + cleanup metadata/socket). */
-export declare function stopBrowserSession(projectDir: string, sessionId: string): boolean;
-/** Stop every live session registered for a project. */
-export declare function stopAllBrowserSessions(projectDir: string): number;
-/** Live browser sessions for a project (metadata + socket + pid still present). */
-export declare function listBrowserSessions(projectDir: string): SessionMeta[];
 /**
  * Client-only interactive loop against a running detached session - reopens
  * the same rendering/parsing the foreground `--cli` loop uses, driven purely

package/dist/live/auto-session/ipc.js

@@ -4,112 +4,17 @@
  * directory, mirroring the existing `.waygraph-traverse/` dotdir convention.
  * See openspec/changes/waygraph-auto-cli-session-control.
  */
-import { createServer, connect } from "node:net";
 import { spawn } from "node:child_process";
+import { mkdirSync, openSync, rmSync, writeFileSync, } from "node:fs";
 import { createRequire } from "node:module";
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, rmSync, openSync, } from "node:fs";
-import { join, dirname } from "node:path";
-import { tmpdir } from "node:os";
-import { fileURLToPath } from "node:url";
-import { randomBytes } from "node:crypto";
-import { createInterface } from "node:readline/promises";
+import { connect, createServer } from "node:net";
+import { dirname, join } from "node:path";
 import { stdin as input, stdout as output } from "node:process";
-import { AutoSession } from "./auto-session.js";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
 import { ignorePageGone } from "../../engine/page-gone.js";
-function sessionDir(projectDir) {
-    return join(projectDir, ".waygraph-auto");
-}
-function metaPath(projectDir, sessionId) {
-    return join(sessionDir(projectDir), `${sessionId}.json`);
-}
-/** Global index so session control works even when cwd ≠ the project that spawned the session. */
-function globalMetaPath(sessionId) {
-    return join(socketDir(), `${sessionId}.meta.json`);
-}
-function isPidAlive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Deliberately NOT under the project directory (unlike meta/log files) -
- * a real bug found while proving out openspec/changes/waygraph-map's own
- * "waypack" loading claim: a project loaded through a consumer's own deeply
- * nested `node_modules/<pkg>` path can push the socket's absolute path past
- * the OS's AF_UNIX `sun_path` limit (~108 bytes on Linux), failing with
- * `listen EINVAL`. A short, fixed-location directory sidesteps this
- * regardless of how deep `projectDir` itself is nested. `sessionId` alone
- * (8 hex chars, `generateSessionId()`) is enough to keep this collision-safe
- * across every project on the machine sharing this one flat directory - the
- * same randomness space this package already relied on per-project.
- */
-function socketDir() {
-    return join(tmpdir(), "waygraph-auto");
-}
-function socketPathFor(sessionId) {
-    return join(socketDir(), `${sessionId}.sock`);
-}
-function logPathFor(projectDir, sessionId) {
-    return join(sessionDir(projectDir), `${sessionId}.log`);
-}
-function generateSessionId() {
-    return randomBytes(4).toString("hex");
-}
-function readSessionMeta(projectDir, sessionId) {
-    const p = metaPath(projectDir, sessionId);
-    if (!existsSync(p))
-        return null;
-    try {
-        return JSON.parse(readFileSync(p, "utf-8"));
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Resolve session metadata from a project hint (cwd) or the global registry.
- * Fixes "session unreachable" when the agent calls status/send from a different
- * directory or pane than the one that ran `pilot start`.
- */
-export function resolveSessionMeta(sessionId, projectDirHint) {
-    if (projectDirHint) {
-        const local = readSessionMeta(projectDirHint, sessionId);
-        if (local)
-            return local;
-    }
-    const globalPath = globalMetaPath(sessionId);
-    if (existsSync(globalPath)) {
-        try {
-            return JSON.parse(readFileSync(globalPath, "utf-8"));
-        }
-        catch {
-            return null;
-        }
-    }
-    return null;
-}
-function writeGlobalSessionMeta(meta) {
-    mkdirSync(socketDir(), { recursive: true });
-    writeFileSync(globalMetaPath(meta.sessionId), JSON.stringify(meta, null, 2));
-}
-function removeSessionFiles(projectDir, sessionId) {
-    for (const p of [
-        metaPath(projectDir, sessionId),
-        globalMetaPath(sessionId),
-        socketPathFor(sessionId),
-    ]) {
-        try {
-            rmSync(p, { force: true });
-        }
-        catch {
-            /* ignore */
-        }
-    }
-}
+import { AutoSession } from "./auto-session.js";
+import { generateSessionId, isPidAlive, logPathFor, metaPath, readSessionMeta, removeSessionFiles, resolveSessionMeta, sessionDir, socketDir, socketPathFor, writeGlobalSessionMeta } from "./files.js";
 /** Reads newline-delimited JSON off a socket, one message at a time. */
 function readOneMessage(sock, timeoutMs) {
     return new Promise((resolvePromise, reject) => {
@@ -412,51 +317,6 @@ export async function spawnDetachedSession(init, readyTimeoutMs = 20_000) {
         throw new Error(`session "${sessionId}" said it was ready but wrote no metadata - check ${log}`);
     return meta;
 }
-/** Stop one detached session (SIGTERM + cleanup metadata/socket). */
-export function stopBrowserSession(projectDir, sessionId) {
-    const meta = resolveSessionMeta(sessionId, projectDir);
-    if (!meta)
-        return false;
-    try {
-        process.kill(meta.pid, "SIGTERM");
-    }
-    catch {
-        /* already gone */
-    }
-    removeSessionFiles(meta.projectDir, sessionId);
-    return true;
-}
-/** Stop every live session registered for a project. */
-export function stopAllBrowserSessions(projectDir) {
-    const sessions = listBrowserSessions(projectDir);
-    for (const meta of sessions) {
-        stopBrowserSession(meta.projectDir, meta.sessionId);
-    }
-    return sessions.length;
-}
-/** Live browser sessions for a project (metadata + socket + pid still present). */
-export function listBrowserSessions(projectDir) {
-    const dir = sessionDir(projectDir);
-    if (!existsSync(dir))
-        return [];
-    const out = [];
-    for (const f of readdirSync(dir)) {
-        if (!f.endsWith(".json"))
-            continue;
-        const id = f.slice(0, -".json".length);
-        const meta = readSessionMeta(projectDir, id);
-        if (!meta)
-            continue;
-        if (!existsSync(socketPathFor(id)))
-            continue;
-        if (!isPidAlive(meta.pid)) {
-            removeSessionFiles(projectDir, id);
-            continue;
-        }
-        out.push(meta);
-    }
-    return out.sort((a, b) => a.startedAt.localeCompare(b.startedAt));
-}
 function printSnapshotMenu(snapshot) {
     console.log("");
     console.log(`You are here: ${snapshot.here ?? "Unknown (pick Start here)"}`);

package/dist/live/auto-session/open-browser.d.ts

@@ -0,0 +1,6 @@
+import type { BrowserContext, Page } from "@playwright/test";
+export declare function openSessionBrowser(projectDir: string, headless: boolean, baseURL: string | undefined, startUrl: string | undefined): Promise<{
+    closeBrowser: () => Promise<void>;
+    context: BrowserContext;
+    page: Page;
+}>;

package/dist/live/auto-session/open-browser.js

@@ -0,0 +1,47 @@
+import { instrumentPilotActions } from "../../demo/overlay/pilot/actions.js";
+import { installPersistentPilotOverlay } from "../../demo/overlay/pilot/shell.js";
+import { ignorePageGone, ignoreTimeout } from "../../engine/page-gone.js";
+import { chromiumExecutablePath, launchContext } from "../../runtime/browser.js";
+import { configuredExtensions } from "../../runtime/waygraph-config.js";
+export async function openSessionBrowser(projectDir, headless, baseURL, startUrl) {
+    const { chromium } = await import("@playwright/test");
+    const executablePath = chromiumExecutablePath();
+    // Real gap found live: a headed (--non-headless) session kept a fixed
+    // 1280x720 content area even when the user maximized/fullscreened the
+    // actual window - `viewport: null` alone only makes the PAGE track the
+    // window; the window itself still launches at Chromium's own small
+    // default size unless told to start maximized. Same fix cli.ts's own
+    // --step/headed launch already uses (see its own comment there) -
+    // headless keeps the fixed viewport since there's no real window to size.
+    const launchOpts = {
+        headless,
+        // Keep Playwright's default --no-startup-window for headful: without it
+        // Chromium opens its own "New Tab" window AND our context.newPage() opens
+        // a second about:blank window. bringToFront() below surfaces the real page.
+        args: headless ? [] : ["--start-maximized"],
+    };
+    if (executablePath)
+        launchOpts.executablePath = executablePath;
+    const contextOpts = {
+        viewport: headless ? { width: 1280, height: 720 } : null,
+    };
+    if (baseURL)
+        contextOpts.baseURL = baseURL;
+    const { close: closeBrowser, context } = await launchContext({
+        launcher: chromium,
+        launch: launchOpts,
+        context: contextOpts,
+        extensions: await configuredExtensions(projectDir),
+    });
+    await installPersistentPilotOverlay(context);
+    const page = await context.newPage();
+    instrumentPilotActions(page, headless ? 0 : 450);
+    if (startUrl) {
+        await page.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(ignorePageGone);
+        await page.waitForLoadState("load").catch(ignoreTimeout);
+    }
+    else {
+        await page.goto("about:blank").catch(ignorePageGone);
+    }
+    return { closeBrowser, context, page };
+}

package/dist/live/pilot/pilot.d.ts

@@ -29,8 +29,8 @@
  * new execution primitive.
  */
 import { type WaygraphGraph } from "../../analysis/graph.js";
-import { type BrowserStartInit } from "../auto-session/start.js";
 import type { SessionSnapshot } from "../auto-session/helpers.js";
+import { type BrowserStartInit } from "../auto-session/start.js";
 /** What `pilotStart` returns: the session id, socket path and first snapshot. */
 export interface PilotStartResult {
     sessionId: string;

package/dist/live/pilot/pilot.js

@@ -29,7 +29,8 @@
  * new execution primitive.
  */
 import { discoverGraph } from "../../analysis/graph.js";
-import { requestSession, resolveSessionMeta, } from "../auto-session/ipc.js";
+import { resolveSessionMeta } from "../auto-session/files.js";
+import { requestSession, } from "../auto-session/ipc.js";
 import { browserStart } from "../auto-session/start.js";
 /**
  * Starts a detached session and reads back its own graph + starting