spexcode 0.2.3 → 0.2.5

package/README.md

@@ -14,9 +14,9 @@
 Spec-driven development with AI agents in the loop. SpexCode keeps a versioned tree of specs inside
 your git repo, links every spec to the code it governs, and runs a session manager that dispatches
 coding agents into isolated worktrees. You review and merge; the tool keeps intent and
-implementation from drifting apart. (All screenshots below are this very repo on its own board.)
+implementation from drifting apart.
 
-[![This repo's spec tree, grown from its own git history](docs/spec-tree-hero.gif)](https://spexcode.net/assets/spec-tree-growth.mp4)
+[![Watch: this repo's spec tree grow from its git history](docs/spec-tree-poster.jpg)](https://spexcode.net/assets/spec-tree-growth.mp4)
 
 <sub>▶ This repo's own spec tree, replayed from its git history — 160 spec nodes growing over three weeks. Click for the [full video](https://spexcode.net/assets/spec-tree-growth.mp4).</sub>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spexcode",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "type": "module",
   "description": "SpexCode — a spec-driven, self-developing dev tool. The `spex` CLI + spec server reads the .spec tree and its git history, and serves the dashboard.",
   "license": "MIT",

package/spec-cli/bin/spex.mjs

@@ -35,20 +35,23 @@ if (conflicted.length) {
   console.error('spex executes this TypeScript directly (no build step); resolve the merge, then retry. (exit 75)')
   process.exit(75)
 }
-// tsx lives in spec-cli/node_modules in the dev monorepo, but npm may hoist it above the installed
-// `spexcode` package in a real consumer project. Try local candidates first, then let Node resolve upward
-// from spec-cli so project-local and global installs work the same way.
-const tsxCandidates = [join(pkg, 'node_modules', '.bin', 'tsx'), join(pkg, '..', 'node_modules', '.bin', 'tsx')]
-function resolveTsx() {
-  const local = tsxCandidates.find(existsSync)
-  if (local) return local
+// @@@ cross-platform tsx resolution ([[platform-support]]) - resolve tsx's JS ENTRY (dist/cli.mjs) with
+// Node's own resolver from spec-cli, then run it through THIS node binary (process.execPath). tsx may live
+// in spec-cli/node_modules (dev) or be hoisted above the installed `spexcode` package (a real consumer
+// project) — one resolver covers both without hardcoded consumer paths. We deliberately never spawn the
+// `.bin/tsx` shim, nor a `.mjs` directly: on Windows the shim is an extensionless sh script and the `.mjs`
+// leans on a shebang, neither of which `child_process.spawn` can execute — that is the #37 crash
+// (`spawn …\node_modules\.bin\tsx ENOENT`) of `spex init`. `node dist/cli.mjs …` is shell-free and identical
+// on every OS.
+function resolveTsxCli() {
   try {
     const req = createRequire(join(pkg, 'package.json'))
     return join(dirname(req.resolve('tsx/package.json')), 'dist', 'cli.mjs')
   } catch {
-    return tsxCandidates[0]
+    console.error('spex: cannot find the `tsx` runtime this package needs — run `npm install` in the SpexCode package, then retry.')
+    process.exit(69)
   }
 }
-const tsx = resolveTsx()
-spawn(tsx, [cli, ...process.argv.slice(2)], { stdio: 'inherit' })
+const tsxCli = resolveTsxCli()
+spawn(process.execPath, [tsxCli, cli, ...process.argv.slice(2)], { stdio: 'inherit' })
   .on('exit', (code) => process.exit(code ?? 0))

package/spec-cli/hooks/harness.sh

@@ -99,13 +99,39 @@ hp_store_dir() {
   printf '%s' "$direct"
 }
 
-# the deterministic content fingerprint of the EDITABLE config roots (.config + config md/sh) — the gate's
-# "did the .config move?" signal. Run with cwd = the project. ONE definition: the dispatch.sh gate sources this
-# and materialize.ts shells to it, so the gate and the renderer can NEVER disagree on what "changed" means (the
-# two used to inline this pipeline verbatim, each commenting the other "MUST match").
+# the RENDERER's own version fingerprint — the toolchain side of the gate key. The rendered artifacts are a
+# function of (config content, renderer), so a TOOLCHAIN update must move the key too, or an updated deploy
+# never self-heals its stale contract/shims/manifest until someone happens to edit .config (the field lesson:
+# a toolchain update does NOT self-heal). A source checkout answers with the git TREE hash of the package dir
+# (moves exactly when the toolchain's content moves, not on every repo commit); an npm install (no .git)
+# answers with the package.json hash (npm bumps the version). env-stripped git — a git hook's exported
+# GIT_DIR must not misdirect repo discovery (same rule as git.ts's git()).
+SPEXCODE_HP_PKG="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." 2>/dev/null && pwd)"
+hp_renderer_version() {
+  ( cd "$SPEXCODE_HP_PKG" 2>/dev/null && env -u GIT_DIR -u GIT_INDEX_FILE git rev-parse 'HEAD:./' 2>/dev/null ) \
+    || sha256sum "$SPEXCODE_HP_PKG/package.json" 2>/dev/null | cut -d' ' -f1 \
+    || echo unversioned
+}
+
+# the deterministic content fingerprint of EVERYTHING the render is a function of: the EDITABLE config
+# roots (.config + config md/sh), the PERSISTED POLICY files (the MAIN checkout's spexcode.json +
+# spexcode.local.json — the `harnesses` set and `render` vote materialize reads via readConfig(mainCheckout)),
+# and the renderer version above — the gate's "did anything the render depends on move?" signal. The policy
+# files are in the key so a harness-selection or render-policy edit SELF-HEALS on the very next hook event
+# (before this, narrowing `harnesses` left the deselected harness's stale artifacts in place until an
+# unrelated .config edit happened to fire the gate — [[harness-select]]). Run with cwd = the project. ONE
+# definition: the dispatch.sh gate sources this and materialize.ts shells to it, so the gate and the renderer
+# can NEVER disagree on what "changed" means (the two used to inline this pipeline verbatim, each commenting
+# the other "MUST match"). env-stripped git, same rule as hp_renderer_version.
 hp_config_hash() {
-  find .spec/*/.config .spec/*/config \( -name '*.md' -o -name '*.sh' \) -type f -print0 2>/dev/null \
-    | sort -z | xargs -0 cat 2>/dev/null | sha256sum | cut -d' ' -f1
+  local gcd
+  gcd=$(env -u GIT_DIR -u GIT_INDEX_FILE git rev-parse --path-format=absolute --git-common-dir 2>/dev/null) \
+    || gcd=$(realpath "$(env -u GIT_DIR -u GIT_INDEX_FILE git rev-parse --git-common-dir 2>/dev/null)" 2>/dev/null)
+  { hp_renderer_version
+    find .spec/*/.config .spec/*/config \( -name '*.md' -o -name '*.sh' \) -type f -print0 2>/dev/null \
+      | sort -z | xargs -0 cat 2>/dev/null
+    [ -n "$gcd" ] && cat "$(dirname "$gcd")/spexcode.json" "$(dirname "$gcd")/spexcode.local.json" 2>/dev/null
+  } | sha256sum | cut -d' ' -f1
 }
 
 # the tool a payload is about to run / just ran (harness-agnostic field name).

package/spec-cli/src/board.ts

@@ -4,6 +4,7 @@ import { resolveLayout, readConfig } from './layout.js'
 import { listSessions } from './sessions.js'
 import { repoRoot, driftIndex, historyIndex } from './git.js'
 import { residentForgeState } from '../../spec-forge/src/resident.js'
+import { resolveForgeHost } from '../../spec-forge/src/drivers.js'
 import { mergedIssues } from './issues.js'
 import { evalContext, evalTimeline } from '../../spec-yatsu/src/evaltab.js'
 import { yatsuNodesAsync } from '../../spec-yatsu/src/yatsu.js'
@@ -109,7 +110,7 @@ export async function buildBoard() {
   // empty absent a forge, so the fold then carries the local slice alone. Sorted open-first, newest first.
   const isOpen = (i: { status: string }) => i.status === 'open'
   const issuesByNode: Record<string, ReturnType<typeof mergedIssues>> = {}
-  for (const issue of mergedIssues({ host: 'github', state: residentForgeState() }, nodes.map((n) => n.id)))
+  for (const issue of mergedIssues({ host: resolveForgeHost(), state: residentForgeState() }, nodes.map((n) => n.id)))
     for (const nid of issue.nodes) (issuesByNode[nid] ??= []).push(issue)
   for (const n of nodes) {
     const issues = issuesByNode[n.id]

package/spec-cli/src/boardCache.ts

@@ -18,6 +18,18 @@ export type Board = Awaited<ReturnType<typeof buildBoard>>
 // genuinely-degraded hot path shouts while an ordinary cold start stays quiet-ish.
 const BUDGET_MS = Number(process.env.SPEXCODE_BOARD_BUDGET_MS || 1500)
 
+// a build that NEVER settles is a different animal from a slow one: `inflight` clears only in the finally
+// below, so a never-settling buildBoard() would pin the single-flight forever — every later read (even of a
+// perfectly good cached board) short-circuits into the pinned promise before `valid` is consulted,
+// invalidation can't help, no log ever fires, and only a restart cures it (the live wedge: hung git
+// children → /api/board 503 forever, silently). So the build races a generous watchdog that REJECTS loudly;
+// the rejection flows through the SAME finally → inflight clears → the next read retries fresh. Sitting at
+// the single-flight boundary, this one wall bounds every never-settle cause — including ones with no child
+// process at all (fs/promises under libuv threadpool starvation); git.ts's per-child timeouts merely make
+// the common cause die sooner. Generous: well above the slowest legitimate cold build, so it only ever
+// fires on a genuine wedge.
+const BUILD_TIMEOUT_MS = Number(process.env.SPEXCODE_BOARD_BUILD_TIMEOUT_MS || 120000)
+
 let cached: Board | null = null   // last completed build; served while `valid`
 let cachedJson: string | null = null   // JSON.stringify(cached), serialized ONCE per build (see getBoardJson)
 let valid = false
@@ -42,13 +54,27 @@ export function getBoard(): Promise<Board> {
   const startGen = gen
   const p = (async () => {
     const t0 = Date.now()
+    let watchdog: ReturnType<typeof setTimeout> | undefined
     try {
-      const board = await buildBoard()
+      const board = await Promise.race([
+        buildBoard(),
+        // the race consumes the loser's eventual settlement, so an abandoned build that fails later
+        // can't surface as an unhandled rejection; unref'd so a pending watchdog never holds a one-shot
+        // CLI process open.
+        new Promise<never>((_, reject) => {
+          watchdog = setTimeout(() => {
+            console.warn(`spec-cli: /api/board build did not settle within ${BUILD_TIMEOUT_MS}ms — wedged build abandoned so the next read can retry`)
+            reject(new Error(`board build did not settle within ${BUILD_TIMEOUT_MS}ms`))
+          }, BUILD_TIMEOUT_MS)
+          watchdog.unref?.()
+        }),
+      ])
       cached = board
       cachedJson = null   // invalidate the memoized serialization; re-serialized lazily on first read
       valid = gen === startGen
       return board
     } finally {
+      clearTimeout(watchdog)
       const ms = Date.now() - t0
       if (ms > BUDGET_MS) console.warn(`spec-cli: /api/board build took ${ms}ms (budget ${BUDGET_MS}ms) — hot path is slow`)
       inflight = null

package/spec-cli/src/boardStream.ts

@@ -89,10 +89,11 @@ function fireChanged(): void {
 }
 
 // ---- event source 0: an EXPLICIT server-side nudge ----
-// for the one mutation the watchers structurally cannot see: /rename writes the worktree's `.session`
-// (the name's ONE home, outside the watched store — [[session-rename]]). The route calls this instead of
-// double-writing the name into the store: a notification problem gets a notification solution, never a
-// second data home. Same debounced funnel as every other source.
+// for a server-side mutation that must show instantly regardless of watcher health: /rename writes the
+// session's global record (`session.json` — [[session-rename]]), which lives INSIDE the watched store, so
+// source 1 normally sees the write too. The explicit route call stays because that fs watch is best-effort
+// (it can fail to attach), and the nudge makes the sub-second rename guarantee deterministic. Same
+// debounced funnel as every other source.
 export const notifyBoardChanged = (): void => fireChanged()
 
 // ---- event source 1: the session store (lifecycle status writes) ----

package/spec-cli/src/cli.ts

@@ -52,7 +52,7 @@ function flushExit(code = 0): Promise<never> {
 }
 const has = (name: string) => process.argv.includes(`--${name}`)
 // bare positionals after argv index `from`, skipping flags and their values (selectors for ls/watch).
-const VALUE_FLAGS = new Set(['--status', '--as', '--interval', '--propose', '--note', '--node', '--prompt', '--timeout', '--reason', '--out', '--password', '--tls-cert', '--tls-key', '--harness', '--launcher', '--harness-session', '--port', '--api', '--api-port', '--host', '--preset', '--limit', '--session', '--depth'])
+const VALUE_FLAGS = new Set(['--status', '--as', '--interval', '--propose', '--note', '--node', '--prompt', '--prompt-file', '--timeout', '--reason', '--out', '--password', '--tls-cert', '--tls-key', '--harness', '--launcher', '--harness-session', '--port', '--api', '--api-port', '--host', '--preset', '--render', '--limit', '--session', '--depth'])
 function positionals(from: number): string[] {
   const out: string[] = []
   for (let i = from; i < process.argv.length; i++) {
@@ -66,7 +66,8 @@ function positionals(from: number): string[] {
 // After a successful launch, nudge the caller to actually MONITOR the session — launch-then-forget is a real
 // gap (a supervisor or human launches and then never watches, so a review/failure goes unnoticed). Goes to
 // STDERR so the JSON on stdout (which callers parse) stays clean; keyed to whoever's calling — a supervising
-// agent has an own-session id, a human at a terminal does not.
+// agent has an own-session id, a human at a terminal does not. The hint also names the COMM channel
+// (`spex send`) — field-tested gap: callers who couldn't find it reached for raw tmux keystrokes instead.
 async function launchMonitorReminder(id: string): Promise<void> {
   const { ownSessionId } = await import('./sessions.js')
   const agent = ownSessionId()
@@ -78,6 +79,7 @@ async function launchMonitorReminder(id: string): Promise<void> {
   } else {
     console.error(`  \`spex watch\` — the live stream of actionable session transitions (or \`spex wait ${id}\` to block on this one)`)
   }
+  console.error(`  talk to it: \`spex send ${id} "<msg>"\` — never raw tmux keystrokes`)
 }
 
 const greeted = new Set<string>()
@@ -163,6 +165,11 @@ if (cmd && cmd !== 'help' && (has('help') || process.argv.includes('-h'))) {
 }
 
 if (cmd === 'serve') {
+  // fail loud, not cryptic ([[platform-support]]): serve IS the entry to the session runtime, which needs a
+  // POSIX host (tmux/bash/unix-sockets). On a non-POSIX host (native Windows) point at WSL2 and exit here,
+  // before importing the supervisor spawns tsx into a downstream ENOENT.
+  const { assertSessionRuntime } = await import('./runtime-guard.js')
+  assertSessionRuntime()
   // the supervisor owns the public port and runs index.ts as a child for zero-downtime reloads; it
   // (not `tsx watch`) is what watches spec-cli/src, so the package `serve` script must NOT use --watch.
   // --port is sugar over the PORT env supervise.ts reads — set BEFORE importing so it takes effect. This
@@ -197,7 +204,7 @@ if (cmd === 'serve') {
   const { guideText } = await import('./guide.js')
   const text = guideText(process.argv[3])
   if (text === null) {
-    console.error(`spex guide: no topic '${process.argv[3]}'. Topics: spec, yatsu, config. Run \`spex guide\` (no topic) for the setup workflow, \`spex help\` for the command map.`)
+    console.error(`spex guide: no topic '${process.argv[3]}'. Topics: spec, yatsu, config, footprint. Run \`spex guide\` (no topic) for the setup workflow, \`spex help\` for the command map.`)
     process.exit(2)
   }
   console.log(text)
@@ -272,9 +279,9 @@ if (cmd === 'serve') {
   }
 } else if (cmd === 'init') {
   // scaffold a repo to adopt SpexCode: copy the shipped DATA templates (seed spec tree + git hooks)
-  // into <targetDir> (default cwd). spex init [targetDir]
+  // into <targetDir> (default cwd). spex init [targetDir] [--preset <tier>] [--render <word>]
   const { specInit } = await import('./init.js')
-  await specInit(positionals(3)[0], flag('preset'))
+  await specInit(positionals(3)[0], flag('preset'), flag('render'))
 } else if (cmd === 'uninstall') {
   // the surgical inverse of init: remove every SpexCode-generated artifact (harness shims/contract/trust, the
   // .gitignore block, the global store, any plugin bundle) — NEVER the user's .spec/.config data or their own
@@ -396,8 +403,12 @@ if (cmd === 'serve') {
 } else if (cmd === 'materialize') {
   // @@@ materialize - the pay-per-change render: surface nodes → manifest + AGENTS.md/CLAUDE.md block +
   // shims + Codex trust, for cwd's project. The cheap shell gate (dispatch.sh) invokes it only on change.
-  const { materialize } = await import('./materialize.js')
+  // The adoption vote hint ([[render-policy]]) prints only here and on init — the human surfaces — never
+  // from the silent gate/bootstrap renders of the same function.
+  const { materialize, renderVoteHint } = await import('./materialize.js')
   console.log(`materialized — content-hash ${materialize()}`)
+  const hint = renderVoteHint()
+  if (hint) console.log(`\n${hint}`)
 } else if (cmd === 'doctor') {
   // @@@ doctor - the diagnosis surface ([[doctor]], né `self` — renamed: "self" read as the tool itself /
   // the global install, while the report is about THIS agent's wiring): does the materialized workflow
@@ -481,10 +492,16 @@ if (cmd === 'serve') {
     intervalMs,
   }), true)   // greet=true: a stream watch greets its specific targets once; `wait` (one-shot) does not
 } else if (cmd === 'wait') {
-  const { watchSessions } = await import('./sessions.js')
+  const { watchSessions, ownSessionId } = await import('./sessions.js')
   const { clientListSessions } = await import('./client.js')
   const [id] = positionals(3)
   if (!id) { console.error('usage: spex wait <id> [--timeout SECONDS] [--interval SECONDS] [--idle]'); process.exit(2) }
+  // point-of-use turn-freeze warning ([[graph]]): a managed agent that runs this wait in the FOREGROUND
+  // freezes its whole turn until the target turns actionable — a warning that used to live only in help
+  // prose, now said where it matters. Foreground vs background is invisible from here, so the hint prints
+  // for ANY managed-agent shell (harmless in a background transcript), on stderr, and changes nothing else.
+  const own = ownSessionId()
+  if (own) console.error(`spex wait: heads-up (managed agent ${own.slice(0, 8)}) — this command BLOCKS until ${id} turns actionable; run it in the BACKGROUND or it freezes your whole turn (its exit is your wake-up). Proceeding.`)
   const intervalMs = (Number(flag('interval')) || 2) * 1000
   const timeoutSec = Number(flag('timeout')) || 1200
   const r = await withWatchEdge([id], intervalMs, () => watchSessions(() => {}, {
@@ -500,12 +517,23 @@ if (cmd === 'serve') {
   console.error(`spex wait: timeout — ${id} did not reach an actionable status within ${timeoutSec}s`)
   process.exit(1)
 } else if (cmd === 'new') {
-  // shorthand for `spex session new`: spex new "<prompt>" [--node X]  (prompt = first positional or --prompt)
+  // shorthand for `spex session new`: spex new "<prompt>" [--node X]  (prompt = first positional or --prompt,
+  // or --prompt-file <path>|- so a long multi-paragraph prompt never fights shell quoting — [[prompt-file]]).
   // createSession POSTs to the running backend so the launch runs in the backend's process (auth env + cap);
   // it falls back to an in-process launch only when no backend answers.
   const { createSession } = await import('./sessions.js')
   if (has('harness')) { console.error('spex new: --harness was removed; use --launcher <name> (for example --launcher codex)'); process.exit(2) }
-  const prompt = flag('prompt') ?? positionals(3)[0] ?? ''
+  const promptFile = flag('prompt-file')
+  const inline = flag('prompt') ?? positionals(3)[0]
+  let prompt = inline ?? ''
+  if (promptFile !== undefined) {
+    // fail-loud exclusive: never silently pick one of two prompt sources.
+    if (inline !== undefined) { console.error('spex new: give the prompt either inline or via --prompt-file, not both'); process.exit(2) }
+    const { readFileSync } = await import('node:fs')
+    try { prompt = promptFile === '-' ? readFileSync(0, 'utf8') : readFileSync(promptFile, 'utf8') }
+    catch (e) { console.error(`spex new: --prompt-file ${promptFile}: ${e instanceof Error ? e.message : e}`); process.exit(2) }
+    if (!prompt.trim()) { console.error(`spex new: --prompt-file ${promptFile === '-' ? 'stdin' : promptFile} is empty — refusing a promptless launch`); process.exit(2) }
+  }
   const nodeArg = flag('node')
   const created = await createSession(nodeArg ? stripRefSigil(nodeArg) : null, prompt, flag('launcher') ?? undefined)
   console.log(JSON.stringify(created, null, 2))
@@ -517,11 +545,34 @@ if (cmd === 'serve') {
   // launch path). `c` (client.ts) backs the read/control subs that route through the backend. Lazily imported.
   const s = await import('./sessions.js')
   const c = await import('./client.js')
+  const l = await import('./layout.js')
+  const { existsSync, writeFileSync } = await import('node:fs')
   const id = process.argv[4]
   // the agent-authored state writers resolve WHICH session by id: a `--session <id>` flag (the lifecycle
   // hooks pass it, parsed from the payload, since they no longer have a cwd `.session`) wins, else the
   // harness env var (ownSessionId — the agent's own `spex session …` carries the harness session id).
   const sess = flag('session')
+  // @@@ no-record diagnosis ([[state]]) - the session store resolves from the CURRENT directory (runtimeRoot
+  // ← the cwd's git common dir), so the classic declaration failure is a cd OUTSIDE the session's project —
+  // and a bare "no session record" told the author none of that (field-reported). Name the actual cause and
+  // route the fix; each branch is a distinct situation, distinguished by probing the same store the writer used.
+  const noRecord = (): string => {
+    // cwd probe FIRST: outside a git repo nothing below can resolve — not the store, and not even the env
+    // id (ownSessionId's alias walk reads the store too) — so diagnose the cwd before touching either.
+    let ids: string[] | null
+    try { ids = l.listSessionIds() } catch { ids = null }
+    if (ids === null) return `no session record — declarations resolve the session store from the CURRENT directory, and ${process.cwd()} is not inside a git repository. cd back into the session's worktree and re-declare.`
+    const wid = sess || s.ownSessionId()   // safe now: the store just resolved, so the alias walk cannot throw
+    if (!wid) return 'no session record — no session id to write: this shell carries no harness session env (SPEXCODE_SESSION_ID / CLAUDE_CODE_SESSION_ID) and no --session was given. Pass --session <id> (spex ls lists ids).'
+    if (ids.length === 0) return `no session record for ${wid.slice(0, 8)} — declarations resolve the session store from the CURRENT directory, and the project at ${process.cwd()} has no sessions at all: you are in a different project's checkout. cd back into the session's worktree and re-declare.`
+    return `no session record for ${wid.slice(0, 8)} — this project's store (resolved from ${process.cwd()}) holds ${ids.length} session(s) but not this one: a wrong --session id, or you are declaring from a different project's checkout. cd back into the session's worktree and re-declare, or pass a valid --session <id> (spex ls).`
+  }
+  // a state writer from a non-repo cwd throws git's not-a-repo before it can return false — map exactly
+  // that throw to the no-record path (noRecord re-probes and names the cwd); anything else stays loud.
+  const mark = (fn: () => boolean): boolean => {
+    try { return fn() }
+    catch (e) { if (/not a git repository/i.test(String((e as any)?.stderr ?? e))) return false; throw e }
+  }
   // appended to a done/ask/block declaration: states (not commands) that the next tool call's mark-active hook re-flips the global record to active, so a re-read won't show this.
   const DECLARED = ' — recorded; the human sees it in the dashboard. This state lives in your session\'s global record; your next tool call flips that record back to active (the mark-active hook, by design), so it is normal for this declaration not to persist.'
   // appended ONLY to a propose-close declaration: a worktree about to be discarded may still own ephemeral things the agent started to test this change; nudge (not gate) it to reclaim them before the worktree goes, keyed on whether the thing should outlive the task — never on who started it (a deliberately long-running service / a production build is started-by-you yet must be left alone). Project-agnostic on purpose.
@@ -529,10 +580,22 @@ if (cmd === 'serve') {
   // truncation transparency ([[state]]): the board table shows only the first NOTE_BOARD_LIMIT chars of a
   // note. When a declared note overflows that cap, the confirmation says so — length, what the board shows,
   // where the full text is readable — so the cut is visible to the author instead of silently eaten.
-  // A nudge riding the echo, never a gate: the declaration has already landed.
-  const noteEcho = (note?: string) => (note && note.length > s.NOTE_BOARD_LIMIT)
-    ? `\nyour note is ${note.length} chars; the board table shows only the first ${s.NOTE_BOARD_LIMIT} — the full text IS recorded, and readable via spex review ${(sess || s.ownSessionId() || '<your-session>').slice(0, 8)} / spex ls --json.`
-    : ''
+  // Taught ONCE per session: the first overflowing note prints the full notice and drops a sentinel beside
+  // the record; later overflows stay silent (the rule was taught — a verbatim repeat on every park/ask is
+  // noise, field-reported). A nudge riding the echo, never a gate: the declaration has already landed.
+  const noteEcho = (note?: string): string => {
+    if (!note || note.length <= s.NOTE_BOARD_LIMIT) return ''
+    const wid = sess || s.ownSessionId()
+    const rid = wid ? (l.readAliasedRawRecord(wid)?.session_id ?? wid) : null   // sentinel lives in the RECORD's dir, so an aliased codex id lands on the same file
+    if (rid) {
+      const sentinel = l.sessionArtifactPath(rid, 'note-echo-taught')
+      try {
+        if (existsSync(sentinel)) return ''
+        writeFileSync(sentinel, `${new Date().toISOString()}\n`)   // only reached on a successful declaration (the echo rides the success branch)
+      } catch { /* unreadable/unwritable store dir → fall through and teach again; never block the echo */ }
+    }
+    return `\nyour note is ${note.length} chars; the board table shows only the first ${s.NOTE_BOARD_LIMIT} — the full text IS recorded, and readable via spex review ${(wid || '<your-session>').slice(0, 8)} / spex ls --json. (said once — later long notes won't repeat this.)`
+  }
   if (sub === 'reopen') {
     // bring the agent back up (relaunch ONLY if confirmed offline, the backend owns it); demotes a working
     // `active` to idle but leaves a standing declaration/proposal untouched (see sessions.ts reopen()). The
@@ -545,8 +608,8 @@ if (cmd === 'serve') {
   } else if (sub === 'state') {
     // the agent authors ITS OWN state: active|awaiting|parked|error  [--propose] [--note] [--session]
     const st = process.argv[4] as any
-    const ok = s.markState(st, { proposal: flag('propose') as any, note: flag('note'), sessionId: sess })
-    console.log(ok ? `state -> ${st}${noteEcho(flag('note'))}` : 'no session record (unknown --session / no CLAUDE_CODE_SESSION_ID, or bad status)')
+    const ok = mark(() => s.markState(st, { proposal: flag('propose') as any, note: flag('note'), sessionId: sess }))
+    console.log(ok ? `state -> ${st}${noteEcho(flag('note'))}` : noRecord())
   } else if (sub === 'done') {
     // sugar for awaiting; --propose merge|nothing|close, optional --note
     const p = (flag('propose') as any) || 'nothing'
@@ -558,18 +621,18 @@ if (cmd === 'serve') {
       try { closeNote += (await import('./localIssues.js')).closeoutNudge(sess ?? s.ownSessionId()) }
       catch (e) { console.error(`issue closeout check failed (declaration unaffected): ${e instanceof Error ? e.message : e}`) }
     }
-    console.log(s.markDone(p, sess, flag('note')) ? `done (${p})${DECLARED}${noteEcho(flag('note'))}${closeNote}` : 'no session record')
+    console.log(mark(() => s.markDone(p, sess, flag('note'))) ? `done (${p})${DECLARED}${noteEcho(flag('note'))}${closeNote}` : noRecord())
   } else if (sub === 'park') {
     // sugar: the agent is waiting on a background task; it will self-resume (NOT idle/awaiting)
-    console.log(s.markState('parked', { note: flag('note'), sessionId: sess }) ? `parked${DECLARED}${noteEcho(flag('note'))}` : 'no session record')
+    console.log(mark(() => s.markState('parked', { note: flag('note'), sessionId: sess })) ? `parked${DECLARED}${noteEcho(flag('note'))}` : noRecord())
   } else if (sub === 'fail') {
     // the StopFailure hook marks its session (--session from the payload) as error (turn died on an API error)
-    console.log(s.markError(sess) ? 'marked error' : 'no session record')
+    console.log(mark(() => s.markError(sess)) ? 'marked error' : noRecord())
   } else if (sub === 'ask') {
     // the agent DELIBERATELY declares it is pausing to ask the human a question (like `done`/`park`, an
     // authored state — NOT guarded active-only). The --note carries the question. Distinct from `park`
     // (waiting on a background task, self-resumes): an asking agent resumes only when the human replies.
-    console.log(s.markState('asking', { note: flag('note'), sessionId: sess }) ? `asking${DECLARED}${noteEcho(flag('note'))}` : 'no session record')
+    console.log(mark(() => s.markState('asking', { note: flag('note'), sessionId: sess })) ? `asking${DECLARED}${noteEcho(flag('note'))}` : noRecord())
   } else if (sub === 'commit-gate') {
     // the Stop gate's deterministic commit check (from cwd = the worktree): exit 0 if the node branch is
     // ready to declare done/merge (work committed + ahead of main), else print the reason and exit 1. Uses

package/spec-cli/src/contract-filter.ts

@@ -0,0 +1,154 @@
+import { mkdirSync, readFileSync, rmSync, writeFileSync, chmodSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import { execFileSync } from 'node:child_process'
+import { git } from './git.js'
+import { writeManagedBlock, removeManagedBlock } from './harness.js'
+
+// @@@ contract-filter ([[content-filter]]) - the render=hidden answer for a MIXED-CONTENT contract file: a
+// CLAUDE.md/AGENTS.md the HOST ALREADY TRACKS, where "generate + ignore" is a no-op (git ignores only
+// untracked paths) and the folded-in block would ride the tracked file into every teammate's diff. A git
+// clean/smudge content filter keeps the two contents on their own sides of the index: the REPO stores the
+// pristine host prose (clean strips our sentinel block on stage/diff), the WORKING TREE carries prose + block
+// (smudge re-injects it on checkout). Everything the filter needs is PER-CLONE — `git config
+// filter.spexcode.*` + a managed block in `.git/info/attributes` + two files under `<common>/spexcode/` —
+// zero repo footprint, exactly the hidden contract. The sentinels are the load-bearing anchor: the invariant
+// is clean(smudge(x)) == x (for text ending in one newline — see the shim), so `git status` stays clean.
+// Planted ONLY for a file the host tracks (the weakest sufficient tool: an untracked contract file is wholly
+// ours and plain generate+ignore already hides it — no filter). materialize plants/refreshes it under
+// render=hidden and erases it under every other policy ([[render-policy]] / the forgetting law).
+
+// the three field-sharpened edges this module owes ([[content-filter]]):
+//   ① the configured command points at a STABLE shim path and degrades to `cat` (identity) when the shim is
+//     missing — a bare missing filter command makes git spray "cannot fork" fatals on EVERY operation;
+//   ② a changed contract does NOT propagate by itself (git re-smudges only on checkout) — materialize's
+//     re-render writes the managed block straight into the working file (writeManagedBlock IS the re-smudge),
+//     and this module refreshes the block file the shim reads so future checkouts agree;
+//   ③ unplanting must strip the block from the WORKING FILES before the config goes away, or the block
+//     residue surfaces as an uncommitted modification — the caller (dematerialize) removes the managed
+//     blocks first and only then calls removeContractFilter.
+
+function commonDirOf(proj: string): string {
+  return git(['-C', proj, 'rev-parse', '--path-format=absolute', '--git-common-dir']).trim()
+}
+const filterDir = (common: string) => join(common, 'spexcode')
+const shimPath = (common: string) => join(filterDir(common), 'contract-filter.sh')
+const blockPath = (common: string) => join(filterDir(common), 'contract-block.md')
+const attributesPath = (common: string) => join(common, 'info', 'attributes')
+
+// the per-clone shim both filter directions run through. Pure shell/awk (no node boot on git's hot path),
+// mirroring writeManagedBlock/removeManagedBlock's normalization exactly so the two writers agree:
+//   clean : drop the sentinel block (+ the blank line smudge printed before it) → the pristine host prose.
+//   smudge: clean first (defensive — a block already in the index can never double-inject), then append one
+//           blank line + START + the contract-block file's content + END.
+// Byte-exactness holds for text ending in exactly one newline (git's own well-formed-text shape); a pristine
+// file ending in zero or 2+ newlines is normalized to one on the first round-trip and stable after.
+const SHIM = `#!/usr/bin/env bash
+# spexcode contract filter (generated by spex materialize — render=hidden; see [[content-filter]]).
+# clean(smudge(x)) == x: the repo keeps the pristine host prose, the working tree carries prose + block.
+set -u
+mode="\${1:?usage: contract-filter.sh smudge|clean}"
+here="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
+block="$here/contract-block.md"
+strip() {
+  awk 'BEGIN { n = 0 }
+    { lines[n++] = $0 }
+    END {
+      s = -1; e = -1
+      for (i = 0; i < n; i++) {
+        if (lines[i] == "<!-- spexcode:start -->" && s < 0) s = i
+        if (lines[i] == "<!-- spexcode:end -->" && s >= 0 && e < 0) e = i
+      }
+      if (s >= 0 && e >= s) {
+        a = s; while (a > 0 && lines[a-1] == "") a--
+        b = e; while (b + 1 < n && lines[b+1] == "") b++
+        j = 0
+        for (i = 0; i < n; i++) if (i < a || i > b) lines[j++] = lines[i]
+        n = j
+      }
+      # NO leading-blank strip: dropping a..b (block + its surrounding blanks) can never CREATE a leading
+      # blank, and a host file that BEGINS with blank lines must keep them — clean(smudge(x)) == x.
+      for (i = 0; i < n; i++) print lines[i]
+    }'
+}
+case "$mode" in
+  clean) strip ;;
+  smudge)
+    if [ ! -r "$block" ]; then cat; exit 0; fi          # no block content → identity (graceful, never fatal)
+    strip | awk -v b="$block" 'BEGIN { n = 0 }
+      { lines[n++] = $0 }
+      END {
+        while (n > 0 && lines[n-1] == "") n--           # trim trailing blanks (writeManagedBlock parity)
+        for (i = 0; i < n; i++) print lines[i]
+        if (n > 0) print ""
+        print "<!-- spexcode:start -->"
+        while ((getline l < b) > 0) print l
+        print "<!-- spexcode:end -->"
+      }' ;;
+  *) echo "contract-filter.sh: unknown mode $mode" >&2; exit 1 ;;
+esac
+`
+
+// edge ①: the command git runs is a tolerant wrapper — the shim path is an ARGUMENT ($0), and a missing/
+// unreadable shim degrades to `cat` (identity) instead of a per-operation fatal.
+const filterCmd = (shim: string, mode: 'smudge' | 'clean') =>
+  `sh -c 'test -r "$0" && exec bash "$0" ${mode} || exec cat' '${shim.replace(/'/g, `'\\''`)}'`
+
+// plant (or refresh) the filter for the given TRACKED contract files: the shim + the block content it
+// smudges, the per-clone git config, and the attribute lines binding each file to the filter. Idempotent —
+// every write is a full replace. `contract` is the assembled block body (guide + surface:system).
+export function plantContractFilter(proj: string, trackedFiles: string[], contract: string): void {
+  const common = commonDirOf(proj)
+  mkdirSync(filterDir(common), { recursive: true })
+  writeFileSync(blockPath(common), contract.endsWith('\n') ? contract : `${contract}\n`)   // edge ②: the shim's smudge source, refreshed with the render
+  writeFileSync(shimPath(common), SHIM)
+  chmodSync(shimPath(common), 0o755)
+  git(['-C', proj, 'config', 'filter.spexcode.smudge', filterCmd(shimPath(common), 'smudge')])
+  git(['-C', proj, 'config', 'filter.spexcode.clean', filterCmd(shimPath(common), 'clean')])
+  // attribute patterns are checkout-relative, so one line serves the main checkout and every worktree.
+  const entries = trackedFiles.map((f) => `/${relative(proj, f)} filter=spexcode`).sort().join('\n')
+  mkdirSync(join(common, 'info'), { recursive: true })
+  writeManagedBlock(attributesPath(common), entries, ['# ', ''])
+  settleIndexStat(proj, trackedFiles)
+}
+
+// settle the index STAT for each file — the famous filtered-path phantom-`M`: git cannot verify a
+// clean-filtered path by stat alone (worktree size ≠ blob size by design), and `git status` reports such an
+// entry modified FOREVER without ever content-checking it (field-verified on git 2.43; `git diff` meanwhile
+// runs the filter and shows nothing; even `update-index --really-refresh` leaves it). The block-strip side of
+// a mode switch/backout leaves the same stale stat on the then-unfiltered path. `git add --renormalize`
+// re-cleans the file and refreshes the cached stat — run ONLY when the (possibly filtered) worktree already
+// EQUALS the index blob, so it is a pure stat refresh that can never stage a user's real unstaged edit (a
+// genuine edit keeps its honest `M`). Exported for dematerialize (the unplant side); plant calls it below.
+// Best-effort: an unsettled stat is cosmetic noise, never corruption.
+export function settleIndexStat(proj: string, files: string[]): void {
+  const env = { ...process.env }
+  delete env.GIT_DIR; delete env.GIT_WORK_TREE; delete env.GIT_INDEX_FILE; delete env.GIT_OBJECT_DIRECTORY
+  for (const f of files) {
+    const rel = relative(proj, f)
+    try {
+      const indexBlob = git(['-C', proj, 'rev-parse', `:${rel}`]).trim()
+      const filtered = execFileSync('git', ['-C', proj, 'hash-object', '--path', rel, '--stdin'],
+        { input: readFileSync(f), env, stdio: ['pipe', 'pipe', 'ignore'] }).toString().trim()
+      if (indexBlob === filtered) git(['-C', proj, 'add', '--renormalize', '--', rel])
+    } catch { /* best-effort */ }
+  }
+}
+
+// the full inverse (edge ③ — call AFTER the managed blocks left the working files): attribute lines out,
+// config keys unset, shim + block content removed. `<common>/spexcode/` may host other spexcode data
+// (yatsu blobs), so only OUR two files go, never the dir.
+export function removeContractFilter(proj: string): void {
+  let common: string
+  try { common = commonDirOf(proj) } catch { return }   // not a git repo → nothing was ever planted
+  removeManagedBlock(attributesPath(common), ['# ', ''], true)
+  for (const key of ['filter.spexcode.smudge', 'filter.spexcode.clean']) {
+    try { git(['-C', proj, 'config', '--unset', key]) } catch { /* not set — already clean */ }
+  }
+  rmSync(shimPath(common), { force: true })
+  rmSync(blockPath(common), { force: true })
+}
+
+// is the filter currently planted? (the assert-side probe tests use; cheap: one config read)
+export function contractFilterPlanted(proj: string): boolean {
+  try { return git(['-C', proj, 'config', 'filter.spexcode.clean']).trim().length > 0 } catch { return false }
+}

package/spec-cli/src/git.ts

@@ -5,11 +5,24 @@ import { join, isAbsolute, resolve } from 'node:path'
 
 const US = '\x1f', RS = '\x1e'
 
+// @@@ bounded git children - a git child that never exits (wedged fs, a hijacked PATH git, a dead network
+// mount) must not pin its awaiter forever: [[board-cache]]'s settle guarantee starts at this seam. Every
+// shared helper passes a generous timeout (an order of magnitude above the slowest legitimate full-history
+// walk) with SIGKILL — same pattern sessions.ts's tmux/ps probes already use — so a hung child dies and the
+// call fails like any other git failure instead of hanging its caller's promise. The kill is warned loudly:
+// gitA maps failure to '', which would otherwise hide the pathology as an innocently-empty result.
+const GIT_TIMEOUT_MS = Number(process.env.SPEXCODE_GIT_TIMEOUT_MS || 120000)
+function warnIfTimedOut(e: any, args: string[]): void {
+  if (e?.signal === 'SIGKILL') console.warn(`spec-cli: git ${args.slice(0, 6).join(' ')}… killed after ${GIT_TIMEOUT_MS}ms — child never exited`)
+}
+
 // strip git's hook-exported env (GIT_DIR etc.) so every call discovers the repo from the filesystem.
 export function git(args: string[]): string {
   const env = { ...process.env }
   delete env.GIT_DIR; delete env.GIT_WORK_TREE; delete env.GIT_INDEX_FILE; delete env.GIT_OBJECT_DIRECTORY
-  return execFileSync('git', args, { encoding: 'utf8', env, stdio: ['ignore', 'pipe', 'pipe'] })
+  try {
+    return execFileSync('git', args, { encoding: 'utf8', env, stdio: ['ignore', 'pipe', 'pipe'], timeout: GIT_TIMEOUT_MS, killSignal: 'SIGKILL' })
+  } catch (e: any) { warnIfTimedOut(e, args); throw e }
 }
 
 const pexecFile = promisify(execFile)
@@ -17,18 +30,19 @@ export async function gitA(args: string[]): Promise<string> {
   const env = { ...process.env }
   delete env.GIT_DIR; delete env.GIT_WORK_TREE; delete env.GIT_INDEX_FILE; delete env.GIT_OBJECT_DIRECTORY
   try {
-    const { stdout } = await pexecFile('git', args, { encoding: 'utf8', env, maxBuffer: 1 << 24 })
+    const { stdout } = await pexecFile('git', args, { encoding: 'utf8', env, maxBuffer: 1 << 24, timeout: GIT_TIMEOUT_MS, killSignal: 'SIGKILL' })
     return stdout
-  } catch { return '' }
+  } catch (e: any) { warnIfTimedOut(e, args); return '' }
 }
 
 export async function gitTry(args: string[]): Promise<{ ok: boolean; stdout: string; stderr: string }> {
   const env = { ...process.env }
   delete env.GIT_DIR; delete env.GIT_WORK_TREE; delete env.GIT_INDEX_FILE; delete env.GIT_OBJECT_DIRECTORY
   try {
-    const { stdout, stderr } = await pexecFile('git', args, { encoding: 'utf8', env, maxBuffer: 1 << 24 })
+    const { stdout, stderr } = await pexecFile('git', args, { encoding: 'utf8', env, maxBuffer: 1 << 24, timeout: GIT_TIMEOUT_MS, killSignal: 'SIGKILL' })
     return { ok: true, stdout, stderr }
   } catch (e: any) {
+    warnIfTimedOut(e, args)
     return { ok: false, stdout: e?.stdout ?? '', stderr: e?.stderr ?? String(e?.message ?? e) }
   }
 }