spexcode 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,86 @@
+<img src="docs/sdd-tuxedo-pooh.png" alt="Writing code vs. authoring a living, executable specification artifact" width="420">
+
+> Spec-driven development gets wrecked by spec drift and spec bloat. SpexCode's bet
+> is to keep the spec the cheap, honest twin of the code — rewritten in place, never
+> a tuxedo of stale ceremony.
+
+**SpexCode** is a spec-driven, self-developing dev tool. Every part of a project becomes a versioned
+*spec node* — a `.spec/**/spec.md` whose body states the part's *present* intent — and **git is the
+database**: a node's version is its count of content commits, and "drift" is governed code that moved
+ahead of its spec. A `spex` CLI plus a live dashboard read all of it straight from git; there is no
+separate store.
+
+There are two ways to meet SpexCode, and they are kept separate on purpose:
+
+- **[Using SpexCode](#using-spexcode)** — install the `spex` CLI from npm and govern *your own* project.
+- **[Contributing to SpexCode](#contributing-to-spexcode)** — develop the tool itself, in this repo.
+
+---
+
+## Using SpexCode
+
+You don't clone this repo to *use* SpexCode. Install the published CLI once, then point it at any project.
+
+```sh
+npm i -g spexcode      # installs the `spex` command (needs Node ≥ 22)
+```
+
+Adopt it in your project — `spex init` is **additive**, it never restructures your code:
+
+```sh
+cd ~/my-app
+spex init              # seed .spec/, a starter spexcode.json, and git hooks — nothing destructive
+# 1. edit .spec/project/spec.md to describe your project
+# 2. point spexcode.json's  lint.governedRoots  at your real source dir(s)
+spex lint              # the "coverage" warnings are your adoption TODO list
+```
+
+Run it. The backend and the dashboard are **two commands on two ports**, so several projects can run
+side by side on one host (the cwd picks which project is served):
+
+```sh
+spex serve --port 8788                       # the backend (API + sessions) for THIS repo
+spex dashboard --port 5174 --api-port 8788   # the board UI, pointed at that backend
+```
+
+Then open <http://localhost:5174>. With no flags, `spex serve` defaults to `:8787` and `spex dashboard`
+to `:5173`.
+
+Day to day:
+
+| command | what it does |
+| --- | --- |
+| `spex lint` | check the spec↔code graph — coverage, drift, and the living-body rules |
+| `spex watch` | stream session / board transitions as they happen |
+| `spex guide` | print the full workflow, plus the `spec.md` / `yatsu.md` file-format manuals |
+| `spex board` | dump the current board state as JSON |
+
+The spec tree is ground truth and git is its database: every change is a `spec.md` node, **rewritten in
+place** (never a `## vN` changelog) and versioned by its commits.
+
+---
+
+## Contributing to SpexCode
+
+This repository *is* the SpexCode source, and it **dogfoods itself**: every change to the tool lands as a
+spec node merged into `main`. Set up a checkout:
+
+```sh
+git clone https://github.com/shuxueshuxue/spexcode && cd spexcode
+npm --prefix spec-cli install
+npm --prefix spec-dashboard install
+npm run hooks          # install the per-clone git hooks (main-guard + the session-stamp hook)
+```
+
+The development loop runs from source, with hot-reload — this is what `npm run web` is for, as opposed
+to an installed user's `spex dashboard`:
+
+```sh
+npm run api            # backend on :8787, hot-reloads on spec-cli/src changes
+npm run web            # the dashboard via Vite (HMR), proxying /api → :8787
+```
+
+The contribution ritual in one breath: branch `node/<id>` off `main`, make the code change **and** its
+`spec.md` *together*, commit, then `spex session done --propose merge` — a human performs the `--no-ff`
+merge. That ritual, the spec-node model, the lint rules, and the reflexive config system are all spelled
+out in **[`CLAUDE.md`](./CLAUDE.md)** — read it before your first change.

package/package.json

@@ -1,23 +1,30 @@
 {
   "name": "spexcode",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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",
-  "bin": { "spex": "bin/spex.mjs" },
+  "bin": { "spex": "spec-cli/bin/spex.mjs" },
   "files": [
-    "src",
-    "!src/**/*.test.ts",
-    "templates",
-    "bin",
-    "dashboard-dist",
+    "spec-cli/src",
+    "!spec-cli/src/**/*.test.ts",
+    "spec-cli/bin",
+    "spec-cli/templates",
+    "spec-cli/hooks",
+    "spec-yatsu/src",
+    "!spec-yatsu/src/**/*.test.ts",
+    "spec-forge/src",
+    "!spec-forge/src/**/*.test.ts",
+    "spec-dashboard/dist",
     "README.md"
   ],
   "engines": { "node": ">=22" },
   "scripts": {
-    "serve": "tsx src/cli.ts serve",
-    "lint": "tsx src/cli.ts lint",
-    "test": "tsx --test src/*.test.ts",
+    "api": "npm --prefix spec-cli run serve",
+    "web": "npm --prefix spec-dashboard run dev",
+    "lint": "npm --prefix spec-cli run -s lint",
+    "seed": "bash scripts/seed-spec-history.sh",
+    "hooks": "bash scripts/install-hooks.sh",
     "prepublishOnly": "node scripts/prepublish.mjs",
     "postinstall": "node -e \"try{require('fs').readdirSync('node_modules/node-pty/prebuilds').forEach(d=>{try{require('fs').chmodSync('node_modules/node-pty/prebuilds/'+d+'/spawn-helper',0o755)}catch{}})}catch{}\""
   },

package/{bin → spec-cli/bin}/spex.mjs

@@ -2,14 +2,18 @@
 // @@@ spex launcher - this repo has no build step, so the installed `spex` bin shells to tsx to
 // run the TypeScript CLI directly. After `npm link` (or a global install) `spex lint` works anywhere.
 import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { dirname, join } from 'node:path'
 
 // @@@ self-contained - resolve tsx + cli from THIS package, not the cwd. A fresh worktree off main has
 // no node_modules, so `npx tsx` there would try to install; using the package's own tsx makes a global
 // `spex` work from any cwd (agents, git hooks) against this package's code, operating on the cwd.
-const pkg = join(dirname(fileURLToPath(import.meta.url)), '..')
-const tsx = join(pkg, 'node_modules', '.bin', 'tsx')
+const pkg = join(dirname(fileURLToPath(import.meta.url)), '..') // spec-cli/
 const cli = join(pkg, 'src', 'cli.ts')
+// tsx lives in spec-cli/node_modules in the dev monorepo, but at the PUBLISHED package root's
+// node_modules (one level up: spec-cli is a subdir of the `spexcode` tarball) when installed. Try both.
+const tsxCandidates = [join(pkg, 'node_modules', '.bin', 'tsx'), join(pkg, '..', 'node_modules', '.bin', 'tsx')]
+const tsx = tsxCandidates.find(existsSync) ?? tsxCandidates[0]
 spawn(tsx, [cli, ...process.argv.slice(2)], { stdio: 'inherit' })
   .on('exit', (code) => process.exit(code ?? 0))

package/spec-cli/hooks/dispatch.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# @@@ dispatch - the SINGLE hook entry point for ALL harness lifecycle events. The shim (.claude/settings.json
+# / .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.
+set -u
+# args: `<harness> <Event>`. A harness id as $1 (claude|codex) 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.
+harness=claude
+case "${1:-}" in claude|codex) harness="$1"; shift ;; esac
+event="${1:?usage: dispatch.sh <harness> <Event>}"
+export SPEXCODE_HARNESS="$harness"
+# the harness.sh path (the adapter's shell mirror) — sibling of this script; hook handlers source it, and we
+# source it here too for hp_runtime_dir (the per-project store dir).
+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.
+rt="$(cd "$proj" 2>/dev/null && hp_runtime_dir)" || rt=""
+
+# --- (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
+  ( flock 9
+    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
+  ) 9>"$rt/.materialize.lock"
+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
+trap 'rm -f "$err"' EXIT
+rc=0
+# manifest line: event<TAB>order<TAB>block<TAB>script  (pre-sorted by event,order,script)
+while IFS=$'\t' read -r ev order block script; do
+  [ "$ev" = "$event" ] || continue
+  out="$(printf '%s' "$input" | bash "$proj/$script" 2>"$err")"; code=$?
+  [ -n "$out" ] && printf '%s' "$out"
+  if [ "$block" = "true" ] && { [ "$code" = "2" ] || printf '%s' "$out" | grep -q '"decision"[[:space:]]*:[[:space:]]*"block"'; }; then
+    cat "$err" >&2
+    # codex reads a Stop block's continuation prompt from STDERR (+ exit 2), NOT the claude-style
+    # decision:block JSON a handler writes to stdout. So when we block on the JSON path under codex and the
+    # handler left stderr empty, extract its "reason" and forward it to stderr — else codex sees exit 2 with
+    # no stderr ("Stop hook exited with code 2 but did not write a continuation prompt"). Claude is unchanged
+    # (it keeps reading the stdout JSON). The reason is the JSON's last field, so capture to the final `"}`.
+    if [ "$SPEXCODE_HARNESS" = codex ] && [ ! -s "$err" ]; then
+      printf '%s' "$out" | sed -n 's/.*"reason"[[:space:]]*:[[:space:]]*"\(.*\)"[[:space:]]*}[[:space:]]*$/\1/p' \
+        | sed 's/\\"/"/g; s/\\\\/\\/g' >&2
+    fi
+    rc=2
+  fi
+done < "$manifest"
+exit "$rc"

package/spec-cli/hooks/harness.sh

@@ -0,0 +1,178 @@
+#!/usr/bin/env bash
+# @@@ harness.sh - the SHELL face of the [[harness-adapter]] (spec-cli/src/harness.ts). The hook scripts run
+# as pure shell, so they cannot import the TS adapter; this sourced library is its mirror. dispatch.sh sources
+# it and exports SPEXCODE_HARNESS (claude|codex) — baked into the shim by each adapter, so a hook learns its
+# harness deterministically, never by sniffing the payload shape. EVERY harness-divergent payload-parse lives
+# HERE; the hook scripts stay harness-agnostic and just call hp_* (the one place Claude's tool names appear in
+# shell, plus codex's Bash-command mapping). The session-id + global-store resolution is harness-agnostic and
+# lives here too, so the six hooks no longer each repeat the git-common-dir → project-key dance.
+
+# the string value of a top-level JSON string field (first match). Harness-agnostic — both harnesses' payloads
+# carry session_id / tool_name as plain string fields. $1 = payload, $2 = field name. The value is scanned as a
+# real JSON string: the closing quote is the first UNESCAPED `"`, so a value containing `\"` (a quoted literal
+# inside a codex Bash/apply_patch command — extremely common) is captured WHOLE, not truncated at the inner
+# quote. The standard escapes are decoded (`\"` `\\` `\/` `\n` `\t` `\r` `\b` `\f`), so a patch envelope's `\n`
+# arrives as a real newline here (the downstream codex decode then no-ops). Pure awk, no jq on the hot path.
+hp_field() {
+  printf '%s' "$1" | awk -v field="$2" '
+    BEGIN { s = ""; while ((getline line) > 0) s = s (s == "" ? "" : "\n") line }
+    END {
+      key = "\"" field "\""
+      n = length(s); i = 1
+      while (i <= n) {
+        p = index(substr(s, i), key)
+        if (p == 0) exit
+        i += p + length(key) - 1
+        # skip whitespace, require a colon, skip whitespace, require an opening quote
+        while (i <= n && substr(s, i, 1) ~ /[ \t\n]/) i++
+        if (substr(s, i, 1) != ":") continue
+        i++
+        while (i <= n && substr(s, i, 1) ~ /[ \t\n]/) i++
+        if (substr(s, i, 1) != "\"") continue
+        i++
+        out = ""
+        while (i <= n) {
+          c = substr(s, i, 1)
+          if (c == "\\") {
+            e = substr(s, i + 1, 1)
+            if      (e == "n") out = out "\n"
+            else if (e == "t") out = out "\t"
+            else if (e == "r") out = out "\r"
+            else if (e == "b") out = out "\b"
+            else if (e == "f") out = out "\f"
+            else               out = out e   # \" \\ \/ and any other → the literal char
+            i += 2
+          } else if (c == "\"") {
+            print out; exit
+          } else {
+            out = out c; i++
+          }
+        }
+        exit
+      }
+    }'
+}
+
+# the session id from a payload (both harnesses use session_id).
+# the GOVERNED record id the launcher baked into the session env (SPEXCODE_SESSION_ID) wins over the harness's
+# own payload session_id. This is what lets a dashboard-launched CODEX session feed its governed record: codex
+# mints its OWN thread id (un-pinnable), so the record can't be keyed by it — instead the launcher keys the
+# record by a SpexCode id and exports it into the launch, and every hook resolves THAT. Claude's payload id is
+# already the record id, so the env (= same value) is a harmless no-op there. A self-launched agent sets no
+# env → falls back to the payload session_id (its own non-governed record). One resolver, both harnesses.
+hp_session_id() { printf '%s' "${SPEXCODE_SESSION_ID:-$(hp_field "$1" 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.
+# Echoes the dir; returns non-zero (echoing nothing) when git can't resolve, so a caller can `|| exit 0`.
+hp_runtime_dir() {
+  local gcd
+  gcd=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null) || gcd=$(realpath "$(git rev-parse --git-common-dir 2>/dev/null)" 2>/dev/null)
+  [ -n "$gcd" ] || return 1
+  printf '%s/projects/%s' "${SPEXCODE_HOME:-$HOME/.spexcode}" "$(printf '%s' "$(dirname "$gcd")" | 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 carries NO
+# SPEXCODE_SESSION_ID, so hp_session_id falls back to the payload session_id = the codex THREAD id — NOT the
+# SpexCode record id the dir is keyed by. So when no record sits at <id> directly, find the one record that
+# captured this id as `harness_session_id` (the backend stored it at thread/start, before the first tool turn).
+# A grep over the few session.json files — no jq on the hot path; the trailing quote anchors the value so a
+# thread id can't match a longer one as a prefix. Direct hit wins; a miss with no alias echoes the direct path
+# unchanged, so the caller's `[ -e "$rec" ]` still no-ops gracefully. Mirrors layout.ts `readAliasedRawRecord`.
+hp_store_dir() {
+  local rd; rd=$(hp_runtime_dir) || return 1
+  local direct="$rd/sessions/$1"
+  if [ -e "$direct/session.json" ]; then printf '%s' "$direct"; return 0; fi
+  local hit
+  hit=$(grep -lF "\"harness_session_id\": \"$1\"" "$rd"/sessions/*/session.json 2>/dev/null | head -1)
+  [ -n "$hit" ] && { printf '%s' "${hit%/session.json}"; return 0; }
+  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").
+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
+}
+
+# the tool a payload is about to run / just ran (harness-agnostic field name).
+hp_tool() { hp_field "$1" tool_name; }
+
+# is THIS payload the agent pausing to ask the HUMAN a question? Claude: the AskUserQuestion tool. Codex: the
+# experimental request_user_input tool (its only structured ask path). Echoes "1" when yes, else nothing.
+hp_is_ask() {
+  case "$SPEXCODE_HARNESS" in
+    codex) [ "$(hp_tool "$1")" = request_user_input ] && printf 1 ;;
+    *)     [ "$(hp_tool "$1")" = AskUserQuestion ] && printf 1 ;;
+  esac
+}
+
+# the question text of an ask payload (best-effort; for the board note). Both harnesses carry it under a
+# "question" field of the tool input — so it is just the first such JSON string value: collapse onto hp_field,
+# which (unlike the old grep `[^"]*`) handles an embedded `\"` and decodes escapes instead of truncating.
+hp_ask_note() { hp_field "$1" question; }
+
+# the CODE file(s) a payload touches, mapped to the trigger the spec hooks key on. $2 = mode:
+#   access  → the file being READ or edited ([[spec-first]] fires on any code touch)
+#   mutate  → the file being EDITED      ([[spec-of-file]] fires only on a mutation)
+# Echoes the path(s), ONE PER LINE — a codex multi-file apply_patch (several `*** Update File:` markers)
+# touches several files in one tool call, so every consuming hook iterates the lines. Echoes nothing when the
+# payload is not a code touch of that mode. The harness divergence:
+#   Claude — Read/Edit/Write/NotebookEdit + tool_input.file_path|notebook_path.
+#   Codex  — NO file_path. An EDIT is its own first-class tool `tool_name:"apply_patch"` whose tool_input.command
+#            is the bare patch envelope (`*** Update File: <path>`); a READ/shell is `tool_name:"Bash"` +
+#            tool_input.command. Both carry the touched file inside `command`, so we parse that one field.
+hp_code_path() {
+  local payload="$1" mode="$2" tool
+  tool=$(hp_tool "$payload")
+  case "$SPEXCODE_HARNESS" in
+    codex)
+      case "$tool" in apply_patch|Bash) ;; *) return 0 ;; esac
+      _hp_codex_cmd_path "$(hp_field "$payload" command)" "$mode"
+      ;;
+    *)
+      case "$mode" in
+        mutate) case "$tool" in Edit|Write|NotebookEdit) ;; *) return 0 ;; esac ;;
+        *)      case "$tool" in Read|Edit|Write|NotebookEdit) ;; *) return 0 ;; esac ;;
+      esac
+      local p; p=$(hp_field "$payload" file_path); [ -n "$p" ] || p=$(hp_field "$payload" notebook_path)
+      printf '%s' "$p"
+      ;;
+  esac
+}
+
+# @@@ codex command → path - the apply_patch / sed / cat path-extractor. Codex never sends a file_path; the
+# touched file lives inside `command`. Two shapes: a PATCH envelope carries `*** (Add|Update|Delete) File:
+# <path>` lines (always a MUTATION) — this is what the apply_patch tool sends, the bare envelope with NO literal
+# `apply_patch` token, so we detect it by the File: markers themselves (the legacy `apply_patch` token is kept
+# too, for a shell-wrapped invocation); a plain command (sed/cat/head/rg/…) carries the path as a token.
+# A MUTATION is a patch envelope or a write shape (a redirect, tee, `sed -i`, dd of=); in `mutate` mode a pure
+# read yields nothing. A patch envelope can carry SEVERAL `*** Update File:` markers (a multi-file edit) — ALL
+# of them are emitted, one per line, so the consuming hook acts on every touched file (a single-file patch
+# emits one line; a plain command emits its one token). The plain-command path is the last path-like token
+# (has a / or a .ext), ignoring flags — matches the verified-facts example `sed -n 1p f.ts` → `f.ts`.
+# Best-effort: an exotic command may not resolve, which only means a missed nudge, never a wrong block.
+_hp_codex_cmd_path() {
+  local mode="$2" cmd
+  # the command arrives as a JSON STRING value; hp_field already decodes JSON escapes (so a patch File: line
+  # already ends at a real newline). This gsub is a no-op safety net for any caller that bypassed hp_field.
+  cmd=$(printf '%s' "$1" | awk '{gsub(/\\n/,"\n"); gsub(/\\t/,"\t")}1')
+  case "$cmd" in
+    *apply_patch*|*applypatch*|*'*** Add File:'*|*'*** Update File:'*|*'*** Delete File:'*)
+      printf '%s\n' "$cmd" | sed -n 's/^\*\*\* \(Add\|Update\|Delete\) File: \(.*\)$/\2/p' | sed 's/[[:space:]]*$//'
+      return 0 ;;
+  esac
+  local is_mutate=0
+  case "$cmd" in *' >> '*|*' > '*|*' >>'*|*' >'*|*' tee '*|*'sed -i'*|*' dd '*) is_mutate=1 ;; esac
+  [ "$mode" = mutate ] && [ "$is_mutate" = 0 ] && return 0
+  printf '%s\n' "$cmd" | tr ' \t' '\n\n' | grep -E '^[^-].*[/.][A-Za-z0-9_]+' | grep -vE '^(apply_patch|applypatch)$' | tail -1
+}
+
+# the notification type of a Notification payload (Claude only — Codex fires no Notification event).
+hp_notification_type() { hp_field "$1" notification_type; }

package/{src → spec-cli/src}/cli.ts

@@ -293,6 +293,20 @@ if (cmd === 'serve') {
     if (r.snippet) console.log(`    ${r.snippet}`)
   })
   process.exit(0)
+} else if (cmd === 'relay') {
+  const { relaySearch } = await import('./relay.js')
+  const query = positionals(3).join(' ')
+  if (!query.trim()) { console.error('usage: spex relay <query> [--json] [--limit N]'); process.exit(2) }
+  const limit = Number(flag('limit')) || 3
+  const hits = await relaySearch(query, { limit })
+  if (has('json')) { console.log(JSON.stringify(hits)); process.exit(0) }
+  if (!hits.length) { console.log(`no spec node matches "${query}"`); process.exit(0) }
+  hits.forEach((h, i) => {
+    console.log(`${String(i + 1).padStart(2)}. ${h.title}  [${h.id}]  ·  score ${h.score}`)
+    if (h.code.length) h.code.forEach((c) => console.log(`    ${c}`))
+    else console.log(`    (no governed code: files — a pure-prose node)`)
+  })
+  process.exit(0)
 } else if (cmd === 'ls' || cmd === 'sessions') {
   // pretty list of living sessions + states. `spex ls [SEL...] [--status a,b] [--json]`
   // the board comes from the backend (so `spex ls` shows the sessions of whatever SPEXCODE_API_URL points at,

package/{src → spec-cli/src}/harness.ts

@@ -8,6 +8,7 @@ import { promisify } from 'node:util'
 import { fileURLToPath } from 'node:url'
 import { claudeSlashCommands, codexSlashCommands, type SlashCommand } from './slash-commands.js'
 import { runtimeRoot, mainCheckout } from './layout.js'
+import { tsxBin } from './tsx-bin.js'
 
 // @@@ harness-adapter - the ONE seam between SpexCode and the coding-agent harness (Claude Code, Codex, …).
 // Every harness-specific fact lives behind THIS interface with one implementation per harness; product code
@@ -124,7 +125,7 @@ function shQuote(s: string): string {
 // launch shell can call back into `spex codex-launch` to own the thread + fire the first turn before it
 // exec's the visible TUI.
 const PKG = fileURLToPath(new URL('..', import.meta.url))
-const SPEX = `${join(PKG, 'node_modules', '.bin', 'tsx')} ${join(PKG, 'src', 'cli.ts')}`
+const SPEX = `${tsxBin(PKG)} ${join(PKG, 'src', 'cli.ts')}`
 
 const ACCEPT_TIMEOUT_MS = 2500
 // @@@ replyViaSocket - inject `text` as a prompt AND confirm the daemon ACCEPTED it (not mere write-success,
@@ -258,19 +259,11 @@ export function codexLaunchCommand(_id: string, codexCmd = process.env.SPEXCODE_
     '    for i in $(seq 1 100); do [ -S "$sock" ] && break; sleep 0.05; done',
     '  fi',
     ') 9>"$lock"',
-    // TWO launch modes, on ONE tail channel ("$@"). reopen() hands a `--resume <thread-id>` tail (see
-    // codexHarness.resumeArg) to bring the SAME conversation back: resume that OWNED thread DIRECTLY — no new
-    // thread, no first-turn prompt. ANY other tail is a NEW launch: BACKEND owns the thread — `codex-launch`
-    // does thread/start { cwd = this worktree } on the shared per-project app-server, stores the new id on the
-    // governed record (SPEXCODE_SESSION_ID), and fires the tail as the FIRST turn, materializing the rollout.
-    // Either way it ends with a thread id, which the visible TUI then RESUMES (the rollout persists on disk),
-    // rendering it natively. A new launch's tail is always ONE single-quoted prompt arg, so it can never be the
-    // literal "--resume" marker — the discriminator is unambiguous.
-    `if [ "$1" = "--resume" ]; then`,
-    `  tid=$2`,
-    `else`,
-    `  tid=$(${SPEX} codex-launch "$sock" "$PWD" "$@")`,
-    `fi`,
+    // BACKEND owns the thread: `codex-launch` does thread/start { cwd = this worktree } on the shared
+    // per-project app-server, stores the new thread id on the governed record (SPEXCODE_SESSION_ID), and
+    // fires the launch prompt as the first turn — materializing the rollout. It prints the thread id, which
+    // the visible TUI then RESUMES (the rollout persists on disk), rendering it natively. "$@" is the prompt.
+    `tid=$(${SPEX} codex-launch "$sock" "$PWD" "$@")`,
     `exec ${codexCmd} --remote unix://"$sock" resume "$tid"`,
   ].join('\n')
   return `bash -lc ${shQuote(script)} spexcode-codex`
@@ -653,10 +646,7 @@ export const codexHarness: Harness = {
   slashCommands: codexSlashCommands,
   liveness: (rec, tmuxAlive, runtimeDir) => (tmuxAlive && existsSync(codexAppServerSock(runtimeDir)) ? 'online' : 'offline'),
   deliver: (rec, text) => deliverViaCodexAppServer(rec, text),
-  // owned thread id → `--resume <id>` MARKER the codex launch script reads to resume that thread DIRECTLY (NOT
-  // a tail handed to a bare `codex` — the script's final `codex … resume "$tid"` performs codex's own resume on
-  // the owned id, the SAME conversation); none → empty tail → relaunch a FRESH thread on the same worktree/record.
-  resumeArg: (rec) => (rec.harnessSessionId ? `--resume ${rec.harnessSessionId}` : ''),
+  resumeArg: (rec) => (rec.harnessSessionId ? `resume ${rec.harnessSessionId}` : ''),   // owned thread id → codex `resume <id>` (SAME conversation); none → relaunch FRESH
 }
 
 // every adapter — materialize iterates this to render each harness's artifacts in one pass.

package/{src → spec-cli/src}/layout.ts

@@ -125,30 +125,13 @@ export type RawRecord = {
   sortkey: number | null; createdAt: number; harness?: string; harness_session_id?: string
 }
 // the agent's OWN session id from the environment — the only locator now that the record left the worktree.
-// Three tiers, in order:
-//   (1) a harness's per-thread env var (`sessionEnvVar`) RESOLVED VIA THE ALIAS — when it lands on a governed
-//       record (directly, or through that record's `harness_session_id`), that record's SpexCode id is the
-//       answer. This MUST win: codex's design-C runs ONE shared per-project app-server whose env carries the
-//       FIRST launched session's `SPEXCODE_SESSION_ID`, and the agent's shell tool (its `spex session
-//       done/park/ask`) runs INSIDE that app-server process, so `SPEXCODE_SESSION_ID` is contaminated with the
-//       wrong session. But codex injects the ACTING thread's id into every spawned command's env as
-//       CODEX_THREAD_ID (== codex's `sessionEnvVar`), so the per-thread var aliases to the RIGHT record while
-//       the shared `SPEXCODE_SESSION_ID` does not.
-//   (2) else `SPEXCODE_SESSION_ID` (the GOVERNED record id the launcher bakes in) — the claude path and the
-//       non-shared baseline, mirroring the shell hooks' `hp_session_id`.
-//   (3) else a harness's env var RAW — a self-launched, non-governed agent's own minted id, which has no
-//       governed record to alias to (codex CODEX_THREAD_ID / claude CLAUDE_CODE_SESSION_ID). The RAW form must
-//       stay BELOW (2): an un-aliased codex thread id is not a record key, so it must never beat a real
-//       `SPEXCODE_SESSION_ID`.
-// Claude is UNCHANGED: its `sessionEnvVar` (CLAUDE_CODE_SESSION_ID) already EQUALS its record id, so tier (1)
-// resolves to that very id — the same value `SPEXCODE_SESSION_ID` would have returned; there is no shared
-// app-server to contaminate it. No worktree fallback. (sessions.ts's `ownSessionId` delegates here; spec-yatsu
-// reads it to resolve the current node.)
+// SPEXCODE_SESSION_ID (the GOVERNED record id the launcher bakes in) wins, EXACTLY mirroring the shell hooks'
+// `hp_session_id` — this matters for codex, whose own CODEX_THREAD_ID is its un-pinnable minted id and does NOT
+// equal the governed record id, so resolving the harness var first would point a governed codex agent's own
+// `spex session …` at the wrong/nonexistent record. Else each adapter's env var (Claude CLAUDE_CODE_SESSION_ID
+// — already == the record id; Codex CODEX_THREAD_ID for a self-launched, non-governed agent). No worktree
+// fallback. (sessions.ts's `ownSessionId` delegates here; spec-yatsu reads it to resolve the current node.)
 export function envSessionId(): string | null {
-  for (const h of HARNESSES) {
-    const v = process.env[h.sessionEnvVar]
-    if (v && v.trim()) { const r = readAliasedRawRecord(v.trim()); if (r) return r.session_id }
-  }
   const o = process.env.SPEXCODE_SESSION_ID
   if (o && o.trim()) return o.trim()
   for (const h of HARNESSES) { const v = process.env[h.sessionEnvVar]; if (v && v.trim()) return v.trim() }

package/{src → spec-cli/src}/materialize.ts

@@ -6,6 +6,7 @@ import { loadSystemConfig, loadSkillConfig } from './specs.js'
 import { compileManifest } from './hooks.js'
 import { HARNESSES, writeManagedBlock } from './harness.js'
 import { runtimeRoot } from './layout.js'
+import { tsxBin } from './tsx-bin.js'
 
 // @@@ materialize - the "pay-per-change" node step (≈0.85s) the cheap shell gate invokes ONLY when the
 // .config content-hash moved. It renders the spec tree's surface nodes into the flat artifacts each
@@ -19,7 +20,7 @@ import { runtimeRoot } from './layout.js'
 
 const PKG = fileURLToPath(new URL('..', import.meta.url))                 // installed spec-cli root
 const DISPATCH = join(PKG, 'hooks', 'dispatch.sh')
-const SPEX = `${join(PKG, 'node_modules', '.bin', 'tsx')} ${join(PKG, 'src', 'cli.ts')}`
+const SPEX = `${tsxBin(PKG)} ${join(PKG, 'src', 'cli.ts')}`
 // the manifest + content-hash marker render into the GLOBAL per-project store (layout.runtimeRoot), NOT the
 // worktree — the worktree keeps zero SpexCode-rendered runtime; only the harness-discovered contract files +
 // shims (which the harness must find in-tree) are written under proj below.

package/spec-cli/src/relay.ts

@@ -0,0 +1,28 @@
+import { searchSpecs } from './search.js'
+import { loadSpecs } from './specs.js'
+
+export type RelayHit = { id: string; title: string; path: string; score: number; code: string[] }
+
+export async function relaySearch(query: string, opts: { limit?: number } = {}): Promise<RelayHit[]> {
+  const limit = opts.limit ?? 3
+  const hits = await searchSpecs(query, { limit })
+  if (!hits.length) return []
+  // one spec-index read; per node: its frontmatter `code:` governed paths (files/dirs/globs) + the tree shape.
+  const specs = await loadSpecs()
+  const codeById = new Map(specs.map((s) => [s.id, (s.code as string[]) ?? []]))
+  const childrenOf = new Map<string, string[]>()
+  for (const s of specs) if (s.parent) childrenOf.set(s.parent, [...(childrenOf.get(s.parent) ?? []), s.id])
+  const subtreeCode = (id: string): string[] => {
+    const own = codeById.get(id) ?? []
+    if (own.length) return own
+    const acc: string[] = []
+    const stack = [...(childrenOf.get(id) ?? [])]
+    while (stack.length) {
+      const c = stack.pop()!
+      acc.push(...(codeById.get(c) ?? []))
+      stack.push(...(childrenOf.get(c) ?? []))
+    }
+    return [...new Set(acc)]
+  }
+  return hits.map((h) => ({ id: h.id, title: h.title, path: h.path, score: h.score, code: subtreeCode(h.id) }))
+}

package/{src → spec-cli/src}/supervise.ts

@@ -8,13 +8,14 @@ import { fileURLToPath } from 'node:url'
 import { dirname, join } from 'node:path'
 import { installProcessGuards } from './resilience.js'
 import { resolvePublicConfig, startGateway, ensureDashboardBuilt, resolveDistDir } from './gateway.js'
+import { tsxBin } from './tsx-bin.js'
 
 // the supervisor OWNS the public port, so it must outlive any transient throw: an uncaught error here is
 // logged and survived, never an exit that closes the port (and the tmux session) and takes the frontend down.
 installProcessGuards()
 
 const here = dirname(fileURLToPath(import.meta.url))
-const tsx = join(here, '..', 'node_modules', '.bin', 'tsx')   // this package's own tsx (no build step)
+const tsx = tsxBin(join(here, '..'))   // this package's own tsx — spec-cli/node_modules (dev) or pkg root (published)
 const entry = join(here, 'index.ts')                          // the real Hono server
 const publicPort = Number(process.env.PORT || 8787)
 

package/spec-cli/src/tsx-bin.ts

@@ -0,0 +1,11 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+// @@@ tsxBin - where the tsx executable lives, dev-or-published. In the dev monorepo it sits in
+// spec-cli/node_modules; in the PUBLISHED `spexcode` tarball spec-cli is a SUBDIR of the package, so tsx
+// installs one level up at the package ROOT's node_modules. Resolve against both so the supervisor's child
+// spawn and the baked launch/hook SPEX commands work in either layout. `pkgDir` is the spec-cli directory.
+export function tsxBin(pkgDir: string): string {
+  const candidates = [join(pkgDir, 'node_modules', '.bin', 'tsx'), join(pkgDir, '..', 'node_modules', '.bin', 'tsx')]
+  return candidates.find(existsSync) ?? candidates[0]
+}