@bookedsolid/rea 0.6.0 → 0.6.2

package/dist/gateway/downstream.d.ts

@@ -111,7 +111,18 @@ 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): 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.
+     */
     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.
@@ -134,9 +135,22 @@ 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): 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.
+     */
     get lastError() {
-        return this.lastErrorMessage;
+        if (this.lastErrorMessage === null)
+            return null;
+        return boundedDiagnosticString(this.lastErrorMessage);
     }
     async connect() {
         if (this.client !== null)

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

package/dist/gateway/server.js

@@ -35,7 +35,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprot
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { DownstreamPool, splitPrefixed } from './downstream-pool.js';
-import { META_HEALTH_TOOL_NAME, META_SERVER_NAME, META_TOOL_NAME, buildHealthSnapshot, metaHealthToolDescriptor, } from './meta/health.js';
+import { boundedDiagnosticString, META_HEALTH_TOOL_NAME, META_SERVER_NAME, META_TOOL_NAME, buildHealthSnapshot, metaHealthToolDescriptor, sanitizeHealthSnapshot, } from './meta/health.js';
 import { appendAuditRecord } from '../audit/append.js';
 import { getPkgVersion } from '../cli/utils.js';
 import { createAuditMiddleware } from './middleware/audit.js';
@@ -127,6 +127,11 @@ export function createGateway(opts) {
     const pool = new DownstreamPool(registry, logger);
     const gatewayVersion = getPkgVersion();
     const startedAtMs = Date.now();
+    // BUG-011 (0.6.2) — process-lifetime counter of failed audit appends from
+    // the `__rea__health` short-circuit. Exposed on the health snapshot as
+    // `summary.audit_fail_count` so operators can detect the silent-audit-gap
+    // condition without parsing stderr.
+    let healthAuditFailCount = 0;
     const server = new Server({ name: 'rea', version: gatewayVersion }, { capabilities: { tools: {} } });
     // Build the circuit breaker with observability hooks wired in — state
     // transitions log a structured record AND update the Prometheus gauge.
@@ -161,7 +166,13 @@ export function createGateway(opts) {
         try {
             const contents = await fs.readFile(path.join(baseDir, '.rea', 'HALT'), 'utf8');
             const trimmed = contents.trim();
-            return { halt: true, reason: trimmed.length > 0 ? trimmed : null };
+            // Hard-cap the raw read at the diagnostic string budget before it
+            // enters the snapshot. An oversize HALT file (operator accident or
+            // local attacker) must not cause an O(size) allocation on every
+            // `__rea__health` call. `sanitizeHealthSnapshot` also truncates,
+            // but capping at ingestion keeps the snapshot itself bounded.
+            const bounded = boundedDiagnosticString(trimmed);
+            return { halt: true, reason: bounded.length > 0 ? bounded : null };
         }
         catch {
             return { halt: false, reason: null };
@@ -220,14 +231,23 @@ export function createGateway(opts) {
         if (prefixed === META_HEALTH_TOOL_NAME) {
             const startMs = Date.now();
             const haltState = await readHalt();
-            const snapshot = buildHealthSnapshot({
+            // Internal snapshot carries the raw diagnostic strings — used by the
+            // audit record below so operators have the full text in the log even
+            // when the MCP response has them stripped/redacted.
+            const internalSnapshot = buildHealthSnapshot({
                 gatewayVersion,
                 startedAtMs,
                 policy,
                 downstreams: pool.healthSnapshot(),
                 halt: haltState.halt,
                 haltReason: haltState.reason,
+                auditFailCount: healthAuditFailCount,
             });
+            // BUG-011 (0.6.2) — sanitize BEFORE serializing to the wire. Strips
+            // `halt_reason` + per-downstream `last_error` by default; when
+            // `gateway.health.expose_diagnostics: true` applies redactSecrets +
+            // injection-scan and replaces any non-clean string with the sentinel.
+            const wireSnapshot = sanitizeHealthSnapshot(internalSnapshot, policy);
             // Best-effort audit append. Failures here must never prevent the
             // caller from getting the health response — that would defeat the
             // whole point of a "works when everything else is broken" tool.
@@ -241,24 +261,45 @@ export function createGateway(opts) {
                     session_id: currentSessionId(),
                     duration_ms: Date.now() - startMs,
                     metadata: {
-                        halt: snapshot.gateway.halt,
-                        downstreams_registered: snapshot.summary.registered,
-                        downstreams_healthy: snapshot.summary.healthy,
+                        halt: internalSnapshot.gateway.halt,
+                        // BUG-011 (0.6.2) — N-3: the audit log is the authoritative
+                        // trusted-operator sink for full diagnostic text. Strings are
+                        // already bounded at ingestion (halt-file read + downstream
+                        // lastError getter) via `boundedDiagnosticString`, and the
+                        // audit file is on local disk with hash-chained append-only
+                        // semantics — not LLM-reachable. Log the pre-sanitize strings
+                        // here so the `rea doctor` / audit-tail path preserves the
+                        // text the MCP wire strips under the default policy.
+                        halt_reason: internalSnapshot.gateway.halt_reason,
+                        downstreams_registered: internalSnapshot.summary.registered,
+                        downstreams_healthy: internalSnapshot.summary.healthy,
+                        downstream_errors: internalSnapshot.downstreams
+                            .filter((d) => d.last_error !== null)
+                            .map((d) => ({ name: d.name, last_error: d.last_error })),
                     },
                 });
             }
             catch (err) {
-                logger.warn({
+                // BUG-011 (0.6.2) — elevated from `warn` to `error`. A dropped
+                // meta.health audit entry is an observability gap: the response
+                // still goes out but the record of it is missing, which defeats
+                // the forensic value of the hash chain for that call. Also bump a
+                // process-lifetime counter surfaced on the next snapshot's
+                // `summary.audit_fail_count` so operators can detect the condition
+                // without parsing stderr.
+                healthAuditFailCount += 1;
+                logger.error({
                     event: 'meta.health.audit_failed',
                     message: 'failed to append audit record for __rea__health; serving response anyway',
                     error: err instanceof Error ? err.message : String(err),
+                    audit_fail_count: healthAuditFailCount,
                 });
             }
             return {
                 content: [
                     {
                         type: 'text',
-                        text: JSON.stringify(snapshot, null, 2),
+                        text: JSON.stringify(wireSnapshot, null, 2),
                     },
                 ],
             };

package/dist/policy/loader.d.ts

@@ -95,6 +95,23 @@ declare const PolicySchema: z.ZodObject<{
             max_age_days?: number | undefined;
         } | undefined;
     }>>;
+    gateway: z.ZodOptional<z.ZodObject<{
+        health: z.ZodOptional<z.ZodObject<{
+            expose_diagnostics: z.ZodOptional<z.ZodBoolean>;
+        }, "strict", z.ZodTypeAny, {
+            expose_diagnostics?: boolean | undefined;
+        }, {
+            expose_diagnostics?: boolean | undefined;
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        health?: {
+            expose_diagnostics?: boolean | undefined;
+        } | undefined;
+    }, {
+        health?: {
+            expose_diagnostics?: boolean | undefined;
+        } | undefined;
+    }>>;
 }, "strict", z.ZodTypeAny, {
     version: string;
     profile: string;
@@ -133,6 +150,11 @@ declare const PolicySchema: z.ZodObject<{
             max_age_days?: number | undefined;
         } | undefined;
     } | undefined;
+    gateway?: {
+        health?: {
+            expose_diagnostics?: boolean | undefined;
+        } | undefined;
+    } | undefined;
 }, {
     version: string;
     profile: string;
@@ -171,6 +193,11 @@ declare const PolicySchema: z.ZodObject<{
             max_age_days?: number | undefined;
         } | undefined;
     } | undefined;
+    gateway?: {
+        health?: {
+            expose_diagnostics?: boolean | undefined;
+        } | undefined;
+    } | undefined;
 }>;
 /**
  * Async policy loader with TTL cache and mtime-based invalidation.

package/dist/policy/loader.js

@@ -93,6 +93,20 @@ const InjectionPolicySchema = z
     suspicious_blocks_writes: z.boolean().optional(),
 })
     .strict();
+/**
+ * BUG-011 (0.6.2) — gateway-level policy. Currently only the `health`
+ * sub-block is defined; kept strict so typos (`gateway.heath`) fail loudly.
+ */
+const GatewayHealthPolicySchema = z
+    .object({
+    expose_diagnostics: z.boolean().optional(),
+})
+    .strict();
+const GatewayPolicySchema = z
+    .object({
+    health: GatewayHealthPolicySchema.optional(),
+})
+    .strict();
 const PolicySchema = z
     .object({
     version: z.string(),
@@ -111,6 +125,7 @@ const PolicySchema = z
     review: ReviewPolicySchema.optional(),
     redact: RedactPolicySchema.optional(),
     audit: AuditPolicySchema.optional(),
+    gateway: GatewayPolicySchema.optional(),
 })
     .strict();
 const DEFAULT_CACHE_TTL_MS = 30_000;

package/dist/policy/types.d.ts

@@ -124,6 +124,33 @@ export interface AuditPolicy {
 export interface InjectionPolicy {
     suspicious_blocks_writes?: boolean;
 }
+/**
+ * BUG-011 (0.6.2) — gateway-level policy knobs.
+ *
+ * `health.expose_diagnostics` governs whether `__rea__health` emits
+ * `halt_reason` and per-downstream `last_error` strings in its MCP response
+ * (vs. dropping them to `null`). The short-circuit responds BEFORE the
+ * middleware chain — so it bypasses `redact` and `injection` middleware by
+ * design (the tool must stay callable under HALT). That means downstream
+ * error strings, which are populated verbatim from `err.message`, can carry
+ * secrets or injection payloads all the way to the caller unless we
+ * sanitize in the short-circuit path itself.
+ *
+ * Default `false` (fields emitted as `null`). The Helix team's explicit
+ * preference was "strip, don't redact" — a smaller trust ask than trusting
+ * our secret/injection pattern coverage. Operators who accept that trade-off
+ * (e.g. single-tenant dev boxes) can flip `expose_diagnostics: true`, at
+ * which point the short-circuit applies the same `redactSecrets` +
+ * `classifyInjection` pass the middleware chain would. The full untouched
+ * values always flow into the audit log regardless — diagnostics remain
+ * available via `rea doctor`, just not over the MCP wire.
+ */
+export interface GatewayHealthPolicy {
+    expose_diagnostics?: boolean;
+}
+export interface GatewayPolicy {
+    health?: GatewayHealthPolicy;
+}
 export interface Policy {
     version: string;
     profile: string;
@@ -141,4 +168,5 @@ export interface Policy {
     review?: ReviewPolicy;
     redact?: RedactPolicy;
     audit?: AuditPolicy;
+    gateway?: GatewayPolicy;
 }

package/hooks/commit-review-gate.sh

@@ -15,6 +15,62 @@ set -uo pipefail
 # ── 1. Read ALL stdin immediately ─────────────────────────────────────────────
 INPUT=$(cat)
 
+# ── 1a. Cross-repo guard (must come FIRST — before any rea-scoped check) ──────
+# BUG-012 (0.6.2) — mirror of push-review-gate.sh §1a. Script-location
+# anchor (not CLAUDE_PROJECT_DIR) owns the trust decision. See the
+# push-gate comment and THREAT_MODEL.md § CLAUDE_PROJECT_DIR for the full
+# rationale. In short: CLAUDE_PROJECT_DIR is caller-controlled, cannot be
+# trusted for authorization, and the hook's own filesystem location is the
+# only forge-resistant anchor available to a bash script.
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]:-$0}")" && pwd -P 2>/dev/null)"
+# Walk up from SCRIPT_DIR looking for `.rea/policy.yaml`. Matches every
+# reasonable install topology (see push-review-gate.sh §1a for the full
+# rationale). A hard-coded `../..` breaks the source-path invocation
+# (`bash hooks/commit-review-gate.sh`) and silently reads .rea state from
+# the WRONG directory.
+REA_ROOT=""
+_anchor_candidate="$SCRIPT_DIR"
+for _ in 1 2 3 4; do
+  _anchor_candidate="$(cd -- "$_anchor_candidate/.." && pwd -P 2>/dev/null || true)"
+  if [[ -n "$_anchor_candidate" && -f "$_anchor_candidate/.rea/policy.yaml" ]]; then
+    REA_ROOT="$_anchor_candidate"
+    break
+  fi
+done
+if [[ -z "$REA_ROOT" ]]; then
+  printf 'rea-hook: no .rea/policy.yaml found within 4 parents of %s\n' \
+    "$SCRIPT_DIR" >&2
+  printf 'rea-hook:   is this an installed rea hook, or is `.rea/policy.yaml`\n' >&2
+  printf 'rea-hook:   nested more than 4 directories above the hook script?\n' >&2
+  exit 2
+fi
+unset _anchor_candidate
+
+if [[ -n "${CLAUDE_PROJECT_DIR:-}" ]]; then
+  CPD_REAL=$(cd -- "${CLAUDE_PROJECT_DIR}" 2>/dev/null && pwd -P 2>/dev/null || true)
+  if [[ -n "$CPD_REAL" && "$CPD_REAL" != "$REA_ROOT" ]]; then
+    printf 'rea-hook: ignoring CLAUDE_PROJECT_DIR=%s — anchoring to script location %s\n' \
+      "$CLAUDE_PROJECT_DIR" "$REA_ROOT" >&2
+  fi
+fi
+
+CWD_REAL=$(pwd -P 2>/dev/null || pwd)
+CWD_COMMON=$(git -C "$CWD_REAL" rev-parse --path-format=absolute --git-common-dir 2>/dev/null || true)
+REA_COMMON=$(git -C "$REA_ROOT" rev-parse --path-format=absolute --git-common-dir 2>/dev/null || true)
+if [[ -n "$CWD_COMMON" && -n "$REA_COMMON" ]]; then
+  CWD_COMMON_REAL=$(cd "$CWD_COMMON" 2>/dev/null && pwd -P 2>/dev/null || echo "$CWD_COMMON")
+  REA_COMMON_REAL=$(cd "$REA_COMMON" 2>/dev/null && pwd -P 2>/dev/null || echo "$REA_COMMON")
+  if [[ "$CWD_COMMON_REAL" != "$REA_COMMON_REAL" ]]; then
+    exit 0
+  fi
+elif [[ -z "$CWD_COMMON" && -z "$REA_COMMON" ]]; then
+  case "$CWD_REAL/" in
+    "$REA_ROOT"/*|"$REA_ROOT"/) : ;;  # inside rea — run the gate
+    *) exit 0 ;;                       # outside rea — not our gate
+  esac
+fi
+# Mixed state or probe error → fail CLOSED: run the gate.
+
 # ── 2. Dependency check ──────────────────────────────────────────────────────
 if ! command -v jq >/dev/null 2>&1; then
   printf 'REA ERROR: jq is required but not installed.\n' >&2
@@ -23,7 +79,6 @@ if ! command -v jq >/dev/null 2>&1; then
 fi
 
 # ── 3. HALT check ────────────────────────────────────────────────────────────
-REA_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
 HALT_FILE="${REA_ROOT}/.rea/HALT"
 if [ -f "$HALT_FILE" ]; then
   printf 'REA HALT: %s\nAll agent operations suspended. Run: rea unfreeze\n' \

package/hooks/push-review-gate.sh

@@ -37,6 +37,110 @@ set -uo pipefail
 # ── 1. Read ALL stdin immediately ─────────────────────────────────────────────
 INPUT=$(cat)
 
+# ── 1a. Cross-repo guard (must come FIRST — before any rea-scoped check) ──────
+# BUG-012 (0.6.2) — anchor the install to the SCRIPT'S OWN LOCATION on disk.
+# The hook knows where it lives: installed at `<root>/.claude/hooks/<name>.sh`,
+# so `<root>` is two levels up from `BASH_SOURCE[0]`. No caller-controlled
+# env var participates in the trust decision.
+#
+# WHY THIS CHANGED in 0.6.2
+# The 0.6.1 guard read `REA_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"` before the
+# jq/HALT checks. That made `CLAUDE_PROJECT_DIR` a trust boundary: any process
+# that could set it to a foreign path bypassed HALT and every other rea
+# gate. CLAUDE_PROJECT_DIR is documentation/UX — it tells the wrapper which
+# project directory the user opened. It is NOT authentication. Authorization
+# must come from something the caller cannot forge, hence the script-path
+# anchor. See THREAT_MODEL.md § CLAUDE_PROJECT_DIR.
+#
+# BEHAVIOR UNDER EACH INSTALL TOPOLOGY
+#   Consumer install:  <consumer>/.claude/hooks/push-review-gate.sh
+#                      → REA_ROOT = <consumer>
+#                      → Guard runs against <consumer>/.rea/policy.yaml.
+#   rea dogfood:       /…/rea/.claude/hooks/push-review-gate.sh
+#                      → REA_ROOT = /…/rea (this repo itself)
+#                      → Guard runs against rea's own policy.yaml.
+#
+# CLAUDE_PROJECT_DIR, if set, is still TREATED AS ADVISORY: if it names a
+# different path, we emit a one-line stderr note and continue with the
+# script-derived REA_ROOT. We never short-circuit based on comparing the
+# env var against the script location — that would re-open the bypass.
+#
+# Repo-identity comparison via shared `--git-common-dir`, NOT path-prefix or
+# `--show-toplevel`. A linked worktree created by `git worktree add` has a
+# different toplevel but the SAME repository (shared object DB / refs /
+# history). Any worktree of rea IS rea and must run the gate.
+# `--path-format=absolute` (Git ≥ 2.31, March 2021) normalizes the common
+# dir so the same repo's common-dir is equal regardless of which worktree
+# asked. Engines pin Node ≥20 which ships with a recent-enough Git for dev.
+#
+# BUG-012 fail-closed: when ONE side is a git checkout and the other is not
+# (or the `--git-common-dir` probe errored), we run the gate (treat as
+# same-repo). Fail open on probe failure is what 0.6.1 did and it meant a
+# transient git quirk inside a legitimate rea worktree could bypass HALT.
+# The path-prefix fallback is ONLY used when BOTH sides are non-git — the
+# documented 0.5.1 non-git escape-hatch scenario (`data/`, `figgy`).
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]:-$0}")" && pwd -P 2>/dev/null)"
+# Walk up from SCRIPT_DIR looking for `.rea/policy.yaml`. This resolves
+# correctly for every reasonable topology — installed copy at
+# `<root>/.claude/hooks/<name>.sh` (2 up), source-of-truth copy at
+# `<root>/hooks/<name>.sh` (1 up, used when rea dogfoods itself or a
+# developer runs `bash hooks/push-review-gate.sh` to smoke-test), and any
+# future `hooks/_lib/` nesting. A hard-coded `../..` breaks the source-path
+# invocation and silently reads .rea state from the WRONG directory.
+# Cap at 4 levels so a stray hook dropped in the wrong spot fails fast
+# instead of walking to the filesystem root.
+REA_ROOT=""
+_anchor_candidate="$SCRIPT_DIR"
+for _ in 1 2 3 4; do
+  _anchor_candidate="$(cd -- "$_anchor_candidate/.." && pwd -P 2>/dev/null || true)"
+  if [[ -n "$_anchor_candidate" && -f "$_anchor_candidate/.rea/policy.yaml" ]]; then
+    REA_ROOT="$_anchor_candidate"
+    break
+  fi
+done
+if [[ -z "$REA_ROOT" ]]; then
+  printf 'rea-hook: no .rea/policy.yaml found within 4 parents of %s\n' \
+    "$SCRIPT_DIR" >&2
+  printf 'rea-hook:   is this an installed rea hook, or is `.rea/policy.yaml`\n' >&2
+  printf 'rea-hook:   nested more than 4 directories above the hook script?\n' >&2
+  exit 2
+fi
+unset _anchor_candidate
+
+# Advisory-only: warn if the caller set CLAUDE_PROJECT_DIR to a path that
+# does not match the script anchor. Never let the env var override the
+# decision.
+if [[ -n "${CLAUDE_PROJECT_DIR:-}" ]]; then
+  CPD_REAL=$(cd -- "${CLAUDE_PROJECT_DIR}" 2>/dev/null && pwd -P 2>/dev/null || true)
+  if [[ -n "$CPD_REAL" && "$CPD_REAL" != "$REA_ROOT" ]]; then
+    printf 'rea-hook: ignoring CLAUDE_PROJECT_DIR=%s — anchoring to script location %s\n' \
+      "$CLAUDE_PROJECT_DIR" "$REA_ROOT" >&2
+  fi
+fi
+
+CWD_REAL=$(pwd -P 2>/dev/null || pwd)
+CWD_COMMON=$(git -C "$CWD_REAL" rev-parse --path-format=absolute --git-common-dir 2>/dev/null || true)
+REA_COMMON=$(git -C "$REA_ROOT" rev-parse --path-format=absolute --git-common-dir 2>/dev/null || true)
+if [[ -n "$CWD_COMMON" && -n "$REA_COMMON" ]]; then
+  # Both sides are git checkouts. Realpath'd common-dirs match IFF they
+  # point at the same underlying repository (main or linked worktree).
+  CWD_COMMON_REAL=$(cd "$CWD_COMMON" 2>/dev/null && pwd -P 2>/dev/null || echo "$CWD_COMMON")
+  REA_COMMON_REAL=$(cd "$REA_COMMON" 2>/dev/null && pwd -P 2>/dev/null || echo "$REA_COMMON")
+  if [[ "$CWD_COMMON_REAL" != "$REA_COMMON_REAL" ]]; then
+    exit 0
+  fi
+elif [[ -z "$CWD_COMMON" && -z "$REA_COMMON" ]]; then
+  # Both sides non-git: legitimate 0.5.1 non-git escape-hatch. Fall back to
+  # a literal path-prefix match. Quoted expansions prevent glob expansion.
+  case "$CWD_REAL/" in
+    "$REA_ROOT"/*|"$REA_ROOT"/) : ;;  # inside rea — run the gate
+    *) exit 0 ;;                       # outside rea — not our gate
+  esac
+fi
+# Mixed state (one side git, other not) or either probe failed → fail
+# CLOSED: run the gate. A transient `--git-common-dir` probe failure in a
+# legitimate rea worktree must not silently bypass HALT.
+
 # ── 2. Dependency check ──────────────────────────────────────────────────────
 if ! command -v jq >/dev/null 2>&1; then
   printf 'REA ERROR: jq is required but not installed.\n' >&2
@@ -45,7 +149,6 @@ if ! command -v jq >/dev/null 2>&1; then
 fi
 
 # ── 3. HALT check ────────────────────────────────────────────────────────────
-REA_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
 HALT_FILE="${REA_ROOT}/.rea/HALT"
 if [ -f "$HALT_FILE" ]; then
   printf 'REA HALT: %s\nAll agent operations suspended. Run: rea unfreeze\n' \

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bookedsolid/rea",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "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/scripts/tarball-smoke.sh

@@ -181,6 +181,121 @@ echo "[smoke]   → $AGENT_COUNT agents, $HOOK_COUNT hooks, $COMMAND_COUNT comma
 echo "[smoke] rea doctor"
 ./node_modules/.bin/rea doctor
 
+# ---------------------------------------------------------------------------
+# BUG-013 — security-claim content gate.
+#
+# If any changeset carries the `[security]` marker, the tarball MUST ship
+# compiled evidence of the claimed fix. The rule:
+#
+#   1. Find every `.changeset/*.md` in the source tree that contains `[security]`
+#   2. Assert AT LEAST ONE `*sanitize*.test.ts` or `*security*.test.ts` exists
+#      under `src/` (a "security-claim" changeset without a matching regression
+#      test is a marketing bullet, not a shipped fix)
+#   3. For every such test file, extract the symbols it imports from the
+#      module under test (named imports from relative paths) and assert each
+#      symbol appears somewhere under `dist/`. Tests are excluded from the
+#      npm build (tsconfig.build.json), so a stale dist/ from a prior release
+#      would not contain the new symbol that the test exercises — this catches
+#      the 0.6.0→0.6.1 byte-identical dist/ regression that motivated BUG-013.
+#
+# Bypass-resistant: the gate keys on the changeset marker, not a flag the
+# release author chooses. Narrow: no-op when no `[security]` changesets exist.
+#
+# Known limits (called out honestly rather than papered over):
+#   - The gate asserts the imported SYMBOLS are present in dist/. It does
+#     NOT assert those symbols are NEW vs. the previous published release.
+#     A test that imports only pre-existing symbols would satisfy the gate
+#     against a stale dist/. The two defense-in-depth layers that close
+#     this gap — `Rebuild dist/ from HEAD before publish` and
+#     `Verify published tarball dist/ matches CI-built dist/` — live in
+#     `.github/workflows/release.yml` (see `.rea/drafts-0.6.2/` for the
+#     pending hand-apply patch). The content gate here catches the
+#     0.6.0→0.6.1 class of regression in the common case; the workflow
+#     hash check catches the adversarial case.
+#   - The gate does not tie a specific changeset to a specific test file.
+#     If a security changeset names BUG-X but the shipping security test
+#     covers BUG-Y, the gate passes. Mitigation is the same: the workflow
+#     hash verification plus human review of the changeset at PR time.
+# ---------------------------------------------------------------------------
+SEC_CHANGESETS="$(grep -l '\[security\]' "$REPO_ROOT"/.changeset/*.md 2>/dev/null || true)"
+if [ -n "$SEC_CHANGESETS" ]; then
+  echo "[smoke] security-claim gate: $(printf '%s\n' "$SEC_CHANGESETS" | wc -l | awk '{print $1}') changeset(s) tagged [security]"
+
+  SEC_SRC_TESTS="$(cd "$REPO_ROOT" && find src -type f \( -name '*sanitize*.test.ts' -o -name '*security*.test.ts' \) 2>/dev/null | sort)"
+  if [ -z "$SEC_SRC_TESTS" ]; then
+    echo "[smoke] FAIL — [security] changeset present but no *sanitize*.test.ts or *security*.test.ts under src/" >&2
+    echo "[smoke]        a security-claim changeset with no matching regression test is a trust violation" >&2
+    exit 2
+  fi
+
+  # For each security test, collect the named imports pulled from relative
+  # paths — those are the symbols under test and must be compiled into dist/.
+  # Example line we want to match:
+  #   import { sanitizeHealthSnapshot, INJECTION_REDACTED_PLACEHOLDER } from './health';
+  # We ignore imports from bare package names ('vitest', 'node:fs', etc.).
+  MISSING_SYMBOLS=""
+  SYMBOL_COUNT=0
+  while IFS= read -r src_test; do
+    [ -z "$src_test" ] && continue
+    # Collect named imports from relative-path sources using perl for a
+    # multi-line regex. Output: one symbol per line.
+    # We intentionally skip:
+    #   - `import type { ... }`      — entire clause is type-only
+    #   - `{ ..., type Foo, ... }`   — inline type-only marker on a member
+    # TypeScript erases both at compile time, so asserting them against dist/
+    # would false-positive. Also skip `as` aliases (the aliased symbol is a
+    # local rebind, not the exported one we want to grep).
+    SYMBOLS="$(perl -0777 -ne '
+      while (/import(\s+type)?\s*\{([^}]+)\}\s*from\s*[\x27"](\.[^\x27"]+)[\x27"]/sg) {
+        next if $1;  # whole clause is `import type { ... }` — skip
+        my $group = $2;
+        $group =~ s/\s+/ /g;
+        for my $sym (split /,/, $group) {
+          $sym =~ s/^\s+|\s+$//g;
+          next if $sym =~ /^type\s+/;  # inline `type Foo` — skip
+          $sym =~ s/\s+as\s+\w+$//;
+          next unless $sym =~ /^\w+$/;
+          print "$sym\n";
+        }
+      }
+    ' "$REPO_ROOT/$src_test" | sort -u)"
+
+    while IFS= read -r sym; do
+      [ -z "$sym" ] && continue
+      SYMBOL_COUNT=$((SYMBOL_COUNT + 1))
+      # grep -r across dist/ — if the symbol does not appear anywhere, the
+      # build did not include the fix the test covers.
+      if ! grep -r --include='*.js' -l -F -w "$sym" "$REPO_ROOT/dist" >/dev/null 2>&1; then
+        MISSING_SYMBOLS="$MISSING_SYMBOLS
+  $sym (imported by $src_test)"
+      fi
+    done <<< "$SYMBOLS"
+  done <<< "$SEC_SRC_TESTS"
+
+  if [ -n "$MISSING_SYMBOLS" ]; then
+    echo "[smoke] FAIL — [security] changeset present but symbols under test are MISSING from dist/:" >&2
+    echo "[smoke]        (dist/ may be stale — rebuild before publishing)" >&2
+    printf '%s\n' "$MISSING_SYMBOLS" >&2
+    exit 2
+  fi
+
+  # Codex review blocker #1 (2026-04-20) — a test file written with
+  # namespace/default/dynamic imports, or one that only imports from bare
+  # packages, produces zero symbols to check. Before this guard, the gate
+  # would pass with "0 symbols all present in dist/", re-opening the
+  # byte-identical-dist/ regression that BUG-013 was written to catch.
+  if [ "$SYMBOL_COUNT" -eq 0 ]; then
+    echo "[smoke] FAIL — [security] changeset present but no checkable symbols extracted" >&2
+    echo "[smoke]        one or more src/**/(*sanitize*|*security*).test.ts files must use" >&2
+    echo "[smoke]        the \`import { Named } from './relative'\` shape so the gate can" >&2
+    echo "[smoke]        verify the symbol under test appears in compiled dist/." >&2
+    echo "[smoke]        (namespace/default/dynamic-only imports can't be verified)" >&2
+    exit 2
+  fi
+
+  echo "[smoke]   → $(printf '%s\n' "$SEC_SRC_TESTS" | wc -l | awk '{print $1}') security regression test(s), $SYMBOL_COUNT imported symbol(s) all present in dist/"
+fi
+
 # 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"