spexcode 0.6.0 → 0.6.2

package/spec-cli/src/layout.ts

@@ -1,7 +1,7 @@
 import { readFileSync, existsSync, readdirSync } from 'node:fs'
 import { join, dirname, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { git, repoRoot, gitA, headSha, worktreeSpecSig, worktreeSpecDelta, type NodeOp } from './git.js'
+import { git, repoRoot, gitA, gitAbortError, currentGitBuildAbortSignal, gitInterpretationIdentity, headSha, worktreeSpecSig, worktreeSpecDelta, worktreeSpecDeltas, withGitAbortSignal, type NodeOp } from './git.js'
 import { guardWorktree } from './resilience.js'
 import { HARNESSES, type HarnessId } from './harness.js'
 import { encodeProject, projectRuntimeRoot, spexcodeHome } from './project-store.js'
@@ -170,10 +170,28 @@ export function readUploadPolicy(root: string): UploadPolicy {
 // the shared git common dir (env-stripped git() so a hook's exported GIT_DIR can't misdirect it). Memoized:
 // it's a process constant, but mainBranch()/mainRoot() resolve it per call (~60 git rev-parse forks per board build without the cache).
 let commonDirCache: string | null = null
+const commonDirsByPath = new Map<string, string>()
+const topsByPath = new Map<string, string>()
 export function gitCommonDir(): string {
   if (commonDirCache === null) commonDirCache = git(['rev-parse', '--path-format=absolute', '--git-common-dir']).trim()
   return commonDirCache
 }
+function commonDirFor(proj: string): string {
+  const key = resolve(proj)
+  const known = commonDirsByPath.get(key)
+  if (known) return known
+  const common = git(['-C', proj, 'rev-parse', '--path-format=absolute', '--git-common-dir']).trim()
+  commonDirsByPath.set(key, common)
+  return common
+}
+function topFor(proj: string): string {
+  const key = resolve(proj)
+  const known = topsByPath.get(key)
+  if (known) return known
+  const top = git(['-C', proj, 'rev-parse', '--show-toplevel']).trim()
+  topsByPath.set(key, top)
+  return top
+}
 
 export function mainBranch(): string {
   let checkout: string
@@ -186,9 +204,7 @@ export function mainBranch(): string {
 // `.codex` (codex-rs hooks_config_folder override), NOT the worktree's, so the codex hooks shim + trust
 // materialize here while AGENTS.md/skills stay per-worktree — see [[harness-adapter]] (harness.ts).
 export function mainCheckout(proj?: string): string {
-  const gcd = proj
-    ? git(['-C', proj, 'rev-parse', '--path-format=absolute', '--git-common-dir']).trim()
-    : gitCommonDir()
+  const gcd = proj ? commonDirFor(proj) : gitCommonDir()
   return dirname(gcd)
 }
 
@@ -222,9 +238,7 @@ export function mainRoot(proj?: string): string {
 // proj-aware for `spex init <dir>` / materialize(proj); cwd-based default for the hooks/board. The shell
 // hooks mirror this as hp_runtime_dir.
 export function runtimeRoot(proj?: string): string {
-  const gcd = proj
-    ? git(['-C', proj, 'rev-parse', '--path-format=absolute', '--git-common-dir']).trim()
-    : gitCommonDir()
+  const gcd = proj ? commonDirFor(proj) : gitCommonDir()
   return projectRuntimeRoot(gcd)
 }
 // the per-WORKTREE materialize slot — <runtime>/trees/<enc(worktree-toplevel)> — holding the materialize
@@ -236,7 +250,7 @@ export function runtimeRoot(proj?: string): string {
 // land on the same slot from the same tree, and only from the same tree. Throws when `wt` is not a live
 // git tree (fail loud); a best-effort caller (the close-time GC) wraps it.
 export function treeSlotDir(wt: string): string {
-  const top = git(['-C', wt, 'rev-parse', '--show-toplevel']).trim()
+  const top = topFor(wt)
   return join(runtimeRoot(wt), 'trees', encodeProject(top || wt))
 }
 // this project's per-session records dir, one session's dir, its structured record, and a sibling artifact —
@@ -262,6 +276,7 @@ export type RawRecord = {
   launch_cmd?: string // the RESOLVED base launcher command PINNED at creation, so a resume replays the EXACT launcher (and its config-dir env) that made the conversation, never a since-changed default ([[launcher-select]] resume-launcher-pin); absent → old record, fall back to the launcher name / ambient
   create_request_id?: string // SHA-256 digest of the create Idempotency-Key; the raw key is never persisted
   create_payload_hash?: string // normalized create payload bound to create_request_id
+  base?: string // the exact fork point pinned at creation; absent/empty → the auto-detected source-of-truth branch
   launch_readiness_pending?: '' | RawLaunchReadinessPending
 }
 
@@ -431,6 +446,10 @@ export function readAliasedRawRecord(id: string): RawRecord | null {
 export function readAliasedRecordEntry(id: string): RecordEntry {
   const direct = readRecordEntry(id)
   if (direct.kind !== 'absent') return direct
+  // @@@ absence splits in two, and only one half is an alias question - an id owning a store dir is already
+  // one of ours (the sentinel-only agent above), so its emptiness is settled; searching would let an unrelated
+  // record answer under a live session's own name, and costs a whole-store re-parse per 1s supervisor tick.
+  if (existsSync(sessionStoreDir(id))) return { kind: 'absent' }
   for (const sid of listSessionIds()) {
     const r = readRawRecord(sid)
     if (r && r.harness_session_id && r.harness_session_id === id) return { kind: 'ok', raw: r }
@@ -448,35 +467,113 @@ export function listSessionIds(): string[] {
   return ents.filter((d) => d.isDirectory()).map((d) => d.name)
 }
 
-// memo the overlay (4 git diffs/worktree, all .spec-scoped) keyed on fork-point merge-base + HEAD + spec
-// sig + MAIN'S TIP ([[worktree-linker]]): the main-tip component is what lets a merge landing identical
-// content dissolve a worktree's now-moot ops — the recompute it triggers is cheap because every diff is
-// .spec-scoped.
+// @@@ branch -> session, so a moved ref can DERIVE its invalidation scope - a session's evaluation depends
+// on its own branch tip, the base branch tip and their merge-base; no other ref participates. Without this
+// map a ref watcher knows only that "something under refs/ moved" and the honest fallback is to invalidate
+// every session ([[taste]] 19). One record read per session, and only when the session store itself moved.
+export function sessionBranchIndex(): Map<string, string> {
+  const index = new Map<string, string>()
+  for (const id of listSessionIds()) {
+    let branch: unknown
+    try { branch = readRawRecord(id)?.branch } catch { continue }   // a corrupt record narrows nothing
+    if (typeof branch === 'string' && branch) index.set(branch, id)
+  }
+  return index
+}
+
+// Retain only completed per-worktree overlays. Interpretation + main tip + HEAD + working signature completely
+// determine the merge-base and projection; a landed main tip therefore dissolves now-moot ops on the next read.
 const deltaCache = new Map<string, { key: string; ops: NodeOp[] }>()
 const safeHead = (p: string): string => { try { return headSha(p) } catch { return '' } }
-const safeMergeBase = async (wtPath: string, mainRef: string): Promise<string> => {
-  try { return (await gitA(['-C', wtPath, 'merge-base', mainRef, 'HEAD'])).trim() } catch { return '' }
-}
 let layoutHeadWarned = false
-async function cachedDelta(wtPath: string, mainRef: string, mainSha: string): Promise<NodeOp[]> {
-  const wtHead = safeHead(wtPath)
-  const base = await safeMergeBase(wtPath, mainRef)
-  // fail loud, never stale: if the merge-base, HEAD, or main tip can't be read the key is untrustworthy —
-  // bypass the cache and recompute (warn once) rather than risk serving a delta keyed on an empty sha
-  // across a real change.
-  if (!base || !wtHead || !mainSha) {
-    if (!layoutHeadWarned) { layoutHeadWarned = true; console.warn('spec-cli: layout overlay cache bypassed (unreadable merge-base/HEAD/main tip), recomputing every read') }
-    return worktreeSpecDelta(wtPath, mainRef)
+type LayoutDeltaOutcome = { ops: NodeOp[] } | { error: unknown }
+type LayoutDeltaFlight = {
+  promise: Promise<Map<string, LayoutDeltaOutcome>>
+  controller: AbortController
+  waiters: Set<symbol>
+  settled: boolean
+}
+const layoutDeltaFlights = new Map<string, LayoutDeltaFlight>()
+
+// One exact public layout generation owns the cold overlay computation. The map is only an in-flight join:
+// the entry is deleted at settlement and deltaCache remains the sole retained result state.
+async function layoutDeltas(paths: string[], main: string, mainRef: string, mainSha: string): Promise<Map<string, LayoutDeltaOutcome>> {
+  const snapshots = paths.map((path) => ({ path, head: safeHead(path), sig: worktreeSpecSig(path) }))
+  const interpretation = gitInterpretationIdentity(main)
+  const flightKey = JSON.stringify([interpretation, mainRef, mainSha, snapshots.map(({ path, head, sig }) => [path, head, sig]).sort((a, b) => a[0].localeCompare(b[0]))])
+  let flight = layoutDeltaFlights.get(flightKey)
+  if (flight?.controller.signal.aborted) {
+    layoutDeltaFlights.delete(flightKey)
+    flight = undefined
+  }
+  if (!flight) {
+    const controller = new AbortController()
+    const entry: LayoutDeltaFlight = { promise: Promise.resolve(new Map()), controller, waiters: new Set(), settled: false }
+    entry.promise = withGitAbortSignal(controller.signal, async () => {
+    const outcomes = new Map<string, LayoutDeltaOutcome>()
+    const misses: typeof snapshots = []
+    for (const snapshot of snapshots) {
+      const key = `${interpretation}\0${mainSha}\0${snapshot.head}\0${snapshot.sig}`
+      const hit = snapshot.head && mainSha ? deltaCache.get(snapshot.path) : null
+      if (hit?.key === key) outcomes.set(snapshot.path, { ops: hit.ops })
+      else misses.push(snapshot)
+    }
+
+    const valid = misses.filter(({ head }) => !!head && !!mainSha)
+    const batched = await worktreeSpecDeltas(main, mainSha, valid.map(({ path, head }) => ({ path, head })), interpretation)
+    for (const snapshot of valid) {
+      const outcome = batched.get(snapshot.path) ?? { error: new Error(`layout overlay batch omitted ${snapshot.path}`) }
+      if ('error' in outcome) outcomes.set(snapshot.path, outcome)
+      else {
+        const key = `${interpretation}\0${mainSha}\0${snapshot.head}\0${snapshot.sig}`
+        deltaCache.set(snapshot.path, { key, ops: outcome.ops })
+        outcomes.set(snapshot.path, { ops: outcome.ops })
+      }
+    }
+
+    await Promise.all(misses.filter(({ head }) => !head || !mainSha).map(async (snapshot) => {
+      if (!existsSync(snapshot.path)) {
+        outcomes.set(snapshot.path, { error: new Error(`worktree ${snapshot.path} is absent`) })
+        return
+      }
+      if (!layoutHeadWarned) {
+        layoutHeadWarned = true
+        console.warn('spec-cli: layout overlay cache bypassed (unreadable HEAD/main tip), recomputing every read')
+      }
+      try { outcomes.set(snapshot.path, { ops: await worktreeSpecDelta(snapshot.path, mainRef) }) }
+      catch (error) { outcomes.set(snapshot.path, { error }) }
+    }))
+    return outcomes
+    }).finally(() => {
+      entry.settled = true
+      if (layoutDeltaFlights.get(flightKey) === entry) layoutDeltaFlights.delete(flightKey)
+    })
+    layoutDeltaFlights.set(flightKey, entry)
+    flight = entry
+  }
+
+  const token = Symbol(flightKey)
+  const callerSignal = currentGitBuildAbortSignal()
+  flight.waiters.add(token)
+  let onAbort: (() => void) | null = null
+  try {
+    if (!callerSignal) return await flight.promise
+    if (callerSignal.aborted) throw gitAbortError()
+    return await Promise.race([
+      flight.promise,
+      new Promise<Map<string, LayoutDeltaOutcome>>((_, reject) => {
+        onAbort = () => reject(gitAbortError())
+        callerSignal.addEventListener('abort', onAbort, { once: true })
+      }),
+    ])
+  } finally {
+    if (onAbort) callerSignal?.removeEventListener('abort', onAbort)
+    flight.waiters.delete(token)
+    if (!flight.settled && flight.waiters.size === 0) flight.controller.abort()
   }
-  const key = `${base}\0${wtHead}\0${mainSha}\0${worktreeSpecSig(wtPath)}`
-  const hit = deltaCache.get(wtPath)
-  if (hit && hit.key === key) return hit.ops
-  const ops = await worktreeSpecDelta(wtPath, mainRef, base)
-  deltaCache.set(wtPath, { key, ops })
-  return ops
 }
 
-export async function resolveLayout(): Promise<Layout> {
+export async function resolveLayout(options: { activeSessionIds?: readonly string[] } = {}): Promise<Layout> {
   const root = repoRoot()
   const main = dirname(gitCommonDir())   // the main checkout — same answer from main OR any linked worktree
   const cfg = readConfig(main)
@@ -496,22 +593,36 @@ export async function resolveLayout(): Promise<Layout> {
   const publicEntries = listSessionIds().map((id) => readPublicRecordEntry(id))
     .filter((entry) => entry.kind === 'corrupt' ? entry.governed !== false : entry.kind === 'ok' && entry.raw.governed)
   const records = publicEntries.flatMap((entry) => entry.kind === 'ok' ? [entry] : [])
+  const projectedActive = options.activeSessionIds ? new Set(options.activeSessionIds) : null
+  const isActive = (record: RawRecord): boolean => projectedActive
+    ? projectedActive.has(record.session_id)
+    : !record.archived
   // main's tip, resolved ONCE per board read — a component of every worktree's overlay cache key
   // ([[worktree-linker]]: landed content must dissolve the ops it made moot).
   const mainSha = await (async () => {
     try { return (await gitA(['-C', main, 'rev-parse', '--verify', `${mainRef}^{commit}`])).trim() } catch { return '' }
   })()
+  const activePaths = records.filter(({ raw }) => isActive(raw)).map(({ raw }) => raw.worktree_path)
+  const deltas = await layoutDeltas(activePaths, main, mainRef, mainSha)
   const rows = await Promise.all(records.map(({ raw: r, liveness }) => {
     const node = r.node ?? (r.branch && r.branch.startsWith(convention.branchPrefix) ? r.branch.slice(convention.branchPrefix.length) : null)
     const base: Worktree = { path: r.worktree_path, branch: r.branch, node, session: r.session_id, status: r.status, isMain: false, ...(liveness ? { liveness } : {}), ops: [] }
-    // @@@ archived rows cost nothing - a shelved session ([[archive]]) keeps its row (the record is the
-    // existence truth) but skips the per-worktree spec-delta entirely: that git-history probe is the board's
-    // dominant per-row cost, and shelving is exactly the human saying "stop spending attention here". So the
-    // price of a retained archive is one enumerated record, NOT a git walk per poll.
-    if (r.archived) return Promise.resolve(base)
+    // @@@ projected shelves cost nothing - a cold archived session ([[archive]]) keeps its record but leaves
+    // the working-set projection and skips the per-worktree spec delta. An archived runtime hazard is still
+    // projected active by listSessions, so it deliberately retains the same ops in both full and splice builds.
+    if (!isActive(r)) return Promise.resolve(base)
     return guardWorktree<Worktree>(r.worktree_path,
-      async (): Promise<Worktree> => ({ ...base, ops: await cachedDelta(r.worktree_path, mainRef, mainSha) }),
-      (): Worktree => ({ ...base, ops: deltaCache.get(r.worktree_path)?.ops ?? [] }))
+      (): Worktree => {
+        const outcome = deltas.get(r.worktree_path)
+        if (!outcome) throw new Error(`layout overlay missing ${r.worktree_path}`)
+        if ('error' in outcome) throw outcome.error
+        return { ...base, ops: outcome.ops }
+      },
+      (): Worktree => {
+        const cached = deltaCache.get(r.worktree_path)
+        if (!cached) throw new Error(`layout overlay failed before ${r.worktree_path} had a last-known result`)
+        return { ...base, ops: cached.ops }
+      })
   }))
   const corruptRows: Worktree[] = publicEntries.flatMap((entry) => entry.kind === 'corrupt'
     ? [{ path: '', branch: null, node: null, session: entry.sessionId, status: 'corrupt', liveness: 'unknown', isMain: false, ops: [] }]
@@ -521,9 +632,9 @@ export async function resolveLayout(): Promise<Layout> {
   const mainRow: Worktree = { path: main, branch: base, node: null, session: null, status: null, isMain: true, ops: [] }
   const worktrees = [mainRow, ...sessionWorktrees]
   // drop cache entries for worktrees that may no longer hold one — closed sessions (gone from the store) AND
-  // newly-archived ones (which no longer compute a delta), so archiving SELF-EVICTS its cached ops instead of
+  // newly-cold archived ones (which no longer compute a delta), so archiving SELF-EVICTS its cached ops instead of
   // stranding them in a map nothing prunes.
-  const live = new Set(records.filter(({ raw }) => !raw.archived).map(({ raw }) => raw.worktree_path))
+  const live = new Set(records.filter(({ raw }) => isActive(raw)).map(({ raw }) => raw.worktree_path))
   for (const k of [...deltaCache.keys()]) if (!live.has(k)) deltaCache.delete(k)
   return { main: convention.main || main || root, convention, worktrees }
 }

package/spec-cli/src/lint.ts

@@ -1,12 +1,20 @@
 import { readFileSync, existsSync, statSync } from 'node:fs'
 import { join } from 'node:path'
-import { repoRoot, git, sourceIndexes, rowsFor, treeFilePaths, treeFileText, type DriftPathEvent } from './git.js'
+import { repoRoot, git, sourceIndexes, rowsFor, treeFilePaths, treeFileText, withEventLedgerBuild, type DriftPathEvent } from './git.js'
 import { loadSpecs, parseFrontmatter } from './specs.js'
 import { readJsonConfig } from './layout.js'
 import { extractors, extractorFor, extOf, parseCodeEntry, relationClaimsPath, resolveAnchor, resolveSelectors, windowEvents, anchorHitQueries } from './anchors.js'
 import { DEFAULT_TEST_GLOBS, sourcePolicyDescription, trackedSourceFiles } from './source-files.js'
 
 export type Finding = { level: 'error' | 'warn'; rule: string; spec?: string; file?: string; msg: string }
+export const SPEC_LINT_REPORT_PROJECTION = 'spex.spec-lint.report'
+export const SPEC_LINT_REPORT_SCHEMA_VERSION = 1
+export type SpecLintReport = {
+  projection: typeof SPEC_LINT_REPORT_PROJECTION
+  schemaVersion: typeof SPEC_LINT_REPORT_SCHEMA_VERSION
+  sourceFiles: string[]
+  findings: Finding[]
+}
 
 export type LintConfig = {
   governedRoots: string[]       // dirs whose tracked source files must each be governed by a spec. '.' = whole project.
@@ -69,6 +77,7 @@ export function normalizeConfig(cfg: LintConfig): LintConfig {
 }
 
 export type SpecLintOptions = { tip?: string }
+type SpecLintRun = { sourceFiles: string[]; findings: Finding[] }
 
 function untrackedAdoptionFiles(root: string): string[] {
   if (git(['-C', root, 'rev-parse', '--is-inside-work-tree']).trim() !== 'true') return []
@@ -126,6 +135,24 @@ export async function pendingTouchesGoverned(root: string, tip: string): Promise
 }
 
 export async function specLint(root = repoRoot(), regs = extractors(root), options: SpecLintOptions = {}): Promise<Finding[]> {
+  return (await specLintRun(root, regs, options)).findings
+}
+
+export async function specLintReport(root = repoRoot(), regs = extractors(root), options: SpecLintOptions = {}): Promise<SpecLintReport> {
+  const run = await specLintRun(root, regs, options)
+  return {
+    projection: SPEC_LINT_REPORT_PROJECTION,
+    schemaVersion: SPEC_LINT_REPORT_SCHEMA_VERSION,
+    sourceFiles: run.sourceFiles,
+    findings: run.findings,
+  }
+}
+
+function specLintRun(root: string, regs: ReturnType<typeof extractors>, options: SpecLintOptions): Promise<SpecLintRun> {
+  return withEventLedgerBuild(root, () => specLintInLedger(root, regs, options))
+}
+
+async function specLintInLedger(root: string, regs: ReturnType<typeof extractors>, options: SpecLintOptions): Promise<SpecLintRun> {
   const tip = options.tip ?? 'HEAD'
   const pending = tip !== 'HEAD'
   const changed = pending ? pendingChangedPaths(root, tip) : []
@@ -145,11 +172,14 @@ export async function specLint(root = repoRoot(), regs = extractors(root), optio
   if (untracked.length) {
     const shown = untracked.slice(0, 6)
     const suffix = untracked.length > shown.length ? ` (+${untracked.length - shown.length} more)` : ''
-    return [{
-      level: 'error',
-      rule: 'integrity',
-      msg: `project source of truth is untracked: ${shown.join(', ')}${suffix} — add it with \`git add .spec spexcode.json\` and commit it; generated harness files such as .codex/, .claude/, and AGENTS.md are machine-local`,
-    }]
+    return {
+      sourceFiles: [],
+      findings: [{
+        level: 'error',
+        rule: 'integrity',
+        msg: `project source of truth is untracked: ${shown.join(', ')}${suffix} — add it with \`git add .spec spexcode.json\` and commit it; generated harness files such as .codex/, .claude/, and AGENTS.md are machine-local`,
+      }],
+    }
   }
   const governed = trackedSourceFiles(root, cfg.governedRoots, cfg, tip)
   const [hidx, didx] = await sourceIndexes(root, tip)
@@ -436,7 +466,7 @@ export async function specLint(root = repoRoot(), regs = extractors(root), optio
     out.push({ level: 'warn', rule: 'related-drift', msg: `${rd.length} related file(s) across ${byNode.size} node(s) drifted ahead of their spec (SOFT — a dependency shifted, worth a glance; never blocks, no ack, no eval staleness). Most: ${worst}` })
   }
 
-  return out
+  return { sourceFiles: governed.slice().sort(), findings: out }
 }
 
 export const DRIFT_GUIDANCE = `DRIFT — a governed file has moved ahead of its spec. A CHECKPOINT, not a chore: find WHERE the truth