spexcode 0.5.1 → 0.5.3

package/spec-cli/src/graph.ts

@@ -4,7 +4,7 @@ import { listSessions } from './sessions.js'
 import { repoRoot, driftIndex, historyIndex } from './git.js'
 import { residentForgeState } from '../../spec-forge/src/resident.js'
 import { resolveForgeHost } from '../../spec-forge/src/drivers.js'
-import { mergedIssues } from './issues.js'
+import { boardThreads } 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'
@@ -42,6 +42,14 @@ export function nodeEvalSummary(scenarios: { name: string }[], readings: any[])
   return summary
 }
 
+// @@@ a shelved row carries no delta ([[archive]]) - the board has TWO producers (a full buildBoard and the
+// sessions-only spliceSessions), and shelving is a session-scoped write, so it takes the SPLICE path — which
+// reuses the previous board's ops by path. Skipping the delta only in layout's row builder would therefore be
+// invisible exactly when it fires: the splice would carry the stale ops forward forever. The rule belongs to
+// the row, not to one producer, so both decorate through this one function.
+const rowOps = (s: { path: string; archived?: boolean }, opsByPath: Record<string, any[]>): any[] =>
+  (s.archived ? [] : opsByPath[s.path] || [])
+
 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
@@ -113,20 +121,16 @@ export async function buildBoard() {
   // 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):
-  // open-count : thread-count : reply-count : latest-activity. Every thread write — open, reply, remark,
-  // resolve, retract, close — moves at least one component, so a store write ALWAYS moves board bytes:
-  // [[graph-delta]] suppresses no-change broadcasts, and without a moving byte an external write would
-  // stay invisible to viewers until the fallback poll ([[remark-substrate]] write-visibility). The per-node
-  // fold below stays [[graph-lean]]-slim (no reply payloads); this stamp is the freshness carrier.
-  const issuesStamp = [
-    merged.filter(isOpen).length,
-    merged.length,
-    merged.reduce((n, i) => n + i.replies.length, 0),
-    merged.flatMap((i) => [i.created, ...i.replies.flatMap((r) => [r.at, r.resolvedAt ?? ''])]).reduce((a, b) => (b > a ? b : a), ''),
-  ].join(':')
-  const issuesByNode: Record<string, ReturnType<typeof mergedIssues>> = {}
+  // ONE store walk yielding both halves ([[issues]] boardThreads): the ISSUE surfaces get the split
+  // population, the freshness carrier gets the whole store.
+  const { issues: merged, stamp: issuesStamp } = boardThreads({ host: resolveForgeHost(), state: residentForgeState() }, nodes.map((n) => n.id))
+  // `issuesStamp` above is that ONE board-level freshness stamp, over EVERY thread — noded or nodeless,
+  // both stores, BOTH remark hosts. It is folded from the whole store and NOT from the split `merged`: a
+  // scenario-hosted remark lands on an eval track the issue read splits out ([[eval-issue-split]]), so a
+  // carrier folded over the issue half alone left an open READING blind to every remark on it — the write
+  // moved no board byte, [[graph-delta]] correctly suppressed the no-change broadcast, and the push never
+  // fired at all. The per-node fold below stays [[graph-lean]]-slim (no reply payloads).
+  const issuesByNode: Record<string, ReturnType<typeof boardThreads>['issues']> = {}
   for (const issue of merged)
     for (const nid of issue.nodes) (issuesByNode[nid] ??= []).push(issue)
   for (const n of nodes) {
@@ -161,7 +165,7 @@ export async function buildBoard() {
   const sess = sessions.map((s) => ({
     ...s,
     source: s.path,
-    ops: opsByPath[s.path] || [],
+    ops: rowOps(s, opsByPath),
     evalSummary: evalProjections.get(s.id),
   }))
 
@@ -189,7 +193,7 @@ export async function spliceSessions(prev: Awaited<ReturnType<typeof buildBoard>
   const sess = sessions.map((s) => ({
     ...s,
     source: s.path,
-    ops: opsByPath[s.path] || [],
+    ops: rowOps(s, opsByPath),
     evalSummary: evalProjections.get(s.id),
   }))
   return { ...prev, sessions: sess }

package/spec-cli/src/graphCache.ts

@@ -1,4 +1,14 @@
+import { createHash } from 'node:crypto'
+import { readFileSync, readdirSync, statSync } from 'node:fs'
+import { isAbsolute, join, resolve } from 'node:path'
 import { buildBoard, spliceSessions } from './graph.js'
+import { headSha, repoRoot, withGitAbortSignal } from './git.js'
+import { listSessionIds, mainBranch, mainCheckout, readPublicRecordEntry, sessionArtifactPath, sessionRecordPath } from './layout.js'
+import { boardThreads } from './issues.js'
+import { resolveForgeHost } from '../../spec-forge/src/drivers.js'
+import { residentForgeState } from '../../spec-forge/src/resident.js'
+import { resolveProjectIdentity } from './project-identity.js'
+import { sessionEvalProjection } from '../../spec-eval/src/sessioneval.js'
 
 // @@@ 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
@@ -7,11 +17,197 @@ import { buildBoard, spliceSessions } from './graph.js'
 // 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 [[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.
+// signals [[graph-stream]] already watches (session-store writes, git-ref/worktree moves); the cold patrol
+// enters this cache's input-revision validation flight instead of manufacturing a change. So a poll storm
+// costs ONE build, a quiet stretch costs ZERO, and the SSE rebuild and the route share the same operation.
 
 export type Board = Awaited<ReturnType<typeof buildBoard>>
+export type BoardConsistency = 'fresh' | 'stale-ok'
+export type BoardRead = { board: Board; freshness: 'fresh' | 'stale'; refreshing: boolean; error?: string }
+export type BoardJsonRead = BoardRead & { json: string }
+
+type BoardInputRevision = {
+  full: string
+  sessions: string
+  projections: string
+  combined: string
+  fullParts: Record<string, string>
+  projectionIds: string[]
+}
+const DEBUG = process.env.SPEXCODE_BOARD_DEBUG === '1'
+
+function textOrNull(path: string): string | null {
+  try { return readFileSync(path, 'utf8') }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null
+    throw error
+  }
+}
+
+function gitDirOf(root: string): string {
+  const dotgit = join(root, '.git')
+  try { if (statSync(dotgit).isDirectory()) return dotgit }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return ''
+    throw error
+  }
+  const dotgitText = textOrNull(dotgit)
+  if (dotgitText === null) return ''
+  const match = dotgitText.match(/^gitdir:\s*(.+)$/m)
+  if (!match) throw new Error(`unparseable gitdir pointer at ${dotgit}`)
+  const dir = match[1].trim()
+  return isAbsolute(dir) ? dir : resolve(root, dir)
+}
+
+function commonDirOf(root: string): string {
+  const gitDir = gitDirOf(root)
+  if (!gitDir) return ''
+  const common = textOrNull(join(gitDir, 'commondir'))
+  if (common === null) return gitDir
+  const dir = common.trim()
+  if (!dir) throw new Error(`empty commondir pointer at ${join(gitDir, 'commondir')}`)
+  return isAbsolute(dir) ? dir : resolve(gitDir, dir)
+}
+
+function refSha(root: string, ref: string): string {
+  if (/^[0-9a-f]{40}$/.test(ref)) return ref
+  const common = commonDirOf(root)
+  if (!common) return '<missing>'
+  const names = ref.startsWith('refs/') ? [ref] : [`refs/heads/${ref}`, `refs/remotes/${ref}`]
+  for (const name of names) {
+    const loose = textOrNull(join(common, name))
+    if (loose !== null) return loose.trim() || '<missing>'
+  }
+  const packed = textOrNull(join(common, 'packed-refs'))
+  if (packed !== null) {
+    for (const line of packed.split('\n')) {
+      if (!line || line[0] === '#' || line[0] === '^') continue
+      const space = line.indexOf(' ')
+      if (space > 0 && names.includes(line.slice(space + 1).trim())) return line.slice(0, space).trim()
+    }
+  }
+  return '<missing>'
+}
+
+function headRevision(root: string): string {
+  if (!gitDirOf(root)) return '<missing>'
+  return headSha(root)
+}
+
+// Patrol validation needs a stronger contract than the overlay cache's best-effort mtime key: ctime catches
+// a same-size edit whose mtime was restored, and every non-ENOENT read failure is loud instead of collapsing an
+// unreadable subtree into a stable "unchanged" revision. A path that vanishes during the sample is represented
+// by its absence and is rechecked by the producer fence.
+function strictSpecTreeRevision(wtPath: string): string {
+  const root = join(wtPath, '.spec')
+  try { statSync(root) }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return ''
+    throw error
+  }
+  const parts: string[] = []
+  const stack = [root]
+  while (stack.length) {
+    const dir = stack.pop()!
+    let entries
+    try { entries = readdirSync(dir, { withFileTypes: true }) }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+      continue
+    }
+    for (const entry of entries) {
+      const path = join(dir, entry.name)
+      if (entry.isDirectory()) { stack.push(path); continue }
+      try {
+        const stat = statSync(path)
+        parts.push(`${path}:${stat.mtimeMs}:${stat.ctimeMs}:${stat.size}`)
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+      }
+    }
+  }
+  return parts.sort().join('\n')
+}
+
+function worktreeRevision(root: string): unknown {
+  return {
+    root,
+    head: headRevision(root),
+    spec: strictSpecTreeRevision(root),
+  }
+}
+
+function digest(value: unknown): string {
+  return createHash('sha256').update(JSON.stringify(value)).digest('hex')
+}
+
+// The patrol's cheap authority check. These are exactly the mutable inputs a board assembly reads, folded
+// without doing the assembly: HEAD/config + `.spec`, governed records and active governed worktree state,
+// the issue-store carrier, and the already-resident session-eval projections. It intentionally does not call
+// listSessions or sessionEvalProjections: verification must neither poll tmux again nor mint/schedule eval work.
+// The hot/warm liveness signatures and eval generations remain graph-stream's canonical event-owned axes.
+function boardInputRevision(board: Board | null): BoardInputRevision {
+  const root = repoRoot()
+  const ids = listSessionIds().sort()
+  // listSessions projects both the structured record and the separately-stored originating prompt into each
+  // board row. Fold both exact artifacts so a missed store event cannot leave a stale label/prompt forever.
+  const sessionInputs = ids.map((id) => [
+    id,
+    textOrNull(sessionRecordPath(id)),
+    textOrNull(sessionArtifactPath(id, 'prompt')),
+  ] as const)
+  const records = ids.map(readPublicRecordEntry).flatMap((entry) => entry.kind === 'ok' ? [entry.raw] : [])
+  const governed = records.filter((record) => record.governed).sort((a, b) => a.session_id.localeCompare(b.session_id))
+  const activeRoots = [...new Set(governed.filter((record) => !record.archived).map((record) => record.worktree_path))].sort()
+  const main = mainCheckout()
+  const base = mainBranch()
+  const mainTip = refSha(main, base)
+
+  const nodeIds = (board?.nodes ?? []).map((node) => node.id)
+  const issuesStamp = boardThreads({ host: resolveForgeHost(), state: residentForgeState() }, nodeIds).stamp
+  const fullInputs = {
+    root: worktreeRevision(root),
+    config: [
+      [join(root, 'spexcode.json'), textOrNull(join(root, 'spexcode.json'))],
+      [join(root, 'spexcode.local.json'), textOrNull(join(root, 'spexcode.local.json'))],
+      [join(main, 'spexcode.json'), textOrNull(join(main, 'spexcode.json'))],
+      [join(main, 'spexcode.local.json'), textOrNull(join(main, 'spexcode.local.json'))],
+    ],
+    main: { root: main, branch: base, tip: mainTip },
+    worktrees: activeRoots.map((worktree) => worktreeRevision(worktree)),
+    issuesStamp,
+    identity: resolveProjectIdentity(root, root),
+  }
+  const fullParts = Object.fromEntries(Object.entries(fullInputs).map(([key, value]) => [key, digest(value)]))
+  const full = digest(fullParts)
+  const sessions = digest(sessionInputs)
+
+  // Every board row carries an evalSummary, including non-governed sessions. Governed filtering owns only
+  // worktree observation; projection identity follows the whole store enumeration so a blind observer cannot
+  // strand a non-governed row on an older resident phase/value.
+  const projectionIds = ids
+  const projections = digest(projectionIds.map((id) => [id, sessionEvalProjection(id)]))
+  return { full, sessions, projections, combined: digest([full, sessions, projections]), fullParts, projectionIds }
+}
+
+// Bind an input sample to what the completed board actually carries. The sample supplies the graph/session
+// revision observed immediately after the producer; issue and projection values come from the returned board
+// itself. Re-reading all inputs here would create a certification race: a blind change after the producer's
+// after-sample could otherwise be mistaken for an input the already-built board contains.
+function revisionCarriedByBoard(sample: BoardInputRevision, board: Board): BoardInputRevision {
+  const fullParts = { ...sample.fullParts, issuesStamp: digest(board.issuesStamp) }
+  const full = digest(fullParts)
+  const boardProjections = new Map(board.sessions.map((session) => [session.id, session.evalSummary ?? null]))
+  const projections = digest(sample.projectionIds.map((id) => [id, boardProjections.get(id) ?? null]))
+  return {
+    full,
+    sessions: sample.sessions,
+    projections,
+    combined: digest([full, sample.sessions, projections]),
+    fullParts,
+    projectionIds: sample.projectionIds,
+  }
+}
 
 // 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
@@ -29,88 +225,236 @@ const BUDGET_MS = Number(process.env.SPEXCODE_BOARD_BUDGET_MS || 1500)
 // the common cause die sooner. Generous: well above the slowest legitimate cold build, so it only ever
 // fires on a genuine wedge.
 const BUILD_TIMEOUT_MS = Number(process.env.SPEXCODE_BOARD_BUILD_TIMEOUT_MS || 120000)
+const RETRY_BACKOFF_MS = Number(process.env.SPEXCODE_BOARD_RETRY_BACKOFF_MS || 1000)
+const BACKGROUND_START_DELAY_MS = Number(process.env.SPEXCODE_BOARD_BACKGROUND_START_DELAY_MS || 300)
 
 // 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.
+// worktree `.spec` edit, or a changed graph-domain patrol revision) 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 cachedRevision: BoardInputRevision | null = null // input revision represented by `cached`
 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
+type Flight = { wait: Promise<Board>; settle: Promise<Board> }
+let inflight: Flight | null = null
+let gen = 0                       // bumped on invalidation so patrol validation cannot certify across an event
+let retryAt = 0
+let lastFailure: Error | null = null
 
 // 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++
+// sessions splice). The last-good JSON stays intact while dirty so stale readers can return it without
+// paying serialization again; a successful replacement clears it.
+function mergeDirty(scope: Scope): void {
   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 '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> {
+}
+
+export function invalidateBoard(scope: Scope = 'full'): void {
+  gen++
+  mergeDirty(scope)
+  retryAt = 0
+  lastFailure = null
+}
+
+// One flight owns BOTH patrol validation and a producer. A patrol first folds the cheap input revision; an
+// exact match resolves to `cached` without calling either producer. A mismatch derives the changed domain and
+// falls through to the same build path an explicit watcher invalidation takes. An invalidation during validation
+// also falls through under this flight, so validation can never race a second producer into existence.
+type FlightMode = 'dirty' | 'patrol'
+function startBuild(mode: FlightMode = 'dirty'): Flight | null {
   if (inflight) return inflight
-  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
+  if (Date.now() < retryAt) return null
+  const flightStartGen = gen
+  const controller = new AbortController()
+  let watchdog: ReturnType<typeof setTimeout> | undefined
+  let timedOut = false
+  let built = false
+  let buildStartedAt = 0
+  let buildScope: Scope = 'full'
+  let buildFullStable = true
+  let buildSessionsStable = true
+  let completedRevision: BoardInputRevision | null = null
+  // Do not invoke the producer inline. buildBoard() has an asynchronous signature but performs a sizeable
+  // synchronous setup before its first await (Promise.all evaluates its arguments immediately). A stale HTTP
+  // caller must be able to return its last-good bytes before that setup runs; first-cold/fresh callers still
+  // await the same deferred promise below.
+  let resolveBuild!: (board: Board) => void
+  let rejectBuild!: (error: unknown) => void
+  const build = new Promise<Board>((resolve, reject) => {
+    resolveBuild = resolve
+    rejectBuild = reject
+  })
+  // Give a stale HTTP response a turn to flush before the producer's synchronous setup occupies the event
+  // loop. Fresh callers simply absorb this small scheduling window while waiting on the same flight.
+  setTimeout(() => {
+    if (controller.signal.aborted) {
+      rejectBuild(Object.assign(new Error('graph build aborted before start'), { name: 'AbortError' }))
+      return
+    }
     try {
-      const board = await Promise.race([
-        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/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?.()
-        }),
-      ])
+      Promise.resolve(withGitAbortSignal(controller.signal, async () => {
+        if (mode === 'patrol' && dirty === 'none' && cached && cachedRevision) {
+          const anchorRevision = cachedRevision
+          const observed = await boardInputRevision(cached)
+          if (controller.signal.aborted)
+            throw Object.assign(new Error('graph patrol aborted'), { name: 'AbortError' })
+          if (gen === flightStartGen && dirty === 'none' && observed.combined === anchorRevision.combined)
+            return cached
+          // A changed revision with no watcher event is the patrol doing its repair job. If an explicit event
+          // arrived meanwhile it already set the correct (possibly sessions-only) scope, which we must not
+          // overwrite. An otherwise-clean mismatch derives its scope from the moved input domain.
+          if (gen === flightStartGen && dirty === 'none') {
+            gen++
+            if (DEBUG) {
+              const moved = Object.keys(observed.fullParts)
+                .filter((key) => observed.fullParts[key] !== anchorRevision.fullParts[key])
+              console.warn(`spec-cli: graph patrol revision moved — scope=${observed.full === anchorRevision.full ? 'sessions' : 'full'} inputs=[${moved.join(', ')}]`)
+            }
+            dirty = observed.full === anchorRevision.full ? 'sessions' : 'full'
+          }
+        }
+
+        const prev = cached
+        const before = await boardInputRevision(prev)
+        if (controller.signal.aborted)
+          throw Object.assign(new Error('graph build aborted before producer start'), { name: 'AbortError' })
+        // A session signal cannot vouch for the graph domain. Before splicing, compare the current full inputs
+        // to the revision the cached node/meta units actually carry; a missed graph watcher promotes this same
+        // flight to full instead of certifying old nodes under a new revision.
+        if (dirty === 'sessions' && prev && cachedRevision && before.full !== cachedRevision.full) {
+          if (DEBUG) console.warn('spec-cli: session refresh found moved graph inputs — promoting to full')
+          dirty = 'full'
+        }
+        const sessionsOnly = dirty === 'sessions' && prev !== null
+        buildScope = sessionsOnly ? 'sessions' : 'full'
+        // Consume the scope this producer is satisfying. Invalidation after this point starts a NEW dirty
+        // window with its own domain: a session completion during a long full build owes one splice, not
+        // another full build. The occupied `inflight` slot keeps fresh/stale readers joined while dirty is clean.
+        dirty = 'none'
+        built = true
+        buildStartedAt = Date.now()
+        const board = await (sessionsOnly ? spliceSessions(prev!) : buildBoard())
+        const after = await boardInputRevision(prev)
+        const carried = revisionCarriedByBoard(after, board)
+        const movedFull = Object.keys(after.fullParts)
+          .filter((key) => after.fullParts[key] !== before.fullParts[key])
+        // The first build can initialize the resident forge carrier that it then returns. That movement is
+        // stable only when the finished board carries the after-sample's exact issue stamp. Every other cold
+        // movement remains dirty just like a warm one; cold start is not a blanket race exemption.
+        const coldIssueInitialization = prev === null
+          && movedFull.every((key) => key === 'issuesStamp')
+          && after.fullParts.issuesStamp === carried.fullParts.issuesStamp
+        buildFullStable = before.full === after.full || coldIssueInitialization
+        buildSessionsStable = before.sessions === after.sessions
+        if (DEBUG && (!buildFullStable || !buildSessionsStable)) {
+          console.warn(`spec-cli: graph inputs moved during ${buildScope} producer — next=${buildFullStable ? 'sessions' : 'full'} inputs=[${movedFull.join(', ')}] sessions=${buildSessionsStable ? 'stable' : 'moved'}`)
+        }
+        completedRevision = carried
+        return board
+      }))
+        .then(resolveBuild, rejectBuild)
+    } catch (error) {
+      rejectBuild(error)
+    }
+  }, mode === 'patrol' ? 0 : BACKGROUND_START_DELAY_MS).unref?.()
+  const timeoutError = () => new Error(`graph build did not settle within ${BUILD_TIMEOUT_MS}ms`)
+
+  // `settle` owns the real builder. The watchdog only rejects `wait`; the slot remains occupied until this
+  // promise settles, so a next read can never overlap an abandoned git/fs build.
+  let settle!: Promise<Board>
+  settle = build.then((board) => {
+    if (timedOut) throw timeoutError()
+    if (built) {
       cached = board
-      cachedJson = null   // invalidate the memoized serialization; re-serialized lazily on first read
-      // 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/graph build took ${ms}ms (budget ${BUDGET_MS}ms) — hot path is slow`)
-      inflight = null
+      cachedJson = null
+      cachedRevision = completedRevision
+      if (!buildFullStable) mergeDirty('full')
+      else if (!buildSessionsStable) mergeDirty('sessions')
     }
-  })()
-  inflight = p
-  return p
+    retryAt = 0
+    lastFailure = null
+    return board
+  }).catch((error) => {
+    const failure = error instanceof Error ? error : new Error(String(error))
+    if (built) mergeDirty(buildScope)
+    lastFailure = failure
+    retryAt = Date.now() + RETRY_BACKOFF_MS
+    console.warn(`spec-cli: /api/graph build failed — ${failure.message}`)
+    throw failure
+  }).finally(() => {
+    clearTimeout(watchdog)
+    if (inflight?.settle === settle) inflight = null
+    const ms = built ? Date.now() - buildStartedAt : 0
+    if (built && ms > BUDGET_MS)
+      console.warn(`spec-cli: /api/graph build took ${ms}ms (budget ${BUDGET_MS}ms) — ${buildScope} path is slow`)
+  })
+
+  const wait = new Promise<Board>((resolve, reject) => {
+    watchdog = setTimeout(() => {
+      timedOut = true
+      console.warn(`spec-cli: /api/graph build did not settle within ${BUILD_TIMEOUT_MS}ms — aborting the single-flight build`)
+      controller.abort()
+      reject(timeoutError())
+    }, BUILD_TIMEOUT_MS)
+    watchdog.unref?.()
+    settle.then((board) => {
+      if (!timedOut) resolve(board)
+    }, (error) => {
+      if (!timedOut) reject(error)
+    })
+  })
+  const flight = { wait, settle }
+  inflight = flight
+  // Background stale readers intentionally do not await these promises. Observe both rejection paths so a
+  // failed build is loud without becoming an unhandled rejection.
+  void wait.catch(() => {})
+  void settle.catch(() => {})
+  return flight
+}
+
+export function getBoard(): Promise<Board> {
+  // A clean-looking cache can be under patrol validation. Fresh readers join that flight before taking the
+  // cache fast path, otherwise one can return stale bytes while the flight is discovering a missed change.
+  if (inflight) return inflight.wait
+  if (dirty === 'none' && cached) return Promise.resolve(cached)
+  const flight = startBuild('dirty')
+  if (flight) return flight.wait
+  return Promise.reject(lastFailure ?? new Error('graph build retry is temporarily backing off'))
+}
+
+// The delta-gated cold tick calls this instead of invalidating. Equal inputs resolve to the cached object;
+// changed inputs repair through the same flight and full producer as a watcher-owned invalidation.
+export function patrolBoard(): Promise<Board> {
+  if (!cached) return getBoard()
+  const flight = startBuild('patrol')
+  if (flight) return flight.wait
+  return Promise.reject(lastFailure ?? new Error('graph patrol retry is temporarily backing off'))
+}
+
+export async function readBoard(consistency: BoardConsistency = 'fresh'): Promise<BoardRead> {
+  if (consistency === 'stale-ok' && cached) {
+    const stale = dirty !== 'none' || inflight !== null
+    const flight = stale ? startBuild('dirty') : null
+    return { board: cached, freshness: stale ? 'stale' : 'fresh', refreshing: !!flight, ...(lastFailure ? { error: lastFailure.message } : {}) }
+  }
+  const board = await getBoard()
+  return { board, freshness: 'fresh', refreshing: false }
 }
 
 // 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 ([[graph-delta]]).
-export async function getBoardJson(): Promise<string> {
-  const board = await getBoard()
-  if (board === cached && cachedJson !== null) return cachedJson
+export async function getBoardJson(consistency: BoardConsistency = 'fresh'): Promise<BoardJsonRead> {
+  const result = await readBoard(consistency)
+  const board = result.board
+  if (board === cached && cachedJson !== null) return { ...result, json: cachedJson }
   const json = JSON.stringify(board)
   if (board === cached) cachedJson = json   // memoize only the CURRENT build's serialization
-  return json
+  return { ...result, json }
 }