spexcode 0.1.6 → 0.2.1

package/spec-cli/src/board.ts

@@ -3,8 +3,10 @@ import { loadSpecs, deriveStatus } from './specs.js'
 import { resolveLayout, readConfig } from './layout.js'
 import { listSessions } from './sessions.js'
 import { repoRoot, driftIndex, historyIndex } from './git.js'
-import { residentForgeView } from '../../spec-forge/src/resident.js'
+import { residentForgeState } from '../../spec-forge/src/resident.js'
+import { mergedIssues } from './issues.js'
 import { evalContext, evalTimeline } from '../../spec-yatsu/src/evaltab.js'
+import { yatsuNodesAsync } from '../../spec-yatsu/src/yatsu.js'
 
 // a ghost (added) node's parent: the existing node whose directory is the longest prefix of the new one.
 function resolveParent(path: string, byDir: Record<string, string>): string | null {
@@ -17,6 +19,22 @@ function resolveParent(path: string, byDir: Record<string, string>): string | nu
   return null
 }
 
+// the board's eval summary ([[board-lean]]): the LATEST reading per scenario, each kept as the VERBATIM
+// reading object — a filter, never a projection. Consumers hang optional fields off a reading (the
+// annotator's timelineBlob rides only video readings), so dropping a field here is a SILENT downstream
+// degradation no error would surface; the field-preservation unit test pins this contract.
+export function latestPerScenario<T extends { scenario: string }>(readings: T[]): T[] {
+  const seen = new Set<string>()
+  return readings.filter((r) => !seen.has(r.scenario) && (seen.add(r.scenario), true))
+}
+
+// the board's scenario fold ([[board-lean]]): the declared set rides SLIM — {name, tags} is everything an
+// overview surface joins state onto (badge, stats, focus rows, search rows); the prose (description/
+// expected) and per-scenario code stay off the hot poll, carried by `/api/specs/lite` and `/api/specs/:id/evals`.
+export function slimScenarios(scenarios: { name: string; tags?: string[] }[]): { name: string; tags?: string[] }[] {
+  return scenarios.map((s) => ({ name: s.name, ...(s.tags?.length ? { tags: s.tags } : {}) }))
+}
+
 export async function buildBoard() {
   // all three sources are warm-cheap and independent, so the board inherits their speed for free: loadSpecs
   // REUSES the HEAD-keyed spec-history cache (the git-derived node data — see specs.ts/git.ts), resolveLayout
@@ -77,35 +95,46 @@ export async function buildBoard() {
   const nodes = [
     ...specs.map((n: any) => {
       const overlays = overlaysByNode[n.id] || []
-      return { ...n, overlays, status: deriveStatus({ version: n.version, drift: n.drift, hasOverlay: overlays.length > 0, hasCode: (n.code?.length ?? 0) > 0, fmStatus: n.fmStatus ?? undefined }) }
+      // `body` and its derivation `parts` are DROPPED from the board payload ([[board-lean]]): together ~56% of
+      // the bytes, and detail the graph overview never renders. The detail view fetches them per node from
+      // `/api/specs/:id/content` on open, and the search palette fetches the body corpus from `/api/specs/lite`
+      // once on open — both off this hot poll. `undefined` makes JSON.stringify omit the keys.
+      return { ...n, body: undefined, parts: undefined, overlays, status: deriveStatus({ version: n.version, drift: n.drift, hasOverlay: overlays.length > 0, hasCode: (n.code?.length ?? 0) > 0, fmStatus: n.fmStatus ?? undefined }) }
     }),
     ...Object.values(ghostById),
   ]
-  // fold spec-forge issues onto each node (full set → issues, open subset → openIssues, attached only when
-  // non-empty), non-blocking: residentForgeView never waits on `gh` and returns [] absent a forge, so a
-  // forge-less board is unchanged. Sorted open-first, newest number first.
-  const isOpen = (i: any) => (i.state || '').toLowerCase() === 'open'
-  const issuesByNode: Record<string, any[]> = {}
-  for (const link of residentForgeView(nodes.map((n) => n.id))) {
-    issuesByNode[link.node] = link.issues
-      .map((i) => ({ number: i.number, state: i.state, title: i.title, url: i.url }))
-      .sort((a, b) => Number(isOpen(b)) - Number(isOpen(a)) || b.number - a.number)
-  }
+  // fold each node's issues onto it through the unified Issue port ([[issues]]): the resident forge slice
+  // AND the local store's threads, one merged store-tagged list (full set → issues, open subset →
+  // openIssues, attached only when non-empty). Non-blocking: residentForgeState never waits on `gh` and is
+  // empty absent a forge, so the fold then carries the local slice alone. Sorted open-first, newest first.
+  const isOpen = (i: { status: string }) => i.status === 'open'
+  const issuesByNode: Record<string, ReturnType<typeof mergedIssues>> = {}
+  for (const issue of mergedIssues({ host: 'github', state: residentForgeState() }, nodes.map((n) => n.id)))
+    for (const nid of issue.nodes) (issuesByNode[nid] ??= []).push(issue)
   for (const n of nodes) {
     const issues = issuesByNode[n.id]
     if (!issues || !issues.length) continue
     n.issues = issues
-    const open = issues.filter(isOpen)
+      .sort((a, b) => Number(isOpen(b)) - Number(isOpen(a)) || b.created.localeCompare(a.created))
+      .map((i) => ({ id: i.id, store: i.store, status: i.status, concern: i.concern, url: i.url }))
+    const open = n.issues.filter(isOpen)
     if (open.length) n.openIssues = open
   }
 
-  // fold each yatsu node's eval timeline onto it, riding this one board poll: `evals` (readings, newest-first)
-  // and `scenarios` (the declared set) attached only when the node declares scenarios. evalContext reuses the
-  // specs + driftIndex above; evalTimeline short-circuits non-yatsu nodes so the poll stays fast.
-  const ectx = evalContext(root, specs, idx, hidx)
+  // fold each yatsu node's eval state onto it — as the LEAN summary ([[board-lean]]): `evals` carries only
+  // the LATEST reading per scenario (newest-first), which is all any overview surface consumes (the score
+  // badge, stats, search all reduce to latest-per-scenario anyway); the full timeline stays off the board
+  // and is lazy-loaded by the eval tab from `/api/specs/:id/evals`. `scenarios` (the declared set) rides
+  // SLIM — {name, tags} only, the fields every overview surface joins state onto — with its prose
+  // (description/expected) and per-scenario code off the hot poll: they ride the `/api/specs/lite` corpus
+  // (search palette, focus-panel preview) and the `/api/specs/:id/evals` timeline (eval tab).
+  // evalContext reuses the specs + driftIndex above; evalTimeline short-circuits non-yatsu nodes. The
+  // yatsu walk rides fs/promises ([[board-cache]]) so it yields the event loop instead of stalling /health.
+  const ynodes = await yatsuNodesAsync(root)
+  const ectx = await evalContext(root, specs, idx, hidx, undefined, ynodes)
   await Promise.all(nodes.map(async (n) => {
     const tl = await evalTimeline(n.id, ectx)
-    if (tl.hasYatsu) { n.evals = tl.readings; n.scenarios = tl.scenarios }
+    if (tl.hasYatsu) { n.evals = latestPerScenario(tl.readings); n.scenarios = slimScenarios(tl.scenarios) }
   }))
 
   const opsByPath: Record<string, any[]> = {}

package/spec-cli/src/boardCache.ts

@@ -0,0 +1,70 @@
+import { buildBoard } from './board.js'
+
+// @@@ board-cache — single-flight + cache for the hot /api/board build ([[board-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
+// 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.
+
+export type Board = Awaited<ReturnType<typeof buildBoard>>
+
+// a build slower than this is LOGGED, never silently tolerated — the fail-loud regression alarm. Sized
+// above a warm build (~sub-second once the fs walks yield) but below the cold two-walk first build, so a
+// genuinely-degraded hot path shouts while an ordinary cold start stays quiet-ish.
+const BUDGET_MS = Number(process.env.SPEXCODE_BOARD_BUDGET_MS || 1500)
+
+let cached: Board | null = null   // last completed build; served while `valid`
+let cachedJson: string | null = null   // JSON.stringify(cached), serialized ONCE per build (see getBoardJson)
+let valid = false
+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 {
+  gen++
+  valid = false
+}
+
+// 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.
+export function getBoard(): Promise<Board> {
+  if (inflight) return inflight
+  if (valid && cached) return Promise.resolve(cached)
+  const startGen = gen
+  const p = (async () => {
+    const t0 = Date.now()
+    try {
+      const board = await buildBoard()
+      cached = board
+      cachedJson = null   // invalidate the memoized serialization; re-serialized lazily on first read
+      valid = gen === startGen
+      return board
+    } finally {
+      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`)
+      inflight = null
+    }
+  })()
+  inflight = p
+  return p
+}
+
+// the SERIALIZED board for the /api/board 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]]).
+export async function getBoardJson(): Promise<string> {
+  const board = await getBoard()
+  if (board === cached && cachedJson !== null) return cachedJson
+  const json = JSON.stringify(board)
+  if (board === cached) cachedJson = json   // memoize only the CURRENT build's serialization
+  return json
+}

package/spec-cli/src/boardDelta.ts

@@ -0,0 +1,90 @@
+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]])
+// 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
+// equivalence argument (see the spec node's equivalence.md) is checkable by the property tests alone.
+//
+// Unit keys: `node:<id>` (one spec node), `sess:<id>` (one session row), `nodes#order` / `sess#order`
+// (id sequences, preserving array order), `meta` (every other top-level field as one small object).
+// Precondition P: node ids and session ids are collision-free. unitize REPORTS P (`ok`) rather than
+// assuming it — on a violation the transport falls back to full-snapshot sends, so a delta is only ever
+// chained between snapshots where the decomposition is a real bijection.
+
+export type Units = Map<string, { j: string; v: unknown }>
+export type Delta = { from: string; to: string; set: Record<string, unknown>; del: string[] }
+
+type Boardish = { nodes?: unknown; sessions?: unknown; [k: string]: unknown }
+
+// decompose a board into units. `ok` = the bijection precondition held (arrays are arrays, ids unique &
+// non-empty); when false the map is still returned (usable for tagging) but must not seed a delta chain.
+export function unitize(board: Boardish): { units: Units; ok: boolean } {
+  const units: Units = new Map()
+  let ok = true
+  const keyed = (arr: unknown, prefix: string, orderKey: string): void => {
+    const list = Array.isArray(arr) ? arr : (ok = false, [])
+    const order: string[] = []
+    for (const item of list) {
+      const id = (item as { id?: unknown })?.id
+      if (typeof id !== 'string' || !id || units.has(`${prefix}${id}`)) { ok = false; continue }
+      units.set(`${prefix}${id}`, { j: JSON.stringify(item), v: item })
+      order.push(id)
+    }
+    units.set(orderKey, { j: JSON.stringify(order), v: order })
+  }
+  const { nodes, sessions, ...meta } = board
+  keyed(nodes, 'node:', 'nodes#order')
+  keyed(sessions, 'sess:', 'sess#order')
+  units.set('meta', { j: JSON.stringify(meta), v: meta })
+  return { units, ok }
+}
+
+// the snapshot tag: a digest over every unit's key + content hash, order-independent (keys sorted). Two
+// builds serializing equal content get equal tags; JSON.stringify equality is conservative (equal strings ⇒
+// equal values; a key-order difference at worst re-sends an unchanged unit, never misses a changed one).
+export function tagOf(units: Units): string {
+  const h = createHash('sha1')
+  for (const key of [...units.keys()].sort()) {
+    const u = units.get(key)!
+    h.update(key).update('\0').update(u.j).update('\0')
+  }
+  return h.digest('hex')
+}
+
+// diff two unit maps into the minimal patch: units whose serialized content moved land in `set` (with the
+// NEW value), units that vanished land in `del`. apply(prev, diff(prev, next)) = next — the round-trip
+// lemma the property tests pin down.
+export function diffUnits(prev: Units, next: Units): { set: Record<string, unknown>; del: string[] } {
+  const set: Record<string, unknown> = {}
+  const del: string[] = []
+  for (const [key, u] of next) {
+    const p = prev.get(key)
+    if (!p || p.j !== u.j) set[key] = u.v
+  }
+  for (const key of prev.keys()) if (!next.has(key)) del.push(key)
+  return { set, del }
+}
+
+// apply a patch to a unit-value map — the exact algorithm the dashboard mirrors in data.js, kept here so
+// the round-trip property is provable against the real shape, not a paraphrase of it.
+export function applyDelta(values: Map<string, unknown>, d: Pick<Delta, 'set' | 'del'>): Map<string, unknown> {
+  const out = new Map(values)
+  for (const key of d.del) out.delete(key)
+  for (const [key, v] of Object.entries(d.set)) out.set(key, v)
+  return out
+}
+
+// reconstruct the board from unit values — R(U(B)) = B on the P-satisfying subspace (the client's render
+// input after every applied patch). Order rides the #order units, so array order survives the round trip.
+export function boardFromUnits(values: Map<string, unknown>): Boardish {
+  const pick = (prefix: string, orderKey: string): unknown[] => {
+    const order = (values.get(orderKey) as string[] | undefined) || []
+    return order.map((id) => values.get(`${prefix}${id}`))
+  }
+  const meta = (values.get('meta') as Record<string, unknown> | undefined) || {}
+  return { ...meta, nodes: pick('node:', 'nodes#order'), sessions: pick('sess:', 'sess#order') }
+}
+
+export const unitValues = (units: Units): Map<string, unknown> => new Map([...units].map(([k, u]) => [k, u.v]))

package/spec-cli/src/boardStream.ts

@@ -0,0 +1,178 @@
+import { streamSSE } from 'hono/streaming'
+import type { Context } from 'hono'
+import { watch, mkdirSync, type FSWatcher } from 'node:fs'
+import { join } from 'node:path'
+import { sessionsRoot, gitCommonDir } from './layout.js'
+import { sessionSignature } from './sessions.js'
+import { getBoard, invalidateBoard } from './boardCache.js'
+import { unitize, tagOf, diffUnits, type Units } from './boardDelta.js'
+
+// @@@ board-stream — the board's freshness is PUSHED, not polled. A dashboard subscribes here ONCE; in
+// plain mode it gets a bare `board-changed` and refetches /api/board (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 ([[board-delta]]): a `board-full {to, board}` on connect, then `board-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.
+//
+// Event sources, ALL funneled into one debounced pipeline: (1) fs.watch on the per-user session store —
+// every lifecycle transition lands as a sessions/<id>/session.json write; (2) fs.watch on the shared git
+// dir's refs (+ packed-refs/HEAD) — a commit or merge moves a ref, so tree reshapes push instead of
+// waiting out a poll; (3) a subscriber-gated ~2s poll of the CHEAP tmux session signature ([[sessions]])
+// for liveness/activity, which never touch a file; (4) a delta-gated ~15s cold tick that rebuilds and
+// diffs server-side, catching what no watcher sees (uncommitted worktree spec edits, forge issues) — ONE
+// rebuild per tick total, replacing every open dashboard's own 15s full refetch. Plain mode without delta
+// subscribers keeps its zero-build behavior: sources just fan out `board-changed`.
+
+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
+
+// ---- 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 ([[board-cache]]); fireChanged() already invalidated the
+      // cache, so this gets a fresh build (or joins one a concurrent poll already started).
+      try { board = await getBoard() } catch { for (const n of [...plainSubs]) { try { n() } catch { /* swept on abort */ } }; continue }
+      const boardJson = JSON.stringify(board)
+      const { units, ok } = unitize(board as Record<string, unknown>)
+      const tag = tagOf(units)
+      if (tag === lastTag) continue
+      const fullFrame: Frame = { event: 'board-full', data: `{"to":"${tag}","board":${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: 'board-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 */ } }
+    } while (dirty)
+  } finally { building = false }
+}
+
+// a merge/launch/close touches several record files at once; collapse the burst into ONE signal. 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(): void {
+  // invalidate the route's board cache ([[board-cache]]) on EVERY change signal, before the debounce guard
+  // — a plain-mode client that polls /api/board (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()
+  if (debounce) return
+  debounce = setTimeout(() => {
+    debounce = null
+    if (deltaSubs.size) void rebuildAndBroadcast()
+    else for (const notify of [...plainSubs]) { try { notify() } catch { /* swept on abort */ } }
+  }, 150)
+}
+
+// ---- event source 0: an EXPLICIT server-side nudge ----
+// for the one mutation the watchers structurally cannot see: /rename writes the worktree's `.session`
+// (the name's ONE home, outside the watched store — [[session-rename]]). The route calls this instead of
+// double-writing the name into the store: a notification problem gets a notification solution, never a
+// second data home. Same debounced funnel as every other source.
+export const notifyBoardChanged = (): void => fireChanged()
+
+// ---- event source 1: the session store (lifecycle status writes) ----
+let watcher: FSWatcher | null = null
+function ensureWatcher(): void {
+  if (watcher) return
+  const root = sessionsRoot()
+  try { mkdirSync(root, { recursive: true }) } catch { /* best-effort; the watch below still tries */ }
+  try { watcher = watch(root, { recursive: true }, () => fireChanged()) } catch { watcher = null }
+}
+
+// ---- event source 2: git refs (a commit/merge reshapes the tree the moment the ref moves) ----
+// 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
+  refsWatchers = []
+  try {
+    const common = gitCommonDir()
+    try { refsWatchers.push(watch(join(common, 'refs'), { recursive: true }, () => fireChanged())) } catch { /* loose refs unwatched */ }
+    try { refsWatchers.push(watch(common, (_e, f) => { if (f === 'packed-refs' || f === 'HEAD') fireChanged() })) } catch { /* packed refs unwatched */ }
+  } catch { /* not a repo? the cold tick still covers */ }
+}
+
+// ---- event source 3: the tmux-derived signature (liveness + activity — never a file write) ----
+let poller: ReturnType<typeof setInterval> | null = null
+let lastSig = ''
+function ensureLivePoll(): void {
+  if (poller) return
+  poller = setInterval(() => {
+    void sessionSignature().then((sig) => { if (sig !== lastSig) { lastSig = sig; fireChanged() } }).catch(() => {})
+  }, 2000)
+}
+
+// ---- event source 4: the cold tick — the server-side replacement for every client's slow fallback poll.
+// Rebuild+diff on a relaxed timer so what NO watcher sees (an uncommitted worktree spec edit, a forge
+// issue refresh) still lands; an unchanged tag broadcasts nothing. 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) void rebuildAndBroadcast() }, 15000)
+}
+
+function stopSourcesIfIdle(): void {
+  if (plainSubs.size + deltaSubs.size > 0) return
+  if (poller) { clearInterval(poller); poller = null; lastSig = '' }
+  if (coldTick) { clearInterval(coldTick); coldTick = null }
+}
+
+// GET /api/board/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 `board-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()
+  return streamSSE(c, async (stream) => {
+    let aborted = false
+    const send: DeltaSend = (frame) => { void stream.writeSSE(frame).catch(() => {}) }
+    const notify: Notify = () => { void stream.writeSSE({ event: 'board-changed', data: 'x' }).catch(() => {}) }
+    if (delta) { deltaSubs.add(send); ensureColdTick() } else { plainSubs.add(notify) }
+    ensureLivePoll()
+    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) {
+        await stream.sleep(25000)
+        if (aborted) break
+        await stream.writeSSE({ event: 'ping', data: 'x' })
+      }
+    } finally { unsub() }
+  })
+}