spexcode 0.5.2 → 0.5.3

package/spec-cli/src/sh.ts

@@ -0,0 +1,3 @@
+export function shQuote(s: string): string {
+  return `'${s.replace(/'/g, `'\\''`)}'`
+}

package/spec-cli/src/source-files.ts

@@ -54,14 +54,39 @@ function isTextWorktreeFile(root: string, path: string): boolean {
 // Source discovery classifies tracked paths and bytes only. Language structure belongs to anchors.ts's
 // adapter registry; adding a language must never add a branch here.
 export function isSourceFile(root: string, path: string, policy: SourcePolicy): boolean {
+  if (!isSourcePath(path, policy)) return false
+  return isTextWorktreeFile(root, path)
+}
+
+function isSourcePath(path: string, policy: SourcePolicy): boolean {
   if (isSpexCodeData(path)) return false
   if (policy.sourceIncludeGlobs !== null && !policy.sourceIncludeGlobs.some((glob) => globToRe(glob).test(path))) return false
   if (policy.sourceExcludeGlobs.some((glob) => globToRe(glob).test(path))) return false
   if (policy.testGlobs.some((glob) => globToRe(glob).test(path))) return false
-  return isTextWorktreeFile(root, path)
+  return true
 }
 
-export function trackedSourceFiles(root: string, roots: string[], policy: SourcePolicy): string[] {
+export function trackedSourceFiles(root: string, roots: string[], policy: SourcePolicy, tip = 'HEAD'): string[] {
+  if (tip !== 'HEAD') {
+    let listed = '', textOut = ''
+    try {
+      listed = git(['-C', root, '-c', 'core.quotePath=false', 'ls-tree', '-r', '-z', '-l', tip, '--', ...roots])
+      textOut = git(['-C', root, '-c', 'core.quotePath=false', 'grep', '-I', '-l', '-z', '-e', '', tip, '--', ...roots])
+    } catch { /* git grep exits 1 when the tree slice has no non-empty text */ }
+    const text = new Set(textOut.split('\0').map((entry) => {
+      const prefix = `${tip}:`
+      return entry.startsWith(prefix) ? entry.slice(prefix.length) : entry
+    }).filter(Boolean))
+    const out = new Set<string>()
+    for (const record of listed.split('\0')) {
+      if (!record) continue
+      const m = record.match(/^100\d+ blob [0-9a-f]+\s+(\d+)\t([\s\S]+)$/)
+      if (!m) continue
+      const path = m[2]
+      if (isSourcePath(path, policy) && (+m[1] === 0 || text.has(path))) out.add(path)
+    }
+    return [...out]
+  }
   const out = new Set<string>()
   for (const governedRoot of roots) {
     let listed = ''

package/spec-cli/src/specs.ts

@@ -1,8 +1,9 @@
 import { readFileSync, readdirSync, existsSync } from 'node:fs'
 import { readFile, readdir } from 'node:fs/promises'
 import { join, relative, basename } from 'node:path'
-import { repoRoot, historyIndex, rowsFor, statsFor, pathsStats, driftIndex, driftFor, fileDiffAt } from './git.js'
-import { parseCodeEntry, parseRelation } from './anchors.js'
+import { repoRoot, historyIndex, rowsFor, statsFor, pathsStats, driftIndex, driftFor, fileDiffAt,
+  sourceIndexes, treeTextFiles, type HistoryIndex, type DriftIndex } from './git.js'
+import { parseCodeEntry, parseRelation, relationClaimsPath } from './anchors.js'
 
 // a node is any directory under .spec holding a spec.md; its parent is the nearest ancestor that also holds one.
 const ROOT = repoRoot()
@@ -12,7 +13,7 @@ type FmValue = string | string[]
 type Raw = { id: string; parent: string | null; relPath: string; fm: Record<string, FmValue>; body: string }
 
 // line-based frontmatter: scalars are `key: value`; an empty key followed by `- item` lines is a list (e.g. `code:`).
-function parseFrontmatter(src: string) {
+export function parseFrontmatter(src: string) {
   const fm: Record<string, FmValue> = {}
   let body = src
   const m = src.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/)
@@ -153,7 +154,21 @@ async function walkAsync(dir: string, parent: string | null, acc: Raw[], root: s
     if (e.isDirectory()) await walkAsync(join(dir, e.name), myId, acc, root)
   }
 }
-async function rawsAsync(root: string): Promise<Raw[]> {
+export type SpecTreeSnapshot = { tip: string; files: ReadonlyMap<string, string> }
+
+async function rawsAsync(root: string, tip = 'HEAD', snapshot?: SpecTreeSnapshot): Promise<Raw[]> {
+  if (snapshot || tip !== 'HEAD') {
+    const acc: Raw[] = []
+    const files = snapshot?.files ?? treeTextFiles(root, tip, '.spec')
+    for (const [relPath, source] of [...files].sort(([a], [b]) => a.localeCompare(b))) {
+      if (!relPath.endsWith('/spec.md')) continue
+      const segs = relPath.split('/')
+      const { fm, body } = parseFrontmatter(source)
+      acc.push({ id: segs[segs.length - 2], parent: null, relPath, fm, body })
+    }
+    reId(acc)
+    return acc
+  }
   const acc: Raw[] = []
   const specDir = join(root, '.spec')
   if (existsSync(specDir)) await walkAsync(specDir, null, acc, root)
@@ -164,12 +179,7 @@ async function rawsAsync(root: string): Promise<Raw[]> {
 // the claim rule shared by both relations (exact path, dir-prefix, or *-glob). See [[governed-related]].
 function claimMatcher(file: string): (cf: string) => boolean {
   const rel = file.startsWith('/') ? relative(ROOT, file) : file
-  return (cf: string): boolean => {
-    if (cf === rel) return true
-    if (rel.startsWith(cf.replace(/\/+$/, '') + '/')) return true
-    if (cf.includes('*')) return new RegExp('^' + cf.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*') + '$').test(rel)
-    return false
-  }
+  return (claim) => relationClaimsPath(claim, rel)
 }
 
 // spec node(s) that GOVERN a file (frontmatter `code:` — source of truth, drives drift + eval freshness); reads only
@@ -227,12 +237,29 @@ export function specContent(id: string): { body: string; parts: ReturnType<typeo
 // instead ([[source-of-truth]]'s several-checkouts principle at the loader level): its .spec is the
 // branch's pending proposal, so eval surfaces rooted at a session must load the spec tree from the SAME
 // root as their readings/indexes, or a branch-NEW node simply does not exist for them.
-export async function loadSpecs(root: string = ROOT) {
-  // both indexes are one cached git walk each and independent — fetch them in parallel (async git, off
-  // the event loop). Every node below is then a pure lookup.
-  const [idx, didx, allRaws] = await Promise.all([historyIndex(root), driftIndex(root), rawsAsync(root)])
-  return Promise.all(allRaws.map(async (r) => {
-    const h = rowsFor(idx, r.relPath)
+export type LoadSpecsOptions = {
+  tip?: string
+  history?: HistoryIndex | null
+  drift?: DriftIndex | null
+  snapshot?: SpecTreeSnapshot
+}
+export async function loadSpecs(root: string = ROOT, options: LoadSpecsOptions = {}) {
+  // The default pair shares one immutable-event snapshot; explicit sides let callers skip or supply either
+  // projection. Every node below is then a pure in-memory lookup.
+  const tip = options.tip ?? 'HEAD'
+  if (options.snapshot && options.snapshot.tip !== tip) {
+    throw new Error(`loadSpecs snapshot tip '${options.snapshot.tip}' does not match requested tip '${tip}'`)
+  }
+  const indexes = options.history === undefined && options.drift === undefined
+    ? sourceIndexes(root, tip)
+    : Promise.all([
+      options.history === null ? Promise.resolve(null) : options.history ?? historyIndex(root, tip),
+      options.drift === null ? Promise.resolve(null) : options.drift ?? driftIndex(root, tip),
+    ])
+  const [[idx, didx], allRaws] = await Promise.all([indexes, rawsAsync(root, tip, options.snapshot)])
+  const loaded = []
+  for (const r of allRaws) {
+    const h = idx ? rowsFor(idx, r.relPath) : []
     // session = the Session: trailer of the node's latest version; frontmatter `session:` is the fallback.
     const fmSession = str(r.fm.session)
     const session = h[0]?.session || (fmSession && fmSession !== 'null' ? fmSession : null)
@@ -249,19 +276,24 @@ export async function loadSpecs(root: string = ROOT) {
     const relatedScoped = relatedRel.entries.filter((e) => e.selectors.length > 0)
     const relationProblems = [...codeRel.problems, ...relatedRel.problems]
     const S = h[0]?.hash || ''
-    const driftFiles = code
-      .map((f) => ({ file: f, behind: driftFor(didx, S, f) }))
-      .filter((d) => d.behind > 0)
+    const driftFiles = []
+    for (const f of code) {
+      const d = didx ? { file: f, behind: driftFor(didx, S, f, r.id) } : { file: f, behind: 0 }
+      if (d.behind > 0) driftFiles.push(d)
+    }
     const drift = driftFiles.reduce((a, d) => a + d.behind, 0)
     // related drift is the SOFT tier ([[governed-related]]): same ancestry basis, but it stays OUT of
     // `drift` — it never feeds status, the commit gate, or eval freshness. It surfaces only as a lint warn nudge.
     // A SCOPED related entry is excluded here: its file-level movement is silent by design — only a
     // selector HIT warns, and that verdict needs the anchor engine, so lint derives it, not the loader.
-    const relatedDriftFiles = relatedRel.entries.filter((e) => !e.selectors.length)
-      .map((e) => ({ file: e.path, behind: driftFor(didx, S, e.path) }))
-      .filter((d) => d.behind > 0)
+    const relatedDriftFiles = []
+    for (const e of relatedRel.entries) {
+      if (e.selectors.length) continue
+      const d = didx ? { file: e.path, behind: driftFor(didx, S, e.path, r.id) } : { file: e.path, behind: 0 }
+      if (d.behind > 0) relatedDriftFiles.push(d)
+    }
     const fmStatus = str(r.fm.status, '') || null
-    return {
+    loaded.push({
       id: r.id,
       parent: r.parent,
       path: r.relPath,
@@ -287,8 +319,9 @@ export async function loadSpecs(root: string = ROOT) {
       // cold load); the history tab fetches it lazily via specDiffAt. See [[work-pane]].
       body: r.body.trim(),
       parts: parseParts(r.body),
-    }
-  }))
+    })
+  }
+  return loaded
 }
 
 // per-node version timeline; each row sums the node's spec.md stat (rename-followed, via statsFor) and its

package/spec-cli/src/supervise.ts

@@ -4,7 +4,8 @@ import net from 'node:net'
 import http from 'node:http'
 import { randomUUID } from 'node:crypto'
 import { spawn, type ChildProcess } from 'node:child_process'
-import { statSync, readdirSync, type Dirent } from 'node:fs'
+import type { Dirent } from 'node:fs'
+import { stat, readdir } from 'node:fs/promises'
 import { fileURLToPath } from 'node:url'
 import { dirname, join } from 'node:path'
 import { installProcessGuards } from './resilience.js'
@@ -14,6 +15,9 @@ import { tsxBin } from './tsx-bin.js'
 import { publishEndpoint, dropOwnEndpoint } from './host.js'
 import { repoRoot as servedRepoRoot } from './git.js'
 import { resolveProjectIdentity } from './project-identity.js'
+import { startResourceMonitor } from './host-resources.js'
+import { registerBackendInstance, unregisterBackendInstance } from './runtime-ownership.js'
+import { sessionIdentityEnvVars } from './harness.js'
 
 // the supervisor OWNS the public port, so it must outlive any transient throw: an uncaught error here is
 // logged and survived, never an exit that closes the port (and the tmux session) and takes the frontend down.
@@ -50,6 +54,13 @@ const watchRoots = [
 // different serve generation fails the match and is treated as offline, never proxied to.
 const instanceId = randomUUID()
 const projectRoot = servedRepoRoot() // the actual git tree whose source/spec/config the child serves
+// A backend is a project control plane, never the session that happened to invoke `spex serve`. Strip every
+// adapter identity before any hot child is spawned; otherwise all backend work is falsely charged to that
+// caller long after its session ends.
+for (const key of sessionIdentityEnvVars()) delete process.env[key]
+process.env.SPEXCODE_PROJECT_ROOT = projectRoot
+process.env.SPEXCODE_INSTANCE_ID = instanceId
+registerBackendInstance(instanceId, process.pid, projectRoot)
 
 type Backend = { port: number; child: ChildProcess }
 let current: Backend | null = null   // which internal port new proxy connections forward to
@@ -176,7 +187,7 @@ function dropEndpoint(): void {
   try { dropOwnEndpoint(instanceId, projectRoot) } catch { /* not ours / already gone */ }
 }
 
-const shutdown = () => { dropEndpoint(); try { current?.child.kill('SIGTERM') } catch { /* */ } process.exit(0) }
+const shutdown = () => { dropEndpoint(); unregisterBackendInstance(instanceId); try { current?.child.kill('SIGTERM') } catch { /* */ } process.exit(0) }
 process.on('SIGINT', shutdown)
 process.on('SIGTERM', shutdown)
 
@@ -187,7 +198,7 @@ current = first
 // SIGTERM (not SIGKILL): the child is a `tsx` wrapper around the real node server — SIGKILL kills the wrapper
 // instantly and ORPHANS the server still bound to its port, whereas tsx FORWARDS SIGTERM to it (the same
 // signal the reload drain uses). Sent synchronously here, before the process.exit that follows.
-const reapChild = () => { try { current?.child.kill('SIGTERM') } catch { /* already gone */ } }
+const reapChild = () => { unregisterBackendInstance(instanceId); try { current?.child.kill('SIGTERM') } catch { /* already gone */ } }
 if (publicCfg) {
   // public mode: the raw proxy stays on loopback; the password-gated gateway owns the public port.
   const distDir = resolveDistDir() // bundled <pkg>/dashboard-dist when installed, else monorepo spec-dashboard/dist
@@ -197,6 +208,7 @@ if (publicCfg) {
 } else {
   listenOrExit(proxy, publicPort, { label: 'supervisor', cleanup: reapChild, onListen: () => { recordEndpoint(childApiBase); console.log(`spec-cli supervisor serving on http://localhost:${publicPort} (zero-downtime reloads, backend :${first.port})`) } })
 }
+startResourceMonitor()
 
 // watch every imported source tree; debounce a burst of writes (a merge touching several files across
 // packages) into one reload. A root that can't be watched (a package absent in some checkout) is logged
@@ -207,19 +219,27 @@ if (publicCfg) {
 // deaf: every 2s, take the newest .ts/.js/.json mtime across the trees; a jump triggers the debounced reload
 // (a burst of writes still lands as one). Polling a few small src trees is negligible cost.
 let timer: NodeJS.Timeout | undefined
-const newestMtime = (dir: string): number => {
+const newestMtime = async (dir: string): Promise<number> => {
   let max = 0
   let entries: Dirent[]
-  try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return 0 }   // a tree absent in some checkout → skip
+  try { entries = await readdir(dir, { withFileTypes: true }) } catch { return 0 }   // a tree absent in some checkout → skip
   for (const e of entries) {
-    if (e.isDirectory()) { if (e.name !== 'node_modules') max = Math.max(max, newestMtime(join(dir, e.name))) }
-    else if (/\.(ts|js|mjs|json)$/.test(e.name)) { try { max = Math.max(max, statSync(join(dir, e.name)).mtimeMs) } catch { /* raced unlink */ } }
+    if (e.isDirectory()) { if (e.name !== 'node_modules') max = Math.max(max, await newestMtime(join(dir, e.name))) }
+    else if (/\.(ts|js|mjs|json)$/.test(e.name)) { try { max = Math.max(max, (await stat(join(dir, e.name))).mtimeMs) } catch { /* raced unlink */ } }
   }
   return max
 }
-const scanMtime = (): number => { let m = 0; for (const root of watchRoots) m = Math.max(m, newestMtime(root)); return m }
-let lastMtime = scanMtime()   // baseline at boot — only a LATER change reloads
+const scanMtime = async (): Promise<number> => {
+  let m = 0
+  for (const root of watchRoots) m = Math.max(m, await newestMtime(root))
+  return m
+}
+let lastMtime = await scanMtime()   // baseline at boot — only a LATER change reloads
+let scanning = false
 setInterval(() => {
-  const m = scanMtime()
-  if (m > lastMtime) { lastMtime = m; clearTimeout(timer); timer = setTimeout(() => void reload('code change'), 150) }
+  if (scanning) return
+  scanning = true
+  void scanMtime().then((m) => {
+    if (m > lastMtime) { lastMtime = m; clearTimeout(timer); timer = setTimeout(() => void reload('code change'), 150) }
+  }).finally(() => { scanning = false })
 }, 2000).unref()

package/spec-cli/src/uninstall.ts

@@ -150,15 +150,16 @@ export function uninstall(targetArg: string | undefined, opts: { hooks?: boolean
   }
   const bundles = sweepPluginBundles(proj, pluginHosts)
 
-  // 5. The whole store: per-tree manifests/hashes/ledgers, legacy project-global products, and sessions.
-  let removedStore: string | null = null
-  if (store && existsSync(store)) {
-    rmSync(store, { recursive: true, force: true })
-    removedStore = store
+  // 5. The whole store: per-tree manifests/hashes/ledgers and sessions.
+  const removedStores: string[] = []
+  for (const candidate of new Set([store].filter((path): path is string => !!path))) {
+    if (!existsSync(candidate)) continue
+    rmSync(candidate, { recursive: true, force: true })
+    removedStores.push(candidate)
   }
 
   console.log(`✓ dematerialized (contract blocks, shims, Codex trust, skills, sub-agents, ignore blocks, content filter) for ${HARNESSES.map((h) => h.id).join(', ')}`)
-  if (removedStore) console.log(`✓ removed the global per-project store (${removedStore})`)
+  if (removedStores.length) console.log(`✓ removed the global per-project store (${removedStores.join(', ')})`)
   if (bundles.length) console.log(`✓ removed plugin bundle(s): ${bundles.join(', ')}`)
 
   // Git hooks are per-clone and may carry user logic → preserved unless --hooks (and even then only while

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

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# spexcode-managed-hook-v1
+# Candidate lint is driven solely by reference-transaction. This hook intentionally carries no marker,
+# message hash, tree binding, or TTL; Git's immutable commit object is the only candidate identity.
+# Git does not apply scissors cleanup to every no-editor/-F path, so normalize the final message here,
+# after every editor, using scissors only when the repository explicitly selected that cleanup mode.
+if [ "$(git config --get commit.cleanup 2>/dev/null || true)" = scissors ]; then
+  msg_file="$1"
+  tmp="${msg_file}.spexcode-scissors.$$"
+  awk '/^# ------------------------ >8 ------------------------$/ { exit } { print }' "$msg_file" \
+    | git stripspace --strip-comments > "$tmp"
+  mv "$tmp" "$msg_file"
+fi
+exit 0

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

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+# spexcode-managed-hook-v1
 # @@@ shared spex runner - resolve the `spex` CLI ONCE, into spex_cli(), so BOTH the main-guard trunk
 # lookup and the spec-lint shim shim through the same mechanism (no duplicated, drift-prone resolution).
 # This must work for BOTH ways this hook ships: a real project that installed @spexcode/spec-cli, and the
@@ -27,6 +28,19 @@ spex_cli() {
   esac
 }
 
+# A commit containing only issue storage cannot change governed code or an anchor range. Keep this as a
+# path-property check at the hook boundary so the common dashboard write does not pay materialize/eval
+# backstops; any mixed commit continues through the full hook chain and the reference transaction gate.
+staged_issue_only=1
+staged_any=0
+while IFS= read -r -d '' staged_path; do
+  staged_any=1
+  case "$staged_path" in .spec/.issues/*) ;; *) staged_issue_only=0 ;; esac
+done < <(git diff --cached --name-only -z 2>/dev/null)
+if [ "$staged_any" -eq 1 ] && [ "$staged_issue_only" -eq 1 ]; then
+  exit 0
+fi
+
 # @@@ tree-unchanged stamp - a commit whose tree EQUALS HEAD's tree (`git write-tree` over the commit's own
 # index — the hook's GIT_INDEX_FILE, a temp HEAD-tree index for `commit --only --allow-empty`) adds NO
 # content: it cannot smuggle code past the main-guard below and cannot introduce spec↔code drift, so the
@@ -74,14 +88,20 @@ 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 spec 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
-# hook's GIT_DIR, so lint validates THIS worktree's `.spec`).
+# @@@ spec-lint - reference-transaction owns the candidate gate. When the installed consumer is the
+# SpexCode unmarked predicate, running full HEAD lint here would restore the history-scaled cost this gate
+# removes. A missing/custom consumer keeps the old full lint fallback, so a hook collision never reduces
+# local coverage. Static identity matters: never execute a user-owned hook with made-up probe arguments.
+# Bypass with SPEXCODE_SKIP_LINT=1. It shims through shared spex_cli() resolved above.
 if [ -z "${SPEXCODE_SKIP_LINT:-}" ]; then
   if [ -n "$spex_kind" ]; then
-    spex_cli spec lint >&2
-    lint_rc=$?
+    consume_hook=$(git rev-parse --git-path hooks/reference-transaction 2>/dev/null)
+    if [ -x "$consume_hook" ] && grep -q 'one unmarked predicate at Git' "$consume_hook" 2>/dev/null; then
+      lint_rc=0
+    else
+      spex_cli spec lint >&2
+      lint_rc=$?
+    fi
     # exit 75 = the launcher's mid-merge guard (spex's own source holds conflict markers — transient).
     # Degrade to advisory rather than walling every commit behind a merge someone else is resolving.
     if [ "$lint_rc" -eq 75 ]; then

package/spec-cli/templates/hooks/prepare-commit-msg

@@ -1,57 +1,29 @@
 #!/usr/bin/env bash
+# spexcode-managed-hook-v1
 # @@@ session-stamp - auto-attribute a commit to the SESSION that authored it, ACROSS HARNESSES. SpexCode
 # reads the `Session:` trailer as a version's attribution (git is the database), keyed by the SpexCode record
-# id so the dashboard's session window links to it. Resolving that id is a harness-adapter concern, mirroring
-# `envSessionId` / the shell `hp_store_dir` alias:
-#   - Claude exports CLAUDE_CODE_SESSION_ID, which EQUALS the record id → stamp it directly.
-#   - Codex has no such equality: its per-command CODEX_THREAD_ID is the THREAD id, not the record key, and the
-#     SHARED per-project app-server means SPEXCODE_SESSION_ID is contaminated with the FIRST session's id — so
-#     it must NOT be trusted. Resolve the thread id → record via the SAME `harness_session_id` alias the shell
-#     hooks use, AT COMMIT TIME (the record is swept on close, so read-time aliasing would fail), and stamp the
-#     resolved RECORD id.
-#   - Per-session-process harnesses (opencode; pi) export NO harness var to tool subprocesses — their identity
-#     channel IS the launch-injected SPEXCODE_SESSION_ID (each TUI is one process, no shared-server
-#     contamination). Trust it only as the LAST tier, and only when the record it names is verifiably not a
-#     codex record — so a codex shell that somehow lost its CODEX_THREAD_ID can never stamp the first
-#     session's id.
-# No-op outside a governed session, or if a Session: trailer is already present (so the dogfood ritual / a
-# human can still set it explicitly).
+# id so the dashboard's session window links to it.
+#
+# The id is simply READ here, because it was established where it is KNOWN: whoever creates an agent's
+# execution context injects that context's own record id, and nothing else may carry one.
+#   - a session launch bakes `SPEXCODE_SESSION_ID=<record id>` into the agent's process — and STRIPS every
+#     session-identity variable it inherited first, so the pane's ancestry (a tmux server started long ago by
+#     someone else) cannot smuggle one in;
+#   - a codex thread gets the same variable injected into every command it spawns, at `thread/start`, via
+#     codex's own `shell_environment_policy.set` — the tool shell is a child of the SHARED app-server and must
+#     therefore inherit nothing, so the backend hands it its identity per thread instead;
+#   - that shared app-server, and any other process we own that belongs to no single session, is spawned with
+#     those variables stripped. A process that outlived its session handing its id to strangers is exactly how
+#     this trailer once named a session that no longer existed (github#76).
+# So there is nothing to resolve, alias, or verify at commit time: the variable is present only in processes
+# that genuinely belong to that session, and it already IS the record id. No store lookup, no per-harness
+# tiers, and nothing derived from the current directory — where a process stands says nothing about who it is.
+# No id → no trailer. An existing Session: trailer is left alone, so the ritual / a human can set one by hand.
 set -euo pipefail
 msg_file="$1"
 grep -qiE '^Session:[[:space:]]' "$msg_file" && exit 0
+[ -n "${SPEXCODE_SESSION_ID:-}" ] || exit 0
 
-# the per-project store (mirrors layout.ts runtimeRoot / harness.sh hp_runtime_dir): keyed by the project
-# (dirname of the ABSOLUTE git-common-dir), '/' and '.' → '-'.
-gcd=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null) \
-  || gcd=$(realpath "$(git rev-parse --git-common-dir 2>/dev/null)" 2>/dev/null) || gcd=""
-rd=""
-[ -n "$gcd" ] && rd="${SPEXCODE_HOME:-$HOME/.spexcode}/projects/$(printf '%s' "$(dirname "$gcd")" | sed 's#[/.]#-#g')"
-
-sid="${CLAUDE_CODE_SESSION_ID:-}"                       # claude: the exported id IS the record id
-if [ -z "$sid" ] && [ -n "${CODEX_THREAD_ID:-}" ] && [ -n "$rd" ]; then # codex: alias the thread id → record id
-  if [ -e "$rd/sessions/$CODEX_THREAD_ID/session.json" ]; then
-    sid="$CODEX_THREAD_ID"                               # a governed record keyed by the thread id (rare/direct)
-  else                                                   # else the record that captured it as harness_session_id
-    # @@@ unmatched-is-noop - grep's no-match (exit 1) and an absent sessions glob (exit 2) are the
-    # NOT-GOVERNED case, not an error: any repo inherits a foreign CODEX_THREAD_ID from a codex session's
-    # shell, and under `set -euo pipefail` a bare grep|head assignment would abort the hook — and the
-    # commit — before the intended `[ -z "$sid" ] && exit 0` no-op. Genuine errors past this lookup
-    # (interpret-trailers etc.) still fail loud via set -e.
-    hit=$(grep -lF "\"harness_session_id\": \"$CODEX_THREAD_ID\"" "$rd"/sessions/*/session.json 2>/dev/null | head -1) || hit=""
-    [ -n "$hit" ] && sid=$(basename "$(dirname "$hit")")
-  fi
-fi
-if [ -z "$sid" ] && [ -n "${SPEXCODE_SESSION_ID:-}" ] && [ -n "$rd" ]; then
-  # last tier of the shared envSessionId precedence rule: no harness var claimed the commit, so the
-  # launch-injected record id is the identity — IF its record exists (governance check; swept on close) and
-  # is not codex's (the one harness whose shared server contaminates this env var).
-  rec="$rd/sessions/$SPEXCODE_SESSION_ID/session.json"
-  if [ -e "$rec" ] && ! grep -q '"harness": "codex"' "$rec"; then
-    sid="$SPEXCODE_SESSION_ID"
-  fi
-fi
-
-[ -z "$sid" ] && exit 0
 # Stamp via interpret-trailers (git's own sample-hook mechanism), NOT a raw printf append: appending after a
 # message that already carries a trailer block (e.g. `spex spec ack`'s Spec-OK) opens a new paragraph, and git then
 # parses ONLY the last paragraph as trailers — the earlier trailers silently become body prose. interpret-trailers
@@ -59,5 +31,5 @@ fi
 # on an unterminated message (git merge -m writes MERGE_MSG without one) it folds the trailer into the subject
 # paragraph, where git's trailer parser never looks — the reason merge commits' Session: never parsed.
 [ -n "$(tail -c1 "$msg_file")" ] && echo >> "$msg_file"
-git interpret-trailers --in-place --trailer "Session: $sid" "$msg_file"
+git interpret-trailers --in-place --trailer "Session: $SPEXCODE_SESSION_ID" "$msg_file"
 exit 0

package/spec-cli/templates/hooks/reference-transaction

@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+# spexcode-managed-hook-v1
+# @@@ candidate lint ([[code-anchor]]) - one unmarked predicate at Git's prepared ref boundary:
+# a refs/heads update that introduces a commit object which is not already reachable from refs/reflogs.
+# Structural ref plumbing is inert; no commit-msg arm, marker, TTL, tree, parent, or message identity exists.
+set -u
+state="${1:-}"
+payload=$(cat)
+[ -z "${SPEXCODE_GATE_TRACE:-}" ] || printf 'spexcode-gate: reference state=%s action=%s payload=%s\n' "$state" "${GIT_REFLOG_ACTION:-}" "$(printf '%s' "$payload" | tr '\n' ';')" >&2
+[ "$state" = prepared ] || exit 0
+[ -z "${SPEXCODE_SKIP_LINT:-}" ] || exit 0
+
+candidate=
+candidate_old=
+operation_git_dir=$(git rev-parse --git-dir 2>/dev/null || printf .git)
+while read -r old new ref; do
+  [ -n "${new:-}" ] || continue
+  case "$ref" in HEAD|refs/heads/*) ;; *) continue ;; esac
+  case "$new" in *[!0-9a-f]*) continue ;; esac
+  [ "$(git cat-file -t "$new" 2>/dev/null || true)" = commit ] || continue
+  # Git exposes no operation name at this boundary. Do not infer one from old=0 or from ancestor process
+  # command lines: an unreachable ref creation is the same observable candidate as any other new ref object.
+  case "$old" in '' ) continue ;; esac
+  candidate="$new"
+  candidate_old="$old"
+  break
+done <<< "$payload"
+[ -n "$candidate" ] || exit 0
+
+# Rebase/cherry-pick/revert/am author new content even when a detached rewrite left the object in a reflog.
+# Ordinary reset/branch/checkout targets are already reachable and therefore remain inert.
+force_operation=0
+if [ -d "$operation_git_dir/rebase-merge" ] || [ -d "$operation_git_dir/rebase-apply" ] \
+  || [ -d "$operation_git_dir/sequencer" ] || [ -f "$operation_git_dir/CHERRY_PICK_HEAD" ] \
+  || [ -f "$operation_git_dir/REVERT_HEAD" ]; then
+  force_operation=1
+fi
+if [ "$force_operation" -eq 0 ]; then
+  if [ -n "$(git for-each-ref --contains "$candidate" --format='%(refname)' 2>/dev/null)" ] \
+    || git reflog --all --format=%H 2>/dev/null | grep -Fqx "$candidate"; then
+    [ -z "${SPEXCODE_GATE_TRACE:-}" ] || echo "spexcode-gate: reachable candidate=$candidate skipped" >&2
+    exit 0
+  fi
+fi
+[ -z "${SPEXCODE_GATE_TRACE:-}" ] || echo "spexcode-gate: candidate=$candidate force=$force_operation" >&2
+
+# Local issue/remark commits change only non-topology data. With no code path and no node spec.md in the
+# candidate diff, an anchored unit cannot have moved and no governing claim can have changed. Prove that
+# narrow shape directly at the ref boundary so dashboard writes do not launch a full CLI merely to rediscover
+# the same fact. This is candidate classification, not a writer-set bypass: every other shape still lints.
+issue_only=1
+parent_count=$(git rev-list --parents -n1 "$candidate" 2>/dev/null | awk '{print NF-1}')
+[ "${parent_count:-0}" -gt 1 ] && issue_only=0
+changed_paths=$(git -c core.quotePath=false diff-tree --no-commit-id --name-only -r -m "$candidate_old" "$candidate" 2>/dev/null || true)
+[ -n "$changed_paths" ] || issue_only=0
+while IFS= read -r path; do
+  [ -n "$path" ] || continue
+  case "$path" in .spec/.issues/*) ;; *) issue_only=0; break ;; esac
+done <<< "$changed_paths"
+if [ "$issue_only" -eq 1 ]; then
+  [ -z "${SPEXCODE_GATE_TRACE:-}" ] || echo "spexcode-gate: issue-only candidate=$candidate skipped before lint" >&2
+  exit 0
+fi
+
+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_kind=
+if command -v spex >/dev/null 2>&1; then
+  spex_kind=path
+elif [ -x "$repo_root/node_modules/.bin/spex" ]; then
+  spex_kind=local
+elif [ -x "$main_root/spec-cli/bin/spex.mjs" ]; then
+  spex_kind=pkg
+fi
+spex_cli() {
+  case "$spex_kind" in
+    path) spex "$@" ;;
+    local) "$repo_root/node_modules/.bin/spex" "$@" ;;
+    pkg) "$main_root/spec-cli/bin/spex.mjs" "$@" ;;
+    *) return 127 ;;
+  esac
+}
+if [ -z "$spex_kind" ]; then
+  echo "• SpexCode: candidate spec-lint skipped — no \`spex\` CLI found; CI still enforces." >&2
+  exit 0
+fi
+SPEXCODE_GATE_SCOPE_ONLY=1 spex_cli spec lint --pending "$candidate" >&2
+lint_rc=$?
+if [ "$lint_rc" -eq 76 ]; then
+  [ -z "${SPEXCODE_GATE_TRACE:-}" ] || echo "spexcode-gate: non-governed candidate=$candidate skipped before full lint" >&2
+  exit 0
+fi
+[ -z "${SPEXCODE_GATE_TRACE:-}" ] || echo "spexcode-gate: lint_rc=$lint_rc candidate=$candidate" >&2
+if [ "$lint_rc" -eq 75 ]; then
+  echo "• SpexCode: candidate spec-lint skipped — spex is paused mid-merge (exit 75); CI still enforces." >&2
+  exit 0
+fi
+if [ "$lint_rc" -ne 0 ]; then
+  echo "✗ SpexCode: candidate spec-lint failed; the ref is unchanged and staged/sequencer state is intact." >&2
+  echo "  Explicit bypass: SPEXCODE_SKIP_LINT=1 git commit …" >&2
+  echo "  Continue after staging a repair: git merge --continue | git cherry-pick --continue | git rebase --continue" >&2
+  echo "  Abort the active operation:       git merge --abort    | git cherry-pick --abort    | git rebase --abort" >&2
+  exit 1
+fi
+exit 0

package/spec-cli/templates/spec/project/.plugins/commands/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 worker-sized tasks and dispatch one worker per independent task (`spex session 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 session watch`, review proposals with `spex session review <id>`, merge good ones with `git -C <root> merge --no-ff <branch>`, then close. Never let a worker self-merge; keep `spex spec lint` at 0 errors. To READ a worker's current state, use the one-shot snapshots (`spex session review <id>` or `spex session ls` — both return immediately); to WAIT for a worker, background `spex session wait <id>` — it is edge-triggered: it returns only when it OBSERVES the worker transition from non-actionable into an actionable status (an already-actionable arrival state does not return it), printing the observed status path — which is also how you wait for a dispatched merge to actually land; never block on `spex session watch`, which STREAMS forever and will freeze your turn. **Stay parked while your fleet runs:** after dispatching, background a `spex session wait <child>` per worker (per the manager loop) so that when you stop with children still working you land in `parked` — self-resuming on the next child transition — NOT `asking`; only go `asking` when you genuinely need the human. This matters because the dashboard **folds each child under you and shows YOUR own status for the whole group** (session-nesting, no child-status aggregation), so a supervisor that stays parked-while-they-run is what makes that folded group status honest. 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. **DRAIN THE ISSUES** (issues / local-issues) as part of your loop: `spex issue ls` lists every open concern in one place — the taste concerns finished sessions recorded locally, AND the forge's issues, store-tagged. Cluster the same concern yourself (use judgment — duplicates are a recurrence SIGNAL, not noise; fold them into one) and weigh by recurrence AND novelty — **recurrence is salience, not importance, so never just fix the highest count**: a sharp single-voice concern can outrank a popular gripe. For the ones worth acting on, `spex session new "<task>"` a worker to land it (mention the concern's node as `[[<id>]]` if it has one), then `spex issue ls resolve <id> --as accepted|landed` (or `rejected`, with a reply saying why) so the store reflects the decision. 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. This preset IS your complete playbook (dispatch → monitor → review → merge → close, and how to parallelize) — the CLI's own `spex help session` is the reference for every verb's exact semantics. Drive the goal: decompose it into worker-sized tasks and dispatch one worker per independent task (`spex session 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 session watch`, review proposals with `spex session review <id>`, dispatch the merge of good ones back to their own session (`spex session merge <id>`; the doer syncs the base into its own worktree first, so what reaches `<root>` is a trivial merge) and confirm it landed, then close. `<root>` is the fleet's ONE landing door — it takes one landing at a time, so a worker whose merge finds it mid-merge waits rather than racing, and you never fix up another lane's half-merged index yourself. Never let a worker self-merge; keep `spex spec lint` at 0 errors. To READ a worker's current state, use the one-shot snapshots (`spex session review <id>` or `spex session ls` — both return immediately); to WAIT for a worker, background `spex session wait <id>` — it is edge-triggered: it returns only when it OBSERVES the worker transition from non-actionable into an actionable status (an already-actionable arrival state does not return it), printing the observed status path — which is also how you wait for a dispatched merge to actually land; never block on `spex session watch`, which STREAMS forever and will freeze your turn. **Stay parked while your fleet runs:** after dispatching, background a `spex session wait <child>` per worker (per the manager loop) so that when you stop with children still working you land in `parked` — self-resuming on the next child transition — NOT `asking`; only go `asking` when you genuinely need the human. This matters because the dashboard **folds each child under you and shows YOUR own status for the whole group** (session-nesting, no child-status aggregation), so a supervisor that stays parked-while-they-run is what makes that folded group status honest. 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. **DRAIN THE ISSUES** (issues / local-issues) as part of your loop: `spex issue ls` lists every open concern in one place — the taste concerns finished sessions recorded locally, AND the forge's issues, store-tagged. Cluster the same concern yourself (use judgment — duplicates are a recurrence SIGNAL, not noise; fold them into one) and weigh by recurrence AND novelty — **recurrence is salience, not importance, so never just fix the highest count**: a sharp single-voice concern can outrank a popular gripe. For the ones worth acting on, `spex session new "<task>"` a worker to land it (mention the concern's node as `[[<id>]]` if it has one), then `spex issue ls resolve <id> --as accepted|landed` (or `rejected`, with a reply saying why) so the store reflects the decision. Report progress as you go and when the goal is complete. Your goal follows: