@bookedsolid/rea 0.6.2 → 0.8.0

package/.husky/pre-push

@@ -29,8 +29,22 @@
 
 set -eu
 
+# git passes the remote name as $1 to pre-push. Fall back to `origin` for
+# direct invocation (tests, manual runs). The shared core uses the same
+# argv_remote convention — parity required so a push to `upstream` probes
+# `upstream/main` rather than stale `origin/main`.
+REMOTE="${1:-origin}"
+
 REA_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
 
+# Well-known empty-tree SHA: `git hash-object -t tree /dev/null`. Every git
+# installation carries this object implicitly — using it as a merge-base
+# baseline for initial pushes lets `git diff $EMPTY_TREE $local_sha` emit
+# the complete change set against a truly-empty tree. The protected-path
+# check then sees every file in the initial push, so a first push of
+# protected-path changes to a fresh remote is still gated.
+EMPTY_TREE='4b825dc642cb6eb9a060e54bf8d69288fbee4904'
+
 if [ -f "${REA_ROOT}/.rea/HALT" ]; then
   # POSIX `head` does not specify `-c`; use awk for the first line. HALT is
   # a short reason string, so the first line is enough for display.
@@ -81,14 +95,55 @@ while IFS=' ' read -r local_ref local_sha remote_ref remote_sha; do
 
   # Determine merge base. If remote is new (remote_sha is zeros), diff against
   # the default branch; else against remote_sha.
+  #
+  # Anchor on a REMOTE-TRACKING ref (refs/remotes/<remote>/<name>), NOT a bare
+  # branch name. A bare `main` resolves to refs/heads/main, which the pusher
+  # controls locally — a local main fast-forwarded to the feature tip would
+  # give merge-base main <local_sha> == local_sha and silently collapse the
+  # diff to empty. Remote-tracking refs are server-authoritative from the
+  # last fetch and cannot be tampered with locally.
+  #
+  # Fallback order when $REMOTE/HEAD is not set (common on shallow or mirror
+  # clones): probe $REMOTE/main then $REMOTE/master via rev-parse. If neither
+  # exists — initial push to a fresh remote with no tracking refs yet — use
+  # the well-known EMPTY_TREE as the baseline so the diff covers the FULL
+  # change set. This keeps the protected-path check honest on first push
+  # (prior versions of this patch `continue`d here, which was a fail-open
+  # flagged as HIGH by adversarial review).
   if [ "$remote_sha" = "0000000000000000000000000000000000000000" ]; then
-    default_branch=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||')
-    [ -z "${default_branch:-}" ] && default_branch="main"
-    base=$(git merge-base "$default_branch" "$local_sha" 2>/dev/null || printf '')
+    default_ref=$(git symbolic-ref "refs/remotes/${REMOTE}/HEAD" 2>/dev/null || printf '')
+    if [ -z "${default_ref:-}" ]; then
+      if git rev-parse --verify --quiet "refs/remotes/${REMOTE}/main" >/dev/null 2>&1; then
+        default_ref="refs/remotes/${REMOTE}/main"
+      elif git rev-parse --verify --quiet "refs/remotes/${REMOTE}/master" >/dev/null 2>&1; then
+        default_ref="refs/remotes/${REMOTE}/master"
+      else
+        default_ref=""
+      fi
+    fi
+    if [ -n "${default_ref:-}" ]; then
+      base=$(git merge-base "$default_ref" "$local_sha" 2>/dev/null || printf '')
+    else
+      # Bootstrap: no remote-tracking ref exists at all. Use the empty-tree
+      # baseline so the diff covers every file in the push. git diff accepts
+      # a tree SHA as the left-hand side.
+      base="$EMPTY_TREE"
+    fi
   else
     base=$(git merge-base "$remote_sha" "$local_sha" 2>/dev/null || printf '')
   fi
-  [ -z "${base:-}" ] && continue
+  # Fail CLOSED on empty merge-base when a remote ref DID resolve. The
+  # 0.4.0..0.6.2 behavior here was to `continue` — a silent bypass. A push
+  # whose history is unrelated to origin (or any transient git failure at
+  # merge-base resolution) would pass through without the protected-path
+  # check ever running. Refuse instead and force the operator to resolve it.
+  if [ -z "${base:-}" ]; then
+    printf 'PUSH BLOCKED: could not resolve merge-base between %s and %s (local_ref=%s remote_ref=%s).\n' \
+      "${remote_sha:-<new>}" "${local_sha:-<missing>}" "${local_ref:-<unknown>}" "${remote_ref:-<unknown>}" >&2
+    printf '  Run `git fetch %s` and retry. If the history is genuinely unrelated\n' "$REMOTE" >&2
+    printf '  to %s (e.g. grafted branch), resolve manually before pushing.\n' "$REMOTE" >&2
+    exit 1
+  fi
 
   # Check if the diff touches protected paths.
   if git diff --name-only "$base" "$local_sha" 2>/dev/null | grep -qE "$PROTECTED_RE"; then

package/THREAT_MODEL.md

@@ -107,6 +107,20 @@ Downstream MCP servers are treated as untrusted by default. Codex plugin *invoca
 
 ---
 
+### 5.2a `CLAUDE_PROJECT_DIR` as advisory-only signal (BUG-012, 0.6.2)
+
+**Threat:** The `push-review-gate.sh` and `commit-review-gate.sh` hooks need to know the rea repository root so that (a) cross-repo invocations from consumer repositories short-circuit cleanly, and (b) HALT / policy enforcement always evaluates the correct policy file. Prior to 0.6.2, the guard read the root from the `CLAUDE_PROJECT_DIR` environment variable. That variable is caller-controlled — any process invoking the hook (or any shell that has it exported in the environment) can set it to a foreign path, which the guard would then treat as rea. The result: HALT is silently bypassed, the cross-repo short-circuit fires on the wrong comparison, and policy is read from a directory the caller chose.
+
+**Mitigations:**
+
+- The hooks derive `REA_ROOT` from their own on-disk location using `BASH_SOURCE[0]` + `pwd -P`, then walk up to 4 parent directories looking for `.rea/policy.yaml` as the authoritative install marker. Install topology is fixed: hooks live at `<root>/.claude/hooks/<name>.sh`, so the anchor is forge-resistant — a caller cannot relocate the hook file without filesystem write access to the rea install, which is already protected by `settings-protection.sh` and `blocked-paths` enforcement.
+- `CLAUDE_PROJECT_DIR` is retained only as an advisory signal. When set and the realpath differs from the script-derived `REA_ROOT`, the hook emits a stderr advisory and continues using the script-derived value. It is never compared for short-circuit, never used to select the policy file, and never used to locate HALT.
+- The cross-repo guard compares `git rev-parse --git-common-dir` on both sides (not path prefixes). Mixed state (one side git, one non-git) fails **closed** — the gate runs — rather than falling through to path-prefix. Only the both-non-git case still uses path-prefix, matching the documented 0.5.1 non-git escape hatch.
+
+**Residual risk:** If a local attacker has write access to the rea install directory they can move or replace the hook file, which would change `SCRIPT_DIR` and therefore `REA_ROOT`. This is equivalent to tampering with any other hook contents (`settings-protection.sh` already addresses it) and lies outside the `CLAUDE_PROJECT_DIR` threat class. Ref: `__tests__/hooks/push-review-gate-cross-repo.test.ts` "BUG-012: foreign CLAUDE_PROJECT_DIR does NOT bypass HALT".
+
+---
+
 ### 5.3 Policy Tampering
 
 **Threat:** An attacker or rogue agent modifies `policy.yaml` to elevate `autonomy_level` above `max_autonomy_level`, removes blocked paths, or disables `block_ai_attribution`.

package/dist/cli/install/pre-push.js

@@ -268,6 +268,9 @@ const KNOWN_LEGACY_HUSKY_SHA256 = new Set([
     '9d4885b64f50dd91887c2c6b4d17e3aa91b0be5da8e842ca8915bec1bf369de5',
     // Initial publication (commit b513760, G6 MVP).
     '1ee21164ccce628a1ef85c313d09afdcdb8560efd761ec64b046cca6cc319cba',
+    // 0.7.0 — Codex pass-2 empty-tree baseline + $1 remote honoring +
+    // fail-closed on empty merge-base when a remote ref did resolve.
+    '84449e17a04986f3a6580eeb6fb9192cc6d8fabb099cd41cab0574a800c82056',
 ]);
 /**
  * True when `content` contains a POSIX shell construct that detects

package/dist/gateway/downstream.d.ts

@@ -75,6 +75,7 @@ export interface BuiltChildEnv {
 }
 export declare function buildChildEnv(config: RegistryServer, hostEnv?: NodeJS.ProcessEnv): BuiltChildEnv;
 export declare class DownstreamConnection {
+    #private;
     private readonly config;
     /**
      * Optional structured logger (G5). When omitted, connection lifecycle
@@ -93,13 +94,6 @@ export declare class DownstreamConnection {
     /** Epoch ms of the last successful reconnect. Used by the flapping guard. */
     private lastReconnectAt;
     private health;
-    /**
-     * The most recent error observed on this connection (connect or call
-     * failure). Surfaced via `__rea__health` so callers can diagnose an empty
-     * tool catalog without digging through stderr logs. Set to `null` after a
-     * successful connect/reconnect.
-     */
-    private lastErrorMessage;
     constructor(config: RegistryServer, 
     /**
      * Optional structured logger (G5). When omitted, connection lifecycle
@@ -115,13 +109,16 @@ export declare class DownstreamConnection {
      * Last error observed, or null if the connection has never failed (or fully
      * recovered).
      *
-     * BUG-011 (0.6.2): cap exposure via `boundedDiagnosticString`. An
-     * adversarial downstream MCP can throw `new Error(huge_string)`, and that
-     * raw message flows from `err.message` into `lastErrorMessage` at the
-     * assignment sites below. Bounding here means every consumer of the
-     * getter — the `__rea__health` snapshot, diagnostic logs, future status
-     * dashboards — sees a bounded, UTF-16-safe string. `sanitizeHealthSnapshot`
-     * applies the same cap for defense-in-depth.
+     * BUG-011 (0.6.2) → BUG-014 (0.7.0): cap exposure via
+     * `boundedDiagnosticString`. 0.6.2 applied the bound at *read*, which
+     * meant every assignment site was trusted to eventually flow through
+     * this getter. 0.7.0 moves the bound to the private *setter* above, so
+     * the invariant is structural — every `this.#lastErrorMessage = x` write
+     * is bounded at assignment time regardless of how many assignment sites
+     * exist or where they live. We keep the read-side bound as cheap
+     * defense-in-depth (it's a no-op for already-bounded strings and costs
+     * O(length) only if a future intra-class edit writes directly to the
+     * backing field instead of going through the setter).
      */
     get lastError(): string | null;
     connect(): Promise<void>;

package/dist/gateway/downstream.js

@@ -113,8 +113,36 @@ export class DownstreamConnection {
      * failure). Surfaced via `__rea__health` so callers can diagnose an empty
      * tool catalog without digging through stderr logs. Set to `null` after a
      * successful connect/reconnect.
+     *
+     * BUG-014 (0.7.0): true ECMAScript private field + private accessor pair.
+     * Every internal write `this.#lastErrorMessage = x` goes through the
+     * setter, which applies `boundedDiagnosticString` at assignment time.
+     * This converts the prior "bound-at-read" invariant (see `get lastError`
+     * below, which was the single chokepoint before 0.7.0) into a structural
+     * property: no matter how many assignment sites exist, every one produces
+     * a bounded string. A future refactor can add new sites without needing
+     * to know the bound exists — the setter enforces it.
+     *
+     * The backing field `#lastErrorBacking` is the raw storage; only the
+     * setter writes to it. External code cannot reach either name because
+     * both are ES-private (`#`), not TS-private.
      */
-    lastErrorMessage = null;
+    #lastErrorBacking = null;
+    get #lastErrorMessage() {
+        return this.#lastErrorBacking;
+    }
+    set #lastErrorMessage(msg) {
+        if (msg !== null && typeof msg !== 'string') {
+            // BUG-014 defense-in-depth: the TS type gate is strict, but a future
+            // refactor (or an `as unknown as string` cast) could slip a non-string
+            // through. `boundedDiagnosticString` calls `.length` / `.slice` on the
+            // input — a non-string would throw or silently corrupt the field. Fail
+            // loud instead.
+            throw new TypeError(`DownstreamConnection#lastErrorMessage: expected string | null, got ${typeof msg}`);
+        }
+        this.#lastErrorBacking =
+            msg === null ? null : boundedDiagnosticString(msg);
+    }
     constructor(config, 
     /**
      * Optional structured logger (G5). When omitted, connection lifecycle
@@ -139,18 +167,22 @@ export class DownstreamConnection {
      * Last error observed, or null if the connection has never failed (or fully
      * recovered).
      *
-     * BUG-011 (0.6.2): cap exposure via `boundedDiagnosticString`. An
-     * adversarial downstream MCP can throw `new Error(huge_string)`, and that
-     * raw message flows from `err.message` into `lastErrorMessage` at the
-     * assignment sites below. Bounding here means every consumer of the
-     * getter — the `__rea__health` snapshot, diagnostic logs, future status
-     * dashboards — sees a bounded, UTF-16-safe string. `sanitizeHealthSnapshot`
-     * applies the same cap for defense-in-depth.
+     * BUG-011 (0.6.2) → BUG-014 (0.7.0): cap exposure via
+     * `boundedDiagnosticString`. 0.6.2 applied the bound at *read*, which
+     * meant every assignment site was trusted to eventually flow through
+     * this getter. 0.7.0 moves the bound to the private *setter* above, so
+     * the invariant is structural — every `this.#lastErrorMessage = x` write
+     * is bounded at assignment time regardless of how many assignment sites
+     * exist or where they live. We keep the read-side bound as cheap
+     * defense-in-depth (it's a no-op for already-bounded strings and costs
+     * O(length) only if a future intra-class edit writes directly to the
+     * backing field instead of going through the setter).
      */
     get lastError() {
-        if (this.lastErrorMessage === null)
+        const raw = this.#lastErrorMessage;
+        if (raw === null)
             return null;
-        return boundedDiagnosticString(this.lastErrorMessage);
+        return boundedDiagnosticString(raw);
     }
     async connect() {
         if (this.client !== null)
@@ -173,12 +205,12 @@ export class DownstreamConnection {
         catch (err) {
             this.health = 'unhealthy';
             const msg = `failed to resolve env for downstream "${this.config.name}": ${err instanceof Error ? err.message : err}`;
-            this.lastErrorMessage = msg;
+            this.#lastErrorMessage = msg;
             throw new Error(msg);
         }
         if (built.missing.length > 0) {
             this.health = 'unhealthy';
-            this.lastErrorMessage = `missing env: ${built.missing.join(', ')}`;
+            this.#lastErrorMessage = `missing env: ${built.missing.join(', ')}`;
             // One line per missing var so grep/jq users can find the exact gap.
             // We intentionally do NOT log the env key name's VALUE (there is none —
             // it's unresolved) nor any other env values.
@@ -198,12 +230,12 @@ export class DownstreamConnection {
             await client.connect(transport);
             this.client = client;
             this.health = 'healthy';
-            this.lastErrorMessage = null;
+            this.#lastErrorMessage = null;
         }
         catch (err) {
             this.health = 'unhealthy';
             const msg = `failed to connect to downstream "${this.config.name}" (${this.config.command}): ${err instanceof Error ? err.message : err}`;
-            this.lastErrorMessage = msg;
+            this.#lastErrorMessage = msg;
             throw new Error(msg);
         }
     }
@@ -230,7 +262,7 @@ export class DownstreamConnection {
             // this, a connection that failed once and then recovered on the very
             // next call (same client, no reconnect) would forever report the old
             // error via `__rea__health`, misleading operators about live state.
-            this.lastErrorMessage = null;
+            this.#lastErrorMessage = null;
             return result;
         }
         catch (err) {
@@ -253,7 +285,7 @@ export class DownstreamConnection {
                     // stamp the reconnect time so flap-guard can refuse rapid repeats.
                     this.reconnectAttempted = false;
                     this.lastReconnectAt = Date.now();
-                    this.lastErrorMessage = null;
+                    this.#lastErrorMessage = null;
                     this.logger?.info({
                         event: 'downstream.reconnected',
                         server_name: this.config.name,
@@ -264,7 +296,7 @@ export class DownstreamConnection {
                 catch (reconnectErr) {
                     this.health = 'unhealthy';
                     const errMsg = reconnectErr instanceof Error ? reconnectErr.message : String(reconnectErr);
-                    this.lastErrorMessage = errMsg;
+                    this.#lastErrorMessage = errMsg;
                     this.logger?.error({
                         event: 'downstream.reconnect_failed',
                         server_name: this.config.name,
@@ -275,7 +307,7 @@ export class DownstreamConnection {
                 }
             }
             this.health = 'unhealthy';
-            this.lastErrorMessage = message;
+            this.#lastErrorMessage = message;
             this.logger?.error({
                 event: 'downstream.call_failed',
                 server_name: this.config.name,