@spexcode/spec-cli 0.6.6 → 0.6.8

package/dist/transcript-reader.js

@@ -0,0 +1,251 @@
+import { createReadStream, statSync } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { claudeTranscriptPath, codexRolloutPath } from './execution-trace.js';
+export class TranscriptReadError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = 'TranscriptReadError';
+    }
+}
+const MAX_TURNS = 200;
+const MAX_OUTPUT_BYTES = 64 * 1024;
+const POST_RANGE_LOOKAHEAD_LINES = 256;
+const object = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+const items = (value) => Array.isArray(value) ? value : [];
+const string = (value) => typeof value === 'string' && value.trim() ? value : null;
+const idOf = (value) => {
+    if (!value)
+        return null;
+    for (const key of ['id', 'uuid', 'message_id', 'messageId', 'call_id', 'callId', 'client_id', 'clientId']) {
+        const found = string(value[key]);
+        if (found)
+            return found;
+    }
+    return null;
+};
+const timestamp = (value) => {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value !== 'string' || !value.trim())
+        return null;
+    const numeric = Number(value);
+    if (Number.isFinite(numeric))
+        return numeric;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : null;
+};
+const at = (value) => {
+    if (!value)
+        return null;
+    for (const key of ['timestamp', 'created_at', 'createdAt', 'created', 'time']) {
+        const candidate = timestamp(value[key]);
+        if (candidate !== null)
+            return candidate;
+    }
+    return null;
+};
+const compact = (value) => {
+    if (typeof value === 'string')
+        return value;
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+};
+const lineCount = (value) => value ? value.split(/\r?\n/).length : 0;
+function claudeEvent(value) {
+    const entry = object(value);
+    const message = object(entry?.message);
+    if (!entry || !message)
+        return null;
+    const eventAt = at(entry) ?? at(message);
+    if (eventAt === null)
+        return { at: null, turn: null };
+    if (entry.type === 'user' && message.role === 'user') {
+        const blocks = items(message.content);
+        const text = typeof message.content === 'string'
+            ? string(message.content)
+            : blocks.map((block) => string(object(block)?.text)).filter(Boolean).join('\n') || null;
+        const outputs = blocks.flatMap((block) => {
+            const b = object(block);
+            const id = string(b?.tool_use_id);
+            return b?.type === 'tool_result' && id ? [{ id, text: compact(b?.content ?? '') }] : [];
+        });
+        if (outputs.length)
+            return { at: eventAt, turn: null, toolOutputs: outputs };
+        if (text)
+            return { at: eventAt, turn: { id: idOf(entry) ?? idOf(message), at: eventAt, role: 'user', text, tools: [] } };
+    }
+    if (entry.type === 'assistant' && message.role === 'assistant') {
+        const turn = { id: idOf(entry) ?? idOf(message), at: eventAt, role: 'assistant', tools: [] };
+        for (const blockValue of items(message.content)) {
+            const block = object(blockValue);
+            if (block?.type === 'text')
+                turn.text = [turn.text, string(block.text)].filter(Boolean).join('\n') || undefined;
+            if (block?.type === 'tool_use') {
+                const id = string(block.id) ?? `tool-${turn.tools.length}`;
+                turn.tools.push({ id, name: string(block.name) ?? 'tool', input: block.input === undefined ? undefined : compact(block.input), outputLines: 0, outputBytes: 0 });
+            }
+        }
+        return { at: eventAt, turn };
+    }
+    return null;
+}
+function codexEvent(value) {
+    const entry = object(value);
+    const payload = object(entry?.payload);
+    if (!entry || !payload)
+        return null;
+    const eventAt = at(payload) ?? at(entry);
+    if (eventAt === null)
+        return { at: null, turn: null };
+    const type = string(payload.type);
+    if ((entry.type === 'event_msg' && type === 'user_message')
+        || (entry.type === 'response_item' && (type === 'message' || type === 'input_message') && payload.role === 'user')) {
+        const text = typeof payload.message === 'string' ? payload.message : compact(payload.message ?? payload.content ?? '');
+        return text ? { at: eventAt, turn: { id: idOf(payload) ?? idOf(entry), at: eventAt, role: 'user', text, tools: [] } } : null;
+    }
+    if (entry.type === 'event_msg' && type === 'agent_message' && payload.phase === 'commentary') {
+        const text = string(payload.message ?? payload.text);
+        return text ? { at: eventAt, turn: { id: idOf(payload) ?? idOf(entry), at: eventAt, role: 'assistant', text, tools: [] } } : null;
+    }
+    if (entry.type === 'response_item' && (type === 'custom_tool_call' || type === 'function_call')) {
+        const id = string(payload.call_id ?? payload.id) ?? 'tool';
+        return { at: eventAt, turn: { id: idOf(payload) ?? idOf(entry), at: eventAt, role: 'assistant', tools: [{ id, name: string(payload.name ?? payload.tool_name) ?? 'tool', input: payload.input === undefined && payload.arguments === undefined ? undefined : compact(payload.input ?? payload.arguments), outputLines: 0, outputBytes: 0 }] } };
+    }
+    if (entry.type === 'response_item' && (type === 'custom_tool_call_output' || type === 'function_call_output')) {
+        const id = string(payload.call_id ?? payload.id);
+        const output = payload.output ?? payload.result ?? '';
+        return id ? { at: eventAt, turn: null, toolOutputs: [{ id, text: compact(output) }] } : null;
+    }
+    return null;
+}
+function sourcePath(harness, threadId) {
+    if (harness === 'claude' || harness === 'claude-headless')
+        return claudeTranscriptPath(threadId);
+    if (harness === 'codex' || harness === 'codex-headless')
+        return codexRolloutPath(threadId);
+    throw new TranscriptReadError('unsupported', `${harness} does not support transcript access`);
+}
+export async function readTranscript(harness, threadId, range) {
+    const path = sourcePath(harness, threadId);
+    if (!path)
+        throw new TranscriptReadError('missing', `${harness} transcript for ${threadId} is unavailable: file was not found`);
+    let size = 0;
+    try {
+        size = statSync(path).size;
+    }
+    catch (error) {
+        throw new TranscriptReadError('unreadable', `${harness} transcript is unreadable: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (size <= 0)
+        throw new TranscriptReadError('unreadable', `${harness} transcript is unreadable: file is empty`);
+    const parse = harness === 'claude' || harness === 'claude-headless' ? claudeEvent : codexEvent;
+    const turns = [];
+    const byTool = new Map();
+    let sawTimestamp = false;
+    let omittedTurns = 0;
+    let omittedBytes = 0;
+    let outOfOrderEvents = 0;
+    let lookingPastRange = false;
+    let postRangeLines = 0;
+    const input = createReadStream(path, { encoding: 'utf8', highWaterMark: 64 * 1024 });
+    const lines = createInterface({ input, crlfDelay: Infinity });
+    try {
+        for await (const line of lines) {
+            if (!line.trim())
+                continue;
+            let value;
+            try {
+                value = JSON.parse(line);
+            }
+            catch (error) {
+                throw new TranscriptReadError('invalid', `${harness} transcript cannot be parsed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            const event = parse(value);
+            const stopAfterLine = lookingPastRange && ++postRangeLines >= POST_RANGE_LOOKAHEAD_LINES;
+            if (!event) {
+                if (stopAfterLine)
+                    break;
+                continue;
+            }
+            const eventAt = event.at;
+            const hasTimestamp = eventAt !== null;
+            if (hasTimestamp)
+                sawTimestamp = true;
+            if (!lookingPastRange && hasTimestamp && eventAt > range.to) {
+                lookingPastRange = true;
+            }
+            else if (lookingPastRange && hasTimestamp && eventAt <= range.to) {
+                outOfOrderEvents++;
+            }
+            if (hasTimestamp && eventAt >= range.from && eventAt <= range.to) {
+                if (event.toolOutputs) {
+                    for (const output of event.toolOutputs) {
+                        const bytes = Buffer.byteLength(output.text);
+                        const tool = byTool.get(output.id);
+                        if (!tool) {
+                            omittedBytes += bytes;
+                            continue;
+                        }
+                        tool.outputBytes += bytes;
+                        tool.outputLines += lineCount(output.text);
+                        if (tool.output === undefined)
+                            tool.output = '';
+                        const remaining = Math.max(0, MAX_OUTPUT_BYTES - Buffer.byteLength(tool.output));
+                        tool.output += output.text.slice(0, remaining);
+                        if (bytes > remaining)
+                            omittedBytes += bytes - remaining;
+                    }
+                }
+                else if (event.turn) {
+                    if (turns.length >= MAX_TURNS)
+                        omittedTurns++;
+                    else {
+                        turns.push(event.turn);
+                        for (const tool of event.turn.tools)
+                            byTool.set(tool.id, tool);
+                    }
+                }
+            }
+            if (stopAfterLine)
+                break;
+        }
+    }
+    catch (error) {
+        if (error instanceof TranscriptReadError)
+            throw error;
+        throw new TranscriptReadError('unreadable', `${harness} transcript could not be read: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    finally {
+        input.destroy();
+    }
+    if (!sawTimestamp)
+        throw new TranscriptReadError('invalid', `${harness} transcript has no reliable timestamps; interval reads are unavailable`);
+    const normalized = turns.map((turn) => ({
+        ...turn,
+        tools: turn.tools.length ? turn.tools.map((tool) => ({ ...tool })) : undefined,
+    }));
+    return {
+        from: range.from,
+        to: range.to,
+        turns: normalized,
+        truncated: omittedTurns > 0 || omittedBytes > 0 || outOfOrderEvents > 0,
+        omittedTurns,
+        omittedBytes,
+        outOfOrderEvents,
+    };
+}
+export async function readClaudeTranscript(threadId, range) {
+    return readTranscript('claude', threadId, range);
+}
+export async function readCodexTranscript(threadId, range) {
+    return readTranscript('codex', threadId, range);
+}
+export async function unsupportedTranscriptReader(harness, _threadId, _range) {
+    throw new TranscriptReadError('unsupported', `${harness} does not support transcript access`);
+}

package/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spexcode/spec-cli",
-  "version": "0.6.6",
+  "version": "0.6.8",
   "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,11 @@
     "test": "tsx --import ../scripts/test-home.mjs --test src/*.test.ts"
   },
   "dependencies": {
-    "@spexcode/session-core": "0.6.6",
-    "@spexcode/spec-core": "0.6.6",
-    "@spexcode/spec-eval": "0.6.6",
-    "@spexcode/spec-forge": "0.6.6"
+    "@spexcode/session-application": "0.6.8",
+    "@spexcode/session-selflaunch": "0.6.8",
+    "@spexcode/spec-core": "0.6.8",
+    "@spexcode/spec-eval": "0.6.8",
+    "@spexcode/spec-forge": "0.6.8"
   },
   "devDependencies": {
     "@types/node": "^20.16.0",

package/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/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/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/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/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/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/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/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/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.