spexcode 0.6.0 → 0.6.2

package/spec-cli/src/git.ts

@@ -1,10 +1,11 @@
 import { execFileSync, execFile, spawn } from 'node:child_process'
 import { AsyncLocalStorage } from 'node:async_hooks'
-import { readFileSync, readdirSync, statSync, existsSync, writeFileSync, mkdirSync, rmSync, renameSync, openSync, closeSync } from 'node:fs'
-import { join, isAbsolute, resolve } from 'node:path'
+import { readFileSync, readdirSync, statSync, existsSync, writeFileSync, mkdirSync, rmSync, renameSync, openSync, closeSync, accessSync, constants } from 'node:fs'
+import { join, isAbsolute, resolve, delimiter } from 'node:path'
 import { createHash, randomBytes } from 'node:crypto'
 import { projectRuntimeRoot } from './project-store.js'
 import { rootSlots, touchRoot as touchRootLru } from './root-lru.js'
+import { processStartToken } from './process-identity.js'
 
 const US = '\x1f', RS = '\x1e'
 
@@ -14,7 +15,26 @@ const US = '\x1f', RS = '\x1e'
 // permit pool through AsyncLocalStorage, so corpus-wide Promise.all fanout queues here before spawn rather
 // than materializing one process per worktree/eval. Calls outside that build context remain unconstrained.
 const GIT_TIMEOUT_MS = Number(process.env.SPEXCODE_GIT_TIMEOUT_MS || 120000)
+const GIT_SYNC_MAX_BUFFER = 1 << 27
 export const BOARD_GIT_CONCURRENCY = 4
+const gitByPath = new Map<string, string>()
+
+export function gitBinary(env: NodeJS.ProcessEnv = process.env): string {
+  const path = env.PATH || ''
+  const known = gitByPath.get(path)
+  if (known) {
+    try { accessSync(known, constants.X_OK); return known } catch {}
+  }
+  for (const dir of path.split(delimiter)) {
+    const candidate = resolve(dir || '.', 'git')
+    try {
+      accessSync(candidate, constants.X_OK)
+      gitByPath.set(path, candidate)
+      return candidate
+    } catch {}
+  }
+  throw new Error('git executable not found on PATH')
+}
 type GitPermitPool = { acquire: (signal: AbortSignal) => Promise<() => void> }
 type GitBuildContext = { signal: AbortSignal; permits: GitPermitPool }
 const gitBuild = new AsyncLocalStorage<GitBuildContext>()
@@ -107,7 +127,8 @@ export function currentGitBuildAbortSignal(): AbortSignal | undefined {
   return inheritedContext()?.signal
 }
 function warnIfTimedOut(e: any, args: string[]): void {
-  if (e?.signal === 'SIGKILL') console.warn(`spec-cli: git ${args.slice(0, 6).join(' ')}… killed after ${GIT_TIMEOUT_MS}ms — child never exited`)
+  if (e?.code === 'ETIMEDOUT' || e?.spexcodeGitTimeout === true)
+    console.warn(`spec-cli: git ${args.slice(0, 6).join(' ')}… killed after ${GIT_TIMEOUT_MS}ms — child never exited`)
 }
 
 // strip git's hook-exported env (GIT_DIR etc.) so every call discovers the repo from the filesystem.
@@ -115,7 +136,14 @@ export function git(args: string[]): 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 execFileSync('git', withBuildLimits(args), { encoding: 'utf8', env, stdio: ['ignore', 'pipe', 'pipe'], timeout: GIT_TIMEOUT_MS, killSignal: 'SIGKILL' })
+    return execFileSync(gitBinary(env), withBuildLimits(args), {
+      encoding: 'utf8',
+      env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: GIT_TIMEOUT_MS,
+      killSignal: 'SIGKILL',
+      maxBuffer: GIT_SYNC_MAX_BUFFER,
+    })
   } catch (e: any) { warnIfTimedOut(e, args); throw e }
 }
 
@@ -123,13 +151,13 @@ function gitBuffer(args: string[], input?: string): 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 execFileSync('git', withBuildLimits(args), {
+    return execFileSync(gitBinary(env), withBuildLimits(args), {
       input,
       env,
       stdio: ['pipe', 'pipe', 'pipe'],
       timeout: GIT_TIMEOUT_MS,
       killSignal: 'SIGKILL',
-      maxBuffer: 1 << 27,
+      maxBuffer: GIT_SYNC_MAX_BUFFER,
     })
   } catch (e: any) { warnIfTimedOut(e, args); throw e }
 }
@@ -166,9 +194,10 @@ export function isGitObjectId(root: string, value: string): boolean {
 // 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> {
+async function batchBuffer(args: string[], input: string, maxBuffer?: number, extraEnv: Record<string, string> = {}): 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
+  Object.assign(env, extraEnv)
   try { return (await execGitForCaller(args, env, maxBuffer, input)).stdout }
   catch (error: any) {
     if (error?.name === 'AbortError') throw error
@@ -176,9 +205,10 @@ async function batchBuffer(args: string[], input: string, maxBuffer?: number): P
     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)[]> {
+export async function batchRevisionOids(root: string, revisions: string[], options: { replaceObjects?: boolean } = {}): Promise<(string | null)[]> {
   if (!revisions.length) return []
-  const out = (await batchBuffer(['-C', root, 'cat-file', '--batch-check=%(objectname)'], revisions.join('\n') + '\n')).toString('utf8')
+  const extraEnv: Record<string, string> = options.replaceObjects === false ? { GIT_NO_REPLACE_OBJECTS: '1' } : {}
+  const out = (await batchBuffer(['-C', root, 'cat-file', '--batch-check=%(objectname)'], revisions.join('\n') + '\n', undefined, extraEnv)).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) => {
@@ -267,7 +297,7 @@ const GIT_MAX_BUFFER = 1 << 24
 function execGit(args: string[], env: NodeJS.ProcessEnv, signal?: AbortSignal, maxBuffer = GIT_MAX_BUFFER, input?: string): Promise<GitExec> {
   return new Promise((resolve, reject) => {
     if (signal?.aborted) { reject(gitAbortError()); return }
-    const child = spawn('git', args, { env, detached: true, stdio: [input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'] })
+    const child = spawn(gitBinary(env), args, { env, detached: true, stdio: [input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'] })
     const stdout: Buffer[] = [], stderr: Buffer[] = []
     let stdoutBytes = 0, stderrBytes = 0, aborted = false, timedOut = false, overflow = false
     let spawnError: Error | null = null
@@ -335,12 +365,13 @@ async function execGitForCaller(args: string[], env: NodeJS.ProcessEnv, maxBuffe
 // Event streams are the index input itself and may legitimately exceed execFile's fixed maxBuffer. Read
 // them through spawn so the only bound is the index the caller is intentionally constructing; timeout,
 // cancellation, process-group cleanup and build permits remain identical to the ordinary async transport.
-function execGitStream(args: string[], env: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<GitExec> {
+function execGitStream(args: string[], env: NodeJS.ProcessEnv, signal?: AbortSignal, input?: string): Promise<GitExec> {
   return new Promise((resolve, reject) => {
     if (signal?.aborted) { reject(gitAbortError()); return }
-    const child = spawn('git', args, { env, detached: true, stdio: ['ignore', 'pipe', 'pipe'] })
+    const child = spawn(gitBinary(env), args, { env, detached: true, stdio: [input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'] })
     const stdout: Buffer[] = [], stderr: Buffer[] = []
     let settled = false, aborted = false, timedOut = false
+    let stdinError: any = null
     const killTree = () => {
       if (!child.pid) return
       try { process.kill(-child.pid, 'SIGKILL') } catch { /* group may already be gone */ }
@@ -350,8 +381,14 @@ function execGitStream(args: string[], env: NodeJS.ProcessEnv, signal?: AbortSig
     const timer = setTimeout(() => { timedOut = true; killTree() }, GIT_TIMEOUT_MS)
     timer.unref?.()
     signal?.addEventListener('abort', onAbort, { once: true })
-    child.stdout.on('data', (chunk: Buffer) => stdout.push(chunk))
-    child.stderr.on('data', (chunk: Buffer) => stderr.push(chunk))
+    child.stdout!.on('data', (chunk: Buffer) => stdout.push(chunk))
+    child.stderr!.on('data', (chunk: Buffer) => stderr.push(chunk))
+    if (input !== undefined) {
+      // A command can reject its input before the pipe drains. Keep that write failure on the same close
+      // path as exit and abort failures instead of letting Node raise an unhandled EPIPE.
+      child.stdin!.once('error', (error) => { stdinError ??= error })
+      child.stdin!.end(input)
+    }
     child.on('error', (error: any) => {
       if (settled) return
       settled = true; clearTimeout(timer); signal?.removeEventListener('abort', onAbort)
@@ -363,9 +400,9 @@ function execGitStream(args: string[], env: NodeJS.ProcessEnv, signal?: AbortSig
       if (settled) return
       settled = true; clearTimeout(timer); signal?.removeEventListener('abort', onAbort)
       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
+      if (code === 0 && !aborted && !timedOut && !stdinError) { resolve(result); return }
+      const error: any = stdinError ?? new Error(`git exited with ${code ?? childSignal ?? 'unknown status'}`)
+      error.code = stdinError ? error.code : code
       error.signal = childSignal
       error.stdout = result.stdout.toString('utf8')
       error.stderr = result.stderr
@@ -375,11 +412,11 @@ function execGitStream(args: string[], env: NodeJS.ProcessEnv, signal?: AbortSig
     })
   })
 }
-async function execGitStreamForCaller(args: string[], env: NodeJS.ProcessEnv): Promise<GitExec> {
+async function execGitStreamForCaller(args: string[], env: NodeJS.ProcessEnv, input?: string): Promise<GitExec> {
   const context = inheritedContext()
-  if (!context) return execGitStream(args, env)
+  if (!context) return execGitStream(args, env, undefined, input)
   const release = await context.permits.acquire(context.signal)
-  try { return await execGitStream(withBuildLimits(args), env, context.signal) }
+  try { return await execGitStream(withBuildLimits(args), env, context.signal, input) }
   finally { release() }
 }
 
@@ -396,19 +433,47 @@ export async function gitA(args: string[], input?: string): Promise<string> {
   }
 }
 
+async function gitARequired(args: string[], input?: 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 execGitForCaller(args, env, undefined, input)).stdout.toString('utf8') }
+  catch (error: any) {
+    if (error?.name === 'AbortError') throw error
+    warnIfTimedOut(error, args)
+    throw new Error(`git ${args.slice(2, 6).join(' ')} failed: ${String(error?.stderr || error?.message || 'unknown git error').trim()}`)
+  }
+}
+
 type TextEventRecord = { hash: string; raw: string }
 type IdentityEventRecord = { hash: string; identity: IdentityRawRecord }
 type EventRecord = TextEventRecord | IdentityEventRecord
-type EventCache = { streams: Map<EventStreamKind, Map<string, EventRecord>>; streamTips: Map<EventStreamKind, string[]> }
+export type ImmutableHunkRanges = { after: DiffLineRange[]; before: DiffLineRange[][] }
+type EventCache = {
+  streams: Map<EventStreamKind, Map<string, EventRecord>>
+  streamTips: Map<EventStreamKind, string[]>
+  hunks: Map<string, ImmutableHunkRanges>
+}
 type EventStreamOutput = string | IdentityRawRecord[]
-const EVENT_CACHE_SCHEMA = 'history-events-v15'
+// The schema names both the ledger grammar and its on-disk namespace. A reader that predates a row type
+// must never share a ledger with its writer: it seeds the next namespace from Git instead.
+const EVENT_CACHE_SCHEMA = 'history-events-v16'
+const IMMUTABLE_HUNK_FACT = 'immutable-hunk-v1'
 const EVENT_STREAM_KINDS = ['merge', 'identity-raw'] as const
 type EventStreamKind = typeof EVENT_STREAM_KINDS[number]
-type EventCacheLocation = { path: string; identity: string; objectFormat: GitObjectFormat }
+type EventCacheLocation = { path: string; identity: string; interpretation: string; objectFormat: GitObjectFormat }
 type EventLedgerSnapshot = {
   payload: Buffer
   state: EventCache
 }
+type EventLedgerBuild = {
+  location: EventCacheLocation
+  snapshot: EventLedgerSnapshot
+  additions: string[]
+}
+type EventLedgerDiagnostics = { reads: number; locks: number; replaces: number }
+const eventLedgerBuild = new AsyncLocalStorage<EventLedgerBuild>()
+const eventLedgerDemandPolicy = new AsyncLocalStorage<{ path: string }>()
+const eventLedgerDiagnostics: EventLedgerDiagnostics = { reads: 0, locks: 0, replaces: 0 }
 type EventStreamRequest = {
   kind: EventStreamKind
   argsFor: (base: string) => string[]
@@ -460,20 +525,41 @@ function eventCacheLocation(root: string): EventCacheLocation {
     : git(['-C', root, 'for-each-ref', 'refs/replace', '--format=%(refname) %(objectname)'])
   const objectFormat = gitObjectFormat(root)
   if (old && old.shallow === shallow && old.grafts === grafts && old.replacements === replacements && old.objectFormat === objectFormat)
-    return { path: old.path, identity: old.identity, objectFormat }
-  const identity = createHash('sha256')
+    return { path: old.path, identity: old.identity, interpretation: old.interpretation, objectFormat }
+  const interpretation = createHash('sha256')
     .update(`${EVENT_CACHE_SCHEMA}\0${objectFormat}\0${shallow}\0${grafts}\0${replacements}`)
-    .digest('hex').slice(0, 16)
+    .digest('hex')
+  const identity = interpretation.slice(0, 16)
   // projectRuntimeRoot derives checkout identity from dirname(common). A bare repository is its own common
   // dir, so a synthetic `.git` suffix preserves the repository path instead of collapsing sibling bares.
   const gitDir = gitDirOf(root)
   const storeIdentity = gitDir === root && common === root ? join(common, '.git') : common
   const path = join(projectRuntimeRoot(storeIdentity), `${EVENT_CACHE_SCHEMA}-${identity}.ndjson`)
-  eventPathMemo.set(rootId, { common, shallowPath, grafts, shallow, replacementStorage, replacements, path, identity, objectFormat })
-  return { path, identity, objectFormat }
-}
+  eventPathMemo.set(rootId, { common, shallowPath, grafts, shallow, replacementStorage, replacements, path, identity, interpretation, objectFormat })
+  return { path, identity, interpretation, objectFormat }
+}
+
+// One existing source-of-truth identity governs every Git reader that interprets commit images. Consumers
+// may retain the full digest in memory while the ledger keeps its established short directory name.
+export function gitObjectInterpretation(root: string): {
+  identity: string
+  objectFormat: GitObjectFormat
+  replacements: ReadonlyMap<string, string>
+} {
+  const location = eventCacheLocation(root)
+  const raw = eventPathMemo.get(rootKey(root))?.replacements ?? ''
+  const replacements = new Map<string, string>()
+  for (const line of raw.split('\n').filter(Boolean)) {
+    const match = line.match(/^refs\/replace\/([0-9a-f]+) ([0-9a-f]+)$/)
+    if (!match || !isGitObjectIdForFormat(location.objectFormat, match[1]) || !isGitObjectIdForFormat(location.objectFormat, match[2]))
+      throw new Error(`malformed refs/replace projection '${line}' at ${root}`)
+    replacements.set(match[1], match[2])
+  }
+  return { identity: location.interpretation, objectFormat: location.objectFormat, replacements }
+}
+export function gitInterpretationIdentity(root: string): string { return eventCacheLocation(root).identity }
 function emptyEventCache(): EventCache {
-  return { streams: new Map(), streamTips: new Map() }
+  return { streams: new Map(), streamTips: new Map(), hunks: new Map() }
 }
 function exactKeys(value: Record<string, unknown>, expected: string[]): boolean {
   const actual = Object.keys(value).sort()
@@ -498,6 +584,28 @@ function eventStreamKind(value: unknown): EventStreamKind | null {
     ? value as EventStreamKind
     : null
 }
+function decodeHunkRanges(value: unknown): DiffLineRange[] | null {
+  if (!Array.isArray(value)) return null
+  const ranges: DiffLineRange[] = []
+  for (const row of value) {
+    if (!Array.isArray(row) || row.length !== 2 || !Number.isSafeInteger(row[0]) || !Number.isSafeInteger(row[1])
+      || row[0] <= 0 || row[1] < row[0]) return null
+    ranges.push([row[0], row[1]])
+  }
+  return ranges
+}
+function decodeImmutableHunkFact(row: Record<string, unknown>): { key: string; ranges: ImmutableHunkRanges } | null {
+  if (!exactKeys(row, ['a', 'b', 'i', 'k']) || row.k !== IMMUTABLE_HUNK_FACT || typeof row.i !== 'string' || !row.i) return null
+  const after = decodeHunkRanges(row.a)
+  if (!after || !Array.isArray(row.b)) return null
+  const before: DiffLineRange[][] = []
+  for (const parent of row.b) {
+    const ranges = decodeHunkRanges(parent)
+    if (!ranges) return null
+    before.push(ranges)
+  }
+  return { key: row.i, ranges: { after, before } }
+}
 function decodeEventPayload(payload: Buffer, location: EventCacheLocation): EventCache | null {
   const state = emptyEventCache()
   const text = payload.toString('utf8')
@@ -511,6 +619,12 @@ function decodeEventPayload(payload: Buffer, location: EventCacheLocation): Even
     try { value = JSON.parse(line) } catch { return null }
     if (!value || typeof value !== 'object' || Array.isArray(value)) return null
     const row = value as Record<string, unknown>
+    if (row.k === IMMUTABLE_HUNK_FACT) {
+      const fact = decodeImmutableHunkFact(row)
+      if (!fact || state.hunks.has(fact.key)) return null
+      state.hunks.set(fact.key, fact.ranges)
+      continue
+    }
     if (exactKeys(row, ['k', 'tip'])) {
       const kind = typeof row.k === 'string' && row.k.startsWith('tip:') ? eventStreamKind(row.k.slice(4)) : null
       if (!kind || typeof row.tip !== 'string' || !isGitObjectIdForFormat(location.objectFormat, row.tip)) return null
@@ -545,6 +659,7 @@ function decodeEventPayload(payload: Buffer, location: EventCacheLocation): Even
   return state
 }
 function loadEventLedger(location: EventCacheLocation): EventLedgerSnapshot {
+  eventLedgerDiagnostics.reads++
   let file: Buffer
   try { file = readFileSync(location.path) }
   catch (error: any) {
@@ -572,18 +687,29 @@ function loadEventLedger(location: EventCacheLocation): EventLedgerSnapshot {
   }
 }
 
-type EventLockOwner = { pid: number; token: string }
+type EventLockOwner = { pid: number; startToken: string; nonce: string }
 function readEventLockOwner(lock: string): EventLockOwner | null {
   try {
-    const value = JSON.parse(readFileSync(join(lock, 'owner.json'), 'utf8')) as { pid?: unknown; token?: unknown }
-    return Number.isInteger(value.pid) && (value.pid as number) > 0 && typeof value.token === 'string'
-      ? { pid: value.pid as number, token: value.token }
+    const value = JSON.parse(readFileSync(join(lock, 'owner.json'), 'utf8')) as { pid?: unknown; startToken?: unknown; nonce?: unknown }
+    return Number.isInteger(value.pid) && (value.pid as number) > 0
+      && typeof value.startToken === 'string' && !!value.startToken
+      && typeof value.nonce === 'string' && !!value.nonce
+      ? { pid: value.pid as number, startToken: value.startToken, nonce: value.nonce }
       : null
   } catch { return null }
 }
-function processAlive(pid: number): boolean {
-  try { process.kill(pid, 0); return true }
-  catch (error: any) { return error?.code !== 'ESRCH' }
+const sameEventLockOwner = (left: EventLockOwner | null, right: EventLockOwner | null): boolean =>
+  !!left && !!right && left.pid === right.pid && left.startToken === right.startToken && left.nonce === right.nonce
+
+function eventLockOwnerState(owner: EventLockOwner): 'live' | 'dead' | 'unknown' {
+  try { process.kill(owner.pid, 0) }
+  catch (error: any) {
+    if (error?.code === 'ESRCH') return 'dead'
+    if (error?.code !== 'EPERM') return 'unknown'
+  }
+  const observed = processStartToken(owner.pid)
+  if (!observed) return 'unknown'
+  return observed === owner.startToken ? 'live' : 'dead'
 }
 function retireLockPath(active: string): boolean {
   const inert = `${active}.inert.${process.pid}.${randomBytes(8).toString('hex')}`
@@ -596,14 +722,17 @@ function retireLockPath(active: string): boolean {
   return true
 }
 function reclaimDeadEventLock(lock: string, held: EventLockOwner, claimant: EventLockOwner): boolean {
-  if (processAlive(held.pid)) return false
+  if (eventLockOwnerState(held) !== 'dead') return false
   const reclaim = join(lock, 'reclaim')
   if (existsSync(reclaim)) {
     const reclaimer = readEventLockOwner(reclaim)
-    if (!reclaimer || processAlive(reclaimer.pid)) return false
+    if (!reclaimer) throw new Error(`history event cache lock has an unprovable reclaimer: ${lock}`)
+    const state = eventLockOwnerState(reclaimer)
+    if (state === 'unknown') throw new Error(`history event cache lock reclaimer identity is unreadable: ${lock}`)
+    if (state === 'live') return false
     retireLockPath(reclaim)
   }
-  const prepared = join(lock, `reclaim-${claimant.pid}-${claimant.token}`)
+  const prepared = join(lock, `reclaim-${claimant.pid}-${claimant.nonce}`)
   try {
     mkdirSync(prepared)
     writeFileSync(join(prepared, 'owner.json'), JSON.stringify(claimant))
@@ -614,21 +743,29 @@ function reclaimDeadEventLock(lock: string, held: EventLockOwner, claimant: Even
     throw error
   }
   const current = readEventLockOwner(lock)
-  if (current?.pid !== held.pid || current.token !== held.token || processAlive(current.pid)) {
+  if (!sameEventLockOwner(current, held) || (current && eventLockOwnerState(current) !== 'dead')) {
     retireLockPath(reclaim)
     return false
   }
   return retireLockPath(lock)
 }
-async function withEventCacheLock<T>(path: string, run: () => Promise<T> | T): Promise<T> {
+const EVENT_LEDGER_BUSY = Symbol('event ledger held by a live writer')
+
+async function withEventCacheLock<T>(
+  path: string,
+  run: () => Promise<T> | T,
+  waitForWriter = true,
+): Promise<T | typeof EVENT_LEDGER_BUSY> {
   const lock = `${path}.lock`
   mkdirSync(join(path, '..'), { recursive: true })
-  const owner: EventLockOwner = { pid: process.pid, token: randomBytes(16).toString('hex') }
+  const startToken = processStartToken(process.pid)
+  if (!startToken) throw new Error(`cannot prove history event cache lock claimant identity: ${path}`)
+  const owner: EventLockOwner = { pid: process.pid, startToken, nonce: randomBytes(16).toString('hex') }
   const attempts = Math.max(1, Math.ceil(GIT_TIMEOUT_MS / 5))
   const signal = inheritedContext()?.signal
   for (let attempt = 0; ; attempt++) {
     if (signal?.aborted) throw gitAbortError()
-    const claimant = `${lock}.claim.${owner.pid}.${owner.token}`
+    const claimant = `${lock}.claim.${owner.pid}.${owner.nonce}`
     try {
       mkdirSync(claimant)
       writeFileSync(join(claimant, 'owner.json'), JSON.stringify(owner))
@@ -638,7 +775,30 @@ async function withEventCacheLock<T>(path: string, run: () => Promise<T> | T): P
       rmSync(claimant, { recursive: true, force: true })
       if (error?.code !== 'EEXIST' && error?.code !== 'ENOTEMPTY') throw error
       const held = readEventLockOwner(lock)
-      if (held && reclaimDeadEventLock(lock, held, owner)) continue
+      if (!held) {
+        if (!existsSync(lock)) continue
+        throw new Error(`history event cache lock has no provable exact owner: ${path}`)
+      }
+      const heldState = eventLockOwnerState(held)
+      if (heldState === 'unknown')
+        throw new Error(`history event cache lock owner identity is unreadable: ${path}`)
+      if (heldState === 'dead') {
+        if (reclaimDeadEventLock(lock, held, owner)) continue
+        if (!existsSync(lock)) continue
+      }
+      if (!waitForWriter) {
+        const current = readEventLockOwner(lock)
+        if (!current) {
+          if (!existsSync(lock)) continue
+          throw new Error(`history event cache lock has no provable exact owner: ${path}`)
+        }
+        const state = eventLockOwnerState(current)
+        if (state === 'live') return EVENT_LEDGER_BUSY
+        // A live reclaimer may be arbitrating this exact dead owner. Foreground demand can safely derive
+        // from the atomic snapshot, but must not spin synchronously until that separate lease finishes.
+        if (state === 'dead') return EVENT_LEDGER_BUSY
+        throw new Error(`history event cache lock owner identity is unreadable: ${path}`)
+      }
       if (attempt >= attempts) {
         const heldBy = readEventLockOwner(lock)?.pid
         throw new Error(`timed out waiting for history event cache lock held by ${heldBy ? `pid ${heldBy}` : 'unknown owner'}: ${path}`)
@@ -646,8 +806,9 @@ async function withEventCacheLock<T>(path: string, run: () => Promise<T> | T): P
       await new Promise((resolve) => setTimeout(resolve, 5))
     }
   }
+  eventLedgerDiagnostics.locks++
   try { return await run() } finally {
-    if (readEventLockOwner(lock)?.token === owner.token) retireLockPath(lock)
+    if (sameEventLockOwner(readEventLockOwner(lock), owner)) retireLockPath(lock)
   }
 }
 function removeEventTemps(path: string): void {
@@ -668,12 +829,78 @@ function replaceEventLedger(path: string, payload: Buffer, additions: string[]):
     writeFileSync(fd, eventIntegrityFooter(payload, addition))
     const written = fd; fd = null; closeSync(written)
     renameSync(tmp, path)
+    eventLedgerDiagnostics.replaces++
   } catch (error) {
     if (fd !== null) closeSync(fd)
     rmSync(tmp, { force: true })
     throw error
   }
 }
+const EVENT_LEDGER_RETRY = Symbol('event ledger identity moved')
+
+function activeEventLedger(root: string): EventLedgerBuild | null {
+  const build = eventLedgerBuild.getStore()
+  if (!build) return null
+  return eventCacheLocation(root).path === build.location.path ? build : null
+}
+
+async function runEventLedgerAttempt<T>(
+  root: string,
+  location: EventCacheLocation,
+  run: () => Promise<T>,
+  persist: boolean,
+): Promise<T | typeof EVENT_LEDGER_RETRY> {
+  const build: EventLedgerBuild = { location, snapshot: loadEventLedger(location), additions: [] }
+  const result = await eventLedgerBuild.run(build, run)
+  if (eventCacheLocation(root).identity !== location.identity) return EVENT_LEDGER_RETRY
+  if (persist && build.additions.length) {
+    removeEventTemps(location.path)
+    mkdirSync(join(location.path, '..'), { recursive: true })
+    replaceEventLedger(location.path, build.snapshot.payload, build.additions)
+  }
+  return result
+}
+
+async function eventLedgerTransaction<T>(
+  root: string,
+  run: () => Promise<T>,
+  demand: boolean,
+): Promise<T> {
+  if (activeEventLedger(root)) return run()
+  for (let attempt = 0; attempt < 8; attempt++) {
+    const location = eventCacheLocation(root)
+    const locked = await withEventCacheLock(
+      location.path,
+      () => runEventLedgerAttempt(root, location, run, true),
+      !demand,
+    )
+    const value = locked === EVENT_LEDGER_BUSY
+      ? await runEventLedgerAttempt(root, location, run, false)
+      : locked
+    if (value !== EVENT_LEDGER_RETRY) return value as T
+  }
+  throw new Error('history event cache identity changed repeatedly during one ledger build')
+}
+
+// The event ledger is one build transaction, not one transaction per consumer: stream extraction and
+// immutable hunk derivation share the snapshot, integrity verdict, lock, and final replacement.
+export function withEventLedgerBuild<T>(root: string, run: () => Promise<T>): Promise<T> {
+  const demand = eventLedgerDemandPolicy.getStore()
+  return eventLedgerTransaction(root, run, !!demand && demand.path === eventCacheLocation(root).path)
+}
+
+// Demand is an ambient acquisition POLICY, not an eager lock. Nested ledger consumers therefore use the
+// read-only path under a live writer, while observer waits, revision reads, and stable-cut replay take no lock.
+export function withEventLedgerDemand<T>(root: string, run: () => Promise<T>): Promise<T> {
+  const path = eventCacheLocation(root).path
+  if (eventLedgerDemandPolicy.getStore()?.path === path) return run()
+  return eventLedgerDemandPolicy.run({ path }, run)
+}
+
+export function eventLedgerDiagnosticsForTests(): EventLedgerDiagnostics { return { ...eventLedgerDiagnostics } }
+export function resetEventLedgerDiagnosticsForTests(): void {
+  eventLedgerDiagnostics.reads = 0; eventLedgerDiagnostics.locks = 0; eventLedgerDiagnostics.replaces = 0
+}
 function sortedEventRecords(records: Iterable<EventRecord>, request: EventStreamRequest): EventRecord[] {
   return [...records].filter((record) => request.reachable.has(record.hash))
     .sort((a, b) => (request.order.get(a.hash) ?? Number.MAX_SAFE_INTEGER) - (request.order.get(b.hash) ?? Number.MAX_SAFE_INTEGER))
@@ -711,6 +938,16 @@ function appendEventTip(state: EventCache, kind: EventStreamKind, tip: string, a
   state.streamTips.set(kind, tips)
   additions.push(JSON.stringify({ k: `tip:${kind}`, tip }) + '\n')
 }
+function appendImmutableHunkFact(state: EventCache, key: string, ranges: ImmutableHunkRanges, additions: string[]): void {
+  const existing = state.hunks.get(key)
+  if (existing) {
+    if (JSON.stringify(existing) !== JSON.stringify(ranges))
+      throw new Error(`immutable hunk ledger fact disagrees for image identity ${JSON.stringify(key)}`)
+    return
+  }
+  state.hunks.set(key, ranges)
+  additions.push(JSON.stringify({ k: IMMUTABLE_HUNK_FACT, i: key, a: ranges.after, b: ranges.before }) + '\n')
+}
 function parseEventRecords(out: string, kind: EventStreamKind, location: EventCacheLocation): EventRecord[] {
   if (kind === 'identity-raw') return parseIdentityRawEventRecords(out, location)
   const records: EventRecord[] = []
@@ -771,39 +1008,46 @@ async function deriveEventStreams(
   }
   if (new Set(requests.map((request) => request.kind)).size !== requests.length)
     throw new Error('one event-ledger transaction cannot request the same stream twice')
-
-  const run = async (location: EventCacheLocation): Promise<Map<EventStreamKind, EventStreamOutput> | null> => {
-    const snapshot = loadEventLedger(location)
-    const missing = requests.filter((request) => !(snapshot.state.streamTips.get(request.kind) ?? []).includes(tip))
-    const outputs = await Promise.all(missing.map((request) => {
-      const base = [...(snapshot.state.streamTips.get(request.kind) ?? [])].reverse()
-        .find((candidate) => request.reachable.has(candidate)) ?? ''
-      return strictEventGit(request.argsFor(base))
-    }))
-    if (eventCacheLocation(root).identity !== location.identity) return null
-
-    const additions: string[] = []
-    for (let index = 0; index < missing.length; index++) {
-      const request = missing[index]
-      for (const record of parseEventRecords(outputs[index], request.kind, location))
-        appendEventRecord(snapshot.state, request.kind, record, additions)
-      if (persist) appendEventTip(snapshot.state, request.kind, tip, additions)
-    }
-    if (persist && additions.length) {
-      removeEventTemps(location.path)
-      mkdirSync(join(location.path, '..'), { recursive: true })
-      replaceEventLedger(location.path, snapshot.payload, additions)
-    }
-    return new Map(requests.map((request) => [request.kind, renderEventStream(snapshot.state, request)]))
-  }
-
-  for (let attempt = 0; attempt < 8; attempt++) {
-    const location = eventCacheLocation(root)
-    const result = persist ? await withEventCacheLock(location.path, () => run(location)) : await run(location)
-    if (result) return result
-  }
-  throw new Error(`history event cache identity changed repeatedly while deriving ${tip}`)
+  const build = activeEventLedger(root)
+  if (!build) return withEventLedgerBuild(root, () => deriveEventStreams(root, tip, requests, persist, cache))
+  const { location, snapshot, additions } = build
+  const missing = requests.filter((request) => !(snapshot.state.streamTips.get(request.kind) ?? []).includes(tip))
+  const outputs = await Promise.all(missing.map((request) => {
+    const base = [...(snapshot.state.streamTips.get(request.kind) ?? [])].reverse()
+      .find((candidate) => request.reachable.has(candidate)) ?? ''
+    return strictEventGit(request.argsFor(base))
+  }))
+  for (let index = 0; index < missing.length; index++) {
+    const request = missing[index]
+    for (const record of parseEventRecords(outputs[index], request.kind, location))
+      appendEventRecord(snapshot.state, request.kind, record, additions)
+    if (persist) appendEventTip(snapshot.state, request.kind, tip, additions)
+  }
+  return new Map(requests.map((request) => [request.kind, renderEventStream(snapshot.state, request)]))
+}
+
+// Immutable hunk ranges are a ledger fact, not a second anchor cache: callers name their whole image-key
+// demand, receive only facts the shared ledger already certified, and derive/persist misses in their own read.
+export function readImmutableHunkFacts(root: string, keys: Iterable<string>): Map<string, ImmutableHunkRanges> {
+  const wanted = new Set(keys)
+  if (!wanted.size) return new Map()
+  const build = activeEventLedger(root)
+  if (!build) return new Map()
+  const found = new Map<string, ImmutableHunkRanges>()
+  for (const key of wanted) {
+    const ranges = build.snapshot.state.hunks.get(key)
+    if (ranges) found.set(key, ranges)
+  }
+  return found
+}
+
+export async function persistImmutableHunkFacts(root: string, facts: ReadonlyMap<string, ImmutableHunkRanges>): Promise<void> {
+  if (!facts.size) return
+  const build = activeEventLedger(root)
+  if (!build) return withEventLedgerBuild(root, () => persistImmutableHunkFacts(root, facts))
+  for (const [key, ranges] of facts) appendImmutableHunkFact(build.snapshot.state, key, ranges, build.additions)
 }
+
 async function eventStream(
   root: string,
   tip: string,
@@ -826,13 +1070,17 @@ async function identityRawEventStream(root: string, tip: string, request: EventS
   return value as IdentityRawRecord[]
 }
 export type GitTryFailure = 'exit' | 'spawn' | 'timeout'
-export async function gitTry(args: string[], options: { indexFile?: string } = {}): Promise<{ ok: boolean; stdout: string; stderr: string; failure?: GitTryFailure }> {
+export async function gitTry(args: string[], options: { indexFile?: string; extraEnv?: Record<string, string | undefined>; input?: string } = {}): Promise<{ ok: boolean; stdout: string; stderr: string; failure?: GitTryFailure }> {
   const env = { ...process.env }
+  for (const [key, value] of Object.entries(options.extraEnv ?? {})) {
+    if (value === undefined) delete env[key]
+    else env[key] = value
+  }
   delete env.GIT_DIR; delete env.GIT_WORK_TREE; delete env.GIT_INDEX_FILE; delete env.GIT_OBJECT_DIRECTORY
   if (options.indexFile) env.GIT_INDEX_FILE = options.indexFile
   const context = inheritedContext()
   try {
-    const { stdout, stderr } = await execGitForCaller(args, env)
+    const { stdout, stderr } = await execGitForCaller(args, env, undefined, options.input)
     return { ok: true, stdout: stdout.toString('utf8'), stderr }
   } catch (e: any) {
     if (context?.signal.aborted || e?.name === 'AbortError') throw e
@@ -842,10 +1090,17 @@ export async function gitTry(args: string[], options: { indexFile?: string } = {
   }
 }
 
-export async function gitRequiredA(args: string[], purpose: string): Promise<string> {
+// A walk whose OUTPUT is a projection the caller is intentionally building reads through the streamed
+// transport (no fixed stdout bound); `input` lets its revision roster ride stdin, so argv cannot grow with
+// the roster and needs no chunking.
+export async function gitRequiredA(args: string[], purpose: string, options: { input?: string; extraEnv?: Record<string, string | undefined> } = {}): Promise<string> {
   const env = { ...process.env }
+  for (const [key, value] of Object.entries(options.extraEnv ?? {})) {
+    if (value === undefined) delete env[key]
+    else env[key] = value
+  }
   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.toString('utf8') }
+  try { return (await execGitStreamForCaller(args, env, options.input)).stdout.toString('utf8') }
   catch (error: any) {
     if (error?.name === 'AbortError') throw error
     warnIfTimedOut(error, args)
@@ -1445,6 +1700,15 @@ export type DriftPathEvent = {
   parents: { commit: string; historicalPath: string }[]
 }
 
+// The ancestry substrate the reachability functions below actually read: a topology projection plus its
+// memoized closures. `DriftIndex` is one instance of it (HEAD's history); `unionTopology` builds another for
+// revisions HEAD cannot reach. Sharing the type is what keeps ONE reachability rule for both.
+export type Reachability = {
+  ord: Map<string, number>
+  parents: Map<string, string[]>
+  anc: Map<string, Uint8Array>
+}
+
 export type DiffLineRange = [number, number]
 export type CombinedDiffOwnedChanges = { after: DiffLineRange[]; before: DiffLineRange[][]; parentPaths: string[] }
 
@@ -1832,7 +2096,7 @@ export function historyEventCachePathForTests(root: string): string { return eve
 // 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 {
+export function ancestorsOf(idx: Reachability, sha: string): Uint8Array | undefined {
   const hit = idx.anc.get(sha)
   if (hit) return hit
   const start = idx.ord.get(sha)
@@ -1857,7 +2121,7 @@ export function ancestorsOf(idx: DriftIndex, sha: string): Uint8Array | undefine
 // 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 {
+export function primeAncestorClosures(idx: Reachability, 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
@@ -1916,11 +2180,31 @@ export function primeAncestorClosures(idx: DriftIndex, shas: Iterable<string>):
     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 {
+export function inAncestors(idx: Reachability, bits: Uint8Array, sha: string): boolean {
   const o = idx.ord.get(sha)
   return o !== undefined && (bits[o >> 3] & (1 << (o & 7))) !== 0
 }
 
+// @@@ one walk for a whole roster of revisions, HEAD-reachable or not - the index above projects HEAD's
+// history, so a revision HEAD cannot reach (an unmerged branch, a rebased-away measurement anchor) has NO
+// ancestry there and `ancestorsOf` correctly answers undefined. A caller that needs those revisions' own
+// past gets it from the SAME projection shape, built by one `rev-list --parents` walk over the union of the
+// roster's histories, with the roster on stdin so argv never grows with it. Deliberately a SEPARATE
+// structure, never a graft into the shared index: making off-history tips reachable there would silently
+// switch every ancestry-vs-content decision that keys on `undefined`.
+export async function unionTopology(root: string, revisions: readonly string[]): Promise<Reachability> {
+  const roster = [...new Set(revisions)].filter(Boolean)
+  const reach: Reachability = { ord: new Map(), parents: new Map(), anc: new Map() }
+  if (!roster.length) return reach
+  const out = await gitRequiredA(['-C', root, 'rev-list', '--parents', '--stdin'], 'cannot walk revision topology', {
+    input: roster.map((revision) => `${revision}\n`).join(''),
+    // the roster is already exact object ids; do not reinterpret them if refs/replace moves mid-read.
+    extraEnv: { GIT_NO_REPLACE_OBJECTS: '1' },
+  })
+  const projection = topologyProjection(out)
+  return { ord: projection.order, parents: projection.parents, anc: new Map() }
+}
+
 // @@@ 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
@@ -2060,13 +2344,13 @@ function parseStatPath(token: string): { from: string; to: string } {
   const arrowAt = token.indexOf(' => ')
   return arrowAt >= 0 ? { from: token.slice(0, arrowAt), to: token.slice(arrowAt + 4) } : { from: token, to: token }
 }
-export async function mergeBaseDiff(wtPath: string, mainRef = 'main'): Promise<ReviewDiffFile[]> {
+export async function mergeBaseDiff(wtPath: string, mainRef = 'main', headRef = 'HEAD'): Promise<ReviewDiffFile[]> {
   const run = (args: string[]) => gitA(['-C', wtPath, '-c', 'core.quotePath=false', ...args])
-  const base = (await run(['merge-base', mainRef, 'HEAD'])).trim()
+  const base = (await run(['merge-base', mainRef, headRef])).trim()
   if (!base) return []
   const [numstatOut, statusOut] = await Promise.all([
-    run(['diff', '--numstat', '-M', `${base}..HEAD`]),
-    run(['diff', '--name-status', '-M', `${base}..HEAD`]),
+    run(['diff', '--numstat', '-M', `${base}..${headRef}`]),
+    run(['diff', '--name-status', '-M', `${base}..${headRef}`]),
   ])
   const status = new Map<string, { status: string; from: string }>()
   for (const r of parseNameStatus(statusOut)) status.set(r.to, { status: DIFF_STATUS[r.code] ?? r.code, from: r.from })
@@ -2087,11 +2371,11 @@ export async function mergeBaseDiff(wtPath: string, mainRef = 'main'): Promise<R
   return files
 }
 
-export function mergeConflicts(wtPath: string, mainRef = 'main'): Promise<boolean> {
+export function mergeConflicts(wtPath: string, mainRef = 'main', headRef = 'HEAD'): Promise<boolean> {
   return new Promise((resolve) => {
     const env = { ...process.env }
     delete env.GIT_DIR; delete env.GIT_WORK_TREE; delete env.GIT_INDEX_FILE; delete env.GIT_OBJECT_DIRECTORY
-    execFile('git', ['-C', wtPath, 'merge-tree', '--write-tree', '--no-messages', mainRef, 'HEAD'],
+    execFile(gitBinary(env), ['-C', wtPath, 'merge-tree', '--write-tree', '--no-messages', mainRef, headRef],
       { encoding: 'utf8', env, maxBuffer: 1 << 24 },
       // execFile sets err.code to the numeric EXIT code on a non-zero exit (1 = conflicts), or a string
       // errno (e.g. 'ENOENT') if git can't be spawned — only the exit-1 case is a real conflict verdict.
@@ -2104,19 +2388,7 @@ export function mergeConflicts(wtPath: string, mainRef = 'main'): Promise<boolea
 // spoken: content equal to main is no op, an existing node reads `edited` never `added`) AND have been
 // touched by this branch since its fork point (attribution — main's own post-fork movement is not this
 // worktree's op). A `status --porcelain` pass adds untracked spec.md, a third diff vs HEAD marks committed.
-export async function worktreeSpecDelta(wtPath: string, mainRef: string, baseHint?: string): Promise<NodeOp[]> {
-  const run = (args: string[]) => gitA(['-C', wtPath, '-c', 'core.quotePath=false', ...args])
-  // fork point = where this worktree branched from main; '' (no common ancestor / unreadable ref) falls
-  // back to mainRef so we still surface changes rather than going silent. The caller (cachedDelta) already
-  // computes this same merge-base to key its cache, so it passes it in to avoid a redundant subprocess.
-  const base = baseHint || (await run(['merge-base', mainRef, 'HEAD'])).trim() || mainRef
-  // the four queries are independent — run them in parallel.
-  const [mainOut, workOut, commOut, statusOut] = await Promise.all([
-    run(['diff', '--name-status', '-M', mainRef, '--', '.spec']),
-    run(['diff', '--name-status', '-M', base, '--', '.spec']),
-    run(['diff', '--name-status', '-M', `${base}...HEAD`, '--', '.spec']),
-    run(['status', '--porcelain', '--untracked-files=all', '--', '.spec']),
-  ])
+function projectWorktreeSpecDelta(mainOut: string, workOut: string, commOut: string, statusOut: string): NodeOp[] {
   const proposals = parseNameStatus(mainOut)
   // the branch's own footprint since its fork point — both sides of every row, so a rename matches
   // whichever side the vs-main diff names.
@@ -2140,7 +2412,7 @@ export async function worktreeSpecDelta(wtPath: string, mainRef: string, baseHin
   for (const r of proposals) {
     const path = r.code === 'D' ? r.from : r.to
     if (!isSpecMd(path)) continue
-    if (!touched.has(r.to) && !touched.has(r.from)) continue   // main moved it, not this branch → no op
+    if (!touched.has(r.to) && !touched.has(r.from)) continue
     seen.add(path)
     const op = codeFor[r.code] ?? 'edited'
     ops.push({
@@ -2156,3 +2428,129 @@ export async function worktreeSpecDelta(wtPath: string, mainRef: string, baseHin
   }
   return ops
 }
+
+type WorktreeSpecDemand = { path: string; head: string }
+export type WorktreeSpecDeltaOutcome = { base: string; ops: NodeOp[] } | { error: unknown }
+
+async function boundedMap<T, R>(values: T[], concurrency: number, fn: (value: T) => Promise<R>): Promise<R[]> {
+  const results = new Array<R>(values.length)
+  let next = 0
+  await Promise.all(Array.from({ length: Math.min(concurrency, values.length) }, async () => {
+    while (true) {
+      const index = next++
+      if (index >= values.length) return
+      results[index] = await fn(values[index])
+    }
+  }))
+  return results
+}
+
+// One cold layout demand across many linked worktrees. Merge-base and working-status are path facts, so they
+// stay per worktree under a fixed concurrency. Clean rows then collapse to immutable main→HEAD and base→HEAD
+// pairs in one framed child; dirty rows retain the ordinary worktree-aware projection.
+export async function worktreeSpecDeltas(root: string, mainSha: string, demands: WorktreeSpecDemand[], interpretation = gitInterpretationIdentity(root)): Promise<Map<string, WorktreeSpecDeltaOutcome>> {
+  const results = new Map<string, WorktreeSpecDeltaOutcome>()
+  if (!demands.length) return results
+  if (gitInterpretationIdentity(root) !== interpretation) {
+    const error = new Error('Git interpretation changed before the worktree overlay batch')
+    for (const demand of demands) results.set(demand.path, { error })
+    return results
+  }
+  const prepared = await boundedMap(demands, 4, async (demand) => {
+    try {
+      const run = (args: string[]) => gitARequired(['-C', demand.path, '-c', 'core.quotePath=false', ...args])
+      const [baseOut, statusOut] = await Promise.all([
+        run(['merge-base', mainSha, demand.head]),
+        run(['status', '--porcelain', '--untracked-files=all', '--', '.spec']),
+      ])
+      const base = baseOut.trim()
+      if (!base) throw new Error(`git merge-base returned no base for ${demand.path}`)
+      return { ...demand, base, statusOut }
+    } catch (error) {
+      results.set(demand.path, { error })
+      return null
+    }
+  })
+
+  const clean = prepared.filter((row): row is NonNullable<typeof row> => !!row && row.statusOut.trim() === '')
+  const dirty = prepared.filter((row): row is NonNullable<typeof row> => !!row && row.statusOut.trim() !== '')
+  const pairs: Array<{ from: string; to: string }> = []
+  const pairIndex = new Map<string, number>()
+  const addPair = (from: string, to: string): number => {
+    const key = `${from}\0${to}`
+    const hit = pairIndex.get(key)
+    if (hit != null) return hit
+    const index = pairs.length
+    pairIndex.set(key, index)
+    pairs.push({ from, to })
+    return index
+  }
+  const cleanIndexes = clean.map((row) => ({
+    row,
+    main: addPair(mainSha, row.head),
+    branch: addPair(row.base, row.head),
+  }))
+
+  if (pairs.length) {
+    try {
+      // diff-tree's stdin pair syntax is `<new> <old>`; reverse each ordinary from→to pair deliberately.
+      // --always is load-bearing: it emits a frame for an empty pair, preserving positional ownership.
+      const input = pairs.map(({ from, to }) => `${to} ${from}`).join('\n') + '\n'
+      const out = await gitARequired([
+        '-C', root, '-c', 'core.quotePath=false', 'diff-tree', '--stdin', '--no-commit-id', '--always',
+        '-r', '--name-status', '-M', `--format=${RS}%H`, '--', '.spec',
+      ], input)
+      // For two-tree stdin rows, diff-tree writes that row's name-status payload BEFORE its --format marker.
+      // The first split segment is therefore pair 0; each later pair lives after the previous marker, while
+      // the final marker carries no following pair. Treating markers as openers shifts every non-empty result.
+      const records = out.split(RS)
+      if (records.length - 1 !== pairs.length) throw new Error(`git diff-tree --stdin returned ${records.length - 1} frames for ${pairs.length} pairs`)
+      const frames = pairs.map((_, index) => {
+        if (index === 0) return records[0].split('\n').filter(Boolean).join('\n')
+        const lines = records[index].replace(/^\n/, '').split('\n')
+        lines.shift()
+        return lines.filter(Boolean).join('\n')
+      })
+      for (const { row, main, branch } of cleanIndexes) {
+        results.set(row.path, { base: row.base, ops: projectWorktreeSpecDelta(frames[main], frames[branch], frames[branch], '') })
+      }
+    } catch (error) {
+      for (const { row } of cleanIndexes) results.set(row.path, { error })
+    }
+  }
+
+  await Promise.all(dirty.map(async (row) => {
+    try {
+      const run = (args: string[]) => gitARequired(['-C', row.path, '-c', 'core.quotePath=false', ...args])
+      const [mainOut, workOut, commOut] = await Promise.all([
+        run(['diff', '--name-status', '-M', mainSha, '--', '.spec']),
+        run(['diff', '--name-status', '-M', row.base, '--', '.spec']),
+        run(['diff', '--name-status', '-M', `${row.base}...${row.head}`, '--', '.spec']),
+      ])
+      results.set(row.path, { base: row.base, ops: projectWorktreeSpecDelta(mainOut, workOut, commOut, row.statusOut) })
+    } catch (error) {
+      results.set(row.path, { error })
+    }
+  }))
+  if (gitInterpretationIdentity(root) !== interpretation) {
+    const error = new Error('Git interpretation changed during the worktree overlay batch')
+    for (const demand of demands) results.set(demand.path, { error })
+  }
+  return results
+}
+
+export async function worktreeSpecDelta(wtPath: string, mainRef: string, baseHint?: string): Promise<NodeOp[]> {
+  const run = (args: string[]) => gitA(['-C', wtPath, '-c', 'core.quotePath=false', ...args])
+  // fork point = where this worktree branched from main; '' (no common ancestor / unreadable ref) falls
+  // back to mainRef so we still surface changes rather than going silent. The caller (cachedDelta) already
+  // computes this same merge-base to key its cache, so it passes it in to avoid a redundant subprocess.
+  const base = baseHint || (await run(['merge-base', mainRef, 'HEAD'])).trim() || mainRef
+  // the four queries are independent — run them in parallel.
+  const [mainOut, workOut, commOut, statusOut] = await Promise.all([
+    run(['diff', '--name-status', '-M', mainRef, '--', '.spec']),
+    run(['diff', '--name-status', '-M', base, '--', '.spec']),
+    run(['diff', '--name-status', '-M', `${base}...HEAD`, '--', '.spec']),
+    run(['status', '--porcelain', '--untracked-files=all', '--', '.spec']),
+  ])
+  return projectWorktreeSpecDelta(mainOut, workOut, commOut, statusOut)
+}