muonroi-cli 1.5.0 → 1.6.1

package/dist/src/cli/cost-forensics.d.ts

@@ -8,6 +8,7 @@
  * confirm that sub-agent context no longer balloons past 80k input
  * after the cumulative cap kicks in.
  */
+import type { SessionExperienceCounts } from "../orchestrator/session-experience.js";
 export interface CostForensicsRow {
     id: number;
     source: string;
@@ -35,6 +36,8 @@ export interface CostForensicsSummary {
     cacheHitRatio: number;
     peakSingleCallInput: number;
     events: CostForensicsRow[];
+    /** Anti-mù counters for this session (null when none recorded). */
+    experience: SessionExperienceCounts | null;
 }
 /**
  * Return ALL session ids matching a prefix (newest first, capped at 5).

package/dist/src/cli/cost-forensics.js

@@ -11,6 +11,7 @@
 import { getProviderCapabilities } from "../providers/capabilities.js";
 import { detectProviderForModel } from "../providers/runtime.js";
 import { getDatabase } from "../storage/db.js";
+import { selectSessionExperience } from "../storage/session-experience-store.js";
 function resolveSessionId(prefix) {
     const rows = getDatabase()
         .prepare(`SELECT id FROM sessions WHERE id LIKE ? ORDER BY created_at DESC LIMIT 5`)
@@ -103,6 +104,7 @@ export function collectCostForensics(sessionId) {
         cacheHitRatio,
         peakSingleCallInput,
         events,
+        experience: selectSessionExperience(sessionId),
     };
 }
 export function computeCacheCadence(events) {
@@ -164,6 +166,15 @@ export function printCostForensics(summary, opts = {}) {
             `(~${formatNum(cadence.estReBilledTokens)} tok re-billed). ` +
             `Likely fast tool-loop latency — fewer/batched tool rounds recover this.`);
     }
+    // Anti-mù counters for this session (rec #1 persisted forensics).
+    if (summary.experience) {
+        const x = summary.experience;
+        const rehydrated = x.rehydratedCache + x.rehydratedDisk + x.rehydratedEe;
+        w(`Anti-mù:             ${x.compactions} compaction(s), ${x.elided} tool output(s) elided` +
+            `${x.elided > 0 ? ` (${formatNum(x.totalElidedChars)} chars)` : ""}, ` +
+            `${rehydrated} rehydrated (cache=${x.rehydratedCache} disk=${x.rehydratedDisk} ee=${x.rehydratedEe}), ` +
+            `${x.unavailable} needed-but-unavailable.`);
+    }
     w(``);
     w(`Per-event breakdown:`);
     w(`${"seq".padEnd(5)}${"src".padEnd(10)}${"input".padStart(9)}${"out".padStart(7)}${"cacheR".padStart(9)}${"cacheC".padStart(8)}  ts`);

package/dist/src/cli/cost-forensics.test.js

@@ -62,6 +62,7 @@ function summary(events) {
         cacheHitRatio: totalInput > 0 ? totalCacheRead / totalInput : 0,
         peakSingleCallInput: Math.max(0, ...events.map((e) => e.inputTokens)),
         events,
+        experience: null,
     };
 }
 function captureStdout(fn) {

package/dist/src/cli/experience-report.d.ts

@@ -0,0 +1,20 @@
+/**
+ * src/cli/experience-report.ts
+ *
+ * `muonroi-cli usage experience` — cross-session anti-mù telemetry. Aggregates
+ * the per-session session_experience snapshots to answer the measure-before-
+ * re-architecting question: how often does compaction actually elide a tool
+ * output, and when the agent goes back for one, can it recover it?
+ *
+ * This is the data gate for the deferred anti-mù re-architecture (auto-protect /
+ * auto-rehydrate). Low elision rate or high recovery rate ⇒ the friction is rare
+ * or cognitive, not data-loss ⇒ defer. High unavailable / low recovery ⇒ real
+ * loss ⇒ justified.
+ */
+import { type ExperienceAggregate } from "../storage/session-experience-store.js";
+/** Pure renderer — returns the report lines so it is unit-testable without a DB. */
+export declare function renderExperienceAggregate(agg: ExperienceAggregate, limit: number): string[];
+export declare function runExperienceReport(opts?: {
+    limit?: number;
+    json?: boolean;
+}): Promise<void>;

package/dist/src/cli/experience-report.js

@@ -0,0 +1,76 @@
+/**
+ * src/cli/experience-report.ts
+ *
+ * `muonroi-cli usage experience` — cross-session anti-mù telemetry. Aggregates
+ * the per-session session_experience snapshots to answer the measure-before-
+ * re-architecting question: how often does compaction actually elide a tool
+ * output, and when the agent goes back for one, can it recover it?
+ *
+ * This is the data gate for the deferred anti-mù re-architecture (auto-protect /
+ * auto-rehydrate). Low elision rate or high recovery rate ⇒ the friction is rare
+ * or cognitive, not data-loss ⇒ defer. High unavailable / low recovery ⇒ real
+ * loss ⇒ justified.
+ */
+import { aggregateSessionExperience } from "../storage/session-experience-store.js";
+function pct(n, d) {
+    return d > 0 ? `${((n / d) * 100).toFixed(0)}%` : "—";
+}
+function num(n) {
+    return n.toLocaleString("en-US");
+}
+/** Pure renderer — returns the report lines so it is unit-testable without a DB. */
+export function renderExperienceAggregate(agg, limit) {
+    const t = agg.totals;
+    const rehydrated = t.rehydratedCache + t.rehydratedDisk + t.rehydratedEe;
+    const out = [];
+    out.push("");
+    out.push(`Session-experience aggregate — latest ${agg.sessionCount} session(s) with a snapshot (cap ${limit})`);
+    out.push("─".repeat(72));
+    if (agg.sessionCount === 0) {
+        out.push("No session_experience snapshots recorded yet.");
+        out.push("Run some real (non-meta) sessions, then re-check — compaction only");
+        out.push("persists a snapshot once it actually elides / rehydrates something.");
+        return out;
+    }
+    out.push(`Sessions with compaction elision:   ${agg.sessionsWithElision} (${pct(agg.sessionsWithElision, agg.sessionCount)})`);
+    out.push(`Sessions hitting needed-but-unavail: ${agg.sessionsWithUnavailable} (${pct(agg.sessionsWithUnavailable, agg.sessionCount)})`);
+    out.push("");
+    out.push("Totals across those sessions:");
+    out.push(`  Compactions fired:       ${num(t.compactions)}`);
+    out.push(`  Tool outputs elided:     ${num(t.elided)} (${num(t.totalElidedChars)} chars)`);
+    out.push(`  Rehydrated via ee_query: ${num(rehydrated)} (cache=${t.rehydratedCache} disk=${t.rehydratedDisk} ee=${t.rehydratedEe})`);
+    out.push(`  Needed-but-unavailable:  ${num(t.unavailable)}`);
+    out.push(`  EE timeouts / errors:    ${num(t.eeTimeouts)} / ${num(t.eeErrors)}`);
+    out.push("");
+    out.push(`Rehydrate recovery rate: ${(agg.rehydrateRecoveryRate * 100).toFixed(0)}%  (rehydrated / (rehydrated + unavailable))`);
+    out.push("");
+    // Decision signal for the deferred re-architecture.
+    out.push("Re-architecture decision signal:");
+    if (t.elided === 0) {
+        out.push("  • Compaction has not elided anything — friction is not occurring. DEFER.");
+    }
+    else {
+        const elisionRate = agg.sessionsWithElision / agg.sessionCount;
+        if (elisionRate < 0.2) {
+            out.push(`  • Elision bites in only ${pct(agg.sessionsWithElision, agg.sessionCount)} of sessions — rare. Likely DEFER.`);
+        }
+        if (agg.rehydrateRecoveryRate >= 0.9 || t.unavailable === 0) {
+            out.push("  • Recovery rate high / no unavailable — manual rehydrate works; friction is cognitive, not data-loss. Manifest+keepLast likely enough.");
+        }
+        else {
+            out.push(`  • Recovery rate ${(agg.rehydrateRecoveryRate * 100).toFixed(0)}% with ${num(t.unavailable)} unrecoverable — real data loss. Auto-protect/auto-rehydrate JUSTIFIED.`);
+        }
+    }
+    return out;
+}
+export async function runExperienceReport(opts = {}) {
+    const limit = opts.limit && opts.limit > 0 ? opts.limit : 100;
+    const agg = aggregateSessionExperience(limit);
+    if (opts.json) {
+        process.stdout.write(`${JSON.stringify(agg, null, 2)}\n`);
+        return;
+    }
+    for (const line of renderExperienceAggregate(agg, limit))
+        process.stdout.write(`${line}\n`);
+}
+//# sourceMappingURL=experience-report.js.map

package/dist/src/cli/experience-report.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * experience-report renderer — the cross-session decision signal that gates the
+ * deferred anti-mù auto-protect/auto-rehydrate re-architecture.
+ */
+export {};

package/dist/src/cli/experience-report.test.js

@@ -0,0 +1,63 @@
+/**
+ * experience-report renderer — the cross-session decision signal that gates the
+ * deferred anti-mù auto-protect/auto-rehydrate re-architecture.
+ */
+import { describe, expect, it } from "vitest";
+import { renderExperienceAggregate } from "./experience-report.js";
+function counts(p = {}) {
+    return {
+        compactions: 0,
+        elided: 0,
+        totalElidedChars: 0,
+        rehydratedCache: 0,
+        rehydratedDisk: 0,
+        rehydratedEe: 0,
+        unavailable: 0,
+        eeTimeouts: 0,
+        eeErrors: 0,
+        ...p,
+    };
+}
+function agg(p = {}) {
+    return {
+        sessionCount: p.sessionCount ?? 1,
+        sessionsWithElision: p.sessionsWithElision ?? 0,
+        sessionsWithUnavailable: p.sessionsWithUnavailable ?? 0,
+        totals: counts(p.totals),
+        rehydrateRecoveryRate: p.rehydrateRecoveryRate ?? 1,
+        perSession: p.perSession ?? [],
+    };
+}
+describe("renderExperienceAggregate", () => {
+    it("reports the no-data case clearly", () => {
+        const text = renderExperienceAggregate(agg({ sessionCount: 0 }), 100).join("\n");
+        expect(text).toContain("No session_experience snapshots recorded yet");
+    });
+    it("signals DEFER when nothing was ever elided", () => {
+        const text = renderExperienceAggregate(agg({ sessionCount: 5, totals: { compactions: 3 } }), 100).join("\n");
+        expect(text).toContain("has not elided anything");
+        expect(text).toContain("DEFER");
+    });
+    it("signals cognitive-not-data-loss when recovery is high / no unavailable", () => {
+        const text = renderExperienceAggregate(agg({
+            sessionCount: 4,
+            sessionsWithElision: 3,
+            rehydrateRecoveryRate: 1,
+            totals: { compactions: 5, elided: 20, rehydratedCache: 8 },
+        }), 100).join("\n");
+        expect(text).toMatch(/cognitive, not data-loss/);
+        expect(text).not.toMatch(/JUSTIFIED/);
+    });
+    it("signals re-architecture JUSTIFIED when recovery is low with unrecoverable artifacts", () => {
+        const text = renderExperienceAggregate(agg({
+            sessionCount: 6,
+            sessionsWithElision: 5,
+            sessionsWithUnavailable: 4,
+            rehydrateRecoveryRate: 0.3,
+            totals: { compactions: 10, elided: 40, rehydratedEe: 3, unavailable: 7 },
+        }), 100).join("\n");
+        expect(text).toContain("real data loss");
+        expect(text).toContain("JUSTIFIED");
+    });
+});
+//# sourceMappingURL=experience-report.test.js.map

package/dist/src/ee/artifact-cache.d.ts

@@ -0,0 +1,56 @@
+/**
+ * src/ee/artifact-cache.ts
+ *
+ * Durable fallback for compaction-elided tool outputs (issue #3 increment 2 /
+ * anti-mù durability).
+ *
+ * When B3/B4 compaction rewrites a low-value tool result into a ~200-char stub,
+ * the full content is shipped to the Experience Engine (source="tool-artifact")
+ * so a later `ee_query("tool-artifact id=X")` can rehydrate it. But that recovery
+ * depends on EE (Qdrant/HTTP) being reachable. This module is the EE-independent
+ * recovery path, in two tiers:
+ *   - in-process LRU (keyed by toolCallId): authoritative full content for THIS
+ *     session, instant, survives an EE outage mid-session;
+ *   - append-only disk spill (~/.muonroi-cli/artifact-cache.jsonl): survives a
+ *     PROCESS RESTART too, so a restart + EE-down double-failure can still
+ *     rehydrate. Disable with MUONROI_ARTIFACT_CACHE_DISK=0.
+ *
+ * ee_query reads in-memory first, then disk, then falls back to EE /api/search
+ * (the cross-session source). Both tiers are bounded; both are best-effort and
+ * fail-open (a disk error never breaks recall).
+ */
+export interface ArtifactEntry {
+    toolName: string;
+    content: string;
+}
+/**
+ * Record an elided tool output by toolCallId. In-memory set is synchronous;
+ * the disk append is fire-and-forget (tracked so tests can flush it). No-ops on
+ * empty id/content.
+ */
+export declare function recordArtifact(toolCallId: string, toolName: string, content: string): void;
+/** The actual disk append (awaitable). Resets the file when it exceeds the size cap. */
+export declare function appendArtifactToDisk(toolCallId: string, toolName: string, content: string): Promise<void>;
+/** Exact in-memory lookup by toolCallId. */
+export declare function getArtifact(toolCallId: string): ArtifactEntry | null;
+/**
+ * Synchronous in-memory lookup from a contract query string. Returns null when
+ * the query has no id= or the id is not in the in-process LRU.
+ */
+export declare function findArtifactByQuery(query: string): (ArtifactEntry & {
+    toolCallId: string;
+}) | null;
+/**
+ * Disk-tier lookup (survives restart). Scans the spill file newest-first so the
+ * most recent record for an id wins. Fail-open: a missing/corrupt file yields
+ * null, never throws.
+ */
+export declare function findArtifactOnDisk(query: string): Promise<(ArtifactEntry & {
+    toolCallId: string;
+}) | null>;
+export declare function __resetArtifactCacheForTests(): void;
+export declare function __setArtifactCacheMaxForTests(n: number): void;
+export declare function __setArtifactCacheDiskPathForTests(p: string | null): void;
+export declare function __artifactCacheSize(): number;
+/** Await all in-flight fire-and-forget disk writes (deterministic tests). */
+export declare function flushArtifactDiskWrites(): Promise<void>;

package/dist/src/ee/artifact-cache.js

@@ -0,0 +1,155 @@
+/**
+ * src/ee/artifact-cache.ts
+ *
+ * Durable fallback for compaction-elided tool outputs (issue #3 increment 2 /
+ * anti-mù durability).
+ *
+ * When B3/B4 compaction rewrites a low-value tool result into a ~200-char stub,
+ * the full content is shipped to the Experience Engine (source="tool-artifact")
+ * so a later `ee_query("tool-artifact id=X")` can rehydrate it. But that recovery
+ * depends on EE (Qdrant/HTTP) being reachable. This module is the EE-independent
+ * recovery path, in two tiers:
+ *   - in-process LRU (keyed by toolCallId): authoritative full content for THIS
+ *     session, instant, survives an EE outage mid-session;
+ *   - append-only disk spill (~/.muonroi-cli/artifact-cache.jsonl): survives a
+ *     PROCESS RESTART too, so a restart + EE-down double-failure can still
+ *     rehydrate. Disable with MUONROI_ARTIFACT_CACHE_DISK=0.
+ *
+ * ee_query reads in-memory first, then disk, then falls back to EE /api/search
+ * (the cross-session source). Both tiers are bounded; both are best-effort and
+ * fail-open (a disk error never breaks recall).
+ */
+import { appendFile, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+const DEFAULT_MAX_ENTRIES = 100;
+/** Per-entry cap so one giant output can't dominate the footprint. */
+const MAX_CONTENT_CHARS = 200_000;
+/** Disk-file size cap; on overflow the file is reset (EE retains older artifacts). */
+const DISK_MAX_BYTES = 8 * 1024 * 1024;
+const store = new Map();
+let maxEntries = DEFAULT_MAX_ENTRIES;
+let diskPathOverride = null;
+const pendingWrites = new Set();
+function diskEnabled() {
+    return process.env.MUONROI_ARTIFACT_CACHE_DISK !== "0";
+}
+function diskPath() {
+    return diskPathOverride ?? path.join(os.homedir(), ".muonroi-cli", "artifact-cache.jsonl");
+}
+/** Extract the id from a "tool-artifact id=<id>" / "full tool result id=<id>" query. */
+function extractArtifactId(query) {
+    const m = /\bid\s*=\s*["']?([A-Za-z0-9_\-:.]+)/i.exec(query || "");
+    return m ? m[1] : null;
+}
+/**
+ * Record an elided tool output by toolCallId. In-memory set is synchronous;
+ * the disk append is fire-and-forget (tracked so tests can flush it). No-ops on
+ * empty id/content.
+ */
+export function recordArtifact(toolCallId, toolName, content) {
+    if (!toolCallId || typeof content !== "string" || content.length === 0)
+        return;
+    const capped = content.slice(0, MAX_CONTENT_CHARS);
+    if (store.has(toolCallId))
+        store.delete(toolCallId); // refresh recency
+    store.set(toolCallId, { toolName: toolName || "", content: capped });
+    while (store.size > maxEntries) {
+        const oldest = store.keys().next().value;
+        if (oldest === undefined)
+            break;
+        store.delete(oldest);
+    }
+    if (diskEnabled()) {
+        const w = appendArtifactToDisk(toolCallId, toolName || "", capped).catch((err) => {
+            console.error(`[artifact-cache] disk append failed: ${err?.message}`);
+        });
+        pendingWrites.add(w);
+        void w.finally(() => pendingWrites.delete(w));
+    }
+}
+/** The actual disk append (awaitable). Resets the file when it exceeds the size cap. */
+export async function appendArtifactToDisk(toolCallId, toolName, content) {
+    const p = diskPath();
+    await mkdir(path.dirname(p), { recursive: true });
+    try {
+        const s = await stat(p);
+        if (s.size > DISK_MAX_BYTES)
+            await writeFile(p, "");
+    }
+    catch {
+        /* file does not exist yet — nothing to cap */
+    }
+    await appendFile(p, `${JSON.stringify({ id: toolCallId, toolName, content })}\n`);
+}
+/** Exact in-memory lookup by toolCallId. */
+export function getArtifact(toolCallId) {
+    if (!toolCallId)
+        return null;
+    return store.get(toolCallId) ?? null;
+}
+/**
+ * Synchronous in-memory lookup from a contract query string. Returns null when
+ * the query has no id= or the id is not in the in-process LRU.
+ */
+export function findArtifactByQuery(query) {
+    const id = extractArtifactId(query);
+    if (!id)
+        return null;
+    const hit = store.get(id);
+    return hit ? { toolCallId: id, toolName: hit.toolName, content: hit.content } : null;
+}
+/**
+ * Disk-tier lookup (survives restart). Scans the spill file newest-first so the
+ * most recent record for an id wins. Fail-open: a missing/corrupt file yields
+ * null, never throws.
+ */
+export async function findArtifactOnDisk(query) {
+    if (!diskEnabled())
+        return null;
+    const id = extractArtifactId(query);
+    if (!id)
+        return null;
+    let text;
+    try {
+        text = await readFile(diskPath(), "utf8");
+    }
+    catch {
+        return null; // no spill file yet
+    }
+    const lines = text.split("\n");
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i];
+        if (!line)
+            continue;
+        try {
+            const row = JSON.parse(line);
+            if (row.id === id)
+                return { toolCallId: id, toolName: row.toolName ?? "", content: row.content ?? "" };
+        }
+        catch {
+            /* skip a torn/partial append line */
+        }
+    }
+    return null;
+}
+// ─── Test hooks ──────────────────────────────────────────────────────────────
+export function __resetArtifactCacheForTests() {
+    store.clear();
+    maxEntries = DEFAULT_MAX_ENTRIES;
+    diskPathOverride = null;
+}
+export function __setArtifactCacheMaxForTests(n) {
+    maxEntries = Math.max(1, n);
+}
+export function __setArtifactCacheDiskPathForTests(p) {
+    diskPathOverride = p;
+}
+export function __artifactCacheSize() {
+    return store.size;
+}
+/** Await all in-flight fire-and-forget disk writes (deterministic tests). */
+export async function flushArtifactDiskWrites() {
+    await Promise.allSettled([...pendingWrites]);
+}
+//# sourceMappingURL=artifact-cache.js.map

package/dist/src/ee/artifact-cache.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/ee/artifact-cache.test.js

@@ -0,0 +1,69 @@
+import { rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { __artifactCacheSize, __resetArtifactCacheForTests, __setArtifactCacheDiskPathForTests, __setArtifactCacheMaxForTests, appendArtifactToDisk, findArtifactByQuery, findArtifactOnDisk, flushArtifactDiskWrites, getArtifact, recordArtifact, } from "./artifact-cache.js";
+// Redirect the disk spill to a temp file for EVERY test so recordArtifact never
+// writes the real ~/.muonroi-cli/artifact-cache.jsonl.
+const diskFile = path.join(os.tmpdir(), `muonroi-artifact-cache-test-${process.pid}.jsonl`);
+beforeEach(() => __setArtifactCacheDiskPathForTests(diskFile));
+afterEach(async () => {
+    __resetArtifactCacheForTests();
+    delete process.env.MUONROI_ARTIFACT_CACHE_DISK;
+    await rm(diskFile, { force: true });
+});
+describe("artifact-cache (in-memory tier — durable rehydrate when EE is down)", () => {
+    it("records and retrieves an elided output by toolCallId", () => {
+        recordArtifact("call_7", "read_file", "FULL CONTENT of src/auth.ts");
+        expect(getArtifact("call_7")).toEqual({ toolName: "read_file", content: "FULL CONTENT of src/auth.ts" });
+        expect(getArtifact("missing")).toBeNull();
+    });
+    it("no-ops on empty id or empty content", () => {
+        recordArtifact("", "read_file", "x");
+        recordArtifact("call_x", "read_file", "");
+        expect(__artifactCacheSize()).toBe(0);
+    });
+    it("findArtifactByQuery extracts the id from the contract query strings", () => {
+        recordArtifact("abc123", "grep", "GREP HITS");
+        expect(findArtifactByQuery("tool-artifact id=abc123")?.content).toBe("GREP HITS");
+        expect(findArtifactByQuery("full tool result id=abc123")?.toolCallId).toBe("abc123");
+        expect(findArtifactByQuery("tool-artifact  ID = abc123")?.content).toBe("GREP HITS"); // spacing/case
+        expect(findArtifactByQuery("tool-artifact id=nope")).toBeNull(); // not cached
+        expect(findArtifactByQuery("no id here")).toBeNull(); // no id=
+    });
+    it("evicts the oldest entries past the LRU cap; re-recording refreshes recency", () => {
+        __setArtifactCacheMaxForTests(2);
+        recordArtifact("a", "t", "A");
+        recordArtifact("b", "t", "B");
+        recordArtifact("a", "t", "A2"); // touch 'a' → now 'b' is oldest
+        recordArtifact("c", "t", "C"); // evicts 'b'
+        expect(getArtifact("a")?.content).toBe("A2");
+        expect(getArtifact("c")?.content).toBe("C");
+        expect(getArtifact("b")).toBeNull();
+        expect(__artifactCacheSize()).toBe(2);
+    });
+});
+describe("artifact-cache (disk spill — survives a process restart)", () => {
+    it("rehydrates from disk after the in-memory tier is gone (simulated restart)", async () => {
+        recordArtifact("call_disk", "read_file", "PERSISTED CONTENT");
+        await flushArtifactDiskWrites();
+        // Simulate a restart: in-memory tier cleared, but the disk file persists.
+        __resetArtifactCacheForTests();
+        __setArtifactCacheDiskPathForTests(diskFile);
+        expect(findArtifactByQuery("tool-artifact id=call_disk")).toBeNull(); // memory gone
+        const onDisk = await findArtifactOnDisk("tool-artifact id=call_disk");
+        expect(onDisk?.content).toBe("PERSISTED CONTENT");
+        expect(onDisk?.toolName).toBe("read_file");
+    });
+    it("newest record for an id wins on disk", async () => {
+        await appendArtifactToDisk("dup", "t", "OLD");
+        await appendArtifactToDisk("dup", "t", "NEW");
+        expect((await findArtifactOnDisk("tool-artifact id=dup"))?.content).toBe("NEW");
+    });
+    it("respects MUONROI_ARTIFACT_CACHE_DISK=0 (no disk read)", async () => {
+        await appendArtifactToDisk("x", "t", "C");
+        process.env.MUONROI_ARTIFACT_CACHE_DISK = "0";
+        expect(await findArtifactOnDisk("tool-artifact id=x")).toBeNull();
+    });
+});
+//# sourceMappingURL=artifact-cache.test.js.map

package/dist/src/ee/search.js

@@ -97,11 +97,13 @@ export async function mirrorRecallLocally(query, meta, logPath) {
  * unavailability/timeout — never throws for transport errors.
  */
 export async function searchEE(query, opts = {}) {
-    const { createEEClient } = await import("./client.js");
-    const { loadEEAuthToken, getCachedServerBaseUrl } = await import("./auth.js");
-    const authToken = (await loadEEAuthToken()) ?? undefined;
-    const baseUrl = getCachedServerBaseUrl() ?? undefined;
-    return createEEClient({ baseUrl, authToken }).search(query, opts);
+    // Route through the shared injectable default client (same one the WRITE leg
+    // persistArtifact → getDefaultEEClient().extract uses), NOT a fresh per-call
+    // client. This unifies the anti-mù seam: setDefaultEEClient now intercepts BOTH
+    // the artifact write and the artifact READ leg, and the default client carries
+    // the boot-loaded token + 401 refresh maintained by intercept.ts.
+    const { getDefaultEEClient } = await import("./intercept.js");
+    return getDefaultEEClient().search(query, opts);
 }
 /**
  * Active recall over the EE brain via /api/recall (recallMode) — the fixed

package/dist/src/ee/search.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/ee/search.test.js

@@ -0,0 +1,23 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { setDefaultEEClient } from "./intercept.js";
+import { searchEE } from "./search.js";
+// Issue #3 seam: searchEE used to build a FRESH createEEClient, so the artifact
+// READ leg (ee_query "tool-artifact id=X") could not be intercepted by
+// setDefaultEEClient — while the WRITE leg (persistArtifact → getDefaultEEClient
+// .extract) could. Routing searchEE through getDefaultEEClient unifies the seam:
+// one injected client now intercepts both legs (testable end-to-end + the spot a
+// durability fallback can hook).
+describe("searchEE — routes through the injectable default EE client", () => {
+    afterEach(() => {
+        setDefaultEEClient(null); // teardown → next getDefaultEEClient lazy-inits a real one
+    });
+    it("uses getDefaultEEClient().search so the artifact READ leg is interceptable", async () => {
+        const fakeResp = { results: [{ id: "x", text: "REHYDRATED" }] };
+        const search = vi.fn().mockResolvedValue(fakeResp);
+        setDefaultEEClient({ search });
+        const out = await searchEE("tool-artifact id=x", { collections: ["experience-behavioral"], limit: 1 });
+        expect(search).toHaveBeenCalledWith("tool-artifact id=x", { collections: ["experience-behavioral"], limit: 1 });
+        expect(out).toBe(fakeResp);
+    });
+});
+//# sourceMappingURL=search.test.js.map

package/dist/src/generated/version.d.ts

@@ -1,2 +1,2 @@
-export declare const PACKAGE_VERSION = "1.5.0";
+export declare const PACKAGE_VERSION = "1.6.1";
 export declare const PACKAGE_DESCRIPTION = "BYOK AI coding agent with multi-model council debate, role-based routing, and auto-compact.";

package/dist/src/generated/version.js

@@ -1,5 +1,5 @@
 // AUTO-GENERATED by scripts/sync-version.cjs. DO NOT EDIT BY HAND.
 // Sourced from package.json at build time so it survives bun --compile bundling.
-export const PACKAGE_VERSION = "1.5.0";
+export const PACKAGE_VERSION = "1.6.1";
 export const PACKAGE_DESCRIPTION = "BYOK AI coding agent with multi-model council debate, role-based routing, and auto-compact.";
 //# sourceMappingURL=version.js.map

package/dist/src/gsd/__tests__/directives.test.js

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 import { scoreComplexity } from "../complexity.js";
-import { buildDirective } from "../directives.js";
+import { buildDirective, mentionsEcosystemScope } from "../directives.js";
 import { detectGrayAreas } from "../gray-areas.js";
 describe("buildDirective", () => {
     it("emits a blocking heavy directive with mandatory steps", () => {
@@ -66,6 +66,29 @@ describe("buildDirective", () => {
         expect(out.blocking).toBe(false);
         expect(out.text.length).toBeLessThan(300);
     });
+    it("appends the muonroi-docs nudge for an ecosystem question (session 41ccfeb2ceee turn 1)", () => {
+        const complexity = scoreComplexity("bạn hiểu thế nào về ecosystem muonroi nói chung");
+        const out = buildDirective({ complexity, phase: null, grayAreas: [], informational: true, ecosystem: true });
+        expect(out.text).toMatch(/QUESTION \/ explanatory/); // still the human-facing question directive
+        expect(out.text).toMatch(/ECOSYSTEM SCOPE/);
+        expect(out.text).toMatch(/muonroi-docs MCP is the AUTHORITATIVE source|AUTHORITATIVE source/);
+        expect(out.text).toMatch(/call it FIRST/i);
+    });
+    it("does NOT append the ecosystem nudge for a plain question", () => {
+        const complexity = scoreComplexity("how does this CLI affect you?");
+        const out = buildDirective({ complexity, phase: null, grayAreas: [], informational: true });
+        expect(out.text).not.toMatch(/ECOSYSTEM SCOPE/);
+    });
+    it("mentionsEcosystemScope is tight: ecosystem/BB wording yes, bare CLI-internals no", () => {
+        // Fires on genuine ecosystem scope (the case muonroi-docs exists to serve)…
+        expect(mentionsEcosystemScope("ecosystem muonroi nói chung và muonroi-cli nói riêng")).toBe(true);
+        expect(mentionsEcosystemScope("hệ sinh thái muonroi gồm những gì")).toBe(true);
+        expect(mentionsEcosystemScope("how does the building-block rule engine work")).toBe(true);
+        // …but NOT on a muonroi-cli internals question that merely names the product,
+        // which would wrongly steer toward .NET package docs.
+        expect(mentionsEcosystemScope("how does muonroi-cli compaction work")).toBe(false);
+        expect(mentionsEcosystemScope("fix the off-by-one in the router")).toBe(false);
+    });
     it("renders the recommended option first in gray-area block", () => {
         const prompt = "redo everything from scratch";
         const complexity = scoreComplexity(prompt);

package/dist/src/gsd/directives.d.ts

@@ -31,6 +31,21 @@ export interface DirectiveInput {
      * buildDirective emits a human-facing question directive instead.
      */
     informational?: boolean;
+    /**
+     * True when the turn is about the Muonroi ECOSYSTEM (the whole platform, BB/
+     * .NET packages, building-block, open-core boundary, setup/install) rather than
+     * muonroi-cli's own TS internals. When set, buildDirective appends a nudge to
+     * consult the authoritative muonroi-docs MCP first. Computed by the caller via
+     * mentionsEcosystemScope so a CLI-internals question (which merely contains the
+     * word "muonroi") does NOT misfire toward .NET docs.
+     *
+     * Live miss (session 41ccfeb2ceee turn 1): "bạn hiểu thế nào về ecosystem
+     * muonroi…" — muonroi-docs WAS in the toolset (smart-filter kept it) but the
+     * question directive steered the agent to read/grep local files, so it answered
+     * "no comprehensive ecosystem description in the files read" instead of querying
+     * the shipped authoritative source.
+     */
+    ecosystem?: boolean;
 }
 export interface DirectiveOutput {
     text: string;
@@ -38,4 +53,11 @@ export interface DirectiveOutput {
     /** True when the directive forbids the agent from acting before clarifying. */
     blocking: boolean;
 }
+export declare function mentionsEcosystemScope(message: string): boolean;
+/**
+ * Appended to any directive when the turn is ecosystem-scoped. Phrased
+ * conditionally ("if … available") so it is harmless when muonroi-docs is not
+ * configured — the model simply finds no such tool and falls back to local files.
+ */
+export declare const ECOSYSTEM_DOCS_NUDGE: string;
 export declare function buildDirective(input: DirectiveInput): DirectiveOutput;