spexcode 0.5.7 → 0.5.9

package/spec-cli/src/graphCache.ts

@@ -1,30 +1,25 @@
 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 { buildBoard, rebasePublishedSessions, 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 { readReviewSnapshot } from './reviewSnapshot.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
-// 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 [[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 }
+export type RevisionPublication = {
+  revision: () => number
+  invalidate: () => void
+  wait: () => Promise<void>
+}
 
 type BoardInputRevision = {
   full: string
@@ -34,6 +29,7 @@ type BoardInputRevision = {
   fullParts: Record<string, string>
   projectionIds: string[]
 }
+type SessionInputRevision = Pick<BoardInputRevision, 'sessions' | 'projections' | 'projectionIds'>
 const DEBUG = process.env.SPEXCODE_BOARD_DEBUG === '1'
 
 function textOrNull(path: string): string | null {
@@ -146,8 +142,7 @@ function digest(value: unknown): string {
 // 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()
+function sessionInputRevision(): SessionInputRevision {
   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.
@@ -156,13 +151,19 @@ function boardInputRevision(board: Board | null): BoardInputRevision {
     textOrNull(sessionRecordPath(id)),
     textOrNull(sessionArtifactPath(id, 'prompt')),
   ] as const)
-  const records = ids.map(readPublicRecordEntry).flatMap((entry) => entry.kind === 'ok' ? [entry.raw] : [])
+  const projections = digest(ids.map((id) => [id, sessionEvalProjection(id)]))
+  return { sessions: digest(sessionInputs), projections, projectionIds: ids }
+}
+
+function boardInputRevision(board: Board | null): BoardInputRevision {
+  const root = repoRoot()
+  const session = sessionInputRevision()
+  const records = listSessionIds().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 = {
@@ -180,14 +181,12 @@ function boardInputRevision(board: Board | null): BoardInputRevision {
   }
   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 }
+  return {
+    full,
+    ...session,
+    combined: digest([full, session.sessions, session.projections]),
+    fullParts,
+  }
 }
 
 // Bind an input sample to what the completed board actually carries. The sample supplies the graph/session
@@ -209,6 +208,38 @@ function revisionCarriedByBoard(sample: BoardInputRevision, board: Board): Board
   }
 }
 
+// A sessions splice reuses its base topology. It may sample fresh record/projection inputs, but it must never
+// certify that those old nodes carry a full revision sampled after the base was built.
+function revisionCarriedBySessionSplice(base: BoardInputRevision, sample: SessionInputRevision, board: Board, stable: boolean): BoardInputRevision {
+  const boardProjections = new Map(board.sessions.map((session) => [session.id, session.evalSummary ?? null]))
+  const projections = stable
+    ? digest(sample.projectionIds.map((id) => [id, boardProjections.get(id) ?? null]))
+    : sample.projections
+  return {
+    full: base.full,
+    sessions: sample.sessions,
+    projections,
+    combined: digest([base.full, sample.sessions, projections]),
+    fullParts: base.fullParts,
+    projectionIds: sample.projectionIds,
+  }
+}
+
+// The full producer's topology may be newer than the last published session projection. When completion
+// re-bases that already-visible projection onto the new topology, keep the full carrier from the producer and
+// only the sessions/projections carrier from the published rows. Do not sample current inputs here: that would
+// certify a write that neither producer actually carried.
+function revisionCarriedByPublishedSessionRebase(full: BoardInputRevision, published: BoardInputRevision): BoardInputRevision {
+  return {
+    full: full.full,
+    sessions: published.sessions,
+    projections: published.projections,
+    combined: digest([full.full, published.sessions, published.projections]),
+    fullParts: full.fullParts,
+    projectionIds: published.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
 // genuinely-degraded hot path shouts while an ordinary cold start stays quiet-ish.
@@ -228,11 +259,8 @@ const BUILD_TIMEOUT_MS = Number(process.env.SPEXCODE_BOARD_BUILD_TIMEOUT_MS || 1
 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, or a changed graph-domain patrol revision) can reshape anything, so the next read
-// does the whole buildBoard(). 'none' = clean.
+// The structural/full and sessions obligations are deliberately separate. A full build can take seconds;
+// a persisted session row cannot be silently converted into time behind that unrelated topology work.
 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)
@@ -240,16 +268,19 @@ let cachedRevision: BoardInputRevision | null = null // input revision represent
 let dirty: Scope | 'none' = 'full'   // no cached board yet → the first read builds fully
 type Flight = { wait: Promise<Board>; settle: Promise<Board> }
 let inflight: Flight | null = null
+let sessionFlight: Flight | null = null
+let sessionOwed = false
+let sessionGeneration = 0
+let sessionProjectionPublication = 0
+let topologyGeneration = 0
 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). The last-good JSON stays intact while dirty so stale readers can return it without
-// paying serialization again; a successful replacement clears it.
+// keeps hitting the cache. `dirty` is the structural producer's scope; `sessionOwed` is intentionally not
+// folded into it, because full+sessions owes both a full convergence and a cheap first projection.
 function mergeDirty(scope: Scope): void {
   if (scope === 'full' || dirty === 'full') dirty = 'full'
   else dirty = 'sessions'
@@ -257,20 +288,90 @@ function mergeDirty(scope: Scope): void {
 
 export function invalidateBoard(scope: Scope = 'full'): void {
   gen++
+  if (scope === 'sessions') { sessionOwed = true; sessionGeneration++ }
   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.
+function traceCacheCommit(scope: Scope, startedAt: number): void {
+  if (!DEBUG) return
+  const at = Date.now()
+  console.warn(`spec-cli: graph cache ${JSON.stringify({ at, stage: 'cache-commit', scope, buildMs: at - startedAt })}`)
+}
+
+function startSessionSplice(): Flight | null {
+  if (!cached || !cachedRevision || !sessionOwed) return null
+  if (sessionFlight) return sessionFlight
+  sessionOwed = false
+  if (dirty === 'sessions') dirty = 'none'
+  let timedOut = false
+  const startedAt = Date.now()
+  let watchdog: ReturnType<typeof setTimeout> | undefined
+  const timeoutError = () => new Error(`graph session splice did not settle within ${BUILD_TIMEOUT_MS}ms`)
+  const producer = Promise.resolve().then(async () => {
+    // A full completion may replace the topology while listSessions is in flight. Rebase before publishing;
+    // the splice is a projection over whatever last-good structure is current, never a whole-board write race.
+    while (true) {
+      const base = cached, revision = cachedRevision, generation = topologyGeneration
+      if (!base || !revision) throw new Error('graph session splice lost its cached topology')
+      const before = sessionInputRevision()
+      const board = await spliceSessions(base)
+      const after = sessionInputRevision()
+      if (base !== cached || revision !== cachedRevision || generation !== topologyGeneration) continue
+      const stable = before.sessions === after.sessions && before.projections === after.projections
+      cached = board
+      cachedJson = null
+      cachedRevision = revisionCarriedBySessionSplice(revision, before, board, stable)
+      sessionProjectionPublication++
+      if (!stable) {
+        sessionOwed = true
+        sessionGeneration++
+        mergeDirty('sessions')
+      }
+      return board
+    }
+  })
+    .then((board) => {
+      if (timedOut) throw timeoutError()
+      traceCacheCommit('sessions', startedAt)
+      return board
+    })
+    .catch((error) => {
+      sessionOwed = true
+      mergeDirty('sessions')
+      throw error
+    })
+  let settle!: Promise<Board>
+  settle = producer.finally(() => {
+    clearTimeout(watchdog)
+    if (sessionFlight?.settle === settle) sessionFlight = null
+  })
+  const wait = new Promise<Board>((resolve, reject) => {
+    watchdog = setTimeout(() => {
+      timedOut = true
+      console.warn(`spec-cli: graph session splice did not settle within ${BUILD_TIMEOUT_MS}ms`)
+      reject(timeoutError())
+    }, BUILD_TIMEOUT_MS)
+    watchdog.unref?.()
+    settle.then((board) => { if (!timedOut) resolve(board) }, (error) => { if (!timedOut) reject(error) })
+  })
+  const flight = { wait, settle }
+  sessionFlight = flight
+  void wait.catch(() => {})
+  void settle.catch(() => {})
+  return flight
+}
+
+// One flight owns BOTH validation and a producer. Every refresh — patrol or watcher-signalled — 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 build path. An invalidation during validation also falls
+// through under this flight, so validation can never race a second producer into existence. `mode` no longer
+// selects who validates; it only says whether a stale HTTP response is waiting for a turn to flush first.
 type FlightMode = 'dirty' | 'patrol'
 function startBuild(mode: FlightMode = 'dirty'): Flight | null {
   if (inflight) return inflight
   if (Date.now() < retryAt) return null
-  const flightStartGen = gen
   const controller = new AbortController()
   let watchdog: ReturnType<typeof setTimeout> | undefined
   let timedOut = false
@@ -279,6 +380,9 @@ function startBuild(mode: FlightMode = 'dirty'): Flight | null {
   let buildScope: Scope = 'full'
   let buildFullStable = true
   let buildSessionsStable = true
+  let buildSessionGeneration = sessionGeneration
+  let buildSessionProjectionPublication = sessionProjectionPublication
+  let buildStartedWithSessionOwed = false
   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
@@ -299,37 +403,42 @@ function startBuild(mode: FlightMode = 'dirty'): Flight | null {
     }
     try {
       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 anchor = cachedRevision
+        const sampledGen = gen
         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'
+        // ONE rule for every refresh: the domain a producer runs is DERIVED from the inputs that actually
+        // moved, never assigned by whoever signalled. A watcher names the leaf it saw, not what the board
+        // reads — a generated harness artifact rewritten inside a live worktree, or a linked worktree no
+        // governed record names, moves no board input at all, and used to buy a whole structural assembly
+        // anyway. The revision sampled here is the complete full-domain contract, so an unmoved full
+        // obligation is DISCHARGED without assembly. The session projection is deliberately NOT
+        // dischargeable: liveness lives on graph-stream's poller axis, outside this revision, so a claimed
+        // sessions obligation always survives and takes its splice. A sample taken after the write is what
+        // the watcher event was about; an invalidation arriving after the sample keeps its own dirty window.
+        if (prev && anchor && gen === sampledGen) {
+          const fullMoved = before.full !== anchor.full
+          const projectionMoved = before.sessions !== anchor.sessions || before.projections !== anchor.projections
+          // A projection move nobody signalled is this validation doing the patrol's repair job.
+          if (projectionMoved && !sessionOwed && dirty !== 'sessions') {
+            gen++
+            sessionOwed = true
+            sessionGeneration++
+          }
+          const owed = fullMoved ? 'full' : (sessionOwed || dirty === 'sessions') ? 'sessions' : 'none'
+          if (DEBUG && owed !== 'none') {
+            const moved = Object.keys(before.fullParts).filter((key) => before.fullParts[key] !== anchor.fullParts[key])
+            console.warn(`spec-cli: graph refresh revision moved — signalled=${dirty} scope=${owed} inputs=[${moved.join(', ')}]`)
+          } else if (DEBUG && dirty !== 'none') {
+            console.warn(`spec-cli: graph refresh discharged a ${dirty} signal — no board input moved`)
+          }
+          if (fullMoved) dirty = 'full'
+          else if (sessionOwed || dirty === 'sessions') dirty = 'sessions'
+          // Discharging CONSUMES the claim. Leaving it standing would make every later read re-enter this
+          // validation, hold the board permanently stale/refreshing, and never converge.
+          else { dirty = 'none'; return prev }
         }
         const sessionsOnly = dirty === 'sessions' && prev !== null
         buildScope = sessionsOnly ? 'sessions' : 'full'
@@ -337,11 +446,14 @@ function startBuild(mode: FlightMode = 'dirty'): Flight | null {
         // 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'
+        if (sessionsOnly) sessionOwed = false
         built = true
+        buildSessionGeneration = sessionGeneration
+        buildSessionProjectionPublication = sessionProjectionPublication
+        buildStartedWithSessionOwed = sessionOwed
         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
@@ -349,13 +461,20 @@ function startBuild(mode: FlightMode = 'dirty'): Flight | null {
         // 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
+          && after.fullParts.issuesStamp === digest(board.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
+        // The anchor must name the sample this board is KNOWN to have read, because validation now discharges
+        // an unmoved obligation for every refresh, not only the patrol's. An input that moved DURING the
+        // producer leaves the board built from the pre-move value while the after-sample already names the
+        // post-move one; anchoring on `after` would let the next validation discharge the re-owed dirty scope
+        // against a revision this board never carried, and the cache would converge on nothing. So a moved
+        // half anchors on `before` — the conservative direction, which costs at most one extra rebuild and can
+        // never certify unread bytes.
+        completedRevision = revisionCarriedByBoard(buildFullStable && buildSessionsStable ? after : before, board)
         return board
       }))
         .then(resolveBuild, rejectBuild)
@@ -368,14 +487,31 @@ function startBuild(mode: FlightMode = 'dirty'): Flight | null {
   // `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) => {
+  settle = build.then(async (board) => {
     if (timedOut) throw timeoutError()
     if (built) {
+      // A full build's session snapshot may predate a session projection that clients already saw. Rebase those
+      // published rows in memory on the new topology. This completion path must stay bounded: a later/unpublished
+      // session generation remains owed to the independent cheap splice rather than making full wait for quiet.
+      const publishedDuringBuild = sessionProjectionPublication !== buildSessionProjectionPublication
+      if (buildScope === 'full' && publishedDuringBuild && cached && cachedRevision) {
+        board = rebasePublishedSessions(board, cached)
+        completedRevision = revisionCarriedByPublishedSessionRebase(completedRevision!, cachedRevision)
+      }
+      const sessionStillOwed = sessionOwed || (!publishedDuringBuild && (
+        buildStartedWithSessionOwed || !buildSessionsStable || buildSessionGeneration !== sessionGeneration
+      ))
+      if (sessionStillOwed) {
+        sessionOwed = true
+        mergeDirty('sessions')
+      }
       cached = board
       cachedJson = null
       cachedRevision = completedRevision
+      if (buildScope === 'full') topologyGeneration++
+      else sessionProjectionPublication++
       if (!buildFullStable) mergeDirty('full')
-      else if (!buildSessionsStable) mergeDirty('sessions')
+      traceCacheCommit(buildScope, buildStartedAt)
     }
     retryAt = 0
     lastFailure = null
@@ -422,12 +558,51 @@ 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 === 'full') {
+    const flight = startBuild('dirty')
+    if (flight) return flight.wait
+  }
+  if (sessionFlight) return sessionFlight.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'))
 }
 
+export async function waitForPublishedRevision(required: number, publication: RevisionPublication): Promise<void> {
+  while (publication.revision() < required) {
+    publication.invalidate()
+    await publication.wait()
+  }
+}
+
+// A board flight can have captured a resident forge slice before its reconcile publishes a newer revision.
+// That older flight may settle, but cannot discharge this request: its invalidation stays owed and the fence
+// consumes the next publication instead of letting a fresh /api/issues read return the old review snapshot.
+export async function getBoardForForgeRevision(required: number): Promise<Board> {
+  await waitForPublishedRevision(required, {
+    revision: () => readReviewSnapshot().forgeRevision,
+    invalidate: () => invalidateBoard('full'),
+    wait: async () => {
+      const current = inflight
+      if (current) await current.settle
+      else await getBoard()
+    },
+  })
+  return cached ?? getBoard()
+}
+
+// Delta delivery may choose the sessions obligation while a route-owned full is still in flight. Starting
+// the full first preserves structural convergence; returning the splice first keeps the lifecycle surface live.
+export function getBoardForSessionRefresh(): Promise<Board> {
+  if (cached && sessionOwed) {
+    if (!inflight && dirty === 'full') startBuild('dirty')
+    const flight = startSessionSplice()
+    if (flight) return flight.wait
+  }
+  return getBoard()
+}
+
 // 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> {
@@ -439,8 +614,14 @@ export function patrolBoard(): Promise<Board> {
 
 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
+    const stale = dirty !== 'none' || inflight !== null || sessionFlight !== null || sessionOwed
+    // A held session splice already owns this refresh. Returning stale bytes must not manufacture a full
+    // producer beside it; a real full obligation still starts its one structural producer independently.
+    const flight = inflight
+      ?? (dirty === 'full' ? startBuild('dirty') : null)
+      ?? sessionFlight
+      ?? (sessionOwed ? startSessionSplice() : null)
+      ?? (dirty === 'sessions' ? startBuild('dirty') : null)
     return { board: cached, freshness: stale ? 'stale' : 'fresh', refreshing: !!flight, ...(lastFailure ? { error: lastFailure.message } : {}) }
   }
   const board = await getBoard()

package/spec-cli/src/graphDelta.ts

@@ -1,18 +1,5 @@
 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 ([[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
-// 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[] }