@bookedsolid/rea 0.3.0 → 0.4.0

package/dist/gateway/downstream.js

@@ -37,6 +37,7 @@
  */
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { interpolateEnv } from '../registry/interpolate.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.
@@ -66,14 +67,6 @@ const DEFAULT_ENV_ALLOWLIST = [
  * handle it.
  */
 const RECONNECT_FLAP_WINDOW_MS = 30_000;
-/**
- * Build the child env by layering:
- *   allowlist → registry env_passthrough → registry env.
- * Later entries win. Missing host values are skipped so `process.env[name]`
- * being undefined does not serialize as the literal string "undefined".
- *
- * Exported for testing.
- */
 export function buildChildEnv(config, hostEnv = process.env) {
     const out = {};
     for (const name of DEFAULT_ENV_ALLOWLIST) {
@@ -88,14 +81,21 @@ export function buildChildEnv(config, hostEnv = process.env) {
                 out[name] = v;
         }
     }
+    // Interpolate placeholders in config.env BEFORE layering it on top.
+    // `interpolateEnv` is pure — no I/O, throws only on malformed syntax
+    // (unterminated brace, empty `${}`, illegal var name). Missing host
+    // vars are reported via `result.missing`; the caller decides whether
+    // to refuse the spawn.
+    const interp = interpolateEnv(config.env, hostEnv);
     // Explicit config.env wins — operator typed these values deliberately.
-    for (const [k, v] of Object.entries(config.env)) {
+    for (const [k, v] of Object.entries(interp.resolved)) {
         out[k] = v;
     }
-    return out;
+    return { env: out, missing: interp.missing, secretKeys: interp.secretKeys };
 }
 export class DownstreamConnection {
     config;
+    logger;
     client = null;
     /**
      * Whether a reconnect has already been attempted in the CURRENT failure
@@ -107,8 +107,15 @@ export class DownstreamConnection {
     /** Epoch ms of the last successful reconnect. Used by the flapping guard. */
     lastReconnectAt = 0;
     health = 'healthy';
-    constructor(config) {
+    constructor(config, 
+    /**
+     * Optional structured logger (G5). When omitted, connection lifecycle
+     * events are simply not logged — keeping the class usable in unit tests
+     * that don't care about observability.
+     */
+    logger) {
         this.config = config;
+        this.logger = logger;
     }
     get name() {
         return this.config.name;
@@ -119,10 +126,40 @@ export class DownstreamConnection {
     async connect() {
         if (this.client !== null)
             return;
+        // Resolve env BEFORE spawning. If any `${VAR}` reference in the registry's
+        // explicit env: map is unset at startup, refuse to spawn this server:
+        //   - log a clear, secret-safe error (only the var name appears; the
+        //     resolved value would not exist anyway since it's missing)
+        //   - mark this connection unhealthy so the pool skips it
+        //   - leave every other server's spawn path untouched (the gateway as a
+        //     whole keeps coming up)
+        //
+        // Malformed syntax (unterminated brace, `${}`, illegal identifier) throws
+        // from interpolateEnv — that's a load-time error and we propagate it so
+        // the operator sees it at startup with server context attached.
+        let built;
+        try {
+            built = buildChildEnv(this.config);
+        }
+        catch (err) {
+            this.health = 'unhealthy';
+            throw new Error(`failed to resolve env for downstream "${this.config.name}": ${err instanceof Error ? err.message : err}`);
+        }
+        if (built.missing.length > 0) {
+            this.health = 'unhealthy';
+            // 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.
+            for (const missingVar of built.missing) {
+                console.error(`[rea-gateway] refusing to start downstream "${this.config.name}": ` +
+                    `env references ${'${'}${missingVar}${'}'} but process.env.${missingVar} is not set`);
+            }
+            throw new Error(`downstream "${this.config.name}" refused to start — missing env: ${built.missing.join(', ')}`);
+        }
         const transport = new StdioClientTransport({
             command: this.config.command,
             args: this.config.args,
-            env: buildChildEnv(this.config),
+            env: built.env,
         });
         const client = new Client({ name: `rea-gateway-client:${this.config.name}`, version: '0.2.0' }, { capabilities: {} });
         try {
@@ -157,11 +194,16 @@ export class DownstreamConnection {
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
-            const withinFlapWindow = this.lastReconnectAt !== 0 &&
-                Date.now() - this.lastReconnectAt < RECONNECT_FLAP_WINDOW_MS;
+            const withinFlapWindow = this.lastReconnectAt !== 0 && Date.now() - this.lastReconnectAt < RECONNECT_FLAP_WINDOW_MS;
             if (!this.reconnectAttempted && !withinFlapWindow) {
                 this.reconnectAttempted = true;
                 this.health = 'degraded';
+                this.logger?.warn({
+                    event: 'downstream.reconnect_attempt',
+                    server_name: this.config.name,
+                    message: `downstream "${this.config.name}" will reconnect once after error`,
+                    reason: message,
+                });
                 try {
                     await this.close();
                     await this.connect();
@@ -170,14 +212,31 @@ export class DownstreamConnection {
                     // stamp the reconnect time so flap-guard can refuse rapid repeats.
                     this.reconnectAttempted = false;
                     this.lastReconnectAt = Date.now();
+                    this.logger?.info({
+                        event: 'downstream.reconnected',
+                        server_name: this.config.name,
+                        message: `downstream "${this.config.name}" reconnected successfully`,
+                    });
                     return result;
                 }
                 catch (reconnectErr) {
                     this.health = 'unhealthy';
+                    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),
+                    });
                     throw new Error(`downstream "${this.config.name}" unhealthy after one reconnect: ${reconnectErr instanceof Error ? reconnectErr.message : reconnectErr}`);
                 }
             }
             this.health = 'unhealthy';
+            this.logger?.error({
+                event: 'downstream.call_failed',
+                server_name: this.config.name,
+                message: `downstream "${this.config.name}" call failed`,
+                error: message,
+            });
             throw new Error(`downstream "${this.config.name}" call failed: ${message}`);
         }
     }

package/dist/gateway/log.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Structured gateway logger (G5).
+ *
+ * Minimal JSON-lines logger for `rea serve` and its collaborators. The existing
+ * codebase had `console.error`/`console.warn` scattered across the gateway;
+ * that worked for humans tailing stderr but made logs impossible to parse for
+ * future tooling (shipping to syslog, aggregating in a dashboard, greping
+ * per-session).
+ *
+ * Design constraints (from the task spec):
+ *
+ *   1. NO dependency — pino would be overkill, and dep weight matters for an
+ *      install-anywhere CLI. ~30 lines of hand-rolled code is enough.
+ *   2. Respect `REA_LOG_LEVEL` (info default; debug for future verbose hooks).
+ *   3. Pretty-print on a TTY stderr; emit JSON lines on non-TTY (CI, redirected
+ *      stderr, process-supervised runs).
+ *   4. Preserve the `[rea-serve]` / `[rea]` prefix convention — the helix smoke
+ *      test greps for these. Pretty-mode prints them explicitly; JSON mode
+ *      carries them as structured fields.
+ *   5. Never throw. A logger that can crash the gateway is a bad trade.
+ *
+ * ## What this is NOT
+ *
+ * - Not an OpenTelemetry integration — see {@link ./observability/metrics.ts}
+ *   for counters/gauges. Logs and metrics are separate concerns.
+ * - Not the audit log — `.rea/audit.jsonl` is a hash-chained, tamper-evident
+ *   record of tool calls. This module is free-form operator observability.
+ * - Not a file logger. Records go to stderr only. If you need durable logs,
+ *   redirect the process's stderr.
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/** Structured fields every record carries. Additional fields are allowed. */
+export interface LogFields {
+    /** Short verb-ish name — `downstream.connect`, `circuit.open`, etc. */
+    event: string;
+    /** Running gateway session id, when known. Omitted from startup records. */
+    session_id?: string;
+    /** Name of a downstream MCP server, when the record is server-scoped. */
+    server_name?: string;
+    /** Human-readable message. JSON mode carries it verbatim. */
+    message: string;
+    /** Any additional context. Values must be JSON-serializable. */
+    [key: string]: unknown;
+}
+export interface Logger {
+    debug(fields: LogFields): void;
+    info(fields: LogFields): void;
+    warn(fields: LogFields): void;
+    error(fields: LogFields): void;
+    /** Spawn a logger that merges `base` into every record. */
+    child(base: Partial<LogFields>): Logger;
+}
+/**
+ * Pre-emit field redactor. Called for every string-valued field in a
+ * record just before serialization. Returns the redacted string.
+ *
+ * SECURITY: downstream error messages may carry credential material
+ * (env var names, argv fragments, file paths). Without a hook the raw
+ * text reaches stderr unchanged. `createLogger` in `rea serve` installs
+ * a redactor compiled from the same SECRET_PATTERNS used by the redact
+ * middleware so log records carry the same protection as audit records.
+ *
+ * The hook must be synchronous, total (never throw), and idempotent on
+ * already-redacted strings. It MUST NOT perform I/O.
+ */
+export type FieldRedactor = (value: string) => string;
+export interface LoggerOptions {
+    /** Minimum level to emit. Default from REA_LOG_LEVEL env, else 'info'. */
+    level?: LogLevel;
+    /** Sink for serialized records. Defaults to `process.stderr`. */
+    stream?: NodeJS.WritableStream;
+    /**
+     * Force output mode. Default: auto — JSON when `stream.isTTY !== true`,
+     * pretty when the stream is a TTY.
+     */
+    mode?: 'json' | 'pretty';
+    /** Clock injection for tests. Default: `Date.now`. */
+    now?: () => number;
+    /** Base fields merged into every record (used by `child()`). */
+    base?: Partial<LogFields>;
+    /**
+     * Optional pre-emit redactor applied to every string-valued field.
+     * See {@link FieldRedactor}. When omitted, no log-field redaction runs
+     * (0.3.x behavior). `rea serve` wires this up to the same patterns the
+     * redact middleware uses so downstream error messages can't leak creds
+     * to stderr.
+     */
+    redactField?: FieldRedactor;
+}
+/**
+ * Parse `REA_LOG_LEVEL`. Unknown values fall back to 'info' — we never want
+ * startup to fail because an operator typo'd an env var.
+ */
+export declare function resolveLogLevel(raw: string | undefined): LogLevel;
+/**
+ * Build a {@link FieldRedactor} from a list of plain regexes. Each regex
+ * is applied in order with `String.prototype.replace`, producing
+ * `[REDACTED]` where a match is found.
+ *
+ * Why not reuse the middleware's `SafeRegex` wrappers?
+ *   - Log fields are short operator-supplied strings (typically downstream
+ *     error messages + event names), not arbitrary MCP payloads. The
+ *     ReDoS surface that motivated `SafeRegex` for the redact middleware
+ *     does not apply here — the patterns we ship are anchored and
+ *     bounded.
+ *   - Running regex in a worker thread on every log line would add
+ *     measurable latency to every event and pull in the worker pool on
+ *     startup. For a sync logger that needs to be near-free, a
+ *     sync-regex path is the right tradeoff.
+ *
+ * Exported so callers can pass their own compiled pattern list without
+ * touching the internal shape.
+ */
+export declare function buildRegexRedactor(patterns: ReadonlyArray<{
+    name: string;
+    pattern: RegExp;
+}>): FieldRedactor;
+/**
+ * Create a logger. Defaults are appropriate for `rea serve` at runtime;
+ * tests inject `stream`, `mode`, and `now` directly.
+ */
+export declare function createLogger(opts?: LoggerOptions): Logger;

package/dist/gateway/log.js

@@ -0,0 +1,334 @@
+/**
+ * Structured gateway logger (G5).
+ *
+ * Minimal JSON-lines logger for `rea serve` and its collaborators. The existing
+ * codebase had `console.error`/`console.warn` scattered across the gateway;
+ * that worked for humans tailing stderr but made logs impossible to parse for
+ * future tooling (shipping to syslog, aggregating in a dashboard, greping
+ * per-session).
+ *
+ * Design constraints (from the task spec):
+ *
+ *   1. NO dependency — pino would be overkill, and dep weight matters for an
+ *      install-anywhere CLI. ~30 lines of hand-rolled code is enough.
+ *   2. Respect `REA_LOG_LEVEL` (info default; debug for future verbose hooks).
+ *   3. Pretty-print on a TTY stderr; emit JSON lines on non-TTY (CI, redirected
+ *      stderr, process-supervised runs).
+ *   4. Preserve the `[rea-serve]` / `[rea]` prefix convention — the helix smoke
+ *      test greps for these. Pretty-mode prints them explicitly; JSON mode
+ *      carries them as structured fields.
+ *   5. Never throw. A logger that can crash the gateway is a bad trade.
+ *
+ * ## What this is NOT
+ *
+ * - Not an OpenTelemetry integration — see {@link ./observability/metrics.ts}
+ *   for counters/gauges. Logs and metrics are separate concerns.
+ * - Not the audit log — `.rea/audit.jsonl` is a hash-chained, tamper-evident
+ *   record of tool calls. This module is free-form operator observability.
+ * - Not a file logger. Records go to stderr only. If you need durable logs,
+ *   redirect the process's stderr.
+ */
+/** Ordered lowest → highest. A record is emitted iff its level ≥ current. */
+const LEVEL_ORDER = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+};
+/**
+ * Hard byte-cap for string-valued log fields. Applied before any regex runs
+ * so that an attacker-influenced error message (e.g. a downstream MCP error
+ * that echoes request content) cannot cause catastrophic backtracking against
+ * the redaction pattern set, even if a badly-written pattern is loaded.
+ *
+ * 4 KiB is generous for any legitimate structured-log value and tiny compared
+ * to the multi-MB payloads that would be needed to trigger backtracking on
+ * a pathological pattern.
+ */
+const MAX_LOG_FIELD_BYTES = 4096;
+/**
+ * Parse `REA_LOG_LEVEL`. Unknown values fall back to 'info' — we never want
+ * startup to fail because an operator typo'd an env var.
+ */
+export function resolveLogLevel(raw) {
+    if (raw === undefined)
+        return 'info';
+    const normalized = raw.trim().toLowerCase();
+    if (normalized === 'debug' ||
+        normalized === 'info' ||
+        normalized === 'warn' ||
+        normalized === 'error') {
+        return normalized;
+    }
+    return 'info';
+}
+/**
+ * ANSI color helpers. Kept tiny — we don't pull chalk to color four words.
+ * A non-TTY writer never hits these because pretty mode only runs on a TTY.
+ */
+const COLOR = {
+    reset: '\x1b[0m',
+    dim: '\x1b[2m',
+    red: '\x1b[31m',
+    yellow: '\x1b[33m',
+    green: '\x1b[32m',
+    cyan: '\x1b[36m',
+};
+function levelColor(level) {
+    switch (level) {
+        case 'error':
+            return COLOR.red;
+        case 'warn':
+            return COLOR.yellow;
+        case 'info':
+            return COLOR.green;
+        case 'debug':
+            return COLOR.cyan;
+    }
+}
+/**
+ * Resolve `mode` from options and stream. A non-TTY stream always gets JSON —
+ * that is the well-defined contract for supervisors like systemd or Claude
+ * Code's MCP runner which redirect our stderr.
+ */
+function resolveMode(stream, explicit) {
+    if (explicit !== undefined)
+        return explicit;
+    const isTTY = stream.isTTY === true;
+    return isTTY ? 'pretty' : 'json';
+}
+/**
+ * Stringify a record body. We do NOT use JSON.stringify's replacer argument
+ * for ordering — JSON.stringify preserves insertion order for string keys,
+ * so composing the record in a stable order is enough.
+ */
+function serialize(record) {
+    try {
+        return JSON.stringify(record);
+    }
+    catch {
+        // Last-ditch: drop unserializable values. A logger that throws on a
+        // circular ref in a user-supplied field would be a denial-of-service
+        // surface on its own daemon.
+        return JSON.stringify({
+            timestamp: record['timestamp'],
+            level: record['level'],
+            event: record['event'],
+            message: '[unserializable log record]',
+        });
+    }
+}
+/**
+ * Safe stringify for pretty-mode extras. JSON mode has its own serialize()
+ * fallback; pretty mode historically called `JSON.stringify(v)` raw, which
+ * throws on cyclic references. The outer emit() wrapped that in an empty
+ * try/catch so the entire record was dropped silently — a logger that
+ * drops records on operator-supplied extras is a DoS surface.
+ *
+ * Here we catch the throw, substitute a stable placeholder, and keep
+ * emitting. The record reaches the operator even if one field is
+ * unserializable.
+ */
+function safeStringifyExtra(v) {
+    try {
+        return JSON.stringify(v);
+    }
+    catch {
+        return '[unserializable]';
+    }
+}
+/**
+ * Pretty-format for a human reader. Keeps the `[rea-serve]` prefix convention
+ * so the helix smoke test's grep still matches.
+ */
+function formatPretty(level, timestamp, fields) {
+    const color = levelColor(level);
+    const levelTag = level.toUpperCase().padEnd(5);
+    // Strip C0 controls and DEL from disk-sourced strings before terminal output
+    // to prevent ANSI/OSC escape injection from compromised MCP error messages.
+    const strip = (s) => s.replace(/[\x00-\x1f\x7f\u200b-\u200f\u202a-\u202e\u2028\u2029\u2066-\u2069]/g, '?');
+    const event = strip(fields.event);
+    const message = strip(fields.message);
+    // Extract the well-known fields we already rendered.
+    const { event: _e, message: _m, session_id, server_name, ...rest } = fields;
+    void _e;
+    void _m;
+    const extras = [];
+    if (server_name !== undefined)
+        extras.push(`server=${strip(String(server_name))}`);
+    if (session_id !== undefined)
+        extras.push(`session=${strip(String(session_id)).slice(0, 8)}`);
+    for (const [k, v] of Object.entries(rest)) {
+        if (k === 'timestamp' || k === 'level')
+            continue; // trusted-internal: toISOString + enum-derived
+        extras.push(`${k}=${typeof v === 'string' ? strip(v) : safeStringifyExtra(v)}`);
+    }
+    const extrasStr = extras.length > 0 ? ` ${COLOR.dim}${extras.join(' ')}${COLOR.reset}` : '';
+    return `${COLOR.dim}${timestamp}${COLOR.reset} ${color}${levelTag}${COLOR.reset} [rea-serve] ${event}: ${message}${extrasStr}\n`;
+}
+class BasicLogger {
+    minLevel;
+    stream;
+    mode;
+    now;
+    base;
+    redactField;
+    constructor(opts) {
+        const level = opts.level ?? resolveLogLevel(process.env['REA_LOG_LEVEL']);
+        this.minLevel = LEVEL_ORDER[level];
+        this.stream = opts.stream ?? process.stderr;
+        this.mode = resolveMode(this.stream, opts.mode);
+        this.now = opts.now ?? Date.now;
+        this.base = opts.base ?? {};
+        this.redactField = opts.redactField;
+    }
+    debug(fields) {
+        this.emit('debug', fields);
+    }
+    info(fields) {
+        this.emit('info', fields);
+    }
+    warn(fields) {
+        this.emit('warn', fields);
+    }
+    error(fields) {
+        this.emit('error', fields);
+    }
+    child(base) {
+        return new BasicLogger({
+            level: inverseLevel(this.minLevel),
+            stream: this.stream,
+            mode: this.mode,
+            now: this.now,
+            base: { ...this.base, ...base },
+            ...(this.redactField !== undefined ? { redactField: this.redactField } : {}),
+        });
+    }
+    /**
+     * Apply the configured field redactor (if any) to every string-valued
+     * entry in the merged record. Non-string values pass through
+     * unchanged — a JSON-serializable object with credentials inside would
+     * need its own redactor upstream; the typical leak path for downstream
+     * MCP errors is a plain-string `error` or `message` field.
+     *
+     * SECURITY: downstream error messages are attacker-influenced and can
+     * be arbitrarily long. A badly-backtracking pattern applied to a large
+     * string would stall the event loop. Hard-cap each string field at
+     * MAX_LOG_FIELD_BYTES BEFORE applying any regex. The cap is applied
+     * regardless of whether a redactor is configured so the logger never
+     * writes runaway-length values to stderr even without patterns loaded.
+     */
+    applyRedactor(merged) {
+        const redactor = this.redactField;
+        const out = {};
+        for (const [k, v] of Object.entries(merged)) {
+            if (typeof v === 'string') {
+                // Truncate before regex — prevents catastrophic backtracking on
+                // attacker-controlled strings regardless of which patterns are loaded.
+                const capped = v.length > MAX_LOG_FIELD_BYTES
+                    ? v.slice(0, MAX_LOG_FIELD_BYTES) + '\u2026[truncated]'
+                    : v;
+                if (redactor === undefined) {
+                    out[k] = capped;
+                }
+                else {
+                    try {
+                        out[k] = redactor(capped);
+                    }
+                    catch {
+                        // A crashing redactor must not drop the record. Fall back to
+                        // a stable sentinel so the record still reaches the operator
+                        // without the raw (possibly sensitive) value.
+                        out[k] = '[redactor-error]';
+                    }
+                }
+            }
+            else {
+                out[k] = v;
+            }
+        }
+        return out;
+    }
+    emit(level, raw) {
+        if (LEVEL_ORDER[level] < this.minLevel)
+            return;
+        // Merge in base fields; explicit fields win.
+        const merged0 = { ...this.base, ...raw };
+        // SECURITY: apply the field redactor BEFORE serialization so the line
+        // written to stderr never contains the raw string. No-op when no
+        // redactor was configured.
+        const merged = this.applyRedactor(merged0);
+        const timestamp = new Date(this.now()).toISOString();
+        try {
+            let line;
+            if (this.mode === 'json') {
+                const record = { timestamp, level, ...merged };
+                line = serialize(record) + '\n';
+            }
+            else {
+                line = formatPretty(level, timestamp, merged);
+            }
+            this.stream.write(line);
+        }
+        catch {
+            // Last resort — the stream rejected our write. Swallow; nothing we do
+            // here can improve the situation.
+        }
+    }
+}
+/**
+ * Recover the log level name from its numeric order. Only used when creating
+ * a child logger so the child inherits the parent's level without a second env
+ * lookup.
+ */
+function inverseLevel(order) {
+    for (const [name, n] of Object.entries(LEVEL_ORDER)) {
+        if (n === order)
+            return name;
+    }
+    return 'info';
+}
+/**
+ * Build a {@link FieldRedactor} from a list of plain regexes. Each regex
+ * is applied in order with `String.prototype.replace`, producing
+ * `[REDACTED]` where a match is found.
+ *
+ * Why not reuse the middleware's `SafeRegex` wrappers?
+ *   - Log fields are short operator-supplied strings (typically downstream
+ *     error messages + event names), not arbitrary MCP payloads. The
+ *     ReDoS surface that motivated `SafeRegex` for the redact middleware
+ *     does not apply here — the patterns we ship are anchored and
+ *     bounded.
+ *   - Running regex in a worker thread on every log line would add
+ *     measurable latency to every event and pull in the worker pool on
+ *     startup. For a sync logger that needs to be near-free, a
+ *     sync-regex path is the right tradeoff.
+ *
+ * Exported so callers can pass their own compiled pattern list without
+ * touching the internal shape.
+ */
+export function buildRegexRedactor(patterns) {
+    // Capture patterns by reference; they are long-lived across logger use.
+    return (value) => {
+        let out = value;
+        for (const { pattern } of patterns) {
+            // Always create a fresh RegExp for global or sticky patterns — shared
+            // stateful RegExp objects carry `lastIndex` that concurrent callers (e.g.
+            // the SafeRegex worker in the redact middleware) can leave non-zero,
+            // causing String.replace to start mid-string and silently skip leading
+            // secrets. The `y` (sticky) flag carries the same hazard as `g`.
+            const re = (pattern.global || pattern.sticky)
+                ? new RegExp(pattern.source, pattern.flags)
+                : pattern;
+            out = out.replace(re, '[REDACTED]');
+        }
+        return out;
+    };
+}
+/**
+ * Create a logger. Defaults are appropriate for `rea serve` at runtime;
+ * tests inject `stream`, `mode`, and `now` directly.
+ */
+export function createLogger(opts = {}) {
+    return new BasicLogger(opts);
+}

package/dist/gateway/middleware/audit.d.ts

@@ -1,5 +1,6 @@
 import type { Policy } from '../../policy/types.js';
 import type { Middleware } from './chain.js';
+import type { MetricsRegistry } from '../observability/metrics.js';
 /**
  * Post-execution middleware: appends a hash-chained JSONL audit record.
  *
@@ -23,4 +24,12 @@ import type { Middleware } from './chain.js';
  *     the rotation boundary. When no `audit.rotation` block is set in policy,
  *     rotation is a no-op — 0.2.x behavior is preserved.
  */
-export declare function createAuditMiddleware(baseDir: string, policy?: Policy): Middleware;
+export declare function createAuditMiddleware(baseDir: string, policy?: Policy, 
+/**
+ * Optional metrics registry. When supplied, the
+ * `rea_audit_lines_appended_total` counter is incremented on every
+ * successful append (post-fsync). When omitted, no metrics are emitted —
+ * keeps the middleware usable in unit tests that don't exercise the
+ * observability surface.
+ */
+metrics?: MetricsRegistry): Middleware;

package/dist/gateway/middleware/audit.js

@@ -26,7 +26,15 @@ import { maybeRotate } from '../audit/rotator.js';
  *     the rotation boundary. When no `audit.rotation` block is set in policy,
  *     rotation is a no-op — 0.2.x behavior is preserved.
  */
-export function createAuditMiddleware(baseDir, policy) {
+export function createAuditMiddleware(baseDir, policy, 
+/**
+ * Optional metrics registry. When supplied, the
+ * `rea_audit_lines_appended_total` counter is incremented on every
+ * successful append (post-fsync). When omitted, no metrics are emitted —
+ * keeps the middleware usable in unit tests that don't exercise the
+ * observability surface.
+ */
+metrics) {
     // REA writes to a single .rea/audit.jsonl file (not dated per-day files).
     const reaDir = path.join(baseDir, '.rea');
     const auditFile = path.join(reaDir, 'audit.jsonl');
@@ -56,6 +64,15 @@ export function createAuditMiddleware(baseDir, policy) {
         // kill-switch denied before policy middleware ran).
         const duration_ms = Date.now() - ctx.start_time;
         const autonomyLevel = ctx.metadata.autonomy_level ?? policy?.autonomy_level ?? 'unknown';
+        // Cap ctx.error before writing the audit record. A downstream MCP server
+        // can produce arbitrarily long error strings; if the audit record grows
+        // beyond ~64 KiB, `rea status` misreports it as corrupt because the tail
+        // window in summarizeAudit cannot contain the full record. 4096 bytes is
+        // generous for any legitimate error description.
+        const MAX_AUDIT_ERROR_BYTES = 4096;
+        if (ctx.error && ctx.error.length > MAX_AUDIT_ERROR_BYTES) {
+            ctx.error = ctx.error.slice(0, MAX_AUDIT_ERROR_BYTES) + '\u2026[truncated]';
+        }
         // Serialize audit writes via a queue to maintain hash chain linearity under concurrency.
         // Each write awaits the previous one before running its lock-scoped append.
         const writePromise = writeQueue.then(async () => {
@@ -112,6 +129,14 @@ export function createAuditMiddleware(baseDir, policy) {
                         await fs.appendFile(auditFile, line);
                     }
                     await fsyncFile(auditFile);
+                    // Only increment after fsync — a counter advance for a line that
+                    // was never durable on disk would be a lie.
+                    try {
+                        metrics?.incAuditLines(1);
+                    }
+                    catch {
+                        // Metrics failures must never crash the gateway.
+                    }
                 });
             }
             catch (auditErr) {