spexcode 0.1.0

package/src/ranker.ts

@@ -0,0 +1,129 @@
+// tier multipliers, name > desc > body. A doc's NAME is the strongest signal, its one-line DESC a curated
+// summary (next), its BODY the weakest per-hit — but the body carries BM25 term-frequency so a doc that
+// genuinely concentrates a rare word still climbs. IDF scales all three. The spread only ORDERS the tiers;
+// the discriminating magnitude comes from rarity (IDF) and body-density (BM25), not these constants — which
+// is why they sit in flat plateaus rather than being fitted to any case.
+const W_NAME_PREFIX = 8
+const W_NAME_SUBSTR = 5
+const W_DESC = 3
+const W_BODY = 1
+
+// a tiny stoplist of question scaffolding + length-1 tokens, dropped so "how does the … is it …" can't drown
+// the content words. Deliberately small and general — NOT tuned to any benchmark; just the function words a
+// natural-language query carries that match nothing meaningful.
+const STOP = new Set([
+  'the', 'a', 'an', 'and', 'or', 'of', 'to', 'in', 'on', 'is', 'it', 'its', 'as', 'at', 'by', 'for',
+  'how', 'does', 'do', 'what', 'which', 'that', 'this', 'these', 'those', 'with', 'from', 'into', 'are',
+  'be', 'can', 'just', 'them', 'they', 'their', 'so', 'if', 'not', 'no', 'but', 'vs', 'us', 'we', 'you',
+])
+
+// split on non-alphanumeric, lowercase, drop stopwords + length-1 tokens, de-dup.
+export function terms(query: string): string[] {
+  const seen = new Set<string>()
+  for (const w of query.toLowerCase().split(/[^a-z0-9]+/)) {
+    if (w.length > 1 && !STOP.has(w)) seen.add(w)
+  }
+  return [...seen]
+}
+
+// the words of a field, lowercased — used for word-boundary (prefix-of-a-word) matching, which kills
+// short-token pollution (`main` must not match inside `domain`).
+function words(text: string): string[] {
+  return text.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean)
+}
+
+// name match is forward-only (a chosen short field — reverse would let a plural query light up every `spec-*`
+// name); desc/body match bidirectionally so a singular/plural mismatch still hits, reverse gated to words ≥3
+// chars so a stray short word can't swallow a longer term (IDF neutralises the generic words it pulls in).
+function nameMatch(term: string, w: string): boolean { return w.startsWith(term) }
+function textMatch(term: string, w: string): boolean { return w.startsWith(term) || (w.length >= 3 && term.startsWith(w)) }
+
+// classic BM25 tf: frequency with saturation (K1 sets how fast it saturates) and length-normalisation (B),
+// both in a wide insensitive plateau. tf=0 → 0.
+const K1 = 1.2
+const B = 0.4
+function bm25tf(tf: number, len: number, avgLen: number): number {
+  if (tf <= 0) return 0
+  return (tf * (K1 + 1)) / (tf + K1 * (1 - B + (B * len) / (avgLen || 1)))
+}
+
+// the precomputed searchable fields of one doc (built once, reused for df, scoring, and snippet).
+type Fields<T> = { ref: T; name: string; nameWords: string[]; desc: string; descWords: string[]; bodyWords: string[]; snippetText: string }
+
+// the pre-IDF weight a term earns against one doc, picking its single best tier (three fields): a name
+// word-prefix beats a name substring beats a desc hit beats a body hit. Name and desc are short, chosen
+// fields → binary presence; the body carries the BM25-saturated, length-normalised frequency that
+// discriminates the long ties.
+function tierWeight<T>(term: string, n: Fields<T>, avgBodyLen: number): number {
+  if (n.nameWords.some((w) => nameMatch(term, w))) return W_NAME_PREFIX
+  if (n.name.includes(term)) return W_NAME_SUBSTR
+  if (n.descWords.some((w) => textMatch(term, w))) return W_DESC
+  const tf = n.bodyWords.reduce((c, w) => c + (textMatch(term, w) ? 1 : 0), 0)
+  return W_BODY * bm25tf(tf, n.bodyWords.length, avgBodyLen)
+}
+
+// a short single-line window of prose around the FIRST matched term, so a reader sees WHY it matched. Falls
+// back to the desc (then the text head) when only the name matched. Collapsed to one line, ~window chars.
+function snippetFor(text: string, desc: string, qterms: string[], window = 140): string {
+  const flat = text.replace(/\s+/g, ' ').trim()
+  const lower = flat.toLowerCase()
+  let at = -1
+  for (const t of qterms) {
+    const m = lower.match(new RegExp('\\b' + t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')))
+    if (m && m.index !== undefined && (at < 0 || m.index < at)) at = m.index
+  }
+  if (at < 0) {
+    const fb = (desc || flat).replace(/\s+/g, ' ').trim()
+    return fb.length > window ? fb.slice(0, window).trimEnd() + '…' : fb
+  }
+  const start = Math.max(0, at - Math.floor(window / 3))
+  let s = flat.slice(start, start + window).trim()
+  if (start > 0) s = '…' + s
+  if (start + window < flat.length) s = s + '…'
+  return s
+}
+
+// what a caller hands in per doc: the original item (`ref`, returned verbatim) + its three text fields.
+export type RankInput<T> = { ref: T; name: string; desc: string; body: string }
+export type Ranked<T> = { ref: T; score: number; snippet: string }
+
+// the shared entrypoint: sum each query term's best-tier weight × IDF, keep docs hitting ≥1 term, sort by
+// score desc (stable — equal scores keep the caller's pre-sorted input order), cap to `limit` (default 10).
+export function rankDocs<T>(query: string, inputs: RankInput<T>[], opts: { limit?: number } = {}): Ranked<T>[] {
+  const limit = opts.limit ?? 10
+  const qterms = terms(query)
+  if (!qterms.length) return []
+
+  const docs: Fields<T>[] = inputs.map((d) => {
+    const name = d.name.toLowerCase()
+    return {
+      ref: d.ref, name, nameWords: words(name),
+      desc: d.desc.toLowerCase(), descWords: words(d.desc),
+      bodyWords: words(d.body),
+      snippetText: `${d.desc}\n${d.body}`,
+    }
+  })
+
+  // IDF per query term: df = docs containing it (any field), idf = ln(N/df) — a term in every doc scores 0,
+  // a rare one carries the rank. Read from the corpus, not hand-set.
+  const N = docs.length
+  const avgBodyLen = docs.reduce((a, n) => a + n.bodyWords.length, 0) / (N || 1)
+  const idf: Record<string, number> = {}
+  for (const t of qterms) {
+    let df = 0
+    for (const n of docs) {
+      if (n.nameWords.some((w) => nameMatch(t, w)) || n.descWords.some((w) => textMatch(t, w)) || n.bodyWords.some((w) => textMatch(t, w))) df++
+    }
+    idf[t] = df > 0 ? Math.log(N / df) : 0
+  }
+
+  const scored: Ranked<T>[] = []
+  for (const n of docs) {
+    let score = 0
+    for (const t of qterms) score += tierWeight(t, n, avgBodyLen) * idf[t]
+    if (score <= 0) continue
+    scored.push({ ref: n.ref, score: Math.round(score * 100) / 100, snippet: snippetFor(n.snippetText, n.desc, qterms) })
+  }
+  scored.sort((a, b) => b.score - a.score)   // stable: equal scores keep the caller's pre-sorted input order
+  return scored.slice(0, limit)
+}

package/src/resilience.ts

@@ -0,0 +1,41 @@
+import { existsSync } from 'node:fs'
+
+function describe(e: unknown): string {
+  return e instanceof Error ? e.message : String(e)
+}
+
+// run a per-worktree DETAIL read; on a throw, branch on whether the worktree DIRECTORY still exists.
+//   dir gone   → the worktree was genuinely removed mid-read → return null so the caller omits it.
+//   dir present → a flaky detail read (ENOENT race on a sibling file, or a git index/ref lock under a
+//                 concurrent merge) → return the caller's `degraded` row so an EXISTING worktree is NEVER
+//                 dropped from the board. read-failure != non-existence.
+// `dir` is the worktree path (the existence fact). Accepts a sync OR async fn — resolveLayout's overlay
+// read is async, listSessions' row read is sync; `degraded` is a sync raw-facts fallback.
+export async function guardWorktree<T>(dir: string, fn: () => T | Promise<T>, degraded: () => T): Promise<T | null> {
+  try {
+    return await fn()
+  } catch (e) {
+    if (!existsSync(dir)) {
+      console.warn(`spec-cli: worktree ${dir} gone from disk (removed mid-read), omitting: ${describe(e)}`)
+      return null
+    }
+    console.warn(`spec-cli: worktree ${dir} detail-read failed (transient/lock); serving degraded row: ${describe(e)}`)
+    return degraded()
+  }
+}
+
+// the last-resort process net: log an otherwise-fatal async throw and KEEP SERVING. Registering these
+// handlers is itself what overrides Node's default "print the stack and exit" — so the backend rides out
+// a transient race it didn't anticipate instead of dropping the public port. Idempotent (guarded) so a
+// double-install in one process can't stack duplicate handlers.
+let guardsInstalled = false
+export function installProcessGuards(): void {
+  if (guardsInstalled) return
+  guardsInstalled = true
+  process.on('unhandledRejection', (reason) => {
+    console.error(`spec-cli: unhandledRejection kept the server alive (investigate): ${reason instanceof Error ? reason.stack : describe(reason)}`)
+  })
+  process.on('uncaughtException', (err) => {
+    console.error(`spec-cli: uncaughtException kept the server alive (investigate): ${err?.stack || describe(err)}`)
+  })
+}

package/src/search.bench.mjs

@@ -0,0 +1,47 @@
+// throwaway benchmark harness for spec-search — drives the REAL `spex search --json` over the 15 holdout
+// cases and reports recall@1, recall@3, MRR. Not shipped/committed; the cases live in the node's yatsu.md.
+import { execFileSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+const BIN = join(dirname(fileURLToPath(import.meta.url)), '..', 'bin', 'spex.mjs')
+
+const CASES = [
+  ['exit-cleanup', "does /exit remove the session's worktree and tmux, or just orphan them?", ['session-console']],
+  ['owner-at-edit', 'how does an agent learn which spec governs a file it just edited?', ['injected-context/spec-of-file']],
+  ['main-block', 'what stops an agent from committing or merging straight into main?', ['main-guard']],
+  ['main-escape', 'the escape hatch that lets seeding run on the main branch', ['main-guard']],
+  ['inter-agent-msg', 'how do two running agent sessions send messages to each other?', ['agent-reply-channel', 'comms']],
+  ['search-hidden-node', 'keyboard shortcut to find a node hidden inside a collapsed subtree', ['keyboard-nav']],
+  ['session-order', 'how is the order of sessions in the session list decided?', ['session-reorder']],
+  ['node-status', 'what makes a node show as pending vs active vs merged vs drift?', ['spec-node-states']],
+  ['dashboard-backend', 'how does the dashboard reach the backend API and on which port?', ['api-endpoint']],
+  ['loss-measured', "how is a node's loss measured and its scenarios scored?", ['yatsu-core']],
+  ['launch-injection', "what context gets injected into a freshly launched agent's prompt?", ['injected-context']],
+  ['read-before-code', 'the one-shot nudge that makes an agent read its spec before touching code', ['injected-context/spec-first']],
+  ['hot-reload', 'zero-downtime backend reload without dropping connections', ['supervisor']],
+  ['many-owners', 'can several specs own the same code file, and what happens if too many do?', ['governed-related']],
+  ['active-spec-search', 'an injected sub-agent that searches specs for the agent, the spec analog of Explore', ['spec-scout']],
+]
+
+let r1 = 0, r3 = 0, mrr = 0
+const rows = []
+for (const [name, query, expect] of CASES) {
+  const out = execFileSync('node', [BIN, 'search', query, '--json', '--limit', '10'], { encoding: 'utf8' })
+  const results = JSON.parse(out)
+  const ids = results.map((x) => x.id)
+  const rank = ids.findIndex((id) => expect.includes(id)) + 1   // 1-based; 0 = not found
+  const hit1 = rank === 1
+  const hit3 = rank >= 1 && rank <= 3
+  if (hit1) r1++
+  if (hit3) r3++
+  if (rank >= 1) mrr += 1 / rank
+  rows.push({ name, rank: rank || '—', top: ids.slice(0, 3).join(', '), expect: expect.join('|') })
+}
+const n = CASES.length
+for (const row of rows) {
+  const mark = row.rank === 1 ? '✓1' : (typeof row.rank === 'number' && row.rank <= 3 ? '·3' : (row.rank === '—' ? '✗ ' : `·${row.rank}`))
+  console.log(`${mark} ${row.name.padEnd(20)} want=${row.expect.padEnd(22)} rank=${String(row.rank).padStart(2)}  top3: ${row.top}`)
+}
+console.log('—'.repeat(72))
+console.log(`recall@1 = ${r1}/${n} = ${(r1 / n).toFixed(3)}   recall@3 = ${r3}/${n} = ${(r3 / n).toFixed(3)}   MRR = ${(mrr / n).toFixed(3)}`)

package/src/search.ts

@@ -0,0 +1,24 @@
+import { loadSpecsLite } from './specs.js'
+import { rankDocs, type RankInput } from './ranker.js'
+
+export type SearchResult = { id: string; title: string; path: string; score: number; snippet: string }
+export type SearchStats = { nodes: number; tokens: number; ms: number }
+
+export async function searchSpecs(query: string, opts: { limit?: number; onStats?: (s: SearchStats) => void } = {}): Promise<SearchResult[]> {
+  const t0 = performance.now()
+  // pre-sort by (shorter id, then id): rankDocs sorts stably, so for equal-scored nodes this IS the tiebreak.
+  const nodes = loadSpecsLite()
+    .slice()
+    .sort((a, b) => a.id.length - b.id.length || a.id.localeCompare(b.id))
+  const inputs: RankInput<(typeof nodes)[number]>[] = nodes.map((s) => ({
+    ref: s, name: `${s.title} ${s.id}`, desc: s.desc, body: s.body,
+  }))
+  const out = rankDocs(query, inputs, { limit: opts.limit }).map((r) => ({
+    id: r.ref.id, title: r.ref.title, path: r.ref.path, score: r.score, snippet: r.snippet,
+  }))
+  if (opts.onStats) {
+    const tokens = inputs.reduce((a, i) => a + `${i.name} ${i.desc} ${i.body}`.split(/[^a-z0-9]+/i).filter(Boolean).length, 0)
+    opts.onStats({ nodes: inputs.length, tokens, ms: performance.now() - t0 })
+  }
+  return out
+}

package/src/self.ts

@@ -0,0 +1,256 @@
+// @@@ spex self - the SELF-DIAGNOSIS surface (spec-cli/self). When a user launches their OWN claude/codex
+// with no SpexCode process in the launch, the workflow reaches that agent only through the files
+// materialize() renders (the manifest in the global store; the in-tree contract blocks + hook shims + codex
+// trust). `self` answers "is this agent actually governed, or silently running free?" — diagnosing that
+// materialized contract per LAYER, looping the same HARNESSES adapter materialize renders through (so claude
+// AND codex are covered with no hardcoded paths). It catches the SILENT failure: a shim whose handler is
+// missing, a PATH that can't resolve `spex`, a contract that never landed. Read-only today: `doctor`,
+// `contract` (print the surface:system text any agent reads), `env`. install/uninstall are STAGED (noteStaged).
+import { existsSync, readFileSync, accessSync, constants } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { execFileSync } from 'node:child_process'
+import { homedir } from 'node:os'
+import { loadSystemConfig } from './specs.js'
+import { runtimeRoot, envSessionId, readAliasedRawRecord } from './layout.js'
+
+// this file lives at <pkgRoot>/src/self.ts, so `..` is the package root — the same derivation init.ts/
+// materialize.ts use (never a hardcoded repo path), so the git-hook template lookup survives a relocated install.
+const PKG_ROOT = fileURLToPath(new URL('..', import.meta.url))
+
+// run a git query in `dir`, swallowing git's own stderr — a non-repo returns null (the absence IS the signal).
+function git(dir: string, args: string[]): string | null {
+  try { return execFileSync('git', ['-C', dir, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() }
+  catch { return null }
+}
+function repoRoot(dir: string): string | null { return git(dir, ['rev-parse', '--show-toplevel']) }
+function commonHooksDir(dir: string): string | null {
+  const common = git(dir, ['rev-parse', '--path-format=absolute', '--git-common-dir'])
+  return common ? join(common, 'hooks') : null
+}
+const read = (f: string): string => { try { return readFileSync(f, 'utf8') } catch { return '' } }
+
+// @@@ contractText - the layer-2 payload: the composed `surface:system` bodies, the SAME join materialize()
+// folds into each harness's contract file — so a BYOA agent reads byte-identical guidance.
+function contractText(): { names: string[]; body: string } {
+  let cfgs: { name: string; body: string }[] = []
+  try { cfgs = loadSystemConfig().map((c) => ({ name: c.name, body: c.body })) } catch { /* tree-less cwd → empty */ }
+  return { names: cfgs.map((c) => c.name), body: cfgs.map((c) => c.body.trim()).filter(Boolean).join('\n\n') }
+}
+
+// compare an installed git hook to the shipped template: spexcode (current) | stale (older SpexCode, re-run
+// `spex init`) | foreign (a real conflict) | missing. The stale/foreign split keeps a slightly-behind repo
+// from reading as a CONFLICT.
+type HookState = 'spexcode' | 'stale' | 'foreign' | 'missing'
+function hookState(hooksDir: string | null, name: string): HookState {
+  if (!hooksDir) return 'missing'
+  const installed = join(hooksDir, name)
+  if (!existsSync(installed)) return 'missing'
+  const body = read(installed)
+  try { if (body === readFileSync(join(PKG_ROOT, 'templates', 'hooks', name), 'utf8')) return 'spexcode' } catch { /* fall through */ }
+  return /SpexCode/.test(body) ? 'stale' : 'foreign'
+}
+
+// does `bin` resolve to an executable on the inherited PATH? Returns the resolving path, or null. This is the
+// precondition behind a dozen confusing symptoms — a session shell whose PATH misses the global bin dir gets
+// `command not found` for spex/codex/claude (npm's global prefix landing off-PATH).
+function resolveOnPath(bin: string): string | null {
+  for (const d of (process.env.PATH || '').split(':')) {
+    if (!d) continue
+    const p = join(d, bin)
+    try { accessSync(p, constants.X_OK); return p } catch { /* not here */ }
+  }
+  return null
+}
+
+// parse the materialized manifest (TAB lines: event<TAB>order<TAB>block<TAB>script) → the unique handler
+// scripts, repo-relative. The dispatcher runs each as bash "<proj>/<script>".
+function manifestScripts(text: string): string[] {
+  const out = new Set<string>()
+  for (const line of text.split('\n')) {
+    const f = line.split('\t')
+    if (f.length >= 4 && f[3]) out.add(f[3])
+  }
+  return [...out]
+}
+
+// ping the backend (apiBase) with a short timeout so doctor never hangs on a dead/wrong SPEXCODE_API_URL.
+async function backendReachable(): Promise<{ base: string; up: boolean }> {
+  let base = 'http://127.0.0.1:8787'
+  try { base = (await import('./sessions.js')).apiBase() } catch { /* keep default */ }
+  const ctrl = new AbortController()
+  const t = setTimeout(() => ctrl.abort(), 800)
+  try { return { base, up: (await fetch(`${base}/api/sessions`, { signal: ctrl.signal })).ok } }
+  catch { return { base, up: false } }
+  finally { clearTimeout(t) }
+}
+
+// the headline: a per-layer report of whether the SpexCode workflow truly reaches THIS agent.
+async function doctor(): Promise<number> {
+  const cwd = process.cwd()
+  const root = repoRoot(cwd)
+  const base = root ?? cwd   // the contract files (CLAUDE.md/AGENTS.md) + hook shims live at the worktree ROOT — anchor every probe here
+  const adopted = existsSync(join(base, '.spec')) && existsSync(join(base, 'spexcode.json'))
+  // managed = THIS agent's own session is a GOVERNED record in the global store (the dashboard launcher set
+  // governed:true). That governed flag is the source of truth the old worktree `.session` presence only implied
+  // (see [[state]]); resolve the agent's id from its env and read the record — a self-launched BYOA agent has none.
+  const ownId = envSessionId()
+  const managed = !!(ownId && readAliasedRawRecord(ownId)?.governed)
+  const hooksDir = commonHooksDir(cwd)
+  const { names, body } = contractText()
+
+  const { HARNESSES } = await import('./harness.js')
+  type H = typeof HARNESSES[number]
+  // which harness is the RUNNING agent? the one whose session env var is set in this process.
+  const runningHarness: H | undefined = HARNESSES.find((h) => process.env[h.sessionEnvVar])
+
+  const L: string[] = []
+  const line = (k: string, v: string) => L.push(`  ${k.padEnd(16)}: ${v}`)
+  L.push('spex self doctor — how the SpexCode workflow reaches this agent\n')
+
+  L.push('Agent')
+  line('detected', runningHarness ? `${runningHarness.id}  (${runningHarness.sessionEnvVar}=${process.env[runningHarness.sessionEnvVar]})` : 'none detected (no harness session env var set)')
+  L.push('\nRepo')
+  line('spex-adopted', adopted ? 'yes (.spec/ + spexcode.json)' : root ? 'no — run `spex init`' : 'not a git repo')
+  line('root', base)
+  line('mode', managed ? 'managed worktree (backend-launched session)' : 'standalone repo (bring-your-own-agent)')
+
+  // --- preconditions: nothing downstream fires without these ---
+  L.push('\nPreconditions (without these nothing downstream fires)')
+  for (const bin of ['spex', 'claude', 'codex']) {
+    const at = resolveOnPath(bin)
+    line(`PATH ${bin}`, at ? `resolves (${at})` : 'NOT on PATH — a session shell will hit `command not found`')
+  }
+  const codexHome = process.env.CODEX_HOME || join(homedir(), '.codex')
+  const codexCfg = read(join(codexHome, 'config.toml'))
+  const codexAuth = existsSync(join(codexHome, 'auth.json'))
+  line('codex auth', (/base_url|model_provider/.test(codexCfg) && codexAuth) ? `present (${codexHome})` : `incomplete (${codexHome}: config provider/base_url ${/base_url|model_provider/.test(codexCfg) ? 'ok' : 'MISSING'}, auth.json ${codexAuth ? 'ok' : 'MISSING'})`)
+
+  // --- git-hook floor: enforces for ANY agent/harness ---
+  const preCommit = hookState(hooksDir, 'pre-commit')
+  const prepare = hookState(hooksDir, 'prepare-commit-msg')
+  const hb = (s: HookState) => s === 'spexcode' ? 'installed (SpexCode)' : s === 'stale' ? 'OUTDATED (older SpexCode — re-run `spex init`)' : s === 'foreign' ? 'PRESENT but not SpexCode\'s (a foreign hook holds the slot)' : 'MISSING'
+  L.push('\nLayer 1 — git-hook floor (enforces for ANY agent)')
+  line('pre-commit', hb(preCommit))
+  line('prepare-cmsg', hb(prepare))
+  line('hooks dir', hooksDir ?? '—')
+
+  // --- contract: the surface:system block landed in each harness's contract file ---
+  L.push('\nLayer 2 — contract (surface:system text)')
+  line('nodes', names.length ? names.join(', ') : 'none — contract is empty')
+  for (const h of HARNESSES) {
+    const present = h.contractFiles(base).every((f) => /<!--\s*spexcode:start\s*-->/.test(read(f)))
+    line(`in ${h.id}`, present ? `block present (${h.contractFiles(base).map((f) => f.replace(base + '/', '')).join(', ')})` : 'NOT landed — run `spex self contract` / materialize')
+  }
+  line('view', 'spex self contract')
+
+  // --- hooks: the shim → dispatch, the manifest, and EVERY handler readable in the worktree ---
+  L.push('\nLayer 3 — hooks (shim → dispatch · manifest · handler-existence)')
+  for (const h of HARNESSES) {
+    const shim = read(h.shimFile(base))
+    line(`${h.id} shim`, /dispatch\.sh/.test(shim) ? `wired (${h.shimFile(base).replace(base + '/', '')})` : 'NOT wired (no dispatch shim)')
+  }
+  let manifestText = ''
+  try { manifestText = read(join(runtimeRoot(base), 'hooks-manifest')) } catch { /* non-git / no store */ }
+  if (!manifestText) {
+    line('manifest', 'MISSING from the global store — materialize never ran (hooks fire but find no manifest)')
+  } else {
+    const scripts = manifestScripts(manifestText)
+    const missing = scripts.filter((s) => !existsSync(join(base, s)))
+    line('manifest', `${scripts.length} handler(s) in the global store`)
+    line('handlers', missing.length === 0 ? 'all readable in the worktree' : `${missing.length} MISSING in the worktree → those hooks SILENTLY NO-OP:`)
+    for (const m of missing) L.push(`      ✗ ${m}`)
+  }
+  // codex trust
+  const trustPresent = codexCfg.includes(`# spexcode:trust:${base}`)
+  line('codex trust', trustPresent ? 'trusted_hash block present in ~/.codex/config.toml' : 'absent (codex self-launch would prompt for trust)')
+
+  // --- backend: orchestration; absent is normal for BYOA ---
+  const { base: backendBase, up } = await backendReachable()
+  L.push('\nLayer 4 — session orchestration (backend-only: dispatch · queue · comms)')
+  line('backend', up ? `reachable at ${backendBase}` : `not reachable at ${backendBase}`)
+
+  // --- verdict ---
+  L.push('\nCoverage verdict')
+  line('preconditions', resolveOnPath('spex') ? 'spex resolves' : 'BLOCKED — spex not on PATH (fix first)')
+  line('layer 1', preCommit === 'spexcode' ? 'ENFORCED' : preCommit === 'stale' ? 'ENFORCED (older — update with `spex init`)' : preCommit === 'foreign' ? 'CONFLICT (a non-SpexCode hook holds the slot)' : 'ABSENT')
+  line('layer 2', body.length === 0 ? 'ABSENT (no contract)' : 'see per-harness above')
+  line('layer 3', manifestText ? 'see handler-existence above' : 'ABSENT (no manifest — agent ungoverned)')
+  line('layer 4', up ? 'present' : managed ? 'EXPECTED but backend down' : 'absent (normal for bring-your-own-agent)')
+
+  // --- footprint: every artifact Spex wrote here, + any slot held by something not ours ---
+  L.push('\nFootprint (what Spex wrote into this environment)')
+  const foot: string[] = []
+  const ours = (s: HookState) => s === 'spexcode' || s === 'stale'
+  if (ours(preCommit)) foot.push(`${join(hooksDir!, 'pre-commit')}  (SpexCode${preCommit === 'stale' ? ', outdated' : ''})`)
+  if (ours(prepare)) foot.push(`${join(hooksDir!, 'prepare-commit-msg')}  (SpexCode${prepare === 'stale' ? ', outdated' : ''})`)
+  for (const h of HARNESSES) {
+    if (/dispatch\.sh/.test(read(h.shimFile(base)))) foot.push(`${h.shimFile(base)}  (${h.id} hook shim)`)
+    for (const f of h.contractFiles(base)) if (/<!--\s*spexcode:start\s*-->/.test(read(f))) foot.push(`${f}  (${h.id} contract block)`)
+  }
+  if (trustPresent) foot.push(`${join(codexHome, 'config.toml')}  (codex trust block)`)
+  L.push(foot.length ? foot.map((f) => `  ${f}`).join('\n') : '  (nothing — Spex has written no files into this environment)')
+  const collisions = [preCommit, prepare].filter((s) => s === 'foreign').length
+  line('\ncollisions', collisions ? `${collisions} hook slot(s) held by a non-SpexCode hook` : 'none')
+
+  console.log(L.join('\n'))
+  return 0
+}
+
+// print the layer-2 contract so any agent/harness can be handed exactly what materialize folds in.
+function contract(): number {
+  const { body } = contractText()
+  if (!body) { console.error('spex self: no surface:system nodes in this .spec tree — the contract is empty.'); return 0 }
+  console.log(body)
+  return 0
+}
+
+// raw environment facts doctor reasons over — for debugging the diagnosis itself.
+function env(): number {
+  const cwd = process.cwd()
+  const facts: Record<string, string> = {
+    cwd,
+    repoRoot: repoRoot(cwd) ?? '(not a git repo)',
+    branch: git(cwd, ['rev-parse', '--abbrev-ref', 'HEAD']) ?? '—',
+    node: process.version,
+    CLAUDE_CODE_SESSION_ID: process.env.CLAUDE_CODE_SESSION_ID ?? '',
+    CODEX_THREAD_ID: process.env.CODEX_THREAD_ID ?? '',
+    SPEXCODE_API_URL: process.env.SPEXCODE_API_URL ?? '(default :8787)',
+    'PATH spex': resolveOnPath('spex') ?? '(not on PATH)',
+    tmux: process.env.TMUX ? 'inside tmux' : 'no',
+  }
+  for (const [k, v] of Object.entries(facts)) console.log(`${k.padEnd(24)}: ${v}`)
+  return 0
+}
+
+// install/uninstall are STAGED: wiring layer-3 hooks into a standalone repo is only SAFE once the hooks
+// detect a missing managed session and degrade. So the diagnosis ships first; the installer lands behind it.
+function noteStaged(verb: string): number {
+  console.error(`spex self ${verb} is not available yet — it is staged behind the hook-degradation prerequisite
+(the live hooks must detect a missing managed session and degrade before they can be safely wired into your
+own agent's config). Meanwhile: \`spex self doctor\` reports your coverage, and \`spex self contract\` prints
+the workflow text you can hand any agent.`)
+  return 2
+}
+
+function usage(): number {
+  console.error(`spex self — diagnose how the SpexCode workflow reaches your agent
+  doctor       per-layer report: preconditions · git-hook floor · contract · hooks(+handlers) · backend · footprint  (default)
+  contract     print the surface:system contract text (hand it to any agent)
+  env          raw environment facts the diagnosis reads
+  install      [staged] wire the materialized contract + hooks into your agent  (--agent claude, --minimal)
+  uninstall    [staged] reverse exactly what install wrote`)
+  return 0
+}
+
+export async function runSelf(args: string[]): Promise<number> {
+  switch (args[0] ?? 'doctor') {
+    case 'doctor': return await doctor()
+    case 'contract': return contract()
+    case 'env': return env()
+    case 'install': return noteStaged('install')
+    case 'uninstall': return noteStaged('uninstall')
+    case 'help': case '--help': case '-h': return usage()
+    default: console.error(`spex self: unknown subcommand "${args[0]}"`); usage(); return 2
+  }
+}