@bookedsolid/rea 0.6.1 → 0.7.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
@@ -111,7 +105,21 @@ export declare class DownstreamConnection {
     get isHealthy(): boolean;
     /** True iff the underlying MCP client is currently connected. */
     get isConnected(): boolean;
-    /** Last error observed, or null if the connection has never failed (or fully recovered). */
+    /**
+     * Last error observed, or null if the connection has never failed (or fully
+     * recovered).
+     *
+     * 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>;
     listTools(): Promise<DownstreamToolInfo[]>;

package/dist/gateway/downstream.js

@@ -38,6 +38,7 @@
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { interpolateEnv } from '../registry/interpolate.js';
+import { boundedDiagnosticString } from './meta/health.js';
 /**
  * Neutral env vars every child inherits. These are the ones shells/toolchains
  * need to function but carry no secrets in a well-configured environment.
@@ -112,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
@@ -134,9 +163,26 @@ export class DownstreamConnection {
     get isConnected() {
         return this.client !== null;
     }
-    /** Last error observed, or null if the connection has never failed (or fully recovered). */
+    /**
+     * Last error observed, or null if the connection has never failed (or fully
+     * recovered).
+     *
+     * 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() {
-        return this.lastErrorMessage;
+        const raw = this.#lastErrorMessage;
+        if (raw === null)
+            return null;
+        return boundedDiagnosticString(raw);
     }
     async connect() {
         if (this.client !== null)
@@ -159,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.
@@ -184,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);
         }
     }
@@ -216,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) {
@@ -239,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,
@@ -250,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,
@@ -261,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,

package/dist/gateway/meta/health.d.ts

@@ -77,6 +77,14 @@ export interface MetaHealthSnapshot {
         connected: number;
         healthy: number;
         total_tools: number;
+        /**
+         * BUG-011 (0.6.2) — process-lifetime count of `meta.health` audit-append
+         * failures. An operator who sees this incrementing is looking at a silent
+         * observability gap: the short-circuit response is still being served,
+         * but the audit log is losing entries. Surfaced here so the condition is
+         * detectable without parsing stderr.
+         */
+        audit_fail_count: number;
     };
 }
 export interface BuildHealthSnapshotDeps {
@@ -98,6 +106,12 @@ export interface BuildHealthSnapshotDeps {
     haltReason: string | null;
     /** Current epoch ms. Injected for determinism in tests. */
     nowMs?: number;
+    /**
+     * BUG-011 (0.6.2) — process-lifetime audit-append failure counter.
+     * Injected from `server.ts` so the snapshot reports a live value.
+     * Absent → surfaces as 0 in the snapshot.
+     */
+    auditFailCount?: number;
 }
 /**
  * Pure function that builds the snapshot from injected state. All I/O happens
@@ -105,6 +119,69 @@ export interface BuildHealthSnapshotDeps {
  * throws" a local invariant rather than a chain-wide claim.
  */
 export declare function buildHealthSnapshot(deps: BuildHealthSnapshotDeps): MetaHealthSnapshot;
+/**
+ * BUG-011 (0.6.2) — placeholder the sanitizer writes into any string whose
+ * injection classification comes back non-clean under `expose_diagnostics`.
+ * Exported so tests can assert the exact token.
+ */
+export declare const INJECTION_REDACTED_PLACEHOLDER = "<redacted: suspected injection>";
+/**
+ * BUG-011 (0.6.2) — max code-units of diagnostic text surfaced through the
+ * meta-tool wire under `expose_diagnostics: true`. Upstream MCP error
+ * messages and HALT-file contents are ADVERSARY-CONTROLLABLE (a downstream
+ * can throw `new Error(huge_string)`); without a cap, an attacker can force
+ * `__rea__health` responses into the hundreds of MB, DoS-ing the one tool
+ * designed to remain callable when everything else is broken. 4096 UTF-16
+ * code units is plenty to diagnose a real failure and cheap to keep on the
+ * wire — even in the worst-case all-surrogate-pair scenario the UTF-8 byte
+ * length stays under ~16 KiB. Named `_CHARS` because JavaScript string
+ * `.length` and `.slice` are code-unit operations, not byte operations;
+ * Codex review C-11.1 flagged the previous `_BYTES` naming as misleading.
+ * Truncation happens BEFORE redact/inject scanning so those routines
+ * always see bounded input.
+ */
+export declare const DIAGNOSTIC_STRING_MAX_CHARS = 4096;
+/**
+ * Bound a diagnostic string at `DIAGNOSTIC_STRING_MAX_CHARS` without
+ * emitting a lone high-surrogate. Exported so every site that ingests an
+ * adversary-controllable diagnostic string (`downstream.ts#lastError`,
+ * `server.ts` HALT-file read, the sanitizer itself) shares one definition
+ * of "bounded diagnostic string". Codex review N-1 (2026-04-20).
+ *
+ * Callers that want the `… [truncated]` sentinel appended should use
+ * `truncateForDiagnostics`; callers that just need a hard upper bound
+ * (audit-tap sites where a sentinel would be noise) use this directly.
+ */
+export declare function boundedDiagnosticString(s: string): string;
+/**
+ * BUG-011 (0.6.2) — sanitize a snapshot before it crosses the MCP wire.
+ *
+ * The `__rea__health` short-circuit in `server.ts` responds BEFORE the
+ * middleware chain so the tool stays callable under HALT. That bypasses the
+ * normal `redact` and `injection` middleware by design — but `last_error`
+ * and `halt_reason` are populated verbatim from upstream error messages
+ * (`err.message` / `String(err)`) and from the HALT file contents. Both can
+ * contain secrets (a downstream MCP that echoes an API key in its error
+ * path) or prompt-injection payloads (any adversarial downstream).
+ *
+ * Sanitization strategy, gated by `policy.gateway.health.expose_diagnostics`:
+ *
+ *   - `undefined` or `false` (default): STRIP. `halt_reason` → `null`;
+ *     every `downstreams[].last_error` → `null`. Consumers who want the raw
+ *     text read the audit log (`event: meta.health`) or `rea doctor`.
+ *
+ *   - `true` (explicit opt-in): REDACT. Apply `redactSecrets` (default
+ *     secret-pattern list, 100ms match budget per pattern) to the string;
+ *     then run `classifyInjection` at `Tier.Read` (the short-circuit tier
+ *     for meta-tool reads). If the classification is anything other than
+ *     `clean`, replace the entire string with
+ *     `INJECTION_REDACTED_PLACEHOLDER` — the post-redact output cannot be
+ *     trusted as human-readable text when injection markers are present.
+ *
+ * Pure — no I/O, no logging, no mutation of the input snapshot. The caller
+ * passes the pre-built snapshot; this returns a fresh object.
+ */
+export declare function sanitizeHealthSnapshot(snapshot: MetaHealthSnapshot, policy: Policy): MetaHealthSnapshot;
 /**
  * The descriptor the gateway advertises via `tools/list`. No arguments —
  * callers request a snapshot by calling with `{}`. Keeping the surface

package/dist/gateway/meta/health.js

@@ -43,6 +43,9 @@
  *    broken. Every field is best-effort; a missing value is surfaced as
  *    `null`, not as an exception.
  */
+import { Tier } from '../../policy/types.js';
+import { compileDefaultSecretPatterns, redactSecrets, REDACT_TIMEOUT_SENTINEL, } from '../middleware/redact.js';
+import { classifyInjection, compileInjectionPatterns, scanStringForInjection, } from '../middleware/injection.js';
 /** Canonical MCP tool name exposed by the gateway. */
 export const META_HEALTH_TOOL_NAME = '__rea__health';
 /** `server_name` recorded in audit entries for this meta-tool. */
@@ -88,9 +91,166 @@ export function buildHealthSnapshot(deps) {
             connected,
             healthy,
             total_tools,
+            audit_fail_count: deps.auditFailCount ?? 0,
         },
     };
 }
+/**
+ * BUG-011 (0.6.2) — placeholder the sanitizer writes into any string whose
+ * injection classification comes back non-clean under `expose_diagnostics`.
+ * Exported so tests can assert the exact token.
+ */
+export const INJECTION_REDACTED_PLACEHOLDER = '<redacted: suspected injection>';
+/**
+ * BUG-011 (0.6.2) — max code-units of diagnostic text surfaced through the
+ * meta-tool wire under `expose_diagnostics: true`. Upstream MCP error
+ * messages and HALT-file contents are ADVERSARY-CONTROLLABLE (a downstream
+ * can throw `new Error(huge_string)`); without a cap, an attacker can force
+ * `__rea__health` responses into the hundreds of MB, DoS-ing the one tool
+ * designed to remain callable when everything else is broken. 4096 UTF-16
+ * code units is plenty to diagnose a real failure and cheap to keep on the
+ * wire — even in the worst-case all-surrogate-pair scenario the UTF-8 byte
+ * length stays under ~16 KiB. Named `_CHARS` because JavaScript string
+ * `.length` and `.slice` are code-unit operations, not byte operations;
+ * Codex review C-11.1 flagged the previous `_BYTES` naming as misleading.
+ * Truncation happens BEFORE redact/inject scanning so those routines
+ * always see bounded input.
+ */
+export const DIAGNOSTIC_STRING_MAX_CHARS = 4096;
+const TRUNCATION_SUFFIX = '… [truncated]';
+/**
+ * Drop a trailing lone high-surrogate so the result is valid UTF-16 that
+ * round-trips cleanly through UTF-8 encoders. `String.prototype.slice` cuts
+ * at an arbitrary code-unit index — when that index falls between a
+ * surrogate pair, the naive result ends with U+D800–U+DBFF on its own and
+ * `Buffer.from(s, 'utf8')` silently replaces it with U+FFFD, corrupting
+ * the diagnostic. Codex review C-11.2 / N-1.
+ */
+function dropTrailingHighSurrogate(s) {
+    if (s.length === 0)
+        return s;
+    const last = s.charCodeAt(s.length - 1);
+    return last >= 0xd800 && last <= 0xdbff ? s.slice(0, -1) : s;
+}
+/**
+ * Bound a diagnostic string at `DIAGNOSTIC_STRING_MAX_CHARS` without
+ * emitting a lone high-surrogate. Exported so every site that ingests an
+ * adversary-controllable diagnostic string (`downstream.ts#lastError`,
+ * `server.ts` HALT-file read, the sanitizer itself) shares one definition
+ * of "bounded diagnostic string". Codex review N-1 (2026-04-20).
+ *
+ * Callers that want the `… [truncated]` sentinel appended should use
+ * `truncateForDiagnostics`; callers that just need a hard upper bound
+ * (audit-tap sites where a sentinel would be noise) use this directly.
+ */
+export function boundedDiagnosticString(s) {
+    if (s.length <= DIAGNOSTIC_STRING_MAX_CHARS)
+        return s;
+    return dropTrailingHighSurrogate(s.slice(0, DIAGNOSTIC_STRING_MAX_CHARS));
+}
+/**
+ * Truncate `raw` to at most `DIAGNOSTIC_STRING_MAX_CHARS` code units
+ * (including the suffix). After slicing at an arbitrary code-unit index
+ * we may be left with a lone high-surrogate (U+D800–U+DBFF) — drop it
+ * so downstream UTF-8 encoders don't silently replace it with U+FFFD.
+ */
+function truncateForDiagnostics(raw) {
+    if (raw.length <= DIAGNOSTIC_STRING_MAX_CHARS)
+        return raw;
+    const sliced = dropTrailingHighSurrogate(raw.slice(0, DIAGNOSTIC_STRING_MAX_CHARS - TRUNCATION_SUFFIX.length));
+    return sliced + TRUNCATION_SUFFIX;
+}
+/**
+ * BUG-011 (0.6.2) — sanitize a snapshot before it crosses the MCP wire.
+ *
+ * The `__rea__health` short-circuit in `server.ts` responds BEFORE the
+ * middleware chain so the tool stays callable under HALT. That bypasses the
+ * normal `redact` and `injection` middleware by design — but `last_error`
+ * and `halt_reason` are populated verbatim from upstream error messages
+ * (`err.message` / `String(err)`) and from the HALT file contents. Both can
+ * contain secrets (a downstream MCP that echoes an API key in its error
+ * path) or prompt-injection payloads (any adversarial downstream).
+ *
+ * Sanitization strategy, gated by `policy.gateway.health.expose_diagnostics`:
+ *
+ *   - `undefined` or `false` (default): STRIP. `halt_reason` → `null`;
+ *     every `downstreams[].last_error` → `null`. Consumers who want the raw
+ *     text read the audit log (`event: meta.health`) or `rea doctor`.
+ *
+ *   - `true` (explicit opt-in): REDACT. Apply `redactSecrets` (default
+ *     secret-pattern list, 100ms match budget per pattern) to the string;
+ *     then run `classifyInjection` at `Tier.Read` (the short-circuit tier
+ *     for meta-tool reads). If the classification is anything other than
+ *     `clean`, replace the entire string with
+ *     `INJECTION_REDACTED_PLACEHOLDER` — the post-redact output cannot be
+ *     trusted as human-readable text when injection markers are present.
+ *
+ * Pure — no I/O, no logging, no mutation of the input snapshot. The caller
+ * passes the pre-built snapshot; this returns a fresh object.
+ */
+export function sanitizeHealthSnapshot(snapshot, policy) {
+    const expose = policy.gateway?.health?.expose_diagnostics === true;
+    if (!expose) {
+        return {
+            ...snapshot,
+            gateway: { ...snapshot.gateway, halt_reason: null },
+            downstreams: snapshot.downstreams.map((d) => ({ ...d, last_error: null })),
+        };
+    }
+    // expose_diagnostics === true: redact + injection-scan every diagnostic
+    // string. Compile patterns per-call — this path fires only when the LLM
+    // (or an operator) invokes `__rea__health`, which is rare enough that the
+    // allocation cost is irrelevant and the bounded freshness is a net win.
+    const secretPatterns = compileDefaultSecretPatterns({
+        timeoutMs: 100,
+    });
+    const injectionPatterns = compileInjectionPatterns(100);
+    const clean = (raw) => {
+        if (raw === null)
+            return null;
+        // Truncate BEFORE scanning: an adversarial downstream can produce
+        // arbitrarily long error strings, and the sanitizer must not spend
+        // O(n) per-pattern time on attacker-chosen n.
+        const bounded = truncateForDiagnostics(raw);
+        // Codex review C-11.3: `redactSecrets` returns `timedOut: true` and
+        // replaces the full input with REDACT_TIMEOUT_SENTINEL when a pattern's
+        // match budget is exceeded. Treat that exactly like a non-clean
+        // injection verdict — the output cannot be trusted as human-readable
+        // text and must not distinguish timeout-hit from pattern-hit on the
+        // wire.
+        //
+        // N-2 defense-in-depth: also collapse when the post-redact output
+        // HAPPENS to equal the sentinel (e.g., a downstream echoes the string
+        // in its error text). The sentinel is a gateway-internal token; its
+        // presence on the meta-tool wire is always a failure signal, not a
+        // diagnostic. Collapsing to the injection placeholder keeps the
+        // on-wire output indistinguishable from a real timeout.
+        const { output, timedOut } = redactSecrets(bounded, secretPatterns);
+        if (timedOut || output === REDACT_TIMEOUT_SENTINEL) {
+            return INJECTION_REDACTED_PLACEHOLDER;
+        }
+        const scan = {
+            literalMatches: new Set(),
+            base64DecodedMatches: new Set(),
+        };
+        scanStringForInjection(output, scan, injectionPatterns);
+        // Tier.Read: any literal match AT ALL classifies to `likely_injection`
+        // under the decision table (rule 4). That's the right bar here — a
+        // meta-tool response is a read-tier surface by construction.
+        const verdict = classifyInjection(scan, Tier.Read);
+        if (verdict.verdict !== 'clean')
+            return INJECTION_REDACTED_PLACEHOLDER;
+        return output;
+    };
+    return {
+        ...snapshot,
+        gateway: { ...snapshot.gateway, halt_reason: clean(snapshot.gateway.halt_reason) },
+        downstreams: snapshot.downstreams.map((d) => ({
+            ...d,
+            last_error: clean(d.last_error),
+        })),
+    };
+}
 /**
  * The descriptor the gateway advertises via `tools/list`. No arguments —
  * callers request a snapshot by calling with `{}`. Keeping the surface