@compr/opscontext-mcp 2.4.3 → 2.5.0

package/dist/hooks.js

@@ -550,4 +550,158 @@ export function formatDocCoverageViolationsJson(violations) {
         })),
     });
 }
+/**
+ * 🔒 LOCKED [RULE-PARITY-IS-DIFF-AWARE] — 2026-08-19
+ * ⛔ NEVER make this fire on commits that touch none of the rule's files.
+ * WHY: parity is a property of the whole repo, so the naive implementation checks the
+ *      working tree on every commit — which means one pre-existing drift blocks every
+ *      unrelated commit until someone fixes it. That is how a useful gate becomes a gate
+ *      everyone disables. doc_coverage already learned this: it only fires when the commit
+ *      touches the rule's source paths.
+ * FIX: fire only when the commit stages a change to at least one file the rule governs.
+ *      Editing one of the three agent docs is exactly the moment parity can break, and
+ *      exactly the moment the author has the context to fix it. `--all` (see cliHookRuleParity)
+ *      audits the whole repo on demand, for CI or a deliberate sweep.
+ *
+ * 🔒 LOCKED [RULE-PARITY-READS-THE-INDEX] — 2026-08-19
+ * ⛔ NEVER evaluate marker presence from the working tree during a pre-commit check.
+ * WHY: the first cut did, with the rationalisation that "for a normal `git commit` the
+ *      working tree IS the post-commit state". That is false whenever staging is partial,
+ *      which is the normal case for anyone using `git add -p`. Demonstrated: stage the
+ *      REMOVAL of the marker from CLAUDE.md, then restore it in the working tree only —
+ *      the gate passed, and the commit that deleted the rule from the file agents read
+ *      went through clean. The check was measuring a state git was not about to record.
+ *      Same family as [SCORE-CANARY]'s pins and [EXEC-FAILURE-IS-NOT-EMPTY]: the tool
+ *      answered confidently about something it had not actually looked at.
+ * FIX: for staged files read the INDEX blob (`git show :path`) — that is literally what
+ *      the commit will contain. Unstaged files keep their worktree content, because the
+ *      commit leaves them untouched. `--all` audits the worktree by design: it answers
+ *      "is the repo consistent right now", not "is this commit consistent".
+ */
+/**
+ * Content of `rel` as it will exist AFTER the pending commit.
+ * Staged → the index blob. Not staged → the working tree (the commit does not touch it).
+ * Returns null when the path will not exist.
+ */
+function contentAfterCommit(repoRoot, rel, stagedSet, useWorktree) {
+    if (!useWorktree && stagedSet.has(rel)) {
+        try {
+            return execSync(`git show :"${rel}"`, {
+                cwd: repoRoot,
+                encoding: "utf-8",
+                maxBuffer: 32 * 1024 * 1024,
+            });
+        }
+        catch {
+            // [EXEC-FAILURE-IS-NOT-EMPTY] — "git show failed" is not "the file is absent".
+            // Not a git repo, a corrupt index, or a path git cannot resolve all land here.
+            // Fall through to the working tree rather than reporting a file that plainly
+            // exists as missing. A staged DELETION never reaches this branch: getStagedFiles
+            // filters on --diff-filter=ACMR, so deleted paths are not in stagedSet and are
+            // correctly read as absent from the worktree below.
+        }
+    }
+    const abs = join(repoRoot, rel);
+    if (!existsSync(abs))
+        return null;
+    return readFileSync(abs, "utf-8");
+}
+export function runRuleParity(policy, files, repoRoot, opts = {}) {
+    const stagedSet = new Set(files.map((f) => f.path));
+    const violations = [];
+    for (const rule of policy.rule_parity) {
+        // [RULE-PARITY-IS-DIFF-AWARE] — only fire when this commit touches a governed file.
+        if (!opts.all && !rule.required_in.some((p) => stagedSet.has(p)))
+            continue;
+        const presentIn = [];
+        const missingFrom = [];
+        const missingFiles = [];
+        for (const rel of rule.required_in) {
+            // [RULE-PARITY-READS-THE-INDEX] — what the commit records, not what is on disk.
+            const content = contentAfterCommit(repoRoot, rel, stagedSet, opts.all === true);
+            if (content === null) {
+                missingFiles.push(rel);
+                continue;
+            }
+            if (content.includes(rule.marker))
+                presentIn.push(rel);
+            else
+                missingFrom.push(rel);
+        }
+        if (missingFiles.length > 0) {
+            violations.push({
+                severity: rule.severity,
+                ruleId: rule.id,
+                marker: rule.marker,
+                presentIn,
+                missingFrom,
+                missingFiles,
+                reason: "file-not-found",
+            });
+            continue;
+        }
+        // Adopted nowhere. Only a violation when the rule says it is mandatory.
+        if (presentIn.length === 0) {
+            if (rule.always_required) {
+                violations.push({
+                    severity: rule.severity,
+                    ruleId: rule.id,
+                    marker: rule.marker,
+                    presentIn,
+                    missingFrom,
+                    reason: "marker-required-but-absent-everywhere",
+                });
+            }
+            continue;
+        }
+        // Present somewhere but not everywhere — the drift this rule exists to catch.
+        if (missingFrom.length > 0) {
+            violations.push({
+                severity: rule.severity,
+                ruleId: rule.id,
+                marker: rule.marker,
+                presentIn,
+                missingFrom,
+                reason: "marker-missing-from-some-files",
+            });
+        }
+    }
+    return violations;
+}
+export function formatRuleParityViolations(violations) {
+    if (violations.length === 0)
+        return "✅ All rule-parity rules satisfied.";
+    const lines = [];
+    const blocking = violations.filter((v) => v.severity === "block").length;
+    lines.push(`📐 RULE PARITY: ${violations.length} violation(s) — ${blocking} blocking, ${violations.length - blocking} warning(s).`);
+    for (const v of violations) {
+        if (v.reason === "file-not-found") {
+            lines.push(`  [${v.severity}] ${v.ruleId}: listed file(s) do not exist → ${v.missingFiles.join(", ")}`);
+            continue;
+        }
+        if (v.reason === "marker-required-but-absent-everywhere") {
+            lines.push(`  [${v.severity}] ${v.ruleId}: marker "${v.marker}" is required but present in none of ${v.missingFrom.join(", ")}`);
+            continue;
+        }
+        lines.push(`  [${v.severity}] ${v.ruleId}: marker "${v.marker}" is out of sync.`);
+        lines.push(`      present in : ${v.presentIn.join(", ")}`);
+        lines.push(`      MISSING from: ${v.missingFrom.join(", ")}`);
+    }
+    return lines.join("\n");
+}
+export function formatRuleParityViolationsJson(violations) {
+    return JSON.stringify({
+        check: "rule-parity",
+        violations: violations.length,
+        blocking: violations.filter((v) => v.severity === "block").length,
+        details: violations.map((v) => ({
+            rule_id: v.ruleId,
+            severity: v.severity,
+            reason: v.reason,
+            present_in: v.presentIn,
+            missing_from: v.missingFrom,
+            missing_files: v.missingFiles ?? [],
+        })),
+    });
+}
 //# sourceMappingURL=hooks.js.map

package/dist/index.js

@@ -8,7 +8,7 @@ import { searchChunks } from "./search.js";
 import { initEmbeddings, embedChunks, vectorSearch, isEmbeddingsReady, } from "./embeddings.js";
 import { collectProjectOps, collectSystemOps } from "./collectors.js";
 import { loadCache, saveCache } from "./cache.js";
-import { listProjects, checkPorts, runComplianceAudit, formatProjectList, formatPortMap, formatPlan, scoreProject, formatScoreReport, } from "./agents.js";
+import { listProjects, checkPorts, runComplianceAudit, formatProjectList, formatPortMap, formatPlan, scoreProject, formatScoreReport, runScoreCanary, } from "./agents.js";
 import { saveSession, loadSession, listSessions, deleteSession, formatSession, formatSessionList, } from "./sessions.js";
 import { verifyChain, readAuditLog, filterByRange } from "./audit.js";
 import { startEventIngestServer } from "./http-server.js";
@@ -479,6 +479,29 @@ server.tool("score_project", "Score one or all projects on AI-readiness (0-100%)
     const gate = gateCheck("score_project");
     if (gate)
         return { content: [{ type: "text", text: gate }] };
+    // 🔒 LOCKED [SCORE-CANARY-COVERS-EVERY-SCORER] — 2026-08-19
+    // ⛔ NEVER let a scoring entry point run without the canary.
+    // WHY: [SCORE-CANARY] was wired on the CLI only. This MCP tool — the path
+    //    Claude Code actually scores through — had zero call sites, so a
+    //    drifting scorer would have been caught when a human typed the
+    //    command and missed entirely when an agent called the tool. Session
+    //    21 §H2 found the same shape in the fleet-write guard: a guard that
+    //    covers one caller reads, from the outside, exactly like one that works.
+    // FIX: canary here too. This tool never writes SCORE.md, so a deviation
+    //    is reported rather than fatal — but it is never silent.
+    const canary = runScoreCanary();
+    if (!canary.ok) {
+        return {
+            content: [{
+                    type: "text",
+                    text: "🚨 Scoring canary FAILED — these scores are NOT trustworthy.\n\n" +
+                        canary.deviations.map((d) => `   • ${d}`).join("\n") +
+                        (canary.inconclusive
+                            ? "\n\nThe canary fixture could not be built, so the scorer is unverified. This is an unknown, not a pass."
+                            : "\n\nThe scorer no longer behaves as pinned. Fix the deviation or update the pin deliberately."),
+                }],
+        };
+    }
     const projectDirs = loadProjectDirs();
     let scores;
     if (project) {

package/dist/policy.d.ts

@@ -89,6 +89,89 @@ export type BypassToken = z.infer<typeof BypassTokenSchema>;
 /**
  * The full policy document — schema version 1.
  */
+/**
+ * 🔒 LOCKED [RULE-PARITY-IS-DOC-TO-DOC] — 2026-08-19
+ * ⛔ NEVER fold this into doc_coverage. They answer different questions.
+ * WHY: doc_coverage maps SOURCE → DOC ("you changed src/audit.ts, update SKILLS.md").
+ *      It cannot see the failure that motivated this: a rule that existed in
+ *      ~/.claude/CLAUDE.md and AGENT_USAGE.md but NOT in .github/copilot-instructions.md
+ *      — so it was invisible to Cursor, Windsurf and Copilot, which read only the latter.
+ *      No source file changed, so no doc_coverage rule could ever fire. The rule was
+ *      written, reviewed, and simply not where the readers look.
+ * FIX: parity between DOCS. If a marker appears in any listed file, it must appear in all
+ *      of them. Deliberately literal-substring, not regex: a marker is a grep-able tag in
+ *      the LOCK tradition, and a regex here would fail open on a typo.
+ */
+export declare const RuleParitySchema: z.ZodObject<{
+    id: z.ZodString;
+    marker: z.ZodString;
+    required_in: z.ZodArray<z.ZodString>;
+    severity: z.ZodDefault<z.ZodEnum<{
+        warn: "warn";
+        block: "block";
+    }>>;
+    always_required: z.ZodDefault<z.ZodBoolean>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Model pricing, in dollars per million tokens.
+ *
+ * 🔒 LOCKED [PRICING-LIVES-IN-POLICY] — 2026-08-19
+ * ⛔ NEVER hardcode a rate in the collector, the detector or the CLI.
+ * WHY: rates change, and the collector must be able to value runs for models
+ *    it has never heard of. A rate baked into a compiled `dist/` is a rate
+ *    nobody can correct without a release.
+ * FIX: rates live in `.contextengine/policy.json` → `agent_cost.pricing`.
+ *    Lookup is longest-prefix with a `*` catch-all; an unmatched model is
+ *    reported as UNPRICED, never silently valued at zero.
+ */
+export declare const ModelPricingSchema: z.ZodObject<{
+    model: z.ZodString;
+    input_per_mtok: z.ZodNumber;
+    output_per_mtok: z.ZodNumber;
+    cache_read_per_mtok: z.ZodNumber;
+    cache_write_5m_per_mtok: z.ZodNumber;
+    cache_write_1h_per_mtok: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type ModelPricingRule = z.infer<typeof ModelPricingSchema>;
+/**
+ * Thresholds for the context_burn and fanout_without_canary detectors.
+ *
+ * 🔒 LOCKED [BURN-IS-COST-WEIGHTED-NOT-VOLUME] — 2026-08-19
+ * ⛔ NEVER fire context_burn on a low output/volume ratio alone.
+ * WHY: a healthy 30-agent workflow measures 1.8% output by volume. That looks
+ *    alarming and is not: cache_read is billed at 0.1x input, so those same
+ *    tokens are 28% of cost, and the run cost $35 against $120 without cache.
+ *    Firing on the volume ratio would flag every well-cached run ever done and
+ *    train the user to ignore the alert — the exact failure the
+ *    [DRIFT-HEURISTICS] LOCK in detector.ts exists to prevent.
+ * FIX: fire on cache INEFFICIENCY (cache_read / cache_write below
+ *    min_cache_efficiency — the prefix is being rebuilt, not reused), on tool
+ *    calls per agent, and on valued cost per agent. Real evidence for the
+ *    inefficiency rule: wf_f676d824 spent 68% of $209 on cache WRITES,
+ *    22.7M written against only 8.5M read, across 722 agents.
+ */
+export declare const AgentCostSchema: z.ZodObject<{
+    billing_mode: z.ZodDefault<z.ZodEnum<{
+        api: "api";
+        subscription: "subscription";
+    }>>;
+    pricing: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        model: z.ZodString;
+        input_per_mtok: z.ZodNumber;
+        output_per_mtok: z.ZodNumber;
+        cache_read_per_mtok: z.ZodNumber;
+        cache_write_5m_per_mtok: z.ZodNumber;
+        cache_write_1h_per_mtok: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    min_cache_efficiency: z.ZodDefault<z.ZodNumber>;
+    max_tool_calls_per_agent: z.ZodDefault<z.ZodNumber>;
+    max_cost_per_agent_usd: z.ZodDefault<z.ZodNumber>;
+    min_fanout_for_canary: z.ZodDefault<z.ZodNumber>;
+    max_failed_share: z.ZodDefault<z.ZodNumber>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AgentCost = z.infer<typeof AgentCostSchema>;
 export declare const PolicySchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
     extends: z.ZodOptional<z.ZodString>;
@@ -133,6 +216,37 @@ export declare const PolicySchema: z.ZodObject<{
         requires_reason_min_length: z.ZodDefault<z.ZodNumber>;
         description: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
+    rule_parity: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        marker: z.ZodString;
+        required_in: z.ZodArray<z.ZodString>;
+        severity: z.ZodDefault<z.ZodEnum<{
+            warn: "warn";
+            block: "block";
+        }>>;
+        always_required: z.ZodDefault<z.ZodBoolean>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    agent_cost: z.ZodOptional<z.ZodObject<{
+        billing_mode: z.ZodDefault<z.ZodEnum<{
+            api: "api";
+            subscription: "subscription";
+        }>>;
+        pricing: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            model: z.ZodString;
+            input_per_mtok: z.ZodNumber;
+            output_per_mtok: z.ZodNumber;
+            cache_read_per_mtok: z.ZodNumber;
+            cache_write_5m_per_mtok: z.ZodNumber;
+            cache_write_1h_per_mtok: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>>;
+        min_cache_efficiency: z.ZodDefault<z.ZodNumber>;
+        max_tool_calls_per_agent: z.ZodDefault<z.ZodNumber>;
+        max_cost_per_agent_usd: z.ZodDefault<z.ZodNumber>;
+        min_fanout_for_canary: z.ZodDefault<z.ZodNumber>;
+        max_failed_share: z.ZodDefault<z.ZodNumber>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type Policy = z.infer<typeof PolicySchema>;
 /**

package/dist/policy.js

@@ -106,6 +106,90 @@ export const BypassTokenSchema = z.object({
 /**
  * The full policy document — schema version 1.
  */
+/**
+ * 🔒 LOCKED [RULE-PARITY-IS-DOC-TO-DOC] — 2026-08-19
+ * ⛔ NEVER fold this into doc_coverage. They answer different questions.
+ * WHY: doc_coverage maps SOURCE → DOC ("you changed src/audit.ts, update SKILLS.md").
+ *      It cannot see the failure that motivated this: a rule that existed in
+ *      ~/.claude/CLAUDE.md and AGENT_USAGE.md but NOT in .github/copilot-instructions.md
+ *      — so it was invisible to Cursor, Windsurf and Copilot, which read only the latter.
+ *      No source file changed, so no doc_coverage rule could ever fire. The rule was
+ *      written, reviewed, and simply not where the readers look.
+ * FIX: parity between DOCS. If a marker appears in any listed file, it must appear in all
+ *      of them. Deliberately literal-substring, not regex: a marker is a grep-able tag in
+ *      the LOCK tradition, and a regex here would fail open on a typo.
+ */
+export const RuleParitySchema = z.object({
+    id: z.string().min(1).describe("Stable identifier for this parity rule"),
+    marker: z
+        .string()
+        .min(3)
+        .describe("Literal substring that marks the rule's presence, e.g. 'MULTI-AGENT COST'"),
+    required_in: z
+        .array(z.string())
+        .min(2)
+        .describe("Repo-relative doc paths that must agree. Fewer than 2 makes parity meaningless."),
+    severity: z.enum(["block", "warn"]).default("block"),
+    /** When true the marker must be present in EVERY file, even if currently in none. */
+    always_required: z.boolean().default(false),
+    description: z.string().optional(),
+});
+/**
+ * Model pricing, in dollars per million tokens.
+ *
+ * 🔒 LOCKED [PRICING-LIVES-IN-POLICY] — 2026-08-19
+ * ⛔ NEVER hardcode a rate in the collector, the detector or the CLI.
+ * WHY: rates change, and the collector must be able to value runs for models
+ *    it has never heard of. A rate baked into a compiled `dist/` is a rate
+ *    nobody can correct without a release.
+ * FIX: rates live in `.contextengine/policy.json` → `agent_cost.pricing`.
+ *    Lookup is longest-prefix with a `*` catch-all; an unmatched model is
+ *    reported as UNPRICED, never silently valued at zero.
+ */
+export const ModelPricingSchema = z.object({
+    model: z.string().min(1).describe("Exact model id, a prefix of one, or '*' as catch-all"),
+    input_per_mtok: z.number().nonnegative(),
+    output_per_mtok: z.number().nonnegative(),
+    cache_read_per_mtok: z.number().nonnegative(),
+    cache_write_5m_per_mtok: z.number().nonnegative(),
+    cache_write_1h_per_mtok: z.number().nonnegative().optional(),
+});
+/**
+ * Thresholds for the context_burn and fanout_without_canary detectors.
+ *
+ * 🔒 LOCKED [BURN-IS-COST-WEIGHTED-NOT-VOLUME] — 2026-08-19
+ * ⛔ NEVER fire context_burn on a low output/volume ratio alone.
+ * WHY: a healthy 30-agent workflow measures 1.8% output by volume. That looks
+ *    alarming and is not: cache_read is billed at 0.1x input, so those same
+ *    tokens are 28% of cost, and the run cost $35 against $120 without cache.
+ *    Firing on the volume ratio would flag every well-cached run ever done and
+ *    train the user to ignore the alert — the exact failure the
+ *    [DRIFT-HEURISTICS] LOCK in detector.ts exists to prevent.
+ * FIX: fire on cache INEFFICIENCY (cache_read / cache_write below
+ *    min_cache_efficiency — the prefix is being rebuilt, not reused), on tool
+ *    calls per agent, and on valued cost per agent. Real evidence for the
+ *    inefficiency rule: wf_f676d824 spent 68% of $209 on cache WRITES,
+ *    22.7M written against only 8.5M read, across 722 agents.
+ */
+export const AgentCostSchema = z.object({
+    /**
+     * `subscription` — no dollar is debited; cost is a valuation and CAPACITY is
+     * the scarce resource. `api` — cost is a real debit.
+     */
+    billing_mode: z.enum(["subscription", "api"]).default("subscription"),
+    pricing: z.array(ModelPricingSchema).default([]),
+    /** cache_read / cache_write below this means the cache is thrashing. */
+    min_cache_efficiency: z.number().nonnegative().default(3),
+    /** Per-agent tool calls above this means the agent is searching, not working. */
+    max_tool_calls_per_agent: z.number().positive().default(2),
+    /** Valued cost of a single agent, in dollars. */
+    max_cost_per_agent_usd: z.number().nonnegative().default(3),
+    /** Below this many agents, a fan-out is too small to need a canary. */
+    min_fanout_for_canary: z.number().int().positive().default(5),
+    /** Share of agents that may die without a result before this is a failure. */
+    max_failed_share: z.number().min(0).max(1).default(0.05),
+    description: z.string().optional(),
+});
 export const PolicySchema = z.object({
     version: z.literal(1).describe("Policy schema version. Pin to 1 — bumps require a migration path."),
     extends: z
@@ -118,6 +202,8 @@ export const PolicySchema = z.object({
     deploy_verify_hosts: z.array(DeployVerifyHostSchema).default([]),
     commit_message_required: z.array(CommitMessageRequiredSchema).default([]),
     bypass_tokens: z.array(BypassTokenSchema).default([]),
+    rule_parity: z.array(RuleParitySchema).default([]),
+    agent_cost: AgentCostSchema.optional(),
 });
 export function validatePolicy(raw) {
     const result = PolicySchema.safeParse(raw);
@@ -209,6 +295,10 @@ export function formatPolicySummary(policy) {
     for (const b of policy.bypass_tokens) {
         lines.push(`  - ${b.id} → TTL ${b.ttl_seconds}s, reason ≥ ${b.requires_reason_min_length} chars`);
     }
+    lines.push(`Rule-parity rules: ${policy.rule_parity.length}`);
+    for (const r of policy.rule_parity) {
+        lines.push(`  - ${r.id} → marker "${r.marker}" must agree across ${r.required_in.length} file(s) [${r.severity}]${r.always_required ? " (always required)" : ""}`);
+    }
     return lines.join("\n");
 }
 export function formatValidationErrors(errors) {

package/dist/transcript-collector.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Transcript collector — per-subagent token, cost and intensity accounting
+ * read from Claude Code's own JSONL transcripts.
+ *
+ * Layout (verified against 2,310 real agent transcripts on 2026-08-19):
+ *
+ *   ~/.claude/projects/<project-slug>/<sessionId>.jsonl              parent session
+ *   ~/.claude/projects/<project-slug>/<sessionId>/subagents/
+ *        agent-<agentId>.jsonl                                       Agent-tool subagent
+ *        workflows/<wf_id>/agent-<agentId>.jsonl                     Workflow subagent
+ *
+ * 🔒 LOCKED [TRANSCRIPT-DEDUP-BY-MESSAGE-ID] — 2026-08-19
+ * ⛔ NEVER sum `message.usage` per JSONL line. One assistant `message.id` is
+ *    written across SEVERAL lines (one per content block: thinking, text, each
+ *    tool_use), and EVERY line repeats the SAME usage object.
+ * WHY: measured on a real agent transcript, naive per-line summing reported
+ *    624,873 cache_read tokens where the true figure was 225,183 — a 2.8x
+ *    overcount, and 4.6x on cache_creation. A cost report that overstates by
+ *    3x is worse than no cost report: it gets disbelieved, then ignored.
+ * FIX: reduce by `message.id`. Verified invariant over 1,609 message ids in
+ *    126 files: input_tokens / cache_creation_input_tokens /
+ *    cache_read_input_tokens are CONSTANT within an id (0 exceptions), and
+ *    output_tokens increases monotonically, so the max is the final count.
+ *    tests/transcript-collector.test.ts pins both halves.
+ */
+/** Raw token tallies, in tokens. */
+export interface TokenTally {
+    input: number;
+    cacheWrite5m: number;
+    cacheWrite1h: number;
+    cacheRead: number;
+    output: number;
+}
+/**
+ * How a subagent's transcript ended. `capacity_exhausted` is the one that
+ * matters on a subscription: the agent was launched, consumed context, and
+ * returned nothing because the usage window ran out.
+ */
+export type AgentStatus = "reported_structured" | "reported_text" | "capacity_exhausted" | "output_cap" | "api_error" | "no_report";
+export interface AgentUsage {
+    agentId: string;
+    file: string;
+    /** Dominant real model, for display. Never `<synthetic>` — see the LOCK below. */
+    model: string | null;
+    /**
+     * Tokens attributed to the model that actually produced them.
+     *
+     * 🔒 LOCKED [PRICE-PER-MESSAGE-MODEL-NOT-PER-AGENT] — 2026-08-19
+     * ⛔ NEVER price an agent's whole tally at one model taken from its last
+     *    assistant message.
+     * WHY: Claude Code writes client-side notices ("You're out of usage
+     *    credits", "API Error: …") as assistant messages with model
+     *    `<synthetic>` and ALL-ZERO usage. They land LAST, so last-wins tagged
+     *    every capacity-killed agent `<synthetic>`, and since that model has no
+     *    price its real consumption was dropped as UNPRICED: 2.2M tokens
+     *    silently missing from wf_41771d7b — precisely the agents that died,
+     *    i.e. the cost of the failure the report exists to surface.
+     * FIX: tally per message model and price each group at its own rate.
+     *    `<synthetic>` contributes 0 tokens and is excluded from `model`.
+     */
+    tokensByModel: Map<string | null, TokenTally>;
+    toolCalls: number;
+    /** Distinct assistant messages (API round-trips), after dedup. */
+    turns: number;
+    tokens: TokenTally;
+    startedAt: number | null;
+    endedAt: number | null;
+    durationMs: number | null;
+    status: AgentStatus;
+    /** True when the agent actually returned a result to its caller. */
+    reported: boolean;
+}
+export type RunKind = "workflow" | "agents" | "session";
+export interface RunUsage {
+    /** Workflow id (`wf_…`) for workflow runs, else the session id. */
+    runId: string;
+    kind: RunKind;
+    /** Decoded project slug, e.g. `-Users-yan-Projects-ContextEngine`. */
+    project: string;
+    sessionId: string;
+    agents: AgentUsage[];
+    totals: TokenTally;
+    toolCalls: number;
+    startedAt: number | null;
+    endedAt: number | null;
+    /** Wall-clock span of the run, not the sum of agent durations. */
+    durationMs: number | null;
+}
+/** Dollars per million tokens, per tier. */
+export interface ModelPricing {
+    model: string;
+    input_per_mtok: number;
+    output_per_mtok: number;
+    cache_read_per_mtok: number;
+    cache_write_5m_per_mtok: number;
+    cache_write_1h_per_mtok?: number;
+}
+export interface CostBreakdown {
+    input: number;
+    cacheWrite: number;
+    cacheRead: number;
+    output: number;
+    total: number;
+    /** What the same tokens would have cost with no cache at all. */
+    withoutCache: number;
+    /** Tokens with no pricing entry — surfaced, never silently zeroed. */
+    unpricedTokens: number;
+}
+/**
+ * Longest-prefix pricing lookup. `*` is the catch-all. Returns null when
+ * nothing matches — the caller must report that, not assume free.
+ *
+ * 🔒 LOCK [ABSENCE-IS-NOT-A-VERDICT] — an unpriced model is "I don't know
+ *    what this cost", never "$0". Session 21's recurring bug shape.
+ */
+export declare function pricingFor(model: string | null, table: ModelPricing[]): ModelPricing | null;
+/**
+ * Value a token tally at API list prices.
+ *
+ * 🔒 LOCKED [COST-IS-NOTIONAL-ON-SUBSCRIPTION] — 2026-08-19
+ * ⛔ NEVER present this number as money spent, or gate anything on it alone,
+ *    without stating the billing mode.
+ * WHY: this machine runs Claude Code on a Max subscription (verified:
+ *    `subscriptionType: max`, no ANTHROPIC_API_KEY anywhere). No dollar here
+ *    is ever debited. The figure is a VALUATION at public API rates, useful
+ *    only to compare two approaches against each other.
+ * FIX: on subscription the scarce resource is CAPACITY, not money. A $75 run
+ *    that finishes beats a $40 run that loses 13% of its agents to the usage
+ *    window. `contextengine cost` therefore always prints volume, valued cost
+ *    AND intensity — never one alone.
+ */
+export declare function costOf(t: TokenTally, p: ModelPricing | null): CostBreakdown;
+export declare function emptyTally(): TokenTally;
+export declare function addTally(a: TokenTally, b: TokenTally): TokenTally;
+export declare function totalTokens(t: TokenTally): number;
+/** Tokens the model actually wrote, as a share of all tokens moved. */
+export declare function outputShare(t: TokenTally): number;
+/**
+ * cache_read / cache_write. HIGH is healthy — it means a prefix was built
+ * once and reused many times. LOW means the cache is being rebuilt and thrown
+ * away (unstable prefix, cold fan-out). This is the ratio that actually
+ * signals waste; a large cache_read on its own does not.
+ */
+export declare function cacheEfficiency(t: TokenTally): number;
+/** Root of Claude Code's transcript store. Env override exists for tests. */
+export declare function transcriptRoot(): string;
+/**
+ * Parse one `agent-*.jsonl`. Tolerant by design: transcripts are appended
+ * live and a truncated final line is normal, so unparseable lines are
+ * skipped rather than failing the whole run.
+ */
+export declare function parseAgentTranscript(file: string): AgentUsage;
+/**
+ * Terminal state of an agent, read from its own last words.
+ *
+ * 🔒 LOCKED [AGENT-REPORTED-IS-NOT-LAST-LINE] — 2026-08-19
+ * ⛔ NEVER decide "this agent completed" from the last LINE of the transcript.
+ * WHY: 2,090 of 2,310 real transcripts end on a `user` line — the tool_result
+ *    for the agent's own final `StructuredOutput` call. Reading the last line
+ *    classified 2,146 healthy agents as "other" and would have made
+ *    fanout_without_canary fire on every workflow ever run.
+ * FIX: an agent reported if it produced a final text block, or a
+ *    StructuredOutput call that returned success. Measured with this rule:
+ *    2,285 reported / 19 capacity_exhausted / 3 api_error / 2 no_report.
+ */
+export declare function classifyStatus(lastText: string, structuredOk: boolean): AgentStatus;
+export declare function isReported(s: AgentStatus): boolean;
+export interface CollectOptions {
+    /** Only this session id (the uuid naming the transcript dir). */
+    session?: string;
+    /** Only projects whose slug contains this substring. */
+    project?: string;
+    /** Only this run id (`wf_…`). */
+    run?: string;
+    /** Ignore runs that ended before this epoch-ms. */
+    since?: number;
+    root?: string;
+}
+/**
+ * Walk the transcript store and return one RunUsage per fan-out.
+ *
+ * A "run" is a workflow directory (`subagents/workflows/wf_…`) or the loose
+ * `subagents/` directory of a session (Agent-tool calls). Parent-session
+ * transcripts are not fan-outs and are excluded — this measures the cost of
+ * DELEGATION, which is the thing worth deciding about before spending it.
+ */
+export declare function collectRuns(opts?: CollectOptions): RunUsage[];
+export interface RunMetrics {
+    agents: number;
+    reported: number;
+    capacityExhausted: number;
+    failed: number;
+    toolCalls: number;
+    medianToolCalls: number;
+    outputShare: number;
+    cacheEfficiency: number;
+    cost: CostBreakdown;
+    /** Agents that started before ANY sibling had reported — the un-canaried fleet. */
+    launchedBeforeFirstReport: number;
+}
+export declare function runCost(run: RunUsage, table: ModelPricing[]): CostBreakdown;
+/**
+ * The canary count. "Run ONE unit and read its consumption before scaling"
+ * is only obeyed if some agent finished before the rest were launched, so
+ * count the agents whose start precedes the earliest sibling completion.
+ */
+export declare function metricsFor(run: RunUsage, table: ModelPricing[]): RunMetrics;
+//# sourceMappingURL=transcript-collector.d.ts.map