waygraph 0.15.11 → 0.15.14

package/README.md

@@ -718,16 +718,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

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>;
     /**