spexcode 0.6.0 → 0.6.1

package/spec-cli/src/materialize.ts

@@ -5,11 +5,12 @@ import { execFileSync } from 'node:child_process'
 import { loadSystemConfig, loadSkillConfig, loadAgentConfig, loadConfig } from './specs.js'
 import { compileManifest } from './hooks.js'
 import { writeManagedBlock, removeManagedBlock, HARNESSES, type HarnessArtifacts } from './harness.js'
-import { git } from './git.js'
-import { runtimeRoot, treeSlotDir, mainCheckout, readConfig, encodeProject } from './layout.js'
+import { git, gitBinary } from './git.js'
+import { runtimeRoot, treeSlotDir, mainCheckout, readConfig } from './layout.js'
 import { resolveHarnessTargets, partitionHarnesses } from './harness-select.js'
 import { emitPlugin, cleanPlugin, pluginBundleDir, pluginVersion } from './plugin-harness.js'
-import { plantContractFilter, removeContractFilter, retireLegacyContractBlock, settleIndexStat, type ContractFilterBinding, type ContractFilterPayload } from './contract-filter.js'
+import { clearContractFilterPayload, contractFilterPlanted, plantContractFilter, removeContractFilter, settleIndexStat, type ContractFilterBinding, type ContractFilterPayload } from './contract-filter.js'
+import { writeFileIfChanged } from './file-write.js'
 
 export type MaterializedArtifact = {
   kind: 'hook manifest' | 'contract' | 'shim' | 'skill' | 'agent' | 'plugin bundle' | 'trust'
@@ -37,7 +38,9 @@ const SPEX = join(PKG, 'bin', 'spex.mjs')
 export function contentHash(proj: string): string {
   try {
     const harnessSh = join(PKG, 'hooks', 'harness.sh')
-    return execFileSync('bash', ['-c', `cd "${proj}" && . "${harnessSh}" && hp_config_hash`]).toString().trim()
+    const gitDir = dirname(gitBinary(process.env))
+    const env = { ...process.env, PATH: `${gitDir}:${process.env.PATH || ''}` }
+    return execFileSync('bash', ['-c', `cd "${proj}" && . "${harnessSh}" && hp_config_hash`], { env }).toString().trim()
   } catch { return '' }
 }
 
@@ -61,34 +64,22 @@ function infoExcludePath(proj: string): string {
 function isTracked(proj: string, file: string): boolean {
   try { git(['-C', proj, 'ls-files', '--error-unmatch', file]); return true } catch { return false }
 }
+function clearSkipWorktree(proj: string, file: string): void {
+  if (!isTracked(proj, file)) return
+  try { git(['-C', proj, 'update-index', '--no-skip-worktree', file]) } catch {}
+}
 
 function registeredTrees(proj: string): string[] {
   const rows = git(['-C', mainCheckout(proj), 'worktree', 'list', '--porcelain', '-z']).split('\0')
   return rows.filter((row) => row.startsWith('worktree ')).map((row) => row.slice('worktree '.length))
 }
 
-const TREE_IGNORE_RECEIPT = 'tree-ignore-v1'
-
-function hasLegacyTreeIgnore(proj: string): boolean {
-  return registeredTrees(proj).some((tree) => {
-    const slot = join(runtimeRoot(proj), 'trees', encodeProject(tree))
-    return existsSync(join(slot, 'content-hash')) && !existsSync(join(slot, TREE_IGNORE_RECEIPT))
-  })
-}
-
-function managedExcludeEntries(file: string): string[] {
-  if (!existsSync(file)) return []
-  const lines = readFileSync(file, 'utf8').split('\n')
-  const start = lines.indexOf('# spexcode:start')
-  const end = lines.indexOf('# spexcode:end', start + 1)
-  return start >= 0 && end > start ? lines.slice(start + 1, end).filter(Boolean) : []
-}
-
 function selectionBody(selected: typeof HARNESSES, plugin = false): string {
   return [...new Set([...selected.map((h) => h.dispatchId), ...(plugin ? ['plugin'] : [])])].sort().join('\n') + '\n'
 }
 
 function publishSelection(path: string, body: string): void {
+  try { if (readFileSync(path, 'utf8') === body) return } catch (error: any) { if (error?.code !== 'ENOENT') throw error }
   const prepared = `${path}.${process.pid}.tmp`
   writeFileSync(prepared, body)
   renameSync(prepared, path)
@@ -108,46 +99,96 @@ function hostContentOf(file: string): string {
   if (!existsSync(file)) return ''
   return stripSpexcodeBlock(readFileSync(file, 'utf8'))
 }
-// clear a legacy skip-worktree bit (the retired private-overlay mechanism; erase-only now — nothing asserts
-// it). Best-effort: an index race or a non-repo must not fail the materialize.
-function clearSkipWorktree(proj: string, file: string): void {
-  if (!isTracked(proj, file)) return
-  try { git(['-C', proj, 'update-index', '--no-skip-worktree', file]) } catch { /* best-effort */ }
-}
-
 // the identity stamp on every generated skill/agent file — what lets the erase phase forget a product whose
 // NODE was renamed or deleted (the name-scoped sweep can only reconstruct paths the LIVE config still names).
 export const GENERATED_MARK = '<!-- spexcode:generated -->'
-function sweepGeneratedSkills(dir: string | null): void {
-  if (!dir || !existsSync(dir)) return
+function pruneGeneratedSkills(dir: string | null, keep: ReadonlySet<string>): boolean {
+  if (!dir || !existsSync(dir)) return false
+  let changed = false
   for (const e of readdirSync(dir, { withFileTypes: true })) {
     if (!e.isDirectory()) continue
     const f = join(dir, e.name, 'SKILL.md')
-    try { if (existsSync(f) && readFileSync(f, 'utf8').includes(GENERATED_MARK)) rmSync(join(dir, e.name), { recursive: true, force: true }) } catch { /* unreadable → not provably ours */ }
+    try {
+      if (!keep.has(e.name) && existsSync(f) && readFileSync(f, 'utf8').includes(GENERATED_MARK)) {
+        rmSync(join(dir, e.name), { recursive: true, force: true })
+        changed = true
+      }
+    } catch { /* unreadable → not provably ours */ }
   }
+  return changed
 }
-function sweepGeneratedAgents(dir: string | null): void {
-  if (!dir || !existsSync(dir)) return
+function pruneGeneratedAgents(dir: string | null, keep: ReadonlySet<string>): boolean {
+  if (!dir || !existsSync(dir)) return false
+  let changed = false
   for (const e of readdirSync(dir, { withFileTypes: true })) {
     if (!e.isFile() || !e.name.endsWith('.md')) continue
     const f = join(dir, e.name)
-    try { if (readFileSync(f, 'utf8').includes(GENERATED_MARK)) rmSync(f, { force: true }) } catch { /* unreadable → not provably ours */ }
+    try {
+      if (!keep.has(e.name.slice(0, -3)) && readFileSync(f, 'utf8').includes(GENERATED_MARK)) {
+        rmSync(f, { force: true })
+        changed = true
+      }
+    } catch { /* unreadable → not provably ours */ }
+  }
+  return changed
+}
+
+type TreeTargets = {
+  contracts: ReadonlySet<string>
+  treeShims: ReadonlySet<string>
+  anchors: ReadonlySet<string>
+  skills: ReadonlyMap<string, ReadonlySet<string>>
+  agents: ReadonlyMap<string, ReadonlySet<string>>
+}
+
+function cleanupHarnessDirs(proj: string): void {
+  const roots = new Set([proj, mainCheckout(proj)])
+  const dirs = HARNESSES.flatMap((h) => {
+    const anchor = h.worktreeHookAnchor(proj)
+    return [h.skillDir(proj), h.agentDir(proj), dirname(h.shimFile(proj)), anchor ? dirname(anchor) : null]
+  }).filter((d): d is string => !!d)
+  for (const d of [...new Set([...dirs, ...dirs.map((dir) => dirname(dir))])]
+    .filter((dir) => !roots.has(dir)).sort((a, b) => b.length - a.length)) {
+    try { rmdirSync(d) } catch {}
   }
 }
 
+function reconcileTree(proj: string, targets: TreeTargets, tracked: (file: string) => boolean): void {
+  let removed = false
+  const contractFiles = new Set(HARNESSES.flatMap((h) => h.contractFiles(proj)))
+  for (const file of contractFiles) {
+    if (targets.contracts.has(file) || !existsSync(file)) continue
+    const text = readFileSync(file, 'utf8')
+    if (!text.includes('<!-- spexcode:start -->')) continue
+    removeManagedBlock(file, ['<!-- ', ' -->'], !tracked(file))
+    removed = true
+  }
+  const treeShims = new Set(HARNESSES.filter((h) => h.shimScope === 'tree').map((h) => h.shimFile(proj)))
+  const anchors = new Set(HARNESSES.map((h) => h.worktreeHookAnchor(proj)).filter((path): path is string => !!path))
+  for (const file of [...treeShims, ...anchors]) {
+    if (targets.treeShims.has(file) || targets.anchors.has(file) || !existsSync(file)) continue
+    if (readFileSync(file, 'utf8').includes('dispatch.sh')) { rmSync(file, { force: true }); removed = true }
+  }
+  for (const dir of new Set(HARNESSES.map((h) => h.skillDir(proj)).filter((path): path is string => !!path)))
+    removed = pruneGeneratedSkills(dir, targets.skills.get(dir) ?? new Set()) || removed
+  for (const dir of new Set(HARNESSES.map((h) => h.agentDir(proj)).filter((path): path is string => !!path)))
+    removed = pruneGeneratedAgents(dir, targets.agents.get(dir) ?? new Set()) || removed
+  if (removed) cleanupHarnessDirs(proj)
+}
+
 function eraseTree(proj: string, arts: HarnessArtifacts, preserveProject: boolean): void {
   for (const h of HARNESSES) {
     // h.clean = the adapter's surgical inverse: contract block (sentinels, deleteIfEmpty), the dispatch.sh-
     // stamped shim + worktree anchor, the trust block, and the arts-named skill/agent files.
     h.clean(proj, arts, preserveProject)
-    for (const f of h.contractFiles(proj)) clearSkipWorktree(proj, f)   // legacy private-overlay bit — erase-only
-    sweepGeneratedSkills(h.skillDir(proj))
-    sweepGeneratedAgents(h.agentDir(proj))
+    for (const f of h.contractFiles(proj)) clearSkipWorktree(proj, f)
+    pruneGeneratedSkills(h.skillDir(proj), new Set())
+    pruneGeneratedAgents(h.agentDir(proj), new Set())
   }
   // same authorship rule as the contract files: deleteIfEmpty only when .gitignore is UNTRACKED (wholly-ours
   // generated file); a HOST-TRACKED .gitignore that carried nothing but our block is stripped, never deleted.
   removeManagedBlock(join(proj, '.gitignore'), ['# ', ''], !isTracked(proj, '.gitignore'))
-  removeContractFilter(proj, [...HARNESSES.flatMap((h) => h.contractFiles(proj)), join(proj, '.gitignore')])
+  clearContractFilterPayload(proj, [...HARNESSES.flatMap((h) => h.contractFiles(proj)), join(proj, '.gitignore')])
   // the block-strip left tracked contract files stat-dirty (under a filter git NEVER content-verifies them,
   // and even unfiltered the phantom-`M` lingers) — settle the index stat, content-guarded so a user's real
   // unstaged edit is never staged ([[content-filter]] edge 2).
@@ -157,16 +198,7 @@ function eraseTree(proj: string, arts: HarnessArtifacts, preserveProject: boolea
   // because a harness may nest its shim a level below its home (opencode's .opencode/plugins/, pi's
   // .pi/extensions/) — but never the checkout roots themselves. rmdirSync is NON-recursive, so a dir holding
   // any user file survives untouched; `.git/spexcode/` is deliberately NOT swept (shared per-clone home).
-  for (const h of HARNESSES) {
-    const anchor = h.worktreeHookAnchor(proj)
-    const dirs = [h.skillDir(proj), h.agentDir(proj), dirname(h.shimFile(proj)), anchor ? dirname(anchor) : null]
-      .filter((d): d is string => !!d)
-    const roots = new Set([proj, mainCheckout(proj)])
-    const sweep = [...new Set([...dirs, ...dirs.map((d) => dirname(d))])]
-      .filter((d) => !roots.has(d))
-      .sort((a, b) => b.length - a.length)
-    for (const d of sweep) { try { rmdirSync(d) } catch { /* non-empty or absent — keep */ } }
-  }
+  cleanupHarnessDirs(proj)
 }
 
 export function dematerialize(proj = process.cwd(), arts: HarnessArtifacts = { skills: [], agents: [] }): void {
@@ -177,7 +209,7 @@ export function dematerialize(proj = process.cwd(), arts: HarnessArtifacts = { s
     git(['-C', tree, 'rev-parse', '--show-toplevel'])
   }
   for (const tree of trees) {
-    // Only the caller's live spec may widen the legacy name sweep. Siblings are identity-stamp-only: the
+    // Only the caller's live spec may widen the name sweep. Siblings are identity-stamp-only: the
     // same name there may be user-owned or may not exist in this tree's divergent spec at all.
     eraseTree(tree, tree === current ? arts : { skills: [], agents: [] }, false)
   }
@@ -196,7 +228,7 @@ export function materialize(proj = process.cwd()): MaterializeResult {
   }
   // (1) hook manifest (persistent — the dispatcher reads it; regenerated only here, on change).
   const manifest = join(rt, 'hooks-manifest')
-  writeFileSync(manifest, compileManifest())
+  writeFileIfChanged(manifest, compileManifest())
   record('hook manifest', manifest)
   // (2) the contract = the surface:system plugin bodies (in name order), written WHOLE into EACH harness's
   //     contract file(s) + (3) each harness's thin shim → dispatch.sh + (4) its trust. All owned by the adapter.
@@ -213,14 +245,7 @@ export function materialize(proj = process.cwd()): MaterializeResult {
   const skillNodes = loadSkillConfig()
   const agentNodes = loadAgentConfig()
   const commandNodes = loadConfig()
-  const arts: HarnessArtifacts = { skills: skillNodes.map((s) => s.name), agents: agentNodes.map((a) => a.name) }
 
-  // ---- ERASE (the forgetting law): every landing point cleared by identity stamp, whatever policy — or
-  // legacy mode — wrote it last. Unselected harnesses need no separate prune branch: the erase already
-  // forgot them, and only the selected ones are asserted below.
-  eraseTree(proj, arts, true)
-
-  // ---- ASSERT: rewrite each landing point per the CURRENT policy.
   // a skill node → the agentskills.io SKILL.md primitive: `name`+`description` frontmatter (the load-trigger)
   // over the body instructions, closed by the GENERATED_MARK identity stamp (what the erase phase keys on).
   // One pure artifact builder shared by every harness — divergence is only its skillDir.
@@ -239,53 +264,80 @@ export function materialize(proj = process.cwd()): MaterializeResult {
   // because their residence is the live three-state kind detection below, not a static entry.
   const artifactPaths: string[] = []
   const machinePaths: string[] = []
-  const contractPaths: string[] = []
+  const contractTargets = new Map<string, string>()
+  const treeShimTargets = new Map<string, string>()
+  const anchorTargets = new Map<string, string>()
+  const skillTargets = new Map<string, string>()
+  const agentTargets = new Map<string, string>()
+  const skillsByDir = new Map<string, Set<string>>()
+  const agentsByDir = new Map<string, Set<string>>()
+  const addTarget = (targets: Map<string, string>, path: string, content: string) => {
+    const prior = targets.get(path)
+    if (prior !== undefined && prior !== content) throw new Error(`conflicting materialize targets for ${path}`)
+    targets.set(path, content)
+  }
   for (const h of selected) {
-    if (contract) for (const f of h.contractFiles(proj)) { writeManagedBlock(f, contract); contractPaths.push(f); record('contract', f) }
+    if (contract) for (const f of h.contractFiles(proj)) addTarget(contractTargets, f, contract)
     const shim = h.shim(DISPATCH, SPEX)
     if (h.shimScope === 'tree') {
-      const shimFile = h.shimFile(proj)
-      mkdirSync(dirname(shimFile), { recursive: true })
-      writeFileSync(shimFile, shim.content)
-      record('shim', shimFile)
-      machinePaths.push(shimFile)
+      addTarget(treeShimTargets, h.shimFile(proj), shim.content)
     }
     // a linked-worktree ANCHOR copy of the shim, when the harness needs one (codex: the shim lives at the main
     // checkout, so the worktree gets no `.codex/` unless we place one). One adapter line; null otherwise.
     const anchor = h.worktreeHookAnchor(proj)
-    if (anchor) { mkdirSync(dirname(anchor), { recursive: true }); writeFileSync(anchor, shim.content); machinePaths.push(anchor); record('shim', anchor) }
+    if (anchor) addTarget(anchorTargets, anchor, shim.content)
+  }
+  for (const sk of skillNodes) for (const h of selected) {
+    const dir = h.skillDir(proj); if (!dir) continue
+    addTarget(skillTargets, join(dir, sk.name, 'SKILL.md'), skillArtifact(sk))
+    const names = skillsByDir.get(dir) ?? new Set<string>(); names.add(sk.name); skillsByDir.set(dir, names)
+  }
+  for (const ag of agentNodes) for (const h of selected) {
+    const dir = h.agentDir(proj); if (!dir) continue
+    addTarget(agentTargets, join(dir, `${ag.name}.md`), agentArtifact(ag))
+    const names = agentsByDir.get(dir) ?? new Set<string>(); names.add(ag.name); agentsByDir.set(dir, names)
+  }
+  const tracked = new Map<string, boolean>()
+  const isTrackedHere = (file: string) => {
+    const known = tracked.get(file)
+    if (known !== undefined) return known
+    const value = isTracked(proj, file); tracked.set(file, value); return value
+  }
+  reconcileTree(proj, {
+    contracts: new Set(contractTargets.keys()), treeShims: new Set(treeShimTargets.keys()), anchors: new Set(anchorTargets.keys()),
+    skills: skillsByDir, agents: agentsByDir,
+  }, isTrackedHere)
+  const changedMaterialized = new Set<string>()
+  for (const [file, content] of contractTargets) {
+    if (writeManagedBlock(file, content)) changedMaterialized.add(file)
+    record('contract', file)
+  }
+  const contractPaths = [...contractTargets.keys()]
+  for (const [file, content] of treeShimTargets) {
+    mkdirSync(dirname(file), { recursive: true }); writeFileIfChanged(file, content)
+    record('shim', file); machinePaths.push(file)
+  }
+  for (const [file, content] of anchorTargets) {
+    mkdirSync(dirname(file), { recursive: true }); writeFileIfChanged(file, content)
+    record('shim', file); machinePaths.push(file)
   }
   const selectedByDispatch = new Map(selected.map((h) => [h.dispatchId, h]))
   for (const h of selectedByDispatch.values()) {
     const shim = h.shim(DISPATCH, SPEX)
     if (h.shimScope === 'project') {
       const file = h.shimFile(proj)
-      mkdirSync(dirname(file), { recursive: true }); writeFileSync(file, shim.content)
+      mkdirSync(dirname(file), { recursive: true }); writeFileIfChanged(file, shim.content)
       record('shim', file)
     }
     for (const file of h.writeTrust(proj, shim.cmd)) record('trust', file)
   }
-  // (6) skills + (7) sub-agents — each surface node → the file the harness auto-discovers, one per selected
-  //     harness that has the primitive (skillDir/agentDir null skips — the divergence is the adapter's line).
-  for (const sk of skillNodes) {
-    for (const h of selected) {
-      const dir = h.skillDir(proj); if (!dir) continue
-      const f = join(dir, sk.name, 'SKILL.md')
-      mkdirSync(dirname(f), { recursive: true })
-      writeFileSync(f, skillArtifact(sk))
-      artifactPaths.push(f)
-      record('skill', f)
-    }
+  for (const [file, content] of skillTargets) {
+    mkdirSync(dirname(file), { recursive: true }); writeFileIfChanged(file, content)
+    artifactPaths.push(file); record('skill', file)
   }
-  for (const ag of agentNodes) {
-    for (const h of selected) {
-      const dir = h.agentDir(proj); if (!dir) continue
-      const f = join(dir, `${ag.name}.md`)
-      mkdirSync(dirname(f), { recursive: true })
-      writeFileSync(f, agentArtifact(ag))
-      artifactPaths.push(f)
-      record('agent', f)
-    }
+  for (const [file, content] of agentTargets) {
+    mkdirSync(dirname(file), { recursive: true }); writeFileIfChanged(file, content)
+    artifactPaths.push(file); record('agent', file)
   }
   // (8) the PLUGIN target ([[plugin-harness]]): materialize the whole system into one self-contained Claude-plugin
   //     bundle per selected folder. A plugin is EXCLUSIVE (`selected` is empty then). Pruning a DESELECTED
@@ -294,11 +346,7 @@ export function materialize(proj = process.cwd()): MaterializeResult {
   //     global store records the folders emitted last run; any prev folder absent from the current set is
   //     clean()ed, then the current folders are emitted and the ledger rewritten.
   const ledger = join(rt, 'plugin-folders')
-  // migration: a tree last materialized pre-slot left its ledger as the project-global file — read it once as
-  // the prev set so a deselected folder is still pruned; every write lands in the slot from here on.
-  const legacyLedger = join(runtimeRoot(proj), 'plugin-folders')
-  const ledgerSrc = existsSync(ledger) ? ledger : legacyLedger
-  const prevFolders = existsSync(ledgerSrc) ? readFileSync(ledgerSrc, 'utf8').split('\n').map((l) => l.trim()).filter(Boolean) : []
+  const prevFolders = existsSync(ledger) ? readFileSync(ledger, 'utf8').split('\n').map((l) => l.trim()).filter(Boolean) : []
   const curFolders = plugins.map((p) => p.folder)
   for (const f of prevFolders) if (!curFolders.includes(f)) cleanPlugin(proj, f)
   if (plugins.length) {
@@ -315,7 +363,7 @@ export function materialize(proj = process.cwd()): MaterializeResult {
       record('plugin bundle', pluginBundleDir(proj, p.folder))
     }
   }
-  writeFileSync(ledger, curFolders.join('\n'))
+  writeFileIfChanged(ledger, curFolders.join('\n'))
   // (9) ignore + mixed text. Only checkout-invariant residue and project-shared shims belong in the COMMON
   // info/exclude; selection-dependent paths live in this tree's filtered working .gitignore.
   const mc = mainCheckout(proj)
@@ -327,43 +375,38 @@ export function materialize(proj = process.cwd()): MaterializeResult {
     'spexcode.local.json', '.worktrees/', '.session',
   ]
   const entries = (list: string[]) => [...new Set(list)].sort().join('\n')
-  const priorCommonEntries = managedExcludeEntries(infoExcludePath(proj))
-
   // Contract residence stays a live fact. Selection-dependent untracked products are ignored by this tree's
   // working .gitignore, whose own managed block is filtered when the host tracks/owns that file.
   const filterContracts: string[] = []
   const oursContracts: string[] = []
   for (const f of contractPaths) {
-    if (isTracked(proj, f) || hostContentOf(f).trim()) filterContracts.push(f)
+    if (isTrackedHere(f) || hostContentOf(f).trim()) filterContracts.push(f)
     else oursContracts.push(f)
   }
   const localEntries = [...machinePaths, ...bundlePaths, ...artifactPaths, ...oursContracts]
     .map((p) => relative(proj, p)).filter((p) => !p.startsWith('..'))
   const ignoreFile = join(proj, '.gitignore')
-  const ignoreTracked = isTracked(proj, ignoreFile)
+  const ignoreTracked = isTrackedHere(ignoreFile)
   const ignoreHost = existsSync(ignoreFile) ? readFileSync(ignoreFile, 'utf8') : ''
   if (!ignoreTracked && !ignoreHost.trim()) localEntries.push('.gitignore')
   const ignoreBody = entries(localEntries)
-  writeManagedBlock(ignoreFile, ignoreBody, ['# ', ''])
+  if (writeManagedBlock(ignoreFile, ignoreBody, ['# ', ''])) changedMaterialized.add(ignoreFile)
 
   const payloads: ContractFilterPayload[] = filterContracts.map((file) => ({ file: relative(proj, file), content: contract }))
   if (ignoreTracked || ignoreHost.trim()) payloads.push({ file: '.gitignore', content: ignoreBody })
   const bindings: ContractFilterBinding[] = [
     ...[...new Set(HARNESSES.flatMap((h) => h.contractFiles(proj).map((file) => relative(proj, file))))]
-      .map((file) => ({ file, start: '<!-- spexcode:start -->', end: '<!-- spexcode:end -->', legacy: true })),
+      .map((file) => ({ file, start: '<!-- spexcode:start -->', end: '<!-- spexcode:end -->' })),
     { file: '.gitignore', start: '# spexcode:start', end: '# spexcode:end' },
   ]
-  if (payloads.length) plantContractFilter(proj, payloads, bindings)
-  // (5) finish diagnostics/migration, then atomically publish the allowlist LAST. Dispatch consumes only that
+  if (payloads.length) plantContractFilter(proj, payloads, bindings, [...changedMaterialized])
+  else if (contractFilterPlanted(proj)) removeContractFilter(proj, [...HARNESSES.flatMap((h) => h.contractFiles(proj)), join(proj, '.gitignore')])
+  // (5) finish diagnostics, then atomically publish the allowlist LAST. Dispatch consumes only that
   // final receipt; a killed writer leaves the preceding successful selection intact.
   const h = contentHash(proj)
-  writeFileSync(join(rt, 'content-hash'), h)
-  writeFileSync(join(rt, 'contract-filter-v2'), '')
-  writeFileSync(join(rt, TREE_IGNORE_RECEIPT), '')
-  writeFileSync(join(runtimeRoot(proj), 'harness-selection-v1'), '')
-  retireLegacyContractBlock(proj)
-  const legacyEntries = hasLegacyTreeIgnore(proj) ? priorCommonEntries : []
-  writeManagedBlock(infoExcludePath(proj), entries([...commonEntries, ...legacyEntries]), ['# ', ''])
+  writeFileIfChanged(join(rt, 'content-hash'), h)
+  writeFileIfChanged(join(runtimeRoot(proj), 'harness-selection-v1'), '')
+  writeManagedBlock(infoExcludePath(proj), entries(commonEntries), ['# ', ''])
   publishSelection(join(rt, 'harnesses'), selectionBody(selected, plugins.length > 0))
   return { contentHash: h, planted }
 }

package/spec-cli/src/plugin-harness.ts

@@ -1,6 +1,7 @@
-import { writeFileSync, mkdirSync, readFileSync, existsSync, rmSync, copyFileSync } from 'node:fs'
+import { mkdirSync, readFileSync, existsSync, readdirSync, rmSync } from 'node:fs'
 import { join, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { copyFileIfChanged, writeFileIfChanged } from './file-write.js'
 
 // @@@ plugin-harness - the PLUGIN BUNDLE emitter: materialize the whole SpexCode system into ONE self-contained
 // Claude-plugin bundle dropped into the host-agent-scanned folder [[harness-select]] resolved (e.g. `.zcode` /
@@ -103,23 +104,33 @@ export function emitPlugin(proj: string, folder: string, r: PluginBundle): void
   const hooksDir = join(bundle, 'hooks')
   mkdirSync(meta, { recursive: true })
   mkdirSync(hooksDir, { recursive: true })
-  writeFileSync(join(meta, 'plugin.json'), pluginManifest(r.version))
+  writeFileIfChanged(join(meta, 'plugin.json'), pluginManifest(r.version))
   // hooks: the SHARED dispatcher + its shell mirror (copied verbatim — the exact native wiring), the contract
   // injector + its pre-encoded payload, and the event→dispatch binding.
-  copyFileSync(join(HOOKS_SRC, 'dispatch.sh'), join(hooksDir, 'dispatch.sh'))
-  copyFileSync(join(HOOKS_SRC, 'harness.sh'), join(hooksDir, 'harness.sh'))
-  writeFileSync(join(hooksDir, 'inject-contract.sh'), INJECT_SH)
-  writeFileSync(join(hooksDir, 'contract-context.json'), contractContextJson(r.contract))
-  writeFileSync(join(hooksDir, 'hooks.json'), pluginHooksJson(r.spex))
+  copyFileIfChanged(join(HOOKS_SRC, 'dispatch.sh'), join(hooksDir, 'dispatch.sh'))
+  copyFileIfChanged(join(HOOKS_SRC, 'harness.sh'), join(hooksDir, 'harness.sh'))
+  writeFileIfChanged(join(hooksDir, 'inject-contract.sh'), INJECT_SH)
+  writeFileIfChanged(join(hooksDir, 'contract-context.json'), contractContextJson(r.contract))
+  writeFileIfChanged(join(hooksDir, 'hooks.json'), pluginHooksJson(r.spex))
   // skills / agents / commands — the Claude-plugin layout, the SAME materialized contents as the native dirs.
+  reconcileBundleDirectory(join(bundle, 'skills'), new Set(r.skills.map((s) => s.name)))
+  reconcileBundleDirectory(join(bundle, 'agents'), new Set(r.agents.map((a) => `${a.name}.md`)))
+  reconcileBundleDirectory(join(bundle, 'commands'), new Set(r.commands.map((c) => `${c.name}.md`)))
   for (const s of r.skills) writeBundleFile(join(bundle, 'skills', s.name, 'SKILL.md'), s.content)
   for (const a of r.agents) writeBundleFile(join(bundle, 'agents', `${a.name}.md`), a.content)
   for (const c of r.commands) writeBundleFile(join(bundle, 'commands', `${c.name}.md`), c.content)
 }
 
+function reconcileBundleDirectory(dir: string, expectedNames: ReadonlySet<string>): void {
+  if (!existsSync(dir)) return
+  for (const entry of readdirSync(dir)) {
+    if (!expectedNames.has(entry)) rmSync(join(dir, entry), { recursive: true, force: true })
+  }
+}
+
 function writeBundleFile(f: string, content: string): void {
   mkdirSync(dirname(f), { recursive: true })
-  writeFileSync(f, content)
+  writeFileIfChanged(f, content)
 }
 
 // the INVERSE of emitPlugin — prune the bundle when its folder is DESELECTED ([[harness-delivery]] tracks the

package/spec-cli/src/process-identity.ts

@@ -142,6 +142,19 @@ export function verifyDetachedRuntime(pid: number, receiptFile: string, adapter:
   return live
 }
 
+// The inverse question of verifyDetachedRuntime: not "is the recorded process running right now" but "is it
+// provably GONE". The two are not complements — a missing receipt, an unreadable identity, or a PID we never
+// recorded answers neither, and a caller that treats "unproven" as "dead" would retire a live runtime it can
+// simply no longer address. Only a recorded start identity that the live PID no longer matches (including a
+// PID that is not running at all) is proof of death.
+export function detachedRuntimeIsGone(pid: number, receiptFile: string, adapter: ProcessAdapter = hostProcessAdapter): boolean {
+  let receipt: DetachedLaunchReceiptV4 | null
+  try { receipt = parseDetachedLaunchReceipt(readFileSync(receiptFile, 'utf8'), adapter.platform) }
+  catch { return false }
+  if (!receipt || receipt.pid !== pid) return false
+  return adapter.startToken(pid) !== receipt.startToken
+}
+
 // A v3 scope is only a migration witness when every recorded and live Linux identity agrees. Readers never
 // call this: minting a v4 receipt belongs to the write admission path that needs the shared runtime.
 export function migrateLegacyDetachedRuntimeReceipt(

package/spec-cli/src/reviews.ts

@@ -1,7 +1,7 @@
 import { createHash } from 'node:crypto'
 import { listSessions } from './sessions.js'
 import { getBoard, getBoardForForgeRevision } from './graphCache.js'
-import { buildSessionEvals, type SessionEvals } from '../../spec-eval/src/sessioneval.js'
+import { type SessionEvalOrderRow, buildSessionEvals, type SessionEvals } from '../../spec-eval/src/sessioneval.js'
 import { evalTimeline } from '../../spec-eval/src/evaltab.js'
 import { issuesEnabled as issuesEnabledForReview } from './localIssues.js'
 import { issueStores as issueStoresForReview } from './issues.js'
@@ -217,15 +217,26 @@ export function scopedEvalReviewItems(model: SessionEvals): ReviewItem[] {
 
 const evalItemKey = (item: any): string => `${String(item?.node ?? '')}\0${String(item?.scenario ?? '')}`
 
-function evalNeighbor(item: any): EvalNeighbor {
+function evalNeighbor(item: any, stateOf: (row: { node: string; scenario: string }) => string): EvalNeighbor {
   return {
     node: String(item.node),
     scenario: String(item.scenario),
-    state: String(item.state ?? evalReviewState(item)),
+    state: stateOf(item),
   }
 }
 
-export function boundedEvalNeighbors(items: ReviewItem[], node: string, scenario: string, want = 5) {
+// `sequence` is the whole measured population in list order; `stateOf` answers only for rows whose freshness
+// was actually computed. On a focused build those are two different sets — the sequence spans the scope, the
+// states cover the selected row and its window — which is exactly why the state is looked up rather than
+// carried: a row this response does not render contributes its POSITION and nothing else.
+export function boundedEvalNeighbors(
+  sequence: { node: string; scenario: string }[],
+  node: string,
+  scenario: string,
+  stateOf: (row: { node: string; scenario: string }) => string,
+  want = 5,
+) {
+  const items = sequence
   const key = `${node}\0${scenario}`
   const index = items.findIndex((item) => evalItemKey(item) === key)
   if (index < 0) return { prev: [], next: [], total: items.length, index: null, order: 'default' as const }
@@ -235,8 +246,8 @@ export function boundedEvalNeighbors(items: ReviewItem[], node: string, scenario
   const nextN = Math.min(after, Math.max(Math.ceil(take / 2), take - before))
   const prevN = Math.min(before, take - nextN)
   return {
-    prev: items.slice(index - prevN, index).reverse().map(evalNeighbor),
-    next: items.slice(index + 1, index + 1 + nextN).map(evalNeighbor),
+    prev: items.slice(index - prevN, index).reverse().map((item) => evalNeighbor(item, stateOf)),
+    next: items.slice(index + 1, index + 1 + nextN).map((item) => evalNeighbor(item, stateOf)),
     total: items.length,
     index,
     order: 'default' as const,
@@ -248,12 +259,22 @@ export function projectEvalDetail(
   historySource: ReviewItem[],
   node: string,
   scenario: string,
-  metadata: { scope?: string | null; summary?: SessionEvals['summary']; evalRevision?: SessionEvals['evalRevision'] } = {},
+  metadata: {
+    scope?: string | null
+    summary?: SessionEvals['summary']
+    evalRevision?: SessionEvals['evalRevision']
+    // the scope's whole measured sequence, when `items` deliberately holds only the rendered window
+    sequence?: { node: string; scenario: string }[]
+  } = {},
 ): EvalDetailReview {
   const results = items.filter((item: any) => item.filterKind === EVAL_FILTER_KIND.RESULT)
   const selected = results.find((item) => evalItemKey(item) === `${node}\0${scenario}`) ?? null
   const history = historySource.filter((reading: any) => String(reading.scenario) === scenario)
-  const neighbors = boundedEvalNeighbors(results, node, scenario)
+  const stateByKey = new Map(results.map((item: any) => [evalItemKey(item), String(item.state ?? evalReviewState(item))]))
+  const sequence = metadata.sequence
+    ?? results.map((item: any) => ({ node: String(item.node), scenario: String(item.scenario) }))
+  const neighbors = boundedEvalNeighbors(sequence, node, scenario,
+    (row) => stateByKey.get(evalItemKey(row)) ?? 'empty')
   const scope = metadata.scope ?? null
   return {
     scope,
@@ -266,15 +287,38 @@ export function projectEvalDetail(
   }
 }
 
+// the measured population in list order, from the freshness-free rows: a filed reading leads (newest first),
+// and the tie-breaks are the identity ones — the SAME comparison `byNewest` applies, over the only fields it
+// actually reads. Blind rows never enter, exactly as the detail's own `results` filter excludes them.
+export function measuredSequence(order: SessionEvalOrderRow[]): { node: string; scenario: string }[] {
+  return order.filter((row) => row.ts)
+    .sort((a, b) => String(b.ts ?? '').localeCompare(String(a.ts ?? ''))
+      || a.node.localeCompare(b.node) || a.scenario.localeCompare(b.scenario))
+    .map((row) => ({ node: row.node, scenario: row.scenario }))
+}
+
+// the nodes whose verdicts the response will publish: the selected row's, plus a window wide enough to
+// contain any neighbour boundedEvalNeighbors can choose (it takes at most five, split around the index).
+export function focusNodes(order: SessionEvalOrderRow[], node: string, scenario: string): string[] {
+  const sequence = measuredSequence(order)
+  const index = sequence.findIndex((row) => row.node === node && row.scenario === scenario)
+  if (index < 0) return [node]
+  return [...new Set([node, ...sequence.slice(Math.max(0, index - 6), index + 7).map((row) => row.node)])]
+}
+
 export async function evalDetailReview(node: string, scenario: string, scope?: string | null): Promise<EvalDetailReview | null> {
   if (scope) {
-    const model = await buildSessionEvals(scope)
+    // A detail renders ONE row plus at most five neighbours, but owes the whole population's index/total.
+    // So name the window from the freshness-free sequence and let only those nodes pay the freshness pass;
+    // a build that finds a full cached model ignores the pick and answers from it instead.
+    const model = await buildSessionEvals(scope, (order) => focusNodes(order, node, scenario))
     if (!model) return null
     const sourceNode = model.nodes.find((candidate) => candidate.id === node)
     return projectEvalDetail(scopedEvalReviewItems(model), sourceNode?.evals ?? [], node, scenario, {
       scope,
       summary: model.summary,
       evalRevision: model.evalRevision,
+      ...(model.order ? { sequence: measuredSequence(model.order) } : {}),
     })
   }
   await getBoard()
@@ -335,13 +379,13 @@ export async function evalsReview(query: string | undefined, requestedPage: unkn
     const filtered = evalFilterModel(items, tokenFilterState(text, 'eval'), { sessions, defaultKind: 'all', defaultSection: '' })
     return {
       scope,
-      gates: model.gates,
+      gates: model.gates ?? [],
       unknown: model.nodes.reduce((count, node) => count + (node.unknownCoverage?.length ?? 0), 0),
       summary: model.summary,
       evalRevision: model.evalRevision,
       impact: model.impact,
       ...paginateReview(items, filtered.shown, filtered, requestedPage, {
-        domain: 'evals', scope, items, gates: model.gates, summary: model.summary,
+        domain: 'evals', scope, items, gates: model.gates ?? [], summary: model.summary,
         evalRevision: model.evalRevision, impact: model.impact, sessions: sessions.map((session) => session.id),
       }),
     }