@compr/opscontext-mcp 2.4.3 → 2.5.1

package/dist/cli.d.ts

@@ -12,6 +12,7 @@
  *   contextengine save-learning        Save a learning (terminal fallback for MCP)
  *   contextengine score [project|path] AI-readiness score for one project (default: cwd; --all for fleet)
  *   contextengine audit               Run compliance audit across all projects
+ *   contextengine cost                Multi-agent token/cost/capacity report from transcripts
  *   contextengine help                Show this message
  */
 export {};

package/dist/cli.js

@@ -12,6 +12,7 @@
  *   contextengine save-learning        Save a learning (terminal fallback for MCP)
  *   contextengine score [project|path] AI-readiness score for one project (default: cwd; --all for fleet)
  *   contextengine audit               Run compliance audit across all projects
+ *   contextengine cost                Multi-agent token/cost/capacity report from transcripts
  *   contextengine help                Show this message
  */
 import { existsSync, readFileSync, writeFileSync, mkdirSync, statSync } from "fs";
@@ -297,6 +298,62 @@ function generatePreCommitHook() {
 // ---------------------------------------------------------------------------
 // Template for post-commit hook (auto-push)
 // ---------------------------------------------------------------------------
+/**
+ * Generate the commit-msg hook — the ONLY place `commit_message_required`
+ * can run.
+ *
+ * 🔒 LOCKED [COMMIT-MSG-HOOK-MUST-BE-INSTALLED] — 2026-08-19
+ * ⛔ NEVER ship a `commit_message_required` policy rule without generating
+ *    this hook in the same `init`.
+ * WHY: the rule type, its CLI subcommand, and its tests all existed and all
+ *    passed, but `init` installed only pre-commit and post-commit. Proven by
+ *    execution on 2026-08-19: in a repo created by `contextengine init` with
+ *    a `severity: block` rule on `server/deploy.sh`, committing that file
+ *    with a non-compliant message SUCCEEDED. The gate could not fire because
+ *    nothing called it. It worked in this repo only because a commit-msg
+ *    hook had been installed by hand — so the author's own machine was the
+ *    one place the gap was invisible.
+ * FIX: install commit-msg alongside pre-commit. `commit_message_required`
+ *    cannot run from pre-commit — git does not populate the message file
+ *    until after pre-commit returns (see the subcommand's own note).
+ */
+function generateCommitMsgHook() {
+    const lines = [];
+    lines.push("#!/bin/zsh");
+    lines.push("# ContextEngine — commit-msg policy gate");
+    lines.push("# Runs .contextengine/policy.json `commit_message_required` rules.");
+    lines.push("# MUST live here, not pre-commit: git does not populate the commit");
+    lines.push("# message file until after pre-commit returns.");
+    lines.push("");
+    lines.push('COMMIT_MSG_FILE="$1"');
+    lines.push("");
+    lines.push("find_ce_cli() {");
+    lines.push('  if [[ -x "node_modules/.bin/contextengine" ]]; then');
+    lines.push('    echo "node_modules/.bin/contextengine"');
+    lines.push("    return");
+    lines.push("  fi");
+    lines.push("  if command -v contextengine >/dev/null 2>&1; then");
+    lines.push("    command -v contextengine");
+    lines.push("  fi");
+    lines.push("}");
+    lines.push("");
+    lines.push("CE_CLI=$(find_ce_cli)");
+    lines.push("HAS_POLICY=false");
+    lines.push("[[ -f .contextengine/policy.json ]] && HAS_POLICY=true");
+    lines.push("");
+    lines.push("# No CLI or no policy = nothing to enforce. Stay silent and pass.");
+    lines.push('if [[ -z "$CE_CLI" || "$HAS_POLICY" != "true" ]]; then');
+    lines.push("  exit 0");
+    lines.push("fi");
+    lines.push("");
+    lines.push('if ! "$CE_CLI" hook commit-message-required "$COMMIT_MSG_FILE"; then');
+    lines.push("  exit 1");
+    lines.push("fi");
+    lines.push("");
+    lines.push("exit 0");
+    lines.push("");
+    return lines.join("\n");
+}
 function generatePostCommitHook() {
     const lines = [];
     lines.push("#!/bin/zsh");
@@ -449,6 +506,7 @@ async function runInit() {
             const hooksDir = join(cwd, ".git", "hooks");
             const preCommitDest = join(hooksDir, "pre-commit");
             const postCommitDest = join(hooksDir, "post-commit");
+            const commitMsgDest = join(hooksDir, "commit-msg");
             if (existsSync(preCommitDest)) {
                 console.log("  ⏭  .git/hooks/pre-commit already exists — skipping");
                 skipped++;
@@ -462,6 +520,21 @@ async function runInit() {
                     created++;
                 }
             }
+            // [COMMIT-MSG-HOOK-MUST-BE-INSTALLED] — without this, every
+            // commit_message_required rule is silently unenforced.
+            if (existsSync(commitMsgDest)) {
+                console.log("  ⏭  .git/hooks/commit-msg already exists — skipping");
+                skipped++;
+            }
+            else {
+                const answer = isNonInteractive ? "y" : await ask(rl, "  Install commit-msg hook (commit-message policy gate)? [Y/n] ");
+                if (answer.toLowerCase() !== "n") {
+                    mkdirSync(hooksDir, { recursive: true });
+                    writeFileSync(commitMsgDest, generateCommitMsgHook(), { mode: 0o755 });
+                    console.log("  ✅ Installed .git/hooks/commit-msg");
+                    created++;
+                }
+            }
             if (existsSync(postCommitDest)) {
                 console.log("  ⏭  .git/hooks/post-commit already exists — skipping");
                 skipped++;
@@ -529,7 +602,10 @@ import { activate, deactivate, getActivationStatus, gateCheck, } from "./activat
 import { syncTierA, syncTierB, loadCommunityStore, communityRulesToChunks, mergeWithDedup, STORE_PATH as COMMUNITY_STORE_PATH, } from "./community-sync.js";
 import { readAuditLog, verifyChain, filterByRange, toCsv, } from "./audit.js";
 import { loadRepoPolicy, parsePolicy, formatPolicySummary, formatValidationErrors, repoPolicyPath, } from "./policy.js";
-import { getStagedFiles, runSecretScan, runDocCoverage, runCommitMessageRequired, formatSecretViolations, formatDocCoverageViolations, formatSecretViolationsJson, formatDocCoverageViolationsJson, formatCommitMessageViolations, formatCommitMessageViolationsJson, } from "./hooks.js";
+import { collectRuns, metricsFor, transcriptRoot, emptyTally, addTally, totalTokens, pricingStatus, pricingFor, } from "./transcript-collector.js";
+import { DEFAULT_PRICING, DEFAULT_PRICING_ASOF } from "./default-pricing.js";
+import { runTranscriptHeuristics, DEFAULT_COST_THRESHOLDS, } from "./detector.js";
+import { getStagedFiles, runSecretScan, runDocCoverage, runCommitMessageRequired, runRuleParity, formatSecretViolations, formatDocCoverageViolations, formatSecretViolationsJson, formatDocCoverageViolationsJson, formatCommitMessageViolations, formatCommitMessageViolationsJson, formatRuleParityViolations, formatRuleParityViolationsJson, } from "./hooks.js";
 import { safeAppend } from "./audit.js";
 import { installSkill, locateBundledSkill, buildManagedBlock, syncClaudeMd, } from "./claude-integration.js";
 import { fileURLToPath } from "url";
@@ -1314,6 +1390,13 @@ Subcommands:
   doc-coverage   For each policy.doc_coverage rule, check whether the
                  commit touches matching source paths AND the required
                  doc section is staged. Exit 1 on blocking violations.
+  rule-parity [--all]
+                 For each policy.rule_parity rule, check that the marker
+                 is present in EVERY listed doc, not just some. Fires only
+                 when the commit touches one of those docs; --all audits
+                 the whole repo regardless of the diff. Exit 1 on blocking
+                 violations.
+
   commit-message-required [MSG_FILE]
                  For each policy.commit_message_required rule, check
                  whether the commit touches matching source paths AND
@@ -1377,7 +1460,17 @@ tamper-evident audit log at ~/.contextengine/audit.log.`);
         console.error(`Error reading staged diff: ${e instanceof Error ? e.message : String(e)}`);
         process.exit(1);
     }
-    if (stagedFiles.length === 0)
+    // 🔒 LOCKED [RULE-PARITY-ALL-IGNORES-DIFF] — 2026-08-19
+    // ⛔ NEVER let the empty-staged-diff short-circuit swallow an --all audit.
+    // WHY: `hook rule-parity --all` is a whole-repo audit for CI and deliberate sweeps —
+    //      it does not depend on the diff at all. This early return ran first, so on a
+    //      clean tree the command printed NOTHING and exited 0. A compliance check that
+    //      reports success precisely when it did not run is the same failure shape as the
+    //      `Secrets exposure` 6/6 pass in [EXEC-FAILURE-IS-NOT-EMPTY]: silence read as a
+    //      clean bill of health. Caught by running it, not by reading it.
+    // FIX: exempt the diff-independent audits from the short-circuit.
+    const auditsWholeRepo = sub === "rule-parity" && args.includes("--all");
+    if (stagedFiles.length === 0 && !auditsWholeRepo)
         return; // nothing to scan
     if (sub === "secret-scan") {
         const violations = runSecretScan(policy, stagedFiles);
@@ -1422,6 +1515,30 @@ tamper-evident audit log at ~/.contextengine/audit.log.`);
             process.exit(1);
         return;
     }
+    if (sub === "rule-parity") {
+        // --all audits every rule regardless of what this commit touches (CI / sweeps).
+        const all = args.includes("--all");
+        const violations = runRuleParity(policy, stagedFiles, repoRoot, { all });
+        if (jsonMode) {
+            process.stdout.write(formatRuleParityViolationsJson(violations) + "\n");
+        }
+        else {
+            console.log(formatRuleParityViolations(violations));
+        }
+        const blocking = violations.filter((v) => v.severity === "block");
+        for (const v of blocking) {
+            safeAppend("hook.block", {
+                check: "rule-parity",
+                rule_id: v.ruleId,
+                reason: v.reason,
+                present_in: v.presentIn,
+                missing_from: v.missingFrom,
+            });
+        }
+        if (blocking.length > 0)
+            process.exit(1);
+        return;
+    }
     if (sub === "commit-message-required") {
         // Locate the commit-message file. Order:
         //   1. CLI positional arg (`contextengine hook commit-message-required
@@ -2148,6 +2265,220 @@ function cliStats() {
     }
 }
 // ---------------------------------------------------------------------------
+// cost — multi-agent spend, read from Claude Code's own transcripts
+// ---------------------------------------------------------------------------
+function fmtTok(n) {
+    if (n >= 1e6)
+        return `${(n / 1e6).toFixed(1)}M`;
+    if (n >= 1e3)
+        return `${(n / 1e3).toFixed(0)}k`;
+    return String(n);
+}
+function fmtDur(ms) {
+    if (ms === null || !Number.isFinite(ms))
+        return "—";
+    const s = Math.round(ms / 1000);
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return `${m}m${String(s % 60).padStart(2, "0")}s`;
+    return `${Math.floor(m / 60)}h${String(m % 60).padStart(2, "0")}m`;
+}
+/** Resolve cost thresholds + pricing from policy, falling back to defaults. */
+function loadCostThresholds(cwd) {
+    const res = loadRepoPolicy(cwd);
+    if (res && res.ok && res.policy.agent_cost) {
+        const a = res.policy.agent_cost;
+        // [DEFAULT-RATES-SHIP-WITH-THE-PACKAGE] — an agent_cost block that omits
+        // `pricing` must not silently price nothing.
+        const hasOwnRates = a.pricing.length > 0;
+        return {
+            t: {
+                billing_mode: a.billing_mode,
+                pricing: hasOwnRates ? a.pricing : DEFAULT_PRICING,
+                min_cache_efficiency: a.min_cache_efficiency,
+                max_tool_calls_per_agent: a.max_tool_calls_per_agent,
+                max_cost_per_agent_usd: a.max_cost_per_agent_usd,
+                min_fanout_for_canary: a.min_fanout_for_canary,
+                max_failed_share: a.max_failed_share,
+            },
+            source: ".contextengine/policy.json" +
+                (hasOwnRates ? "" : ` (rates: built-in, as of ${DEFAULT_PRICING_ASOF})`),
+        };
+    }
+    return {
+        t: DEFAULT_COST_THRESHOLDS,
+        source: `built-in defaults, rates as of ${DEFAULT_PRICING_ASOF} (no agent_cost in policy.json)`,
+    };
+}
+async function cliCost(argv) {
+    const flag = (name) => {
+        const i = argv.indexOf(`--${name}`);
+        return i >= 0 ? argv[i + 1] : undefined;
+    };
+    const json = argv.includes("--json");
+    const topRaw = flag("top");
+    const top = topRaw ? Math.max(1, parseInt(topRaw, 10) || 10) : 10;
+    const daysRaw = flag("days");
+    const since = daysRaw ? Date.now() - parseInt(daysRaw, 10) * 86_400_000 : undefined;
+    const cwd = process.cwd();
+    const { t, source } = loadCostThresholds(cwd);
+    const runs = collectRuns({
+        session: flag("session"),
+        project: flag("project"),
+        run: flag("run"),
+        since,
+    });
+    if (!runs.length) {
+        console.log("No multi-agent runs found in " + transcriptRoot());
+        console.log("(fan-outs only: parent sessions are not counted — this measures delegation)");
+        return;
+    }
+    const scored = runs
+        .map((r) => ({ run: r, m: metricsFor(r, t.pricing) }))
+        .sort((a, b) => b.m.cost.total - a.m.cost.total);
+    const signals = runTranscriptHeuristics(runs, t);
+    if (json) {
+        console.log(JSON.stringify({
+            billing_mode: t.billing_mode,
+            cost_is_notional: t.billing_mode === "subscription",
+            thresholds_source: source,
+            runs: scored.map(({ run, m }) => ({
+                runId: run.runId, kind: run.kind, project: run.project, sessionId: run.sessionId,
+                volume: run.totals, intensity: {
+                    agents: m.agents, reported: m.reported, failed: m.failed,
+                    capacityExhausted: m.capacityExhausted, toolCalls: m.toolCalls,
+                    medianToolCalls: m.medianToolCalls, durationMs: run.durationMs,
+                    launchedBeforeFirstReport: m.launchedBeforeFirstReport,
+                },
+                cost: m.cost, cacheEfficiency: Number.isFinite(m.cacheEfficiency) ? m.cacheEfficiency : null,
+                outputShare: m.outputShare,
+            })),
+            signals,
+        }, null, 2));
+        return;
+    }
+    // Aggregate across everything in scope.
+    let vol = emptyTally();
+    let agents = 0, toolCalls = 0, failed = 0, capacity = 0, reported = 0;
+    let cost = 0, withoutCache = 0, unpriced = 0;
+    // Which models carried tokens but matched no rate — named in the output so
+    // the fix is actionable instead of "something was unpriced".
+    const unpricedModels = new Set();
+    for (const { run, m } of scored) {
+        for (const a of run.agents) {
+            for (const [model, tally] of a.tokensByModel) {
+                if (totalTokens(tally) > 0 && !pricingFor(model, t.pricing)) {
+                    unpricedModels.add(model ?? "(no model recorded)");
+                }
+            }
+        }
+        vol = addTally(vol, run.totals);
+        agents += m.agents;
+        toolCalls += m.toolCalls;
+        failed += m.failed;
+        capacity += m.capacityExhausted;
+        reported += m.reported;
+        cost += m.cost.total;
+        withoutCache += m.cost.withoutCache;
+        unpriced += m.cost.unpricedTokens;
+    }
+    const allTok = totalTokens(vol);
+    const cw = vol.cacheWrite5m + vol.cacheWrite1h;
+    console.log("");
+    console.log(`MULTI-AGENT COST — ${scored.length} run(s), ${agents} subagents`);
+    console.log(`thresholds: ${source}`);
+    console.log("");
+    // ── 1. VOLUME ───────────────────────────────────────────────────────────
+    console.log("VOLUME (tokens moved)");
+    const volRow = (label, n) => console.log(`  ${label.padEnd(16)} ${fmtTok(n).padStart(8)}  ${allTok ? ((100 * n) / allTok).toFixed(1).padStart(5) : "  0.0"}%`);
+    volRow("cache read", vol.cacheRead);
+    volRow("cache write", cw);
+    volRow("input (fresh)", vol.input);
+    volRow("output", vol.output);
+    console.log(`  ${"total".padEnd(16)} ${fmtTok(allTok).padStart(8)}`);
+    console.log("");
+    // ── 2. VALUED COST ──────────────────────────────────────────────────────
+    const notional = t.billing_mode === "subscription";
+    let ci = 0, ccw = 0, ccr = 0, co = 0;
+    for (const { m } of scored) {
+        ci += m.cost.input;
+        ccw += m.cost.cacheWrite;
+        ccr += m.cost.cacheRead;
+        co += m.cost.output;
+    }
+    const agg = {
+        input: ci, cacheWrite: ccw, cacheRead: ccr, output: co,
+        total: cost, withoutCache, unpricedTokens: unpriced,
+    };
+    const status = pricingStatus(agg);
+    console.log(`VALUED COST (API list prices)${notional && status !== "unpriced" ? " — NOTIONAL, NOT BILLED" : ""}`);
+    // [NEVER-RENDER-AN-UNKNOWN-AS-A-NUMBER] — with nothing priced there is no
+    // cost to show. Printing a $0.00 table here reads as "this run was free"
+    // and "caching saved 0%", both false.
+    if (status === "unpriced") {
+        console.log(`  UNPRICED — no rate matched any model in this data, so no cost can be`);
+        console.log(`  stated. ${fmtTok(unpriced)} tokens were moved. This is an unknown, not $0.`);
+        console.log("");
+        console.log(`  Models seen without a rate: ${[...unpricedModels].sort().join(", ") || "(unknown)"}`);
+        console.log(`  Add them to .contextengine/policy.json → agent_cost.pricing.`);
+        console.log("");
+    }
+    else {
+        if (notional) {
+            console.log("  This machine runs Claude Code on a subscription: no dollar below is");
+            console.log("  debited. Use these figures to compare approaches, not as spend.");
+        }
+        const costRow = (label, n) => console.log(`  ${label.padEnd(16)} ${("$" + n.toFixed(2)).padStart(8)}  ${cost ? ((100 * n) / cost).toFixed(1).padStart(5) : "  0.0"}%`);
+        costRow("cache read", ccr);
+        costRow("cache write", ccw);
+        costRow("input (fresh)", ci);
+        costRow("output", co);
+        console.log(`  ${"total".padEnd(16)} ${("$" + cost.toFixed(2)).padStart(8)}`);
+        console.log(`  ${"without cache".padEnd(16)} ${("$" + withoutCache.toFixed(2)).padStart(8)}  ` +
+            `caching saved $${(withoutCache - cost).toFixed(2)} (${withoutCache ? (100 * (1 - cost / withoutCache)).toFixed(0) : "0"}%)`);
+        if (status === "partial") {
+            console.log(`  ⚠ ${fmtTok(unpriced)} tokens UNPRICED and NOT in the figures above` +
+                ` (${[...unpricedModels].sort().join(", ") || "unknown model"}) — the total is a floor, not the cost`);
+        }
+        console.log("");
+    }
+    // ── 3. INTENSITY (the capacity proxy) ───────────────────────────────────
+    console.log(`INTENSITY (capacity proxy${notional ? " — the scarce resource here" : ""})`);
+    console.log(`  subagents        ${String(agents).padStart(8)}`);
+    console.log(`  reported         ${String(reported).padStart(8)}`);
+    console.log(`  returned nothing ${String(failed).padStart(8)}${failed ? `  (${((100 * failed) / agents).toFixed(0)}% of the fleet)` : ""}`);
+    console.log(`  died at window   ${String(capacity).padStart(8)}${capacity ? "  ← capacity spent for no result" : ""}`);
+    console.log(`  tool calls       ${String(toolCalls).padStart(8)}  (${(toolCalls / Math.max(1, agents)).toFixed(1)}/agent)`);
+    console.log(`  cache reuse      ${(cw ? (vol.cacheRead / cw).toFixed(1) + "x" : "—").padStart(8)}  ${cw && vol.cacheRead / cw < t.min_cache_efficiency ? "← below floor, prefix is being rebuilt" : "(higher is better)"}`);
+    console.log("");
+    // ── Top runs ────────────────────────────────────────────────────────────
+    console.log(`TOP RUNS BY VALUED COST (${Math.min(top, scored.length)} of ${scored.length})`);
+    console.log(`  ${"cost".padStart(8)} ${"agents".padStart(6)} ${"dead".padStart(4)} ${"tools".padStart(5)} ${"reuse".padStart(6)} ${"dur".padStart(7)}  run`);
+    for (const { run, m } of scored.slice(0, top)) {
+        const reuse = Number.isFinite(m.cacheEfficiency) ? m.cacheEfficiency.toFixed(1) + "x" : "—";
+        console.log(`  ${("$" + m.cost.total.toFixed(2)).padStart(8)} ${String(m.agents).padStart(6)} ` +
+            `${String(m.failed).padStart(4)} ${String(m.medianToolCalls).padStart(5)} ${reuse.padStart(6)} ` +
+            `${fmtDur(run.durationMs).padStart(7)}  ${run.runId} ${run.project.replace(/^-Users-yan-/, "")}`);
+    }
+    console.log("");
+    // ── Signals ─────────────────────────────────────────────────────────────
+    if (!signals.length) {
+        console.log("✅ No context_burn or fanout_without_canary signals.");
+    }
+    else {
+        const crit = signals.filter((s) => s.severity === "critical");
+        console.log(`SIGNALS — ${signals.length} (${crit.length} critical)`);
+        for (const s of signals.slice(0, 20)) {
+            console.log(`  ${s.severity === "critical" ? "🔴" : "⚠️ "} [${s.kind}] ${s.reason}`);
+        }
+        if (signals.length > 20)
+            console.log(`  … ${signals.length - 20} more (use --json)`);
+    }
+    console.log("");
+}
+// ---------------------------------------------------------------------------
 // Main — route to init, CLI subcommand, or MCP server
 // ---------------------------------------------------------------------------
 const command = process.argv[2];
@@ -2184,6 +2515,12 @@ Usage:
                                        Export hash-chained audit log (evidence aligned with
                                        SOC 2 CC7.2 + ISO 27001 A.12.4.1 — not a certification)
   contextengine audit-verify           Verify audit log chain integrity (tamper detection)
+  contextengine cost [--session ID] [--project NAME] [--run wf_ID] [--days N] [--top N] [--json]
+                                       Multi-agent spend from Claude Code transcripts. Always prints
+                                       VOLUME (tokens), VALUED COST (API list prices — notional on a
+                                       subscription) and INTENSITY (agents, tool calls, deaths at the
+                                       usage window), because volume and cost tell opposite stories.
+                                       Flags context_burn + fanout_without_canary.
   contextengine policy <validate|show> [args]
                                        Author + validate the declarative .contextengine/policy.json
   contextengine init-extension-secret [--force]
@@ -2197,7 +2534,7 @@ Usage:
                                        Stream drift / loop / stuck-tool / fabrication alerts from the audit log
   contextengine emit-event <kind> <payload-json> [--actor NAME]
                                        Append a single event to the audit log (for integrations / scripted tests)
-  contextengine hook <secret-scan|doc-coverage>
+  contextengine hook <secret-scan|doc-coverage|rule-parity|commit-message-required>
                                        Run policy-driven pre-commit checks against staged diff
                                        (exit 1 on blocking violation; CE_JSON=1 for CI output)
   contextengine install-skill [--global | --project] [--force]
@@ -2215,6 +2552,7 @@ Usage:
                                        Accepts a project name or a directory path.
                                        --all scores every discovered project (writes to each).
   contextengine audit                  Run compliance audit (Pro)
+  contextengine cost                   Multi-agent token/cost/capacity report
   contextengine activate <key> <email> Activate a Pro license
   contextengine deactivate             Remove license and premium modules
   contextengine stats                  Show live MCP session stats (value meter)
@@ -2304,6 +2642,12 @@ else if (command === "score") {
         process.exit(1);
     });
 }
+else if (command === "cost") {
+    cliCost(process.argv.slice(3)).catch((err) => {
+        console.error("Error:", err);
+        process.exit(1);
+    });
+}
 else if (command === "audit") {
     cliAudit().catch((err) => {
         console.error("Error:", err);

package/dist/default-pricing.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Built-in model rates, in dollars per million tokens.
+ *
+ * 🔒 LOCKED [DEFAULT-RATES-SHIP-WITH-THE-PACKAGE] — 2026-08-20
+ * ⛔ NEVER ship an empty default pricing table again.
+ * WHY: `[PRICING-LIVES-IN-POLICY]` was read as "ship no rates at all", so
+ *    2.5.0 shipped `pricing: []` as the default. Every user without an
+ *    `agent_cost` block in their own policy.json got a VALUED COST panel
+ *    reading `total $0.00` and `caching saved $0.00 (0%)` over 1.08 BILLION
+ *    real tokens — a confident, wrong-looking verdict on the headline feature
+ *    of the release. The LOCK's intent was "rates must be correctable without
+ *    a release", not "the product ships priced at nothing".
+ * FIX: ship rates here, as DATA in their own module, never inline in the
+ *    collector / detector / CLI. `.contextengine/policy.json` →
+ *    `agent_cost.pricing` still wins outright when present, and this file
+ *    compiles to plain readable JS in `dist/`, so a rate can be corrected in
+ *    place without waiting for a release.
+ *
+ * Rates are Anthropic API list prices. Cache read is 0.1x input, cache write
+ * 5m is 1.25x input, cache write 1h is 2x input.
+ */
+import type { ModelPricing } from "./transcript-collector.js";
+/**
+ * When these rates were last checked against published pricing. Surfaced in
+ * `contextengine cost` output: a rate table with no date is a rate table
+ * nobody knows to distrust.
+ */
+export declare const DEFAULT_PRICING_ASOF = "2026-08-20";
+/**
+ * Longest-prefix matched, so dated ids (`claude-haiku-4-5-20251001`) resolve
+ * to their family. Deliberately NO `*` catch-all: a model absent from this
+ * table must report as UNPRICED, never be valued at a guessed rate
+ * (`[ABSENCE-IS-NOT-A-VERDICT]`).
+ */
+export declare const DEFAULT_PRICING: ModelPricing[];
+//# sourceMappingURL=default-pricing.d.ts.map

package/dist/default-pricing.js

@@ -0,0 +1,57 @@
+/**
+ * Built-in model rates, in dollars per million tokens.
+ *
+ * 🔒 LOCKED [DEFAULT-RATES-SHIP-WITH-THE-PACKAGE] — 2026-08-20
+ * ⛔ NEVER ship an empty default pricing table again.
+ * WHY: `[PRICING-LIVES-IN-POLICY]` was read as "ship no rates at all", so
+ *    2.5.0 shipped `pricing: []` as the default. Every user without an
+ *    `agent_cost` block in their own policy.json got a VALUED COST panel
+ *    reading `total $0.00` and `caching saved $0.00 (0%)` over 1.08 BILLION
+ *    real tokens — a confident, wrong-looking verdict on the headline feature
+ *    of the release. The LOCK's intent was "rates must be correctable without
+ *    a release", not "the product ships priced at nothing".
+ * FIX: ship rates here, as DATA in their own module, never inline in the
+ *    collector / detector / CLI. `.contextengine/policy.json` →
+ *    `agent_cost.pricing` still wins outright when present, and this file
+ *    compiles to plain readable JS in `dist/`, so a rate can be corrected in
+ *    place without waiting for a release.
+ *
+ * Rates are Anthropic API list prices. Cache read is 0.1x input, cache write
+ * 5m is 1.25x input, cache write 1h is 2x input.
+ */
+/**
+ * When these rates were last checked against published pricing. Surfaced in
+ * `contextengine cost` output: a rate table with no date is a rate table
+ * nobody knows to distrust.
+ */
+export const DEFAULT_PRICING_ASOF = "2026-08-20";
+function rate(model, input, output) {
+    return {
+        model,
+        input_per_mtok: input,
+        output_per_mtok: output,
+        cache_read_per_mtok: Number((input * 0.1).toFixed(4)),
+        cache_write_5m_per_mtok: Number((input * 1.25).toFixed(4)),
+        cache_write_1h_per_mtok: Number((input * 2).toFixed(4)),
+    };
+}
+/**
+ * Longest-prefix matched, so dated ids (`claude-haiku-4-5-20251001`) resolve
+ * to their family. Deliberately NO `*` catch-all: a model absent from this
+ * table must report as UNPRICED, never be valued at a guessed rate
+ * (`[ABSENCE-IS-NOT-A-VERDICT]`).
+ */
+export const DEFAULT_PRICING = [
+    rate("claude-opus-5", 5, 25),
+    rate("claude-opus-4-8", 5, 25),
+    rate("claude-opus-4-7", 5, 25),
+    rate("claude-opus-4-6", 5, 25),
+    rate("claude-opus-4-5", 5, 25),
+    rate("claude-fable-5", 10, 50),
+    rate("claude-mythos-5", 10, 50),
+    rate("claude-sonnet-5", 3, 15),
+    rate("claude-sonnet-4-6", 3, 15),
+    rate("claude-sonnet-4-5", 3, 15),
+    rate("claude-haiku-4-5", 1, 5),
+];
+//# sourceMappingURL=default-pricing.js.map

package/dist/detector.d.ts

@@ -1,5 +1,5 @@
 import { type AuditRecord, type AuditEvent } from "./audit.js";
-export type DriftKind = "loop" | "stuck" | "context_bloat" | "fabrication_suspect" | "drift" | "no_insight" | "stale_doc_signal" | "silent_failure";
+export type DriftKind = "loop" | "stuck" | "context_bloat" | "fabrication_suspect" | "drift" | "no_insight" | "stale_doc_signal" | "silent_failure" | "context_burn" | "fanout_without_canary";
 export type Severity = "info" | "warn" | "critical";
 export interface DriftSignal {
     kind: DriftKind;
@@ -61,4 +61,43 @@ export declare const _internal: {
     detectStaleDocSignal: typeof detectStaleDocSignal;
 };
 export type { AuditRecord, AuditEvent };
+import type { RunUsage, RunMetrics, ModelPricing } from "./transcript-collector.js";
+export interface CostThresholds {
+    billing_mode: "subscription" | "api";
+    pricing: ModelPricing[];
+    min_cache_efficiency: number;
+    max_tool_calls_per_agent: number;
+    max_cost_per_agent_usd: number;
+    min_fanout_for_canary: number;
+    max_failed_share: number;
+}
+export declare const DEFAULT_COST_THRESHOLDS: CostThresholds;
+/**
+ * context_burn — the run is paying for context it is not reusing.
+ *
+ * Fires on cache INEFFICIENCY, tool-call inflation, or per-agent valued cost.
+ * Deliberately does NOT fire on a low output/volume ratio: see
+ * [BURN-IS-COST-WEIGHTED-NOT-VOLUME] in policy.ts.
+ */
+export declare function detectContextBurn(run: RunUsage, t: CostThresholds, m?: RunMetrics): DriftSignal | null;
+/**
+ * fanout_without_canary — the fleet was launched before any single unit had
+ * reported, so nothing was known about per-agent consumption when the spend
+ * was committed.
+ *
+ * 🔒 LOCKED [CANARY-IS-A-TIME-ORDERING] — 2026-08-19
+ * ⛔ NEVER implement this as "no agent reported". A completed 300-agent run
+ *    has 300 reports and was still un-canaried.
+ * WHY: the rule being enforced is "run ONE unit and read its consumption
+ *    BEFORE scaling". That is a statement about ordering, not about outcomes,
+ *    and it is only checkable by comparing each agent's start time against the
+ *    earliest sibling completion.
+ * FIX: count agents that started before the first report landed. Severity
+ *    rises when agents then died at the usage window — on a subscription that
+ *    is the failure that actually costs something (real case: 15 of 51 agents
+ *    lost in wf_41771d7b, 0 completed).
+ */
+export declare function detectFanoutWithoutCanary(run: RunUsage, t: CostThresholds, m?: RunMetrics): DriftSignal | null;
+/** Run both transcript heuristics over a set of runs. */
+export declare function runTranscriptHeuristics(runs: RunUsage[], t?: CostThresholds): DriftSignal[];
 //# sourceMappingURL=detector.d.ts.map