muonroi-cli 1.3.4 → 1.4.1

package/dist/src/models/registry.d.ts

@@ -18,3 +18,5 @@ export declare function getSupportedReasoningEfforts(modelId: string): Reasoning
  */
 export declare function getModelByTier(tier: "fast" | "balanced" | "premium", preferProvider?: string): ModelInfo | undefined;
 export declare function getModelsForProvider(providerId: string): ModelInfo[];
+export declare function getFirstCatalogModel(): ModelInfo;
+export declare function getFirstCatalogProvider(): string;

package/dist/src/models/registry.js

@@ -65,4 +65,13 @@ export function getModelByTier(tier, preferProvider) {
 export function getModelsForProvider(providerId) {
     return MODELS.filter((m) => m.provider === providerId);
 }
+export function getFirstCatalogModel() {
+    const m = MODELS.find(() => true);
+    if (!m)
+        throw new Error("No models in catalog. Check src/models/catalog.json or catalog endpoint.");
+    return m;
+}
+export function getFirstCatalogProvider() {
+    return getFirstCatalogModel().provider;
+}
 //# sourceMappingURL=registry.js.map

package/dist/src/ops/__tests__/doctor-ee-health.test.js

@@ -12,7 +12,7 @@ vi.mock("../../ee/health.js", () => ({
 // Mock getDatabase with a minimal SQLite-like interface
 const mockGet = vi.fn().mockReturnValue({ cnt: 0 });
 const mockPrepare = vi.fn().mockReturnValue({ get: mockGet });
-vi.mock("../../storage/db.js", () => ({
+vi.mock("../../storage/db", () => ({
     getDatabase: vi.fn(() => ({ prepare: mockPrepare })),
 }));
 // Mock other external dependencies to prevent network calls in doctor

package/dist/src/ops/doctor.js

@@ -157,9 +157,9 @@ async function checkBrainEmptiness() {
         // Count ee_injection events with event_subtype='no_match' in last 30 days
         const cutoff = new Date(Date.now() - 30 * 86_400_000).toISOString();
         const row = db
-            .prepare(`SELECT COUNT(*) as cnt FROM interaction_logs
-         WHERE event_type = 'ee_injection'
-           AND event_subtype = 'no_match'
+            .prepare(`SELECT COUNT(*) as cnt FROM interaction_logs
+         WHERE event_type = 'ee_injection'
+           AND event_subtype = 'no_match'
            AND created_at >= ?`)
             .get(cutoff);
         const noMatchCount = row?.cnt ?? 0;
@@ -258,10 +258,10 @@ async function checkCouncilMcpNudge() {
         // 2. Query DB for [Council Memory] records with URL or research topics
         const db = getDatabase();
         const rows = db
-            .prepare(`SELECT message_json FROM messages
-         WHERE role = 'system'
-           AND message_json LIKE '%[Council Memory]%'
-         ORDER BY created_at DESC
+            .prepare(`SELECT message_json FROM messages
+         WHERE role = 'system'
+           AND message_json LIKE '%[Council Memory]%'
+         ORDER BY created_at DESC
          LIMIT 50`)
             .all();
         let qualifyingCount = 0;

package/dist/src/orchestrator/__tests__/agent-base-url-switch.test.d.ts

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

package/dist/src/orchestrator/__tests__/agent-base-url-switch.test.js

@@ -0,0 +1,77 @@
+/**
+ * Regression: Agent.setModel / Agent.setApiKey must NOT carry a previous
+ * provider's default baseURL into the new provider's factory.
+ *
+ * Evidence (session 2492d6579b1d, see DB `interaction_logs.error api` row
+ * with metadata 'The supported API model names are deepseek-v4-pro or
+ * deepseek-v4-flash, but you passed deepseek-ai/DeepSeek-V4-Flash.'):
+ *
+ * Before the fix, switching defaultProvider from deepseek → siliconflow via
+ * the UI left this.baseURL = "https://api.deepseek.com" from startup. The
+ * setModel rebuild path constructed a SiliconflowStrategy factory but bound
+ * it to the DeepSeek apiBase, so requests landed at api.deepseek.com with a
+ * SiliconFlow-prefixed model id, which DeepSeek rejected with the literal
+ * error string above.
+ *
+ * This test exercises the public Agent surface to confirm the fix detects a
+ * stale "this is another provider's default apiBase" baseURL and drops it.
+ */
+import { afterEach, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { loadCatalog } from "../../models/registry.js";
+import { apiBaseFor } from "../../providers/endpoints.js";
+import { Agent } from "../orchestrator.js";
+describe("Agent provider switch — baseURL hygiene", () => {
+    beforeAll(async () => {
+        await loadCatalog();
+    });
+    beforeEach(() => {
+        // Tests run in-process with no real key persistence; skip session DB to
+        // keep the assertions on pure provider/URL state.
+        process.env.MUONROI_TEST_NO_PERSIST = "1";
+        process.env.MUONROI_TEST_NO_KEYCHAIN = "1";
+    });
+    afterEach(() => {
+        delete process.env.MUONROI_TEST_NO_PERSIST;
+        delete process.env.MUONROI_TEST_NO_KEYCHAIN;
+    });
+    it("setModel drops stale baseURL when switching to a different provider", () => {
+        const agent = new Agent("sk-test-deepseek", apiBaseFor("deepseek"), "deepseek-v4-flash", undefined, {
+            persistSession: false,
+        });
+        expect(agent.getProviderId()).toBe("deepseek");
+        expect(agent.baseURL).toBe(apiBaseFor("deepseek"));
+        agent.setModel("deepseek-ai/DeepSeek-V4-Flash");
+        expect(agent.getProviderId()).toBe("siliconflow");
+        // Stale DS apiBase must be dropped so the SF factory binds to SF's URL.
+        expect(agent.baseURL).toBeNull();
+    });
+    it("setModel preserves a genuine custom baseURL (not a known provider apiBase)", () => {
+        const customURL = "https://proxy.internal.example.com/v1";
+        const agent = new Agent("sk-test", customURL, "deepseek-v4-flash", undefined, {
+            persistSession: false,
+        });
+        expect(agent.baseURL).toBe(customURL);
+        agent.setModel("deepseek-ai/DeepSeek-V4-Flash");
+        // Custom URL doesn't match any known provider apiBase → kept as override.
+        expect(agent.baseURL).toBe(customURL);
+    });
+    it("setModel does NOT drop baseURL when staying on the same provider", () => {
+        const agent = new Agent("sk-test", apiBaseFor("siliconflow"), "alibaba/Qwen3-30B-A3B-Instruct-2507", undefined, {
+            persistSession: false,
+        });
+        expect(agent.getProviderId()).toBe("siliconflow");
+        agent.setModel("deepseek-ai/DeepSeek-V4-Flash");
+        expect(agent.getProviderId()).toBe("siliconflow");
+        expect(agent.baseURL).toBe(apiBaseFor("siliconflow"));
+    });
+    it("setApiKey drops a stale apiBase that targets a different provider", () => {
+        const agent = new Agent(undefined, undefined, "deepseek-ai/DeepSeek-V4-Flash", undefined, {
+            persistSession: false,
+        });
+        expect(agent.getProviderId()).toBe("siliconflow");
+        // Caller hands setApiKey a stale DeepSeek apiBase — must be dropped.
+        agent.setApiKey("sk-test", apiBaseFor("deepseek"));
+        expect(agent.baseURL).toBeNull();
+    });
+});
+//# sourceMappingURL=agent-base-url-switch.test.js.map

package/dist/src/orchestrator/__tests__/batch-turn-runner.test.js

@@ -5,8 +5,13 @@
 // the (stub) batch API. The Phase 0 batch stubs throw, so every successful
 // path through `run()` here goes via the catch-block — that's exactly what
 // we want to assert (transient retry + abort + recordUsage guard).
-import { describe, expect, it } from "vitest";
+import { beforeAll, describe, expect, it } from "vitest";
+import { getTestModels, getTestProviders } from "../../__test-helpers__/catalog-fixtures.js";
+import { loadCatalog } from "../../models/registry.js";
 import { BatchTurnRunner } from "../batch-turn-runner.js";
+beforeAll(async () => {
+    await loadCatalog();
+});
 function makeBashStub() {
     return {
         getCwd: () => process.cwd(),
@@ -69,6 +74,8 @@ function makeDeps(overrides = {}) {
     return { deps, counters };
 }
 function makeArgs(signal, providerStub) {
+    const testModels = getTestModels();
+    const testProviders = getTestProviders();
     return {
         userModelMessage: { role: "user", content: "hello" },
         observer: undefined,
@@ -76,8 +83,8 @@ function makeArgs(signal, providerStub) {
         subagents: [],
         system: "",
         runtime: {
-            modelId: "deepseek-ai/DeepSeek-V4-Flash",
-            modelInfo: { provider: "siliconflow", contextWindow: 131_072 },
+            modelId: testModels.fast,
+            modelInfo: { provider: testProviders.default, contextWindow: 131_072 },
             model: {},
             providerOptions: {},
             unsupportedParams: [],

package/dist/src/orchestrator/__tests__/cross-turn-dedup.test.js

@@ -13,10 +13,9 @@ describe("CrossTurnDedup", () => {
             dedup.beginTurn();
             const second = dedup.maybeDedup("read_file", payload);
             expect(second).not.toBeNull();
-            expect(second).toContain("identical to earlier turn");
-            expect(second).toContain("tool=read_file");
-            expect(second).toContain("turn=1");
-            expect(second).toContain("sha256=");
+            expect(second).toContain("[dup of");
+            expect(second).toContain("read_file");
+            expect(second).toContain("turn 1");
         });
         it("distinct large tool outputs do not collide on sha256-16", () => {
             // Two large strings differing only in last char must produce different
@@ -26,23 +25,19 @@ describe("CrossTurnDedup", () => {
             const dedup = new CrossTurnDedup({ minChars: 100 });
             dedup.beginTurn();
             const a = "A".repeat(2_000);
-            const b = "A".repeat(1_999) + "B";
+            const b = `${"A".repeat(1_999)}B`;
             expect(dedup.maybeDedup("read_file", a)).toBeNull();
             // Distinct content must NOT hit the cache.
             expect(dedup.maybeDedup("read_file", b)).toBeNull();
-            // Re-emitting `a` must produce a stub whose hash differs from the one
-            // that would be produced for `b` — i.e. distinct cache entries coexist.
+            // Two distinct payloads → two distinct cache entries (verified via
+            // cache size since the marker no longer embeds the hash post-G3).
+            expect(dedup.getStats().size).toBe(2);
+            // Re-emitting either payload now triggers a dedup hit.
             const stubA = dedup.maybeDedup("read_file", a);
             const stubB = dedup.maybeDedup("read_file", b);
             expect(stubA).not.toBeNull();
             expect(stubB).not.toBeNull();
-            const hashA = /sha256=([0-9a-f]+)/.exec(stubA)?.[1];
-            const hashB = /sha256=([0-9a-f]+)/.exec(stubB)?.[1];
-            expect(hashA).toBeDefined();
-            expect(hashB).toBeDefined();
-            expect(hashA).toHaveLength(16);
-            expect(hashB).toHaveLength(16);
-            expect(hashA).not.toBe(hashB);
+            expect(dedup.getStats().hits).toBe(2);
         });
         it("does not dedup different outputs", () => {
             const dedup = new CrossTurnDedup();
@@ -134,7 +129,7 @@ describe("CrossTurnDedup", () => {
             expect(first).toBe(payload);
             const second = (await exec({}));
             expect(second).not.toBe(payload);
-            expect(second).toContain("identical to earlier turn");
+            expect(second).toContain("[dup of");
         });
         it("dedups the .output field on object-shaped results", async () => {
             const dedup = new CrossTurnDedup({ minChars: 10 });
@@ -146,7 +141,34 @@ describe("CrossTurnDedup", () => {
             const first = (await exec({}));
             expect(first.output).toBe(payload);
             const second = (await exec({}));
-            expect(second.output).toContain("identical to earlier turn");
+            expect(second.output).toContain("[dup of");
+        });
+        it("dedups MCP content-array text parts across calls", async () => {
+            // MCP results are { type: "content", value: [{type:"text", text}] } — a
+            // shape the dedup previously ignored, so re-fetching the same MCP payload
+            // (e.g. the same docs page) re-billed full content every turn.
+            const dedup = new CrossTurnDedup({ minChars: 10 });
+            dedup.beginTurn();
+            const payload = "r".repeat(1_000);
+            const tools = {
+                mcp_docs__fetch: makeTool({ type: "content", value: [{ type: "text", text: payload }] }),
+            };
+            const wrapped = wrapToolSetWithDedup(tools, dedup);
+            const exec = wrapped.mcp_docs__fetch.execute;
+            const first = (await exec({}));
+            expect(first.value[0].text).toBe(payload);
+            const second = (await exec({}));
+            expect(second.value[0].text).toContain("[dup of");
+        });
+        it("leaves non-text MCP content parts (images) untouched", async () => {
+            const dedup = new CrossTurnDedup({ minChars: 10 });
+            dedup.beginTurn();
+            const image = { type: "image", data: "BASE64", mediaType: "image/png" };
+            const tools = { mcp_x__shot: makeTool({ type: "content", value: [image] }) };
+            const wrapped = wrapToolSetWithDedup(tools, dedup);
+            const exec = wrapped.mcp_x__shot.execute;
+            const out = (await exec({}));
+            expect(out.value[0]).toEqual(image);
         });
     });
 });

package/dist/src/orchestrator/__tests__/error-forensics.test.d.ts

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

package/dist/src/orchestrator/__tests__/error-forensics.test.js

@@ -0,0 +1,93 @@
+/**
+ * Forensics envelope for opaque provider 4xx errors.
+ *
+ * Background: 16 occurrences in interaction_logs of
+ *   "The parameter is invalid. Please check again."
+ * (siliconflow / DeepSeek-V4-Flash, 2026-05-13 → 2026-05-14) were logged with
+ * ONLY the friendly message. With nothing else captured — no status code,
+ * no response body, no request param names — the cause is unrecoverable
+ * without a repro. summarizeApiErrorForLog closes that gap.
+ *
+ * Test goals:
+ *   1. Wire-shape we WANT to persist (statusCode, urlHost, body trunc, param keys).
+ *   2. NEVER persist request param VALUES (might contain secrets / PII).
+ *   3. Cap response body so a 1MB error response can't bloat interaction_logs.
+ *   4. Identity null on non-APICallError so the helper is safe to call
+ *      unconditionally from the log site.
+ */
+import { APICallError } from "@ai-sdk/provider";
+import { describe, expect, it } from "vitest";
+import { summarizeApiErrorForLog } from "../error-utils.js";
+describe("summarizeApiErrorForLog", () => {
+    it("captures the wire envelope for an APICallError without leaking param values", () => {
+        const err = new APICallError({
+            message: "The parameter is invalid. Please check again.",
+            url: "https://api.siliconflow.com/v1/chat/completions",
+            requestBodyValues: {
+                model: "deepseek-ai/DeepSeek-V4-Flash",
+                messages: [{ role: "user", content: "secret prompt" }],
+                temperature: 0.7,
+                tools: [{ type: "function", function: { name: "read_file" } }],
+            },
+            statusCode: 400,
+            responseBody: '{"error":{"message":"The parameter is invalid. Please check again.","code":20015}}',
+            isRetryable: false,
+        });
+        const out = summarizeApiErrorForLog(err);
+        expect(out).not.toBeNull();
+        expect(out.statusCode).toBe(400);
+        expect(out.urlHost).toBe("api.siliconflow.com");
+        expect(out.responseBodyTrunc).toBe('{"error":{"message":"The parameter is invalid. Please check again.","code":20015}}');
+        // Keys ONLY — values must never reach the log.
+        expect(out.requestParamKeys).toEqual(["messages", "model", "temperature", "tools"]);
+        // Confirm no value leak by stringifying the whole envelope.
+        const serialized = JSON.stringify(out);
+        expect(serialized).not.toContain("secret prompt");
+        expect(serialized).not.toContain("DeepSeek-V4-Flash");
+        expect(serialized).not.toContain("read_file");
+        expect(out.isRetryable).toBe(false);
+    });
+    it("truncates response body over 1000 chars to keep interaction_logs bounded", () => {
+        const giantBody = `${"x".repeat(2_000)}`;
+        const err = new APICallError({
+            message: "rate limit",
+            url: "https://api.example.com/x",
+            requestBodyValues: {},
+            statusCode: 429,
+            responseBody: giantBody,
+        });
+        const out = summarizeApiErrorForLog(err);
+        expect(out).not.toBeNull();
+        expect(out.responseBodyTrunc.length).toBeLessThanOrEqual(1020);
+        expect(out.responseBodyTrunc.endsWith("…[truncated]")).toBe(true);
+    });
+    it("returns null for non-APICallError so the helper is safe to call unconditionally", () => {
+        expect(summarizeApiErrorForLog(new Error("plain"))).toBeNull();
+        expect(summarizeApiErrorForLog("string error")).toBeNull();
+        expect(summarizeApiErrorForLog(undefined)).toBeNull();
+    });
+    it("handles malformed URL without throwing — urlHost becomes undefined", () => {
+        const err = new APICallError({
+            message: "bad",
+            url: "not a url",
+            requestBodyValues: {},
+            statusCode: 500,
+        });
+        const out = summarizeApiErrorForLog(err);
+        expect(out).not.toBeNull();
+        expect(out.urlHost).toBeUndefined();
+        expect(out.statusCode).toBe(500);
+    });
+    it("handles non-object requestBodyValues without crashing — requestParamKeys becomes undefined", () => {
+        const err = new APICallError({
+            message: "x",
+            url: "https://api.example.com/x",
+            requestBodyValues: "raw json string", // pathological case
+            statusCode: 400,
+        });
+        const out = summarizeApiErrorForLog(err);
+        expect(out).not.toBeNull();
+        expect(out.requestParamKeys).toBeUndefined();
+    });
+});
+//# sourceMappingURL=error-forensics.test.js.map

package/dist/src/orchestrator/__tests__/flow-resume.test.js

@@ -18,7 +18,7 @@ async function makeTempDir(prefix) {
 }
 afterEach(async () => {
     for (const d of tempDirs) {
-        await rm(d, { recursive: true, force: true }).catch(() => { });
+        await rm(d, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }).catch(() => { });
     }
     tempDirs = [];
 });

package/dist/src/orchestrator/__tests__/humanize-api-error.test.d.ts

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

package/dist/src/orchestrator/__tests__/humanize-api-error.test.js

@@ -0,0 +1,68 @@
+/**
+ * P0 #2 — surface the ROUTED model/provider on account/auth/rate errors so a
+ * cryptic provider 402 ("Insufficient Balance") tells the user WHICH model it
+ * actually ran (e.g. a project-pinned deepseek model overriding their default)
+ * and how to fix it, instead of leaving them guessing.
+ */
+import { APICallError } from "@ai-sdk/provider";
+import { describe, expect, it } from "vitest";
+import { humanizeApiError } from "../error-utils.js";
+function apiErr(statusCode, responseBody) {
+    return new APICallError({
+        message: "provider error",
+        url: "https://api.deepseek.com/chat/completions",
+        requestBodyValues: { model: "deepseek-v4-flash" },
+        statusCode,
+        responseBody,
+        isRetryable: false,
+    });
+}
+describe("humanizeApiError — routing context (P0 #2)", () => {
+    it("adds routed model + provider + a balance hint on 402", () => {
+        const err = apiErr(402, '{"error":{"message":"Insufficient Balance"}}');
+        const msg = humanizeApiError(err, { modelId: "deepseek-v4-flash", providerId: "deepseek" });
+        expect(msg).toContain("Insufficient Balance");
+        expect(msg).toContain("deepseek-v4-flash");
+        expect(msg).toContain("deepseek");
+        expect(msg).toMatch(/-m /); // suggests switching model
+        expect(msg).toMatch(/balance|credit/i);
+    });
+    it("points to keys login on 401/403", () => {
+        const msg = humanizeApiError(apiErr(401, '{"error":{"message":"bad key"}}'), {
+            modelId: "gpt-5.4-mini",
+            providerId: "openai",
+        });
+        expect(msg).toContain("gpt-5.4-mini");
+        expect(msg).toMatch(/keys login/);
+    });
+    it("mentions rate limit + switch on 429", () => {
+        const msg = humanizeApiError(apiErr(429, '{"error":{"message":"slow down"}}'), {
+            modelId: "deepseek-v4-flash",
+            providerId: "deepseek",
+        });
+        expect(msg).toMatch(/rate.?limit/i);
+        expect(msg).toMatch(/-m /);
+    });
+    it("does NOT add a routing suffix on server-side 500 (not the user's routing)", () => {
+        const msg = humanizeApiError(apiErr(500, '{"error":{"message":"boom"}}'), {
+            modelId: "deepseek-v4-flash",
+            providerId: "deepseek",
+        });
+        expect(msg).not.toContain("routed to");
+        expect(msg).not.toContain("deepseek-v4-flash");
+    });
+    it("is unchanged when no context is supplied (backward compatible)", () => {
+        const err = apiErr(402, '{"error":{"message":"Insufficient Balance"}}');
+        const withoutCtx = humanizeApiError(err);
+        expect(withoutCtx).toBe("Insufficient Balance");
+        expect(withoutCtx).not.toContain("routed to");
+    });
+    it("flags balance even when status is unparsed but the body says so", () => {
+        // Some gateways surface the balance error without a clean statusCode.
+        const err = new Error("Insufficient Balance");
+        const msg = humanizeApiError(err, { modelId: "deepseek-v4-flash", providerId: "deepseek" });
+        expect(msg).toContain("deepseek-v4-flash");
+        expect(msg).toMatch(/balance|credit/i);
+    });
+});
+//# sourceMappingURL=humanize-api-error.test.js.map

package/dist/src/orchestrator/__tests__/message-processor.test.js

@@ -4,7 +4,8 @@
 // correctly and that the auto-council short-circuit + batch-api delegation
 // invariants hold without running a real LLM turn. The full streaming
 // behaviour is covered by tests/harness/cost-leak-{f1,g1,b4,c3}.spec.ts.
-import { describe, expect, it } from "vitest";
+import { beforeAll, describe, expect, it } from "vitest";
+import { loadCatalog } from "../../models/registry.js";
 import { MessageProcessor } from "../message-processor.js";
 function makeBashStub() {
     return {
@@ -20,6 +21,7 @@ function makeCouncilStub(extra = {}) {
         setContinuation: () => { },
         setLastSynthesis: () => { },
         resolveNonDisabledFallback: async () => ({ modelId: "deepseek-ai/DeepSeek-V4-Flash" }),
+        createQuestionResponder: () => async () => "",
         ...extra,
     };
 }
@@ -114,6 +116,9 @@ function makeDeps(overrides = {}) {
     };
 }
 describe("MessageProcessor — DI surface invariants", () => {
+    beforeAll(async () => {
+        await loadCatalog();
+    });
     it("constructs without throwing when given a valid deps bag", () => {
         const processor = new MessageProcessor(makeDeps());
         expect(processor).toBeInstanceOf(MessageProcessor);

package/dist/src/orchestrator/__tests__/read-path-budget.test.js

@@ -34,6 +34,38 @@ describe("ReadPathBudget", () => {
             expect(b.checkAndIncrement("read_file", "/a")).toBeNull();
         }
     });
+    it("notifyWrite resets counters for the same path across all tool names", () => {
+        const b = new ReadPathBudget(1);
+        expect(b.checkAndIncrement("read_file", "/a.ts")).toBeNull();
+        expect(b.checkAndIncrement("mcp__filesystem__read_text_file", "/a.ts")).toBeNull();
+        // Both tools are now at cap for /a.ts
+        expect(b.checkAndIncrement("read_file", "/a.ts")).not.toBeNull();
+        // Simulate a write to /a.ts — both counters must reset.
+        b.notifyWrite("/a.ts");
+        expect(b.checkAndIncrement("read_file", "/a.ts")).toBeNull();
+        expect(b.checkAndIncrement("mcp__filesystem__read_text_file", "/a.ts")).toBeNull();
+        expect(b.getStats().writeInvalidations).toBe(2);
+    });
+    it("notifyWrite normalizes path case + slashes", () => {
+        const b = new ReadPathBudget(1);
+        expect(b.checkAndIncrement("read_file", "C:\\Foo\\Bar.ts")).toBeNull();
+        expect(b.checkAndIncrement("read_file", "C:\\Foo\\Bar.ts")).not.toBeNull();
+        b.notifyWrite("c:/foo/bar.ts");
+        expect(b.checkAndIncrement("read_file", "C:\\Foo\\Bar.ts")).toBeNull();
+    });
+    it("notifyWrite does not touch counters for other paths", () => {
+        const b = new ReadPathBudget(1);
+        b.checkAndIncrement("read_file", "/a.ts");
+        b.checkAndIncrement("read_file", "/b.ts");
+        b.notifyWrite("/a.ts");
+        expect(b.checkAndIncrement("read_file", "/a.ts")).toBeNull(); // reset
+        expect(b.checkAndIncrement("read_file", "/b.ts")).not.toBeNull(); // still capped
+    });
+    it("notifyWrite is a no-op when cap=0 (budget disabled)", () => {
+        const b = new ReadPathBudget(0);
+        b.notifyWrite("/a.ts"); // should not throw
+        expect(b.getStats().writeInvalidations).toBe(0);
+    });
 });
 describe("isReadTool detection", () => {
     it.each([
@@ -81,14 +113,40 @@ describe("wrapToolSetWithReadBudget", () => {
         const r1 = await exec({ path: "/x" });
         const r2 = await exec({ path: "/x" });
         expect(r1).toBe("content of /x");
-        expect(r2).toMatchObject({});
+        // Stub is a string (per ReadPathBudget.checkAndIncrement JSDoc + impl) containing the guidance message.
+        // The wrapper returns it directly so the agent sees the explanation without extra object wrapping.
+        expect(typeof r2).toBe("string");
         expect(String(r2)).toContain("read budget exceeded");
         expect(calls).toEqual(["/x"]); // inner execute only fired once
     });
-    it("passes non-read tools through unchanged", () => {
+    it("passes neither-read-nor-write tools through unchanged", () => {
         const tool = makeReadTool(() => "nope");
-        const wrapped = wrapToolSetWithReadBudget({ write_file: tool }, new ReadPathBudget(1));
-        expect(wrapped.write_file).toBe(tool);
+        const wrapped = wrapToolSetWithReadBudget({ list_directory: tool }, new ReadPathBudget(1));
+        expect(wrapped.list_directory).toBe(tool);
+    });
+    it("wraps write_file/edit_file so post-write read counters reset", async () => {
+        const readCalls = [];
+        const writeCalls = [];
+        const readTool = makeReadTool(async (input) => {
+            const p = input.path;
+            readCalls.push(p);
+            return `content of ${p}`;
+        });
+        const writeTool = makeReadTool(async (input) => {
+            const p = input.path;
+            writeCalls.push(p);
+            return `wrote ${p}`;
+        });
+        const budget = new ReadPathBudget(1);
+        const wrapped = wrapToolSetWithReadBudget({ read_file: readTool, edit_file: writeTool }, budget);
+        const readExec = wrapped.read_file.execute;
+        const editExec = wrapped.edit_file.execute;
+        expect(await readExec({ path: "/foo.ts" })).toBe("content of /foo.ts");
+        expect(String(await readExec({ path: "/foo.ts" }))).toContain("read budget exceeded");
+        expect(await editExec({ path: "/foo.ts" })).toBe("wrote /foo.ts");
+        expect(await readExec({ path: "/foo.ts" })).toBe("content of /foo.ts");
+        expect(readCalls).toEqual(["/foo.ts", "/foo.ts"]);
+        expect(writeCalls).toEqual(["/foo.ts"]);
     });
     it("null budget returns original tool set by reference", () => {
         const tools = { read_file: {} };

package/dist/src/orchestrator/__tests__/retry-classifier.test.js

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
 import { classifyStreamError } from "../retry-classifier.js";
+import { STALL_ABORT_REASON } from "../stall-watchdog.js";
 describe("classifyStreamError", () => {
     it("classifies ECONNREFUSED as transient", () => {
         const err = new Error("connect ECONNREFUSED 127.0.0.1:443");
@@ -61,6 +62,15 @@ describe("classifyStreamError", () => {
         const result = classifyStreamError(err);
         expect(result.transient).toBe(false);
     });
+    it("classifies a provider-stall watchdog abort as NOT transient (no retry-storm)", () => {
+        // The stall watchdog aborts with DOMException(STALL_ABORT_REASON, "TimeoutError").
+        // It must NOT be retried — a stalled provider just stalls again, burning
+        // another full timeout of silence. Distinct from a generic AbortSignal.timeout().
+        const err = new DOMException(STALL_ABORT_REASON, "TimeoutError");
+        const result = classifyStreamError(err);
+        expect(result.transient).toBe(false);
+        expect(result.reason).toBe("provider-stall");
+    });
     it("classifies TimeoutError (AbortSignal.timeout) as transient", () => {
         const err = new DOMException("signal timed out", "TimeoutError");
         const result = classifyStreamError(err);