spexcode 0.2.3 → 0.2.5

package/spec-cli/src/search.bench.mjs

@@ -53,10 +53,20 @@ for (const row of rows) {
   console.log(`${mark} ${row.name.padEnd(20)} want=${row.expect.padEnd(22)} rank=${String(row.rank).padStart(2)}  top3: ${row.top}`)
 }
 
-// zero-result fail-loud regression: a CJK query over the English corpus returns nothing, and the
-// zero-result message must carry the corpus-is-English translate-and-retry fact (fail-loud, unconditional)
-// plus the browse-all next step (no nearest titles — a CJK query has nothing to be lexically near).
-const cjk = execFileSync('node', [BIN, 'search', '重命名一个会话'], { encoding: 'utf8' })
+// CJK-positive: the corpus is mostly English but a few nodes carry Chinese prose — the root `spexcode`
+// node's body repeats 节点 throughout. A per-CJK-character tokenizer must let a Chinese content word reach
+// that node; `spex search "节点"` MUST return `spexcode` in results (the bug: the old tokenizer split on
+// [^a-z0-9]+ and discarded all CJK, so every Chinese query dead-ended at zero results).
+const cjkPos = JSON.parse(execFileSync('node', [BIN, 'search', '节点', '--json', '--limit', '10'], { encoding: 'utf8' }))
+const cjkPosRank = cjkPos.map((x) => x.id).findIndex((id) => matches(id, 'spexcode')) + 1
+const cjkPosPass = cjkPosRank >= 1
+console.log(`${cjkPosPass ? `✓${cjkPosRank}` : '✗ '} cjk-positive          want=spexcode(节点)                rank=${cjkPosRank || '—'}  top3: ${cjkPos.slice(0, 3).map((x) => x.id).join(', ')}`)
+
+// zero-result fail-loud regression: a CJK query whose characters appear NOWHERE in the corpus (会/话) returns
+// nothing, and the zero-result message must still carry the corpus-is-English translate-and-retry fact
+// (fail-loud) plus the browse-all next step — CJK support does not suppress the honest zero-result route.
+// (No nearest titles: a CJK query has nothing to be lexically near.)
+const cjk = execFileSync('node', [BIN, 'search', '会话'], { encoding: 'utf8' })
 const cjkPass = cjk.includes('corpus is English') && cjk.includes('spex tree')
 console.log(`${cjkPass ? '✓ ' : '✗ '} cjk-zero-result       want=corpus-is-English + spex-tree  ${cjkPass ? 'both present' : 'MISSING: ' + cjk.trim()}`)
 
@@ -67,4 +77,4 @@ const typoPass = typo.includes('nearest titles') && typo.includes('keyboard-nav'
 console.log(`${typoPass ? '✓ ' : '✗ '} typo-zero-result      want=nearest-titles(keyboard-nav) + spex-tree  ${typoPass ? 'both present' : 'MISSING: ' + typo.trim()}`)
 
 console.log('—'.repeat(72))
-console.log(`recall@1 = ${r1}/${n} = ${(r1 / n).toFixed(3)}   recall@3 = ${r3}/${n} = ${(r3 / n).toFixed(3)}   MRR = ${(mrr / n).toFixed(3)}   cjk-hint = ${cjkPass ? 'PASS' : 'FAIL'}   typo-route = ${typoPass ? 'PASS' : 'FAIL'}`)
+console.log(`recall@1 = ${r1}/${n} = ${(r1 / n).toFixed(3)}   recall@3 = ${r3}/${n} = ${(r3 / n).toFixed(3)}   MRR = ${(mrr / n).toFixed(3)}   cjk-positive = ${cjkPosPass ? 'PASS' : 'FAIL'}   cjk-hint = ${cjkPass ? 'PASS' : 'FAIL'}   typo-route = ${typoPass ? 'PASS' : 'FAIL'}`)

package/spec-cli/src/sessions.ts

@@ -4,6 +4,7 @@ import { randomUUID } from 'node:crypto'
 import { readFileSync, writeFileSync, appendFileSync, existsSync, renameSync, mkdirSync, rmSync, readdirSync, realpathSync, statSync } from 'node:fs'
 import { join, dirname, relative, isAbsolute } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { seedWorktreeHostState } from './worktree-sources.js'
 import { git, gitA, gitTry, repoRoot, mergeBaseDiff, mergeConflicts, type ReviewDiffFile } from './git.js'
 import { loadSpecs } from './specs.js'
 import { defaultHarness, defaultLauncher, harnessById, resolveLauncher, rvSock, rendezvousListening, type Harness, type DispatchResult, type PaneProbe, type ProcTable } from './harness.js'
@@ -501,9 +502,9 @@ export function toSession(rec: SessRec, status: DisplayStatus, lv: Liveness, act
 }
 
 // @@@ renameSession - set (or clear) a session's human display NAME: the user-chosen override that wins
-// over the derived label (node/title/branch/id) on every surface. Persisted to the worktree's `.session`
-// — the only writer of that file — so the name survives backend restarts and is read back like any other
-// field. A blank name CLEARS the override, reverting the row to its derived label. Works for a session in
+// over the derived label (node/title/branch/id) on every surface. Persisted to the session's global
+// record (`session.json` in the store, like every other field) so the name survives backend restarts
+// and is read back like any other field. A blank name CLEARS the override, reverting the row to its derived label. Works for a session in
 // any state (queued/live/offline) since it edits the on-disk record, not the live tmux. Unknown id → false
 // (the route answers 404). The frontend's right-click rename is the sole caller today.
 export async function renameSession(id: string, name: string): Promise<boolean> {
@@ -801,7 +802,13 @@ export const isBackendDown = (e: unknown): boolean => e instanceof Error && e.na
 export const isBackendUnreachable = (e: unknown): boolean =>
   isBackendDown(e) && (e as { status?: number }).status === undefined
 
-const slugify = (s: string | null) => (s || 'session').replace(/[^a-zA-Z0-9_-]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '') || 'session'
+// @@@ slugify - the branch/worktree-safe slug. Keeps ANY unicode letter/number (git refs and the filesystem
+// take unicode), so a CJK prompt survives as the readable name its author typed instead of being stripped to
+// nothing — transliteration would buy ASCII at the cost of a dependency and a name nobody wrote. NFC pins one
+// canonical byte form across IME/OS variants. Non-empty is guaranteed by the 'session' fallback; uniqueness
+// is the caller's job (newSession suffixes the session short-id).
+export const slugify = (s: string | null) =>
+  (s || 'session').normalize('NFC').replace(/[^\p{L}\p{N}_-]+/gu, '-').replace(/-+/g, '-').replace(/^-+|-+$/g, '') || 'session'
 
 // @@@ node + title from the prompt - the spec node a session works on is whatever it @-mentions, NOT a UI
 // "focused node": the dashboard prefills `@<focused> ` as a deletable convenience, so the node the user
@@ -812,8 +819,14 @@ const slugify = (s: string | null) => (s || 'session').replace(/[^a-zA-Z0-9_-]/g
 // (`.config`) keeps the dot — without `\.?` here `[[.config]]` captures nothing and never resolves to a node.
 const MENTION = /\[\[(\.?[A-Za-z0-9_-]+)\]\]/
 const mentionedNode = (prompt: string): string | null => prompt.match(MENTION)?.[1] ?? null
-function titleFromPrompt(prompt: string): string | null {
-  const first = (prompt || '').trim().split('\n')[0].trim()
+// @@@ identity-token strip - an `@session` actor mention ([[mentions]]) or a bare UUID-shaped token in the
+// prompt is ANOTHER session's identity, never this one's name. A title/slug wearing it misleads every
+// board/git surface — and a worker tasked with cleaning that session can match its OWN worktree and delete
+// it from under itself. Strip both before deriving; whatever prose remains names the session.
+const UUID_TOKEN = /\b[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\b/g
+const stripIdentityTokens = (s: string) => s.replace(/(^|\s)@[A-Za-z0-9_-]+/g, '$1').replace(UUID_TOKEN, ' ')
+export function titleFromPrompt(prompt: string): string | null {
+  const first = stripIdentityTokens(prompt || '').split('\n').map((l) => l.trim()).find(Boolean) || ''
   const words = first.split(/\s+/).filter(Boolean).slice(0, 7).join(' ')
   if (!words) return null
   return words.length > 50 ? words.slice(0, 49).trimEnd() + '…' : words
@@ -953,7 +966,7 @@ export async function drainQueue(): Promise<void> {
 
 // @@@ superviseQueue - the periodic drainer. Started once at serve(). The explicit drainQueue() calls on
 // newSession/close/propose cover the slot-freeing events the SERVER handles, but an agent proposing done or
-// going parked writes its .session from a hook subprocess the server never sees, and a crash just makes a
+// going parked writes its global session.json record from a hook subprocess the server never sees, and a crash just makes a
 // socket vanish — so a timer is what turns those into freed slots. Cheap: one worktree+tmux snapshot per tick,
 // and a no-op when nothing is queued. Idempotent (guarded), so a second call is harmless.
 let supervisingQueue = false
@@ -1038,7 +1051,7 @@ export async function createSession(node: string | null, prompt: string, launche
   return await res.json() as Session
 }
 
-// @@@ newSession - durable worktree (branch node/<slug> off main) + .session label. The agent does NOT
+// @@@ newSession - durable worktree (branch node/<slug> off main) + a global session.json record. The agent does NOT
 // launch inline any more: the worktree is prepared and parked as `queued`, then drainQueue() launches it
 // immediately if we're under the concurrency cap, else it waits its turn. Backs both the dashboard POST and
 // `spex session new`. Creating or deleting a spec node is NOT a server op — it is prompt-driven work the
@@ -1061,6 +1074,10 @@ export async function newSession(node: string | null, prompt: string, parent: st
   const branch = `node/${slug}`
   const path = join(mainRoot(), '.worktrees', slug)
   await gitA(['-C', mainRoot(), 'worktree', 'add', '-b', branch, path, mainBranch()])
+  // the checkout delivers the tracked spec sources and the materialize below delivers the renders; the ONE
+  // thing git cannot carry is the machine-local spexcode.local.json — copied as a snapshot ([[render-policy]];
+  // no-op when the main checkout has none).
+  seedWorktreeHostState(mainRoot(), path)
   // prepared but NOT launched: enters the queue as `queued`. drainQueue() below launches it at once when a
   // slot is free, else it waits — durable as a global record (+ its worktree), so it survives a backend
   // restart and is still findable. governed:true — this is a DASHBOARD/CLI-launched session, so it feeds the
@@ -1085,7 +1102,7 @@ export async function newSession(node: string | null, prompt: string, parent: st
   // self-launched one does — by auto-discovery, not CLI injection. This is why the launch line below carries no
   // --append-system-prompt / --settings, and why we no longer hide CLAUDE.md: hiding it suppressed the agent's
   // own memory load too. One delivery path for both launch modes ([[harness-delivery]]).
-  try { materialize(path) } catch { /* best-effort; the dispatch.sh gate re-renders on the first event anyway */ }
+  bootstrapMaterialize(rec)
   let launchPrompt = prompt
   if (ref) {
     // @@@ spec pointer - the ref (explicit --node, else the prompt's first [[id]] ref) named an EXISTING node.
@@ -1104,6 +1121,24 @@ export async function newSession(node: string | null, prompt: string, parent: st
   return toSession(after, queued ? 'queued' : 'working', queued ? 'offline' : 'starting')
 }
 
+// @@@ bootstrapMaterialize - the creation-time materialize is BOOTSTRAP, not best-effort: it is what renders
+// the worktree's .claude/.codex shims (the settings.json hook wiring) in the first place, and the dispatch.sh
+// re-render gate RIDES ON those hooks — so when this render fails, no hook ever fires, the gate never runs,
+// and the worker comes up ungoverned (no contract block, no stop-gate) with nothing saying so. Fail loud
+// instead: log the cause + worktree, and stamp the failure on the record's `note` so the board/watch surface
+// it. The launch still proceeds — a visibly degraded worker the human can close + re-dispatch beats a refused
+// launch, and status stays agent-authored ([[state]]): we stamp the note, never an inferred `error` state.
+// `doMaterialize` is injectable only so tests can simulate the failure.
+export function bootstrapMaterialize(rec: SessRec, doMaterialize: (proj: string) => unknown = materialize): void {
+  try {
+    doMaterialize(rec.worktreePath)
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e)
+    console.error(`spex: materialize failed for worktree ${rec.worktreePath} — hooks/contract not rendered, worker launches UNGOVERNED: ${msg}`)
+    writeRecord({ ...rec, note: `materialize failed at creation — worker ungoverned (no hooks/contract): ${msg}` })
+  }
+}
+
 // @@@ waitForReady - after a launch/relaunch, the agent needs SEVERAL SECONDS to come up; launch() only TYPES
 // the start line via send-keys and returns immediately, so the agent's online-signal does not exist yet on
 // return. Poll the ADAPTER's liveness ([[harness-adapter]]) at a small interval up to a bounded timeout so the
@@ -1499,7 +1534,41 @@ export function resolveSession(selector: string, sessions: Session[]): Resolved
   return hits.length ? { ambiguous: hits } : { none: true }
 }
 
-const trunc = (s: string, n: number) => (s.length > n ? s.slice(0, n - 1) + '\u2026' : s)
+// @@@ display width - the table aligns by TERMINAL CELLS, not code units. CJK/fullwidth glyphs render
+// two cells wide, so `slice`/`padEnd` (which count code units) shear a wide glyph mid-cut and under-pad
+// the column, misaligning everything after it. A small wcwidth-style range check covers the wide blocks
+// that actually reach session labels/prompts \u2014 no dependency needed.
+const isWideCp = (cp: number): boolean =>
+  (cp >= 0x1100 && cp <= 0x115f) ||                   // Hangul Jamo
+  (cp >= 0x2e80 && cp <= 0xa4cf && cp !== 0x303f) ||  // CJK radicals \u2026 kana \u2026 CJK ideographs \u2026 Yi
+  (cp >= 0xac00 && cp <= 0xd7a3) ||                   // Hangul syllables
+  (cp >= 0xf900 && cp <= 0xfaff) ||                   // CJK compatibility ideographs
+  (cp >= 0xfe30 && cp <= 0xfe4f) ||                   // CJK compatibility forms
+  (cp >= 0xff00 && cp <= 0xff60) ||                   // fullwidth forms
+  (cp >= 0xffe0 && cp <= 0xffe6) ||                   // fullwidth signs
+  (cp >= 0x1f300 && cp <= 0x1faff) ||                 // emoji
+  (cp >= 0x20000 && cp <= 0x3fffd)                    // CJK extensions B+
+export function displayWidth(s: string): number {
+  let w = 0
+  for (const ch of s) w += isWideCp(ch.codePointAt(0)!) ? 2 : 1
+  return w
+}
+// truncate to a display width (the ellipsis occupies its own cell); never cuts a wide glyph in half.
+export function truncWidth(s: string, max: number): string {
+  if (displayWidth(s) <= max) return s
+  let w = 0
+  let out = ''
+  for (const ch of s) {
+    const cw = isWideCp(ch.codePointAt(0)!) ? 2 : 1
+    if (w + cw > max - 1) break
+    out += ch
+    w += cw
+  }
+  return out + '\u2026'
+}
+// pad to a display width \u2014 `padEnd` would count a double-cell glyph as one and under-pad the column.
+export const padWidth = (s: string, w: number): string => s + ' '.repeat(Math.max(0, w - displayWidth(s)))
+const trunc = truncWidth
 // the board table's NOTE display cap \u2014 exported so the declaration echo (cli.ts) can tell an author
 // exactly where their note gets cut, instead of the cap living as an anonymous magic number here.
 export const NOTE_BOARD_LIMIT = 50
@@ -1525,10 +1594,10 @@ export function formatTable(sessions: Session[], color = true): string {
   const rows = sessions.map((s) => {
     const g = STATUS_GLYPH[s.status] ?? '\u00b7'
     const code = ANSI[s.status] ?? '0'
-    const name = sessionLabel(s).slice(0, 22).padEnd(22)
+    const name = padWidth(truncWidth(sessionLabel(s), 22), 22)
     const st = s.status.padEnd(13)
     const merges = (s.merges ? `\u00d7${s.merges}` : '').padEnd(4)
-    const prompt = c('90', (s.promptPreview ? trunc(s.promptPreview, 40) : '').padEnd(42))   // what it was asked to do
+    const prompt = c('90', padWidth(s.promptPreview ? trunc(s.promptPreview, 40) : '', 42))   // what it was asked to do
     const note = s.note ? c('90', trunc(s.note, NOTE_BOARD_LIMIT)) : ''
     return `  ${c(code, g)} ${c(code, st)} ${name} ${c('90', s.id.slice(0, 8))} ${merges}${prompt}${note}`
   })

package/spec-cli/src/specs.ts

@@ -92,22 +92,30 @@ function walk(dir: string, parent: string | null, acc: Raw[]) {
   }
 }
 
-// re-key each node to the shortest globally-unique trailing path-suffix (overrides walk's placeholder
-// basename id/parent); the second loop recomputes parent by path-ancestry.
-// A node id is a URL-safe single token ([[id-url-safe]]) — never a '/'-joined path, which would break
-// every `:id` route and fetch that treats an id as one path segment. So the disambiguation separator is
-// '_': like '/' it never occurs inside a dir basename (so the join stays unambiguous), but unlike '/' it
-// is a URL/wikilink/DOM-safe unreserved char, so a collision-qualified id (e.g. `.config_spec-scout`)
-// stays a single token everywhere it is resolved.
-function reId(acc: Raw[]): void {
-  const segs = acc.map((r) => r.relPath.split(/[/\\]/).slice(1, -1))   // path under .spec, minus 'spec.md'
+// the id MINT ([[id-url-safe]]): key each node — given its path segments under .spec — to its leaf dir
+// name, or on a leaf collision the shortest globally-unique trailing path-suffix. A node id is a URL-safe
+// single token — never a '/'-joined path, which would break every `:id` route and fetch that treats an id
+// as one path segment. So the disambiguation separator is '_': like '/' it never occurs inside a dir
+// basename (so the join stays unambiguous), but unlike '/' it is a URL/wikilink/DOM-safe unreserved char,
+// so a collision-qualified id (e.g. `.config_spec-scout`) stays a single token everywhere it is resolved.
+// Exported as the ONE mint every id producer shares: spec-yatsu mints its node ids through this same
+// function over this same universe (every spec node), so a colliding leaf carries one canonical id
+// system-wide instead of a second, diverging bare-leaf scheme.
+export function mintIds(segs: string[][]): string[] {
   const suffix = (s: string[], k: number) => s.slice(s.length - k).join('_')
-  for (let i = 0; i < acc.length; i++) {
-    const s = segs[i]
+  return segs.map((s, i) => {
     let k = 1
     while (k < s.length && segs.some((o, j) => j !== i && o.length >= k && suffix(o, k) === suffix(s, k))) k++
-    acc[i].id = suffix(s, k)
-  }
+    return suffix(s, k)
+  })
+}
+
+// re-key each node via the mint (overrides walk's placeholder basename id/parent); the second loop
+// recomputes parent by path-ancestry.
+function reId(acc: Raw[]): void {
+  const segs = acc.map((r) => r.relPath.split(/[/\\]/).slice(1, -1))   // path under .spec, minus 'spec.md'
+  const ids = mintIds(segs)
+  for (let i = 0; i < acc.length; i++) acc[i].id = ids[i]
   for (let i = 0; i < acc.length; i++) {
     let best = -1
     for (let j = 0; j < acc.length; j++) {
@@ -217,11 +225,17 @@ export async function loadSpecs() {
     const fmSession = str(r.fm.session)
     const session = h[0]?.session || (fmSession && fmSession !== 'null' ? fmSession : null)
     const code = list(r.fm.code)
+    const related = list(r.fm.related)
     const S = h[0]?.hash || ''
     const driftFiles = code
       .map((f) => ({ file: f, behind: driftFor(didx, S, f) }))
       .filter((d) => d.behind > 0)
     const drift = driftFiles.reduce((a, d) => a + d.behind, 0)
+    // related drift is the SOFT tier ([[governed-related]]): same ancestry basis, but it stays OUT of
+    // `drift` — it never feeds status, the commit gate, or yatsu. It surfaces only as a lint warn nudge.
+    const relatedDriftFiles = related
+      .map((f) => ({ file: f, behind: driftFor(didx, S, f) }))
+      .filter((d) => d.behind > 0)
     const fmStatus = str(r.fm.status, '') || null
     return {
       id: r.id,
@@ -234,13 +248,14 @@ export async function loadSpecs() {
       hue: Number(str(r.fm.hue, '210')),
       desc: str(r.fm.desc),
       code,
-      related: list(r.fm.related),
+      related,
       version: h.length,
       reason: h[0]?.reason || '',
       // ISO date of the node's latest version commit (h is newest-first), or null if unversioned.
       lastEdited: h[0]?.date || null,
       drift,
       driftFiles,
+      relatedDriftFiles,
       // the latest version's spec.md patch is NOT precomputed here (it cost 2 git show forks per node on
       // cold load); the history tab fetches it lazily via specDiffAt. See [[work-pane]].
       body: r.body.trim(),

package/spec-cli/src/supervise.ts

@@ -17,7 +17,7 @@ import { runtimeRoot } from './layout.js'
 installProcessGuards()
 
 const here = dirname(fileURLToPath(import.meta.url))
-const tsx = tsxBin(join(here, '..'))   // this package's own tsx — spec-cli/node_modules (dev) or pkg root (published)
+const tsx = tsxBin(join(here, '..'))   // tsx's JS entry (dist/cli.mjs), run via `node` below — dev or published
 const entry = join(here, 'index.ts')                          // the real Hono server
 const publicPort = Number(process.env.PORT || 8787)
 
@@ -79,7 +79,7 @@ async function boot(): Promise<Backend | null> {
   // process.env.SPEXCODE_API_URL: the env this serve itself inherited may carry ANOTHER project's backend
   // (the exact misroute [[remote-client]]'s ladder exists to kill), and a worker's env is its routing
   // LIFELINE — it must be a deterministic backend-injected fact, not an inheritance gamble.
-  const child = spawn(tsx, [entry], { stdio: 'inherit', env: { ...process.env, PORT: String(port), SPEXCODE_API_URL: childApiBase } })
+  const child = spawn(process.execPath, [tsx, entry], { stdio: 'inherit', env: { ...process.env, PORT: String(port), SPEXCODE_API_URL: childApiBase } })
   // if the ACTIVE backend dies unexpectedly (crash, OOM), restart it so the public port keeps serving.
   // Planned retirement sets current to the NEW child first, so the old child's exit fails this identity
   // check and is ignored. boot()'s ~5s health budget rate-limits any crash loop.

package/spec-cli/src/tsx-bin.ts

@@ -1,20 +1,18 @@
-import { existsSync } from 'node:fs'
 import { createRequire } from 'node:module'
 import { dirname, join } from 'node:path'
 
-// @@@ tsxBin - where the tsx executable lives, dev-or-published. In the dev monorepo it sits in
+// @@@ tsxBin - tsx's JS ENTRY (dist/cli.mjs), dev-or-published, run through `node` by the caller
+// (`spawn(process.execPath, [tsxBin(pkgDir), entry, …])`). In the dev monorepo tsx sits in
 // spec-cli/node_modules; in an installed `spexcode` package npm may hoist it to the consumer's node_modules
-// instead of nesting it under the package. Resolve explicit local candidates first, then let Node's own
-// package resolver walk upward from spec-cli so dev, global, and project-local installs share one mechanism.
+// — Node's own package resolver from spec-cli covers dev, global, and project-local installs in one rule.
+// We resolve the .mjs entry rather than the `.bin/tsx` shim on purpose: the shim is an unspawnable sh
+// script on Windows, so `node dist/cli.mjs` (identical to the shim on POSIX) is the one cross-platform form.
 // `pkgDir` is the spec-cli directory.
 export function tsxBin(pkgDir: string): string {
-  const candidates = [join(pkgDir, 'node_modules', '.bin', 'tsx'), join(pkgDir, '..', 'node_modules', '.bin', 'tsx')]
-  const local = candidates.find(existsSync)
-  if (local) return local
   try {
     const req = createRequire(join(pkgDir, 'package.json'))
     return join(dirname(req.resolve('tsx/package.json')), 'dist', 'cli.mjs')
   } catch {
-    return candidates[0]
+    throw new Error(`tsx runtime not found from ${pkgDir} — run \`npm install\` in the SpexCode package`)
   }
 }

package/spec-cli/src/uninstall.ts

@@ -1,17 +1,20 @@
 import { existsSync, readFileSync, readdirSync, rmSync } from 'node:fs'
 import { join, resolve, relative } from 'node:path'
 import { execFileSync } from 'node:child_process'
-import { HARNESSES, removeManagedBlock, type HarnessArtifacts } from './harness.js'
+import { HARNESSES, type HarnessArtifacts } from './harness.js'
 import { runtimeRoot, readConfig, mainCheckout } from './layout.js'
 import { resolveHarnessTargets } from './harness-select.js'
 import { loadSkillConfig, loadAgentConfig } from './specs.js'
+import { dematerialize } from './materialize.js'
 
-// @@@ spex-uninstall - the surgical inverse of spex-init/materialize. init + harness-delivery WRITE the
-// SpexCode footprint into a repo; this REMOVES it, so a project can fully back out. EVERY removal is gated on a
-// SpexCode IDENTITY STAMP (the managed-block sentinels, the shim's own dispatch.sh command line, the trust
-// sentinels, the name-scoped on-demand paths, the plugin name stamp), so it can only ever delete what SpexCode
-// itself generated. The one inviolable rule: the user's spec ASSET (.spec/.config) is NEVER touched — uninstall
-// removes only generated WIRING, not the spec graph that wiring served.
+// @@@ spex-uninstall - materialize(∅) plus the store: the in-tree/global-config backout IS dematerialize (the
+// same identity-stamped erase phase every render runs first — the forgetting law's empty policy), and this
+// command adds only what a render never owns per-run: the global per-project store, the plugin-bundle sweep,
+// and the optional git hooks. EVERY removal is gated on a SpexCode IDENTITY STAMP (the managed-block
+// sentinels, the shim's own dispatch.sh command line, the trust sentinels, the generated mark / name-scoped
+// on-demand paths, the plugin name stamp), so it can only ever delete what SpexCode itself generated. The one
+// inviolable rule: the user's spec ASSET (.spec/.config) is NEVER touched — uninstall removes only generated
+// WIRING, not the spec graph that wiring served.
 
 // the standard plugin-host folders a host agent scans (in addition to any named in spexcode.json's `harnesses`).
 const DEFAULT_PLUGIN_HOSTS = ['.claude', '.codex'] as const
@@ -95,14 +98,10 @@ export function uninstall(targetArg: string | undefined, opts: { hooks?: boolean
     process.chdir(prevCwd)
   }
 
-  // 1. every harness's own artifacts — clean() is the adapter's surgical inverse (managed contract block w/
-  //    deleteIfEmpty, generated shim, trust block, named skill/agent files). materialize cleans only UNSELECTED
-  //    harnesses; uninstall cleans EVERY one. clean() already calls removeTrust, so it is the full inverse.
-  for (const h of HARNESSES) h.clean(proj, arts)
-
-  // 2. the shared .gitignore block — the one in-tree artifact no adapter owns (materialize writes it directly),
-  //    so strip it directly too: the managed `#` block, deleteIfEmpty so a wholly-ours .gitignore is removed.
-  removeManagedBlock(join(proj, '.gitignore'), ['# ', ''], true)
+  // 1+2. materialize(∅): every harness's artifacts (contract block, shim, trust, skills/agents), the managed
+  //    .gitignore + info/exclude blocks, any legacy skip-worktree bit, and the content filter — the SAME
+  //    erase phase every render runs, asserted against the empty policy. One inverse, never a parallel one.
+  dematerialize(proj, arts)
 
   // 3. the global per-project store — manifest + content-hash marker + gate lock + session records. This is the
   //    runtime tier, not the user's spec asset, so the whole dir is ours.
@@ -124,8 +123,7 @@ export function uninstall(targetArg: string | undefined, opts: { hooks?: boolean
   }
   const bundles = sweepPluginBundles(proj, pluginHosts)
 
-  console.log(`✓ pruned harness artifacts (CLAUDE.md/AGENTS.md block, shims, Codex trust, skills, sub-agents) for ${HARNESSES.map((h) => h.id).join(', ')}`)
-  console.log('✓ stripped the .gitignore spexcode block')
+  console.log(`✓ dematerialized (contract blocks, shims, Codex trust, skills, sub-agents, ignore blocks, content filter) for ${HARNESSES.map((h) => h.id).join(', ')}`)
   if (store) console.log(`✓ removed the global per-project store (${store})`)
   if (bundles.length) console.log(`✓ removed plugin bundle(s): ${bundles.join(', ')}`)
 

package/spec-cli/src/worktree-sources.ts

@@ -0,0 +1,56 @@
+import { appendFileSync, copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { git } from './git.js'
+
+// @@@ worktree-sources ([[render-policy]]) - a fresh session worktree is fed by THREE transports, one per
+// source kind, and the kind decides the transport — never a mode branch:
+//   - TRACKED project state (`.spec`, `spexcode.json`) arrives by GIT CHECKOUT: the sources are always
+//     tracked (git is the database), so `git worktree add` alone delivers them. No symlink — a link is a
+//     WRITE-SEMANTICS declaration (write-through to the main tree), and spec writes go back through the
+//     branch/merge ritual, not through a side channel.
+//   - RENDERS (contract blocks, shims, skills) are DERIVED — transported by re-render, not by link or copy:
+//     sessions.ts materializes into the worktree at creation, and the dispatch gate re-renders on change.
+//   - HOST state (`spexcode.local.json`, machine-local and never tracked) is COPIED — a snapshot: the worker
+//     reads the same launchers/policy the host had at dispatch, but its writes land on its own copy and die
+//     with the worktree, never on the host's real config (a worker once wrote "its" test config through the
+//     old symlink and wiped the host's launchers → every later dispatch 401'd).
+// This module owns only the third transport (plus hiding what it seeds). A failure degrades that worker
+// (default launchers/policy), so it is reported, not swallowed.
+export function seedWorktreeHostState(main: string, wt: string): void {
+  const f = 'spexcode.local.json'
+  try {
+    if (!existsSync(join(main, f)) || existsSync(join(wt, f))) return
+    copyFileSync(join(main, f), join(wt, f))
+  } catch (e) {
+    console.error(`spexcode: could not seed ${f} from ${main} into worktree ${wt} — that worker runs on defaults (${e})`)
+    return
+  }
+  hideSeededFromGit(wt, [f])
+}
+
+// what we seed, we hide: a seeded entry git still sees is force-add bait (a real PR once carried seeded
+// files into a product repo). `.git/info/exclude` lives in the COMMON git dir, so one write hides the entry
+// in every linked worktree AND the main checkout. Only entries seeded by THIS call and reported un-ignored
+// by `git check-ignore` are written: idempotent across dispatches, and a repo whose render already ignores
+// the overlay (materialize's block under any policy) writes nothing — the self-heal for a half-configured repo.
+function hideSeededFromGit(wt: string, seeded: string[]): void {
+  for (const f of seeded) {
+    try {
+      if (isIgnored(wt, f)) continue
+      const exclude = join(git(['-C', wt, 'rev-parse', '--path-format=absolute', '--git-common-dir']).trim(), 'info', 'exclude')
+      mkdirSync(dirname(exclude), { recursive: true })
+      const cur = existsSync(exclude) ? readFileSync(exclude, 'utf8') : ''
+      appendFileSync(exclude, `${cur && !cur.endsWith('\n') ? '\n' : ''}${f}\n`)
+    } catch (e) {
+      console.error(`spexcode: could not hide seeded ${f} in the shared info/exclude for ${wt} — it will show untracked there (${e})`)
+    }
+  }
+}
+
+function isIgnored(wt: string, f: string): boolean {
+  try { git(['-C', wt, 'check-ignore', '-q', f]); return true }
+  catch (e: any) {
+    if (e?.status === 1) return false   // check-ignore's documented "not ignored" exit
+    throw e
+  }
+}

package/spec-cli/templates/spec/project/.config/core/stop-gate/spec.md

@@ -12,6 +12,6 @@ The blocking stop gate, with two jobs, each holding a hard loop-break so it neve
 
 The COMMIT gate keeps a done/merge proposal honest: such a proposal is rejected while the branch still carries uncommitted work or is zero commits ahead of main, because the ritual commits the spec and code BEFORE proposing. Clean work is allowed to stop; a dirty proposal blocks once with the reason, and if the agent ignores it the gate escapes by downgrading to `asking` so a false "ready to merge" can never stand.
 
-The DECLARE gate refuses to let a session stop in an undeclared `active` state, since a state is a claim the board and other agents act on, not a box ticked to end a turn. A declared state stops freely; an undeclared first stop blocks once to make the agent pick the true state; on the forced continuation it auto-declares a safe default — committed work becomes `awaiting`, otherwise `asking` — so the loop is guaranteed to end.
+The DECLARE gate refuses to let a session stop in an undeclared `active` state, since a state is a claim the board and other agents act on, not a box ticked to end a turn. A declared state stops freely; an undeclared first stop blocks once to make the agent pick the true state; on the forced continuation it auto-declares a safe default — committed work becomes `awaiting`, otherwise `asking` — so the loop is guaranteed to end. The full block text (choices, each with its application condition, plus the discipline of declaring as the turn's LAST call — any later tool call re-flips the record to active) prints once per session, marked by a sentinel file beside the session record; later undeclared stops get a one-line reminder that stays self-explanatory — menu, declare-last, and the `spex help session` entry that recovers the full conditions.
 
 It is the enforcement edge of [[core]]: nothing leaves a session except as committed work under a truthful declaration. The freshness it reads is set by [[mark-active]].

package/spec-cli/templates/spec/project/.config/core/stop-gate/stop-gate.sh

@@ -109,12 +109,30 @@ if [ "$cont" = true ]; then
   exit 0
 fi
 
-# first stop in an undeclared state -> nudge exactly once. The reason names the PATH-independent CLI ($S)
-# ONCE as a shared `<CLI> session <choice>` prefix, then lists the five choices as a compact newline menu of
-# bare subcommands — so the terminal output stays legible instead of repeating the long abs path per option.
-# It EMPHASIZES that each state is a CLAIM others act on (not a box to tick to end the turn) and gives the
-# precise APPLICATION CONDITION for each — so the agent picks the TRUE one. park is policed hardest because
-# a false park (no real background task) reads on the board as "fine, self-resuming" when the agent actually
-# needs the human, which is the most damaging mislabel.
-printf '{"decision":"block","reason":"Your session state is a CLAIM the board, your supervisor, and other agents act on — not a box to tick to end the turn. Stopping undeclared makes your outcome a guess. Pick the ONE that is TRUE right now and run `%s session <choice>`, choosing the <choice> whose condition holds:\\n  • done --propose merge  — spec+code COMMITTED on the branch and genuinely ready for a human to review/merge (not just probably-done).\\n  • done --propose nothing — committed, but you are NOT proposing a merge; paused for the human to look.\\n  • park --note <what-you-await> — ONLY when a real BACKGROUND TASK will wake you (a spex wait you backgrounded, a running build/job). If nothing is actually running to resume you, you are NOT parked — you are waiting on the human, so use ask; never use park as a default to clear this gate.\\n  • done --propose close — you propose discarding this worktree.\\n  • ask --note <your-question> — you need the human: a real question, or you are simply stopped awaiting direction; you resume only when they reply."}\n' "$S"
+# first stop in an undeclared state -> block. The FULL teaching text prints ONCE per session; every later
+# undeclared stop gets a ONE-LINE version (a heavy session hits this gate 15-20x a night — re-printing the
+# full menu each time is pure token noise). The once-sentinel is a plain file beside session.json in the
+# session's global store dir — the same per-session-sentinel mechanism as the CLI's note-echo-taught; $sdir
+# is already alias-resolved here, so a codex thread id lands on the same file, and an unwritable dir just
+# teaches again (never blocks the block). The terse line must stay SELF-EXPLANATORY: an agent whose context
+# was compacted may never have seen the full text, so the line carries the whole command menu, the
+# declare-LAST discipline, and the `help session` entry that re-explains each choice's condition — every bit
+# of the full-to-terse information gap is recoverable from the entry, none of it from memory.
+taught="$sdir/stop-gate-taught"
+if [ -f "$taught" ]; then
+  printf '{"decision":"block","reason":"undeclared stop — pick the ONE true state and declare it as the LAST call of your turn: `%s session <done --propose merge|nothing|close / park --note <what-you-await> / ask --note <your-question>>`. Which choice is true (and why park is never a default): `%s help session`."}\n' "$S" "$S"
+  exit 0
+fi
+touch "$taught" 2>/dev/null || true
+# The full reason names the PATH-independent CLI ($S) ONCE as a shared `<CLI> session <choice>` prefix, then
+# lists the five choices as a compact newline menu of bare subcommands — so the terminal output stays legible
+# instead of repeating the long abs path per option. It EMPHASIZES that each state is a CLAIM others act on
+# (not a box to tick to end the turn) and gives the precise APPLICATION CONDITION for each — so the agent
+# picks the TRUE one. park is policed hardest because a false park (no real background task) reads on the
+# board as "fine, self-resuming" when the agent actually needs the human, which is the most damaging mislabel.
+# It ends with the ORDERING discipline — declare LAST, then stop — because a declaration followed by more
+# tool calls honestly re-flips the record to active (mark-active, by design) and re-blocks the next stop;
+# this block text is the one place every undeclared stopper is guaranteed to read, so the teaching that
+# kills the park->block->re-park loop at its source lives here.
+printf '{"decision":"block","reason":"Your session state is a CLAIM the board, your supervisor, and other agents act on — not a box to tick to end the turn. Stopping undeclared makes your outcome a guess. Pick the ONE that is TRUE right now and run `%s session <choice>`, choosing the <choice> whose condition holds:\\n  • done --propose merge  — spec+code COMMITTED on the branch and genuinely ready for a human to review/merge (not just probably-done).\\n  • done --propose nothing — committed, but you are NOT proposing a merge; paused for the human to look.\\n  • park --note <what-you-await> — ONLY when a real BACKGROUND TASK will wake you (a spex wait you backgrounded, a running build/job). If nothing is actually running to resume you, you are NOT parked — you are waiting on the human, so use ask; never use park as a default to clear this gate.\\n  • done --propose close — you propose discarding this worktree.\\n  • ask --note <your-question> — you need the human: a real question, or you are simply stopped awaiting direction; you resume only when they reply.\\n\\nDECLARE LAST, THEN STOP: finish everything else in the turn first — speak, send your messages, arm your background waits — and make the declaration your FINAL call. Any tool call AFTER it flips your record back to active (mark-active, by design: activity is activity), so the next stop re-blocks and demands a fresh declaration; declaring last kills that loop at its source.\\n\\n(This full explanation shows once per session; later undeclared stops get a one-line reminder. `%s help session` re-explains the choices any time.)"}\n' "$S" "$S"
 exit 0