@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/clients/web/server.js

@@ -1,7 +1,7 @@
-// server.ts — the unified `crtr web serve` host: the crouter web UI server.
+// server.ts — the unified surface web server: the crouter web UI server.
 //
-// ONE long-running server process on 127.0.0.1 that serves THREE concerns on one
-// origin (the §2 unified server):
+// ONE long-running server process on the bound host that serves THREE concerns
+// on one origin (the §2 unified server):
 //   • GET  /*               → the shell SPA (static dist/web-client/, or Vite
 //                             middleware in --dev) + SPA fallback.
 //   • POST /__crtr/source   → the source + command bridge: decode a SourceRequest
@@ -13,7 +13,7 @@
 //   • WS   /node/<id>       → open that node's ALREADY-running broker `view.sock`
 //                             and relay frames VERBATIM both directions. The relay
 //                             adds NOTHING — the browser is the SAME protocol peer
-//                             as `crtr attach`.
+//                             as `crtr surface attach`.
 //
 // §0 ONE-WRITER INVARIANT: the WS relay is ONLY a socket relay. It NEVER calls
 // reviveNode, NEVER spawns `pi --session`, NEVER touches SessionManager, and
@@ -21,23 +21,34 @@
 // ALREADY-running broker's `view.sock`; if the broker is not running the WS is
 // closed with a clear reason. The relay NEVER launches an engine. ALL writes go
 // through the bridge running `crtr` SUBPROCESSES — this process is never the
-// sanctioned writer; the CLI it shells out to is.
+// sanctioned writer; the CLI it shells out to is. The sanctioned exception is a
+// relay fault record written directly to the node when the broker socket fails.
 //
 // One `view.sock` connection per browser-WS (N browsers of one node = N broker
 // clients) — the broker fans out natively, so there is no bridge-side fan-out.
 import { createServer as createHttpServer } from 'node:http';
-import { createConnection } from 'node:net';
+import { createConnection, isIP } from 'node:net';
 import { createReadStream, existsSync, statSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, extname, join, normalize, resolve } from 'node:path';
 import { WebSocketServer } from 'ws';
-import { nodeDir } from '../../core/canvas/paths.js';
+import { viewSocketPath } from '../../core/canvas/paths.js';
 import { getNode } from '../../core/canvas/index.js';
 import { BROKER_READ_CAPS, CLIENT_READ_CAPS, FrameDecoder, FrameOverflowError, } from '../../core/runtime/broker-protocol.js';
+import { classify } from '../../core/fault-classifier.js';
+import { clearFault, recordFault } from '../../core/runtime/fault.js';
 import { createLocalTransport } from '../../core/view/transport-local.js';
+import { createBurstCoalescingTransport } from '../../core/view/transport-cache.js';
 import { runSourceRequest } from '../../core/view/bridge.js';
 import { startEventHub } from './events.js';
 import { createDevServer } from './dev-server.js';
+import { SOURCE_CACHE_TTL_MS, isCoalescableSourceRequest } from './source-cache.js';
+// ── Hearth product seam: model-auth lane (P3.3b, Silas-approved exception) ──
+// This is the ONLY Hearth-aware import in this file. All OAuth/status/start/
+// finish product logic lives in core/hearth/model-auth-guest.ts; this module
+// provides only routing + relay-token enforcement for the lane (see the route
+// block in startWebServer below).
+import { handleHearthModelAuthRequest } from '../../core/hearth/model-auth-guest.js';
 const HERE = dirname(fileURLToPath(import.meta.url));
 /** Candidate dirs to serve the shell SPA bundle from, in priority order: an
  *  explicit override, the compiled-module-relative `dist/web-client/` (what
@@ -94,11 +105,46 @@ function nodeIdFromPath(pathname) {
         return null; // malformed percent-encoding — treat as no match
     }
 }
-/** A node id is used to build `nodeDir(id)/view.sock`, so it MUST NOT contain a
- *  path separator or `..` (e.g. a decoded `..%2f..` would escape `nodes/`). */
+/** A node id is used to build the broker socket path via `viewSocketPath(id)`, so
+ *  it MUST NOT contain a path separator or `..` (e.g. a decoded `..%2f..`). */
 function isSafeNodeId(id) {
     return id !== '' && !/[/\\]/.test(id) && !id.includes('..');
 }
+function isLoopbackHost(host) {
+    const lower = host.toLowerCase();
+    const ipVersion = isIP(host);
+    if (lower === 'localhost' || lower === '::1')
+        return true;
+    if (ipVersion === 4 && host.startsWith('127.'))
+        return true;
+    if (lower === '::ffff:127.0.0.1')
+        return true;
+    if (ipVersion === 6 && lower.startsWith('::ffff:127.'))
+        return true;
+    return false;
+}
+function hostForUrl(host) {
+    return host.includes(':') ? `[${host}]` : host;
+}
+function requestTokens(req) {
+    const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+    const tokens = [];
+    const queryToken = url.searchParams.get('token');
+    if (queryToken !== null && queryToken !== '')
+        tokens.push(queryToken);
+    const authorization = req.headers.authorization;
+    if (typeof authorization === 'string') {
+        const match = /^Bearer\s+(.+)$/.exec(authorization);
+        if (match !== null && match[1] !== '')
+            tokens.push(match[1]);
+    }
+    return tokens;
+}
+function requestTokenMatches(req, secret) {
+    if (secret === undefined)
+        return false;
+    return requestTokens(req).some((token) => token === secret);
+}
 /** A WS close reason is capped at 123 UTF-8 bytes by the protocol. */
 function clampReason(reason) {
     const buf = Buffer.from(reason, 'utf8');
@@ -149,7 +195,7 @@ function serveStatic(clientDir, req, res) {
     }
     if (!existsSync(filePath)) {
         res.writeHead(503, { 'content-type': 'text/plain; charset=utf-8' });
-        res.end('crtr web shell bundle not found — run `npm run build` to emit it into ' +
+        res.end('crtr surface web shell bundle not found — run `npm run build` to emit it into ' +
             `${clientDir} (or pass --dev for Vite middleware)\n`);
         return;
     }
@@ -192,10 +238,15 @@ function bridgeConnection(ws, nodeId) {
         }
         return;
     }
-    const sockPath = join(nodeDir(nodeId), 'view.sock');
+    clearFault(nodeId, { link: 'browser↔relay' });
+    const sockPath = viewSocketPath(nodeId);
     const socket = createConnection(sockPath);
     const decoder = new FrameDecoder(CLIENT_READ_CAPS);
     let closed = false;
+    let browserFaultRecorded = false;
+    socket.on('connect', () => {
+        clearFault(nodeId, { link: 'relay↔broker' });
+    });
     const teardown = (wsCode, reason) => {
         if (closed)
             return;
@@ -234,12 +285,62 @@ function bridgeConnection(ws, nodeId) {
         }
     });
     socket.on('error', (err) => {
+        const classification = classify('relay↔broker', err);
+        recordFault(nodeId, {
+            link: 'relay↔broker',
+            op: 'bridge socket',
+            kind: classification.kind,
+            retry: { disposition: 'manual' },
+            message: err.message,
+        });
         const reason = err.code === 'ECONNREFUSED' || err.code === 'ENOENT'
             ? `no running broker for ${nodeId}`
             : `view socket error for ${nodeId}: ${err.message}`;
         teardown(1011, reason);
     });
-    socket.on('close', () => teardown(1000, `broker for ${nodeId} closed`));
+    socket.on('close', (hadError) => {
+        if (closed || hadError)
+            return;
+        clearFault(nodeId, { link: 'relay↔broker' });
+        teardown(1000, 'broker socket closed');
+    });
+    ws.on('close', (code, reason) => {
+        const reasonText = reason.toString('utf8');
+        if (closed) {
+            if (code === 1000)
+                clearFault(nodeId, { link: 'browser↔relay' });
+            return;
+        }
+        if (code === 1000) {
+            clearFault(nodeId, { link: 'browser↔relay' });
+        }
+        else if (!browserFaultRecorded) {
+            browserFaultRecorded = true;
+            const classification = classify('browser↔relay', { code, reason: reasonText });
+            recordFault(nodeId, {
+                link: 'browser↔relay',
+                op: 'browser websocket',
+                kind: classification.kind,
+                retry: { disposition: 'manual' },
+                message: reasonText || `browser relay closed (${code})`,
+            });
+        }
+        teardown(code, reasonText || `browser relay closed (${code})`);
+    });
+    ws.on('error', () => {
+        if (!browserFaultRecorded) {
+            browserFaultRecorded = true;
+            const classification = classify('browser↔relay', { code: 1006, reason: 'browser ws error' });
+            recordFault(nodeId, {
+                link: 'browser↔relay',
+                op: 'browser websocket',
+                kind: classification.kind,
+                retry: { disposition: 'manual' },
+                message: 'browser ws error',
+            });
+        }
+        teardown(1011, 'browser ws error');
+    });
     // WS → socket: re-frame each message as one newline-terminated JSON line.
     // VERBATIM (no parse) — the broker validates and bounds its own reads.
     ws.on('message', (data) => {
@@ -259,34 +360,43 @@ function bridgeConnection(ws, nodeId) {
             /* dead socket — its 'close' drives teardown */
         }
     });
-    ws.on('close', () => teardown(1000, 'browser closed'));
-    ws.on('error', () => teardown(1011, 'browser ws error'));
 }
-/** Build + start the unified web server. Binds 127.0.0.1 only (remote access is
- *  out of scope — §9). Resolves once the server is listening. Async because
- *  --dev awaits a Vite middleware server before listening. */
+/** Build + start the unified web server. Binds the requested host/port and
+ *  resolves once the server is listening. Async because --dev awaits a Vite
+ *  middleware server before listening. */
 export async function startWebServer(opts) {
     const host = opts.host ?? '127.0.0.1';
+    const token = opts.token !== undefined && opts.token !== '' ? opts.token : undefined;
     const dev = opts.dev ?? false;
+    const tokenRequired = !isLoopbackHost(host);
+    if (tokenRequired && (token === undefined || token === '')) {
+        throw new Error(`crtr surface web serve --host ${host} requires --token for remote-capable endpoints`);
+    }
     const clientDir = resolveClientDir();
     // The bridge runs view sources + command verbs locally, in the cwd crtr was
     // invoked from (a git-pr view inspects THIS repo; a `crtr node new` lands here).
-    const transport = createLocalTransport({ cwd: process.cwd() });
+    const transport = createBurstCoalescingTransport(createLocalTransport({ cwd: process.cwd() }), {
+        ttlMs: SOURCE_CACHE_TTL_MS,
+        shouldCache: isCoalescableSourceRequest,
+    });
     // The SSE change lane — one hub, fanned to every connected EventSource.
     const eventHub = startEventHub();
-    // Same-origin allowlist (M1): a browser bypasses same-origin policy on both
-    // WebSockets AND cross-origin POSTs, so any web page the user visits could
-    // otherwise open ws://127.0.0.1:PORT/node/<id> and DRIVE their agents, OR POST
-    // /__crtr/source to run ARBITRARY exec. The same gate guards all three write/
-    // drive surfaces (WS upgrade, bridge POST, SSE GET). Populated once we know the
-    // bound port. A request with NO Origin (a CLI/curl/test client, not a browser)
-    // is allowed — the threat model is foreign browser pages, which always send it.
+    // Same-origin allowlist: tokenless localhost pages keep the legacy guard,
+    // while a valid relay token can authorize remote Hearth route origins that would
+    // otherwise be rejected by originAllowed().
     let allowedOrigins = new Set();
     const originAllowed = (origin) => {
         if (origin === undefined || origin === '')
             return true;
         return allowedOrigins.has(origin);
     };
+    const requestAllowed = (req) => {
+        if (requestTokenMatches(req, token))
+            return true;
+        if (tokenRequired)
+            return false;
+        return originAllowed(req.headers.origin);
+    };
     // Assigned before listen() when --dev; the request handler closes over it.
     let vite;
     const httpServer = createHttpServer((req, res) => {
@@ -294,15 +404,16 @@ export async function startWebServer(opts) {
             const url = new URL(req.url ?? '/', 'http://127.0.0.1');
             const pathname = url.pathname;
             // The source + command bridge: POST /__crtr/source → run the SourceRequest
-            // through the local transport. Origin-gated (same M1 gate as the WS relay):
-            // arbitrary exec from a foreign browser page is exactly what M1 prevents.
+            // through the local transport. Token-or-origin gated (same guard as the WS
+            // relay): arbitrary exec from a foreign browser page is exactly what the
+            // remote binding guard prevents.
             if (pathname === '/__crtr/source') {
                 if (req.method !== 'POST') {
                     res.writeHead(405, { 'content-type': 'text/plain; charset=utf-8', allow: 'POST' });
                     res.end('method not allowed\n');
                     return;
                 }
-                if (!originAllowed(req.headers.origin)) {
+                if (!requestAllowed(req)) {
                     res.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' });
                     res.end('forbidden\n');
                     return;
@@ -319,15 +430,16 @@ export async function startWebServer(opts) {
                 });
                 return;
             }
-            // The SSE change-invalidation lane: GET /__crtr/events. Origin-gated too —
-            // a foreign page should not even learn the user's graph is mutating.
+            // The SSE change-invalidation lane: GET /__crtr/events. Token-or-origin
+            // gated too — a foreign page should not even learn the user's graph is
+            // mutating.
             if (pathname === '/__crtr/events') {
                 if (req.method !== 'GET') {
                     res.writeHead(405, { 'content-type': 'text/plain; charset=utf-8', allow: 'GET' });
                     res.end('method not allowed\n');
                     return;
                 }
-                if (!originAllowed(req.headers.origin)) {
+                if (!requestAllowed(req)) {
                     res.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' });
                     res.end('forbidden\n');
                     return;
@@ -335,6 +447,24 @@ export async function startWebServer(opts) {
                 eventHub.addClient(res);
                 return;
             }
+            // ── Hearth product seam: model-auth lane ──
+            // Isolated per the P3.3a/P3.3b approved exception. ALL Hearth/OAuth logic
+            // lives in core/hearth/model-auth-guest.ts; this block is ONLY routing +
+            // the relay-token gate. CRITICAL: this lane uses the STRICT token-only
+            // predicate requestTokenMatches(req, token), never requestAllowed() —
+            // requestAllowed() also accepts a same-origin loopback request with NO
+            // token at all, which would make this lane tokenless on local/dev binds.
+            // Every /__hearth/model-auth/* request fails closed (401) without an
+            // exact relay-token match, even on loopback.
+            if (pathname.startsWith('/__hearth/model-auth/anthropic/')) {
+                if (!requestTokenMatches(req, token)) {
+                    res.writeHead(401, { 'content-type': 'text/plain; charset=utf-8' });
+                    res.end('relay token required\n');
+                    return;
+                }
+                void handleHearthModelAuthRequest(req, res);
+                return;
+            }
             // --dev: Vite middleware owns all remaining asset/HTML serving (incl. its
             // own SPA fallback). It is mounted AFTER the bridge + SSE checks above, so
             // those never fall through to Vite.
@@ -383,7 +513,7 @@ export async function startWebServer(opts) {
                 socket.destroy();
                 return;
             }
-            if (!originAllowed(req.headers.origin)) {
+            if (!requestAllowed(req)) {
                 socket.write('HTTP/1.1 403 Forbidden\r\n\r\n');
                 socket.destroy();
                 return;
@@ -414,13 +544,14 @@ export async function startWebServer(opts) {
             // A server error AFTER listen (e.g. an accept failure) must not be an
             // unhandled 'error' that crashes the process (n9) — log + carry on.
             httpServer.on('error', (err) => {
-                process.stderr.write(`crtr web: server error: ${err.message}\n`);
+                process.stderr.write(`crtr surface web: server error: ${err.message}\n`);
             });
             const addr = httpServer.address();
             const port = typeof addr === 'object' && addr !== null ? addr.port : opts.port;
-            const url = `http://${host}:${port}`;
+            const hostUrl = hostForUrl(host);
+            const url = `http://${hostUrl}:${port}`;
             allowedOrigins = new Set([
-                `http://${host}:${port}`,
+                `http://${hostUrl}:${port}`,
                 `http://127.0.0.1:${port}`,
                 `http://localhost:${port}`,
             ]);

package/dist/clients/web/source-cache.d.ts

@@ -0,0 +1,10 @@
+import type { SourceRequest } from '../../core/view/contract.js';
+/** TTL for coalesced source reads. Must comfortably exceed the SSE debounce
+ *  (events.ts, 150 ms) so a single mutation's fan-out collapses to one
+ *  subprocess per distinct read, while staying short enough that the next
+ *  poll/SSE refreshes promptly. */
+export declare const SOURCE_CACHE_TTL_MS = 500;
+/** True iff `req` is an idempotent `crtr … --json` read safe to burst-coalesce.
+ *  Anything carrying stdin or a cwd override, any non-exec request, and any
+ *  command not on the {@link CACHEABLE_READS} allowlist is rejected. */
+export declare function isCoalescableSourceRequest(req: SourceRequest): boolean;

package/dist/clients/web/source-cache.js

@@ -0,0 +1,57 @@
+// source-cache.ts — which `/__crtr/source` requests the host may burst-coalesce.
+//
+// The web client has no data API: every read is a `crtr … --json` subprocess
+// POSTed to /__crtr/source, and one SSE invalidation fans out to N independent
+// React subscribers that each re-issue their own read. On NFS-backed canvas
+// state each such subprocess is expensive, so an SSE burst spawns a storm of
+// duplicate reads. The host wraps the transport in a burst-coalescing decorator
+// (transport-cache.ts) keyed on JSON.stringify(req); this predicate decides
+// which requests are safe to share/cache within a short TTL.
+//
+// ONLY idempotent, side-effect-free `crtr` reads belong here. Writes
+// (node new / canvas revive / node msg), file reads, http requests, and any
+// request carrying stdin or an overridden cwd are NEVER cacheable — caching
+// those would drop a mutation or serve a stale cross-cwd read. Target-dependent
+// reads (node inspect snapshot/show for a specific id) ARE cacheable because the id
+// is part of the request and therefore part of the coalescing key, so distinct
+// ids never collide.
+/** TTL for coalesced source reads. Must comfortably exceed the SSE debounce
+ *  (events.ts, 150 ms) so a single mutation's fan-out collapses to one
+ *  subprocess per distinct read, while staying short enough that the next
+ *  poll/SSE refreshes promptly. */
+export const SOURCE_CACHE_TTL_MS = 500;
+/** The literal `crtr … --json` read commands the web client re-issues on every
+ *  SSE burst. Each entry is matched positionally against the exec args; an
+ *  `'*'` placeholder matches exactly one arbitrary arg (a target id). */
+const CACHEABLE_READS = [
+    ['canvas', 'snapshot', '--json'],
+    ['human', 'list', '--json'],
+    ['surface', 'view', 'list', '--json'],
+    ['node', 'inspect', 'snapshot', '*', '--json'],
+    ['node', 'inspect', 'show', '*', '--json'],
+];
+function argsMatch(pattern, args) {
+    if (pattern.length !== args.length)
+        return false;
+    for (let i = 0; i < pattern.length; i++) {
+        if (pattern[i] === '*')
+            continue;
+        if (pattern[i] !== args[i])
+            return false;
+    }
+    return true;
+}
+/** True iff `req` is an idempotent `crtr … --json` read safe to burst-coalesce.
+ *  Anything carrying stdin or a cwd override, any non-exec request, and any
+ *  command not on the {@link CACHEABLE_READS} allowlist is rejected. */
+export function isCoalescableSourceRequest(req) {
+    if (req.kind !== 'exec')
+        return false;
+    if (req.bin !== 'crtr')
+        return false;
+    if (req.stdin !== undefined)
+        return false;
+    if (req.cwd !== undefined)
+        return false;
+    return CACHEABLE_READS.some((pattern) => argsMatch(pattern, req.args));
+}

package/dist/clients/web/web-cmd.js

@@ -1,15 +1,15 @@
-// web-cmd.ts — the `crtr web` command leaf + registration.
+// web-cmd.ts — the `crtr surface web` command leaf + registration.
 //
 // Starts the ONE long-running unified web server (server.ts): the crouter web UI
 // host. It serves the shell SPA, the source + command bridge (POST
 // /__crtr/source), the SSE change lane (GET /__crtr/events), and a VERBATIM
-// browser ⇄ broker relay on `ws://127.0.0.1:PORT/node/<id>` (the browser becomes
-// the SAME protocol peer as `crtr attach`). The node is selected by the URL, so
+// browser ⇄ broker relay on `ws://HOST:PORT/node/<id>` (the browser becomes
+// the SAME protocol peer as surface attach). The node is selected by the URL, so
 // there is NO positional node here.
 //
 // Command shape (plan §3.6): the CLI path-walker forbids a flat top-level leaf
 // (`defineRoot.subtrees` is `BranchDef[]`), so `web` is a BRANCH wrapping a
-// single leaf: `crtr web serve`.
+// single leaf: `crtr surface web serve`.
 import { spawn } from 'node:child_process';
 import { defineBranch, defineLeaf } from '../../core/command.js';
 import { startWebServer } from './server.js';
@@ -37,10 +37,10 @@ function openBrowser(url) {
 const webServeLeaf = defineLeaf({
     name: 'serve',
     description: 'start the crouter web UI server — the shell, the source/command bridge, and a browser ⇄ broker relay',
-    whenToUse: 'you want the crouter web UI: a browser shell to watch the canvas and drive headless nodes, instead of a terminal pane. It starts ONE long-running local server (127.0.0.1) that serves the shell SPA, the source + command bridge (POST /__crtr/source — views\' reads AND `crtr` command writes), an SSE change-invalidation lane (GET /__crtr/events), and a VERBATIM browser ⇄ broker relay on /node/<id> (the browser becomes the same protocol peer as `crtr attach`: one controller drives, extra viewers follow read-only). The relay NEVER starts an engine — each node must already have a running headless broker (focus or revive it first); all writes flow through `crtr` subprocesses the bridge runs. Pass --dev for Vite middleware (HMR) while iterating on the shell. The server runs until ctrl+c; the node is picked in the browser via the URL, not on the command line.',
+    whenToUse: 'you want the crouter web UI: a browser shell to watch the canvas and drive headless nodes, instead of a terminal pane. It starts ONE long-running server (default 127.0.0.1) that serves the shell SPA, the source + command bridge (POST /__crtr/source — views\' reads AND `crtr` command writes), an SSE change-invalidation lane (GET /__crtr/events), and a VERBATIM browser ⇄ broker relay on /node/<id> (the browser becomes the same protocol peer as surface attach: one controller drives, extra viewers follow read-only). If you bind a non-loopback host, pass --token so the remote-capable bridge, SSE, and relay endpoints can authorize the page. The relay NEVER starts an engine — each node must already have a running headless broker (focus or revive it first); all writes flow through `crtr` subprocesses the bridge runs. Pass --dev for Vite middleware (HMR) while iterating on the shell. The server runs until ctrl+c; the node is picked in the browser via the URL, not on the command line.',
     help: {
         name: 'web serve',
-        summary: 'start the long-running crouter web UI server on 127.0.0.1: serves the shell SPA, the POST /__crtr/source bridge, the GET /__crtr/events SSE lane, and a VERBATIM browser ⇄ node-broker relay (browser picks the node via /node/<id>)',
+        summary: 'start the long-running crouter web UI server: serves the shell SPA, the POST /__crtr/source bridge, the GET /__crtr/events SSE lane, and a VERBATIM browser ⇄ node-broker relay (browser picks the node via /node/<id>)',
         params: [
             {
                 kind: 'flag',
@@ -50,6 +50,21 @@ const webServeLeaf = defineLeaf({
                 default: DEFAULT_PORT,
                 constraint: `TCP port to bind on 127.0.0.1. Default ${DEFAULT_PORT}.`,
             },
+            {
+                kind: 'flag',
+                name: 'host',
+                type: 'string',
+                required: false,
+                default: '127.0.0.1',
+                constraint: 'TCP host to bind. Default 127.0.0.1. Non-loopback binds require --token.',
+            },
+            {
+                kind: 'flag',
+                name: 'token',
+                type: 'string',
+                required: false,
+                constraint: 'Bearer token for remote-capable bridge, SSE, and broker relay requests. Required for non-loopback binds.',
+            },
             {
                 kind: 'flag',
                 name: 'open',
@@ -70,25 +85,29 @@ const webServeLeaf = defineLeaf({
         output: [],
         outputKind: 'object',
         effects: [
-            'Binds a long-running HTTP+WebSocket server on 127.0.0.1:<port> and keeps serving until interrupted (ctrl+c / SIGTERM). Safe to run non-interactively (daemon-like): it prints the URL and serves.',
-            'Serves the shell SPA (static dist/web-client/, or Vite middleware under --dev), runs the POST /__crtr/source bridge (exec/file/http in this cwd), streams the GET /__crtr/events SSE change lane, and on a browser ws://127.0.0.1:<port>/node/<id> connection opens that node\'s running broker view.sock and relays frames VERBATIM both directions.',
+            'Binds a long-running HTTP+WebSocket server on the requested host and port and keeps serving until interrupted (ctrl+c / SIGTERM). Safe to run non-interactively (daemon-like): it prints the URL and serves.',
+            'Serves the shell SPA (static dist/web-client/, or Vite middleware under --dev), runs the POST /__crtr/source bridge (exec/file/http in this cwd), streams the GET /__crtr/events SSE change lane, and on a browser ws://HOST:<port>/node/<id> connection opens that node\'s running broker view.sock and relays frames VERBATIM both directions. Non-loopback binds require a token so the remote Hearth route is not an unauthenticated command surface.',
             'The relay NEVER spawns pi and NEVER writes any session — it only opens a socket to an already-running broker; if the broker is not running, the browser connection is closed with a clear reason. All graph mutations go through `crtr` subprocesses the bridge runs.',
         ],
     },
     run: async (input) => {
         const port = input['port'] ?? DEFAULT_PORT;
+        const host = input['host'] ?? '127.0.0.1';
+        const tokenRaw = input['token'];
+        const token = tokenRaw !== undefined && tokenRaw !== '' ? tokenRaw : undefined;
         const open = input['open'] ?? false;
         const dev = input['dev'] ?? false;
-        const server = await startWebServer({ port, dev });
+        const server = await startWebServer({ port, host, token, dev });
         const nodeUrlShape = `${server.url}/node/<id>`;
-        process.stdout.write(`crtr web serving on ${server.url}${dev ? ' (--dev: Vite middleware)' : ''}\n` +
+        const browserUrl = token !== undefined ? `${server.url}?token=${encodeURIComponent(token)}` : server.url;
+        process.stdout.write(`crtr surface web serving on ${server.url}${dev ? ' (--dev: Vite middleware)' : ''}\n` +
             `  open a node:  ${nodeUrlShape}\n` +
             `  bridge:       POST ${server.url}/__crtr/source\n` +
             `  events (SSE): GET  ${server.url}/__crtr/events\n` +
             `  shell assets: ${dev ? 'Vite middleware (HMR)' : server.clientDir}\n` +
             `  (ctrl+c to stop)\n`);
         if (open)
-            openBrowser(server.url);
+            openBrowser(browserUrl);
         // Long-running: resolve only on a shutdown signal, tearing down cleanly.
         await new Promise((resolveShutdown) => {
             const shutdown = () => {
@@ -108,12 +127,12 @@ export function registerWeb() {
         rootEntry: {
             concept: 'the crouter web UI server — one host serving the browser shell, the source/command bridge, an SSE change lane, and a VERBATIM relay to nodes\' running brokers',
             desc: 'serve the crouter web UI for the canvas and headless nodes',
-            useWhen: 'you want the crouter web UI in a browser instead of a tmux pane: watch the canvas and drive headless nodes. It runs one long-lived local server that serves the shell SPA, runs view sources + `crtr` command writes over POST /__crtr/source, streams canvas-change invalidations over GET /__crtr/events (SSE), and relays a browser connection VERBATIM to a node\'s already-running broker on /node/<id> — same protocol peer as `crtr attach`. The node is selected in the browser via the URL; the relay never starts an engine, so each node must already have a running headless broker.',
+            useWhen: 'you want the crouter web UI in a browser instead of a tmux pane: watch the canvas and drive headless nodes. It runs one long-lived server that serves the shell SPA, runs view sources and crtr command writes over POST /__crtr/source, streams canvas-change invalidations over GET /__crtr/events, and relays a browser connection VERBATIM to a node\'s already-running broker on /node/<id>. The node is selected in the browser via the URL; if the server is bound off-loopback, the page must carry a token so the relay and bridge can authorize.',
         },
         help: {
             name: 'web',
             summary: 'serve the crouter web UI: the shell SPA, the source/command bridge, the SSE change lane, and a VERBATIM relay to headless nodes\' brokers',
-            model: '`serve` starts the ONE long-running unified server on 127.0.0.1 (--port, default 7878; --open to launch the browser; --dev for Vite middleware/HMR). It serves the shell SPA (static dist/web-client/ shipped, Vite middleware in --dev), the POST /__crtr/source bridge (views\' reads AND `crtr` command writes via the local exec/file/http transport), the GET /__crtr/events SSE change-invalidation lane, and on a browser ws://127.0.0.1:PORT/node/<id> connection opens that node\'s broker view.sock and relays frames VERBATIM both ways — the browser is the same protocol peer as `crtr attach` (one controller drives, extra viewers are read-only; arbitration + dialogs ride the same frames). The relay NEVER spawns pi or writes a session: the node must already have a running headless broker (focus or revive it first); all graph mutations flow through `crtr` subprocesses the bridge runs. The server keeps running until ctrl+c; the node is chosen in the browser via the URL, not on the command line.',
+            model: 'The branch is a long-running browser surface. `serve` starts the unified server on the bound host and port, serves the shell SPA, exposes the source/command bridge and SSE change lane, and relays browser frames to a node\'s running broker. The node is chosen in the browser via the URL; the server itself only hosts the surface and never spawns an engine.',
         },
         children: [webServeLeaf],
     });

package/dist/commands/__tests__/human.test.js

@@ -10,6 +10,8 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { parseArgv } from '../../core/command.js';
+import { renderLeafArgv } from '../../core/help.js';
+import { humanAsk } from '../human/prompts.js';
 import { humanCancel } from '../human/queue.js';
 import { createNode, getNode, closeDb } from '../../core/canvas/index.js';
 // ---------------------------------------------------------------------------
@@ -23,34 +25,6 @@ function tmpJson(obj) {
     return p;
 }
 // ---------------------------------------------------------------------------
-// human approve — positional title + optional flags
-// ---------------------------------------------------------------------------
-describe('human approve: params', () => {
-    const params = [
-        { kind: 'positional', name: 'title', type: 'string', required: true, constraint: 'The question.' },
-        { kind: 'flag', name: 'subtitle', type: 'string', required: false, constraint: 'One-line context.' },
-        { kind: 'flag', name: 'body', type: 'string', required: false, constraint: 'Markdown body.' },
-    ];
-    test('parses positional title', async () => {
-        const result = await parseArgv(params, ['Deploy to prod?']);
-        assert.equal(result['title'], 'Deploy to prod?');
-    });
-    test('parses title with optional flags', async () => {
-        const result = await parseArgv(params, ['Deploy?', '--subtitle', 'v1.2.3', '--body', 'LGTM']);
-        assert.equal(result['title'], 'Deploy?');
-        assert.equal(result['subtitle'], 'v1.2.3');
-        assert.equal(result['body'], 'LGTM');
-    });
-    test('flags absent → undefined', async () => {
-        const result = await parseArgv(params, ['Deploy?']);
-        assert.equal(result['subtitle'], undefined);
-        assert.equal(result['body'], undefined);
-    });
-    test('missing title throws missing_parameter', async () => {
-        await assert.rejects(() => parseArgv(params, []), (err) => { assert.match(err.message, /required parameter is missing/); return true; });
-    });
-});
-// ---------------------------------------------------------------------------
 // human review — positional file (path) + optional --output
 // ---------------------------------------------------------------------------
 describe('human review: params', () => {
@@ -172,6 +146,34 @@ describe('human ask: params', () => {
     });
 });
 // ---------------------------------------------------------------------------
+// human ask — shorthand question + strict --context-file deck
+// ---------------------------------------------------------------------------
+describe('human ask: shorthand', () => {
+    test('help documents both the bare question and --context-file forms', () => {
+        const out = renderLeafArgv(humanAsk.help);
+        assert.match(out, /QUESTION/);
+        assert.match(out, /--context-file PATH/);
+        assert.match(out, /crtr human ask "<question>"/);
+        assert.match(out, /crtr human ask --context-file deck\.json/);
+    });
+    test('parses a positional question into input.question', async () => {
+        const result = await parseArgv(humanAsk.help.params ?? [], ['Should we ship today?']);
+        assert.equal(result['question'], 'Should we ship today?');
+        assert.equal(result['wait'], false);
+    });
+    test('parses --context-file into input.deck while keeping the strict deck path', async () => {
+        const deck = {
+            title: 'Choose a path',
+            interactions: [
+                { id: 'q', title: 'Pick one', options: [{ id: 'yes', label: 'Yes' }] },
+            ],
+        };
+        const path = tmpJson(deck);
+        const result = await parseArgv(humanAsk.help.params ?? [], ['--context-file', path]);
+        assert.deepEqual(result['deck'], deck);
+    });
+});
+// ---------------------------------------------------------------------------
 // human cancel — positional job_id + optional --reason
 // ---------------------------------------------------------------------------
 describe('human cancel: params', () => {

package/dist/commands/canvas-history/search.js

@@ -2,7 +2,7 @@ import { defineLeaf } from '../../core/command.js';
 import { usage } from '../../core/errors.js';
 import { buildCorpus, } from '../../core/canvas/index.js';
 const TYPES = ['report', 'doc', 'roadmap', 'meta'];
-const NODE_KINDS = ['developer', 'spec', 'design', 'review', 'explore', 'plan', 'general'];
+const NODE_KINDS = ['advisor', 'developer', 'spec', 'design', 'review', 'explore', 'plan', 'general'];
 const STATUSES = ['active', 'idle', 'done', 'dead', 'canceled'];
 const SORTS = ['relevance', 'recency', 'oldest'];
 const REL_UNITS = {

package/dist/commands/canvas-history.js

@@ -9,15 +9,12 @@ import { defineBranch } from '../core/command.js';
 import { searchLeaf } from './canvas-history/search.js';
 import { readLeaf } from './canvas-history/read.js';
 import { showLeaf } from './canvas-history/show.js';
-import { callerCwd, corpusStats } from '../core/canvas/index.js';
-/** The bounded per-cwd `<corpus>` aggregate for the branch -h — pre-empts a
- *  `search` call just to gauge the corpus (cli-design §15: aggregate, never
- *  enumerate). Soft-fails to omission if the db is unreachable. */
+/** A tiny per-cwd `<corpus>` marker for branch -h — just enough context to
+ *  anchor the help text without scanning nodes or files. Uses only the injected
+ *  node cwd env (or the process cwd outside a node), so help stays cheap. */
 function corpusBlock() {
-    const cwd = callerCwd();
-    const s = corpusStats(cwd);
-    const span = s.span !== null ? `${s.span.from} → ${s.span.to}` : 'n/a';
-    return `<corpus cwd="${cwd}" nodes="${s.nodes}" reports="${s.reports}" docs="${s.docs}" span="${span}"/>`;
+    const cwd = process.env['CRTR_NODE_CWD'] ?? process.cwd();
+    return `<corpus cwd="${cwd}"/>`;
 }
 export const historyBranch = defineBranch({
     name: 'history',

package/dist/commands/canvas-issue.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../core/command.js';
+export declare const issueNewLeaf: LeafDef;