spexcode 0.5.9 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spexcode",
-  "version": "0.5.9",
+  "version": "0.6.1",
   "type": "module",
   "description": "SpexCode — a spec-driven, self-developing dev tool. The `spex` CLI + spec server reads the .spec tree and its git history, and serves the dashboard.",
   "license": "MIT",

package/spec-cli/src/cli.ts

@@ -161,28 +161,13 @@ async function followKit(selectors: string[], verb: string): Promise<{
   return { watcher, follow: (emit, opts) => followSessions(emit, { ...opts, targets, self: watcher, row }) }
 }
 
-const greeted = new Set<string>()
-// Starting a STREAM follow on named live sessions announces itself ([[session-follow]]): one appended line per
-// target per process, so a stream never re-nags and a one-shot `wait` never announces at all. The append is the
-// delivery, taken locally, so the announce needs no backend either.
-async function greetWatchTargets(watcher: string, selectors: string[]): Promise<void> {
-  try {
-    const real = selectors.filter((sel) => sel && sel !== '@all')
-    if (!real.length) return
-    const { localCachedSessions } = await import('./client.js')
-    const { selectSessions, sendText, sessionHeadline } = await import('./sessions.js')
-    const board = localCachedSessions(true)
-    // name the watcher by its board HEADLINE (same as the reply-channel footer), delimited as a session title.
-    const mine = board.find((s) => s.id === watcher)
-    const me = mine ? sessionHeadline(mine) : watcher
-    const meWho = me && me !== watcher ? `session "${me}" (${watcher})` : `session ${watcher}`
-    for (const target of selectSessions(board, real).map((s) => s.id)) {
-      if (target === watcher || greeted.has(target)) continue
-      greeted.add(target)
-      const text = `🔭 ${meWho} is now supervising you — they started \`spex session watch\` over this session. To reach them directly, run: spex session send ${watcher} "<your message>". (One-time heads-up; reply only if you need to.)`
-      void sendText(target, text)   // no sender id → the connection notice is not double-counted as comms
-    }
-  } catch { /* greeting is best-effort — it must never disturb the watch */ }
+async function localWatchTargetsOrExit(selectors: string[], verb: string): Promise<string[]> {
+  if (!selectors.length) { console.error(`usage: ${verb} <SEL...>`); process.exit(2) }
+  const { localCachedSessions } = await import('./client.js')
+  const { selectSessions } = await import('./sessions.js')
+  const targets = selectSessions(localCachedSessions(true), selectors).map((session) => session.id)
+  if (!targets.length) { console.error(`${verb}: no such local session: ${selectors.join(' ')}`); process.exit(2) }
+  return targets
 }
 
 async function resolveSelectorOrExit(selector: string): Promise<string> {
@@ -545,12 +530,12 @@ if (cmd === 'serve') {
       const stale = e.fresh ? '' : ` (stale: ${(e.staleAxes || []).join(',')})`
       console.log(`    ${e.inSession ? '✦' : ' '} ${verdict}${stale}  ${e.scenario}  — ${e.ts}${e.evaluator ? ` · ${e.evaluator}` : ''}`)
     }
-  } else if (['add', 'ls', 'scenario', 'matrix', 'lint', 'ok', 'retract', 'clean'].includes(sub)) {
+  } else if (['add', 'ls', 'scenario', 'lint', 'ok', 'retract', 'clean'].includes(sub)) {
     // node-scoped verbs — thin route; the logic lives in spec-eval.
     const { runEval } = await import('../../spec-eval/src/cli.js')
     await flushExit(await runEval(process.argv.slice(3)))
   } else {
-    console.error(`spex eval: unknown verb '${sub}' — add | ls | scenario ls/write | matrix | lint | ok | retract | clean  (spex help eval)`)
+    console.error(`spex eval: unknown verb '${sub}' — add | ls | scenario ls/write | lint | ok | retract | clean  (spex help eval)`)
     if (!sub.startsWith('--')) console.error(`  (the old \`spex eval <SEL>\` session read is now \`spex eval ls --session <SEL>\` [--export])`) // dead-words-ok: signpost — one-version tombstone teaching the renamed spelling (0.4.0 removes it)
     process.exit(2)
   }
@@ -626,8 +611,18 @@ if (cmd === 'serve') {
       if (!prompt.trim()) { console.error(`spex session new: --prompt-file ${promptFile === '-' ? 'stdin' : promptFile} is empty — refusing a promptless launch`); process.exit(2) }
     }
     const created = await createSession(prompt, flag('launcher') ?? undefined)
+    const { ownSessionId, subscribeSessionWatch } = await import('./sessions.js')
+    let watchEstablished = false
+    if (created.parent && created.parent === ownSessionId()) {
+      try {
+        await subscribeSessionWatch(created.parent, [created.id])
+        watchEstablished = true
+      } catch (error) {
+        console.error(`spex session new: child ${created.id} was created, but its managed watch was not established: ${error instanceof Error ? error.message : String(error)}`)
+      }
+    }
     console.log(JSON.stringify(created, null, 2))
-    console.error((await import('./help.js')).sessionLaunchReceipt(created.id))
+    console.error((await import('./help.js')).sessionLaunchReceipt(created.id, watchEstablished))
   } else if (sub === 'ls') {
     // pretty list of living sessions + states. `spex session ls [SEL...] [--status a,b] [--json]`
     // the board comes from the backend (so it shows the sessions of whatever SPEXCODE_API_URL points at,
@@ -648,19 +643,39 @@ if (cmd === 'serve') {
     if (has('json')) console.log(JSON.stringify(report, null, 2))
     else console.log((await import('./host-resources.js')).formatResourceReport(report))
   } else if (sub === 'watch') {
-    const selectors = positionals(4)
-    const kit = await followKit(selectors, 'spex session watch')
-    if (kit.watcher) void greetWatchTargets(kit.watcher, selectors)
-    await kit.follow((line) => console.log(line), {
-      statuses: flag('status')?.split(','),
-      includeIdle: has('idle'),
-      as: flag('as'),
-      intervalMs: (Number(flag('interval')) || 1) * 1000,
-    })
+    const [verb, ...rest] = positionals(4)
+    const { ownSessionId, subscribeSessionWatch, listSessionWatches, cancelSessionWatch } = await import('./sessions.js')
+    const watcher = ownSessionId()
+    if (verb === 'stream') {
+      const kit = await followKit(rest, 'spex session watch stream')
+      await kit.follow((line) => console.log(line), {
+        statuses: flag('status')?.split(','),
+        includeIdle: has('idle'),
+        as: flag('as'),
+        intervalMs: (Number(flag('interval')) || 1) * 1000,
+      })
+    } else if (verb === 'list') {
+      if (!watcher) { console.error('spex session watch list: no governed caller session — this caller has no durable watch relation'); process.exit(2) }
+      for (const watch of listSessionWatches(watcher)) console.log(`${watch.target}\t${watch.createdAt}`)
+    } else if (verb === 'cancel') {
+      if (!watcher) { console.error(`spex session watch cancel: no governed caller session — run \`spex session wait ${rest.join(' ')}\` in the background instead`); process.exit(2) }
+      const targets = await localWatchTargetsOrExit(rest, 'spex session watch cancel')
+      console.log(`cancelled ${cancelSessionWatch(watcher, targets)} watch${targets.length === 1 ? '' : 'es'}`)
+    } else {
+      const selectors = [verb, ...rest].filter(Boolean)
+      if (!watcher) {
+        if (!selectors.length) { console.error('usage: spex session watch <SEL...>'); process.exit(2) }
+        console.error(`spex session watch: no governed caller session — run \`spex session wait ${selectors.join(' ')}\` in the BACKGROUND to receive the next actionable transition`)
+      } else {
+        const targets = await localWatchTargetsOrExit(selectors, 'spex session watch')
+        const result = await subscribeSessionWatch(watcher, targets)
+        console.log(`watching ${result.watched.join(' ')}`)
+      }
+    }
   } else if (sub === 'wait') {
     const selectors = positionals(4)
     const kit = await followKit(selectors, 'spex session wait')
-    const named = selectors.join(' ') || 'your inbox'
+    const named = selectors.join(' ') || 'your own log'
     // point-of-use turn-freeze warning ([[session-follow]]): a managed agent that runs this wait in the FOREGROUND
     // freezes its whole turn until the target produces an edge — a warning that used to live only in help
     // prose, now said where it matters. Foreground vs background is invisible from here, so the hint prints
@@ -923,25 +938,31 @@ if (cmd === 'serve') {
     delete env.SPEXCODE_SESSION_ID
     const runtime = await spawnDetachedRuntime({ cwd, logFile, pidFile, receiptFile, command, args, env })
     console.log(runtime.pid)
-  } else if (sub === 'codex-generation-current') {
-    const [root, command] = process.argv.slice(4, 6)
-    if (!root || !command) { console.error('usage: spex internal codex-generation-current <runtime-root> <codex-command>'); process.exit(2) }
-    const { ensureCodexCurrentGeneration } = await import('./codex-runtime-generations.js')
+  } else if (sub === 'codex-generation-current' || sub === 'codex-generation-session') {
+    // Both launch spellings resolve ONE endpoint and print it as shell assignments. Starting a root is the same
+    // detached spawn either way — a session identity must never ride into the shared, project-scoped daemon.
+    const resume = sub === 'codex-generation-session'
+    const [root, ...rest] = process.argv.slice(4)
+    const [sessionId, threadId, sessionCommand] = rest
+    const command = resume ? sessionCommand : rest[0]
+    if (!root || !command || (resume && (!sessionId || !threadId))) {
+      console.error(resume
+        ? 'usage: spex internal codex-generation-session <runtime-root> <session-id> <thread-id> <codex-command>'
+        : 'usage: spex internal codex-generation-current <runtime-root> <codex-command>')
+      process.exit(2)
+    }
+    const { ensureCodexCurrentGeneration, resolveCodexGenerationForResume } = await import('./codex-runtime-generations.js')
     const { spawnDetachedRuntime } = await import('./runtime-ownership.js')
     const { sessionIdentityEnvVars } = await import('./harness.js')
     const env = { ...process.env }
     for (const key of sessionIdentityEnvVars()) delete env[key]
-    const endpoint = await ensureCodexCurrentGeneration(root, async (candidate) => {
+    const start = async (candidate: { logFile: string; pidFile: string; receiptFile: string; socketPath: string }) => {
       await spawnDetachedRuntime({ cwd: root, logFile: candidate.logFile, pidFile: candidate.pidFile, receiptFile: candidate.receiptFile,
         command, args: ['app-server', '--listen', `unix://${candidate.socketPath}`], env })
-    })
-    const quote = (value: string) => `'${value.replace(/'/g, `'\\''`)}'`
-    console.log(`sock=${quote(endpoint.socketPath)}; pid=${quote(endpoint.pidFile)}; receipt=${quote(endpoint.receiptFile)}; log=${quote(endpoint.logFile)}; export SPEXCODE_CODEX_GENERATION=${quote(endpoint.id)}`)
-  } else if (sub === 'codex-generation-session') {
-    const [root, sessionId, threadId] = process.argv.slice(4, 7)
-    if (!root || !sessionId || !threadId) { console.error('usage: spex internal codex-generation-session <runtime-root> <session-id> <thread-id>'); process.exit(2) }
-    const { resolveCodexGenerationForSession } = await import('./codex-runtime-generations.js')
-    const endpoint = resolveCodexGenerationForSession(root, sessionId, threadId)
+    }
+    const endpoint = resume
+      ? await resolveCodexGenerationForResume(root, sessionId!, threadId!, start)
+      : await ensureCodexCurrentGeneration(root, start)
     if (!endpoint) { console.error(`no exact Codex generation binding for session ${sessionId} thread ${threadId}`); process.exit(1) }
     const quote = (value: string) => `'${value.replace(/'/g, `'\\''`)}'`
     console.log(`sock=${quote(endpoint.socketPath)}; pid=${quote(endpoint.pidFile)}; receipt=${quote(endpoint.receiptFile)}; log=${quote(endpoint.logFile)}; export SPEXCODE_CODEX_GENERATION=${quote(endpoint.id)}`)
@@ -1043,28 +1064,6 @@ if (cmd === 'serve') {
     const st = process.argv[4] as any
     const ok = mark(() => s.markState(st, { proposal: flag('propose') as any, note: flag('note'), sessionId: sess }))
     console.log(ok.ok ? `state -> ${st}${noteEcho(flag('note'))}` : ok.reason ?? noRecord())
-  } else if (sub === 'session-cursor') {
-    // the turn-boundary mail reader advances its own inbox cursor here ([[session-cursors]]) — the same
-    // one-writer discipline as session-state: shell reads the file, it never rewrites it, so a follower's
-    // entries in the same file cannot be clobbered by a partial shell write.
-    const to = Number(flag('to'))
-    const sess = flag('session')
-    if (process.argv[4] !== 'inbox' || !sess || !Number.isFinite(to)) {
-      console.error('usage: spex internal session-cursor inbox --session <id> --to <event-index>')
-      process.exit(2)
-    }
-    const { advanceInbox, inboxCursor } = await import('./session-cursors.js')
-    const { readAliasedRawRecord } = await import('./layout.js')
-    // the hook may address a codex THREAD id; the cursor file is keyed by the record id, so resolve the alias
-    // through the one seam that owns that rule.
-    const record = readAliasedRawRecord(sess)
-    if (!record) console.log('noop (no session record)')
-    else {
-      advanceInbox(record.session_id, to)
-      // report where the cursor ACTUALLY is: advancing is monotonic, so a lower offer is ignored, and
-      // echoing the request back would confirm a move that did not happen.
-      console.log(`inbox -> ${inboxCursor(record.session_id)}`)
-    }
   } else if (sub === 'session-fail') {
     // StopFailure is one native source for the shared active-only turn-failure CAS. A declaration or explicit
     // stop that landed first is authoritative, just as it is for Codex notifications and headless exits.

package/spec-cli/src/client.ts

@@ -41,7 +41,7 @@ function cachedStatus(rec: ReturnType<typeof fromRaw>): DisplayStatus {
 function corruptCachedSession(id: string, reason: string): Session {
   const label = `${id.slice(0, 8)} (unreadable record)`
   return {
-    id, node: null, branch: null, path: '', label, headline: label, raw: { name: null, title: null },
+    id, node: null, branch: null, path: '', label, title: label, raw: { name: null, title: null },
     parent: null, harness: 'unknown', capabilities: { headless: false }, launcher: null,
     lifecycle: 'active', proposal: null, merges: 0, status: 'corrupt', liveness: 'unknown',
     note: `session record is unreadable: ${reason}`, archived: false, archiveHazard: null,

package/spec-cli/src/codex-runtime-generations.ts

@@ -3,7 +3,7 @@ import { createConnection, type Socket } from 'node:net'
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { tmpdir } from 'node:os'
-import { processStartToken, verifyDetachedRuntime } from './process-identity.js'
+import { detachedRuntimeIsGone, processStartToken, verifyDetachedRuntime } from './process-identity.js'
 
 export type CodexGenerationEndpoint = Readonly<{
   id: string
@@ -271,6 +271,32 @@ function hasLegacyResidue(root: string): boolean {
   return [endpoint.pidFile, endpoint.receiptFile, endpoint.socketPath].some(existsSync)
 }
 
+// A generation whose recorded process is provably gone — the host restarted, the OOM killer fired, a /tmp sweep
+// took the socket with it. Death is a POSITIVE fact, not the absence of proof: such a root holds no threads, no
+// peers, and no protective references, so nothing it once carried can be lost by retiring it. Everything else
+// that fails `endpointIdentity` is AMBIGUOUS — a live process we can no longer address — and keeps its root.
+function goneGeneration(endpoint: CodexGenerationEndpoint): boolean {
+  if (endpointIdentity(endpoint)) return false
+  let pid: number
+  try { pid = Number(readFileSync(endpoint.pidFile, 'utf8').trim()) }
+  catch { return false }
+  return Number.isInteger(pid) && pid > 0 && detachedRuntimeIsGone(pid, endpoint.receiptFile)
+}
+
+// Retire a gone generation inside the caller's ledger lock, returning the published ledger (null when the
+// generation is still there to serve or merely unaddressable). Its bindings deliberately survive: a session's
+// conversation lives in Codex's on-disk rollout, so those rows are stale pointers to re-pin, not lost threads.
+function retireGoneGenerationLocked(root: string, previous: CodexGenerationLedger, id: string): CodexGenerationLedger | null {
+  const generation = previous.generations[id]
+  if (!generation || generation.state === 'reclaimed' || !goneGeneration(generation.endpoint)) return null
+  return writeLedger(root, previous, {
+    current: previous.current === id ? null : previous.current,
+    pending: previous.pending === id ? null : previous.pending,
+    generations: { ...previous.generations, [id]: { state: 'reclaimed', endpoint: generation.endpoint } },
+    bindings: previous.bindings,
+  })
+}
+
 function bootstrapBindings(root: string, generationId: string): Record<string, CodexGenerationBinding> {
   const result: Record<string, CodexGenerationBinding> = {}
   const sessions = join(root, 'sessions')
@@ -305,13 +331,18 @@ function bindingProtectsGeneration(root: string, sessionId: string, binding: Cod
 function bootstrapLedger(root: string): CodexGenerationLedger {
   const legacy = legacyCodexGenerationEndpoint(root)
   if (!hasLegacyResidue(root)) return emptyLedger()
-  if (!endpointIdentity(legacy)) throw new Error('legacy Codex root is present but its exact detached PID/start/receipt/socket identity is unproven')
+  // Residue left by a legacy root that has since died enters the ledger already reclaimed rather than blocking
+  // the bootstrap: it has nothing to drain. Its governed bindings are still recorded so those sessions resolve
+  // to a stale pointer they can re-pin, instead of losing the thread they own.
+  const gone = goneGeneration(legacy)
+  if (!gone && !endpointIdentity(legacy))
+    throw new Error('legacy Codex root is present but its exact detached PID/start/receipt/socket identity is unproven')
   return {
     version: 3,
     revision: 0,
     current: null,
     pending: null,
-    generations: { [legacy.id]: { state: 'draining', endpoint: legacy } },
+    generations: { [legacy.id]: { state: gone ? 'reclaimed' : 'draining', endpoint: legacy } },
     bindings: bootstrapBindings(root, legacy.id),
   }
 }
@@ -373,9 +404,13 @@ export async function ensureCodexCurrentGeneration(root: string, start: (endpoin
       }
       if (previous.current) {
         const generation = previous.generations[previous.current]
-        if (!generation || generation.state !== 'current' || !endpointIdentity(generation.endpoint))
-          throw new Error('canonical Codex generation is missing, replaced, or unproven; refusing to route new traffic')
-        return { kind: 'current', endpoint: generation.endpoint }
+        if (generation && generation.state === 'current' && endpointIdentity(generation.endpoint))
+          return { kind: 'current', endpoint: generation.endpoint }
+        // A canonical root that is provably gone is retired here and replaced by the rest of this same call:
+        // refusing forever would make one host restart permanently un-routable. Anything else stays a refusal.
+        const healed = retireGoneGenerationLocked(root, previous, previous.current)
+        if (!healed) throw new Error('canonical Codex generation is missing, replaced, or unproven; refusing to route new traffic')
+        previous = healed
       }
       if (previous.pending) {
         const pending = previous.generations[previous.pending]
@@ -491,12 +526,67 @@ export function prepareCodexGenerationClose(root: string, sessionId: string, thr
     if (!binding || binding.threadId !== threadId) throw new Error(`Codex session ${sessionId} has no exact generation binding to close`)
     if (binding.phase === 'record-removing') return
     const generation = previous.generations[binding.generationId]
-    if (!generation || generation.state === 'reclaimed') throw new Error(`Codex session ${sessionId} binding names an absent or reclaimed generation`)
+    // A retired root can neither route this thread nor be pinned by it, so there is nothing for the removal
+    // marker to protect: drop the binding outright and let close proceed. An ABSENT generation is corruption.
+    if (!generation) throw new Error(`Codex session ${sessionId} binding names an absent generation`)
+    if (generation.state === 'reclaimed') {
+      const remaining = { ...previous.bindings }
+      delete remaining[sessionId]
+      writeLedger(root, previous, { current: previous.current, pending: previous.pending, generations: previous.generations, bindings: remaining })
+      return
+    }
     const bindings = { ...previous.bindings, [sessionId]: { ...binding, phase: 'record-removing' as const } }
     writeLedger(root, previous, { current: previous.current, pending: previous.pending, generations: previous.generations, bindings })
   })
 }
 
+// Re-pin an existing exact binding onto another live generation. The transaction phase is carried over, so a
+// registration or close that is mid-flight keeps its crash boundary while its route is corrected.
+export function repinCodexGeneration(root: string, sessionId: string, threadId: string, generationId: string): void {
+  withLedgerLockSync(root, () => {
+    const previous = readCodexGenerationLedger(root)
+    const binding = previous.bindings[sessionId]
+    if (!binding || binding.threadId !== threadId) throw new Error(`Codex session ${sessionId} has no exact binding to re-pin`)
+    const generation = previous.generations[generationId]
+    if (!generation || generation.state === 'reclaimed') throw new Error(`Codex generation ${generationId} is absent or reclaimed`)
+    if (binding.generationId === generationId) return
+    const bindings = { ...previous.bindings, [sessionId]: { ...binding, generationId } }
+    writeLedger(root, previous, { current: previous.current, pending: previous.pending, generations: previous.generations, bindings })
+  })
+}
+
+// The resume boundary. A binding to a LIVE generation still routes only there — an existing conversation is
+// never moved out from under the client that holds it. But a binding whose root is gone names a process, not a
+// conversation: the thread's durable home is its on-disk rollout, which any generation can load. So the gone
+// root is retired and the session is re-pinned to the canonical one, which loads that same rollout. Missing,
+// mismatched, ambiguous, or unprotected bindings remain refusals — resume never invents a route.
+export async function resolveCodexGenerationForResume(
+  root: string,
+  sessionId: string,
+  threadId: string,
+  start: (endpoint: CodexGenerationEndpoint) => Promise<void>,
+): Promise<CodexGenerationEndpoint | null> {
+  const ledger = readCodexGenerationLedger(root)
+  const binding = ledger.bindings[sessionId]
+  if (!binding || binding.threadId !== threadId || !bindingProtectsGeneration(root, sessionId, binding)) return null
+  const generation = ledger.generations[binding.generationId]
+  if (!generation) return null
+  if (generation.state !== 'reclaimed') {
+    if (endpointIdentity(generation.endpoint)) return generation.endpoint
+    const retired = await withLedgerLock(root, async () => {
+      const previous = readCodexGenerationLedger(root)
+      if (previous.bindings[sessionId]?.generationId !== binding.generationId) return false
+      const observed = previous.generations[binding.generationId]
+      if (!observed) return false
+      return observed.state === 'reclaimed' || !!retireGoneGenerationLocked(root, previous, binding.generationId)
+    })
+    if (!retired) return null
+  }
+  const current = await ensureCodexCurrentGeneration(root, start)
+  repinCodexGeneration(root, sessionId, threadId, current.id)
+  return current
+}
+
 export function resolveCodexGenerationForSession(root: string, sessionId: string, threadId: string): CodexGenerationEndpoint | null {
   const ledger = readCodexGenerationLedger(root)
   const binding = ledger.bindings[sessionId]

package/spec-cli/src/commit-surgery.ts

@@ -2,6 +2,7 @@ import { execFileSync } from 'node:child_process'
 import { relative } from 'node:path'
 import { materialize, stripSpexcodeBlock, GENERATED_MARK } from './materialize.js'
 import { HARNESSES } from './harness.js'
+import { gitBinary } from './git.js'
 
 // GIT ENV, deliberately INVERTED from git.ts's git(): every call here PRESERVES the hook's environment —
 // GIT_INDEX_FILE must be honored so the surgery reads/writes the EXACT index this commit is being built
@@ -9,7 +10,7 @@ import { HARNESSES } from './harness.js'
 // operating on the real one would silently miss them). git.ts strips that env for repo DISCOVERY reasons;
 // index surgery is the one place the env is the point.
 const raw = (args: string[], input?: string): string =>
-  execFileSync('git', args, { input, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] })
+  execFileSync(gitBinary(process.env), args, { input, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] })
 
 function inHead(p: string): boolean {
   try { raw(['cat-file', '-e', `HEAD:${p}`]); return true } catch { return false }

package/spec-cli/src/contract-filter.ts

@@ -1,9 +1,10 @@
-import { mkdirSync, readFileSync, rmSync, writeFileSync, chmodSync, existsSync } from 'node:fs'
+import { mkdirSync, readFileSync, rmSync, chmodSync, existsSync, readdirSync, statSync } from 'node:fs'
 import { join, relative } from 'node:path'
 import { execFileSync } from 'node:child_process'
-import { git } from './git.js'
+import { git, gitBinary } from './git.js'
 import { writeManagedBlock, removeManagedBlock } from './harness.js'
 import { encodeProject, runtimeRoot, treeSlotDir } from './layout.js'
+import { writeFileIfChanged } from './file-write.js'
 
 // the three field-sharpened edges this module owes ([[content-filter]]):
 //   ① the configured command points at a STABLE shim path and degrades to `cat` (identity) when the shim is
@@ -20,20 +21,13 @@ function commonDirOf(proj: string): string {
 }
 const filterDir = (common: string) => join(common, 'spexcode')
 const shimPath = (common: string) => join(filterDir(common), 'contract-filter.sh')
-const blockPath = (common: string) => join(filterDir(common), 'contract-block.md')
 const rootPath = (common: string) => join(filterDir(common), 'contract-filter-root')
 const bindingsPath = (common: string) => join(filterDir(common), 'contract-filter-bindings')
 const treeFilterDir = (proj: string) => join(treeSlotDir(proj), 'contract-filter')
 const attributesPath = (common: string) => join(common, 'info', 'attributes')
 
-const registeredSlots = (proj: string) => git(['-C', proj, 'worktree', 'list', '--porcelain', '-z']).split('\0')
-  .filter((row) => row.startsWith('worktree ')).map((row) =>
-    join(runtimeRoot(proj), 'trees', encodeProject(row.slice('worktree '.length))))
-const legacyFilterTree = (proj: string) => registeredSlots(proj)
-  .some((slot) => existsSync(join(slot, 'content-hash')) && !existsSync(join(slot, 'contract-filter-v2')))
-
 export type ContractFilterPayload = { file: string; content: string }
-export type ContractFilterBinding = { file: string; start: string; end: string; legacy?: boolean }
+export type ContractFilterBinding = { file: string; start: string; end: string }
 
 // The common shim both filter directions run through. Pure shell/awk (no node boot on git's hot path), it
 // resolves the invoking checkout to that tree's payload before mirroring managed-block normalization:
@@ -48,19 +42,15 @@ set -u
 mode="\${1:?usage: contract-filter.sh smudge|clean <path>}"
 path="\${2:?usage: contract-filter.sh smudge|clean <path>}"
 here="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
-binding="$(awk -F '\t' -v p="$path" '$1 == p { print $2 "\t" $3 "\t" $4; exit }' "$here/contract-filter-bindings" 2>/dev/null)"
+binding="$(awk -F '\t' -v p="$path" '$1 == p { print $2 "\t" $3; exit }' "$here/contract-filter-bindings" 2>/dev/null)"
 [ -n "$binding" ] || { cat; exit 0; }
 start="\${binding%%$'\t'*}"; rest="\${binding#*$'\t'}"
-end="\${rest%%$'\t'*}"; legacy="\${rest#*$'\t'}"
+end="$rest"
 top="$(git rev-parse --show-toplevel 2>/dev/null || true)"
 root="$(cat "$here/contract-filter-root" 2>/dev/null || true)"
 key="$(printf '%s' "$top" | sed 's#[/.]#-#g')"
 manifest="$root/trees/$key/contract-filter/manifest"
 payload="$(awk -F '\t' -v p="$path" '$1 == p { print $2; exit }' "$manifest" 2>/dev/null)"
-# A pre-v2 tree has only the old common payload. Once that tree materializes, its marker makes a missing
-# per-file payload mean identity (for example, AGENTS.md in a Claude-only tree), never global fallback.
-marker="$root/trees/$key/contract-filter-v2"
-if [ ! -r "$payload" ] && [ ! -f "$marker" ] && [ "$legacy" = 1 ] && [ -r "$here/contract-block.md" ]; then payload="$here/contract-block.md"; fi
 strip() {
   awk -v sline="$start" -v eline="$end" 'BEGIN { n = 0 }
     { lines[n++] = $0 }
@@ -105,33 +95,54 @@ const filterCmd = (shim: string, mode: 'smudge' | 'clean') =>
 
 // plant (or refresh) the filter for the given contract files (tracked, or untracked-with-host-content —
 // pre-armed): the shim + the block content it smudges, the per-clone git config, and the attribute lines
-// binding each file to the filter. Idempotent — every write is a full replace. `contract` is the assembled
-// block body (guide + surface:system). settleIndexStat skips untracked entries (no index blob) by design.
-export function plantContractFilter(proj: string, payloads: ContractFilterPayload[], bindings: ContractFilterBinding[]): void {
+// binding each file to the filter. `contract` is the assembled block body (guide + surface:system).
+// settleIndexStat skips untracked entries (no index blob) by design and only runs after a real filter change.
+export function plantContractFilter(proj: string, payloads: ContractFilterPayload[], bindings: ContractFilterBinding[], changedFiles: readonly string[] = []): boolean {
   const common = commonDirOf(proj)
   mkdirSync(filterDir(common), { recursive: true })
-  writeFileSync(shimPath(common), SHIM)
-  chmodSync(shimPath(common), 0o755)
-  git(['-C', proj, 'config', 'filter.spexcode.smudge', filterCmd(shimPath(common), 'smudge')])
-  git(['-C', proj, 'config', 'filter.spexcode.clean', filterCmd(shimPath(common), 'clean')])
-  writeFileSync(bindingsPath(common), bindings.map((b) => `${b.file}\t${b.start}\t${b.end}\t${b.legacy ? 1 : 0}`).join('\n') + '\n')
+  let changed = writeFileIfChanged(shimPath(common), SHIM)
+  if (changed || (statSync(shimPath(common)).mode & 0o777) !== 0o755) chmodSync(shimPath(common), 0o755)
+  const commands = new Map([
+    ['filter.spexcode.smudge', filterCmd(shimPath(common), 'smudge')],
+    ['filter.spexcode.clean', filterCmd(shimPath(common), 'clean')],
+  ])
+  const configured = new Map<string, string>()
+  try {
+    for (const row of git(['-C', proj, 'config', '--get-regexp', '^filter\\.spexcode\\.(smudge|clean)$']).trimEnd().split('\n')) {
+      const at = row.indexOf(' ')
+      if (at > 0) configured.set(row.slice(0, at), row.slice(at + 1))
+    }
+  } catch {}
+  for (const [key, command] of commands) {
+    if (configured.get(key) === command) continue
+    git(['-C', proj, 'config', key, command])
+    changed = true
+  }
+  changed = writeFileIfChanged(bindingsPath(common), bindings.map((b) => `${b.file}\t${b.start}\t${b.end}`).join('\n') + '\n') || changed
   const dir = treeFilterDir(proj)
-  rmSync(dir, { recursive: true, force: true }); mkdirSync(dir, { recursive: true })
+  mkdirSync(dir, { recursive: true })
   const manifest: string[] = []
+  const wanted = new Set(['manifest'])
   for (const [i, payload] of payloads.entries()) {
     const target = join(dir, String(i))
-    writeFileSync(target, payload.content.endsWith('\n') ? payload.content : `${payload.content}\n`)
+    wanted.add(String(i))
+    changed = writeFileIfChanged(target, payload.content.endsWith('\n') ? payload.content : `${payload.content}\n`) || changed
     manifest.push(`${payload.file}\t${target}`)
   }
+  for (const entry of readdirSync(dir)) {
+    if (!wanted.has(entry)) { rmSync(join(dir, entry), { recursive: true, force: true }); changed = true }
+  }
   const manifestPath = join(dir, 'manifest')
-  writeFileSync(manifestPath, manifest.join('\n') + (manifest.length ? '\n' : ''))
-  writeFileSync(rootPath(common), `${runtimeRoot(proj)}\n`)
+  changed = writeFileIfChanged(manifestPath, manifest.join('\n') + (manifest.length ? '\n' : '')) || changed
+  changed = writeFileIfChanged(rootPath(common), `${runtimeRoot(proj)}\n`) || changed
   // Attribute patterns are checkout-relative; the stable binding set is safe in the common git dir because
   // the driver selects a payload from the invoking checkout's tree slot.
   const entries = bindings.map((b) => `/${b.file} filter=spexcode`).sort().join('\n')
   mkdirSync(join(common, 'info'), { recursive: true })
-  writeManagedBlock(attributesPath(common), entries, ['# ', ''])
-  settleIndexStat(proj, payloads.map((p) => join(proj, p.file)))
+  changed = writeManagedBlock(attributesPath(common), entries, ['# ', '']) || changed
+  const settle = changed ? payloads.map((p) => join(proj, p.file)) : changedFiles
+  if (settle.length) settleIndexStat(proj, [...new Set(settle)])
+  return changed
 }
 
 // settle the index STAT for each file — the famous filtered-path phantom-`M`: git cannot verify a
@@ -150,7 +161,7 @@ export function settleIndexStat(proj: string, files: string[]): void {
     const rel = relative(proj, f)
     try {
       const indexBlob = git(['-C', proj, 'rev-parse', `:${rel}`]).trim()
-      const filtered = execFileSync('git', ['-C', proj, 'hash-object', '--path', rel, '--stdin'],
+      const filtered = execFileSync(gitBinary(env), ['-C', proj, 'hash-object', '--path', rel, '--stdin'],
         { input: readFileSync(f), env, stdio: ['pipe', 'pipe', 'ignore'] }).toString().trim()
       if (indexBlob === filtered) git(['-C', proj, 'add', '--renormalize', '--', rel])
     } catch { /* best-effort */ }
@@ -160,24 +171,29 @@ export function settleIndexStat(proj: string, files: string[]): void {
 // the full inverse (edge ③ — call AFTER the managed blocks left the working files): attribute lines out,
 // config keys unset, shim + block content removed. `<common>/spexcode/` may host other spexcode data
 // (evidence blobs), so only OUR two files go, never the dir.
+export function clearContractFilterPayload(proj: string, files: string[] = []): void {
+  try { rmSync(treeFilterDir(proj), { recursive: true, force: true }) } catch { /* inaccessible tree */ }
+  settleIndexStat(proj, files)
+}
+
 export function removeContractFilter(proj: string, files: string[] = [], final = false): void {
   let common: string
   try { common = commonDirOf(proj) } catch { return }   // not a git repo → nothing was ever planted
-  try { rmSync(treeFilterDir(proj), { recursive: true, force: true }) } catch { /* inaccessible tree */ }
-  settleIndexStat(proj, files)
-  const anotherPayload = registeredSlots(proj).some((slot) => existsSync(join(slot, 'contract-filter', 'manifest')))
-  const legacyTree = legacyFilterTree(proj)
-  if (!legacyTree) rmSync(blockPath(common), { force: true })
-  if (!final && (anotherPayload || legacyTree)) return
+  clearContractFilterPayload(proj, files)
+  const anotherPayload = final ? false : (() => {
+    const rows = git(['-C', proj, 'worktree', 'list', '--porcelain', '-z']).split('\0')
+    const root = runtimeRoot(proj)
+    return rows
+      .filter((row) => row.startsWith('worktree '))
+      .map((row) => row.slice('worktree '.length))
+      .some((tree) => existsSync(join(root, 'trees', encodeProject(tree), 'contract-filter', 'manifest')))
+  })()
+  if (!final && anotherPayload) return
   removeManagedBlock(attributesPath(common), ['# ', ''], true)
   for (const key of ['filter.spexcode.smudge', 'filter.spexcode.clean']) {
     try { git(['-C', proj, 'config', '--unset-all', key]) } catch { /* not set — already clean */ }
   }
-  for (const path of [shimPath(common), blockPath(common), rootPath(common), bindingsPath(common)]) rmSync(path, { force: true })
-}
-
-export function retireLegacyContractBlock(proj: string): void {
-  if (!legacyFilterTree(proj)) rmSync(blockPath(commonDirOf(proj)), { force: true })
+  for (const path of [shimPath(common), rootPath(common), bindingsPath(common)]) rmSync(path, { force: true })
 }
 
 // is the filter currently planted? (the assert-side probe tests use; cheap: one config read)