spexcode 0.2.4 → 0.2.6

package/spec-cli/src/help.ts

@@ -72,11 +72,12 @@ session list. Identical to GET /api/board; needs the backend (spex serve) reacha
     see: 'spex tree (the same graph, human-readable) · spex ls (just the sessions, as a table) · spex search (find one node instead of dumping all)',
   },
   guide: {
-    line: 'guide [topic]         the manuals: setup workflow · spec/yatsu file formats · spexcode.json',
+    line: 'guide [topic]         the manuals: setup workflow · spec/yatsu file formats · spexcode.json · footprint',
     body: `Usage: spex guide            the human setup workflow (install once, adopt a repo, serve)
        spex guide spec       the spec.md file format + every lint rule
        spex guide yatsu      the yatsu.md scenario format + how loss is measured and filed
        spex guide config     every spexcode.json / spexcode.local.json field, and which file it belongs in
+       spex guide footprint  the footprint model: never-tracked artifacts, exclude + content filter, anchors
 
 guide is the SKILL layer — workflows and formats. Command usage lives here in help
 (\`spex help <cmd>\`); guide carries what the commands assume you know.`,
@@ -180,16 +181,21 @@ a node/<id> branch links its PR for free). Read-only — git/.spec stays the sin
   },
   // ── dispatch & manage sessions (manager loop) ─────────────────────────────
   new: {
-    line: 'new "<prompt>"        launch a worker session in its own node worktree  [--node <id>] [--launcher <name>]',
+    line: 'new "<prompt>"        launch a worker session in its own node worktree  [--prompt-file <path>|-] [--node <id>] [--launcher <name>]',
     body: `Usage: spex new "<task prompt>" [--node <id>] [--launcher <name>]
+       spex new --prompt-file <path>|- [--node <id>] [--launcher <name>]
 
 Creates a session: node branch + worktree + a launched agent carrying your prompt (= session new).
 Give it ONLY its task — the dev-flow contract reaches it through the materialized system prompt.
+--prompt-file <path> reads the prompt from a file (- = stdin), so a long multi-paragraph prompt never
+fights shell quoting; it is exclusive with the inline prompt (both given = error), and an unreadable
+or empty file refuses the launch.
 The launcher name selects both the agent harness and the command/auth profile (built-ins: claude, codex);
 omitting it requires sessions.defaultLauncher in spexcode.json or spexcode.local.json.
 Routes through the running backend (auth env + concurrency cap); prints the created session JSON.
-Then MONITOR it: background \`spex wait <id>\`, or \`spex watch\` for the whole stream.`,
-    see: 'spex wait / spex watch (monitor) · spex review (when it proposes) · ' + SEL_NOTE.split('\n')[0],
+Then MONITOR it: background \`spex wait <id>\`, or \`spex watch\` for the whole stream.
+Talk to it with \`spex send <id> "<msg>"\` — never raw tmux keystrokes.`,
+    see: 'spex wait / spex watch (monitor) · spex send (talk to it) · spex review (when it proposes) · ' + SEL_NOTE.split('\n')[0],
   },
   ls: {
     line: 'ls [SEL…]             living-sessions table  [--status a,b] [--json] [--api URL]',
@@ -312,7 +318,9 @@ ${ROUTING_NOTE}`,
 
 Scaffolds adoption in one shot: seeds a starter .spec tree (project root + .config plugins), plants
 spexcode.json, installs the git hooks, and materializes the harness artifacts (contract block +
-shims). Additive — never overwrites your files. --preset picks the .config plugin tier (cumulative).`,
+shims). Additive — never overwrites your files. --preset picks the .config plugin tier (cumulative).
+Footprint needs no vote: materialized artifacts are never tracked — hidden via the per-clone .git/info/exclude, with
+a tracked/mixed CLAUDE.md/AGENTS.md covered by the clean/smudge filter (see spex guide footprint).`,
     see: 'spex guide (the full setup workflow) · spex uninstall (the inverse) · spex lint (adoption TODO)',
   },
   uninstall: {
@@ -320,30 +328,32 @@ shims). Additive — never overwrites your files. --preset picks the .config plu
     body: `Usage: spex uninstall [dir=cwd] [--hooks]
 
 Removes every SpexCode-GENERATED artifact (harness shims · contract blocks · trust entries ·
-.gitignore block · global store · plugin bundle) and never your .spec/.config data or your own
+exclude/ignore blocks · global store · plugin bundle) and never your .spec/.config data or your own
 prose. Git hooks are preserved unless --hooks.`,
     see: 'spex init (re-adopt later — your .spec survives)',
   },
   materialize: {
-    line: 'materialize           re-render the harness artifacts (contract block · shims) for cwd’s project',
+    line: 'materialize           re-materialize the harness artifacts (contract block · shims) for cwd’s project',
     body: `Usage: spex materialize
 
-Renders the surface:system config nodes into the managed <!-- spexcode --> block of
-CLAUDE.md/AGENTS.md plus the .claude/.codex shims, and prints the content hash. Run it after a
-toolchain update or any .config edit that the automatic dispatch gate hasn't picked up — these
-artifacts are generated and gitignored, so they never arrive via git.`,
-    see: 'spex doctor (verify the render actually reaches an agent)',
+Materializes the surface:system config nodes into the managed <!-- spexcode --> block of
+CLAUDE.md/AGENTS.md plus the .claude/.codex shims, and prints the content hash. The materialize anchors on
+git-native events only (init · this verb · session-worktree creation · the pre-commit/post-checkout/
+post-merge hooks) — run it by hand after a toolchain update, or in the setup step of any clone that
+has no spex-planted hooks yet (CI, a cloud agent): the artifacts are generated and excluded, so they
+never arrive via git.`,
+    see: 'spex doctor (verify the materialized artifacts actually reach an agent)',
   },
   doctor: {
     line: 'doctor                diagnose whether the workflow actually reaches this agent — per-layer, per-harness',
     body: `Usage: spex doctor             per-layer coverage report: preconditions · git-hook floor · contract ·
-                               hooks + handler existence · backend — for every harness materialize renders
+                               hooks + handler existence · backend — for every harness materialize delivers to
        spex doctor contract    print the composed surface:system text any agent here reads
        spex doctor conflicts   detect double-delivery (loose artifacts beside the managed ones)
 
 Run it when a worker seems to be missing its contract or hooks — it names the broken layer and the
 repair, instead of you diffing materialized files by hand.`,
-    see: 'spex materialize (re-render the artifacts doctor checks)',
+    see: 'spex materialize (re-materialize the artifacts doctor checks)',
   },
   serve: {
     line: 'serve                 run the API backend (default :8787)  [--port N] [--public --password pw]',
@@ -372,10 +382,12 @@ so bind wide only on a network you trust (for the internet, use \`spex serve --p
   // ── plumbing ──────────────────────────────────────────────────────────────
   internal: {
     line: '',   // deliberately not on the map
-    body: `Usage: spex internal <trunk | codex-launch | codex-turn>
+    body: `Usage: spex internal <trunk | commit-surgery | refresh-footprint | codex-launch | codex-turn>
 
 Machine plumbing — called by generated hooks and launch scripts, never typed by a human or agent:
-  trunk         print the resolved source-of-truth branch (the pre-commit main-guard captures it)
+  trunk             print the resolved source-of-truth branch (the pre-commit main-guard captures it)
+  commit-surgery    pre-commit footprint anchor: unconditional materialize + staged-index repair
+  refresh-footprint quiet materialize — the post-checkout/post-merge freshness anchor
   codex-launch  <sock> <cwd> [prompt…]   backend-owned codex thread/start + first turn (launch script)
   codex-turn    <sock> <threadId> <text…>  fire a follow-up turn on an owned thread (tests/scripts)
 

package/spec-cli/src/index.ts

@@ -7,6 +7,7 @@ import { loadSpecs, loadSpecsLite, specContent, specHistory, specDiffAt, loadCon
 import { issuesEnabled, remarkOnHost, resolveRemark, retractRemark } from './localIssues.js'
 import { closeIssue, createIssue, issueStores, mergedIssues, promote, replyIssue } from './issues.js'
 import { residentForgeState, refreshForgeNow } from '../../spec-forge/src/resident.js'
+import { resolveForgeHost } from '../../spec-forge/src/drivers.js'
 import { summarize } from './mentions.js'
 import { resolveLayout, mainBranch } from './layout.js'
 import { getBoardJson } from './boardCache.js'
@@ -44,7 +45,8 @@ app.get('/health', (c) => c.text('ok'))
 // shares ONE build instead of each running its own — the poll-frequency cut (push channel) and the
 // build-coalescing cut compound. A hard timeout bounds a wedged build to a loud 503 rather than an
 // unboundedly-held connection (the wall sits well above the legitimately-several-seconds cold first build);
-// the underlying single-flight build keeps running and caches for the next poll.
+// a merely-slow single-flight build keeps running and caches for the next poll, while a NEVER-settling one
+// is bounded by [[board-cache]]'s own build watchdog, so the next poll retries a fresh build.
 const BOARD_TIMEOUT_MS = Number(process.env.SPEXCODE_BOARD_TIMEOUT_MS || 20000)
 app.get('/api/board', etag(), async (c) => {
   const timeout = Symbol('timeout')
@@ -160,7 +162,7 @@ app.get('/api/issues', etag(), (c) =>
   c.json({
     enabled: issuesEnabled(),
     stores: issueStores(),
-    issues: mergedIssues({ host: 'github', state: residentForgeState() }, loadSpecsLite().map((s) => s.id)),
+    issues: mergedIssues({ host: resolveForgeHost(), state: residentForgeState() }, loadSpecsLite().map((s) => s.id)),
   }))
 // the WRITE surface ([[local-issues]] / [[issues-view]]) — the human reply path, STORE-ROUTED through the one
 // reply verb ([[issues]] replyIssue): a local id git-commits to the trunk store, a forge id ('github#N')
@@ -181,7 +183,7 @@ app.post('/api/issues/:id/reply', async (c) => {
   try {
     // the mention prompt's node context, from the same resident merge the GET serves
     const node = id.includes('#')
-      ? mergedIssues({ host: 'github', state: residentForgeState() }, loadSpecsLite().map((s) => s.id)).find((i) => i.id === id)?.nodes[0] ?? null
+      ? mergedIssues({ host: resolveForgeHost(), state: residentForgeState() }, loadSpecsLite().map((s) => s.id)).find((i) => i.id === id)?.nodes[0] ?? null
       : null
     const r = await replyIssue(id, text, { author: 'human', node, evidence })
     if (r.store !== 'local') await refreshForgeNow()
@@ -446,9 +448,10 @@ app.post('/api/sessions/:id/rawkey', async (c) => {
 // removes the worktree. {ok:false} = no such session.
 app.post('/api/sessions/:id/exit', async (c) => c.json({ ok: await exitSession(c.req.param('id')) }))
 app.post('/api/sessions/:id/close', async (c) => c.json({ ok: await closeSession(c.req.param('id')) }))
-// set (or clear, with a blank) a session's display-name override; persists to the worktree's `.session` so
-// it survives a restart. Unknown id → 404. The worktree file is OUTSIDE the store the board watchers see,
-// so the route nudges the stream explicitly ([[board-stream]]) — the rename shows in ~150ms, not a cold tick.
+// set (or clear, with a blank) a session's display-name override; persists to the session's global record
+// (`session.json`) so it survives a restart. Unknown id → 404. That record sits INSIDE the watched store, but
+// the store watch is best-effort (it can fail to attach), so the route still nudges the stream explicitly
+// ([[board-stream]]) — the rename shows in ~150ms deterministically, never waiting out a cold tick.
 app.post('/api/sessions/:id/rename', async (c) => {
   const body = await c.req.json().catch(() => ({}))
   const ok = await renameSession(c.req.param('id'), typeof body?.name === 'string' ? body.name : '')

package/spec-cli/src/init.ts

@@ -1,8 +1,8 @@
-import { existsSync, mkdirSync, copyFileSync, readdirSync, statSync, chmodSync } from 'node:fs'
+import { existsSync, mkdirSync, copyFileSync, readdirSync, statSync, chmodSync, writeFileSync } from 'node:fs'
 import { join, resolve, relative } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { execFileSync } from 'node:child_process'
-import { readConfig } from './layout.js'
+import { readConfig, readJsonConfig } from './layout.js'
 import { resolveHarnessTargets } from './harness-select.js'
 
 // this file lives at <pkgRoot>/src/init.ts, so `..` is the package root — the same derivation the
@@ -99,13 +99,16 @@ export async function specInit(targetArg: string | undefined, presetArg?: string
     }
   }
 
-  // 1b. plant a starter spexcode.json (the lint/layout knob), pointing governedRoots at `src/`.
+  // 1b. plant a starter spexcode.json (the lint/layout knob). The success message reports the value the
+  // template ACTUALLY ships (read from the planted file, never restated as a string literal here — the two
+  // once drifted: the message claimed ["src"] while the template seeded ["."]).
   const cfgDest = join(targetDir, 'spexcode.json')
   if (existsSync(cfgDest)) {
     console.warn(`• spexcode.json already exists at ${cfgDest} — left untouched.`)
   } else {
     copyFileSync(join(TEMPLATES, 'spexcode.json'), cfgDest)
-    console.log(`✓ planted spexcode.json — set lint.governedRoots to YOUR source dirs (starter: ["src"])`)
+    const roots = JSON.stringify(readJsonConfig(cfgDest)?.lint?.governedRoots ?? null)
+    console.log(`✓ planted spexcode.json — lint.governedRoots starts as ${roots} (the whole git-tracked tree, tests excluded); curate explicit roots later if you want a narrower graph`)
   }
 
   // validate the harness DELIVERY TARGET set ([[harness-select]]) up front: a bad `harnesses` set (plugin +
@@ -141,29 +144,33 @@ export async function specInit(targetArg: string | undefined, presetArg?: string
     if (installed.length) console.log(`✓ installed git hooks (${installed.join(', ')}) → ${hooksDir}`)
   }
 
-  // 2c. RENDER the harness-discovered artifacts so a USER-self-launched claude/codex works with zero further
+  // 2c. MATERIALIZE the harness-discovered artifacts so a USER-self-launched claude/codex works with zero further
   // steps: the hook manifest (in the GLOBAL per-project store, not the worktree), the AGENTS.md/CLAUDE.md
   // <spexcode> contract block (user content preserved), the .claude/.codex shims, and the Codex trust (global,
   // scoped) so codex self-launch is prompt-free. Runs with cwd = the target so the loaders read the just-seeded
-  // .config. Idempotent — the dispatch.sh gate keeps it fresh thereafter on every .config edit.
+  // .config. Idempotent — the planted git hooks (pre-commit/post-checkout/post-merge) keep it fresh
+  // thereafter on the git-native anchors ([[commit-surgery]]); no harness event ever triggers a materialize.
   const prevCwd = process.cwd()
   try {
     process.chdir(targetDir)
     const { materialize } = await import('./materialize.js')
     materialize(targetDir)
-    console.log('✓ materialized harness artifacts (global hook manifest, AGENTS.md/CLAUDE.md block, .claude/.codex shims, Codex trust)')
+    console.log('✓ materialized harness artifacts (global hook manifest, AGENTS.md/CLAUDE.md block, harness shims, Codex trust)')
   } catch (e) {
     console.warn(`• materialize skipped (${(e as Error).message}) — run \`spex materialize\` once the packages are installed.`)
   } finally {
     process.chdir(prevCwd)
   }
 
-  // 3. next steps — what the human must do to bring the instance to life.
+  // 3. next steps — what the human must do to bring the instance to life. The governedRoots line reads the
+  // LIVE value (the planted starter's, or a pre-existing config's) so it can never drift from what's on disk.
+  const rootsNow = JSON.stringify(readJsonConfig(cfgDest)?.lint?.governedRoots ?? null)
   console.log(`
 Next steps:
   1. Edit .spec/project/spec.md to describe YOUR project, then grow child nodes beneath it.
-  2. Set lint.governedRoots in spexcode.json to your source dir(s) — until you do, \`spex lint\`
-     warns it is governing nothing (it ships pointing at "src").
+  2. lint.governedRoots in spexcode.json (currently ${rootsNow}) names what \`spex lint\` governs —
+     ["."] governs the whole git-tracked tree (tests excluded); narrow it to explicit source roots
+     when you want a curated graph.
   3. Start the backend and open the board:
        spex serve                       # http://localhost:8787
   4. \`spex lint\` should report 0 errors. Coverage warnings are your adoption TODO (source files no

package/spec-cli/src/issues.ts

@@ -9,7 +9,7 @@
 // (createIssue/createComment/closeIssue — the driver stays the only network toucher; the tracer stays read-only).
 import type { ForgeIssue, ForgePR } from '../../spec-forge/src/port.js'
 import { resolveLinks } from '../../spec-forge/src/links.js'
-import { DEFAULT_FORGE_HOST, FORGE_DRIVERS, forgeDriverFor, forgeIssueStores } from '../../spec-forge/src/drivers.js'
+import { FORGE_DRIVERS, forgeDriverFor, forgeIssueStores, resolveForgeHost } from '../../spec-forge/src/drivers.js'
 import { closeLocalIssue, loadLocalIssues, loadOne, postLocalIssue, reply, issuesEnabled, replyLocalIssue, runIssueWrite, ISSUE_WRITE_SUBS } from './localIssues.js'
 import { dispatchMentions, parseMentions, type DispatchOutcome, type LoopIn } from './mentions.js'
 import { envSessionId } from './layout.js'
@@ -191,8 +191,9 @@ export async function promote(id: string, opts: { author?: string } = {}): Promi
   const author = opts.author || envSessionId() || 'unknown'
   const t = loadOne(id)
   if (t.status !== 'open') throw new Error(`'${id}' is ${t.status} — only an open local issue promotes`)
-  const driver = forgeDriverFor(DEFAULT_FORGE_HOST)
-  if (!driver) throw new Error(`unknown default forge host '${DEFAULT_FORGE_HOST}'`)
+  const host = resolveForgeHost()
+  const driver = forgeDriverFor(host)
+  if (!driver) throw new Error(`no driver for this repo's forge host '${host}' (known: ${FORGE_DRIVERS.map((d) => d.host).join(', ')}) — promotion needs one`)
   const body = [
     t.body,
     t.nodes.length ? `\nSpec: ${t.nodes.join(', ')}` : '',
@@ -300,8 +301,9 @@ export async function runIssues(args: string[]): Promise<number> {
   const nodeIds = loadSpecsLite().map((s) => s.id)
   let forge: ForgeSlice | null = null
   try {
-    const driver = forgeDriverFor(DEFAULT_FORGE_HOST)
-    if (!driver) throw new Error(`unknown default forge host '${DEFAULT_FORGE_HOST}'`)
+    const host = resolveForgeHost()
+    const driver = forgeDriverFor(host)
+    if (!driver) throw new Error(`no driver for this repo's forge host '${host}' (known: ${FORGE_DRIVERS.map((d) => d.host).join(', ')})`)
     const [issues, prs] = await Promise.all([driver.listIssues(), driver.listPRs()])
     forge = { host: driver.host, state: { issues, prs } }
   } catch (e) {

package/spec-cli/src/layout.ts

@@ -10,12 +10,15 @@ type Config = {
   mainBranch?: string              // source-of-truth BRANCH worktrees fork from (default: auto-detected — see mainBranch())
   branchPrefix?: string            // how a branch names its node (default: "node/")
   preset?: string                  // the SELECTED init preset — which cumulative .config tier `spex init` seeds (default 'default'; seed-time only, no launcher gate; read by init.ts; see [[init-preset]])
-  // PRIVATE-OVERLAY mode ([[private-overlay]]) — belongs in the gitignored spexcode.local.json, NEVER the
-  // committed spexcode.json. When true, `spex materialize` leaves ZERO trace in the host's TRACKED files /
-  // shared history: the managed ignore entries (incl .spec + spexcode.json, which the DEFAULT mode commits —
-  // "git is the database") go to the per-clone `.git/info/exclude`, and any host-tracked contract file
-  // (CLAUDE.md/AGENTS.md) the system block folds into is marked `skip-worktree` so that block never stages.
-  // The dogfood becomes invisible to collaborators, trading away git-derived spec version history ([[source-of-truth]]).
+  // RETIRED ([[residence]]) — the old three-word footprint vote. Materialized artifacts carry no facts and are never
+  // tracked now (one residence behavior: the per-clone exclude, plus the content filter for a mixed
+  // contract file), so the field is IGNORED with a loud non-fatal notice (materialize's retiredAxisNotice);
+  // it stays in the type only so the notice can read it. The schema deliberately has NO knob for the spec
+  // DATA: `.spec` + spexcode.json are ALWAYS tracked ("git is the database") — the vocabulary itself makes
+  // "untrack the spec" unsayable.
+  render?: string
+  // RETIRED (residence compat): the old private-overlay toggle — ignored with the same loud notice;
+  // its data-untrack semantics are long gone. See `spex guide footprint` MIGRATIONS.
   private?: boolean
   // which harness targets `spex materialize` delivers into — native ids ('claude'|'codex') or a {plugin:"<folder>"}
   // bundle; resolved + validated by [[harness-select]] (harness-select.ts). Default (omitted): all native harnesses.
@@ -46,12 +49,15 @@ type Config = {
   issues?: {
     enabled?: boolean                // the [[local-issues]] issues-workflow on/off switch (default ON). OFF silences the post-merge nudge + hides the dashboard view; flip with `spex issues on|off`. (Pre-rename `proposals.enabled` still reads — localIssues.ts issuesEnabled.)
   }
+  forge?: {
+    host?: string                    // explicit forge host id ('github'|'gitlab'|…) overriding the origin-remote derivation ([[forge-host]] — read by spec-forge drivers.ts resolveForgeHost, not here). A project fact → committed spexcode.json.
+  }
 }
 // the resolved LAYOUT convention — main/mainBranch/branchPrefix filled to defaults. `dashboard`, `sessions`,
-// `serve`, `harnesses`, and `preset` are frontend/runtime/policy concerns (read separately via readConfig —
+// `serve`, `harnesses`, `render`, and `preset` are frontend/runtime/policy concerns (read separately via readConfig —
 // preset by init.ts at seed time, harnesses by [[harness-select]]; see api-endpoint / sessions.ts maxActive /
 // gateway.ts), NOT layout fields, so they stay out of the convention rather than forcing a default.
-type Convention = Required<Omit<Config, 'dashboard' | 'sessions' | 'serve' | 'harnesses' | 'preset' | 'issues' | 'private'>>
+type Convention = Required<Omit<Config, 'dashboard' | 'sessions' | 'serve' | 'harnesses' | 'preset' | 'issues' | 'forge' | 'private' | 'render'>>
 
 export type Worktree = {
   path: string; branch: string | null; node: string | null
@@ -133,17 +139,29 @@ export function spexcodeHome(): string {
 export function encodeProject(root: string): string {
   return root.replace(/[/.]/g, '-')
 }
-// this project's per-PROJECT runtime tier — the materialized hook manifest + content-hash marker (and the
-// gate's lock) — living alongside sessions/ under the SAME global per-project dir, so NOTHING SpexCode renders
-// stays in the worktree (not even the manifest; the worktree holds only the harness-discovered CLAUDE.md/
-// AGENTS.md + shims, which must sit in-tree). proj-aware for `spex init <dir>` / materialize(proj); cwd-based
-// default for the hooks/board. The shell hooks mirror this as hp_runtime_dir.
+// this project's per-PROJECT runtime tier — the sessions/ records AND the per-TREE materialize slots (below) —
+// living under the SAME global per-project dir, so NOTHING SpexCode materializes stays in the worktree (the
+// worktree holds only the harness-discovered CLAUDE.md/AGENTS.md + shims, which must sit in-tree).
+// proj-aware for `spex init <dir>` / materialize(proj); cwd-based default for the hooks/board. The shell
+// hooks mirror this as hp_runtime_dir.
 export function runtimeRoot(proj?: string): string {
   const gcd = proj
     ? git(['-C', proj, 'rev-parse', '--path-format=absolute', '--git-common-dir']).trim()
     : gitCommonDir()
   return join(spexcodeHome(), 'projects', encodeProject(dirname(gcd)))
 }
+// the per-WORKTREE materialize slot — <runtime>/trees/<enc(worktree-toplevel)> — holding the materialize
+// products that are a pure function of ONE tree's .config (hooks-manifest, content-hash, plugin-folders).
+// Slotted per tree exactly like sessions/<id> is slotted per session: the old single global file made the
+// last-materialized tree win, so dispatch ran tree A's compiled hook set inside tree B's sessions
+// ([[hook-dispatch]]). Key = the sessions encodeProject transform over `rev-parse --show-toplevel`, the
+// SAME derivation dispatch.sh's shell mirror (hp_tree_dir) runs from its own cwd — so writer and reader
+// land on the same slot from the same tree, and only from the same tree. Throws when `wt` is not a live
+// git tree (fail loud); a best-effort caller (the close-time GC) wraps it.
+export function treeSlotDir(wt: string): string {
+  const top = git(['-C', wt, 'rev-parse', '--show-toplevel']).trim()
+  return join(runtimeRoot(wt), 'trees', encodeProject(top || wt))
+}
 // this project's per-session records dir, one session's dir, its structured record, and a sibling artifact —
 // all keyed by session_id under <home>/projects/<enc>/sessions/.
 export function sessionsRoot(): string { return join(runtimeRoot(), 'sessions') }

package/spec-cli/src/lint.ts

@@ -140,6 +140,11 @@ export async function specLint(): Promise<Finding[]> {
         out.push({ level: 'error', rule: 'integrity', spec: s.id, file: f, msg: `spec '${s.id}' lists a missing file: ${f}` })
       owners.set(f, [...(owners.get(f) ?? []), s.id])
     }
+    // one-govern: a node is source of truth for at most ONE file, so drift/yatsu/ack have a single
+    // unambiguous subject (see [[governed-related]]). >1 is a defect — pick the true subject, demote the
+    // rest to related. ERROR (the node-side twin of too-many-owners' file-side bound). 0 is fine.
+    if (s.code.length > 1)
+      out.push({ level: 'error', rule: 'one-govern', spec: s.id, msg: `'${s.id}' governs ${s.code.length} files [${s.code.join(', ')}] — a node is source of truth for at most ONE. Keep the true subject in code:, move the rest to related:` })
   }
   // a file is COVERED if any node GOVERNS (code:) or merely REFERENCES (related:) it; integrity covers both.
   // `related:` is the coverage net: govern is a sharp ideally-one-file pointer, so most files are reached by
@@ -217,6 +222,20 @@ export async function specLint(): Promise<Finding[]> {
       out.push({ level: 'warn', rule: 'drift', spec: s.id, file: d.file, msg: `${d.file} is ${d.behind} commit(s) ahead of spec '${s.id}' (v${s.version}) — may be stale` })
   }
 
+  // related drift: the SOFT tier ([[governed-related]]). A referenced file moved ahead of the node's
+  // version — a nudge that a dependency shifted. Same ancestry basis as govern drift, but WARN-only,
+  // never reaching the commit gate (driftGate reads govern) or yatsu. It is COMMON (shared substrate and
+  // faces change often without re-versioning every referrer), so per-file it is a wall; like
+  // too-many-owners it collapses to ONE summary line, with the per-file detail riding the board
+  // (relatedDriftFiles). It stays a soft edge, never a per-file interruption.
+  const rd = specs.flatMap((s) => s.relatedDriftFiles.map((d) => ({ id: s.id, behind: d.behind })))
+  if (rd.length) {
+    const byNode = new Map<string, number>()
+    for (const d of rd) byNode.set(d.id, (byNode.get(d.id) ?? 0) + 1)
+    const worst = [...byNode].sort((a, b) => b[1] - a[1]).slice(0, 5).map(([id, n]) => `${id}(${n})`).join(', ')
+    out.push({ level: 'warn', rule: 'related-drift', msg: `${rd.length} related file(s) across ${byNode.size} node(s) drifted ahead of their spec (SOFT — a dependency shifted, worth a glance; never blocks, no ack, no yatsu). Most: ${worst}` })
+  }
+
   return out
 }
 

package/spec-cli/src/localIssues.ts

@@ -362,16 +362,28 @@ export async function replyLocalIssue(id: string, body: string, author: string,
 // The FALLBACK CHAIN of candidates a reply loops in ([[mentions]] loop-in / [[remark-substrate]] R3's dispatch
 // clause), tried in order until one is online. A plain thread's only candidate is its author (`by`). An
 // EVAL-COMMENT thread (concern `eval: <node> · <scenario>`, the eval-remark track) chains: the agent who FILED
-// the reading the remark judges FIRST, then — when that filer is offline/absent — the NODE's governing session,
-// so an unresolved remark still REACHES an agent who can act on it. This is notification only; it resolves
-// nothing (R3: resolve is a deliberate `spex resolve`). Non-eval threads pay nothing (no yatsu/specs import).
+// the reading the remark judges FIRST — resolved from the TRUNK sidecar, then from each LIVE session's
+// WORKTREE (an in-flight reading, filed on an unmerged branch, is invisible to the trunk — exactly the
+// review-time case, when the filer sits online awaiting review and the remark must reach them) — then, when
+// every filer is offline/absent, the NODE's governing session, so an unresolved remark still REACHES an agent
+// who can act on it. A broken/absent worktree sidecar falls through silently — one bad worktree never fails
+// the remark write. This is notification only; it resolves nothing (R3: resolve is a deliberate
+// `spex resolve`). Non-eval threads pay nothing (no yatsu/specs/sessions import).
 const EVAL_CONCERN_RE = /^eval: (.+?) · (.+)$/   // node first (never contains ' · '), then the scenario (may)
 async function threadOriginators(thread: Issue): Promise<(string | null)[]> {
   const m = EVAL_CONCERN_RE.exec(thread.concern)
   if (!m) return [thread.by]
   const node = m[1].trim(), scenario = m[2].trim()
   const { evalReadingFiler } = await import('../../spec-yatsu/src/filing.js')
-  return [evalReadingFiler(node, scenario), await nodeGoverningSession(node)]
+  const chain: (string | null)[] = [evalReadingFiler(node, scenario)]
+  try {
+    const { listSessions } = await import('./sessions.js')
+    for (const s of await listSessions()) {
+      try { if (s.path) chain.push(evalReadingFiler(node, scenario, s.path)) } catch { /* one unreadable worktree → next link */ }
+    }
+  } catch { /* sessions unavailable (bare store, no tmux) → trunk-only chain, as before */ }
+  chain.push(await nodeGoverningSession(node))
+  return chain
 }
 
 // A node's governing session — the `session` its spec resolves to (the Session: trailer of its latest version,