instar 0.28.107 → 0.28.108

package/dist/monitoring/LlmRateGate.d.ts

@@ -1,28 +1,28 @@
 /**
  * LlmRateGate — actuator primitive for the burn-detection auto-heal system.
  *
- * Phase 1 (this file): ships as a NO-OP. The primitive exists, the shape is
- * stable, and instar-internal LLM callers can already consult it before each
- * call — but no decision-maker is wired in yet, so `shouldFire(key)` always
- * returns true. This deliberate sequencing avoids a regression window where
- * the BurnDetector emits signals with no actuator to honour them.
+ * Phase 1 shipped the no-op shape. Phase 4 upgrades the gate into a stateful
+ * actuator: the burn-throttle runbook installs throttles via `installThrottle`,
+ * the LLM callers consult `shouldFire` / `decide`, and a throttle auto-expires
+ * after its TTL elapses. Per the umbrella spec §"Signal-vs-Authority
+ * Decomposition", the gate enforces decisions made elsewhere — it never
+ * decides anything on its own.
  *
- * Future phases (per docs/specs/token-burn-detection-and-self-heal.md):
- *   - Phase 4 (burn-throttle runbook): the Remediator-Tier-2 runbook stores
- *     signed throttle decisions; the gate consults that store.
- *   - Phase 4 (HMAC-signed jobs.json.throttle-overrides): scheduled-job
- *     overrides land via this gate so the same actuator covers cron entries.
+ * State: in-memory only. The throttle store is process-local. If the agent
+ * restarts, any in-memory throttle is dropped — which is the right default
+ * (a restart is itself a reset, and the burn-detector will re-emit any
+ * surviving signal within 60s). Persistent throttles for scheduled-job cron
+ * entries live in a separate file (`.instar/jobs.json.throttle-overrides`,
+ * HMAC-signed) handled by the scheduler — out of scope for this primitive.
  *
- * Authority shape: the gate ENFORCES decisions that were made elsewhere. It
- * does NOT decide. Brittle threshold detectors must never write to this
- * gate directly — only the Remediator (with signed-context Tier-2 capability
- * tokens) can install a throttle. This honours the signal-vs-authority
- * boundary in docs/signal-vs-authority.md.
- *
- * Singleton-per-process: every LLM caller in the process shares one gate so
- * a single throttle decision covers every code path that uses the same
- * attribution key. The class exposes a static `instance()` accessor; tests
- * use the public constructor + `reset()` to isolate from the singleton.
+ * Authority: the gate accepts throttles only via `installThrottle`, which the
+ * runbook calls with a capability token. The token is verified by the gate
+ * against the agent's HMAC key (passed at constructor time when the gate
+ * needs to enforce, or skipped for tests). When no key is configured, the
+ * gate accepts throttles without verification — that's the "trusted local
+ * caller" mode used by the runbook before the F-8 capability surface fully
+ * lands. The verification path is in place so the runbook can switch to
+ * signed tokens without API churn.
  */
 export interface LlmRateGateDecision {
     /** Whether the gate currently allows the next LLM call for this key. */
@@ -30,34 +30,134 @@ export interface LlmRateGateDecision {
     /** ISO timestamp the decision was made (debug / log). */
     decidedAt: string;
     /** Why — for log + verification trace. */
-    reason: 'phase-1-noop' | 'no-throttle-installed' | 'throttle-active' | 'throttle-expired';
+    reason: 'no-throttle-installed' | 'throttle-active' | 'throttle-expired' | 'runbook-self-exempt';
+    /** When the active throttle (if any) expires. Phase 4: ISO timestamp. */
+    throttleExpiresAt?: string;
+}
+export interface InstalledThrottle {
+    attributionKey: string;
+    /** ISO timestamp when the throttle was installed. */
+    installedAt: string;
+    /** ISO timestamp when the throttle auto-reverts. */
+    expiresAt: string;
+    /** Free-text reason the runbook chose this throttle. */
+    reason: string;
+    /** Issuer identity (the runbook). Audit trail only. */
+    issuer: string;
+}
+export interface InstallThrottleInput {
+    attributionKey: string;
+    /** Throttle duration in milliseconds (auto-reverts when elapsed). */
+    durationMs: number;
+    /** Free-text reason for audit. */
+    reason: string;
+    /** Issuer identity for audit (e.g. 'burn-throttle-runbook'). */
+    issuer: string;
+    /**
+     * Unique identifier for the originating burn signal. Used by the gate as a
+     * replay-prevention nonce — once consumed, the same signalId cannot install
+     * another throttle. The runbook derives this from the DegradationEvent's
+     * monotonic timestamp + attribution key. Reviewer-required (Phase 4
+     * second-pass review §1) to close the infinite-replay window on captured
+     * capability tokens.
+     */
+    signalId: string;
+    /**
+     * Capability token over the canonical install payload. When the gate has
+     * an HMAC key configured (production), the token MUST be present and
+     * valid. When no key is configured (tests / pre-F-8 wiring), the token
+     * is ignored — see the class doc for the "trusted local caller" caveat
+     * (the HMAC defends external/cross-process forgery, not in-process mints).
+     */
+    capabilityToken?: string;
+}
+export interface LlmRateGateOptions {
+    /**
+     * Optional HMAC key for capability-token verification. When set, every
+     * installThrottle call must include a valid `capabilityToken` over the
+     * canonical payload.
+     */
+    capabilityKey?: Buffer | null;
+    /** Injectable clock for tests. */
+    now?: () => number;
 }
 export declare class LlmRateGate {
     private static singleton;
+    private readonly throttles;
+    private readonly capabilityKey;
+    private readonly now;
+    /**
+     * Consumed signal IDs — replay-prevention nonces. Per Phase 4 second-pass
+     * review §1. Garbage-collected lazily during `installThrottle`: entries
+     * older than the maximum throttle TTL (2× the longest seen) can be
+     * dropped because their corresponding throttle has long since expired.
+     */
+    private readonly consumedSignalIds;
+    /** Tracks the longest throttle duration seen, used for GC of consumed IDs. */
+    private maxThrottleDurationMs;
+    constructor(opts?: LlmRateGateOptions);
     /**
      * Process-wide singleton. Tests should use `new LlmRateGate()` + `reset()`
      * rather than this accessor, so they don't bleed throttles into each other.
      */
     static instance(): LlmRateGate;
     /**
-     * Phase 1: always returns true. The signature is stable so callers can
-     * adopt the consult-before-call pattern today; future phases enforce it.
+     * Read-side: does the gate currently allow a call for this key?
      *
-     * @param attributionKey  componentName::promptFingerprint key. Reserved
-     *                        values: keys starting with `burn-throttle-runbook::`
-     *                        are exempt by design (self-reinforcing-loop guard
-     *                        per spec §"Self-reinforcing loop guard").
+     * @param attributionKey componentName::promptFingerprint. Reserved prefix
+     *                       `burn-throttle-runbook::*` is structurally exempt
+     *                       (self-reinforcing-loop guard).
      */
     shouldFire(attributionKey: string): boolean;
+    decide(attributionKey: string): LlmRateGateDecision;
+    /**
+     * Install a throttle for an attribution key. Called by the burn-throttle
+     * runbook. Refuses keys with the runbook-self exempt prefix as a defence
+     * in depth (the gate also exempts on the read path).
+     *
+     * Returns the InstalledThrottle if accepted, or throws on:
+     *   - Self-attribution attempts.
+     *   - Capability-token verification failure (when key is configured).
+     *   - Zero/negative duration.
+     */
+    installThrottle(input: InstallThrottleInput): InstalledThrottle;
+    private signWithKey;
     /**
-     * Same as shouldFire() but returns the full decision record. Useful for
-     * tests and for the burn-throttle runbook's verification step.
+     * Revoke an active throttle. Idempotent (no-op if no throttle exists).
+     * Called by the Telegram inline-button handler in Phase 5 and by the
+     * runbook's manual-override path.
      */
-    decide(attributionKey: string): LlmRateGateDecision;
+    revokeThrottle(attributionKey: string): boolean;
+    /**
+     * List currently-active throttles. Used by the verification step (Phase 6)
+     * and by the dashboard surface.
+     */
+    listActiveThrottles(): InstalledThrottle[];
+    /**
+     * Compute the capability token for an install payload. Used by the
+     * runbook to sign its own throttle requests. Returns null when no
+     * capability key is configured (test mode).
+     *
+     * **Threat-model note (Phase 4 second-pass review §2):** this mint and the
+     * verification it pairs with both live on the same gate object, so any
+     * in-process caller holding a gate reference can forge a valid token. The
+     * HMAC therefore defends the **external/cross-process boundary** only
+     * — chiefly the persistent throttle-overrides file the scheduler reads
+     * (Phase 4-extension, not in this PR). For in-process integrity we rely
+     * on the fact that all callers of LlmRateGate are instar source under
+     * the same `/instar-dev` review gate. If/when the runbook is moved to a
+     * separate process, this mint method should be relocated to the runbook
+     * service alone and removed from the gate's API surface.
+     */
+    computeCapabilityToken(input: {
+        attributionKey: string;
+        durationMs: number;
+        issuer: string;
+        signalId: string;
+    }): string | null;
     /**
-     * Reset all installed throttles. Phase 1 has no throttles, so this is a
-     * no-op; future phases will clear the in-memory throttle map. Exposed for
-     * tests so a misconfigured singleton can't bleed across `describe` blocks.
+     * Reset all installed throttles. Exposed for tests so a misconfigured
+     * singleton can't bleed across `describe` blocks.
      */
     reset(): void;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"LlmRateGate.d.ts","sourceRoot":"","sources":["../../src/monitoring/LlmRateGate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,OAAO,EAAE,OAAO,CAAC;IACjB,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,MAAM,EAAE,cAAc,GAAG,uBAAuB,GAAG,iBAAiB,GAAG,kBAAkB,CAAC;CAC3F;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAC,SAAS,CAA4B;IAEpD;;;OAGG;IACH,MAAM,CAAC,QAAQ,IAAI,WAAW;IAO9B;;;;;;;;OAQG;IACH,UAAU,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO;IAI3C;;;OAGG;IACH,MAAM,CAAC,cAAc,EAAE,MAAM,GAAG,mBAAmB;IAmBnD;;;;OAIG;IACH,KAAK,IAAI,IAAI;CAGd"}
+{"version":3,"file":"LlmRateGate.d.ts","sourceRoot":"","sources":["../../src/monitoring/LlmRateGate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,OAAO,EAAE,OAAO,CAAC;IACjB,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,MAAM,EACF,uBAAuB,GACvB,iBAAiB,GACjB,kBAAkB,GAClB,qBAAqB,CAAC;IAC1B,yEAAyE;IACzE,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,iBAAiB;IAChC,cAAc,EAAE,MAAM,CAAC;IACvB,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC,cAAc,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;OAOG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,kCAAkC;IAClC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAC,SAAS,CAA4B;IACpD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwC;IAClE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA6B;IAC/D,8EAA8E;IAC9E,OAAO,CAAC,qBAAqB,CAAkB;gBAEnC,IAAI,CAAC,EAAE,kBAAkB;IAKrC;;;OAGG;IACH,MAAM,CAAC,QAAQ,IAAI,WAAW;IAO9B;;;;;;OAMG;IACH,UAAU,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO;IAI3C,MAAM,CAAC,cAAc,EAAE,MAAM,GAAG,mBAAmB;IAuBnD;;;;;;;;;OASG;IACH,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,iBAAiB;IA0D/D,OAAO,CAAC,WAAW;IAUnB;;;;OAIG;IACH,cAAc,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO;IAI/C;;;OAGG;IACH,mBAAmB,IAAI,iBAAiB,EAAE;IAc1C;;;;;;;;;;;;;;;OAeG;IACH,sBAAsB,CAAC,KAAK,EAAE;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,GAAG,IAAI;IAK9H;;;OAGG;IACH,KAAK,IAAI,IAAI;CAGd"}

package/dist/monitoring/LlmRateGate.js

@@ -1,31 +1,48 @@
 /**
  * LlmRateGate — actuator primitive for the burn-detection auto-heal system.
  *
- * Phase 1 (this file): ships as a NO-OP. The primitive exists, the shape is
- * stable, and instar-internal LLM callers can already consult it before each
- * call — but no decision-maker is wired in yet, so `shouldFire(key)` always
- * returns true. This deliberate sequencing avoids a regression window where
- * the BurnDetector emits signals with no actuator to honour them.
+ * Phase 1 shipped the no-op shape. Phase 4 upgrades the gate into a stateful
+ * actuator: the burn-throttle runbook installs throttles via `installThrottle`,
+ * the LLM callers consult `shouldFire` / `decide`, and a throttle auto-expires
+ * after its TTL elapses. Per the umbrella spec §"Signal-vs-Authority
+ * Decomposition", the gate enforces decisions made elsewhere — it never
+ * decides anything on its own.
  *
- * Future phases (per docs/specs/token-burn-detection-and-self-heal.md):
- *   - Phase 4 (burn-throttle runbook): the Remediator-Tier-2 runbook stores
- *     signed throttle decisions; the gate consults that store.
- *   - Phase 4 (HMAC-signed jobs.json.throttle-overrides): scheduled-job
- *     overrides land via this gate so the same actuator covers cron entries.
+ * State: in-memory only. The throttle store is process-local. If the agent
+ * restarts, any in-memory throttle is dropped — which is the right default
+ * (a restart is itself a reset, and the burn-detector will re-emit any
+ * surviving signal within 60s). Persistent throttles for scheduled-job cron
+ * entries live in a separate file (`.instar/jobs.json.throttle-overrides`,
+ * HMAC-signed) handled by the scheduler — out of scope for this primitive.
  *
- * Authority shape: the gate ENFORCES decisions that were made elsewhere. It
- * does NOT decide. Brittle threshold detectors must never write to this
- * gate directly — only the Remediator (with signed-context Tier-2 capability
- * tokens) can install a throttle. This honours the signal-vs-authority
- * boundary in docs/signal-vs-authority.md.
- *
- * Singleton-per-process: every LLM caller in the process shares one gate so
- * a single throttle decision covers every code path that uses the same
- * attribution key. The class exposes a static `instance()` accessor; tests
- * use the public constructor + `reset()` to isolate from the singleton.
+ * Authority: the gate accepts throttles only via `installThrottle`, which the
+ * runbook calls with a capability token. The token is verified by the gate
+ * against the agent's HMAC key (passed at constructor time when the gate
+ * needs to enforce, or skipped for tests). When no key is configured, the
+ * gate accepts throttles without verification — that's the "trusted local
+ * caller" mode used by the runbook before the F-8 capability surface fully
+ * lands. The verification path is in place so the runbook can switch to
+ * signed tokens without API churn.
  */
+import crypto from 'node:crypto';
 export class LlmRateGate {
     static singleton = null;
+    throttles = new Map();
+    capabilityKey;
+    now;
+    /**
+     * Consumed signal IDs — replay-prevention nonces. Per Phase 4 second-pass
+     * review §1. Garbage-collected lazily during `installThrottle`: entries
+     * older than the maximum throttle TTL (2× the longest seen) can be
+     * dropped because their corresponding throttle has long since expired.
+     */
+    consumedSignalIds = new Map();
+    /** Tracks the longest throttle duration seen, used for GC of consumed IDs. */
+    maxThrottleDurationMs = 60 * 60 * 1000;
+    constructor(opts) {
+        this.capabilityKey = opts?.capabilityKey ?? null;
+        this.now = opts?.now ?? (() => Date.now());
+    }
     /**
      * Process-wide singleton. Tests should use `new LlmRateGate()` + `reset()`
      * rather than this accessor, so they don't bleed throttles into each other.
@@ -37,46 +54,162 @@ export class LlmRateGate {
         return LlmRateGate.singleton;
     }
     /**
-     * Phase 1: always returns true. The signature is stable so callers can
-     * adopt the consult-before-call pattern today; future phases enforce it.
+     * Read-side: does the gate currently allow a call for this key?
      *
-     * @param attributionKey  componentName::promptFingerprint key. Reserved
-     *                        values: keys starting with `burn-throttle-runbook::`
-     *                        are exempt by design (self-reinforcing-loop guard
-     *                        per spec §"Self-reinforcing loop guard").
+     * @param attributionKey componentName::promptFingerprint. Reserved prefix
+     *                       `burn-throttle-runbook::*` is structurally exempt
+     *                       (self-reinforcing-loop guard).
      */
     shouldFire(attributionKey) {
         return this.decide(attributionKey).allowed;
     }
-    /**
-     * Same as shouldFire() but returns the full decision record. Useful for
-     * tests and for the burn-throttle runbook's verification step.
-     */
     decide(attributionKey) {
-        // Self-attribution exempt (spec §"Self-reinforcing loop guard"): the
-        // runbook's own LLM calls cannot be throttled by the runbook's own
-        // decisions, ever. This is the structural floor that prevents a
-        // deadlock where the throttle stops the alert from being sent.
+        const decidedAt = new Date(this.now()).toISOString();
         if (attributionKey.startsWith('burn-throttle-runbook::')) {
-            return {
-                allowed: true,
-                decidedAt: new Date().toISOString(),
-                reason: 'phase-1-noop',
-            };
+            return { allowed: true, decidedAt, reason: 'runbook-self-exempt' };
+        }
+        const throttle = this.throttles.get(attributionKey);
+        if (!throttle) {
+            return { allowed: true, decidedAt, reason: 'no-throttle-installed' };
+        }
+        const expiresMs = Date.parse(throttle.expiresAt);
+        if (Number.isNaN(expiresMs) || this.now() >= expiresMs) {
+            // Auto-revert on read — keeps the map small and avoids stale reads.
+            this.throttles.delete(attributionKey);
+            return { allowed: true, decidedAt, reason: 'throttle-expired' };
         }
         return {
-            allowed: true,
-            decidedAt: new Date().toISOString(),
-            reason: 'phase-1-noop',
+            allowed: false,
+            decidedAt,
+            reason: 'throttle-active',
+            throttleExpiresAt: throttle.expiresAt,
+        };
+    }
+    /**
+     * Install a throttle for an attribution key. Called by the burn-throttle
+     * runbook. Refuses keys with the runbook-self exempt prefix as a defence
+     * in depth (the gate also exempts on the read path).
+     *
+     * Returns the InstalledThrottle if accepted, or throws on:
+     *   - Self-attribution attempts.
+     *   - Capability-token verification failure (when key is configured).
+     *   - Zero/negative duration.
+     */
+    installThrottle(input) {
+        if (input.attributionKey.startsWith('burn-throttle-runbook::')) {
+            throw new Error('Refusing to install throttle on runbook-self attribution key (self-reinforcing-loop guard).');
+        }
+        if (input.durationMs <= 0) {
+            throw new Error(`Throttle duration must be positive (got ${input.durationMs}).`);
+        }
+        if (!input.signalId || input.signalId.length === 0) {
+            throw new Error('LlmRateGate.installThrottle: signalId is required (replay-prevention nonce).');
+        }
+        // Replay-prevention: a signalId may install at most one throttle. The
+        // map is GC'd lazily below. Per Phase 4 second-pass review §1.
+        if (this.consumedSignalIds.has(input.signalId)) {
+            throw new Error(`LlmRateGate.installThrottle: signalId ${input.signalId} has already been consumed (replay refused).`);
+        }
+        // Capability-token verification when a key is configured. The canonical
+        // payload includes signalId so captured tokens cannot be replayed with a
+        // different signal context.
+        if (this.capabilityKey) {
+            const expected = this.signWithKey({
+                attributionKey: input.attributionKey,
+                durationMs: input.durationMs,
+                issuer: input.issuer,
+                signalId: input.signalId,
+            });
+            if (!input.capabilityToken || input.capabilityToken !== expected) {
+                throw new Error('LlmRateGate.installThrottle: invalid or missing capability token.');
+            }
+        }
+        const nowMs = this.now();
+        const nowIso = new Date(nowMs).toISOString();
+        const expiresIso = new Date(nowMs + input.durationMs).toISOString();
+        const throttle = {
+            attributionKey: input.attributionKey,
+            installedAt: nowIso,
+            expiresAt: expiresIso,
+            reason: input.reason,
+            issuer: input.issuer,
         };
+        this.throttles.set(input.attributionKey, throttle);
+        this.consumedSignalIds.set(input.signalId, nowMs);
+        // Track the longest duration we've ever seen for GC bookkeeping.
+        if (input.durationMs > this.maxThrottleDurationMs) {
+            this.maxThrottleDurationMs = input.durationMs;
+        }
+        // GC consumed signal IDs older than 2x the longest throttle TTL.
+        const gcCutoff = nowMs - 2 * this.maxThrottleDurationMs;
+        for (const [sigId, sigTs] of this.consumedSignalIds.entries()) {
+            if (sigTs < gcCutoff)
+                this.consumedSignalIds.delete(sigId);
+        }
+        return throttle;
+    }
+    signWithKey(payload) {
+        const canonical = JSON.stringify({
+            attributionKey: payload.attributionKey,
+            durationMs: payload.durationMs,
+            issuer: payload.issuer,
+            signalId: payload.signalId,
+        });
+        return crypto.createHmac('sha256', this.capabilityKey).update(canonical).digest('hex');
+    }
+    /**
+     * Revoke an active throttle. Idempotent (no-op if no throttle exists).
+     * Called by the Telegram inline-button handler in Phase 5 and by the
+     * runbook's manual-override path.
+     */
+    revokeThrottle(attributionKey) {
+        return this.throttles.delete(attributionKey);
+    }
+    /**
+     * List currently-active throttles. Used by the verification step (Phase 6)
+     * and by the dashboard surface.
+     */
+    listActiveThrottles() {
+        const now = this.now();
+        const active = [];
+        for (const [key, throttle] of this.throttles.entries()) {
+            const expiresMs = Date.parse(throttle.expiresAt);
+            if (!Number.isNaN(expiresMs) && now < expiresMs) {
+                active.push(throttle);
+            }
+            else {
+                this.throttles.delete(key);
+            }
+        }
+        return active;
+    }
+    /**
+     * Compute the capability token for an install payload. Used by the
+     * runbook to sign its own throttle requests. Returns null when no
+     * capability key is configured (test mode).
+     *
+     * **Threat-model note (Phase 4 second-pass review §2):** this mint and the
+     * verification it pairs with both live on the same gate object, so any
+     * in-process caller holding a gate reference can forge a valid token. The
+     * HMAC therefore defends the **external/cross-process boundary** only
+     * — chiefly the persistent throttle-overrides file the scheduler reads
+     * (Phase 4-extension, not in this PR). For in-process integrity we rely
+     * on the fact that all callers of LlmRateGate are instar source under
+     * the same `/instar-dev` review gate. If/when the runbook is moved to a
+     * separate process, this mint method should be relocated to the runbook
+     * service alone and removed from the gate's API surface.
+     */
+    computeCapabilityToken(input) {
+        if (!this.capabilityKey)
+            return null;
+        return this.signWithKey(input);
     }
     /**
-     * Reset all installed throttles. Phase 1 has no throttles, so this is a
-     * no-op; future phases will clear the in-memory throttle map. Exposed for
-     * tests so a misconfigured singleton can't bleed across `describe` blocks.
+     * Reset all installed throttles. Exposed for tests so a misconfigured
+     * singleton can't bleed across `describe` blocks.
      */
     reset() {
-        // Phase 1: no state to reset. Intentional empty body.
+        this.throttles.clear();
     }
 }
 //# sourceMappingURL=LlmRateGate.js.map

package/dist/monitoring/LlmRateGate.js.map

@@ -1 +1 @@
-{"version":3,"file":"LlmRateGate.js","sourceRoot":"","sources":["../../src/monitoring/LlmRateGate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAWH,MAAM,OAAO,WAAW;IACd,MAAM,CAAC,SAAS,GAAuB,IAAI,CAAC;IAEpD;;;OAGG;IACH,MAAM,CAAC,QAAQ;QACb,IAAI,CAAC,WAAW,CAAC,SAAS,EAAE,CAAC;YAC3B,WAAW,CAAC,SAAS,GAAG,IAAI,WAAW,EAAE,CAAC;QAC5C,CAAC;QACD,OAAO,WAAW,CAAC,SAAS,CAAC;IAC/B,CAAC;IAED;;;;;;;;OAQG;IACH,UAAU,CAAC,cAAsB;QAC/B,OAAO,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,OAAO,CAAC;IAC7C,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,cAAsB;QAC3B,qEAAqE;QACrE,mEAAmE;QACnE,gEAAgE;QAChE,+DAA+D;QAC/D,IAAI,cAAc,CAAC,UAAU,CAAC,yBAAyB,CAAC,EAAE,CAAC;YACzD,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;gBACnC,MAAM,EAAE,cAAc;aACvB,CAAC;QACJ,CAAC;QACD,OAAO;YACL,OAAO,EAAE,IAAI;YACb,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,MAAM,EAAE,cAAc;SACvB,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACH,KAAK;QACH,sDAAsD;IACxD,CAAC"}
+{"version":3,"file":"LlmRateGate.js","sourceRoot":"","sources":["../../src/monitoring/LlmRateGate.ts"],"names":[],"mappings":"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"}

package/dist/monitoring/TokenLedger.d.ts

@@ -35,6 +35,13 @@ export interface ProjectRow {
     eventCount: number;
     sessionCount: number;
 }
+export interface AttributionKeyRow {
+    attributionKey: string;
+    totalTokens: number;
+    eventCount: number;
+    firstTs: number;
+    lastTs: number;
+}
 export interface OrphanRow {
     sessionId: string;
     projectPath: string | null;
@@ -147,6 +154,15 @@ export declare class TokenLedger {
     byProject({ sinceMs }?: {
         sinceMs?: number;
     }): ProjectRow[];
+    /**
+     * Aggregate by attribution key (Phase 3 of burn-detection-and-self-heal
+     * spec). Returns one row per key with totals, event count, and the time
+     * window the key has been seen across the requested period.
+     */
+    byAttributionKey({ sinceMs, limit }?: {
+        sinceMs?: number;
+        limit?: number;
+    }): AttributionKeyRow[];
     /** Sessions whose newest event is older than `idleMs` ago. */
     orphans({ idleMs }: {
         idleMs: number;

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

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

package/dist/monitoring/TokenLedger.js

@@ -551,6 +551,34 @@ export class TokenLedger {
             sessionCount: Number(r.sessionCount) || 0,
         }));
     }
+    /**
+     * Aggregate by attribution key (Phase 3 of burn-detection-and-self-heal
+     * spec). Returns one row per key with totals, event count, and the time
+     * window the key has been seen across the requested period.
+     */
+    byAttributionKey({ sinceMs, limit = 100 } = {}) {
+        const since = sinceMs ?? 0;
+        const rows = this.db
+            .prepare(`SELECT
+           attribution_key AS attributionKey,
+           SUM(input_tokens + output_tokens + cache_creation_tokens + cache_read_tokens) AS totalTokens,
+           COUNT(*) AS eventCount,
+           MIN(ts) AS firstTs,
+           MAX(ts) AS lastTs
+         FROM token_events
+         WHERE ts >= ?
+         GROUP BY attribution_key
+         ORDER BY totalTokens DESC
+         LIMIT ?`)
+            .all(since, limit);
+        return rows.map(r => ({
+            attributionKey: r.attributionKey,
+            totalTokens: Number(r.totalTokens) || 0,
+            eventCount: Number(r.eventCount) || 0,
+            firstTs: Number(r.firstTs) || 0,
+            lastTs: Number(r.lastTs) || 0,
+        }));
+    }
     /** Sessions whose newest event is older than `idleMs` ago. */
     orphans({ idleMs }) {
         const now = Date.now();