spexcode 0.2.8 → 0.4.0

package/spec-cli/src/{boardCache.ts → graphCache.ts}

@@ -1,13 +1,13 @@
-import { buildBoard } from './board.js'
+import { buildBoard, spliceSessions } from './graph.js'
 
-// @@@ board-cache — single-flight + cache for the hot /api/board build ([[board-lean]]). Assembling the
+// @@@ graph-cache — single-flight + cache for the hot /api/graph build ([[graph-lean]]). Assembling the
 // board is expensive (two full-history git-log walks cold, a full `.spec` fs walk every build), so the
 // route MUST NOT rebuild per request: index.ts once ran `buildBoard()` inline on EVERY poll, so a normal
 // dashboard's overlapping polls (+ SSE-triggered refetches) multiplied into N simultaneous builds and
 // starved the event loop — one real user could wedge the backend. Here ONE build is shared by all
 // concurrent callers (a promise memo — this IS the max-concurrent-builds cap: at most one runs) and its
 // result is cached until a REAL change invalidates it. The cache is invalidated by the SAME freshness
-// signals [[board-stream]] already watches (session-store writes, git-ref moves, the cold tick), via
+// signals [[graph-stream]] already watches (session-store writes, git-ref moves, the cold tick), via
 // invalidateBoard(). So a poll storm costs ONE build, a quiet stretch costs ZERO, and the SSE rebuild and
 // the route share the very same in-flight build.
 
@@ -22,7 +22,7 @@ const BUDGET_MS = Number(process.env.SPEXCODE_BOARD_BUDGET_MS || 1500)
 // below, so a never-settling buildBoard() would pin the single-flight forever — every later read (even of a
 // perfectly good cached board) short-circuits into the pinned promise before `valid` is consulted,
 // invalidation can't help, no log ever fires, and only a restart cures it (the live wedge: hung git
-// children → /api/board 503 forever, silently). So the build races a generous watchdog that REJECTS loudly;
+// children → /api/graph 503 forever, silently). So the build races a generous watchdog that REJECTS loudly;
 // the rejection flows through the SAME finally → inflight clears → the next read retries fresh. Sitting at
 // the single-flight boundary, this one wall bounds every never-settle cause — including ones with no child
 // process at all (fs/promises under libuv threadpool starvation); git.ts's per-child timeouts merely make
@@ -30,53 +30,73 @@ const BUDGET_MS = Number(process.env.SPEXCODE_BOARD_BUDGET_MS || 1500)
 // fires on a genuine wedge.
 const BUILD_TIMEOUT_MS = Number(process.env.SPEXCODE_BOARD_BUILD_TIMEOUT_MS || 120000)
 
-let cached: Board | null = null   // last completed build; served while `valid`
+// the cache's staleness has a DOMAIN, not just a bit: a 'sessions' change (a lifecycle write, a
+// liveness/activity poll flip) touches only the session rows, so the next read can SPLICE fresh sessions
+// onto the still-valid node/meta units instead of re-walking git+`.spec`; a 'full' change (a ref move, a
+// worktree `.spec` edit, the cold-tick patrol) can reshape anything, so the next read does the whole
+// buildBoard(). 'none' = clean.
+type Scope = 'sessions' | 'full'
+let cached: Board | null = null   // last completed build; served while `dirty === 'none'`
 let cachedJson: string | null = null   // JSON.stringify(cached), serialized ONCE per build (see getBoardJson)
-let valid = false
+let dirty: Scope | 'none' = 'full'   // no cached board yet → the first read builds fully
 let inflight: Promise<Board> | null = null
 let gen = 0                       // bumped on every invalidation — detects a change that landed MID-build
 
-// mark the cache stale. Called by every board-stream freshness source (see boardStream.fireChanged), so a
-// real change forces the next getBoard() to rebuild while a quiet poll storm keeps hitting the cache.
-export function invalidateBoard(): void {
+// mark the cache stale at a SCOPE. Called by every board-stream freshness source (see
+// boardStream.fireChanged), so a real change forces the next getBoard() to rebuild while a quiet poll storm
+// keeps hitting the cache. The scope only ESCALATES within a dirty window: none→sessions→full, and a
+// 'sessions' signal arriving while 'full' is already pending stays 'full' (a full rebuild subsumes a
+// sessions splice). cachedJson is dropped either way — a splice replaces the board object, so its old
+// serialization is stale regardless of scope.
+export function invalidateBoard(scope: Scope = 'full'): void {
   gen++
-  valid = false
+  if (scope === 'full' || dirty === 'full') dirty = 'full'
+  else dirty = 'sessions'
+  cachedJson = null
 }
 
 // the coalesced board read the route and the SSE rebuild both go through. A concurrent caller during a
 // build shares the in-flight promise; a caller after a completed build gets the cached value until the
-// next invalidation. A change that lands WHILE a build runs (gen moved) leaves the cache invalid so the
-// NEXT read rebuilds — the just-finished build still returns to its waiters (freshest available when they
-// asked), never cached as current. Mirrors [[board-stream]]'s building/dirty loop.
+// next invalidation. A 'sessions'-scoped dirty with a cached board takes the SPLICE path (spliceSessions —
+// fresh session rows onto the cached node/meta units) under the SAME single-flight promise + watchdog +
+// generation rules; anything else (dirty 'full', or no cache to splice onto) does a full buildBoard(). A
+// change that lands WHILE a build runs (gen moved) leaves the cache dirty so the NEXT read rebuilds — a
+// 'full' invalidation landing mid-splice leaves it dirty 'full' for the next read. The just-finished build
+// still returns to its waiters (freshest available when they asked), never cached as current. Mirrors
+// [[graph-stream]]'s building/dirty loop.
 export function getBoard(): Promise<Board> {
   if (inflight) return inflight
-  if (valid && cached) return Promise.resolve(cached)
+  if (dirty === 'none' && cached) return Promise.resolve(cached)
   const startGen = gen
+  const sessionsOnly = dirty === 'sessions' && cached !== null
+  const prev = cached
   const p = (async () => {
     const t0 = Date.now()
     let watchdog: ReturnType<typeof setTimeout> | undefined
     try {
       const board = await Promise.race([
-        buildBoard(),
+        sessionsOnly ? spliceSessions(prev!) : buildBoard(),
         // the race consumes the loser's eventual settlement, so an abandoned build that fails later
         // can't surface as an unhandled rejection; unref'd so a pending watchdog never holds a one-shot
         // CLI process open.
         new Promise<never>((_, reject) => {
           watchdog = setTimeout(() => {
-            console.warn(`spec-cli: /api/board build did not settle within ${BUILD_TIMEOUT_MS}ms — wedged build abandoned so the next read can retry`)
-            reject(new Error(`board build did not settle within ${BUILD_TIMEOUT_MS}ms`))
+            console.warn(`spec-cli: /api/graph build did not settle within ${BUILD_TIMEOUT_MS}ms — wedged build abandoned so the next read can retry`)
+            reject(new Error(`graph build did not settle within ${BUILD_TIMEOUT_MS}ms`))
           }, BUILD_TIMEOUT_MS)
           watchdog.unref?.()
         }),
       ])
       cached = board
       cachedJson = null   // invalidate the memoized serialization; re-serialized lazily on first read
-      valid = gen === startGen
+      // clean ONLY if no invalidation landed during the build; otherwise leave `dirty` at whatever scope
+      // those in-build invalidations escalated it to (a mid-splice 'full' stays 'full' for the next read).
+      if (gen === startGen) dirty = 'none'
       return board
     } finally {
       clearTimeout(watchdog)
       const ms = Date.now() - t0
-      if (ms > BUDGET_MS) console.warn(`spec-cli: /api/board build took ${ms}ms (budget ${BUDGET_MS}ms) — hot path is slow`)
+      if (ms > BUDGET_MS) console.warn(`spec-cli: /api/graph build took ${ms}ms (budget ${BUDGET_MS}ms) — hot path is slow`)
       inflight = null
     }
   })()
@@ -84,9 +104,9 @@ export function getBoard(): Promise<Board> {
   return p
 }
 
-// the SERIALIZED board for the /api/board route — JSON.stringify runs ONCE per build, not once per poll,
+// the SERIALIZED board for the /api/graph route — JSON.stringify runs ONCE per build, not once per poll,
 // so a poll storm of cache hits costs zero serialization CPU (only the etag hash for the 304 path). The SSE
-// path still takes the object (getBoard) because it decomposes it into delta units ([[board-delta]]).
+// path still takes the object (getBoard) because it decomposes it into delta units ([[graph-delta]]).
 export async function getBoardJson(): Promise<string> {
   const board = await getBoard()
   if (board === cached && cachedJson !== null) return cachedJson

package/spec-cli/src/{boardDelta.ts → graphDelta.ts}

@@ -1,7 +1,7 @@
 import { createHash } from 'node:crypto'
 
 // @@@ board-delta — the pure core of the board's incremental push: decompose a board snapshot into a keyed
-// UNIT MAP, tag it, and diff two unit maps into a minimal {set, del} patch. The transport ([[board-stream]])
+// UNIT MAP, tag it, and diff two unit maps into a minimal {set, del} patch. The transport ([[graph-stream]])
 // chains these patches over SSE (`from`/`to` tags) so a subscribed dashboard applies a few KB per change
 // instead of refetching the full ~600KB snapshot; the client-side mirror of apply/reconstruct lives in the
 // dashboard's data layer. Everything here is pure and synchronous — no fs, no git, no stream — so the

package/spec-cli/src/graphStream.ts

@@ -0,0 +1,288 @@
+import { streamSSE } from 'hono/streaming'
+import type { Context } from 'hono'
+import { watch, mkdirSync, readdirSync, readFileSync, existsSync, type FSWatcher } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { sessionsRoot, gitCommonDir } from './layout.js'
+import { hotSignature, warmSignature } from './sessions.js'
+import { getBoard, invalidateBoard } from './graphCache.js'
+import { unitize, tagOf, diffUnits, type Units } from './graphDelta.js'
+
+// @@@ board-stream — the board's freshness is PUSHED, not polled. A dashboard subscribes here ONCE; in
+// plain mode it gets a bare `graph-changed` and refetches /api/graph (the legacy protocol, kept verbatim
+// for old clients); in DELTA mode (`?mode=delta`) the server itself rebuilds on change and streams the
+// hash-chained patch ([[graph-delta]]): a `graph-full {to, graph}` on connect, then `graph-delta
+// {from, to, set, del}` per change — a few KB against the ~600KB snapshot, with a full-snapshot send
+// whenever the patch wouldn't win (bigger than the board, or the unit decomposition's id-uniqueness
+// precondition failed), so a delta subscriber is NEVER worse off than a full refetch.
+//
+// Every source carries the DOMAIN of the change it saw — 'sessions' (only the session rows moved) or 'full'
+// (anything could have) — and fireChanged funnels them into ONE debounced pipeline, escalating to the max
+// scope seen in the window so the cache can splice sessions instead of rebuilding whole ([[graph-cache]]).
+// Sources: (1) fs.watch on the per-user session store — every lifecycle transition lands as a
+// sessions/<id>/session.json write → 'sessions'; (2) fs.watch on the shared git dir's refs (+
+// packed-refs/HEAD) — a commit/merge moves a ref, reshaping the tree → 'full'; (3) fs.watch on the git
+// worktree REGISTRY (+ each live worktree's `.spec`) — an uncommitted spec edit in a linked worktree → 'full';
+// (4) two subscriber-gated pollers of the tmux-derived signatures ([[sessions]]) that never touch a file —
+// a 100ms HOT syscall poll and a 1s WARM tmux poll, both → 'sessions'; (5) a delta-gated ~15s cold-tick
+// PATROL that invalidates FULL, rebuilds and diffs — the self-heal authority that catches whatever every
+// leaf watcher missed (and is loud when it has to: see the repair accounting below) → 'full'. Plain mode
+// without delta subscribers keeps its zero-build behavior: sources just fan out `graph-changed`.
+
+type Scope = 'sessions' | 'full'
+type Notify = () => void
+type Frame = { event: string; data: string }
+type DeltaSend = (frame: Frame) => void
+const plainSubs = new Set<Notify>()
+const deltaSubs = new Set<DeltaSend>()
+let debounce: ReturnType<typeof setTimeout> | null = null
+let pendingScope: Scope | null = null   // the MAX change scope accumulated across the current debounce window
+const maxScope = (a: Scope | null, b: Scope): Scope => (a === 'full' || b === 'full' ? 'full' : 'sessions')
+
+// under SPEXCODE_BOARD_DEBUG=1, every broadcast logs its changed unit keys + trigger tags + build ms.
+const DEBUG = process.env.SPEXCODE_BOARD_DEBUG === '1'
+// 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<string>()
+
+// watchers a test can amputate to prove the patrol still heals the graph ([[graph-stream]]): a CSV of
+// store,refs,worktrees 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<string>()
+function isDisabled(name: string): boolean {
+  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: Units | null = null
+let lastTag = ''
+let lastFullFrame: Frame | null = null
+let building = false
+let dirty = false
+
+async function rebuildAndBroadcast(): Promise<void> {
+  if (building) { dirty = true; return }
+  building = true
+  try {
+    do {
+      dirty = false
+      let board: unknown
+      // 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).
+      const t0 = Date.now()
+      try { board = await getBoard() } catch { for (const n of [...plainSubs]) { try { n() } catch { /* swept on abort */ } }; continue }
+      const buildMs = Date.now() - t0
+      const boardJson = JSON.stringify(board)
+      const { units, ok } = unitize(board as Record<string, unknown>)
+      const tag = tagOf(units)
+      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: Frame = { 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 }
+      }
+      lastUnits = ok ? units : null
+      lastTag = tag
+      lastFullFrame = fullFrame
+      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.
+      const tags = [...triggerTags]
+      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`)
+      triggerTags.clear()
+    } 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 change SCOPE; the window accumulates the MAX ([[graph-cache]] escalates none→sessions→full).
+// 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: Scope = 'full'): void {
+  pendingScope = maxScope(pendingScope, scope)
+  // invalidate the route's board cache ([[graph-cache]]) on EVERY change signal, at the accumulated 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(pendingScope)
+  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
+    pendingScope = null
+    if (deltaSubs.size) void rebuildAndBroadcast()
+    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: Scope = 'full'): void => fireChanged(scope)
+
+// ---- event source 1: the session store (lifecycle status writes) → 'sessions' ----
+let watcher: FSWatcher | null = null
+function ensureWatcher(): void {
+  if (watcher) return
+  if (isDisabled('store')) return
+  const root = sessionsRoot()
+  try { mkdirSync(root, { recursive: true }) } catch { /* best-effort; the watch below still tries */ }
+  try { watcher = watch(root, { recursive: true }, () => fireChanged('sessions')) } catch { watcher = null }
+}
+
+// ---- event source 2: git refs (a commit/merge reshapes the tree the moment the ref moves) → 'full' ----
+// refs/ recursively for loose refs (heads, worktree branches), plus the common dir itself non-recursively
+// for packed-refs rewrites and HEAD flips. Best-effort like every source: no watch → the cold tick covers.
+let refsWatchers: FSWatcher[] | null = null
+function ensureRefsWatcher(): void {
+  if (refsWatchers) return
+  if (isDisabled('refs')) return
+  refsWatchers = []
+  try {
+    const common = gitCommonDir()
+    try { refsWatchers.push(watch(join(common, 'refs'), { recursive: true }, () => fireChanged('full'))) } catch { /* loose refs unwatched */ }
+    try { refsWatchers.push(watch(common, (_e, f) => { if (f === 'packed-refs' || f === 'HEAD') fireChanged('full') })) } catch { /* packed refs unwatched */ }
+  } catch { /* not a repo? the cold tick still covers */ }
+}
+
+// ---- event source 3: the git worktree REGISTRY + each live worktree's `.spec` → 'full' ----
+// An UNCOMMITTED spec edit in a linked worktree moves no ref and writes no session record, so neither
+// source 1 nor 2 sees it — only a watch on the worktree's own `.spec` does. The registry (`<git-common>/
+// worktrees/<name>/`) is the index of live worktrees; watching it non-recursively catches add/remove of a
+// worktree, and on each event we RECONCILE the per-worktree `.spec` watchers (resolving each entry's tree
+// via its `gitdir` file). Everything best-effort: a failed watch just leaves that path to the patrol.
+let registryWatcher: FSWatcher | null = null
+const specWatchers = new Map<string, FSWatcher>()   // registry entry name → recursive watch on <worktree>/.spec
+function reconcileWorktrees(): void {
+  let dir: string
+  try { dir = join(gitCommonDir(), 'worktrees') } catch { return }
+  let ents: import('node:fs').Dirent[] = []
+  try { ents = readdirSync(dir, { withFileTypes: true }) } catch { /* no worktrees registry yet */ }
+  const live = new Set<string>()
+  for (const e of ents) {
+    if (!e.isDirectory()) continue
+    live.add(e.name)
+    if (specWatchers.has(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 wtPath = dirname(readFileSync(join(dir, e.name, 'gitdir'), 'utf8').trim())
+      const specDir = join(wtPath, '.spec')
+      if (existsSync(specDir)) specWatchers.set(e.name, watch(specDir, { recursive: true }, () => fireChanged('full')))
+    } catch { /* best-effort; the patrol covers an unwatched worktree */ }
+  }
+  for (const [name, w] of [...specWatchers]) if (!live.has(name)) { try { w.close() } catch { /* already gone */ } ; specWatchers.delete(name) }
+}
+function ensureWorktreeRegistry(): void {
+  if (registryWatcher) return
+  if (isDisabled('worktrees')) return
+  try {
+    const dir = join(gitCommonDir(), 'worktrees')
+    try { mkdirSync(dir, { recursive: true }) } catch { /* best-effort */ }
+    // 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 = watch(dir, () => { reconcileWorktrees(); fireChanged('full') })
+  } catch { registryWatcher = null }
+  reconcileWorktrees()   // attach for the worktrees that already exist when the source starts
+}
+
+// ---- 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: ReturnType<typeof setInterval> | null = null
+let warmPoller: ReturnType<typeof setInterval> | null = null
+let lastHot = ''
+let lastWarm = ''
+function ensurePollers(): void {
+  if (!hotPoller) hotPoller = setInterval(() => {
+    void hotSignature().then((sig) => { if (sig !== lastHot) { lastHot = sig; 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. Rebuild+diff on a relaxed timer so what NO watcher saw (an uncommitted
+// worktree spec edit a registry watch missed, a forge issue refresh) still lands. It INVALIDATES FULL first
+// — otherwise getBoard() serves the stale cache and the patrol is a no-op (the real bug this fixes) — and
+// tags the window 'patrol' so the repair accounting can flag a change only it caught. Delta-gated: plain-only
+// clients keep their own client-side fallback, so without delta subscribers this must not burn builds.
+let coldTick: ReturnType<typeof setInterval> | null = null
+function ensureColdTick(): void {
+  if (coldTick) return
+  coldTick = setInterval(() => {
+    if (!deltaSubs.size) return
+    invalidateBoard('full')
+    triggerTags.add('patrol')
+    void rebuildAndBroadcast()
+  }, 15000)
+}
+
+function stopSourcesIfIdle(): void {
+  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 function boardStream(c: Context) {
+  const delta = c.req.query('mode') === 'delta'
+  ensureWatcher()
+  ensureRefsWatcher()
+  ensureWorktreeRegistry()
+  return streamSSE(c, async (stream) => {
+    let aborted = false
+    const send: DeltaSend = (frame) => { void stream.writeSSE(frame).catch(() => {}) }
+    const notify: Notify = () => { void stream.writeSSE({ event: 'graph-changed', data: 'x' }).catch(() => {}) }
+    if (delta) { deltaSubs.add(send); ensureColdTick() } else { plainSubs.add(notify) }
+    ensurePollers()
+    const unsub = (): void => { 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() }
+  })
+}