spexcode 0.2.5 → 0.2.7

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.
@@ -334,10 +334,13 @@ async function procSnapshot(): Promise<ProcTable> {
 }
 // @@@ LiveSnap - the ONE liveness snapshot the whole session list shares. `windows` = our live tmux windows
 // (id → PaneProbe) + one whole-box process table; `sockets` = the ids whose rendezvous socket has a LIVE
-// LISTENER (connect-probed once here, not the file-exists lie — [[harness-adapter]]); `probeFailed` = the tmux
-// window probe itself FAILED (timed out under load), which is DISTINCT from "tmux up, no sessions" — the former
-// means death is UNPROVEN so those rows read `unknown`, the latter is authoritative and reads `offline`.
-export type LiveSnap = { probeFailed: boolean; windows: Map<string, PaneProbe>; sockets: Set<string> }
+// LISTENER (connect-probed once here, not the file-exists lie — [[harness-adapter]]); `unproven` = the ids whose
+// LISTENER probe could not conclude (timeout under load / EAGAIN off a full-but-alive backlog — see
+// rendezvousListening's tri-state) — death UNPROVEN, so those rows read `unknown`, never `offline`;
+// `probeFailed` = the tmux window probe itself FAILED (timed out under load), which is DISTINCT from "tmux up,
+// no sessions" — the former means death is UNPROVEN so those rows read `unknown`, the latter is authoritative
+// and reads `offline`.
+export type LiveSnap = { probeFailed: boolean; windows: Map<string, PaneProbe>; sockets: Set<string>; unproven: Set<string> }
 async function liveSnapshot(): Promise<LiveSnap> {
   const windows = new Map<string, PaneProbe>()
   let out: string
@@ -346,7 +349,7 @@ async function liveSnapshot(): Promise<LiveSnap> {
   } catch (e) {
     // a TIMEOUT/kill is a probe FAILURE (we can't tell who's alive → unknown, never a false graveyard). A clean
     // non-zero exit ("no server running" — genuinely zero sessions) is authoritative → the empty map = offline.
-    return { probeFailed: probeTimedOut(e), windows, sockets: new Set() }
+    return { probeFailed: probeTimedOut(e), windows, sockets: new Set(), unproven: new Set() }
   }
   const procs = await procSnapshot().catch(() => undefined)   // codex-only, auxiliary; its failure isn't a liveness failure
   for (const line of out.split('\n')) {
@@ -356,12 +359,19 @@ async function liveSnapshot(): Promise<LiveSnap> {
     windows.set(name, { panePid: Number.isFinite(pid) && pid > 0 ? pid : undefined, procs })
   }
   // LISTENER probe for every windowed session, once, in parallel (tooth: a live listener, not a lingering
-  // socket file). A codex session has no rvSock → instant ENOENT → not in the set, and codex ignores it anyway.
+  // socket file). A codex session has no rvSock → instant ENOENT → proven dead for the socket axis (codex
+  // ignores it anyway). The tri-state matters here: 'unproven' (timeout/EAGAIN — a wedged or thrashed but
+  // possibly-alive listener) lands in `unproven`, never silently in the not-live bucket, so liveness() can
+  // render it `unknown` instead of a false `offline` (issue #40's load-spike graveyard).
   const ids = [...windows.keys()]
   const listening = await Promise.all(ids.map((id) => rendezvousListening(id)))
   const sockets = new Set<string>()
-  ids.forEach((id, i) => { if (listening[i]) sockets.add(id) })
-  return { probeFailed: false, windows, sockets }
+  const unproven = new Set<string>()
+  ids.forEach((id, i) => {
+    if (listening[i] === 'live') sockets.add(id)
+    else if (listening[i] === 'unproven') unproven.add(id)
+  })
+  return { probeFailed: false, windows, sockets, unproven }
 }
 
 // @@@ paneTitles - every session pane's RAW tmux title, free from tmux. The worker launches one pane per
@@ -389,10 +399,11 @@ async function paneTitles(): Promise<Map<string, string>> {
 // dashboard waiting for its slow cold-path fallback. Sorted so it only moves on a real change.
 export async function sessionSignature(): Promise<string> {
   const [snap, titles] = await Promise.all([liveSnapshot(), paneTitles()])
-  // fold in probe-failure and the live-listener set so a socket dying (claude exit) OR the probe flipping to
-  // unknown pushes a board-changed immediately, not only on window churn.
+  // fold in probe-failure, the live-listener set AND the unproven set so a socket dying (claude exit), the
+  // probe flipping to unknown, or a listener wedging (unproven) pushes a board-changed immediately, not only
+  // on window churn.
   return (snap.probeFailed ? 'PROBEFAIL|' : '') + [...snap.windows.keys()].sort().join(',') + '#' +
-    [...snap.sockets].sort().join(',') + '|' + [...titles].sort().map(([k, v]) => `${k}=${v}`).join(',')
+    [...snap.sockets].sort().join(',') + '~' + [...snap.unproven].sort().join(',') + '|' + [...titles].sort().map(([k, v]) => `${k}=${v}`).join(',')
 }
 
 // @@@ paneActivity - the harness-aware live self-summary: the SINGLE place a raw pane title becomes (or does
@@ -463,6 +474,10 @@ export function liveness(rec: SessRec, snap: LiveSnap): Liveness {
   // online-signal hasn't appeared yet reads 'starting' for the boot window, only past it 'offline'.
   const h = harnessById(rec.harness || defaultHarness.id)
   if (h.liveness(rec, snap.windows.has(rec.session), runtimeRoot(), snap.windows.get(rec.session), snap.sockets.has(rec.session)) === 'online') return 'online'
+  // not provably online — but if this session's LISTENER probe couldn't conclude (timeout under load / EAGAIN
+  // off a full-but-alive backlog), death is UNPROVEN: `unknown`, never a false `offline` a supervisor would
+  // act on (issue #40 — a wedged-but-alive worker must not read as an actionable corpse).
+  if (snap.unproven.has(rec.session)) return 'unknown'
   const at = launchedAt.get(rec.session)
   return at && Date.now() - at < BOOT_GRACE_MS ? 'starting' : 'offline'
 }
@@ -817,14 +832,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 +1092,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 +1116,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 +1140,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 +1153,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 +1275,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 +1465,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
@@ -1638,8 +1662,12 @@ export type WatchOpts = { source: () => Promise<Session[]>; selectors?: string[]
 // "block for a worker, then exit" that is GUARANTEED to return. The deadline is checked EVERY poll, before
 // EVERY sleep (and even when a poll throws), so a target stuck in ANY non-actionable state
 // (`working`/`parked`/`idle`/`queued`/`starting`) can never hang the caller — it exits at the deadline.
-// `reached` = the target hit an actionable status; the rest are the loud exits.
-export type WatchOutcome = { reached: DisplayStatus } | { timedOut: true } | { gone: true } | { backendDown: string }
+// `reached` = the target hit an actionable status; the rest are the loud exits. `backendDown` is a verdict
+// about the TRANSPORT, never the session — `kind` keeps its two shapes distinct for the caller's outcome
+// surface: 'unreachable' (nothing listening, the whole timeout was spent retrying) vs 'http' (reachable but
+// broken, failed loud at once). The caller must surface these OUTSIDE the session-status vocabulary — a
+// supervisor must never be able to read a transport failure as a session state (issue #40).
+export type WatchOutcome = { reached: DisplayStatus } | { timedOut: true } | { gone: true } | { backendDown: string; kind: 'unreachable' | 'http' }
 export async function watchSessions(emit: (line: string) => void, opts: WatchOpts): Promise<WatchOutcome> {
   const { source, selectors = [], statuses, includeIdle = false, intervalMs = 5000, as, until } = opts
   const tag = as ? `[${as}] ` : ''
@@ -1693,7 +1721,7 @@ export async function watchSessions(emit: (line: string) => void, opts: WatchOpt
       //    is rebooting its hot-reloaded child behind the stable port on a sibling merge. This is TRANSIENT:
       //    record it, warn ONCE, and keep polling — the deadline (below) is the only hard wall, so a
       //    backgrounded `spex wait` survives the ~1s restart instead of dying on the interrupted fetch.
-      if (until && isBackendDown(e) && !isBackendUnreachable(e)) return { backendDown: (e as Error).message }
+      if (until && isBackendDown(e) && !isBackendUnreachable(e)) return { backendDown: (e as Error).message, kind: 'http' }
       if (isBackendDown(e)) {
         downMsg = (e as Error).message
         if (!warnedDown) { warnedDown = true; console.error(`${tag}[spex] watch: ${downMsg}; retrying every ${intervalMs / 1000}s…`) }
@@ -1703,7 +1731,7 @@ export async function watchSessions(emit: (line: string) => void, opts: WatchOpt
     // guarantees `spex wait` can never hang on a worker stuck outside WATCH_ACTIONABLE — nor spin forever on a
     // backend that never comes back. Hitting the deadline while still unreachable reports THAT (`backendDown`),
     // not a false "no actionable status" timeout, so the manager sees the honest cause.
-    if (until && Date.now() >= deadline) return downMsg ? { backendDown: downMsg } : { timedOut: true }
+    if (until && Date.now() >= deadline) return downMsg ? { backendDown: downMsg, kind: 'unreachable' } : { timedOut: true }
     await sleep(intervalMs)
   }
 }

package/spec-cli/src/specs.ts

@@ -102,7 +102,9 @@ function walk(dir: string, parent: string | null, acc: Raw[]) {
 // 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('_')
+  // 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++
@@ -357,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),
@@ -390,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/uninstall.ts

@@ -8,8 +8,8 @@ import { loadSkillConfig, loadAgentConfig } from './specs.js'
 import { dematerialize } from './materialize.js'
 
 // @@@ 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,
+// 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
@@ -100,11 +100,12 @@ export function uninstall(targetArg: string | undefined, opts: { hooks?: boolean
 
   // 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.
+  //    erase phase every materialize 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.
+  // 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)

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

@@ -2,14 +2,16 @@ import { appendFileSync, copyFileSync, existsSync, mkdirSync, readFileSync } fro
 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
+// @@@ worktree-sources ([[residence]]) - 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.
+//   - MATERIALIZED ARTIFACTS (contract blocks, shims, skills) are DERIVED — transported by re-materialize,
+//     not by link or copy:
+//     sessions.ts materializes into the worktree at creation, and the git-native anchors (pre-commit /
+//     post-checkout / post-merge — [[commit-surgery]]) re-materialize 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
@@ -31,7 +33,7 @@ export function seedWorktreeHostState(main: string, wt: string): void {
 // 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
+// by `git check-ignore` are written: idempotent across dispatches, and a repo whose materialize 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) {

package/spec-cli/templates/hooks/post-checkout

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# @@@ footprint refresh (post-checkout) ([[commit-surgery]]) - a branch checkout is one of the three git
+# transitions that can move the materialize's inputs: .spec/.config content changes across branches, and a
+# contract file's TRACKEDNESS can flip (switching to a branch that tracks CLAUDE.md checks out the pristine
+# index prose — the re-materialize here writes the block back into the working file, binds the clean/smudge
+# filter, and withdraws the exclude entry; the kind-transition heals itself). Git-native anchors only —
+# never a harness event. Quiet, best-effort: a failed refresh self-heals at the next anchor (pre-commit's
+# unconditional materialize is the correctness backstop).
+#
+# args: <prev-HEAD> <new-HEAD> <flag>; flag=1 is a branch checkout, flag=0 a file checkout (git checkout --
+# <path> restores files and moves nothing the materialize depends on — skip those).
+[ "${3:-0}" = "1" ] || exit 0
+main_root=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)")
+repo_root=$(git rev-parse --show-toplevel 2>/dev/null)
+if command -v spex >/dev/null 2>&1; then
+  spex internal refresh-footprint >/dev/null 2>&1 || true
+elif [ -x "$repo_root/node_modules/.bin/spex" ]; then
+  "$repo_root/node_modules/.bin/spex" internal refresh-footprint >/dev/null 2>&1 || true
+elif [ -x "$main_root/spec-cli/bin/spex.mjs" ]; then
+  "$main_root/spec-cli/bin/spex.mjs" internal refresh-footprint >/dev/null 2>&1 || true
+fi
+exit 0

package/spec-cli/templates/hooks/post-merge

@@ -9,19 +9,25 @@
 # the feature is OFF in spexcode.json), so this hook is a THIN resolver + caller: resolve `spex` the same
 # three ways the pre-commit hook does, pass the merged node, echo whatever it prints. No CLI resolvable → no
 # nudge (safe degradation, same as the lint shim's advisory mode).
+main_root=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)")
+repo_root=$(git rev-parse --show-toplevel 2>/dev/null)
+spex_run() {
+  if command -v spex >/dev/null 2>&1; then spex "$@"
+  elif [ -x "$repo_root/node_modules/.bin/spex" ]; then "$repo_root/node_modules/.bin/spex" "$@"
+  elif [ -x "$main_root/spec-cli/bin/spex.mjs" ]; then "$main_root/spec-cli/bin/spex.mjs" "$@"
+  else return 127; fi
+}
+
+# @@@ footprint refresh ([[commit-surgery]]) - a merge is one of the three git transitions that can move the
+# materialize's inputs (.spec/.config content, contract-file trackedness), so re-materialize here — git-native
+# anchors only, never a harness event. Quiet, best-effort: a failed refresh self-heals at the next anchor.
+spex_run internal refresh-footprint >/dev/null 2>&1 || true
+
 subj=$(git log -1 --format=%s 2>/dev/null)
 case "$subj" in
   "merge node/"*) ;;
   *) exit 0 ;;
 esac
 node=$(printf '%s' "$subj" | sed -n 's#^merge \(node/[^:]*\):.*#\1#p')
-main_root=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)")
-repo_root=$(git rev-parse --show-toplevel 2>/dev/null)
-if command -v spex >/dev/null 2>&1; then
-  spex issues nudge "$node"
-elif [ -x "$repo_root/node_modules/.bin/spex" ]; then
-  "$repo_root/node_modules/.bin/spex" issues nudge "$node"
-elif [ -x "$main_root/spec-cli/bin/spex.mjs" ]; then
-  "$main_root/spec-cli/bin/spex.mjs" issues nudge "$node"
-fi
+spex_run issues nudge "$node"
 exit 0

package/spec-cli/templates/hooks/pre-commit

@@ -64,6 +64,16 @@ if [ "$branch" = "$trunk" ] && [ ! -f "$git_dir/MERGE_HEAD" ] && [ -z "${SPEXCOD
   exit 1
 fi
 
+# @@@ footprint surgery ([[commit-surgery]]) - the history anchor: an UNCONDITIONAL materialize (masks fresh
+# at the one moment history is written) + staged-index repair — strip the spexcode sentinel block from any
+# staged blob (source = the staged blob, so `git add -p` partial staging survives), unstage HEAD-untracked
+# generated artifacts. REPAIRS AND PROCEEDS, never rejects; one note per repair on stderr. Runs INSIDE the
+# hook env on purpose: the surgery honors GIT_INDEX_FILE so a pathspec/`-a` commit's TEMPORARY index is the
+# one repaired. Advisory when spex is unresolvable or errors (CI lint enforces); never blocks the commit.
+if [ -n "$spex_kind" ]; then
+  spex_cli internal commit-surgery || echo "• SpexCode: footprint surgery skipped (error above) — a generated artifact may be staged; CI still enforces." >&2
+fi
+
 # @@@ spec-lint - the hook is just a thin shim over `spex lint`. It blocks on errors only (broken
 # spec↔code links); coverage/drift are warnings. Bypass with SPEXCODE_SKIP_LINT=1. It shims through the
 # shared spex_cli() resolved above (repoRoot() discovers the cwd's toplevel via git.ts, which strips the

package/spec-cli/templates/spec/project/.config/distill/digest.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+// digest.mjs — locate a dead session's transcript on disk and print a compact markdown digest.
+// Usage: node digest.mjs <session-id | path/to/transcript.jsonl>
+// Read-only: never resumes, prompts, or mutates the session. Exit 1 (loud) when no transcript is found.
+//
+// Harness coverage: claude (projects/<enc-cwd>/<id>.jsonl) and codex (sessions/YYYY/MM/DD/rollout-*<id>.jsonl).
+// The digest keeps the high-signal stream — user prompts in full, assistant text, tool calls as one-liners,
+// error results — and drops the bulk (tool outputs, attachments, sidechains, reasoning).
+
+import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+
+const arg = process.argv[2]
+if (!arg) { console.error('usage: digest.mjs <session-id | transcript.jsonl>'); process.exit(1) }
+
+const TRUNC = (s, n) => { s = String(s ?? '').trim(); return s.length > n ? s.slice(0, n) + ` …[+${s.length - n} chars]` : s }
+
+// ---- locate -------------------------------------------------------------
+const claudeRoots = () => {
+  const roots = []
+  if (process.env.CLAUDE_CONFIG_DIR) roots.push(process.env.CLAUDE_CONFIG_DIR)
+  for (const e of readdirSync(homedir(), { withFileTypes: true }))
+    if (e.isDirectory() && e.name.startsWith('.claude')) roots.push(join(homedir(), e.name))
+  return roots
+}
+const findClaude = (id) => {
+  for (const root of claudeRoots()) {
+    const proj = join(root, 'projects')
+    if (!existsSync(proj)) continue
+    for (const d of readdirSync(proj)) {
+      const f = join(proj, d, `${id}.jsonl`)
+      if (existsSync(f)) return f
+    }
+  }
+  return null
+}
+const findCodex = (id) => {
+  const root = join(process.env.CODEX_HOME || join(homedir(), '.codex'), 'sessions')
+  if (!existsSync(root)) return null
+  const stack = [root]
+  while (stack.length) {
+    const dir = stack.pop()
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      if (e.isDirectory()) stack.push(join(dir, e.name))
+      else if (e.name.startsWith('rollout-') && e.name.includes(id) && e.name.endsWith('.jsonl')) return join(dir, e.name)
+    }
+  }
+  return null
+}
+const file = arg.endsWith('.jsonl') ? arg : (findClaude(arg) || findCodex(arg))
+if (!file || !existsSync(file)) { console.error(`no transcript found for "${arg}" (searched claude projects/ and codex sessions/)`); process.exit(1) }
+
+// ---- parse --------------------------------------------------------------
+const lines = readFileSync(file, 'utf8').split('\n').filter(Boolean)
+const out = []
+const meta = { cwd: null, branch: null, first: null, last: null }
+const filesTouched = new Set()
+let errors = 0
+const seen = new Set()
+
+// harness-injected preamble arrives typed as "user" (system-reminders, AGENTS.md folds, codex permission/skill
+// blocks) — it is noise to a digest, and real human prompts essentially never open with these markers.
+const isInjected = (t) => /^(<|# AGENTS\.md instructions|Caveat: The messages below)/.test(t.trimStart())
+const userBlock = (t) => { t = String(t ?? '').trim(); return t && !isInjected(t) ? `\n## user\n${t}` : null }
+
+const toolLine = (name, input = {}) => {
+  if ((name === 'Edit' || name === 'Write' || name === 'NotebookEdit') && input.file_path) filesTouched.add(input.file_path)
+  const hint = input.description || input.file_path || input.command || input.prompt || input.query || input.pattern || ''
+  return `→ ${name}${hint ? ` · ${TRUNC(hint, 160)}` : ''}`
+}
+
+for (const raw of lines) {
+  let l; try { l = JSON.parse(raw) } catch { continue }
+  const ts = l.timestamp
+  if (ts) { meta.first ||= ts; meta.last = ts }
+  if (l.cwd) meta.cwd ||= l.cwd
+  if (l.gitBranch && l.gitBranch !== 'HEAD') meta.branch ||= l.gitBranch
+
+  // claude shape: {type: user|assistant, message:{content}, isSidechain}
+  if (l.type === 'user' || l.type === 'assistant') {
+    if (l.isSidechain) continue // subagent noise
+    const c = l.message?.content
+    if (typeof c === 'string') { const u = userBlock(c); if (u) out.push(u); continue }
+    for (const item of c || []) {
+      if (item.type === 'text' && item.text?.trim()) {
+        if (l.type === 'user') { const u = userBlock(item.text); if (u) out.push(u) }
+        else out.push(TRUNC(item.text, 2000))
+      }
+      else if (item.type === 'tool_use') out.push(toolLine(item.name, item.input))
+      else if (item.type === 'tool_result' && item.is_error) {
+        errors++
+        const t = Array.isArray(item.content) ? item.content.map((x) => x.text || '').join(' ') : item.content
+        out.push(`⚠ tool error: ${TRUNC(t, 400)}`)
+      }
+    }
+    continue
+  }
+
+  // codex shape: {type: session_meta|response_item|event_msg, payload:{...}}. The same message is logged
+  // BOTH as a response_item and an event_msg (version-dependent which exists) — dedupe on the text.
+  const p = l.payload
+  if (!p) continue
+  if (l.type === 'session_meta') { meta.cwd ||= p.cwd; continue }
+  const pushMsg = (role, text) => {
+    text = String(text ?? '').trim()
+    if (!text || seen.has(text)) return
+    seen.add(text)
+    if (role === 'user') { const u = userBlock(text); if (u) out.push(u) }
+    else if (role === 'assistant') out.push(TRUNC(text, 2000)) // developer/system roles are harness plumbing
+  }
+  if (l.type === 'event_msg' && (p.type === 'user_message' || p.type === 'agent_message'))
+    pushMsg(p.type === 'user_message' ? 'user' : 'assistant', p.message)
+  else if (l.type === 'response_item') {
+    if (p.type === 'message') {
+      pushMsg(p.role, (p.content || []).map((x) => x.text || '').join('\n'))
+    } else if (p.type === 'function_call') {
+      let input = {}; try { input = JSON.parse(p.arguments || '{}') } catch {}
+      out.push(toolLine(p.name, input))
+    } else if (p.type === 'function_call_output' && /error/i.test(String(p.output).slice(0, 200))) {
+      errors++
+      out.push(`⚠ tool error: ${TRUNC(p.output, 400)}`)
+    }
+  }
+}
+
+// ---- emit ---------------------------------------------------------------
+const kb = Math.round(statSync(file).size / 1024)
+console.log(`# transcript digest — ${arg}`)
+console.log(`- file: ${file} (${kb} KB, ${lines.length} lines)`)
+if (meta.first) console.log(`- span: ${meta.first} → ${meta.last}`)
+if (meta.cwd) console.log(`- cwd: ${meta.cwd}`)
+if (meta.branch) console.log(`- branch: ${meta.branch}`)
+console.log(out.join('\n'))
+console.log(`\n---\n- transcript: ${file}\n- tool errors seen: ${errors}`)
+if (filesTouched.size) console.log(`- files edited:\n${[...filesTouched].map((f) => `  - ${f}`).join('\n')}`)

package/spec-cli/templates/spec/project/.config/distill/spec.md

@@ -0,0 +1,74 @@
+---
+title: distill
+surface: skill, command
+status: active
+hue: 210
+desc: Use when the human wants to inherit a past or dead session's knowledge and work — "distill session X / 继承那个 session 的经验 / 接手它的工作 / 把之前 session 的东西捞回来 / harvest, salvage a finished session". Given a session id, read its transcript from disk (NEVER resume or re-prompt it — its cache is cold and a re-prime is expensive), distill goal · decisions · traps · next steps into the current session, and if its worktree/branch never merged, carry the work over and retire the resources.
+---
+
+# distill
+
+Inherit a finished (or dead) session's **mind and desk** without waking it — mind = its transcript on disk,
+desk = its worktree/branch. The one iron rule: **never resume, reopen, send to, or otherwise re-prompt the
+old session** (cold cache: any turn pays a full re-prime). Everything below is read-only files and plain git.
+
+## 1 · resolve the session
+
+Input: a session id — SpexCode's, a bare harness id (claude / codex thread), or a transcript `.jsonl` path.
+
+- **SpexCode session** (first choice — the join is first-class): its record is
+  `~/.spexcode/projects/*/sessions/<id>/session.json` — glob for the id, prefix ok. Take `worktree_path`,
+  `branch`, `harness`, `harness_session_id`, `status`, `title`; the originating goal is
+  `spex session prompt <id>`. For a claude-harness session the transcript id IS the SpexCode session id;
+  for codex it is `harness_session_id`.
+- **Any other session**: treat the arg as the harness's own id. The transcript carries `cwd` (and, unless
+  the worktree was detached, a branch) — the digest header surfaces them; that is your join to its desk.
+
+## 2 · digest the transcript — mechanical first, model second
+
+`node .spec/<root>/.config/distill/digest.mjs <id-or-path>` locates the transcript (claude:
+`$CLAUDE_CONFIG_DIR` and every `~/.claude*` config dir → `projects/*/<id>.jsonl`; codex: `$CODEX_HOME` or
+`~/.codex` → `sessions/**/rollout-*<id>.jsonl`) and prints a compact digest: the human's prompts in full,
+the agent's own text, tool calls as one-liners, error results, and a footer with the files it edited and
+the raw transcript path. It exits loud when nothing is found — do not fall back to resuming the session.
+
+Read the digest yourself when small; big (>~100 KB) → a subagent returns only the distillation below, so
+the inheritance never floods your own context. Its ⚠ error lines and footer are step 3's trap material.
+
+## 3 · distill — forward-looking, not narrative
+
+Completed work is git's job to remember; do not re-narrate it — and never paste raw transcript. State in
+your reply, and work from, what the transcript knows that git does not:
+
+- **Goal & landing** — what it set out to do, and where it actually stopped (merged? proposal pending?
+  abandoned mid-flight?).
+- **Decisions & why** — the direction that was settled, including options weighed and rejected.
+- **Traps** — failures, dead ends, gotchas, and every correction the human made. These are the
+  highest-value lines in the whole transcript.
+- **Unfinished / next actions** — what it would have done next.
+- **Pointers** — files edited, spec nodes touched, and the raw transcript path itself, so later questions
+  drill into the source instead of inheriting everything up front.
+
+## 4 · salvage the desk
+
+The SpexCode record names the worktree/branch; otherwise the digest's `cwd` may be a linked worktree
+(`git -C <cwd> rev-parse --git-common-dir`). Salvage inside that repo — it need not be the one you sit in.
+Cross-check the digest's files-edited footer against that worktree: a manager-style session's edits often
+live OUTSIDE it (main-checkout config, other repos) — those need a by-hand look, not the recipe below.
+
+- **Already merged** (`git merge-base --is-ancestor <branch> <trunk>`) → nothing to salvage; note it and
+  go to cleanup. A tip that EQUALS the merge-base carried no commits — say "never committed", not "merged".
+- **Unmerged commits** → carry them onto your current branch: `git cherry-pick <base>..<branch>` (keeps
+  authorship and `Session:` trailers); fall back to applying `git diff <base> <branch>` when the history
+  is too messy to replay.
+- **Uncommitted changes** in the old worktree → `git -C <wt> status --porcelain`; apply its diff to your
+  tree and copy untracked files over. Commit the salvage in your own tree, naming the origin session in
+  the message.
+
+## 5 · clean up — only after the salvage LANDED
+
+Cleanup discards state — verify the salvaged commits are in your tree (or the branch genuinely merged) first.
+
+- SpexCode session: `spex session close <id>` retires the session and its worktree in one verb.
+- Bare worktree: `git worktree remove <wt>`, + `git branch -D <branch>` once confirmed carried or merged.
+- In doubt, keep the resources and say so — a kept worktree costs disk; a wrong cleanup costs the work.

package/spec-cli/templates/spec/project/.config/supervisor/spec.md

@@ -5,4 +5,4 @@ status: active
 hue: 280
 desc: Launch a supervisor agent that manages other agents from the main checkout to drive a goal to completion.
 ---
-You are a SpexCode supervisor — a **manager**, not a feature worker. Your work base is the main checkout (the repository root), NOT your own worktree: do all git via `git -C <root>`, everything else via the `spex` CLI, and never write feature code. **FIRST, read `<root>/CLAUDE.md` — specifically its "Supervising — the manager loop" section** — that is your complete playbook (dispatch → monitor → review → merge → close, and how to parallelize). Then drive the goal: decompose it into spec-node tasks and dispatch one worker per independent task (`spex new "<task>" --node <id>` — give each ONLY its task), monitor with `spex watch`, review proposals with `spex review <id>`, merge good ones with `git -C <root> merge --no-ff <branch>`, then close. Never let a worker self-merge; keep `spex lint` at 0 errors. To WAIT on a worker, POLL one-shot (`spex review <id>` or `spex ls` — both return immediately); never block on `spex watch`, which STREAMS forever and will freeze your turn. One footgun that bites a fresh supervisor: before `spex session close <id>`, confirm the merge landed (`git -C <root> log -1` shows HEAD at the new merge commit) — closing an unmerged branch discards the work. Report progress as you go and when the goal is complete. Your goal follows:
+You are a SpexCode supervisor — a **manager**, not a feature worker. Your work base is the main checkout (the repository root), NOT your own worktree: do all git via `git -C <root>`, everything else via the `spex` CLI, and never write feature code. **FIRST, read `<root>/CLAUDE.md` — specifically its "Supervising — the manager loop" section** — that is your complete playbook (dispatch → monitor → review → merge → close, and how to parallelize). Then drive the goal: decompose it into worker-sized tasks and dispatch one worker per independent task (`spex new "<task>"` — give each ONLY its task; a task about one specific node mentions it as `[[<id>]]`, which only sets the branch name and board attribution; the session's real node links come from what it edits), monitor with `spex watch`, review proposals with `spex review <id>`, merge good ones with `git -C <root> merge --no-ff <branch>`, then close. Never let a worker self-merge; keep `spex lint` at 0 errors. To WAIT on a worker, POLL one-shot (`spex review <id>` or `spex ls` — both return immediately); never block on `spex watch`, which STREAMS forever and will freeze your turn. One footgun that bites a fresh supervisor: before `spex session close <id>`, confirm the merge landed (`git -C <root> log -1` shows HEAD at the new merge commit) — closing an unmerged branch discards the work. Report progress as you go and when the goal is complete. Your goal follows: