waygraph 0.15.54 → 0.16.1

package/dist/{session/browser.d.ts → live/auto-session/start.d.ts}

@@ -1,4 +1,4 @@
-import type { AutoSessionInit } from "../auto-session.js";
+import type { AutoSessionInit } from "./helpers.js";
 export interface BrowserStartInit extends AutoSessionInit {
     /** Preset names or paths; resolved before spawn. */
     injectTokens?: string[];
@@ -12,4 +12,3 @@ export interface BrowserStartResult {
 }
 /** Always spawns a new detached session — does not stop or reuse existing ones. */
 export declare function browserStart(init: BrowserStartInit): Promise<BrowserStartResult>;
-export { listBrowserSessions, stopBrowserSession, stopAllBrowserSessions, type SessionMeta, } from "./auto-session-ipc.js";

package/dist/{session/browser.js → live/auto-session/start.js}

@@ -6,8 +6,8 @@
  * Session lifecycle is explicit: `browser sessions` lists what's live;
  * `browser start` always opens another; `browser attach` / `browser stop` pick one up or shut it down.
  */
-import { spawnDetachedSession } from "./auto-session-ipc.js";
-import { resolveInjectRoots } from "./block-inject.js";
+import { spawnDetachedSession } from "./ipc.js";
+import { resolveInjectRoots } from "../../manifest/roots.js";
 /** Always spawns a new detached session — does not stop or reuse existing ones. */
 export async function browserStart(init) {
     const inject = init.inject ??
@@ -26,4 +26,3 @@ export async function browserStart(init) {
         inject,
     };
 }
-export { listBrowserSessions, stopBrowserSession, stopAllBrowserSessions, } from "./auto-session-ipc.js";

package/dist/{pilot-overlay → live/pilot}/panel.d.ts

@@ -1,4 +1,4 @@
-import type { SessionSnapshot } from "../auto-session.js";
+import type { SessionSnapshot } from "../auto-session/helpers.js";
 import type { Page } from "@playwright/test";
 /** Minimal shape needed to render the graph tree - matches WaygraphGraph. */
 interface PilotOverlayGraph {

package/dist/{pilot-overlay → live/pilot}/panel.js

@@ -1,4 +1,5 @@
-import { ensureInstalled } from "./shell.js";
+import { ensureInstalled } from "../../demo/overlay/pilot/shell.js";
+import { ignorePageGone } from "../../engine/page-gone.js";
 /**
  * Refreshes the badge text and the (possibly-collapsed) panel's two tabs
  * ("Here" - current live menu; "All nodes" - whole project graph as a
@@ -10,6 +11,8 @@ export async function updatePilotOverlay(page, info) {
     await ensureInstalled(page);
     await page
         .evaluate(async ({ sessionId, snapshot, graph }) => {
+        // Block names, labels and descriptions can carry the page's own text (an Effect's instance label is read off
+        // the live DOM), so they go in as text nodes (__wgEl), never as markup.
         const badge = __wgById("wg-pilot-badge");
         const current = __wgById("wg-pilot-panel-current");
         const graphPanel = __wgById("wg-pilot-panel-graph");
@@ -21,26 +24,16 @@ export async function updatePilotOverlay(page, info) {
         badge.textContent = `Waygraph Pilot - ${idPart} - ${hereLabel}`;
         const totalEdges = snapshot.sections.reduce((n, s) => n + s.edges.length, 0);
         if (totalEdges === 0) {
-            current.innerHTML = onBlank
-                ? '<div class="wg-pilot-empty">Blank page — no Block moves yet. Use auto goto or a nav Block when ready.</div>'
-                : '<div class="wg-pilot-empty">No Block moves from here right now.</div>';
+            __wgSet(current, __wgEl("div", { class: "wg-pilot-empty" }, onBlank ? "Blank page — no Block moves yet. Use auto goto or a nav Block when ready." : "No Block moves from here right now."));
         }
         else {
-            current.innerHTML = snapshot.sections
-                .map((section) => {
-                const rows = section.edges
-                    .map((edge) => {
-                    const desc = edge.description ? ` - ${edge.description}` : "";
-                    const label = edge.label ? ` (${edge.label})` : "";
-                    return `<div class="wg-pilot-edge">[${edge.index}] <span class="wg-pilot-kind">${edge.kind}</span> ${edge.block}${label} -&gt; ${edge.to}${desc}</div>`;
-                })
-                    .join("");
-                return `<div class="wg-pilot-section">${section.title}</div>${rows}`;
-            })
-                .join("");
+            __wgSet(current, snapshot.sections.map((section) => [
+                __wgEl("div", { class: "wg-pilot-section" }, section.title),
+                section.edges.map((edge) => __wgEl("div", { class: "wg-pilot-edge" }, `[${edge.index}] `, __wgEl("span", { class: "wg-pilot-kind" }, edge.kind), ` ${edge.block}${edge.label ? ` (${edge.label})` : ""} -> ${edge.to}${edge.description ? ` - ${edge.description}` : ""}`)),
+            ]));
         }
         if (!graph || graph.nodes.length === 0) {
-            graphPanel.innerHTML = '<div class="wg-pilot-empty">No graph data yet.</div>';
+            __wgSet(graphPanel, __wgEl("div", { class: "wg-pilot-empty" }, "No graph data yet."));
             return;
         }
         // Flat indented-text tree - the ORIGINAL "All nodes" rendering.
@@ -49,18 +42,14 @@ export async function updatePilotOverlay(page, info) {
         // when Mermaid genuinely can't load (e.g. offline), not the primary
         // rendering anymore.
         const renderTextTree = () => {
-            graphPanel.innerHTML = graph.nodes
-                .map((node) => {
+            __wgSet(graphPanel, graph.nodes.map((node) => {
                 const outgoing = graph.edges.filter((e) => e.from === node.checkpoint || e.from === "*");
                 const rows = outgoing.length
-                    ? outgoing
-                        .map((e) => `<div class="wg-pilot-graph-edge"><span class="wg-pilot-kind">${e.kind}</span> ${e.block} -&gt; ${e.to}</div>`)
-                        .join("")
-                    : '<div class="wg-pilot-graph-edge wg-pilot-empty">(no outgoing edges)</div>';
+                    ? outgoing.map((e) => __wgEl("div", { class: "wg-pilot-graph-edge" }, __wgEl("span", { class: "wg-pilot-kind" }, e.kind), ` ${e.block} -> ${e.to}`))
+                    : [__wgEl("div", { class: "wg-pilot-graph-edge wg-pilot-empty" }, "(no outgoing edges)")];
                 const here = node.checkpoint === snapshot.here ? " (here)" : "";
-                return `<div class="wg-pilot-graph-node"><div class="wg-pilot-graph-checkpoint">${node.checkpoint}${here}</div>${rows}</div>`;
-            })
-                .join("");
+                return __wgEl("div", { class: "wg-pilot-graph-node" }, __wgEl("div", { class: "wg-pilot-graph-checkpoint" }, node.checkpoint + here), rows);
+            }));
         };
         try {
             const w = window;
@@ -80,10 +69,11 @@ export async function updatePilotOverlay(page, info) {
                 throw new Error("mermaid did not attach to window after load");
             // Real, direct user request: "left to right stuff. maybe mermaid?
             // with square ish arrows???" - LR layout, linear (non-curvy) edges.
-            w.mermaid.initialize({ startOnLoad: false, theme: "dark", securityLevel: "loose", flowchart: { curve: "linear" } });
+            // strict: Mermaid escapes label text itself; plain SVG labels (no HTML) so the result parses as SVG.
+            w.mermaid.initialize({ startOnLoad: false, theme: "dark", securityLevel: "strict", flowchart: { curve: "linear", htmlLabels: false } });
             const sanitize = (s) => s.replace(/[^A-Za-z0-9_]/g, "_");
             // Every Nav Block gets a `from:"*"` wildcard edge for pathfinding
-            // (see auto-explore.ts's own isUrlNav comment). Real, screenshot-
+            // (see live/auto/explore.ts's own isUrlNav comment). Real, screenshot-
             // confirmed finding, TWICE over:
             // 1. Collapsing all of these into one shared "Anywhere" hub node
             //    still broke the layout - ~9 of 10 Checkpoints have their own
@@ -137,8 +127,10 @@ export async function updatePilotOverlay(page, info) {
                 lines.push(`  ${sanitize(e.from)} -->|${e.block}| ${sanitize(e.to)}`);
             }
             const { svg } = await w.mermaid.render(`wg-mermaid-${Date.now()}`, lines.join("\n"));
-            graphPanel.innerHTML =
-                svg + `<div class="wg-pilot-graph-note">[nav] = also directly reachable via sidebar/URL from anywhere (not drawn as an edge - see the "Here" tab for what's live on this page).</div>`;
+            const diagram = __wgSvg(svg);
+            if (diagram.nodeName !== "svg")
+                throw new Error("mermaid output did not parse as SVG");
+            __wgSet(graphPanel, diagram, __wgEl("div", { class: "wg-pilot-graph-note" }, '[nav] = also directly reachable via sidebar/URL from anywhere (not drawn as an edge - see the "Here" tab for what\'s live on this page).'));
             // Real, direct user request: "i hope it is zoomed to the current
             // node" - the diagram is usually bigger than the panel, so scroll
             // (not zoom - the SVG itself stays real size, legible) the "here"
@@ -151,5 +143,5 @@ export async function updatePilotOverlay(page, info) {
             renderTextTree();
         }
     }, { sessionId: info.sessionId, snapshot: info.snapshot, graph: info.graph ?? null })
-        .catch(() => { });
+        .catch(ignorePageGone);
 }

package/dist/{session → live/pilot}/pilot.d.ts

@@ -28,9 +28,9 @@
  * hand-picking indices from each status response) that proved this needs no
  * new execution primitive.
  */
-import { type WaygraphGraph } from "../analysis/graph.js";
-import { type BrowserStartInit } from "./browser.js";
-import type { SessionSnapshot } from "../auto-session.js";
+import { type WaygraphGraph } from "../../analysis/graph.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/{session → live/pilot}/pilot.js

@@ -28,9 +28,10 @@
  * hand-picking indices from each status response) that proved this needs no
  * new execution primitive.
  */
-import { discoverGraph } from "../analysis/graph.js";
-import { requestSession, resolveSessionMeta, } from "./auto-session-ipc.js";
-import { browserStart } from "./browser.js";
+import { discoverGraph } from "../../analysis/graph.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
  * snapshot in one call, so an agent bootstraps with everything it needs
@@ -39,7 +40,7 @@ import { browserStart } from "./browser.js";
  * --detach` and `waygraph graph` itself.
  */
 export async function pilotStart(init) {
-    const { resolveInjectRoots } = await import("./block-inject.js");
+    const { resolveInjectRoots } = await import("../../manifest/roots.js");
     const exploreInject = init.inject ??
         (init.injectTokens?.length ? resolveInjectRoots(init.injectTokens, init.projectDir) : undefined);
     const started = await browserStart({

package/dist/{traverse/run.d.ts → live/traverse/traverse.d.ts}

@@ -28,7 +28,7 @@ export interface TraverseOptions {
     /** Traverse id for greppable lines (default traverse-1). */
     traverseId?: string;
     /** Phase C: glob / regex / bare `--blocks` file select. */
-    blocksSelect?: import("../blocks-select.js").BlocksSelect;
+    blocksSelect?: import("../../manifest/select.js").BlocksSelect;
     /** Phase D: parallel workers (default 1). Cap 4. */
     parallel?: number;
     /** Phase D: clone (default) or inherit. Inherit refused when parallel > 1. */

package/dist/live/traverse/traverse.js

@@ -0,0 +1,212 @@
+import { Engine } from "../../engine/engine.js";
+import { envFlag, envString } from "../../engine/env.js";
+import { MemPage } from "../../engine/mem/mem.js";
+import { ignorePageGone, ignoreTimeout } from "../../engine/page-gone.js";
+import { chromiumExecutablePath } from "../../runtime/browser.js";
+import { resolveBaseUrl } from "../../runtime/waygraph-config.js";
+import { buildExploreContext, } from "../auto/explore.js";
+import { buildCoverageReport, collectGraphEdgeKeys, defaultCoverageOutPath, formatCoverageLine, writeCoverageReport, } from "./coverage.js";
+import { EdgeLeaseCoordinator } from "./lease.js";
+import { restoreMem, runTraverseWorker, seedMem, snapshotMem } from "./worker.js";
+/**
+ * Serial or parallel graph crawl. Prints greppable PASS/FAIL + Coverage lines.
+ * Exit: 0 leaf ok (+ coverage ok), 1 break/timeout, 2 coverage gate fail (Phase E).
+ */
+export async function runTraverse(projectDir, options = {}) {
+    let parallel = Math.max(1, Math.floor(options.parallel ?? 1));
+    if (parallel > 4) {
+        console.error(`waygraph traverse: --parallel ${parallel} capped to 4`);
+        parallel = 4;
+    }
+    const session = options.session ?? (parallel > 1 ? "clone" : "clone");
+    if (parallel > 1 && session === "inherit") {
+        console.error("waygraph traverse: --session inherit is refused with --parallel > 1 (races); use --session clone");
+        return 1;
+    }
+    const maxSteps = options.maxSteps ?? 50;
+    const maxVisitsPerNode = options.maxVisitsPerNode ?? 2;
+    const maxVisitsPerEdge = options.maxVisitsPerEdge ?? 1;
+    const timeoutMs = options.timeoutMs ?? 15 * 60_000;
+    const headed = options.headed === true || envFlag("WAYGRAPH_HEADED");
+    const baseURL = options.baseURL ?? (await resolveBaseUrl(projectDir)) ?? envString("WAYGRAPH_BASE_URL");
+    const startUrl = options.startUrl ?? baseURL;
+    const minEdgeCoverage = options.minEdgeCoverage != null && Number.isFinite(options.minEdgeCoverage)
+        ? options.minEdgeCoverage
+        : undefined;
+    const coverageOut = options.coverageOut ?? defaultCoverageOutPath(projectDir);
+    const { graph, library } = await buildExploreContext(projectDir, options.blocksSelect ? { blocksSelect: options.blocksSelect } : undefined);
+    if (options.blocksSelect) {
+        console.error(`waygraph traverse: --blocks ${options.blocksSelect.raw} -> ` +
+            `${library.byName.size} block(s), ${graph.edges.length} edge(s)`);
+    }
+    const allEdgeKeys = collectGraphEdgeKeys(graph.edges);
+    const leases = new EdgeLeaseCoordinator({ projectDir, persist: parallel > 1 });
+    const engine = new Engine({ headless: !headed, slowMo: headed ? 100 : 0 });
+    if (envString("WAYGRAPH_EXTENSIONS"))
+        console.error("waygraph traverse: extensions are not loaded (workers use plain contexts)");
+    const { chromium } = await import("@playwright/test");
+    const executablePath = chromiumExecutablePath();
+    const launchOpts = {
+        headless: !headed,
+    };
+    if (executablePath)
+        launchOpts.executablePath = executablePath;
+    const browser = await chromium.launch(launchOpts);
+    console.error(`waygraph traverse: ${graph.nodes.length} node(s), ${graph.edges.length} edge(s)` +
+        (baseURL ? ` base=${baseURL}` : "") +
+        ` parallel=${parallel} session=${session}` +
+        ` maxSteps=${maxSteps} maxVisits/node=${maxVisitsPerNode} maxVisits/edge=${maxVisitsPerEdge}` +
+        (minEdgeCoverage !== undefined
+            ? ` minEdgeCoverage=${(minEdgeCoverage * 100).toFixed(1)}%`
+            : ""));
+    const emitCoverage = (workers) => {
+        const hitUnion = new Set();
+        for (const w of workers) {
+            for (const k of w.result.edgesHit)
+                hitUnion.add(k);
+        }
+        const report = buildCoverageReport({
+            projectDir,
+            parallel,
+            allEdgeKeys,
+            hitKeys: hitUnion,
+            ...(minEdgeCoverage !== undefined ? { minEdgeCoverage } : {}),
+            workers: workers.map(({ traverseId, result }) => ({
+                traverseId,
+                exitCode: result.exitCode,
+                steps: result.steps,
+                edgesHit: result.edgesHit.length,
+                ...(result.leaf ? { leaf: result.leaf } : {}),
+            })),
+        });
+        console.log(formatCoverageLine(report));
+        console.error(`waygraph traverse: coverage hit=${report.edgesHit}/${report.edgesTotal}` +
+            (report.missed.length
+                ? ` missed=${report.missed.slice(0, 8).join(",")}${report.missed.length > 8 ? "..." : ""}`
+                : "") +
+            (options.noCoverageReport ? "" : ` report=${coverageOut}`));
+        if (!options.noCoverageReport) {
+            writeCoverageReport(coverageOut, report);
+        }
+        if (report.coveragePass === false) {
+            console.error(`waygraph traverse: FAIL coverage gate ratio=${(report.ratio * 100).toFixed(1)}%` +
+                ` < min=${((report.minEdgeCoverage ?? 0) * 100).toFixed(1)}%`);
+            return 2;
+        }
+        return 0;
+    };
+    try {
+        if (parallel <= 1) {
+            const contextOpts = {
+                viewport: { width: 1280, height: 720 },
+            };
+            if (baseURL)
+                contextOpts.baseURL = baseURL;
+            const context = await browser.newContext(contextOpts);
+            const page = await context.newPage();
+            const mem = new MemPage();
+            seedMem(library.byName, mem, options.data);
+            if (startUrl) {
+                await page.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(ignorePageGone);
+                await page.waitForLoadState("load").catch(ignoreTimeout);
+            }
+            const traverseId = options.traverseId ?? "traverse-1";
+            const result = await runTraverseWorker({
+                traverseId,
+                workerIndex: 0,
+                parallel: 1,
+                maxSteps,
+                maxVisitsPerNode,
+                maxVisitsPerEdge,
+                timeoutMs,
+                ...(options.from ? { from: options.from } : {}),
+                ...(startUrl ? { startUrl } : {}),
+                ...(baseURL ? { baseURL } : {}),
+                ...(options.data ? { data: options.data } : {}),
+                graph,
+                library,
+                engine,
+                context,
+                page,
+                mem,
+                leases,
+            });
+            await context.close().catch(ignorePageGone);
+            const coverageCode = emitCoverage([{ traverseId, result }]);
+            if (result.exitCode !== 0)
+                return result.exitCode;
+            return coverageCode;
+        }
+        // Phase D: bootstrap one context for storageState, then N clones.
+        const bootOpts = {
+            viewport: { width: 1280, height: 720 },
+        };
+        if (baseURL)
+            bootOpts.baseURL = baseURL;
+        const bootContext = await browser.newContext(bootOpts);
+        const bootPage = await bootContext.newPage();
+        const bootMem = new MemPage();
+        seedMem(library.byName, bootMem, options.data);
+        if (startUrl) {
+            await bootPage.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(ignorePageGone);
+            await bootPage.waitForLoadState("load").catch(ignoreTimeout);
+        }
+        const storageState = await bootContext.storageState();
+        const memSnap = snapshotMem(library.byName, bootMem);
+        await bootContext.close().catch(ignorePageGone);
+        console.error(`waygraph traverse: forked ${parallel} clone workers (storageState + mem snapshot)`);
+        const workerMeta = await Promise.all(Array.from({ length: parallel }, async (_, i) => {
+            const traverseId = `traverse-${i + 1}`;
+            const ctxOpts = {
+                viewport: { width: 1280, height: 720 },
+                storageState,
+            };
+            if (baseURL)
+                ctxOpts.baseURL = baseURL;
+            const context = await browser.newContext(ctxOpts);
+            const page = await context.newPage();
+            const mem = new MemPage();
+            restoreMem(library.byName, mem, memSnap, options.data);
+            if (startUrl) {
+                await page.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(ignorePageGone);
+            }
+            try {
+                const result = await runTraverseWorker({
+                    traverseId,
+                    workerIndex: i,
+                    parallel,
+                    maxSteps,
+                    maxVisitsPerNode,
+                    maxVisitsPerEdge,
+                    timeoutMs,
+                    ...(options.from ? { from: options.from } : {}),
+                    ...(startUrl ? { startUrl } : {}),
+                    ...(baseURL ? { baseURL } : {}),
+                    ...(options.data ? { data: options.data } : {}),
+                    graph,
+                    library,
+                    engine,
+                    context,
+                    page,
+                    mem,
+                    leases,
+                });
+                return { traverseId, result };
+            }
+            finally {
+                await context.close().catch(ignorePageGone);
+            }
+        }));
+        const results = workerMeta.map((w) => w.result);
+        const worst = results.reduce((a, b) => Math.max(a, b.exitCode), 0);
+        const pass = results.filter((c) => c.exitCode === 0).length;
+        console.error(`waygraph traverse: suite parallel=${parallel} pass=${pass}/${parallel} exit=${worst}`);
+        const coverageCode = emitCoverage(workerMeta);
+        if (worst !== 0)
+            return worst;
+        return coverageCode;
+    }
+    finally {
+        await browser.close().catch(ignorePageGone);
+    }
+}

package/dist/live/traverse/worker.d.ts

@@ -0,0 +1,37 @@
+import type { BrowserContext, Page } from "@playwright/test";
+import type { WaygraphGraph } from "../../analysis/graph.js";
+import type { Checkpoint } from "../../engine/checkpoint/checkpoint.js";
+import { Engine } from "../../engine/engine.js";
+import { MemPage, type MemKey } from "../../engine/mem/mem.js";
+import type { BlockEntry } from "../../manifest/project.js";
+import { buildExploreContext, type ExploreEdge } from "../auto/explore.js";
+import { EdgeLeaseCoordinator } from "./lease.js";
+import type { TraverseWorkerResult } from "./traverse.js";
+export declare function seedMem(library: Map<string, BlockEntry>, mem: MemPage, dataJson?: string): void;
+export declare function snapshotMem(library: Map<string, BlockEntry>, mem: MemPage): Record<string, unknown>;
+export declare function restoreMem(library: Map<string, BlockEntry>, mem: MemPage, snap: Record<string, unknown>, dataJson?: string): void;
+export declare function missingMemKeys(entry: BlockEntry, mem: MemPage): MemKey<unknown>[];
+export declare function ensureMem(entry: BlockEntry, mem: MemPage): void;
+export declare function edgeKey(edge: ExploreEdge): string;
+export declare function runOneBlock(engine: Engine, entry: BlockEntry, context: BrowserContext, page: Page, mem: MemPage): Promise<Checkpoint<string>>;
+export interface WorkerOpts {
+    traverseId: string;
+    workerIndex: number;
+    parallel: number;
+    maxSteps: number;
+    maxVisitsPerNode: number;
+    maxVisitsPerEdge: number;
+    timeoutMs: number;
+    from?: string;
+    startUrl?: string;
+    baseURL?: string;
+    data?: string;
+    graph: WaygraphGraph;
+    library: Awaited<ReturnType<typeof buildExploreContext>>["library"];
+    engine: Engine;
+    context: BrowserContext;
+    page: Page;
+    mem: MemPage;
+    leases: EdgeLeaseCoordinator;
+}
+export declare function runTraverseWorker(opts: WorkerOpts): Promise<TraverseWorkerResult>;

package/dist/live/traverse/worker.js

@@ -0,0 +1,200 @@
+import { envString } from "../../engine/env.js";
+import { buildFlow } from "../../engine/flow/flow.js";
+import { ignorePageGone } from "../../engine/page-gone.js";
+import { detectHere } from "../auto/auto.js";
+import { buildExploreMenu } from "../auto/explore.js";
+import { memStubValue } from "../auto/mem.js";
+import { EdgeLeaseCoordinator } from "./lease.js";
+export function seedMem(library, mem, dataJson) {
+    const raw = dataJson ?? envString("WAYGRAPH_DATA") ?? envString("WAYGRAPH_AUTO_MEM");
+    let envParsed = {};
+    if (raw) {
+        try {
+            envParsed = JSON.parse(raw);
+        }
+        catch {
+            throw new Error(`waygraph traverse: --data / WAYGRAPH_DATA is not valid JSON`);
+        }
+    }
+    for (const entry of library.values()) {
+        for (const k of entry.block.requires ?? []) {
+            if (mem.has(k))
+                continue;
+            if (k.name in envParsed) {
+                mem.set(k, envParsed[k.name]);
+                continue;
+            }
+            const def = memStubValue(k);
+            if (def !== undefined)
+                mem.set(k, def);
+        }
+    }
+}
+export function snapshotMem(library, mem) {
+    const out = {};
+    for (const entry of library.values()) {
+        for (const k of entry.block.requires ?? []) {
+            if (mem.has(k) && !(k.name in out)) {
+                out[k.name] = mem.get(k);
+            }
+        }
+    }
+    return out;
+}
+export function restoreMem(library, mem, snap, dataJson) {
+    seedMem(library, mem, dataJson);
+    for (const entry of library.values()) {
+        for (const k of entry.block.requires ?? []) {
+            if (k.name in snap) {
+                mem.set(k, snap[k.name]);
+            }
+        }
+    }
+}
+export function missingMemKeys(entry, mem) {
+    return (entry.block.requires ?? []).filter((k) => !mem.has(k));
+}
+export function ensureMem(entry, mem) {
+    const missing = missingMemKeys(entry, mem);
+    if (missing.length === 0)
+        return;
+    throw new Error(`Block "${entry.block.name}" needs Mem keys: ${missing.map((k) => k.name).join(", ")} ` +
+        `(pass --data '{...}' or WAYGRAPH_DATA)`);
+}
+export function edgeKey(edge) {
+    const id = edge.instanceOption?.id;
+    return id ? `${edge.block}::${id}` : edge.block;
+}
+export async function runOneBlock(engine, entry, context, page, mem) {
+    const flow = buildFlow([entry.block], engine.config);
+    const BLOCK_TIMEOUT_MS = 45000;
+    let timer;
+    try {
+        const ran = await Promise.race([
+            flow.run(context, mem, { page, closeOnFinish: false }),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`Block "${entry.block.name}" timed out after ${BLOCK_TIMEOUT_MS / 1000}s`)), BLOCK_TIMEOUT_MS);
+            }),
+        ]);
+        return ran.result;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+export async function runTraverseWorker(opts) {
+    const { traverseId, workerIndex, parallel, maxSteps, maxVisitsPerNode, maxVisitsPerEdge, timeoutMs, graph, library, engine, context, mem, leases, } = opts;
+    let page = opts.page;
+    const startUrl = opts.startUrl;
+    const nodeVisits = new Map();
+    const edgeVisits = new Map();
+    const edgesHit = new Set();
+    let steps = 0;
+    const startedAt = Date.now();
+    let lastHere = opts.from ?? null;
+    let exitCode = 0;
+    let leaf;
+    try {
+        for (;;) {
+            if (Date.now() - startedAt > timeoutMs) {
+                console.log(`[Killed timeout[${traverseId}] node=${lastHere ?? "?"} wallMs=${timeoutMs}]`);
+                exitCode = 1;
+                break;
+            }
+            if (steps >= maxSteps) {
+                console.log(`[Killed max-steps[${traverseId}] node=${lastHere ?? "?"} steps=${steps} max=${maxSteps}]`);
+                exitCode = 1;
+                break;
+            }
+            if (page.isClosed()) {
+                page = await context.newPage();
+                if (startUrl) {
+                    await page.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(ignorePageGone);
+                }
+            }
+            const detected = await detectHere(page, library.navBlocks);
+            const here = lastHere ?? detected ?? opts.from ?? null;
+            if (here && (nodeVisits.get(here) ?? 0) >= maxVisitsPerNode) {
+                console.log(`[Killed loop[${traverseId}] node=${here} visits=${nodeVisits.get(here)} max=${maxVisitsPerNode}]`);
+                exitCode = 1;
+                break;
+            }
+            const menu = await buildExploreMenu(page, graph, library, here);
+            const candidates = menu.flat.filter((edge) => {
+                const key = edgeKey(edge);
+                if ((edgeVisits.get(key) ?? 0) >= maxVisitsPerEdge)
+                    return false;
+                if (parallel > 1) {
+                    if (EdgeLeaseCoordinator.partitionIndex(key, parallel) !== workerIndex) {
+                        return false;
+                    }
+                }
+                return true;
+            });
+            if (candidates.length === 0) {
+                const label = here ?? detected ?? "unknown";
+                leaf = label;
+                console.log(`[Reached Leaf Node[${traverseId}] at=${label} steps=${steps}]`);
+                console.error(`waygraph traverse[${traverseId}]: PASS leaf edgesHit=${edgesHit.size} steps=${steps}`);
+                break;
+            }
+            const pick = [...candidates].sort((a, b) => {
+                const aWild = a.from === "*" ? 1 : 0;
+                const bWild = b.from === "*" ? 1 : 0;
+                if (aWild !== bWild)
+                    return aWild - bWild;
+                return edgeKey(a).localeCompare(edgeKey(b));
+            })[0];
+            const key = edgeKey(pick);
+            if (!leases.tryClaim(key, traverseId)) {
+                // Another worker won a race (instance fan-out); treat as unavailable.
+                edgeVisits.set(key, maxVisitsPerEdge);
+                continue;
+            }
+            const entry = library.byName.get(pick.block);
+            if (!entry) {
+                console.log(`[Broke at edge[${traverseId}] block=${pick.block} from=${here ?? "?"} to=${pick.to} reason=not-loaded]`);
+                exitCode = 1;
+                break;
+            }
+            const fromLabel = here ?? pick.from;
+            try {
+                if (pick.instanceOption) {
+                    mem.set(pick.instanceOption.key, pick.instanceOption.value);
+                }
+                ensureMem(entry, mem);
+                console.error(`waygraph traverse[${traverseId}]: step ${steps + 1} ${fromLabel} -[${pick.block}]-> ${pick.to}` +
+                    (pick.label ? ` (${pick.label})` : ""));
+                const out = await runOneBlock(engine, entry, context, page, mem);
+                const observed = typeof out === "object" && out && "__state" in out
+                    ? String(out.__state)
+                    : pick.to;
+                edgeVisits.set(key, (edgeVisits.get(key) ?? 0) + 1);
+                edgesHit.add(key);
+                if (here)
+                    nodeVisits.set(here, (nodeVisits.get(here) ?? 0) + 1);
+                lastHere = observed;
+                steps += 1;
+                if (observed !== pick.to && pick.to !== "*") {
+                    console.error(`waygraph traverse[${traverseId}]: WARN static to=${pick.to} observed=${observed}`);
+                }
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                console.log(`[Broke at edge[${traverseId}] block=${pick.block} from=${fromLabel} to=${pick.to}] ${msg}`);
+                exitCode = 1;
+                break;
+            }
+        }
+    }
+    finally {
+        console.error(`waygraph traverse[${traverseId}]: done exit=${exitCode} steps=${steps} edgesHit=${edgesHit.size}`);
+    }
+    return {
+        exitCode,
+        steps,
+        edgesHit: [...edgesHit],
+        ...(leaf ? { leaf } : {}),
+    };
+}