spexcode 0.5.9 → 0.6.1

package/spec-cli/src/init.ts

@@ -1,29 +1,20 @@
 import { existsSync, mkdirSync, copyFileSync, readFileSync, readdirSync, renameSync, rmSync, statSync, chmodSync, writeFileSync } from 'node:fs'
-import { createHash } from 'node:crypto'
 import { join, resolve, relative, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { execFileSync } from 'node:child_process'
 import { readConfig, readJsonConfig } from './layout.js'
 import { resolveHarnessTargets, parseHarnessFlag, NATIVE_HARNESS_IDS } from './harness-select.js'
+import { gitBinary } from './git.js'
 
 // this file lives at <pkgRoot>/src/init.ts, so `..` is the package root — the same derivation the
 // launch paths use, never a hardcoded repo path (so a relocated/installed package still finds its data).
 const pkgRoot = fileURLToPath(new URL('..', import.meta.url))
 const TEMPLATES = join(pkgRoot, 'templates')
 const MANAGED_HOOK_HEADER = '# spexcode-managed-hook-v1'
-const LEGACY_MANAGED_HOOKS: Record<string, Set<string>> = {
-  'pre-commit': new Set(['fc33a6ff2b444fa47210a2594b6a714613d9c62fd8ec77a9a13aec81143de8a7']),
-  'prepare-commit-msg': new Set(['08b26ad8ffb305a64b7cddc868231854c84d539b8e5e9324702bd2c293044183']),
-}
-
-function hookDigest(path: string): string {
-  return createHash('sha256').update(readFileSync(path)).digest('hex')
-}
 
-function isManagedHook(path: string, name: string): boolean {
+function isManagedHook(path: string): boolean {
   const source = readFileSync(path, 'utf8')
   return source.split('\n').slice(0, 4).includes(MANAGED_HOOK_HEADER)
-    || LEGACY_MANAGED_HOOKS[name]?.has(createHash('sha256').update(source).digest('hex')) === true
 }
 
 function replaceHook(source: string, dest: string): void {
@@ -71,7 +62,7 @@ function copyTreeNoClobber(srcDir: string, destDir: string, base: string): strin
 // hooks/ (shared across all worktrees). Returns null (with a loud reason) when <dir> isn't a git repo.
 function resolveHooksDir(dir: string): string | null {
   try {
-    const common = execFileSync('git', ['-C', dir, 'rev-parse', '--path-format=absolute', '--git-common-dir'], {
+    const common = execFileSync(gitBinary(process.env), ['-C', dir, 'rev-parse', '--path-format=absolute', '--git-common-dir'], {
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'ignore'], // swallow git's own "fatal: not a git repository" — our warning is the signal
     }).trim()
@@ -86,8 +77,8 @@ function resolveHooksDir(dir: string): string | null {
 // turn that feature branch into trunk).
 function adoptionMainBranch(dir: string): string {
   try {
-    const common = execFileSync('git', ['-C', dir, 'rev-parse', '--path-format=absolute', '--git-common-dir'], { encoding: 'utf8' }).trim()
-    const branch = execFileSync('git', ['-C', dirname(common), 'symbolic-ref', '--short', 'HEAD'], { encoding: 'utf8' }).trim()
+    const common = execFileSync(gitBinary(process.env), ['-C', dir, 'rev-parse', '--path-format=absolute', '--git-common-dir'], { encoding: 'utf8' }).trim()
+    const branch = execFileSync(gitBinary(process.env), ['-C', dirname(common), 'symbolic-ref', '--short', 'HEAD'], { encoding: 'utf8' }).trim()
     if (branch) return branch
   } catch { /* render the one product-level repair below */ }
   const error = new Error('cannot determine the source-of-truth branch at adoption — check out the trunk in the root checkout, or set "mainBranch" in spexcode.json before re-running `spex init`')
@@ -113,7 +104,7 @@ export async function specInit(targetArg: string | undefined, presetArg?: string
   // NOT `git init` for them: creating a repo is a side effect beyond init's remit (a subdir, a dir not
   // meant as a repo root), and `git init` is one deliberate command.
   try {
-    execFileSync('git', ['-C', targetDir, 'rev-parse', '--is-inside-work-tree'], { stdio: ['ignore', 'ignore', 'ignore'] })
+    execFileSync(gitBinary(process.env), ['-C', targetDir, 'rev-parse', '--is-inside-work-tree'], { stdio: ['ignore', 'ignore', 'ignore'] })
   } catch {
     console.error(`spex init: ${targetDir} is not a git repository. SpexCode is git-backed (git is the version database; the hooks live in .git). Run \`git init\` there first, then \`spex init\`.`)
     process.exit(1)
@@ -210,8 +201,8 @@ export async function specInit(targetArg: string | undefined, presetArg?: string
       const source = join(hooksSrc, e.name)
       const dest = join(hooksDir, e.name)
       if (existsSync(dest)) {
-        if (hookDigest(dest) === hookDigest(source)) continue
-        if (isManagedHook(dest, e.name)) {
+        if (readFileSync(dest).equals(readFileSync(source))) continue
+        if (isManagedHook(dest)) {
           replaceHook(source, dest)
           refreshed.push(e.name)
         } else {

package/spec-cli/src/layout.ts

@@ -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 —
@@ -448,6 +462,20 @@ export function listSessionIds(): string[] {
   return ents.filter((d) => d.isDirectory()).map((d) => d.name)
 }
 
+// @@@ 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
+}
+
 // 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

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(