spexcode 0.5.8 → 0.6.0

package/spec-cli/src/delivery-queue.ts

@@ -0,0 +1,107 @@
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, writeSync } from 'node:fs'
+import { join } from 'node:path'
+import { runtimeRoot, sessionArtifactPath, sessionStoreDir } from './layout.js'
+
+// @@@ delivery-queue - what a session still OWES its agent. The log ([[session-timeline]]) is the record and
+// grows forever; this is the debt and is consumed, so it lives in its own small file whose resting state is
+// EMPTY. Nothing here reads the log: an entry carries the text it will hand over, so history could be trimmed
+// or archived without changing what is owed. A session that predates this mechanism owes nothing, because a
+// queue is only ever filled by an enqueue — which is why no backlog migration exists.
+
+export type PendingMessage = { mid: string; text: string; from: string | null }
+
+const queuePath = (id: string): string => sessionArtifactPath(id, 'pending.json')
+
+// @@@ its own lock, deliberately NOT the record lock - the drain holds this across the adapter insert, which
+// is what makes "claim" real: two processes draining the same session cannot both hand over one message. The
+// record lock could never span that call — a native turn runs lifecycle hooks that re-enter the record writer,
+// and holding it there deadlocks the adapter's own confirmation. Nothing in the delivery path takes this one,
+// so spanning the insert costs no contention. PID liveness reclaims a lock whose holder died mid-insert.
+const lockRoot = (): string => join(runtimeRoot(), '.delivery-locks')
+const lockPath = (id: string): string => join(lockRoot(), `${id}.lock`)
+
+const pause = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms))
+
+async function acquire(id: string, timeoutMs: number): Promise<(() => void) | null> {
+  mkdirSync(lockRoot(), { recursive: true })
+  const path = lockPath(id), deadline = Date.now() + timeoutMs
+  for (;;) {
+    try {
+      const fd = openSync(path, 'wx')
+      writeSync(fd, String(process.pid))
+      closeSync(fd)
+      return () => { try { unlinkSync(path) } catch { /* a liveness reclaim already removed it */ } }
+    } catch (e) {
+      if ((e as NodeJS.ErrnoException).code !== 'EEXIST') throw e
+      let owner = 0
+      try { owner = Number(readFileSync(path, 'utf8').trim()) || 0 } catch { /* race with creator/releaser */ }
+      if (owner && owner !== process.pid) {
+        try { process.kill(owner, 0) } catch { try { unlinkSync(path) } catch { /* race */ }; continue }
+      }
+      // A drain is never urgent enough to fight for: whoever holds the lock is delivering these same messages,
+      // and the retry sweep will come back. Declining is not a lost message.
+      if (Date.now() >= deadline) return null
+      await pause(25)
+    }
+  }
+}
+
+function read(id: string): PendingMessage[] {
+  try {
+    const raw = JSON.parse(readFileSync(queuePath(id), 'utf8')) as unknown
+    if (!Array.isArray(raw)) return []
+    return raw.filter((m): m is PendingMessage =>
+      !!m && typeof m === 'object'
+      && typeof (m as PendingMessage).mid === 'string'
+      && typeof (m as PendingMessage).text === 'string')
+  } catch { return [] }   // absent, empty, or unparseable all mean the honest thing: nothing owed
+}
+
+// Written whole and atomically; an empty queue is REMOVED rather than left as `[]`, so "is anything owed?" is
+// one existsSync on the sweep's hot path.
+function write(id: string, msgs: PendingMessage[]): void {
+  const path = queuePath(id)
+  if (!msgs.length) { try { unlinkSync(path) } catch { /* already gone */ } ; return }
+  mkdirSync(sessionStoreDir(id), { recursive: true })
+  const tmp = `${path}.${process.pid}.tmp`
+  writeFileSync(tmp, JSON.stringify(msgs, null, 2) + '\n')
+  renameSync(tmp, path)
+}
+
+// The enqueue rides the timeline append ([[dispatch]]): the caller holds the session's RECORD lock across
+// both, and the record is written first, so a crash between them leaves a message visible but undelivered —
+// never delivered but unrecorded.
+export function enqueue(id: string, msg: PendingMessage): void {
+  write(id, [...read(id), msg])
+}
+
+export const pendingMessages = (id: string): PendingMessage[] => read(id)
+
+export const owesDelivery = (id: string): boolean => existsSync(queuePath(id))
+
+// Hand over what is owed, in order, exactly once. `insert` reports whether the adapter took the message: only
+// then is the entry dropped. A refusal ENDS the pass with that entry still queued and everything behind it
+// still behind it — order is a property of a conversation, so a message is never skipped to deliver a later
+// one. Returns how many were handed over and how many are still owed.
+export async function drain(
+  id: string,
+  insert: (msg: PendingMessage) => Promise<boolean>,
+  timeoutMs = 5_000,
+): Promise<{ delivered: number; remaining: number }> {
+  const release = await acquire(id, timeoutMs)
+  if (!release) return { delivered: 0, remaining: read(id).length }
+  let delivered = 0
+  try {
+    for (;;) {
+      const queued = read(id)
+      if (!queued.length) return { delivered, remaining: 0 }
+      let ok = false
+      try { ok = await insert(queued[0]) } catch { ok = false }
+      if (!ok) return { delivered, remaining: queued.length }
+      // Re-read before removing: a send that landed while this pass ran appended to the tail, and rewriting a
+      // stale snapshot minus the head would silently drop it.
+      write(id, read(id).filter((m) => m.mid !== queued[0].mid))
+      delivered++
+    }
+  } finally { release() }
+}

package/spec-cli/src/doctor.ts

@@ -1,8 +1,3 @@
-// @@@ spex doctor - the opt-in, read-only project DIAGNOSIS surface ([[doctor]]). Bare doctor composes
-// spec-health findings with the delivery audit: when a user launches their OWN agent with no SpexCode
-// process in the launch, the workflow reaches it only through the files materialize() writes. The audit
-// loops the same HARNESSES adapter materialize uses and catches missing delivery or duplicate discovery.
-// `--contract` and `--conflicts` remain focused representations of that same diagnosis.
 import { existsSync, readFileSync, readdirSync, accessSync, constants } from 'node:fs'
 import { join, dirname, basename } from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -179,8 +174,6 @@ function healthReport(findings: HealthFinding[], adopted: boolean): string[] {
   return lines
 }
 
-// @@@ contractText - the layer-2 payload: the composed `surface:system` bodies, the SAME join materialize()
-// folds into each harness's contract file — so a BYOA agent reads byte-identical guidance.
 function contractText(): { names: string[]; body: string } {
   let cfgs: { name: string; body: string }[] = []
   try { cfgs = loadSystemConfig().map((c) => ({ name: c.name, body: c.body })) } catch { /* tree-less cwd → empty */ }
@@ -223,15 +216,6 @@ function manifestScripts(text: string): string[] {
   return [...out]
 }
 
-// @@@ double-delivery - the SILENT conflict on the OTHER axis from under-delivery: not "did the contract
-// land?" but "did it land TWICE?". A self-launched agent can be reached by BOTH the loose native delivery
-// materialize() writes into the worktree AND a `spexcode` plugin bundle the user installed independently
-// (Claude marketplace) or a stale leftover — doubling every hook (dispatch.sh fires per copy), shadowing
-// skills, confusing the `/` menu. We never sniff payload: every count is by IDENTITY STAMP — a shim's
-// `dispatch.sh` command line (the hook-routing stamp, the same one cleanHarness keys on), a plugin.json
-// `name:"spexcode"` (the bundle stamp), and our own materialized skill NAMES. Per harness we count, on three
-// channels, how many spexcode-stamped copies reach the agent; any channel >1 is a double-delivery conflict.
-
 // a plugin bundle dir found under a harness's plugins root, carrying a spexcode stamp.
 type Bundle = { dir: string; name: string; scope: string; hooksToDispatch: boolean; skillsDir: string }
 

package/spec-cli/src/gateway-auth.ts

@@ -1,16 +1,3 @@
-// @@@ gateway auth - the ONE authorization mechanism of the multi-project gateway ([[gateway-hub]]).
-// Everything about passwords and visitors lives HERE, at the gateway: the project backends stay loopback
-// internal services that never see a credential, a cookie, or a visitor identity. Two signed scopes only:
-// an ADMIN session grants /projects (management) plus every /p/:projectId route; a PROJECT session grants
-// exactly its own /p/:projectId route. A project with no configured password is open; with no admin
-// password, loopback may manage implicitly while non-loopback /projects stays locked.
-//
-// Secrets discipline: password VERIFIERS (scrypt, salted) live only in the per-user private store
-// (~/.spexcode/gateway/auth.json, 0600) — never in a repo, never in a backend record, never plaintext.
-// Session tokens are HMAC-signed claims under a random per-user secret, so they survive a gateway restart
-// with no server-side session table, verified in constant time. Each verifier carries a random `gen` that
-// rotates on every set/clear and is embedded in the tokens it authenticates — changing or clearing a
-// password instantly invalidates every session it minted.
 import { createHmac, createHash, randomBytes, scryptSync, timingSafeEqual } from 'node:crypto'
 import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'

package/spec-cli/src/gateway.ts

@@ -1,8 +1,3 @@
-// @@@ public gateway - the internet face of `spex serve --public`. The supervisor (supervise.ts) and its
-// Hono child stay bound to 127.0.0.1; THIS is the only listener on 0.0.0.0. It terminates TLS, gates every
-// request behind one password (a designed login → signed cookie), serves the built dashboard, and reverse-
-// proxies /api + the terminal WebSocket to the loopback supervisor. Loopback is the trust boundary (local
-// agents hit the supervisor directly, no password); the gateway is the boundary crossed from outside.
 import http from 'node:http'
 import https from 'node:https'
 import net from 'node:net'
@@ -17,10 +12,6 @@ import { loginPage } from './login-page.js'
 import { listenOrExit } from './listen.js'
 import { installConnectionReaper } from './reaper.js'
 
-// @@@ resolvePublicConfig - the cert/gate is a RESOLVED value, never hardcoded. Reads the same precedence
-// chain the spec promises: flag > env > spexcode.json > self-signed default. Returns null when public mode
-// is off (the supervisor then serves plain loopback, unchanged). process.argv carries the `spex serve …`
-// flags since the supervisor runs in the same process as the CLI command.
 export type PublicConfig = { password: string; tls: { cert: string; key: string } | null }
 function argFlag(name: string): string | undefined {
   const i = process.argv.indexOf(`--${name}`)
@@ -82,10 +73,6 @@ function selfSignedCert(): { cert: string; key: string } {
   return { cert: readFileSync(certFile, 'utf8'), key: readFileSync(keyFile, 'utf8') }
 }
 
-// @@@ cookie auth - the gate is a designed login, NOT the browser's Basic dialog. The auth cookie is a
-// keyed HMAC of a constant under a secret DERIVED from the password, so it (a) survives a restart with no
-// server-side session store and (b) reveals nothing about the password. Verified in constant time. The same
-// cookie authorises /api and the WebSocket upgrade — the browser sends it on the same-origin handshake.
 const COOKIE = 'spex_auth'
 function authToken(password: string): string {
   const secret = createHmac('sha256', password).update('spexcode-public-gateway-v1').digest()
@@ -150,20 +137,11 @@ export function startGateway(opts: GatewayOpts): void {
     return serveStatic(req, res, opts.distDir, url)
   }
 
-  // server-side connection reaping ([[spec-cli]] / [[public-mode]]) - the internet-facing gateway is the
-  // public server in public mode, so it carries the SAME reaping as the child: the socket-level
-  // `installConnectionReaper` (reaper.ts), the single owner of the header/idle deadlines — it disables
-  // Node's own overlapping HTTP timeouts, which were measured to race and shadow it (issue #65), so no
-  // timeout options are passed here. Idle keep-alive / slow-loris / never-completing request only; the
-  // gated WS upgrade (handled below) is an active stream and exempt for its lifetime.
   const server = secure
     ? https.createServer({ cert: opts.tls!.cert, key: opts.tls!.key }, handler)
     : http.createServer(handler)
   installConnectionReaper(server)
 
-  // @@@ WS gate - the terminal socket rides an HTTP upgrade. Gate it by the SAME cookie (the browser sends
-  // it on the same-origin handshake), then raw-pipe to the loopback supervisor, replaying the buffered
-  // upgrade request so the child completes the WebSocket handshake. Mirrors supervise.ts's byte pipe.
   server.on('upgrade', (req, socket, head) => {
     if (gated && !isAuthed(req, token, cookieName)) { socket.destroy(); return }
     const up = net.connect(opts.upstreamPort, '127.0.0.1', () => {

package/spec-cli/src/git.ts

@@ -4,6 +4,7 @@ import { readFileSync, readdirSync, statSync, existsSync, writeFileSync, mkdirSy
 import { join, isAbsolute, resolve } from 'node:path'
 import { createHash, randomBytes } from 'node:crypto'
 import { projectRuntimeRoot } from './project-store.js'
+import { rootSlots, touchRoot as touchRootLru } from './root-lru.js'
 
 const US = '\x1f', RS = '\x1e'
 
@@ -152,9 +153,32 @@ export function isGitObjectId(root: string, value: string): boolean {
 // Batch immutable object lookups used by the shared anchor/index path. Git accepts revision:path queries on
 // batch-check, so dozens of rev-parse + cat-file children collapse into two bounded processes without
 // changing the returned bytes or object ids.
-export function batchRevisionOids(root: string, revisions: string[]): (string | null)[] {
+//
+// These are async for two reasons a synchronous execFileSync cannot serve once the caller batches its WHOLE
+// invocation rather than one reading at a time. A sync child is invisible to the build's permit pool and its
+// abort signal, so a watchdog abort could not kill it; and one build-wide `cat-file --batch` reading tens of
+// megabytes would be a single uninterruptible stretch — exactly the /health-blocking shape [[graph-cache]]
+// closed for the fs walks.
+//
+// Chunking is a real output bound, not ceremony: the async transport caps a child's stdout at GIT_MAX_BUFFER
+// and overflow is a loud error. Revision rows are 41 bytes each, so only the blob read (payload-sized) needs
+// a chunk; the cap is on COUNT because sizes are unknown until git answers, and it is set so an ordinary
+// source corpus never approaches the byte ceiling.
+const BATCH_BLOB_CHUNK = 256
+const BATCH_BLOB_MAX_BUFFER = 1 << 26
+async function batchBuffer(args: string[], input: string, maxBuffer?: number): Promise<Buffer> {
+  const env = { ...process.env }
+  delete env.GIT_DIR; delete env.GIT_WORK_TREE; delete env.GIT_INDEX_FILE; delete env.GIT_OBJECT_DIRECTORY
+  try { return (await execGitForCaller(args, env, maxBuffer, input)).stdout }
+  catch (error: any) {
+    if (error?.name === 'AbortError') throw error
+    warnIfTimedOut(error, args)
+    throw new Error(`git ${args.slice(2, 5).join(' ')} failed: ${String(error?.stderr || error?.message || 'unknown git error').trim()}`)
+  }
+}
+export async function batchRevisionOids(root: string, revisions: string[]): Promise<(string | null)[]> {
   if (!revisions.length) return []
-  const out = gitBuffer(['-C', root, 'cat-file', '--batch-check=%(objectname)'], revisions.join('\n') + '\n').toString('utf8')
+  const out = (await batchBuffer(['-C', root, 'cat-file', '--batch-check=%(objectname)'], revisions.join('\n') + '\n')).toString('utf8')
   const lines = out.split('\n')
   if (lines.length - 1 !== revisions.length) throw new Error(`git cat-file --batch-check returned ${lines.length - 1} rows for ${revisions.length} revisions`)
   return revisions.map((revision, index) => {
@@ -164,25 +188,28 @@ export function batchRevisionOids(root: string, revisions: string[]): (string |
     throw new Error(`git cat-file --batch-check returned '${value}' for ${revision}`)
   })
 }
-export function batchBlobTexts(root: string, oids: string[]): Map<string, string> {
+export async function batchBlobTexts(root: string, oids: string[]): Promise<Map<string, string>> {
   const unique = [...new Set(oids.filter(Boolean))]
   const files = new Map<string, string>()
   if (!unique.length) return files
   for (const oid of unique) if (!isGitObjectId(root, oid)) throw new Error(`invalid object id '${oid}'`)
-  const out = gitBuffer(['-C', root, 'cat-file', '--batch'], unique.join('\n') + '\n')
-  let offset = 0
-  for (const oid of unique) {
-    const newline = out.indexOf(10, offset)
-    if (newline < 0) throw new Error(`git cat-file --batch ended before ${oid}`)
-    const header = out.subarray(offset, newline).toString('utf8')
-    const size = Number(header.match(/ blob (\d+)$/)?.[1])
-    if (!header.startsWith(`${oid} blob `) || !Number.isFinite(size)) throw new Error(`git cat-file --batch returned '${header}' for ${oid}`) // dead-words-ok: Git object protocol type
-    const start = newline + 1, end = start + size
-    if (end >= out.length || out[end] !== 0x0a) throw new Error(`git cat-file --batch truncated object ${oid}`)
-    files.set(oid, out.subarray(start, end).toString('utf8'))
-    offset = end + 1
+  for (let cursor = 0; cursor < unique.length; cursor += BATCH_BLOB_CHUNK) {
+    const chunk = unique.slice(cursor, cursor + BATCH_BLOB_CHUNK)
+    const out = await batchBuffer(['-C', root, 'cat-file', '--batch'], chunk.join('\n') + '\n', BATCH_BLOB_MAX_BUFFER)
+    let offset = 0
+    for (const oid of chunk) {
+      const newline = out.indexOf(10, offset)
+      if (newline < 0) throw new Error(`git cat-file --batch ended before ${oid}`)
+      const header = out.subarray(offset, newline).toString('utf8')
+      const size = Number(header.match(/ blob (\d+)$/)?.[1])
+      if (!header.startsWith(`${oid} blob `) || !Number.isFinite(size)) throw new Error(`git cat-file --batch returned '${header}' for ${oid}`) // dead-words-ok: Git object protocol type
+      const start = newline + 1, end = start + size
+      if (end >= out.length || out[end] !== 0x0a) throw new Error(`git cat-file --batch truncated object ${oid}`)
+      files.set(oid, out.subarray(start, end).toString('utf8'))
+      offset = end + 1
+    }
+    if (offset !== out.length) throw new Error(`git cat-file --batch returned ${out.length - offset} unexpected trailing bytes`)
   }
-  if (offset !== out.length) throw new Error(`git cat-file --batch returned ${out.length - offset} unexpected trailing bytes`)
   return files
 }
 
@@ -229,7 +256,9 @@ export function treeFileText(root: string, tip: string, path: string): string |
   catch { return null }
 }
 
-type GitExec = { stdout: string; stderr: string }
+// stdout stays a Buffer to the transport's edge: `cat-file --batch` frames each payload by BYTE length, so
+// a decode before framing mis-slices every object after the first multi-byte character. Text callers decode.
+type GitExec = { stdout: Buffer; stderr: string }
 
 // execFile's AbortSignal kills only its direct child. A wedged adapter may have descendants (the
 // deterministic tests use a shell + sleep), so async git runs in their own process group and abort/timeout
@@ -265,14 +294,21 @@ function execGit(args: string[], env: NodeJS.ProcessEnv, signal?: AbortSignal, m
     child.once('close', (code, childSignal) => {
       clearTimeout(timer)
       signal?.removeEventListener('abort', onAbort)
-      const result = { stdout: Buffer.concat(stdout).toString('utf8'), stderr: Buffer.concat(stderr).toString('utf8') }
+      const result = { stdout: Buffer.concat(stdout), stderr: Buffer.concat(stderr).toString('utf8') }
       if (code === 0 && !aborted && !timedOut && !overflow && !spawnError) { resolve(result); return }
       const error: any = spawnError ?? new Error(overflow
         ? `git output exceeded ${maxBuffer} bytes`
         : `git exited with ${code ?? childSignal ?? 'unknown status'}`)
-      error.code = overflow ? 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER' : code
+      // @@@ a spawn failure keeps its OWN cause - a child that never started still emits `close`, with the
+      // negated errno as its code (EACCES arrives as -13). Overwriting the spawn error's `'EACCES'`/`'ENOENT'`
+      // with that number turns "git could not RUN" into "git ran and exited", and every caller that separates
+      // the two reads the second as a real git answer: the freshness batch concluded "the anchor object is
+      // unreadable", session create concluded "the branch does not exist". A machine where git is missing or
+      // unexecutable would have been told, silently, that the thing it asked about is absent.
+      if (overflow) error.code = 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER'
+      else if (!spawnError) error.code = code
       error.signal = childSignal
-      error.stdout = result.stdout
+      error.stdout = result.stdout.toString('utf8')
       error.stderr = result.stderr
       if (aborted) error.name = 'AbortError'
       if (timedOut) error.spexcodeGitTimeout = true
@@ -326,12 +362,12 @@ function execGitStream(args: string[], env: NodeJS.ProcessEnv, signal?: AbortSig
     child.on('close', (code, childSignal) => {
       if (settled) return
       settled = true; clearTimeout(timer); signal?.removeEventListener('abort', onAbort)
-      const result = { stdout: Buffer.concat(stdout).toString('utf8'), stderr: Buffer.concat(stderr).toString('utf8') }
+      const result = { stdout: Buffer.concat(stdout), stderr: Buffer.concat(stderr).toString('utf8') }
       if (code === 0 && !aborted && !timedOut) { resolve(result); return }
       const error: any = new Error(`git exited with ${code ?? childSignal ?? 'unknown status'}`)
       error.code = code
       error.signal = childSignal
-      error.stdout = result.stdout
+      error.stdout = result.stdout.toString('utf8')
       error.stderr = result.stderr
       if (aborted) error.name = 'AbortError'
       if (timedOut) error.spexcodeGitTimeout = true
@@ -353,7 +389,7 @@ export async function gitA(args: string[], input?: string): Promise<string> {
   const context = inheritedContext()
   try {
     const { stdout } = await execGitForCaller(args, env, undefined, input)
-    return stdout
+    return stdout.toString('utf8')
   } catch (e: any) {
     if (context?.signal.aborted || e?.name === 'AbortError') throw e
     warnIfTimedOut(e, args); return ''
@@ -797,7 +833,7 @@ export async function gitTry(args: string[], options: { indexFile?: string } = {
   const context = inheritedContext()
   try {
     const { stdout, stderr } = await execGitForCaller(args, env)
-    return { ok: true, stdout, stderr }
+    return { ok: true, stdout: stdout.toString('utf8'), stderr }
   } catch (e: any) {
     if (context?.signal.aborted || e?.name === 'AbortError') throw e
     warnIfTimedOut(e, args)
@@ -809,7 +845,7 @@ export async function gitTry(args: string[], options: { indexFile?: string } = {
 export async function gitRequiredA(args: string[], purpose: string): Promise<string> {
   const env = { ...process.env }
   delete env.GIT_DIR; delete env.GIT_WORK_TREE; delete env.GIT_INDEX_FILE; delete env.GIT_OBJECT_DIRECTORY
-  try { return (await execGitStreamForCaller(args, env)).stdout }
+  try { return (await execGitStreamForCaller(args, env)).stdout.toString('utf8') }
   catch (error: any) {
     if (error?.name === 'AbortError') throw error
     warnIfTimedOut(error, args)
@@ -990,7 +1026,7 @@ const indexCache = new Map<string, Promise<HistoryIndex>>()
 const indexRoots = new Map<string, string>()
 const driftRoots = new Map<string, string>()
 const driftIdxCache = new Map<string, Promise<DriftIndex>>()
-const INDEX_ROOT_SLOTS = Math.max(4, Number(process.env.SPEXCODE_INDEX_CACHE_ROOTS || 32))
+const INDEX_ROOT_SLOTS = rootSlots(process.env.SPEXCODE_INDEX_CACHE_ROOTS, 32)
 
 function rootKey(root: string): string { return resolve(root) }
 
@@ -999,23 +1035,9 @@ function indexCacheKey(root: string, head: string): string { return `${eventCach
 // A project-namespaced ledger path plus HEAD identifies immutable index contents. Its path is scoped to the
 // common Git store and interpretation state, so linked worktrees share while independent same-HEAD clones do not.
 // The checkout root owns which live view is useful; the root bound keeps closed worktrees from leaking.
+// The bookkeeping itself is [[root-lru]]'s — this only names the store and the bound.
 function touchRoot(roots: Map<string, string>, cache: Map<string, Promise<unknown>>, root: string, cacheKey: string): void {
-  const key = rootKey(root)
-  const previous = roots.get(key)
-  if (previous !== cacheKey) {
-    roots.set(key, cacheKey)
-    if (previous && ![...roots.values()].includes(previous)) cache.delete(previous)
-  } else {
-    roots.delete(key)
-    roots.set(key, cacheKey)
-  }
-  while (roots.size > INDEX_ROOT_SLOTS) {
-    const oldest = roots.keys().next().value as string | undefined
-    if (oldest === undefined) break
-    const oldHead = roots.get(oldest)
-    roots.delete(oldest)
-    if (oldHead && ![...roots.values()].includes(oldHead)) cache.delete(oldHead)
-  }
+  touchRootLru(roots, cache, rootKey(root), cacheKey, INDEX_ROOT_SLOTS)
 }
 
 function dropFailed(cache: Map<string, Promise<unknown>>, head: string, promise: Promise<unknown>): void {
@@ -1804,9 +1826,10 @@ export function resetHistoryCachesForTests(): void {
   eventPathMemo.clear(); gitObjectFormatMemo.clear()
 }
 export function historyEventCachePathForTests(root: string): string { return eventCacheLocation(root).path }
-// the reachability set of `sha` — itself plus every ancestor — as a bitset over the walk's dense ids.
-// Built once per queried sha by following parent edges in memory (no git fork), memoized on the index;
-// a bitset costs history-length BITS, so hundreds of cached shas stay cheap on the board hot path.
+// @@@ one ordinary ancestry memo, with a batch entrance - every closure below has exactly the same dense
+// bitset shape in idx.anc. A caller that already knows several bases can prime them in one child-to-parent
+// topology pass; the short-lived frontier is released before returning. Unknown or ad-hoc revisions retain
+// this direct parent DFS, so neither path introduces a second reachability representation or persistent fact.
 // undefined when `sha` is not reachable from HEAD (rebased away, an unmerged branch, or never on any
 // ref) — callers apply their own conservative rule to that "can't prove" case.
 export function ancestorsOf(idx: DriftIndex, sha: string): Uint8Array | undefined {
@@ -1830,13 +1853,81 @@ export function ancestorsOf(idx: DriftIndex, sha: string): Uint8Array | undefine
   idx.anc.set(sha, bits)
   return bits
 }
+
+// Fill the existing ancestry memo for a known roster in one child-before-parent topology pass. At each
+// commit the transient row names requested descendants; emitting those bits into the ordinary closures makes
+// the resulting bytes identical to calling ancestorsOf() independently for every requested SHA.
+export function primeAncestorClosures(idx: DriftIndex, shas: Iterable<string>): void {
+  const endpoints = [...new Set(shas)].filter((sha) => !idx.anc.has(sha) && idx.ord.has(sha))
+  if (!endpoints.length) return
+  const count = idx.ord.size
+  const width = (endpoints.length + 7) >> 3
+  const closureWidth = (count + 7) >> 3
+  const endpointAt = new Map(endpoints.map((sha, position) => [sha, position]))
+  const hashAt = new Array<string>(count)
+  for (const [hash, position] of idx.ord) hashAt[position] = hash
+
+  // Every row waits until all of its children have contributed. Parents outside the walked topology are
+  // deliberately absent: they are the same shallow boundary ancestorsOf() stops at.
+  const childrenLeft = new Int32Array(count)
+  for (const parents of idx.parents.values()) for (const parent of parents) {
+    const position = idx.ord.get(parent)
+    if (position !== undefined) childrenLeft[position]++
+  }
+  const ready: number[] = []
+  for (let position = 0; position < count; position++) if (childrenLeft[position] === 0) ready.push(position)
+
+  const closures = endpoints.map(() => new Uint8Array(closureWidth))
+  const rows = new Map<number, Uint8Array>(), pool: Uint8Array[] = []
+  const rowFor = (position: number): Uint8Array => {
+    const existing = rows.get(position)
+    if (existing) return existing
+    const row = pool.pop() ?? new Uint8Array(width)
+    rows.set(position, row)
+    return row
+  }
+  let visited = 0
+  while (ready.length) {
+    const position = ready.pop()!
+    visited++
+    const row = rowFor(position)
+    rows.delete(position)
+    const endpoint = endpointAt.get(hashAt[position])
+    if (endpoint !== undefined) row[endpoint >> 3] |= 1 << (endpoint & 7)
+    for (let byte = 0; byte < width; byte++) {
+      let pending = row[byte]
+      while (pending) {
+        const bit = 31 - Math.clz32(pending & -pending)
+        closures[(byte << 3) + bit][position >> 3] |= 1 << (position & 7)
+        pending &= pending - 1
+      }
+    }
+    for (const parent of idx.parents.get(hashAt[position]) ?? []) {
+      const parentPosition = idx.ord.get(parent)
+      if (parentPosition === undefined) continue
+      const target = rowFor(parentPosition)
+      for (let byte = 0; byte < width; byte++) target[byte] |= row[byte]
+      if (--childrenLeft[parentPosition] === 0) ready.push(parentPosition)
+    }
+    row.fill(0)
+    pool.push(row)
+  }
+  if (visited !== count)
+    throw new Error(`cannot prime ancestry closures: topology yielded ${visited} of ${count} reachable commits`)
+  for (let position = 0; position < endpoints.length; position++) idx.anc.set(endpoints[position], closures[position])
+}
 export function inAncestors(idx: DriftIndex, bits: Uint8Array, sha: string): boolean {
   const o = idx.ord.get(sha)
   return o !== undefined && (bits[o >> 3] & (1 << (o & 7))) !== 0
 }
 
+// @@@ reachability is membership, not a closure - `ancestorsOf` returns undefined for EXACTLY the shas
+// absent from `idx.ord` (both writers of `idx.anc` gate on ord: the single-sha path after its ord lookup
+// succeeds, the batch after an explicit `ord.has` filter), so asking it here answered a hash-table
+// question by walking the whole parent DAG and allocating an ord.size-wide bitset per distinct sha —
+// per eval reading, on every board build.
 export function commitReachable(idx: DriftIndex, sha: string): boolean {
-  return ancestorsOf(idx, sha) !== undefined
+  return idx.ord.has(sha)
 }
 
 // the valid Spec-OK coverage for a node's version commit: `sinceHash` is the node's OWN latest version,
@@ -1891,10 +1982,22 @@ export function pathRangeEvents(idx: DriftIndex, sinceHash: string, path: string
   })
 }
 
-export function driftPathWindow(idx: DriftIndex, sinceHash: string, path: string, nodeId?: string): DriftPathEvent[] | null {
+// @@@ eventsSince - THE meaning of "this path changed since <sha>", in one place. A commit touching `path`
+// lies in `sha..HEAD` exactly when it is NOT an ancestor of `sha` — true DAG reachability, wherever a
+// date-ordered log happens to place it. `null` is the honest third answer: the anchor commit is not reachable
+// (folded, rebased, cherry-picked away), so ancestry cannot testify at all and the caller must decide what to
+// do about that — the spec layer reports no window, the eval layer falls back to comparing content.
+// Callers add their OWN layer's decoration on top (ack cover is spec-only; the content probe is eval-only);
+// what none of them may do is restate the reachability rule, which is how it came to exist four times.
+export function eventsSince(idx: DriftIndex, sinceHash: string, path: string): DriftPathEvent[] | null {
   const base = ancestorsOf(idx, sinceHash)
   if (!base) return null
-  const events = pathEvents(idx, path).filter((event) => !inAncestors(idx, base, event.commit))
+  return pathEvents(idx, path).filter((event) => !inAncestors(idx, base, event.commit))
+}
+
+export function driftPathWindow(idx: DriftIndex, sinceHash: string, path: string, nodeId?: string): DriftPathEvent[] | null {
+  const events = eventsSince(idx, sinceHash, path)
+  if (!events) return null
   const cover = ackCoverFor(idx, sinceHash, nodeId)
   return events.filter((event) => !cover.some((a) => inAncestors(idx, a, event.commit))
       && !selfAckCovers(idx, sinceHash, event.commit, nodeId))

package/spec-cli/src/graph.ts

@@ -2,10 +2,10 @@ import { loadSpecs, deriveStatus } from './specs.js'
 import { resolveLayout } from './layout.js'
 import { listSessions } from './sessions.js'
 import { repoRoot, driftIndex, historyIndex } from './git.js'
-import { residentForgeState } from '../../spec-forge/src/resident.js'
+import { residentForgeRevision, residentForgeState } from '../../spec-forge/src/resident.js'
 import { resolveForgeHost } from '../../spec-forge/src/drivers.js'
 import { boardThreads } from './issues.js'
-import { evalContext, evalTimeline } from '../../spec-eval/src/evaltab.js'
+import { evalContext, evalTimelines } from '../../spec-eval/src/evaltab.js'
 import { evalNodesAsync } from '../../spec-eval/src/scenarios.js'
 import { resolveProjectIdentity } from './project-identity.js'
 import { sessionEvalProjections } from '../../spec-eval/src/sessioneval.js'
@@ -123,7 +123,9 @@ export async function buildBoard() {
   const isOpen = (i: { status: string }) => i.status === 'open'
   // 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))
+  const forgeState = residentForgeState()
+  const forgeRevision = residentForgeRevision()
+  const { issues: merged, stamp: issuesStamp } = boardThreads({ host: resolveForgeHost(), state: forgeState }, 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
@@ -149,15 +151,16 @@ export async function buildBoard() {
   // eval-file walk rides fs/promises ([[graph-cache]]) so it yields the event loop instead of stalling /health.
   const ynodes = await evalNodesAsync(root)
   const ectx = await evalContext(root, specs, idx, hidx, undefined, ynodes)
-  const evalReviewNodes = (await Promise.all(nodes.map(async (n) => {
-    const tl = await evalTimeline(n.id, ectx)
+  const timelines = await evalTimelines(nodes.map((n) => n.id), ectx)
+  const evalReviewNodes = timelines.map((tl, index) => {
+    const n = nodes[index]
     if (!tl.hasEvalFile) return null
     const latest = latestPerScenario(tl.readings)
     n.reviewSummary = { ...(n.reviewSummary || {}), evals: nodeEvalSummary(tl.scenarios, latest) }
     return { id: n.id, hue: n.hue, scenarios: tl.scenarios, evals: latest, readings: tl.readings }
-  }))).filter((node): node is NonNullable<typeof node> => node !== null)
+  }).filter((node): node is NonNullable<typeof node> => node !== null)
 
-  publishReviewSnapshot({ issues: merged, evalNodes: evalReviewNodes })
+  publishReviewSnapshot({ issues: merged, evalNodes: evalReviewNodes, forgeRevision })
 
   const opsByPath: Record<string, any[]> = {}
   opWts.forEach((w) => { opsByPath[w.path] = w.ops })
@@ -198,3 +201,21 @@ export async function spliceSessions(prev: Awaited<ReturnType<typeof buildBoard>
   }))
   return { ...prev, sessions: sess }
 }
+
+// A full producer may finish after the session lane has already shown a newer row. Reuse that published
+// projection on the full topology without another store read: topology owns the current per-path ops, while
+// the published row owns lifecycle/eval fields. This is deliberately synchronous so a full completion never
+// waits for a quiet session store.
+export function rebasePublishedSessions(
+  topology: Awaited<ReturnType<typeof buildBoard>>,
+  published: Awaited<ReturnType<typeof buildBoard>>,
+): Awaited<ReturnType<typeof buildBoard>> {
+  const opsByPath: Record<string, any[]> = {}
+  for (const session of topology.sessions) opsByPath[session.source] = session.ops
+  const sessions = published.sessions.map((session) => ({
+    ...session,
+    source: session.path,
+    ops: rowOps(session, opsByPath),
+  }))
+  return { ...topology, sessions }
+}