spexcode 0.2.4 → 0.2.6

package/README.md

@@ -74,7 +74,7 @@ Requires Node ≥ 22 and git. This part is plain tooling — no AI involved yet.
 ```sh
 npm i -g spexcode        # installs the `spex` command
 cd your-repo
-spex init                # seeds .spec/, installs git hooks, renders the agent contract
+spex init                # seeds .spec/, installs git hooks, materializes the agent contract
 spex serve               # API backend on :8787
 spex dashboard           # board UI on :5173, proxying to the backend
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spexcode",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "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/dispatch.sh

@@ -3,22 +3,21 @@
 # / .codex/hooks.json, written by each [[harness-adapter]]) binds one line per event to
 # `dispatch.sh <harness> <Event>` — the harness id is BAKED IN by the adapter that wrote the shim, so this is
 # the deterministic harness DETECTOR for the shell side: we export SPEXCODE_HARNESS (read by harness.sh, the
-# adapter's shell mirror, which the hook handlers source) without ever sniffing the payload shape. Two jobs,
-# in order:
-#   (1) GATE — a cheap pure-shell content hash of the config roots (~10ms, every event). If it moved since the
-#       last render, re-run `spex materialize` (the ~0.85s node step) to bring manifest + contract (AGENTS.md/
-#       CLAUDE.md block) + shims + Codex trust back in lockstep with the EDITABLE .config. Content-based, so it
-#       catches bash/sed/user/other-agent/git edits alike (a tool-payload path would miss them). Serialized by
-#       a lock with a re-check inside, so concurrent sessions never race the write (§ atomicity).
-#   (2) DISPATCH — run every handler bound to <Event> from the persistent manifest, in order, feeding each the
-#       ORIGINAL stdin. Reproduces the native parallel multi-hook contract DETERMINISTICALLY: all handlers run
-#       (side effects preserved), their stdout (decision/additionalContext) is concatenated through, and a
-#       block:true handler that exits 2 makes the dispatch exit 2 with that handler's stderr — the one signal
-#       the harness propagates. Pure bash, no node boot on the hot path (node runs only inside the gate, only
-#       on actual change). cwd = the project/worktree. $SPEX (abs tsx+cli) is inherited from the shim env.
+# adapter's shell mirror, which the hook handlers source) without ever sniffing the payload shape. ONE job:
+#   DISPATCH — run every handler bound to <Event> from the persistent manifest, in order, feeding each the
+#   ORIGINAL stdin. Reproduces the native parallel multi-hook contract DETERMINISTICALLY: all handlers run
+#   (side effects preserved), their stdout (decision/additionalContext) is concatenated through, and a
+#   block:true handler that exits 2 makes the dispatch exit 2 with that handler's stderr — the one signal
+#   the harness propagates. Pure bash, no node boot on the hot path. cwd = the project/worktree. $SPEX (abs
+#   tsx+cli) is inherited from the shim env.
+#
+# The old (1) GATE — an auto-materialize when the config content-hash moved — is RETIRED ([[commit-surgery]]):
+# a harness event is never a materialize trigger; the materialize anchors are git-native only (spex verbs,
+# session-worktree creation, and the pre-commit/post-checkout/post-merge hooks). .config edits are
+# git-transactional: they take effect at the commit/checkout/merge that carries them, like any other source.
 set -u
 # args: `<harness> <Event>`. A harness id as $1 (claude|codex|plugin) is consumed; otherwise we keep $1 as the
-# event and default the harness to claude — so a stale shim still rendered as `dispatch.sh <Event>` keeps working.
+# event and default the harness to claude — so a stale shim still written as `dispatch.sh <Event>` keeps working.
 # `plugin` is the bundle form ([[plugin-harness]]): it parses payloads as the claude family in harness.sh (z-code/
 # Claude share Claude's tool names + file_path), so it joins the claude branch there via the default case.
 harness=claude
@@ -30,35 +29,24 @@ export SPEXCODE_HARNESS="$harness"
 export SPEXCODE_HARNESS_LIB="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/harness.sh"
 . "$SPEXCODE_HARNESS_LIB"
 proj="${CLAUDE_PROJECT_DIR:-$PWD}"
-# the manifest + content-hash + gate lock live in the GLOBAL per-project store (mirrors layout.runtimeRoot),
-# NOT the worktree — so the worktree carries zero SpexCode-rendered runtime. Empty if git can't resolve.
+# the manifest lives in THIS tree's materialize slot of the GLOBAL per-project store (mirrors layout.treeSlotDir),
+# NOT the worktree — and per tree, so a dispatch can only read the manifest of the tree it fires in
+# ([[hook-dispatch]]). Slot key = this cwd's rev-parse --show-toplevel through hp_tree_dir. Empty if git
+# can't resolve.
 rt="$(cd "$proj" 2>/dev/null && hp_runtime_dir)" || rt=""
+slot="$(cd "$proj" 2>/dev/null && hp_tree_dir)" || slot=""
 
-# --- (1) gate -------------------------------------------------------------------------------------------
-# the config fingerprint is hp_config_hash (harness.sh, already sourced) — the SAME function materialize.ts
-# shells to, so the gate and the renderer never disagree on "changed".
-cur="$( (cd "$proj" 2>/dev/null && hp_config_hash) )"
-if [ -n "$rt" ] && [ -n "$cur" ] && [ "$cur" != "$(cat "$rt/content-hash" 2>/dev/null || true)" ]; then
-  mkdir -p "$rt" 2>/dev/null
-  # POSIX-portable mutex: mkdir is atomic on every POSIX fs, so it serializes the render with NO dependency on
-  # util-linux `flock` (absent on macOS — where it silently no-op'd, letting concurrent sessions race the write).
-  # Spin on `mkdir` with a bounded wait; after ~10s (200 * 0.05s, well above the ~0.85s materialize) treat the
-  # dir as orphaned by a dead entrant and clear it, so a stale lock can never deadlock a launch. Held only across
-  # the re-check + render, released right after.
-  lockd="$rt/.materialize.lock.d"
-  _lk=0
-  until mkdir "$lockd" 2>/dev/null; do
-    _lk=$((_lk+1)); [ "$_lk" -ge 200 ] && { rm -rf "$lockd" 2>/dev/null; _lk=0; }
-    sleep 0.05
-  done
-  if [ "$cur" != "$(cat "$rt/content-hash" 2>/dev/null || true)" ]; then   # re-check: a sibling dispatch may have just rendered
-    ( cd "$proj" && ${SPEX:-spex} materialize >/dev/null 2>&1 )
-  fi
-  rmdir "$lockd" 2>/dev/null
+# --- dispatch ---------------------------------------------------------------------------------------------
+if [ -n "${SPEX_HOOK_MANIFEST:-}" ]; then
+  manifest="$SPEX_HOOK_MANIFEST"
+else
+  # migration window: a tree last materialized by a pre-slot toolchain has no slot until its next git-native
+  # anchor — fall back to the legacy global manifest (its exact pre-migration behavior) so no hook (the
+  # Stop gate included) silently no-ops. The legacy file is never written again; the next anchor plants the
+  # slot and this branch goes dead.
+  manifest="$slot/hooks-manifest"
+  [ -f "$manifest" ] || manifest="$rt/hooks-manifest"
 fi
-
-# --- (2) dispatch ---------------------------------------------------------------------------------------
-manifest="${SPEX_HOOK_MANIFEST:-$rt/hooks-manifest}"
 [ -f "$manifest" ] || exit 0          # no manifest yet (materialize never ran) → nothing to dispatch
 input="$(cat 2>/dev/null || true)"    # capture stdin ONCE; each handler gets its own copy
 err="/tmp/.spex-hook-$$.err"          # per-dispatch (pid-unique) stderr capture; no cross-session race

package/spec-cli/hooks/harness.sh

@@ -70,7 +70,7 @@ hp_session_id() {
 
 # the per-PROJECT GLOBAL runtime dir (mirrors spec-cli/src/layout.ts `runtimeRoot`): <store>/projects/<enc>,
 # keyed by the project (dirname of the ABSOLUTE git-common-dir, so the answer is identical from main or any
-# worktree). This is where the materialized hook manifest + content-hash + gate lock live — NOT the worktree.
+# worktree). The per-session dirs and the per-tree materialize slots (hp_tree_dir) live under it.
 # Echoes the dir; returns non-zero (echoing nothing) when git can't resolve, so a caller can `|| exit 0`.
 hp_runtime_dir() {
   local gcd
@@ -79,6 +79,19 @@ hp_runtime_dir() {
   printf '%s/projects/%s' "${SPEXCODE_HOME:-$HOME/.spexcode}" "$(printf '%s' "$(dirname "$gcd")" | sed 's#[/.]#-#g')"
 }
 
+# the per-WORKTREE materialize slot (mirrors layout.ts `treeSlotDir`): <runtime>/trees/<enc(worktree-toplevel)> —
+# where THIS tree's materialized hook manifest + content-hash marker live. Keyed by the cwd's own
+# `rev-parse --show-toplevel` through the same enc transform, so a dispatch can only ever read the manifest
+# of the tree it fires in ([[hook-dispatch]] — the old single global file let the last-materialized tree's
+# hook set reach every other tree's sessions). Echoes the dir; returns non-zero when git can't resolve.
+hp_tree_dir() {
+  local rd top
+  rd=$(hp_runtime_dir) || return 1
+  top=$(git rev-parse --show-toplevel 2>/dev/null)
+  [ -n "$top" ] || return 1
+  printf '%s/trees/%s' "$rd" "$(printf '%s' "$top" | sed 's#[/.]#-#g')"
+}
+
 # the per-session GLOBAL store dir for a session id — <runtime>/sessions/<id> (sibling of the per-project
 # runtime above). Echoes the dir; returns non-zero (echoing nothing) when git can't resolve.
 # ALIAS resolution: a codex hook fires from the shared per-PROJECT app-server process, whose env may carry a
@@ -99,13 +112,36 @@ 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 TOOLCHAIN's own version fingerprint — the toolchain side of the content key. The materialized artifacts
+# are a function of (config content, toolchain), 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_toolchain_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 materialize 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 materialize reads via readConfig(mainCheckout)), and the
+# toolchain version above. Since the dispatch-gate retired ([[commit-surgery]] — materialize anchors on
+# git-native events only), this is a FRESHNESS STAMP materialize records after each pass, a diagnostic
+# (is the last materialize current?) rather than a trigger. Run with cwd = the project. ONE definition:
+# materialize.ts shells to it. env-stripped git, same rule as hp_toolchain_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_toolchain_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', '--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,7 +279,7 @@ 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>]
   const { specInit } = await import('./init.js')
   await specInit(positionals(3)[0], flag('preset'))
 } else if (cmd === 'uninstall') {
@@ -394,15 +401,16 @@ if (cmd === 'serve') {
   const run = cmd === 'remark' ? m.runRemark : cmd === 'resolve' ? m.runResolve : m.runRetract
   await flushExit(await run(process.argv.slice(3)))
 } 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.
+  // @@@ materialize - surface nodes → manifest + AGENTS.md/CLAUDE.md block + shims + Codex
+  // trust, for cwd's project. Anchored on git-native events only ([[commit-surgery]]): this verb, init,
+  // session-worktree creation, and the planted pre-commit/post-checkout/post-merge hooks.
   const { materialize } = await import('./materialize.js')
   console.log(`materialized — content-hash ${materialize()}`)
 } 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
   // actually reach this agent? Bare `doctor` reports per-layer coverage (preconditions · git-hook floor ·
-  // contract · hooks+handler-existence · backend) over the same HARNESSES materialize renders through;
+  // contract · hooks+handler-existence · backend) over the same HARNESSES materialize delivers through;
   // `contract` prints the surface:system text; `conflicts` just the double-delivery check. Thin route.
   const { runDoctor } = await import('./doctor.js')
   await flushExit(await runDoctor(process.argv.slice(3)))
@@ -481,10 +489,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 +514,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 +542,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 +577,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 +605,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 +618,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
@@ -697,6 +757,19 @@ if (cmd === 'serve') {
     const sid = process.env.SPEXCODE_SESSION_ID
     if (sid) markHarnessSessionId(sid, r.threadId)
     console.log(r.threadId)
+  } else if (sub === 'commit-surgery') {
+    // the pre-commit footprint anchor ([[commit-surgery]]): unconditional materialize + staged-index repair
+    // (strip our sentinel block from staged blobs, unstage HEAD-untracked generated artifacts). Called only
+    // by the planted pre-commit hook; repairs and proceeds, never rejects. Exit non-zero only on an internal
+    // error — the hook treats that as advisory (warn + continue), CI lint remains the real gate.
+    const { commitSurgery } = await import('./commit-surgery.js')
+    commitSurgery()
+  } else if (sub === 'refresh-footprint') {
+    // the post-checkout / post-merge freshness anchor ([[commit-surgery]]): a quiet materialize after a git
+    // state transition (the only events that can move the materialize's inputs — .spec/.config arrive by commit,
+    // merge, or checkout). Best-effort and silent on success; hooks call it fire-and-forget.
+    const { materialize } = await import('./materialize.js')
+    try { materialize() } catch (e) { console.error(`spexcode: footprint refresh failed (${(e as Error).message})`); process.exit(1) }
   } else if (sub === 'codex-turn') {
     // fire a follow-up turn on an OWNED thread over the per-project socket (the delivery channel, exposed for
     // tests / scripts). steer-vs-start is chosen live from the thread read.