@spinabot/brigade 0.1.1 → 1.0.0

package/dist/core/event-logger.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Brigade event logger — writes every Pi session event to a JSONL file
+ * under `~/.brigade/logs/<YYYY-MM-DD>.jsonl`. One file per day, append-only.
+ *
+ * Why: Brigade has no other log sink. When something goes weird (model
+ * hangs, hallucination, mid-turn switch confusion), the user can `cat`
+ * today's log file and see the actual event sequence — including timestamps,
+ * tool calls, errors, retries, all of it.
+ *
+ * Format: one JSON object per line, with these always-present fields:
+ *   { ts: <ISO 8601>, type: <event.type>, ... event-specific fields ... }
+ *
+ * Failure mode: if the log file can't be opened or a write fails, the logger
+ * silently degrades — log loss is preferable to crashing the user's chat.
+ * Errors are surfaced to stderr at startup ONLY (not on every write).
+ */
+import type { AgentSession } from "@mariozechner/pi-coding-agent";
+/** Drained by the gateway on shutdown. */
+export declare function awaitEventLogFlush(): Promise<void>;
+/**
+ * Subscribe to a session's events and write each one to today's log file.
+ * Returns an unsubscribe function — call it when the session ends to detach.
+ *
+ * One unsub per session is sufficient; we don't deduplicate.
+ */
+export declare function attachEventLogger(session: AgentSession): () => void;
+/** Path of today's log file — useful for `/log` slash command later. */
+export declare function getTodayLogPath(): string;
+/**
+ * Append a single event record to today's log JSONL. Same write path used
+ * by `attachEventLogger` (best-effort, swallowed on FS errors, rotated
+ * when the daily file exceeds the size cap).
+ *
+ * The record SHOULD carry at minimum `ts` (ISO 8601) + `type` (string), but
+ * we don't enforce — log readers tolerate missing fields and skip malformed
+ * lines individually.
+ */
+export declare function appendSessionEvent(record: Record<string, unknown>): void;
+/**
+ * Tail-read JSONL records from a day's log file.
+ *
+ *   opts.day      — YYYY-MM-DD; default today
+ *   opts.maxBytes — only the LAST N bytes of the file are parsed (default 64 KiB)
+ *
+ * Returns the parsed records in file order (oldest-first within the tail
+ * slice). Malformed lines are skipped silently — one bad line never breaks
+ * the read.
+ */
+export declare function readSessionEventTail(opts?: {
+    day?: string;
+    maxBytes?: number;
+}): Record<string, unknown>[];
+/**
+ * Pull the most recent error-shaped event out of today's JSONL log. Used by
+ * `brigade gateway status` (and friends) to surface a "last error" hint when
+ * the gateway is stopped — operator gets a breadcrumb pointing at the cause
+ * without having to grep the file themselves.
+ *
+ * Returns `undefined` when:
+ *   - The log file doesn't exist yet (first-run).
+ *   - No event in the last `lookbackBytes` slice looks like an error.
+ *   - File is unreadable.
+ *
+ * Surfaces a "Last gateway error: ..." snapshot for status output.
+ */
+export interface LastErrorSnapshot {
+    ts: string;
+    message: string;
+    type?: string;
+}
+export declare function getLastLoggedError(opts?: {
+    lookbackBytes?: number;
+}): LastErrorSnapshot | undefined;
+//# sourceMappingURL=event-logger.d.ts.map

package/dist/core/event-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-logger.d.ts","sourceRoot":"","sources":["../../src/core/event-logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAqB,MAAM,+BAA+B,CAAC;AAoDrF,0CAA0C;AAC1C,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CAIxD;AA0BD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,IAAI,CAoDnE;AA2GD,wEAAwE;AACxE,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAmBD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAaxE;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,GAAE;IAC1C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;CACb,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAoCjC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,kBAAkB,CAAC,IAAI,GAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,iBAAiB,GAAG,SAAS,CAwDvG"}

package/dist/core/event-logger.js

@@ -14,11 +14,73 @@
  * silently degrades — log loss is preferable to crashing the user's chat.
  * Errors are surfaced to stderr at startup ONLY (not on every write).
  */
-import { appendFileSync, existsSync, mkdirSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, renameSync, statSync, unlinkSync } from "node:fs";
 import * as path from "node:path";
+import { tryGetRuntimeContext } from "../storage/runtime-context.js";
 import { BRIGADE_DIR } from "./config.js";
+/* ───────────────────── convex-mode batched sink ───────────────────── */
+// Pi fires 4-8 events per tool call — one mutation per event would be far
+// too chatty. Rows buffer here and drain in order; flush every 500 ms or
+// 100 rows, whichever first. Log rows are observability (loss-tolerant on
+// hard kill); the gateway shutdown drains the chain.
+const eventRowBuffer = [];
+let eventFlushChain = Promise.resolve();
+let eventFlushTimer;
+const EVENT_FLUSH_MS = 500;
+const EVENT_FLUSH_MAX = 100;
+function enqueueSessionEventRow(store, row) {
+    eventRowBuffer.push(row);
+    if (eventRowBuffer.length >= EVENT_FLUSH_MAX) {
+        void flushSessionEventRows(store);
+        return;
+    }
+    if (!eventFlushTimer) {
+        eventFlushTimer = setTimeout(() => {
+            eventFlushTimer = undefined;
+            void flushSessionEventRows(store);
+        }, EVENT_FLUSH_MS);
+        eventFlushTimer.unref?.();
+    }
+}
+function flushSessionEventRows(store) {
+    if (eventFlushTimer) {
+        clearTimeout(eventFlushTimer);
+        eventFlushTimer = undefined;
+    }
+    const rows = eventRowBuffer.splice(0, eventRowBuffer.length);
+    if (rows.length === 0)
+        return eventFlushChain;
+    eventFlushChain = eventFlushChain
+        .then(async () => {
+        for (const row of rows) {
+            await store.logs.appendSessionEvent(row);
+        }
+    })
+        .catch(() => {
+        /* observability rows — drop on backend failure, never crash a turn */
+    });
+    return eventFlushChain;
+}
+/** Drained by the gateway on shutdown. */
+export async function awaitEventLogFlush() {
+    const rctx = tryGetRuntimeContext();
+    if (rctx?.mode === "convex")
+        await flushSessionEventRows(rctx.store);
+    await eventFlushChain;
+}
 /** Directory we append to. Created lazily on first write. */
 const LOGS_DIR = path.join(BRIGADE_DIR, "logs");
+/**
+ * Per-file size cap. Once today's `.jsonl` exceeds this, we rotate to
+ * `<day>.jsonl.1` (rotating any prior `.1` to `.2`, up to MAX_LOG_BACKUPS).
+ * Brigade's surface is smaller than a multi-tenant gateway so 100 MB is
+ * plenty in normal use; runaway days (broken stream loops, attack-style
+ * spam) are still bounded.
+ */
+const MAX_LOG_FILE_BYTES = 100 * 1024 * 1024;
+const MAX_LOG_BACKUPS = 4;
+/** Check size every N writes so the stat call doesn't dominate hot paths. */
+const SIZE_CHECK_EVERY_N_WRITES = 32;
 /** YYYY-MM-DD using UTC so log files don't roll over at confusing local times. */
 function todayFile() {
     const now = new Date();
@@ -35,6 +97,7 @@ function todayFile() {
  */
 export function attachEventLogger(session) {
     let warnedOnce = false;
+    let writeCount = 0;
     const ensureDir = () => {
         try {
             if (!existsSync(LOGS_DIR))
@@ -51,14 +114,30 @@ export function attachEventLogger(session) {
         }
     };
     const writeEvent = (event) => {
-        if (!ensureDir())
-            return;
         // Build the row. Strip massive fields (full message contents repeated on
         // every delta) — we want the log to be greppable, not a token-by-token
         // replay. Tool calls, errors, retries, state changes are kept full.
         const row = serializeForLog(event);
+        // Convex mode — batched write-behind to the sessionEvents table. This
+        // is the hottest log path in Brigade (4-8 events per tool call), so
+        // rows buffer and flush in batches; the chat never blocks on it.
+        const rctx = tryGetRuntimeContext();
+        if (rctx?.mode === "convex") {
+            enqueueSessionEventRow(rctx.store, row);
+            return;
+        }
+        if (!ensureDir())
+            return;
+        const filePath = todayFile();
+        // Periodically check file size and rotate before write to keep log
+        // files bounded. Cheap stat every N writes — checking on every write
+        // would dominate hot paths during streaming.
+        if (writeCount % SIZE_CHECK_EVERY_N_WRITES === 0) {
+            rotateIfTooLarge(filePath);
+        }
+        writeCount++;
         try {
-            appendFileSync(todayFile(), JSON.stringify(row) + "\n", "utf8");
+            appendFileSync(filePath, JSON.stringify(row) + "\n", "utf8");
         }
         catch {
             /* drop the line — never crash the chat for a log write */
@@ -66,6 +145,54 @@ export function attachEventLogger(session) {
     };
     return session.subscribe(writeEvent);
 }
+/**
+ * Rotate the file if it's over MAX_LOG_FILE_BYTES. Series:
+ *   <path>.jsonl     → <path>.jsonl.1   (most recent backup)
+ *   <path>.jsonl.1   → <path>.jsonl.2
+ *   ...
+ *   <path>.jsonl.<MAX_LOG_BACKUPS-1>   → unlinked (oldest dropped)
+ *
+ * All operations are best-effort; rotation failures fall through silently
+ * so the next append still has a chance to succeed (worst case: no rotation
+ * happened, file keeps growing, next check tries again).
+ */
+function rotateIfTooLarge(filePath) {
+    let size;
+    try {
+        size = statSync(filePath).size;
+    }
+    catch {
+        // File doesn't exist yet — nothing to rotate.
+        return;
+    }
+    if (size < MAX_LOG_FILE_BYTES)
+        return;
+    // Drop the oldest backup, then shift the rest down.
+    const oldest = `${filePath}.${MAX_LOG_BACKUPS}`;
+    try {
+        unlinkSync(oldest);
+    }
+    catch {
+        /* may not exist — fine */
+    }
+    for (let n = MAX_LOG_BACKUPS - 1; n >= 1; n--) {
+        const src = `${filePath}.${n}`;
+        const dst = `${filePath}.${n + 1}`;
+        try {
+            renameSync(src, dst);
+        }
+        catch {
+            /* may not exist — fine */
+        }
+    }
+    try {
+        renameSync(filePath, `${filePath}.1`);
+    }
+    catch {
+        // If we can't rotate, leave the file alone. Caller will append on
+        // top and the next size-check tries again — better than throwing.
+    }
+}
 /**
  * Convert a Pi event into a log-friendly row. The full event payload often
  * includes the cumulative assistant message on every delta — that turns a
@@ -94,8 +221,17 @@ function serializeForLog(event) {
             };
         }
         case "message_end":
-            // Final message — full content kept for replay/debugging.
-            return { ...base, role: ev.message?.role, content: ev.message?.content, stopReason: ev.message?.stopReason };
+            // Final message — full content kept for replay/debugging. Pi puts a
+            // provider/transport failure here as stopReason "error"/"aborted" +
+            // `errorMessage`; capture it so a failed turn is diagnosable from the
+            // log instead of showing as a mysterious empty message.
+            return {
+                ...base,
+                role: ev.message?.role,
+                content: ev.message?.content,
+                stopReason: ev.message?.stopReason,
+                errorMessage: ev.message?.errorMessage,
+            };
         case "tool_execution_start":
             return { ...base, toolCallId: ev.toolCallId, toolName: ev.toolName, args: ev.args };
         case "tool_execution_end":
@@ -119,4 +255,161 @@ function serializeForLog(event) {
 export function getTodayLogPath() {
     return todayFile();
 }
+// ============================================================================
+// Public append + tail helpers (added in Phase 2 PR4 so the BrigadeStore
+// `LogStore` adapter can wrap event-logging through a typed seam instead of
+// only writing via `attachEventLogger`). The on-disk format is unchanged —
+// these helpers just expose the same JSONL pattern the existing subscribe
+// path uses.
+// ============================================================================
+/** Resolve which log file a day-anchored read should target. */
+function logPathFor(day) {
+    if (!day)
+        return todayFile();
+    // Defensive: only allow YYYY-MM-DD (8 digits with dashes). Anything else
+    // falls back to today so a malformed `day` arg can't escape the logs dir.
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(day))
+        return todayFile();
+    return path.join(LOGS_DIR, `${day}.jsonl`);
+}
+/**
+ * Append a single event record to today's log JSONL. Same write path used
+ * by `attachEventLogger` (best-effort, swallowed on FS errors, rotated
+ * when the daily file exceeds the size cap).
+ *
+ * The record SHOULD carry at minimum `ts` (ISO 8601) + `type` (string), but
+ * we don't enforce — log readers tolerate missing fields and skip malformed
+ * lines individually.
+ */
+export function appendSessionEvent(record) {
+    try {
+        if (!existsSync(LOGS_DIR))
+            mkdirSync(LOGS_DIR, { recursive: true });
+    }
+    catch {
+        return; // dir unwritable — drop the line
+    }
+    const filePath = todayFile();
+    rotateIfTooLarge(filePath);
+    try {
+        appendFileSync(filePath, JSON.stringify(record) + "\n", "utf8");
+    }
+    catch {
+        /* drop the line — never crash on a log write */
+    }
+}
+/**
+ * Tail-read JSONL records from a day's log file.
+ *
+ *   opts.day      — YYYY-MM-DD; default today
+ *   opts.maxBytes — only the LAST N bytes of the file are parsed (default 64 KiB)
+ *
+ * Returns the parsed records in file order (oldest-first within the tail
+ * slice). Malformed lines are skipped silently — one bad line never breaks
+ * the read.
+ */
+export function readSessionEventTail(opts = {}) {
+    const filePath = logPathFor(opts.day);
+    let stat;
+    try {
+        stat = statSync(filePath);
+    }
+    catch {
+        return [];
+    }
+    const lookback = Math.max(1, opts.maxBytes ?? 64 * 1024);
+    const start = Math.max(0, stat.size - lookback);
+    let chunk;
+    try {
+        const fs = require("node:fs");
+        const fd = fs.openSync(filePath, "r");
+        try {
+            const len = stat.size - start;
+            chunk = Buffer.alloc(len);
+            fs.readSync(fd, chunk, 0, len, start);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const raw of chunk.toString("utf8").split("\n")) {
+        const line = raw.trim();
+        if (!line)
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            // Malformed line — could be a truncated mid-write from a crash.
+            // Skip rather than poisoning the whole tail read.
+        }
+    }
+    return out;
+}
+export function getLastLoggedError(opts = {}) {
+    const filePath = todayFile();
+    let stat;
+    try {
+        stat = statSync(filePath);
+    }
+    catch {
+        return undefined;
+    }
+    const lookback = opts.lookbackBytes ?? 64 * 1024;
+    const start = Math.max(0, stat.size - lookback);
+    let chunk;
+    try {
+        // Read a tail slice synchronously — this runs from the status command,
+        // never on a hot path. Reading the whole file would be wasteful on big
+        // logs (size-cap is 100 MB).
+        const fs = require("node:fs");
+        const fd = fs.openSync(filePath, "r");
+        try {
+            const len = stat.size - start;
+            chunk = Buffer.alloc(len);
+            fs.readSync(fd, chunk, 0, len, start);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch {
+        return undefined;
+    }
+    const lines = chunk.toString("utf8").split("\n");
+    // Scan tail-to-head for the most recent error-shaped row.
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const raw = lines[i]?.trim();
+        if (!raw)
+            continue;
+        let row;
+        try {
+            row = JSON.parse(raw);
+        }
+        catch {
+            continue;
+        }
+        const type = typeof row.type === "string" ? row.type : undefined;
+        // Brigade's serializer surfaces the following error-shaped events:
+        //   tool_execution_end (isError === true)
+        //   auto_retry_start (errorMessage)
+        //   compaction_end (aborted, errorMessage)
+        //   agent_end with stopReason === "error" — but that's not directly logged
+        if (type === "tool_execution_end" && row.isError === true) {
+            const result = typeof row.result === "string" ? row.result : JSON.stringify(row.result);
+            return { ts: String(row.ts ?? ""), type, message: `tool ${row.toolName} failed: ${result}` };
+        }
+        if (type === "auto_retry_start" && typeof row.errorMessage === "string") {
+            return { ts: String(row.ts ?? ""), type, message: `auto retry: ${row.errorMessage}` };
+        }
+        if (type === "compaction_end" && row.aborted === true && typeof row.errorMessage === "string") {
+            return { ts: String(row.ts ?? ""), type, message: `compaction aborted: ${row.errorMessage}` };
+        }
+    }
+    return undefined;
+}
 //# sourceMappingURL=event-logger.js.map

package/dist/core/event-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-logger.js","sourceRoot":"","sources":["../../src/core/event-logger.ts"],"names":[],"mappings":"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"}

package/dist/core/exec-approvals.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Brigade exec-approvals — synchronous tool-approval gate for `bash` and any
+ * future tool that touches the operator's machine.
+ *
+ * v1 shape (per-agent, file-backed allowlist):
+ *   - Operator approves once → command (or pattern) lands in an allowlist file
+ *     at `<agentDir>/exec-approvals.json` (one file per agent id).
+ *   - Subsequent invocations of the same command short-circuit `decideApproval`
+ *     → returns `"allow"` without prompting.
+ *   - Unknown commands return `"prompt"`; the caller (bash tool) then surfaces
+ *     a TUI prompt and writes the decision back via `recordApproval`.
+ *   - Hard-deny patterns (rm -rf /, dd to /dev/sda, etc.) return `"deny"` and
+ *     are NEVER stored. Caller rejects without prompting the operator.
+ *
+ * Per-agent layout:
+ *   - Each agent gets its own allowlist at `<agentDir>/exec-approvals.json`,
+ *     matching how `auth-profiles.json` and `profile-state.json` are scoped.
+ *     A `rm -rf <agentDir>` reset truly wipes that agent's trust state along
+ *     with everything else.
+ *   - The DEFAULT agent ("main") migrates the legacy global file at
+ *     `~/.brigade/exec-approvals.json` on first read: if the global exists and
+ *     the per-agent file doesn't, the contents move into `<agentDir>/exec-
+ *     approvals.json` and the global is renamed to `.migrated`. Idempotent —
+ *     re-running after migration is a no-op.
+ *
+ * Multi-process cache discipline (matters for long-lived gateway + concurrent
+ * `brigade exec allow` from another shell):
+ *   - The file's mtime is captured at load time (per-agent cache entry). Every
+ *     `decideApproval` / `recordApproval` stats the file FIRST; if mtime moved,
+ *     the entry is dropped and reloaded. This makes the second-shell flow
+ *     ("operator runs `brigade exec allow X --agent main` while the TUI is
+ *     mid-turn") work without restart — the next bash refusal in the running
+ *     TUI picks up the new approval on its next call.
+ *   - Cost: one stat() per gate call. Negligible (microseconds) vs the
+ *     correctness gain.
+ *
+ * Concurrent-writer race avoidance (two `brigade exec allow` shells racing):
+ *   - Every write reads FRESH from disk first (bypassing cache), merges the
+ *     in-memory mutation with whatever's on disk RIGHT NOW, then writes the
+ *     union atomically via PID-tagged tempfile + rename. Last writer wins
+ *     PER COMMAND, but no entries are LOST.
+ *
+ * File-permission discipline:
+ *   - On write we chmod 0600 (operator-only read/write). Allowlist entries
+ *     can reveal a lot about an operator's workflow (cloud creds, secrets
+ *     paths, internal hostnames) — group/world access is never warranted.
+ *   - The check is best-effort on Windows (chmod is a partial-fidelity op
+ *     under NTFS) but defensible on POSIX hosts where the threat is real.
+ *
+ * Symlink-target guard:
+ *   - Before writing, lstat the destination — if it's a symbolic link, refuse.
+ *     This catches the footgun where an operator (or a malicious dotfile in
+ *     a shared system) plants `exec-approvals.json` as a symlink pointing at
+ *     `/etc/passwd`.
+ *
+ * Storage layout (`<agentDir>/exec-approvals.json`):
+ *   {
+ *     "version": 1,
+ *     "commands": ["ls -la", "git status", "npm test"],
+ *     "patterns": ["^git diff( |$)", "^cat package\\.json$"]
+ *   }
+ */
+export type ApprovalDecision = "allow" | "deny" | "prompt";
+/**
+ * Resolve the absolute path to an agent's exec-approvals.json. Pure function
+ * over `resolveAgentDir` so callers (CLI, diagnostics) can discover the path
+ * without loading the file.
+ */
+export declare function resolveExecApprovalsPath(agentId?: string | undefined): string;
+/** Convex-mode boot hydration — install the agent's allowlist into the
+ *  module cache so the synchronous gate (`decideApproval`) works without
+ *  disk or network on the hot path. Called from storage/boot.ts. */
+export declare function primeApprovalsCache(agentId: string, contents: {
+    commands: string[];
+    patterns: string[];
+}): void;
+/** Resolves when every approval mutation enqueued so far reached the
+ *  backend (convex mode). */
+export declare function awaitApprovalsFlush(): Promise<void>;
+/**
+ * Decide whether a command can run without prompting the operator.
+ *
+ *   - `"deny"` — hard-blocked pattern; caller MUST refuse and never prompt.
+ *   - `"allow"` — allowlist hit; caller can run immediately.
+ *   - `"prompt"` — caller should surface a TUI prompt; on operator approval,
+ *     caller passes the decision back via `recordApproval`.
+ *
+ * `agentId` selects which per-agent allowlist to consult. Defaults to the
+ * canonical agent so legacy single-agent callers keep working unchanged.
+ */
+export declare function decideApproval(command: string, agentId?: string | undefined): ApprovalDecision;
+/**
+ * Test-time helper exported so other modules can ask "is this command in
+ * the hard-deny set?" without having to re-implement the regex list.
+ */
+export declare function isHardDenied(command: string): boolean;
+/**
+ * Does a given regex pattern match ANY hard-denied probe command? Used by
+ * `recordApproval(kind: "pattern")` to refuse footgun-shaped patterns at
+ * write time.
+ */
+export declare function patternMatchesHardDeny(pattern: string): boolean;
+/**
+ * Persist an operator's "always allow" approval to the per-agent allowlist.
+ * `kind: "exact"` adds the command verbatim; `kind: "pattern"` adds it as a
+ * regex. Either way the change lands on disk before the function returns.
+ *
+ * Concurrent-write safety: re-reads FRESH from disk (bypassing cache) and
+ * merges the addition INTO that fresh snapshot, so a sibling process's recent
+ * write isn't clobbered.
+ */
+export declare function recordApproval(command: string, kind?: "exact" | "pattern", agentId?: string | undefined): void;
+/**
+ * Remove an exact command OR a pattern from the per-agent allowlist. Looks
+ * in BOTH lists — if the value matches either, it's dropped. Returns the
+ * count of entries actually removed.
+ */
+export declare function removeApproval(value: string, agentId?: string | undefined): {
+    removedCommands: number;
+    removedPatterns: number;
+};
+/**
+ * Thrown by `recordApproval` (or the writer's symlink guard) when the
+ * caller asks Brigade to write something it refuses to write.
+ */
+export declare class BrigadeApprovalRefusedError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown by the loader when the file's schema version isn't supported.
+ */
+export declare class BrigadeApprovalFileVersionError extends Error {
+    constructor(message: string);
+}
+/**
+ * Test-only helper. Wipes the in-memory cache so the next call to
+ * `decideApproval` re-reads from disk.
+ */
+export declare function _resetApprovalsCacheForTests(): void;
+/**
+ * Return the absolute path to the approvals file for `agentId`. Useful for
+ * `brigade doctor` + `brigade status` so the operator knows where the trust
+ * list lives.
+ */
+export declare function getApprovalsFilePath(agentId?: string | undefined): string;
+/**
+ * Read-only summary of the on-disk allowlist for the given agent. Surfaced
+ * by `brigade status` / `brigade doctor` so the operator can see at a glance
+ * how many commands are approved and where the file lives.
+ *
+ * Always reads via the cache so a long-lived gateway sees the same view as
+ * any in-flight gate call. Returns zeros when the file is missing or
+ * unparseable rather than throwing — the calling diagnostic surface decides
+ * how to render an empty state. A version mismatch is reported via the
+ * `error` field instead of throwing so `brigade doctor` can render a
+ * remediation hint without crashing.
+ */
+/**
+ * Enumerate every approval row for an agent. Returned in a stable shape:
+ *   { commands: string[], patterns: string[] }
+ *
+ * Used by the `brigade store migrate` engine — earlier versions only had
+ * `readApprovalsSummary` (counts), which forced operators to copy entries
+ * by hand. This enumerator exposes the underlying data without leaking
+ * the on-disk file shape.
+ */
+export declare function listApprovals(agentId?: string | undefined): {
+    commands: string[];
+    patterns: string[];
+};
+export declare function readApprovalsSummary(agentId?: string | undefined): {
+    commandCount: number;
+    patternCount: number;
+    filePath: string;
+    fileExists: boolean;
+    error?: string;
+};
+//# sourceMappingURL=exec-approvals.d.ts.map

package/dist/core/exec-approvals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec-approvals.d.ts","sourceRoot":"","sources":["../../src/core/exec-approvals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AAWH,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;AA8D3D;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,GAAE,MAAM,GAAG,SAA4B,GAAG,MAAM,CAE/F;AA0ID;;oEAEoE;AACpE,wBAAgB,mBAAmB,CAClC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,GAClD,IAAI,CAUN;AAMD;6BAC6B;AAC7B,wBAAgB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAEnD;AAgFD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC7B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,MAAM,GAAG,SAA4B,GAC5C,gBAAgB,CAuBlB;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAOrD;AAyBD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAW/D;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC7B,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,OAAO,GAAG,SAAmB,EACnC,OAAO,GAAE,MAAM,GAAG,SAA4B,GAC5C,IAAI,CA6DN;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC7B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,MAAM,GAAG,SAA4B,GAC5C;IAAE,eAAe,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAA;CAAE,CA+CtD;AAED;;;GAGG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;gBACzC,OAAO,EAAE,MAAM;CAI3B;AAED;;GAEG;AACH,qBAAa,+BAAgC,SAAQ,KAAK;gBAC7C,OAAO,EAAE,MAAM;CAI3B;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,IAAI,IAAI,CAGnD;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CACnC,OAAO,GAAE,MAAM,GAAG,SAA4B,GAC5C,MAAM,CAER;AAED;;;;;;;;;;;GAWG;AACH;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC5B,OAAO,GAAE,MAAM,GAAG,SAA4B,GAC5C;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAQ5C;AAED,wBAAgB,oBAAoB,CACnC,OAAO,GAAE,MAAM,GAAG,SAA4B,GAC5C;IACF,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CACf,CAyBA"}