ctxloom-pro 1.2.7 → 1.3.1

package/README.md

@@ -47,6 +47,8 @@ The full first-run flow is **one install + one trial + one init per project.** E
 npm install -g ctxloom-pro
 ```
 
+> **For local trial / dev use the unpinned command above is fine.** For unattended CI usage, pin to the exact version (`ctxloom-pro@1.3.1`) so future CLI releases don't silently desync your agent-spec coverage — see the workflow example below.
+
 ### 2 — Start your free trial (once per email)
 
 ```bash
@@ -341,7 +343,10 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with: { node-version: '20' }
-      - run: npm install -g ctxloom-pro
+      # Exact pin (not `@^1`) so future CLI releases that add/remove MCP
+      # tools don't silently desync your reviewer-agent specs. Bump on
+      # every release; see CHANGELOG.md for the live version table.
+      - run: npm install -g ctxloom-pro@1.3.1
       - run: ctxloom index
       - run: ctxloom rules check --json
 ```
@@ -502,6 +507,83 @@ Pass `--no-git` to disable the overlay entirely. Tools degrade gracefully — th
 
 ---
 
+## Response Budgets (v1.2.7+)
+
+Twelve source-returning tools accept a server-enforced **token budget**. When a response would exceed the budget, the server auto-substitutes a lighter form (Skeletonizer signature view, summary-only XML, or paths-without-snippets) instead of dumping 50KB of source into your context window.
+
+### Opting in
+
+Pass any of these three optional fields to any of the 12 supported tools:
+
+```json
+{
+  "max_response_tokens": 4000,
+  "on_budget_exceeded": "skeleton",
+  "response_format": "auto"
+}
+```
+
+| Field | Values | Default |
+|---|---|---|
+| `max_response_tokens` | positive integer | per-tool (see below) |
+| `on_budget_exceeded` | `"skeleton"` \| `"truncate"` \| `"error"` | `"skeleton"` |
+| `response_format` | `"full"` \| `"skeleton"` \| `"auto"` | `"auto"` |
+
+**Back-compat:** when none of these fields are passed, the tool returns its raw response unchanged. Existing callers see zero behavior change.
+
+### Response envelope
+
+When you opt in, the response is wrapped in a JSON envelope:
+
+```json
+{
+  "data": "<the actual tool output — XML, text, or whatever the tool returns>",
+  "meta": {
+    "format": "full" | "skeleton" | "truncated",
+    "original_tokens_est": 8400,
+    "returned_tokens_est": 1600,
+    "fallback_reason": null | "budget_exceeded" | "minified_input" | "size_cap" | "skeleton_failed"
+  }
+}
+```
+
+### Supported tools + default budgets
+
+Defaults activate only when you opt in (any of the 3 fields above) without specifying `max_response_tokens` explicitly.
+
+| Tool | Default | Skeleton fallback |
+|---|---:|---|
+| `ctx_get_file` | 8000 | Skeletonizer view of the file (~90% reduction on TS) |
+| `ctx_get_context_packet` | 6000 | Re-render with the primary file skeletonized |
+| `ctx_get_definition` | 2000 | none — truncate-only (already structural) |
+| `ctx_git_diff_review` | 8000 | Drop `<skeleton>` blocks + omit transitive importers |
+| `ctx_search` | 4000 | Drop content snippets (paths + scores only) |
+| `ctx_full_text_search` | 4000 | Drop match snippets (paths + match counts only) |
+| `ctx_wiki_generate` | 12000 | Downgrade to `detail_level=minimal` |
+| `ctx_find_large_functions` | 2000 | none — truncate-only |
+| `ctx_apply_refactor` | 2000 | none — truncate-only |
+| `ctx_refactor_preview` | 4000 | Drop per-change before/after, keep file summary |
+| `ctx_cross_repo_search` | 4000 | Drop content snippets |
+| `ctx_execution_flow` | 4000 | none — truncate-only |
+
+Defaults are **provisional** (derived from the issue's initial table); a future release will re-derive them from real per-tool p75 telemetry once enough usage data accumulates.
+
+### Token estimator
+
+Default = `chars / 4` — within ±10% of GPT/Claude tokenizers on code with zero tokenization cost. Pluggable per-tool via the `estimator` option on `BudgetOptions` for callers that need accuracy-critical estimation (e.g. tiktoken).
+
+### Kill switch
+
+Set `CTXLOOM_DISABLE_BUDGET=1` in the environment to silently ignore every `max_response_tokens` arg server-wide. Tools behave exactly as in pre-v1.2.7. Documented escape hatch for the soak period.
+
+### Telemetry
+
+Set `CTXLOOM_TELEMETRY_LEVEL=full` to emit structured `mcp.budget.exceeded` and `mcp.fallback.used` events to stderr. Useful for tuning defaults against your own usage patterns.
+
+> **Note:** `CTXLOOM_TELEMETRY_LEVEL` is also consumed by the license / PostHog telemetry layer (see [Telemetry](#telemetry) below) which only recognizes `all` / `error` / `off`. `full` is a separate, **additive** level — it enables budget-event emission *without narrowing* PostHog scope. To narrow PostHog telemetry, set the variable to `error` or `off`; those values disable budget events as a side effect.
+
+---
+
 ## CLI Commands
 
 ```

package/apps/dashboard/dist/server/index.js

@@ -166,12 +166,12 @@ var init_VectorStore = __esm({
 // server/index.ts
 import express from "express";
 import cors from "cors";
-import path44 from "path";
-import fs32 from "fs";
+import path45 from "path";
+import fs33 from "fs";
 import { fileURLToPath as fileURLToPath2 } from "url";
 
 // server/loader.ts
-import path38 from "path";
+import path39 from "path";
 
 // ../../packages/core/src/graph/DependencyGraph.ts
 import fs7 from "fs";
@@ -3181,8 +3181,8 @@ var CoChangeIndex = class _CoChangeIndex {
     if (event.isBulk || event.isMerge) return;
     const paths = event.files.map((f) => f.path);
     if (paths.length === 0) return;
-    for (const path45 of paths) {
-      this.nodeCounts.set(path45, (this.nodeCounts.get(path45) ?? 0) + 1);
+    for (const path46 of paths) {
+      this.nodeCounts.set(path46, (this.nodeCounts.get(path46) ?? 0) + 1);
     }
     for (let i = 0; i < paths.length; i++) {
       for (let j = i + 1; j < paths.length; j++) {
@@ -3329,8 +3329,8 @@ var ChurnIndex = class _ChurnIndex {
    */
   snapshot() {
     const nodes = {};
-    for (const [path45, raw] of this.nodes) {
-      nodes[path45] = {
+    for (const [path46, raw] of this.nodes) {
+      nodes[path46] = {
         commits: raw.commits,
         churnLines: raw.churnLines,
         bugCommits: raw.bugCommits,
@@ -3345,8 +3345,8 @@ var ChurnIndex = class _ChurnIndex {
    */
   static load(s) {
     const idx = new _ChurnIndex();
-    for (const [path45, raw] of Object.entries(s.nodes)) {
-      idx.nodes.set(path45, {
+    for (const [path46, raw] of Object.entries(s.nodes)) {
+      idx.nodes.set(path46, {
         commits: raw.commits,
         churnLines: raw.churnLines,
         bugCommits: raw.bugCommits,
@@ -3359,8 +3359,8 @@ var ChurnIndex = class _ChurnIndex {
   // -------------------------------------------------------------------------
   // Private helpers
   // -------------------------------------------------------------------------
-  getOrCreate(path45) {
-    const existing = this.nodes.get(path45);
+  getOrCreate(path46) {
+    const existing = this.nodes.get(path46);
     if (existing !== void 0) return existing;
     const fresh = {
       commits: 0,
@@ -3369,7 +3369,7 @@ var ChurnIndex = class _ChurnIndex {
       authorCounts: {},
       lastTouch: 0
     };
-    this.nodes.set(path45, fresh);
+    this.nodes.set(path46, fresh);
     return fresh;
   }
 };
@@ -3450,12 +3450,12 @@ var OwnershipIndex = class _OwnershipIndex {
    */
   snapshot() {
     const nodes = {};
-    for (const [path45, raw] of this.nodes) {
+    for (const [path46, raw] of this.nodes) {
       const authorWeights = {};
       for (const [email, entry] of Object.entries(raw.authorWeights)) {
         authorWeights[email] = { ...entry };
       }
-      nodes[path45] = { authorWeights, lastTouch: raw.lastTouch };
+      nodes[path46] = { authorWeights, lastTouch: raw.lastTouch };
     }
     return { version: 1, nodes };
   }
@@ -3464,23 +3464,23 @@ var OwnershipIndex = class _OwnershipIndex {
    */
   static load(s) {
     const idx = new _OwnershipIndex();
-    for (const [path45, raw] of Object.entries(s.nodes)) {
+    for (const [path46, raw] of Object.entries(s.nodes)) {
       const authorWeights = {};
       for (const [email, entry] of Object.entries(raw.authorWeights)) {
         authorWeights[email] = { ...entry };
       }
-      idx.nodes.set(path45, { authorWeights, lastTouch: raw.lastTouch });
+      idx.nodes.set(path46, { authorWeights, lastTouch: raw.lastTouch });
     }
     return idx;
   }
   // -------------------------------------------------------------------------
   // Private helpers
   // -------------------------------------------------------------------------
-  getOrCreate(path45) {
-    const existing = this.nodes.get(path45);
+  getOrCreate(path46) {
+    const existing = this.nodes.get(path46);
     if (existing !== void 0) return existing;
     const fresh = { authorWeights: {}, lastTouch: 0 };
-    this.nodes.set(path45, fresh);
+    this.nodes.set(path46, fresh);
     return fresh;
   }
 };
@@ -4718,8 +4718,8 @@ function getErrorMap() {
 
 // ../../node_modules/zod/v3/helpers/parseUtil.js
 var makeIssue = (params) => {
-  const { data, path: path45, errorMaps, issueData } = params;
-  const fullPath = [...path45, ...issueData.path || []];
+  const { data, path: path46, errorMaps, issueData } = params;
+  const fullPath = [...path46, ...issueData.path || []];
   const fullIssue = {
     ...issueData,
     path: fullPath
@@ -4835,11 +4835,11 @@ var errorUtil;
 
 // ../../node_modules/zod/v3/types.js
 var ParseInputLazyPath = class {
-  constructor(parent, value, path45, key) {
+  constructor(parent, value, path46, key) {
     this._cachedPath = [];
     this.parent = parent;
     this.data = value;
-    this._path = path45;
+    this._path = path46;
     this._key = key;
   }
   get path() {
@@ -8294,6 +8294,13 @@ init_embedder();
 // ../../packages/core/src/budget/budget.ts
 init_logger();
 
+// ../../packages/core/src/budget/eventCollector.ts
+init_logger();
+import fs16 from "fs";
+import os2 from "os";
+import path16 from "path";
+var DEFAULT_TELEMETRY_DIR = path16.join(os2.homedir(), ".ctxloom", "telemetry");
+
 // ../../packages/core/src/tools/search.ts
 var Schema = external_exports.object({
   query: external_exports.string().describe("Search query \u2014 natural language or code fragment"),
@@ -8316,7 +8323,7 @@ var Schema2 = external_exports.object({
 });
 
 // ../../packages/core/src/tools/context-packet.ts
-import path16 from "path";
+import path17 from "path";
 var Schema3 = external_exports.object({
   target_file: external_exports.string().describe("Relative path to the primary file"),
   mode: external_exports.enum(["edit", "read"]).optional().default("edit").describe("Context mode"),
@@ -8328,7 +8335,7 @@ var Schema3 = external_exports.object({
 });
 
 // ../../packages/core/src/tools/findCallers.ts
-import path17 from "path";
+import path18 from "path";
 
 // ../../packages/core/src/tools/call-graph.ts
 var Schema4 = external_exports.object({
@@ -8429,7 +8436,7 @@ var Schema12 = external_exports.object({
 });
 
 // ../../packages/core/src/tools/knowledge-gaps.ts
-import path18 from "path";
+import path19 from "path";
 var Schema13 = external_exports.object({
   min_importers: external_exports.number().min(1).max(50).optional().default(3).describe(
     "Minimum importers to qualify as an untested hub (default: 3)"
@@ -8458,7 +8465,7 @@ var Schema14 = external_exports.object({
 });
 
 // ../../packages/core/src/tools/wiki-generate.ts
-import fs16 from "fs";
+import fs17 from "fs";
 var Schema15 = external_exports.object({
   force: external_exports.boolean().optional().default(false).describe(
     "Regenerate all pages even if content unchanged (default: false)"
@@ -8506,8 +8513,8 @@ var Schema17 = external_exports.object({
 });
 
 // ../../packages/core/src/tools/refactor-preview.ts
-import fs17 from "fs";
-import path19 from "path";
+import fs18 from "fs";
+import path20 from "path";
 var Schema18 = external_exports.object({
   symbol: external_exports.string().min(1).describe("Symbol name to rename (exact match, case-sensitive)"),
   new_name: external_exports.string().min(1).describe("New name for the symbol"),
@@ -8542,8 +8549,8 @@ var Schema19 = external_exports.object({
 init_embedder();
 init_VectorStore();
 init_logger();
-import fs18 from "fs";
-import path20 from "path";
+import fs19 from "fs";
+import path21 from "path";
 var Schema20 = external_exports.object({
   query: external_exports.string().min(1).describe("Search query \u2014 natural language or code fragment"),
   limit: external_exports.number().min(1).max(100).optional().default(10).describe(
@@ -8560,8 +8567,8 @@ var Schema20 = external_exports.object({
 });
 
 // ../../packages/core/src/tools/apply-refactor.ts
-import fs19 from "fs";
-import path21 from "path";
+import fs20 from "fs";
+import path22 from "path";
 var Schema21 = external_exports.object({
   symbol: external_exports.string().min(1).describe("Symbol name to rename (exact, case-sensitive)"),
   new_name: external_exports.string().min(1).describe("New name for the symbol"),
@@ -8594,8 +8601,8 @@ var Schema22 = external_exports.object({
 });
 
 // ../../packages/core/src/tools/full-text-search.ts
-import fs20 from "fs";
-import path22 from "path";
+import fs21 from "fs";
+import path23 from "path";
 var Schema23 = external_exports.object({
   query: external_exports.string().min(1).describe("Search term \u2014 literal or /regex/"),
   mode: external_exports.enum(["hybrid", "keyword", "semantic"]).optional().default("hybrid"),
@@ -8627,8 +8634,8 @@ var Schema25 = external_exports.object({
 });
 
 // ../../packages/core/src/tools/graph-snapshot.ts
-import fs21 from "fs";
-import path23 from "path";
+import fs22 from "fs";
+import path24 from "path";
 var schema = external_exports.object({
   name: external_exports.string().min(1).max(64).regex(/^[\w.-]+$/, "Name may only contain letters, digits, dots, underscores, hyphens").describe(
     'Snapshot name (e.g. "before-refactor", "v1.0"). Used as the filename.'
@@ -8640,8 +8647,8 @@ var schema = external_exports.object({
 });
 
 // ../../packages/core/src/tools/graph-diff.ts
-import fs22 from "fs";
-import path24 from "path";
+import fs23 from "fs";
+import path25 from "path";
 var schema2 = external_exports.object({
   baseline: external_exports.string().min(1).describe('Name of the baseline snapshot (the "before" state).'),
   current: external_exports.string().min(1).describe('Name of the current snapshot (the "after" state).'),
@@ -8682,8 +8689,8 @@ var Schema27 = external_exports.object({
 });
 
 // ../../packages/core/src/rules/loadConfig.ts
-import fs23 from "fs/promises";
-import path25 from "path";
+import fs24 from "fs/promises";
+import path26 from "path";
 
 // ../../node_modules/js-yaml/dist/js-yaml.mjs
 function isNothing(subject) {
@@ -11312,24 +11319,24 @@ var Schema29 = external_exports.object({
 });
 
 // ../../packages/core/src/tools/ruleManager.ts
-import fs24 from "fs";
-import path26 from "path";
-
-// ../../packages/core/src/review/AuthorResolver.ts
-import fs25 from "fs/promises";
+import fs25 from "fs";
 import path27 from "path";
 
-// ../../packages/core/src/review/CodeownersWriter.ts
+// ../../packages/core/src/review/AuthorResolver.ts
 import fs26 from "fs/promises";
 import path28 from "path";
 
-// ../../packages/core/src/review/loadConfig.ts
+// ../../packages/core/src/review/CodeownersWriter.ts
 import fs27 from "fs/promises";
 import path29 from "path";
 
-// ../../packages/core/src/security/PathValidator.ts
+// ../../packages/core/src/review/loadConfig.ts
+import fs28 from "fs/promises";
 import path30 from "path";
-import fs28 from "fs";
+
+// ../../packages/core/src/security/PathValidator.ts
+import path31 from "path";
+import fs29 from "fs";
 var MAX_FILE_SIZE = 5 * 1024 * 1024;
 
 // ../../packages/core/src/index.ts
@@ -11340,7 +11347,7 @@ init_logger();
 
 // ../../packages/core/src/license/LicenseStore.ts
 import { readFileSync, writeFileSync, unlinkSync, mkdirSync, chmodSync, existsSync } from "fs";
-import path31 from "path";
+import path32 from "path";
 
 // ../../packages/core/src/license/types.ts
 var FINGERPRINT_RE = /^sha256:[0-9a-f]{64}$/;
@@ -11363,19 +11370,19 @@ var API_BASE = process.env["CTXLOOM_API_BASE"] ?? "https://api.ctxloom.com";
 
 // ../../packages/core/src/license/Fingerprint.ts
 import crypto4 from "crypto";
-import os2 from "os";
+import os3 from "os";
 import { readFileSync as readFileSync2 } from "fs";
 
 // ../../packages/core/src/license/index.ts
-import os5 from "os";
+import os6 from "os";
 
 // ../../packages/core/src/license/DistinctIdStore.ts
 import { readFileSync as readFileSync3, writeFileSync as writeFileSync2, mkdirSync as mkdirSync2, existsSync as existsSync2 } from "fs";
-import path32 from "path";
-import os3 from "os";
+import path33 from "path";
+import os4 from "os";
 var UUID_V4_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 function distinctIdPath(home) {
-  return path32.join(home ?? os3.homedir(), ".ctxloom", "distinct_id");
+  return path33.join(home ?? os4.homedir(), ".ctxloom", "distinct_id");
 }
 function isValidV4(id) {
   return typeof id === "string" && UUID_V4_REGEX.test(id);
@@ -11394,9 +11401,9 @@ function getOrCreateDistinctId(home) {
   }
   const record = {
     id: crypto.randomUUID(),
-    alias_pending: os3.hostname()
+    alias_pending: os4.hostname()
   };
-  mkdirSync2(path32.dirname(filePath), { recursive: true });
+  mkdirSync2(path33.dirname(filePath), { recursive: true });
   writeFileSync2(filePath, JSON.stringify(record), { mode: 384 });
   return record;
 }
@@ -11422,7 +11429,7 @@ function resolveTelemetryLevel() {
 }
 var TELEMETRY_LEVEL = resolveTelemetryLevel();
 var TELEMETRY_DISABLED = TELEMETRY_LEVEL === "off";
-var CTXLOOM_VERSION = "1.2.7".length > 0 ? "1.2.7" : "dev";
+var CTXLOOM_VERSION = "1.3.1".length > 0 ? "1.3.1" : "dev";
 var POSTHOG_HOST = "https://eu.i.posthog.com";
 var POSTHOG_KEY = process.env["POSTHOG_API_KEY"] ?? (true ? "phc_CiDkmFLcZ2K6uCpcoSUQLmFrnnUvsyXGhSxopX5TVKE6" : "");
 var SENTRY_DSN = process.env["SENTRY_DSN"] ?? (true ? "https://81c94a0f04a8e242dee493ac1e17f733@o4508531702497280.ingest.de.sentry.io/4511256875368528" : "");
@@ -11555,31 +11562,31 @@ function parseStack(stack) {
 
 // ../../packages/core/src/license/FunnelMilestones.ts
 import { existsSync as existsSync3, mkdirSync as mkdirSync3, writeFileSync as writeFileSync3 } from "fs";
-import path33 from "path";
-import os4 from "os";
+import path34 from "path";
+import os5 from "os";
 
 // ../../packages/core/src/license/TelemetryNotice.ts
 import { existsSync as existsSync4, mkdirSync as mkdirSync4, writeFileSync as writeFileSync4 } from "fs";
-import path34 from "path";
-import os6 from "os";
+import path35 from "path";
+import os7 from "os";
 
 // ../../packages/core/src/server/ProjectState.ts
-import path36 from "path";
+import path37 from "path";
 
 // ../../packages/core/src/server/projectId.ts
 import crypto5 from "crypto";
-import path35 from "path";
+import path36 from "path";
 
 // ../../packages/core/src/server/ProjectStateManager.ts
 init_logger();
 
 // ../../packages/core/src/server/resolveProjectRoot.ts
-import fs29 from "fs";
-import path37 from "path";
+import fs30 from "fs";
+import path38 from "path";
 
 // server/loader.ts
 async function loadContext(root) {
-  const absRoot = path38.resolve(root);
+  const absRoot = path39.resolve(root);
   const overlay = new GitOverlayStore(absRoot);
   const gitEnabled = await overlay.loadSnapshot();
   const graph = new DependencyGraph();
@@ -11832,21 +11839,21 @@ function buildOwnershipRouter(ctx) {
 
 // server/routes/file.ts
 import { Router as Router7 } from "express";
-import fs30 from "fs/promises";
-import path39 from "path";
+import fs31 from "fs/promises";
+import path40 from "path";
 function buildFileRouter(ctx) {
   const router = Router7();
   router.get("/", async (req, res) => {
     const rel = req.query.path;
     if (!rel) return res.status(400).json({ error: "missing path" });
-    const abs = path39.resolve(ctx.root, rel);
-    const rootBoundary = ctx.root.endsWith(path39.sep) ? ctx.root : ctx.root + path39.sep;
+    const abs = path40.resolve(ctx.root, rel);
+    const rootBoundary = ctx.root.endsWith(path40.sep) ? ctx.root : ctx.root + path40.sep;
     if (abs !== ctx.root && !abs.startsWith(rootBoundary)) {
       return res.status(403).json({ error: "forbidden" });
     }
     try {
-      const content = await fs30.readFile(abs, "utf-8");
-      const ext = path39.extname(abs).slice(1);
+      const content = await fs31.readFile(abs, "utf-8");
+      const ext = path40.extname(abs).slice(1);
       res.json({ content, lines: content.split("\n").length, ext });
     } catch {
       res.status(404).json({ error: "not found" });
@@ -11858,7 +11865,7 @@ function buildFileRouter(ctx) {
 // server/routes/open.ts
 import { Router as Router8 } from "express";
 import { execFile as execFile2 } from "child_process";
-import path40 from "path";
+import path41 from "path";
 function tryOpen(bin, abs) {
   return new Promise((resolve) => {
     execFile2(bin, [abs], { timeout: 5e3 }, (err) => resolve(!err));
@@ -11869,8 +11876,8 @@ function buildOpenRouter(ctx) {
   router.post("/", async (req, res) => {
     const rel = req.body?.path;
     if (!rel || typeof rel !== "string") return res.status(400).json({ error: "missing path" });
-    const abs = path40.resolve(ctx.root, rel);
-    const rootBoundary = ctx.root.endsWith(path40.sep) ? ctx.root : ctx.root + path40.sep;
+    const abs = path41.resolve(ctx.root, rel);
+    const rootBoundary = ctx.root.endsWith(path41.sep) ? ctx.root : ctx.root + path41.sep;
     if (abs !== ctx.root && !abs.startsWith(rootBoundary)) {
       return res.status(403).json({ error: "forbidden" });
     }
@@ -11882,8 +11889,8 @@ function buildOpenRouter(ctx) {
 
 // server/routes/tokens.ts
 import { Router as Router9 } from "express";
-import path41 from "path";
-import fs31 from "fs";
+import path42 from "path";
+import fs32 from "fs";
 var CHARS_PER_TOKEN = 4;
 var cache = null;
 function buildTokensRouter(ctx) {
@@ -11898,9 +11905,9 @@ function buildTokensRouter(ctx) {
     let fullChars = 0;
     let skeletonChars = 0;
     for (const file of files) {
-      const absPath = path41.join(ctx.root, file);
+      const absPath = path42.join(ctx.root, file);
       try {
-        const content = fs31.readFileSync(absPath, "utf-8");
+        const content = fs32.readFileSync(absPath, "utf-8");
         fullChars += content.length;
         const skeleton = await skeletonizer.skeletonize(absPath);
         skeletonChars += skeleton.length;
@@ -12001,17 +12008,17 @@ function buildFileTrendsRouter(ctx) {
 
 // server/routes/projects.ts
 import { Router as Router12 } from "express";
-import path43 from "path";
+import path44 from "path";
 
 // server/projects.ts
 import { existsSync as existsSync5, readFileSync as readFileSync4 } from "fs";
-import os7 from "os";
-import path42 from "path";
+import os8 from "os";
+import path43 from "path";
 import crypto6 from "crypto";
-var HOME = os7.homedir();
-var REGISTRY_PATH = path42.join(HOME, ".ctxloom", "repos.json");
+var HOME = os8.homedir();
+var REGISTRY_PATH = path43.join(HOME, ".ctxloom", "repos.json");
 function slugFor(root) {
-  const abs = path42.resolve(root);
+  const abs = path43.resolve(root);
   return crypto6.createHash("sha1").update(abs).digest("hex").slice(0, 12);
 }
 function readRegistry() {
@@ -12026,27 +12033,27 @@ function readRegistry() {
   }
 }
 function listProjects(defaultRoot) {
-  const absDefault = path42.resolve(defaultRoot);
+  const absDefault = path43.resolve(defaultRoot);
   const out = [
     {
       slug: slugFor(absDefault),
-      name: path42.basename(absDefault) || absDefault,
+      name: path43.basename(absDefault) || absDefault,
       root: absDefault,
       isDefault: true,
-      hasSnapshot: existsSync5(path42.join(absDefault, ".ctxloom"))
+      hasSnapshot: existsSync5(path43.join(absDefault, ".ctxloom"))
     }
   ];
   const seen = /* @__PURE__ */ new Set([absDefault]);
   for (const entry of readRegistry()) {
-    const abs = path42.resolve(entry.root);
+    const abs = path43.resolve(entry.root);
     if (seen.has(abs)) continue;
     seen.add(abs);
     const item = {
       slug: slugFor(abs),
-      name: entry.name ?? (path42.basename(abs) || abs),
+      name: entry.name ?? (path43.basename(abs) || abs),
       root: abs,
       isDefault: false,
-      hasSnapshot: existsSync5(path42.join(abs, ".ctxloom"))
+      hasSnapshot: existsSync5(path43.join(abs, ".ctxloom"))
     };
     if (entry.alias !== void 0) item.alias = entry.alias;
     out.push(item);
@@ -12099,7 +12106,7 @@ function buildProjectsRouter(deps) {
     } catch (err) {
       const detail = err instanceof Error ? err.message : String(err);
       res.status(500).json({
-        error: `failed to switch to ${path43.basename(target.root)}: ${detail}`
+        error: `failed to switch to ${path44.basename(target.root)}: ${detail}`
       });
     }
   });
@@ -12156,7 +12163,7 @@ function buildTelemetryRouter() {
 }
 
 // server/index.ts
-var __dirname2 = path44.dirname(fileURLToPath2(import.meta.url));
+var __dirname2 = path45.dirname(fileURLToPath2(import.meta.url));
 async function startDashboard(options) {
   const { root, port, open } = options;
   console.log(`ctxloom dashboard \u2014 loading context from ${root}...`);
@@ -12215,9 +12222,9 @@ async function startDashboard(options) {
       }
       activeWatcher = null;
     }
-    const snapshotDir = path44.join(targetRoot, ".ctxloom");
+    const snapshotDir = path45.join(targetRoot, ".ctxloom");
     try {
-      activeWatcher = fs32.watch(snapshotDir, (_event, filename) => {
+      activeWatcher = fs33.watch(snapshotDir, (_event, filename) => {
         if (!filename || !filename.includes("snapshot")) return;
         if (debounce) clearTimeout(debounce);
         debounce = setTimeout(async () => {
@@ -12246,12 +12253,12 @@ async function startDashboard(options) {
       attachSnapshotWatcher(newRoot);
     }
   }));
-  const clientDist = path44.join(__dirname2, "../dashboard/client");
-  const clientDistExists = fs32.existsSync(path44.join(clientDist, "index.html"));
+  const clientDist = path45.join(__dirname2, "../dashboard/client");
+  const clientDistExists = fs33.existsSync(path45.join(clientDist, "index.html"));
   if (clientDistExists) {
     app.use(express.static(clientDist, { dotfiles: "allow" }));
     app.get(/.*/, (_req, res) => {
-      res.sendFile(path44.join(clientDist, "index.html"), { dotfiles: "allow" });
+      res.sendFile(path45.join(clientDist, "index.html"), { dotfiles: "allow" });
     });
   } else {
     app.get(/^\/(?!api\/).*/, (_req, res) => {

package/dist/budgetStats-TURA232F.js

@@ -0,0 +1,116 @@
+// packages/core/src/utils/stats.ts
+function percentile(values, p) {
+  if (values.length === 0) return null;
+  const sorted = [...values].sort((a, b) => a - b);
+  const idx = Math.floor((sorted.length - 1) * p);
+  return sorted[idx];
+}
+
+// packages/core/src/budget/budgetStats.ts
+function summarize(events, windowStart, windowEnd) {
+  const byTool = /* @__PURE__ */ new Map();
+  for (const e of events) {
+    const existing = byTool.get(e.tool);
+    if (existing) existing.push(e);
+    else byTool.set(e.tool, [e]);
+  }
+  const fallbackTable = [];
+  const distributionTable = [];
+  for (const [tool, bucket] of byTool) {
+    const fallbackUsed = bucket.filter((e) => e.event === "mcp.fallback.used");
+    if (fallbackUsed.length > 0) {
+      let skeleton = 0, truncate = 0, error = 0;
+      for (const e of fallbackUsed) {
+        const mode = typeof e.mode === "string" ? e.mode : "";
+        if (mode === "skeleton" || mode === "skeleton+truncate") skeleton++;
+        else if (mode === "truncate" || mode === "truncate-fallback") truncate++;
+        else if (mode === "error") error++;
+      }
+      const total = skeleton + truncate + error;
+      if (total > 0) {
+        fallbackTable.push({
+          tool,
+          breaches: fallbackUsed.length,
+          skeletonPct: Math.round(skeleton / total * 100),
+          truncatePct: Math.round(truncate / total * 100),
+          errorPct: Math.round(error / total * 100)
+        });
+      }
+    }
+    const tokens = bucket.filter((e) => e.event === "mcp.budget.exceeded").map((e) => typeof e.original_tokens === "number" ? e.original_tokens : null).filter((n) => n !== null);
+    if (tokens.length > 0) {
+      distributionTable.push({
+        tool,
+        n: tokens.length,
+        min: Math.min(...tokens),
+        p50: percentile(tokens, 0.5),
+        p75: percentile(tokens, 0.75),
+        p95: percentile(tokens, 0.95),
+        max: Math.max(...tokens)
+      });
+    }
+  }
+  fallbackTable.sort((a, b) => a.tool.localeCompare(b.tool));
+  distributionTable.sort((a, b) => a.tool.localeCompare(b.tool));
+  return {
+    windowStart: windowStart.toISOString(),
+    windowEnd: windowEnd.toISOString(),
+    totalEvents: events.length,
+    fallbackTable,
+    distributionTable
+  };
+}
+function renderSummary(s) {
+  const lines = [];
+  const startDate = s.windowStart.slice(0, 10);
+  const endDate = s.windowEnd.slice(0, 10);
+  lines.push(`Budget event summary (${startDate} \u2192 ${endDate}, ${s.totalEvents} events)`);
+  lines.push("");
+  if (s.totalEvents === 0) {
+    lines.push("No events in window. Either:");
+    lines.push("  - No budget breaches occurred (everything fit under budgets)");
+    lines.push(`  - CTXLOOM_TELEMETRY_LEVEL is not set to "full" in the MCP server's env`);
+    lines.push("  - No tool calls have opted into the budget surface yet");
+    return lines.join("\n");
+  }
+  lines.push("Fallback distribution per tool");
+  lines.push("");
+  if (s.fallbackTable.length === 0) {
+    lines.push("  (no fallback events recorded in window)");
+  } else {
+    lines.push("| Tool                       | Breaches | Skeleton % | Truncate % | Error % |");
+    lines.push("|----------------------------|---------:|-----------:|-----------:|--------:|");
+    for (const r of s.fallbackTable) {
+      lines.push(
+        `| ${r.tool.padEnd(26)} | ${String(r.breaches).padStart(8)} | ${String(r.skeletonPct).padStart(9)}% | ${String(r.truncatePct).padStart(9)}% | ${String(r.errorPct).padStart(6)}% |`
+      );
+    }
+  }
+  lines.push("");
+  lines.push("Original-token distribution per tool (over-budget calls only)");
+  lines.push("");
+  if (s.distributionTable.length === 0) {
+    lines.push("  (no budget-breach events recorded in window)");
+  } else {
+    lines.push("| Tool                       |   n |    min |    p50 |    p75 |    p95 |    max |");
+    lines.push("|----------------------------|----:|-------:|-------:|-------:|-------:|-------:|");
+    for (const r of s.distributionTable) {
+      lines.push(
+        `| ${r.tool.padEnd(26)} | ${String(r.n).padStart(3)} | ${fmt(r.min)} | ${fmt(r.p50)} | ${fmt(r.p75)} | ${fmt(r.p95)} | ${fmt(r.max)} |`
+      );
+    }
+    lines.push("");
+    lines.push("The **p75** column is the input for per-tool default budget tuning");
+    lines.push("(packages/core/src/tools/*.ts \u2192 DEFAULT_MAX_RESPONSE_TOKENS).");
+  }
+  return lines.join("\n");
+}
+function fmt(n) {
+  return n === null ? "     \u2014" : String(n).padStart(6);
+}
+export {
+  percentile,
+  renderSummary,
+  summarize
+};
+//# sourceMappingURL=budgetStats-TURA232F.js.map

package/dist/chunk-5I6CJITG.js

@@ -0,0 +1,99 @@
+import {
+  logger
+} from "./chunk-TYDMSHV7.js";
+
+// packages/core/src/budget/eventCollector.ts
+import fs from "fs";
+import os from "os";
+import path from "path";
+var DEFAULT_TELEMETRY_DIR = path.join(os.homedir(), ".ctxloom", "telemetry");
+function telemetryDir() {
+  const raw = process.env.CTXLOOM_TELEMETRY_DIR ?? DEFAULT_TELEMETRY_DIR;
+  if (raw.includes("..") || !path.isAbsolute(raw)) {
+    if (!telemetryDirWarned) {
+      telemetryDirWarned = true;
+      logger.warn('CTXLOOM_TELEMETRY_DIR rejected \u2014 must be an absolute path with no ".." segments; using default', {
+        rejected: raw,
+        fallback: DEFAULT_TELEMETRY_DIR
+      });
+    }
+    return DEFAULT_TELEMETRY_DIR;
+  }
+  return path.resolve(raw);
+}
+var telemetryDirWarned = false;
+function filenameForDate(date) {
+  const y = date.getUTCFullYear();
+  const m = String(date.getUTCMonth() + 1).padStart(2, "0");
+  const d = String(date.getUTCDate()).padStart(2, "0");
+  return `budget-events-${y}-${m}-${d}.jsonl`;
+}
+function appendEvent(event, now = /* @__PURE__ */ new Date()) {
+  try {
+    const dir = telemetryDir();
+    fs.mkdirSync(dir, { recursive: true });
+    const file = path.join(dir, filenameForDate(now));
+    const persisted = { ts: now.toISOString(), ...event };
+    fs.appendFileSync(file, JSON.stringify(persisted) + "\n", "utf-8");
+  } catch (err) {
+    if (!appendFailureWarned) {
+      appendFailureWarned = true;
+      logger.warn("telemetry sink append failed (further failures suppressed)", {
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+}
+var appendFailureWarned = false;
+function __resetTelemetryWarnFlagsForTests() {
+  telemetryDirWarned = false;
+  appendFailureWarned = false;
+}
+function readEvents(opts = {}) {
+  const until = opts.until ?? /* @__PURE__ */ new Date();
+  const since = opts.since ?? new Date(until.getTime() - 14 * 24 * 60 * 60 * 1e3);
+  const dir = telemetryDir();
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  for (let cursor = new Date(Date.UTC(since.getUTCFullYear(), since.getUTCMonth(), since.getUTCDate())); cursor.getTime() <= until.getTime(); cursor = new Date(cursor.getTime() + 24 * 60 * 60 * 1e3)) {
+    const file = path.join(dir, filenameForDate(cursor));
+    if (!fs.existsSync(file)) continue;
+    const text = fs.readFileSync(file, "utf-8");
+    for (const line of text.split("\n")) {
+      if (line.trim() === "") continue;
+      let parsed;
+      try {
+        parsed = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (!isPersistedEvent(parsed)) continue;
+      const eventTs = new Date(parsed.ts).getTime();
+      if (!Number.isFinite(eventTs)) continue;
+      if (eventTs < since.getTime() || eventTs > until.getTime()) continue;
+      if (opts.tool && parsed.tool !== opts.tool) continue;
+      out.push(parsed);
+    }
+  }
+  return out;
+}
+function isPersistedEvent(v) {
+  if (!v || typeof v !== "object") return false;
+  const o = v;
+  return typeof o.ts === "string" && typeof o.event === "string" && typeof o.tool === "string";
+}
+var diskSink = {
+  append(event) {
+    appendEvent(event);
+  }
+};
+
+export {
+  telemetryDir,
+  filenameForDate,
+  appendEvent,
+  __resetTelemetryWarnFlagsForTests,
+  readEvents,
+  diskSink
+};
+//# sourceMappingURL=chunk-5I6CJITG.js.map

package/dist/{chunk-RY3JAC2Q.js → chunk-TIYTPWYN.js}

@@ -5,6 +5,9 @@ import {
   collectFiles,
   generateEmbedding
 } from "./chunk-UVR65QBJ.js";
+import {
+  diskSink
+} from "./chunk-5I6CJITG.js";
 import {
   logger
 } from "./chunk-TYDMSHV7.js";
@@ -4634,13 +4637,18 @@ function readBudgetArgs(args) {
 function isBudgetDisabled() {
   return process.env.CTXLOOM_DISABLE_BUDGET === "1";
 }
-function emitTelemetry(event) {
+function emitTelemetry(event, sink = diskSink) {
   if (process.env.CTXLOOM_TELEMETRY_LEVEL !== "full") return;
   logger.info(event.event, event);
+  try {
+    sink.append(event);
+  } catch {
+  }
 }
 async function enforceBudget(opts) {
   const { full, args, toolName, defaultMaxTokens, skeletonProducer } = opts;
   const estimate = opts.estimator ?? defaultTokenEstimator;
+  const sink = opts.sink ?? opts.ctx?.telemetrySink ?? diskSink;
   const originalTokens = estimate(full);
   if (isBudgetDisabled()) {
     return {
@@ -4706,7 +4714,7 @@ async function enforceBudget(opts) {
     original_tokens: originalTokens,
     budget,
     ratio: originalTokens / budget
-  });
+  }, sink);
   const mode = args.on_budget_exceeded ?? "skeleton";
   if (mode === "error") {
     const err = new Error(
@@ -4725,7 +4733,7 @@ async function enforceBudget(opts) {
       tool: toolName,
       fallback_reason: "budget_exceeded",
       mode: "truncate"
-    });
+    }, sink);
     return {
       text: sliced2,
       meta: {
@@ -4745,7 +4753,7 @@ async function enforceBudget(opts) {
         tool: toolName,
         fallback_reason: "budget_exceeded",
         mode: "skeleton"
-      });
+      }, sink);
       return {
         text: skeleton,
         meta: {
@@ -4762,7 +4770,7 @@ async function enforceBudget(opts) {
       tool: toolName,
       fallback_reason: "budget_exceeded",
       mode: "skeleton+truncate"
-    });
+    }, sink);
     return {
       text: slicedSk,
       meta: {
@@ -4779,7 +4787,7 @@ async function enforceBudget(opts) {
     tool: toolName,
     fallback_reason: "skeleton_failed",
     mode: "truncate-fallback"
-  });
+  }, sink);
   return {
     text: sliced,
     meta: {
@@ -4887,6 +4895,7 @@ function registerSearchTool(registry, ctx) {
       if (!hasBudgetArgs(args)) return full;
       const skeletonProducer = async () => renderResults(parsed.query, ranked, false);
       const result = await enforceBudget({
+        ctx,
         full,
         args: readBudgetArgs(args),
         toolName: "ctx_search",
@@ -4946,6 +4955,7 @@ function registerFileTool(registry, ctx) {
       const absPath = validator.validate(parsed.path);
       const skeletonizer = await ctx.getSkeletonizer(parsed.project_root);
       const result = await enforceBudget({
+        ctx,
         full,
         args: readBudgetArgs(args),
         toolName: "ctx_get_file",
@@ -5054,6 +5064,7 @@ ${sk}`;
         return renderPacket({ ...parts, primaryContent: primarySkeleton });
       };
       const result = await enforceBudget({
+        ctx,
         full,
         args: readBudgetArgs(args),
         toolName: "ctx_get_context_packet",
@@ -5217,6 +5228,7 @@ function registerDefinitionTool(registry, ctx) {
       }
       if (!hasBudgetArgs(args)) return full;
       const result = await enforceBudget({
+        ctx,
         full,
         args: readBudgetArgs(args),
         toolName: "ctx_get_definition",
@@ -6258,6 +6270,7 @@ function registerWikiGenerateTool(registry, ctx) {
       const full = detail_level === "minimal" ? renderMinimal() : renderStandard();
       if (!hasBudgetArgs(args)) return full;
       const budgetResult = await enforceBudget({
+        ctx,
         full,
         args: readBudgetArgs(args),
         toolName: "ctx_wiki_generate",
@@ -6405,6 +6418,7 @@ function registerGitDiffReviewTool(registry, ctx) {
       const maybeBudget = async (full2, skeletonProducer) => {
         if (!hasBudgetArgs(args)) return full2;
         const result = await enforceBudget({
+          ctx,
           full: full2,
           args: readBudgetArgs(args),
           toolName: "ctx_git_diff_review",
@@ -6622,6 +6636,7 @@ function registerRefactorPreviewTool(registry, ctx) {
       const full = render(true);
       if (!hasBudgetArgs(args)) return full;
       const result = await enforceBudget({
+        ctx,
         full,
         args: readBudgetArgs(args),
         toolName: "ctx_refactor_preview",
@@ -6743,6 +6758,7 @@ function registerExecutionFlowTool(registry, ctx) {
       const maybeBudget = async (full) => {
         if (!hasBudgetArgs(args)) return full;
         const result = await enforceBudget({
+          ctx,
           full,
           args: readBudgetArgs(args),
           toolName: "ctx_execution_flow",
@@ -6899,7 +6915,7 @@ var Schema20 = z22.object({
 function escapeXML19(text) {
   return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
-function registerCrossRepoSearchTool(registry, _ctx, registryFilePath) {
+function registerCrossRepoSearchTool(registry, ctx, registryFilePath) {
   const repoRegistryPath = registryFilePath ?? path18.join(process.env.HOME ?? process.env.USERPROFILE ?? "", ".ctxloom", "repos.json");
   registry.register(
     "ctx_cross_repo_search",
@@ -7007,6 +7023,7 @@ function registerCrossRepoSearchTool(registry, _ctx, registryFilePath) {
       const full = render(true);
       if (!hasBudgetArgs(args)) return full;
       const result = await enforceBudget({
+        ctx,
         full,
         args: readBudgetArgs(args),
         toolName: "ctx_cross_repo_search",
@@ -7116,6 +7133,7 @@ function registerApplyRefactorTool(registry, ctx) {
       const full = xml.join("\n");
       if (!hasBudgetArgs(args)) return full;
       const result = await enforceBudget({
+        ctx,
         full,
         args: readBudgetArgs(args),
         toolName: "ctx_apply_refactor",
@@ -7333,6 +7351,7 @@ function registerFullTextSearchTool(registry, ctx) {
       const maybeBudget = async (full, skeletonProducer) => {
         if (!hasBudgetArgs(args)) return full;
         const result = await enforceBudget({
+          ctx,
           full,
           args: readBudgetArgs(args),
           toolName: "ctx_full_text_search",
@@ -7897,6 +7916,7 @@ function registerFindLargeFunctionsTool(registry, ctx) {
       }
       if (!hasBudgetArgs(args)) return full;
       const result = await enforceBudget({
+        ctx,
         full,
         args: readBudgetArgs(args),
         toolName: "ctx_find_large_functions",
@@ -9342,7 +9362,7 @@ var TELEMETRY_DISABLED = TELEMETRY_LEVEL === "off";
 function getTelemetryLevel() {
   return TELEMETRY_LEVEL;
 }
-var CTXLOOM_VERSION = "1.2.7".length > 0 ? "1.2.7" : "dev";
+var CTXLOOM_VERSION = "1.3.1".length > 0 ? "1.3.1" : "dev";
 var POSTHOG_HOST = "https://eu.i.posthog.com";
 var POSTHOG_KEY = process.env["POSTHOG_API_KEY"] ?? (true ? "phc_CiDkmFLcZ2K6uCpcoSUQLmFrnnUvsyXGhSxopX5TVKE6" : "");
 var SENTRY_DSN = process.env["SENTRY_DSN"] ?? (true ? "https://81c94a0f04a8e242dee493ac1e17f733@o4508531702497280.ingest.de.sentry.io/4511256875368528" : "");
@@ -10072,4 +10092,4 @@ export {
   FirstTouchTracker,
   EmittedOnceTracker
 };
-//# sourceMappingURL=chunk-RY3JAC2Q.js.map
+//# sourceMappingURL=chunk-TIYTPWYN.js.map

package/dist/eventCollector-QSRBVUDF.js

@@ -0,0 +1,18 @@
+import {
+  __resetTelemetryWarnFlagsForTests,
+  appendEvent,
+  diskSink,
+  filenameForDate,
+  readEvents,
+  telemetryDir
+} from "./chunk-5I6CJITG.js";
+import "./chunk-TYDMSHV7.js";
+export {
+  __resetTelemetryWarnFlagsForTests,
+  appendEvent,
+  diskSink,
+  filenameForDate,
+  readEvents,
+  telemetryDir
+};
+//# sourceMappingURL=eventCollector-QSRBVUDF.js.map

package/dist/index.js

@@ -49,7 +49,7 @@ import {
   validateDefaultRoot,
   wrapWithIndexingEnvelope,
   writeCODEOWNERS
-} from "./chunk-RY3JAC2Q.js";
+} from "./chunk-TIYTPWYN.js";
 import {
   VectorStore
 } from "./chunk-DVI2RWJR.js";
@@ -57,6 +57,7 @@ import {
   generateEmbedding,
   indexDirectory
 } from "./chunk-UVR65QBJ.js";
+import "./chunk-5I6CJITG.js";
 import {
   logger
 } from "./chunk-TYDMSHV7.js";
@@ -1018,7 +1019,7 @@ try {
 } catch {
 }
 var args = process.argv.slice(2);
-var ctxloomVersion = "1.2.7".length > 0 ? "1.2.7" : "dev";
+var ctxloomVersion = "1.3.1".length > 0 ? "1.3.1" : "dev";
 if (args.includes("--version") || args.includes("-v")) {
   process.stdout.write(`ctxloom ${ctxloomVersion}
 `);
@@ -1086,12 +1087,12 @@ function buildActivityFromOverlay(store) {
     lastCommitTimestamp
   }));
 }
-var LICENSE_GATE_BYPASS_COMMANDS = /* @__PURE__ */ new Set(["trial", "activate", "deactivate", "status", "--help"]);
+var LICENSE_GATE_BYPASS_COMMANDS = /* @__PURE__ */ new Set(["trial", "activate", "deactivate", "status", "budget-stats", "--help"]);
 async function checkLicense() {
   if (command !== void 0 && LICENSE_GATE_BYPASS_COMMANDS.has(command)) return;
   const ciKey = process.env["CTXLOOM_LICENSE_KEY"];
   if (ciKey) {
-    const { ApiClient } = await import("./src-3ZB6BHFW.js");
+    const { ApiClient } = await import("./src-KTFHRVTO.js");
     const client = new ApiClient(process.env["CTXLOOM_API_BASE"]);
     try {
       const result = await client.validate(ciKey, "ci-ephemeral");
@@ -1496,7 +1497,7 @@ async function main() {
         process.exit(1);
       }
       if (alias !== void 0) {
-        const { validateAlias } = await import("./src-3ZB6BHFW.js");
+        const { validateAlias } = await import("./src-KTFHRVTO.js");
         const v = validateAlias(alias);
         if (!v.ok) {
           console.error(`[ctxloom] Invalid alias: ${v.reason}`);
@@ -1569,6 +1570,23 @@ async function main() {
       }
       break;
     }
+    case "budget-stats": {
+      const windowArg = args.find((a) => a.startsWith("--window="))?.split("=")[1] ?? "14d";
+      const toolArg = args.find((a) => a.startsWith("--tool="))?.split("=")[1];
+      const days = parseInt(windowArg.replace(/d$/, ""), 10);
+      if (!Number.isFinite(days) || days <= 0) {
+        console.error(`[ctxloom] Invalid --window=${windowArg} \u2014 expected an integer day count like 14d`);
+        process.exit(1);
+      }
+      const until = /* @__PURE__ */ new Date();
+      const since = new Date(until.getTime() - days * 24 * 60 * 60 * 1e3);
+      const { readEvents } = await import("./eventCollector-QSRBVUDF.js");
+      const { summarize, renderSummary } = await import("./budgetStats-TURA232F.js");
+      const events = readEvents({ since, until, tool: toolArg });
+      const summary = summarize(events, since, until);
+      console.log(renderSummary(summary));
+      break;
+    }
     case "dashboard": {
       const port = Number(
         args.find((a) => a.startsWith("--port="))?.split("=")[1] ?? "7842"
@@ -1743,7 +1761,7 @@ Suggested reviewers for ${files.length} file(s):`);
         process.stderr.write("[ctxloom] --limit must be a non-negative integer (0 for unlimited)\n");
         process.exit(2);
       }
-      const { loadRulesConfig, RulesChecker, formatText, formatJson, RulesConfigError } = await import("./src-3ZB6BHFW.js");
+      const { loadRulesConfig, RulesChecker, formatText, formatJson, RulesConfigError } = await import("./src-KTFHRVTO.js");
       let config;
       try {
         config = await loadRulesConfig(root);
@@ -1767,7 +1785,7 @@ Suggested reviewers for ${files.length} file(s):`);
       }
       let graph;
       if (useSnapshot) {
-        const { DependencyGraph: DG } = await import("./src-3ZB6BHFW.js");
+        const { DependencyGraph: DG } = await import("./src-KTFHRVTO.js");
         graph = new DG();
         const loaded = await graph.loadSnapshotOnly(root);
         if (!loaded) {
@@ -1776,7 +1794,7 @@ Suggested reviewers for ${files.length} file(s):`);
         }
       } else {
         process.stderr.write("[ctxloom] Building dependency graph...\n");
-        const { ASTParser: ASTParser2, DependencyGraph: DependencyGraph2 } = await import("./src-3ZB6BHFW.js");
+        const { ASTParser: ASTParser2, DependencyGraph: DependencyGraph2 } = await import("./src-KTFHRVTO.js");
         let parser;
         try {
           parser = new ASTParser2();
@@ -1828,6 +1846,9 @@ Usage:
   ctxloom dashboard            Start the web dashboard (port 7842)
   ctxloom dashboard --port=N   Start on custom port
   ctxloom dashboard --open     Open browser automatically
+  ctxloom budget-stats         Aggregate Phase B budget events (per-tool p50/p75/p95)
+  ctxloom budget-stats --window=Nd      Lookback window in days (default: 14)
+  ctxloom budget-stats --tool=NAME      Restrict to one tool
   ctxloom review-suggest [files]   Suggest reviewers from ownership index
   ctxloom authors-sync             Map git emails to GitHub handles (needs GITHUB_TOKEN)
   ctxloom rules check              Check architecture rules (.ctxloom/rules.yml)

package/dist/{src-3ZB6BHFW.js → src-KTFHRVTO.js}

@@ -103,7 +103,7 @@ import {
   validateDefaultRoot,
   wrapWithIndexingEnvelope,
   writeCODEOWNERS
-} from "./chunk-RY3JAC2Q.js";
+} from "./chunk-TIYTPWYN.js";
 import {
   VectorStore
 } from "./chunk-DVI2RWJR.js";
@@ -113,6 +113,7 @@ import {
   generateEmbedding,
   indexDirectory
 } from "./chunk-UVR65QBJ.js";
+import "./chunk-5I6CJITG.js";
 import {
   logger
 } from "./chunk-TYDMSHV7.js";
@@ -228,4 +229,4 @@ export {
   wrapWithIndexingEnvelope,
   writeCODEOWNERS
 };
-//# sourceMappingURL=src-3ZB6BHFW.js.map
+//# sourceMappingURL=src-KTFHRVTO.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ctxloom-pro",
-  "version": "1.2.7",
+  "version": "1.3.1",
   "description": "ctxloom — The Universal Code Context Engine. A local-first MCP server providing intelligent code context via hybrid Vector + AST + Graph search with Skeletonization (92% token reduction).",
   "type": "module",
   "main": "dist/index.js",