spexcode 0.2.5 → 0.2.6

package/spec-cli/src/materialize.ts

@@ -6,13 +6,15 @@ 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, mainCheckout, readConfig } from './layout.js'
+import { runtimeRoot, treeSlotDir, mainCheckout, readConfig } 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'
 
-// @@@ materialize - the "pay-per-change" node step (≈0.85s) the cheap shell gate invokes ONLY when the
-// content-hash moved. It renders the spec tree's surface nodes into the flat artifacts each consumer reads
+// @@@ materialize - the materialize step (≈0.85s), anchored on GIT-NATIVE events only ([[commit-surgery]]):
+// spex verbs (init/materialize), session-worktree creation, and the planted git hooks (pre-commit,
+// post-checkout, post-merge) — never a harness event; the harness is a READER of the materialized files, not
+// a trigger. It turns the spec tree's surface nodes into the flat artifacts each consumer reads
 // cheaply, so a USER-self-launched claude/codex (no SpexCode process in the launch) gets the whole system via
 // harness-auto-discovered files: (1) the hook MANIFEST (our dispatcher reads it), (2) the CONTRACT — the
 // tracked docs guide (docs/AGENT_GUIDE.md) FOLLOWED BY the surface:system bodies — written WHOLE into each
@@ -20,7 +22,7 @@ import { plantContractFilter, removeContractFilter, settleIndexStat } from './co
 // (Codex's deterministic trusted_hash; Claude none). EVERY harness-specific fact is owned by the
 // [[harness-adapter]] (harness.ts) — this file just loops over HARNESSES.
 //
-// THE FORGETTING LAW ([[harness-delivery]]): materialize(P₂) ∘ materialize(P₁) = materialize(P₂) — a render
+// THE FORGETTING LAW ([[harness-delivery]]): materialize(P₂) ∘ materialize(P₁) = materialize(P₂) — one pass
 // under the current policy fully forgets every prior policy's artifacts; idempotence is the special case
 // P₂ = P₁, and dematerialize (= materialize(∅), what `spex uninstall` builds on) is the empty policy. The
 // implementation is ERASE-THEN-ASSERT over a CLOSED set of landing points: each is first erased
@@ -35,15 +37,17 @@ const DISPATCH = join(PKG, 'hooks', 'dispatch.sh')
 // resolution AND the mid-merge guard (a conflicted source tree degrades to one line + exit 75, not an
 // esbuild stacktrace), so every hook-baked callback inherits both.
 const SPEX = join(PKG, 'bin', 'spex.mjs')
-// the manifest + content-hash marker render into the GLOBAL per-project store (layout.runtimeRoot), NOT the
-// worktree — the worktree keeps zero SpexCode-rendered runtime; only the harness-discovered contract files +
-// shims (which the harness must find in-tree) are written under proj below.
+// the manifest + content-hash marker + plugin-folder ledger land in the materialized TREE's own slot of the
+// GLOBAL per-project store (layout.treeSlotDir — trees/<enc-worktree>), NOT the worktree and NOT one shared
+// per-project file: each is a pure function of ONE tree's .config, and the old single slot let the last-
+// materialized tree's hook set reach every other tree's dispatch ([[hook-dispatch]]). The worktree keeps
+// zero SpexCode-materialized runtime; only the harness-discovered contract files + shims (which the harness
+// must find in-tree) are written under proj below.
 
-// the deterministic content fingerprint of the config roots + THE RENDERER ITSELF. ONE definition —
-// `hp_config_hash` in the shell mirror (harness.sh) — which the dispatch.sh gate ALSO calls, so the gate and
-// this renderer can never disagree on "changed". It folds in hp_renderer_version (the toolchain-side content
-// hash), so a TOOLCHAIN update moves the key and the next gate self-heals the rendered artifacts — closing
-// the "toolchain updated but nothing re-materialized" hole ([[harness-delivery]]).
+// the deterministic content fingerprint of the config roots + THE TOOLCHAIN ITSELF (`hp_config_hash` in the
+// shell mirror, harness.sh). Stamped as a freshness record after every materialize; it folds in
+// hp_toolchain_version (the toolchain-side content hash), so a stale stamp is diagnosable after a toolchain
+// update ([[harness-delivery]]).
 export function contentHash(proj: string): string {
   try {
     const harnessSh = join(PKG, 'hooks', 'harness.sh')
@@ -51,43 +55,23 @@ export function contentHash(proj: string): string {
   } catch { return '' }
 }
 
-// @@@ render policy ([[render-policy]]) - ONE share axis, voted only for the machine-independent RENDERS.
-// `.spec` + `spexcode.json` are ALWAYS tracked (git is the database — no knob can untrack them); machine
-// facts (shims, spexcode.local.json) are ALWAYS ignored; run residue (.worktrees/) is always ignored. The
-// vote decides where the renders (contract blocks, skills, agents) sit — and, recursively, where their
-// ignore rules live: `committed` drops the render entries from the ignore block (the renders are ordinary
-// committed files), `ignored` (default) keeps the block in the TRACKED .gitignore, `hidden` moves the whole
-// block to the per-clone .git/info/exclude and covers a HOST-TRACKED contract file with the clean/smudge
-// content filter ([[content-filter]]) instead of the retired skip-worktree bit.
-export type RenderPolicy = 'committed' | 'ignored' | 'hidden'
-export function resolveRenderPolicy(cfg: { render?: string; private?: boolean }, proj?: string): RenderPolicy {
-  const r = cfg.render?.trim()
-  if (r) {
-    if (r !== 'committed' && r !== 'ignored' && r !== 'hidden') {
-      const err = new Error(`invalid render policy '${r}' — the render axis has three words: committed | ignored | hidden (see \`spex guide footprint\`)`)
-      err.name = 'ConfigError'
-      throw err
-    }
-    return r
-  }
-  if (cfg.private) {
-    // LEGACY private:true — the retired untrack-private mode. Its render half maps to 'hidden'; its
-    // data-untrack half is GONE (the spec sources are always tracked now). Loud, non-fatal: the deployment
-    // keeps working while the notice names the two migration moves.
-    let untracked: string[] = []
-    if (proj) untracked = ['.spec', 'spexcode.json'].filter((p) => existsSync(join(proj, p)) && !isTracked(proj, p))
-    console.error(
-      `spexcode: \`private: true\` is retired — reading it as \`"render": "hidden"\`.\n` +
-      `  → migrate spexcode.local.json: replace "private": true with "render": "hidden".` +
-      (untracked.length
-        ? `\n  → your spec sources are still untracked (${untracked.join(' + ')}); the untrack-private mode is gone, so track them once:\n` +
-          `      git add ${untracked.join(' ')}   (then commit on your branch)\n` +
-          `    WARNING: tracking is not retroactive secrecy — history already pushed elsewhere cannot be recalled.`
-        : ''),
-    )
-    return 'hidden'
-  }
-  return 'ignored'
+// @@@ 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
+// 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.
+export function retiredAxisNotice(cfg: { render?: string; private?: boolean }): void {
+  if (!cfg.render?.trim() && !cfg.private) return
+  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` +
+    `  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\`).`,
+  )
 }
 
 function gitCommonDirOf(proj: string): string {
@@ -100,38 +84,28 @@ function isTracked(proj: string, file: string): boolean {
   try { git(['-C', proj, 'ls-files', '--error-unmatch', file]); return true } catch { return false }
 }
 
-// @@@ adoption vote hint ([[render-policy]] story 4 + 21) - the one-time decision guidance for the "mystery M"
-// moment: under the DEFAULT policy a host-TRACKED contract file (a team's own CLAUDE.md/AGENTS.md) carries the
-// generated block and shows honestly dirty in status — deliberate, but a first-minute adopter just sees an
-// unexplained modification. So the HUMAN surfaces (spex init + the manual `spex materialize` verb — never the
-// silent gate/bootstrap renders) print this guidance exactly while the vote is still open: only when (a) no
-// explicit `render` is set (the default `ignored` is in effect by omission, not by choice — an explicit vote,
-// any word, retires the hint) and (b) a SELECTED harness's contract file is actually host-tracked. Mechanism,
-// not interaction: plain stdout naming the three words, their consequences, and where the vote lives — init is
-// routinely run by agents, so there is no TUI prompt to hang on.
-export function renderVoteHint(proj = process.cwd()): string | null {
-  const cfg = readConfig(mainCheckout(proj))
-  if (cfg.render?.trim() || cfg.private) return null            // an explicit vote (or the legacy mapping) — decided
-  const { selected } = partitionHarnesses(resolveHarnessTargets(cfg.harnesses))
-  const tracked = selected.flatMap((h) => h.contractFiles(proj)).filter((f) => isTracked(proj, f))
-  if (!tracked.length) return null
-  const names = tracked.map((f) => relative(proj, f)).join(' + ')
-  const [be, carry] = tracked.length > 1 ? ['are', 'carry'] : ['is', 'carries']
-  return [
-    `note: ${names} ${be} tracked by this repo and now ${carry} the generated <!-- spexcode --> block — the`,
-    `modification you see in git status. That dirtiness is HONEST under the current default (render: ignored),`,
-    `kept visible on purpose until you vote where the generated renders should live:`,
-    `  committed   renders become ordinary committed files — teammates/CI get the contract natively`,
-    `  ignored     (current default) renders stay generated+gitignored; a tracked contract file stays dirty`,
-    `  hidden      zero repo footprint — ignore rules live in .git/info/exclude and the tracked file is`,
-    `              covered by the clean/smudge filter (index stays pristine, status clean)`,
-    `Vote once and this note retires: "render": "committed" | "ignored" in spexcode.json (a project fact) or`,
-    `"render": "hidden" in spexcode.local.json (a host fact) — or adopt in one step: spex init --render <word>.`,
-    `Full model: spex guide footprint.`,
-  ].join('\n')
+// @@@ 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
+// user began writing their own prose into it) → neither hidden nor tracked-for-them: the exclude entry is
+// withheld (hiding user content would make their prose invisible to git — data-loss shaped) and the clean
+// filter is pre-armed so their eventual, entirely-their-own `git add` strips our block automatically.
+const SENTINEL_RE = /\n*<!-- spexcode:start -->[\s\S]*?<!-- spexcode:end -->\n*/
+export function stripSpexcodeBlock(text: string): string {
+  const m = SENTINEL_RE.exec(text)
+  if (!m) return text
+  // mirror removeManagedBlock exactly: our block + its surrounding blanks collapse to one '\n', and only a
+  // block sitting at the TOP of the file drops the leading newline (a host file beginning with its own
+  // blank lines keeps them — clean(smudge(x)) == x).
+  const replaced = text.replace(SENTINEL_RE, '\n')
+  return m.index === 0 ? replaced.replace(/^\n+/, '') : replaced
+}
+function hostContentOf(file: string): string {
+  if (!existsSync(file)) return ''
+  return stripSpexcodeBlock(readFileSync(file, 'utf8'))
 }
 // clear a legacy skip-worktree bit (the retired private-overlay mechanism; erase-only now — nothing asserts
-// it). Best-effort: an index race or a non-repo must not fail the render.
+// it). Best-effort: an index race or a non-repo must not fail the materialize.
 function clearSkipWorktree(proj: string, file: string): void {
   if (!isTracked(proj, file)) return
   try { git(['-C', proj, 'update-index', '--no-skip-worktree', file]) } catch { /* best-effort */ }
@@ -139,7 +113,7 @@ function clearSkipWorktree(proj: string, file: string): void {
 
 // the identity stamp on every generated skill/agent file — what lets the erase phase forget a product whose
 // NODE was renamed or deleted (the name-scoped sweep can only reconstruct paths the LIVE config still names).
-const GENERATED_MARK = '<!-- spexcode:generated -->'
+export const GENERATED_MARK = '<!-- spexcode:generated -->'
 function sweepGeneratedSkills(dir: string | null): void {
   if (!dir || !existsSync(dir)) return
   for (const e of readdirSync(dir, { withFileTypes: true })) {
@@ -159,11 +133,11 @@ function sweepGeneratedAgents(dir: string | null): void {
 
 // @@@ dematerialize - materialize(∅): the ERASE phase, also the whole of a backout ([[spex-uninstall]] adds
 // only the global store + plugin sweep + optional git hooks on top). Every removal is gated on an identity
-// stamp, so it deletes ONLY what a render wrote — never the user's prose, settings, or any .spec data. Order
+// stamp, so it deletes ONLY what a materialize wrote — never the user's prose, settings, or any .spec data. Order
 // matters once: the managed blocks leave the WORKING contract files before the content filter's config goes
 // (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 rendered since, including products of renamed/deleted nodes.
+// covers everything materialized since, including products of renamed/deleted nodes.
 export function dematerialize(proj = process.cwd(), arts: HarnessArtifacts = { skills: [], agents: [] }): void {
   for (const h of HARNESSES) {
     // h.clean = the adapter's surgical inverse: contract block (sentinels, deleteIfEmpty), the dispatch.sh-
@@ -192,9 +166,9 @@ export function dematerialize(proj = process.cwd(), arts: HarnessArtifacts = { s
   }
 }
 
-// the whole pay-per-change render. proj defaults to cwd. Returns the new content-hash it stamped.
+// the whole pay-per-change materialize. proj defaults to cwd. Returns the new content-hash it stamped.
 export function materialize(proj = process.cwd()): string {
-  const rt = runtimeRoot(proj)                                            // global per-project store, not the worktree
+  const rt = treeSlotDir(proj)                                            // this tree's slot in the global store, not the worktree
   mkdirSync(rt, { recursive: true })
   // (1) hook manifest (persistent — the dispatcher reads it; regenerated only here, on change).
   writeFileSync(join(rt, 'hooks-manifest'), compileManifest())
@@ -209,7 +183,7 @@ export function materialize(proj = process.cwd()): string {
   // native harness). resolveHarnessTargets FAILS LOUD on an illegal set (plugin+native, plugin w/o folder).
   const cfg = readConfig(mainCheckout(proj))
   const targets = resolveHarnessTargets(cfg.harnesses)
-  const policy = resolveRenderPolicy(cfg, proj)                           // [[render-policy]] — committed | ignored | hidden
+  retiredAxisNotice(cfg)                                                  // [[residence]] — the vote axis is retired
   const { selected, plugins } = partitionHarnesses(targets)
   const skillNodes = loadSkillConfig()
   const agentNodes = loadAgentConfig()
@@ -224,25 +198,25 @@ export function materialize(proj = process.cwd()): string {
   // ---- ASSERT: rewrite each landing point per the CURRENT policy.
   // a skill node → the agentskills.io SKILL.md primitive: `name`+`description` frontmatter (the load-trigger)
   // over the body instructions, closed by the GENERATED_MARK identity stamp (what the erase phase keys on).
-  // One pure render shared by every harness — divergence is only its skillDir.
-  const renderSkill = (sk: { name: string; desc: string; body: string }) =>
+  // One pure artifact builder shared by every harness — divergence is only its skillDir.
+  const skillArtifact = (sk: { name: string; desc: string; body: string }) =>
     `---\nname: ${sk.name}\ndescription: ${JSON.stringify(sk.desc)}\n---\n\n${sk.body}\n\n${GENERATED_MARK}\n`
   // an agent node → a coding-agent sub-agent definition (the same primitive .claude/agents/*.md ships): the
   // node's `desc` is the on-demand load-trigger, its `tools` the harness tool allowlist, its body the agent's
   // system prompt. Same stamp, same reason.
-  const renderAgent = (ag: { name: string; desc: string; tools: string[]; body: string }) =>
+  const agentArtifact = (ag: { name: string; desc: string; tools: string[]; body: string }) =>
     `---\nname: ${ag.name}\ndescription: ${ag.desc}\ntools: ${ag.tools.join(', ')}\n---\n\n${ag.body}\n\n${GENERATED_MARK}\n`
   // a command node → a host `/`-menu command file: plugin-only (the native path serves command presets via
   // the dashboard /api/slash-commands instead).
-  const renderCommand = (cm: { desc: string; body: string }) =>
+  const commandArtifact = (cm: { desc: string; body: string }) =>
     (cm.desc ? `---\ndescription: ${JSON.stringify(cm.desc)}\n---\n\n` : '') + `${cm.body}\n`
-  // two ignore classes, split because only `committed` treats them differently: RENDERS are machine-
-  // independent products the team may choose to commit; MACHINE paths (shims bake this install's abs path,
-  // bundles too) are never committable under any policy.
-  const renderPaths: string[] = []
+  // materialized artifacts and machine facts both land in the same per-clone exclude; contract files are kept separate
+  // because their residence is the live three-state kind detection below, not a static entry.
+  const artifactPaths: string[] = []
   const machinePaths: string[] = []
+  const contractPaths: string[] = []
   for (const h of selected) {
-    if (contract) for (const f of h.contractFiles(proj)) { writeManagedBlock(f, contract); renderPaths.push(f) }
+    if (contract) for (const f of h.contractFiles(proj)) { writeManagedBlock(f, contract); contractPaths.push(f) }
     const shimFile = h.shimFile(proj)
     mkdirSync(dirname(shimFile), { recursive: true })
     const shim = h.shim(DISPATCH, SPEX)
@@ -261,8 +235,8 @@ export function materialize(proj = process.cwd()): string {
       const dir = h.skillDir(proj); if (!dir) continue
       const f = join(dir, sk.name, 'SKILL.md')
       mkdirSync(dirname(f), { recursive: true })
-      writeFileSync(f, renderSkill(sk))
-      renderPaths.push(f)
+      writeFileSync(f, skillArtifact(sk))
+      artifactPaths.push(f)
     }
   }
   for (const ag of agentNodes) {
@@ -270,37 +244,42 @@ export function materialize(proj = process.cwd()): string {
       const dir = h.agentDir(proj); if (!dir) continue
       const f = join(dir, `${ag.name}.md`)
       mkdirSync(dirname(f), { recursive: true })
-      writeFileSync(f, renderAgent(ag))
-      renderPaths.push(f)
+      writeFileSync(f, agentArtifact(ag))
+      artifactPaths.push(f)
     }
   }
-  // (8) the PLUGIN target ([[plugin-harness]]): render the whole system into one self-contained Claude-plugin
+  // (8) the PLUGIN target ([[plugin-harness]]): materialize the whole system into one self-contained Claude-plugin
   //     bundle per selected folder. A plugin is EXCLUSIVE (`selected` is empty then). Pruning a DESELECTED
   //     folder needs the PREVIOUS folder set, which the live config no longer names — the one landing point
   //     the identity-stamped erase cannot enumerate (a folder is an arbitrary path) — so a tiny ledger in the
   //     global store records the folders emitted last run; any prev folder absent from the current set is
   //     clean()ed, then the current folders are emitted and the ledger rewritten.
   const ledger = join(rt, 'plugin-folders')
-  const prevFolders = existsSync(ledger) ? readFileSync(ledger, 'utf8').split('\n').map((l) => l.trim()).filter(Boolean) : []
+  // migration: a tree last materialized pre-slot left its ledger as the project-global file — read it once as
+  // the prev set so a deselected folder is still pruned; every write lands in the slot from here on.
+  const legacyLedger = join(runtimeRoot(proj), 'plugin-folders')
+  const ledgerSrc = existsSync(ledger) ? ledger : legacyLedger
+  const prevFolders = existsSync(ledgerSrc) ? readFileSync(ledgerSrc, 'utf8').split('\n').map((l) => l.trim()).filter(Boolean) : []
   const curFolders = plugins.map((p) => p.folder)
   for (const f of prevFolders) if (!curFolders.includes(f)) cleanPlugin(proj, f)
   if (plugins.length) {
-    const render = {
+    const bundle = {
       contract,
-      skills: skillNodes.map((s) => ({ name: s.name, content: renderSkill(s) })),
-      agents: agentNodes.map((a) => ({ name: a.name, content: renderAgent(a) })),
-      commands: commandNodes.map((c) => ({ name: c.name, content: renderCommand(c) })),
+      skills: skillNodes.map((s) => ({ name: s.name, content: skillArtifact(s) })),
+      agents: agentNodes.map((a) => ({ name: a.name, content: agentArtifact(a) })),
+      commands: commandNodes.map((c) => ({ name: c.name, content: commandArtifact(c) })),
       spex: SPEX,
       version: pluginVersion(),
     }
-    for (const p of plugins) emitPlugin(proj, p.folder, render)
+    for (const p of plugins) emitPlugin(proj, p.folder, bundle)
   }
   writeFileSync(ledger, curFolders.join('\n'))
-  // (9) the ignore rules — themselves an artifact whose HOME the same axis decides ([[render-policy]]):
-  //     committed/ignored → a managed `#` block in the TRACKED .gitignore (the team sees the rule);
-  //     hidden → the identical block in the per-clone .git/info/exclude (zero repo footprint).
-  // Entries must be CHECKOUT-INVARIANT: `.gitignore` is ONE tracked file shared by the main checkout and
-  // every worktree, so each entry is anchored to the checkout it LIVES under — proj-relative when inside
+  // (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.
   const mc = mainCheckout(proj)
@@ -318,23 +297,20 @@ export function materialize(proj = process.cwd()): string {
     ...[...machinePaths, ...bundlePaths].map(anchor).filter((p): p is string => p !== null),
     'spexcode.local.json', '.worktrees/', '.session',
   ]
-  const renderEntries = renderPaths.map(anchor).filter((p): p is string => p !== null)
-  const entries = (list: string[]) => [...new Set(list)].sort().join('\n')
-  if (policy === 'hidden') {
-    writeManagedBlock(infoExcludePath(proj), entries([...machineEntries, ...renderEntries]), ['# ', ''])
-    // a HOST-TRACKED contract file cannot be ignored — cover it with the clean/smudge content filter
-    // ([[content-filter]]) so the block lives in the working tree while the index keeps the pristine prose.
-    // Untracked contract files are wholly ours: generate + exclude suffices, no filter (weakest tool).
-    const trackedContracts = selected
-      .flatMap((h) => h.contractFiles(proj))
-      .filter((f) => contract && isTracked(proj, f))
-    if (trackedContracts.length) plantContractFilter(proj, trackedContracts, contract)
-  } else {
-    // committed: the renders become ordinary committed files — ONLY their entries leave the block.
-    const list = policy === 'committed' ? machineEntries : [...machineEntries, ...renderEntries]
-    if (list.length) writeManagedBlock(join(proj, '.gitignore'), entries(list), ['# ', ''])
+  // 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 filterContracts: string[] = []
+  const oursContracts: string[] = []
+  for (const f of contractPaths) {
+    if (isTracked(proj, f) || hostContentOf(f).trim()) filterContracts.push(f)
+    else oursContracts.push(f)
   }
-  // (5) stamp the content-hash marker LAST (so a crash mid-render leaves it stale → re-renders next gate).
+  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 h = contentHash(proj)
   writeFileSync(join(rt, 'content-hash'), h)
   return h

package/spec-cli/src/mentions.ts

@@ -6,9 +6,11 @@
 // separate, and sessions.ts is imported LAZILY so a mention-free post pays nothing.
 
 // ── parse (pure) ──────────────────────────────────────────────────────────────────────────────────────
-// `@<token>` at a word boundary is an actor; `[[<id>]]` is a topic. Tokens are [A-Za-z0-9_-]; a session id,
-// a short label/prefix, or the literal `new`. Both forms are deduped in first-seen order.
-const ACTOR_RE = /(?:^|\s)@([A-Za-z0-9_-]+)/g
+// `@<token>` at a word boundary is an actor; `[[<id>]]` is a topic. Token chars are any unicode
+// letter/number plus [_-] (a CJK session handle or node id is first-class — same charset the launch-side
+// MENTION and the dashboard's MENTION_RE use); a session id, a short label/prefix, or the literal `new`.
+// Both forms are deduped in first-seen order.
+const ACTOR_RE = /(?:^|\s)@([\p{L}\p{N}_-]+)/gu
 const NODE_RE = /\[\[([^\]\s]+)\]\]/g
 
 const uniq = (xs: string[]): string[] => [...new Set(xs)]

package/spec-cli/src/plugin-harness.ts

@@ -2,7 +2,7 @@ import { writeFileSync, mkdirSync, readFileSync, existsSync, rmSync, copyFileSyn
 import { join, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
-// @@@ plugin-harness - the PLUGIN BUNDLE emitter: render the whole SpexCode system into ONE self-contained
+// @@@ plugin-harness - the PLUGIN BUNDLE emitter: materialize the whole SpexCode system into ONE self-contained
 // Claude-plugin bundle dropped into the host-agent-scanned folder [[harness-select]] resolved (e.g. `.zcode` /
 // `.claude` → <folder>/plugins/spexcode/). It is the plugin-target counterpart of the native per-harness
 // write [[harness-adapter]] does — chosen INSTEAD of the natives (plugin exclusivity), so [[harness-delivery]]'s
@@ -29,11 +29,12 @@ const PLUGIN_ROOT = '${CLAUDE_PLUGIN_ROOT}'
 // never invokes the extras, so binding all is harmless and one emit serves every host.
 const PLUGIN_EVENTS = ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'Stop', 'StopFailure', 'Notification'] as const
 
-// the gathered surface artifacts this render writes into the bundle. contract = the assembled guide+system
+// the gathered surface artifacts this materialize writes into the bundle. contract = the assembled guide+system
 // block (the SAME string the native path folds into CLAUDE.md, here delivered as additionalContext); skills/
-// agents/commands are the already-rendered file CONTENTS (reusing materialize's renderSkill/renderAgent), keyed
+// agents/commands are the already-materialized file CONTENTS (reusing materialize's skillArtifact/agentArtifact),
+// keyed
 // by node name; spex is the baked tsx+cli invocation the dispatcher gate calls; version stamps plugin.json.
-export type PluginRender = {
+export type PluginBundle = {
   contract: string
   skills: { name: string; content: string }[]
   agents: { name: string; content: string }[]
@@ -63,7 +64,7 @@ function pluginManifest(version: string): string {
 }
 
 // hooks.json in the Claude/z-code-compatible shape { "hooks": { "<Event>": [{ "hooks": [command…] }] } }. Every
-// event → the SHARED dispatch.sh (`plugin` baked as its harness id, SPEX inherited for the gate); SessionStart
+// event → the SHARED dispatch.sh (`plugin` baked as its harness id, SPEX inherited by handlers); SessionStart
 // ALSO runs inject-contract.sh first, so the contract additionalContext lands alongside the normal dispatch.
 function pluginHooksJson(spex: string): string {
   const dispatch = (e: string) => `SPEX='${spex}' bash "${PLUGIN_ROOT}/hooks/dispatch.sh" plugin ${e}`
@@ -78,7 +79,7 @@ function pluginHooksJson(spex: string): string {
   return JSON.stringify({ hooks }, null, 2)
 }
 
-// the SessionStart hook OUTPUT carrying the contract as additionalContext. JSON-encoded HERE, at render time,
+// the SessionStart hook OUTPUT carrying the contract as additionalContext. JSON-encoded HERE, at materialize time,
 // so the runtime hook is a trivial `cat` — never a fragile shell escaping of arbitrary contract prose.
 function contractContextJson(contract: string): string {
   return JSON.stringify({ hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: contract } }, null, 2)
@@ -89,14 +90,14 @@ function contractContextJson(contract: string): string {
 const INJECT_SH = `#!/usr/bin/env bash
 # Emit the SpexCode contract as SessionStart additionalContext — the harness-neutral contract injection (the
 # superpowers pattern; Claude/z-code normalize hookSpecificOutput.additionalContext) that replaces a plugin
-# host's missing --append-system-prompt. The JSON was rendered at materialize time, so this is a trivial cat.
+# host's missing --append-system-prompt. The JSON was written at materialize time, so this is a trivial cat.
 here="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
 [ -f "$here/contract-context.json" ] && cat "$here/contract-context.json"
 exit 0
 `
 
 // emit (or idempotently re-emit) the whole bundle into <folder>/plugins/spexcode.
-export function emitPlugin(proj: string, folder: string, r: PluginRender): void {
+export function emitPlugin(proj: string, folder: string, r: PluginBundle): void {
   const bundle = pluginBundleDir(proj, folder)
   const meta = join(bundle, '.claude-plugin')
   const hooksDir = join(bundle, 'hooks')
@@ -110,7 +111,7 @@ export function emitPlugin(proj: string, folder: string, r: PluginRender): void
   writeFileSync(join(hooksDir, 'inject-contract.sh'), INJECT_SH)
   writeFileSync(join(hooksDir, 'contract-context.json'), contractContextJson(r.contract))
   writeFileSync(join(hooksDir, 'hooks.json'), pluginHooksJson(r.spex))
-  // skills / agents / commands — the Claude-plugin layout, the SAME rendered contents as the native dirs.
+  // skills / agents / commands — the Claude-plugin layout, the SAME materialized contents as the native dirs.
   for (const s of r.skills) writeBundleFile(join(bundle, 'skills', s.name, 'SKILL.md'), s.content)
   for (const a of r.agents) writeBundleFile(join(bundle, 'agents', `${a.name}.md`), a.content)
   for (const c of r.commands) writeBundleFile(join(bundle, 'commands', `${c.name}.md`), c.content)

package/spec-cli/src/sessions.ts

@@ -9,7 +9,7 @@ import { git, gitA, gitTry, repoRoot, mergeBaseDiff, mergeConflicts, type Review
 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.
@@ -817,14 +817,17 @@ export const slugify = (s: string | null) =>
 // 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
 // @@@ 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, ' ')
+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(' ')
@@ -1074,8 +1077,9 @@ 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]];
+  // 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
@@ -1097,7 +1101,7 @@ 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
@@ -1121,9 +1125,9 @@ 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,
+// @@@ 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
@@ -1134,7 +1138,7 @@ export function bootstrapMaterialize(rec: SessRec, doMaterialize: (proj: string)
     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}`)
+    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}` })
   }
 }
@@ -1256,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
@@ -1446,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