spexcode 0.5.3 → 0.5.5

package/spec-cli/src/host-resources.ts

@@ -7,7 +7,7 @@ import { defaultHarness, HARNESSES, harnessById, sessionIdentityEnvVars, type Ha
 import { listSessionIds, readConfig, readJsonConfig, readPublicRecordEntry, readRawRecord, runtimeRoot, type PublicRecordEntry, type RawRecord } from './layout.js'
 import { repoRoot } from './git.js'
 import { endpointRecordPath } from './host.js'
-import { parseProcStat, processStartToken, processTopology, type ProcessIdentity } from './process-identity.js'
+import { detachedRuntimeGenerationToken, parseProcStat, processStartToken, verifyDetachedRuntime, type ProcessIdentity } from './process-identity.js'
 import { readBackendInstanceRecords, type BackendInstanceRecord } from './runtime-ownership.js'
 
 type Proc = ProcessIdentity & {
@@ -384,6 +384,7 @@ const sessionStopBlocker = async (
   harnessId: string | null,
   recs = rawRecords(),
   knownProbes?: Map<string, SharedRuntimeProbe>,
+  opts: { coldReceipt?: unknown } = {},
 ): Promise<string | null> => {
   const allowed = harnessId
     ? new Set((harnessById(harnessId).sharedRuntimes?.(runtimeRoot()) ?? []).map((descriptor) => descriptor.key))
@@ -392,7 +393,6 @@ const sessionStopBlocker = async (
     if (allowed && !allowed.has(key)) continue
     const descriptor = entry.descriptor
     const pid = runtimePid(descriptor.pidFile)
-    const startToken = pid ? processStartToken(pid) : null
     const ownerCounts = new Map<string, number>()
     for (const rec of entry.recs) if (rec.harness_session_id) ownerCounts.set(rec.harness_session_id, (ownerCounts.get(rec.harness_session_id) ?? 0) + 1)
     const targetThread = entry.recs.find((rec) => rec.session_id === id)?.harness_session_id
@@ -401,24 +401,16 @@ const sessionStopBlocker = async (
     if (!knownProbes && descriptor.mutationGuard) {
       if (!targetThread) return `${descriptor.label} target has no exact governed thread identity`
       if (!pid) return `${descriptor.label} target-scoped mutation guard has no readable owner PID`
-      if (!startToken) return `${descriptor.label} PID ${pid} target-scoped mutation guard has no readable process-start identity`
-      const topologyBefore = processTopology(pid)
-      let stampBefore = ''
-      try { stampBefore = readFileSync(descriptor.isolationFile, 'utf8').trim() } catch { /* legacy unsafe runtime */ }
-      if (!topologyBefore || topologyBefore.startToken !== startToken || topologyBefore.processGroupId !== pid || topologyBefore.sessionId !== pid ||
-        stampBefore !== `detached-v3 ${pid} ${startToken} ${pid} ${pid}`)
-        return `${descriptor.label} PID ${pid}@${startToken} has no matching live detached process-boundary record`
+      const identityBefore = verifyDetachedRuntime(pid, descriptor.receiptFile)
+      if (!identityBefore.ok)
+        return `${descriptor.label} PID ${pid} has no matching live detached process-boundary record: ${identityBefore.reason}`
       let guard
-      try { guard = await descriptor.mutationGuard(targetThread) }
+      try { guard = await descriptor.mutationGuard(targetThread, opts) }
       catch (error) { return `${descriptor.label} target-scoped mutation guard failed: ${(error as Error).message}` }
-      const startAfter = processStartToken(pid)
-      const topologyAfter = processTopology(pid)
-      let stampAfter = ''
-      try { stampAfter = readFileSync(descriptor.isolationFile, 'utf8').trim() } catch { /* changed/missing identity */ }
-      if (startAfter !== startToken || !topologyAfter || topologyAfter.startToken !== startToken ||
-        topologyAfter.processGroupId !== pid || topologyAfter.sessionId !== pid || stampAfter !== stampBefore)
-        return `${descriptor.label} PID/start/isolation identity changed during target-scoped mutation guard`
-      if (guard.descendantIds.length)
+      const identityAfter = verifyDetachedRuntime(pid, descriptor.receiptFile)
+      if (!identityAfter.ok || detachedRuntimeGenerationToken(identityAfter.identity) !== detachedRuntimeGenerationToken(identityBefore.identity))
+        return `${descriptor.label} PID/start/detached-receipt identity changed during target-scoped mutation guard${identityAfter.ok ? '' : `: ${identityAfter.reason}`}`
+      if (guard.descendantIds.length && guard.coldTeardownAuthorized !== true)
         return `${descriptor.label} target thread ${targetThread} has owned descendants (${guard.descendantIds.join(', ')})`
       if (!guard.healthy)
         return `${descriptor.label} target thread ${targetThread} is unknown: ${guard.error || 'target-scoped mutation guard failed'}`
@@ -433,17 +425,13 @@ const sessionStopBlocker = async (
       ? `${siblings.length} live sibling thread(s)`
       : probe.healthy ? `${probe.references.length} live thread reference(s)` : 'an unproven live reference set'
     if (!pid) return `${descriptor.label} has ${liveReason} but no readable owner PID`
-    if (!startToken) return `${descriptor.label} PID ${pid} has ${liveReason} but no readable process-start identity`
-    const topology = processTopology(pid)
-    let stamp = ''
-    try { stamp = readFileSync(descriptor.isolationFile, 'utf8').trim() } catch { /* legacy unsafe runtime */ }
-    if (!topology || topology.startToken !== startToken || topology.processGroupId !== pid || topology.sessionId !== pid ||
-      stamp !== `detached-v3 ${pid} ${startToken} ${pid} ${pid}`) {
+    const identity = verifyDetachedRuntime(pid, descriptor.receiptFile)
+    if (!identity.ok) {
       const refs = probe.references.map((reference) => reference.referenceId).join(', ') || 'no loaded threads'
-      return `${descriptor.label} PID ${pid}@${startToken} serves ${refs} and has no matching live detached process-boundary record`
+      return `${descriptor.label} PID ${pid} serves ${refs} and has no matching live detached process-boundary record: ${identity.reason}`
     }
     if (!probe.healthy)
-      return `${descriptor.label} PID ${pid}@${startToken} has an unproven live reference set: ${probe.error || 'unknown probe failure'}`
+      return `${descriptor.label} PID ${pid}@${identity.identity.startToken} has an unproven live reference set: ${probe.error || 'unknown probe failure'}`
   }
   return null
 }
@@ -658,9 +646,13 @@ export async function collectResourceReport(opts: { procRoot?: string; persist?:
   return report
 }
 
-export async function assertSessionStopSafe(id: string, rec: (HarnessLivenessRecord & { harness?: string }) | null): Promise<void> {
+export async function assertSessionStopSafe(
+  id: string,
+  rec: (HarnessLivenessRecord & { harness?: string }) | null,
+  opts: { coldReceipt?: unknown } = {},
+): Promise<void> {
   if (!rec) throw new ResourceConflict(`refusing to stop ${id}: no readable session record proves the adapter or leaf owner`)
-  const blocker = await sessionStopBlocker(id, rec.harness || null)
+  const blocker = await sessionStopBlocker(id, rec.harness || null, rawRecords(), undefined, opts)
   if (blocker) throw new ResourceConflict(`refusing to stop ${id}: ${blocker}`)
 }
 

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/init.ts

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, copyFileSync, readFileSync, readdirSync, renameSync, rmSync, statSync, chmodSync, writeFileSync } from 'node:fs'
 import { createHash } from 'node:crypto'
-import { join, resolve, relative } from 'node:path'
+import { join, resolve, relative, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { execFileSync } from 'node:child_process'
 import { readConfig, readJsonConfig } from './layout.js'
@@ -81,6 +81,20 @@ function resolveHooksDir(dir: string): string | null {
   }
 }
 
+// Detect once, at adoption, while the root checkout still names the branch being adopted. Steady-state
+// layout never re-derives trunk identity from a mutable checkout (an ordinary `git switch node/x` must not
+// turn that feature branch into trunk).
+function adoptionMainBranch(dir: string): string {
+  try {
+    const common = execFileSync('git', ['-C', dir, 'rev-parse', '--path-format=absolute', '--git-common-dir'], { encoding: 'utf8' }).trim()
+    const branch = execFileSync('git', ['-C', dirname(common), 'symbolic-ref', '--short', 'HEAD'], { encoding: 'utf8' }).trim()
+    if (branch) return branch
+  } catch { /* render the one product-level repair below */ }
+  const error = new Error('cannot determine the source-of-truth branch at adoption — check out the trunk in the root checkout, or set "mainBranch" in spexcode.json before re-running `spex init`')
+  error.name = 'ConfigError'
+  throw error
+}
+
 export async function specInit(targetArg: string | undefined, presetArg?: string, harnessArg?: string): Promise<void> {
   const targetDir = resolve(targetArg ?? process.cwd())
 
@@ -153,18 +167,23 @@ export async function specInit(targetArg: string | undefined, presetArg?: string
   const cfgDest = join(targetDir, 'spexcode.json')
   const nativeChosen = (chosenHarnesses as unknown[]).filter((m): m is string => typeof m === 'string')
   if (existsSync(cfgDest)) {
-    if (flagRaw) {
-      // an explicit --harness on a re-init is a deliberate command: restamp THAT field, touch nothing else.
-      const cfg = (readJsonConfig(cfgDest) ?? {}) as Record<string, unknown>
-      cfg.harnesses = flagRaw
+    const cfg = (readJsonConfig(cfgDest) ?? {}) as Record<string, unknown>
+    const stampedBranch = typeof cfg.mainBranch !== 'string' || !cfg.mainBranch.trim()
+    if (stampedBranch) cfg.mainBranch = adoptionMainBranch(targetDir)
+    if (flagRaw) cfg.harnesses = flagRaw
+    if (flagRaw || stampedBranch) {
       writeFileSync(cfgDest, JSON.stringify(cfg, null, 2) + '\n')
-      console.log(`✓ stamped "harnesses": ${JSON.stringify(flagRaw)} into the existing spexcode.json (other fields untouched)`)
+      console.log(`✓ stamped ${[
+        flagRaw ? `"harnesses": ${JSON.stringify(flagRaw)}` : '',
+        stampedBranch ? `"mainBranch": ${JSON.stringify(cfg.mainBranch)}` : '',
+      ].filter(Boolean).join(' and ')} into the existing spexcode.json (other fields untouched)`)
     } else {
       console.warn(`• spexcode.json already exists at ${cfgDest} — left untouched (harnesses: ${JSON.stringify(chosenHarnesses)}).`)
     }
   } else {
     const cfg = (readJsonConfig(join(TEMPLATES, 'spexcode.json')) ?? {}) as Record<string, any>
     cfg.harnesses = chosenHarnesses
+    cfg.mainBranch = adoptionMainBranch(targetDir)
     if (nativeChosen.length && cfg.sessions?.launchers) {
       cfg.sessions.launchers = Object.fromEntries(
         Object.entries(cfg.sessions.launchers as Record<string, { harness?: string }>).filter(([, l]) => nativeChosen.includes(l.harness ?? 'claude')))
@@ -173,7 +192,7 @@ export async function specInit(targetArg: string | undefined, presetArg?: string
     }
     writeFileSync(cfgDest, JSON.stringify(cfg, null, 2) + '\n')
     const roots = JSON.stringify(readJsonConfig(cfgDest)?.lint?.governedRoots ?? null)
-    console.log(`✓ planted spexcode.json — harnesses ${JSON.stringify(chosenHarnesses)}, launchers ${JSON.stringify(Object.keys(cfg.sessions?.launchers ?? {}))}; lint.governedRoots starts as ${roots} (the whole git-tracked tree, tests excluded)`)
+    console.log(`✓ planted spexcode.json — mainBranch ${JSON.stringify(cfg.mainBranch)}, harnesses ${JSON.stringify(chosenHarnesses)}, launchers ${JSON.stringify(Object.keys(cfg.sessions?.launchers ?? {}))}; lint.governedRoots starts as ${roots} (the whole git-tracked tree, tests excluded)`)
   }
 
   // 2. install the git hooks. Unknown existing hooks are user-owned and stay byte-identical. An exact

package/spec-cli/src/layout.ts

@@ -9,7 +9,7 @@ export { encodeProject, spexcodeHome } from './project-store.js'
 
 export type Config = {
   main?: string                    // path to the source-of-truth checkout (default: the `main` worktree)
-  mainBranch?: string              // source-of-truth BRANCH worktrees fork from (default: auto-detected — see mainBranch())
+  mainBranch?: string              // stable source-of-truth branch stamped by init (default: "main")
   branchPrefix?: string            // how a branch names its node (default: "node/")
   preset?: string                  // the SELECTED init preset — which cumulative .plugins tier `spex init` seeds (default 'default'; seed-time only, no launcher gate; read by init.ts; see [[init-preset]])
   // RETIRED ([[residence]]) — the old three-word footprint vote. Materialized artifacts carry no facts and are never
@@ -115,16 +115,8 @@ export function gitCommonDir(): string {
 
 export function mainBranch(): string {
   let checkout: string
-  try {
-    checkout = mainCheckout()
-  } catch { return 'main' }
-  const override = readConfig(checkout).mainBranch?.trim()
-  if (override) return override
-  try {
-    const cur = git(['-C', checkout, 'symbolic-ref', '--short', 'HEAD']).trim()
-    if (cur) return cur
-  } catch { /* detached/bare checkout: use the documented conventional default */ }
-  return 'main'
+  try { checkout = mainCheckout() } catch { return 'main' }
+  return readConfig(checkout).mainBranch?.trim() || 'main'
 }
 
 // the MAIN checkout (the root working tree) for a project — the SAME answer from main OR any linked worktree

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 }
 }