waygraph 0.15.11 → 0.15.15

package/README.md

@@ -296,6 +296,13 @@ nothing is blocked, nothing fails to build. `waygraph check [project]` is the
 complementary whole-project sweep for contexts with no editor watching (CI, generated
 code, an autonomous agent authoring Blocks) - it warns, never fails the process.
 
+**`waygraph typecheck [project]`** runs `tsc --noEmit` then the same **bad-practice** scan
+(wildcard `Checkpoint<string>`, assert blocks missing type args, multi-`.fill()` Methods,
+fill+click in one Method). Practices warn only unless `tsc` fails; use `--no-practices` to
+skip the scan. Opt out per file: `// waygraph-ignore-practices` or
+`// waygraph-ignore: multi-input, combined-action`. Print full agent guidance:
+`waygraph --skill-convention`.
+
 ### Demo narration
 
 Automation rings are gray; authored stubs/slides can use
@@ -662,27 +669,52 @@ space is constrained to this project's own pre-verified Blocks (each with a real
 already checked) instead of freeform DOM/pixel guessing - narrower, but far more accurate and
 deterministic.
 
+### auto vs browser vs pilot
+
+| Layer | Command | What it is |
+|-------|---------|------------|
+| **auto** | `waygraph auto` | Interactive explore (picker / `--cli` menu). **Not** a persistent agent browser. |
+| **browser** | `waygraph browser start` | New persistent Playwright session — **headful by default**, **about:blank by default**. |
+| **pilot** | `waygraph pilot start` | Bootstrap only: `browser start` + whole-project `graph` + starting `snapshot` in one JSON payload. Does not plan or act. |
+
+Session control (`send`, `status`, `highlight`, `dom`, …) works on **`auto`**, **`browser`**, and
+**`pilot`** — same socket, same session id. Prefer the `browser`/`pilot` prefix when driving a
+detached session; `auto` remains for the interactive picker and legacy `--cli --detach`.
+
+**Session lifecycle is explicit** — list what's live before opening another:
+
 ```bash
-waygraph pilot start --non-headless
+waygraph browser                         # show browser subcommands
+waygraph browser sessions [--json]       # list live sessions; --json for agents
+waygraph browser start                   # always opens a new session
+waygraph browser stop <sessionId>        # shut one down
+waygraph browser stop --all              # shut every session for this project
+waygraph browser attach <sessionId>        # terminal picker on an existing session
+waygraph pilot attach <sessionId>          # graph + snapshot, no new browser
+```
+
+```bash
+waygraph pilot start
 # {"sessionId":"bb65d74c","socketPath":"...","headless":false,"graph":{...},"snapshot":{...}}
 ```
 
-One call gives an agent everything it needs to start: a real, already-running Playwright
-session (the exact mechanism `auto --cli --detach` already provides), and the whole project's
-Block graph (`graph` - every Checkpoint/edge/description, not just what's reachable from the
-current position, so the agent can plan several steps ahead). From there, the agent drives the
-session itself, one pick at a time, using the session-control commands that already existed
-before Pilot did:
+`pilot start` is one round trip for agents that need the whole graph immediately. For browser-only
+work (no graph payload), use `browser start`. `auto --cli --detach` still works but is the older
+explore entry point — prefer `browser start` for agent-driven sessions.
+
+From a live session, drive one pick at a time:
 
 ```bash
-waygraph auto status <sessionId>              # read the current menu (no side effects)
-waygraph auto send <sessionId> "<pick>"       # run one pick, get the resulting menu back
-waygraph auto dom <sessionId>                 # inspect the live DOM/ARIA tree
-waygraph auto trace <sessionId>               # read the Checkpoint/Block history so far
-waygraph auto reach <sessionId> <Checkpoint>  # run a whole multi-step route in one call
-waygraph auto resync <sessionId>              # force here to re-detect from the real page
+waygraph browser status <sessionId>              # read the current menu (no side effects)
+waygraph browser send <sessionId> "<pick>"       # run one pick, get the resulting menu back
+waygraph browser dom <sessionId>                 # inspect the live DOM/ARIA tree
+waygraph browser trace <sessionId>               # read the Checkpoint/Block history so far
+waygraph browser reach <sessionId> <Checkpoint>  # run a whole multi-step route in one call
+waygraph browser resync <sessionId>              # force here to re-detect from the real page
 ```
 
+(`auto …` and `pilot …` accept the same subcommands with the same `<sessionId>`.)
+
 Worked example (run for real against `examples/saucedemo`, no new execution code involved): an
 agent gets a plain request - "log me in and buy the backpack" - reads the graph and the starting
 `status`, reasons out login -> add-to-cart -> cart -> checkout info -> submit -> finish as the
@@ -718,16 +750,18 @@ outright rather than left as a caveat.
 
 **On-page indicator.** A headful (`--non-headless`) session looks like an ordinary browser
 tab otherwise - no sign anything is driving it, which matters once a human might be watching
-or co-driving the same visible session. Every session now injects a small badge (bottom-right
+or co-driving the same visible session. Every session injects a small badge (bottom-right
 corner: `Waygraph Pilot - session <id> - <Checkpoint>`) that click-expands into a panel
 listing the current live menu's real edges (block name, kind, target Checkpoint,
-description) - the same data `auto status` returns, rendered in the page itself. Both refresh
-automatically after every `send`/`reach`/`reload`/`resync`/raw action - there's nothing
-separate to call to keep it in sync. Particularly useful for Blind Pilot: watching the panel
-update as newly-authored Blocks get picked up via `reload` shows the map actually growing,
-live, not just a JSON diff in a terminal. Self-contained (`src/pilot-overlay.ts`), not built
-on `waygraph demo`'s own panel/banner system, for the same `cli.ts`-side-effect reason
-`pilot-v1`'s old narrate-mode ring wasn't either.
+description) - the same data `auto status` returns, rendered in the page itself. The overlay
+shell is installed via `context.addInitScript`, so it **persists on `about:blank`** and
+survives `goto` navigations (browser start defaults to blank; pilot navigates when a base URL
+exists). Headful sessions paint the badge immediately on start — no need to call `status`
+first. Bottom-left activity toasts label raw primitives as **`Running (no Block): …`**
+(click/type/goto/upload outside the Block library); Block runs stay **`Running (Block): …`**.
+Both refresh automatically after every `send`/`reach`/`reload`/`resync`/raw action.
+Self-contained (`src/pilot-overlay.ts`), not built on `waygraph demo`'s own panel/banner
+system.
 
 **Pilot itself does no planning, resolving, narrating, or acting** - `pilotStart`'s only job is
 starting the session and handing back its graph in one round trip; see `src/pilot.ts`. An
@@ -1021,17 +1055,24 @@ Flows are files (0.10.5+):
 | Ad-hoc Blocks | `waygraph run --blocks "login then nav-cart" --data '{...}'` |
 | Headed execute | `waygraph run --blocks shopFlow --non-headless --video` |
 | Explore | `waygraph auto` / `waygraph auto --cli` |
+| Browser command reference | `waygraph browser` |
+| List live browser sessions | `waygraph browser sessions [--json]` |
+| Open a new persistent browser | `waygraph browser start` (headful, about:blank by default) |
+| Stop a browser session | `waygraph browser stop <sessionId>` / `stop --all` |
+| Pilot bootstrap (browser + graph + snapshot) | `waygraph pilot start` |
+| Attach to existing session (graph only) | `waygraph pilot attach <sessionId>` |
 | Path-find | `waygraph auto --blocks LoginPage OrderComplete` |
-| Run `--cli` as a background session | `waygraph auto --cli --detach` -> `{sessionId, socketPath}` |
-| Drive a detached session (no TTY) | `waygraph auto send <sessionId> "<pick>"` -> JSON state |
-| Read a detached session's state | `waygraph auto status <sessionId>` (no side effects) |
-| Reattach a terminal to a detached session | `waygraph auto attach <sessionId>` |
+| Run `--cli` as a background session (legacy) | `waygraph auto --cli --detach` -> `{sessionId, socketPath}` |
+| Drive a detached session (no TTY) | `waygraph browser send <sessionId> "<pick>"` -> JSON state |
+| Read a detached session's state | `waygraph browser status <sessionId>` (no side effects) |
+| Reattach a terminal to a detached session | `waygraph browser attach <sessionId>` |
 | Read the live page (aria, small/default) | `waygraph auto dom <sessionId>` |
 | Read the live page (raw DOM, bounded) | `waygraph auto dom <sessionId> --mode full` |
 | Scope either to one element | `waygraph auto dom <sessionId> --selector ".inventory_list"` |
 | Detached session with a real visible browser | `waygraph auto --cli --detach --non-headless` |
 | Read the session's Checkpoint/Block history | `waygraph auto trace <sessionId>` |
 | Whole-project nav-escape + inline-selector + orphan sweep | `waygraph check [project]` |
+| `tsc --noEmit` + bad-practice warnings | `waygraph typecheck [project]` (`--no-practices` to skip scan) |
 | Waygraph Map enforcement (verbatim url-vs-folder, exits 1 on a violation) | `waygraph map [project]` |
 | Graph crawl | `waygraph traverse [project] --parallel N --min-edge-coverage 80%` |
 | Coding-agent defs | `waygraph agent-dive --loop claude` |
@@ -1165,7 +1206,7 @@ it out from under you.
 git clone git@github.com:deviate-dv8/waygraph.git
 cd waygraph
 npm install
-npm run typecheck   # tsc --noEmit
+npm run typecheck   # waygraph typecheck . (tsc --noEmit + practice warnings)
 npm run test        # playwright test
 npm run build       # tsc -p tsconfig.build.json, emits dist/
 ```

package/dist/auto-explore.d.ts

@@ -1,6 +1,11 @@
 import type { Page } from "@playwright/test";
 import type { Block, Checkpoint, WaygraphInstanceOption } from "./types.js";
 import { type WaygraphGraph, type WaygraphEdge } from "./graph.js";
+export interface ExploreContextOpts {
+    blocksSelect?: import("./blocks-select.js").BlocksSelect;
+    /** Absolute paths of extra Block trees to merge (host projectDir is always first). */
+    inject?: string[];
+}
 export interface BlockEntry {
     block: Block<Checkpoint<string>, Checkpoint<string>>;
     exportName: string;
@@ -32,9 +37,7 @@ export interface ExploreMenu {
 /**
  * Import every `*.block.ts` export keyed by runtime Block `.name`.
  */
-export declare function loadBlockLibrary(projectDir: string, opts?: {
-    blocksSelect?: import("./blocks-select.js").BlocksSelect;
-}): Promise<{
+export declare function loadBlockLibrary(projectDir: string, opts?: ExploreContextOpts): Promise<{
     byName: Map<string, BlockEntry>;
     navBlocks: BlockEntry[];
 }>;
@@ -48,9 +51,7 @@ export declare function exploreChoices(graph: WaygraphGraph, here: string | null
 export declare function buildExploreMenu(page: Page, graph: WaygraphGraph, library: {
     byName: Map<string, BlockEntry>;
 }, here: string | null): Promise<ExploreMenu>;
-export declare function buildExploreContext(projectDir: string, opts?: {
-    blocksSelect?: import("./blocks-select.js").BlocksSelect;
-}): Promise<{
+export declare function buildExploreContext(projectDir: string, opts?: ExploreContextOpts): Promise<{
     graph: WaygraphGraph;
     library: Awaited<ReturnType<typeof loadBlockLibrary>>;
 }>;

package/dist/auto-explore.js

@@ -1,6 +1,7 @@
 import { readdirSync, statSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
 import { discoverGraph } from "./graph.js";
+import { exploreRoots, injectTaggedFile } from "./block-inject.js";
 function walkDir(dir, pattern) {
     const results = [];
     let entries;
@@ -105,42 +106,52 @@ export async function loadBlockLibrary(projectDir, opts) {
     const { matchBlocksSelect } = await import("./blocks-select.js");
     const byName = new Map();
     const navBlocks = [];
+    const navSeen = new Set();
     const select = opts?.blocksSelect;
-    for (const file of walkDir(projectDir, /\.block\.ts$/)) {
-        const relFile = relative(projectDir, file).replace(/\\/g, "/");
-        // Glob/bare: path filter before import. Regex: need block name — filter after.
-        if (select && select.kind !== "regex" && !matchBlocksSelect(select, { relFile })) {
-            continue;
-        }
-        let mod;
-        try {
-            mod = await importModule(file);
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            if (/second time|playwright/i.test(msg)) {
-                console.error(`waygraph auto: skip ${relFile}: ${msg.split("\n")[0]}`);
-            }
-            continue;
-        }
-        for (const [exportName, exported] of Object.entries(mod)) {
-            if (!isBlockLike(exported))
+    for (const root of exploreRoots(projectDir, opts?.inject)) {
+        for (const file of walkDir(root, /\.block\.ts$/)) {
+            const relFile = relative(root, file).replace(/\\/g, "/");
+            const taggedFile = injectTaggedFile(projectDir, root, relFile);
+            // Glob/bare: path filter before import. Regex: need block name — filter after.
+            if (select && select.kind !== "regex" && !matchBlocksSelect(select, { relFile })) {
                 continue;
-            if (select &&
-                !matchBlocksSelect(select, { relFile, blockName: exported.name })) {
+            }
+            let mod;
+            try {
+                mod = await importModule(file);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                if (/second time|playwright/i.test(msg)) {
+                    console.error(`waygraph auto: skip ${relFile}: ${msg.split("\n")[0]}`);
+                }
                 continue;
             }
-            const kind = isNavBlockMarked(exported) ? "nav" : "action";
-            const entry = {
-                block: exported,
-                exportName,
-                file: relFile,
-                kind,
-                description: typeof exported.description === "string" ? exported.description : "",
-            };
-            byName.set(exported.name, entry);
-            if (kind === "nav")
-                navBlocks.push(entry);
+            for (const [exportName, exported] of Object.entries(mod)) {
+                if (!isBlockLike(exported))
+                    continue;
+                if (select &&
+                    !matchBlocksSelect(select, { relFile, blockName: exported.name })) {
+                    continue;
+                }
+                const kind = isNavBlockMarked(exported) ? "nav" : "action";
+                const entry = {
+                    block: exported,
+                    exportName,
+                    file: taggedFile,
+                    kind,
+                    description: typeof exported.description === "string" ? exported.description : "",
+                };
+                if (byName.has(exported.name)) {
+                    console.error(`waygraph: inject skipped duplicate Block name "${exported.name}" (${taggedFile})`);
+                    continue;
+                }
+                byName.set(exported.name, entry);
+                if (kind === "nav" && !navSeen.has(exported.name)) {
+                    navSeen.add(exported.name);
+                    navBlocks.push(entry);
+                }
+            }
         }
     }
     navBlocks.sort((a, b) => {

package/dist/auto-session-ipc.d.ts

@@ -54,6 +54,13 @@ export type HighlightResponse = {
     ok: false;
     error: string;
 };
+export declare function readSessionMeta(projectDir: string, sessionId: string): SessionMeta | null;
+/**
+ * Resolve session metadata from a project hint (cwd) or the global registry.
+ * Fixes "session unreachable" when the agent calls status/send from a different
+ * directory or pane than the one that ran `pilot start`.
+ */
+export declare function resolveSessionMeta(sessionId: string, projectDirHint?: string): SessionMeta | null;
 /**
  * Client-side: sends one request to a running session and returns its
  * response. Reports a stale/unreachable session as an error within
@@ -129,6 +136,12 @@ export declare function runAutoServeCommand(init: AutoSessionInit, sessionId: st
  * than re-implementing that resolution here.
  */
 export declare function spawnDetachedSession(init: AutoSessionInit, readyTimeoutMs?: number): Promise<SessionMeta>;
+/** Stop one detached session (SIGTERM + cleanup metadata/socket). */
+export declare function stopBrowserSession(projectDir: string, sessionId: string): boolean;
+/** Stop every live session registered for a project. */
+export declare function stopAllBrowserSessions(projectDir: string): number;
+/** Live browser sessions for a project (metadata + socket + pid still present). */
+export declare function listBrowserSessions(projectDir: string): SessionMeta[];
 /**
  * Client-only interactive loop against a running detached session - reopens
  * the same rendering/parsing the foreground `--cli` loop uses, driven purely

package/dist/auto-session-ipc.js

@@ -6,7 +6,8 @@
  */
 import { createServer, connect } from "node:net";
 import { spawn } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync, openSync, } from "node:fs";
+import { createRequire } from "node:module";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, rmSync, openSync, } from "node:fs";
 import { join, dirname } from "node:path";
 import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
@@ -20,6 +21,19 @@ function sessionDir(projectDir) {
 function metaPath(projectDir, sessionId) {
     return join(sessionDir(projectDir), `${sessionId}.json`);
 }
+/** Global index so session control works even when cwd ≠ the project that spawned the session. */
+function globalMetaPath(sessionId) {
+    return join(socketDir(), `${sessionId}.meta.json`);
+}
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Deliberately NOT under the project directory (unlike meta/log files) -
  * a real bug found while proving out openspec/changes/waygraph-map's own
@@ -44,7 +58,7 @@ function logPathFor(projectDir, sessionId) {
 function generateSessionId() {
     return randomBytes(4).toString("hex");
 }
-function readSessionMeta(projectDir, sessionId) {
+export function readSessionMeta(projectDir, sessionId) {
     const p = metaPath(projectDir, sessionId);
     if (!existsSync(p))
         return null;
@@ -55,9 +69,36 @@ function readSessionMeta(projectDir, sessionId) {
         return null;
     }
 }
+/**
+ * Resolve session metadata from a project hint (cwd) or the global registry.
+ * Fixes "session unreachable" when the agent calls status/send from a different
+ * directory or pane than the one that ran `pilot start`.
+ */
+export function resolveSessionMeta(sessionId, projectDirHint) {
+    if (projectDirHint) {
+        const local = readSessionMeta(projectDirHint, sessionId);
+        if (local)
+            return local;
+    }
+    const globalPath = globalMetaPath(sessionId);
+    if (existsSync(globalPath)) {
+        try {
+            return JSON.parse(readFileSync(globalPath, "utf-8"));
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+function writeGlobalSessionMeta(meta) {
+    mkdirSync(socketDir(), { recursive: true });
+    writeFileSync(globalMetaPath(meta.sessionId), JSON.stringify(meta, null, 2));
+}
 function removeSessionFiles(projectDir, sessionId) {
     for (const p of [
         metaPath(projectDir, sessionId),
+        globalMetaPath(sessionId),
         socketPathFor(sessionId),
     ]) {
         try {
@@ -110,9 +151,20 @@ function readOneMessage(sock, timeoutMs) {
     });
 }
 export async function requestSession(projectDir, sessionId, request, timeoutMs = 15_000) {
-    const meta = readSessionMeta(projectDir, sessionId);
+    const meta = resolveSessionMeta(sessionId, projectDir);
     if (!meta) {
-        return { ok: false, error: `no such session "${sessionId}" (no metadata under .waygraph-auto/)` };
+        return {
+            ok: false,
+            error: `no such session "${sessionId}" (no metadata under ${projectDir}/.waygraph-auto/ or global registry) — ` +
+                "run from the project that started the session, or `waygraph pilot sessions` to list live ids",
+        };
+    }
+    if (!isPidAlive(meta.pid)) {
+        removeSessionFiles(meta.projectDir, sessionId);
+        return {
+            ok: false,
+            error: `session "${sessionId}" is not running (pid ${meta.pid} exited) — start a new session with pilot/browser start`,
+        };
     }
     return new Promise((resolvePromise) => {
         const sock = connect(meta.socketPath);
@@ -283,6 +335,7 @@ export async function serveSession(session, projectDir, sessionId, headless = tr
         headless,
     };
     writeFileSync(metaPath(projectDir, sessionId), JSON.stringify(meta, null, 2));
+    writeGlobalSessionMeta(meta);
     process.on("SIGTERM", () => void shutdown());
     process.on("SIGINT", () => void shutdown());
 }
@@ -305,17 +358,31 @@ export async function runAutoServeCommand(init, sessionId) {
 export async function spawnDetachedSession(init, readyTimeoutMs = 20_000) {
     const sessionId = generateSessionId();
     mkdirSync(sessionDir(init.projectDir), { recursive: true });
-    const launcher = join(dirname(fileURLToPath(import.meta.url)), "..", "bin", "waygraph");
+    const pkgRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+    const require = createRequire(join(pkgRoot, "package.json"));
+    const tsxEsm = require.resolve("tsx/esm");
+    const cli = join(pkgRoot, "dist", "cli.js");
     const logFd = openSync(logPathFor(init.projectDir, sessionId), "a");
-    const args = ["__auto-serve", init.projectDir, "--session-id", sessionId];
+    const args = ["--import", tsxEsm, cli, "__auto-serve", init.projectDir, "--session-id", sessionId];
     if (init.baseURL)
         args.push("--base-url", init.baseURL);
+    if (init.startUrl)
+        args.push("--goto", init.startUrl);
+    if (init.skipInitialNavigation)
+        args.push("--blank");
     if (init.headless === false)
         args.push("--non-headless");
-    const child = spawn(process.execPath, [launcher, ...args], {
+    if (init.headless === true)
+        args.push("--headless");
+    for (const p of init.inject ?? []) {
+        args.push("--inject", p);
+    }
+    // Spawn cli.js directly — not bin/waygraph (which would fork a second Node).
+    const child = spawn(process.execPath, args, {
         detached: true,
         stdio: ["ignore", logFd, logFd],
         windowsHide: true,
+        env: process.env,
     });
     child.unref();
     const deadline = Date.now() + readyTimeoutMs;
@@ -328,6 +395,51 @@ export async function spawnDetachedSession(init, readyTimeoutMs = 20_000) {
     throw new Error(`session "${sessionId}" did not become ready within ${readyTimeoutMs}ms - ` +
         `check ${logPathFor(init.projectDir, sessionId)} for errors`);
 }
+/** Stop one detached session (SIGTERM + cleanup metadata/socket). */
+export function stopBrowserSession(projectDir, sessionId) {
+    const meta = resolveSessionMeta(sessionId, projectDir);
+    if (!meta)
+        return false;
+    try {
+        process.kill(meta.pid, "SIGTERM");
+    }
+    catch {
+        /* already gone */
+    }
+    removeSessionFiles(meta.projectDir, sessionId);
+    return true;
+}
+/** Stop every live session registered for a project. */
+export function stopAllBrowserSessions(projectDir) {
+    const sessions = listBrowserSessions(projectDir);
+    for (const meta of sessions) {
+        stopBrowserSession(meta.projectDir, meta.sessionId);
+    }
+    return sessions.length;
+}
+/** Live browser sessions for a project (metadata + socket + pid still present). */
+export function listBrowserSessions(projectDir) {
+    const dir = sessionDir(projectDir);
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const f of readdirSync(dir)) {
+        if (!f.endsWith(".json"))
+            continue;
+        const id = f.slice(0, -".json".length);
+        const meta = readSessionMeta(projectDir, id);
+        if (!meta)
+            continue;
+        if (!existsSync(socketPathFor(id)))
+            continue;
+        if (!isPidAlive(meta.pid)) {
+            removeSessionFiles(projectDir, id);
+            continue;
+        }
+        out.push(meta);
+    }
+    return out.sort((a, b) => a.startedAt.localeCompare(b.startedAt));
+}
 function printSnapshotMenu(snapshot) {
     console.log("");
     console.log(`You are here: ${snapshot.here ?? "Unknown (pick Start here)"}`);

package/dist/auto-session.d.ts

@@ -58,6 +58,10 @@ export interface AutoSessionInit {
     baseURL?: string;
     startUrl?: string;
     blocksSelect?: import("./blocks-select.js").BlocksSelect;
+    /** Absolute paths — merged Block libraries (see `waygraph browser --inject`). */
+    inject?: string[];
+    /** When true, open about:blank instead of baseURL/startUrl (browser default). */
+    skipInitialNavigation?: boolean;
     /** Default true. false launches a real visible browser window. */
     headless?: boolean;
     /**
@@ -175,6 +179,7 @@ export interface StorageSnapshot {
  */
 export declare class AutoSession {
     private readonly projectDir;
+    private readonly inject;
     private readonly blocksSelect;
     private graph;
     private library;
@@ -189,6 +194,9 @@ export declare class AutoSession {
     private lastRunNote;
     private readonly trace;
     private readonly consoleLog;
+    private readonly knownInteractionSelectors;
+    private readonly headless;
+    private lastOverlayInfo;
     private constructor();
     static start(init: AutoSessionInit): Promise<AutoSession>;
     /** Pure getter - returns a copy, not the live array. */
@@ -198,21 +206,16 @@ export declare class AutoSession {
     getConsoleLog(): ConsoleLogEntry[];
     private pushConsoleLog;
     private currentMenu;
+    /** Paint the overlay on about:blank / immediately after session start (headful browser). */
+    private bootstrapOverlay;
+    /** Re-apply cached overlay state after navigation (init script restores shell only). */
+    private repaintOverlayAfterNavigation;
     /**
-     * Real, direct user request: a Blind Pilot agent had no way to ask "which
-     * of the links visible on THIS page are already covered by a NavBlock" -
-     * only manual DOM inspection + guessing hrefs, exactly what this session
-     * had been doing by hand the whole time this feature was built. Compares
-     * every same-origin `<a href>` on the page against every NavBlock's own
-     * static url (`__waygraphNavUrl` - see `defineNavBlock`'s own comment for
-     * why only plain-string urls qualify), and `console.warn()`s each pathname
-     * with no NavBlock at all - surfaced through the same real console capture
-     * `auto console` already reads, not a separate channel. Deduped per path
-     * per page load (a `Set` living on `window`, so it survives repeated
-     * `currentMenu()` calls but resets on a real navigation) - once is enough
-     * to flag a gap, repeating it on every status/send call would just be noise.
+     * Flags same-origin `<a href>` paths and visible buttons with no NavBlock
+     * URL / Block selector in the loaded library — read via `auto console`.
+     * Deduped per page load so repeated status/send calls stay quiet.
      */
-    private warnUnmappedLinks;
+    private warnUnmappedInteractions;
     /** Pure getter - no Block runs, no mem/page mutation. */
     currentSnapshot(): Promise<SessionSnapshot>;
     /**