@spexcode/spec-cli 0.6.5

package/dist/graphCache.js

@@ -0,0 +1,716 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { rebasePublishedSessions } from '@spexcode/spec-core';
+import { buildBoard, spliceSessions } from './graphSnapshot.js';
+import { headSha, repoRoot, withGitAbortSignal } from '@spexcode/spec-core';
+import { listSessionIds, mainBranch, mainCheckout, readPublicRecordEntry, sessionArtifactPath, sessionRecordPath } from '@spexcode/spec-core';
+import { boardThreads } from './issues.js';
+import { resolveForgeHost } from '@spexcode/spec-forge/drivers';
+import { residentForgeState } from '@spexcode/spec-forge/resident';
+import { resolveProjectIdentity } from '@spexcode/spec-core';
+import { readReviewSnapshot } from '@spexcode/spec-core';
+import { sessionEvalProjection } from '@spexcode/spec-eval/sessioneval';
+const DEBUG = process.env.SPEXCODE_BOARD_DEBUG === '1';
+function textOrNull(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+function gitDirOf(root) {
+    const dotgit = join(root, '.git');
+    try {
+        if (statSync(dotgit).isDirectory())
+            return dotgit;
+    }
+    catch (error) {
+        if (error.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) {
+    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, ref) {
+    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) {
+    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) {
+    const root = join(wtPath, '.spec');
+    try {
+        statSync(root);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return '';
+        throw error;
+    }
+    const parts = [];
+    const stack = [root];
+    while (stack.length) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch (error) {
+            if (error.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.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+    }
+    return parts.sort().join('\n');
+}
+function worktreeRevision(root) {
+    return {
+        root,
+        head: headRevision(root),
+        spec: strictSpecTreeRevision(root),
+    };
+}
+function digest(value) {
+    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 sessionInputRevision() {
+    const ids = listSessionIds().sort();
+    // listSessions projects the structured record plus a one-line preview of the separately-stored originating
+    // prompt into each board row. Fold both exact artifacts so a missed store event cannot leave a stale
+    // label/preview forever — the prompt file is folded because the preview is derived from it.
+    const sessionInputs = ids.map((id) => [
+        id,
+        textOrNull(sessionRecordPath(id)),
+        textOrNull(sessionArtifactPath(id, 'prompt')),
+    ]);
+    const projections = digest(ids.map((id) => [id, sessionEvalProjection(id)]));
+    const activeRoots = [...new Set(ids.flatMap((id) => {
+            const entry = readPublicRecordEntry(id);
+            return entry.kind === 'ok' && entry.raw.governed && !entry.raw.archived ? [entry.raw.worktree_path] : [];
+        }))].sort();
+    return { sessions: digest(sessionInputs), projections, projectionIds: ids, activeRoots };
+}
+function boardInputRevision(board) {
+    const root = repoRoot();
+    const session = sessionInputRevision();
+    // Durable active records are the current root set; a cached ordinary row may be stale and must not replace
+    // them. The one projection-only addition is explicit: listSessions republishes an archived-runtime hazard
+    // into the working set, and that marked row keeps its root monitored until cold state is repaired.
+    const activeRoots = [...new Set([
+            ...session.activeRoots,
+            ...(board?.sessions.flatMap((row) => row.archiveHazard ? [row.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 worktreeParts = Object.fromEntries(activeRoots.map((worktree) => [worktree, digest(worktreeRevision(worktree))]));
+    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: worktreeParts,
+        issuesStamp,
+        identity: resolveProjectIdentity(root, root),
+    };
+    const fullParts = Object.fromEntries(Object.entries(fullInputs).map(([key, value]) => [key, digest(value)]));
+    const full = digest(fullParts);
+    return {
+        full,
+        ...session,
+        combined: digest([full, session.sessions, session.projections]),
+        fullParts,
+        worktreeParts,
+    };
+}
+// 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, board) {
+    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,
+        worktreeParts: sample.worktreeParts,
+        projectionIds: sample.projectionIds,
+    };
+}
+// 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, sample, board, stable) {
+    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,
+        worktreeParts: base.worktreeParts,
+        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, published) {
+    return {
+        full: full.full,
+        sessions: published.sessions,
+        projections: published.projections,
+        combined: digest([full.full, published.sessions, published.projections]),
+        fullParts: full.fullParts,
+        worktreeParts: full.worktreeParts,
+        projectionIds: published.projectionIds,
+    };
+}
+function carrySubtractiveWorktrees(base, activeRoots) {
+    const active = new Set(activeRoots);
+    const known = Object.keys(base.worktreeParts);
+    if (activeRoots.some((root) => !(root in base.worktreeParts)))
+        return { revision: base, added: true };
+    if (known.every((root) => active.has(root)))
+        return { revision: base, added: false };
+    const worktreeParts = Object.fromEntries(Object.entries(base.worktreeParts).filter(([root]) => active.has(root)));
+    const fullParts = { ...base.fullParts, worktrees: digest(worktreeParts) };
+    const full = digest(fullParts);
+    return {
+        revision: {
+            ...base,
+            full,
+            fullParts,
+            worktreeParts,
+            combined: digest([full, base.sessions, base.projections]),
+        },
+        added: false,
+    };
+}
+function isPureSubtractiveWorktreeMove(base, sample) {
+    const moved = Object.keys(sample.fullParts).filter((key) => sample.fullParts[key] !== base.fullParts[key]);
+    if (moved.length !== 1 || moved[0] !== 'worktrees')
+        return false;
+    const current = Object.keys(sample.worktreeParts);
+    const previous = Object.keys(base.worktreeParts);
+    return current.length < previous.length
+        && current.every((root) => sample.worktreeParts[root] === base.worktreeParts[root]);
+}
+// a build slower than this is LOGGED, never silently tolerated — the fail-loud regression alarm. Sized
+// above a warm build (~sub-second once the fs walks yield) but below the cold two-walk first build, so a
+// genuinely-degraded hot path shouts while an ordinary cold start stays quiet-ish.
+const BUDGET_MS = Number(process.env.SPEXCODE_BOARD_BUDGET_MS || 1500);
+// a build that NEVER settles is a different animal from a slow one: `inflight` clears only in the finally
+// below, so a never-settling buildBoard() would pin the single-flight forever — every later read (even of a
+// perfectly good cached board) short-circuits into the pinned promise before `valid` is consulted,
+// invalidation can't help, no log ever fires, and only a restart cures it (the live wedge: hung git
+// children → /api/graph 503 forever, silently). So the build races a generous watchdog that REJECTS loudly;
+// the rejection flows through the SAME finally → inflight clears → the next read retries fresh. Sitting at
+// the single-flight boundary, this one wall bounds every never-settle cause — including ones with no child
+// process at all (fs/promises under libuv threadpool starvation); git.ts's per-child timeouts merely make
+// 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);
+let cached = null; // last completed build; served while `dirty === 'none'`
+let cachedJson = null; // JSON.stringify(cached), serialized ONCE per build (see getBoardJson)
+let cachedRevision = null; // input revision represented by `cached`
+let dirty = 'full'; // no cached board yet → the first read builds fully
+let inflight = null;
+let sessionFlight = 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 = 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. `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) {
+    if (scope === 'full' || dirty === 'full')
+        dirty = 'full';
+    else
+        dirty = 'sessions';
+}
+export function invalidateBoard(scope = 'full') {
+    gen++;
+    if (scope === 'sessions') {
+        sessionOwed = true;
+        sessionGeneration++;
+    }
+    mergeDirty(scope);
+    retryAt = 0;
+    lastFailure = null;
+}
+function traceCacheCommit(scope, startedAt) {
+    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() {
+    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;
+    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 &&
+                JSON.stringify(before.activeRoots) === JSON.stringify(after.activeRoots);
+            const projectedRoots = [...new Set(board.sessions.map((row) => row.path))].sort();
+            const rootTransition = carrySubtractiveWorktrees(revision, projectedRoots);
+            const carried = stable ? rootTransition.revision : revision;
+            cached = board;
+            cachedJson = null;
+            cachedRevision = revisionCarriedBySessionSplice(carried, before, board, stable);
+            sessionProjectionPublication++;
+            if (rootTransition.added)
+                mergeDirty('full');
+            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;
+    settle = producer.finally(() => {
+        clearTimeout(watchdog);
+        if (sessionFlight?.settle === settle)
+            sessionFlight = null;
+    });
+    const wait = new Promise((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;
+}
+function startBuild(mode = 'dirty') {
+    if (inflight)
+        return inflight;
+    if (Date.now() < retryAt)
+        return null;
+    const controller = new AbortController();
+    let watchdog;
+    let timedOut = false;
+    let built = false;
+    let buildStartedAt = 0;
+    let buildScope = 'full';
+    let buildFullStable = true;
+    let buildSessionsStable = true;
+    let buildSessionGeneration = sessionGeneration;
+    let buildSessionProjectionPublication = sessionProjectionPublication;
+    let buildStartedWithSessionOwed = false;
+    let buildAddedSessionRoot = false;
+    let completedRevision = 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;
+    let rejectBuild;
+    const build = new Promise((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 {
+            Promise.resolve(withGitAbortSignal(controller.signal, async () => {
+                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' });
+                // 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 subtractiveWorktreeMove = fullMoved && isPureSubtractiveWorktreeMove(anchor, before);
+                    const structuralMoved = fullMoved && !subtractiveWorktreeMove;
+                    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 || subtractiveWorktreeMove) && !sessionOwed && dirty !== 'sessions') {
+                        gen++;
+                        sessionOwed = true;
+                        sessionGeneration++;
+                    }
+                    const owed = structuralMoved ? '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 graph input moved`);
+                    }
+                    if (structuralMoved)
+                        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';
+                // 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';
+                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 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 === 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'}`);
+                }
+                // 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.
+                if (sessionsOnly && anchor) {
+                    const projectedRoots = [...new Set(board.sessions.map((row) => row.path))].sort();
+                    const rootTransition = carrySubtractiveWorktrees(anchor, projectedRoots);
+                    buildAddedSessionRoot = rootTransition.added;
+                    completedRevision = revisionCarriedBySessionSplice(rootTransition.revision, before, board, buildFullStable && buildSessionsStable && !rootTransition.added);
+                }
+                else {
+                    completedRevision = revisionCarriedByBoard(buildFullStable && buildSessionsStable ? after : before, board);
+                }
+                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;
+    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 || buildAddedSessionRoot)
+                mergeDirty('full');
+            traceCacheCommit(buildScope, buildStartedAt);
+        }
+        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((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() {
+    // 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, publication) {
+    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) {
+    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() {
+    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() {
+    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 = 'fresh') {
+    if (consistency === 'stale-ok' && cached) {
+        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();
+    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(consistency = 'fresh') {
+    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 { ...result, json };
+}