spexcode 0.6.2 → 0.6.5

package/node_modules/@spexcode/spec-cli/dist/graphStream.js

@@ -0,0 +1,1195 @@
+import { streamSSE } from 'hono/streaming';
+import { watch, mkdirSync, readdirSync, readFileSync } from 'node:fs';
+import { join, dirname, relative, resolve, basename } from 'node:path';
+import { sessionsRoot, gitCommonDir, repoRoot, sessionBranchIndex, mainBranch } from '@spexcode/spec-core';
+import { hotSignature, warmSignature, listSessions, pendingSessionCreateWorktreePaths } from './sessions.js';
+import { getBoard, getBoardForSessionRefresh, invalidateBoard, patrolBoard } from './graphCache.js';
+import { unitize, tagOf, diffUnits } from '@spexcode/spec-core';
+import { holdSessionEvalProjectionObserver, invalidateSessionEvalProjections, releaseSessionEvalProjectionObserver, setSessionEvalProjectionNotify, setSessionEvalProjectionWarmup, } from '@spexcode/spec-eval/sessioneval';
+// @@@ watch transport - the ONE place the platform appears. Observing a tree is a single product-level
+// registration; how many registrations the OS actually holds for it is the transport's business.
+//   consolidated-recursive — the OS itself observes a whole subtree from one registration (Darwin
+//     FSEvents, Windows ReadDirectoryChangesW). It reports by PATH, so an atomic replacement inside the
+//     tree stays visible, and exclusions filter on delivery because nothing is consumed per directory.
+//   exact-directory — no such observer exists (Linux), and Node's `recursive` option is a USERSPACE
+//     fan-out registering one inotify watch per file AND directory (measured: 201 directories -> 801
+//     watches) which, watching files by inode, goes blind the moment a file is atomically replaced. So
+//     we enumerate directories once and install one NON-recursive watch each, all multiplexed onto the
+//     loop's single shared inotify descriptor, excluding .git/node_modules at traversal time.
+export const consolidatedRecursiveWatch = (platform = process.platform) => platform === 'darwin' || platform === 'win32';
+// The live census across every registry: `sources` is what graph-stream asked the platform for (one per
+// canonical root), `registrations` is what the platform is actually holding for them. Both are read by the
+// watcher-budget tests and logged under SPEXCODE_BOARD_DEBUG, so a plateau is observable on every platform
+// rather than only where /proc exposes inotify descriptors.
+const liveRegistries = new Set();
+let liveRegistrations = 0;
+export function graphWatcherCensus() {
+    return { sources: liveRegistries.size, registrations: liveRegistrations };
+}
+export class TreeWatcherRegistry {
+    root;
+    source;
+    scope;
+    transport;
+    recursive;
+    ignore;
+    watchFactory;
+    onInput;
+    onFailure;
+    handles = new Map();
+    refreshImmediate = null;
+    failed = false;
+    constructor(options) {
+        this.root = resolve(options.root);
+        this.source = options.source;
+        this.scope = options.scope;
+        this.recursive = options.recursive !== false;
+        this.transport = options.transport
+            ?? (this.recursive && consolidatedRecursiveWatch() ? 'consolidated-recursive' : 'exact-directory');
+        this.ignore = options.ignore ?? (() => false);
+        this.watchFactory = options.watchFactory ?? watch;
+        this.onInput = options.onInput;
+        this.onFailure = options.onFailure;
+    }
+    get size() { return this.handles.size; }
+    paths() { return [...this.handles.keys()].sort(); }
+    // one kernel-side observer covers the subtree: the root is the only path we register, and no rename can
+    // make the desired set drift, so there is nothing to re-walk.
+    get consolidated() { return this.recursive && this.transport === 'consolidated-recursive'; }
+    desiredDirectories() {
+        const desired = new Set();
+        const visit = (dir) => {
+            desired.add(dir);
+            if (!this.recursive || this.consolidated)
+                return;
+            let entries;
+            try {
+                entries = readdirSync(dir, { withFileTypes: true });
+            }
+            catch (error) {
+                if (dir !== this.root && error.code === 'ENOENT') {
+                    desired.delete(dir);
+                    return;
+                }
+                throw error;
+            }
+            for (const entry of entries) {
+                if (!entry.isDirectory() || entry.isSymbolicLink())
+                    continue;
+                const path = join(dir, entry.name);
+                const rel = relative(this.root, path);
+                if (!this.ignore(rel))
+                    visit(path);
+            }
+        };
+        visit(this.root);
+        return desired;
+    }
+    closeHandles() {
+        if (this.refreshImmediate) {
+            clearImmediate(this.refreshImmediate);
+            this.refreshImmediate = null;
+        }
+        const handles = [...this.handles.values()];
+        this.handles.clear();
+        liveRegistrations -= handles.length;
+        liveRegistries.delete(this);
+        for (const handle of handles) {
+            try {
+                handle.close();
+            }
+            catch { /* already gone */ }
+        }
+    }
+    sourceError(path, error) {
+        const err = error;
+        const reason = error instanceof Error ? error.message : String(error);
+        // source + path + errno, always — an exhausted platform must name which syscall budget it refused.
+        const errno = err?.code && !reason.includes(err.code) ? ` (errno ${err.code})` : '';
+        return new Error(`spec-cli: graph watcher '${this.source}' failed at ${path}: ${reason}${errno}`);
+    }
+    fail(path, error) {
+        if (this.failed)
+            return false;
+        this.failed = true;
+        this.closeHandles();
+        this.onFailure(this.sourceError(path, error));
+        return false;
+    }
+    scheduleRefresh() {
+        if (this.refreshImmediate || this.failed)
+            return;
+        this.refreshImmediate = setImmediate(() => {
+            this.refreshImmediate = null;
+            this.refresh();
+        });
+        this.refreshImmediate.unref?.();
+    }
+    refresh() {
+        if (this.refreshImmediate) {
+            clearImmediate(this.refreshImmediate);
+            this.refreshImmediate = null;
+        }
+        this.failed = false;
+        let desired;
+        try {
+            desired = this.desiredDirectories();
+        }
+        catch (error) {
+            return this.fail(this.root, error);
+        }
+        const before = this.handles.size;
+        for (const [path, handle] of [...this.handles]) {
+            if (desired.has(path))
+                continue;
+            this.handles.delete(path);
+            liveRegistrations--;
+            try {
+                handle.close();
+            }
+            catch { /* already gone */ }
+        }
+        const options = this.consolidated ? { recursive: true } : {};
+        for (const path of desired) {
+            if (this.handles.has(path))
+                continue;
+            try {
+                let handle;
+                const callback = (event, filename) => {
+                    if (this.handles.get(path) !== handle)
+                        return;
+                    if (filename == null) {
+                        this.fail(path, new Error('pathless filesystem event'));
+                        return;
+                    }
+                    const inputPath = resolve(path, String(filename));
+                    const rel = relative(this.root, inputPath);
+                    if (rel.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`) || rel === '..') {
+                        this.fail(path, new Error(`event escaped watcher root: ${String(filename)}`));
+                        return;
+                    }
+                    if (this.ignore(rel))
+                        return;
+                    this.onInput(event, rel);
+                    // only the userspace transport's desired set can drift: a new directory under a consolidated
+                    // observer is already covered by the kernel.
+                    if (this.recursive && !this.consolidated && event === 'rename')
+                        this.scheduleRefresh();
+                };
+                handle = this.watchFactory(path, options, callback);
+                this.handles.set(path, handle);
+                liveRegistrations++;
+                handle.on('error', (error) => {
+                    if (this.handles.get(path) === handle)
+                        this.fail(path, error);
+                });
+            }
+            catch (error) {
+                return this.fail(path, error);
+            }
+        }
+        if (this.handles.size)
+            liveRegistries.add(this);
+        if (DEBUG && this.handles.size !== before)
+            console.warn(`spec-cli: graph watchers — sources=${liveRegistries.size} registrations=${liveRegistrations} (${this.source}: ${this.transport} ${this.handles.size})`);
+        return true;
+    }
+    close() {
+        this.failed = false;
+        this.closeHandles();
+    }
+}
+const plainSubs = new Set();
+const deltaSubs = new Set();
+let debounce = null;
+let pendingFull = false;
+let pendingSessions = false;
+export const addPendingGraphChange = (pending, scope) => ({
+    full: pending.full || scope === 'full',
+    sessions: pending.sessions || scope === 'sessions',
+});
+// Git creates the registry entry before the session transaction publishes its durable record. A registry
+// event for that private candidate must not start a full board build while the `git worktree add` child is
+// still running; the create route flushes the deferred event after publication (or cleanup).
+export function isSessionCreateCandidateRegistryEvent(relativePath, candidatePaths) {
+    const entry = relativePath.split(/[\\/]+/).filter(Boolean)[0] ?? '';
+    if (!entry)
+        return false;
+    for (const path of candidatePaths)
+        if (basename(resolve(path)) === entry)
+            return true;
+    return false;
+}
+// under SPEXCODE_BOARD_DEBUG=1, every broadcast logs its changed unit keys + trigger tags + build ms.
+const DEBUG = process.env.SPEXCODE_BOARD_DEBUG === '1';
+function traceLatency(stage, detail = {}) {
+    if (DEBUG)
+        console.warn(`spec-cli: graph latency ${JSON.stringify({ at: Date.now(), stage, ...detail })}`);
+}
+// the set of trigger tags accrued SINCE THE LAST BROADCAST — each fireChanged adds its scope, the cold tick
+// adds 'patrol'. Cleared on every broadcast. Its job: prove WHO caused a broadcast, so a change that only
+// the patrol saw (tag set === {'patrol'}) is flagged as a repair — some leaf watcher was blind.
+const triggerTags = new Set();
+// watchers a test can amputate to prove the patrol still heals the graph ([[graph-stream]]): a CSV of
+// store,refs,worktrees,project-root makes the matching ensure* a no-op (with a one-time warning), so a change on that
+// path reaches subscribers ONLY via the cold-tick patrol — the missing-watcher scenario, on demand.
+const DISABLED = new Set((process.env.SPEXCODE_DISABLE_WATCHERS || '').split(',').map((s) => s.trim()).filter(Boolean));
+const warnedDisabled = new Set();
+function isDisabled(name) {
+    if (!DISABLED.has(name))
+        return false;
+    if (!warnedDisabled.has(name)) {
+        warnedDisabled.add(name);
+        console.warn(`spec-cli: graph watcher '${name}' disabled via SPEXCODE_DISABLE_WATCHERS — the cold-tick patrol must cover it`);
+    }
+    return true;
+}
+// ---- the rebuild→diff→broadcast pipeline (runs only while delta subscribers exist) ----
+// last successfully-broadcast snapshot: the delta chain's anchor. `lastFullFrame` is what a fresh
+// subscriber gets instantly; `lastUnits`+`lastTag` are what the next diff chains from. A snapshot that
+// failed the unitize precondition anchors nothing (lastUnits=null) so every following send is a full.
+let lastUnits = null;
+let lastTag = '';
+let lastFullFrame = null;
+let building = false;
+let dirty = false;
+let patrolPending = false;
+let sessionRefreshRequested = false;
+let wakeSessionRefresh = null;
+async function rebuildAndBroadcast(patrol = false, sessions = false, full = false) {
+    if (patrol)
+        patrolPending = true;
+    if (sessions)
+        sessionRefreshRequested = true;
+    if (building) {
+        dirty = true;
+        if (sessions) {
+            wakeSessionRefresh?.();
+            wakeSessionRefresh = null;
+        }
+        return;
+    }
+    building = true;
+    try {
+        do {
+            dirty = false;
+            const validate = patrolPending;
+            patrolPending = false;
+            const sessionsFirst = sessionRefreshRequested;
+            sessionRefreshRequested = false;
+            let servedSessionProjection = sessionsFirst;
+            let board;
+            // share the route's single-flight build ([[graph-cache]]); fireChanged() already invalidated the
+            // cache (at the accumulated scope), so this gets a fresh build/splice (or joins one a concurrent poll
+            // already started). The patrol instead asks that same cache flight to validate its input revision;
+            // equal inputs return the anchor without invoking a producer.
+            const t0 = Date.now();
+            try {
+                let wake;
+                const sessionWake = new Promise((resolve) => { wake = resolve; });
+                wakeSessionRefresh = wake;
+                // A sessions-first turn can still fall back to an active route-owned full. Keep its wait wakeable
+                // too: a later persisted session change must re-enter the cheap projection rather than queue behind it.
+                const boardWait = sessionsFirst
+                    ? getBoardForSessionRefresh()
+                    : validate ? patrolBoard() : getBoard();
+                const outcome = await Promise.race([
+                    boardWait.then((value) => ({ value })),
+                    sessionWake.then(() => ({ value: null })),
+                ]);
+                if (wakeSessionRefresh === wake)
+                    wakeSessionRefresh = null;
+                if (outcome.value === null) {
+                    boardWait.catch(() => { });
+                    board = await getBoardForSessionRefresh();
+                    servedSessionProjection = true;
+                    if (validate)
+                        patrolPending = true;
+                    dirty = true; // the full wait was preempted only for delivery; it remains owed.
+                }
+                else {
+                    board = outcome.value;
+                    if (sessionsFirst && validate) {
+                        patrolPending = true;
+                        dirty = true;
+                    }
+                }
+            }
+            catch {
+                // A failed refresh consumes no cause: graph-cache restores the producer scope, so its stream-side
+                // attribution must remain owed too. This also retains watcher causes that arrived while the failed
+                // flight was occupied. A later patrol may recover the work, but it is then one cause alongside those
+                // healthy leaf signals rather than a false patrol-only blind-watcher repair.
+                for (const n of [...plainSubs]) {
+                    try {
+                        n();
+                    }
+                    catch { /* swept on abort */ }
+                }
+                continue;
+            }
+            const buildMs = Date.now() - t0;
+            if (servedSessionProjection)
+                traceLatency('session-projection-complete', { patrol: validate });
+            const boardJson = JSON.stringify(board);
+            const { units, ok } = unitize(board);
+            const tag = tagOf(units);
+            // A session-first frame consumes its own cause, but a full/patrol cause remains owed until structural
+            // convergence. Otherwise the first cheap projection would erase patrol accountability before the full
+            // result could name it. A normal frame consumes its whole trigger set, including a no-op frame.
+            const tags = [...triggerTags];
+            triggerTags.clear();
+            if (servedSessionProjection)
+                for (const tag of tags)
+                    if (tag === 'full' || tag === 'patrol')
+                        triggerTags.add(tag);
+            if (sessionsFirst && full)
+                dirty = true;
+            if (tag === lastTag)
+                continue;
+            // the changed unit keys — computed against the prior anchor when we have one (a first paint has no
+            // anchor, so no repair claim can be made against it).
+            const changedKeys = lastUnits ? (() => { const { set, del } = diffUnits(lastUnits, units); return [...Object.keys(set), ...del]; })() : [];
+            const fullFrame = { event: 'graph-full', data: `{"to":"${tag}","graph":${boardJson}}` };
+            let frame = fullFrame;
+            if (lastUnits && ok) {
+                const { set, del } = diffUnits(lastUnits, units);
+                const deltaData = JSON.stringify({ from: lastTag, to: tag, set, del });
+                // guaranteed win: ship the patch only when it actually beats the snapshot
+                if (deltaData.length < fullFrame.data.length)
+                    frame = { event: 'graph-delta', data: deltaData };
+            }
+            // the anchor is only meaningful while a delta subscriber holds the chain live: with none left,
+            // nothing rebuilds on change, so a cached anchor would silently age into a stale first frame for the
+            // NEXT era's subscriber (issue #70). A build that completes after the last unsub caches nothing
+            // (stopSourcesIfIdle cleared the anchor; leaving lastTag/lastUnits stale-cleared is consistent —
+            // rebuilds only run while delta subscribers exist, so nothing chains from them meanwhile).
+            if (deltaSubs.size) {
+                lastUnits = ok ? units : null;
+                lastTag = tag;
+                lastFullFrame = fullFrame;
+            }
+            traceLatency('broadcast', { event: frame.event, sessionProjection: servedSessionProjection, tags, changedKeys });
+            for (const send of [...deltaSubs]) {
+                try {
+                    send(frame);
+                }
+                catch { /* swept on abort */ }
+            }
+            for (const n of [...plainSubs]) {
+                try {
+                    n();
+                }
+                catch { /* swept on abort */ }
+            }
+            // ---- repair accounting: a real (tag-moved) broadcast whose ONLY trigger was the cold-tick patrol
+            // means a leaf watcher was BLIND — the patrol self-healed it. That is a bug report, not routine, so
+            // it is ALWAYS loud (repairs are supposed to be zero — [[graph-stream]]). Under DEBUG, every
+            // broadcast logs its changed keys + triggers + build ms.
+            if (changedKeys.length && tags.length === 1 && tags[0] === 'patrol')
+                console.warn(`spec-cli: PATROL-REPAIR — the cold tick caught a change no leaf watcher pushed; changed units: [${changedKeys.join(', ')}] — a blind watcher, investigate`);
+            if (DEBUG)
+                console.warn(`spec-cli: graph broadcast — changed [${changedKeys.join(', ')}] triggers {${tags.join(', ')}} build ${buildMs}ms`);
+        } while (dirty);
+    }
+    finally {
+        building = false;
+    }
+}
+// a merge/launch/close touches several record files at once; collapse the burst into ONE signal. Each call
+// carries its own change SCOPE: full and sessions are independent obligations, not a max-scope replacement.
+// With delta subscribers the debounced fire rebuilds and broadcasts (plain subs then ride the same
+// tag-moved gate — no spurious refetches); without them it stays the zero-build legacy notify.
+function fireChanged(scope = 'full', evalTarget) {
+    // Advance eval input generations BEFORE invalidating/building the board, so the first frame caused by an
+    // input event is `updating(lastKnown)`. Summary completion calls this function without a target.
+    if (scope === 'sessions')
+        traceLatency('sessions-signal');
+    if (evalTarget)
+        invalidateSessionEvalProjections(evalTarget);
+    const pending = addPendingGraphChange({ full: pendingFull, sessions: pendingSessions }, scope);
+    pendingFull = pending.full;
+    pendingSessions = pending.sessions;
+    // invalidate the route's board cache ([[graph-cache]]) on EVERY change signal at its OWN scope,
+    // before the debounce guard — a plain-mode client that polls /api/graph (no delta rebuild here) must
+    // still see fresh data on its next poll, and a delta rebuild below re-reads the same now-stale cache.
+    invalidateBoard(scope);
+    triggerTags.add(scope);
+    // DEBOUNCE = 25ms. Real fs-event bursts (a merge touching many records) were MEASURED to span 0–5ms, so a
+    // 25ms window collapses them with room to spare while shaving ~125ms off the old 150ms lag; anything
+    // wider than the window is coalesced anyway by the in-flight build's dirty-rerun loop, which is the real
+    // burst absorber. So the debounce is a micro-collapse, not the coalescer.
+    if (debounce)
+        return;
+    debounce = setTimeout(() => {
+        debounce = null;
+        const full = pendingFull, sessions = pendingSessions;
+        pendingFull = false;
+        pendingSessions = false;
+        if (deltaSubs.size)
+            void rebuildAndBroadcast(false, sessions, full);
+        else
+            for (const notify of [...plainSubs]) {
+                try {
+                    notify();
+                }
+                catch { /* swept on abort */ }
+            }
+    }, 25);
+}
+// ---- event source 0: an EXPLICIT server-side nudge ----
+// for a server-side mutation that must show instantly regardless of watcher health: /rename writes the
+// session's global record (`session.json` — [[session-rename]]), which lives INSIDE the watched store, so
+// source 1 normally sees the write too. The explicit route call stays because that fs watch is best-effort
+// (it can fail to attach), and the nudge makes the sub-second rename guarantee deterministic. Same
+// debounced funnel as every other source; defaults to 'full' but the rename route passes 'sessions'.
+export const notifyBoardChanged = (scope = 'full') => fireChanged(scope, scope === 'full' ? 'all' : undefined);
+// Stable summary batches re-enter the SAME session-unit graph path; this is not a second transport.
+setSessionEvalProjectionNotify(() => fireChanged('sessions'));
+// ---- ONE repair scheduler for every filesystem source ----
+// A source the platform refuses keeps its observer hold and is retried by THIS timer alone — never by a
+// graph build, an HTTP read, a poller tick or a registry event. That is the whole anti-storm rule: the
+// resource being exhausted (a registration budget, a descriptor table) is PROCESS-wide, so its backoff
+// belongs to the process, not to each source racing its own retry and re-walking the corpus every time.
+// `heldSources` is what an ordinary pass may not re-attempt; only the scheduled pass lifts that.
+const heldSources = new Set();
+let repairTimer = null;
+let repairStep = 0;
+let repairing = false;
+const mayAttach = (source) => repairing || !heldSources.has(source);
+// The failure is loud ONCE per episode and names source + path + errno (the registry built that message);
+// every later source felled by the same exhausted budget is counted, not re-printed, and the repair line
+// reports the total. A half-attached registry is already closed by the registry itself before we get here.
+function noteSourceFailure(source, error) {
+    const known = heldSources.has(source);
+    heldSources.add(source);
+    if (!known && heldSources.size === 1)
+        console.error(error instanceof Error ? error.message : String(error));
+    scheduleWatcherRepair();
+}
+function noteSourceHealthy(source) {
+    if (!heldSources.delete(source))
+        return;
+    if (heldSources.size === 0)
+        repairStep = 0;
+}
+function scheduleWatcherRepair() {
+    if (repairTimer || !heldSources.size)
+        return;
+    const delay = Math.min(30_000, 250 * 2 ** Math.min(repairStep, 7));
+    repairStep++;
+    const era = watcherEra;
+    console.error(`spec-cli: graph watcher repair — ${heldSources.size} source(s) held, retrying in ${delay}ms; the cold-tick patrol covers the gap until they reattach`);
+    repairTimer = setTimeout(() => {
+        repairTimer = null;
+        if (era !== watcherEra)
+            return;
+        repairing = true;
+        void ensureBoardFileWatchers()
+            .catch((error) => console.error(`spec-cli: graph watcher repair failed — ${error instanceof Error ? error.message : String(error)}`))
+            .finally(() => {
+            repairing = false;
+            if (heldSources.size)
+                scheduleWatcherRepair();
+        });
+    }, delay);
+    repairTimer.unref?.();
+}
+// ---- event source 1: the session store (lifecycle status writes) → 'sessions' ----
+let activeStoreRoot = null;
+let activeCommonRoot = null;
+let watcherEra = 0;
+let storeWatcher = null;
+function ensureWatcher(root) {
+    if (storeWatcher?.root === root)
+        return;
+    if (storeWatcher) {
+        storeWatcher.close();
+        storeWatcher = null;
+    }
+    if (isDisabled('store') || !mayAttach('store'))
+        return;
+    try {
+        mkdirSync(root, { recursive: true });
+    }
+    catch (error) {
+        console.error(`spec-cli: graph watcher 'store' could not create ${root}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const registry = new TreeWatcherRegistry({
+        root,
+        source: 'store',
+        scope: 'sessions',
+        onInput: () => { dropBranchIndex(); fireChanged('sessions'); }, // a created/renamed session may own a new branch
+        onFailure: (error) => {
+            if (storeWatcher === registry)
+                storeWatcher = null;
+            noteSourceFailure('store', error);
+            fireChanged('sessions');
+        },
+    });
+    storeWatcher = registry;
+    if (!registry.refresh()) {
+        if (storeWatcher === registry)
+            storeWatcher = null;
+        return;
+    }
+    noteSourceHealthy('store');
+}
+let refsWatchers = null;
+const REFS_OBSERVER = 'graph:refs';
+// @@@ the moved ref NAMES its scope - the watcher has always known which ref moved and threw it away, so
+// every ref movement anywhere invalidated every session's evaluation. On a host carrying dozens of branches
+// and a bot that commits continuously that means nothing is ever warm: observed on adopter-a as an input
+// generation of 1208 against a last-known 254. A session's fingerprint reads exactly three refs — its own
+// tip, the base tip, and their merge-base — so a ref that is neither cannot move it. `packed-refs` and
+// `HEAD` stay broad on purpose: a packed update rewrites many refs behind ONE event, so it names nothing.
+// the index is read from the session store, so it is only ever stale when that store moved — and the store
+// has its own watcher, which drops it. A ref burst therefore costs one map lookup, not 76 record reads.
+let branchIndexMemo = null;
+function branchIndex() {
+    return (branchIndexMemo ??= sessionBranchIndex());
+}
+function dropBranchIndex() { branchIndexMemo = null; }
+export function evalTargetForRef(ref, base, branches) {
+    if (ref === undefined)
+        return 'all'; // an unnamed movement must assume the worst
+    const rel = ref.replace(/\\/g, '/');
+    if (!rel.startsWith('heads/'))
+        return undefined; // tags and remotes feed no session fingerprint
+    const branch = rel.slice('heads/'.length);
+    if (!branch)
+        return 'all';
+    if (branch === base)
+        return 'all'; // every merge-base may have moved
+    const id = branches.get(branch);
+    return id ? { id } : undefined; // a branch no session owns moves no session's evaluation
+}
+export function watchSessionEvalRefs(common, onInput, onFailure) {
+    let attached = [];
+    let failed = false;
+    let ready = false;
+    let attachError = null;
+    const close = () => {
+        const registries = attached;
+        attached = [];
+        for (const registry of registries)
+            registry.close();
+    };
+    const fail = (error) => {
+        if (failed)
+            return;
+        failed = true;
+        close();
+        if (ready)
+            onFailure(error);
+        else
+            attachError = error;
+    };
+    const refs = new TreeWatcherRegistry({
+        root: join(common, 'refs'),
+        source: 'refs',
+        scope: 'full',
+        onInput: (_event, rel) => onInput(rel),
+        onFailure: fail,
+    });
+    attached.push(refs);
+    if (!refs.refresh())
+        throw attachError ?? new Error(`spec-cli: graph watcher 'refs' failed at ${refs.root}`);
+    const commonFiles = new TreeWatcherRegistry({
+        root: common,
+        source: 'refs-common',
+        scope: 'full',
+        recursive: false,
+        onInput: (_event, file) => { if (file === 'packed-refs' || file === 'HEAD')
+            onInput(); }, // names nothing -> 'all'
+        onFailure: fail,
+    });
+    attached.push(commonFiles);
+    if (!commonFiles.refresh())
+        throw attachError ?? new Error(`spec-cli: graph watcher 'refs-common' failed at ${common}`);
+    ready = true;
+    return { root: resolve(common), close };
+}
+function refsWatcherFailed(error) {
+    refsWatchers = null;
+    noteSourceFailure('refs', error);
+    if (holdSessionEvalProjectionObserver(REFS_OBSERVER, 'all'))
+        fireChanged('full');
+}
+function ensureRefsWatcher(common = activeCommonRoot) {
+    if (!common)
+        return;
+    if (refsWatchers?.root === common)
+        return;
+    if (refsWatchers) {
+        refsWatchers.close();
+        refsWatchers = null;
+    }
+    if (isDisabled('refs')) {
+        if (holdSessionEvalProjectionObserver(REFS_OBSERVER, 'all'))
+            fireChanged('full');
+        return;
+    }
+    if (!mayAttach('refs'))
+        return;
+    try {
+        refsWatchers = watchSessionEvalRefs(common, (ref) => fireChanged('full', evalTargetForRef(ref, mainBranch(), branchIndex())), refsWatcherFailed);
+        noteSourceHealthy('refs');
+        if (releaseSessionEvalProjectionObserver(REFS_OBSERVER))
+            fireChanged('full');
+    }
+    catch (error) {
+        refsWatchers = null;
+        noteSourceFailure('refs', error);
+        if (holdSessionEvalProjectionObserver(REFS_OBSERVER, 'all'))
+            fireChanged('full');
+    }
+}
+// ---- event source 3: worktree registry + working roots + per-worktree indexes → 'full' ----
+// Summary inputs include ordinary dirty source and staged-only changes, not just `.spec`. Each live
+// worktree is therefore TWO canonical roots — its working tree and git's metadata dir for it (`index`) —
+// and that pair is the whole per-worktree registration cost, whatever the corpus inside it holds.
+let registryWatcher = null;
+let registryReady = false;
+const worktreeWatchers = new Map();
+const worktreeObserver = (name) => `graph:worktree:${name}`;
+const worktreeSource = (name) => `worktree:${name}`;
+const PROJECT_ROOT_SOURCE = 'project-root';
+let projectRootWatcher = null;
+const ignoredWorktreePath = (file) => file.split(/[\\/]/).some((segment) => segment === '.git' || segment === 'node_modules');
+// @@@ linked worktrees are not graph input for THIS backend - the board's node statuses derive from the
+// served checkout's own HEAD, so a file under `.worktrees/<node>` belongs to a different branch's tree and
+// cannot move any status here until it lands and this HEAD advances. Watching them registers one inotify
+// watch per directory (Linux takes the exact-directory transport) and buys nothing: measured on this repo,
+// 20,124 of 20,473 watched directories were linked worktrees against 843 in the served tree.
+// The per-worktree registries above keep their own roots; only the project-root sweep skips them.
+export const ignoredProjectRootPath = (file) => ignoredWorktreePath(file) || file.split(/[\\/]/).some((segment) => segment === '.worktrees');
+// The directory whose tree this backend serves is graph input even before it has a `.spec` tree or any live
+// session worktree. Keeping it in the same root registry as linked worktrees means a first `spex init` or
+// agent-created spec invalidates a warmed empty board instead of leaving a confidently stale cache until a
+// delta patrol happens to repair it. `repoRoot()` matches graph-cache's revision owner: a backend launched
+// from a linked worktree must observe that linked root, not the common-dir checkout.
+function ensureProjectRootWatcher() {
+    const root = resolve(repoRoot());
+    const coveredByWorktree = [...worktreeWatchers.values()].some((row) => row.path === root);
+    if (projectRootWatcher?.root === root && !coveredByWorktree)
+        return;
+    if (projectRootWatcher) {
+        projectRootWatcher.close();
+        projectRootWatcher = null;
+    }
+    // A malformed registry that resolves a linked worktree onto the served project must not spend a duplicate root
+    // registration. That live worktree watcher already names a full graph change on every root event.
+    if (coveredByWorktree) {
+        noteSourceHealthy(PROJECT_ROOT_SOURCE);
+        return;
+    }
+    if (isDisabled(PROJECT_ROOT_SOURCE))
+        return;
+    if (!mayAttach(PROJECT_ROOT_SOURCE))
+        return;
+    let registry;
+    registry = new TreeWatcherRegistry({
+        root,
+        source: PROJECT_ROOT_SOURCE,
+        scope: 'full',
+        ignore: ignoredProjectRootPath,
+        onInput: () => fireChanged('full', 'all'),
+        onFailure: (error) => {
+            if (projectRootWatcher === registry)
+                projectRootWatcher = null;
+            noteSourceFailure(PROJECT_ROOT_SOURCE, error);
+            fireChanged('full', 'all');
+        },
+    });
+    projectRootWatcher = registry;
+    if (!registry.refresh()) {
+        if (projectRootWatcher === registry)
+            projectRootWatcher = null;
+        return;
+    }
+    noteSourceHealthy(PROJECT_ROOT_SOURCE);
+}
+export function watchSessionEvalWorktree(wtPath, gitDir, onInput, onFailure) {
+    let failed = false;
+    let ready = false;
+    let attachError = null;
+    let root = null;
+    let index = null;
+    const close = () => {
+        root?.close();
+        index?.close();
+    };
+    const fail = (error) => {
+        if (failed)
+            return;
+        failed = true;
+        close();
+        if (ready)
+            onFailure(error);
+        else
+            attachError = error;
+    };
+    root = new TreeWatcherRegistry({
+        root: wtPath,
+        source: `worktree:${resolve(wtPath)}`,
+        scope: 'full',
+        ignore: ignoredWorktreePath,
+        onInput: () => onInput(),
+        onFailure: fail,
+    });
+    if (!root.refresh())
+        throw attachError ?? new Error(`spec-cli: graph watcher 'worktree' failed at ${wtPath}`);
+    index = new TreeWatcherRegistry({
+        root: gitDir,
+        source: `worktree-index:${resolve(wtPath)}`,
+        scope: 'full',
+        recursive: false,
+        onInput: (_event, file) => { if (file === 'index')
+            onInput(); },
+        onFailure: fail,
+    });
+    if (!index.refresh())
+        throw attachError ?? new Error(`spec-cli: graph watcher 'worktree-index' failed at ${gitDir}`);
+    ready = true;
+    return { path: resolve(wtPath), root, index, close };
+}
+function dropWorktreeWatcher(name) {
+    const row = worktreeWatchers.get(name);
+    if (!row)
+        return null;
+    worktreeWatchers.delete(name);
+    row.close();
+    return row;
+}
+function watcherFailed(name, path, error) {
+    // Failure/overflow has no trustworthy path. Keep last-known, mark the target updating, and hand the
+    // reattach to the one repair scheduler; the authorized summary build is the one authoritative rescan,
+    // never a periodic sweep and never a re-walk driven by whatever read noticed the failure.
+    dropWorktreeWatcher(name);
+    noteSourceFailure(worktreeSource(name), error);
+    if (holdSessionEvalProjectionObserver(worktreeObserver(name), { path }))
+        fireChanged('full');
+}
+const forcedWorktreeSessions = new Set();
+let worktreeReconcileFlight = null;
+export function sessionWorktreeWatchPaths(sessions, forcedSessions = new Set()) {
+    return new Set(sessions
+        .filter((session) => session.liveness !== 'offline' || forcedSessions.has(session.id))
+        .map((session) => resolve(session.path)));
+}
+async function reconcileWorktreePass(forcedSessions, era, common) {
+    const dir = join(common, 'worktrees');
+    let sessions;
+    try {
+        sessions = await listSessions();
+    }
+    catch {
+        return;
+    }
+    if (era !== watcherEra)
+        return;
+    const wantedPaths = sessionWorktreeWatchPaths(sessions, forcedSessions);
+    let ents = [];
+    try {
+        ents = readdirSync(dir, { withFileTypes: true });
+    }
+    catch { /* no worktrees registry yet */ }
+    const wantedNames = new Set();
+    let released = false;
+    for (const e of ents) {
+        if (!e.isDirectory())
+            continue;
+        let wtPath;
+        try {
+            wtPath = dirname(readFileSync(join(dir, e.name, 'gitdir'), 'utf8').trim());
+        }
+        catch {
+            continue;
+        }
+        const normalizedPath = resolve(wtPath);
+        if (!wantedPaths.has(normalizedPath)) {
+            if (dropWorktreeWatcher(e.name))
+                released = releaseSessionEvalProjectionObserver(worktreeObserver(e.name)) || released;
+            noteSourceHealthy(worktreeSource(e.name));
+            continue;
+        }
+        wantedNames.add(e.name);
+        const existing = worktreeWatchers.get(e.name);
+        if (existing?.path === normalizedPath)
+            continue;
+        const rootChanged = existing != null;
+        if (existing)
+            dropWorktreeWatcher(e.name);
+        // a held worktree is the repair scheduler's to reattach — an ordinary reconcile pass must not re-walk
+        // it, which is what turned one refused registration into a per-read attach storm.
+        if (!mayAttach(worktreeSource(e.name)))
+            continue;
+        try {
+            // the entry's `gitdir` file points at the worktree's `<tree>/.git` (file or dir); its parent is the tree.
+            const row = watchSessionEvalWorktree(wtPath, join(dir, e.name), () => fireChanged('full', { path: wtPath }), (error) => watcherFailed(e.name, wtPath, error));
+            if (era !== watcherEra) {
+                row.close();
+                return;
+            }
+            worktreeWatchers.set(e.name, row);
+            noteSourceHealthy(worktreeSource(e.name));
+            if (rootChanged)
+                fireChanged('full', { path: wtPath });
+            // The replacement is live before its hold is removed. This delta authorizes one double-read rescan,
+            // so edits made anywhere in the unwatched interval are inside the new generation's fingerprint.
+            if (releaseSessionEvalProjectionObserver(worktreeObserver(e.name)))
+                fireChanged('full');
+        }
+        catch (error) {
+            // An attach failure is observable: mark unknown/full now. The repair scheduler owns the reattach; no
+            // patrol is allowed to call the eval projection current meanwhile.
+            noteSourceFailure(worktreeSource(e.name), error);
+            if (holdSessionEvalProjectionObserver(worktreeObserver(e.name), { path: wtPath }))
+                fireChanged('full');
+        }
+    }
+    for (const name of worktreeWatchers.keys())
+        if (!wantedNames.has(name)) {
+            dropWorktreeWatcher(name);
+            released = releaseSessionEvalProjectionObserver(worktreeObserver(name)) || released;
+        }
+    for (const source of [...heldSources]) {
+        const name = source.startsWith('worktree:') ? source.slice('worktree:'.length) : null;
+        if (name && !wantedNames.has(name)) {
+            noteSourceHealthy(source);
+            released = releaseSessionEvalProjectionObserver(worktreeObserver(name)) || released;
+        }
+    }
+    if (released)
+        fireChanged('full');
+}
+function reconcileWorktrees(forceSessionId) {
+    // Blinding a leaf must blind it from EVERY entry point. Reconciliation is reached from the liveness
+    // poller and from registry events as well as from the ensure pass, so gating only the ensure pass left
+    // the per-worktree observers attaching anyway — the injection looked applied while the leaf still saw
+    // everything, which makes the patrol's accountability untestable rather than merely untested.
+    if (isDisabled('worktrees'))
+        return Promise.resolve();
+    if (forceSessionId)
+        forcedWorktreeSessions.add(forceSessionId);
+    if (worktreeReconcileFlight)
+        return worktreeReconcileFlight;
+    const era = watcherEra;
+    const common = activeCommonRoot;
+    if (!common)
+        return Promise.resolve();
+    const flight = (async () => {
+        do {
+            if (era !== watcherEra)
+                return;
+            const forced = new Set(forcedWorktreeSessions);
+            forcedWorktreeSessions.clear();
+            await reconcileWorktreePass(forced, era, common);
+        } while (forcedWorktreeSessions.size);
+    })().finally(() => { if (worktreeReconcileFlight === flight)
+        worktreeReconcileFlight = null; });
+    worktreeReconcileFlight = flight;
+    void flight.catch((error) => {
+        console.warn(`spec-cli: worktree watcher reconciliation failed — ${error instanceof Error ? error.message : String(error)}`);
+    });
+    return flight;
+}
+const WORKTREE_REGISTRY_OBSERVER = 'graph:worktree-registry';
+let deferredRegistryChange = false;
+let deferredRegistryTimer = null;
+function flushDeferredRegistryChange() {
+    if (!deferredRegistryChange)
+        return;
+    deferredRegistryChange = false;
+    if (deferredRegistryTimer) {
+        clearTimeout(deferredRegistryTimer);
+        deferredRegistryTimer = null;
+    }
+    void reconcileWorktrees();
+    fireChanged('full', 'all');
+}
+// A crashed or disconnected create request must not leave the registry event deferred forever. The normal
+// route flush is immediate; this bounded fallback preserves the watcher contract if the process never reaches
+// its response boundary.
+function deferRegistryChange() {
+    deferredRegistryChange = true;
+    if (deferredRegistryTimer)
+        return;
+    deferredRegistryTimer = setTimeout(() => {
+        deferredRegistryTimer = null;
+        flushDeferredRegistryChange();
+    }, 10_000);
+    deferredRegistryTimer.unref?.();
+}
+export function flushDeferredWorktreeRegistryChange() {
+    flushDeferredRegistryChange();
+}
+export function watchSessionEvalRegistry(dir, onInput, onFailure) {
+    let ready = false;
+    let attachError = null;
+    const registry = new TreeWatcherRegistry({
+        root: dir,
+        source: 'worktree-registry',
+        scope: 'full',
+        recursive: false,
+        onInput: (_event, relativePath) => onInput(_event, relativePath),
+        onFailure: (error) => {
+            if (ready)
+                onFailure(error);
+            else
+                attachError = error;
+        },
+    });
+    if (!registry.refresh())
+        throw attachError ?? new Error(`spec-cli: graph watcher 'worktree-registry' failed at ${dir}`);
+    ready = true;
+    return registry;
+}
+function registryWatcherFailed(error) {
+    registryWatcher = null;
+    registryReady = false;
+    noteSourceFailure('worktree-registry', error);
+    if (holdSessionEvalProjectionObserver(WORKTREE_REGISTRY_OBSERVER, 'all'))
+        fireChanged('full');
+}
+async function ensureWorktreeRegistry(forceSessionId) {
+    const common = activeCommonRoot;
+    if (!common)
+        return;
+    const dir = resolve(join(common, 'worktrees'));
+    // The registry watcher already reconciles add/remove events. Re-scanning every ordinary graph/evals read
+    // turns a large worktree registry into an artificial request latency floor; only a scoped read may demand
+    // one target after startup, while the unscoped hot path reuses the attached live watchers.
+    // an attached registry short-circuits the scan for ordinary reads, but a REPAIR pass exists precisely to
+    // reattach held worktrees, so it must reach the reconcile even when the registry itself is healthy.
+    if (registryWatcher?.root === dir) {
+        if (forceSessionId || repairing)
+            await reconcileWorktrees(forceSessionId);
+        return;
+    }
+    if (registryWatcher) {
+        registryWatcher.close();
+        registryWatcher = null;
+        registryReady = false;
+    }
+    // A platform may reject registry watches. Once the initial reconciliation has run, ordinary
+    // reads must not repeat its full worktree scan while the repair pass is pending; scoped reads can
+    // still demand their target explicitly.
+    if (registryReady && !forceSessionId && !repairing)
+        return;
+    if (registryReady && (forceSessionId || repairing)) {
+        await reconcileWorktrees(forceSessionId);
+        return;
+    }
+    if (isDisabled('worktrees')) {
+        registryReady = true;
+        if (holdSessionEvalProjectionObserver(WORKTREE_REGISTRY_OBSERVER, 'all'))
+            fireChanged('full');
+        return;
+    }
+    if (!mayAttach('worktree-registry'))
+        return;
+    registryReady = true;
+    try {
+        try {
+            mkdirSync(dir, { recursive: true });
+        }
+        catch (error) {
+            console.error(`spec-cli: graph watcher 'worktree-registry' could not create ${dir}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        // a registry add/remove is itself a 'full' change (a new/gone worktree reshapes the overlay); also
+        // reconcile the per-worktree `.spec` watchers on every registry event.
+        registryWatcher = watchSessionEvalRegistry(dir, (_event, relativePath) => {
+            if (isSessionCreateCandidateRegistryEvent(relativePath, pendingSessionCreateWorktreePaths())) {
+                deferRegistryChange();
+                return;
+            }
+            void reconcileWorktrees();
+            fireChanged('full', 'all');
+        }, registryWatcherFailed);
+        noteSourceHealthy('worktree-registry');
+    }
+    catch (error) {
+        registryWatcher = null;
+        registryReady = false;
+        noteSourceFailure('worktree-registry', error);
+        if (holdSessionEvalProjectionObserver(WORKTREE_REGISTRY_OBSERVER, 'all'))
+            fireChanged('full');
+    }
+    await reconcileWorktrees(forceSessionId); // attach for the live/demanded worktrees that already exist
+    if (registryWatcher && releaseSessionEvalProjectionObserver(WORKTREE_REGISTRY_OBSERVER))
+        fireChanged('full');
+}
+// Attach the canonical filesystem sources before an HTTP snapshot starts summary work. This closes the
+// request→SSE handoff gap: an edit after the snapshot build has a watcher before it can occur. A source
+// the platform refused is NOT retried here — it is held for the repair scheduler, so an HTTP read never
+// becomes a reattach loop.
+export async function ensureBoardFileWatchers(forceSessionId) {
+    const storeRoot = resolve(sessionsRoot());
+    const commonRoot = resolve(gitCommonDir());
+    if ((activeStoreRoot && activeStoreRoot !== storeRoot) || (activeCommonRoot && activeCommonRoot !== commonRoot))
+        closeBoardFileWatchers();
+    activeStoreRoot = storeRoot;
+    activeCommonRoot = commonRoot;
+    ensureWatcher(storeRoot);
+    ensureRefsWatcher(commonRoot);
+    await ensureWorktreeRegistry(forceSessionId);
+    ensureProjectRootWatcher();
+}
+export function closeBoardFileWatchers() {
+    watcherEra++;
+    if (repairTimer) {
+        clearTimeout(repairTimer);
+        repairTimer = null;
+    }
+    if (deferredRegistryTimer) {
+        clearTimeout(deferredRegistryTimer);
+        deferredRegistryTimer = null;
+    }
+    deferredRegistryChange = false;
+    heldSources.clear();
+    repairStep = 0;
+    repairing = false;
+    forcedWorktreeSessions.clear();
+    worktreeReconcileFlight = null;
+    storeWatcher?.close();
+    storeWatcher = null;
+    refsWatchers?.close();
+    refsWatchers = null;
+    registryWatcher?.close();
+    registryWatcher = null;
+    registryReady = false;
+    projectRootWatcher?.close();
+    projectRootWatcher = null;
+    for (const [name, row] of worktreeWatchers) {
+        row.close();
+        releaseSessionEvalProjectionObserver(worktreeObserver(name));
+    }
+    worktreeWatchers.clear();
+    releaseSessionEvalProjectionObserver(REFS_OBSERVER);
+    releaseSessionEvalProjectionObserver(WORKTREE_REGISTRY_OBSERVER);
+    activeStoreRoot = null;
+    activeCommonRoot = null;
+}
+// ---- event source 4: the two-tier tmux-derived pollers (liveness + activity — never a file write) → 'sessions' ----
+// The signals a store watch can't see are tmux-derived, and they split by cost ([[sessions]]): a HOT 100ms
+// poll of a cheap syscall-only fingerprint (a socket dying, a listener wedging) and a WARM 1s poll of the
+// pane-title self-summaries (a headline change is a tmux round-trip, too dear at 100ms). Both fire 'sessions'.
+let hotPoller = null;
+let warmPoller = null;
+let lastHot = '';
+let lastWarm = '';
+function ensurePollers() {
+    if (!hotPoller)
+        hotPoller = setInterval(() => {
+            void hotSignature().then((sig) => {
+                if (sig !== lastHot) {
+                    lastHot = sig;
+                    void reconcileWorktrees();
+                    fireChanged('sessions');
+                }
+            }).catch(() => { });
+        }, 100);
+    if (!warmPoller)
+        warmPoller = setInterval(() => {
+            void warmSignature().then((sig) => { if (sig !== lastWarm) {
+                lastWarm = sig;
+                fireChanged('sessions');
+            } }).catch(() => { });
+        }, 1000);
+}
+// ---- event source 5: the cold-tick PATROL — the server-side replacement for every client's slow fallback
+// poll, AND the self-heal authority. A relaxed tick asks graph-cache's ONE flight to compare its board-input
+// revision: unchanged state returns the anchor without assembly, while an unobserved ref/worktree/store move
+// escalates there to a full rebuild. The 'patrol' tag keeps that repair accountable. Delta-gated: plain-only
+// clients keep their own client-side fallback, so without delta subscribers this does no validation work.
+let coldTick = null;
+function ensureColdTick() {
+    if (coldTick)
+        return;
+    coldTick = setInterval(() => {
+        if (!deltaSubs.size)
+            return;
+        triggerTags.add('patrol');
+        void rebuildAndBroadcast(true);
+    }, 15000);
+}
+function stopSourcesIfIdle() {
+    // the delta anchor dies with its era's last subscriber: past this point changes invalidate the cache but
+    // never rebuild, so lastFullFrame would drift arbitrarily far from the real board — and the next era's
+    // first subscriber would be anchored on it (its warm-terminal set then drops live sessions' panes, and the
+    // client's recovery lanes can latch each other out — issue #70). A new era opens on a fresh build instead.
+    if (deltaSubs.size === 0) {
+        lastUnits = null;
+        lastTag = '';
+        lastFullFrame = null;
+        patrolPending = false;
+    }
+    if (deltaSubs.size === 0)
+        setSessionEvalProjectionWarmup(false);
+    if (plainSubs.size + deltaSubs.size > 0)
+        return;
+    if (hotPoller) {
+        clearInterval(hotPoller);
+        hotPoller = null;
+        lastHot = '';
+    }
+    if (warmPoller) {
+        clearInterval(warmPoller);
+        warmPoller = null;
+        lastWarm = '';
+    }
+    if (coldTick) {
+        clearInterval(coldTick);
+        coldTick = null;
+    }
+}
+// GET /api/graph/stream — one SSE per dashboard tab, server→client only, with a periodic `ping` so an
+// idle proxy never times the connection out. On a backend hot-reload the stream drops and EventSource
+// auto-reconnects to the fresh child; a delta subscriber's reconnect lands a fresh `graph-full`, so the
+// chain re-anchors with no client-side repair logic.
+export async function boardStream(c) {
+    const delta = c.req.query('mode') === 'delta';
+    await ensureBoardFileWatchers();
+    return streamSSE(c, async (stream) => {
+        let aborted = false;
+        const send = (frame) => { void stream.writeSSE(frame).catch(() => { }); };
+        const notify = () => { void stream.writeSSE({ event: 'graph-changed', data: 'x' }).catch(() => { }); };
+        if (delta) {
+            deltaSubs.add(send);
+            setSessionEvalProjectionWarmup(true);
+            ensureColdTick();
+        }
+        else {
+            plainSubs.add(notify);
+        }
+        ensurePollers();
+        const unsub = () => { deltaSubs.delete(send); plainSubs.delete(notify); stopSourcesIfIdle(); };
+        stream.onAbort(() => { aborted = true; unsub(); });
+        try {
+            await stream.writeSSE({ event: 'ready', data: 'x' });
+            if (delta) {
+                // seed the chain: the cached anchor snapshot immediately (same tag the next delta chains from),
+                // then a fire so a connect during a quiet stretch converges to truly-current within one build.
+                if (lastFullFrame) {
+                    await stream.writeSSE(lastFullFrame).catch(() => { });
+                    fireChanged();
+                }
+                else
+                    void rebuildAndBroadcast();
+            }
+            while (!aborted) {
+                // ping every 10s — the client's heartbeat contract is 2.5× this window ([[graph-stream]]), so a
+                // silent-death gap is caught inside one client watchdog interval, and idle proxies never time out.
+                await stream.sleep(10000);
+                if (aborted)
+                    break;
+                await stream.writeSSE({ event: 'ping', data: 'x' });
+            }
+        }
+        finally {
+            unsub();
+        }
+    });
+}