vigiles 12.0.0 → 12.2.0

package/dist/eval-cost.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Eval cost transparency — make what a real-model run SPENT impossible to miss.
+ * vigiles's whole affordability pitch is "runs on your Claude subscription, not a
+ * metered API," so every real-model run should say — out loud — how many tokens it
+ * spent, the API-equivalent dollar cost, and (loudly) if it was billed to a
+ * METERED API key instead of your subscription.
+ *
+ * HONEST SCOPE: we surface tokens + the API-equivalent `$` (`total_cost_usd` from
+ * the `claude` CLI) + a running session tally. We deliberately do NOT show a
+ * "% of your subscription" — Anthropic does not expose a subscription's quota or
+ * limit programmatically (and the real limits are rolling rate windows, not a
+ * dollar bucket), so any percentage would be fiction. See docs/eval-architecture.md.
+ *
+ * Pure + injectable (env + an output sink), so the whole thing is unit-tested
+ * without a model or a real key.
+ */
+import type { EvalUsage, ArmUsage, EvalReport } from "./eval.js";
+/** A normalized cost/token snapshot — the common shape a report renders from. */
+export interface CostSummary {
+    /** API-equivalent cost (`total_cost_usd`) — the number that matters. */
+    readonly costUsd: number;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cacheCreationTokens: number;
+    readonly cacheReadTokens: number;
+}
+/** Total tokens across all four billing buckets. */
+export declare function totalTokens(c: CostSummary): number;
+/** A per-run {@link EvalUsage} → the common snapshot. */
+export declare function costFromRun(u: EvalUsage): CostSummary;
+/** An aggregated per-arm {@link ArmUsage} → the common snapshot. */
+export declare function costFromArm(u: ArmUsage): CostSummary;
+/** Sum any number of snapshots (e.g. every arm of an A/B). */
+export declare function sumCosts(costs: readonly CostSummary[]): CostSummary;
+/** The whole-{@link EvalReport} cost — every arm summed. */
+export declare function costFromEvalReport(report: EvalReport): CostSummary;
+/**
+ * How the run was billed. `metered` is true when a real Anthropic API key is in
+ * the environment — the `claude` CLI bills those PER TOKEN, whereas a
+ * subscription run (auth via `~/.claude`, no key var) costs $0 beyond the sub.
+ * The mock/deterministic tier never reaches here (it has no real cost), so a
+ * present key means a real metered run.
+ */
+export interface Billing {
+    readonly metered: boolean;
+    /** Which env var carried the key (for the actionable "unset X" message). */
+    readonly keyVar: string | null;
+}
+export declare function detectBilling(env?: NodeJS.ProcessEnv): Billing;
+/** Add a run to the running session total and return the new total. */
+export declare function recordSessionCost(c: CostSummary): CostSummary;
+/** The session total so far. */
+export declare function sessionCost(): CostSummary;
+/** Reset the session tally (test seam). */
+export declare function resetSessionCost(): void;
+/**
+ * The human-readable cost block for a run. Shows tokens + API-equivalent `$`, the
+ * billed-to line (a LOUD warning + an actionable fix when metered, a green ✅ when
+ * on the subscription), and the session tally when it exceeds this run.
+ */
+export declare function formatCostSummary(c: CostSummary, opts: {
+    billing: Billing;
+    session?: CostSummary | null;
+}): string;
+/**
+ * Record `c` into the session tally and emit its cost block. The default sink is
+ * stderr (so a run's cost never pollutes `--json` stdout). Injectable env + sink
+ * keep it fully testable. Returns the emitted text (also handy for a skill to
+ * relay to the user).
+ */
+export declare function emitCostSummary(c: CostSummary, opts?: {
+    env?: NodeJS.ProcessEnv;
+    out?: (s: string) => void;
+}): string;
+//# sourceMappingURL=eval-cost.d.ts.map

package/dist/eval-cost.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.totalTokens = totalTokens;
+exports.costFromRun = costFromRun;
+exports.costFromArm = costFromArm;
+exports.sumCosts = sumCosts;
+exports.costFromEvalReport = costFromEvalReport;
+exports.detectBilling = detectBilling;
+exports.recordSessionCost = recordSessionCost;
+exports.sessionCost = sessionCost;
+exports.resetSessionCost = resetSessionCost;
+exports.formatCostSummary = formatCostSummary;
+exports.emitCostSummary = emitCostSummary;
+const ZERO = {
+    costUsd: 0,
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheCreationTokens: 0,
+    cacheReadTokens: 0,
+};
+/** Total tokens across all four billing buckets. */
+function totalTokens(c) {
+    return (c.inputTokens + c.outputTokens + c.cacheCreationTokens + c.cacheReadTokens);
+}
+/** A per-run {@link EvalUsage} → the common snapshot. */
+function costFromRun(u) {
+    return {
+        costUsd: u.costUsd,
+        inputTokens: u.inputTokens,
+        outputTokens: u.outputTokens,
+        cacheCreationTokens: u.cacheCreationTokens,
+        cacheReadTokens: u.cacheReadTokens,
+    };
+}
+/** An aggregated per-arm {@link ArmUsage} → the common snapshot. */
+function costFromArm(u) {
+    return {
+        costUsd: u.totalCostUsd,
+        inputTokens: u.totalInputTokens,
+        outputTokens: u.totalOutputTokens,
+        cacheCreationTokens: u.totalCacheCreationTokens,
+        cacheReadTokens: u.totalCacheReadTokens,
+    };
+}
+/** Sum any number of snapshots (e.g. every arm of an A/B). */
+function sumCosts(costs) {
+    return costs.reduce((a, c) => ({
+        costUsd: a.costUsd + c.costUsd,
+        inputTokens: a.inputTokens + c.inputTokens,
+        outputTokens: a.outputTokens + c.outputTokens,
+        cacheCreationTokens: a.cacheCreationTokens + c.cacheCreationTokens,
+        cacheReadTokens: a.cacheReadTokens + c.cacheReadTokens,
+    }), ZERO);
+}
+/** The whole-{@link EvalReport} cost — every arm summed. */
+function costFromEvalReport(report) {
+    return sumCosts(Object.values(report.arms).map((a) => costFromArm(a.usage)));
+}
+const KEY_VARS = ["ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"];
+function detectBilling(env = process.env) {
+    for (const v of KEY_VARS) {
+        const val = env[v];
+        if (val !== undefined && val.trim() !== "")
+            return { metered: true, keyVar: v };
+    }
+    return { metered: false, keyVar: null };
+}
+// --- Session tally (within one process) ------------------------------------
+let SESSION = ZERO;
+/** Add a run to the running session total and return the new total. */
+function recordSessionCost(c) {
+    SESSION = sumCosts([SESSION, c]);
+    return SESSION;
+}
+/** The session total so far. */
+function sessionCost() {
+    return SESSION;
+}
+/** Reset the session tally (test seam). */
+function resetSessionCost() {
+    SESSION = ZERO;
+}
+// --- Formatting ------------------------------------------------------------
+function fmtUsd(n) {
+    return `$${n < 0.01 && n > 0 ? n.toFixed(4) : n.toFixed(2)}`;
+}
+function fmtInt(n) {
+    return Math.round(n).toLocaleString("en-US");
+}
+function fmtK(n) {
+    return n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(Math.round(n));
+}
+/**
+ * The human-readable cost block for a run. Shows tokens + API-equivalent `$`, the
+ * billed-to line (a LOUD warning + an actionable fix when metered, a green ✅ when
+ * on the subscription), and the session tally when it exceeds this run.
+ */
+function formatCostSummary(c, opts) {
+    const lines = [];
+    lines.push(`  Spent: ${fmtInt(totalTokens(c))} tokens ` +
+        `(${fmtK(c.inputTokens)} in · ${fmtK(c.outputTokens)} out · ${fmtK(c.cacheReadTokens)} cache) ` +
+        `· ~${fmtUsd(c.costUsd)} API-equivalent`);
+    if (opts.billing.metered) {
+        const v = opts.billing.keyVar ?? "ANTHROPIC_API_KEY";
+        lines.push(`  ⚠ Billed to: METERED API (${v} is set) — you paid ~${fmtUsd(c.costUsd)} this run.`, `     Run it free on your Claude subscription: unset ${v}, then \`claude login\`.`);
+    }
+    else {
+        lines.push(`  Billed to: your Claude subscription — $0 metered ✅`);
+    }
+    if (opts.session && opts.session.costUsd > c.costUsd) {
+        lines.push(`  Session so far: ${fmtInt(totalTokens(opts.session))} tokens · ~${fmtUsd(opts.session.costUsd)} API-equivalent`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Record `c` into the session tally and emit its cost block. The default sink is
+ * stderr (so a run's cost never pollutes `--json` stdout). Injectable env + sink
+ * keep it fully testable. Returns the emitted text (also handy for a skill to
+ * relay to the user).
+ */
+function emitCostSummary(c, opts = {}) {
+    // A no-cost run (a replay, a zero-trial eval) has nothing to report.
+    if (totalTokens(c) === 0 && c.costUsd === 0)
+        return "";
+    const billing = detectBilling(opts.env ?? process.env);
+    const session = recordSessionCost(c);
+    const text = formatCostSummary(c, { billing, session });
+    (opts.out ??
+        ((s) => {
+            console.error(s);
+        }))(text);
+    return text;
+}
+//# sourceMappingURL=eval-cost.js.map

package/dist/eval.d.ts

@@ -327,6 +327,8 @@ export interface CheckRate {
 export interface CheckReport {
     readonly n: number;
     readonly perCheck: readonly CheckRate[];
+    /** Cost / latency / token totals for the run (the same source as `runEval`). */
+    readonly usage: ArmUsage;
 }
 /**
  * Score a check vocabulary across trials — the scored counterpart to
@@ -714,6 +716,8 @@ export interface TriggerRateReport {
      * `n` means the measurement is thin (e.g. a Codex usage limit was hit); re-run.
      */
     readonly errored?: number;
+    /** Cost / tokens SPENT across all runs (relevant + irrelevant) — feeds the cost summary. */
+    readonly usage: ArmUsage;
 }
 /**
  * An eval-tier transport: how to RUN a real harness turn and PARSE its output.

package/dist/eval.js

@@ -65,8 +65,10 @@ const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
+const observe_js_1 = require("./observe.js");
 const plugin_loader_js_1 = require("./adapters/claude-code/plugin-loader.js");
 const runtime_js_1 = require("./adapters/claude-code/runtime.js");
+const eval_cost_js_1 = require("./eval-cost.js");
 const proofs_js_1 = require("./core/proofs.js");
 const harness_test_js_1 = require("./harness-test.js");
 const eval_cache_js_1 = require("./eval-cache.js");
@@ -144,7 +146,11 @@ function spawnAgent(a) {
  * `runEvalWith` with the real agent runner.
  */
 async function runEval(spec) {
-    return runEvalWith(spec, spawnAgent);
+    const report = await runEvalWith(spec, spawnAgent);
+    // Surface what the run spent — tokens + API-equivalent $, and a LOUD warning if
+    // it was billed to a metered API key instead of the subscription. See eval-cost.ts.
+    (0, eval_cost_js_1.emitCostSummary)((0, eval_cost_js_1.costFromEvalReport)(report));
+    return report;
 }
 /**
  * Score a check vocabulary across trials — the scored counterpart to
@@ -201,6 +207,7 @@ async function measureWith(spec, runner) {
                     n: s?.n ?? 0,
                 };
             }),
+            usage: arm?.usage ?? aggregateUsage([]),
         };
     }
     finally {
@@ -211,7 +218,9 @@ async function measureWith(spec, runner) {
 /* v8 ignore start -- real claude subprocess; thin wrapper over measureWith */
 /** Score a check vocabulary across trials against the real `claude` CLI. */
 async function measure(spec) {
-    return measureWith(spec, spawnAgent);
+    const report = await measureWith(spec, spawnAgent);
+    (0, eval_cost_js_1.emitCostSummary)((0, eval_cost_js_1.costFromArm)(report.usage));
+    return report;
 }
 /** Score checks across arms (injectable runner). Reuses `runEvalWith`. */
 async function measureArmsWith(spec, runner) {
@@ -245,6 +254,7 @@ async function measureArmsWith(spec, runner) {
                         n: s?.n ?? 0,
                     };
                 }),
+                usage: arm.usage,
             };
         }
         return { arms };
@@ -278,7 +288,10 @@ function stubArmPluginDirs(arms) {
 /* v8 ignore start -- real claude subprocess; thin wrapper over measureArmsWith */
 /** Score checks across arms against the real `claude` CLI. */
 async function measureArms(spec) {
-    return measureArmsWith(spec, spawnAgent);
+    const report = await measureArmsWith(spec, spawnAgent);
+    // Sum every arm's spend — an A/B run pays for both arms.
+    (0, eval_cost_js_1.emitCostSummary)((0, eval_cost_js_1.sumCosts)(Object.values(report.arms).map((a) => (0, eval_cost_js_1.costFromArm)(a.usage))));
+    return report;
 }
 /* v8 ignore stop */
 /**
@@ -1496,13 +1509,17 @@ async function runTriggerTrial(prompt, cfg, runner) {
             pluginDir: cfg.pluginDir,
             timeoutMs: cfg.timeoutMs,
         });
+        // Usage comes from the parser (harness-neutral: Claude + Codex both fill it),
+        // and a run costs tokens even when it errors — so accumulate it either way.
+        const ctx = makeContext(cwd, out, cfg.parse);
         // An errored/rate-limited turn is NOT a "skill didn't fire" miss — it's
         // excluded from the rate, so e.g. a Codex usage limit can't read as recall 0.
         if (cfg.runError?.(out))
-            return { fired: 0, errored: true };
+            return { fired: 0, errored: true, usage: ctx.usage };
         return {
-            fired: cfg.fired(makeContext(cwd, out, cfg.parse)) ? 1 : 0,
+            fired: cfg.fired(ctx) ? 1 : 0,
             errored: false,
+            usage: ctx.usage,
         };
     }
     finally {
@@ -1539,6 +1556,7 @@ async function runTriggerSet(prompts, cfg, runner) {
         fired: firedBy.reduce((a, b) => a + b, 0),
         n: trialsBy.reduce((a, b) => a + b, 0),
         errored,
+        usages: outcomes.map((o) => o.usage),
     };
 }
 /**
@@ -1624,6 +1642,7 @@ async function measureTriggerRateWith(spec, runner, parse = parseClaudeRun, runE
                 perPrompt: relevant.perPrompt,
                 competitors,
                 errored: positiveOrUndefined(relevant.errored),
+                usage: aggregateUsage(relevant.usages),
             };
             if ((spec.irrelevantPrompts?.length ?? 0) === 0)
                 return base;
@@ -1635,6 +1654,8 @@ async function measureTriggerRateWith(spec, runner, parse = parseClaudeRun, runE
                 falsePositiveRate: irrelevant.n > 0 ? irrelevant.fired / irrelevant.n : 0,
                 precision: fires > 0 ? relevant.fired / fires : undefined,
                 perIrrelevant: irrelevant.perPrompt,
+                // Total cost across BOTH sets (the precision runs cost tokens too).
+                usage: aggregateUsage([...relevant.usages, ...irrelevant.usages]),
             };
         });
     }
@@ -1654,7 +1675,26 @@ async function measureTriggerRateWith(spec, runner, parse = parseClaudeRun, runE
  */
 async function measureTriggerRate(spec, opts = {}) {
     const d = opts.evalDriver ?? exports.claudeEvalDriver;
-    return measureTriggerRateWith(spec, d.runner, d.parse, d.runError, d.harness ?? "claude-code");
+    const report = await measureTriggerRateWith(spec, d.runner, d.parse, d.runError, d.harness ?? "claude-code");
+    // Surface what the run spent (tokens + API-equivalent $ + metered warning).
+    (0, eval_cost_js_1.emitCostSummary)((0, eval_cost_js_1.costFromArm)(report.usage));
+    // Feed the flight recorder: recall (+ precision when measured) for this skill.
+    const evalName = spec.name ?? "trigger-rate";
+    (0, observe_js_1.appendObservation)({
+        kind: "eval",
+        name: evalName,
+        metric: "recall",
+        value: report.rate,
+    });
+    if (report.precision !== undefined) {
+        (0, observe_js_1.appendObservation)({
+            kind: "eval",
+            name: evalName,
+            metric: "precision",
+            value: report.precision,
+        });
+    }
+    return report;
 }
 /* v8 ignore stop */
 /** Format a trigger-rate report: overall %, then each prompt's rate. */

package/dist/observe.d.ts

@@ -0,0 +1,109 @@
+/** Bumped when the record shape changes in a non-additive way. */
+export declare const OBSERVE_VERSION = 1;
+/** The ledger filename under the `.vigiles/` directory. */
+export declare const LEDGER_FILE = "runs.jsonl";
+/** Fields every record carries; `v`/`ts` are stamped by the writer, not the caller. */
+export interface ObservationBase {
+    /** schema version (`OBSERVE_VERSION`) */
+    v: number;
+    /** ISO-8601 timestamp */
+    ts: string;
+}
+/** A gate/hook decision observed in a real session. */
+export interface HookObservation extends ObservationBase {
+    kind: "hook";
+    event: string;
+    decision: "allow" | "deny" | "ask";
+    /** the compiled-hook rule/name, when known */
+    rule?: string;
+    /** enforce actually blocked; observe recorded a would-be block */
+    mode?: "enforce" | "observe";
+    /** the bash command inspected, when the gate keyed on one */
+    cmd?: string;
+    reason?: string;
+}
+/** A subagent tool-contract decision (the PreToolUse rail). */
+export interface AgentObservation extends ObservationBase {
+    kind: "agent";
+    /** the dispatched subagent */
+    name: string;
+    tool: string;
+    allowed: boolean;
+    reason?: string;
+}
+/** Whether a skill fired for a turn (behavioral surface — best-effort per harness). */
+export interface SkillObservation extends ObservationBase {
+    kind: "skill";
+    name: string;
+    fired: boolean;
+}
+/** A measured eval outcome (recall, cost, a check rate, …). */
+export interface EvalObservation extends ObservationBase {
+    kind: "eval";
+    name: string;
+    metric: string;
+    value: number;
+}
+/** A capability/blast-radius change observed at PR time. */
+export interface CapabilityDiffObservation extends ObservationBase {
+    kind: "capability-diff";
+    pr?: number;
+    added: string[];
+    removed?: string[];
+    /** true when the change loosened the agent's effect surface */
+    widened: boolean;
+}
+/** The discriminated union every reader narrows on `kind`. */
+export type ObservationRecord = HookObservation | AgentObservation | SkillObservation | EvalObservation | CapabilityDiffObservation;
+/** What a caller supplies — the writer stamps `v` + `ts`. */
+export type ObservationInput = Omit<HookObservation, "v" | "ts"> | Omit<AgentObservation, "v" | "ts"> | Omit<SkillObservation, "v" | "ts"> | Omit<EvalObservation, "v" | "ts"> | Omit<CapabilityDiffObservation, "v" | "ts">;
+/** Serialize one record to a single JSONL line (trailing newline included). */
+export declare function formatObservation(record: ObservationRecord): string;
+/**
+ * Append one observation to `<cwd>/.vigiles/runs.jsonl`. Best-effort: any failure is
+ * swallowed so recording can never break a live session (the `ts`/`clock` here is a
+ * runtime side effect, intentionally — this module records reality, it is not a spec).
+ */
+export declare function appendObservation(input: ObservationInput, cwd?: string): void;
+/**
+ * Read the ledger back. Tolerant by design: a malformed or partially-written line is
+ * skipped rather than throwing, so a torn append never nukes the whole read.
+ */
+export declare function readObservations(cwd?: string): ObservationRecord[];
+/** Filter the ledger to one record kind, narrowing the type for the caller. */
+export declare function observationsOfKind<K extends ObservationRecord["kind"]>(records: readonly ObservationRecord[], kind: K): Extract<ObservationRecord, {
+    kind: K;
+}>[];
+/** A denial rendered as a structured `{label, reason}` — the shared shape the
+ *  terminal line and the JSON summary both derive from (one-detector-no-drift). */
+export interface LedgerDenial {
+    readonly label: string;
+    readonly reason: string;
+}
+/** Per-kind record count. */
+export interface LedgerCount {
+    readonly kind: ObservationRecord["kind"];
+    readonly count: number;
+}
+/** The structured ledger summary carried in the versioned AuditReport JSON. */
+export interface LedgerSummary {
+    readonly total: number;
+    readonly counts: readonly LedgerCount[];
+    readonly denials: number;
+    /** The most recent denials (blocked gates / out-of-contract tool calls). */
+    readonly recentDenials: readonly LedgerDenial[];
+}
+/**
+ * The structured ledger summary for the AuditReport JSON — total, per-kind counts,
+ * and the recent denials. `undefined` when nothing is recorded, so the report field
+ * stays absent (additive/optional). Shares `isDenial`/`denialParts` with the
+ * terminal `formatLedgerSummary` so the two can't drift.
+ */
+export declare function summarizeObservations(records: readonly ObservationRecord[]): LedgerSummary | undefined;
+/**
+ * A compact human summary of the ledger for `vigiles audit` — total, counts by kind,
+ * and the recent high-signal denials. Empty string when there is nothing recorded, so
+ * the caller can skip the section entirely.
+ */
+export declare function formatLedgerSummary(records: readonly ObservationRecord[]): string;
+//# sourceMappingURL=observe.d.ts.map

package/dist/observe.js

@@ -0,0 +1,164 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LEDGER_FILE = exports.OBSERVE_VERSION = void 0;
+exports.formatObservation = formatObservation;
+exports.appendObservation = appendObservation;
+exports.readObservations = readObservations;
+exports.observationsOfKind = observationsOfKind;
+exports.summarizeObservations = summarizeObservations;
+exports.formatLedgerSummary = formatLedgerSummary;
+/**
+ * The local, agent-readable "flight recorder" ledger — `.vigiles/runs.jsonl`.
+ *
+ * The connective layer of the four-instrument loop (see the Direction section of
+ * CLAUDE.md and `research/harness-observability-direction.md`): every instrument
+ * (verify / gate / measure / observe) appends a typed record here, and the file is
+ * read three ways off ONE schema — by `vigiles audit`, by the agent debugging its own
+ * harness, and (later) by an aggregation surface.
+ *
+ * Harness-agnostic by construction: the record kinds are neutral concepts, so this
+ * lives at the composition/library root (adapters + cli CALL it; it imports no adapter,
+ * and it is NOT part of the reference-verification `core/` domain).
+ *
+ * Append is best-effort — recording must never break a live session.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/** Bumped when the record shape changes in a non-additive way. */
+exports.OBSERVE_VERSION = 1;
+/** The ledger filename under the `.vigiles/` directory. */
+exports.LEDGER_FILE = "runs.jsonl";
+/** Serialize one record to a single JSONL line (trailing newline included). */
+function formatObservation(record) {
+    return JSON.stringify(record) + "\n";
+}
+/**
+ * Append one observation to `<cwd>/.vigiles/runs.jsonl`. Best-effort: any failure is
+ * swallowed so recording can never break a live session (the `ts`/`clock` here is a
+ * runtime side effect, intentionally — this module records reality, it is not a spec).
+ */
+function appendObservation(input, cwd = process.cwd()) {
+    try {
+        const dir = (0, node_path_1.resolve)(cwd, ".vigiles");
+        (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+        const record = {
+            v: exports.OBSERVE_VERSION,
+            ts: new Date().toISOString(),
+            ...input,
+        };
+        (0, node_fs_1.appendFileSync)((0, node_path_1.resolve)(dir, exports.LEDGER_FILE), formatObservation(record));
+    }
+    catch {
+        /* best-effort — recording is never allowed to break a session */
+    }
+}
+/**
+ * Read the ledger back. Tolerant by design: a malformed or partially-written line is
+ * skipped rather than throwing, so a torn append never nukes the whole read.
+ */
+function readObservations(cwd = process.cwd()) {
+    let raw;
+    try {
+        raw = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(cwd, ".vigiles", exports.LEDGER_FILE), "utf8");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        const parsed = tryParseRecord(trimmed);
+        if (parsed)
+            out.push(parsed);
+    }
+    return out;
+}
+/** Filter the ledger to one record kind, narrowing the type for the caller. */
+function observationsOfKind(records, kind) {
+    return records.filter((r) => r.kind === kind);
+}
+/** Was this record a denial (a blocked gate or an out-of-contract tool call)? */
+function isDenial(r) {
+    return ((r.kind === "hook" && r.decision === "deny") ||
+        (r.kind === "agent" && !r.allowed));
+}
+/** Structured description of a denial (the single source for label + reason). */
+function denialParts(r) {
+    if (r.kind === "hook")
+        return { label: `hook ${r.rule ?? r.event}`, reason: r.reason ?? "denied" };
+    if (r.kind === "agent")
+        return {
+            label: `${r.name} → ${r.tool}`,
+            reason: r.reason ?? "outside contract",
+        };
+    return { label: r.kind, reason: "" };
+}
+/** One line describing a denial for the terminal summary. */
+function denialLine(r) {
+    const d = denialParts(r);
+    return `    ✗ ${d.label}: ${d.reason}`;
+}
+/**
+ * The structured ledger summary for the AuditReport JSON — total, per-kind counts,
+ * and the recent denials. `undefined` when nothing is recorded, so the report field
+ * stays absent (additive/optional). Shares `isDenial`/`denialParts` with the
+ * terminal `formatLedgerSummary` so the two can't drift.
+ */
+function summarizeObservations(records) {
+    if (records.length === 0)
+        return undefined;
+    const map = new Map();
+    for (const r of records)
+        map.set(r.kind, (map.get(r.kind) ?? 0) + 1);
+    const denied = records.filter(isDenial);
+    return {
+        total: records.length,
+        counts: Array.from(map.entries()).map(([kind, count]) => ({ kind, count })),
+        denials: denied.length,
+        recentDenials: denied.slice(-5).map(denialParts),
+    };
+}
+/**
+ * A compact human summary of the ledger for `vigiles audit` — total, counts by kind,
+ * and the recent high-signal denials. Empty string when there is nothing recorded, so
+ * the caller can skip the section entirely.
+ */
+function formatLedgerSummary(records) {
+    if (records.length === 0)
+        return "";
+    const lines = [
+        `Flight recorder — ${records.length} record${records.length === 1 ? "" : "s"} in .vigiles/${exports.LEDGER_FILE}`,
+    ];
+    const counts = new Map();
+    for (const r of records)
+        counts.set(r.kind, (counts.get(r.kind) ?? 0) + 1);
+    const byKind = Array.from(counts.entries())
+        .map(([k, n]) => `${n} ${k}`)
+        .join(", ");
+    lines.push(`  by kind: ${byKind}`);
+    const denials = records.filter(isDenial);
+    if (denials.length > 0) {
+        lines.push(`  recent denials (${denials.length}):`);
+        for (const r of denials.slice(-5))
+            lines.push(denialLine(r));
+    }
+    return lines.join("\n");
+}
+/** Parse one JSONL line into a record, or `null` if it is not a well-formed record. */
+function tryParseRecord(line) {
+    try {
+        const value = JSON.parse(line);
+        if (value &&
+            typeof value === "object" &&
+            typeof value.kind === "string") {
+            return value;
+        }
+    }
+    catch {
+        /* tolerate a torn/malformed line */
+    }
+    return null;
+}
+//# sourceMappingURL=observe.js.map

package/dist/research-index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Research-index completeness — the deterministic FLOOR keeping the `research/`
+ * corpus and its index (`research/CLAUDE.md.spec.ts`) in sync. The spec's
+ * `keyFiles` map is the AGENT-FACING index of every research doc; the compiler
+ * already verifies the OTHER direction (every indexed path EXISTS, else
+ * `vigiles compile` fails), so the only open gap is a doc that was ADDED but
+ * never indexed. This check closes it: every `research/*.md` (except the
+ * human-facing `README.md`) must appear in the index, or the dogfood test fails.
+ *
+ * Pure — the caller supplies the doc filenames and the index content (the spec
+ * source, where an entry is AUTHORED), so it runs over the real `research/` dir
+ * in a test or over any file set. Bidirectional sync = compiler (index ⊆ docs)
+ * + this check (docs ⊆ index).
+ */
+/** Docs that are the index itself / human front-door, not indexed entries. */
+export declare const INDEX_EXEMPT: readonly ["README.md"];
+/**
+ * Research doc basenames (e.g. `roadmap.md`) NOT referenced anywhere in
+ * `indexContent`. A doc counts as indexed if its repo-relative path
+ * (`research/<name>.md`) appears in the index — the exact form the spec's
+ * `keyFiles` keys use. Exempt docs (the README) are never flagged.
+ */
+export declare function unindexedResearchDocs(docFilenames: readonly string[], indexContent: string, exempt?: readonly string[]): string[];
+/**
+ * Index entries pointing at a `research/<name>.md` that no longer exists on
+ * disk. The compiler catches this at compile time (a missing `keyFiles` path is
+ * a compile error), so this is a belt-and-suspenders reader for a test that
+ * wants to assert it directly without invoking the compiler.
+ */
+export declare function deadIndexEntries(docFilenames: readonly string[], indexContent: string): string[];
+//# sourceMappingURL=research-index.d.ts.map