spexcode 0.5.4 → 0.5.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spexcode",
-  "version": "0.5.4",
+  "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

@@ -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/harness.ts

@@ -37,6 +37,8 @@ export type HarnessLaunchReadinessFence = {
   readonly proof: Readonly<Record<string, unknown>>
   validate(current: () => HarnessLaunchReadyRecord | null): Promise<boolean>
 }
+export type TurnFailure = { message: string; completedAt: number | null }
+export type FailureSubscription = { close(): void; readonly closed: Promise<string | null> }
 // the per-pane runtime probe the caller snapshots ONCE for the whole session list and hands liveness():
 // the pane's root pid (tmux `#{pane_pid}`), the hot-tier `pidAlive` verdict, and — ONLY on the legacy path —
 // one whole-box pid→(ppid, comm) table (a single `ps` spawn).
@@ -132,6 +134,8 @@ export async function adapterLoadedReferenceState(
 
 export interface Harness {
   readonly id: HarnessId
+  // the id baked into the materialized shim. Headless variants reuse their native family's shim.
+  readonly dispatchId: 'claude' | 'codex' | 'opencode' | 'pi'
   // whether this harness runs without an interactive TUI. The dashboard launcher picker hides headless
   // adapters by default ([[launcher-visibility]]); CLI launcher resolution never consumes that policy.
   readonly headless: boolean
@@ -192,6 +196,9 @@ export interface Harness {
   // --- materialize: shim + contract + trust ([[harness-delivery]]) ---
   // the auto-discovered hook shim file for this harness (.claude/settings.json vs .codex/hooks.json).
   shimFile(proj: string): string
+  // whether that shim belongs to one checkout or the whole project. This is adapter placement data: Codex
+  // reads one root-checkout hook file for every linked tree; the other harnesses discover their tree-local file.
+  shimScope: 'tree' | 'project'
   // a LINKED WORKTREE's extra shim copy — the worktree-side `.codex` hook file that ANCHORS codex's project
   // config layer, or null when the harness needs none. codex-rs only builds a project config layer (and thus
   // only DISCOVERS a worktree thread's hooks) for a dir in [cwd..project_root] that contains a `.codex/`
@@ -267,6 +274,9 @@ export interface Harness {
   // (mid-turn, not queued for after the agent stops) or `turn/start`s a fresh turn when the thread is idle.
   // Returns ok=false with a reason that propagates to the API.
   deliver(rec: HarnessDeliveryRecord, text: string): Promise<DispatchResult>
+  // Observe native turn failures that this harness does not expose as a lifecycle hook. The adapter owns the
+  // transport subscription; sessions owns observer reconciliation and the active-only lifecycle CAS.
+  observeTurnFailures?(rec: HarnessDeliveryRecord, onFailure: (failure: TurnFailure) => void): FailureSubscription
   // Hard-interrupt the current turn through the harness's native control plane. Optional because a harness
   // without a confirmed native interrupt must refuse rather than emulate one with a signal or PTY key.
   interrupt?(rec: HarnessDeliveryRecord): Promise<DispatchResult>
@@ -304,7 +314,7 @@ export interface Harness {
   // skill/agent files named in `arts` — never the user's surrounding prose, their other settings, or any .spec
   // data. materialize calls it for every UNSELECTED harness, so dropping a harness from spexcode.json's
   // `harnesses` prunes that harness's products on the next re-materialize.
-  clean(proj: string, arts: HarnessArtifacts): void
+  clean(proj: string, arts: HarnessArtifacts, preserveProject?: boolean): void
   // the inverse of writeTrust: strip THIS project's spexcode trust block from the harness's global config.
   // Codex removes its `~/.codex/config.toml` block; Claude is a no-op (it wrote none).
   removeTrust(proj: string): void
@@ -816,6 +826,106 @@ function drainWsFrames(s: FrameState, conn: Socket, onText: (json: string) => vo
 const WS_UPGRADE = (key: string) => `GET /rpc HTTP/1.1\r\nHost: localhost\r\nConnection: Upgrade\r\nUpgrade: websocket\r\nSec-WebSocket-Version: 13\r\nSec-WebSocket-Key: ${key}\r\n\r\n`
 const wsInitialize: JsonRpc = { id: 1, method: 'initialize', params: { clientInfo: { name: 'spexcode', title: 'SpexCode', version: '0.0.0' }, capabilities: { experimentalApi: true, requestAttestation: false } } }
 
+// Codex has no StopFailure hook, but its app-server has the stronger native signal: every subscribed turn ends
+// with turn/completed and a final completed/interrupted/failed status. Rejoin is atomic with subscription, so
+// this observer also survives backend replacement; a thread already in systemError is reconciled from its
+// latest turn before later live notifications take over.
+export function codexTurnFailureObserver(
+  rec: HarnessDeliveryRecord,
+  onFailure: (failure: TurnFailure) => void,
+): FailureSubscription {
+  const threadId = rec.harnessSessionId
+  if (!threadId) return { close: () => {}, closed: Promise.resolve(null) }
+  const sock = codexAppServerSock(rec.runtimeDir || runtimeRoot())
+  const conn: Socket = createConnection(sock)
+  const frames: FrameState = { buf: Buffer.alloc(0), fragOp: 0, fragBuf: Buffer.alloc(0) }
+  let upgraded = false, settled = false
+  let reconciliationTimer: ReturnType<typeof setTimeout> | null = null
+  let resolveClosed!: (reason: string | null) => void
+  const closed = new Promise<string | null>((resolve) => { resolveClosed = resolve })
+  const cancelReconciliation = () => {
+    if (!reconciliationTimer) return
+    clearTimeout(reconciliationTimer)
+    reconciliationTimer = null
+  }
+  const finish = (reason: string | null) => {
+    if (settled) return
+    settled = true
+    clearTimeout(timer)
+    cancelReconciliation()
+    try { conn.destroy() } catch {}
+    resolveClosed(reason)
+  }
+  const timer = setTimeout(() => finish('Codex turn observer did not subscribe within 5000ms'), 5000)
+  timer.unref?.()
+  const send = (message: JsonRpc) => conn.write(wsText(JSON.stringify(message)))
+  const report = (turn: unknown, fallbackMessage?: string) => {
+    const value = turn as { status?: unknown; completedAt?: unknown; error?: { message?: unknown } | null }
+    if (value?.status !== 'failed' && !fallbackMessage) return
+    const nativeMessage = typeof value?.error?.message === 'string' ? value.error.message.trim() : ''
+    onFailure({
+      message: nativeMessage || fallbackMessage || 'Codex turn failed',
+      completedAt: typeof value?.completedAt === 'number' && Number.isFinite(value.completedAt) ? value.completedAt : null,
+    })
+  }
+  conn.on('error', (error) => finish(`Codex turn observer connection failed: ${rpcError(error)}`))
+  conn.on('close', () => finish('Codex turn observer connection closed'))
+  conn.on('connect', () => conn.write(WS_UPGRADE(randomBytes(16).toString('base64'))))
+  const handle = (json: string) => {
+    let message: JsonRpc
+    try { message = JSON.parse(json) } catch { return }
+    if (message.error) return finish(`Codex turn observer request failed: ${message.error.message || JSON.stringify(message.error)}`)
+    if (message.id === 1 && message.result) {
+      send({ method: 'initialized', params: {} })
+      return send({
+        id: 2,
+        method: 'thread/resume',
+        params: { threadId, excludeTurns: true, initialTurnsPage: { limit: 1, sortDirection: 'desc', itemsView: 'notLoaded' } },
+      })
+    }
+    if (message.id === 2 && message.result) {
+      clearTimeout(timer)
+      const result = message.result as { thread?: { status?: { type?: unknown } }; initialTurnsPage?: { data?: unknown } }
+      if (result.thread?.status?.type === 'systemError') {
+        const turns = result.initialTurnsPage?.data
+        const latest = Array.isArray(turns) ? turns[0] : null
+        // Give a concurrently-starting turn's native notification precedence over this historical snapshot.
+        reconciliationTimer = setTimeout(() => {
+          reconciliationTimer = null
+          report(latest, 'Codex thread entered systemError before the turn observer subscribed')
+        }, 100)
+        reconciliationTimer.unref?.()
+      }
+      return
+    }
+    if (message.method === 'turn/started') {
+      const params = message.params as { threadId?: unknown } | undefined
+      if (params?.threadId === threadId) cancelReconciliation()
+    }
+    if (message.method === 'turn/completed') {
+      const params = message.params as { threadId?: unknown; turn?: unknown } | undefined
+      if (params?.threadId === threadId) {
+        cancelReconciliation()
+        report(params.turn)
+      }
+    }
+  }
+  conn.on('data', (chunk: Buffer) => {
+    frames.buf = Buffer.concat([frames.buf, chunk])
+    if (!upgraded) {
+      const split = frames.buf.indexOf('\r\n\r\n')
+      if (split < 0) return
+      const head = frames.buf.slice(0, split).toString('utf8')
+      if (!/^HTTP\/1\.1 101/.test(head)) return finish(`Codex app-server refused turn observer: ${head.split('\r\n')[0]}`)
+      upgraded = true
+      frames.buf = frames.buf.slice(split + 4)
+      send(wsInitialize)
+    }
+    if (drainWsFrames(frames, conn, handle)) finish('Codex app-server closed the turn observer')
+  })
+  return { close: () => finish(null), closed }
+}
+
 // Protocol-verified cold/restore seam. The Codex schema (`codex app-server generate-json-schema --experimental`)
 // defines thread/archive and thread/unarchive with {threadId}; no guessed method or process command is used.
 type CodexGenerationFence = { dir: string; generation: string }
@@ -1787,16 +1897,16 @@ function isTrackedFile(proj: string, f: string): boolean {
 // block; the skill/agent files sit at name-scoped paths reconstructed from `arts`. So it removes ONLY our own
 // blocks and our own named products — never a user's CLAUDE.md/AGENTS.md prose, a hand-made settings.json, or
 // a sibling skill/agent the user added, and NEVER any .spec data.
-function cleanHarness(h: Harness, proj: string, arts: HarnessArtifacts): void {
+function cleanHarness(h: Harness, proj: string, arts: HarnessArtifacts, preserveProject = false): void {
   // deleteIfEmpty ONLY for an UNTRACKED contract file: a wholly-ours generated file goes; a HOST-TRACKED file
   // that carried nothing but our block (an empty committed CLAUDE.md we folded into) is stripped back to its
   // pristine emptiness but never deleted — deleting a tracked file would surface as a `D` in the host's status.
   for (const f of h.contractFiles(proj)) removeManagedBlock(f, ['<!-- ', ' -->'], !isTrackedFile(proj, f))
   const shim = h.shimFile(proj)
-  if (existsSync(shim) && readFileSync(shim, 'utf8').includes('dispatch.sh')) rmSync(shim, { force: true })
+  if ((h.shimScope === 'tree' || !preserveProject) && existsSync(shim) && readFileSync(shim, 'utf8').includes('dispatch.sh')) rmSync(shim, { force: true })
   const anchor = h.worktreeHookAnchor(proj)   // the linked-worktree anchor copy, same identity gate as the shim
   if (anchor && existsSync(anchor) && readFileSync(anchor, 'utf8').includes('dispatch.sh')) rmSync(anchor, { force: true })
-  h.removeTrust(proj)
+  if (!preserveProject) h.removeTrust(proj)
   const sd = h.skillDir(proj)
   if (sd) for (const n of arts.skills) rmSync(join(sd, n), { recursive: true, force: true })
   const ad = h.agentDir(proj)
@@ -1953,6 +2063,7 @@ const noLaunchEnv = (): string[] => []
 
 export const claudeHarness: Harness = {
   id: 'claude',
+  dispatchId: 'claude',
   headless: false,
   events: CLAUDE_EVENTS,
   ownsRendezvous: true,                              // reclaude opens the rendezvous control socket (prompt delivery + liveness)
@@ -1963,6 +2074,7 @@ export const claudeHarness: Harness = {
   sessionEnvVar: 'CLAUDE_CODE_SESSION_ID',
   launchEnv: rendezvousLaunchEnv,
   shimFile: (proj) => join(proj, '.claude', 'settings.json'),
+  shimScope: 'tree',
   worktreeHookAnchor: () => null,                    // claude's shim already lives in the worktree (.claude/settings.json) — self-anchors, no root rewrite
   contractFiles: (proj) => [join(proj, 'CLAUDE.md')],
   skillDir: (proj) => join(proj, '.claude', 'skills'),
@@ -1970,7 +2082,7 @@ export const claudeHarness: Harness = {
   shim: (dispatch, spex) => buildShim('claude', CLAUDE_EVENTS, dispatch, spex),
   writeTrust: () => [],                            // Claude relies on folder-trust — no artifact to report
   removeTrust: () => { /* Claude wrote no trust — nothing to strip */ },
-  clean(proj, arts) { cleanHarness(this, proj, arts) },
+  clean(proj, arts, preserveProject) { cleanHarness(this, proj, arts, preserveProject) },
   slashCommands: claudeSlashCommands,
   // online iff the window is up AND a LIVE LISTENER is on the rendezvous socket (`socketLive`, connect-probed by
   // the caller) — NOT the mere existence of a stale socket FILE a crashed claude leaves behind (the 30-min
@@ -2020,6 +2132,7 @@ export const claudeHeadlessHarness: Harness = {
 
 export const codexHarness: Harness = {
   id: 'codex',
+  dispatchId: 'codex',
   headless: false,
   sharedRuntimeSpawn: true,
   events: CODEX_EVENTS,
@@ -2038,6 +2151,7 @@ export const codexHarness: Harness = {
   // per-worktree (codex loads THOSE by walking the thread cwd). dispatch.sh resolves `proj` from the thread
   // cwd, so one shared shim serves every worktree.
   shimFile: (proj) => join(mainCheckout(proj), '.codex', 'hooks.json'),
+  shimScope: 'project',
   // a LINKED worktree also needs its OWN `.codex/hooks.json` so codex-rs anchors the project config layer for
   // the worktree cwd (without a `.codex/` under the worktree root, codex builds no layer, so the rewritten
   // root-checkout hooks are never discovered and NO hooks fire — bypass_hook_trust cannot rescue a layer that
@@ -2070,7 +2184,7 @@ export const codexHarness: Harness = {
   writeTrust: (proj, cmdFor) => [writeCodexTrust(mainCheckout(proj), CODEX_EVENTS, cmdFor)],
   // trust is keyed by the MAIN checkout (where the codex shim materializes) — strip it at the same key.
   removeTrust: (proj) => removeCodexTrust(mainCheckout(proj)),
-  clean(proj, arts) { cleanHarness(this, proj, arts) },
+  clean(proj, arts, preserveProject) { cleanHarness(this, proj, arts, preserveProject) },
   slashCommands: codexSlashCommands,
   // online iff the tmux window is up AND the agent is live. PRIMARY: the launch-registered `agent.pid` hot-tier
   // verdict (`pidAlive`) — a 100ms syscall (kill-0), no ps scan. LEGACY: a pre-registration session has no
@@ -2086,6 +2200,7 @@ export const codexHarness: Harness = {
   },
   leafOwnerNeedle: (rec) => rec.harnessSessionId ?? null,
   deliver: (rec, text) => deliverViaCodexAppServer(rec, text),
+  observeTurnFailures: codexTurnFailureObserver,
   cleanupRuntime: async () => { /* project-scoped app-server is shared; no per-session transport to remove */ },
   coldRetirementPreflight: async (rec) => {
     if (!rec.harnessSessionId) return { ok: false, reason: 'no exact Codex thread identity is registered' }
@@ -2354,6 +2469,7 @@ export const codexHeadlessHarness: Harness = {
 // one-run defence. See pi-harness.ts for the extension source + trust mechanics.
 export const piHarness: Harness = {
   id: 'pi',
+  dispatchId: 'pi',
   headless: false,
   events: PI_EVENTS,
   ownsRendezvous: true,                              // the generated extension binds rvSock(id) and speaks the reclaude protocol
@@ -2364,6 +2480,7 @@ export const piHarness: Harness = {
   sessionEnvVar: 'PI_SESSION_ID',                    // exported by the generated extension at session_start; tool subprocesses inherit it
   launchEnv: rendezvousLaunchEnv,
   shimFile: (proj) => join(proj, '.pi', 'extensions', 'spexcode.ts'),
+  shimScope: 'tree',
   worktreeHookAnchor: () => null,                    // the extension lives in the worktree and self-anchors, like claude
   contractFiles: (proj) => [join(proj, 'AGENTS.md')],   // pi auto-loads AGENTS.md context files (shared with codex — writeManagedBlock is idempotent)
   skillDir: (proj) => join(proj, '.pi', 'skills'),   // Agent Skills standard dirs, discovered after project trust
@@ -2374,7 +2491,7 @@ export const piHarness: Harness = {
   }),
   writeTrust: (proj) => [writePiTrust(mainCheckout(proj))], // trust keys on the MAIN checkout; nearest-parent lookup covers worktrees
   removeTrust: (proj) => removePiTrust(mainCheckout(proj)),
-  clean(proj, arts) { cleanHarness(this, proj, arts) },
+  clean(proj, arts, preserveProject) { cleanHarness(this, proj, arts, preserveProject) },
   slashCommands: piSlashCommands,
   // claude's exact liveness: the window is up AND a live LISTENER answers on the rendezvous socket — the
   // socket the generated extension binds. socketLive is already probed for every windowed session.
@@ -2409,6 +2526,7 @@ export const piHeadlessHarness: Harness = {
 
 export const opencodeHarness: Harness = {
   id: 'opencode',
+  dispatchId: 'opencode',
   headless: false,
   events: OPENCODE_EVENTS,
   // LITERALLY true: the generated plugin ([[opencode-harness]], opencode.ts) BINDS the per-session rendezvous
@@ -2428,6 +2546,7 @@ export const opencodeHarness: Harness = {
   // the "shim" is a generated opencode PLUGIN in the worktree's own tree — opencode auto-loads project plugins
   // by walking the cwd, so like claude it self-anchors and needs no root-checkout rewrite or worktree anchor.
   shimFile: (proj) => join(proj, '.opencode', 'plugins', 'spexcode.ts'),
+  shimScope: 'tree',
   worktreeHookAnchor: () => null,
   contractFiles: (proj) => [join(proj, 'AGENTS.md')],   // opencode reads AGENTS.md natively (same file codex owns; the managed block is idempotent across writers)
   skillDir: (proj) => join(proj, '.opencode', 'skills'),
@@ -2437,7 +2556,7 @@ export const opencodeHarness: Harness = {
   shim: (dispatch, spex) => ({ content: opencodePluginSource(dispatch, spex), cmd: (e) => `SPEX='${spex}' bash ${dispatch} opencode ${e}` }),
   writeTrust: () => [],                            // permission policy stays with the launcher command; no trust artifact to report
   removeTrust: () => { /* nothing was written */ },
-  clean(proj, arts) { cleanHarness(this, proj, arts) },
+  clean(proj, arts, preserveProject) { cleanHarness(this, proj, arts, preserveProject) },
   slashCommands: opencodeSlashCommands,
   // online iff the window is up AND the agent answers on a channel: PREFER the rendezvous socket listener
   // (the plugin is alive), FALL BACK to the launch-registered agent.pid (kill-0) so a plugin that failed to

package/spec-cli/src/index.ts

@@ -15,7 +15,7 @@ import { resolveLayout, mainBranch } from './layout.js'
 import { getBoardJson } from './graphCache.js'
 import { boardStream, closeBoardFileWatchers, ensureBoardFileWatchers, notifyBoardChanged } from './graphStream.js'
 import { gitA, gitTry, repoRoot } from './git.js'
-import { listSessions, sendText, interruptSession, rawKey, stopSession, closeSession, archiveSession, resumeSession, mergeSession, reviewPayload, captureSessionResult, sessionPrompt, sessionGraph, registerWatch, deregisterWatch, renameSession, setSessionSort, sessionCreateRequest, superviseQueue, SessionRecordUnusable, TMUX_SOCK } from './sessions.js'
+import { listSessions, sendText, interruptSession, rawKey, stopSession, closeSession, archiveSession, resumeSession, mergeSession, reviewPayload, captureSessionResult, sessionPrompt, sessionGraph, registerWatch, deregisterWatch, renameSession, setSessionSort, sessionCreateRequest, superviseQueue, superviseTurnFailures, SessionRecordUnusable, TMUX_SOCK } from './sessions.js'
 import { superviseTimeline, readTimeline } from './session-timeline.js'
 import { defaultHarness, HARNESSES, dashboardLauncherList, launcherDefault } from './harness.js'
 import { evalTimeline, readBlobByHash } from '../../spec-eval/src/evaltab.js'
@@ -684,6 +684,7 @@ installConnectionReaper(server as unknown as HttpServer)
 injectWebSocket(server)
 superviseBridges()   // restore visible helpers after failure; their viewer subscriptions survive replacement
 superviseQueue()     // launch queued sessions as slots free (catches agent-authored proposals/crashes the server never sees directly)
+superviseTurnFailures() // reconcile adapter-owned native failure subscriptions across backend replacement
 superviseTimeline()  // record authored-lifecycle transitions to each session's durable timeline ([[session-timeline]])
 console.log(`spec-cli serving .spec (from git) on http://localhost:${port}`)
 

package/spec-cli/src/materialize.ts

@@ -1,4 +1,4 @@
-import { writeFileSync, mkdirSync, readFileSync, existsSync, readdirSync, rmSync, rmdirSync } from 'node:fs'
+import { writeFileSync, mkdirSync, readFileSync, existsSync, readdirSync, renameSync, rmSync, rmdirSync } from 'node:fs'
 import { join, dirname, relative } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { execFileSync } from 'node:child_process'
@@ -6,10 +6,10 @@ import { loadSystemConfig, loadSkillConfig, loadAgentConfig, loadConfig } from '
 import { compileManifest } from './hooks.js'
 import { writeManagedBlock, removeManagedBlock, HARNESSES, type HarnessArtifacts } from './harness.js'
 import { git } from './git.js'
-import { runtimeRoot, treeSlotDir, mainCheckout, readConfig } from './layout.js'
+import { runtimeRoot, treeSlotDir, mainCheckout, readConfig, encodeProject } from './layout.js'
 import { resolveHarnessTargets, partitionHarnesses } from './harness-select.js'
 import { emitPlugin, cleanPlugin, pluginBundleDir, pluginVersion } from './plugin-harness.js'
-import { plantContractFilter, removeContractFilter, settleIndexStat } from './contract-filter.js'
+import { plantContractFilter, removeContractFilter, retireLegacyContractBlock, settleIndexStat, type ContractFilterBinding, type ContractFilterPayload } from './contract-filter.js'
 
 export type MaterializedArtifact = {
   kind: 'hook manifest' | 'contract' | 'shim' | 'skill' | 'agent' | 'plugin bundle' | 'trust'
@@ -34,8 +34,9 @@ export type MaterializeResult = { contentHash: string; planted: MaterializedArti
 // implementation is ERASE-THEN-ASSERT over a CLOSED set of landing points: each is first erased
 // unconditionally by its IDENTITY STAMP (sentinel blocks, the shim's dispatch.sh command line, the generated
 // mark on skills/agents, the filter config namespace, the skip-worktree bit), then rewritten per the current
-// policy (possibly to nothing). No ledger of past states, no pairwise migration branches — the erase IS the
-// migration, whatever the previous state was.
+// policy (possibly to nothing). There are no policy-pair branches. The one cross-tree migration receipt below
+// preserves old common ignore entries until every registered tree owns its local projection; it never reads or
+// reconstructs a sibling policy.
 
 const PKG = fileURLToPath(new URL('..', import.meta.url))                 // installed spec-cli root
 const DISPATCH = join(PKG, 'hooks', 'dispatch.sh')
@@ -64,8 +65,8 @@ export function contentHash(proj: string): string {
 // @@@ footprint kinds ([[residence]]) - the vote axis is RETIRED: materialized artifacts carry no facts, so
 // they are NEVER tracked — there is exactly ONE residence behavior, not three. `.spec` + `spexcode.json` are ALWAYS
 // tracked (git is the database — no knob can untrack them); machine facts (shims, spexcode.local.json),
-// run residue (.worktrees/), and wholly-ours artifacts are hidden by the per-clone .git/info/exclude (the
-// host's tracked .gitignore is never touched); a contract file the host TRACKS — or one the user has begun
+// run residue (.worktrees/) stays in the common exclude; tree-selected artifacts are hidden by a managed
+// working .gitignore block whose tracked bytes stay pristine through the content filter. A contract file the host TRACKS — or one the user has begun
 // writing THEIR OWN prose into — is covered by the clean/smudge content filter ([[content-filter]]). An
 // environment without the generator (a teammate's clone, CI, a cloud agent) runs `spex materialize` in its
 // setup step — there is no committed-artifact delivery mode.
@@ -74,7 +75,7 @@ export function retiredAxisNotice(cfg: { render?: string; private?: boolean }):
   const field = cfg.render?.trim() ? `"render": "${cfg.render.trim()}"` : '"private": true'
   console.error(
     `spexcode: the render vote is retired — ${field} is ignored. Materialized artifacts are never tracked:\n` +
-    `  ignore rules live in the per-clone .git/info/exclude, a host-tracked contract file is covered by the\n` +
+    `  tree-local ignore rules live in a filtered working .gitignore, and a host-tracked contract is covered by the\n` +
     `  clean/smudge filter, and a clone without spex runs \`spex materialize\` in its setup step. Remove the\n` +
     `  field from spexcode.json / spexcode.local.json to retire this notice (see \`spex guide footprint\`).`,
   )
@@ -90,6 +91,38 @@ function isTracked(proj: string, file: string): boolean {
   try { git(['-C', proj, 'ls-files', '--error-unmatch', file]); return true } catch { return false }
 }
 
+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 {
+  const prepared = `${path}.${process.pid}.tmp`
+  writeFileSync(prepared, body)
+  renameSync(prepared, path)
+}
+
 // @@@ contract kind detection ([[residence]]) - a contract file's residence is a LIVE CONTENT FACT, not
 // an install-time choice, re-judged on every materialize: TRACKED → filter domain; untracked + wholly ours
 // (nothing left after stripping our sentinel block) → exclude domain; untracked + HOST CONTENT present (the
@@ -144,11 +177,11 @@ function sweepGeneratedAgents(dir: string | null): void {
 // (edge ③ in [[content-filter]] — a block outliving its clean filter surfaces as an uncommitted change).
 // `arts` (live skill/agent node names) widens the sweep to pre-stamp legacy files; the GENERATED_MARK sweep
 // covers everything materialized since, including products of renamed/deleted nodes.
-export function dematerialize(proj = process.cwd(), arts: HarnessArtifacts = { skills: [], agents: [] }): void {
+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)
+    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))
@@ -156,8 +189,7 @@ export function dematerialize(proj = process.cwd(), arts: HarnessArtifacts = { s
   // 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'))
-  try { removeManagedBlock(infoExcludePath(proj), ['# ', ''], false) } catch { /* not a git repo */ }
-  removeContractFilter(proj)                                            // AFTER the blocks left the working files
+  removeContractFilter(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).
@@ -179,6 +211,22 @@ export function dematerialize(proj = process.cwd(), arts: HarnessArtifacts = { s
   }
 }
 
+export function dematerialize(proj = process.cwd(), arts: HarnessArtifacts = { skills: [], agents: [] }): void {
+  const trees = registeredTrees(proj)
+  const current = git(['-C', proj, 'rev-parse', '--show-toplevel']).trim()
+  for (const tree of trees) {
+    if (!existsSync(tree)) throw new Error(`cannot dematerialize project while registered worktree ${tree} is inaccessible — repair or remove/prune it first`)
+    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
+    // 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)
+  }
+  try { removeManagedBlock(infoExcludePath(proj), ['# ', ''], false) } catch { /* not a git repo */ }
+  removeContractFilter(proj, [...HARNESSES.flatMap((h) => h.contractFiles(proj)), join(proj, '.gitignore')], true)
+}
+
 // the whole pay-per-change materialize. proj defaults to cwd. Its receipt is populated at each successful
 // write so callers report the actual selected footprint instead of maintaining a second artifact inventory.
 export function materialize(proj = process.cwd()): MaterializeResult {
@@ -198,9 +246,9 @@ export function materialize(proj = process.cwd()): MaterializeResult {
   // own hand-written prose is not folded in — repo-local notes belong in the harness file's own
   // block-outside region (untracked, per-clone), and anything that must reach EVERY agent is a plugin node.
   const contract = loadSystemConfig().map((c) => c.body.trim()).filter(Boolean).join('\n\n')
-  // WHICH harnesses to deliver into ([[harness-select]]): the spexcode.json `harnesses` set (default = every
-  // native harness). resolveHarnessTargets FAILS LOUD on an illegal set (plugin+native, plugin w/o folder).
-  const cfg = readConfig(mainCheckout(proj))
+  // WHICH harnesses to deliver into ([[harness-select]]): this tree's explicit spexcode.json `harnesses` set.
+  // resolveHarnessTargets FAILS LOUD on an illegal set (plugin+native, plugin w/o folder).
+  const cfg = readConfig(proj)
   const targets = resolveHarnessTargets(cfg.harnesses)
   retiredAxisNotice(cfg)                                                  // [[residence]] — the vote axis is retired
   const { selected, plugins } = partitionHarnesses(targets)
@@ -212,7 +260,7 @@ export function materialize(proj = process.cwd()): MaterializeResult {
   // ---- 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.
-  dematerialize(proj, arts)
+  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)
@@ -236,18 +284,29 @@ export function materialize(proj = process.cwd()): MaterializeResult {
   const contractPaths: string[] = []
   for (const h of selected) {
     if (contract) for (const f of h.contractFiles(proj)) { writeManagedBlock(f, contract); contractPaths.push(f); record('contract', f) }
-    const shimFile = h.shimFile(proj)
-    mkdirSync(dirname(shimFile), { recursive: true })
     const shim = h.shim(DISPATCH, SPEX)
-    writeFileSync(shimFile, shim.content)
-    record('shim', shimFile)
-    for (const f of h.writeTrust(proj, shim.cmd)) record('trust', f)
-    machinePaths.push(shimFile)
+    if (h.shimScope === 'tree') {
+      const shimFile = h.shimFile(proj)
+      mkdirSync(dirname(shimFile), { recursive: true })
+      writeFileSync(shimFile, shim.content)
+      record('shim', shimFile)
+      machinePaths.push(shimFile)
+    }
     // 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) }
   }
+  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)
+      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) {
@@ -299,44 +358,54 @@ export function materialize(proj = process.cwd()): MaterializeResult {
     }
   }
   writeFileSync(ledger, curFolders.join('\n'))
-  // (9) the ignore rules — ALWAYS the per-clone .git/info/exclude ([[residence]]): the exclude is not a
-  //     history guard (the pre-commit surgery owns history — [[commit-surgery]]) but the ignored-bit
-  //     DECLARATION every other git door consults (checkout may overwrite, clean -fd spares, status/add -A/
-  //     stash stay silent). The host's tracked .gitignore is never touched.
-  // Entries must be CHECKOUT-INVARIANT: the exclude lives in the COMMON git dir shared by the main checkout
-  // and every worktree, so each entry is anchored to the checkout it LIVES under — proj-relative when inside
-  // proj, else MAIN-checkout-relative (the codex shim resolves to `.codex/hooks.json` from any checkout; a
-  // pattern naming a main-only path is a harmless no-op in a worktree). A path under neither root is dropped.
+  // (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)
-  const anchor = (abs: string): string | null => {
-    const p = relative(proj, abs); if (!p.startsWith('..')) return p
-    const m = relative(mc, abs); if (!m.startsWith('..')) return m
-    return null
-  }
-  // machine facts + run residue, ignored under EVERY policy: the shims/anchors/bundles (bake this install's
-  // abs path), spexcode.local.json (the host overlay — a `git add -A` must never leak it), and the session
-  // residue (`.worktrees/` where launches plant worktrees; `.session` is the legacy per-worktree state file
-  // an old backend wrote). Static strings stay checkout-invariant.
   const bundlePaths = curFolders.map((f) => pluginBundleDir(proj, f))
-  const machineEntries = [
-    ...[...machinePaths, ...bundlePaths].map(anchor).filter((p): p is string => p !== null),
+  const commonEntries = [
+    ...[...new Set(HARNESSES.filter((h) => h.shimScope === 'project' && existsSync(h.shimFile(proj)) &&
+      readFileSync(h.shimFile(proj), 'utf8').includes('dispatch.sh')).map((h) => relative(mc, h.shimFile(proj))))]
+      .filter((p) => !p.startsWith('..')),
     'spexcode.local.json', '.worktrees/', '.session',
   ]
-  // the contract three-state ([[residence]]): tracked → filter; untracked+wholly-ours → exclude;
-  // untracked+host-content → NO exclude (never hide user prose) + the clean filter pre-armed, so the user's
-  // own eventual `git add` strips our block — tracking stays entirely their act.
+  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)
     else oursContracts.push(f)
   }
-  if (contract && filterContracts.length) plantContractFilter(proj, filterContracts, contract)
-  const artifactEntries = [...artifactPaths, ...oursContracts].map(anchor).filter((p): p is string => p !== null)
-  const entries = (list: string[]) => [...new Set(list)].sort().join('\n')
-  writeManagedBlock(infoExcludePath(proj), entries([...machineEntries, ...artifactEntries]), ['# ', ''])
-  // (5) stamp the content-hash marker LAST (a diagnostic freshness record; a crash mid-materialize leaves it stale).
+  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 ignoreHost = existsSync(ignoreFile) ? readFileSync(ignoreFile, 'utf8') : ''
+  if (!ignoreTracked && !ignoreHost.trim()) localEntries.push('.gitignore')
+  const ignoreBody = entries(localEntries)
+  writeManagedBlock(ignoreFile, ignoreBody, ['# ', ''])
+
+  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 })),
+    { 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
+  // 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]), ['# ', ''])
+  publishSelection(join(rt, 'harnesses'), selectionBody(selected, plugins.length > 0))
   return { contentHash: h, planted }
 }

package/spec-cli/src/sessions.ts

@@ -7,7 +7,7 @@ import { fileURLToPath } from 'node:url'
 import { seedWorktreeHostState } from './worktree-sources.js'
 import { git, gitA, gitTry, repoRoot, mergeBaseDiff, mergeConflicts, type ReviewDiffFile } from './git.js'
 import { loadConfig, loadSpecs, type ConfigPreset, type SpecLite } from './specs.js'
-import { adapterLoadedReferenceState, defaultHarness, sessionIdentityEnvVars, defaultLauncher, harnessById, procSnapshot, resolveLauncher, rendezvousListening, stampRvSock, type Harness, type HarnessLaunchReadinessFence, type DispatchResult, type PaneProbe, type ProcTable } from './harness.js'
+import { adapterLoadedReferenceState, defaultHarness, sessionIdentityEnvVars, defaultLauncher, harnessById, procSnapshot, resolveLauncher, rendezvousListening, stampRvSock, type Harness, type HarnessLaunchReadinessFence, type TurnFailure, type FailureSubscription, type DispatchResult, type PaneProbe, type ProcTable } from './harness.js'
 import { materialize } from './materialize.js'
 import { mainBranch, gitCommonDir, readConfig, runtimeRoot, treeSlotDir, sessionStoreDir, sessionRecordPath, sessionArtifactPath, listSessionIds, rawLaunchReadinessOriginal, readAliasedRawRecord, readRecordEntry, readAliasedRecordEntry, readPublicRecordEntry, envSessionId, isSessionLifecycle, isSessionProposal, type PublicRecordEntry, type RawRecord, type SessionLifecycle, type SessionProposal } from './layout.js'
 import { recordSent, recordStatus, lastHumanSendVia } from './session-timeline.js'
@@ -1651,6 +1651,106 @@ export function superviseQueue(intervalMs = 3000): void {
   void tick()
 }
 
+type TurnFailureObserverState = {
+  fingerprint: string
+  subscription: FailureSubscription | null
+  startedAt: number
+  failures: number
+  retryAt: number
+  lastReason: string | null
+}
+const turnFailureObservers = new Map<string, TurnFailureObserverState>()
+let supervisingTurnFailures = false
+const TURN_FAILURE_OBSERVER_STABLE_MS = 5000
+
+export function turnFailureNote(harness: string, failure: TurnFailure): string {
+  const message = failure.message.replace(/\s+/g, ' ').trim().slice(0, 500) || 'turn failed'
+  const at = failure.completedAt == null ? '' : ` at ${new Date(failure.completedAt * 1000).toISOString()}`
+  return `${harness} turn failed${at}: ${message}`
+}
+
+export function turnFailureRetryDelay(failures: number): number {
+  return Math.min(30_000, 1000 * 2 ** Math.max(0, Math.min(failures - 1, 5)))
+}
+
+function deferTurnFailureObserver(id: string, harness: string, state: TurnFailureObserverState, reason: string): void {
+  state.subscription = null
+  state.failures++
+  const delay = turnFailureRetryDelay(state.failures)
+  state.retryAt = Date.now() + delay
+  if (state.lastReason !== reason)
+    console.warn(`[spex ${harness}] turn failure observer for ${id} disconnected (${reason}); retrying in ${delay}ms`)
+  state.lastReason = reason
+}
+
+// Reconcile one adapter-owned native failure subscription per live governed session. Product code knows only
+// the optional interface capability; Codex owns WebSocket/thread semantics and Claude keeps using StopFailure.
+export function reconcileTurnFailureObservers(): void {
+  const wanted = new Map<string, { rec: SessRec; harness: Harness; fingerprint: string }>()
+  for (const id of listSessionIds()) {
+    let rec: SessRec | null = null
+    try { rec = readRecord(id) } catch { continue }
+    if (!rec?.governed || rec.stopped || rec.archived || !rec.harnessSessionId) continue
+    const harness = harnessById(rec.harness || defaultHarness.id)
+    if (!harness.observeTurnFailures) continue
+    wanted.set(id, { rec, harness, fingerprint: `${harness.id}:${rec.harnessSessionId}:${runtimeRoot()}` })
+  }
+  for (const [id, state] of turnFailureObservers) {
+    if (wanted.get(id)?.fingerprint === state.fingerprint) continue
+    turnFailureObservers.delete(id)
+    state.subscription?.close()
+  }
+  for (const [id, target] of wanted) {
+    const now = Date.now()
+    let state = turnFailureObservers.get(id)
+    if (state?.subscription) {
+      if (state.failures > 0 && now - state.startedAt >= TURN_FAILURE_OBSERVER_STABLE_MS) {
+        state.failures = 0
+        state.retryAt = 0
+        state.lastReason = null
+      }
+      continue
+    }
+    if (state && now < state.retryAt) continue
+    state ??= { fingerprint: target.fingerprint, subscription: null, startedAt: 0, failures: 0, retryAt: 0, lastReason: null }
+    state.startedAt = now
+    turnFailureObservers.set(id, state)
+    try {
+      const subscription = target.harness.observeTurnFailures!({
+        session: id,
+        worktreePath: target.rec.worktreePath,
+        harnessSessionId: target.rec.harnessSessionId,
+        runtimeDir: runtimeRoot(),
+        launchCmd: target.rec.launchCmd,
+      }, (failure) => {
+        if (turnFailureObservers.get(id)?.fingerprint !== target.fingerprint) return
+        try { markTurnFailure(id, turnFailureNote(target.harness.id, failure)) }
+        catch (error) { console.error(`[spex ${target.harness.id}] could not record native turn failure for ${id}: ${error instanceof Error ? error.message : String(error)}`) }
+      })
+      state.subscription = subscription
+      void subscription.closed.then((reason) => {
+        if (turnFailureObservers.get(id) !== state) return
+        if (reason) deferTurnFailureObserver(id, target.harness.id, state, reason)
+        else turnFailureObservers.delete(id)
+      })
+    } catch (error) {
+      deferTurnFailureObserver(id, target.harness.id, state, error instanceof Error ? error.message : String(error))
+    }
+  }
+}
+
+export function superviseTurnFailures(intervalMs = 1000): void {
+  if (supervisingTurnFailures) return
+  supervisingTurnFailures = true
+  const tick = () => {
+    try { reconcileTurnFailureObservers() }
+    catch (error) { console.error(`spex: turn failure reconciliation failed: ${error instanceof Error ? error.message : String(error)}`) }
+    const timer = setTimeout(tick, intervalMs)
+    timer.unref?.()
+  }
+  tick()
+}
+
 // @@@ assertProjectMatch - a WRITE is PROJECT-BOUND, but routing is by URL. A mutating verb's intent is
 // "act on the project my cwd is in", yet the resolved base is a pure URL carrying no project identity —
 // the backend it answers acts on ITS OWN mainRoot, so a stale inherited SPEXCODE_API_URL (pointing at
@@ -2105,19 +2205,23 @@ export function markState(status: Lifecycle, opts: { proposal?: Proposal; note?:
 }
 export const markDone = (proposal: Proposal = 'nothing', sessionId?: string, note?: string) => markState('awaiting', { proposal, note, sessionId })
 export const markError = (sessionId?: string) => markState('error', { sessionId })
-// @@@ headless turn outcome - a harness turn is an ephemeral child, so its non-zero exit is the one external
-// runtime fact that must become visible on the durable board. Compare-and-set only an undeclared active record:
-// a zero exit is never routed here, and a declaration that landed before teardown is authoritative.
-export function markHeadlessTurnFailure(sessionId: string, harness: string, exitCode: string): boolean {
-  if (exitCode === '0') return false
+// @@@ harness turn failure - native adapter failures are external runtime facts that must become visible on
+// the durable board. Compare-and-set only an undeclared active record, so a declaration that landed before a
+// late process close or app-server completion remains authoritative.
+export function markTurnFailure(sessionId: string | undefined, note: string): boolean {
+  if (!sessionId) return false
   return runSessionOperationSync({ op: 'lifecycle-transition', sessionId }, () => withRecordLockSync(sessionId, () => {
     const rec = readLiveRecord(sessionId)
-    if (!rec || rec.status !== 'active') return false
-    const outcome = /^\d+$/.test(exitCode) ? `exit code ${exitCode}` : `signal ${exitCode}`
-    writeRecord({ ...rec, status: 'error', proposal: null, note: `${harness} turn exited with ${outcome}` })
+    if (!rec || rec.status !== 'active' || rec.stopped || rec.archived) return false
+    writeRecord({ ...rec, status: 'error', proposal: null, note })
     return true
   }))
 }
+export function markHeadlessTurnFailure(sessionId: string, harness: string, exitCode: string): boolean {
+  if (exitCode === '0') return false
+  const outcome = /^\d+$/.test(exitCode) ? `exit code ${exitCode}` : `signal ${exitCode}`
+  return markTurnFailure(sessionId, `${harness} turn exited with ${outcome}`)
+}
 export function markHarnessSessionId(sessionId: string | undefined, harnessSessionId: string | undefined): boolean {
   const id = sessionId || ownSessionId()
   if (!id || !harnessSessionId) return false

package/spec-cli/templates/spec/project/.plugins/core/session-fail/spec.md

@@ -7,7 +7,9 @@ events:
 - StopFailure
 order: 10
 block: false
+code:
+- .spec/project/.plugins/core/session-fail/fail.sh
 ---
 When a turn ends not because the agent declared but because the API itself failed, this hook structurally marks the session `error`. A failed turn is a real outcome the board must show, and without this signal the session would freeze under whatever state it last held — reading as "active" or "awaiting" long after it actually died.
 
-It is non-blocking and unconditional on the failure event: the failure already happened, so the only job is to record it truthfully. As a board-lifecycle hook it acts only on a GOVERNED session — resolved in the global store from the payload's `session_id` — and writes via `spex internal session-fail --session <id>`. By turning an API error into a declared `error` state it keeps the [[stop-gate]] family's invariant intact — a session's displayed state always reflects what is really true of its last turn — for the one stop path the agent cannot narrate itself.
+It is non-blocking on the failure event: the failure already happened, so the only job is to report it truthfully. As a board-lifecycle hook it acts only on a GOVERNED session — resolved in the global store from the payload's `session_id` — and writes via `spex internal session-fail --session <id>`. That machine entry reaches the same live-active compare-and-set as Codex's native failed completion and a headless turn's non-zero exit (harness-adapter): only an undeclared, non-stopped `active` record becomes `error`. A declaration, explicit stop, or archive that landed first remains authoritative; a late native failure never rewrites it. This one writer keeps the [[stop-gate]] family's invariant intact for every harness while each adapter retains only its native failure signal.

package/spec-cli/templates/spec/project/.plugins/core/spec.md

@@ -18,6 +18,6 @@ The body is the contract; update it with code when intent changes.
 2. COMMIT BEFORE YOU DECLARE. Commit the spec and the code it justifies before declaring done or proposing merge.
 Independent intent gets its own sibling node; do not ride it on an assigned node.
 3. THE BODY IS A LIVING CURRENT-STATE DOCUMENT. Rewrite present intent in place; never add a `## vN` changelog.
-4. KEEP THE LOSS SIGNAL HONEST. `spex spec lint` is the blocking correctness gate; `spex eval lint --changed`
-reports measurement gaps. Re-run changed eval scenarios through the real product, commit the verified tree, then
+4. KEEP THE LOSS SIGNAL HONEST. Before declaring, run both: `spex spec lint` is the blocking correctness gate;
+`spex eval lint --changed` reports measurement gaps. Re-run changed eval scenarios through the real product, commit the verified tree, then
 file with `spex eval add`; the reading's `codeSha` must name that commit, and evidence must fit the behavior.