@nxuss/lemma 1.10.0 → 1.12.0

package/dist/cjs/utils/ReadWorkspaceCache.js

@@ -8,6 +8,7 @@ exports.getLastEmitted = getLastEmitted;
 exports.recordSent = recordSent;
 exports.resetReadCache = resetReadCache;
 const crypto_1 = __importDefault(require("crypto"));
+const SharedLedgerStore_1 = require("./SharedLedgerStore");
 // Session-scoped (lives for the MCP server process lifetime, which is normally the
 // whole conversation). Tracks the content hash we last actually sent back to the
 // model for a given (filePath, view) pair, so a second identical read doesn't
@@ -42,11 +43,24 @@ function cacheKey(resolvedPath, view) {
     ];
     return parts.join("::");
 }
+function getSharedRead(resolvedPath, view) {
+    const raw = (0, SharedLedgerStore_1.getSharedEntry)(process.cwd(), "read-cache", cacheKey(resolvedPath, view));
+    if (!raw)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
 /** Check whether this exact (path, view) content was already sent this session. */
 function checkAlreadySent(resolvedPath, view, rawContent) {
     const hash = sha256(rawContent);
     const key = cacheKey(resolvedPath, view);
-    const unchanged = lastSent.get(key) === hash;
+    // In-process history wins; a sibling fork's shared entry only counts when this process
+    // has never seen the key itself — same "opt-in, scoped, fail-open" contract as OutputLedger.
+    const unchanged = lastSent.has(key) ? lastSent.get(key) === hash : getSharedRead(resolvedPath, view)?.hash === hash;
     return { unchanged, hash };
 }
 /**
@@ -55,12 +69,21 @@ function checkAlreadySent(resolvedPath, view, rawContent) {
  * "send the full file", never "assume it is unchanged".
  */
 function getLastEmitted(resolvedPath, view) {
-    return lastEmitted.get(cacheKey(resolvedPath, view)) ?? null;
+    const key = cacheKey(resolvedPath, view);
+    const local = lastEmitted.get(key);
+    if (local !== undefined)
+        return local;
+    return getSharedRead(resolvedPath, view)?.emitted ?? null;
 }
 /** Record that this content was just sent, so future identical reads short-circuit. */
 function recordSent(resolvedPath, view, hash, emitted) {
     const key = cacheKey(resolvedPath, view);
     lastSent.set(key, hash);
+    // Mirrors the local size cap: an oversized entry is skipped locally too, so keeping it
+    // out of the shared file avoids bloating something every sibling process reads on every hit.
+    if (emitted === undefined || emitted.length <= MAX_ENTRY_CHARS) {
+        (0, SharedLedgerStore_1.setSharedEntry)(process.cwd(), "read-cache", key, JSON.stringify({ hash, emitted }));
+    }
     if (emitted === undefined)
         return;
     const previous = lastEmitted.get(key);

package/dist/cjs/utils/ReadWorkspaceCache.js.map

@@ -1 +1 @@
-{"version":3,"file":"ReadWorkspaceCache.js","sourceRoot":"","sources":["../../../src/utils/ReadWorkspaceCache.ts"],"names":[],"mappings":";;;;;AA6DA,4CAKC;AAOD,wCAEC;AAGD,gCAiCC;AAGD,wCAIC;AAtHD,oDAA4B;AAE5B,mFAAmF;AACnF,iFAAiF;AACjF,8EAA8E;AAC9E,2DAA2D;AAC3D,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,WAAW,GAAG,IAAI,GAAG,EAAkB,CAAC;AAE9C;;;;GAIG;AACH,MAAM,iBAAiB,GAAG,OAAS,CAAC;AAEpC,mGAAmG;AACnG,MAAM,eAAe,GAAG,MAAO,CAAC;AAEhC,IAAI,YAAY,GAAG,CAAC,CAAC;AAErB,SAAS,MAAM,CAAC,OAAe;IAC7B,OAAO,gBAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACnE,CAAC;AAcD,SAAS,QAAQ,CAAC,YAAoB,EAAE,IAAc;IACpD,MAAM,KAAK,GAAG;QACZ,YAAY;QACZ,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI;QAC1B,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI;QAC9B,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,GAAG;QACrC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG;KACpC,CAAC;IACF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAOD,mFAAmF;AACnF,SAAgB,gBAAgB,CAAC,YAAoB,EAAE,IAAc,EAAE,UAAkB;IACvF,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;IAChC,MAAM,GAAG,GAAG,QAAQ,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;IACzC,MAAM,SAAS,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC;IAC7C,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;AAC7B,CAAC;AAED;;;;GAIG;AACH,SAAgB,cAAc,CAAC,YAAoB,EAAE,IAAc;IACjE,OAAO,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC;AAC/D,CAAC;AAED,uFAAuF;AACvF,SAAgB,UAAU,CAAC,YAAoB,EAAE,IAAc,EAAE,IAAY,EAAE,OAAgB;IAC7F,MAAM,GAAG,GAAG,QAAQ,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;IACzC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAExB,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO;IAElC,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACtC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,YAAY,IAAI,QAAQ,CAAC,MAAM,CAAC;QAChC,qFAAqF;QACrF,gFAAgF;QAChF,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,GAAG,eAAe,EAAE,CAAC;QACrC,sFAAsF;QACtF,gCAAgC;QAChC,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACxB,OAAO;IACT,CAAC;IAED,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAC9B,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;IAE/B,oFAAoF;IACpF,2FAA2F;IAC3F,OAAO,YAAY,GAAG,iBAAiB,EAAE,CAAC;QACxC,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC;QACzC,IAAI,MAAM,CAAC,IAAI;YAAE,MAAM;QACvB,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAE,CAAC;QAC/C,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACjC,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;IACjC,CAAC;AACH,CAAC;AAED,2FAA2F;AAC3F,SAAgB,cAAc;IAC5B,QAAQ,CAAC,KAAK,EAAE,CAAC;IACjB,WAAW,CAAC,KAAK,EAAE,CAAC;IACpB,YAAY,GAAG,CAAC,CAAC;AACnB,CAAC"}
+{"version":3,"file":"ReadWorkspaceCache.js","sourceRoot":"","sources":["../../../src/utils/ReadWorkspaceCache.ts"],"names":[],"mappings":";;;;;AA6EA,4CAOC;AAOD,wCAKC;AAGD,gCAsCC;AAGD,wCAIC;AAhJD,oDAA4B;AAC5B,2DAAqE;AAErE,mFAAmF;AACnF,iFAAiF;AACjF,8EAA8E;AAC9E,2DAA2D;AAC3D,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,WAAW,GAAG,IAAI,GAAG,EAAkB,CAAC;AAE9C;;;;GAIG;AACH,MAAM,iBAAiB,GAAG,OAAS,CAAC;AAEpC,mGAAmG;AACnG,MAAM,eAAe,GAAG,MAAO,CAAC;AAEhC,IAAI,YAAY,GAAG,CAAC,CAAC;AAErB,SAAS,MAAM,CAAC,OAAe;IAC7B,OAAO,gBAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACnE,CAAC;AAcD,SAAS,QAAQ,CAAC,YAAoB,EAAE,IAAc;IACpD,MAAM,KAAK,GAAG;QACZ,YAAY;QACZ,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI;QAC1B,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI;QAC9B,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,GAAG;QACrC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG;KACpC,CAAC;IACF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAYD,SAAS,aAAa,CAAC,YAAoB,EAAE,IAAc;IACzD,MAAM,GAAG,GAAG,IAAA,kCAAc,EAAC,OAAO,CAAC,GAAG,EAAE,EAAE,YAAY,EAAE,QAAQ,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC,CAAC;IACtF,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IACtB,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAoB,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,mFAAmF;AACnF,SAAgB,gBAAgB,CAAC,YAAoB,EAAE,IAAc,EAAE,UAAkB;IACvF,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;IAChC,MAAM,GAAG,GAAG,QAAQ,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;IACzC,uFAAuF;IACvF,6FAA6F;IAC7F,MAAM,SAAS,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,aAAa,CAAC,YAAY,EAAE,IAAI,CAAC,EAAE,IAAI,KAAK,IAAI,CAAC;IACpH,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;AAC7B,CAAC;AAED;;;;GAIG;AACH,SAAgB,cAAc,CAAC,YAAoB,EAAE,IAAc;IACjE,MAAM,GAAG,GAAG,QAAQ,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;IACzC,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACnC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACtC,OAAO,aAAa,CAAC,YAAY,EAAE,IAAI,CAAC,EAAE,OAAO,IAAI,IAAI,CAAC;AAC5D,CAAC;AAED,uFAAuF;AACvF,SAAgB,UAAU,CAAC,YAAoB,EAAE,IAAc,EAAE,IAAY,EAAE,OAAgB;IAC7F,MAAM,GAAG,GAAG,QAAQ,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;IACzC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACxB,uFAAuF;IACvF,6FAA6F;IAC7F,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,MAAM,IAAI,eAAe,EAAE,CAAC;QAC/D,IAAA,kCAAc,EAAC,OAAO,CAAC,GAAG,EAAE,EAAE,YAAY,EAAE,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;IACtF,CAAC;IAED,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO;IAElC,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACtC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,YAAY,IAAI,QAAQ,CAAC,MAAM,CAAC;QAChC,qFAAqF;QACrF,gFAAgF;QAChF,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,GAAG,eAAe,EAAE,CAAC;QACrC,sFAAsF;QACtF,gCAAgC;QAChC,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACxB,OAAO;IACT,CAAC;IAED,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAC9B,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;IAE/B,oFAAoF;IACpF,2FAA2F;IAC3F,OAAO,YAAY,GAAG,iBAAiB,EAAE,CAAC;QACxC,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC;QACzC,IAAI,MAAM,CAAC,IAAI;YAAE,MAAM;QACvB,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAE,CAAC;QAC/C,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACjC,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;IACjC,CAAC;AACH,CAAC;AAED,2FAA2F;AAC3F,SAAgB,cAAc;IAC5B,QAAQ,CAAC,KAAK,EAAE,CAAC;IACjB,WAAW,CAAC,KAAK,EAAE,CAAC;IACpB,YAAY,GAAG,CAAC,CAAC;AACnB,CAAC"}

package/dist/cjs/utils/RoiLedger.d.ts

@@ -0,0 +1,31 @@
+/**
+ * RoiLedger — per-(repo, tool) net token history, persisted across sessions.
+ *
+ * `SavingsLedger` already tracks saved/spent totals, but only by *source* (cache,
+ * contextSqueeze, ...) and only in `~/.lemma-cache/ledger.json` — one file, no notion of
+ * which repo or which specific tool earned its keep. That is not enough to answer "does
+ * `affected_tests` pay for its schema in THIS repo", which is what `tool-profiles.ts` needs
+ * to auto-tune the advertised surface instead of relying purely on the hand-curated
+ * `CORE_TOOL_NAMES` list.
+ *
+ * Scope: one small JSON file per repo, keyed by a hash of the repo path, holding cumulative
+ * (calls, tokensSaved, tokensSpent) per tool name. Fail-open throughout — a lookup or write
+ * that errors must never break the caller; it just means no history this time.
+ *
+ * Hard rule inherited from `tool-profiles.ts`: the tool surface resolves once at startup and
+ * never mutates mid-session. This ledger is written continuously, but only ever *read* by
+ * `resolveToolSurface` once, at process start — so a promotion always reflects PRIOR
+ * sessions, never the one currently running.
+ */
+export interface ToolRoiStats {
+    calls: number;
+    tokensSaved: number;
+    tokensSpent: number;
+}
+export declare function recordRoiSaved(repoRoot: string, tool: string, tokensSaved: number): void;
+export declare function recordRoiSpent(repoRoot: string, tool: string, tokensSpent: number): void;
+/** All per-tool history for this repo, or an empty map if none exists yet or the read fails. */
+export declare function getRoiStats(repoRoot: string): Record<string, ToolRoiStats>;
+/** Test seam only — production code should never need to wipe another repo's history. */
+export declare function resetRoiLedger(repoRoot: string): void;
+//# sourceMappingURL=RoiLedger.d.ts.map

package/dist/cjs/utils/RoiLedger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RoiLedger.d.ts","sourceRoot":"","sources":["../../../src/utils/RoiLedger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AA8DD,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAExF;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAExF;AAED,gGAAgG;AAChG,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAM1E;AAED,yFAAyF;AACzF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAMrD"}

package/dist/cjs/utils/RoiLedger.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * RoiLedger — per-(repo, tool) net token history, persisted across sessions.
+ *
+ * `SavingsLedger` already tracks saved/spent totals, but only by *source* (cache,
+ * contextSqueeze, ...) and only in `~/.lemma-cache/ledger.json` — one file, no notion of
+ * which repo or which specific tool earned its keep. That is not enough to answer "does
+ * `affected_tests` pay for its schema in THIS repo", which is what `tool-profiles.ts` needs
+ * to auto-tune the advertised surface instead of relying purely on the hand-curated
+ * `CORE_TOOL_NAMES` list.
+ *
+ * Scope: one small JSON file per repo, keyed by a hash of the repo path, holding cumulative
+ * (calls, tokensSaved, tokensSpent) per tool name. Fail-open throughout — a lookup or write
+ * that errors must never break the caller; it just means no history this time.
+ *
+ * Hard rule inherited from `tool-profiles.ts`: the tool surface resolves once at startup and
+ * never mutates mid-session. This ledger is written continuously, but only ever *read* by
+ * `resolveToolSurface` once, at process start — so a promotion always reflects PRIOR
+ * sessions, never the one currently running.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordRoiSaved = recordRoiSaved;
+exports.recordRoiSpent = recordRoiSpent;
+exports.getRoiStats = getRoiStats;
+exports.resetRoiLedger = resetRoiLedger;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = __importDefault(require("crypto"));
+const HOME = process.env.HOME || process.env.USERPROFILE || "~";
+const ROI_DIR = path_1.default.join(HOME, ".lemma-cache", "roi");
+function repoHash(repoRoot) {
+    return crypto_1.default.createHash("sha256").update(path_1.default.resolve(repoRoot)).digest("hex").slice(0, 16);
+}
+function roiFilePath(repoRoot) {
+    return path_1.default.join(ROI_DIR, `${repoHash(repoRoot)}.json`);
+}
+function emptyStats() {
+    return { calls: 0, tokensSaved: 0, tokensSpent: 0 };
+}
+function load(repoRoot) {
+    try {
+        const p = roiFilePath(repoRoot);
+        if (fs_1.default.existsSync(p)) {
+            const parsed = JSON.parse(fs_1.default.readFileSync(p, "utf8"));
+            if (parsed && typeof parsed === "object" && parsed.tools)
+                return parsed;
+        }
+    }
+    catch {
+        // Corrupt or unreadable file must never break the caller — start clean for this write.
+    }
+    return { tools: {}, updatedAt: Date.now() };
+}
+function save(repoRoot, data) {
+    try {
+        if (!fs_1.default.existsSync(ROI_DIR))
+            fs_1.default.mkdirSync(ROI_DIR, { recursive: true });
+        data.updatedAt = Date.now();
+        fs_1.default.writeFileSync(roiFilePath(repoRoot), JSON.stringify(data, null, 2), "utf8");
+    }
+    catch {
+        // Non-critical: losing one write just means the next read sees slightly stale history.
+    }
+}
+function bump(repoRoot, tool, field, amount) {
+    if (!tool || !(amount > 0))
+        return;
+    try {
+        const data = load(repoRoot);
+        const stats = data.tools[tool] || emptyStats();
+        if (field === "tokensSaved")
+            stats.tokensSaved += amount;
+        else
+            stats.tokensSpent += amount;
+        // `calls` counts either kind of event once — it is "how many times this tool did
+        // something billable", not a sum of both fields.
+        stats.calls += 1;
+        data.tools[tool] = stats;
+        save(repoRoot, data);
+    }
+    catch {
+        // Fail-open: ROI bookkeeping must never be why a tool call fails.
+    }
+}
+function recordRoiSaved(repoRoot, tool, tokensSaved) {
+    bump(repoRoot, tool, "tokensSaved", tokensSaved);
+}
+function recordRoiSpent(repoRoot, tool, tokensSpent) {
+    bump(repoRoot, tool, "tokensSpent", tokensSpent);
+}
+/** All per-tool history for this repo, or an empty map if none exists yet or the read fails. */
+function getRoiStats(repoRoot) {
+    try {
+        return load(repoRoot).tools;
+    }
+    catch {
+        return {};
+    }
+}
+/** Test seam only — production code should never need to wipe another repo's history. */
+function resetRoiLedger(repoRoot) {
+    try {
+        if (fs_1.default.existsSync(roiFilePath(repoRoot)))
+            fs_1.default.unlinkSync(roiFilePath(repoRoot));
+    }
+    catch {
+        // ignore
+    }
+}
+//# sourceMappingURL=RoiLedger.js.map

package/dist/cjs/utils/RoiLedger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RoiLedger.js","sourceRoot":"","sources":["../../../src/utils/RoiLedger.ts"],"names":[],"mappings":"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"}

package/dist/cjs/utils/SharedLedgerStore.d.ts

@@ -0,0 +1,26 @@
+/**
+ * SharedLedgerStore — file-backed cross-process backing for `OutputLedger` and
+ * `ReadWorkspaceCache`, so subagents that genuinely share a conversation (a `fork`, which
+ * inherits the parent's full context) don't independently re-read the same files or re-run
+ * the same commands the parent already put in that shared context.
+ *
+ * OFF BY DEFAULT — opt in with `LEMMA_SHARED_LEDGER=1` (or `mcp.sharedLedger: true` in
+ * lemma.config.json) AND a `LEMMA_AGENT_TREE_ID` env var identifying the fork tree. Both are
+ * required on purpose:
+ *
+ * - Without a tree id, every process on the machine would share one ledger, and a plain
+ *   fresh subagent (no inherited context) would get told a file is "UNCHANGED" or a command
+ *   "IDENTICAL" for content it never actually received — suppressing content the model
+ *   never saw, which is the one thing these caches must never do.
+ * - The tree id scopes sharing to processes an orchestrator has explicitly declared share a
+ *   context (i.e. `fork` subagents of the same parent), which is the only case where "another
+ *   process already has this" is actually true for THIS process too.
+ *
+ * TTL is short (30 min): a fork tree is a single task, not a persistent cache.
+ */
+export declare function isSharedLedgerEnabled(cwd?: string): boolean;
+/** Get a shared value for `key` (namespaced), or null if disabled, missing, or expired. */
+export declare function getSharedEntry(cwd: string, namespace: "output-ledger" | "read-cache", key: string): string | null;
+/** Record a value under `key` (namespaced) for other trees-scoped processes to read. */
+export declare function setSharedEntry(cwd: string, namespace: "output-ledger" | "read-cache", key: string, value: string): void;
+//# sourceMappingURL=SharedLedgerStore.d.ts.map

package/dist/cjs/utils/SharedLedgerStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SharedLedgerStore.d.ts","sourceRoot":"","sources":["../../../src/utils/SharedLedgerStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AASH,wBAAgB,qBAAqB,CAAC,GAAG,GAAE,MAAsB,GAAG,OAAO,CAa1E;AAgDD,2FAA2F;AAC3F,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,eAAe,GAAG,YAAY,EACzC,GAAG,EAAE,MAAM,GACV,MAAM,GAAG,IAAI,CAWf;AAED,wFAAwF;AACxF,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,eAAe,GAAG,YAAY,EACzC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,GACZ,IAAI,CAcN"}

package/dist/cjs/utils/SharedLedgerStore.js

@@ -0,0 +1,130 @@
+"use strict";
+/**
+ * SharedLedgerStore — file-backed cross-process backing for `OutputLedger` and
+ * `ReadWorkspaceCache`, so subagents that genuinely share a conversation (a `fork`, which
+ * inherits the parent's full context) don't independently re-read the same files or re-run
+ * the same commands the parent already put in that shared context.
+ *
+ * OFF BY DEFAULT — opt in with `LEMMA_SHARED_LEDGER=1` (or `mcp.sharedLedger: true` in
+ * lemma.config.json) AND a `LEMMA_AGENT_TREE_ID` env var identifying the fork tree. Both are
+ * required on purpose:
+ *
+ * - Without a tree id, every process on the machine would share one ledger, and a plain
+ *   fresh subagent (no inherited context) would get told a file is "UNCHANGED" or a command
+ *   "IDENTICAL" for content it never actually received — suppressing content the model
+ *   never saw, which is the one thing these caches must never do.
+ * - The tree id scopes sharing to processes an orchestrator has explicitly declared share a
+ *   context (i.e. `fork` subagents of the same parent), which is the only case where "another
+ *   process already has this" is actually true for THIS process too.
+ *
+ * TTL is short (30 min): a fork tree is a single task, not a persistent cache.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSharedLedgerEnabled = isSharedLedgerEnabled;
+exports.getSharedEntry = getSharedEntry;
+exports.setSharedEntry = setSharedEntry;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = __importDefault(require("crypto"));
+const HOME = process.env.HOME || process.env.USERPROFILE || "~";
+const TTL_MS = 30 * 60 * 1000;
+function isSharedLedgerEnabled(cwd = process.cwd()) {
+    if (!process.env.LEMMA_AGENT_TREE_ID)
+        return false;
+    if (process.env.LEMMA_SHARED_LEDGER === "1")
+        return true;
+    try {
+        const configPath = path_1.default.join(cwd, "lemma.config.json");
+        if (fs_1.default.existsSync(configPath)) {
+            const config = JSON.parse(fs_1.default.readFileSync(configPath, "utf8"));
+            return config?.mcp?.sharedLedger === true;
+        }
+    }
+    catch {
+        // Config errors must never silently turn ON cross-process sharing.
+    }
+    return false;
+}
+function workspaceHash(cwd) {
+    return crypto_1.default.createHash("sha256").update(path_1.default.resolve(cwd)).digest("hex").slice(0, 16);
+}
+function storeDir(cwd) {
+    const treeId = process.env.LEMMA_AGENT_TREE_ID;
+    if (!treeId)
+        return null;
+    // Sanitize: the tree id lands in a path segment.
+    const safeTreeId = treeId.replace(/[^a-zA-Z0-9_-]/g, "").slice(0, 64) || "default";
+    return path_1.default.join(HOME, ".lemma-cache", "session", workspaceHash(cwd), safeTreeId);
+}
+function storeFile(cwd, namespace) {
+    const dir = storeDir(cwd);
+    if (!dir)
+        return null;
+    return path_1.default.join(dir, `${namespace}.json`);
+}
+function loadStore(cwd, namespace) {
+    try {
+        const file = storeFile(cwd, namespace);
+        if (!file || !fs_1.default.existsSync(file))
+            return {};
+        const parsed = JSON.parse(fs_1.default.readFileSync(file, "utf8"));
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function saveStore(cwd, namespace, data) {
+    try {
+        const dir = storeDir(cwd);
+        const file = storeFile(cwd, namespace);
+        if (!dir || !file)
+            return;
+        if (!fs_1.default.existsSync(dir))
+            fs_1.default.mkdirSync(dir, { recursive: true });
+        fs_1.default.writeFileSync(file, JSON.stringify(data), "utf8");
+    }
+    catch {
+        // Fail-open: the caller falls back to in-process-only behavior.
+    }
+}
+/** Get a shared value for `key` (namespaced), or null if disabled, missing, or expired. */
+function getSharedEntry(cwd, namespace, key) {
+    if (!isSharedLedgerEnabled(cwd))
+        return null;
+    try {
+        const data = loadStore(cwd, namespace);
+        const entry = data[key];
+        if (!entry)
+            return null;
+        if (Date.now() - entry.at > TTL_MS)
+            return null;
+        return entry.value;
+    }
+    catch {
+        return null;
+    }
+}
+/** Record a value under `key` (namespaced) for other trees-scoped processes to read. */
+function setSharedEntry(cwd, namespace, key, value) {
+    if (!isSharedLedgerEnabled(cwd))
+        return;
+    try {
+        const data = loadStore(cwd, namespace);
+        data[key] = { value, at: Date.now() };
+        // Bound the file: drop expired entries whenever we touch it, rather than growing forever.
+        const now = Date.now();
+        for (const k of Object.keys(data)) {
+            if (now - data[k].at > TTL_MS)
+                delete data[k];
+        }
+        saveStore(cwd, namespace, data);
+    }
+    catch {
+        // Fail-open.
+    }
+}
+//# sourceMappingURL=SharedLedgerStore.js.map

package/dist/cjs/utils/SharedLedgerStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SharedLedgerStore.js","sourceRoot":"","sources":["../../../src/utils/SharedLedgerStore.ts"],"names":[],"mappings":"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"}

package/dist/cjs/utils/SpeculativeWarmer.d.ts

@@ -0,0 +1,24 @@
+/**
+ * SpeculativeWarmer — precomputes local caches for a file's import neighbors while the
+ * model is off reasoning about what it just read, so a follow-up `get_ast_hologram` or
+ * `depgraph`/`affected_tests` call on a neighbor is a cache hit instead of a cold parse.
+ *
+ * HARD RULE: this warms local caches only (`DepGraph`'s graph cache, `AstSymbolCache`) and
+ * must never touch anything that reaches the model's context. It runs after the response for
+ * the triggering tool call has already been returned, off the event loop's current tick, and
+ * every failure is swallowed — a warming run that throws or runs slow must never be visible
+ * to whoever is waiting on the actual tool call.
+ */
+import { AstSymbol } from "./AstSymbolCache";
+/**
+ * `extractSymbolsWithTsCompiler` lives in `mcp/tools.ts`, which already imports this module —
+ * importing it back here would be circular. The dispatcher registers it once at startup instead.
+ */
+export declare function registerSymbolExtractor(extractor: (absPath: string, relPath: string, parseErrors?: string[]) => AstSymbol[]): void;
+/**
+ * Fire-and-forget: warm the import-neighborhood of `filePath` after a real read. Safe to call
+ * unconditionally — it is a no-op (not just cheap, actually skipped) whenever the extractor
+ * hasn't been registered yet, since that means startup isn't finished.
+ */
+export declare function warmNeighbors(workspaceRoot: string, filePath: string): void;
+//# sourceMappingURL=SpeculativeWarmer.d.ts.map

package/dist/cjs/utils/SpeculativeWarmer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpeculativeWarmer.d.ts","sourceRoot":"","sources":["../../../src/utils/SpeculativeWarmer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,EAAsC,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAQjF;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,KAAK,SAAS,EAAE,GACnF,IAAI,CAEN;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CA4B3E"}

package/dist/cjs/utils/SpeculativeWarmer.js

@@ -0,0 +1,73 @@
+"use strict";
+/**
+ * SpeculativeWarmer — precomputes local caches for a file's import neighbors while the
+ * model is off reasoning about what it just read, so a follow-up `get_ast_hologram` or
+ * `depgraph`/`affected_tests` call on a neighbor is a cache hit instead of a cold parse.
+ *
+ * HARD RULE: this warms local caches only (`DepGraph`'s graph cache, `AstSymbolCache`) and
+ * must never touch anything that reaches the model's context. It runs after the response for
+ * the triggering tool call has already been returned, off the event loop's current tick, and
+ * every failure is swallowed — a warming run that throws or runs slow must never be visible
+ * to whoever is waiting on the actual tool call.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerSymbolExtractor = registerSymbolExtractor;
+exports.warmNeighbors = warmNeighbors;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const DepGraph_1 = require("./DepGraph");
+const AstSymbolCache_1 = require("./AstSymbolCache");
+/** How many neighbor files a single warm pass will touch — bounded so this stays cheap. */
+const MAX_NEIGHBORS = 8;
+const MAX_DEPTH = 1;
+let extractorRef = null;
+/**
+ * `extractSymbolsWithTsCompiler` lives in `mcp/tools.ts`, which already imports this module —
+ * importing it back here would be circular. The dispatcher registers it once at startup instead.
+ */
+function registerSymbolExtractor(extractor) {
+    extractorRef = extractor;
+}
+/**
+ * Fire-and-forget: warm the import-neighborhood of `filePath` after a real read. Safe to call
+ * unconditionally — it is a no-op (not just cheap, actually skipped) whenever the extractor
+ * hasn't been registered yet, since that means startup isn't finished.
+ */
+function warmNeighbors(workspaceRoot, filePath) {
+    if (!extractorRef)
+        return;
+    const extractor = extractorRef;
+    // Deferred and unref'd so it can never keep the process alive or delay the response that
+    // triggered it — this must cost the triggering call nothing.
+    const timer = setTimeout(() => {
+        try {
+            const rel = path_1.default.relative(workspaceRoot, filePath).split(path_1.default.sep).join("/");
+            const graph = (0, DepGraph_1.buildDepGraphMap)(workspaceRoot);
+            const node = graph.get(rel);
+            if (!node)
+                return;
+            const neighbors = (0, DepGraph_1.bfsDepGraph)(graph, rel, "forward", MAX_DEPTH);
+            let warmed = 0;
+            for (const [neighborRel, { node: neighborNode }] of neighbors) {
+                if (warmed >= MAX_NEIGHBORS)
+                    break;
+                if (neighborRel === rel)
+                    continue;
+                if ((0, AstSymbolCache_1.hasFreshEntry)(neighborNode.abs))
+                    continue; // already warm — nothing to do
+                if (!fs_1.default.existsSync(neighborNode.abs))
+                    continue;
+                (0, AstSymbolCache_1.getOrExtractSymbols)(neighborNode.abs, neighborRel, extractor);
+                warmed++;
+            }
+        }
+        catch {
+            // Warming must never surface an error anywhere the model or the user can see it.
+        }
+    }, 0);
+    timer.unref?.();
+}
+//# sourceMappingURL=SpeculativeWarmer.js.map

package/dist/cjs/utils/SpeculativeWarmer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpeculativeWarmer.js","sourceRoot":"","sources":["../../../src/utils/SpeculativeWarmer.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;;;AAiBH,0DAIC;AAOD,sCA4BC;AAtDD,4CAAoB;AACpB,gDAAwB;AACxB,yCAA2D;AAC3D,qDAAiF;AAEjF,2FAA2F;AAC3F,MAAM,aAAa,GAAG,CAAC,CAAC;AACxB,MAAM,SAAS,GAAG,CAAC,CAAC;AAEpB,IAAI,YAAY,GAAuF,IAAI,CAAC;AAE5G;;;GAGG;AACH,SAAgB,uBAAuB,CACrC,SAAoF;IAEpF,YAAY,GAAG,SAAS,CAAC;AAC3B,CAAC;AAED;;;;GAIG;AACH,SAAgB,aAAa,CAAC,aAAqB,EAAE,QAAgB;IACnE,IAAI,CAAC,YAAY;QAAE,OAAO;IAC1B,MAAM,SAAS,GAAG,YAAY,CAAC;IAE/B,yFAAyF;IACzF,6DAA6D;IAC7D,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;QAC5B,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,cAAI,CAAC,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC,KAAK,CAAC,cAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC7E,MAAM,KAAK,GAAG,IAAA,2BAAgB,EAAC,aAAa,CAAC,CAAC;YAC9C,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC5B,IAAI,CAAC,IAAI;gBAAE,OAAO;YAElB,MAAM,SAAS,GAAG,IAAA,sBAAW,EAAC,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;YAChE,IAAI,MAAM,GAAG,CAAC,CAAC;YACf,KAAK,MAAM,CAAC,WAAW,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,IAAI,SAAS,EAAE,CAAC;gBAC9D,IAAI,MAAM,IAAI,aAAa;oBAAE,MAAM;gBACnC,IAAI,WAAW,KAAK,GAAG;oBAAE,SAAS;gBAClC,IAAI,IAAA,8BAAa,EAAC,YAAY,CAAC,GAAG,CAAC;oBAAE,SAAS,CAAC,+BAA+B;gBAC9E,IAAI,CAAC,YAAE,CAAC,UAAU,CAAC,YAAY,CAAC,GAAG,CAAC;oBAAE,SAAS;gBAC/C,IAAA,oCAAmB,EAAC,YAAY,CAAC,GAAG,EAAE,WAAW,EAAE,SAAS,CAAC,CAAC;gBAC9D,MAAM,EAAE,CAAC;YACX,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,iFAAiF;QACnF,CAAC;IACH,CAAC,EAAE,CAAC,CAAC,CAAC;IACN,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;AAClB,CAAC"}

package/dist/cjs/utils/reportSavings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reportSavings.d.ts","sourceRoot":"","sources":["../../../src/utils/reportSavings.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,KAAK,aAAa,GAAG,WAAW,GAAG,gBAAgB,GAAG,cAAc,GAAG,mBAAmB,GAAG,OAAO,CAAC;AAErG,UAAU,aAAa;IACrB,MAAM,EAAE,aAAa,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,cAAc;IACtB,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,KAAK,aAAa,GAAG,aAAa,GAAG,cAAc,CAAC;AAYpD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAE1D;AAED,KAAK,UAAU,GAAG,iBAAiB,GAAG,YAAY,GAAG,WAAW,CAAC;AAEjE,UAAU,WAAW;IACnB,MAAM,EAAE,UAAU,CAAC;IACnB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAErD"}
+{"version":3,"file":"reportSavings.d.ts","sourceRoot":"","sources":["../../../src/utils/reportSavings.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH,KAAK,aAAa,GAAG,WAAW,GAAG,gBAAgB,GAAG,cAAc,GAAG,mBAAmB,GAAG,OAAO,CAAC;AAErG,UAAU,aAAa;IACrB,MAAM,EAAE,aAAa,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,cAAc;IACtB,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,KAAK,aAAa,GAAG,aAAa,GAAG,cAAc,CAAC;AAYpD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAQ1D;AAED,KAAK,UAAU,GAAG,iBAAiB,GAAG,YAAY,GAAG,WAAW,CAAC;AAEjE,UAAU,WAAW;IACnB,MAAM,EAAE,UAAU,CAAC;IACnB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAMrD"}

package/dist/cjs/utils/reportSavings.js

@@ -15,6 +15,7 @@ const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
 const http_1 = __importDefault(require("http"));
+const RoiLedger_1 = require("./RoiLedger");
 function getProxyPort() {
     try {
         const portFile = path_1.default.join(os_1.default.homedir(), '.lemma-cache/proxy.port');
@@ -31,6 +32,12 @@ function getProxyPort() {
  */
 function reportSavings(payload) {
     post('/api/savings-record', payload);
+    if (payload.toolName) {
+        const tokens = 'tokens' in payload ? payload.tokens : Math.floor(Math.max(0, payload.charsBefore - payload.charsAfter) / 4);
+        // Best-effort, repo-scoped: process.cwd() is the workspace root for every MCP tool
+        // handler, same assumption `tools.ts` already makes throughout.
+        (0, RoiLedger_1.recordRoiSaved)(process.cwd(), payload.toolName, tokens);
+    }
 }
 /**
  * Report tokens Lemma *spent* to the proxy's ledger. Same fire-and-forget contract
@@ -39,6 +46,10 @@ function reportSavings(payload) {
  */
 function reportCost(payload) {
     post('/api/cost-record', payload);
+    if (payload.toolName) {
+        const tokens = typeof payload.tokens === 'number' ? payload.tokens : Math.floor(Math.max(0, payload.chars || 0) / 4);
+        (0, RoiLedger_1.recordRoiSpent)(process.cwd(), payload.toolName, tokens);
+    }
 }
 function post(pathname, payload) {
     try {

package/dist/cjs/utils/reportSavings.js.map

@@ -1 +1 @@
-{"version":3,"file":"reportSavings.js","sourceRoot":"","sources":["../../../src/utils/reportSavings.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;;AA0CH,sCAEC;AAkBD,gCAEC;AA9DD,4CAAoB;AACpB,gDAAwB;AACxB,4CAAoB;AACpB,gDAAwB;AAuBxB,SAAS,YAAY;IACnB,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,cAAI,CAAC,IAAI,CAAC,YAAE,CAAC,OAAO,EAAE,EAAE,yBAAyB,CAAC,CAAC;QACpE,IAAI,YAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC5B,OAAO,YAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;QAClD,CAAC;IACH,CAAC;IAAC,MAAM,CAAC,CAAA,CAAC;IACV,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,SAAgB,aAAa,CAAC,OAAsB;IAClD,IAAI,CAAC,qBAAqB,EAAE,OAAO,CAAC,CAAC;AACvC,CAAC;AAaD;;;;GAIG;AACH,SAAgB,UAAU,CAAC,OAAoB;IAC7C,IAAI,CAAC,kBAAkB,EAAE,OAAO,CAAC,CAAC;AACpC,CAAC;AAED,SAAS,IAAI,CAAC,QAAgB,EAAE,OAAgB;IAC9C,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,YAAY,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAErC,MAAM,GAAG,GAAG,cAAI,CAAC,OAAO,CAAC;YACvB,QAAQ,EAAE,WAAW;YACrB,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC;YACpB,IAAI,EAAE,QAAQ;YACd,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,gBAAgB,EAAE,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC;aAC1C;SACF,CAAC,CAAC;QAEH,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC,CAAC,yCAAyC;QACpE,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAChB,GAAG,CAAC,GAAG,EAAE,CAAC;IACZ,CAAC;IAAC,MAAM,CAAC;QACP,kDAAkD;IACpD,CAAC;AACH,CAAC"}
+{"version":3,"file":"reportSavings.js","sourceRoot":"","sources":["../../../src/utils/reportSavings.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;;AA2CH,sCAQC;AAkBD,gCAMC;AAzED,4CAAoB;AACpB,gDAAwB;AACxB,4CAAoB;AACpB,gDAAwB;AACxB,2CAA6D;AAuB7D,SAAS,YAAY;IACnB,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,cAAI,CAAC,IAAI,CAAC,YAAE,CAAC,OAAO,EAAE,EAAE,yBAAyB,CAAC,CAAC;QACpE,IAAI,YAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC5B,OAAO,YAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;QAClD,CAAC;IACH,CAAC;IAAC,MAAM,CAAC,CAAA,CAAC;IACV,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,SAAgB,aAAa,CAAC,OAAsB;IAClD,IAAI,CAAC,qBAAqB,EAAE,OAAO,CAAC,CAAC;IACrC,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QACrB,MAAM,MAAM,GAAG,QAAQ,IAAI,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;QAC5H,mFAAmF;QACnF,gEAAgE;QAChE,IAAA,0BAAc,EAAC,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC1D,CAAC;AACH,CAAC;AAaD;;;;GAIG;AACH,SAAgB,UAAU,CAAC,OAAoB;IAC7C,IAAI,CAAC,kBAAkB,EAAE,OAAO,CAAC,CAAC;IAClC,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QACrB,MAAM,MAAM,GAAG,OAAO,OAAO,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACrH,IAAA,0BAAc,EAAC,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC1D,CAAC;AACH,CAAC;AAED,SAAS,IAAI,CAAC,QAAgB,EAAE,OAAgB;IAC9C,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,YAAY,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAErC,MAAM,GAAG,GAAG,cAAI,CAAC,OAAO,CAAC;YACvB,QAAQ,EAAE,WAAW;YACrB,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC;YACpB,IAAI,EAAE,QAAQ;YACd,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,gBAAgB,EAAE,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC;aAC1C;SACF,CAAC,CAAC;QAEH,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC,CAAC,yCAAyC;QACpE,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAChB,GAAG,CAAC,GAAG,EAAE,CAAC;IACZ,CAAC;IAAC,MAAM,CAAC;QACP,kDAAkD;IACpD,CAAC;AACH,CAAC"}

package/dist/esm/cli/lemma-proxy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lemma-proxy.d.ts","sourceRoot":"","sources":["../../../src/cli/lemma-proxy.ts"],"names":[],"mappings":";AA4cA,wBAAgB,+BAA+B,CAAC,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CA4DvF;AA8lED,wBAAsB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA6KhL"}
+{"version":3,"file":"lemma-proxy.d.ts","sourceRoot":"","sources":["../../../src/cli/lemma-proxy.ts"],"names":[],"mappings":";AA4cA,wBAAgB,+BAA+B,CAAC,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CA4DvF;AA+mED,wBAAsB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA8KhL"}

package/dist/esm/cli/lemma-proxy.js

@@ -916,6 +916,14 @@ async function relayMissStream(res, body, provider, tier) {
         return;
     }
     const hostname = provider === 'openai' ? 'api.openai.com' : 'api.anthropic.com';
+    try {
+        gatekeeper.assertEgressAllowed(hostname);
+    }
+    catch (err) {
+        res.write(`data: ${JSON.stringify({ error: err.message, code: err.code })}\n\ndata: [DONE]\n\n`);
+        res.end();
+        return;
+    }
     const upPath = provider === 'openai' ? '/v1/chat/completions' : '/v1/messages';
     const headers = provider === 'openai'
         ? { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' }
@@ -1914,8 +1922,13 @@ Adjusted Answer:`;
         if (provider === 'openai' || provider === 'anthropic') {
             if (req.body.messages && req.body.messages.length > 0) {
                 injectSqueezedContent(req.body.messages[req.body.messages.length - 1], squeezedPrompt);
-                // Apply conversational history pruning
-                const pruneResult = pruneHistoryMessages(req.body.messages);
+                // Apply conversational history pruning — off by default (T7 guard): pruning
+                // invalidates the cached prompt prefix, which is usually a net loss. Set
+                // LEMMA_FORCE_HISTORY_PRUNE=1 to opt back into the old unconditional behavior
+                // (e.g. for a provider with no prompt caching).
+                const pruneResult = pruneHistoryMessages(req.body.messages, {
+                    force: process.env.LEMMA_FORCE_HISTORY_PRUNE === '1',
+                });
                 req.body.messages = pruneResult.messages;
                 historyTokensSaved = pruneResult.tokensSavedEstimate + Math.floor(compressionSavings / 4);
                 if (pruneResult.tokensSavedEstimate > 0) {
@@ -1960,6 +1973,9 @@ Adjusted Answer:`;
             return res.json(semanticScrubber.unmask(data, tokenMap));
         }
         catch (err) {
+            if (err.code === 'EGRESS_BLOCKED') {
+                return res.status(403).json({ error: err.message, code: err.code, decision: err.decision });
+            }
             return res.status(500).json({ error: err.message });
         }
     }
@@ -1976,6 +1992,7 @@ Adjusted Answer:`;
                 stream: false // keep stream false for simulation simplicity
             };
             const baseURL = 'https://api.openai.com/v1/chat/completions';
+            gatekeeper.assertEgressAllowed(baseURL);
             const resp = await axios.post(baseURL, payload, {
                 headers: {
                     Authorization: `Bearer ${apiKey}`,
@@ -2028,6 +2045,7 @@ Adjusted Answer:`;
             console.log(`\x1b[36m🔀 [Gateway Model Translation] Translating futuristic model ${body.model} to gpt-4o for key compatibility.\x1b[0m`);
             body.model = 'gpt-4o';
         }
+        gatekeeper.assertEgressAllowed(baseURL);
         const resp = await axios.post(baseURL, body, { headers: { ...headers, 'Content-Type': 'application/json' } });
         return resp.data;
     }
@@ -2584,6 +2602,7 @@ Ensure you return strictly JSON. Do not return any other text outside the JSON b
         }
         else {
             // Use OpenAI/Anthropic
+            gatekeeper.assertEgressAllowed('https://api.openai.com/v1/chat/completions');
             const resp = await axios.post('https://api.openai.com/v1/chat/completions', {
                 model: 'gpt-4o',
                 messages: [{ role: 'user', content: prompt }],