waygraph 0.15.54 → 0.16.1

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/{auto-session → live/auto-session}/helpers.d.ts

@@ -1,6 +1,8 @@
-import type { StubPhaseResult } from "../highlights.js";
-import type { BlockEntry, ExploreMenu } from "../session/auto-explore.js";
-import type { PickResult } from "../session/auto-explore-run.js";
+import type { PilotHighlightFixtures } from "../../demo/overlay/pilot/fixtures.js";
+import type { StubPhaseResult } from "../../engine/stub/stub.js";
+import type { BlockEntry } from "../../manifest/project.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. */
@@ -90,7 +92,7 @@ export interface AutoSessionInit {
     projectDir: string;
     baseURL?: string;
     startUrl?: string;
-    blocksSelect?: import("../blocks-select.js").BlocksSelect;
+    blocksSelect?: import("../../manifest/select.js").BlocksSelect;
     /** Absolute paths — merged Block libraries (see `waygraph browser --inject`). */
     inject?: string[];
     /** When true, open about:blank instead of baseURL/startUrl (browser default). */
@@ -139,7 +141,7 @@ export interface TraceStep {
      * Resolved demo-narration fixtures (highlights/todos/device), when the
      * Block actually authors `stubBefore`/`stubAfter`/`stubOnError` - the same
      * data `waygraph demo`'s lifecycle logging already computes (`runStubPhase`
-     * in highlights.ts), reused here for extra context on what a step meant to
+     * in demo/narration/index.ts), reused here for extra context on what a step meant to
      * convey. Omitted when the Block has none, or the result carries nothing.
      */
     stubBefore?: StubPhaseResult;
@@ -210,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/{auto-session → 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. */
@@ -137,7 +138,7 @@ export const TRACE_MAX_STEPS = 500;
  * exist for more than a moment.
  */
 export function stubFilePath(kind) {
-    const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+    const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
     const names = {
         image: "stub.png",
         pdf: "stub.pdf",
@@ -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/{session/auto-session-ipc.d.ts → live/auto-session/ipc.d.ts}

@@ -1,14 +1,7 @@
-import { AutoSession, type AutoSessionInit, type SessionSnapshot, type InspectDomOptions, type DomSnapshot, type TraceStep, type ApplyPathResult, type ConsoleLogEntry, type StorageSnapshot, type StubFileKind } from "../auto-session.js";
-import type { PilotHighlightFixtures } from "../pilot-overlay.js";
-export type { PilotHighlightFixtures } from "../pilot-overlay.js";
-export interface SessionMeta {
-    sessionId: string;
-    socketPath: string;
-    pid: number;
-    projectDir: string;
-    startedAt: string;
-    headless: boolean;
-}
+import type { PilotHighlightFixtures } from "../../demo/overlay/pilot/fixtures.js";
+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
@@ -128,19 +115,15 @@ export declare function serveSession(session: AutoSession, projectDir: string, s
 export declare function runAutoServeCommand(init: AutoSessionInit, sessionId: string): Promise<void>;
 /**
  * Parent-side: spawns a detached background process running the same
- * explore session as a socket server, waits for it to signal readiness (its
- * metadata file appearing), and returns its identity. Recurses through the
+ * explore session as a socket server, waits for it to say it is serving (one
+ * message over an IPC channel, then disconnect), and returns its identity. A
+ * child that exits or stays silent past the timeout fails the start, and a silent
+ * one is stopped. Recurses through the
  * existing `bin/waygraph` launcher (same tsx/esm registration every other
  * invocation already gets) with the hidden `__auto-serve` command, rather
  * 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/{session/auto-session-ipc.js → live/auto-session/ipc.js}

@@ -4,111 +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";
-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 { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+import { ignorePageGone } from "../../engine/page-gone.js";
+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) => {
@@ -318,7 +224,7 @@ export async function serveSession(session, projectDir, sessionId, headless = tr
             return;
         shuttingDown = true;
         server.close();
-        await session.close().catch(() => { });
+        await session.close().catch(ignorePageGone);
         removeSessionFiles(projectDir, sessionId);
         process.exit(0);
     }
@@ -343,14 +249,19 @@ export async function serveSession(session, projectDir, sessionId, headless = tr
 export async function runAutoServeCommand(init, sessionId) {
     const session = await AutoSession.start({ ...init, sessionId });
     await serveSession(session, init.projectDir, sessionId, init.headless ?? true);
+    // Tell the parent that spawned us (spawnDetachedSession) we are serving, then let it go.
+    process.send?.({ ready: true });
+    process.disconnect?.();
     // Keep the event loop alive - the listening server already does this,
     // but await forever here documents the intent for a reader.
     await new Promise(() => { });
 }
 /**
  * Parent-side: spawns a detached background process running the same
- * explore session as a socket server, waits for it to signal readiness (its
- * metadata file appearing), and returns its identity. Recurses through the
+ * explore session as a socket server, waits for it to say it is serving (one
+ * message over an IPC channel, then disconnect), and returns its identity. A
+ * child that exits or stays silent past the timeout fails the start, and a silent
+ * one is stopped. Recurses through the
  * existing `bin/waygraph` launcher (same tsx/esm registration every other
  * invocation already gets) with the hidden `__auto-serve` command, rather
  * than re-implementing that resolution here.
@@ -358,12 +269,12 @@ export async function runAutoServeCommand(init, sessionId) {
 export async function spawnDetachedSession(init, readyTimeoutMs = 20_000) {
     const sessionId = generateSessionId();
     mkdirSync(sessionDir(init.projectDir), { recursive: true });
-    // This file compiles to dist/session/auto-session-ipc.js - two levels down from the package
+    // This file compiles to dist/live/auto-session/ipc.js - three levels down from the package
     // root, not one. Same bug class as cli/util.ts's own packageRoot(); see its comment.
-    const pkgRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+    const pkgRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
     const require = createRequire(join(pkgRoot, "package.json"));
     const tsxEsm = require.resolve("tsx/esm");
-    const cli = join(pkgRoot, "dist", "cli.js");
+    const cli = join(pkgRoot, "dist", "cli", "cli.js");
     const logFd = openSync(logPathFor(init.projectDir, sessionId), "a");
     const args = ["--import", tsxEsm, cli, "__auto-serve", init.projectDir, "--session-id", sessionId];
     if (init.baseURL)
@@ -382,65 +293,29 @@ export async function spawnDetachedSession(init, readyTimeoutMs = 20_000) {
     // Spawn cli.js directly — not bin/waygraph (which would fork a second Node).
     const child = spawn(process.execPath, args, {
         detached: true,
-        stdio: ["ignore", logFd, logFd],
+        stdio: ["ignore", logFd, logFd, "ipc"],
         windowsHide: true,
         env: process.env,
     });
+    const log = logPathFor(init.projectDir, sessionId);
+    const outcome = await new Promise((done) => {
+        const timer = setTimeout(() => done("timeout"), readyTimeoutMs);
+        child.once("message", () => (clearTimeout(timer), done("ready")));
+        child.once("exit", (code) => (clearTimeout(timer), done({ exit: code })));
+    });
+    if (child.connected)
+        child.disconnect();
     child.unref();
-    const deadline = Date.now() + readyTimeoutMs;
-    while (Date.now() < deadline) {
-        const meta = readSessionMeta(init.projectDir, sessionId);
-        if (meta)
-            return meta;
-        await new Promise((r) => setTimeout(r, 150));
+    if (outcome === "timeout") {
+        child.kill("SIGTERM");
+        throw new Error(`session "${sessionId}" did not become ready within ${readyTimeoutMs}ms (stopped it) - check ${log} for errors`);
     }
-    throw new Error(`session "${sessionId}" did not become ready within ${readyTimeoutMs}ms - ` +
-        `check ${logPathFor(init.projectDir, sessionId)} for errors`);
-}
-/** Stop one detached session (SIGTERM + cleanup metadata/socket). */
-export function stopBrowserSession(projectDir, sessionId) {
-    const meta = resolveSessionMeta(sessionId, projectDir);
+    if (outcome !== "ready")
+        throw new Error(`session "${sessionId}" exited (code ${outcome.exit}) before it was ready - check ${log}`);
+    const meta = readSessionMeta(init.projectDir, sessionId);
     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));
+        throw new Error(`session "${sessionId}" said it was ready but wrote no metadata - check ${log}`);
+    return meta;
 }
 function printSnapshotMenu(snapshot) {
     console.log("");

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 };
+}