instar 1.3.230 → 1.3.232

package/dist/monitoring/McpProcessReaper.d.ts

@@ -0,0 +1,135 @@
+/**
+ * McpProcessReaper — Option B of the MCP-leak fix (Codey's design in
+ * `.instar/apprenticeship/codey-task-mcp-leak-reaper.md`).
+ *
+ * The problem: a session spawns MCP-server children (Playwright, mcp-remote,
+ * instar stdio). Killing the session's main pid does NOT cascade to those
+ * children — they re-parent (to PID 1 / launchd) or are held by an npm-exec
+ * wrapper and survive for days. The fleet accumulated ~80 such leaked procs,
+ * up to 5 days old, as a persistent load floor. `OrphanProcessReaper` reaps the
+ * session-level CLI proc but not these MCP *descendants*.
+ *
+ * This is a descendant-aware SWEEP (a sibling reaper, NOT a change to the
+ * shared OrphanProcessReaper / ReapGuard path — zero blast radius on the
+ * working reaper). For each allow-listed MCP proc it resolves the owning tmux
+ * session by walking the ppid chain, and reaps ONLY when the proc is old AND
+ * its owning session is a dead/stale *instar* session or fully orphaned. It
+ * NEVER touches a proc under a live/tracked session, nor under an external
+ * (non-instar) tmux session.
+ *
+ * Ships DARK + DRY-RUN by default (kills processes — same posture as
+ * SessionReaper / AgentWorktreeReaper). Every decision is audited.
+ */
+import { EventEmitter } from 'node:events';
+import { matchMcpSignature, type McpProcessSignature } from './mcpProcessSignatures.js';
+export interface McpProcessReaperConfig {
+    enabled: boolean;
+    dryRun: boolean;
+    /** A proc younger than this is always kept (a starting session's children). */
+    minAgeMs: number;
+    reapIntervalMs: number;
+    /** Bounded blast radius per pass. */
+    maxReapsPerPass: number;
+    /** Max ppid hops when resolving a proc's owning tmux session. */
+    maxAncestorHops: number;
+}
+export declare const DEFAULT_MCP_PROCESS_REAPER_CONFIG: McpProcessReaperConfig;
+export interface McpProcessInfo {
+    pid: number;
+    ppid: number;
+    elapsedMs: number;
+    command: string;
+    signatureId: McpProcessSignature['id'];
+}
+export type McpVerdict = 'keep' | 'reap-eligible';
+export interface McpEvaluation {
+    pid: number;
+    signatureId: McpProcessSignature['id'];
+    ageMs: number;
+    owningSession: string | null;
+    verdict: McpVerdict;
+    /** The gate that forced KEEP, or the reap rationale. */
+    reason: string;
+}
+/**
+ * All signal sources injected so the classifier is unit-testable without a
+ * real process table, tmux, or kill(2). Production wiring supplies ps/tmux/
+ * SessionManager-backed implementations.
+ */
+export interface McpProcessReaperDeps {
+    /** Allow-listed MCP-server processes currently running (this uid). */
+    listMcpProcesses: () => McpProcessInfo[];
+    /** Full pid → ppid map of the process table (for ancestor resolution). */
+    getProcessTree: () => Map<number, number>;
+    /** tmux pane pid → session name. */
+    getTmuxPaneMap: () => Map<number, string>;
+    /** tmux session names that are genuinely live/tracked. SACRED — never reaped. */
+    getLiveSessions: () => Set<string>;
+    /** All instar-pattern tmux session names present (tracked or not). Used to
+     *  tell a dead/stale *instar* session (reapable) from an external one (kept). */
+    getInstarSessions: () => Set<string>;
+    /** SIGTERM the proc. Only called when killsEnabled. */
+    killProcess: (pid: number) => void;
+    /** Append one audit entry (JSONL). Never throws into the reap loop. */
+    audit?: (entry: McpReapAuditEntry) => void;
+    now?: () => number;
+}
+export interface McpReapAuditEntry {
+    ts: number;
+    type: 'reaped' | 'would-reap' | 'kept';
+    pid: number;
+    signatureId: string;
+    ageMs: number;
+    owningSession: string | null;
+    reason: string;
+    dryRun: boolean;
+}
+/**
+ * Walk the ppid chain from `startPid` until a pid is a tmux pane pid. Returns
+ * the owning tmux session name, or null when no tmux ancestor is found within
+ * `maxHops` (i.e. the proc is orphaned / re-parented — its session is dead).
+ * Pure — cycle-safe via a visited set.
+ */
+export declare function resolveOwningSession(startPid: number, tree: Map<number, number>, tmuxPaneMap: Map<number, string>, maxHops: number): string | null;
+/**
+ * Pure per-proc classifier. KEEP unless the proc is old AND its owning session
+ * is a dead/stale instar session or fully orphaned. Order matters: the sacred
+ * gates (live session, external session) short-circuit before age is consulted.
+ */
+export declare function classifyMcpProcess(proc: McpProcessInfo, owningSession: string | null, liveSessions: Set<string>, instarSessions: Set<string>, minAgeMs: number): McpEvaluation;
+export declare class McpProcessReaper extends EventEmitter {
+    private readonly cfg;
+    private readonly deps;
+    private readonly now;
+    private timer?;
+    private running;
+    private lastPassAt;
+    private reapedLastPass;
+    constructor(deps: McpProcessReaperDeps, cfg?: Partial<McpProcessReaperConfig>);
+    start(): void;
+    stop(): void;
+    private get killsEnabled();
+    /** Resolve + classify one proc against the current process/tmux/session view. */
+    private evaluate;
+    /** One reap pass. Returns the per-proc evaluations + what was reaped. */
+    reap(): Promise<{
+        ts: number;
+        evaluations: McpEvaluation[];
+        reaped: number[];
+        dryRun: boolean;
+    }>;
+    private writeAudit;
+    /** Observability snapshot for GET /processes/mcp-reaper (no side effects). */
+    snapshot(): {
+        enabled: boolean;
+        dryRun: boolean;
+        minAgeMs: number;
+        lastPassAt: number;
+        reapedLastPass: number;
+        processes: McpEvaluation[];
+        reapEligible: number;
+    };
+}
+/** Re-export for production wiring that builds McpProcessInfo from a ps line. */
+export { matchMcpSignature };
+//# sourceMappingURL=McpProcessReaper.d.ts.map

package/dist/monitoring/McpProcessReaper.d.ts.map

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

package/dist/monitoring/McpProcessReaper.js

@@ -0,0 +1,229 @@
+/**
+ * McpProcessReaper — Option B of the MCP-leak fix (Codey's design in
+ * `.instar/apprenticeship/codey-task-mcp-leak-reaper.md`).
+ *
+ * The problem: a session spawns MCP-server children (Playwright, mcp-remote,
+ * instar stdio). Killing the session's main pid does NOT cascade to those
+ * children — they re-parent (to PID 1 / launchd) or are held by an npm-exec
+ * wrapper and survive for days. The fleet accumulated ~80 such leaked procs,
+ * up to 5 days old, as a persistent load floor. `OrphanProcessReaper` reaps the
+ * session-level CLI proc but not these MCP *descendants*.
+ *
+ * This is a descendant-aware SWEEP (a sibling reaper, NOT a change to the
+ * shared OrphanProcessReaper / ReapGuard path — zero blast radius on the
+ * working reaper). For each allow-listed MCP proc it resolves the owning tmux
+ * session by walking the ppid chain, and reaps ONLY when the proc is old AND
+ * its owning session is a dead/stale *instar* session or fully orphaned. It
+ * NEVER touches a proc under a live/tracked session, nor under an external
+ * (non-instar) tmux session.
+ *
+ * Ships DARK + DRY-RUN by default (kills processes — same posture as
+ * SessionReaper / AgentWorktreeReaper). Every decision is audited.
+ */
+import { EventEmitter } from 'node:events';
+import { matchMcpSignature } from './mcpProcessSignatures.js';
+export const DEFAULT_MCP_PROCESS_REAPER_CONFIG = {
+    enabled: false,
+    dryRun: true,
+    // Conservative: the leaked procs are hours-to-days old; 2h floor means a
+    // legitimately busy short-lived MCP child is never a candidate.
+    minAgeMs: 2 * 3600 * 1000,
+    reapIntervalMs: 30 * 60 * 1000,
+    maxReapsPerPass: 25,
+    maxAncestorHops: 30,
+};
+/**
+ * Walk the ppid chain from `startPid` until a pid is a tmux pane pid. Returns
+ * the owning tmux session name, or null when no tmux ancestor is found within
+ * `maxHops` (i.e. the proc is orphaned / re-parented — its session is dead).
+ * Pure — cycle-safe via a visited set.
+ */
+export function resolveOwningSession(startPid, tree, tmuxPaneMap, maxHops) {
+    let pid = startPid;
+    const seen = new Set();
+    for (let hop = 0; hop <= maxHops && pid !== undefined && pid > 1; hop++) {
+        if (seen.has(pid))
+            break; // cycle guard
+        seen.add(pid);
+        const session = tmuxPaneMap.get(pid);
+        if (session)
+            return session;
+        pid = tree.get(pid);
+    }
+    return null;
+}
+/**
+ * Pure per-proc classifier. KEEP unless the proc is old AND its owning session
+ * is a dead/stale instar session or fully orphaned. Order matters: the sacred
+ * gates (live session, external session) short-circuit before age is consulted.
+ */
+export function classifyMcpProcess(proc, owningSession, liveSessions, instarSessions, minAgeMs) {
+    const base = {
+        pid: proc.pid,
+        signatureId: proc.signatureId,
+        ageMs: proc.elapsedMs,
+        owningSession,
+    };
+    const keep = (reason) => ({ ...base, verdict: 'keep', reason });
+    const reap = (reason) => ({ ...base, verdict: 'reap-eligible', reason });
+    if (owningSession !== null) {
+        // SACRED: a live/tracked session owns it — keep regardless of age. A long-
+        // running autonomous session legitimately owns old MCP servers.
+        if (liveSessions.has(owningSession))
+            return keep('session-live');
+        // An external (non-instar) tmux session — never touch the user's processes.
+        if (!instarSessions.has(owningSession))
+            return keep('external-session');
+        // A stale/dead *instar* session still lingering in tmux: reapable when old.
+        if (proc.elapsedMs < minAgeMs)
+            return keep('stale-instar-too-young');
+        return reap(`stale-instar-session:${owningSession}`);
+    }
+    // No tmux ancestor — the owning session is dead and this proc re-parented.
+    // This is the dominant leak shape. Reapable only when old.
+    if (proc.elapsedMs < minAgeMs)
+        return keep('orphan-too-young');
+    return reap('orphaned-no-session');
+}
+export class McpProcessReaper extends EventEmitter {
+    cfg;
+    deps;
+    now;
+    timer;
+    running = false;
+    lastPassAt = 0;
+    reapedLastPass = 0;
+    constructor(deps, cfg) {
+        super();
+        this.deps = deps;
+        this.cfg = { ...DEFAULT_MCP_PROCESS_REAPER_CONFIG, ...(cfg ?? {}) };
+        this.now = deps.now ?? (() => Date.now());
+    }
+    start() {
+        if (this.timer || !this.cfg.enabled)
+            return;
+        this.timer = setInterval(() => { void this.reap(); }, this.cfg.reapIntervalMs);
+        if (typeof this.timer.unref === 'function')
+            this.timer.unref();
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+    }
+    get killsEnabled() {
+        return this.cfg.enabled && !this.cfg.dryRun;
+    }
+    /** Resolve + classify one proc against the current process/tmux/session view. */
+    evaluate(proc, tree, tmuxPaneMap, liveSessions, instarSessions) {
+        const owningSession = resolveOwningSession(proc.pid, tree, tmuxPaneMap, this.cfg.maxAncestorHops);
+        return classifyMcpProcess(proc, owningSession, liveSessions, instarSessions, this.cfg.minAgeMs);
+    }
+    /** One reap pass. Returns the per-proc evaluations + what was reaped. */
+    async reap() {
+        if (this.running)
+            return { ts: this.now(), evaluations: [], reaped: [], dryRun: !this.killsEnabled };
+        this.running = true;
+        const reaped = [];
+        const evaluations = [];
+        try {
+            let procs;
+            let tree;
+            let tmuxPaneMap;
+            let liveSessions;
+            let instarSessions;
+            try {
+                procs = this.deps.listMcpProcesses();
+                tree = this.deps.getProcessTree();
+                tmuxPaneMap = this.deps.getTmuxPaneMap();
+                liveSessions = this.deps.getLiveSessions();
+                instarSessions = this.deps.getInstarSessions();
+            }
+            catch (err) {
+                this.emit('error', err);
+                return { ts: this.now(), evaluations: [], reaped: [], dryRun: !this.killsEnabled };
+            }
+            for (const proc of procs) {
+                let evaln;
+                try {
+                    evaln = this.evaluate(proc, tree, tmuxPaneMap, liveSessions, instarSessions);
+                }
+                catch {
+                    // A signal threw — cannot reason about it, so KEEP. Never reap on a
+                    // failed evaluation.
+                    evaln = {
+                        pid: proc.pid, signatureId: proc.signatureId, ageMs: proc.elapsedMs,
+                        owningSession: null, verdict: 'keep', reason: 'eval-error',
+                    };
+                }
+                evaluations.push(evaln);
+                if (evaln.verdict !== 'reap-eligible') {
+                    this.writeAudit({ ts: this.now(), type: 'kept', pid: proc.pid, signatureId: proc.signatureId, ageMs: proc.elapsedMs, owningSession: evaln.owningSession, reason: evaln.reason, dryRun: !this.killsEnabled });
+                    continue;
+                }
+                if (reaped.length >= this.cfg.maxReapsPerPass)
+                    continue; // blast-radius cap
+                if (!this.killsEnabled) {
+                    // Dry-run: classify + audit what we WOULD kill, kill nothing.
+                    this.writeAudit({ ts: this.now(), type: 'would-reap', pid: proc.pid, signatureId: proc.signatureId, ageMs: proc.elapsedMs, owningSession: evaln.owningSession, reason: evaln.reason, dryRun: true });
+                    continue;
+                }
+                try {
+                    this.deps.killProcess(proc.pid);
+                    reaped.push(proc.pid);
+                    this.writeAudit({ ts: this.now(), type: 'reaped', pid: proc.pid, signatureId: proc.signatureId, ageMs: proc.elapsedMs, owningSession: evaln.owningSession, reason: evaln.reason, dryRun: false });
+                    this.emit('reaped', proc);
+                }
+                catch (err) {
+                    this.emit('error', err);
+                }
+            }
+            this.lastPassAt = this.now();
+            this.reapedLastPass = reaped.length;
+            this.emit('pass', { evaluations, reaped });
+        }
+        finally {
+            this.running = false;
+        }
+        return { ts: this.now(), evaluations, reaped, dryRun: !this.killsEnabled };
+    }
+    writeAudit(entry) {
+        try {
+            this.deps.audit?.(entry);
+        }
+        catch { /* audit must never break the loop */ }
+    }
+    /** Observability snapshot for GET /processes/mcp-reaper (no side effects). */
+    snapshot() {
+        let processes = [];
+        try {
+            const procs = this.deps.listMcpProcesses();
+            const tree = this.deps.getProcessTree();
+            const tmuxPaneMap = this.deps.getTmuxPaneMap();
+            const liveSessions = this.deps.getLiveSessions();
+            const instarSessions = this.deps.getInstarSessions();
+            processes = procs.map((proc) => {
+                try {
+                    return this.evaluate(proc, tree, tmuxPaneMap, liveSessions, instarSessions);
+                }
+                catch {
+                    return { pid: proc.pid, signatureId: proc.signatureId, ageMs: proc.elapsedMs, owningSession: null, verdict: 'keep', reason: 'eval-error' };
+                }
+            });
+        }
+        catch { /* listing failed — report empty, never crash the route */ }
+        return {
+            enabled: this.cfg.enabled,
+            dryRun: this.cfg.dryRun,
+            minAgeMs: this.cfg.minAgeMs,
+            lastPassAt: this.lastPassAt,
+            reapedLastPass: this.reapedLastPass,
+            processes,
+            reapEligible: processes.filter((p) => p.verdict === 'reap-eligible').length,
+        };
+    }
+}
+/** Re-export for production wiring that builds McpProcessInfo from a ps line. */
+export { matchMcpSignature };
+//# sourceMappingURL=McpProcessReaper.js.map

package/dist/monitoring/McpProcessReaper.js.map

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

package/dist/monitoring/ResourceLedger.d.ts

@@ -0,0 +1,78 @@
+import type { Database as BetterSqliteDatabase } from 'better-sqlite3';
+/** Canonical event kinds. `circuit-open`/`circuit-recover` come from the breaker
+ *  (the primary, account-level signal); the throttle/quota/529 kinds come from
+ *  RateLimitSentinel (session-scoped, secondary — tagged `source`). */
+export type RateLimitEventKind = 'circuit-open' | 'circuit-recover' | 'throttle' | 'quota' | '529';
+export type RateLimitEventSource = 'circuit-breaker' | 'session-sentinel';
+export interface RateLimitEventInput {
+    ts: number;
+    kind: RateLimitEventKind;
+    source: RateLimitEventSource;
+    /** Stable per-event sequence within this process — together with ts+source it
+     *  forms the row id, so same-ms events are distinct and restarts don't replay. */
+    seq: number;
+    accountKey?: string;
+    sessionName?: string;
+    reason?: string;
+    detail?: string;
+}
+export interface RateLimitSummaryRow {
+    /** Headline: breaker trips (the account-level signal). */
+    circuitOpenCount: number;
+    circuitRecoverCount: number;
+    /** Session-sentinel detections, reported separately (different semantics). */
+    sentinelCount: number;
+    totalEvents: number;
+    /** Breaker trips per hour over the window — the "rate" asked for. */
+    tripsPerHour: number;
+    oldestEventTs: number | null;
+    newestEventTs: number | null;
+    windowMs: number;
+}
+export interface RateLimitKindRow {
+    kind: RateLimitEventKind;
+    source: RateLimitEventSource;
+    count: number;
+    firstTs: number;
+    lastTs: number;
+}
+export interface RateLimitEventRow {
+    id: string;
+    ts: number;
+    kind: RateLimitEventKind;
+    source: RateLimitEventSource;
+    accountKey: string;
+    sessionName: string | null;
+    reason: string | null;
+    detail: string | null;
+}
+export interface ResourceLedgerOptions {
+    /** SQLite db path, or ':memory:' for tests. */
+    dbPath: string;
+    /** Test seam — inject a Database instance. */
+    databaseFactory?: (dbPath: string) => BetterSqliteDatabase;
+}
+export declare class ResourceLedger {
+    private db;
+    private insertEvent;
+    private closed;
+    constructor(opts: ResourceLedgerOptions);
+    /** Per-event identity: ts + source + seq is unique within a process; the source
+     *  prefix keeps breaker and sentinel rows from ever colliding. NOT a content
+     *  hash, so two genuine same-ms events stay distinct. */
+    private static eventId;
+    /** Record one rate-limit event. Idempotent on (source,ts,seq). Never throws —
+     *  observability must not break the observed path. */
+    recordRateLimitEvent(e: RateLimitEventInput): void;
+    /** Count + rate of rate-limit events over the trailing window. */
+    rateLimitSummary(nowMs: number, windowMs: number): RateLimitSummaryRow;
+    /** Per-kind breakdown over the window. */
+    rateLimitByKind(nowMs: number, windowMs: number): RateLimitKindRow[];
+    /** Recent event rows, newest first. */
+    rateLimitEvents(opts?: {
+        sinceMs?: number;
+        limit?: number;
+    }): RateLimitEventRow[];
+    close(): void;
+}
+//# sourceMappingURL=ResourceLedger.d.ts.map

package/dist/monitoring/ResourceLedger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResourceLedger.d.ts","sourceRoot":"","sources":["../../src/monitoring/ResourceLedger.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,QAAQ,IAAI,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAIvE;;uEAEuE;AACvE,MAAM,MAAM,kBAAkB,GAC1B,cAAc,GACd,iBAAiB,GACjB,UAAU,GACV,OAAO,GACP,KAAK,CAAC;AAEV,MAAM,MAAM,oBAAoB,GAAG,iBAAiB,GAAG,kBAAkB,CAAC;AAE1E,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,kBAAkB,CAAC;IACzB,MAAM,EAAE,oBAAoB,CAAC;IAC7B;sFACkF;IAClF,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,0DAA0D;IAC1D,gBAAgB,EAAE,MAAM,CAAC;IACzB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,8EAA8E;IAC9E,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,kBAAkB,CAAC;IACzB,MAAM,EAAE,oBAAoB,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,kBAAkB,CAAC;IACzB,MAAM,EAAE,oBAAoB,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,qBAAqB;IACpC,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,oBAAoB,CAAC;CAC5D;AAkBD,qBAAa,cAAc;IACzB,OAAO,CAAC,EAAE,CAAuB;IACjC,OAAO,CAAC,WAAW,CAA+C;IAClE,OAAO,CAAC,MAAM,CAAS;gBAEX,IAAI,EAAE,qBAAqB;IA4BvC;;6DAEyD;IACzD,OAAO,CAAC,MAAM,CAAC,OAAO;IAItB;0DACsD;IACtD,oBAAoB,CAAC,CAAC,EAAE,mBAAmB,GAAG,IAAI;IAkBlD,kEAAkE;IAClE,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,mBAAmB;IA6BtE,0CAA0C;IAC1C,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,gBAAgB,EAAE;IAapE,uCAAuC;IACvC,eAAe,CAAC,IAAI,GAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,iBAAiB,EAAE;IAerF,KAAK,IAAI,IAAI;CAKd"}

package/dist/monitoring/ResourceLedger.js

@@ -0,0 +1,163 @@
+/**
+ * ResourceLedger — per-agent resource-usage observability (Phase A: rate-limit events).
+ *
+ * Durable, read-only. Mirrors TokenLedger / FeatureMetricsLedger: SQLite opened
+ * through NativeModuleHealer, WAL, registered for close-on-exit via
+ * SqliteRegistry, schema applied idempotently. Like FeatureMetricsLedger, every
+ * write swallows its error so observability can NEVER break the path it
+ * observes. It never gates, throttles, or mutates any runtime flow.
+ *
+ * Phase A persists the one resource signal that is ephemeral today: rate-limit
+ * events. LlmCircuitBreaker counts trips in process-local memory (lost on
+ * restart) and RateLimitSentinel emits transient events — so "how many times was
+ * the account throttled today" is currently unanswerable. This store makes it
+ * durable. Each event is written event-driven by ResourceLedgerPoller (from the
+ * breaker's trip/recover emitter and the sentinel's events), one row per
+ * emission, with a real per-event identity (not a content hash) so legitimate
+ * same-millisecond events don't collapse and a restart can't replay-double-count.
+ *
+ * CPU/memory sampling (resource_samples) + retention is Phase B; the table and
+ * its methods are not in this file yet.
+ *
+ * Spec: docs/specs/per-agent-resource-ledger.md.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import Database from 'better-sqlite3';
+import { registerSqliteHandle } from '../core/SqliteRegistry.js';
+import { NativeModuleHealer } from '../memory/NativeModuleHealer.js';
+const SCHEMA = [
+    `CREATE TABLE IF NOT EXISTS rate_limit_events (
+     id           TEXT PRIMARY KEY,
+     ts           INTEGER NOT NULL,
+     kind         TEXT NOT NULL,
+     source       TEXT NOT NULL,
+     account_key  TEXT NOT NULL DEFAULT 'default',
+     session_name TEXT,
+     reason       TEXT,
+     detail       TEXT
+   )`,
+    `CREATE INDEX IF NOT EXISTS idx_rle_ts ON rate_limit_events (ts)`,
+    `CREATE INDEX IF NOT EXISTS idx_rle_kind_ts ON rate_limit_events (kind, ts)`,
+    `CREATE INDEX IF NOT EXISTS idx_rle_source_ts ON rate_limit_events (source, ts)`,
+];
+export class ResourceLedger {
+    db;
+    insertEvent;
+    closed = false;
+    constructor(opts) {
+        if (opts.dbPath !== ':memory:') {
+            fs.mkdirSync(path.dirname(opts.dbPath), { recursive: true });
+        }
+        // Open through the native-module healer — identical ABI-resilience to
+        // TokenLedger/FeatureMetricsLedger, so a Node upgrade can't brick /resources.
+        this.db = NativeModuleHealer.openWithHealSync('ResourceLedger', () => opts.databaseFactory?.(opts.dbPath) ?? new Database(opts.dbPath));
+        this.db.pragma('journal_mode = WAL');
+        this.db.pragma('synchronous = NORMAL');
+        for (const ddl of SCHEMA) {
+            try {
+                this.db.exec(ddl);
+            }
+            catch (err) {
+                const msg = err.message || '';
+                if (!/duplicate column name/i.test(msg))
+                    throw err;
+            }
+        }
+        registerSqliteHandle(() => { try {
+            this.db?.close();
+        }
+        catch { /* already closed */ } });
+        this.insertEvent = this.db.prepare(`INSERT OR IGNORE INTO rate_limit_events
+         (id, ts, kind, source, account_key, session_name, reason, detail)
+       VALUES (@id, @ts, @kind, @source, @accountKey, @sessionName, @reason, @detail)`);
+    }
+    /** Per-event identity: ts + source + seq is unique within a process; the source
+     *  prefix keeps breaker and sentinel rows from ever colliding. NOT a content
+     *  hash, so two genuine same-ms events stay distinct. */
+    static eventId(e) {
+        return `${e.source}:${e.ts}:${e.seq}`;
+    }
+    /** Record one rate-limit event. Idempotent on (source,ts,seq). Never throws —
+     *  observability must not break the observed path. */
+    recordRateLimitEvent(e) {
+        if (this.closed)
+            return;
+        try {
+            this.insertEvent.run({
+                id: ResourceLedger.eventId(e),
+                ts: e.ts,
+                kind: e.kind,
+                source: e.source,
+                accountKey: e.accountKey && e.accountKey.trim() ? e.accountKey.trim() : 'default',
+                sessionName: e.sessionName ?? null,
+                reason: e.reason ?? null,
+                detail: e.detail ?? null,
+            });
+        }
+        catch {
+            /* swallow — never break the observed path (Close the Loop applied to self) */
+        }
+    }
+    /** Count + rate of rate-limit events over the trailing window. */
+    rateLimitSummary(nowMs, windowMs) {
+        const since = nowMs - windowMs;
+        const row = this.db
+            .prepare(`SELECT
+           SUM(CASE WHEN kind='circuit-open'    THEN 1 ELSE 0 END) AS circuitOpenCount,
+           SUM(CASE WHEN kind='circuit-recover' THEN 1 ELSE 0 END) AS circuitRecoverCount,
+           SUM(CASE WHEN source='session-sentinel' THEN 1 ELSE 0 END) AS sentinelCount,
+           COUNT(*) AS totalEvents,
+           MIN(ts)  AS oldestEventTs,
+           MAX(ts)  AS newestEventTs
+         FROM rate_limit_events
+         WHERE ts >= ?`)
+            .get(since);
+        const trips = Number(row.circuitOpenCount ?? 0);
+        const hours = windowMs / 3_600_000;
+        return {
+            circuitOpenCount: trips,
+            circuitRecoverCount: Number(row.circuitRecoverCount ?? 0),
+            sentinelCount: Number(row.sentinelCount ?? 0),
+            totalEvents: Number(row.totalEvents ?? 0),
+            tripsPerHour: hours > 0 ? +(trips / hours).toFixed(2) : 0,
+            oldestEventTs: row.oldestEventTs ?? null,
+            newestEventTs: row.newestEventTs ?? null,
+            windowMs,
+        };
+    }
+    /** Per-kind breakdown over the window. */
+    rateLimitByKind(nowMs, windowMs) {
+        const since = nowMs - windowMs;
+        return this.db
+            .prepare(`SELECT kind, source, COUNT(*) AS count, MIN(ts) AS firstTs, MAX(ts) AS lastTs
+         FROM rate_limit_events
+         WHERE ts >= ?
+         GROUP BY kind, source
+         ORDER BY count DESC`)
+            .all(since);
+    }
+    /** Recent event rows, newest first. */
+    rateLimitEvents(opts = {}) {
+        const limit = Math.min(Math.max(opts.limit ?? 100, 1), 1000);
+        const since = opts.sinceMs ?? 0;
+        return this.db
+            .prepare(`SELECT id, ts, kind, source, account_key AS accountKey,
+                session_name AS sessionName, reason, detail
+         FROM rate_limit_events
+         WHERE ts >= ?
+         ORDER BY ts DESC
+         LIMIT ?`)
+            .all(since, limit);
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        try {
+            this.db.close();
+        }
+        catch { /* ignore */ }
+    }
+}
+//# sourceMappingURL=ResourceLedger.js.map

package/dist/monitoring/ResourceLedger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResourceLedger.js","sourceRoot":"","sources":["../../src/monitoring/ResourceLedger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AAEtC,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAmErE,MAAM,MAAM,GAAG;IACb;;;;;;;;;KASG;IACH,iEAAiE;IACjE,4EAA4E;IAC5E,gFAAgF;CACjF,CAAC;AAEF,MAAM,OAAO,cAAc;IACjB,EAAE,CAAuB;IACzB,WAAW,CAA+C;IAC1D,MAAM,GAAG,KAAK,CAAC;IAEvB,YAAY,IAA2B;QACrC,IAAI,IAAI,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;YAC/B,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC/D,CAAC;QACD,sEAAsE;QACtE,8EAA8E;QAC9E,IAAI,CAAC,EAAE,GAAG,kBAAkB,CAAC,gBAAgB,CAC3C,gBAAgB,EAChB,GAAG,EAAE,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CACvE,CAAC;QACF,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;QACrC,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,sBAAsB,CAAC,CAAC;QACvC,KAAK,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;YACzB,IAAI,CAAC;gBACH,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACpB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,GAAG,GAAI,GAAa,CAAC,OAAO,IAAI,EAAE,CAAC;gBACzC,IAAI,CAAC,wBAAwB,CAAC,IAAI,CAAC,GAAG,CAAC;oBAAE,MAAM,GAAG,CAAC;YACrD,CAAC;QACH,CAAC;QACD,oBAAoB,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;YAAC,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACzF,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,CAChC;;sFAEgF,CACjF,CAAC;IACJ,CAAC;IAED;;6DAEyD;IACjD,MAAM,CAAC,OAAO,CAAC,CAAsB;QAC3C,OAAO,GAAG,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,GAAG,EAAE,CAAC;IACxC,CAAC;IAED;0DACsD;IACtD,oBAAoB,CAAC,CAAsB;QACzC,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO;QACxB,IAAI,CAAC;YACH,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC;gBACnB,EAAE,EAAE,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC;gBAC7B,EAAE,EAAE,CAAC,CAAC,EAAE;gBACR,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,MAAM,EAAE,CAAC,CAAC,MAAM;gBAChB,UAAU,EAAE,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS;gBACjF,WAAW,EAAE,CAAC,CAAC,WAAW,IAAI,IAAI;gBAClC,MAAM,EAAE,CAAC,CAAC,MAAM,IAAI,IAAI;gBACxB,MAAM,EAAE,CAAC,CAAC,MAAM,IAAI,IAAI;aACzB,CAAC,CAAC;QACL,CAAC;QAAC,MAAM,CAAC;YACP,8EAA8E;QAChF,CAAC;IACH,CAAC;IAED,kEAAkE;IAClE,gBAAgB,CAAC,KAAa,EAAE,QAAgB;QAC9C,MAAM,KAAK,GAAG,KAAK,GAAG,QAAQ,CAAC;QAC/B,MAAM,GAAG,GAAG,IAAI,CAAC,EAAE;aAChB,OAAO,CACN;;;;;;;;uBAQe,CAChB;aACA,GAAG,CAAC,KAAK,CAAkC,CAAC;QAC/C,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,gBAAgB,IAAI,CAAC,CAAC,CAAC;QAChD,MAAM,KAAK,GAAG,QAAQ,GAAG,SAAS,CAAC;QACnC,OAAO;YACL,gBAAgB,EAAE,KAAK;YACvB,mBAAmB,EAAE,MAAM,CAAC,GAAG,CAAC,mBAAmB,IAAI,CAAC,CAAC;YACzD,aAAa,EAAE,MAAM,CAAC,GAAG,CAAC,aAAa,IAAI,CAAC,CAAC;YAC7C,WAAW,EAAE,MAAM,CAAC,GAAG,CAAC,WAAW,IAAI,CAAC,CAAC;YACzC,YAAY,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACzD,aAAa,EAAE,GAAG,CAAC,aAAa,IAAI,IAAI;YACxC,aAAa,EAAE,GAAG,CAAC,aAAa,IAAI,IAAI;YACxC,QAAQ;SACT,CAAC;IACJ,CAAC;IAED,0CAA0C;IAC1C,eAAe,CAAC,KAAa,EAAE,QAAgB;QAC7C,MAAM,KAAK,GAAG,KAAK,GAAG,QAAQ,CAAC;QAC/B,OAAO,IAAI,CAAC,EAAE;aACX,OAAO,CACN;;;;6BAIqB,CACtB;aACA,GAAG,CAAC,KAAK,CAAuB,CAAC;IACtC,CAAC;IAED,uCAAuC;IACvC,eAAe,CAAC,OAA6C,EAAE;QAC7D,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,GAAG,EAAE,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;QAC7D,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC;QAChC,OAAO,IAAI,CAAC,EAAE;aACX,OAAO,CACN;;;;;iBAKS,CACV;aACA,GAAG,CAAC,KAAK,EAAE,KAAK,CAAwB,CAAC;IAC9C,CAAC;IAED,KAAK;QACH,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO;QACxB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,IAAI,CAAC;YAAC,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;IACjD,CAAC;CACF"}