@bookedsolid/rea 0.3.0 → 0.5.0

package/dist/registry/tofu.js

@@ -0,0 +1,173 @@
+/**
+ * TOFU classifier — the G7 gate between `.rea/registry.yaml` and the
+ * downstream pool.
+ *
+ * For each server declared in the registry, classify as:
+ *
+ *   - `first-seen` — no entry in `.rea/fingerprints.json`. Record the
+ *     fingerprint, surface a LOUD block to the operator, allow the server
+ *     to connect. This is the TOFU trust-on-first-use decision; the
+ *     loudness is deliberate so a silent poisoning at first install is
+ *     still visible in stderr / audit / logs.
+ *
+ *   - `unchanged` — fingerprint matches the stored value. Proceed normally.
+ *
+ *   - `drifted` — fingerprint differs from the stored value. Refuse to
+ *     connect the server unless `REA_ACCEPT_DRIFT` names it for a single
+ *     boot. The rest of the gateway stays up — other servers remain
+ *     available, the upstream client just sees a smaller catalog.
+ *
+ * The audit entry, log line, and stderr block are emitted by the caller
+ * (the gateway startup sequence). This module is pure classification plus
+ * store updates; keeping it side-effect-free makes it unit-testable
+ * without stubbing the filesystem or the audit chain.
+ */
+import { fingerprintServer } from './fingerprint.js';
+import { FINGERPRINT_STORE_VERSION } from './fingerprints-store.js';
+function parseAcceptDrift(raw) {
+    if (raw === undefined || raw.trim() === '')
+        return new Set();
+    return new Set(raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0));
+}
+/**
+ * Classify every server in `servers` against the loaded `store`. Pure:
+ * does not read or write the filesystem. Returns one classification per
+ * server in the same order.
+ *
+ * ## Rename-with-removal defense (scope: narrow)
+ *
+ * A name-only lookup is not enough when an attacker rewrites a
+ * previously trusted entry AND changes its `name` at the same time: the
+ * stored lookup would miss and the tampered entry would land as benign
+ * `first-seen`. To close THAT specific shape we compute a rename signal
+ * at boot time:
+ *
+ *   - `disappeared = stored_names - registry_names`
+ *   - `appeared    = registry_names - stored_names`
+ *
+ * If BOTH sets are non-empty in the same boot, at least one declared
+ * entry has been renamed-with-removal (stored entry vanished, a new name
+ * showed up). In that case every entry in `appeared` is promoted from
+ * `first-seen` to `drifted`: the operator MUST explicitly accept it via
+ * `REA_ACCEPT_DRIFT=<new-name>` before it connects.
+ *
+ * ### What this defense does NOT catch
+ *
+ * If the attacker leaves the old trusted entry in the registry (e.g.
+ * flipped `enabled: false`, or left untouched as a decoy) and ADDS a
+ * tampered entry under a new name, `disappeared` stays empty, the
+ * set-difference heuristic does not fire, and the new entry lands as
+ * `first-seen`. That is **not a bypass** of the TOFU contract — it is
+ * structurally identical to `operator added a new MCP server`, which
+ * TOFU intentionally allows with a LOUD stderr banner demanding the
+ * operator's attention. The first-seen banner is the enforcement
+ * mechanism for that shape; the rename-with-removal heuristic above is
+ * strictly additional coverage for the harder-to-notice shape where the
+ * old entry disappears at the same moment the new one arrives.
+ *
+ * Genuinely additive installs (new entry appended with no concurrent
+ * removal) also remain `first-seen` and get the usual LOUD banner.
+ *
+ * This is strictly additive over the name-based lookup — a name-matched
+ * drift (same name, changed config) still classifies as `drifted` via
+ * the primary path.
+ *
+ * The fingerprint itself already includes `server.name` (see
+ * `fingerprint.ts` canonicalization), so an attacker cannot make a
+ * renamed entry's fingerprint coincide with a stored one under a
+ * different name. That means a cross-name fingerprint match would never
+ * happen in practice — the set-difference heuristic above is what
+ * actually defends the rename-with-removal shape.
+ */
+export function classifyServers(servers, store, opts = {}) {
+    const bypass = parseAcceptDrift(opts.acceptDrift);
+    const registryNames = new Set(servers.map((s) => s.name));
+    const storedNames = new Set(Object.keys(store.servers));
+    const disappeared = new Set();
+    for (const n of storedNames) {
+        if (!registryNames.has(n))
+            disappeared.add(n);
+    }
+    const appeared = new Set();
+    for (const n of registryNames) {
+        if (!storedNames.has(n))
+            appeared.add(n);
+    }
+    // A rename is only plausible when something vanished AND something new
+    // appeared in the same boot. Pure additions (disappeared empty) are
+    // still benign first-seen.
+    const renameDetected = disappeared.size > 0 && appeared.size > 0;
+    // When a rename is detected, surface one disappeared stored fingerprint
+    // so the drift-block banner and audit entry have a concrete `stored`
+    // value to display. The choice is deterministic (first in insertion
+    // order from the store object) and documented as representative rather
+    // than authoritative — the operator's job is to compare the new entry
+    // against .rea/fingerprints.json by hand.
+    const representativeStored = renameDetected && disappeared.size > 0
+        ? store.servers[[...disappeared][0]]
+        : undefined;
+    return servers.map((s) => {
+        const current = fingerprintServer(s);
+        const stored = store.servers[s.name];
+        if (stored === undefined) {
+            if (renameDetected && appeared.has(s.name)) {
+                // Rename-then-tamper defense: promote to drifted. Operator must
+                // REA_ACCEPT_DRIFT the new name to let it connect.
+                const c = {
+                    server: s.name,
+                    verdict: 'drifted',
+                    current,
+                    bypassed: bypass.has(s.name),
+                };
+                if (representativeStored !== undefined)
+                    c.stored = representativeStored;
+                return c;
+            }
+            return { server: s.name, verdict: 'first-seen', current, bypassed: false };
+        }
+        if (stored === current) {
+            return { server: s.name, verdict: 'unchanged', current, stored, bypassed: false };
+        }
+        return {
+            server: s.name,
+            verdict: 'drifted',
+            current,
+            stored,
+            bypassed: bypass.has(s.name),
+        };
+    });
+}
+/**
+ * Merge classifications into an updated store. Applies the TOFU rule:
+ *
+ *   - `first-seen`  → add the current fingerprint.
+ *   - `unchanged`   → keep the existing value (no-op).
+ *   - `drifted`     → if bypassed, overwrite with the current fingerprint
+ *                     (operator has authorized the update); otherwise keep
+ *                     the stored value (drift persists across restart until
+ *                     explicitly accepted).
+ *
+ * Does not prune entries for servers that were removed from the registry —
+ * that decision is the operator's, and silently dropping fingerprints
+ * would let an attacker rename-then-reinstall a server to reset TOFU state.
+ */
+export function updateStore(store, classifications) {
+    const next = {
+        version: FINGERPRINT_STORE_VERSION,
+        servers: { ...store.servers },
+    };
+    for (const c of classifications) {
+        if (c.verdict === 'first-seen') {
+            next.servers[c.server] = c.current;
+            continue;
+        }
+        if (c.verdict === 'drifted' && c.bypassed) {
+            next.servers[c.server] = c.current;
+        }
+        // unchanged / drifted-no-bypass → leave store untouched for this server
+    }
+    return next;
+}

package/dist/registry/types.d.ts

@@ -11,7 +11,15 @@ export interface RegistryServer {
     command: string;
     /** Arguments passed to the spawned child process. */
     args: string[];
-    /** Environment variables merged onto the child process env. */
+    /**
+     * Environment variables merged onto the child process env. Values may
+     * reference rea-serve's own `process.env` via `${VAR}` syntax — e.g.
+     * `{ BOT_TOKEN: '${DISCORD_BOT_TOKEN}' }`. Only the curly-brace form is
+     * supported; no `$VAR`, no defaults, no command substitution. If a
+     * referenced var is unset at spawn time the affected server fails to
+     * start (the rest of the gateway still comes up). See
+     * `registry/interpolate.ts` for the full grammar and contract.
+     */
     env: Record<string, string>;
     /**
      * Optional opt-in list of operator-env var names to forward into the child.

package/hooks/push-review-gate.sh

@@ -56,8 +56,31 @@ fi
 # ── 4. Parse command ──────────────────────────────────────────────────────────
 CMD=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
 
+# ── 4a. BUG-008: self-detect git's native pre-push contract ───────────────────
+# When the hook is wired into `.husky/pre-push`, git invokes it with
+#   `$1 = remote name`, `$2 = remote url`
+# and delivers one line per refspec on stdin:
+#   `<local_ref> <local_sha> <remote_ref> <remote_sha>`
+# The Claude Code PreToolUse wrapper instead delivers JSON on stdin, which is
+# what the jq parse above targets. When jq returns empty, the stdin may in
+# fact be git's pre-push ref-list — sniff the first non-blank line, and if it
+# matches the `<ref> <40-hex> <ref> <40-hex>` shape, synthesize CMD as
+# `git push <remote>` (from argv $1) so the remainder of the gate runs
+# through the pre-push parser in step 6 rather than the argv fallback.
+#
+# Any other stdin shape (empty, random JSON, a non-push tool call) still
+# exits 0 here — the gate is a no-op for non-push Bash calls by design.
+FIRST_STDIN_LINE=$(printf '%s' "$INPUT" | awk 'NF { print; exit }')
 if [[ -z "$CMD" ]]; then
-  exit 0
+  if [[ -n "$FIRST_STDIN_LINE" ]] \
+     && printf '%s' "$FIRST_STDIN_LINE" \
+        | grep -qE '^[^[:space:]]+[[:space:]]+[0-9a-f]{40}[[:space:]]+[^[:space:]]+[[:space:]]+[0-9a-f]{40}[[:space:]]*$'; then
+    # Git native pre-push path. Remote comes from argv $1 — falls back to
+    # `origin` for safety if the hook was invoked without arguments.
+    CMD="git push ${1:-origin}"
+  else
+    exit 0
+  fi
 fi
 
 # Only trigger on git push commands
@@ -73,6 +96,167 @@ if [[ -f "$POLICY_FILE" ]]; then
   fi
 fi
 
+# ── 5a. REA_SKIP_PUSH_REVIEW — whole-gate escape hatch ───────────────────────
+# An opt-in bypass for the ENTIRE push-review gate (not just the Codex branch).
+# Exists to unblock consumers when rea itself is broken (as in BUG-009 pre-0.5.0)
+# or a corrupt policy/audit file would otherwise deadlock a push. Requires an
+# explicit non-empty reason; the value of REA_SKIP_PUSH_REVIEW is recorded
+# verbatim in the audit record as the reason.
+#
+# Fail-closed contract matches REA_SKIP_CODEX_REVIEW:
+#   - missing dist/audit/append.js → exit 2
+#   - missing git identity         → exit 2
+#   - Node failure                 → exit 2
+#
+# Audit tool_name is `push.review.skipped`. This is intentionally NOT
+# `codex.review` or `codex.review.skipped` — a skip of the whole gate is a
+# separately-audited event and does not satisfy the Codex-review jq predicate.
+if [[ -n "${REA_SKIP_PUSH_REVIEW:-}" ]]; then
+  SKIP_REASON="$REA_SKIP_PUSH_REVIEW"
+  AUDIT_APPEND_JS="${REA_ROOT}/dist/audit/append.js"
+
+  if [[ ! -f "$AUDIT_APPEND_JS" ]]; then
+    {
+      printf 'PUSH BLOCKED: REA_SKIP_PUSH_REVIEW requires rea to be built.\n'
+      printf '\n'
+      printf '  REA_SKIP_PUSH_REVIEW is set but %s is missing.\n' "$AUDIT_APPEND_JS"
+      printf '  Run: pnpm build\n'
+      printf '\n'
+    } >&2
+    exit 2
+  fi
+
+  # Codex F2: CI-aware refusal. The skip hatch is ambient — any process that
+  # can set env vars can flip the gate off with a forged git identity (git
+  # config is mutable repo config). In a CI context, refuse by default; only
+  # allow if the policy explicitly opted in via review.allow_skip_in_ci=true.
+  if [[ -n "${CI:-}" ]]; then
+    ALLOW_CI_SKIP=""
+    READ_FIELD_JS="${REA_ROOT}/dist/scripts/read-policy-field.js"
+    if [[ -f "$READ_FIELD_JS" ]]; then
+      ALLOW_CI_SKIP=$(REA_ROOT="$REA_ROOT" node "$READ_FIELD_JS" review.allow_skip_in_ci 2>/dev/null || echo "")
+    fi
+    if [[ "$ALLOW_CI_SKIP" != "true" ]]; then
+      {
+        printf 'PUSH BLOCKED: REA_SKIP_PUSH_REVIEW refused in CI context.\n'
+        printf '\n'
+        printf '  CI env var is set. An unauthenticated env-var bypass in a shared\n'
+        printf '  build agent is not trusted. To enable, set\n'
+        printf '    review:\n'
+        printf '      allow_skip_in_ci: true\n'
+        printf '  in .rea/policy.yaml — explicitly authorizing env-var skips in CI.\n'
+        printf '\n'
+      } >&2
+      exit 2
+    fi
+  fi
+
+  SKIP_ACTOR=$(cd "$REA_ROOT" && git config user.email 2>/dev/null || echo "")
+  if [[ -z "$SKIP_ACTOR" ]]; then
+    SKIP_ACTOR=$(cd "$REA_ROOT" && git config user.name 2>/dev/null || echo "")
+  fi
+  if [[ -z "$SKIP_ACTOR" ]]; then
+    {
+      printf 'PUSH BLOCKED: REA_SKIP_PUSH_REVIEW requires a git identity.\n'
+      printf '\n'
+      # shellcheck disable=SC2016  # backticks are literal markdown in user-facing message
+      printf '  Neither `git config user.email` nor `git config user.name`\n'
+      printf '  is set. The skip audit record would have no actor; refusing\n'
+      printf '  to bypass without one.\n'
+      printf '\n'
+    } >&2
+    exit 2
+  fi
+
+  SKIP_BRANCH=$(cd "$REA_ROOT" && git branch --show-current 2>/dev/null || echo "")
+  SKIP_HEAD=$(cd "$REA_ROOT" && git rev-parse HEAD 2>/dev/null || echo "")
+
+  # Codex F2: record OS identity alongside the (mutable, git-sourced) actor so
+  # downstream auditors can reconstruct who REALLY invoked the bypass on a
+  # shared host. None of these are forgeable from inside the push process alone.
+  SKIP_OS_UID=$(id -u 2>/dev/null || echo "")
+  SKIP_OS_WHOAMI=$(whoami 2>/dev/null || echo "")
+  SKIP_OS_HOST=$(hostname 2>/dev/null || echo "")
+  SKIP_OS_PID=$$
+  SKIP_OS_PPID=$PPID
+  SKIP_OS_PPID_CMD=$(ps -o command= -p "$PPID" 2>/dev/null | head -c 512 || echo "")
+  SKIP_OS_TTY=$(tty 2>/dev/null || echo "not-a-tty")
+  SKIP_OS_CI="${CI:-}"
+
+  SKIP_METADATA=$(jq -n \
+    --arg head_sha "$SKIP_HEAD" \
+    --arg branch "$SKIP_BRANCH" \
+    --arg reason "$SKIP_REASON" \
+    --arg actor "$SKIP_ACTOR" \
+    --arg os_uid "$SKIP_OS_UID" \
+    --arg os_whoami "$SKIP_OS_WHOAMI" \
+    --arg os_hostname "$SKIP_OS_HOST" \
+    --arg os_pid "$SKIP_OS_PID" \
+    --arg os_ppid "$SKIP_OS_PPID" \
+    --arg os_ppid_cmd "$SKIP_OS_PPID_CMD" \
+    --arg os_tty "$SKIP_OS_TTY" \
+    --arg os_ci "$SKIP_OS_CI" \
+    '{
+      head_sha: $head_sha,
+      branch: $branch,
+      reason: $reason,
+      actor: $actor,
+      verdict: "skipped",
+      os_identity: {
+        uid: $os_uid,
+        whoami: $os_whoami,
+        hostname: $os_hostname,
+        pid: $os_pid,
+        ppid: $os_ppid,
+        ppid_cmd: $os_ppid_cmd,
+        tty: $os_tty,
+        ci: $os_ci
+      }
+    }' 2>/dev/null)
+
+  if [[ -z "$SKIP_METADATA" ]]; then
+    {
+      printf 'PUSH BLOCKED: REA_SKIP_PUSH_REVIEW could not serialize audit metadata.\n' >&2
+    } >&2
+    exit 2
+  fi
+
+  REA_ROOT="$REA_ROOT" REA_SKIP_METADATA="$SKIP_METADATA" \
+    node --input-type=module -e "
+      const mod = await import(process.env.REA_ROOT + '/dist/audit/append.js');
+      const metadata = JSON.parse(process.env.REA_SKIP_METADATA);
+      await mod.appendAuditRecord(process.env.REA_ROOT, {
+        tool_name: 'push.review.skipped',
+        server_name: 'rea.escape_hatch',
+        status: mod.InvocationStatus.Allowed,
+        tier: mod.Tier.Read,
+        metadata,
+      });
+    " 2>/dev/null
+  NODE_STATUS=$?
+  if [[ "$NODE_STATUS" -ne 0 ]]; then
+    {
+      printf 'PUSH BLOCKED: REA_SKIP_PUSH_REVIEW audit-append failed (node exit %s).\n' "$NODE_STATUS"
+      printf '  Refusing to bypass the push gate without a receipt.\n'
+    } >&2
+    exit 2
+  fi
+
+  {
+    printf '\n'
+    printf '==  PUSH REVIEW GATE SKIPPED via REA_SKIP_PUSH_REVIEW\n'
+    printf '    Reason:  %s\n' "$SKIP_REASON"
+    printf '    Actor:   %s\n' "$SKIP_ACTOR"
+    printf '    Branch:  %s\n' "${SKIP_BRANCH:-<detached>}"
+    printf '    Head:    %s\n' "${SKIP_HEAD:-<unknown>}"
+    printf '    Audited: .rea/audit.jsonl (tool_name=push.review.skipped)\n'
+    printf '\n'
+    printf '    This is a gate weakening. Every invocation is permanently audited.\n'
+    printf '\n'
+  } >&2
+  exit 0
+fi
+
 # ── 6. Determine source/target commits for each refspec ──────────────────────
 # The authoritative source for which commits are being pushed is the pre-push
 # hook stdin contract: one line per refspec, with fields

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bookedsolid/rea",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Agentic governance layer for Claude Code — policy enforcement, hook-based safety gates, audit logging, and Codex-integrated adversarial review for AI-assisted projects",
   "license": "MIT",
   "author": "Booked Solid Technology <oss@bookedsolid.tech> (https://bookedsolid.tech)",

package/profiles/bst-internal-no-codex.yaml

@@ -32,6 +32,11 @@ blocked_paths:
   - SECURITY.md
   - THREAT_MODEL.md
 notification_channel: ""
+# G9: Booked-internal consumers retain the stricter 0.2.x posture — a single
+# literal injection match at write/destructive tier denies (does not merely
+# warn). External profiles inherit the schema default `false`.
+injection:
+  suspicious_blocks_writes: true
 context_protection:
   delegate_to_subagent:
     - pnpm run build

package/profiles/bst-internal.yaml

@@ -15,6 +15,13 @@ blocked_paths:
   - SECURITY.md
   - THREAT_MODEL.md
 notification_channel: ""
+# G9: Booked-internal consumers retain the stricter 0.2.x posture — a single
+# literal injection match at write/destructive tier denies (does not merely
+# warn). External profiles (open-source, client-engagement, minimal, lit-wc)
+# inherit the schema default `false` so upgrading 0.2.x consumers are not
+# silently tightened.
+injection:
+  suspicious_blocks_writes: true
 context_protection:
   delegate_to_subagent:
     - pnpm run build

package/scripts/tarball-smoke.sh

@@ -0,0 +1,197 @@
+#!/usr/bin/env bash
+# tarball-smoke.sh — exercise the packed @bookedsolid/rea tarball end-to-end
+# in an isolated tempdir. Catches packaging regressions (missing files from
+# `files:`, broken exports map, shebang / chmod issues on `bin`, postinstall
+# failures, dependency resolution drift) BEFORE the tarball reaches npm.
+#
+# Must be run from the repo root. Assumes `dist/` has already been built.
+#
+# Runs under CI on every PR and on every push to main; also recommended as a
+# manual gate before hand-authorizing a Changesets release PR merge.
+#
+# ## Developer-run negative probe (optional, not in CI)
+#
+# To verify the tree-equality asserts actually fail loud on a missing shipped
+# file, temporarily drop `commands/` or `.husky/` from `package.json#files[]`,
+# run this script, and confirm it exits non-zero at the install-surface diff
+# step. Revert the `files:` edit before committing. CI does not run this probe
+# because it would mutate package.json.
+#
+# Exit codes:
+#   0 — smoke passed
+#   1 — preflight failure (missing dist, pack failed)
+#   2 — smoke assertion failure (bin missing, init/doctor failed, exports broken)
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$REPO_ROOT"
+
+if [ ! -d "dist" ]; then
+  echo "[smoke] FAIL — dist/ not found. Run 'pnpm build' first." >&2
+  exit 1
+fi
+
+PACK_DIR="$(mktemp -d -t rea-smoke-pack-XXXXXX)"
+SMOKE_DIR="$(mktemp -d -t rea-smoke-install-XXXXXX)"
+DIFF_TMP="$(mktemp -t rea-smoke-diff-XXXXXX)"
+cleanup() { rm -rf -- "$PACK_DIR" "$SMOKE_DIR" 2>/dev/null || true; rm -f "$DIFF_TMP"; }
+# EXIT alone misses Ctrl-C / TERM / HUP during local runs, leaving
+# /tmp/rea-smoke-* tempdirs behind. Trap the interrupt signals too.
+trap cleanup EXIT HUP INT TERM
+
+echo "[smoke] pack → $PACK_DIR"
+pnpm pack --pack-destination "$PACK_DIR" >/dev/null
+TARBALL="$(ls "$PACK_DIR"/bookedsolid-rea-*.tgz | head -1)"
+if [ -z "$TARBALL" ] || [ ! -f "$TARBALL" ]; then
+  echo "[smoke] FAIL — pnpm pack produced no tarball in $PACK_DIR" >&2
+  exit 1
+fi
+echo "[smoke] tarball: $(basename "$TARBALL") ($(wc -c < "$TARBALL" | awk '{printf "%.0f KB\n", $1/1024}'))"
+
+echo "[smoke] install in $SMOKE_DIR"
+cd "$SMOKE_DIR"
+npm init -y >/dev/null
+npm install --no-audit --no-fund --loglevel=error "$TARBALL"
+
+# Drop the temp package.json + lockfile that `npm init -y` + `npm install`
+# wrote. The tempdir must look like a fresh consumer project (no package.json)
+# so `rea init` exercises the same code path a brand-new consumer hits.
+rm -f package.json package-lock.json
+git init -q
+
+echo "[smoke] rea --version"
+VERSION_OUT="$(./node_modules/.bin/rea --version)"
+# Pass the repo-root package.json path via argv to avoid interpolating it
+# into a JS string literal — paths with apostrophes, backslashes, or `${...}`
+# expansions would otherwise break the require() call.
+EXPECTED_VERSION="$(node -p "require(process.argv[1]).version" "$REPO_ROOT/package.json")"
+if [ "$VERSION_OUT" != "$EXPECTED_VERSION" ]; then
+  echo "[smoke] FAIL — rea --version returned '$VERSION_OUT', expected '$EXPECTED_VERSION'" >&2
+  exit 2
+fi
+echo "[smoke]   → $VERSION_OUT"
+
+echo "[smoke] rea --help"
+./node_modules/.bin/rea --help >/dev/null
+
+echo "[smoke] rea init --yes --profile open-source"
+./node_modules/.bin/rea init --yes --profile open-source
+
+# Verify the installed layout matches what init claims it wrote.
+for expected in .rea/policy.yaml .rea/registry.yaml .claude/settings.json CLAUDE.md .rea/install-manifest.json; do
+  if [ ! -f "$expected" ]; then
+    echo "[smoke] FAIL — rea init did not create $expected" >&2
+    exit 2
+  fi
+done
+
+# ---------------------------------------------------------------------------
+# Install-surface tree-equality asserts.
+#
+# Prior versions counted `.claude/agents/*.md` and `.claude/hooks/*.sh` and
+# never verified `.claude/commands/` or the shipped `.husky/pre-push`. A
+# tarball that dropped either surface still passed. We now diff sorted file
+# lists: any missing OR extra file fails loud and names the delta.
+#
+# Surfaces under test:
+#   1. .claude/agents/         ↔ repo agents/*.md              (flat)
+#   2. .claude/hooks/          ↔ repo hooks/**/*.sh            (flat + _lib/)
+#   3. .claude/commands/       ↔ repo commands/*.md            (flat)
+#   4. node_modules/.../.husky ↔ repo .husky/{commit-msg,pre-push}
+#
+# The `.husky/` check targets the package tree under node_modules because
+# `rea init` only copies `.husky/*` into the consumer when `.husky/` already
+# exists there. On a fresh consumer (this smoke's default), the hooks live as
+# `.git/hooks/{commit-msg,pre-push}` via the fallback installers. What must
+# ALWAYS be true is that the tarball itself ships the `.husky/` source of
+# truth — without it, husky-using consumers get nothing.
+# ---------------------------------------------------------------------------
+
+assert_tree_equal() {
+  # $1 — label for error messages
+  # $2 — file listing of the source tree (one relative path per line)
+  # $3 — file listing of the installed tree (one relative path per line)
+  local label="$1" src="$2" dst="$3"
+  if [ -z "$src" ] || [ -z "$dst" ]; then
+    printf '[smoke] FAIL — empty file listing for %s\n' "$label" >&2
+    exit 2
+  fi
+  if ! diff -u <(printf '%s\n' "$src" | sort -u) <(printf '%s\n' "$dst" | sort -u) > "$DIFF_TMP" 2>&1; then
+    echo "[smoke] FAIL — $label differs between source tree and installed tree:" >&2
+    cat "$DIFF_TMP" >&2
+    exit 2
+  fi
+}
+
+# 1. agents — flat listing of *.md
+AGENTS_SRC="$(cd "$REPO_ROOT/agents" && find . -maxdepth 1 -type f -name '*.md' | sed 's|^\./||')"
+AGENTS_DST="$(cd "$SMOKE_DIR/.claude/agents" && find . -maxdepth 1 -type f -name '*.md' | sed 's|^\./||')"
+assert_tree_equal ".claude/agents tree" "$AGENTS_SRC" "$AGENTS_DST"
+
+# 2. hooks — recursive listing of *.sh (walks hooks/_lib/ too)
+HOOKS_SRC="$(cd "$REPO_ROOT/hooks" && find . -type f -name '*.sh' | sed 's|^\./||')"
+HOOKS_DST="$(cd "$SMOKE_DIR/.claude/hooks" && find . -type f -name '*.sh' | sed 's|^\./||')"
+assert_tree_equal ".claude/hooks tree" "$HOOKS_SRC" "$HOOKS_DST"
+
+# 3. commands — flat listing of *.md
+COMMANDS_SRC="$(cd "$REPO_ROOT/commands" && find . -maxdepth 1 -type f -name '*.md' | sed 's|^\./||')"
+COMMANDS_DST="$(cd "$SMOKE_DIR/.claude/commands" && find . -maxdepth 1 -type f -name '*.md' | sed 's|^\./||')"
+assert_tree_equal ".claude/commands tree" "$COMMANDS_SRC" "$COMMANDS_DST"
+
+# 4. husky — explicit pre-push + commit-msg existence inside the package
+#    tree under node_modules. `rea init` does not copy these into a fresh
+#    consumer's root, so we check the shipped copy directly. If either file
+#    is missing from the tarball, husky-using consumers silently get zero
+#    enforcement on their next `pnpm install`.
+#
+#    Executable-bit check is intentionally NOT asserted here: npm's tarball
+#    format strips the group/other execute bits from non-`bin:` files on
+#    install, so the shipped file lives at mode 0644. What matters is that
+#    the installers in commit-msg.ts and pre-push.ts use these as templates
+#    and chmod the destination (.git/hooks/... or .husky/...) themselves.
+HUSKY_PKG_DIR="$SMOKE_DIR/node_modules/@bookedsolid/rea/.husky"
+for husky_file in commit-msg pre-push; do
+  path="$HUSKY_PKG_DIR/$husky_file"
+  if [ ! -f "$path" ]; then
+    echo "[smoke] FAIL — tarball missing .husky/$husky_file (expected at $path)" >&2
+    exit 2
+  fi
+done
+
+# On a fresh consumer (no pre-existing .husky/), rea installs the fallback
+# pre-push + commit-msg into .git/hooks/. Assert that path landed too — it is
+# the enforcement surface for this smoke's simulated consumer.
+for git_hook in commit-msg pre-push; do
+  path="$SMOKE_DIR/.git/hooks/$git_hook"
+  if [ ! -f "$path" ]; then
+    echo "[smoke] FAIL — .git/hooks/$git_hook missing after rea init" >&2
+    exit 2
+  fi
+  if [ ! -x "$path" ]; then
+    echo "[smoke] FAIL — .git/hooks/$git_hook is not executable" >&2
+    exit 2
+  fi
+done
+
+AGENT_COUNT="$(printf '%s\n' "$AGENTS_DST" | grep -c . || true)"
+HOOK_COUNT="$(printf '%s\n' "$HOOKS_DST" | grep -c . || true)"
+COMMAND_COUNT="$(printf '%s\n' "$COMMANDS_DST" | grep -c . || true)"
+echo "[smoke]   → $AGENT_COUNT agents, $HOOK_COUNT hooks, $COMMAND_COUNT commands, .husky/{commit-msg,pre-push} shipped, .git/hooks/{commit-msg,pre-push} installed"
+
+echo "[smoke] rea doctor"
+./node_modules/.bin/rea doctor
+
+# Verify every declared public export resolves. If the exports map points at a
+# file that didn't ship in `files:`, this is where we catch it.
+echo "[smoke] resolve exports"
+node --input-type=module -e "
+import('@bookedsolid/rea').then(m => { if (typeof m !== 'object') { console.error('bad root export'); process.exit(2); } });
+import('@bookedsolid/rea/policy').then(m => { if (!m) { console.error('bad /policy export'); process.exit(2); } });
+import('@bookedsolid/rea/middleware').then(m => { if (!m) { console.error('bad /middleware export'); process.exit(2); } });
+import('@bookedsolid/rea/audit').then(m => {
+  if (typeof m.appendAuditRecord !== 'function') { console.error('audit.appendAuditRecord not a function'); process.exit(2); }
+});
+"
+echo "[smoke]   → root, /policy, /middleware, /audit all resolve"
+
+echo "[smoke] PASS"