waygraph 0.13.7 → 0.14.0

package/dist/cli.js

@@ -19,6 +19,8 @@ import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
 import { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";
 import { runAutoExplore } from "./auto-explore-run.js";
+import { pilotStart } from "./pilot.js";
+import { spawnDetachedSession, requestSession, runAttachLoop, runAutoServeCommand, } from "./auto-session-ipc.js";
 import { runAgentDive } from "./agent-dive.js";
 import { runTraverse } from "./traverse-run.js";
 import { parseMinEdgeCoverage } from "./traverse-coverage.js";
@@ -232,6 +234,7 @@ import {
   completeSequentialTodoDock,
   applyDevicePhase,
   resolveDeviceState,
+  WAYGRAPH_RING_CSS,
 } from "waygraph";
 
 function walkDir(dir, pattern) {
@@ -416,45 +419,10 @@ function seedMemForFlow(mem, flowBlocks, json, label) {
 // Purely CLI-level orchestration - no engine changes, no change to the
 // non-STEP path above.
 const RING_CSS =
-  "#wg-ring{position:fixed;z-index:2147483646;pointer-events:none;opacity:0;" +
-  "border:2.5px solid #7C3AED;border-radius:10px;" +
-  // Opacity fade only - NEVER transition border-color/box-shadow. Tone swaps
-  // (auto gray -> planned purple -> warning yellow) must snap instantly;
-  // color transitions read as a muddy gray/purple/yellow morph on ring 2+.
-  "box-shadow:0 0 0 4px rgba(124,58,237,.16);transition:opacity .3s ease;}" +
-  // Planned (stubs / fixtures / YAP / instruction.highlights) = purple.
-  // Automation (verify fallback, unmatched fill/click) = gray - operators
-  // can ignore engine checks and watch purple + semantic tones.
-  "#wg-ring[data-tone=planned]{border-color:#7C3AED;box-shadow:0 0 0 4px rgba(124,58,237,.16);}" +
-  "#wg-ring[data-tone=auto]{border-color:#9CA3AF;box-shadow:0 0 0 4px rgba(156,163,175,.28);}" +
-  "#wg-ring[data-tone=info]{border-color:#3B82F6;box-shadow:0 0 0 4px rgba(59,130,246,.22);}" +
-  "#wg-ring[data-tone=warning]{border-color:#EAB308;box-shadow:0 0 0 4px rgba(234,179,8,.22);}" +
-  "#wg-ring[data-tone=danger]{border-color:#EF4444;box-shadow:0 0 0 4px rgba(239,68,68,.22);}" +
-  "#wg-ring[data-tone=success]{border-color:#22C55E;box-shadow:0 0 0 4px rgba(34,197,94,.22);}" +
-  // A real element, not a ::after pseudo-element - a pseudo-element's
-  // position is CSS-relative to the ring's own box (left:0 always meant
-  // "the ring's own left edge"), so it had no way to be clamped back onto
-  // screen when that box sat near a viewport edge - the label's text just
-  // ran off, invisibly, with no overflow guard at all. A real sibling can
-  // be measured (its actual rendered width) and repositioned in JS -
-  // pushed back onto screen, same width, never shrunk. See
-  // window.__wgPositionRing in installOverlay.
-  "#wg-ring-label{position:fixed;z-index:2147483646;pointer-events:none;opacity:0;" +
-  "max-width:min(360px,70vw);white-space:normal;padding:6px 10px;border-radius:7px;background:#7C3AED;color:#fff;" +
-  "font:600 12px/1.35 system-ui,sans-serif;transition:opacity .3s ease;}" +
-  "#wg-ring-label[data-tone=planned]{background:#7C3AED;color:#fff;}" +
-  "#wg-ring-label[data-tone=auto]{background:#6B7280;color:#fff;}" +
-  "#wg-ring-label[data-tone=info]{background:#2563EB;color:#fff;}" +
-  "#wg-ring-label[data-tone=warning]{background:#EAB308;color:#1c1917;}" +
-  "#wg-ring-label[data-tone=danger]{background:#DC2626;color:#fff;}" +
-  "#wg-ring-label[data-tone=success]{background:#16A34A;color:#fff;}" +
-  // size: ring pad + label font; weight: label boldness
-  "#wg-ring[data-size=sm]{border-width:1.5px;border-radius:8px;}" +
-  "#wg-ring[data-size=lg]{border-width:4px;border-radius:12px;}" +
-  "#wg-ring-label[data-size=sm]{font-size:10px;line-height:1.25;padding:4px 7px;border-radius:5px;}" +
-  "#wg-ring-label[data-size=lg]{font-size:16px;line-height:1.35;padding:8px 14px;border-radius:9px;max-width:min(480px,85vw);}" +
-  "#wg-ring-label[data-weight=bold]{font-weight:800;}" +
-  "#wg-ring-label[data-weight=normal]{font-weight:600;}" +
+  // Shared with pilot-overlay.ts's showPilotVision - same ring/label CSS,
+  // one source of truth (highlights.ts), so a Blind Pilot vision ring and a
+  // demo stepper ring never visually drift apart.
+  WAYGRAPH_RING_CSS +
   // Mouse cursor icon that travels to a target before it's acted on, plus a
   // quick expanding ripple at the moment of a click - same idea as
   // help-center-clip-engine's #clip-cursor/#clip-ring (video-pipeline). The
@@ -6343,7 +6311,7 @@ async function validateFlows(projectDir) {
 // instant a regular Block's act() calls a navigation method; this command
 // sweeps a whole project in one shot for contexts with no editor watching
 // (CI, an autonomous agent writing Block files without a language server).
-// See openspec/changes/nav-block-and-check/ for the full rationale.
+// See openspec/specs/nav-block-and-check/spec.md for the full rationale.
 // ---------------------------------------------------------------------------
 function discoverBlocks(projectDir) {
     return walkDir(projectDir, /\.block\.ts$/);
@@ -6362,6 +6330,19 @@ function isNavBlockMarked(val) {
     return val.__waygraphKind === "nav";
 }
 const NAV_METHOD_CALLS = ["page.goto(", "page.reload(", "page.goBack(", "page.goForward("];
+/**
+ * Matches a selector-taking Trait factory call whose first argument is a
+ * literal string/template, not an identifier or property access - the exact
+ * shape found repeatedly in hand-written assertion Blocks
+ * (`Trait.visible("#some-id")` instead of `Trait.visible(SomeSel.thing)`).
+ * `Trait.url(...)` is deliberately excluded - it takes a URLPatternInit, never
+ * a DOM selector. Same file-scoped-regex bluntness the nav-escape sweep above
+ * already accepts (see openspec/specs/nav-block-and-check/spec.md) - a known
+ * blind spot on string concatenation/template-built selectors, not solved
+ * here for the same "recipe before promotion" reason that check accepts its
+ * own shared-helper blind spot.
+ */
+const INLINE_SELECTOR_CALL = /\b(?:Trait\.visible|Trait\.text|textEquals|visible)\(\s*["'`]/;
 /**
  * Walks every `*.block.ts` file under `projectDir`, imports each to find its
  * exported Blocks, and for any Block NOT built via `defineNavBlock`, scans
@@ -6457,7 +6438,8 @@ function initCommand(projectName) {
 }
 async function checkCommand(projectDir) {
     const files = discoverBlocks(projectDir);
-    const warnings = [];
+    const navWarnings = [];
+    const selWarnings = [];
     for (const file of files) {
         let mod;
         try {
@@ -6470,15 +6452,21 @@ async function checkCommand(projectDir) {
         for (const [exportName, exported] of Object.entries(mod)) {
             if (!isBlockLike(exported))
                 continue;
-            if (isNavBlockMarked(exported))
-                continue;
             src ??= readFileSync(file, "utf-8");
-            if (NAV_METHOD_CALLS.some((needle) => src.includes(needle))) {
-                warnings.push({ file, blockName: exported.name, exportName });
+            // Nav-escape: NavBlocks are exempt (their generated act() is the one
+            // legitimate goto/click call site).
+            if (!isNavBlockMarked(exported) &&
+                NAV_METHOD_CALLS.some((needle) => src.includes(needle))) {
+                navWarnings.push({ file, blockName: exported.name, exportName });
+            }
+            // Inline selector: applies to every Block kind, including NavBlocks -
+            // a Nav's own `verify` array is just as likely to inline a selector.
+            if (INLINE_SELECTOR_CALL.test(src)) {
+                selWarnings.push({ file, blockName: exported.name, exportName });
             }
         }
     }
-    return warnings;
+    return { navWarnings, selWarnings };
 }
 function takeFlagValue(argv, i, a, flag) {
     if (a.startsWith(flag + "=")) {
@@ -6560,6 +6548,9 @@ function parseRunFlags(argv) {
         else if (a === "--cli") {
             out.cli = true;
         }
+        else if (a === "--detach") {
+            out.detach = true;
+        }
         else if (a === "--headed") {
             out.headed = true;
         }
@@ -6881,9 +6872,81 @@ function usage() {
 Primary (less is more):
   waygraph auto  [project|.flow.ts]        Interactive explore (picker)
                  --cli                     Terminal menu instead of browser panel
+                 --cli --detach            Run the --cli session as a background socket
+                                           server; prints {sessionId, socketPath} and exits
                  --blocks <From> <To>      Graph path-find From->To, then run
                  --data '{...}'            Mem seed (same as demo/run)
                  (pass a .flow.ts to run that flow - same as run)
+                 --cli --detach --non-headless  Detached session with a real visible browser
+                                           (same --non-headless flag run/demo already use)
+  waygraph auto send <sessionId> "<pick>"  Send one pick to a --detach session, print
+                                           the resulting state as JSON (no TTY needed)
+                 --timeout <ms>            Override the 15s default wait for this one call -
+                                           a single Block can legitimately run a slow real
+                                           interaction (e.g. a multi-step mouse drag)
+  waygraph auto status <sessionId>         Read a --detach session's state (no side effects)
+  waygraph auto attach <sessionId>         Reopen an interactive terminal against a
+                                           running --detach session
+  waygraph auto dom <sessionId>            Read the live page's structure (no side effects)
+                 --mode aria|full          Default aria (Playwright ariaSnapshotJSON, AI mode);
+                                           full = bounded raw DOM walk (tag/attrs/text/children)
+                 --selector <sel>          Scope either mode to one element's subtree
+                 --depth N                 Limit snapshot depth (aria: native; full: caller cap)
+  waygraph auto trace <sessionId>          Read the session's Checkpoint/Block-level history
+                                           (no side effects; not raw click/fill recording)
+  waygraph auto console <sessionId>        Read the real browser console/pageerror messages and
+                                           failed (4xx/5xx) network responses seen so far - for
+                                           diagnosing a silent failure (e.g. a form submit that
+                                           does nothing observable in the DOM) that inspectDom
+                                           alone can't explain, since it only reads what actually
+                                           rendered, not what the page/network actually said
+  waygraph auto storage <sessionId>        Read localStorage/sessionStorage plus registered
+                                           service workers (scope/active URL/state) - client-
+                                           side state (push-subscription/auth tokens etc.) that
+                                           never appears in the rendered DOM inspectDom reads
+  waygraph auto click <sessionId> <sel>    Click a real element - works even with zero Blocks
+                                           (Blind Pilot: act before any Block covers this)
+  waygraph auto type <sessionId> <sel> <text>  Fill a real input the same way
+  waygraph auto goto <sessionId> <url>     Navigate the real live page
+  waygraph auto press <sessionId> <sel> <key>
+                                           Presses a real key (Playwright name, e.g. Enter,
+                                           Escape, Tab) on a real focused element - many real
+                                           inline-edit inputs (no visible Save button until you
+                                           type) commit on Enter, not blur/click-elsewhere
+  waygraph auto upload <sessionId> <sel> <image|pdf|video|path>
+                                           Fill a real <input type="file"> - a built-in stub
+                                           (small, real, valid: assets/stubs/stub.png|pdf|mp4)
+                                           or a caller-supplied file path
+                 (click/type/goto/upload each re-detect the session's Checkpoint afterward,
+                  same detection send/status already use)
+  waygraph auto reload <sessionId>         Re-discover the project's Block library/graph
+                                           from disk without restarting the session - picks
+                                           up a Block written to disk mid-session
+  waygraph auto reach <sessionId> <Checkpoint>  Path-find from here to Checkpoint and run
+                                           the whole route in one call - not one auto send
+                                           per step. Same findBlockPath BFS auto --blocks
+                                           <From> <To> already uses, against this session's
+                                           own live graph/position. Fails loud (not a guess)
+                                           if a step has several live options on the page
+                                           (an instanceOptions Block) - use send for that step
+  waygraph auto resync <sessionId>         Force here to be re-detected from the real live
+                                           page right now, discarding whatever was cached -
+                                           fixes a session's tracked position going stale
+                                           after anything OUTSIDE this session changed the
+                                           page (e.g. a human clicking around in a visible
+                                           --non-headless session someone is co-driving);
+                                           send/reach never do this on their own, since they
+                                           only re-detect when the position is already unknown
+  waygraph pilot start                     Bootstrap for an agent: starts a --detach session
+                                           (same as auto --cli --detach) AND reads back the
+                                           whole project's Block graph (same as waygraph
+                                           graph) in one call - {sessionId, socketPath,
+                                           headless, graph, snapshot}. Drive it afterward with
+                                           auto send/status/dom/trace <sessionId> - pilot start
+                                           does not resolve, narrate, or act on anything itself;
+                                           planning a multi-step request is the agent's job.
+                 --non-headless            Real visible browser (same flag as auto/demo/run)
+                 --base-url / --data       Same as auto/demo/run
   waygraph demo  [--blocks <flow|file|spec>]  Watch with step overlay (QA path)
                  --data '{...}'            Mem seed JSON (or inline flow({...}))
                  --auto-next               Auto-advance steps (alias: --autoplay)
@@ -7311,6 +7374,233 @@ Agents shipped: waygraph-planner, waygraph-author, waygraph-healer.
         }
         case "graph":
         case "auto": {
+            // auto send|status|attach <sessionId> - session control against a
+            // --detach'd background session. Intercepted before the normal
+            // project-directory resolution below, same pattern `try demo|auto|
+            // auto:cli` already uses for a sub-verb positional.
+            if (command === "auto" &&
+                (args[1] === "send" ||
+                    args[1] === "status" ||
+                    args[1] === "attach" ||
+                    args[1] === "dom" ||
+                    args[1] === "trace" ||
+                    args[1] === "console" ||
+                    args[1] === "storage" ||
+                    args[1] === "upload" ||
+                    args[1] === "click" ||
+                    args[1] === "type" ||
+                    args[1] === "press" ||
+                    args[1] === "goto" ||
+                    args[1] === "reload" ||
+                    args[1] === "reach" ||
+                    args[1] === "resync")) {
+                const sub = args[1];
+                const sessionId = args[2];
+                if (!sessionId) {
+                    console.error(`waygraph auto ${sub}: missing <sessionId>`);
+                    process.exit(1);
+                }
+                const proj = resolve(process.cwd());
+                if (sub === "attach") {
+                    await runAttachLoop(proj, sessionId);
+                    break;
+                }
+                if (sub === "send") {
+                    const pick = args[3];
+                    if (pick === undefined) {
+                        console.error('waygraph auto send: usage: waygraph auto send <sessionId> "<pick>" [--timeout <ms>]');
+                        process.exit(1);
+                    }
+                    // Real, direct need found live: a single Block can legitimately
+                    // run a genuinely slow real interaction (e.g. a multi-step mouse
+                    // drag) that exceeds the 15s default - same reasoning `auto
+                    // reach` already gets a 90s default for (multiple Blocks in one
+                    // call). Unlike reach, send has no way to know ahead of time
+                    // whether the ONE Block it's running is fast or slow, so this is
+                    // opt-in via a flag rather than a raised default.
+                    let timeoutMs;
+                    for (let i = 4; i < args.length; i++) {
+                        if (args[i] === "--timeout") {
+                            const raw = args[++i];
+                            const n = Number(raw);
+                            if (!Number.isFinite(n) || n <= 0) {
+                                console.error(`waygraph auto send: --timeout must be a positive number of ms, got "${raw}"`);
+                                process.exit(1);
+                            }
+                            timeoutMs = n;
+                        }
+                    }
+                    const res = await requestSession(proj, sessionId, { op: "send", pick }, timeoutMs);
+                    console.log(JSON.stringify(res));
+                    if (!res.ok)
+                        process.exitCode = 1;
+                    break;
+                }
+                if (sub === "dom") {
+                    const domArgs = args.slice(3);
+                    let mode;
+                    let selector;
+                    let depth;
+                    for (let i = 0; i < domArgs.length; i++) {
+                        const a = domArgs[i];
+                        if (a === "--mode" || a.startsWith("--mode=")) {
+                            const v = a.startsWith("--mode=") ? a.slice("--mode=".length) : domArgs[++i];
+                            if (v !== "aria" && v !== "full") {
+                                console.error(`waygraph auto dom: --mode must be "aria" or "full", got "${v}"`);
+                                process.exit(1);
+                            }
+                            mode = v;
+                        }
+                        else if (a === "--selector" || a.startsWith("--selector=")) {
+                            selector = a.startsWith("--selector=") ? a.slice("--selector=".length) : domArgs[++i];
+                        }
+                        else if (a === "--depth" || a.startsWith("--depth=")) {
+                            const raw = a.startsWith("--depth=") ? a.slice("--depth=".length) : domArgs[++i];
+                            const n = Number(raw);
+                            if (!Number.isInteger(n) || n < 1) {
+                                console.error(`waygraph auto dom: --depth must be a positive integer, got "${raw}"`);
+                                process.exit(1);
+                            }
+                            depth = n;
+                        }
+                        else {
+                            console.error(`waygraph auto dom: unrecognized argument "${a}"`);
+                            process.exit(1);
+                        }
+                    }
+                    const res = await requestSession(proj, sessionId, {
+                        op: "dom",
+                        ...(mode ? { mode } : {}),
+                        ...(selector ? { selector } : {}),
+                        ...(depth !== undefined ? { depth } : {}),
+                    });
+                    console.log(JSON.stringify(res));
+                    if (!res.ok)
+                        process.exitCode = 1;
+                    break;
+                }
+                if (sub === "trace") {
+                    const res = await requestSession(proj, sessionId, { op: "trace" });
+                    console.log(JSON.stringify(res));
+                    if (!res.ok)
+                        process.exitCode = 1;
+                    break;
+                }
+                if (sub === "console") {
+                    const res = await requestSession(proj, sessionId, { op: "console" });
+                    console.log(JSON.stringify(res));
+                    if (!res.ok)
+                        process.exitCode = 1;
+                    break;
+                }
+                if (sub === "storage") {
+                    const res = await requestSession(proj, sessionId, { op: "storage" });
+                    console.log(JSON.stringify(res));
+                    if (!res.ok)
+                        process.exitCode = 1;
+                    break;
+                }
+                if (sub === "click") {
+                    const selector = args[3];
+                    if (selector === undefined) {
+                        console.error('waygraph auto click: usage: waygraph auto click <sessionId> "<selector>"');
+                        process.exit(1);
+                    }
+                    const res = await requestSession(proj, sessionId, { op: "click", selector });
+                    console.log(JSON.stringify(res));
+                    if (!res.ok)
+                        process.exitCode = 1;
+                    break;
+                }
+                if (sub === "type") {
+                    const selector = args[3];
+                    const text = args[4];
+                    if (selector === undefined || text === undefined) {
+                        console.error('waygraph auto type: usage: waygraph auto type <sessionId> "<selector>" "<text>"');
+                        process.exit(1);
+                    }
+                    const res = await requestSession(proj, sessionId, { op: "type", selector, text });
+                    console.log(JSON.stringify(res));
+                    if (!res.ok)
+                        process.exitCode = 1;
+                    break;
+                }
+                if (sub === "press") {
+                    const selector = args[3];
+                    const key = args[4];
+                    if (selector === undefined || key === undefined) {
+                        console.error('waygraph auto press: usage: waygraph auto press <sessionId> "<selector>" <key>');
+                        process.exit(1);
+                    }
+                    const res = await requestSession(proj, sessionId, { op: "press", selector, key });
+                    console.log(JSON.stringify(res));
+                    if (!res.ok)
+                        process.exitCode = 1;
+                    break;
+                }
+                if (sub === "goto") {
+                    const url = args[3];
+                    if (url === undefined) {
+                        console.error("waygraph auto goto: usage: waygraph auto goto <sessionId> <url>");
+                        process.exit(1);
+                    }
+                    const res = await requestSession(proj, sessionId, { op: "goto", url });
+                    console.log(JSON.stringify(res));
+                    if (!res.ok)
+                        process.exitCode = 1;
+                    break;
+                }
+                if (sub === "upload") {
+                    const selector = args[3];
+                    const kindOrPath = args[4];
+                    if (selector === undefined || kindOrPath === undefined) {
+                        console.error('waygraph auto upload: usage: waygraph auto upload <sessionId> "<selector>" <image|pdf|video|path-to-file>');
+                        process.exit(1);
+                    }
+                    const stub = kindOrPath === "image" || kindOrPath === "pdf" || kindOrPath === "video"
+                        ? { selector, stub: kindOrPath }
+                        : { selector, stub: { filePath: resolve(process.cwd(), kindOrPath) } };
+                    const res = await requestSession(proj, sessionId, { op: "upload", ...stub });
+                    console.log(JSON.stringify(res));
+                    if (!res.ok)
+                        process.exitCode = 1;
+                    break;
+                }
+                if (sub === "reload") {
+                    const res = await requestSession(proj, sessionId, { op: "reload" });
+                    console.log(JSON.stringify(res));
+                    if (!res.ok)
+                        process.exitCode = 1;
+                    break;
+                }
+                if (sub === "reach") {
+                    const checkpoint = args[3];
+                    if (checkpoint === undefined) {
+                        console.error("waygraph auto reach: usage: waygraph auto reach <sessionId> <Checkpoint>");
+                        process.exit(1);
+                    }
+                    // Longer than every other op's default (15s): a real multi-step
+                    // route runs several real Blocks in sequence server-side before
+                    // responding - a legitimately slow single request, not a hang.
+                    const res = await requestSession(proj, sessionId, { op: "reach", checkpoint }, 90_000);
+                    console.log(JSON.stringify(res));
+                    if (!res.ok)
+                        process.exitCode = 1;
+                    break;
+                }
+                if (sub === "resync") {
+                    const res = await requestSession(proj, sessionId, { op: "resync" });
+                    console.log(JSON.stringify(res));
+                    if (!res.ok)
+                        process.exitCode = 1;
+                    break;
+                }
+                const res = await requestSession(proj, sessionId, { op: "status" });
+                console.log(JSON.stringify(res));
+                if (!res.ok)
+                    process.exitCode = 1;
+                break;
+            }
             const flags = parseRunFlags(args.slice(1));
             applyRunFlags(flags);
             const mermaid = flags.mermaid === true;
@@ -7345,6 +7635,29 @@ Agents shipped: waygraph-planner, waygraph-author, waygraph-healer.
                     "  or path-find: waygraph auto --blocks LoginPage OrderComplete");
                 process.exit(1);
             }
+            // auto --cli --detach: start the explore session as a background socket
+            // server instead of blocking in the interactive loop. Session control
+            // only applies to --cli (spec: "Headful mode is unaffected").
+            if (command === "auto" && flags.detach) {
+                if (!cliPicker) {
+                    console.error("waygraph auto --detach requires --cli (headful has no session control)");
+                    process.exit(1);
+                }
+                const baseURL = flags.baseUrl ?? process.env.WAYGRAPH_BASE_URL ?? resolveBaseUrl(proj);
+                try {
+                    const meta = await spawnDetachedSession({
+                        projectDir: proj,
+                        ...(baseURL ? { baseURL } : {}),
+                        ...(flags.nonHeadless ? { headless: false } : {}),
+                    });
+                    console.log(JSON.stringify({ sessionId: meta.sessionId, socketPath: meta.socketPath, headless: meta.headless }));
+                }
+                catch (err) {
+                    console.error(`waygraph auto --detach: ${err instanceof Error ? err.message : String(err)}`);
+                    process.exit(1);
+                }
+                break;
+            }
             // auto --blocks From To  (graph path-find + run)
             // auto --blocks '/regex/' or '**/*.block.ts'  (Phase C file select → explore)
             if (command === "auto" && (flags.blocksFromTo || flags.blocks)) {
@@ -7389,6 +7702,49 @@ Agents shipped: waygraph-planner, waygraph-author, waygraph-healer.
             await runAutoExplore(proj, baseURL ? { cli: cliPicker, baseURL } : { cli: cliPicker });
             break;
         }
+        case "pilot": {
+            if (args[1] !== "start") {
+                console.error('waygraph pilot: usage: waygraph pilot start [--non-headless] [--base-url <url>] [--data <json>]');
+                process.exit(1);
+            }
+            const flags = parseRunFlags(args.slice(2));
+            applyRunFlags(flags);
+            const proj = resolve(process.cwd());
+            const baseURL = flags.baseUrl ?? process.env.WAYGRAPH_BASE_URL ?? resolveBaseUrl(proj);
+            try {
+                const result = await pilotStart({
+                    projectDir: proj,
+                    ...(baseURL ? { baseURL } : {}),
+                    ...(flags.nonHeadless ? { headless: false } : {}),
+                });
+                console.log(JSON.stringify(result));
+            }
+            catch (err) {
+                console.error(`waygraph pilot start: ${err instanceof Error ? err.message : String(err)}`);
+                process.exit(1);
+            }
+            break;
+        }
+        // Hidden: the detached server's own entry point, spawned by
+        // `spawnDetachedSession` (auto --cli --detach). Not documented in
+        // usage() - not meant to be invoked directly by a person.
+        case "__auto-serve": {
+            const proj = resolve(args[1] ?? process.cwd());
+            const flags = parseRunFlags(args.slice(2));
+            const sessionIdIdx = args.indexOf("--session-id");
+            const sessionId = sessionIdIdx >= 0 ? args[sessionIdIdx + 1] : undefined;
+            if (!sessionId) {
+                console.error("waygraph __auto-serve: missing --session-id");
+                process.exit(1);
+            }
+            const baseURL = flags.baseUrl ?? process.env.WAYGRAPH_BASE_URL ?? resolveBaseUrl(proj);
+            await runAutoServeCommand({
+                projectDir: proj,
+                ...(baseURL ? { baseURL } : {}),
+                ...(flags.nonHeadless ? { headless: false } : {}),
+            }, sessionId);
+            break;
+        }
         case "try": {
             const flags = parseRunFlags(args.slice(1));
             applyRunFlags(flags);
@@ -7418,20 +7774,30 @@ Agents shipped: waygraph-planner, waygraph-author, waygraph-healer.
         }
         case "check": {
             const proj = resolve(args[1] ?? process.cwd());
-            const warnings = await checkCommand(proj);
-            if (warnings.length === 0) {
+            const { navWarnings, selWarnings } = await checkCommand(proj);
+            if (navWarnings.length === 0) {
                 console.log(`waygraph check: no navigation found outside NavBlocks under ${proj}`);
             }
             else {
-                for (const w of warnings) {
+                for (const w of navWarnings) {
                     const rel = relative(proj, w.file);
                     console.warn(`waygraph check: ${rel} (${w.blockName}) calls page.goto/reload/goBack/goForward outside a NavBlock - consider defineNavBlock instead`);
                 }
-                console.log(`waygraph check: ${warnings.length} nav warning${warnings.length === 1 ? "" : "s"}`);
+                console.log(`waygraph check: ${navWarnings.length} nav warning${navWarnings.length === 1 ? "" : "s"}`);
+            }
+            if (selWarnings.length === 0) {
+                console.log(`waygraph check: no inline selectors found in verify arrays under ${proj}`);
+            }
+            else {
+                for (const w of selWarnings) {
+                    const rel = relative(proj, w.file);
+                    console.warn(`waygraph check: ${rel} (${w.blockName}) has an inline selector literal in verify - move it into a *Sel object`);
+                }
+                console.log(`waygraph check: ${selWarnings.length} inline-selector warning${selWarnings.length === 1 ? "" : "s"}`);
             }
             const orphans = await findOrphanBlocks(proj);
             printOrphanReport(proj, orphans);
-            // Nav warnings only - never fail exit code. Orphans are reported for
+            // Warnings only - never fail exit code. Orphans are reported for
             // human/agent cleanup; chain auto refuses while any remain.
             break;
         }

package/dist/engine.d.ts

@@ -637,7 +637,7 @@ export declare function defineBlock<In extends Checkpoint<string>, Out extends C
  * (same shape `DefinedBlock`/`ComposedBlock` already use), so it drops into
  * `defineFlow([...])`, `connect()`, `composeBlock()` exactly like any other
  * Block - no special-casing needed anywhere that only expects a `Block`.
- * See `openspec/changes/nav-block-and-check/` for why this exists.
+ * See `openspec/specs/nav-block-and-check/spec.md` for why this exists.
  */
 export type NavBlock<Out extends Checkpoint<string>> = DefinedBlock<Checkpoint<string>, Out>;
 /**
@@ -742,6 +742,45 @@ export type ActionBlock<In extends Checkpoint<string>, Out extends Checkpoint<st
 export declare function defineMethodBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>>(base: Parameters<typeof defineBlock<In, Out>>[0]): MethodBlock<In, Out>;
 /** @deprecated Prefer {@link defineMethodBlock} - identical helper (0.7 name). */
 export declare const defineActionBlock: typeof defineMethodBlock;
+export interface AssertBlockOptions<Out extends Checkpoint<string> = Checkpoint<string>> {
+    name: string;
+    description?: string;
+    /** Self-loop target - the Checkpoint this assertion runs on and returns to. */
+    checkpoint: Out["__state"];
+    /**
+     * Shorthand for the wait-then-assert shape found repeatedly in hand-written
+     * assertion Blocks: waits for a heading with this accessible name before
+     * `verify` runs. Omit for a pure "assert whatever is already on the page"
+     * check with no wait. Not a general `act()` override - a Block that needs
+     * more than this stays a plain `defineMethodBlock`.
+     */
+    waitForHeading?: string;
+    verify: Trait[] | ((out: Out) => Trait[]);
+    /** Mem keys this assertion's `verify` reads (e.g. a mem-aware Trait) - checked by preflight before the flow runs. */
+    requires?: readonly MemKey<any>[];
+    stubBefore?: import("./highlights.js").HighlightStubPhaseOrFn<Out>;
+    stubAfter?: import("./highlights.js").HighlightStubPhaseOrFn<Out>;
+    stubOnError?: import("./highlights.js").HighlightStubPhaseOrFn<Out>;
+    /** Multi-step yap slides (demo only) - same field `Instruction.slides` exposes elsewhere. */
+    slides?: import("./highlights.js").WaygraphSlidesOrFn<Out>;
+}
+/**
+ * Sugar for a self-loop-only "pure assertion" Block: no hand-written
+ * `act`/`resolve`, just a name, a `checkpoint` tag, and a `verify` array.
+ * `resolve` is generated from the one `checkpoint` field given, closing the
+ * copy/rename footgun where a hand-restated checkpoint string can silently
+ * drift wrong across a copy/pasted file. Mirrors `definePageBlock`'s own
+ * construction pattern (flat options in, `defineBlock` built internally).
+ * See openspec/changes/waygraph-agent-skill-hardening/spec.md.
+ * @example
+ * defineAssertBlock({
+ *   name: "assert-raw-materials-table",
+ *   checkpoint: "RawMaterials",
+ *   waitForHeading: "Raw Materials & Lead Times",
+ *   verify: [Trait.visible(RawMaterialsSel.reorderBadge)],
+ * });
+ */
+export declare function defineAssertBlock<Out extends Checkpoint<string> = Checkpoint<string>>(options: AssertBlockOptions<Out>): MethodBlock<Out, Out>;
 /** One Block (or lazy factory) registered on a {@link PageBlock}. */
 export type PageMethodEntry = DefinedBlock<any, any> | (() => DefinedBlock<any, any>);
 export type PageBlockOptions<Out extends Checkpoint<string>> = {