@bookedsolid/rea 0.3.0 → 0.4.0

package/dist/cli/serve.d.ts

@@ -1,3 +1,46 @@
+/**
+ * State-file shape. `session_id` is the ownership key used by
+ * `cleanupStateIfOwned` during shutdown — a shutting-down instance
+ * that finds a different session_id in the file leaves it alone, so a
+ * later `rea serve` that has raced in and rewritten the breadcrumbs
+ * is never unexpectedly unlinked.
+ */
+interface ServeState {
+    session_id: string;
+    started_at: string;
+    metrics_port: number | null;
+}
+/**
+ * Atomic file write: stage to a per-pid temp name, then rename(2). The
+ * rename is atomic on POSIX within the same filesystem, so readers never
+ * see a half-written buffer. The unique-per-pid temp prefix ensures two
+ * overlapping `rea serve` processes don't clobber each other's stage
+ * files during the brief window between stage and rename.
+ */
+declare function writeFileAtomic(filePath: string, data: string): void;
+/**
+ * Write the `.rea/serve.pid` breadcrumb atomically. `rea status` reads
+ * it and independently `kill(pid, 0)`s before trusting liveness. Stamping
+ * with `process.pid` is what lets `cleanupPidIfOwned` refuse to unlink a
+ * breadcrumb that a newer instance has already claimed.
+ */
+declare function writePidfile(baseDir: string): string;
+declare function writeStateFile(baseDir: string, state: ServeState): string;
+/**
+ * Remove the pidfile ONLY if it still carries this process's pid. A
+ * shutting-down instance that finds a newer pid leaves the breadcrumb
+ * intact so the newer instance's `rea status` users still see "running".
+ * Any read/parse error is treated as "not mine" — we never unlink a file
+ * we cannot prove we own.
+ */
+declare function cleanupPidIfOwned(pidPath: string): void;
+/**
+ * Remove the state file ONLY if its `session_id` matches ours. Keyed on
+ * session id (not pid) because the state payload already carries the
+ * session; reusing that avoids a second cross-file lookup and keeps the
+ * ownership signal local to the file being deleted.
+ */
+declare function cleanupStateIfOwned(statePath: string, ownSessionId: string): void;
 /**
  * `rea serve` — start the MCP gateway.
  *
@@ -5,8 +48,29 @@
  * chain, spawns downstream children from the registry, and connects an upstream
  * stdio MCP server that clients (Claude Code, Helix, etc.) can talk to.
  *
+ * G5 additions:
+ *   - Writes a pidfile + session state breadcrumb for `rea status`.
+ *   - Boots a loopback `/metrics` HTTP endpoint when `REA_METRICS_PORT` is set.
+ *   - Emits structured log records through the gateway logger.
+ *
+ * Breadcrumb race posture:
+ *   - Writes are atomic (`writeFileSync` → `rename(2)`) so readers never see
+ *     a half-written file.
+ *   - Shutdown cleanup is ownership-aware: we only unlink `serve.pid` if its
+ *     pid matches ours, and only unlink `serve.state.json` if its session_id
+ *     matches ours. This prevents a second overlapping `rea serve` from
+ *     losing its breadcrumbs to the first instance's SIGTERM path.
+ *
  * Signals: SIGTERM and SIGINT both trigger a graceful shutdown. We do NOT exit
  * on uncaughtException — that path is owned by `src/cli/index.ts`. If the
  * gateway itself throws during startup we log and exit 1.
  */
 export declare function runServe(): Promise<void>;
+export declare const __TEST_INTERNALS: {
+    writeFileAtomic: typeof writeFileAtomic;
+    writePidfile: typeof writePidfile;
+    writeStateFile: typeof writeStateFile;
+    cleanupPidIfOwned: typeof cleanupPidIfOwned;
+    cleanupStateIfOwned: typeof cleanupStateIfOwned;
+};
+export {};

package/dist/cli/serve.js

@@ -1,8 +1,107 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
 import { loadPolicy } from '../policy/loader.js';
 import { loadRegistry } from '../registry/loader.js';
+import { applyTofuGate } from '../registry/tofu-gate.js';
 import { createGateway } from '../gateway/server.js';
 import { CodexProbe } from '../gateway/observability/codex-probe.js';
-import { POLICY_FILE, REGISTRY_FILE, err, exitWithMissingPolicy, log, reaPath, warn, } from './utils.js';
+import { MetricsRegistry, resolveMetricsPort, startMetricsServer, } from '../gateway/observability/metrics.js';
+import { buildRegexRedactor, createLogger, resolveLogLevel } from '../gateway/log.js';
+import { SECRET_PATTERNS } from '../gateway/middleware/redact.js';
+import { currentSessionId } from '../gateway/session.js';
+import { HALT_FILE, POLICY_FILE, REA_DIR, REGISTRY_FILE, SERVE_PID_FILE, SERVE_STATE_FILE, err, exitWithMissingPolicy, log, reaPath, warn, } from './utils.js';
+/**
+ * Atomic file write: stage to a per-pid temp name, then rename(2). The
+ * rename is atomic on POSIX within the same filesystem, so readers never
+ * see a half-written buffer. The unique-per-pid temp prefix ensures two
+ * overlapping `rea serve` processes don't clobber each other's stage
+ * files during the brief window between stage and rename.
+ */
+function writeFileAtomic(filePath, data) {
+    const dir = path.dirname(filePath);
+    const base = path.basename(filePath);
+    const tmp = path.join(dir, `.${base}.${crypto.randomUUID()}.tmp`);
+    fs.writeFileSync(tmp, data, { encoding: 'utf8', mode: 0o600 });
+    try {
+        fs.renameSync(tmp, filePath);
+    }
+    catch (e) {
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch {
+            /* ignored */
+        }
+        throw e;
+    }
+}
+/**
+ * Write the `.rea/serve.pid` breadcrumb atomically. `rea status` reads
+ * it and independently `kill(pid, 0)`s before trusting liveness. Stamping
+ * with `process.pid` is what lets `cleanupPidIfOwned` refuse to unlink a
+ * breadcrumb that a newer instance has already claimed.
+ */
+function writePidfile(baseDir) {
+    const reaDir = path.join(baseDir, REA_DIR);
+    if (!fs.existsSync(reaDir))
+        fs.mkdirSync(reaDir, { recursive: true });
+    const pidPath = reaPath(baseDir, SERVE_PID_FILE);
+    writeFileAtomic(pidPath, String(process.pid));
+    return pidPath;
+}
+function writeStateFile(baseDir, state) {
+    const p = reaPath(baseDir, SERVE_STATE_FILE);
+    writeFileAtomic(p, JSON.stringify(state, null, 2) + '\n');
+    return p;
+}
+/**
+ * Remove the pidfile ONLY if it still carries this process's pid. A
+ * shutting-down instance that finds a newer pid leaves the breadcrumb
+ * intact so the newer instance's `rea status` users still see "running".
+ * Any read/parse error is treated as "not mine" — we never unlink a file
+ * we cannot prove we own.
+ */
+function cleanupPidIfOwned(pidPath) {
+    try {
+        const raw = fs.readFileSync(pidPath, 'utf8').trim();
+        const pid = Number.parseInt(raw, 10);
+        if (pid === process.pid) {
+            try {
+                fs.unlinkSync(pidPath);
+            }
+            catch {
+                /* already gone */
+            }
+        }
+    }
+    catch {
+        // Missing, unreadable, mid-rename — nothing to clean up safely.
+    }
+}
+/**
+ * Remove the state file ONLY if its `session_id` matches ours. Keyed on
+ * session id (not pid) because the state payload already carries the
+ * session; reusing that avoids a second cross-file lookup and keeps the
+ * ownership signal local to the file being deleted.
+ */
+function cleanupStateIfOwned(statePath, ownSessionId) {
+    try {
+        const raw = fs.readFileSync(statePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed.session_id === ownSessionId) {
+            try {
+                fs.unlinkSync(statePath);
+            }
+            catch {
+                /* already gone */
+            }
+        }
+    }
+    catch {
+        // Missing, unreadable, mid-rename — leave alone.
+    }
+}
 /**
  * `rea serve` — start the MCP gateway.
  *
@@ -10,6 +109,19 @@ import { POLICY_FILE, REGISTRY_FILE, err, exitWithMissingPolicy, log, reaPath, w
  * chain, spawns downstream children from the registry, and connects an upstream
  * stdio MCP server that clients (Claude Code, Helix, etc.) can talk to.
  *
+ * G5 additions:
+ *   - Writes a pidfile + session state breadcrumb for `rea status`.
+ *   - Boots a loopback `/metrics` HTTP endpoint when `REA_METRICS_PORT` is set.
+ *   - Emits structured log records through the gateway logger.
+ *
+ * Breadcrumb race posture:
+ *   - Writes are atomic (`writeFileSync` → `rename(2)`) so readers never see
+ *     a half-written file.
+ *   - Shutdown cleanup is ownership-aware: we only unlink `serve.pid` if its
+ *     pid matches ours, and only unlink `serve.state.json` if its session_id
+ *     matches ours. This prevents a second overlapping `rea serve` from
+ *     losing its breadcrumbs to the first instance's SIGTERM path.
+ *
  * Signals: SIGTERM and SIGINT both trigger a graceful shutdown. We do NOT exit
  * on uncaughtException — that path is owned by `src/cli/index.ts`. If the
  * gateway itself throws during startup we log and exit 1.
@@ -45,7 +157,113 @@ export async function runServe() {
         err(`Failed to load registry: ${message}`);
         process.exit(1);
     }
-    const handle = createGateway({ baseDir, policy, registry });
+    // ── Observability setup (G5) ─────────────────────────────────────────────
+    const sessionId = currentSessionId();
+    // Build the log redactor from both built-in SECRET_PATTERNS and any
+    // operator-defined policy.redact.patterns. This is safe because
+    // applyRedactor in log.ts hard-caps every string field to
+    // MAX_LOG_FIELD_BYTES (4096 bytes) BEFORE running any regex — so
+    // attacker-influenced error strings are already bounded when the patterns
+    // execute. The earlier exclusion of policy patterns was motivated by the
+    // risk of applying operator regexes to unbounded strings; the 4096-byte
+    // cap in applyRedactor eliminates that risk. Policy patterns are validated
+    // as safe-regex at load time (G3), so catastrophic backtracking is already
+    // prevented at the source.
+    const policyLogPatterns = (policy.redact?.patterns ?? []).map((p) => ({
+        name: p.name,
+        pattern: new RegExp(p.regex, p.flags ?? 'g'),
+    }));
+    const logRedactor = buildRegexRedactor([...SECRET_PATTERNS, ...policyLogPatterns]);
+    const logger = createLogger({
+        level: resolveLogLevel(process.env['REA_LOG_LEVEL']),
+        base: { session_id: sessionId },
+        redactField: logRedactor,
+    });
+    const metricsRegistry = new MetricsRegistry();
+    metricsRegistry.markHaltCheck();
+    const metricsPort = resolveMetricsPort(process.env['REA_METRICS_PORT'], logger);
+    let metricsServer;
+    if (metricsPort !== null) {
+        try {
+            metricsServer = await startMetricsServer({
+                port: metricsPort,
+                registry: metricsRegistry,
+                logger,
+            });
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            // We do NOT fail gateway startup because of a metrics-bind failure —
+            // observability is best-effort. Log loudly so the operator notices.
+            logger.error({
+                event: 'metrics.bind_failed',
+                message: `failed to start /metrics on port ${metricsPort}: ${message}`,
+            });
+        }
+    }
+    // G7: TOFU fingerprint gate. Runs BEFORE we build the downstream pool so
+    // drifted servers are filtered out at the edge. First-seen and accepted
+    // drift fire LOUD stderr + audit + log; the gateway stays up either way.
+    //
+    // We pass the FULL declared server list (enabled AND disabled) to the
+    // gate so every entry gets a fingerprint baseline on first sight.
+    // Disabled-entry escape was a real bypass: an attacker who tampered
+    // with a disabled entry got no baseline recorded, so the
+    // disabled→enabled transition always looked benign first-seen on the
+    // next boot. Fingerprinting is a pure canonicalize+sha256 operation on
+    // the registry config (no spawn), so including disabled entries is
+    // cheap and safe.
+    //
+    // The `enabled` filter is applied AFTER the gate: only enabled servers
+    // that passed the gate are handed to the downstream pool for spawn.
+    //
+    // When the registry declares zero servers there is nothing to
+    // fingerprint — skip the gate entirely to avoid a redundant disk write
+    // on zero-server installs.
+    let gatedRegistry = registry;
+    try {
+        if (registry.servers.length > 0) {
+            const { accepted } = await applyTofuGate(baseDir, registry.servers, logger);
+            const acceptedNames = new Set(accepted.map((s) => s.name));
+            gatedRegistry = {
+                ...registry,
+                // Keep only entries that passed the TOFU gate. The `enabled`
+                // filter is applied downstream when the pool decides what to
+                // spawn — disabled entries that passed the gate stay in the
+                // registry so a future enable uses the already-recorded
+                // baseline instead of looking like a fresh first-seen.
+                servers: registry.servers.filter((s) => acceptedNames.has(s.name)),
+            };
+        }
+    }
+    catch (e) {
+        // Fail-closed on TOFU errors (e.g. corrupt fingerprint store). An attacker
+        // who can corrupt the store must not be able to downgrade drift detection
+        // by forcing the gateway into a "first-run" fallback. Surface the error
+        // and exit — operator can delete the store deliberately to re-bootstrap.
+        err(`TOFU gate failed: ${e instanceof Error ? e.message : e}`);
+        console.error('');
+        console.error('  To intentionally re-bootstrap the fingerprint store:');
+        console.error('  1. Inspect .rea/fingerprints.json for tampering');
+        console.error('  2. If safe, delete it and re-run `rea serve`');
+        console.error('');
+        process.exit(1);
+    }
+    const handle = createGateway({
+        baseDir,
+        policy,
+        registry: gatedRegistry,
+        logger,
+        metrics: metricsRegistry,
+    });
+    // ── HALT acknowledgement at startup (G5) ─────────────────────────────────
+    const haltPath = reaPath(baseDir, HALT_FILE);
+    if (fs.existsSync(haltPath)) {
+        logger.info({
+            event: 'halt.acknowledged_at_startup',
+            message: 'HALT present at startup — every tool call will be denied until `.rea/HALT` is removed',
+        });
+    }
     // G11.3 — Codex availability probe. Observational only: a failed probe
     // NEVER fail-closes the gateway at startup. When the policy explicitly
     // opts out of Codex (`review.codex_required: false`), skip the probe
@@ -61,7 +279,22 @@ export async function runServe() {
         }
         codexProbe.start();
     }
+    // ── Pidfile + state (AFTER metrics boot so we persist the real port) ─────
+    const startedAt = new Date().toISOString();
+    const pidPath = writePidfile(baseDir);
+    const statePath = writeStateFile(baseDir, {
+        session_id: sessionId,
+        started_at: startedAt,
+        metrics_port: metricsServer?.port() ?? null,
+    });
+    let shuttingDown = false;
     const shutdown = async (signal) => {
+        // A second signal (e.g. SIGTERM then SIGINT) must NOT re-enter cleanup —
+        // `handle.stop()` is idempotent but `process.exit(0)` racing against
+        // still-running unlink calls would be messy. One-shot guard.
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
         log(`rea serve: received ${signal} — draining and shutting down`);
         codexProbe?.stop();
         try {
@@ -70,6 +303,20 @@ export async function runServe() {
         catch (e) {
             err(`shutdown error: ${e instanceof Error ? e.message : e}`);
         }
+        if (metricsServer !== undefined) {
+            try {
+                await metricsServer.close();
+            }
+            catch {
+                // Best-effort
+            }
+        }
+        // Remove the breadcrumbs LAST and ONLY if we still own them. Another
+        // `rea serve` in the same baseDir may have rewritten them — in that
+        // case the newer instance's `rea status` users should keep seeing
+        // "running".
+        cleanupPidIfOwned(pidPath);
+        cleanupStateIfOwned(statePath, sessionId);
         process.exit(0);
     };
     process.on('SIGTERM', () => void shutdown('SIGTERM'));
@@ -80,6 +327,27 @@ export async function runServe() {
     }
     catch (e) {
         err(`gateway start failed: ${e instanceof Error ? e.message : e}`);
+        // Clean up breadcrumbs before exit — a failed startup should not leave
+        // a stale pidfile claiming we're up. Ownership-aware so we don't nuke
+        // a sibling's breadcrumbs that raced in during our failing startup.
+        cleanupPidIfOwned(pidPath);
+        cleanupStateIfOwned(statePath, sessionId);
+        if (metricsServer !== undefined) {
+            try {
+                await metricsServer.close();
+            }
+            catch {
+                /* ignored */
+            }
+        }
         process.exit(1);
     }
 }
+// Exported for unit testing (the serve entry point itself is process-global).
+export const __TEST_INTERNALS = {
+    writeFileAtomic,
+    writePidfile,
+    writeStateFile,
+    cleanupPidIfOwned,
+    cleanupStateIfOwned,
+};

package/dist/cli/status.d.ts

@@ -0,0 +1,90 @@
+/**
+ * `rea status` — running-process introspection for `rea serve` (G5).
+ *
+ * `rea check` is the ON-DISK view: policy, HALT, recent audit entries. It
+ * works when no gateway is running.
+ *
+ * `rea status` is the LIVE view: is a gateway running for this cwd? What is
+ * its session id? What does the audit chain look like right now? Is HALT
+ * active?
+ *
+ * Detection strategy for "is serve running":
+ *   1. Read `.rea/serve.pid`.
+ *   2. If the pidfile exists, `kill(pid, 0)` to check liveness.
+ *   3. If kill throws ESRCH or EPERM, the pid is stale — treat as not-running
+ *      and surface that nuance in the output.
+ *
+ * Output modes:
+ *   - Default: human-pretty, matching the spacing used by `rea check`.
+ *   - `--json`: canonical JSON object, composable with jq and future tooling.
+ *
+ * This command is read-only. It does NOT clean up stale pidfiles (the serve
+ * process is the only writer). It does NOT run the full audit verifier —
+ * `rea audit verify` is the authoritative check and is expensive on large
+ * chains; here we just report line count, last timestamp, and a cheap "last
+ * record's stored hash is non-empty" heuristic as an integrity smoke signal.
+ */
+/**
+ * Strip every ASCII control code (C0 plus DEL) from a string. Defense
+ * against ANSI/OSC escape injection when a disk-controlled field reaches
+ * the operator's terminal via `console.log` in pretty mode.
+ *
+ * This is strict: every byte in 0x00-0x1F plus 0x7F is replaced with `?`.
+ * That drops CR/LF/TAB inside fields, which is fine — the fields this
+ * helper guards (halt_reason, session_id, started_at, last_timestamp,
+ * profile) are short identifiers or trimmed reasons, not multi-line
+ * narratives. Preserving TAB/LF would reopen the ESC+... attack surface
+ * because ANSI sequences begin with ESC (0x1B).
+ *
+ * SECURITY: Only pretty-print paths call this — JSON mode must not, since
+ * JSON.stringify already escapes control chars safely (`\u0000`), and a
+ * double-pass would corrupt legitimate audit values for downstream jq
+ * consumers.
+ *
+ * Exported so unit tests can assert the exact sanitization behavior.
+ */
+export declare function sanitizeForTerminal(value: string): string;
+export interface StatusOptions {
+    json?: boolean | undefined;
+}
+interface ServeLiveness {
+    running: boolean;
+    pid: number | null;
+    /** When pidfile exists but the process isn't responsive. */
+    stale: boolean;
+    /** From `.rea/serve.state.json`, when present. */
+    session_id: string | null;
+    started_at: string | null;
+    metrics_port: number | null;
+}
+interface AuditStats {
+    present: boolean;
+    lines: number;
+    last_timestamp: string | null;
+    /** Cheap chain smoke: last record has a 64-char hex hash. NOT a full verify. */
+    tail_hash_looks_valid: boolean;
+}
+interface PolicySummary {
+    profile: string;
+    autonomy_level: string;
+    blocked_paths_count: number;
+    codex_required: boolean;
+    halt_active: boolean;
+    halt_reason: string | null;
+}
+interface StatusPayload {
+    base_dir: string;
+    serve: ServeLiveness;
+    policy: PolicySummary;
+    audit: AuditStats;
+}
+/**
+ * Build the canonical payload. Separate from print paths so the JSON and
+ * pretty outputs stay in lockstep.
+ */
+export declare function computeStatusPayload(baseDir: string): StatusPayload;
+export declare function runStatus(options?: StatusOptions): void;
+export declare const INTERNAL: {
+    REA_DIR: string;
+};
+export {};