spexcode 0.4.0 → 0.4.3

package/spec-cli/src/git.ts

@@ -443,7 +443,7 @@ function parseNameStatus(out: string): { code: string; from: string; to: string
   return rows
 }
 
-export type ReviewDiffFile = { path: string; status: string; additions: number; deletions: number }
+export type ReviewDiffFile = { path: string; oldPath?: string; status: string; additions: number; deletions: number }
 const DIFF_STATUS: Record<string, string> = { A: 'added', M: 'modified', D: 'deleted', R: 'renamed', C: 'copied', T: 'type-changed' }
 export async function mergeBaseDiff(wtPath: string, mainRef = 'main'): Promise<ReviewDiffFile[]> {
   const run = (args: string[]) => gitA(['-C', wtPath, '-c', 'core.quotePath=false', ...args])
@@ -453,14 +453,21 @@ export async function mergeBaseDiff(wtPath: string, mainRef = 'main'): Promise<R
     run(['diff', '--numstat', '-M', `${base}..HEAD`]),
     run(['diff', '--name-status', '-M', `${base}..HEAD`]),
   ])
-  const status = new Map<string, string>()
-  for (const r of parseNameStatus(statusOut)) status.set(r.to, DIFF_STATUS[r.code] ?? r.code)
+  const status = new Map<string, { status: string; from: string }>()
+  for (const r of parseNameStatus(statusOut)) status.set(r.to, { status: DIFF_STATUS[r.code] ?? r.code, from: r.from })
   const files: ReviewDiffFile[] = []
   for (const line of numstatOut.split('\n')) {
     const m = line.match(/^(-|\d+)\t(-|\d+)\t(.+)$/)
     if (!m) continue
-    const { to } = parseStatPath(m[3])   // numstat renders a rename as `{old => new}`; keep the final path
-    files.push({ path: to, status: status.get(to) ?? 'modified', additions: m[1] === '-' ? 0 : +m[1], deletions: m[2] === '-' ? 0 : +m[2] })
+    const { from, to } = parseStatPath(m[3])
+    const detail = status.get(to)
+    files.push({
+      path: to,
+      ...(from !== to ? { oldPath: detail?.from ?? from } : {}),
+      status: detail?.status ?? 'modified',
+      additions: m[1] === '-' ? 0 : +m[1],
+      deletions: m[2] === '-' ? 0 : +m[2],
+    })
   }
   return files
 }

package/spec-cli/src/graph.ts

@@ -1,6 +1,5 @@
-import { basename } from 'path'
 import { loadSpecs, deriveStatus } from './specs.js'
-import { resolveLayout, readConfig } from './layout.js'
+import { resolveLayout } from './layout.js'
 import { listSessions } from './sessions.js'
 import { repoRoot, driftIndex, historyIndex } from './git.js'
 import { residentForgeState } from '../../spec-forge/src/resident.js'
@@ -8,6 +7,11 @@ import { resolveForgeHost } from '../../spec-forge/src/drivers.js'
 import { mergedIssues } from './issues.js'
 import { evalContext, evalTimeline } from '../../spec-eval/src/evaltab.js'
 import { evalNodesAsync } from '../../spec-eval/src/scenarios.js'
+import { resolveProjectIdentity } from './project-identity.js'
+import { sessionEvalProjections } from '../../spec-eval/src/sessioneval.js'
+import { publishReviewSnapshot } from './reviewSnapshot.js'
+// @ts-expect-error Shared browser/server scoring keeps graph summary counts aligned with review rows.
+import { evalReviewState } from '../../spec-dashboard/src/reviewFilters.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 {
@@ -20,20 +24,22 @@ function resolveParent(path: string, byDir: Record<string, string>): string | nu
   return null
 }
 
-// the board's eval summary ([[graph-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.
+// The server-only review snapshot keeps latest readings verbatim. Graph JSON receives only counts.
 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 ([[graph-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 function nodeEvalSummary(scenarios: { name: string }[], readings: any[]) {
+  type State = 'pass' | 'fail' | 'stalePass' | 'staleFail' | 'empty'
+  const latest = new Map(latestPerScenario(readings).map((reading) => [reading.scenario, reading]))
+  const summary = { total: scenarios.length, pass: 0, fail: 0, stalePass: 0, staleFail: 0, empty: 0 }
+  for (const scenario of scenarios) {
+    const reading = latest.get(scenario.name)
+    const state = (reading ? evalReviewState(reading) : 'empty') as State
+    summary[state]++
+  }
+  return summary
 }
 
 export async function buildBoard() {
@@ -104,10 +110,8 @@ export async function buildBoard() {
     }),
     ...Object.values(ghostById),
   ]
-  // 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.
+  // Reconcile Issues once. Full rows stay in the server-only review snapshot; graph nodes get counts and
+  // open identity only, enough for tile/stat/tree glances without reconstructing the list.
   const isOpen = (i: { status: string }) => i.status === 'open'
   const merged = mergedIssues({ host: resolveForgeHost(), state: residentForgeState() }, nodes.map((n) => n.id))
   // ONE board-level freshness stamp over EVERY issue thread (noded or nodeless, both stores):
@@ -128,37 +132,44 @@ export async function buildBoard() {
   for (const n of nodes) {
     const issues = issuesByNode[n.id]
     if (!issues || !issues.length) continue
-    n.issues = issues
-      .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
+    const open = issues.filter(isOpen)
+    n.reviewSummary = {
+      ...(n.reviewSummary || {}),
+      issues: { open: open.length, closed: issues.length - open.length, openIds: open.map((issue) => issue.id) },
+    }
   }
 
-  // fold each measurable node's eval state onto it — as the LEAN summary ([[graph-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).
+  // Reconcile current Evals once. Latest rows/declarations stay server-only for paged review; graph nodes
+  // receive the explicit per-state count projection and nothing row-shaped.
   // evalContext reuses the specs + driftIndex above; evalTimeline short-circuits non-measurable nodes. The
   // eval-file walk rides fs/promises ([[graph-cache]]) so it yields the event loop instead of stalling /health.
   const ynodes = await evalNodesAsync(root)
   const ectx = await evalContext(root, specs, idx, hidx, undefined, ynodes)
-  await Promise.all(nodes.map(async (n) => {
+  const evalReviewNodes = (await Promise.all(nodes.map(async (n) => {
     const tl = await evalTimeline(n.id, ectx)
-    if (tl.hasEvalFile) { n.evals = latestPerScenario(tl.readings); n.scenarios = slimScenarios(tl.scenarios) }
-  }))
+    if (!tl.hasEvalFile) return null
+    const latest = latestPerScenario(tl.readings)
+    n.reviewSummary = { ...(n.reviewSummary || {}), evals: nodeEvalSummary(tl.scenarios, latest) }
+    return { id: n.id, hue: n.hue, scenarios: tl.scenarios, evals: latest, readings: tl.readings }
+  }))).filter((node): node is NonNullable<typeof node> => node !== null)
+
+  publishReviewSnapshot({ issues: merged, evalNodes: evalReviewNodes })
 
   const opsByPath: Record<string, any[]> = {}
   opWts.forEach((w) => { opsByPath[w.path] = w.ops })
-  const sess = sessions.map((s) => ({ ...s, source: s.path, ops: opsByPath[s.path] || [] }))
+  const evalProjections = sessionEvalProjections(sessions)
+  const sess = sessions.map((s) => ({
+    ...s,
+    source: s.path,
+    ops: opsByPath[s.path] || [],
+    evalSummary: evalProjections.get(s.id),
+  }))
 
-  const dash = readConfig(root).dashboard
-  // project names the tab ([[tab-title]]); projectIcon is the tab favicon ([[tab-icon]]) — both ride the
-  // /api/graph poll so they re-derive from whichever backend the viewer reached. Empty icon → frontend default.
-  return { nodes, sessions: sess, project: dash?.title || basename(root), projectIcon: dash?.icon || '', issuesStamp }
+  // One resolved identity projection feeds title, favicon, rail, and catalog compatibility. A worktree
+  // backend reads the actual served tree's branch config and identity; endpoint registration uses the
+  // same git toplevel, so a linked worktree occupies its own host slot instead of replacing main.
+  const identity = resolveProjectIdentity(root, root)
+  return { nodes, sessions: sess, identity, issuesStamp }
 }
 
 // @@@ spliceSessions — the SESSIONS-ONLY producer ([[graph-cache]]). A session-scoped change (a lifecycle
@@ -172,8 +183,14 @@ export async function buildBoard() {
 // splice is byte-indistinguishable from a full rebuild whenever only session state moved.
 export async function spliceSessions(prev: Awaited<ReturnType<typeof buildBoard>>): Promise<Awaited<ReturnType<typeof buildBoard>>> {
   const sessions = await listSessions()
+  const evalProjections = sessionEvalProjections(sessions)
   const opsByPath: Record<string, any[]> = {}
   for (const s of prev.sessions) opsByPath[s.source] = s.ops
-  const sess = sessions.map((s) => ({ ...s, source: s.path, ops: opsByPath[s.path] || [] }))
+  const sess = sessions.map((s) => ({
+    ...s,
+    source: s.path,
+    ops: opsByPath[s.path] || [],
+    evalSummary: evalProjections.get(s.id),
+  }))
   return { ...prev, sessions: sess }
 }

package/spec-cli/src/graphStream.ts

@@ -1,11 +1,17 @@
 import { streamSSE } from 'hono/streaming'
 import type { Context } from 'hono'
-import { watch, mkdirSync, readdirSync, readFileSync, existsSync, type FSWatcher } from 'node:fs'
+import { watch, mkdirSync, readdirSync, readFileSync, 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'
+import {
+  holdSessionEvalProjectionObserver,
+  invalidateSessionEvalProjections,
+  releaseSessionEvalProjectionObserver,
+  setSessionEvalProjectionNotify,
+} from '../../spec-eval/src/sessioneval.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
@@ -21,7 +27,7 @@ import { unitize, tagOf, diffUnits, type Units } from './graphDelta.js'
 // 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';
+// worktree REGISTRY (+ each live worktree root and gitdir index) — dirty source/spec/sidecar/rename/stage → '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
@@ -29,6 +35,7 @@ import { unitize, tagOf, diffUnits, type Units } from './graphDelta.js'
 // without delta subscribers keeps its zero-build behavior: sources just fan out `graph-changed`.
 
 type Scope = 'sessions' | 'full'
+type EvalTarget = 'all' | { id?: string; path?: string }
 type Notify = () => void
 type Frame = { event: string; data: string }
 type DeltaSend = (frame: Frame) => void
@@ -94,9 +101,12 @@ async function rebuildAndBroadcast(): Promise<void> {
         // 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
+      // 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 }
       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
@@ -117,7 +127,10 @@ async function rebuildAndBroadcast(): Promise<void> {
 // 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 {
+function fireChanged(scope: Scope = 'full', evalTarget?: EvalTarget): void {
+  // 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 (evalTarget) invalidateSessionEvalProjections(evalTarget)
   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
@@ -143,7 +156,11 @@ function fireChanged(scope: Scope = 'full'): void {
 // 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)
+export const notifyBoardChanged = (scope: Scope = 'full'): void =>
+  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'))
 
 // ---- event source 1: the session store (lifecycle status writes) → 'sessions' ----
 let watcher: FSWatcher | null = null
@@ -157,57 +174,268 @@ function ensureWatcher(): void {
 
 // ---- 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.
+// for packed-refs rewrites and HEAD flips. Ordinary graph units still have the patrol; eval projections are
+// observer-held across a failure and only become current after a replacement watch authorizes a rescan.
 let refsWatchers: FSWatcher[] | null = null
-function ensureRefsWatcher(): void {
+const REFS_OBSERVER = 'graph:refs'
+
+export function watchSessionEvalRefs(
+  common: string,
+  onInput: () => void,
+  onFailure: () => void,
+): FSWatcher[] {
+  const attached: FSWatcher[] = []
+  let failed = false
+  const close = () => {
+    for (const watcher of attached) { try { watcher.close() } catch { /* already gone */ } }
+  }
+  const fail = () => {
+    if (failed) return
+    failed = true
+    close()
+    onFailure()
+  }
+  try {
+    attached.push(watch(join(common, 'refs'), { recursive: true }, (_event, file) => {
+      if (file == null) { fail(); return }
+      onInput()
+    }))
+    attached.push(watch(common, (_event, file) => {
+      if (file == null) { fail(); return }
+      if (file === 'packed-refs' || file === 'HEAD') onInput()
+    }))
+    for (const watcher of attached) watcher.on('error', fail)
+    return attached
+  } catch (error) {
+    close()
+    throw error
+  }
+}
+
+function refsWatcherFailed(): void {
+  refsWatchers = null
+  if (holdSessionEvalProjectionObserver(REFS_OBSERVER, 'all')) fireChanged('full')
+  setImmediate(() => ensureRefsWatcher(false))
+}
+
+function ensureRefsWatcher(retry = true): void {
   if (refsWatchers) return
-  if (isDisabled('refs')) return
-  refsWatchers = []
+  if (isDisabled('refs')) {
+    if (holdSessionEvalProjectionObserver(REFS_OBSERVER, 'all')) fireChanged('full')
+    return
+  }
   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 */ }
+    refsWatchers = watchSessionEvalRefs(common, () => fireChanged('full', 'all'), refsWatcherFailed)
+    if (releaseSessionEvalProjectionObserver(REFS_OBSERVER)) fireChanged('full')
+  } catch {
+    refsWatchers = null
+    if (holdSessionEvalProjectionObserver(REFS_OBSERVER, 'all')) fireChanged('full')
+    if (retry) setImmediate(() => ensureRefsWatcher(false))
+  }
 }
 
-// ---- 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.
+// ---- 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 registry row
+// therefore owns a recursive working-root watcher plus a non-recursive watcher on git's worktree metadata
+// dir (`index`). A delivered event advances that worktree's eval generation before the graph rebuild.
 let registryWatcher: FSWatcher | null = null
-const specWatchers = new Map<string, FSWatcher>()   // registry entry name → recursive watch on <worktree>/.spec
+type WorktreeWatch = { path: string; root: FSWatcher; index: FSWatcher }
+const worktreeWatchers = new Map<string, WorktreeWatch>()
+const worktreeRetryAttempted = new Set<string>()
+const worktreeRetryCount = new Map<string, number>()
+const worktreeObserver = (name: string): string => `graph:worktree:${name}`
+
+export function scheduleWorktreeResubscribe(
+  name: string,
+  attempted: Set<string>,
+  retry: () => void,
+  delayMs = 0,
+): boolean {
+  if (attempted.has(name)) return false
+  attempted.add(name)
+  const timer = setTimeout(() => {
+    attempted.delete(name)
+    retry()
+  }, delayMs)
+  timer.unref?.()
+  return true
+}
+
+function scheduleWorktreeRetry(name: string): boolean {
+  if (worktreeRetryAttempted.has(name)) return false
+  const attempt = (worktreeRetryCount.get(name) ?? 0) + 1
+  worktreeRetryCount.set(name, attempt)
+  const delayMs = Math.min(1_000, 25 * (2 ** Math.min(attempt - 1, 5)))
+  return scheduleWorktreeResubscribe(name, worktreeRetryAttempted, reconcileWorktrees, delayMs)
+}
+
+const ignoredWorktreePath = (file: string): boolean =>
+  file === '.git' || file.startsWith('.git/') || file === 'node_modules' || file.startsWith('node_modules/')
+
+export function watchSessionEvalWorktree(
+  wtPath: string,
+  gitDir: string,
+  onInput: () => void,
+  onFailure: () => void,
+): { root: FSWatcher; index: FSWatcher } {
+  let failed = false
+  let root: FSWatcher | null = null
+  let index: FSWatcher | null = null
+  const fail = () => {
+    if (failed) return
+    failed = true
+    try { root?.close() } catch { /* already gone */ }
+    try { index?.close() } catch { /* already gone */ }
+    onFailure()
+  }
+  try {
+    root = watch(wtPath, { recursive: true }, (_event, filename) => {
+      if (filename == null) { fail(); return }
+      const file = String(filename)
+      if (!ignoredWorktreePath(file)) onInput()
+    })
+    index = watch(gitDir, (_event, filename) => {
+      if (filename == null) { fail(); return }
+      if (String(filename) === 'index') onInput()
+    })
+    root.on('error', fail)
+    index.on('error', fail)
+    return { root, index }
+  } catch (error) {
+    fail()
+    throw error
+  }
+}
+
+function dropWorktreeWatcher(name: string): WorktreeWatch | null {
+  const row = worktreeWatchers.get(name)
+  if (!row) return null
+  worktreeWatchers.delete(name)
+  try { row.root.close() } catch { /* already gone */ }
+  try { row.index.close() } catch { /* already gone */ }
+  return row
+}
+
+function watcherFailed(name: string, path: string): void {
+  // Failure/overflow has no trustworthy path. Keep last-known, mark the target updating, and immediately
+  // resubscribe; the authorized summary build is the one authoritative rescan, never a periodic sweep.
+  dropWorktreeWatcher(name)
+  if (holdSessionEvalProjectionObserver(worktreeObserver(name), { path })) fireChanged('full')
+  scheduleWorktreeRetry(name)
+}
+
 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>()
+  let released = false
   for (const e of ents) {
     if (!e.isDirectory()) continue
     live.add(e.name)
-    if (specWatchers.has(e.name)) continue
+    if (worktreeWatchers.has(e.name) || worktreeRetryAttempted.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 */ }
+      const { root, index } = watchSessionEvalWorktree(
+        wtPath,
+        join(dir, e.name),
+        () => fireChanged('full', { path: wtPath }),
+        () => watcherFailed(e.name, wtPath),
+      )
+      const row = { path: wtPath, root, index }
+      worktreeWatchers.set(e.name, row)
+      worktreeRetryAttempted.delete(e.name)
+      worktreeRetryCount.delete(e.name)
+      // 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 {
+      // An attach failure is observable: mark unknown/full now. The next registry change or explicit graph
+      // source setup retries; no patrol is allowed to call the eval projection current.
+      let path: string | null = null
+      try { path = dirname(readFileSync(join(dir, e.name, 'gitdir'), 'utf8').trim()) } catch { /* broken row */ }
+      if (holdSessionEvalProjectionObserver(worktreeObserver(e.name), path ? { path } : 'all')) fireChanged('full')
+      scheduleWorktreeRetry(e.name)
+    }
+  }
+  for (const name of worktreeWatchers.keys()) if (!live.has(name)) {
+    dropWorktreeWatcher(name)
+    released = releaseSessionEvalProjectionObserver(worktreeObserver(name)) || released
+  }
+  for (const name of worktreeRetryCount.keys()) if (!live.has(name)) {
+    worktreeRetryAttempted.delete(name)
+    worktreeRetryCount.delete(name)
+    released = releaseSessionEvalProjectionObserver(worktreeObserver(name)) || released
   }
-  for (const [name, w] of [...specWatchers]) if (!live.has(name)) { try { w.close() } catch { /* already gone */ } ; specWatchers.delete(name) }
+  if (released) fireChanged('full')
+}
+const WORKTREE_REGISTRY_OBSERVER = 'graph:worktree-registry'
+
+export function watchSessionEvalRegistry(
+  dir: string,
+  onInput: () => void,
+  onFailure: () => void,
+): FSWatcher {
+  let watcher: FSWatcher | null = null
+  let failed = false
+  const fail = () => {
+    if (failed) return
+    failed = true
+    try { watcher?.close() } catch { /* already gone */ }
+    onFailure()
+  }
+  try {
+    watcher = watch(dir, (_event, file) => {
+      if (file == null) { fail(); return }
+      onInput()
+    })
+    watcher.on('error', fail)
+    return watcher
+  } catch (error) {
+    try { watcher?.close() } catch { /* partial attach */ }
+    throw error
+  }
+}
+
+function registryWatcherFailed(): void {
+  registryWatcher = null
+  if (holdSessionEvalProjectionObserver(WORKTREE_REGISTRY_OBSERVER, 'all')) fireChanged('full')
+  setImmediate(() => ensureWorktreeRegistry(false))
 }
-function ensureWorktreeRegistry(): void {
-  if (registryWatcher) return
-  if (isDisabled('worktrees')) return
+
+function ensureWorktreeRegistry(retry = true): void {
+  if (registryWatcher) { reconcileWorktrees(); return }
+  if (isDisabled('worktrees')) {
+    if (holdSessionEvalProjectionObserver(WORKTREE_REGISTRY_OBSERVER, 'all')) fireChanged('full')
+    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 }
+    registryWatcher = watchSessionEvalRegistry(dir, () => {
+      reconcileWorktrees()
+      fireChanged('full', 'all')
+    }, registryWatcherFailed)
+  } catch {
+    registryWatcher = null
+    if (holdSessionEvalProjectionObserver(WORKTREE_REGISTRY_OBSERVER, 'all')) fireChanged('full')
+    if (retry) setImmediate(() => ensureWorktreeRegistry(false))
+  }
   reconcileWorktrees()   // attach for the worktrees that already exist when the source starts
+  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.
+export function ensureBoardFileWatchers(): void {
+  ensureWatcher()
+  ensureRefsWatcher()
+  ensureWorktreeRegistry()
 }
 
 // ---- event source 4: the two-tier tmux-derived pollers (liveness + activity — never a file write) → 'sessions' ----
@@ -245,6 +473,11 @@ function ensureColdTick(): void {
 }
 
 function stopSourcesIfIdle(): void {
+  // 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 }
   if (plainSubs.size + deltaSubs.size > 0) return
   if (hotPoller) { clearInterval(hotPoller); hotPoller = null; lastHot = '' }
   if (warmPoller) { clearInterval(warmPoller); warmPoller = null; lastWarm = '' }
@@ -257,9 +490,7 @@ function stopSourcesIfIdle(): void {
 // chain re-anchors with no client-side repair logic.
 export function boardStream(c: Context) {
   const delta = c.req.query('mode') === 'delta'
-  ensureWatcher()
-  ensureRefsWatcher()
-  ensureWorktreeRegistry()
+  ensureBoardFileWatchers()
   return streamSSE(c, async (stream) => {
     let aborted = false
     const send: DeltaSend = (frame) => { void stream.writeSSE(frame).catch(() => {}) }