waygraph 0.15.43 → 0.15.45

package/dist/session/overlay-beacon.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Blind-agent / Playwright checks for waygraph overlay modals.
+ *
+ * Every live modal root must carry:
+ *   data-wg-ui="1"
+ *   data-wg-modal="panel|banner|auto-panel"
+ *   data-wg-ready="1" when painted and readable
+ *
+ * Agents: do not claim the stepper works unless
+ *   `assertWgOverlayReady(page)` (or WAYGRAPH_PROVE_EXIT=1) passes.
+ */
+import type { Page } from "@playwright/test";
+export declare const WG_UI_SEL = "[data-wg-ui=\"1\"]";
+export declare const WG_READY_PANEL_SEL = "[data-wg-modal=\"panel\"][data-wg-ready=\"1\"]";
+export declare const WG_READY_AUTO_SEL = "[data-wg-modal=\"auto-panel\"][data-wg-ready=\"1\"]";
+export declare const WG_READY_BANNER_SEL = "[data-wg-modal=\"banner\"][data-wg-ready=\"1\"]";
+export type WgModalKind = "panel" | "banner" | "auto-panel";
+export type WgBeaconRow = {
+    id: string | null;
+    modal: string | null;
+    ready: boolean;
+    phase: string | null;
+    step: string | null;
+    block: string | null;
+    collapsed: boolean;
+    opacity: string;
+    textLen: number;
+    w: number;
+    h: number;
+    visible: boolean;
+};
+/** Browser-side beacon reader (also installed as window.__wgOverlayBeacon). */
+export declare function readWgOverlayBeaconInPage(): WgBeaconRow[];
+export declare function readWgOverlayBeacon(page: Page): Promise<WgBeaconRow[]>;
+/**
+ * Hard gate: a blank / missing / opacity-0 modal fails.
+ * Use after demo/auto paints its first overlay.
+ */
+export declare function assertWgOverlayReady(page: Page, opts?: {
+    modal?: WgModalKind;
+    minTextLen?: number;
+    /** When true, collapsed mini chrome is allowed (still needs visible box + text). */
+    allowCollapsed?: boolean;
+}): Promise<WgBeaconRow>;

package/dist/session/overlay-beacon.js

@@ -0,0 +1,85 @@
+/**
+ * Blind-agent / Playwright checks for waygraph overlay modals.
+ *
+ * Every live modal root must carry:
+ *   data-wg-ui="1"
+ *   data-wg-modal="panel|banner|auto-panel"
+ *   data-wg-ready="1" when painted and readable
+ *
+ * Agents: do not claim the stepper works unless
+ *   `assertWgOverlayReady(page)` (or WAYGRAPH_PROVE_EXIT=1) passes.
+ */
+export const WG_UI_SEL = '[data-wg-ui="1"]';
+export const WG_READY_PANEL_SEL = '[data-wg-modal="panel"][data-wg-ready="1"]';
+export const WG_READY_AUTO_SEL = '[data-wg-modal="auto-panel"][data-wg-ready="1"]';
+export const WG_READY_BANNER_SEL = '[data-wg-modal="banner"][data-wg-ready="1"]';
+/** Browser-side beacon reader (also installed as window.__wgOverlayBeacon). */
+export function readWgOverlayBeaconInPage() {
+    const w = globalThis;
+    if (typeof w.__wgOverlayBeacon === "function")
+        return w.__wgOverlayBeacon();
+    return Array.from(document.querySelectorAll(WG_UI_SEL)).map((el) => {
+        const r = el.getBoundingClientRect();
+        const st = getComputedStyle(el);
+        return {
+            id: el.id || null,
+            modal: el.getAttribute("data-wg-modal"),
+            ready: el.getAttribute("data-wg-ready") === "1",
+            phase: el.getAttribute("data-wg-phase"),
+            step: el.getAttribute("data-wg-step"),
+            block: el.getAttribute("data-wg-block"),
+            collapsed: el.getAttribute("data-wg-collapsed") === "1" || el.classList.contains("wg-collapsed"),
+            opacity: st.opacity,
+            textLen: (el.textContent || "").trim().length,
+            w: Math.round(r.width),
+            h: Math.round(r.height),
+            visible: r.width > 0 && r.height > 0 && Number(st.opacity) > 0.05,
+        };
+    });
+}
+export async function readWgOverlayBeacon(page) {
+    return page.evaluate(() => {
+        const w = window;
+        if (typeof w.__wgOverlayBeacon === "function") {
+            return w.__wgOverlayBeacon();
+        }
+        return Array.from(document.querySelectorAll('[data-wg-ui="1"]')).map((el) => {
+            const r = el.getBoundingClientRect();
+            const st = getComputedStyle(el);
+            return {
+                id: el.id || null,
+                modal: el.getAttribute("data-wg-modal"),
+                ready: el.getAttribute("data-wg-ready") === "1",
+                phase: el.getAttribute("data-wg-phase"),
+                step: el.getAttribute("data-wg-step"),
+                block: el.getAttribute("data-wg-block"),
+                collapsed: el.getAttribute("data-wg-collapsed") === "1" || el.classList.contains("wg-collapsed"),
+                opacity: st.opacity,
+                textLen: (el.textContent || "").trim().length,
+                w: Math.round(r.width),
+                h: Math.round(r.height),
+                visible: r.width > 0 && r.height > 0 && Number(st.opacity) > 0.05,
+            };
+        });
+    });
+}
+/**
+ * Hard gate: a blank / missing / opacity-0 modal fails.
+ * Use after demo/auto paints its first overlay.
+ */
+export async function assertWgOverlayReady(page, opts) {
+    const modal = opts?.modal ?? "panel";
+    const minText = opts?.minTextLen ?? 12;
+    const rows = await readWgOverlayBeacon(page);
+    const hit = rows.find((r) => r.modal === modal &&
+        r.ready &&
+        r.visible &&
+        r.textLen >= minText &&
+        (opts?.allowCollapsed || !r.collapsed || r.textLen >= minText));
+    if (!hit) {
+        throw new Error(`waygraph overlay NOT ready (modal=${modal}, minTextLen=${minText}). ` +
+            `beacons=${JSON.stringify(rows)}. ` +
+            `Do not claim stepper/modal works.`);
+    }
+    return hit;
+}

package/dist/session/pilot.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Waygraph Pilot: the one bootstrap call an agent needs to start driving a
+ * real, persistent, inspectable browser session toward a natural-language
+ * goal it plans and executes itself.
+ *
+ * Deliberately NOT a resolver that maps one ask to one Block
+ * (`resolveAsk`/`pilotNarrate`/`pilotAct`, the v1 shape this replaced - see
+ * git tag `waygraph-pilot-v1-logs-prettified` for that history). Real
+ * requests are multi-step ("log in and buy the backpack for me", "make a
+ * signature draft request") and need an agent that plans a whole sequence
+ * against the graph, not a single best-matching edge. `pilotStart` does not
+ * plan, resolve, narrate, or act on anything - it only combines two
+ * already-proven, separately-existing primitives into one payload:
+ *
+ * - `spawnDetachedSession` (same mechanism as `auto --cli --detach`) - a
+ *   real, persistent, visible-if-headful Playwright session an agent can
+ *   keep driving across many calls, not a fresh session per request.
+ * - `discoverGraph` (same mechanism as `waygraph graph`) - the WHOLE
+ *   project's Checkpoint/edge/description graph, not just what's reachable
+ *   from the session's current position, because planning a multi-step
+ *   route needs to see steps ahead, not just the next one.
+ *
+ * Driving the session afterward - `auto send <id> "<pick>"`, `auto status
+ * <id>`, `auto dom <id>`, `auto trace <id>` - is left entirely to whatever
+ * agent is holding it. All four already existed before this file did; see
+ * openspec/changes/waygraph-pilot/design.md for the worked example (a real
+ * login + add-to-cart + checkout run against examples/saucedemo, driven by
+ * hand-picking indices from each status response) that proved this needs no
+ * new execution primitive.
+ */
+import { type WaygraphGraph } from "../analysis/graph.js";
+import { listBrowserSessions, type SessionMeta } from "./auto-session-ipc.js";
+import { type BrowserStartInit } from "./browser.js";
+import type { SessionSnapshot } from "../auto-session.js";
+export interface PilotStartResult {
+    sessionId: string;
+    socketPath: string;
+    headless: boolean;
+    /** The whole project's Block graph - every Checkpoint/edge/description, not just what's reachable right now. */
+    graph: WaygraphGraph;
+    /** The session's starting position, or `null` if the very first `status` read failed. */
+    snapshot: SessionSnapshot | null;
+}
+/**
+ * Starts a detached session and reads back its own graph + starting
+ * snapshot in one call, so an agent bootstraps with everything it needs
+ * (a live session it can keep driving, and the full map of what exists) in
+ * one round trip instead of separately knowing to chain `auto --cli
+ * --detach` and `waygraph graph` itself.
+ */
+export declare function pilotStart(init: BrowserStartInit): Promise<PilotStartResult>;
+/** Reattach to an existing browser session — does not spawn a new browser. */
+export declare function pilotAttach(projectDir: string, sessionId: string, inject?: string[]): Promise<PilotStartResult>;
+export { listBrowserSessions, type SessionMeta };

package/dist/session/pilot.js

@@ -0,0 +1,80 @@
+/**
+ * Waygraph Pilot: the one bootstrap call an agent needs to start driving a
+ * real, persistent, inspectable browser session toward a natural-language
+ * goal it plans and executes itself.
+ *
+ * Deliberately NOT a resolver that maps one ask to one Block
+ * (`resolveAsk`/`pilotNarrate`/`pilotAct`, the v1 shape this replaced - see
+ * git tag `waygraph-pilot-v1-logs-prettified` for that history). Real
+ * requests are multi-step ("log in and buy the backpack for me", "make a
+ * signature draft request") and need an agent that plans a whole sequence
+ * against the graph, not a single best-matching edge. `pilotStart` does not
+ * plan, resolve, narrate, or act on anything - it only combines two
+ * already-proven, separately-existing primitives into one payload:
+ *
+ * - `spawnDetachedSession` (same mechanism as `auto --cli --detach`) - a
+ *   real, persistent, visible-if-headful Playwright session an agent can
+ *   keep driving across many calls, not a fresh session per request.
+ * - `discoverGraph` (same mechanism as `waygraph graph`) - the WHOLE
+ *   project's Checkpoint/edge/description graph, not just what's reachable
+ *   from the session's current position, because planning a multi-step
+ *   route needs to see steps ahead, not just the next one.
+ *
+ * Driving the session afterward - `auto send <id> "<pick>"`, `auto status
+ * <id>`, `auto dom <id>`, `auto trace <id>` - is left entirely to whatever
+ * agent is holding it. All four already existed before this file did; see
+ * openspec/changes/waygraph-pilot/design.md for the worked example (a real
+ * login + add-to-cart + checkout run against examples/saucedemo, driven by
+ * hand-picking indices from each status response) that proved this needs no
+ * new execution primitive.
+ */
+import { discoverGraph } from "../analysis/graph.js";
+import { requestSession, listBrowserSessions, resolveSessionMeta, } from "./auto-session-ipc.js";
+import { browserStart } from "./browser.js";
+/**
+ * Starts a detached session and reads back its own graph + starting
+ * snapshot in one call, so an agent bootstraps with everything it needs
+ * (a live session it can keep driving, and the full map of what exists) in
+ * one round trip instead of separately knowing to chain `auto --cli
+ * --detach` and `waygraph graph` itself.
+ */
+export async function pilotStart(init) {
+    const { resolveInjectRoots } = await import("./block-inject.js");
+    const exploreInject = init.inject ??
+        (init.injectTokens?.length ? resolveInjectRoots(init.injectTokens, init.projectDir) : undefined);
+    const started = await browserStart({
+        ...init,
+        ...(exploreInject?.length ? { inject: exploreInject } : {}),
+        // Pilot navigates to baseURL on start (unlike `browser`, which defaults to about:blank).
+        skipInitialNavigation: init.skipInitialNavigation ?? false,
+    });
+    const graph = await discoverGraph(init.projectDir, exploreInject?.length ? { inject: exploreInject } : undefined);
+    const status = await requestSession(init.projectDir, started.sessionId, { op: "status" });
+    return {
+        sessionId: started.sessionId,
+        socketPath: started.socketPath,
+        headless: started.headless,
+        graph,
+        snapshot: status.ok ? status.snapshot : null,
+    };
+}
+/** Reattach to an existing browser session — does not spawn a new browser. */
+export async function pilotAttach(projectDir, sessionId, inject) {
+    const meta = resolveSessionMeta(sessionId, projectDir);
+    if (!meta) {
+        throw new Error(`waygraph pilot attach: no such session "${sessionId}" — run \`waygraph pilot sessions\` from the project dir`);
+    }
+    const graph = await discoverGraph(meta.projectDir, inject?.length ? { inject } : undefined);
+    const status = await requestSession(meta.projectDir, sessionId, { op: "status" });
+    if (!status.ok) {
+        throw new Error(`waygraph pilot attach: session "${sessionId}" not reachable (${status.error})`);
+    }
+    return {
+        sessionId: meta.sessionId,
+        socketPath: meta.socketPath,
+        headless: meta.headless,
+        graph,
+        snapshot: status.snapshot,
+    };
+}
+export { listBrowserSessions };

package/dist/traverse/coverage.d.ts

@@ -0,0 +1,59 @@
+export interface TraverseCoverageReport {
+    version: 1;
+    generatedAt: string;
+    projectDir: string;
+    parallel: number;
+    /** Unique edge keys in the discovered graph (block names). */
+    edgesTotal: number;
+    /** Graph edges successfully walked this suite (after instance normalize). */
+    edgesHit: number;
+    /** edgesHit / edgesTotal (0 when total is 0). */
+    ratio: number;
+    /** Optional suite gate that was applied (0-1). */
+    minEdgeCoverage?: number;
+    /** true when minEdgeCoverage was set and ratio met it. */
+    coveragePass?: boolean;
+    /** Sorted graph edge keys that were hit. */
+    hit: string[];
+    /** Sorted graph edge keys never walked. */
+    missed: string[];
+    /** Raw worker hit keys (may include block::instanceId). */
+    rawHit?: string[];
+    workers?: Array<{
+        traverseId: string;
+        exitCode: number;
+        steps: number;
+        edgesHit: number;
+        leaf?: string;
+    }>;
+}
+/** Static graph edge key = Block runtime name. */
+export declare function edgeKeyFromGraphEdge(edge: {
+    block: string;
+}): string;
+/** Collect unique edge keys from a WaygraphGraph-like edges list. */
+export declare function collectGraphEdgeKeys(edges: ReadonlyArray<{
+    block: string;
+}>): string[];
+/**
+ * Map a worker hit key onto the static graph key it covers.
+ * `add-to-cart::sku-1` -> `add-to-cart` when that block is in the graph.
+ */
+export declare function normalizeHitKey(hitKey: string, graphKeys: ReadonlySet<string>): string | null;
+/**
+ * Parse --min-edge-coverage: `0.8`, `80%`, `80` (as percent when > 1).
+ * Returns 0-1 fraction, or null when unset/invalid.
+ */
+export declare function parseMinEdgeCoverage(raw: unknown): number | null;
+export declare function buildCoverageReport(opts: {
+    projectDir: string;
+    parallel: number;
+    allEdgeKeys: readonly string[];
+    hitKeys: ReadonlySet<string> | readonly string[];
+    minEdgeCoverage?: number | null;
+    workers?: TraverseCoverageReport["workers"];
+}): TraverseCoverageReport;
+/** Greppable one-liner for agents/CI. */
+export declare function formatCoverageLine(report: TraverseCoverageReport): string;
+export declare function defaultCoverageOutPath(projectDir: string): string;
+export declare function writeCoverageReport(path: string, report: TraverseCoverageReport): void;

package/dist/traverse/coverage.js

@@ -0,0 +1,127 @@
+/**
+ * Phase E: traverse edge coverage report + suite gate.
+ * Coverage is independent of leaf PASS - a green leaf can still fail CI
+ * when --min-edge-coverage is set and ratio is too low.
+ *
+ * Denominator = unique static graph edge block names (FF inners stay as their
+ * own graph edges when discovered; RFC open Q deferred - no covered-via-prefix yet).
+ * A hit of `block::instanceId` counts as covering `block`.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+/** Static graph edge key = Block runtime name. */
+export function edgeKeyFromGraphEdge(edge) {
+    return edge.block;
+}
+/** Collect unique edge keys from a WaygraphGraph-like edges list. */
+export function collectGraphEdgeKeys(edges) {
+    const set = new Set();
+    for (const e of edges)
+        set.add(edgeKeyFromGraphEdge(e));
+    return [...set].sort();
+}
+/**
+ * Map a worker hit key onto the static graph key it covers.
+ * `add-to-cart::sku-1` -> `add-to-cart` when that block is in the graph.
+ */
+export function normalizeHitKey(hitKey, graphKeys) {
+    if (graphKeys.has(hitKey))
+        return hitKey;
+    const base = hitKey.includes("::") ? hitKey.slice(0, hitKey.indexOf("::")) : hitKey;
+    if (graphKeys.has(base))
+        return base;
+    return null;
+}
+/**
+ * Parse --min-edge-coverage: `0.8`, `80%`, `80` (as percent when > 1).
+ * Returns 0-1 fraction, or null when unset/invalid.
+ */
+export function parseMinEdgeCoverage(raw) {
+    if (raw === undefined || raw === null || raw === "")
+        return null;
+    if (typeof raw === "number" && Number.isFinite(raw)) {
+        if (raw < 0)
+            return null;
+        if (raw <= 1)
+            return raw;
+        if (raw <= 100)
+            return raw / 100;
+        return null;
+    }
+    if (typeof raw !== "string")
+        return null;
+    const t = raw.trim().toLowerCase();
+    if (!t)
+        return null;
+    if (t.endsWith("%")) {
+        const n = Number(t.slice(0, -1));
+        if (!Number.isFinite(n) || n < 0 || n > 100)
+            return null;
+        return n / 100;
+    }
+    const n = Number(t);
+    if (!Number.isFinite(n) || n < 0)
+        return null;
+    if (n <= 1)
+        return n;
+    if (n <= 100)
+        return n / 100;
+    return null;
+}
+export function buildCoverageReport(opts) {
+    const all = [...new Set(opts.allEdgeKeys)].sort();
+    const graphSet = new Set(all);
+    const rawList = Array.isArray(opts.hitKeys) ? [...opts.hitKeys] : [...opts.hitKeys];
+    const covered = new Set();
+    for (const raw of rawList) {
+        const n = normalizeHitKey(raw, graphSet);
+        if (n)
+            covered.add(n);
+    }
+    const hit = all.filter((k) => covered.has(k));
+    const missed = all.filter((k) => !covered.has(k));
+    const edgesTotal = all.length;
+    const edgesHit = hit.length;
+    const ratio = edgesTotal === 0 ? 0 : edgesHit / edgesTotal;
+    const min = opts.minEdgeCoverage != null && Number.isFinite(opts.minEdgeCoverage)
+        ? Math.min(1, Math.max(0, opts.minEdgeCoverage))
+        : undefined;
+    const coveragePass = min === undefined ? undefined : ratio + 1e-12 >= min;
+    const coverageExtra = min !== undefined && coveragePass !== undefined
+        ? { minEdgeCoverage: min, coveragePass }
+        : {};
+    return {
+        version: 1,
+        generatedAt: new Date().toISOString(),
+        projectDir: opts.projectDir,
+        parallel: opts.parallel,
+        edgesTotal,
+        edgesHit,
+        ratio: Math.round(ratio * 10000) / 10000,
+        ...coverageExtra,
+        hit,
+        missed,
+        rawHit: [...new Set(rawList)].sort(),
+        ...(opts.workers ? { workers: opts.workers } : {}),
+    };
+}
+/** Greppable one-liner for agents/CI. */
+export function formatCoverageLine(report) {
+    const pct = (report.ratio * 100).toFixed(1);
+    const minPart = report.minEdgeCoverage !== undefined
+        ? ` min=${(report.minEdgeCoverage * 100).toFixed(1)}%` +
+            (report.coveragePass === false
+                ? " FAIL"
+                : report.coveragePass === true
+                    ? " PASS"
+                    : "")
+        : "";
+    return `[Coverage edges=${report.edgesHit}/${report.edgesTotal} ratio=${pct}%${minPart}]`;
+}
+export function defaultCoverageOutPath(projectDir) {
+    return join(projectDir, ".waygraph-traverse", "coverage.json");
+}
+export function writeCoverageReport(path, report) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(report, null, 2) + "\n", "utf-8");
+}

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

@@ -0,0 +1,47 @@
+export type TraverseSessionMode = "clone" | "inherit";
+export interface TraverseWorkerResult {
+    exitCode: number;
+    steps: number;
+    edgesHit: string[];
+    leaf?: string;
+}
+export interface TraverseOptions {
+    baseURL?: string;
+    startUrl?: string;
+    /** Seed checkpoint label (optional - otherwise detect from page / nav). */
+    from?: string;
+    /** Global Mem seed JSON (or use WAYGRAPH_DATA / WAYGRAPH_AUTO_MEM). */
+    data?: string;
+    /** Max Block runs this traverse (default 50). */
+    maxSteps?: number;
+    /** Max times a checkpoint may be visited (default 2). */
+    maxVisitsPerNode?: number;
+    /** Max times an edge key (block::instanceId) may be taken (default 1). */
+    maxVisitsPerEdge?: number;
+    /** Wall-clock budget ms (default 15m). */
+    timeoutMs?: number;
+    /** Show browser (default headless). */
+    headed?: boolean;
+    /** Traverse id for greppable lines (default traverse-1). */
+    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;
+    /**
+     * Phase E: fail suite (exit 2) when hit/total ratio is below this 0-1 fraction.
+     * Leaf PASS alone does not satisfy the gate.
+     */
+    minEdgeCoverage?: number;
+    /** Phase E: write coverage JSON here (default `.waygraph-traverse/coverage.json`). */
+    coverageOut?: string;
+    /** Phase E: skip writing coverage.json (still prints the Coverage line). */
+    noCoverageReport?: boolean;
+}
+/**
+ * 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 declare function runTraverse(projectDir: string, options?: TraverseOptions): Promise<number>;