waygraph 0.12.12 → 0.12.14

package/README.md

@@ -218,10 +218,21 @@ so it drops straight into `defineFlow([start, ..., composed, ..., end])` like an
 `fastForwardComposeBlock(name, steps)` is the same shape marked for **wall-clock
 fast-forward**: one opaque demo step that **blitzes** (no per-inner gate, no smooth
 cursor theater, Playwright slowMo off for that flow unless `WAYGRAPH_SLOWMO` is set)
-unless `waygraph demo --ff-expand`. Put **several** FF units in one Flow when you need
-to race past auth, then a heavy dashboard settle, then watch the interesting middle.
-Saucedemo `checkoutFlow` uses `ff-owner-auth` for the login prefix; `loginFlow` stays
-expanded for Sign In narration. See `docs/proposals/traverse-ffcompose-rfc.md`.
+unless expanded. Put **several** FF units in one Flow when you need to race past auth,
+then a heavy dashboard settle, then watch the interesting middle.
+
+**Dispute / disable FF:** `waygraph demo --ff-disabled` (alias `--no-ff`) expands every
+FFCompose into its inner Blocks so a broken login step is visible as its own panel row.
+Former FF inners keep blitz pacing so wall-clock stays comparable to opaque FF (same
+real acts). `--ff-expand` is the older expand-only flag (same flatten). Saucedemo
+`checkoutFlow` uses `ff-owner-auth` for the login prefix; `loginFlow` stays expanded for
+Sign In narration.
+
+`waygraph traverse` walks the Block graph (Phase B+D). `--parallel N` (default
+`--session clone`) bootstraps one context, forks N workers with `storageState` + mem
+snapshot, partitions edges by hash, and claims via in-process edge leases (audit under
+`.waygraph-traverse/`). `--session inherit` is refused when `parallel > 1`. See
+`docs/proposals/traverse-ffcompose-rfc.md`.
 `spawnTab(entry, page, mem)` drives a genuinely separate second tab through its own
 Block/Flow, in the same browser context an existing `page` already belongs to - the
 pattern `observe()` could already reach for (it's the only phase allowed to touch

package/dist/auto-explore.js

@@ -251,6 +251,8 @@ export async function buildExploreMenu(page, graph, library, here) {
         if (!(await navRunnable(page, entry)))
             continue;
         if (here === null) {
+            // Bootstrap only: URL deep-links as "Start here". Click-nav needs a live
+            // control so it cannot seed an unknown page.
             if (!isUrlNav(entry))
                 continue;
             push(navigate, edge);
@@ -258,6 +260,12 @@ export async function buildExploreMenu(page, graph, library, here) {
         }
         if (edge.to === here)
             continue;
+        // Known screen: do NOT dump every defineNavBlock({ url }) under Navigate.
+        // Graph still marks NavBlocks from:"*" for pathfinding/traverse; auto menu
+        // only offers click-nav whose control is visible on this page (navRunnable).
+        // Otherwise LoginForm lists every app route + mailpit as if legal moves.
+        if (isUrlNav(entry))
+            continue;
         if (isBackEdge(edge) && (edge.from === here || edge.from === "*")) {
             push(back, edge);
         }

package/dist/cli.d.ts

@@ -4,7 +4,7 @@
  *
  * Primary verbs (less is more):
  *   auto   Explore picker; `.flow.ts` / `--blocks From To` = run that path
- *   demo   Watch (step overlay); `--blocks` `--data` `--auto-next` `--fast` `--full` `--ff-expand`
+ *   demo   Watch (step overlay); `--blocks` `--data` `--auto-next` `--fast` `--full` `--ff-expand` `--ff-disabled`
  *   run    Execute; `--blocks` `--data` `--non-headless` `--video`
  *
  * Also: list / nav / validate / check / graph / init / agent-dive / traverse / try

package/dist/cli.js

@@ -4,7 +4,7 @@
  *
  * Primary verbs (less is more):
  *   auto   Explore picker; `.flow.ts` / `--blocks From To` = run that path
- *   demo   Watch (step overlay); `--blocks` `--data` `--auto-next` `--fast` `--full` `--ff-expand`
+ *   demo   Watch (step overlay); `--blocks` `--data` `--auto-next` `--fast` `--full` `--ff-expand` `--ff-disabled`
  *   run    Execute; `--blocks` `--data` `--non-headless` `--video`
  *
  * Also: list / nav / validate / check / graph / init / agent-dive / traverse / try
@@ -2170,11 +2170,11 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
     if ((clearSession || r.resetSession) && i > 0) {
       await resetPageState(context, page, baseURL);
     }
-    // gatesFast: --fast (whole run) or FFCompose opaque steps (one short gate).
-    // skipTheater: WAYGRAPH_FAST_BLOCKS **or** FFCompose — wall-clock blitz
-    // (overlay delays). --fast alone never sets skipTheater.
-    pacing.gatesFast = demoFast || !!r.block.fastForward;
-    pacing.skipTheater = fastBlockNames.has(r.block.name) || !!r.block.fastForward;
+    // gatesFast / skipTheater: opaque FF, former-FF inners (--ff-disabled/--ff-expand),
+    // or WAYGRAPH_FAST_BLOCKS. --fast alone = shorter gates only (keeps theater).
+    pacing.gatesFast = demoFast || !!r.block.fastForward || !!r.wasFastForward;
+    pacing.skipTheater =
+      fastBlockNames.has(r.block.name) || !!r.block.fastForward || !!r.wasFastForward;
     const fixtures = r.highlightFixtures;
     stubBeforeRef.current = resolveHighlightSlots(r.block, "stubBefore", { fixtures });
     const isNavBlock = r.block.__waygraphKind === "nav";
@@ -2484,7 +2484,9 @@ async function main() {
   // truly unexpected failure outside runJsonReportMode's own try/catch)
   // reaches stdout.
   const jsonReport = process.env.WAYGRAPH_JSON === "1";
-  const ffExpand = process.env.WAYGRAPH_FF_EXPAND === "1";
+  const ffExpand =
+    process.env.WAYGRAPH_FF_EXPAND === "1" || process.env.WAYGRAPH_FF_DISABLED === "1";
+  const ffDisabled = process.env.WAYGRAPH_FF_DISABLED === "1";
   /** Expand or keep fastForwardComposeBlock units for demo/run step lists. */
   const flattenBlockInfos = (blockInfos) => {
     const out = [];
@@ -2497,6 +2499,10 @@ async function main() {
             block: step.block,
             ...(step.routes ? { routes: step.routes } : {}),
             ...(bi.resetSessionBefore ? { resetSessionBefore: true } : {}),
+            // Dispute / --ff-disabled: keep blitz pacing on former FF inners so
+            // wall-clock stays comparable to opaque FF (same real acts).
+            wasFastForward: true,
+            ffSource: b.name,
           });
         }
       } else {
@@ -2529,14 +2535,20 @@ async function main() {
           flow.expectedFailureReason && idx === blockInfos.length - 1
             ? flow.expectedFailureReason
             : undefined,
+        ...(bi.wasFastForward ? { wasFastForward: true, ffSource: bi.ffSource } : {}),
       }));
       chainFlows = [flow];
       if (!jsonReport) {
         console.log(
-          "waygraph: running existing flow \\"" + bareRef + "\\" - " +
+          'waygraph: running existing flow "' + bareRef + '" - ' +
             resolved.map((r) => r.block.name).join(" -> ") + " (" + resolved.length + " block" +
             (resolved.length === 1 ? "" : "s") + ", no chain spec needed)",
         );
+        if (ffDisabled) {
+          console.error(
+            "waygraph demo: --ff-disabled - FFCompose expanded to inners (dispute / step locus); blitz pacing kept on former FF steps",
+          );
+        }
       }
     }
   }
@@ -2623,6 +2635,7 @@ async function main() {
         expectedFailureReason:
           meta.expectedFailureReason && remainingInFlow === 1 ? meta.expectedFailureReason : undefined,
         seedMem: isFirstOfSegment ? meta.seedMem : undefined,
+        ...(bi.wasFastForward ? { wasFastForward: true, ffSource: bi.ffSource } : {}),
       };
       remainingInFlow -= 1;
       isFirstOfSegment = false;
@@ -2644,21 +2657,27 @@ async function main() {
   // nobody has to watch a live window for it to be right).
   const headed =
     process.env.WAYGRAPH_HEADED === "0" ? false : process.env.WAYGRAPH_HEADED === "1" || step;
-  // Step mode defaults to a visible Playwright pace (slowMo 350) UNLESS the
-  // flow has an opaque fastForwardComposeBlock — then default slowMo 0 so FF
-  // auth/seed actually blitzes (<10s target) instead of only hiding the cursor
-  // while every click still pays 350ms. Non-FF steps keep overlay theater
-  // (cursor/pop) for watchability. Explicit WAYGRAPH_SLOWMO always wins.
-  const hasOpaqueFf = resolved.some(
-    (r) => r && r.block && r.block.fastForward === true,
+  // Step mode: blitz Playwright slowMo when any opaque FF **or** former-FF
+  // inners (--ff-disabled) are in the resolved list. Explicit WAYGRAPH_SLOWMO wins.
+  const hasFfBlitz = resolved.some(
+    (r) =>
+      r &&
+      ((r.block && r.block.fastForward === true) || r.wasFastForward === true),
   );
   const slowMo = process.env.WAYGRAPH_SLOWMO !== undefined
     ? Number(process.env.WAYGRAPH_SLOWMO)
     : step
-      ? hasOpaqueFf
+      ? hasFfBlitz
         ? 0
         : 350
       : undefined;
+  if (step && hasFfBlitz && process.env.WAYGRAPH_SLOWMO === undefined && !jsonReport) {
+    console.error(
+      ffDisabled
+        ? "waygraph demo: --ff-disabled (expanded) -> Playwright slowMo=0 on former FF steps (blitz; same acts as opaque FF)"
+        : "waygraph demo: opaque FFCompose in flow -> Playwright slowMo=0 (blitz); set WAYGRAPH_SLOWMO to override",
+    );
+  }
   const baseURL = process.env.WAYGRAPH_BASE_URL;
   const title = process.env.WAYGRAPH_TITLE;
   // Comma-separated Block names (their real .name, e.g. "login") that
@@ -3355,6 +3374,10 @@ function parseRunFlags(argv) {
         else if (a === "--ff-expand") {
             out.ffExpand = true;
         }
+        else if (a === "--ff-disabled" || a === "--no-ff") {
+            out.ffDisabled = true;
+            out.ffExpand = true;
+        }
         else if (a === "--non-headless") {
             out.nonHeadless = true;
         }
@@ -3516,6 +3539,10 @@ function applyRunFlags(flags, opts) {
     if (flags.ffExpand) {
         process.env.WAYGRAPH_FF_EXPAND = "1";
     }
+    if (flags.ffDisabled) {
+        process.env.WAYGRAPH_FF_DISABLED = "1";
+        process.env.WAYGRAPH_FF_EXPAND = "1";
+    }
 }
 /**
  * BASE_URL when neither --base-url nor WAYGRAPH_BASE_URL is set:
@@ -3674,6 +3701,7 @@ Primary (less is more):
                  --fast                    Shorter auto-next / Next gates (keeps smooth cursor)
                  --full                    Classic wrap-all block chips (default: carousel)
                  --ff-expand               Expand fastForwardComposeBlock inners as separate steps
+                 --ff-disabled             Dispute: expand FF (alias --no-ff); blitz kept on those inners
                  --auto-play-video         Unattended + recorded: --auto-next + --video (+ step); headless by default
                  --auto-play-video-head    Same, but keep the browser visible (--non-headless)
                  --video-viewport WxH       Recording size (default demo: 1920x1080)
@@ -3684,11 +3712,14 @@ Primary (less is more):
                  --video [dir]             Record .webm
                  --video-viewport WxH       Recording size (default run: 1280x720)
                  --ff-expand               Same as demo (expand FFCompose inners)
+                 --ff-disabled             Same as demo (dispute: expand FF)
 
 Also:
   waygraph list | nav | validate | check | graph | init <name>
-  waygraph traverse [project]              Serial graph crawl (Phase B+)
+  waygraph traverse [project]              Graph crawl (Phase B+D)
                  --blocks <glob|/re/|sub>  Phase C: filter *.block.ts discovery
+                 --parallel N              Phase D: N clone workers (max 4)
+                 --session clone|inherit   Phase D: default clone
                  --from <Checkpoint>       Seed / start checkpoint
                  --data '{...}'            Mem seed
                  --max-steps N             Cap Block runs (default 50)
@@ -3714,6 +3745,7 @@ Examples:
   waygraph auto --blocks LoginPage OrderComplete
   waygraph auto --blocks '/mailpit/'                     # Phase C filtered explore
   waygraph traverse --blocks '**/mailpit/**/*.block.ts'  # Phase C filtered crawl
+  waygraph traverse --parallel 2 --session clone         # Phase D clone workers
   waygraph run  --blocks "loginFlow then add-all-to-cart" --data '{...}' --video
 
 Aliases (compat): \`chain <spec>\` -> run --blocks; \`chain auto A B\` -> auto --blocks A B;
@@ -3808,6 +3840,8 @@ async function main() {
             let headed = false;
             let baseUrl;
             let blocksFilter;
+            let parallel;
+            let session;
             let projectDir = process.cwd();
             for (let i = 0; i < rest.length; i++) {
                 const a = rest[i];
@@ -3833,6 +3867,20 @@ async function main() {
                     }
                     continue;
                 }
+                if (a === "--parallel" || a.startsWith("--parallel=")) {
+                    const v = a.startsWith("--parallel=") ? a.slice("--parallel=".length) : rest[++i];
+                    parallel = Number(v);
+                    continue;
+                }
+                if (a === "--session" || a.startsWith("--session=")) {
+                    const v = a.startsWith("--session=") ? a.slice("--session=".length) : rest[++i];
+                    if (v !== "clone" && v !== "inherit") {
+                        console.error('waygraph traverse: --session must be "clone" or "inherit"');
+                        process.exit(1);
+                    }
+                    session = v;
+                    continue;
+                }
                 if (a === "--max-steps" || a.startsWith("--max-steps=")) {
                     const v = a.startsWith("--max-steps=") ? a.slice(12) : rest[++i];
                     maxSteps = Number(v);
@@ -3861,13 +3909,15 @@ async function main() {
                 if (a === "--help" || a === "-h") {
                     console.log(`waygraph traverse [project] [flags]
 
-Serial graph crawl (RFC Phase B). Walks unused legal edges until a leaf,
-budget kill, or first broken edge.
+Graph crawl (RFC Phase B+D). Walks unused legal edges until a leaf,
+budget kill, or first broken edge. --parallel N uses session clone + edge leases.
 
   --blocks <glob|/regex/|substr>  Phase C: filter *.block.ts discovery
+  --parallel N            Phase D: N clone workers (default 1, max 4)
+  --session clone|inherit Phase D: default clone; inherit refused if parallel>1
   --from <Checkpoint>     start checkpoint (optional)
   --data '{...}'          Mem seed JSON
-  --max-steps N           default 50
+  --max-steps N           default 50 (per worker)
   --max-visits N          per-node visit cap (default 2)
   --max-visits-per-edge N default 1
   --non-headless          show browser
@@ -3875,7 +3925,7 @@ budget kill, or first broken edge.
 
 Examples:
   waygraph traverse --blocks '**/mailpit/**/*.block.ts'
-  waygraph traverse --blocks '/mailpit|login/'
+  waygraph traverse --parallel 2 --session clone --max-steps 20
 
 PASS:  [Reached Leaf Node[traverse-1] at=... steps=N]
 FAIL:  [Broke at edge[traverse-1] block=... from=... to=...]
@@ -3906,6 +3956,8 @@ FAIL:  [Broke at edge[traverse-1] block=... from=... to=...]
                 headed,
                 ...(baseUrl ? { baseURL: baseUrl } : {}),
                 ...(blocksSelect ? { blocksSelect } : {}),
+                ...(parallel !== undefined && Number.isFinite(parallel) ? { parallel } : {}),
+                ...(session ? { session } : {}),
             });
             process.exit(code);
         }
@@ -4006,7 +4058,7 @@ Agents shipped: waygraph-planner, waygraph-author, waygraph-healer.
                 console.error("waygraph demo: missing flow/spec — e.g.\n" +
                     "  waygraph demo src/flows/shop.flow.ts\n" +
                     "  waygraph demo --blocks shopFlow\n" +
-                    "  Flags: --blocks --data --auto-next --fast --full --ff-expand --auto-play-video --title --base-url --video");
+                    "  Flags: --blocks --data --auto-next --fast --full --ff-expand --ff-disabled --auto-play-video --title --base-url --video");
                 process.exit(1);
             }
             const proj = flags.blocks

package/dist/index.d.ts

@@ -11,3 +11,6 @@ export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./gra
 export type { WaygraphGraph, WaygraphNode, WaygraphEdge, SkippedBlock, OrphanBlock } from "./graph.js";
 export { isFileSelectToken, parseBlocksSelect, matchBlocksSelect, globToRegExp, } from "./blocks-select.js";
 export type { BlocksSelect, BlocksSelectKind } from "./blocks-select.js";
+export { EdgeLeaseCoordinator } from "./traverse-lease.js";
+export { runTraverse } from "./traverse-run.js";
+export type { TraverseOptions, TraverseSessionMode } from "./traverse-run.js";

package/dist/index.js

@@ -5,3 +5,5 @@ export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, mo
 export { resolveHighlightSlots, resolveSlides, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, } from "./highlights.js";
 export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";
 export { isFileSelectToken, parseBlocksSelect, matchBlocksSelect, globToRegExp, } from "./blocks-select.js";
+export { EdgeLeaseCoordinator } from "./traverse-lease.js";
+export { runTraverse } from "./traverse-run.js";

package/dist/traverse-lease.d.ts

@@ -0,0 +1,18 @@
+export interface EdgeLeaseRecord {
+    workerId: string;
+    claimedAt: number;
+}
+export declare class EdgeLeaseCoordinator {
+    private readonly held;
+    private readonly dir;
+    constructor(opts?: {
+        projectDir?: string;
+        persist?: boolean;
+    });
+    /** True if this worker now owns `edgeKey` (or already owned it). */
+    tryClaim(edgeKey: string, workerId: string): boolean;
+    release(edgeKey: string, workerId: string): void;
+    /** Stable partition: same key always maps to the same worker index. */
+    static partitionIndex(edgeKey: string, parallel: number): number;
+    private flush;
+}

package/dist/traverse-lease.js

@@ -0,0 +1,62 @@
+/**
+ * Phase D: edge leases so parallel traverse workers never claim the same edge.
+ * In-process Map is authoritative for `--parallel` (same Node process).
+ * Optional JSON under `.waygraph-traverse/` is an audit trail only.
+ */
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+export class EdgeLeaseCoordinator {
+    held = new Map();
+    dir;
+    constructor(opts) {
+        if (opts?.persist && opts.projectDir) {
+            this.dir = join(opts.projectDir, ".waygraph-traverse");
+            if (!existsSync(this.dir))
+                mkdirSync(this.dir, { recursive: true });
+        }
+        else {
+            this.dir = null;
+        }
+    }
+    /** True if this worker now owns `edgeKey` (or already owned it). */
+    tryClaim(edgeKey, workerId) {
+        const cur = this.held.get(edgeKey);
+        if (cur && cur.workerId !== workerId)
+            return false;
+        this.held.set(edgeKey, { workerId, claimedAt: Date.now() });
+        this.flush();
+        return true;
+    }
+    release(edgeKey, workerId) {
+        const cur = this.held.get(edgeKey);
+        if (cur && cur.workerId === workerId) {
+            this.held.delete(edgeKey);
+            this.flush();
+        }
+    }
+    /** Stable partition: same key always maps to the same worker index. */
+    static partitionIndex(edgeKey, parallel) {
+        if (parallel <= 1)
+            return 0;
+        let h = 2166136261;
+        for (let i = 0; i < edgeKey.length; i++) {
+            h ^= edgeKey.charCodeAt(i);
+            h = Math.imul(h, 16777619);
+        }
+        return (h >>> 0) % parallel;
+    }
+    flush() {
+        if (!this.dir)
+            return;
+        try {
+            const payload = {
+                updatedAt: new Date().toISOString(),
+                leases: Object.fromEntries(this.held),
+            };
+            writeFileSync(join(this.dir, "leases.json"), JSON.stringify(payload, null, 2));
+        }
+        catch {
+            /* audit only */
+        }
+    }
+}

package/dist/traverse-run.d.ts

@@ -1,3 +1,4 @@
+export type TraverseSessionMode = "clone" | "inherit";
 export interface TraverseOptions {
     baseURL?: string;
     startUrl?: string;
@@ -19,8 +20,12 @@ export interface TraverseOptions {
     traverseId?: string;
     /** Phase C: glob / regex / bare `--blocks` file select. */
     blocksSelect?: import("./blocks-select.js").BlocksSelect;
+    /** Phase D: parallel workers (default 1). Cap 4. */
+    parallel?: number;
+    /** Phase D: clone (default) or inherit. Inherit refused when parallel > 1. */
+    session?: TraverseSessionMode;
 }
 /**
- * Serial graph crawl. Prints greppable PASS/FAIL lines; non-zero exit on break.
+ * Serial or parallel graph crawl. Prints greppable PASS/FAIL lines; non-zero on break.
  */
 export declare function runTraverse(projectDir: string, options?: TraverseOptions): Promise<number>;

package/dist/traverse-run.js

@@ -1,6 +1,6 @@
 /**
- * Phase B: serial graph traverse (RFC traverse-ffcompose).
- * Walk unused legal edges until leaf / budget / break. No parallel yet.
+ * Phase B+D: graph traverse (serial or --parallel with --session clone).
+ * Walk unused legal edges until leaf / budget / break.
  */
 import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
@@ -8,6 +8,7 @@ import { Engine, start, end, locate } from "./engine.js";
 import { MemPage } from "./mem-page.js";
 import { buildExploreContext, buildExploreMenu, } from "./auto-explore.js";
 import { defaultMemValueForKey } from "./auto-explore-run.js";
+import { EdgeLeaseCoordinator } from "./traverse-lease.js";
 function resolveBaseUrl(projectDir) {
     if (process.env.WAYGRAPH_BASE_URL)
         return process.env.WAYGRAPH_BASE_URL;
@@ -47,6 +48,32 @@ function seedMem(library, mem, dataJson) {
         }
     }
 }
+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)) {
+                try {
+                    out[k.name] = mem.get(k);
+                }
+                catch {
+                    /* skip */
+                }
+            }
+        }
+    }
+    return out;
+}
+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]);
+            }
+        }
+    }
+}
 function missingMemKeys(entry, mem) {
     return (entry.block.requires ?? []).filter((k) => !mem.has(k));
 }
@@ -94,56 +121,18 @@ async function runOneBlock(engine, entry, context, page, mem) {
             clearTimeout(timer);
     }
 }
-/**
- * Serial graph crawl. Prints greppable PASS/FAIL lines; non-zero exit on break.
- */
-export async function runTraverse(projectDir, options = {}) {
-    const traverseId = options.traverseId ?? "traverse-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 || process.env.WAYGRAPH_HEADED === "1";
-    const baseURL = options.baseURL ?? resolveBaseUrl(projectDir) ?? process.env.WAYGRAPH_BASE_URL;
-    const startUrl = options.startUrl ?? baseURL;
-    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 mem = new MemPage();
-    seedMem(library.byName, mem, options.data);
-    const engine = new Engine({ headless: !headed, slowMo: headed ? 100 : 0 });
-    const { chromium } = await import("@playwright/test");
-    const executablePath = process.env.CHROME_PATH || process.env.CHROMIUM_PATH;
-    const launchOpts = {
-        headless: !headed,
-    };
-    if (executablePath)
-        launchOpts.executablePath = executablePath;
-    const browser = await chromium.launch(launchOpts);
-    const contextOpts = {
-        viewport: { width: 1280, height: 720 },
-    };
-    if (baseURL)
-        contextOpts.baseURL = baseURL;
-    const context = await browser.newContext(contextOpts);
-    let page = await context.newPage();
+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 = options.from ?? null;
+    let lastHere = opts.from ?? null;
     let exitCode = 0;
-    console.error(`waygraph traverse[${traverseId}]: ${graph.nodes.length} node(s), ${graph.edges.length} edge(s)` +
-        (baseURL ? ` base=${baseURL}` : "") +
-        ` maxSteps=${maxSteps} maxVisits/node=${maxVisitsPerNode} maxVisits/edge=${maxVisitsPerEdge}`);
     try {
-        if (startUrl) {
-            await page.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(() => { });
-            await page.waitForLoadState("load").catch(() => { });
-        }
         for (;;) {
             if (Date.now() - startedAt > timeoutMs) {
                 console.log(`[Killed timeout[${traverseId}] node=${lastHere ?? "?"} wallMs=${timeoutMs}]`);
@@ -162,7 +151,7 @@ export async function runTraverse(projectDir, options = {}) {
                 }
             }
             const detected = await detectHere(page, library.navBlocks);
-            const here = lastHere ?? detected ?? options.from ?? null;
+            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;
@@ -171,7 +160,14 @@ export async function runTraverse(projectDir, options = {}) {
             const menu = await buildExploreMenu(page, graph, library, here);
             const candidates = menu.flat.filter((edge) => {
                 const key = edgeKey(edge);
-                return (edgeVisits.get(key) ?? 0) < maxVisitsPerEdge;
+                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";
@@ -186,6 +182,12 @@ export async function runTraverse(projectDir, options = {}) {
                     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]`);
@@ -204,7 +206,6 @@ export async function runTraverse(projectDir, options = {}) {
                 const observed = typeof out === "object" && out && "__state" in out
                     ? String(out.__state)
                     : pick.to;
-                const key = edgeKey(pick);
                 edgeVisits.set(key, (edgeVisits.get(key) ?? 0) + 1);
                 edgesHit.add(key);
                 if (here)
@@ -224,8 +225,153 @@ export async function runTraverse(projectDir, options = {}) {
         }
     }
     finally {
-        await browser.close().catch(() => { });
+        console.error(`waygraph traverse[${traverseId}]: done exit=${exitCode} steps=${steps} edgesHit=${edgesHit.size}`);
     }
-    console.error(`waygraph traverse[${traverseId}]: done exit=${exitCode} steps=${steps} edgesHit=${edgesHit.size}`);
     return exitCode;
 }
+/**
+ * Serial or parallel graph crawl. Prints greppable PASS/FAIL lines; non-zero on break.
+ */
+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 || process.env.WAYGRAPH_HEADED === "1";
+    const baseURL = options.baseURL ?? resolveBaseUrl(projectDir) ?? process.env.WAYGRAPH_BASE_URL;
+    const startUrl = options.startUrl ?? baseURL;
+    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 leases = new EdgeLeaseCoordinator({ projectDir, persist: parallel > 1 });
+    const engine = new Engine({ headless: !headed, slowMo: headed ? 100 : 0 });
+    const { chromium } = await import("@playwright/test");
+    const executablePath = process.env.CHROME_PATH || process.env.CHROMIUM_PATH;
+    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}`);
+    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(() => { });
+                await page.waitForLoadState("load").catch(() => { });
+            }
+            const code = await runTraverseWorker({
+                traverseId: options.traverseId ?? "traverse-1",
+                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(() => { });
+            return code;
+        }
+        // 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(() => { });
+            await bootPage.waitForLoadState("load").catch(() => { });
+        }
+        const storageState = await bootContext.storageState();
+        const memSnap = snapshotMem(library.byName, bootMem);
+        await bootContext.close().catch(() => { });
+        console.error(`waygraph traverse: forked ${parallel} clone workers (storageState + mem snapshot)`);
+        const codes = 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(() => { });
+            }
+            try {
+                return 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,
+                });
+            }
+            finally {
+                await context.close().catch(() => { });
+            }
+        }));
+        const worst = codes.reduce((a, b) => Math.max(a, b), 0);
+        const pass = codes.filter((c) => c === 0).length;
+        console.error(`waygraph traverse: suite parallel=${parallel} pass=${pass}/${parallel} exit=${worst}`);
+        return worst;
+    }
+    finally {
+        await browser.close().catch(() => { });
+    }
+}

package/examples/saucedemo/.waygraph-traverse/leases.json

@@ -0,0 +1,29 @@
+{
+  "updatedAt": "2026-09-17T11:18:26.658Z",
+  "leases": {
+    "submit-login": {
+      "workerId": "traverse-2",
+      "claimedAt": 1789643826618
+    },
+    "add-all-to-cart": {
+      "workerId": "traverse-2",
+      "claimedAt": 1789643827327
+    },
+    "nav-cart": {
+      "workerId": "traverse-2",
+      "claimedAt": 1789643829570
+    },
+    "nav-continue-shopping": {
+      "workerId": "traverse-2",
+      "claimedAt": 1789643855282
+    },
+    "nav-item-detail::sauce-labs-backpack": {
+      "workerId": "traverse-2",
+      "claimedAt": 1789643857049
+    },
+    "nav-back-to-inventory": {
+      "workerId": "traverse-2",
+      "claimedAt": 1789643906658
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.12.12",
+  "version": "0.12.14",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "license": "MIT",