waygraph 0.13.7 → 0.15.0

package/dist/cli.js

@@ -18,7 +18,10 @@ import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
 import { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";
+import { checkMap } from "./map-check.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 +235,7 @@ import {
   completeSequentialTodoDock,
   applyDevicePhase,
   resolveDeviceState,
+  WAYGRAPH_RING_CSS,
 } from "waygraph";
 
 function walkDir(dir, pattern) {
@@ -416,45 +420,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 +6312,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 +6331,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 +6439,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 +6453,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 +6549,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 +6873,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)
@@ -6908,6 +6972,12 @@ Primary (less is more):
 
 Also:
   waygraph list | nav | validate | check | graph | init <name>
+  waygraph map   [project]                 Waygraph Map convention enforcement: every static
+                                           Nav/Page url must verbatim-match its src/map/ folder
+                                           path ((group) segments excluded) - exits 1 on a
+                                           violation, unlike check's warnings-only stance. A
+                                           no-op (exit 0, informational) if the project has no
+                                           src/map/ directory at all.
   waygraph traverse [project]              Graph crawl (Phase B-E)
                  --blocks <glob|/re/|sub>  Phase C: filter *.block.ts discovery
                  --parallel N              Phase D: N clone workers (max 4)
@@ -7311,6 +7381,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 +7642,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 +7709,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,23 +7781,59 @@ 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;
         }
+        case "map": {
+            const proj = resolve(args[1] ?? process.cwd());
+            const result = await checkMap(proj);
+            if (!result.hasMapDir) {
+                console.log(`waygraph map: no src/map/ directory under ${proj} - nothing to check ` +
+                    "(this project isn't on the Waygraph Map convention, or hasn't been migrated yet)");
+                break;
+            }
+            console.log(`waygraph map: ${result.nodes.length} node(s) found under ${relative(proj, result.mapRoot)}`);
+            if (result.violations.length === 0) {
+                console.log("waygraph map: 0 violations - every static Nav/Page url verbatim-matches its folder path");
+            }
+            else {
+                for (const v of result.violations) {
+                    console.error(`waygraph map: ${v.file} (${v.block}) - ${v.reason}`);
+                }
+                console.error(`waygraph map: ${result.violations.length} violation${result.violations.length === 1 ? "" : "s"}`);
+                // Unlike `check`'s warnings-only stance, a Map violation is exactly
+                // the class of bug this command exists to catch (a fabricated
+                // folder grouping that never matched the real site, e.g. the real
+                // (auth)/signin/ mistake this command's own header comment cites) -
+                // fail loud, not just warn.
+                process.exitCode = 1;
+            }
+            break;
+        }
         default:
             console.error(`waygraph: unknown command "${command}"`);
             process.exit(1);