@bookedsolid/rea 0.2.1 → 0.4.0

package/dist/cli/status.js

@@ -0,0 +1,399 @@
+/**
+ * `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.
+ */
+import fs from 'node:fs';
+import { loadPolicy } from '../policy/loader.js';
+import { AUDIT_FILE, HALT_FILE, POLICY_FILE, REA_DIR, SERVE_PID_FILE, SERVE_STATE_FILE, err, exitWithMissingPolicy, log, reaPath, } from './utils.js';
+/**
+ * Tail window size for the audit summary. 64 KiB is more than enough to
+ * hold the last audit record (typical record ≪ 1 KiB) but small enough
+ * that reading it never spikes memory even on a multi-hundred-MB chain.
+ */
+const AUDIT_TAIL_WINDOW_BYTES = 64 * 1024;
+/**
+ * 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 function sanitizeForTerminal(value) {
+    return value.replace(/[\x00-\x1f\x7f\u200b-\u200f\u202a-\u202e\u2028\u2029\u2066-\u2069]/g, '?');
+}
+/**
+ * Null-safe wrapper for {@link sanitizeForTerminal} so call sites don't
+ * need a ternary at every disk-sourced field.
+ */
+function safePretty(value) {
+    if (value === null || value === undefined)
+        return null;
+    return sanitizeForTerminal(value);
+}
+/** Returns true if the OS confirms a live process at `pid`. */
+function isProcessAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        // Signal 0 tests existence without delivering a signal.
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        const code = e.code;
+        // EPERM means the process exists but belongs to another user — for our
+        // purposes (was-it-started-on-this-machine), that still counts as alive.
+        // ESRCH means no such process.
+        if (code === 'EPERM')
+            return true;
+        return false;
+    }
+}
+function readPidfile(baseDir) {
+    const p = reaPath(baseDir, SERVE_PID_FILE);
+    try {
+        const raw = fs.readFileSync(p, 'utf8').trim();
+        const n = Number.parseInt(raw, 10);
+        if (!Number.isInteger(n) || n <= 0)
+            return null;
+        return n;
+    }
+    catch {
+        return null;
+    }
+}
+function readServeState(baseDir) {
+    const p = reaPath(baseDir, SERVE_STATE_FILE);
+    try {
+        const raw = fs.readFileSync(p, 'utf8');
+        const parsed = JSON.parse(raw);
+        return {
+            session_id: typeof parsed.session_id === 'string' ? parsed.session_id : null,
+            started_at: typeof parsed.started_at === 'string' ? parsed.started_at : null,
+            metrics_port: typeof parsed.metrics_port === 'number' && Number.isInteger(parsed.metrics_port)
+                ? parsed.metrics_port
+                : null,
+        };
+    }
+    catch {
+        return { session_id: null, started_at: null, metrics_port: null };
+    }
+}
+function probeServe(baseDir) {
+    const pid = readPidfile(baseDir);
+    if (pid === null) {
+        // No pidfile — serve isn't running (at least not via `rea serve`).
+        return {
+            running: false,
+            pid: null,
+            stale: false,
+            session_id: null,
+            started_at: null,
+            metrics_port: null,
+        };
+    }
+    const alive = isProcessAlive(pid);
+    const state = readServeState(baseDir);
+    return {
+        running: alive,
+        pid,
+        stale: !alive,
+        session_id: state.session_id,
+        started_at: state.started_at,
+        metrics_port: state.metrics_port,
+    };
+}
+/**
+ * Count newline bytes in the file via a streaming read. O(file-size) in
+ * wall-clock but O(chunk-size) in memory — production chains can reach
+ * hundreds of MB; we must never hold the full file in a Buffer.
+ */
+function countLinesStreaming(filePath) {
+    let count = 0;
+    let fd;
+    try {
+        fd = fs.openSync(filePath, 'r');
+        const buf = Buffer.alloc(64 * 1024);
+        let bytesRead = 0;
+        while ((bytesRead = fs.readSync(fd, buf, 0, buf.length, null)) > 0) {
+            for (let i = 0; i < bytesRead; i++) {
+                if (buf[i] === 0x0a)
+                    count++;
+            }
+        }
+    }
+    catch {
+        // Partial result is still useful; return whatever we counted.
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                /* ignored */
+            }
+        }
+    }
+    return count;
+}
+/**
+ * Read up to `windowBytes` from the end of the file. Uses `pread` via a
+ * positioned `readSync` so we never materialize more than the window into
+ * memory, regardless of file size. The window is intentionally generous
+ * (default 64 KiB) vs. a typical ~200-byte audit record so the tail line
+ * is always fully represented.
+ */
+function readTailBytes(filePath, windowBytes) {
+    let fd;
+    try {
+        fd = fs.openSync(filePath, 'r');
+        const stat = fs.fstatSync(fd);
+        if (stat.size === 0)
+            return '';
+        const toRead = Math.min(windowBytes, stat.size);
+        const buf = Buffer.alloc(toRead);
+        const start = stat.size - toRead;
+        fs.readSync(fd, buf, 0, toRead, start);
+        return buf.toString('utf8');
+    }
+    catch {
+        return '';
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                /* ignored */
+            }
+        }
+    }
+}
+/**
+ * Quickly compute audit stats without running the full verifier. Memory
+ * posture:
+ *   - Line count is computed with a streaming newline scan (64 KiB chunk
+ *     buffer, regardless of total file size).
+ *   - `last_timestamp` + `tail_hash_looks_valid` come from a 64-KiB tail
+ *     window read via `readSync` at a positive offset — we never
+ *     materialize the full file.
+ *
+ * Missing / corrupt / empty files degrade to "present: false" or
+ * "lines: 0".
+ */
+function summarizeAudit(baseDir) {
+    const p = reaPath(baseDir, AUDIT_FILE);
+    if (!fs.existsSync(p)) {
+        return { present: false, lines: 0, last_timestamp: null, tail_hash_looks_valid: false };
+    }
+    // Streaming line count — O(file-size) CPU, O(chunk) memory.
+    // NOTE: countLinesStreaming and readTailBytes open the file independently.
+    // A concurrent append between the two opens can produce a `lines` count
+    // that is one higher than the tail record implies. This is a display-only
+    // function; the inconsistency is cosmetic and intentionally accepted.
+    const lineCount = countLinesStreaming(p);
+    // Tail-window scan for the last JSON record. If the last window isn't
+    // large enough to contain a full record (extremely rare: record >64 KiB),
+    // we degrade gracefully — the JSON parse just fails and we emit null.
+    const tailWindow = readTailBytes(p, AUDIT_TAIL_WINDOW_BYTES);
+    if (tailWindow.length === 0) {
+        return {
+            present: true,
+            lines: lineCount,
+            last_timestamp: null,
+            tail_hash_looks_valid: false,
+        };
+    }
+    // Find the last complete line. The first line in the window may be a
+    // partial record (we sliced mid-line); ignore it by finding the last
+    // newline-terminated segment.
+    const windowLines = tailWindow.split('\n').filter((line) => line.length > 0);
+    const tail = windowLines[windowLines.length - 1];
+    let last_timestamp = null;
+    let tail_hash_looks_valid = false;
+    if (tail !== undefined) {
+        try {
+            const rec = JSON.parse(tail);
+            if (typeof rec.timestamp === 'string')
+                last_timestamp = rec.timestamp;
+            if (typeof rec.hash === 'string' && /^[0-9a-f]{64}$/i.test(rec.hash)) {
+                tail_hash_looks_valid = true;
+            }
+        }
+        catch {
+            // Broken last line — leave both as default.
+        }
+    }
+    return { present: true, lines: lineCount, last_timestamp, tail_hash_looks_valid };
+}
+/**
+ * Build the canonical payload. Separate from print paths so the JSON and
+ * pretty outputs stay in lockstep.
+ */
+export function computeStatusPayload(baseDir) {
+    const policyPath = reaPath(baseDir, POLICY_FILE);
+    if (!fs.existsSync(policyPath)) {
+        exitWithMissingPolicy(policyPath);
+    }
+    const policy = loadPolicy(baseDir);
+    const haltPath = reaPath(baseDir, HALT_FILE);
+    const haltActive = fs.existsSync(haltPath);
+    let haltReason = null;
+    if (haltActive) {
+        try {
+            haltReason = fs.readFileSync(haltPath, 'utf8').trim();
+        }
+        catch {
+            haltReason = null;
+        }
+    }
+    return {
+        base_dir: baseDir,
+        serve: probeServe(baseDir),
+        policy: {
+            profile: policy.profile,
+            autonomy_level: policy.autonomy_level,
+            blocked_paths_count: policy.blocked_paths.length,
+            codex_required: policy.review?.codex_required !== false,
+            halt_active: haltActive,
+            halt_reason: haltReason,
+        },
+        audit: summarizeAudit(baseDir),
+    };
+}
+function printPretty(payload) {
+    // Every terminal-bound string field flows through `safePretty` or
+    // `sanitizeForTerminal` to prevent ANSI/OSC escape injection. This
+    // includes `base_dir`: although it originates from `process.cwd()`, the
+    // filesystem path is operator-controlled and a maliciously named directory
+    // can embed ESC/OSC bytes that inject terminal sequences when printed.
+    const p = payload.policy;
+    const s = payload.serve;
+    const a = payload.audit;
+    const baseDir = sanitizeForTerminal(payload.base_dir);
+    const profile = sanitizeForTerminal(p.profile);
+    const autonomy = sanitizeForTerminal(p.autonomy_level);
+    const haltReason = safePretty(p.halt_reason);
+    const sessionId = safePretty(s.session_id);
+    const startedAt = safePretty(s.started_at);
+    const lastTimestamp = safePretty(a.last_timestamp);
+    console.log('');
+    log(`Status — ${baseDir}`);
+    console.log('');
+    console.log('  Policy');
+    console.log(`    Profile:            ${profile}`);
+    console.log(`    Autonomy:           ${autonomy}`);
+    console.log(`    Blocked paths:      ${p.blocked_paths_count} entries`);
+    console.log(`    Codex required:     ${p.codex_required ? 'yes' : 'no'}`);
+    if (p.halt_active) {
+        console.log(`    HALT:               ACTIVE`);
+        if (haltReason !== null) {
+            console.log(`                        ${haltReason}`);
+        }
+    }
+    else {
+        console.log(`    HALT:               inactive`);
+    }
+    console.log('');
+    console.log('  rea serve');
+    if (!s.running) {
+        if (s.pid !== null && s.stale) {
+            console.log(`    Running:            no (stale pidfile — pid ${s.pid})`);
+        }
+        else {
+            console.log(`    Running:            no`);
+        }
+    }
+    else {
+        console.log(`    Running:            yes (pid ${s.pid ?? '?'})`);
+        if (sessionId !== null) {
+            console.log(`    Session id:         ${sessionId}`);
+        }
+        if (startedAt !== null) {
+            console.log(`    Started at:         ${startedAt}`);
+        }
+        if (s.metrics_port !== null) {
+            console.log(`    Metrics endpoint:   http://127.0.0.1:${s.metrics_port}/metrics`);
+        }
+        else {
+            console.log(`    Metrics endpoint:   disabled (set REA_METRICS_PORT to enable)`);
+        }
+    }
+    console.log('');
+    console.log('  Audit log');
+    if (!a.present) {
+        console.log(`    State:              not yet written`);
+    }
+    else if (a.lines === 0) {
+        console.log(`    State:              empty`);
+    }
+    else {
+        console.log(`    Lines:              ${a.lines}`);
+        if (lastTimestamp !== null) {
+            console.log(`    Last record at:     ${lastTimestamp}`);
+        }
+        console.log(`    Tail hash:          ${a.tail_hash_looks_valid ? 'looks valid' : 'unexpected shape — run `rea audit verify`'}`);
+    }
+    console.log('');
+}
+function printJson(payload) {
+    process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+}
+export function runStatus(options = {}) {
+    const baseDir = process.cwd();
+    let payload;
+    try {
+        payload = computeStatusPayload(baseDir);
+    }
+    catch (e) {
+        // `exitWithMissingPolicy` already handles the missing-policy path; any
+        // other loadPolicy error reaches here.
+        err(`Failed to build status: ${e instanceof Error ? e.message : String(e)}`);
+        process.exit(1);
+    }
+    if (options.json === true) {
+        printJson(payload);
+    }
+    else {
+        printPretty(payload);
+    }
+}
+// Exported so tests can construct the expected directory without duplicating
+// the path segment.
+export const INTERNAL = { REA_DIR };

package/dist/cli/utils.d.ts

@@ -9,6 +9,10 @@ export declare const POLICY_FILE = "policy.yaml";
 export declare const REGISTRY_FILE = "registry.yaml";
 export declare const HALT_FILE = "HALT";
 export declare const AUDIT_FILE = "audit.jsonl";
+/** Pidfile written by `rea serve` for `rea status` introspection (G5). */
+export declare const SERVE_PID_FILE = "serve.pid";
+/** State file written by `rea serve` carrying session_id + start metadata (G5). */
+export declare const SERVE_STATE_FILE = "serve.state.json";
 export declare function reaPath(baseDir: string, ...segments: string[]): string;
 /**
  * Standard log prefix so users notice the transition from reagent → rea.

package/dist/cli/utils.js

@@ -23,6 +23,10 @@ export const POLICY_FILE = 'policy.yaml';
 export const REGISTRY_FILE = 'registry.yaml';
 export const HALT_FILE = 'HALT';
 export const AUDIT_FILE = 'audit.jsonl';
+/** Pidfile written by `rea serve` for `rea status` introspection (G5). */
+export const SERVE_PID_FILE = 'serve.pid';
+/** State file written by `rea serve` carrying session_id + start metadata (G5). */
+export const SERVE_STATE_FILE = 'serve.state.json';
 export function reaPath(baseDir, ...segments) {
     return path.join(baseDir, REA_DIR, ...segments);
 }

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

@@ -0,0 +1,116 @@
+/**
+ * Audit rotation (G1). Size- and age-based rotation for `.rea/audit.jsonl`
+ * that preserves hash-chain continuity across the rotation boundary.
+ *
+ * ## Triggers
+ *
+ * Rotation fires when EITHER threshold is crossed:
+ *
+ * - `max_bytes` — the current `audit.jsonl` is at or above this many bytes.
+ *   Default when the policy block is present but `max_bytes` is unset:
+ *   `DEFAULT_MAX_BYTES` (50 MiB).
+ * - `max_age_days` — the first record's `timestamp` is older than this many
+ *   days. Default when unset: `DEFAULT_MAX_AGE_DAYS` (30).
+ *
+ * Back-compat: if the `audit.rotation` policy block is ABSENT entirely,
+ * rotation is DISABLED. Defaults only apply when the operator has opted in
+ * by declaring the block (even empty). This is deliberate — we do not want
+ * a 0.2.x install to observe new file-movement behavior on 0.3.0 upgrade
+ * without being asked.
+ *
+ * ## Rotation marker
+ *
+ * On rotation, the current file is renamed to `audit-YYYYMMDD-HHMMSS.jsonl`
+ * in the same directory. A fresh `audit.jsonl` is created containing EXACTLY
+ * one record: a rotation marker.
+ *
+ *     tool_name:          'audit.rotation'
+ *     server_name:        'rea'
+ *     status:             'allowed'
+ *     tier:               'read'
+ *     autonomy_level:     'system'
+ *     prev_hash:          hash of the LAST record in the rotated file
+ *     metadata.rotated_from: the rotated filename (basename)
+ *     metadata.rotated_at:   ISO-8601 instant of rotation
+ *
+ * The marker's `prev_hash` is the chain bridge — an operator verifying the
+ * chain with `rea audit verify --since <rotated-file>` walks rotated →
+ * marker → current and every transition must line up.
+ *
+ * ## Concurrency
+ *
+ * `maybeRotate` is called BEFORE the per-append lock is acquired. It takes
+ * its own short-lived lock on `.rea/` to perform the rename + marker write
+ * atomically. Callers that beat the rotator to the lock simply append to
+ * the (now fresh) file — correctness is preserved because the rotation
+ * marker is a legitimate chain anchor.
+ */
+import type { Policy, AuditRotationPolicy } from '../../policy/types.js';
+/** 50 MiB. Only applied when the operator has declared `audit.rotation`. */
+export declare const DEFAULT_MAX_BYTES: number;
+/** 30 days. Only applied when the operator has declared `audit.rotation`. */
+export declare const DEFAULT_MAX_AGE_DAYS = 30;
+export declare const ROTATION_TOOL_NAME = "audit.rotation";
+export declare const ROTATION_SERVER_NAME = "rea";
+export interface RotationResult {
+    rotated: boolean;
+    /** Absolute path of the rotated file (the `audit-TIMESTAMP.jsonl` file). */
+    rotatedTo?: string;
+}
+/** Resolve effective thresholds from policy. `undefined` thresholds disable that trigger. */
+interface EffectiveThresholds {
+    maxBytes: number | undefined;
+    maxAgeMs: number | undefined;
+}
+/**
+ * Compute the effective rotation thresholds from policy. If the operator has
+ * NOT declared an `audit.rotation` block, BOTH thresholds are undefined and
+ * rotation is disabled (back-compat with 0.2.x).
+ *
+ * If the block IS declared but individual knobs are missing, apply the
+ * documented defaults.
+ */
+declare function effectiveThresholds(policy: Policy | undefined): EffectiveThresholds;
+/**
+ * Build the rotation timestamp filename. UTC for sortability.
+ * Format: `audit-YYYYMMDD-HHMMSS.jsonl`. Collisions (two rotations in the
+ * same second) are resolved by appending `-1`, `-2`, etc.
+ */
+export declare function rotationFilename(at: Date): string;
+/**
+ * Decide whether the current audit file has crossed any rotation threshold.
+ * Exported for testing.
+ */
+export declare function shouldRotate(auditFile: string, thresholds: EffectiveThresholds, now?: Date): Promise<boolean>;
+/**
+ * Perform the rotation unconditionally. Assumes the caller has already
+ * determined rotation is warranted and holds (or is about to acquire) any
+ * outer locks. `performRotation` takes its own lock on `.rea/` to make the
+ * rename + marker write atomic w.r.t. other append-path lockers.
+ *
+ * Returns `{ rotated: false }` if the audit file is empty or missing — an
+ * empty file is a no-op by design (see `rea audit rotate` empty-case).
+ */
+export declare function performRotation(auditFile: string, now?: Date): Promise<RotationResult>;
+/**
+ * Called by the append path BEFORE acquiring its own lock. Cheap when no
+ * rotation is due (one stat, maybe one 64 KiB read for age check); idempotent
+ * when rotation IS due (performRotation re-checks under the lock).
+ *
+ * Never throws. On any error, logs to stderr and returns `rotated: false`
+ * — a broken rotator must NOT break the audit append.
+ */
+export declare function maybeRotate(auditFile: string, policy: Policy | undefined, now?: Date): Promise<RotationResult>;
+/**
+ * CLI-invoked force rotation (`rea audit rotate`). Unlike `maybeRotate` this
+ * DOES ignore thresholds — the operator asked explicitly — but empty files
+ * are still a no-op because rotating an empty chain produces a marker with
+ * no predecessor.
+ */
+export declare function forceRotate(auditFile: string, now?: Date): Promise<RotationResult>;
+/**
+ * Exposed for tests/callers that already know the policy shape. Tests that
+ * want to stub thresholds can call `performRotation` directly.
+ */
+export { effectiveThresholds as _effectiveThresholds };
+export type { EffectiveThresholds, AuditRotationPolicy };