spexcode 0.5.4 → 0.5.6

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'
@@ -632,13 +632,18 @@ app.post('/api/sessions/:id/input', async (c) => {
 app.post('/api/sessions/:id/stop', async (c) => {
   const sessionId = c.req.param('id')
   const authorization = await operationAuthorization(c.req.header.bind(c.req), { op: 'stop', sessionId })
-  return c.json({ ok: await stopSession(sessionId, { authorization }) })
+  const ok = await stopSession(sessionId, { authorization })
+  return c.json(ok ? { ok: true } : { ok: false, error: `no stop transition was committed for session ${sessionId}` }, ok ? 200 : 404)
 })
 app.post('/api/sessions/:id/interrupt', async (c) => {
   const result = await interruptSession(c.req.param('id'))
   return c.json(result, result.ok ? 200 : 502)
 })
-app.post('/api/sessions/:id/close', async (c) => c.json({ ok: await closeSession(c.req.param('id')) }))
+app.post('/api/sessions/:id/close', async (c) => {
+  const sessionId = c.req.param('id')
+  const ok = await closeSession(sessionId)
+  return c.json(ok ? { ok: true } : { ok: false, error: `no close transition was committed for session ${sessionId}` }, ok ? 200 : 404)
+})
 // archive / legacy unarchive signpost ([[archive]]) — archive proves exact cold/offline ownership before filing;
 // `{on:false}` enters the same resume transition and recreates the preserved conversation. {ok:false}=no such session.
 app.post('/api/sessions/:id/archive', async (c) => {
@@ -684,6 +689,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/reviewSnapshot.ts

@@ -21,3 +21,7 @@ export function readReviewSnapshot(): ReviewSnapshot {
   if (!current) throw new Error('review snapshot is unavailable before the first successful graph build')
   return current
 }
+
+export function hasReviewSnapshot(): boolean {
+  return current !== null
+}