@crouton-kit/crouter 0.3.27 → 0.3.29

package/dist/clients/attach/titled-editor.js

@@ -0,0 +1,84 @@
+// titled-editor.ts — the `crtr attach` input editor with two bits of chrome pi's
+// stock editor doesn't give us:
+//   1. the session name painted INTO the top border as a solid-background chip,
+//      so it stays pinned to the editor instead of scrolling off as a free badge;
+//   2. a border color that tracks the agent's thinking level (set by attach-cmd
+//      on each state update), mirroring pi's `getThinkingBorderColor`.
+// Both are pure render-layer chrome; nothing here touches the socket or session.
+import { CustomEditor } from '@earendil-works/pi-coding-agent';
+import { truncateToWidth, visibleWidth } from '@earendil-works/pi-tui';
+/** Per-level border/chip color as a 24-bit RGB triple — ONE blue-violet hue at
+ *  CONSTANT perceived lightness (luma ≈ 120) whose SATURATION alone climbs with
+ *  the budget: a near-gray blue at `minimal` deepening to a vivid violet at
+ *  `xhigh`, never getting lighter or darker — only more colorful. (pi paints its
+ *  own `thinking*` theme colors off its public palette surface, so we own this
+ *  ramp directly — truecolor, not the 16-color ANSI hues, so the saturation
+ *  climb actually reads.) `off` falls back to the caller's default border color. */
+const THINKING_RGB = {
+    off: undefined, // default border color
+    minimal: [125, 115, 135], // near-gray blue-violet
+    low: [129, 109, 151], // muted blue-violet
+    medium: [134, 103, 168], // violet
+    high: [139, 98, 184], // deeper violet
+    xhigh: [144, 92, 200], // vivid violet
+};
+/** The default (thinking `off`) title chip: reverse video + a space of padding
+ *  each side, so the name reads as a label sitting on the border rule. Used as
+ *  the fallback when no thinking color applies. */
+export const defaultTitleStyle = (s) => `\x1b[7m ${s} \x1b[27m`;
+/** Resolve the editor border colorizer for a thinking level. Unknown / `off` →
+ *  the supplied `fallback` (the theme's default border color). */
+export function thinkingBorderColor(level, fallback) {
+    const rgb = level === undefined ? undefined : THINKING_RGB[level];
+    if (rgb === undefined)
+        return fallback;
+    const [r, g, b] = rgb;
+    return (s) => `\x1b[38;2;${r};${g};${b}m${s}\x1b[39m`;
+}
+/** Resolve the title-chip styler for a thinking level: the level's color as the
+ *  chip BACKGROUND with bold white text (a space of padding each side), so the
+ *  session name reads as a solid label in the same hue as the border. Unknown /
+ *  `off` → the supplied `fallback` (the reverse-video default chip). */
+export function thinkingTitleStyle(level, fallback) {
+    const rgb = level === undefined ? undefined : THINKING_RGB[level];
+    if (rgb === undefined)
+        return fallback;
+    const [r, g, b] = rgb;
+    return (s) => `\x1b[48;2;${r};${g};${b}m\x1b[97m\x1b[1m ${s} \x1b[0m`;
+}
+/** Compose the replacement top-border line: solid title chip + border rule +
+ *  info chip, never wider than `width` (pi-tui hard-crashes on an over-wide
+ *  line). The info chip yields entirely when the chip leaves it almost no room,
+ *  and truncates when it only partially fits. Exported pure for the overflow
+ *  regression test. */
+export function composeTopBorder(width, title, info, titleStyle, borderColor) {
+    const chip = title ? titleStyle(truncateToWidth(title, Math.max(1, width - 4), '…')) : '';
+    const chipW = visibleWidth(chip);
+    const avail = width - chipW;
+    let infoChip = '';
+    if (info && avail > 4) {
+        infoChip = visibleWidth(info) <= avail ? info : truncateToWidth(info, avail, '…');
+    }
+    const fill = Math.max(0, width - chipW - visibleWidth(infoChip));
+    return chip + borderColor('─'.repeat(fill)) + infoChip;
+}
+export class TitledEditor extends CustomEditor {
+    /** Session-name chip painted into the LEFT of the top border. Empty → plain. */
+    title = '';
+    /** Pre-styled context string painted into the RIGHT of the top border (cwd /
+     *  branch / git status). Already colorized by the caller; empty → omitted. */
+    info = '';
+    /** Paint the chip solid so the name reads as a label sitting on the border
+     *  rule. Defaults to the reverse-video chip; attach-cmd swaps in a
+     *  thinking-colored background (bold white text) on each state update. */
+    titleStyle = defaultTitleStyle;
+    render(width) {
+        const lines = super.render(width);
+        if ((this.title || this.info) && lines.length > 0) {
+            // Replace the stock top border; dashes in the current (thinking-aware)
+            // border color.
+            lines[0] = composeTopBorder(width, this.title, this.info, this.titleStyle, (s) => this.borderColor(s));
+        }
+        return lines;
+    }
+}

package/dist/clients/attach/view-socket.d.ts

@@ -1,8 +1,23 @@
 import { EventEmitter } from 'node:events';
-import { type BrokerToClient, type ClientToBroker } from '../../core/runtime/broker-protocol.js';
+import type { NodeRow } from '../../core/canvas/types.js';
+import { type BrokerDataFrame, type BrokerToClient, type ClientToBroker, type DequeueFrame, type GetSettingsFrame, type GetTreeFrame, type ListModelsFrame, type ListScopedModelsFrame, type ListSessionsFrame } from '../../core/runtime/broker-protocol.js';
+/** A correlated read-op (or `dequeue`) request MINUS the client-chosen `id` —
+ *  {@link ViewSocketClient.request} mints the `id`, sends the frame, and resolves
+ *  with the matching `data` reply. The picker/operator code builds these; the
+ *  socket owns the correlation token so callers never hand-roll one. */
+export type ReadOpRequest = Omit<ListModelsFrame, 'id'> | Omit<ListSessionsFrame, 'id'> | Omit<GetTreeFrame, 'id'> | Omit<GetSettingsFrame, 'id'> | Omit<ListScopedModelsFrame, 'id'> | Omit<DequeueFrame, 'id'>;
 /** Surfaced when the node has no reachable broker at connect time (no socket
  *  file, or a stale socket with nothing listening). The command catches this to
  *  exit non-zero with a focus/revive hint. */
+/** The reconnect supervisor's give-up predicate (extracted pure so it is
+ *  testable without a socket or TUI). After a broker close the viewer KEEPS
+ *  re-dialing the same `view.sock` while the node is still alive — a yield
+ *  leaves `status='active'` (intent='refresh') and the daemon revives a fresh
+ *  broker on the same path. It gives up only when the node is genuinely gone:
+ *  a terminal status (done/dead/canceled) or a reaped row (null). `idle` is NOT
+ *  terminal — an idle-release node revives on its next inbox wake, so keep
+ *  trying (the supervisor's own ~30s bound caps an indefinite wait). */
+export declare function reconnectShouldGiveUp(row: NodeRow | null): boolean;
 export declare class BrokerUnavailableError extends Error {
     readonly nodeId: string;
     constructor(nodeId: string);
@@ -24,15 +39,35 @@ export interface ViewSocketClient {
 export declare class ViewSocketClient extends EventEmitter {
     private readonly nodeId;
     private socket;
-    private readonly decoder;
+    private decoder;
     private closeEmitted;
+    /** In-flight correlated read-ops, keyed by the `id` minted in {@link request}.
+     *  Resolved by the matching `data` frame / rejected by the matching `error`
+     *  frame in {@link onData}, the request's timeout, or socket teardown. */
+    private pending;
     constructor(nodeId: string);
+    /** Issue a correlated read-op and resolve with the broker's `data` reply (or
+     *  reject on the correlated `error`, a timeout, or socket teardown). Mints the
+     *  `id`, sends `{...frame, id}`, and parks a resolver consumed by {@link onData}.
+     *  The reply is narrowed by the caller on its `kind`. */
+    request(frame: ReadOpRequest): Promise<BrokerDataFrame>;
+    /** Reject + clear every in-flight request (socket gone / decode error) so a
+     *  picker fetch never hangs past the connection it rode on. */
+    private rejectAllPending;
     /** The broker binds `join(nodeDir(id), 'view.sock')` — resolve it the same way. */
     get socketPath(): string;
     /** Open the connection. Wire up listeners; emits `connect` on success or
      *  `error` (a {@link BrokerUnavailableError} for ECONNREFUSED/ENOENT) on
      *  failure. Idempotent guard is the caller's job — call once. */
     connect(): void;
+    /** Re-establish the socket after a broker exit (a yield→revive cycle), on the
+     *  SAME stable `view.sock` path. Installs a FRESH FrameDecoder (a half-frame
+     *  from the dead stream must not corrupt the new one) and resets the close
+     *  guard, then re-dials. Resolves on `connect` (caller re-sends `hello`);
+     *  rejects on the dial's `error` (ECONNREFUSED while the new broker is
+     *  mid-boot, or ENOENT before it re-binds the socket) — both retryable. A
+     *  post-connect error flows through the normal `onError`→`close` path. */
+    redial(): Promise<void>;
     /** Encode + write one client→broker frame. No-op on a dead/absent socket
      *  (a `close` event drives teardown); never throws. */
     send(frame: ClientToBroker): void;

package/dist/clients/attach/view-socket.js

@@ -9,20 +9,40 @@
 // what keeps a broker alive, not attach). It also never uses pi's `RpcClient`
 // (which would spawn its own engine).
 //
-// No reconnect: a dropped broker means the engine's turn-cycle settled and the
-// broker disposed+exited; a fresh focus re-runs attach. On EOF/close → emit
-// `close` (the caller renders "broker gone" + exits). On a connect-time
-// ECONNREFUSED/ENOENT → a `BrokerUnavailableError` so the command exits non-zero
-// with a clear message. Decode is bounded by `CLIENT_READ_CAPS`; a broker that
-// somehow sends an oversized frame surfaces as a clean error+exit, not a crash.
+// Reconnect: a dropped broker emits `close`; the caller's reconnect supervisor
+// decides whether to re-dial (a yield/revive keeps the SAME `view.sock` path —
+// `redial()` re-establishes the socket on it) or give up ("broker gone"). On a
+// connect-time ECONNREFUSED/ENOENT → a `BrokerUnavailableError` so the FIRST
+// connect exits non-zero with a clear message; the same codes during a redial
+// reject the redial promise as retryable. Decode is bounded by
+// `CLIENT_READ_CAPS`; a broker that somehow sends an oversized frame surfaces as
+// a clean error+exit, not a crash.
 import { EventEmitter } from 'node:events';
+import { randomUUID } from 'node:crypto';
 import { createConnection } from 'node:net';
 import { join } from 'node:path';
 import { nodeDir } from '../../core/canvas/paths.js';
 import { CLIENT_READ_CAPS, encodeFrame, FrameDecoder, FrameOverflowError, } from '../../core/runtime/broker-protocol.js';
+/** How long {@link ViewSocketClient.request} waits for the correlated reply before
+ *  rejecting — bounds a pending picker fetch if the broker drops the request
+ *  (it should always reply with `data` or a correlated `error`). */
+const REQUEST_TIMEOUT_MS = 10_000;
 /** Surfaced when the node has no reachable broker at connect time (no socket
  *  file, or a stale socket with nothing listening). The command catches this to
  *  exit non-zero with a focus/revive hint. */
+/** The reconnect supervisor's give-up predicate (extracted pure so it is
+ *  testable without a socket or TUI). After a broker close the viewer KEEPS
+ *  re-dialing the same `view.sock` while the node is still alive — a yield
+ *  leaves `status='active'` (intent='refresh') and the daemon revives a fresh
+ *  broker on the same path. It gives up only when the node is genuinely gone:
+ *  a terminal status (done/dead/canceled) or a reaped row (null). `idle` is NOT
+ *  terminal — an idle-release node revives on its next inbox wake, so keep
+ *  trying (the supervisor's own ~30s bound caps an indefinite wait). */
+export function reconnectShouldGiveUp(row) {
+    if (row === null)
+        return true;
+    return row.status === 'done' || row.status === 'dead' || row.status === 'canceled';
+}
 export class BrokerUnavailableError extends Error {
     nodeId;
     constructor(nodeId) {
@@ -36,10 +56,48 @@ export class ViewSocketClient extends EventEmitter {
     socket;
     decoder = new FrameDecoder(CLIENT_READ_CAPS);
     closeEmitted = false;
+    /** In-flight correlated read-ops, keyed by the `id` minted in {@link request}.
+     *  Resolved by the matching `data` frame / rejected by the matching `error`
+     *  frame in {@link onData}, the request's timeout, or socket teardown. */
+    pending = new Map();
     constructor(nodeId) {
         super();
         this.nodeId = nodeId;
     }
+    /** Issue a correlated read-op and resolve with the broker's `data` reply (or
+     *  reject on the correlated `error`, a timeout, or socket teardown). Mints the
+     *  `id`, sends `{...frame, id}`, and parks a resolver consumed by {@link onData}.
+     *  The reply is narrowed by the caller on its `kind`. */
+    request(frame) {
+        const id = randomUUID();
+        return new Promise((resolve, reject) => {
+            // Fail fast on a dead/absent socket rather than parking a promise that the
+            // reply will never reach (it would otherwise hang the full timeout). A
+            // post-`close` request lands here too — `rejectAllPending` already ran.
+            const sock = this.socket;
+            if (sock === undefined || sock.destroyed) {
+                reject(new Error(`cannot issue '${frame.type}': no live broker connection`));
+                return;
+            }
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`request '${frame.type}' timed out after ${REQUEST_TIMEOUT_MS}ms`));
+            }, REQUEST_TIMEOUT_MS);
+            if (typeof timer.unref === 'function')
+                timer.unref();
+            this.pending.set(id, { resolve, reject, timer });
+            this.send({ ...frame, id });
+        });
+    }
+    /** Reject + clear every in-flight request (socket gone / decode error) so a
+     *  picker fetch never hangs past the connection it rode on. */
+    rejectAllPending(reason) {
+        for (const { reject, timer } of this.pending.values()) {
+            clearTimeout(timer);
+            reject(new Error(reason));
+        }
+        this.pending.clear();
+    }
     /** The broker binds `join(nodeDir(id), 'view.sock')` — resolve it the same way. */
     get socketPath() {
         return join(nodeDir(this.nodeId), 'view.sock');
@@ -55,6 +113,46 @@ export class ViewSocketClient extends EventEmitter {
         socket.on('error', (err) => this.onError(err));
         socket.on('close', () => this.onClose());
     }
+    /** Re-establish the socket after a broker exit (a yield→revive cycle), on the
+     *  SAME stable `view.sock` path. Installs a FRESH FrameDecoder (a half-frame
+     *  from the dead stream must not corrupt the new one) and resets the close
+     *  guard, then re-dials. Resolves on `connect` (caller re-sends `hello`);
+     *  rejects on the dial's `error` (ECONNREFUSED while the new broker is
+     *  mid-boot, or ENOENT before it re-binds the socket) — both retryable. A
+     *  post-connect error flows through the normal `onError`→`close` path. */
+    redial() {
+        this.destroy();
+        this.decoder = new FrameDecoder(CLIENT_READ_CAPS);
+        this.closeEmitted = false;
+        return new Promise((resolve, reject) => {
+            const socket = createConnection(this.socketPath);
+            this.socket = socket;
+            let settled = false;
+            socket.on('connect', () => {
+                if (settled)
+                    return;
+                settled = true;
+                this.emit('connect');
+                resolve();
+            });
+            socket.on('data', (chunk) => this.onData(chunk));
+            socket.on('error', (err) => {
+                if (settled) {
+                    this.onError(err);
+                    return;
+                }
+                settled = true;
+                try {
+                    socket.destroy();
+                }
+                catch {
+                    /* ignore */
+                }
+                reject(err);
+            });
+            socket.on('close', () => this.onClose());
+        });
+    }
     /** Encode + write one client→broker frame. No-op on a dead/absent socket
      *  (a `close` event drives teardown); never throws. */
     send(frame) {
@@ -83,12 +181,37 @@ export class ViewSocketClient extends EventEmitter {
             const msg = err instanceof FrameOverflowError
                 ? `broker sent an oversized frame (${err.message}) — disconnecting`
                 : `failed to decode a broker frame: ${String(err)}`;
+            this.rejectAllPending(msg);
             this.emitError(new Error(msg));
             this.destroy();
             return;
         }
         for (const raw of frames) {
-            this.emit('frame', raw);
+            const frame = raw;
+            // Correlated replies (read-ops + dequeue) are consumed by the pending-by-id
+            // resolver, NOT re-emitted as a generic 'frame' (the attach frame router
+            // would otherwise treat a `data` frame as an AgentSessionEvent). A `data`
+            // frame is ALWAYS a reply, so it is swallowed unconditionally — even a late
+            // post-timeout one (no pending entry) is dropped, never leaked to the
+            // router. An `error` is correlated only when its `id` matches an in-flight
+            // request; an uncorrelated error still flows through.
+            if (frame.type === 'data') {
+                const entry = typeof frame.id === 'string' ? this.pending.get(frame.id) : undefined;
+                if (entry) {
+                    this.pending.delete(frame.id);
+                    clearTimeout(entry.timer);
+                    entry.resolve(frame);
+                }
+                continue;
+            }
+            if (frame.type === 'error' && typeof frame.id === 'string' && this.pending.has(frame.id)) {
+                const entry = this.pending.get(frame.id);
+                this.pending.delete(frame.id);
+                clearTimeout(entry.timer);
+                entry.reject(new Error(frame.message || `request failed: ${frame.code}`));
+                continue;
+            }
+            this.emit('frame', frame);
         }
     }
     onError(err) {
@@ -104,6 +227,7 @@ export class ViewSocketClient extends EventEmitter {
         if (this.closeEmitted)
             return;
         this.closeEmitted = true;
+        this.rejectAllPending('broker connection closed');
         this.emit('close');
     }
     destroy() {

package/dist/clients/web/dev-server.d.ts

@@ -0,0 +1,7 @@
+import type { Server as HttpServer } from 'node:http';
+import type { ViteDevServer } from 'vite';
+/** Create a Vite dev server in middleware mode, HMR bound to `httpServer`.
+ *  Mirrors the old `view serve` resolve setup so the shell's bare imports
+ *  (react, the `@crouton-kit/crouter/web` self-subpath) resolve from the
+ *  generated/shell root. Lazily imports vite so the shipped path never loads it. */
+export declare function createDevServer(httpServer: HttpServer): Promise<ViteDevServer>;

package/dist/clients/web/dev-server.js

@@ -0,0 +1,59 @@
+// dev-server.ts — `crtr web serve --dev` Vite middleware mode.
+//
+// The shipped server serves a prebuilt static shell bundle from dist/web-client/
+// (§11). In --dev a contributor iterating on the shell or a builtin view gets
+// HMR instead: a Vite dev server in MIDDLEWARE mode mounted on the SAME HTTP
+// server as the bridge + WS relay. This is the one place Vite runs at runtime —
+// the mainstream "Vite middleware in dev, static dist in prod" split.
+//
+// The bridge (POST /__crtr/source), the SSE lane (GET /__crtr/events) and the
+// WS relay are owned by server.ts and checked BEFORE Vite's middlewares; this
+// module only supplies the asset/HMR middleware. Vite's HMR WebSocket shares
+// the HTTP server (server.hmr.server) — server.ts's upgrade handler routes
+// `/node/<id>` to the broker relay and leaves every other upgrade for Vite.
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const HERE = dirname(fileURLToPath(import.meta.url));
+/** The shell SPA Vite root — the in-tree shell project (`src/clients/web/web-client/`).
+ *  --dev is a from-source contributor loop, so this resolves against the source
+ *  tree (HERE is `dist/clients/web` when built, `src/clients/web` under tsx);
+ *  walk to the package root and into src. */
+function resolveShellRoot(packageRoot) {
+    return join(packageRoot, 'src', 'clients', 'web', 'web-client');
+}
+/** Create a Vite dev server in middleware mode, HMR bound to `httpServer`.
+ *  Mirrors the old `view serve` resolve setup so the shell's bare imports
+ *  (react, the `@crouton-kit/crouter/web` self-subpath) resolve from the
+ *  generated/shell root. Lazily imports vite so the shipped path never loads it. */
+export async function createDevServer(httpServer) {
+    const packageRoot = resolve(HERE, '../../..');
+    const nodeModules = join(packageRoot, 'node_modules');
+    const shellRoot = resolveShellRoot(packageRoot);
+    const { createServer } = await import('vite');
+    const react = (await import('@vitejs/plugin-react')).default;
+    const tailwindcss = (await import('@tailwindcss/vite')).default;
+    return createServer({
+        configFile: false,
+        root: shellRoot,
+        plugins: [react(), tailwindcss()],
+        appType: 'spa',
+        resolve: {
+            alias: {
+                react: join(nodeModules, 'react'),
+                'react-dom': join(nodeModules, 'react-dom'),
+                // The crtr web runtime is a self-subpath of crouter's own package;
+                // pin it to the built barrel so the shell can import it from any root.
+                '@crouton-kit/crouter/web': join(packageRoot, 'dist', 'web', 'index.js'),
+            },
+            dedupe: ['react', 'react-dom'],
+        },
+        server: {
+            middlewareMode: true,
+            // Share our HTTP server for HMR; server.ts's upgrade handler hands every
+            // non-`/node/<id>` upgrade to Vite (the vite-hmr WebSocket).
+            hmr: { server: httpServer },
+            fs: { allow: [shellRoot, packageRoot] },
+        },
+        logLevel: 'warn',
+    });
+}

package/dist/clients/web/events.d.ts

@@ -0,0 +1,14 @@
+import type { ServerResponse } from 'node:http';
+export type ChangeKind = 'nodes' | 'inbox';
+export interface EventHub {
+    /** Register an SSE client: writes the event-stream headers, streams events
+     *  until the connection closes, and self-removes on close. */
+    addClient: (res: ServerResponse) => void;
+    /** Tear down watchers + heartbeat and end all open streams. */
+    close: () => void;
+}
+/** Start the change-event hub: open the two fs watchers once, fan their
+ *  debounced invalidations out to every connected SSE client. Watchers run for
+ *  the server's lifetime (cheap — two inotify/FSEvents registrations), not
+ *  per-client, so N browsers share one watch. */
+export declare function startEventHub(): EventHub;

package/dist/clients/web/events.js

@@ -0,0 +1,151 @@
+// events.ts — the `crtr web` realtime push lane (the §7 SSE seam, built for v1).
+//
+// ONE server-sent-events stream, `GET /__crtr/events`, that carries CHANGE
+// INVALIDATIONS — never data. The shell / its ViewPanes subscribe and, on an
+// event, re-pull through their existing Sources (the bridge) instead of waiting
+// on a fixed poll tick. SSE carries "something in this class changed"; the
+// consumer decides what to re-read. This keeps the event vocabulary tiny and
+// generic and the contract unchanged (a ViewPane still just runs `refresh`).
+//
+// Event vocabulary (deliberately minimal): { kind: 'nodes' | 'inbox', ts }.
+//   - 'nodes' — the node graph changed (topology, status/intent transitions,
+//     naming). Source: canvas.db (+ its WAL sidecar) mtime. Every transition()
+//     and canvas mutation writes the WAL, so a watch on the home dir's
+//     `canvas.db*` files detects all of them with one cheap watcher.
+//   - 'inbox' — a node's inbox.jsonl gained a message. Source: a recursive watch
+//     on the nodes/ tree, filtered to `inbox.jsonl` writes.
+//
+// WHY these sources (the §7 seam left the event source open): they are the
+// cheapest things that detect node-graph + inbox changes without a daemon hook
+// or a db trigger — pure fs.watch on the two on-disk authorities (canvas.db for
+// the graph, inbox.jsonl appends for messages). No polling, no canvas.db reads.
+import { watch } from 'node:fs';
+import { crtrHome, nodesRoot, ensureHome } from '../../core/canvas/paths.js';
+/** Coalesce a burst of fs events into one emission per kind. WAL writes and
+ *  inbox appends arrive in clusters (a single transition can touch -wal/-shm);
+ *  a short trailing debounce collapses each cluster into a single invalidation,
+ *  which is all a re-pull consumer needs. */
+const DEBOUNCE_MS = 150;
+/** SSE keepalive comment cadence — keeps proxies/clients from idling the stream
+ *  shut. A bare `:` comment line is ignored by EventSource. */
+const HEARTBEAT_MS = 25_000;
+/** Start the change-event hub: open the two fs watchers once, fan their
+ *  debounced invalidations out to every connected SSE client. Watchers run for
+ *  the server's lifetime (cheap — two inotify/FSEvents registrations), not
+ *  per-client, so N browsers share one watch. */
+export function startEventHub() {
+    ensureHome();
+    const clients = new Set();
+    const watchers = [];
+    const timers = new Map();
+    const broadcast = (kind) => {
+        const line = `data: ${JSON.stringify({ kind, ts: Date.now() })}\n\n`;
+        for (const res of clients) {
+            try {
+                res.write(line);
+            }
+            catch {
+                /* a dead stream is reaped by its own 'close' handler */
+            }
+        }
+    };
+    // Debounce per kind: an fs event arms a trailing timer; a fresh event within
+    // the window resets it, so a write cluster emits exactly once.
+    const emit = (kind) => {
+        const existing = timers.get(kind);
+        if (existing !== undefined)
+            clearTimeout(existing);
+        timers.set(kind, setTimeout(() => {
+            timers.delete(kind);
+            broadcast(kind);
+        }, DEBOUNCE_MS));
+    };
+    // Watcher 1 — the canvas home dir (non-recursive). canvas.db lives in WAL
+    // mode, so graph writes land in canvas.db-wal and checkpoints in canvas.db;
+    // watching the dir catches every `canvas.db*` sidecar touch → 'nodes'.
+    try {
+        const homeWatcher = watch(crtrHome(), (_event, filename) => {
+            if (filename !== null && filename.startsWith('canvas.db'))
+                emit('nodes');
+        });
+        homeWatcher.on('error', () => {
+            /* watch dropped (dir replaced) — non-fatal; the poll cadence still backs us */
+        });
+        watchers.push(homeWatcher);
+    }
+    catch {
+        /* fs.watch unavailable on this platform — degrade to poll-only (no SSE) */
+    }
+    // Watcher 2 — the nodes/ tree (recursive). An inbox.jsonl append is a message
+    // landing; a meta.json write is a graph/identity change (naming, polymorph).
+    // Recursive fs.watch is supported on macOS/Windows always and Linux ≥ v20.
+    try {
+        const nodesWatcher = watch(nodesRoot(), { recursive: true }, (_event, filename) => {
+            if (filename === null)
+                return;
+            if (filename.endsWith('inbox.jsonl'))
+                emit('inbox');
+            else if (filename.endsWith('meta.json'))
+                emit('nodes');
+        });
+        nodesWatcher.on('error', () => {
+            /* recursive watch refused/dropped — non-fatal */
+        });
+        watchers.push(nodesWatcher);
+    }
+    catch {
+        /* recursive watch unsupported — inbox push degrades to poll-only */
+    }
+    const heartbeat = setInterval(() => {
+        for (const res of clients) {
+            try {
+                res.write(': ping\n\n');
+            }
+            catch {
+                /* reaped by its 'close' handler */
+            }
+        }
+    }, HEARTBEAT_MS);
+    heartbeat.unref();
+    return {
+        addClient(res) {
+            res.writeHead(200, {
+                'content-type': 'text/event-stream; charset=utf-8',
+                'cache-control': 'no-cache, no-transform',
+                connection: 'keep-alive',
+                // The browser EventSource is same-origin here; no CORS header needed.
+            });
+            // An initial comment flushes headers and confirms the stream is open.
+            res.write(': connected\n\n');
+            clients.add(res);
+            const drop = () => {
+                clients.delete(res);
+            };
+            res.on('close', drop);
+            res.on('error', drop);
+        },
+        close() {
+            clearInterval(heartbeat);
+            for (const t of timers.values())
+                clearTimeout(t);
+            timers.clear();
+            for (const w of watchers) {
+                try {
+                    w.close();
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+            for (const res of clients) {
+                try {
+                    res.end();
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+            clients.clear();
+        },
+    };
+}

package/dist/clients/web/server.d.ts

@@ -0,0 +1,18 @@
+export interface WebServerOptions {
+    port: number;
+    host?: string;
+    /** --dev: mount a Vite dev server (middleware mode, HMR) for asset serving
+     *  instead of the static dist/web-client/ bundle. The bridge + SSE + WS relay
+     *  are identical in both modes. */
+    dev?: boolean;
+}
+export interface RunningWebServer {
+    url: string;
+    port: number;
+    clientDir: string;
+    close: () => Promise<void>;
+}
+/** 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. */
+export declare function startWebServer(opts: WebServerOptions): Promise<RunningWebServer>;