spexcode 0.6.7 → 0.7.0-next.0

package/node_modules/@spexcode/spec-cli/hooks/dispatch.sh

@@ -16,27 +16,23 @@
 # session-worktree creation, and the pre-commit/post-checkout/post-merge hooks). .plugins 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|opencode|pi|zcode|plugin) is consumed; otherwise we keep
-# $1 as the 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]]), `opencode` the generated event-bus plugin
+# args: `<harness> <Event>`. The harness id is explicit. `plugin` is the bundle form ([[plugin-harness]]),
+# `opencode` the generated event-bus plugin
 # ([[opencode-harness]]), `pi` the generated extension ([[pi-harness]]), and `zcode` the native adapter: all four
 # carry Claude-shaped payloads (Claude tool names + file_path), so they join the claude branch in harness.sh via
 # the default case — no parse arm of their own.
 harness=claude
-case "${1:-}" in claude|codex|opencode|pi|zcode|plugin) harness="$1"; shift ;; esac
+case "${1:-}" in claude|codex|opencode|pi|zcode|plugin) harness="$1"; shift ;; *)
+  printf 'dispatch.sh: missing or unknown harness id\n' >&2
+  exit 64
+;; 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).
 hook_root="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-tool_root="$(cd "$hook_root/.." && pwd)"
 export SPEXCODE_HARNESS_LIB="$hook_root/harness.sh"
 . "$SPEXCODE_HARNESS_LIB"
-if [ -n "${SPEX:-}" ]; then
-  read -r -a spex_cmd <<< "$SPEX"
-else
-  spex_cmd=("$tool_root/bin/spex.mjs")
-fi
 proj="${CLAUDE_PROJECT_DIR:-$PWD}"
 # 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
@@ -46,8 +42,7 @@ rt="$(cd "$proj" 2>/dev/null && hp_runtime_dir)" || rt=""
 slot="$(cd "$proj" 2>/dev/null && hp_tree_dir)" || slot=""
 
 # A project transport can outlive the tree that installed it. The current tree's last successful materialize
-# is the authority for whether its events are active. Before the v1 marker, an absent allowlist is the legacy
-# shape; afterwards absence means this tree never successfully selected a harness and dispatch stays inert.
+# is the authority for whether its events are active. A tree without a published selection is inert.
 allowed="$slot/harnesses"
 if [ -f "$allowed" ]; then
   grep -Fxq "$harness" "$allowed" || exit 0
@@ -56,17 +51,8 @@ elif [ -f "$rt/harness-selection-v1" ]; then
 fi
 
 # --- 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
-[ -f "$manifest" ] || exit 0          # no manifest yet (materialize never ran) → nothing to dispatch
+manifest="${SPEX_HOOK_MANIFEST:-$slot/hooks-manifest}"
+[ -f "$manifest" ] || { printf 'dispatch.sh: current tree has no hook manifest\n' >&2; exit 78; }
 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
 cleanup() { rm -f "$err"; }
@@ -78,14 +64,6 @@ rc=0
 while IFS=$'\t' read -r ev order block script; do
   [ "$ev" = "$event" ] || continue
   handler="$proj/$script"
-  # A seeded core hook is tracked project source, so package replacement cannot safely overwrite it. These
-  # byte-exact default revisions compose an ask note into JSON with sed; route only them to the package
-  # implementation. `cmp` makes a user-modified hook ineligible without a platform-specific hash utility.
-  if [ "$script" = '.spec/project/.plugins/core/mark-active/mark-active.sh' ] &&
-    { cmp -s "$handler" "$hook_root/compat/mark-active-sed-v0.fixture" ||
-      cmp -s "$handler" "$hook_root/compat/mark-active-0.5.2-eef1.fixture"; }; then
-    handler="$tool_root/templates/spec/project/.plugins/core/mark-active/mark-active.sh"
-  fi
   out="$(printf '%s' "$input" | bash "$handler" 2>"$err")"; code=$?
   [ -n "$out" ] && printf '%s' "$out"
   if [ "$block" = "true" ] && { [ "$code" = "2" ] || printf '%s' "$out" | grep -q '"decision"[[:space:]]*:[[:space:]]*"block"'; }; then
@@ -101,5 +79,15 @@ while IFS=$'\t' read -r ev order block script; do
     fi
     rc=2
   fi
+  # FAIL LOUD. A non-blocking handler's failure used to vanish completely: its exit code was dropped and its
+  # stderr was overwritten by the next handler and deleted on exit, so a lifecycle hook that could not write
+  # left NO trace anywhere — the board kept whatever state it last held and the reader had to guess whether
+  # the hook had run at all. That silence is what let a whole fleet's mark-active and stop-gate die unnoticed.
+  # Reporting is all this does: a non-blocking hook must not change the dispatch verdict, so `rc` stays the
+  # blocking handlers' to set, and a noisy hook can never turn into a gate.
+  if [ "$code" != 0 ] && [ "$block" != "true" ]; then
+    printf 'dispatch.sh: %s handler %s exited %s\n' "$event" "$script" "$code" >&2
+    [ -s "$err" ] && cat "$err" >&2
+  fi
 done < "$manifest"
 exit "$rc"

package/node_modules/@spexcode/spec-cli/hooks/harness.sh

@@ -84,8 +84,8 @@ hp_session_id() {
     codex) hp_field "$1" session_id ;;
     *)     pid=$(hp_field "$1" session_id)
            if [ -n "$pid" ] && [ -n "$SPEXCODE_SESSION_ID" ] && [ "$pid" != "$SPEXCODE_SESSION_ID" ] \
-              && [ ! -e "$(hp_store_dir "$pid")/session.json" ] \
-              && [ -e "$(hp_store_dir "$SPEXCODE_SESSION_ID")/session.json" ]; then
+              && [ ! -e "$(hp_store_dir "$pid")/runtime.json" ] \
+              && [ -e "$(hp_store_dir "$SPEXCODE_SESSION_ID")/runtime.json" ]; then
              printf '%s' "$SPEXCODE_SESSION_ID"
            else
              printf '%s' "${pid:-$SPEXCODE_SESSION_ID}"
@@ -139,19 +139,19 @@ hp_tree_dir() {
 # payload session_id on codex: 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
+# A grep over the few runtime.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
+  if [ -e "$direct/runtime.json" ]; then printf '%s' "$direct"; return 0; fi
   # same two-halves-of-absence rule as layout.ts's readAliasedRecordEntry: an id owning a store dir is already
   # one of ours, so its emptiness is settled and the alias grep is the wrong question (and a whole-store scan).
   if [ -d "$direct" ]; 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; }
+  hit=$(grep -lF "\"harness_session_id\": \"$1\"" "$rd"/sessions/*/runtime.json 2>/dev/null | head -1)
+  [ -n "$hit" ] && { printf '%s' "${hit%/runtime.json}"; return 0; }
   printf '%s' "$direct"
 }
 

package/node_modules/@spexcode/spec-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spexcode/spec-cli",
-  "version": "0.6.7",
+  "version": "0.7.0-next.0",
   "type": "module",
   "description": "SpexCode CLI + server. The root spexcode package delegates to this compiled package; dashboard assets live in @spexcode/spec-dashboard.",
   "bin": {
@@ -21,7 +21,6 @@
   ],
   "bundledDependencies": [
     "@spexcode/spec-core",
-    "@spexcode/session-core",
     "@spexcode/spec-eval",
     "@spexcode/spec-forge"
   ],
@@ -36,10 +35,13 @@
     "test": "tsx --import ../scripts/test-home.mjs --test src/*.test.ts"
   },
   "dependencies": {
-    "@spexcode/session-core": "0.6.7",
-    "@spexcode/spec-core": "0.6.7",
-    "@spexcode/spec-eval": "0.6.7",
-    "@spexcode/spec-forge": "0.6.7"
+    "@spexcode/session-application": "0.7.0-next.0",
+    "@spexcode/session-selflaunch": "0.7.0-next.0",
+    "@spexcode/spec-core": "0.7.0-next.0",
+    "@spexcode/spec-eval": "0.7.0-next.0",
+    "@spexcode/spec-forge": "0.7.0-next.0",
+    "@spexcode/transcript": "0.7.0-next.0",
+    "smol-toml": "^1.8.0"
   },
   "devDependencies": {
     "@types/node": "^20.16.0",

package/node_modules/@spexcode/spec-cli/templates/hooks/post-checkout

@@ -15,10 +15,12 @@
 [ "${SPEXCODE_DEFER_FOOTPRINT_REFRESH:-}" = "session-create" ] && exit 0
 main_root=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)")
 repo_root=$(git rev-parse --show-toplevel 2>/dev/null)
-if command -v spex >/dev/null 2>&1; then
-  spex internal refresh-footprint >/dev/null 2>&1 || true
+if [ -x "$repo_root/spec-cli/bin/spex.mjs" ]; then
+  "$repo_root/spec-cli/bin/spex.mjs" internal refresh-footprint >/dev/null 2>&1 || true
 elif [ -x "$repo_root/node_modules/.bin/spex" ]; then
   "$repo_root/node_modules/.bin/spex" internal refresh-footprint >/dev/null 2>&1 || true
+elif command -v spex >/dev/null 2>&1; then
+  spex internal refresh-footprint >/dev/null 2>&1 || true
 elif [ -x "$main_root/spec-cli/bin/spex.mjs" ]; then
   "$main_root/spec-cli/bin/spex.mjs" internal refresh-footprint >/dev/null 2>&1 || true
 fi

package/node_modules/@spexcode/spec-cli/templates/hooks/post-merge

@@ -13,8 +13,9 @@
 main_root=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)")
 repo_root=$(git rev-parse --show-toplevel 2>/dev/null)
 spex_run() {
-  if command -v spex >/dev/null 2>&1; then spex "$@"
+  if [ -x "$repo_root/spec-cli/bin/spex.mjs" ]; then "$repo_root/spec-cli/bin/spex.mjs" "$@"
   elif [ -x "$repo_root/node_modules/.bin/spex" ]; then "$repo_root/node_modules/.bin/spex" "$@"
+  elif command -v spex >/dev/null 2>&1; then spex "$@"
   elif [ -x "$main_root/spec-cli/bin/spex.mjs" ]; then "$main_root/spec-cli/bin/spex.mjs" "$@"
   else return 127; fi
 }

package/node_modules/@spexcode/spec-cli/templates/hooks/pre-commit

@@ -12,10 +12,12 @@
 main_root=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)")
 repo_root=$(git rev-parse --show-toplevel 2>/dev/null)
 spex_kind=
-if command -v spex >/dev/null 2>&1; then
-  spex_kind=path
+if [ -x "$repo_root/spec-cli/bin/spex.mjs" ]; then
+  spex_kind=pkg
 elif [ -x "$repo_root/node_modules/.bin/spex" ]; then
   spex_kind=local
+elif command -v spex >/dev/null 2>&1; then
+  spex_kind=path
 elif [ -x "$main_root/spec-cli/bin/spex.mjs" ]; then
   spex_kind=pkg
 fi
@@ -23,7 +25,7 @@ spex_cli() {
   case "$spex_kind" in
     path)  spex "$@" ;;
     local) "$repo_root/node_modules/.bin/spex" "$@" ;;
-    pkg)   "$main_root/spec-cli/bin/spex.mjs" "$@" ;;
+    pkg)   if [ -x "$repo_root/spec-cli/bin/spex.mjs" ]; then "$repo_root/spec-cli/bin/spex.mjs" "$@"; else "$main_root/spec-cli/bin/spex.mjs" "$@"; fi ;;
     *)     return 127 ;;
   esac
 }

package/node_modules/@spexcode/spec-cli/templates/hooks/reference-transaction

@@ -65,10 +65,12 @@ fi
 main_root=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)")
 repo_root=$(git rev-parse --show-toplevel 2>/dev/null)
 spex_kind=
-if command -v spex >/dev/null 2>&1; then
-  spex_kind=path
+if [ -x "$repo_root/spec-cli/bin/spex.mjs" ]; then
+  spex_kind=pkg
 elif [ -x "$repo_root/node_modules/.bin/spex" ]; then
   spex_kind=local
+elif command -v spex >/dev/null 2>&1; then
+  spex_kind=path
 elif [ -x "$main_root/spec-cli/bin/spex.mjs" ]; then
   spex_kind=pkg
 fi
@@ -76,7 +78,7 @@ spex_cli() {
   case "$spex_kind" in
     path) spex "$@" ;;
     local) "$repo_root/node_modules/.bin/spex" "$@" ;;
-    pkg) "$main_root/spec-cli/bin/spex.mjs" "$@" ;;
+    pkg) if [ -x "$repo_root/spec-cli/bin/spex.mjs" ]; then "$repo_root/spec-cli/bin/spex.mjs" "$@"; else "$main_root/spec-cli/bin/spex.mjs" "$@"; fi ;;
     *) return 127 ;;
   esac
 }

package/node_modules/@spexcode/spec-cli/templates/spec/project/.plugins/commands/spec.md

@@ -21,10 +21,5 @@ resolution. A preset with `{{targets}}` always receives the resolved target bloc
 gets a target block only when the invocation actually names a target, so a targetless utility remains a small
 prompt. An unknown leading `/name` stays ordinary prompt text and is never swallowed or guessed.
 
-This node is a **shelf, not a surface** (the [[prompts]] shape): it declares no `surface` field and
-gathers nothing itself. Discovery is recursive and field-driven (surface), so a resident plugs in
-exactly as it would at the root — the gather set is path-independent, so shelving a command changes
-nothing about what `/api/plugins` and the launcher offer. A plugin that serves BOTH surfaces (e.g.
-[[distill]], skill and command) shelves once by its primary identity, never duplicated. The init
-templates mirror this layout. The shelf stays pure presentation: moving a resident beneath it changes
-neither that plugin's identity nor the surfaces gathered from its frontmatter.
+This node is a **shelf, not a surface**. Its routing and relocation invariant is owned once by
+[[.plugins]]'s shelf invariant; this node only describes command-specific discovery and invocation.

package/node_modules/@spexcode/spec-cli/templates/spec/project/.plugins/core/idle/idle.sh

@@ -1,15 +1,9 @@
 #!/usr/bin/env bash
-# On an idle_prompt notification, mark the session idle (the active-only guard in `internal session-idle` keeps a
-# deliberate awaiting/asking/parked/error declaration from being clobbered). GATED on `governed`: only a
-# dashboard-launched session has board state to mark — a self-launched agent's idle is none of our business.
-# State lives in the per-session GLOBAL record session.json (keyed by the harness session_id, grouped per-
-# project — see hp_store_dir); the id is passed to the cli via `--session` so it writes the right record
-# without depending on the worktree (which no longer holds any session file). NOTE the Notification event is
-# Claude-only ([[harness-adapter]]: Codex fires no Notification), so this never runs under Codex.
+# On an idle_prompt notification, ask the canonical lifecycle writer to infer idle. The writer owns both the
+# governed-session boundary and the active-only compare-and-set; this hook only decodes the native event and
+# passes its acting session id. NOTE the Notification event is Claude-only ([[harness-adapter]]: Codex fires no
+# Notification), so this never runs under Codex.
 . "${SPEXCODE_HARNESS_LIB:?harness.sh not exported by dispatch.sh}"
 payload=$(cat 2>/dev/null)
 sid=$(hp_session_id "$payload"); [ -n "$sid" ] || exit 0
-sdir=$(hp_store_dir "$sid") || exit 0
-rec="$sdir/session.json"
-grep -q '"governed"[[:space:]]*:[[:space:]]*true' "$rec" 2>/dev/null || exit 0
 [ "$(hp_notification_type "$payload")" = idle_prompt ] && exec ${SPEX:-spex} internal session-idle --session "$sid"

package/node_modules/@spexcode/spec-cli/templates/spec/project/.plugins/core/idle/spec.md

@@ -10,4 +10,4 @@ block: false
 ---
 Catches the undeclared stop the [[stop-gate]] misses. When the harness signals — via an idle-prompt notification — that the agent is simply sitting idle at its prompt rather than working, this hook marks the session `idle`, so a session that quietly ran out of things to do is not left reading as active on the board.
 
-It acts only on the idle-prompt notification, ignoring every other notification kind. As a board-lifecycle hook it also acts only on a GOVERNED session — it resolves the record in the global store from the payload's `session_id` and no-ops unless `governed: true` — then marks idle via `spex internal session-idle --session <id>`. It is guarded so it never clobbers a deliberate declaration: marking idle applies only to a session still in the undeclared `active` state, leaving any considered `awaiting`, `asking`, `parked`, or `error` claim untouched. Together with [[stop-gate]] and [[session-fail]] it closes the last gap where a session could stop without its true state reaching the board.
+It acts only on the idle-prompt notification, ignoring every other notification kind. As a board-lifecycle hook it passes the payload's acting `session_id` to `spex internal session-idle --session <id>`; the canonical writer owns governed-session resolution and returns a no-op for self-launched or missing records. It is guarded so it never clobbers a deliberate declaration: marking idle applies only to a session still in the undeclared `active` state, leaving any considered `awaiting`, `asking`, `parked`, or `error` claim untouched. Together with [[stop-gate]] and [[session-fail]] it closes the last gap where a session could stop without its true state reaching the board.

package/node_modules/@spexcode/spec-cli/templates/spec/project/.plugins/core/mark-active/mark-active.sh

@@ -13,15 +13,15 @@
 # request_user_input tool) — read via hp_is_ask, so this hook never names a harness tool.
 # Fires BEFORE the tool runs, so a `spex session done` declaration (itself a tool) lands AFTER this and wins;
 # the next real tool flips back to active, forcing a fresh Stop-gate declaration.
-# @@@ read cheap, write through the ONE writer - this hook is on the hot path (every tool call), so it does
-# its own READ in pure shell: three exact-line greps answer "already active, nothing stale to clear?", which
-# is the overwhelmingly common case, and that path exits without spawning anything. When there IS a change to
-# make it hands the write to `spex internal session-state`, the same structured writer the CLI declarations
-# use. It never edits session.json itself: an asking note is arbitrary human/agent prose, and a writer that
-# substitutes prose into existing JSON meets a quote, a backslash, or a newline and leaves a record nothing
-# can parse — which is how a live session came to report "no session record" ([[sessions-core]]).
-# @@@ global store - state lives NOT in the worktree but in the per-session GLOBAL record session.json, keyed
-# by the harness session_id, grouped per-project (see hp_store_dir). GATED on `governed`: a user-self-launched
+# @@@ one writer - this hook is on the hot path (every tool call), but it must not inspect runtime.json to
+# decide whether a transition is needed. That file is only a runtime/worktree envelope; the canonical
+# session application is the lifecycle authority. The structured writer is idempotent for an unchanged state,
+# so every eligible event goes through the same writer and cannot short-circuit on a second fact. It never
+# edits runtime.json itself: an asking note is arbitrary prose, and shell substitution is not a record writer
+# ([[sessions-core]]).
+# @@@ global store - the lifecycle state lives in the canonical session application, keyed by the harness
+# session_id, grouped per-project (see hp_store_dir). The sibling runtime.json is only the runtime/worktree
+# envelope. GATED on `governed`: a user-self-launched
 # (non-governed) session has no board to feed, so this no-ops on it. cwd = the session worktree.
 . "${SPEXCODE_HARNESS_LIB:?harness.sh not exported by dispatch.sh}"
 payload=$(cat 2>/dev/null)
@@ -32,20 +32,20 @@ payload=$(cat 2>/dev/null)
 # discriminator is the payload's own top-level agent_id stamp (hp_is_subagent) — deterministic, never a
 # timing window.
 [ -n "$(hp_is_subagent "$payload")" ] && exit 0
+# Managed watch deliveries are supervision messages, not work performed by this session. They arrive through
+# the harness's ordinary UserPromptSubmit seam, so the freshness hook must recognize the protocol's exact
+# prefix before treating that seam as a human re-entry. This is deliberately a prefix check, not a broad
+# text heuristic: only the canonical `[spex watch] ` wire form is exempt; ordinary prompts and all tools still
+# mark active.
+if [ "$(hp_field "$payload" hook_event_name)" = "UserPromptSubmit" ]; then
+  case "$(hp_field "$payload" prompt)" in
+    "[spex watch] "*) exit 0 ;;
+  esac
+fi
 sid=$(hp_session_id "$payload"); [ -n "$sid" ] || exit 0
-sdir=$(hp_store_dir "$sid") || exit 0
-rec="$sdir/session.json"
-# board-lifecycle gate: only a GOVERNED (dashboard-launched) session has a board state to maintain.
-grep -q '^[[:space:]]*"governed"[[:space:]]*:[[:space:]]*true,\?$' "$rec" 2>/dev/null || exit 0
-
-# does FIELD's line hold exactly VALUE? The record is written one-field-per-line by the single writer
-# (sessions.ts writeRecord), so a whole-line match is exact — and, unlike a value regex, it cannot be fooled
-# by an escaped quote inside a neighbouring note.
-jline_is() { grep -q "^[[:space:]]*\"$1\"[[:space:]]*:[[:space:]]*\"$2\",\?$" "$rec" 2>/dev/null; }
-
-# The writer's own stdout is a human confirmation, not hook output — swallow it so a PreToolUse handler never
-# emits a decision-shaped line; its stderr (a refusal — a corrupt or retired record) still surfaces. We always
-# exit 0: this hook observes freshness, it is not a gate on the tool that triggered it.
+# The canonical writer owns governed/lifecycle validation. The hook must not inspect runtime.json: that file is
+# a runtime envelope, and using it as a gate is how old/missing envelopes silently disabled mark-active.
+# The writer's stdout is a human confirmation, not hook output; stderr remains visible for real refusals.
 if [ -n "$(hp_is_ask "$payload")" ]; then
   # first question's text → the note (best-effort). It is passed as ONE argv word to the writer, so quotes,
   # backslashes, newlines, and non-ASCII reach the record intact — no shell ever composes the JSON.
@@ -53,7 +53,5 @@ if [ -n "$(hp_is_ask "$payload")" ]; then
   exit 0
 fi
 
-# cheap path: already active with nothing stale to clear → no-op (the common every-tool case), no spawn.
-jline_is status active && jline_is proposal '' && jline_is note '' && exit 0
 ${SPEX:-spex} internal session-state active --session "$sid" >/dev/null
 exit 0

package/node_modules/@spexcode/spec-cli/templates/spec/project/.plugins/core/mark-active/spec.md

@@ -15,8 +15,16 @@ The state is read from ONE structured field in the hook payload, never sniffed f
 
 The one activity that does NOT count as the session acting is an IN-PROCESS SUBAGENT's tool call (the harness's Task tool — a sub-conversation inside the same process). Such a call fires the parent's hooks carrying the parent's `session_id`, so without a discriminator a supervising parent could never hold a declared state: its own subagents erased every park/ask within seconds and raced the stop-gate into "undeclared stop". The harness stamps subagent-executed calls with a top-level `agent_id` field the parent's own calls never carry; `hp_is_subagent` reads that stamp deterministically (scanning only the pre-`tool_input` payload prefix, where a tool parameter or file content can never fake an unescaped key), and this hook skips the flip entirely. A subagent working is its parent supervising, not the parent moving on — the parent's own next tool call still flips as before.
 
-It is a board-lifecycle hook, so it acts only on a GOVERNED (dashboard-launched) session — it resolves that session's record in the global per-session store from the payload's `session_id` and no-ops unless `governed: true`. The state it writes lives in that record's `session.json` (state), but it never edits that file itself: it READS it in pure shell (whole-line matches, the hot path stays jq-free) and hands every write to `spex internal session-state`, the one structured writer the CLI declarations use — an asking note is arbitrary prose, and a shell that substitutes prose into existing JSON eventually writes a record nothing can parse.
+It is a board-lifecycle hook, so it acts only on a GOVERNED (dashboard-launched) session — it resolves that session's runtime envelope in the global per-session store from the payload's `session_id` and no-ops unless `governed: true`. Lifecycle state is written to the canonical session application; `runtime.json` is not a lifecycle authority. The hook never edits that envelope itself: it hands every lifecycle write to `spex internal session-state`, the one structured writer the CLI declarations use — an asking note is arbitrary prose, and a shell that substitutes prose into existing JSON eventually writes a record nothing can parse.
 
-This hook carries no conversation. A message addressed to the session reaches its agent as an ordinary prompt through the harness adapter (delivery-queue), which is the only way anything enters a turn, so an inter-agent message is indistinguishable from a human one at the point of arrival. A hook that also injected mail delivered every message a second time and made the agent's context depend on which of two paths won a race; a freshness signal reports a fact about the session and hands nothing over.
+This hook carries no conversation. A message addressed to the session reaches its agent as an ordinary prompt through the harness adapter (delivery-queue), which is the only way anything enters a turn. The one protocol exception is a managed watch notice: the canonical `[spex watch] ` prefix identifies a supervision snapshot, not work performed by the receiving agent, so UserPromptSubmit for that exact wire form does not flip the receiver to `active`. Other inter-agent prompts remain ordinary prompt activity. A hook that also injected mail delivered every message a second time and made the agent's context depend on which of two paths won a race; a freshness signal reports a fact about the session and hands nothing over.
 
 This is the freshness half of the [[core]] discipline: it keeps the board honest about whether a session is working, waiting, or asking, so the gates and the dashboard read a true present state rather than a stale one.
+
+## legacy handler migration
+
+For the two known pre-structured `mark-active` source blobs still tracked by existing projects, dispatch performs
+a bounded migration at the adapter boundary: it executes the current package-owned structured implementation,
+and the next materialize replaces the old tracked handler with that implementation. This is a migration of a
+legacy source identity, not a second lifecycle protocol or a permanent backward-compatibility path. The old
+handler's envelope writes are never allowed to author current lifecycle state.

package/node_modules/@spexcode/spec-cli/templates/spec/project/.plugins/core/session-fail/fail.sh

@@ -1,12 +1,13 @@
 #!/usr/bin/env bash
-# Mark the session errored when a turn ends on an API failure (StopFailure). GATED on `governed`: only a
-# dashboard-launched session has board state to mark. State lives in the per-session GLOBAL record (keyed by
-# the harness session_id, grouped per-project — see hp_store_dir); the id is passed to the cli via `--session`
-# so it writes the right record without depending on the worktree.
+# Mark the session errored when a turn ends on an API failure (StopFailure). The canonical lifecycle writer owns
+# the governed-session boundary and active-only compare-and-set; this hook only decodes the native event and
+# passes its acting session id.
 . "${SPEXCODE_HARNESS_LIB:?harness.sh not exported by dispatch.sh}"
 payload=$(cat 2>/dev/null)
+# an IN-PROCESS SUBAGENT's failed turn (Claude's Task tool) fires the parent's hooks with the PARENT's
+# session_id, so without this the parent's own record would be flipped to `error` by a helper it spawned —
+# the same defect already fixed for mark-active, and the same discriminator fixes it: the payload's own
+# top-level agent_id stamp. A subagent's turn dying is not THIS session's turn dying.
+[ -n "$(hp_is_subagent "$payload")" ] && exit 0
 sid=$(hp_session_id "$payload"); [ -n "$sid" ] || exit 0
-sdir=$(hp_store_dir "$sid") || exit 0
-rec="$sdir/session.json"
-grep -q '"governed"[[:space:]]*:[[:space:]]*true' "$rec" 2>/dev/null || exit 0
 exec ${SPEX:-spex} internal session-fail --session "$sid"

package/node_modules/@spexcode/spec-cli/templates/spec/project/.plugins/core/session-fail/spec.md

@@ -12,4 +12,6 @@ code:
 ---
 When a turn ends not because the agent declared but because the API itself failed, this hook structurally marks the session `error`. A failed turn is a real outcome the board must show, and without this signal the session would freeze under whatever state it last held — reading as "active" or "awaiting" long after it actually died.
 
-It is non-blocking on the failure event: the failure already happened, so the only job is to report it truthfully. As a board-lifecycle hook it acts only on a GOVERNED session — resolved in the global store from the payload's `session_id` — and writes via `spex internal session-fail --session <id>`. That machine entry reaches the same live-active compare-and-set as Codex's native failed completion and a headless turn's non-zero exit (harness-adapter): only an undeclared, non-stopped `active` record becomes `error`. A declaration, explicit stop, or archive that landed first remains authoritative; a late native failure never rewrites it. This one writer keeps the [[stop-gate]] family's invariant intact for every harness while each adapter retains only its native failure signal.
+**A SUBAGENT'S FAILED TURN IS NOT THIS SESSION'S FAILED TURN.** An in-process subagent (Claude's Task tool) fires the parent's hooks carrying the PARENT's `session_id`, so a helper the session spawned could flip the session that spawned it to `error` — a supervising parent marked dead by a delegate it is still supervising. The discriminator is the payload's own top-level `agent_id` stamp, the deterministic one [[mark-active]] already uses for the same reason; it is not a timing window. This is one defect class, so it gets one answer at both hooks rather than a second idea of what "this session acted" means.
+
+It is non-blocking on the failure event: the failure already happened, so the only job is to report it truthfully. As a board-lifecycle hook it passes the payload's acting `session_id` to `spex internal session-fail --session <id>`; the canonical writer, not shell parsing of `runtime.json`, resolves the governed record and owns the live-active compare-and-set. Only an undeclared, non-stopped `active` record becomes `error`. A declaration, explicit stop, or archive that landed first remains authoritative; a late native failure never rewrites it. This one writer keeps the [[stop-gate]] family's invariant intact for every harness while each adapter retains only its native failure signal.

package/node_modules/@spexcode/spec-cli/templates/spec/project/.plugins/core/session-listen/session-listen.sh

@@ -0,0 +1,133 @@
+#!/usr/bin/env bash
+set -u
+
+# A self-launch project opts in only by configuring the adopter database. No configured database means no listener.
+if [ -z "${SPEX_SESSION_DATABASE_PATH+x}" ] && [ -z "${SPEX_SESSION_CONFIG+x}" ]; then
+  exit 0
+fi
+
+# The explicit command is one executable path; an invalid explicit value must not silently fall through to PATH.
+cli="${SPEX_SESSION_CLI:-}"
+if [ -z "$cli" ]; then
+  cli=$(command -v spex-session 2>/dev/null || true)
+fi
+if [ -z "$cli" ] || [ ! -x "$cli" ]; then
+  printf '%s\n' 'session-listen: spex-session CLI not found; install @spexcode/session-selflaunch (npm install) or set SPEX_SESSION_CLI to its executable path' >&2
+  exit 2
+fi
+
+for tool in awk base64 iconv od grep tail sed mktemp cat tr rm; do
+  if ! command -v "$tool" >/dev/null 2>&1; then
+    printf "session-listen: required delivery tool '%s' is missing; install it or repair PATH before retrying\n" "$tool" >&2
+    exit 2
+  fi
+done
+
+capability_error() {
+  printf "session-listen: required delivery capability '%s' is unavailable; install compatible tooling or repair PATH before retrying\n" "$1" >&2
+  exit 2
+}
+
+escape_awk='
+  BEGIN { ORS = "" }
+  NR > 1 { printf "\\n" }
+  {
+    for (i = 1; i <= length($0); i++) {
+      c = substr($0, i, 1)
+      if (c == "\\") printf "\\\\"
+      else if (c == "\"") printf "\\\""
+      else if (c == "\t") printf "\\t"
+      else if (c == "\r") printf "\\r"
+      else if (c == "\b") printf "\\b"
+      else if (c == "\f") printf "\\f"
+      else printf "%s", c
+    }
+  }
+'
+control_pattern='(^|[[:space:]])(00|01|02|03|04|05|06|07|08|0b|0c|0e|0f|1[0-9a-f])([[:space:]]|$)'
+body64_sed='s/.*"bodyBase64":"\([^"]*\)".*/\1/p'
+
+# Existence is not capability. These fixed vectors prove every non-default operation before at-most-once dequeue.
+[ "$(printf ' A ' | tr -d '[:space:]')" = A ] || capability_error 'tr -d character classes'
+[ "$(printf A | od -An -v -tx1 | tr -d '[:space:]')" = 41 ] || capability_error 'od hexadecimal bytes'
+[ "$(printf QQ== | base64 -d 2>/dev/null | od -An -v -tx1 | tr -d '[:space:]')" = 41 ] \
+  || capability_error 'base64 -d exact decoding'
+[ "$(printf '\303\251' | iconv -f UTF-8 -t UTF-8 2>/dev/null | od -An -v -tx1 | tr -d '[:space:]')" = c3a9 ] \
+  || capability_error 'iconv UTF-8 validation'
+printf ' 00 ' | grep -Eq "$control_pattern" || capability_error 'grep extended quiet match'
+if printf ' 0a ' | grep -Eq "$control_pattern"; then capability_error 'grep extended quiet exclusion'; fi
+[ "$(printf AB | tail -c 1)" = B ] || capability_error 'tail byte selection'
+[ "$(printf '%s' '{"bodyBase64":"QQ=="}' | sed -n "$body64_sed")" = QQ== ] \
+  || capability_error 'sed JSON field extraction'
+[ "$(printf 'A\nB\n' | awk "$escape_awk")" = 'A\nB' ] || capability_error 'awk JSON text escaping'
+[ "$(printf A | cat)" = A ] || capability_error 'cat byte emission'
+
+. "${SPEXCODE_HARNESS_LIB:?harness.sh not exported by dispatch.sh}"
+payload=$(cat 2>/dev/null || true)
+sid=$(hp_field "$payload" session_id)
+[ -n "$sid" ] || exit 0
+event=$(hp_field "$payload" hook_event_name)
+
+case "$event" in
+  SessionStart)
+    "$cli" initialize --session-id "$sid" >/dev/null || exit 2
+    ;;
+  UserPromptSubmit)
+    decoded=$(mktemp "${TMPDIR:-/tmp}/spex-session-listen.XXXXXX") || {
+      printf '%s\n' 'session-listen: could not allocate a temporary body file; repair TMPDIR and retry' >&2
+      exit 2
+    }
+    escaped_file="$decoded.escaped"
+    output_file="$decoded.output"
+    if ! : >"$escaped_file" || ! : >"$output_file"; then
+      rm -f "$decoded"
+      rm -f "$escaped_file" "$output_file"
+      printf '%s\n' 'session-listen: could not prepare temporary delivery files; repair TMPDIR and retry' >&2
+      exit 2
+    fi
+    cleanup() { rm -f "$decoded" "$escaped_file" "$output_file"; }
+    trap cleanup EXIT
+    raw=$("$cli" dequeue --session-id "$sid") || exit 2
+    [ "$raw" = 'null' ] && exit 0
+    body64=$(printf '%s' "$raw" | sed -n "$body64_sed")
+    message_id=$(printf '%s' "$raw" | sed -n 's/.*"messageId":"\([^"]*\)".*/\1/p')
+    [ -n "$body64" ] || {
+      printf '%s\n' 'session-listen: spex-session dequeue returned invalid JSON (missing bodyBase64)' >&2
+      exit 2
+    }
+    if ! printf '%s' "$body64" | base64 -d >"$decoded" 2>/dev/null; then
+      printf '%s\n' 'session-listen: spex-session dequeue returned invalid bodyBase64' >&2
+      exit 2
+    fi
+    if ! iconv -f UTF-8 -t UTF-8 "$decoded" >/dev/null 2>/dev/null; then
+      printf 'session-listen: refusing non-UTF-8 body; messageId=%s bodyBase64=%s\n' "$message_id" "$body64" >&2
+      exit 2
+    fi
+    if od -An -v -tx1 "$decoded" | grep -Eq "$control_pattern"; then
+      printf 'session-listen: refusing control-byte body; messageId=%s bodyBase64=%s\n' "$message_id" "$body64" >&2
+      exit 2
+    fi
+    if ! awk "$escape_awk" "$decoded" >"$escaped_file"; then
+      printf 'session-listen: could not encode body for harness input; messageId=%s bodyBase64=%s\n' "$message_id" "$body64" >&2
+      exit 2
+    fi
+    if [ -s "$decoded" ] && [ ! -s "$escaped_file" ]; then
+      printf 'session-listen: non-empty body encoded to empty additionalContext; messageId=%s bodyBase64=%s\n' "$message_id" "$body64" >&2
+      exit 2
+    fi
+    last_byte=$(tail -c 1 "$decoded" | od -An -tx1 | tr -d '[:space:]')
+    if ! {
+      printf '{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"'
+      cat "$escaped_file"
+      [ "$last_byte" = 0a ] && printf '\\n'
+      printf '"}}\n'
+    } >"$output_file"; then
+      printf 'session-listen: could not assemble harness input; messageId=%s bodyBase64=%s\n' "$message_id" "$body64" >&2
+      exit 2
+    fi
+    if ! cat "$output_file"; then
+      printf 'session-listen: could not emit harness input; messageId=%s bodyBase64=%s\n' "$message_id" "$body64" >&2
+      exit 2
+    fi
+    ;;
+esac

package/node_modules/@spexcode/spec-cli/templates/spec/project/.plugins/core/session-listen/spec.md

@@ -0,0 +1,36 @@
+---
+title: session-listen
+surface: hook
+status: active
+hue: 280
+events:
+- SessionStart
+- UserPromptSubmit
+order: 20
+block: true
+---
+The backend-free self-launch message loop. On `SessionStart`, it initializes the harness's native session id in the
+adopter protocol database; initialization is idempotent and creates no governed lifecycle record. On each
+`UserPromptSubmit`, it performs exactly one at-most-once `spex-session dequeue` for that same native id. A message
+body is decoded and emitted as the harness's `hookSpecificOutput.additionalContext` JSON, so the harness input seam
+receives it without a resident process or wake-hint dependency. An empty queue is a successful no-op and emits no
+stdout. The hook never derives a database path: the adopter CLI owns path resolution and locality checks.
+
+Every external delivery tool and each non-default operation it supplies is proven with a fixed result vector before
+`dequeue`, so a binary that exists but lacks or misimplements the required flag cannot consume a message. In
+particular, `base64 -d` must decode `QQ==` to exactly the one byte `0x41`; checking only its exit status would admit a
+shim that merely copies input. `-d` is used because GNU base64 on Linux and base64 on both fleet Macs running macOS
+15.6.1 were measured to decode that vector correctly; this is an observed common capability, not a platform legend.
+The opaque body
+is decoded to a temporary file, validated as UTF-8, and rejected loudly (with its `messageId` and original
+`bodyBase64`) when it contains NUL or other JSON-hostile control bytes. Clean text is escaped with the existing awk
+toolchain without command substitution, preserving embedded and trailing newlines; a non-empty body can never become
+an empty additionalContext success.
+
+The CLI is resolved at runtime through one explicit seam: a non-empty `SPEX_SESSION_CLI` wins, otherwise PATH is
+searched for `spex-session`. If either protocol database environment variable is configured and no CLI can be
+resolved, the hook fails loudly with an installation or `SPEX_SESSION_CLI` repair entrypoint. With neither database
+variable configured, the project has not adopted this capability, so the hook exits silently without trying another
+delivery path. Only these two events are bound: startup establishes the address, and prompt submission is the natural
+harness input seam; a configured-but-broken adopter is a blocking hook failure so dispatch cannot hide it. There is no
+daemon, polling, retry loop, observer, governed record, or compatibility path.

package/node_modules/@spexcode/spec-cli/templates/spec/project/.plugins/core/spec.md

@@ -10,6 +10,8 @@ Use noun-first CLI commands; `spex help` is the authoritative command map.
 
 Anything a human needs to inspect, whether a file or a local webpage, goes out through `spex session files add` or
 `spex session web add`: never paste an absolute path or `host:port`, and never start a static server yourself.
+Put raw file evidence in a persistent directory outside the product repository by default, then run
+`spex session files ls` before review and repair or retract every `INVALID` handoff.
 
 When this session has a clearly running child session (`active` or `parked`), the parent is supervising rather
 than finished: declare `park`, not `done`/`awaiting`, until the child reports a settled state.