@bookedsolid/rea 0.5.0 → 0.6.0

package/dist/audit/append.js

@@ -141,11 +141,22 @@ export async function appendAuditRecord(baseDir, input) {
         .then(async () => {
         record = await doAppend(resolvedBase, input);
     });
-    writeQueues.set(key, next.finally(() => {
+    writeQueues.set(key, next
+        .finally(() => {
         // Keep the queue lean — once this write resolves, drop the reference
         // if nothing newer is chained behind it.
         if (writeQueues.get(key) === next)
             writeQueues.delete(key);
+    })
+        // Swallow rejections on the stored promise so Node doesn't flag it as
+        // an unhandled rejection. The current caller already owns this error
+        // via the `await next` below; the NEXT caller that chains off this
+        // entry also .catch()-es it at the top of its chain. Without this
+        // terminal .catch(), a failed audit append surfaces as a spurious
+        // `unhandledRejection` event — which matters in tests that run the
+        // whole process and in long-lived servers that would log it.
+        .catch(() => {
+        /* handled by caller */
     }));
     await next;
     return record;

package/dist/cli/doctor.d.ts

@@ -19,6 +19,33 @@ export interface CheckResult {
  * Exported so tests can drive this without spinning up the full `runDoctor`.
  */
 export declare function checkFingerprintStore(baseDir: string): Promise<CheckResult>;
+/**
+ * Detect whether `baseDir` is a git repository. Returns true for the three
+ * shapes git itself accepts:
+ *
+ *   1. `.git/` is a directory (vanilla repo).
+ *   2. `.git` is a file with `gitdir: <path>` (linked worktree, submodule).
+ *      The target gitdir is resolved and must exist on disk — a stale or
+ *      orphaned gitlink (submodule whose parent moved, worktree whose main
+ *      repo was deleted) is NOT a git repo and must return false, otherwise
+ *      doctor short-circuits the non-git escape hatch and hard-fails on the
+ *      pre-push check against a `.git/hooks/` that doesn't exist (F1 from
+ *      Codex review of 0.5.1).
+ *   3. Anything else (including a plain file a user accidentally named
+ *      `.git`, or a symlink to nowhere) → false.
+ *
+ * Filesystem-shape predicate only. Deliberately does not consult `GIT_DIR`
+ * or shell out to `git rev-parse` — `rea doctor` already checks things
+ * inside `baseDir/.git/hooks/`, so the shape-on-disk is the right question
+ * for the escape hatch. A GIT_DIR-aware secondary signal is a follow-up.
+ *
+ * Security note (F3): removing `.git/` does NOT bypass governance. The
+ * governance artifact is the pre-push hook; a directory with no `.git/`
+ * has no commits to push and no pre-push event to bypass. The escape
+ * hatch is a UX predicate for knowledge repos and non-source directories,
+ * NOT a trust boundary. Do not key security decisions on the return value.
+ */
+export declare function isGitRepo(baseDir: string): boolean;
 /**
  * Translate a `CodexProbeState` into two doctor CheckResults: one for
  * responsiveness (pass/warn) and one informational line about the last

package/dist/cli/doctor.js

@@ -240,6 +240,75 @@ function checkSettingsJson(baseDir) {
         };
     }
 }
+/**
+ * Detect whether `baseDir` is a git repository. Returns true for the three
+ * shapes git itself accepts:
+ *
+ *   1. `.git/` is a directory (vanilla repo).
+ *   2. `.git` is a file with `gitdir: <path>` (linked worktree, submodule).
+ *      The target gitdir is resolved and must exist on disk — a stale or
+ *      orphaned gitlink (submodule whose parent moved, worktree whose main
+ *      repo was deleted) is NOT a git repo and must return false, otherwise
+ *      doctor short-circuits the non-git escape hatch and hard-fails on the
+ *      pre-push check against a `.git/hooks/` that doesn't exist (F1 from
+ *      Codex review of 0.5.1).
+ *   3. Anything else (including a plain file a user accidentally named
+ *      `.git`, or a symlink to nowhere) → false.
+ *
+ * Filesystem-shape predicate only. Deliberately does not consult `GIT_DIR`
+ * or shell out to `git rev-parse` — `rea doctor` already checks things
+ * inside `baseDir/.git/hooks/`, so the shape-on-disk is the right question
+ * for the escape hatch. A GIT_DIR-aware secondary signal is a follow-up.
+ *
+ * Security note (F3): removing `.git/` does NOT bypass governance. The
+ * governance artifact is the pre-push hook; a directory with no `.git/`
+ * has no commits to push and no pre-push event to bypass. The escape
+ * hatch is a UX predicate for knowledge repos and non-source directories,
+ * NOT a trust boundary. Do not key security decisions on the return value.
+ */
+export function isGitRepo(baseDir) {
+    const dotGit = path.join(baseDir, '.git');
+    let stat;
+    try {
+        // statSync follows symlinks, so a `.git` symlink to a real gitdir is
+        // treated like the real thing; a dangling symlink throws ENOENT and
+        // falls into the catch → false.
+        stat = fs.statSync(dotGit);
+    }
+    catch {
+        return false;
+    }
+    if (stat.isDirectory())
+        return true;
+    if (!stat.isFile())
+        return false;
+    // Gitlink file: `gitdir: <absolute-or-relative-path>`. Read and verify
+    // the target resolves. If the target is missing, git itself would fail
+    // in this directory, so we treat it as non-git.
+    let content;
+    try {
+        content = fs.readFileSync(dotGit, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    // `\s*$` on the old shape was inert (greedy `.+` consumed trailing spaces
+    // and `\s ⊂ .`) — the `.trim()` below did all the work. Tighten to
+    // `(\S.*?)` with an explicit trailing-space class so the captured group
+    // starts at the first non-whitespace char and stops before trailing
+    // whitespace. Still handles CRLF, leading tabs, and path-internal spaces.
+    const match = /^gitdir:\s*(\S.*?)[ \t]*\r?$/m.exec(content);
+    const rawTarget = match?.[1];
+    if (rawTarget === undefined)
+        return false;
+    const targetPath = rawTarget;
+    if (targetPath.length === 0)
+        return false;
+    const resolved = path.isAbsolute(targetPath)
+        ? targetPath
+        : path.join(baseDir, targetPath);
+    return fs.existsSync(resolved);
+}
 function checkCommitMsgHook(baseDir) {
     const hookPath = path.join(baseDir, '.git', 'hooks', 'commit-msg');
     if (!fs.existsSync(hookPath)) {
@@ -443,10 +512,23 @@ export function collectChecks(baseDir, codexProbeState, prePushState) {
         checkAgentsPresent(baseDir),
         checkHooksInstalled(baseDir),
         checkSettingsJson(baseDir),
-        checkCommitMsgHook(baseDir),
     ];
-    if (prePushState !== undefined) {
-        checks.push(checkPrePushHook(prePushState));
+    // Non-git escape hatch: when `.git/` is absent, both git-hook checks are
+    // meaningless (commit-msg + pre-push can't be invoked without git). Emit
+    // one informational line so `rea doctor` exits 0 in knowledge repos and
+    // other non-source-code directories that consume rea governance.
+    if (isGitRepo(baseDir)) {
+        checks.push(checkCommitMsgHook(baseDir));
+        if (prePushState !== undefined) {
+            checks.push(checkPrePushHook(prePushState));
+        }
+    }
+    else {
+        checks.push({
+            label: 'git hooks',
+            status: 'info',
+            detail: 'no `.git/` at baseDir — commit-msg / pre-push checks skipped (not a git repo)',
+        });
     }
     if (codexRequiredFromPolicy(baseDir)) {
         checks.push(checkCodexAgent(baseDir), checkCodexCommand(baseDir));

package/dist/gateway/downstream-pool.d.ts

@@ -14,8 +14,36 @@ export interface PrefixedTool extends DownstreamToolInfo {
     /** Full prefixed name, as exposed to the upstream client. */
     name: string;
 }
+/**
+ * Per-downstream state surfaced by the `__rea__health` meta-tool. Kept
+ * separate from the richer internal state so we only expose what a caller
+ * can actually reason about.
+ */
+export interface DownstreamHealth {
+    name: string;
+    /** Registered in the registry (always true for entries present in the pool). */
+    enabled: boolean;
+    /** Underlying MCP client currently connected. */
+    connected: boolean;
+    /** Gateway considers this downstream healthy enough to route calls to. */
+    healthy: boolean;
+    /** Last error observed, or null if the connection is clean or never errored. */
+    last_error: string | null;
+    /**
+     * Number of tools advertised by the downstream on the most recent
+     * successful `tools/list`, or null when never listed / listing failed.
+     */
+    tools_count: number | null;
+}
 export declare class DownstreamPool {
     private readonly connections;
+    /**
+     * Cached tool counts from the most recent successful `listAllTools` cycle,
+     * keyed by server name. Surfaced via `healthSnapshot()` so the meta-tool
+     * can report per-server counts even when the current listing pass fails
+     * or is skipped. Stale but truthful > absent.
+     */
+    private readonly lastToolsCount;
     constructor(registry: Registry, logger?: Logger);
     get size(): number;
     connectAll(): Promise<void>;
@@ -25,6 +53,12 @@ export declare class DownstreamPool {
      * will see a smaller catalog rather than a crash.
      */
     listAllTools(): Promise<PrefixedTool[]>;
+    /**
+     * Snapshot per-server connection state for the `__rea__health` meta-tool.
+     * Pure / non-blocking — no MCP I/O — so it can be called while HALT is
+     * active or while other tool calls are in-flight.
+     */
+    healthSnapshot(): DownstreamHealth[];
     /**
      * Split a prefixed tool name and dispatch. Returns the raw result from the
      * downstream (the gateway response handler shapes it for the upstream reply).

package/dist/gateway/downstream-pool.js

@@ -8,6 +8,13 @@
 import { DownstreamConnection } from './downstream.js';
 export class DownstreamPool {
     connections = new Map();
+    /**
+     * Cached tool counts from the most recent successful `listAllTools` cycle,
+     * keyed by server name. Surfaced via `healthSnapshot()` so the meta-tool
+     * can report per-server counts even when the current listing pass fails
+     * or is skipped. Stale but truthful > absent.
+     */
+    lastToolsCount = new Map();
     constructor(registry, logger) {
         for (const server of registry.servers) {
             if (!server.enabled)
@@ -45,6 +52,7 @@ export class DownstreamPool {
                 continue;
             try {
                 const tools = await conn.listTools();
+                this.lastToolsCount.set(server, tools.length);
                 for (const t of tools) {
                     const prefixed = {
                         ...t,
@@ -60,6 +68,35 @@ export class DownstreamPool {
         }
         return out;
     }
+    /**
+     * Snapshot per-server connection state for the `__rea__health` meta-tool.
+     * Pure / non-blocking — no MCP I/O — so it can be called while HALT is
+     * active or while other tool calls are in-flight.
+     */
+    healthSnapshot() {
+        const out = [];
+        for (const [name, conn] of this.connections) {
+            const cached = this.lastToolsCount.get(name);
+            const connected = conn.isConnected;
+            const healthy = conn.isHealthy;
+            // Only surface the cached tool count when the connection is BOTH
+            // connected AND healthy right now. Codex F1 caught that a dead
+            // downstream was showing its last-successful count alongside
+            // `healthy: false`, which is a worse-than-null diagnostic — operators
+            // would read "5 tools reachable" from a server that is reachable
+            // through exactly zero tools.
+            const tools_count = connected && healthy && typeof cached === 'number' ? cached : null;
+            out.push({
+                name,
+                enabled: true,
+                connected,
+                healthy,
+                last_error: conn.lastError,
+                tools_count,
+            });
+        }
+        return out;
+    }
     /**
      * Split a prefixed tool name and dispatch. Returns the raw result from the
      * downstream (the gateway response handler shapes it for the upstream reply).

package/dist/gateway/downstream.d.ts

@@ -93,6 +93,13 @@ 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
@@ -102,6 +109,10 @@ export declare class DownstreamConnection {
     logger?: Logger | undefined);
     get name(): string;
     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). */
+    get lastError(): string | null;
     connect(): Promise<void>;
     listTools(): Promise<DownstreamToolInfo[]>;
     /**

package/dist/gateway/downstream.js

@@ -107,6 +107,13 @@ export class DownstreamConnection {
     /** Epoch ms of the last successful reconnect. Used by the flapping guard. */
     lastReconnectAt = 0;
     health = 'healthy';
+    /**
+     * 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.
+     */
+    lastErrorMessage = null;
     constructor(config, 
     /**
      * Optional structured logger (G5). When omitted, connection lifecycle
@@ -123,6 +130,14 @@ export class DownstreamConnection {
     get isHealthy() {
         return this.health !== 'unhealthy';
     }
+    /** True iff the underlying MCP client is currently connected. */
+    get isConnected() {
+        return this.client !== null;
+    }
+    /** Last error observed, or null if the connection has never failed (or fully recovered). */
+    get lastError() {
+        return this.lastErrorMessage;
+    }
     async connect() {
         if (this.client !== null)
             return;
@@ -143,10 +158,13 @@ export class DownstreamConnection {
         }
         catch (err) {
             this.health = 'unhealthy';
-            throw new Error(`failed to resolve env for downstream "${this.config.name}": ${err instanceof Error ? err.message : err}`);
+            const msg = `failed to resolve env for downstream "${this.config.name}": ${err instanceof Error ? err.message : err}`;
+            this.lastErrorMessage = msg;
+            throw new Error(msg);
         }
         if (built.missing.length > 0) {
             this.health = 'unhealthy';
+            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.
@@ -166,10 +184,13 @@ export class DownstreamConnection {
             await client.connect(transport);
             this.client = client;
             this.health = 'healthy';
+            this.lastErrorMessage = null;
         }
         catch (err) {
             this.health = 'unhealthy';
-            throw new Error(`failed to connect to downstream "${this.config.name}" (${this.config.command}): ${err instanceof Error ? err.message : err}`);
+            const msg = `failed to connect to downstream "${this.config.name}" (${this.config.command}): ${err instanceof Error ? err.message : err}`;
+            this.lastErrorMessage = msg;
+            throw new Error(msg);
         }
     }
     async listTools() {
@@ -190,7 +211,13 @@ export class DownstreamConnection {
             await this.connect();
         }
         try {
-            return await this.client.callTool({ name: toolName, arguments: args });
+            const result = await this.client.callTool({ name: toolName, arguments: args });
+            // Clear any lingering error from a previous transient failure. Without
+            // 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;
+            return result;
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
@@ -212,6 +239,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.logger?.info({
                         event: 'downstream.reconnected',
                         server_name: this.config.name,
@@ -221,16 +249,19 @@ export class DownstreamConnection {
                 }
                 catch (reconnectErr) {
                     this.health = 'unhealthy';
+                    const errMsg = reconnectErr instanceof Error ? reconnectErr.message : String(reconnectErr);
+                    this.lastErrorMessage = errMsg;
                     this.logger?.error({
                         event: 'downstream.reconnect_failed',
                         server_name: this.config.name,
                         message: `downstream "${this.config.name}" unhealthy after one reconnect`,
-                        error: reconnectErr instanceof Error ? reconnectErr.message : String(reconnectErr),
+                        error: errMsg,
                     });
-                    throw new Error(`downstream "${this.config.name}" unhealthy after one reconnect: ${reconnectErr instanceof Error ? reconnectErr.message : reconnectErr}`);
+                    throw new Error(`downstream "${this.config.name}" unhealthy after one reconnect: ${errMsg}`);
                 }
             }
             this.health = 'unhealthy';
+            this.lastErrorMessage = message;
             this.logger?.error({
                 event: 'downstream.call_failed',
                 server_name: this.config.name,

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

@@ -0,0 +1,117 @@
+/**
+ * Gateway-internal `__rea__health` meta-tool.
+ *
+ * WHY THIS EXISTS
+ * ===============
+ *
+ * The MCP `listTools` catalog the gateway advertises is the UNION of every
+ * healthy downstream's own catalog. When all downstreams are unhealthy — or
+ * the registry is empty, or fingerprints fail, or an env var is missing — the
+ * catalog is empty. From the LLM's perspective this is indistinguishable from
+ * a gateway that came up fine but happens to have nothing to proxy, and there
+ * is no tool it can call to ask "why is this empty?" because, well, the
+ * catalog is empty.
+ *
+ * This meta-tool closes that diagnostic gap: the gateway ALWAYS exposes
+ * `__rea__health` regardless of downstream state, the kill-switch, or the
+ * middleware chain. A caller can invoke it to get a snapshot of every
+ * registered server's connection state, last error, and tool count.
+ *
+ * DESIGN CHOICES
+ * --------------
+ *
+ * 1. Name shape: `__rea__health`. The leading `__` (instead of a normal
+ *    `<server>__<tool>` prefix) reserves the namespace for gateway-internal
+ *    tools. It never collides with a registered server because
+ *    `src/registry/loader.ts` restricts `name` to `^[a-z0-9][a-z0-9-]*$` —
+ *    no underscores allowed.
+ *
+ * 2. Short-circuit in `server.ts`: the CallTool handler matches on the
+ *    constant below BEFORE calling `splitPrefixed`, and responds directly
+ *    without running the middleware chain. Reasons, ordered:
+ *      (a) This tool must be callable while HALT is present — otherwise the
+ *          operator can't introspect a frozen gateway.
+ *      (b) Tier middleware would classify `health` as Write (default for
+ *          unlisted names) and deny L0 callers — wrong for read-only
+ *          introspection.
+ *      (c) There is no downstream to dispatch to — the entire middleware
+ *          chain is about getting to one safely.
+ *    The short-circuit still writes an audit record via `appendAuditRecord`
+ *    so invocations remain accountable.
+ *
+ * 3. Never throws. Health is the one tool the caller uses when things are
+ *    broken. Every field is best-effort; a missing value is surfaced as
+ *    `null`, not as an exception.
+ */
+import type { Policy } from '../../policy/types.js';
+import type { DownstreamHealth } from '../downstream-pool.js';
+/** Canonical MCP tool name exposed by the gateway. */
+export declare const META_HEALTH_TOOL_NAME = "__rea__health";
+/** `server_name` recorded in audit entries for this meta-tool. */
+export declare const META_SERVER_NAME = "__rea__";
+/** `tool_name` recorded in audit entries for this meta-tool. */
+export declare const META_TOOL_NAME = "health";
+export interface MetaHealthSnapshot {
+    /** rea gateway version (from package.json, pinned to the shipped version). */
+    gateway: {
+        version: string;
+        /** Seconds since gateway process started. */
+        uptime_s: number;
+        /** Whether `.rea/HALT` is present. */
+        halt: boolean;
+        /** When true, the health tool is the only callable tool right now. */
+        halt_reason: string | null;
+    };
+    policy: {
+        profile: string;
+        autonomy_level: string;
+        max_autonomy_level: string;
+        block_ai_attribution: boolean;
+        blocked_paths_count: number;
+    };
+    /** Per-downstream state. Empty array iff the registry is empty. */
+    downstreams: DownstreamHealth[];
+    /** Rolled-up counts the LLM can act on without walking the array. */
+    summary: {
+        registered: number;
+        connected: number;
+        healthy: number;
+        total_tools: number;
+    };
+}
+export interface BuildHealthSnapshotDeps {
+    /** Gateway version (so we can test deterministically without reading package.json). */
+    gatewayVersion: string;
+    /** Gateway boot time in epoch ms. `uptime_s` is computed from this. */
+    startedAtMs: number;
+    /** Frozen policy snapshot — we do not re-read `.rea/policy.yaml` here. */
+    policy: Policy;
+    /** Per-downstream state from the pool. */
+    downstreams: DownstreamHealth[];
+    /** Whether `.rea/HALT` is present at snapshot time. */
+    halt: boolean;
+    /**
+     * HALT reason, if any. `null` when HALT is absent OR when the file exists
+     * but the caller couldn't read its contents — we never surface an I/O
+     * exception through this tool.
+     */
+    haltReason: string | null;
+    /** Current epoch ms. Injected for determinism in tests. */
+    nowMs?: number;
+}
+/**
+ * Pure function that builds the snapshot from injected state. All I/O happens
+ * in the caller (`server.ts`) — keeps this testable and keeps "health never
+ * throws" a local invariant rather than a chain-wide claim.
+ */
+export declare function buildHealthSnapshot(deps: BuildHealthSnapshotDeps): MetaHealthSnapshot;
+/**
+ * The descriptor the gateway advertises via `tools/list`. No arguments —
+ * callers request a snapshot by calling with `{}`. Keeping the surface
+ * argument-free makes the tool trivially safe for any autonomy level.
+ */
+export declare function metaHealthToolDescriptor(): {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+};

package/dist/gateway/meta/health.js

@@ -0,0 +1,108 @@
+/**
+ * Gateway-internal `__rea__health` meta-tool.
+ *
+ * WHY THIS EXISTS
+ * ===============
+ *
+ * The MCP `listTools` catalog the gateway advertises is the UNION of every
+ * healthy downstream's own catalog. When all downstreams are unhealthy — or
+ * the registry is empty, or fingerprints fail, or an env var is missing — the
+ * catalog is empty. From the LLM's perspective this is indistinguishable from
+ * a gateway that came up fine but happens to have nothing to proxy, and there
+ * is no tool it can call to ask "why is this empty?" because, well, the
+ * catalog is empty.
+ *
+ * This meta-tool closes that diagnostic gap: the gateway ALWAYS exposes
+ * `__rea__health` regardless of downstream state, the kill-switch, or the
+ * middleware chain. A caller can invoke it to get a snapshot of every
+ * registered server's connection state, last error, and tool count.
+ *
+ * DESIGN CHOICES
+ * --------------
+ *
+ * 1. Name shape: `__rea__health`. The leading `__` (instead of a normal
+ *    `<server>__<tool>` prefix) reserves the namespace for gateway-internal
+ *    tools. It never collides with a registered server because
+ *    `src/registry/loader.ts` restricts `name` to `^[a-z0-9][a-z0-9-]*$` —
+ *    no underscores allowed.
+ *
+ * 2. Short-circuit in `server.ts`: the CallTool handler matches on the
+ *    constant below BEFORE calling `splitPrefixed`, and responds directly
+ *    without running the middleware chain. Reasons, ordered:
+ *      (a) This tool must be callable while HALT is present — otherwise the
+ *          operator can't introspect a frozen gateway.
+ *      (b) Tier middleware would classify `health` as Write (default for
+ *          unlisted names) and deny L0 callers — wrong for read-only
+ *          introspection.
+ *      (c) There is no downstream to dispatch to — the entire middleware
+ *          chain is about getting to one safely.
+ *    The short-circuit still writes an audit record via `appendAuditRecord`
+ *    so invocations remain accountable.
+ *
+ * 3. Never throws. Health is the one tool the caller uses when things are
+ *    broken. Every field is best-effort; a missing value is surfaced as
+ *    `null`, not as an exception.
+ */
+/** 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. */
+export const META_SERVER_NAME = '__rea__';
+/** `tool_name` recorded in audit entries for this meta-tool. */
+export const META_TOOL_NAME = 'health';
+/**
+ * Pure function that builds the snapshot from injected state. All I/O happens
+ * in the caller (`server.ts`) — keeps this testable and keeps "health never
+ * throws" a local invariant rather than a chain-wide claim.
+ */
+export function buildHealthSnapshot(deps) {
+    const now = deps.nowMs ?? Date.now();
+    const uptime_s = Math.max(0, Math.floor((now - deps.startedAtMs) / 1000));
+    let connected = 0;
+    let healthy = 0;
+    let total_tools = 0;
+    for (const d of deps.downstreams) {
+        if (d.connected)
+            connected += 1;
+        if (d.healthy)
+            healthy += 1;
+        if (typeof d.tools_count === 'number')
+            total_tools += d.tools_count;
+    }
+    return {
+        gateway: {
+            version: deps.gatewayVersion,
+            uptime_s,
+            halt: deps.halt,
+            halt_reason: deps.haltReason,
+        },
+        policy: {
+            profile: deps.policy.profile,
+            autonomy_level: String(deps.policy.autonomy_level),
+            max_autonomy_level: String(deps.policy.max_autonomy_level),
+            block_ai_attribution: deps.policy.block_ai_attribution,
+            blocked_paths_count: deps.policy.blocked_paths.length,
+        },
+        downstreams: deps.downstreams,
+        summary: {
+            registered: deps.downstreams.length,
+            connected,
+            healthy,
+            total_tools,
+        },
+    };
+}
+/**
+ * The descriptor the gateway advertises via `tools/list`. No arguments —
+ * callers request a snapshot by calling with `{}`. Keeping the surface
+ * argument-free makes the tool trivially safe for any autonomy level.
+ */
+export function metaHealthToolDescriptor() {
+    return {
+        name: META_HEALTH_TOOL_NAME,
+        description: 'rea gateway self-diagnostic. Returns the gateway version, HALT state, policy summary, ' +
+            'and per-downstream connection/health/tool-count. Always available, even when every ' +
+            'downstream is unhealthy or HALT is active — this is the tool you call when listTools ' +
+            'comes back empty or suspicious.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    };
+}

package/dist/gateway/server.js

@@ -32,7 +32,12 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+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 { appendAuditRecord } from '../audit/append.js';
+import { getPkgVersion } from '../cli/utils.js';
 import { createAuditMiddleware } from './middleware/audit.js';
 import { createKillSwitchMiddleware } from './middleware/kill-switch.js';
 import { createTierMiddleware } from './middleware/tier.js';
@@ -116,11 +121,13 @@ function buildMiddlewareChain(opts, deps) {
     ];
 }
 export function createGateway(opts) {
-    const { registry } = opts;
+    const { registry, policy, baseDir } = opts;
     const logger = opts.logger ?? createLogger({ base: { session_id: currentSessionId() } });
     const metrics = opts.metrics;
     const pool = new DownstreamPool(registry, logger);
-    const server = new Server({ name: 'rea', version: '0.2.0' }, { capabilities: { tools: {} } });
+    const gatewayVersion = getPkgVersion();
+    const startedAtMs = Date.now();
+    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.
     const breaker = new CircuitBreaker({
@@ -146,22 +153,116 @@ export function createGateway(opts) {
         },
     });
     const staticChain = buildMiddlewareChain(opts, { breaker });
+    // Read `.rea/HALT` without ever throwing. Returns `{halt, reason}` where
+    // `reason` is the (trimmed) file contents or null when the file is absent
+    // / unreadable. The meta-tool never surfaces I/O errors — health is the one
+    // thing that has to keep working when everything else is broken.
+    async function readHalt() {
+        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 };
+        }
+        catch {
+            return { halt: false, reason: null };
+        }
+    }
     // ── Handlers ─────────────────────────────────────────────────────────────
     server.setRequestHandler(ListToolsRequestSchema, async () => {
+        // The `__rea__health` meta-tool is ALWAYS advertised, regardless of
+        // downstream state. This is the systemic answer to the "listTools came
+        // back empty, now what?" diagnostic gap — the LLM can always call
+        // health to find out why.
+        const metaTool = metaHealthToolDescriptor();
         if (pool.size === 0)
-            return { tools: [] };
+            return { tools: [metaTool] };
         const prefixed = await pool.listAllTools();
         return {
-            tools: prefixed.map((t) => ({
-                name: t.name,
-                description: t.description ?? `${t.server} → ${t.name.slice(t.server.length + 2)}`,
-                inputSchema: t.inputSchema ?? { type: 'object' },
-            })),
+            tools: [
+                metaTool,
+                ...prefixed.map((t) => ({
+                    name: t.name,
+                    description: t.description ?? `${t.server} → ${t.name.slice(t.server.length + 2)}`,
+                    inputSchema: t.inputSchema ?? { type: 'object' },
+                })),
+            ],
         };
     });
     server.setRequestHandler(CallToolRequestSchema, async (req) => {
         const prefixed = req.params.name;
         const args = (req.params.arguments ?? {});
+        // Short-circuit the `__rea__health` meta-tool BEFORE the middleware chain
+        // and BEFORE splitPrefixed. Reasons:
+        //   - Must be callable while HALT is active (so the operator can
+        //     introspect a frozen gateway). The kill-switch middleware would
+        //     otherwise deny.
+        //   - `deriveBaseTier('health')` defaults to Write, which would deny L0
+        //     callers. Health is pure introspection — tier doesn't apply.
+        //   - There's no downstream to dispatch to. The middleware chain exists
+        //     to reach one safely.
+        // We still write an audit record so invocations remain accountable.
+        // The `__rea__` prefix is reserved for gateway-internal meta-tools.
+        // Reject any unknown name in that namespace with a clear error rather
+        // than letting `splitPrefixed` produce the confusing `unknown downstream
+        // server ""` message for e.g. `__rea__health ` (trailing space) or a
+        // future meta-tool name the client was guessing at.
+        if (prefixed.startsWith('__rea__') && prefixed !== META_HEALTH_TOOL_NAME) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: `reserved meta-namespace: only "${META_HEALTH_TOOL_NAME}" is defined under __rea__`,
+                    },
+                ],
+            };
+        }
+        if (prefixed === META_HEALTH_TOOL_NAME) {
+            const startMs = Date.now();
+            const haltState = await readHalt();
+            const snapshot = buildHealthSnapshot({
+                gatewayVersion,
+                startedAtMs,
+                policy,
+                downstreams: pool.healthSnapshot(),
+                halt: haltState.halt,
+                haltReason: haltState.reason,
+            });
+            // 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.
+            try {
+                await appendAuditRecord(baseDir, {
+                    tool_name: META_TOOL_NAME,
+                    server_name: META_SERVER_NAME,
+                    status: InvocationStatus.Allowed,
+                    tier: Tier.Read,
+                    autonomy_level: String(policy.autonomy_level),
+                    session_id: currentSessionId(),
+                    duration_ms: Date.now() - startMs,
+                    metadata: {
+                        halt: snapshot.gateway.halt,
+                        downstreams_registered: snapshot.summary.registered,
+                        downstreams_healthy: snapshot.summary.healthy,
+                    },
+                });
+            }
+            catch (err) {
+                logger.warn({
+                    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),
+                });
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(snapshot, null, 2),
+                    },
+                ],
+            };
+        }
         // Split prefix for downstream dispatch; the terminal middleware uses the
         // full prefixed name to call the pool (which re-splits internally).
         let serverName;
@@ -336,7 +437,3 @@ export function createGateway(opts) {
     }
     return { server, start, stop, pool, logger, metrics };
 }
-// Prevent TS from complaining about the unused `Tier` import when the file is
-// compiled in isolation; keeping the import pins the semantic dependency edge
-// for future middleware that may want to inspect the tier in terminal.
-void Tier;

package/package.json

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