spexcode 0.2.4 → 0.2.6

package/spec-cli/src/ranker.ts

@@ -5,7 +5,7 @@
 // is why they sit in flat plateaus rather than being fitted to any case.
 const W_NAME_PREFIX = 8
 const W_NAME_SUBSTR = 5
-const W_DESC = 3
+const W_DESC = 2
 const W_BODY = 1
 
 // a tiny stoplist of question scaffolding + length-1 tokens, dropped so "how does the … is it …" can't drown
@@ -19,19 +19,34 @@ const STOP = new Set([
   'be', 'can', 'just', 'them', 'they', 'their', 'so', 'if', 'not', 'no', 'but', 'vs', 'us', 'we', 'you',
 ])
 
-// split on non-alphanumeric, lowercase, drop stopwords + length-1 tokens, de-dup.
+// The corpus is mostly English but not only — some nodes carry CJK prose (the root spexcode node is a whole
+// Chinese paragraph), and the dashboard palette ([[shared-ranker]]) ranks session/issue titles that are
+// frequently Chinese. CJK has no spaces, so a whitespace/`[^a-z0-9]` split silently discards ALL of it. We
+// tokenize the SAME way on both sides: an ASCII alphanumeric run is one token; each CJK character is its own
+// token (a unigram). Unigrams — not bigrams — keep the shared prefix-match/IDF/BM25 machinery untouched (a
+// single-char query still matches, no bigram edge cases) and stay BLUNT & ROBUST, the floor's whole stance.
+// Han (incl. Ext-A + compat) plus Japanese kana; enough to cover the CJK a spec body or a session title carries.
+const CJK = '\\u3400-\\u4dbf\\u4e00-\\u9fff\\uf900-\\ufaff\\u3040-\\u30ff' // Ext-A · Unified · Compat · kana
+const TOKEN_RE = new RegExp(`[a-z0-9]+|[${CJK}]`, 'g')
+const CJK_RE = new RegExp(`[${CJK}]`)
+function isCjk(t: string): boolean { return CJK_RE.test(t) }
+function tokenize(text: string): string[] {
+  return text.toLowerCase().match(TOKEN_RE) ?? []
+}
+
+// tokenize, lowercase, drop stopwords + length-1 ASCII tokens (a length-1 CJK token is a real word — keep it), de-dup.
 export function terms(query: string): string[] {
   const seen = new Set<string>()
-  for (const w of query.toLowerCase().split(/[^a-z0-9]+/)) {
-    if (w.length > 1 && !STOP.has(w)) seen.add(w)
+  for (const w of tokenize(query)) {
+    if (isCjk(w) || (w.length > 1 && !STOP.has(w))) seen.add(w)
   }
   return [...seen]
 }
 
 // the words of a field, lowercased — used for word-boundary (prefix-of-a-word) matching, which kills
-// short-token pollution (`main` must not match inside `domain`).
+// short-token pollution (`main` must not match inside `domain`); CJK chars are single-char words.
 function words(text: string): string[] {
-  return text.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean)
+  return tokenize(text)
 }
 
 // light query-side stem for prefix matching: drop a trailing plural 's' (len≥4, not 'ss') then a mute 'e'
@@ -87,8 +102,10 @@ function snippetFor(text: string, desc: string, qterms: string[], window = 140):
   const lower = flat.toLowerCase()
   let at = -1
   for (const t of qterms) {
-    const m = lower.match(new RegExp('\\b' + t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')))
-    if (m && m.index !== undefined && (at < 0 || m.index < at)) at = m.index
+    // ASCII terms locate at a word boundary (so `main` doesn't hit inside `domain`); a CJK term has no
+    // `\b` around it (JS `\b` is ASCII-only), so locate it by plain substring.
+    const i = isCjk(t) ? lower.indexOf(t) : lower.search(new RegExp('\\b' + t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')))
+    if (i >= 0 && (at < 0 || i < at)) at = i
   }
   if (at < 0) {
     const fb = (desc || flat).replace(/\s+/g, ' ').trim()

package/spec-cli/src/runtime-guard.ts

@@ -0,0 +1,44 @@
+import { spawnSync } from 'node:child_process'
+
+// @@@ session-runtime guard ([[platform-support]]) - SpexCode's session orchestration rests on POSIX
+// primitives with no native-Windows analog: tmux (the durable detached PTY + capture-pane scrollback +
+// multi-client reattach fabric), hand-written bash launch scripts, and filesystem-path AF_UNIX control
+// sockets. The supported runtime is POSIX — Linux, macOS, or Windows *via WSL2* (a real Linux kernel where
+// tmux/bash/unix-sockets all work). This is the honest gate at the entry to the session runtime: detect the
+// load-bearing primitive (tmux) missing and print ONE actionable line naming the fix, instead of letting a
+// cryptic downstream ENOENT be the user's first signal. Read-only CLI (init/lint/board) never calls this,
+// so it still runs anywhere the launcher does — only the session-launch path (`spex serve`) is gated.
+
+// tmux presence is the primitive we actually depend on, so probe THAT rather than assuming by platform:
+// this also catches a bare POSIX box that simply hasn't installed tmux, not only native Windows.
+export function hasTmux(): boolean {
+  try {
+    return spawnSync('tmux', ['-V'], { stdio: 'ignore' }).status === 0
+  } catch {
+    return false
+  }
+}
+
+// Pure so it is unit-testable without spawning or exiting: null = runtime OK; otherwise the stderr lines.
+// The pointer branches on platform because the honest repair differs — WSL2 on Windows (no POSIX analog at
+// all), install-tmux on a POSIX host that merely lacks it.
+export function sessionRuntimeBlock(env: { hasTmux: boolean; platform: string }): string[] | null {
+  if (env.hasTmux) return null
+  const lines = ['spex: the session runtime needs a POSIX host (tmux, bash, and unix-domain sockets).']
+  if (env.platform === 'win32') {
+    lines.push('Native Windows has no analog for these — run SpexCode under WSL2 (a real Linux kernel):')
+    lines.push('  wsl --install   # then, in the Ubuntu shell: nvm install 22 && npm i -g spexcode')
+  } else {
+    lines.push('tmux is not on PATH — install it and retry (e.g. `apt install tmux`, `brew install tmux`).')
+  }
+  return lines
+}
+
+// Called at the top of the session-launching command path (`spex serve`). Exits 69 (EX_UNAVAILABLE: a
+// required support program does not exist) — a distinct, honest code, not a swallowed error or a stacktrace.
+export function assertSessionRuntime(): void {
+  const block = sessionRuntimeBlock({ hasTmux: hasTmux(), platform: process.platform })
+  if (!block) return
+  for (const line of block) console.error(line)
+  process.exit(69)
+}

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,12 +4,12 @@ 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 { linkUntrackedSpecSources } from './worktree-sources.js'
+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'
 import { materialize } from './materialize.js'
-import { mainBranch, gitCommonDir, readConfig, runtimeRoot, sessionStoreDir, sessionRecordPath, sessionArtifactPath, listSessionIds, readAliasedRawRecord, envSessionId, type RawRecord } from './layout.js'
+import { mainBranch, gitCommonDir, readConfig, runtimeRoot, treeSlotDir, sessionStoreDir, sessionRecordPath, sessionArtifactPath, listSessionIds, readAliasedRawRecord, envSessionId, type RawRecord } from './layout.js'
 import { stripRefSigil } from './mentions.js'
 
 // @@@ sessions - the WORKTREE is the durable unit; tmux is a disposable runtime handle. The per-session
@@ -76,7 +76,7 @@ function maxActive(): number {
 // rvSock is imported only for the two NON-delivery uses that remain product-level: building the launch env var
 // (rvEnv, below) and the best-effort socket sweep on close.
 // env prefix put in front of the spawned agent so it creates this session's rendezvous control socket — and
-// so its hooks + materialize render to the SAME store the backend uses. SPEXCODE_HOME/CODEX_HOME are
+// so its hooks + materialize write to the SAME store the backend uses. SPEXCODE_HOME/CODEX_HOME are
 // propagated when set, because the session inherits the tmux SERVER's env (not the backend's), so without this
 // an overridden home would silently leak the session's hook-state + codex-trust to the default ~/.spexcode /
 // ~/.codex. Deterministic: the session's store = the backend's store, never the ambient env's.
@@ -502,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> {
@@ -802,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
@@ -811,10 +817,19 @@ const slugify = (s: string | null) => (s || 'session').replace(/[^a-zA-Z0-9_-]/g
 // When there is none, the session is node-agnostic and we label it by the first few words of the prompt.
 // The OPTIONAL leading dot is load-bearing: a node id is its dir basename, so a dot-prefixed config root
 // (`.config`) keeps the dot — without `\.?` here `[[.config]]` captures nothing and never resolves to a node.
-const MENTION = /\[\[(\.?[A-Za-z0-9_-]+)\]\]/
+// Token chars are ANY unicode letter/number (slugify's already-made choice): a CJK dir name is a legal node
+// id, so `[[中文节点]]` must bind the session exactly like an ASCII id — ASCII-only here silently launched
+// node-agnostic.
+const MENTION = /\[\[(\.?[\p{L}\p{N}_-]+)\]\]/u
 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)@[\p{L}\p{N}_-]+/gu, '$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
@@ -954,7 +969,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
@@ -1039,7 +1054,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
@@ -1062,9 +1077,11 @@ 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()])
-  // a private-overlay repo keeps the spec sources out of git, so the checkout alone leaves this worktree
-  // spec-blind and hook-dead — link them from main ([[private-overlay]]; no-op on a default-mode repo).
-  linkUntrackedSpecSources(mainRoot(), path)
+  // the checkout delivers the tracked spec sources and the materialize below delivers the materialized
+  // artifacts; the ONE
+  // thing git cannot carry is the machine-local spexcode.local.json — copied as a snapshot ([[residence]];
+  // 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
@@ -1084,12 +1101,12 @@ export async function newSession(node: string | null, prompt: string, parent: st
   }
   writeRecord(rec)
   writePromptFile(id, prompt)   // capture the ORIGINATING prompt (the human/manager's ask) as store metadata (best-effort)
-  // render the harness-discovered artifacts INTO the worktree (CLAUDE.md/AGENTS.md contract block, .claude/.codex
+  // materialize the harness-discovered artifacts INTO the worktree (CLAUDE.md/AGENTS.md contract block, .claude/.codex
   // shims, manifest to the global store) so the launched agent gets the contract + hooks the SAME way a
   // 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.
@@ -1108,6 +1125,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 writes
+// the worktree's .claude/.codex shims (the settings.json hook wiring) in the first place, and every
+// lifecycle dispatch RIDES ON those hooks — so when this materialize fails, no hook ever fires,
+// 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 materialized, 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
@@ -1225,8 +1260,8 @@ export function markIdle(sessionId?: string): boolean {
 // done / propose merge. The dogfood ritual lands every change as a COMMIT on the node branch first, so two
 // states block a declaration: (1) any uncommitted working-tree change, or (2) 0 commits ahead of main
 // (nothing committed to merge). Since the global-store refactor, SpexCode writes NO per-session files into
-// the worktree (the runtime lives in ~/.spexcode), and the only in-tree SpexCode artifacts are gitignored
-// (the materialize shims/skills) or tracked-and-committed (the contract block in CLAUDE.md/AGENTS.md), so
+// the worktree (the runtime lives in ~/.spexcode), and the only in-tree SpexCode artifacts are exclude-
+// hidden materialized artifacts or filter-covered contract blocks ([[residence]]), so
 // neither shows as an uncommitted change — the worktree is pristine and EVERY dirty path is genuine spec/code
 // work, no runtime-file filtering needed.
 // Runs from cwd = the session worktree; ALL git goes through git() so the hook's exported GIT_DIR/GIT_INDEX_FILE
@@ -1415,12 +1450,17 @@ export async function exitSession(id: string): Promise<boolean> {
 // the session's whole global-store record dir — the work is gone, not just stopped. Same stop primitive as
 // exitSession (no duplicate kill path), then the git worktree/branch teardown that exit deliberately skips,
 // then the store sweep (exit KEEPS the record so the session stays on the board offline; close discards it).
+// The tree's materialize slot ([[runtime]] trees/<enc>) retires with the worktree — its key needs the live tree,
+// so it is resolved BEFORE the removal; both sweeps are best-effort (residue is swept at uninstall anyway).
 export async function closeSession(id: string): Promise<boolean> {
   const wt = await findWorktree(id)
   await stopAgentProcess(id)
   if (wt) {
+    let slot: string | null = null
+    try { slot = treeSlotDir(wt.path) } catch { /* tree already unresolvable — nothing to key the slot by */ }
     await gitA(['-C', mainRoot(), 'worktree', 'remove', '--force', wt.path])
     if (wt.branch) await gitA(['-C', mainRoot(), 'branch', '-D', wt.branch])
+    if (slot) { try { rmSync(slot, { recursive: true, force: true }) } catch { /* best-effort GC */ } }
   }
   try { rmSync(sessionStoreDir(id), { recursive: true, force: true }) } catch { /* best-effort sweep of the global record */ }
   void drainQueue()   // a close frees a slot — start the next queued session if any
@@ -1503,7 +1543,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
@@ -1529,10 +1603,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,32 @@ 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'
-  const suffix = (s: string[], k: number) => s.slice(s.length - k).join('_')
-  for (let i = 0; i < acc.length; i++) {
-    const s = segs[i]
+// 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[] {
+  // NFC pins one canonical byte form for a non-ASCII dir name (macOS hands out NFD basenames), so a typed
+  // `[[中文节点]]` (NFC, what an IME emits) string-matches the minted id on every platform.
+  const suffix = (s: string[], k: number) => s.slice(s.length - k).join('_').normalize('NFC')
+  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 +227,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 +250,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(),
@@ -342,7 +359,10 @@ function loadSurface(surface: 'command' | 'system' | 'hook' | 'skill' | 'agent')
       // @@@ skip pending - a `status: pending` plugin is DECLARED INTENT, not yet active. It renders on the
       // board (via loadSpecs) but must NOT gather: neither a command preset, nor folded into a system prompt,
       // nor a live hook. Only built/active plugins surface here, so pending stubs stay inert.
-      if (str(fm.surface) === surface && str(fm.status) !== 'pending') {
+      // the surface field may name SEVERAL surfaces (comma-separated or a YAML list) — the node plugs
+      // into every one it lists, so the match is membership, not equality.
+      const surfaces = list(fm.surface).flatMap((v) => String(v).split(',')).map((v) => v.trim()).filter(Boolean)
+      if (surfaces.includes(surface) && str(fm.status) !== 'pending') {
         out.push({
           name,
           title: str(fm.title, name),
@@ -375,10 +395,10 @@ export function loadSystemConfig(): ConfigPreset[] { return loadSurface('system'
 // the hook handlers (compiled into the per-session hook manifest the dispatcher reads). Each carries its
 // `events`/`order`/`block` binding + co-located script `files`.
 export function loadHookConfig(): ConfigPreset[] { return loadSurface('hook') }
-// the skill bundles (rendered into each harness's auto-discovered SKILL.md dir). Each node's `desc` is the
+// the skill bundles (materialized into each harness's auto-discovered SKILL.md dir). Each node's `desc` is the
 // load-trigger and its `body` is the on-demand instructions; loadSurface passes the folder basename as `name`.
 export function loadSkillConfig(): ConfigPreset[] { return loadSurface('skill') }
-// the sub-agent definitions (rendered into each harness's auto-discovered agent dir, e.g. claude's
+// the sub-agent definitions (materialized into each harness's auto-discovered agent dir, e.g. claude's
 // .claude/agents/<name>.md). Like a skill, the node's `desc` is the on-demand load-trigger and its `body` is the
 // agent's system prompt; additionally its `tools` field is the harness tool allowlist for the spawned agent.
 export function loadAgentConfig(): ConfigPreset[] { return loadSurface('agent') }

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 materialize runs first — the forgetting law's empty policy), and this
+// command adds only what a materialize 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,17 +98,14 @@ 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)
+  // 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 materialize runs, asserted against the empty policy. One inverse, never a parallel one.
+  dematerialize(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)
-
-  // 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.
+  // 3. the global per-project store — the per-tree materialize slots (trees/<enc>: manifest + content-hash +
+  //    plugin ledger), any legacy pre-slot manifest, and the session records. This is the runtime tier,
+  //    not the user's spec asset, so the whole dir is ours.
   let store: string | null = null
   try {
     store = runtimeRoot(proj)
@@ -124,8 +124,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(', ')}`)