@compr/opscontext-mcp 2.4.3 → 2.5.0

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,9 @@ 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, } from "./transcript-collector.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 +1389,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 +1459,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 +1514,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 +2264,183 @@ 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;
+        return {
+            t: {
+                billing_mode: a.billing_mode,
+                pricing: a.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",
+        };
+    }
+    return { t: DEFAULT_COST_THRESHOLDS, source: "built-in defaults (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;
+    for (const { run, m } of scored) {
+        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";
+    console.log(`VALUED COST (API list prices)${notional ? " — NOTIONAL, NOT BILLED" : ""}`);
+    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"}%`);
+    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;
+    }
+    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 (unpriced > 0)
+        console.log(`  ⚠ ${fmtTok(unpriced)} tokens UNPRICED (no matching model in policy) — not counted above`);
+    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 +2477,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 +2496,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 +2514,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 +2604,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/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

package/dist/detector.js

@@ -333,4 +333,120 @@ export const _internal = {
     detectLoop, detectStuck, detectContextBloat, detectFabrication,
     detectDrift, detectNoInsight, detectSilentFailure, detectStaleDocSignal,
 };
+import { metricsFor } from "./transcript-collector.js";
+export const DEFAULT_COST_THRESHOLDS = {
+    billing_mode: "subscription",
+    pricing: [],
+    min_cache_efficiency: 3,
+    max_tool_calls_per_agent: 2,
+    max_cost_per_agent_usd: 3,
+    min_fanout_for_canary: 5,
+    max_failed_share: 0.05,
+};
+function mkRun(kind, severity, reason, payload) {
+    // evidence is AuditRecord[]; transcript signals carry their detail in
+    // payload instead of inventing records that were never written.
+    return { kind, severity, reason, evidence: [], payload, detectedAt: Date.now() };
+}
+/**
+ * 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 function detectContextBurn(run, t, m) {
+    const x = m ?? metricsFor(run, t.pricing);
+    if (x.agents === 0)
+        return null;
+    const reasons = [];
+    let severity = "warn";
+    const cacheWrite = run.totals.cacheWrite5m + run.totals.cacheWrite1h;
+    // Only meaningful once enough was written to judge reuse.
+    if (cacheWrite > 100_000 && x.cacheEfficiency < t.min_cache_efficiency) {
+        const writeShare = x.cost.total > 0 ? x.cost.cacheWrite / x.cost.total : 0;
+        reasons.push(`cache reused ${x.cacheEfficiency.toFixed(1)}x (floor ${t.min_cache_efficiency}x) — ` +
+            `${(cacheWrite / 1e6).toFixed(1)}M written vs ${(run.totals.cacheRead / 1e6).toFixed(1)}M read, ` +
+            `${(writeShare * 100).toFixed(0)}% of valued cost is cache WRITES`);
+        if (writeShare > 0.5)
+            severity = "critical";
+    }
+    if (x.medianToolCalls > t.max_tool_calls_per_agent) {
+        reasons.push(`median ${x.medianToolCalls} tool calls/agent (max ${t.max_tool_calls_per_agent}) — ` +
+            `agents are searching for their inputs instead of being handed them`);
+    }
+    const perAgent = x.cost.total / x.agents;
+    if (perAgent > t.max_cost_per_agent_usd) {
+        reasons.push(`$${perAgent.toFixed(2)}/agent valued (max $${t.max_cost_per_agent_usd.toFixed(2)})`);
+    }
+    if (!reasons.length)
+        return null;
+    return mkRun("context_burn", severity, `${run.runId}: ${reasons.join("; ")}`, {
+        runId: run.runId, project: run.project, sessionId: run.sessionId,
+        agents: x.agents, medianToolCalls: x.medianToolCalls,
+        cacheEfficiency: Number.isFinite(x.cacheEfficiency) ? x.cacheEfficiency : null,
+        cacheWriteTokens: cacheWrite, cacheReadTokens: run.totals.cacheRead,
+        outputShare: x.outputShare, costUsd: x.cost.total, costPerAgentUsd: perAgent,
+        billingMode: t.billing_mode, costIsNotional: t.billing_mode === "subscription",
+    });
+}
+/**
+ * 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 function detectFanoutWithoutCanary(run, t, m) {
+    const x = m ?? metricsFor(run, t.pricing);
+    if (x.agents < t.min_fanout_for_canary)
+        return null;
+    if (x.launchedBeforeFirstReport < t.min_fanout_for_canary)
+        return null;
+    const failedShare = x.agents ? x.failed / x.agents : 0;
+    let severity = "warn";
+    const parts = [
+        `${x.launchedBeforeFirstReport} of ${x.agents} agents launched before any had reported`,
+    ];
+    if (x.capacityExhausted > 0) {
+        severity = "critical";
+        parts.push(`${x.capacityExhausted} died at the usage window (${(100 * x.capacityExhausted / x.agents).toFixed(0)}%) — ` +
+            `capacity spent for no result`);
+    }
+    else if (failedShare > t.max_failed_share) {
+        severity = "critical";
+        parts.push(`${x.failed}/${x.agents} returned nothing (${(failedShare * 100).toFixed(0)}%)`);
+    }
+    return mkRun("fanout_without_canary", severity, `${run.runId}: ${parts.join("; ")}`, {
+        runId: run.runId, project: run.project, sessionId: run.sessionId,
+        agents: x.agents, launchedBeforeFirstReport: x.launchedBeforeFirstReport,
+        reported: x.reported, failed: x.failed, capacityExhausted: x.capacityExhausted,
+        failedShare, costUsd: x.cost.total,
+        billingMode: t.billing_mode, costIsNotional: t.billing_mode === "subscription",
+    });
+}
+/** Run both transcript heuristics over a set of runs. */
+export function runTranscriptHeuristics(runs, t = DEFAULT_COST_THRESHOLDS) {
+    const out = [];
+    for (const run of runs) {
+        const m = metricsFor(run, t.pricing);
+        const burn = detectContextBurn(run, t, m);
+        if (burn)
+            out.push(burn);
+        const fan = detectFanoutWithoutCanary(run, t, m);
+        if (fan)
+            out.push(fan);
+    }
+    return out;
+}
 //# sourceMappingURL=detector.js.map

package/dist/hooks.d.ts

@@ -137,4 +137,18 @@ export declare function formatCommitMessageViolations(violations: CommitMessageV
 export declare function formatCommitMessageViolationsJson(violations: CommitMessageViolation[]): string;
 export declare function formatSecretViolationsJson(violations: SecretViolation[]): string;
 export declare function formatDocCoverageViolationsJson(violations: DocCoverageViolation[]): string;
+export interface RuleParityViolation {
+    severity: "block" | "warn";
+    ruleId: string;
+    marker: string;
+    presentIn: string[];
+    missingFrom: string[];
+    reason: "marker-missing-from-some-files" | "marker-required-but-absent-everywhere" | "file-not-found";
+    missingFiles?: string[];
+}
+export declare function runRuleParity(policy: Policy, files: StagedFile[], repoRoot: string, opts?: {
+    all?: boolean;
+}): RuleParityViolation[];
+export declare function formatRuleParityViolations(violations: RuleParityViolation[]): string;
+export declare function formatRuleParityViolationsJson(violations: RuleParityViolation[]): string;
 //# sourceMappingURL=hooks.d.ts.map