spexcode 0.5.3 → 0.5.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spexcode",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "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/hooks/dispatch.sh

@@ -43,6 +43,16 @@ proj="${CLAUDE_PROJECT_DIR:-$PWD}"
 rt="$(cd "$proj" 2>/dev/null && hp_runtime_dir)" || rt=""
 slot="$(cd "$proj" 2>/dev/null && hp_tree_dir)" || slot=""
 
+# A project transport can outlive the tree that installed it. The current tree's last successful materialize
+# is the authority for whether its events are active. Before the v1 marker, an absent allowlist is the legacy
+# shape; afterwards absence means this tree never successfully selected a harness and dispatch stays inert.
+allowed="$slot/harnesses"
+if [ -f "$allowed" ]; then
+  grep -Fxq "$harness" "$allowed" || exit 0
+elif [ -f "$rt/harness-selection-v1" ]; then
+  exit 0
+fi
+
 # --- dispatch ---------------------------------------------------------------------------------------------
 if [ -n "${SPEX_HOOK_MANIFEST:-}" ]; then
   manifest="$SPEX_HOOK_MANIFEST"

package/spec-cli/src/cli.ts

@@ -1006,10 +1006,10 @@ if (cmd === 'serve') {
     if (!owner) { console.error('maintenance_identity_unknown: hook dispatcher owner identity is not exact'); process.exit(2) }
     sessionMaintenance().finishExternalOperation(ticket, owner)
   } else if (sub === 'shared-runtime-spawn') {
-    const [cwd, logFile, pidFile, isolationFile, command] = process.argv.slice(4, 9)
+    const [cwd, logFile, pidFile, receiptFile, command] = process.argv.slice(4, 9)
     const args = process.argv.slice(9)
-    if (!cwd || !logFile || !pidFile || !isolationFile || !command) {
-      console.error('usage: spex internal shared-runtime-spawn <cwd> <log> <pid-file> <isolation-file> <command> [args...]')
+    if (!cwd || !logFile || !pidFile || !receiptFile || !command) {
+      console.error('usage: spex internal shared-runtime-spawn <cwd> <log> <pid-file> <receipt-file> <command> [args...]')
       process.exit(2)
     }
     const { readFileSync } = await import('node:fs')
@@ -1029,7 +1029,7 @@ if (cmd === 'serve') {
     delete env.SPEXCODE_MAINTENANCE_SESSION_ID
     delete env.SPEXCODE_SESSION_ID
     const runtime = await runSessionOperation({ op: 'shared-spawn', sessionId, ...(delegateChannelPresent ? { delegate } : {}) }, () =>
-      spawnDetachedRuntime({ cwd, logFile, pidFile, isolationFile, command, args, env }))
+      spawnDetachedRuntime({ cwd, logFile, pidFile, receiptFile, command, args, env }))
     console.log(runtime.pid)
   } else if (sub === 'codex-launch') {
     // BACKEND-owned codex thread. On the shared per-project app-server: thread/start { cwd = this worktree }
@@ -1130,10 +1130,11 @@ if (cmd === 'serve') {
     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-fail') {
-    // the StopFailure hook marks its session (--session from the payload) as error (turn died on an API error)
-    const { s, sess, mark, noRecord } = await stateKit()
-    const failed = mark(() => s.markError(sess))
-    console.log(failed.ok ? 'marked error' : failed.reason ?? noRecord())
+    // 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.
+    const { s, sess, mark } = await stateKit()
+    const failed = mark(() => s.markTurnFailure(sess, 'claude turn failed'))
+    console.log(failed.ok ? 'marked error' : failed.reason ?? 'noop (session is not live active)')
   } else if (sub === 'session-turn-fail') {
     // Headless adapters report an ephemeral turn's non-zero exit through this one shared CAS. A declaration
     // that landed before teardown wins, so a late child close can never erase an agent-authored state.
@@ -1143,7 +1144,7 @@ if (cmd === 'serve') {
       process.exit(2)
     }
     const { markHeadlessTurnFailure } = await import('./sessions.js')
-    console.log(markHeadlessTurnFailure(sessionId, harness, exitCode) ? `marked error (${harness} ${exitCode})` : 'noop (no active session record)')
+    console.log(markHeadlessTurnFailure(sessionId, harness, exitCode) ? `marked error (${harness} ${exitCode})` : 'noop (session is not live active)')
   } else if (sub === 'session-idle') {
     // the Notification(idle_prompt) hook marks its session (--session from the payload) idle when claude waits
     // at its prompt. INFERRED, so guarded active-only: it no-ops unless the current status is exactly `active`,

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

@@ -1,8 +1,9 @@
-import { mkdirSync, readFileSync, rmSync, writeFileSync, chmodSync } from 'node:fs'
+import { mkdirSync, readFileSync, rmSync, writeFileSync, chmodSync, existsSync } from 'node:fs'
 import { join, relative } from 'node:path'
 import { execFileSync } from 'node:child_process'
 import { git } from './git.js'
 import { writeManagedBlock, removeManagedBlock } from './harness.js'
+import { encodeProject, runtimeRoot, treeSlotDir } from './layout.js'
 
 // @@@ contract-filter ([[content-filter]]) - the answer for a MIXED-CONTENT contract file: a
 // CLAUDE.md/AGENTS.md the HOST TRACKS — or has begun writing its OWN prose into — where "generate + ignore"
@@ -34,30 +35,54 @@ 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')
 
-// the per-clone shim both filter directions run through. Pure shell/awk (no node boot on git's hot path),
-// mirroring writeManagedBlock/removeManagedBlock's normalization exactly so the two writers agree:
+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 }
+
+// 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:
 //   clean : drop the sentinel block (+ the blank line smudge printed before it) → the pristine host prose.
-//   smudge: clean first (defensive — a block already in the index can never double-inject), then append one
-//           blank line + START + the contract-block file's content + END.
+//   smudge: clean first (a block already in the index can never double-inject), then append the tree payload.
 // Byte-exactness holds for text ending in exactly one newline (git's own well-formed-text shape); a pristine
 // file ending in zero or 2+ newlines is normalized to one on the first round-trip and stable after.
 const SHIM = `#!/usr/bin/env bash
-# spexcode contract filter (generated by spex materialize; see [[content-filter]]).
-# clean(smudge(x)) == x: the repo keeps the pristine host prose, the working tree carries prose + block.
+# spexcode managed-text filter (generated by spex materialize; see [[content-filter]]).
+# One common driver selects the payload belonging to the Git checkout that invoked it.
 set -u
-mode="\${1:?usage: contract-filter.sh smudge|clean}"
+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)"
-block="$here/contract-block.md"
+binding="$(awk -F '\t' -v p="$path" '$1 == p { print $2 "\t" $3 "\t" $4; 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'}"
+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 'BEGIN { n = 0 }
+  awk -v sline="$start" -v eline="$end" 'BEGIN { n = 0 }
     { lines[n++] = $0 }
     END {
       s = -1; e = -1
       for (i = 0; i < n; i++) {
-        if (lines[i] == "<!-- spexcode:start -->" && s < 0) s = i
-        if (lines[i] == "<!-- spexcode:end -->" && s >= 0 && e < 0) e = i
+        if (lines[i] == sline && s < 0) s = i
+        if (lines[i] == eline && s >= 0 && e < 0) e = i
       }
       if (s >= 0 && e >= s) {
         a = s; while (a > 0 && lines[a-1] == "") a--
@@ -66,24 +91,22 @@ strip() {
         for (i = 0; i < n; i++) if (i < a || i > b) lines[j++] = lines[i]
         n = j
       }
-      # NO leading-blank strip: dropping a..b (block + its surrounding blanks) can never CREATE a leading
-      # blank, and a host file that BEGINS with blank lines must keep them — clean(smudge(x)) == x.
       for (i = 0; i < n; i++) print lines[i]
     }'
 }
 case "$mode" in
   clean) strip ;;
   smudge)
-    if [ ! -r "$block" ]; then cat; exit 0; fi          # no block content → identity (graceful, never fatal)
-    strip | awk -v b="$block" 'BEGIN { n = 0 }
+    if [ ! -r "$payload" ]; then strip; exit 0; fi
+    strip | awk -v b="$payload" -v sline="$start" -v eline="$end" 'BEGIN { n = 0 }
       { lines[n++] = $0 }
       END {
-        while (n > 0 && lines[n-1] == "") n--           # trim trailing blanks (writeManagedBlock parity)
+        while (n > 0 && lines[n-1] == "") n--
         for (i = 0; i < n; i++) print lines[i]
         if (n > 0) print ""
-        print "<!-- spexcode:start -->"
+        print sline
         while ((getline l < b) > 0) print l
-        print "<!-- spexcode:end -->"
+        print eline
       }' ;;
   *) echo "contract-filter.sh: unknown mode $mode" >&2; exit 1 ;;
 esac
@@ -92,25 +115,37 @@ esac
 // edge ①: the command git runs is a tolerant wrapper — the shim path is an ARGUMENT ($0), and a missing/
 // unreadable shim degrades to `cat` (identity) instead of a per-operation fatal.
 const filterCmd = (shim: string, mode: 'smudge' | 'clean') =>
-  `sh -c 'test -r "$0" && exec bash "$0" ${mode} || exec cat' '${shim.replace(/'/g, `'\\''`)}'`
+  `sh -c 'test -r "$0" && exec bash "$0" ${mode} "$1" || exec cat' '${shim.replace(/'/g, `'\\''`)}' %f`
 
 // 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, trackedFiles: string[], contract: string): void {
+export function plantContractFilter(proj: string, payloads: ContractFilterPayload[], bindings: ContractFilterBinding[]): void {
   const common = commonDirOf(proj)
   mkdirSync(filterDir(common), { recursive: true })
-  writeFileSync(blockPath(common), contract.endsWith('\n') ? contract : `${contract}\n`)   // edge ②: the shim's smudge source, refreshed with the materialize
   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')])
-  // attribute patterns are checkout-relative, so one line serves the main checkout and every worktree.
-  const entries = trackedFiles.map((f) => `/${relative(proj, f)} filter=spexcode`).sort().join('\n')
+  writeFileSync(bindingsPath(common), bindings.map((b) => `${b.file}\t${b.start}\t${b.end}\t${b.legacy ? 1 : 0}`).join('\n') + '\n')
+  const dir = treeFilterDir(proj)
+  rmSync(dir, { recursive: true, force: true }); mkdirSync(dir, { recursive: true })
+  const manifest: string[] = []
+  for (const [i, payload] of payloads.entries()) {
+    const target = join(dir, String(i))
+    writeFileSync(target, payload.content.endsWith('\n') ? payload.content : `${payload.content}\n`)
+    manifest.push(`${payload.file}\t${target}`)
+  }
+  const manifestPath = join(dir, 'manifest')
+  writeFileSync(manifestPath, manifest.join('\n') + (manifest.length ? '\n' : ''))
+  writeFileSync(rootPath(common), `${runtimeRoot(proj)}\n`)
+  // 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, trackedFiles)
+  settleIndexStat(proj, payloads.map((p) => join(proj, p.file)))
 }
 
 // settle the index STAT for each file — the famous filtered-path phantom-`M`: git cannot verify a
@@ -139,15 +174,24 @@ 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 removeContractFilter(proj: string): void {
+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
   removeManagedBlock(attributesPath(common), ['# ', ''], true)
   for (const key of ['filter.spexcode.smudge', 'filter.spexcode.clean']) {
-    try { git(['-C', proj, 'config', '--unset', key]) } catch { /* not set — already clean */ }
+    try { git(['-C', proj, 'config', '--unset-all', key]) } catch { /* not set — already clean */ }
   }
-  rmSync(shimPath(common), { force: true })
-  rmSync(blockPath(common), { force: true })
+  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 })
 }
 
 // is the filter currently planted? (the assert-side probe tests use; cheap: one config read)

package/spec-cli/src/guide.ts

@@ -282,7 +282,8 @@ see LAUNCHERS.
 
 ── LAYOUT (spexcode.json — portable; set only for a NON-DEFAULT repo layout) ──
   main          path to the source-of-truth checkout. Default: the \`main\` worktree.
-  mainBranch    the source-of-truth BRANCH worktrees fork from. Default: auto-detected.
+  mainBranch    the stable source-of-truth BRANCH worktrees fork from. spex init stamps the root checkout's
+                branch at adoption; an older omitted value uses the conventional main.
   branchPrefix  how a node branch is named. Default "node/".
 Example — a repo whose trunk is \`staging\`, not \`main\`:
   { "mainBranch": "staging" }