@spexcode/spec-cli 0.6.5

package/dist/uploads.d.ts

@@ -0,0 +1,36 @@
+import { type UploadPolicy } from '@spexcode/spec-core';
+type UploadMeta = {
+    version: 1;
+    id: string;
+    name: string;
+    size: number;
+    offset: number;
+    createdAt: number;
+    updatedAt: number;
+};
+export type UploadStatus = Pick<UploadMeta, 'id' | 'name' | 'size' | 'offset'> & Pick<UploadPolicy, 'chunkBytes' | 'concurrency' | 'requestTimeoutMs' | 'retryLimit' | 'retryDelayMs'>;
+export declare class UploadError extends Error {
+    readonly status: number;
+    readonly offset?: number | undefined;
+    constructor(status: number, message: string, offset?: number | undefined);
+}
+export declare const evidenceMaxBytes: () => number;
+export declare function cleanupExpiredUploads(policy?: Required<{
+    maxBytes?: number;
+    chunkBytes?: number;
+    concurrency?: number;
+    requestTimeoutMs?: number;
+    retryLimit?: number;
+    retryDelayMs?: number;
+    incompleteTtlMs?: number;
+    cleanupIntervalMs?: number;
+    minFreeBytes?: number;
+    evidenceMaxBytes?: number;
+}>): void;
+export declare function startUploadReaper(): void;
+export declare function createUpload(name: unknown, size: unknown): UploadStatus;
+export declare function uploadStatus(id: string): UploadStatus;
+export declare function appendUpload(id: string, offset: unknown, body: ReadableStream<Uint8Array> | null, contentLength?: string): Promise<UploadStatus>;
+export declare function completeUpload(id: string): string;
+export declare function cancelUpload(id: string): void;
+export {};

package/dist/uploads.js

@@ -0,0 +1,243 @@
+import { randomUUID } from 'node:crypto';
+import { createWriteStream, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, statfsSync, truncateSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+import { Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { repoRoot } from '@spexcode/spec-core';
+import { readUploadPolicy } from '@spexcode/spec-core';
+// The backend's tmpdir is the worker's filesystem. Completed files stay directly under this sink; private
+// metadata and partial bytes live below .staging until an exact-length transfer is promoted atomically.
+const UPLOAD_DIR = join(tmpdir(), 'spexcode-uploads');
+const STAGING_DIR = join(UPLOAD_DIR, '.staging');
+export class UploadError extends Error {
+    status;
+    offset;
+    constructor(status, message, offset) {
+        super(message);
+        this.status = status;
+        this.offset = offset;
+    }
+}
+const uploadPolicy = () => readUploadPolicy(repoRoot());
+export const evidenceMaxBytes = () => uploadPolicy().evidenceMaxBytes;
+function ensureDirs() {
+    mkdirSync(STAGING_DIR, { recursive: true });
+}
+function safeName(name) {
+    const base = basename(name || '').replace(/[^A-Za-z0-9._-]/g, '_').replace(/^\.+/, '');
+    return base || 'upload';
+}
+function validId(id) {
+    return /^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/i.test(id);
+}
+function metaPath(id) {
+    return join(STAGING_DIR, `${id}.json`);
+}
+function partPath(id) {
+    return join(STAGING_DIR, `${id}.part`);
+}
+function removeTransfer(id) {
+    rmSync(metaPath(id), { force: true });
+    rmSync(partPath(id), { force: true });
+}
+function readMetaFile(id) {
+    if (!validId(id))
+        return null;
+    try {
+        const meta = JSON.parse(readFileSync(metaPath(id), 'utf8'));
+        if (meta.version !== 1 || meta.id !== id || typeof meta.name !== 'string' ||
+            !Number.isSafeInteger(meta.size) || meta.size <= 0 ||
+            !Number.isSafeInteger(meta.offset) || meta.offset < 0 || meta.offset > meta.size ||
+            !Number.isSafeInteger(meta.createdAt) || !Number.isSafeInteger(meta.updatedAt))
+            return null;
+        return meta;
+    }
+    catch {
+        return null;
+    }
+}
+function writeMeta(meta) {
+    const path = metaPath(meta.id);
+    const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    writeFileSync(temp, JSON.stringify(meta) + '\n');
+    renameSync(temp, path);
+}
+function actualOffset(meta) {
+    try {
+        return statSync(partPath(meta.id)).size;
+    }
+    catch {
+        return 0;
+    }
+}
+function status(meta, policy) {
+    const { chunkBytes, concurrency, requestTimeoutMs, retryLimit, retryDelayMs } = policy;
+    return { id: meta.id, name: meta.name, size: meta.size, offset: meta.offset, chunkBytes, concurrency, requestTimeoutMs, retryLimit, retryDelayMs };
+}
+function syncOffset(meta) {
+    const offset = actualOffset(meta);
+    if (offset > meta.size)
+        throw new UploadError(409, 'upload staging file exceeds its declared length');
+    if (offset !== meta.offset) {
+        meta.offset = offset;
+        meta.updatedAt = Date.now();
+        writeMeta(meta);
+    }
+    return meta;
+}
+function loadUpload(id, policy) {
+    const meta = readMetaFile(id);
+    if (!meta)
+        throw new UploadError(404, 'upload not found');
+    if (Date.now() - meta.updatedAt > policy.incompleteTtlMs) {
+        removeTransfer(id);
+        throw new UploadError(404, 'upload expired');
+    }
+    return syncOffset(meta);
+}
+function reservedBytes(policy) {
+    let total = 0;
+    for (const entry of readdirSync(STAGING_DIR, { withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.endsWith('.json'))
+            continue;
+        const meta = readMetaFile(entry.name.slice(0, -5));
+        if (!meta || Date.now() - meta.updatedAt > policy.incompleteTtlMs)
+            continue;
+        total += Math.max(0, meta.size - actualOffset(meta));
+    }
+    return total;
+}
+function reserveCapacity(size, policy) {
+    let available = 0;
+    try {
+        const fs = statfsSync(UPLOAD_DIR);
+        available = Number(fs.bavail) * Number(fs.bsize);
+    }
+    catch {
+        // A filesystem that cannot report capacity will still fail loudly during the stream write.
+        return;
+    }
+    if (size > Math.max(0, available - policy.minFreeBytes - reservedBytes(policy))) {
+        throw new UploadError(507, 'insufficient backend disk capacity for this upload');
+    }
+}
+export function cleanupExpiredUploads(policy = uploadPolicy()) {
+    ensureDirs();
+    const now = Date.now();
+    for (const entry of readdirSync(STAGING_DIR, { withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.endsWith('.json'))
+            continue;
+        const id = entry.name.slice(0, -5);
+        const meta = readMetaFile(id);
+        if (!meta || now - meta.updatedAt > policy.incompleteTtlMs)
+            removeTransfer(id);
+    }
+    for (const entry of readdirSync(STAGING_DIR, { withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.endsWith('.part'))
+            continue;
+        const id = entry.name.slice(0, -5);
+        if (readMetaFile(id))
+            continue;
+        try {
+            if (now - statSync(partPath(id)).mtimeMs > policy.incompleteTtlMs)
+                rmSync(partPath(id), { force: true });
+        }
+        catch { /* raced a cancellation or another cleanup pass */ }
+    }
+}
+export function startUploadReaper() {
+    const sweep = () => {
+        const policy = uploadPolicy();
+        cleanupExpiredUploads(policy);
+        const timer = setTimeout(sweep, policy.cleanupIntervalMs);
+        timer.unref();
+    };
+    sweep();
+}
+export function createUpload(name, size) {
+    const policy = uploadPolicy();
+    if (typeof name !== 'string' || !name.trim())
+        throw new UploadError(400, 'file name is required');
+    if (typeof size !== 'number' || !Number.isSafeInteger(size) || size <= 0)
+        throw new UploadError(400, 'file must not be empty');
+    if (size > policy.maxBytes)
+        throw new UploadError(413, 'file exceeds the configured upload limit');
+    ensureDirs();
+    cleanupExpiredUploads(policy);
+    reserveCapacity(size, policy);
+    const now = Date.now();
+    const meta = { version: 1, id: randomUUID(), name: safeName(name), size, offset: 0, createdAt: now, updatedAt: now };
+    writeMeta(meta);
+    return status(meta, policy);
+}
+export function uploadStatus(id) {
+    const policy = uploadPolicy();
+    return status(loadUpload(id, policy), policy);
+}
+export async function appendUpload(id, offset, body, contentLength) {
+    const policy = uploadPolicy();
+    const meta = loadUpload(id, policy);
+    if (typeof offset !== 'number' || !Number.isSafeInteger(offset) || offset < 0)
+        throw new UploadError(400, 'upload offset must be a non-negative integer');
+    if (offset !== meta.offset)
+        throw new UploadError(409, 'upload offset does not match the committed bytes', meta.offset);
+    if (!body)
+        throw new UploadError(400, 'upload chunk is required');
+    const declared = contentLength == null ? null : Number(contentLength);
+    if (declared != null && (!Number.isSafeInteger(declared) || declared <= 0))
+        throw new UploadError(400, 'content-length must be a positive integer');
+    if (declared != null && (declared > policy.chunkBytes || meta.offset + declared > meta.size)) {
+        throw new UploadError(413, 'upload chunk exceeds its declared bounds');
+    }
+    let written = 0;
+    const before = meta.offset;
+    const limiter = new Transform({
+        transform(chunk, _encoding, callback) {
+            written += chunk.length;
+            if (written > policy.chunkBytes || before + written > meta.size) {
+                callback(new UploadError(413, 'upload chunk exceeds its declared bounds'));
+                return;
+            }
+            callback(null, chunk);
+        },
+    });
+    try {
+        await pipeline(Readable.fromWeb(body), limiter, createWriteStream(partPath(id), { flags: 'a' }));
+    }
+    catch (error) {
+        if (error instanceof UploadError) {
+            truncateSync(partPath(id), before);
+            throw error;
+        }
+        // An interrupted connection may have committed a valid prefix. The next GET reports its actual length.
+        meta.offset = actualOffset(meta);
+        meta.updatedAt = Date.now();
+        writeMeta(meta);
+        throw new UploadError(500, `upload write failed: ${error.message}`);
+    }
+    if (written === 0)
+        throw new UploadError(400, 'upload chunk is empty');
+    meta.offset = actualOffset(meta);
+    meta.updatedAt = Date.now();
+    writeMeta(meta);
+    return status(meta, policy);
+}
+export function completeUpload(id) {
+    const meta = loadUpload(id, uploadPolicy());
+    if (meta.offset !== meta.size)
+        throw new UploadError(409, `upload is incomplete (${meta.offset} of ${meta.size} bytes)`, meta.offset);
+    const path = join(UPLOAD_DIR, `${Date.now().toString(36)}-${meta.id}-${safeName(meta.name)}`);
+    try {
+        renameSync(partPath(id), path);
+        rmSync(metaPath(id), { force: true });
+        return path;
+    }
+    catch (error) {
+        throw new UploadError(500, `upload completion failed: ${error.message}`);
+    }
+}
+export function cancelUpload(id) {
+    loadUpload(id, uploadPolicy());
+    removeTransfer(id);
+}

package/dist/worktree-sources.d.ts

@@ -0,0 +1 @@
+export declare function seedWorktreeHostState(main: string, wt: string): void;

package/dist/worktree-sources.js

@@ -0,0 +1,47 @@
+import { appendFileSync, copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { git } from '@spexcode/spec-core';
+export function seedWorktreeHostState(main, wt) {
+    const f = 'spexcode.local.json';
+    try {
+        if (!existsSync(join(main, f)) || existsSync(join(wt, f)))
+            return;
+        copyFileSync(join(main, f), join(wt, f));
+    }
+    catch (e) {
+        console.error(`spexcode: could not seed ${f} from ${main} into worktree ${wt} — that worker runs on defaults (${e})`);
+        return;
+    }
+    hideSeededFromGit(wt, [f]);
+}
+// what we seed, we hide: a seeded entry git still sees is force-add bait (a real PR once carried seeded
+// files into a product repo). `.git/info/exclude` lives in the COMMON git dir, so one write hides the entry
+// in every linked worktree AND the main checkout. Only entries seeded by THIS call and reported un-ignored
+// by `git check-ignore` are written: idempotent across dispatches, and a repo whose materialize already ignores
+// the overlay (materialize's block under any policy) writes nothing — the self-heal for a half-configured repo.
+function hideSeededFromGit(wt, seeded) {
+    for (const f of seeded) {
+        try {
+            if (isIgnored(wt, f))
+                continue;
+            const exclude = join(git(['-C', wt, 'rev-parse', '--path-format=absolute', '--git-common-dir']).trim(), 'info', 'exclude');
+            mkdirSync(dirname(exclude), { recursive: true });
+            const cur = existsSync(exclude) ? readFileSync(exclude, 'utf8') : '';
+            appendFileSync(exclude, `${cur && !cur.endsWith('\n') ? '\n' : ''}${f}\n`);
+        }
+        catch (e) {
+            console.error(`spexcode: could not hide seeded ${f} in the shared info/exclude for ${wt} — it will show untracked there (${e})`);
+        }
+    }
+}
+function isIgnored(wt, f) {
+    try {
+        git(['-C', wt, 'check-ignore', '-q', f]);
+        return true;
+    }
+    catch (e) {
+        if (e?.status === 1)
+            return false; // check-ignore's documented "not ignored" exit
+        throw e;
+    }
+}

package/hooks/compat/mark-active-0.5.2-eef1.fixture

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# @@@ mark-active - the SINGLE freshness hook, wired to BOTH UserPromptSubmit and PreToolUse. It branches
+# on ONE structured signal read straight from the hook payload (stdin JSON), so the state is HARD — never
+# text-sniffed from the TUI:
+#   the agent is pausing to ask the HUMAN (hp_is_ask) → status: asking, with the question text as the note
+#                                  (the deterministic capture of a question).
+#   any other tool, or a prompt submit → the agent is working → status: active (drop a now-stale proposal/note).
+# WHAT counts as "asking" is the [[harness-adapter]]'s call (Claude: the AskUserQuestion tool; Codex: the
+# 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. Pure shell (no node/tsx) so
+# it stays cheap on every tool call — it value-replaces status/proposal/note in session.json with sed, never jq.
+# @@@ 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
+# (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)
+# an IN-PROCESS SUBAGENT's tool call (Claude's Task tool) fires the parent's hooks with the PARENT's
+# session_id — flipping here let a supervising parent's own subagents erase its declared park/ask within
+# seconds and race the stop-gate into "undeclared stop" (issue #60). A subagent working is not the parent
+# agent ACTING, so its calls never touch the record; the parent's own next tool call still flips. The
+# 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
+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 '"governed"[[:space:]]*:[[:space:]]*true' "$rec" 2>/dev/null || exit 0
+
+jget() { sed -n "s/.*\"$1\"[[:space:]]*:[[:space:]]*\"\([^\"]*\)\".*/\1/p" "$rec" 2>/dev/null | head -1; }
+
+if [ -n "$(hp_is_ask "$payload")" ]; then
+  status=asking
+  note=$(hp_ask_note "$payload")   # first question's text → the note (best-effort)
+else
+  status=active
+  note=
+fi
+
+# cheap path: already active with nothing stale to clear → no-op (the common every-tool case).
+[ "$status" = active ] && [ "$(jget status)" = active ] && [ -z "$(jget proposal)" ] && [ -z "$(jget note)" ] && exit 0
+
+# value-replace status + clear proposal + (re)set note, in place. The record is written one-field-per-line
+# with these keys ALWAYS present (sessions.ts writeRecord), so each is a single value substitution — no key
+# add/remove, no JSON parser. Escape \ / & in the note for the sed REPLACEMENT (the note never contains ").
+note_esc=$(printf '%s' "$note" | sed 's/[\\/&]/\\&/g')
+tmp=$(mktemp) || exit 0
+sed -e "s/\(\"status\"[[:space:]]*:[[:space:]]*\)\"[^\"]*\"/\1\"$status\"/" \
+    -e "s/\(\"proposal\"[[:space:]]*:[[:space:]]*\)\"[^\"]*\"/\1\"\"/" \
+    -e "s/\(\"note\"[[:space:]]*:[[:space:]]*\)\"[^\"]*\"/\1\"$note_esc\"/" \
+    "$rec" > "$tmp" && mv "$tmp" "$rec"
+exit 0

package/hooks/compat/mark-active-sed-v0.fixture

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# @@@ mark-active - the SINGLE freshness hook, wired to BOTH UserPromptSubmit and PreToolUse. It branches
+# on ONE structured signal read straight from the hook payload (stdin JSON), so the state is HARD — never
+# text-sniffed from the TUI:
+#   the agent is pausing to ask the HUMAN (hp_is_ask) → status: asking, with the question text as the note
+#                                  (the deterministic capture of a question).
+#   any other tool, or a prompt submit → the agent is working → status: active (drop a now-stale proposal/note).
+# WHAT counts as "asking" is the [[harness-adapter]]'s call (Claude: the AskUserQuestion tool; Codex: the
+# 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. Pure shell (no node/tsx) so
+# it stays cheap on every tool call — it value-replaces status/proposal/note in session.json with sed, never jq.
+# @@@ 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
+# (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)
+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 '"governed"[[:space:]]*:[[:space:]]*true' "$rec" 2>/dev/null || exit 0
+
+jget() { sed -n "s/.*\"$1\"[[:space:]]*:[[:space:]]*\"\([^\"]*\)\".*/\1/p" "$rec" 2>/dev/null | head -1; }
+
+if [ -n "$(hp_is_ask "$payload")" ]; then
+  status=asking
+  note=$(hp_ask_note "$payload")   # first question's text → the note (best-effort)
+else
+  status=active
+  note=
+fi
+
+# cheap path: already active with nothing stale to clear → no-op (the common every-tool case).
+[ "$status" = active ] && [ "$(jget status)" = active ] && [ -z "$(jget proposal)" ] && [ -z "$(jget note)" ] && exit 0
+
+# value-replace status + clear proposal + (re)set note, in place. The record is written one-field-per-line
+# with these keys ALWAYS present (sessions.ts writeRecord), so each is a single value substitution — no key
+# add/remove, no JSON parser. Escape \ / & in the note for the sed REPLACEMENT (the note never contains ").
+note_esc=$(printf '%s' "$note" | sed 's/[\\/&]/\\&/g')
+tmp=$(mktemp) || exit 0
+sed -e "s/\(\"status\"[[:space:]]*:[[:space:]]*\)\"[^\"]*\"/\1\"$status\"/" \
+    -e "s/\(\"proposal\"[[:space:]]*:[[:space:]]*\)\"[^\"]*\"/\1\"\"/" \
+    -e "s/\(\"note\"[[:space:]]*:[[:space:]]*\)\"[^\"]*\"/\1\"$note_esc\"/" \
+    "$rec" > "$tmp" && mv "$tmp" "$rec"
+exit 0

package/hooks/dispatch.sh

@@ -0,0 +1,105 @@
+#!/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. ONE job:
+#   DISPATCH — run every handler bound to <Event> from the persistent manifest, in order, feeding each the
+#   ORIGINAL stdin. Reproduces the native parallel multi-hook contract DETERMINISTICALLY: all handlers run
+#   (side effects preserved), their stdout (decision/additionalContext) is concatenated through, and a
+#   block:true handler that exits 2 makes the dispatch exit 2 with that handler's stderr — the one signal
+#   the harness propagates. Pure bash, no node boot on the hot path. cwd = the project/worktree. $SPEX (abs
+#   tsx+cli) is inherited from the shim env.
+#
+# The old (1) GATE — an auto-materialize when the config content-hash moved — is RETIRED ([[commit-surgery]]):
+# a harness event is never a materialize trigger; the materialize anchors are git-native only (spex verbs,
+# session-worktree creation, and the pre-commit/post-checkout/post-merge hooks). .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
+# ([[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
+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
+# ([[hook-dispatch]]). Slot key = this cwd's rev-parse --show-toplevel through hp_tree_dir. Empty if git
+# can't resolve.
+rt="$(cd "$proj" 2>/dev/null && hp_runtime_dir)" || rt=""
+slot="$(cd "$proj" 2>/dev/null && hp_tree_dir)" || slot=""
+
+# 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.
+allowed="$slot/harnesses"
+if [ -f "$allowed" ]; then
+  grep -Fxq "$harness" "$allowed" || exit 0
+elif [ -f "$rt/harness-selection-v1" ]; then
+  exit 0
+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
+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"; }
+trap cleanup EXIT
+trap 'exit 130' INT
+trap 'exit 143' HUP TERM
+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
+  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
+    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"