waygraph 0.16.2 → 0.16.4

package/dist/index.js

@@ -1,7 +1,9 @@
-// The runtime layer supplies how an Engine launches its own browser (config, Chromium path, extensions).
-import "./runtime/full-launch.js";
-// Run events are written to the project's run log (.waygraph/runs) when the CLI turns it on.
-import "./runtime/run-log.js";
+import { installFullLaunch } from "./runtime/full-launch.js";
+import { installRunLog } from "./runtime/run-log.js";
+// The package entry wires the runtime in, explicitly: how an Engine launches its own browser (config, Chromium path,
+// extensions), and the run log (.waygraph/runs) the CLI turns on. No module switches itself on by being imported.
+installFullLaunch();
+installRunLog();
 export { connect } from "./engine/run/connect.js";
 export { checkpoint } from "./engine/checkpoint/checkpoint.js";
 export { MemKey, MemPage, key, keyGroup } from "./engine/mem/mem.js";
@@ -39,6 +41,9 @@ export { runTraverse } from "./live/traverse/traverse.js";
 export { buildCoverageReport, collectGraphEdgeKeys, defaultCoverageOutPath, formatCoverageLine, normalizeHitKey, parseMinEdgeCoverage, writeCoverageReport } from "./live/traverse/coverage.js";
 export { WG_UI_SEL, WG_READY_PANEL_SEL, WG_READY_AUTO_SEL, WG_READY_BANNER_SEL, readWgOverlayBeacon, readWgOverlayBeaconInPage, assertWgOverlayReady } from "./demo/overlay/beacon.js";
 export { AutoSession } from "./live/auto-session/auto-session.js";
+export { SESSION_OPS, SESSION_PROTOCOL_VERSION } from "./live/auto-session/protocol.js";
+export { subscribeSession } from "./live/auto-session/feed.js";
+export { requestSession } from "./live/auto-session/ipc.js";
 export { stubFilePath } from "./live/auto-session/helpers.js";
 export { pilotStart } from "./live/pilot/pilot.js";
 export { defineConfig, resolveBaseUrl } from "./runtime/waygraph-config.js";

package/dist/live/auto/auto.js

@@ -61,8 +61,6 @@ export async function runOneBlock(engine, entry, context, page, mem, headful) {
     await page.evaluate("delete window.__wgPendingNavClickLabel").catch(ignorePageGone);
     return result;
 }
-/** Shown in the headful panel after each Block run. */
-let lastRunNote = null;
 /**
  * Interactive waygraph auto: locate current Checkpoint, list runnable Blocks, pick one, repeat.
  */
@@ -70,7 +68,8 @@ export async function runAutoExplore(projectDir, options = {}) {
     await withWebServer(projectDir, () => runAutoExploreCore(projectDir, options));
 }
 async function runAutoExploreCore(projectDir, options = {}) {
-    lastRunNote = null;
+    /** Shown in the headful panel after each Block run. */
+    let lastRunNote = null;
     const cli = options.cli === true;
     const baseURL = options.baseURL ?? (await resolveBaseUrl(projectDir)) ?? envString("WAYGRAPH_BASE_URL");
     const startUrl = options.startUrl ?? baseURL;

package/dist/live/auto/menu.js

@@ -27,8 +27,9 @@ export async function setAutoPanelRunning(page, label) {
     }, label)
         .catch(ignorePageGone);
 }
-export const PANEL_CSS = "#wg-auto-panel{position:fixed;z-index:2147483647;left:50%;bottom:12px;transform:translateX(-50%);" +
-    "max-width:min(92vw,720px);max-height:calc(100vh - 24px);overflow-y:auto;box-sizing:border-box;" +
+// In the bottom-center slot of the overlay layout (demo/overlay/ui/css/layout.css), like the demo's step panel.
+export const PANEL_CSS = "#wg-auto-panel{z-index:var(--wg-z-top);" +
+    "width:min(92vw,720px);overflow-y:auto;box-sizing:border-box;" +
     "background:rgba(20,10,40,.94);color:#fff;border-radius:14px;padding:16px 20px;" +
     "font:14px/1.4 system-ui,sans-serif;box-shadow:0 12px 30px rgba(0,0,0,.35);}" +
     "#wg-auto-panel h3{margin:0 0 10px;font-size:16px;}" +

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

@@ -1,5 +1,6 @@
 import type { PilotHighlightFixtures } from "../../demo/overlay/pilot/fixtures.js";
 import type { ApplyPathResult, ApplyPickResult, AutoSessionInit, ConsoleLogEntry, InspectDomOptions, InspectDomResult, SessionSnapshot, StorageSnapshot, StubFileKind, TraceStep } from "./helpers.js";
+import { type SessionRead } from "./read.js";
 /**
  * A live session driven over IPC (`browser start`, `pilot start`): the same graph, library, mem and browser as
  * `waygraph auto`, moved one call at a time (`applyPick`, `applyPath`, the raw actions) instead of a menu loop.
@@ -17,12 +18,12 @@ export declare class AutoSession {
     private page;
     private readonly startUrl;
     private readonly sessionId;
+    private readonly knownInteractionSelectors;
+    private readonly headless;
     private here;
     private lastRunNote;
     private readonly trace;
     private readonly consoleLog;
-    private readonly knownInteractionSelectors;
-    private readonly headless;
     private lastOverlayInfo;
     private constructor();
     static start(init: AutoSessionInit): Promise<AutoSession>;
@@ -43,8 +44,14 @@ export declare class AutoSession {
      * Deduped per page load so repeated status/send calls stay quiet.
      */
     private warnUnmappedInteractions;
+    /** The Checkpoint the session is at, if known. */
+    get where(): string | null;
     /** Pure getter - no Block runs, no mem/page mutation. */
     currentSnapshot(): Promise<SessionSnapshot>;
+    /** The menu as a snapshot, with what the page shows (Read Blocks) when any covers it. */
+    private snapshotOf;
+    /** Pure getter - what the page shows, from the project's Read Blocks (beta). */
+    read(path?: string): Promise<SessionRead>;
     /**
      * Pure getter - reads the live page's structure at the requested fidelity.
      * No Block runs, no mem/page mutation. `selector` scopes either mode to one

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

@@ -3,7 +3,7 @@ import { findBlockPathDetailed } from "../../analysis/graph.js";
 import { runStubPhase } from "../../demo/narration/narration.js";
 import { describeOverlayFixtures, phaseToOverlayFixtures } from "../../demo/overlay/phase-fixtures.js";
 import { showPilotFixtures } from "../../demo/overlay/pilot/fixtures.js";
-import { showPilotActivity, showPilotVision } from "../../demo/overlay/pilot/shell.js";
+import { showPilotActivity } from "../../demo/overlay/pilot/shell.js";
 import { keepOverlayOnNavigation } from "../../demo/overlay/reattach.js";
 import { verboseLog } from "../../demo/verbose-log.js";
 import { Engine } from "../../engine/engine.js";
@@ -15,17 +15,10 @@ import { buildExploreContext, buildExploreMenu } from "../auto/explore.js";
 import { ensureMem, seedDefaultMem } from "../auto/mem.js";
 import { updatePilotOverlay } from "../pilot/panel.js";
 import { recordPageConsole } from "./console.js";
-import { CONSOLE_LOG_MAX_ENTRIES, TRACE_MAX_STEPS, buildSessionSnapshot, describeHighlight, parsePick, stubFilePath, stubPhaseHasContent } from "./helpers.js";
+import { CONSOLE_LOG_MAX_ENTRIES, TRACE_MAX_STEPS, buildSessionSnapshot, describeHighlight, parsePick, rawTarget, stubFilePath, stubPhaseHasContent } from "./helpers.js";
 import { inspectDom, inspectStorage } from "./inspect.js";
 import { openSessionBrowser } from "./open-browser.js";
-/** The first element `selector` matches, ringed with the pilot's vision ring; or why there is none. */
-async function rawTarget(page, selector, label) {
-    const locator = page.locator(selector).first();
-    if ((await locator.count()) === 0)
-        return `no element matches selector "${selector}"`;
-    await showPilotVision(page, selector, label);
-    return locator;
-}
+import { readSession, snapshotRead } from "./read.js";
 /**
  * A live session driven over IPC (`browser start`, `pilot start`): the same graph, library, mem and browser as
  * `waygraph auto`, moved one call at a time (`applyPick`, `applyPath`, the raw actions) instead of a menu loop.
@@ -43,12 +36,12 @@ export class AutoSession {
     page;
     startUrl;
     sessionId;
+    knownInteractionSelectors;
+    headless;
     here = null;
     lastRunNote = null;
     trace = [];
     consoleLog = [];
-    knownInteractionSelectors;
-    headless;
     lastOverlayInfo = null;
     constructor(projectDir, inject, blocksSelect, graph, library, mem, engine, closeBrowser, context, page, startUrl, sessionId, knownInteractionSelectors, headless) {
         this.projectDir = projectDir;
@@ -118,7 +111,7 @@ export class AutoSession {
         // watching sees the state an API caller just got back, not a frame behind.
         this.lastOverlayInfo = {
             sessionId: this.sessionId,
-            snapshot: buildSessionSnapshot(menu, this.library.byName, this.here, this.lastRunNote),
+            snapshot: await this.snapshotOf(menu),
             graph: this.graph,
         };
         await updatePilotOverlay(this.page, this.lastOverlayInfo);
@@ -163,10 +156,20 @@ export class AutoSession {
         };
         await this.page.evaluate(unmappedInteractionsPageScript, payload).catch(ignorePageGone);
     }
+    /** The Checkpoint the session is at, if known. */
+    get where() { return this.here; }
     /** Pure getter - no Block runs, no mem/page mutation. */
     async currentSnapshot() {
-        const menu = await this.currentMenu();
-        return buildSessionSnapshot(menu, this.library.byName, this.here, this.lastRunNote);
+        return this.snapshotOf(await this.currentMenu());
+    }
+    /** The menu as a snapshot, with what the page shows (Read Blocks) when any covers it. */
+    async snapshotOf(menu) {
+        return { ...buildSessionSnapshot(menu, this.library.byName, this.here, this.lastRunNote), ...(await snapshotRead(this.page, this.mem, this.here)) };
+    }
+    /** Pure getter - what the page shows, from the project's Read Blocks (beta). */
+    async read(path) {
+        this.page = await ensureLivePage(this.context, this.page, this.startUrl);
+        return readSession(this.page, this.mem, this.here, path);
     }
     /**
      * Pure getter - reads the live page's structure at the requested fidelity.
@@ -238,7 +241,7 @@ export class AutoSession {
         const nextMenu = await this.currentMenu();
         return {
             ok: true,
-            snapshot: buildSessionSnapshot(nextMenu, this.library.byName, this.here, this.lastRunNote),
+            snapshot: await this.snapshotOf(nextMenu),
             quit: false,
         };
     }
@@ -251,7 +254,7 @@ export class AutoSession {
         if (pick.type === "quit") {
             return {
                 ok: true,
-                snapshot: buildSessionSnapshot(menu, this.library.byName, this.here, this.lastRunNote),
+                snapshot: await this.snapshotOf(menu),
                 quit: true,
             };
         }
@@ -292,7 +295,7 @@ export class AutoSession {
         this.lastRunNote = `resync -> ${this.here ?? "Unknown"}`;
         return {
             ok: true,
-            snapshot: buildSessionSnapshot(menu, this.library.byName, this.here, this.lastRunNote),
+            snapshot: await this.snapshotOf(menu),
             quit: false,
         };
     }
@@ -363,7 +366,7 @@ export class AutoSession {
         this.lastRunNote = `${what} -> ${this.here ?? "Unknown"}`;
         return {
             ok: true,
-            snapshot: buildSessionSnapshot(menu, this.library.byName, this.here, this.lastRunNote),
+            snapshot: await this.snapshotOf(menu),
             quit: false,
         };
     }
@@ -390,7 +393,7 @@ export class AutoSession {
                 ok: true,
                 painted,
                 missing,
-                snapshot: buildSessionSnapshot(menu, this.library.byName, this.here, this.lastRunNote),
+                snapshot: await this.snapshotOf(menu),
             };
         }
         catch (err) {

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

@@ -0,0 +1,16 @@
+import { type Socket } from "node:net";
+import type { SessionStreamMessage } from "./protocol.js";
+/** The server side: subscribed sockets, fed every run event in this process until `close`. */
+export declare function createFeed(): {
+    add(sock: Socket): void;
+    send(message: SessionStreamMessage): void;
+    close(): void;
+};
+/**
+ * The client side: subscribes to a running session and calls `onMessage` for each line until `close()` (or the session
+ * ends). Rejects when the session is unknown or does not answer the subscribe.
+ */
+export declare function subscribeSession(projectDir: string, sessionId: string, onMessage: (message: SessionStreamMessage) => void, timeoutMs?: number): Promise<{
+    close(): void;
+    closed: Promise<void>;
+}>;

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

@@ -0,0 +1,71 @@
+// A session's live feed (`subscribe`): every run event in the session (steps, reads) and the snapshot after each change,
+// as JSON lines to every subscribed socket. Waygraph UI watches a session through it; `pilot watch <id>` prints it.
+import { connect } from "node:net";
+import { onRunEvent } from "../../engine/run/events.js";
+import { resolveSessionMeta } from "./files.js";
+import { SESSION_PROTOCOL_VERSION } from "./protocol.js";
+/** The server side: subscribed sockets, fed every run event in this process until `close`. */
+export function createFeed() {
+    const subscribers = new Set();
+    const send = (message) => {
+        const line = JSON.stringify(message) + "\n";
+        for (const sock of subscribers)
+            if (!sock.destroyed)
+                sock.write(line);
+    };
+    const off = onRunEvent((event) => send({ type: "event", event }));
+    return {
+        add(sock) {
+            subscribers.add(sock);
+            sock.on("close", () => subscribers.delete(sock));
+            sock.write(JSON.stringify({ ok: true, protocol: SESSION_PROTOCOL_VERSION }) + "\n");
+        },
+        send,
+        close() {
+            off();
+            for (const sock of subscribers)
+                sock.end();
+            subscribers.clear();
+        },
+    };
+}
+/**
+ * The client side: subscribes to a running session and calls `onMessage` for each line until `close()` (or the session
+ * ends). Rejects when the session is unknown or does not answer the subscribe.
+ */
+export function subscribeSession(projectDir, sessionId, onMessage, timeoutMs = 15_000) {
+    const meta = resolveSessionMeta(sessionId, projectDir);
+    if (!meta)
+        return Promise.reject(new Error(`no such session "${sessionId}" - \`waygraph pilot sessions\` lists live ids`));
+    return new Promise((resolve, reject) => {
+        const sock = connect(meta.socketPath);
+        const timer = setTimeout(() => {
+            sock.destroy();
+            reject(new Error(`session "${sessionId}" did not answer subscribe within ${timeoutMs}ms`));
+        }, timeoutMs);
+        const closed = new Promise((done) => sock.on("close", () => done()));
+        let buf = "";
+        let acked = false;
+        sock.on("connect", () => sock.write(JSON.stringify({ op: "subscribe" }) + "\n"));
+        sock.on("error", (err) => {
+            clearTimeout(timer);
+            if (!acked)
+                reject(err);
+        });
+        sock.on("data", (chunk) => {
+            buf += chunk.toString("utf-8");
+            let nl;
+            while ((nl = buf.indexOf("\n")) !== -1) {
+                const line = buf.slice(0, nl);
+                buf = buf.slice(nl + 1);
+                if (!acked) {
+                    acked = true;
+                    clearTimeout(timer);
+                    resolve({ close: () => sock.end(), closed });
+                    continue;
+                }
+                onMessage(JSON.parse(line));
+            }
+        });
+    });
+}

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

@@ -1,3 +1,4 @@
+import type { Locator, Page } from "@playwright/test";
 import type { PilotHighlightFixtures } from "../../demo/overlay/pilot/fixtures.js";
 import type { StubPhaseResult } from "../../engine/stub/stub.js";
 import type { BlockEntry } from "../../manifest/project.js";
@@ -27,6 +28,10 @@ export interface SessionSnapshot {
     /** True when there are no runnable moves from `here` right now. */
     done: boolean;
     lastRunNote: string | null;
+    /** What the page shows, from the project's Read Blocks (beta); absent when none covers this page. */
+    read?: Record<string, unknown>;
+    missing?: string[];
+    readNotes?: Record<string, string>;
 }
 /** Plain, JSON-serializable view of a menu - no Block/MemKey/class references. */
 export declare function buildSessionSnapshot(menu: ExploreMenu, library: Map<string, BlockEntry>, here: string | null, lastRunNote: string | null): SessionSnapshot;
@@ -214,4 +219,6 @@ export interface StorageSnapshot {
 }
 /** What a highlight call paints, in a few words, for the session's activity line. */
 export declare function describeHighlight(fixtures: PilotHighlightFixtures): string;
+/** The first element `selector` matches, ringed with the pilot's vision ring; or why there is none. */
+export declare function rawTarget(page: Page, selector: string, label: string): Promise<Locator | string>;
 export {};

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

@@ -1,6 +1,7 @@
 // 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";
+import { showPilotVision } from "../../demo/overlay/pilot/shell.js";
 /** True when a stub-phase result actually carries authored content worth keeping. */
 export function stubPhaseHasContent(r) {
     return (Object.keys(r.highlights).length > 0 ||
@@ -163,3 +164,11 @@ export function describeHighlight(fixtures) {
         .filter(Boolean)
         .join(", ") || "fixtures");
 }
+/** The first element `selector` matches, ringed with the pilot's vision ring; or why there is none. */
+export async function rawTarget(page, selector, label) {
+    const locator = page.locator(selector).first();
+    if ((await locator.count()) === 0)
+        return `no element matches selector "${selector}"`;
+    await showPilotVision(page, selector, label);
+    return locator;
+}

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

@@ -1,52 +1,8 @@
 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;
-    quit: boolean;
-} | {
-    ok: false;
-    error: string;
-};
-export type DomResponse = {
-    ok: true;
-    snapshot: DomSnapshot;
-} | {
-    ok: false;
-    error: string;
-};
-export type TraceResponse = {
-    ok: true;
-    trace: TraceStep[];
-} | {
-    ok: false;
-    error: string;
-};
-export type ConsoleResponse = {
-    ok: true;
-    consoleLog: ConsoleLogEntry[];
-} | {
-    ok: false;
-    error: string;
-};
-export type StorageResponse = ({
-    ok: true;
-} & StorageSnapshot) | {
-    ok: false;
-    error: string;
-};
-export type ReachResponse = ApplyPathResult;
-export type HighlightResponse = {
-    ok: true;
-    painted: number;
-    missing: string[];
-    snapshot: SessionSnapshot;
-} | {
-    ok: false;
-    error: string;
-};
+import { type AutoSessionInit, type InspectDomOptions, type StubFileKind } from "./helpers.js";
+import type { HelloResponse, ConsoleResponse, DomResponse, HighlightResponse, ReachResponse, ReadResponse, StatusOrSendResponse, StorageResponse, TraceResponse } from "./protocol.js";
 /**
  * Client-side: sends one request to a running session and returns its
  * response. Reports a stale/unreachable session as an error within
@@ -94,6 +50,16 @@ export declare function requestSession(projectDir: string, sessionId: string, re
 export declare function requestSession(projectDir: string, sessionId: string, request: {
     op: "storage";
 }, timeoutMs?: number): Promise<StorageResponse>;
+export declare function requestSession(projectDir: string, sessionId: string, request: {
+    op: "hello";
+}, timeoutMs?: number): Promise<HelloResponse | {
+    ok: false;
+    error: string;
+}>;
+export declare function requestSession(projectDir: string, sessionId: string, request: {
+    op: "read";
+    path?: string;
+}, timeoutMs?: number): Promise<ReadResponse>;
 export declare function requestSession(projectDir: string, sessionId: string, request: {
     op: "reach";
     checkpoint: string;
@@ -110,7 +76,9 @@ export declare function requestSession(projectDir: string, sessionId: string, re
  * already prevents true parallelism, but two overlapping `await`-heavy
  * handlers could still interleave against the same page/mem.
  */
-export declare function serveSession(session: AutoSession, projectDir: string, sessionId: string, headless?: boolean): Promise<void>;
+export declare function serveSession(session: AutoSession, projectDir: string, sessionId: string, headless?: boolean, 
+/** After a quit closed the session and removed its files: the session process exits here. */
+onShutdown?: () => void): Promise<void>;
 /** Entry point for the hidden `__auto-serve` CLI command (runs in the detached child). */
 export declare function runAutoServeCommand(init: AutoSessionInit, sessionId: string): Promise<void>;
 /**

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

@@ -5,7 +5,7 @@
  * See openspec/changes/waygraph-auto-cli-session-control.
  */
 import { spawn } from "node:child_process";
-import { mkdirSync, openSync, rmSync, writeFileSync, } from "node:fs";
+import { mkdirSync, openSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
 import { createRequire } from "node:module";
 import { connect, createServer } from "node:net";
 import { dirname, join } from "node:path";
@@ -15,6 +15,8 @@ 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";
+import { createFeed } from "./feed.js";
+import { SESSION_PROTOCOL_VERSION } from "./protocol.js";
 /** Reads newline-delimited JSON off a socket, one message at a time. */
 function readOneMessage(sock, timeoutMs) {
     return new Promise((resolvePromise, reject) => {
@@ -109,7 +111,9 @@ export async function requestSession(projectDir, sessionId, request, timeoutMs =
  * already prevents true parallelism, but two overlapping `await`-heavy
  * handlers could still interleave against the same page/mem.
  */
-export async function serveSession(session, projectDir, sessionId, headless = true) {
+export async function serveSession(session, projectDir, sessionId, headless = true, 
+/** After a quit closed the session and removed its files: the session process exits here. */
+onShutdown = () => { }) {
     mkdirSync(sessionDir(projectDir), { recursive: true });
     mkdirSync(socketDir(), { recursive: true });
     const socketPath = socketPathFor(sessionId);
@@ -120,6 +124,7 @@ export async function serveSession(session, projectDir, sessionId, headless = tr
         queue = next.catch(() => { });
         return next;
     };
+    const feed = createFeed();
     const server = createServer((sock) => {
         let buf = "";
         sock.on("data", (chunk) => {
@@ -141,6 +146,15 @@ export async function serveSession(session, projectDir, sessionId, headless = tr
             sock.write(JSON.stringify({ ok: false, error: "malformed request (invalid JSON)" }) + "\n");
             return;
         }
+        // Neither waits behind a running request: hello names the protocol, subscribe turns this socket into a live feed.
+        if (request.op === "hello") {
+            sock.write(JSON.stringify({ ok: true, protocol: SESSION_PROTOCOL_VERSION, waygraph: waygraphVersion(), sessionId, here: session.where }) + "\n");
+            return;
+        }
+        if (request.op === "subscribe") {
+            feed.add(sock);
+            return;
+        }
         await enqueue(async () => {
             let response;
             let shouldQuit = false;
@@ -165,6 +179,9 @@ export async function serveSession(session, projectDir, sessionId, headless = tr
                 else if (request.op === "console") {
                     response = { ok: true, consoleLog: session.getConsoleLog() };
                 }
+                else if (request.op === "read") {
+                    response = { ok: true, ...(await session.read(request.path)) };
+                }
                 else if (request.op === "storage") {
                     response = { ok: true, ...(await session.inspectStorage()) };
                 }
@@ -213,6 +230,9 @@ export async function serveSession(session, projectDir, sessionId, headless = tr
                 response = { ok: false, error: err instanceof Error ? err.message : String(err) };
             }
             sock.write(JSON.stringify(response) + "\n");
+            // Whatever changed (a step ran, a reload, a raw action): subscribers get the new snapshot.
+            if (response.ok && "snapshot" in response && "sections" in response.snapshot)
+                feed.send({ type: "snapshot", snapshot: response.snapshot });
             if (shouldQuit) {
                 setImmediate(() => void shutdown());
             }
@@ -224,9 +244,10 @@ export async function serveSession(session, projectDir, sessionId, headless = tr
             return;
         shuttingDown = true;
         server.close();
+        feed.close();
         await session.close().catch(ignorePageGone);
         removeSessionFiles(projectDir, sessionId);
-        process.exit(0);
+        onShutdown();
     }
     await new Promise((resolvePromise, reject) => {
         server.on("error", reject);
@@ -248,7 +269,7 @@ export async function serveSession(session, projectDir, sessionId, headless = tr
 /** Entry point for the hidden `__auto-serve` CLI command (runs in the detached child). */
 export async function runAutoServeCommand(init, sessionId) {
     const session = await AutoSession.start({ ...init, sessionId });
-    await serveSession(session, init.projectDir, sessionId, init.headless ?? true);
+    await serveSession(session, init.projectDir, sessionId, init.headless ?? true, () => process.exit(0));
     // Tell the parent that spawned us (spawnDetachedSession) we are serving, then let it go.
     process.send?.({ ready: true });
     process.disconnect?.();
@@ -372,3 +393,12 @@ export async function runAttachLoop(projectDir, sessionId) {
         rl.close();
     }
 }
+/** This package's version, for `hello` (the file sits three levels below the package root in src/ and dist/). */
+function waygraphVersion() {
+    try {
+        return JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "package.json"), "utf8")).version;
+    }
+    catch {
+        return "unknown";
+    }
+}

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

@@ -0,0 +1,127 @@
+import type { PilotHighlightFixtures } from "../../demo/overlay/pilot/fixtures.js";
+import type { RunEvent } from "../../engine/run/events.js";
+import type { ApplyPathResult, ConsoleLogEntry, DomSnapshot, InspectDomOptions, SessionSnapshot, StorageSnapshot, StubFileKind, TraceStep } from "./helpers.js";
+import type { SessionRead } from "./read.js";
+/** Bumped when a request or response changes shape (adding an op or an optional field does not). */
+export declare const SESSION_PROTOCOL_VERSION = 1;
+/** Every request a session answers. */
+export type SessionRequest = {
+    op: "hello";
+} | {
+    op: "subscribe";
+} | {
+    op: "status";
+} | {
+    op: "send";
+    pick: string;
+} | ({
+    op: "dom";
+} & InspectDomOptions) | {
+    op: "trace";
+} | {
+    op: "click";
+    selector: string;
+} | {
+    op: "type";
+    selector: string;
+    text: string;
+} | {
+    op: "press";
+    selector: string;
+    key: string;
+} | {
+    op: "goto";
+    url: string;
+} | {
+    op: "reload";
+} | {
+    op: "reach";
+    checkpoint: string;
+} | {
+    op: "resync";
+} | {
+    op: "console";
+} | {
+    op: "storage";
+} | {
+    op: "read";
+    path?: string;
+} | {
+    op: "upload";
+    selector: string;
+    stub: StubFileKind | {
+        filePath: string;
+    };
+} | ({
+    op: "highlight";
+} & PilotHighlightFixtures);
+export type StatusOrSendResponse = {
+    ok: true;
+    snapshot: SessionSnapshot;
+    quit: boolean;
+} | {
+    ok: false;
+    error: string;
+};
+export type DomResponse = {
+    ok: true;
+    snapshot: DomSnapshot;
+} | {
+    ok: false;
+    error: string;
+};
+export type TraceResponse = {
+    ok: true;
+    trace: TraceStep[];
+} | {
+    ok: false;
+    error: string;
+};
+export type ConsoleResponse = {
+    ok: true;
+    consoleLog: ConsoleLogEntry[];
+} | {
+    ok: false;
+    error: string;
+};
+export type StorageResponse = ({
+    ok: true;
+} & StorageSnapshot) | {
+    ok: false;
+    error: string;
+};
+export type ReachResponse = ApplyPathResult;
+export type ReadResponse = ({
+    ok: true;
+} & SessionRead) | {
+    ok: false;
+    error: string;
+};
+export type HighlightResponse = {
+    ok: true;
+    painted: number;
+    missing: string[];
+    snapshot: SessionSnapshot;
+} | {
+    ok: false;
+    error: string;
+};
+/** What `hello` answers: the protocol a client is talking to, and where the session is (`null` until a status or step has located it). */
+export type HelloResponse = {
+    ok: true;
+    protocol: number;
+    waygraph: string;
+    sessionId: string;
+    here: string | null;
+};
+/** One line of a `subscribe` feed: every run event in the session (steps, reads), and the snapshot after each change. */
+export type SessionStreamMessage = {
+    type: "event";
+    event: RunEvent;
+} | {
+    type: "snapshot";
+    snapshot: SessionSnapshot;
+};
+export type SessionResponse = HelloResponse | StatusOrSendResponse | DomResponse | TraceResponse | ConsoleResponse | StorageResponse | ReachResponse | ReadResponse | HighlightResponse;
+/** Every op, once: the server, the CLI and `pilot` all check against this list. */
+export declare const SESSION_OPS: readonly ["hello", "subscribe", "status", "send", "dom", "trace", "console", "storage", "read", "upload", "click", "type", "press", "goto", "reload", "reach", "resync", "highlight"];