@mandujs/core 0.39.3 → 0.40.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.39.3",
+  "version": "0.40.1",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",

package/src/brain/__tests__/redactor.test.ts

@@ -0,0 +1,94 @@
+/**
+ * Tests for `packages/core/src/brain/redactor.ts`.
+ *
+ * Each test asserts BOTH invariants we care about:
+ *   1. The secret no longer appears verbatim in the redacted output.
+ *   2. A correctly-kinded `RedactionHit` shows up in the audit list.
+ *
+ * Regression guard — if someone relaxes a pattern to fix a false
+ * positive, the matching test here will fail before a key leaks.
+ */
+
+import { describe, it, expect } from "bun:test";
+import { redactSecrets, redact } from "../redactor";
+
+describe("redactSecrets — OpenAI-style keys", () => {
+  it("redacts sk-... keys and audits the hit", () => {
+    const secret = "sk-proj-ABCDEFGHIJKLMNOPQRSTUVWX";
+    const input = `Use key ${secret} to call.`;
+    const { redacted, hits } = redactSecrets(input);
+    expect(redacted).not.toContain(secret);
+    expect(redacted).toContain("[[REDACTED:openai-key]]");
+    expect(hits.length).toBeGreaterThanOrEqual(1);
+    const sampleContainsFullKey = hits.some((h) => h.sample.includes(secret));
+    expect(sampleContainsFullKey).toBe(false);
+  });
+});
+
+describe("redactSecrets — Bearer tokens", () => {
+  it("redacts Authorization: Bearer headers", () => {
+    const bearer = "Bearer eyJhbGciOiJIUzI1NiJ9abcdefghij.signature-blob";
+    const input = `curl -H 'Authorization: ${bearer}' api/host`;
+    const { redacted, hits } = redactSecrets(input);
+    expect(redacted).not.toContain(bearer);
+    expect(hits.some((h) => h.kind === "bearer-token")).toBe(true);
+  });
+});
+
+describe("redactSecrets — .env references", () => {
+  it("redacts bare .env and .env.production references", () => {
+    const input = "Credentials live in .env and overrides in .env.production.";
+    const { redacted, hits } = redactSecrets(input);
+    expect(redacted).not.toContain(" .env ");
+    expect(redacted).not.toContain(".env.production");
+    expect(hits.filter((h) => h.kind === "env-ref").length).toBeGreaterThanOrEqual(
+      2,
+    );
+  });
+});
+
+describe("redactSecrets — KEY=VALUE assignments", () => {
+  it("redacts API_KEY=... assignments in-place", () => {
+    const input = `OPENAI_API_KEY=sk-fake1234567890abcdef\nDEBUG=1`;
+    const { redacted, hits } = redactSecrets(input);
+    // The whole assignment collapses into a single marker.
+    expect(redacted).toContain("[[REDACTED:api-key-assignment]]");
+    expect(redacted).toContain("DEBUG=1"); // untouched
+    expect(hits.some((h) => h.kind === "api-key-assignment")).toBe(true);
+  });
+});
+
+describe("redactSecrets — multi-match, non-overlapping", () => {
+  it("redacts multiple secrets in a single payload", () => {
+    const gh = "ghp_1234567890abcdefghijklmnopqrstuvwxyz";
+    const aws = "AKIAIOSFODNN7EXAMPLE";
+    const input = `GitHub: ${gh}\nAWS: ${aws}\nNothing here.`;
+    const { redacted, hits } = redactSecrets(input);
+    expect(redacted).not.toContain(gh);
+    expect(redacted).not.toContain(aws);
+    expect(hits.some((h) => h.kind === "github-token")).toBe(true);
+    expect(hits.some((h) => h.kind === "aws-key")).toBe(true);
+  });
+});
+
+describe("redactSecrets — clean input passthrough", () => {
+  it("returns the input unchanged and an empty hit list when nothing matches", () => {
+    const input = "No secrets, just a normal message about the weather.";
+    const { redacted, hits } = redactSecrets(input);
+    expect(redacted).toBe(input);
+    expect(hits.length).toBe(0);
+  });
+});
+
+describe("redact() convenience", () => {
+  it("returns the redacted string directly", () => {
+    const secret = "sk-proj-THISISAFAKEKEY1234567890";
+    const out = redact(`token: ${secret}`);
+    expect(out).not.toContain(secret);
+  });
+
+  it("returns the original string when nothing matches", () => {
+    const input = "hello world";
+    expect(redact(input)).toBe(input);
+  });
+});

package/src/brain/adapters/__tests__/_helpers.ts

@@ -0,0 +1,64 @@
+/**
+ * Shared test fixtures for brain adapter tests.
+ *
+ * Every helper here stays framework-free so the unit tests do not pull
+ * in the real network / keychain / filesystem paths.
+ */
+
+import {
+  CredentialStore,
+  type CredentialBackend,
+  type StoredToken,
+} from "../../credentials";
+import type { HttpClient, OAuthEndpoints } from "../oauth-flow";
+
+/**
+ * In-memory credential store that satisfies `CredentialBackend`. We
+ * construct a regular `CredentialStore` around it so the adapters see
+ * the exact public API (.load/.save/.delete/.list/.touch/.backendName).
+ */
+export function makeMemoryStore(
+  seed: Record<string, StoredToken> = {},
+): CredentialStore {
+  const map = new Map<string, StoredToken>(Object.entries(seed));
+  const backend: CredentialBackend = {
+    name: "memory",
+    async save(provider, token) {
+      map.set(provider, token);
+    },
+    async load(provider) {
+      return map.get(provider) ?? null;
+    },
+    async delete(provider) {
+      map.delete(provider);
+    },
+    async list() {
+      return [...map.keys()];
+    },
+  };
+  return new CredentialStore(backend);
+}
+
+/**
+ * Build a stub `HttpClient` whose behavior is driven by a response
+ * factory. The factory receives the URL and RequestInit and returns a
+ * `Response`. Tests use this to simulate 401 sequences, token
+ * refresh, etc. without spinning up a live server.
+ */
+export function makeStubHttpClient(
+  respond: (url: string, init?: RequestInit) => Response | Promise<Response>,
+): HttpClient {
+  return async (url, init) => respond(url, init);
+}
+
+export const FAKE_ENDPOINTS: OAuthEndpoints = {
+  authorizationUrl: "https://example.test/oauth/authorize",
+  tokenUrl: "https://example.test/oauth/token",
+};
+
+export function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}

package/src/brain/adapters/__tests__/anthropic-oauth.test.ts

@@ -0,0 +1,196 @@
+/**
+ * Tests for `packages/core/src/brain/adapters/anthropic-oauth.ts`.
+ *
+ * Mirror-image of the OpenAI adapter test file. We reuse the shared
+ * in-memory credential store fixture + stub HTTP client, and exercise
+ * the Messages-API-specific quirks (system split, 401 refresh,
+ * stop_sequences mapping).
+ */
+
+import { describe, it, expect, beforeEach } from "bun:test";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  AnthropicOAuthAdapter,
+  ANTHROPIC_DEFAULT_MODEL,
+} from "../anthropic-oauth";
+import {
+  makeMemoryStore,
+  makeStubHttpClient,
+  FAKE_ENDPOINTS,
+  jsonResponse,
+} from "./_helpers";
+import type { StoredToken } from "../../credentials";
+
+let tmp: string;
+
+beforeEach(async () => {
+  tmp = await fs.mkdtemp(path.join(os.tmpdir(), "mandu-anthropic-adapter-"));
+});
+
+function seedToken(): StoredToken {
+  return {
+    access_token: "seed-access",
+    refresh_token: "seed-refresh",
+    expires_at: Math.floor(Date.now() / 1000) + 3600,
+    default_model: ANTHROPIC_DEFAULT_MODEL,
+    provider: "anthropic",
+  };
+}
+
+describe("AnthropicOAuthAdapter — shape + defaults", () => {
+  it("reports adapter name anthropic-oauth and default Haiku model", async () => {
+    const store = makeMemoryStore({ anthropic: seedToken() });
+    const adapter = new AnthropicOAuthAdapter({
+      credentialStore: store,
+      projectRoot: tmp,
+      endpoints: FAKE_ENDPOINTS,
+      httpClient: makeStubHttpClient(() => jsonResponse({ content: [] })),
+      skipConsent: true,
+    });
+    expect(adapter.name).toBe("anthropic-oauth");
+    expect(adapter.model).toBe(ANTHROPIC_DEFAULT_MODEL);
+    const status = await adapter.checkStatus();
+    expect(status.available).toBe(true);
+    expect(status.model).toBe(ANTHROPIC_DEFAULT_MODEL);
+  });
+});
+
+describe("AnthropicOAuthAdapter — redaction invariant", () => {
+  it("redacts secrets and records an audit line", async () => {
+    const store = makeMemoryStore({ anthropic: seedToken() });
+    let capturedBody = "";
+    const http = makeStubHttpClient((_url, init) => {
+      capturedBody = (init?.body as string) ?? "";
+      return jsonResponse({
+        content: [{ type: "text", text: "ok" }],
+        usage: { input_tokens: 5, output_tokens: 3 },
+      });
+    });
+    const adapter = new AnthropicOAuthAdapter({
+      credentialStore: store,
+      projectRoot: tmp,
+      endpoints: FAKE_ENDPOINTS,
+      httpClient: http,
+      skipConsent: true,
+    });
+    const secret = "ghp_1234567890abcdefghijklmnopqrstuvwxyz";
+    const res = await adapter.complete([
+      { role: "user", content: `Investigate token ${secret}.` },
+    ]);
+    expect(res.content).toBe("ok");
+    expect(capturedBody).not.toContain(secret);
+    expect(capturedBody).toContain("[[REDACTED:");
+    const auditPath = path.join(tmp, ".mandu", "brain-redactions.jsonl");
+    const contents = await fs.readFile(auditPath, "utf8");
+    expect(contents).toContain("anthropic");
+  });
+});
+
+describe("AnthropicOAuthAdapter — 401 fallback chain", () => {
+  it("tries silent refresh then scrubs the token on persistent 401", async () => {
+    const store = makeMemoryStore({ anthropic: seedToken() });
+    let calls = 0;
+    const http = makeStubHttpClient((url) => {
+      calls += 1;
+      if (url === FAKE_ENDPOINTS.tokenUrl) {
+        return jsonResponse({
+          access_token: "refreshed",
+          refresh_token: "r2",
+          expires_in: 3600,
+        });
+      }
+      return new Response("unauthorized", { status: 401 });
+    });
+    const adapter = new AnthropicOAuthAdapter({
+      credentialStore: store,
+      projectRoot: tmp,
+      endpoints: FAKE_ENDPOINTS,
+      httpClient: http,
+      skipConsent: true,
+    });
+    const res = await adapter.complete([{ role: "user", content: "ping" }]);
+    expect(res.content).toBe("");
+    expect(calls).toBe(3);
+    expect(await store.load("anthropic")).toBeNull();
+  });
+});
+
+describe("AnthropicOAuthAdapter — system message split", () => {
+  it("pulls leading system messages into the `system` field and sends only user/assistant turns in messages[]", async () => {
+    const store = makeMemoryStore({ anthropic: seedToken() });
+    let capturedBody = "";
+    const http = makeStubHttpClient((_url, init) => {
+      capturedBody = (init?.body as string) ?? "";
+      return jsonResponse({
+        content: [{ type: "text", text: "answer" }],
+        usage: { input_tokens: 1, output_tokens: 1 },
+      });
+    });
+    const adapter = new AnthropicOAuthAdapter({
+      credentialStore: store,
+      projectRoot: tmp,
+      endpoints: FAKE_ENDPOINTS,
+      httpClient: http,
+      skipConsent: true,
+    });
+    await adapter.complete([
+      { role: "system", content: "You are a helpful assistant." },
+      { role: "user", content: "Hi" },
+    ]);
+    const parsed = JSON.parse(capturedBody);
+    expect(parsed.system).toBe("You are a helpful assistant.");
+    expect(parsed.messages).toEqual([{ role: "user", content: "Hi" }]);
+  });
+});
+
+describe("AnthropicOAuthAdapter — telemetryOptOut honored via resolver contract", () => {
+  it("returns empty completion when consent is declined (simulates opt-out UX)", async () => {
+    const store = makeMemoryStore({ anthropic: seedToken() });
+    let dispatched = false;
+    const http = makeStubHttpClient(() => {
+      dispatched = true;
+      return jsonResponse({ content: [{ type: "text", text: "nope" }] });
+    });
+    const adapter = new AnthropicOAuthAdapter({
+      credentialStore: store,
+      projectRoot: tmp,
+      endpoints: FAKE_ENDPOINTS,
+      httpClient: http,
+      consentDeps: {
+        ask: async () => "N",
+        write: () => {},
+        env: {} as NodeJS.ProcessEnv,
+      },
+    });
+    const res = await adapter.complete([{ role: "user", content: "hi" }]);
+    expect(res.content).toBe("");
+    expect(dispatched).toBe(false);
+  });
+});
+
+describe("AnthropicOAuthAdapter — model override flows into request", () => {
+  it("uses overridden model in the outgoing body", async () => {
+    const store = makeMemoryStore({ anthropic: seedToken() });
+    let capturedBody = "";
+    const http = makeStubHttpClient((_url, init) => {
+      capturedBody = (init?.body as string) ?? "";
+      return jsonResponse({
+        content: [{ type: "text", text: "ok" }],
+        usage: { input_tokens: 1, output_tokens: 1 },
+      });
+    });
+    const adapter = new AnthropicOAuthAdapter({
+      credentialStore: store,
+      projectRoot: tmp,
+      endpoints: FAKE_ENDPOINTS,
+      httpClient: http,
+      skipConsent: true,
+      model: "claude-sonnet-4-5-20250929",
+    });
+    await adapter.complete([{ role: "user", content: "hi" }]);
+    const parsed = JSON.parse(capturedBody);
+    expect(parsed.model).toBe("claude-sonnet-4-5-20250929");
+  });
+});

package/src/brain/adapters/__tests__/openai-oauth.test.ts

@@ -0,0 +1,202 @@
+/**
+ * Tests for `packages/core/src/brain/adapters/openai-oauth.ts`.
+ *
+ * The adapter is fully isolatable via its options surface:
+ *   - `credentialStore` — in-memory fixture (no keychain calls).
+ *   - `httpClient`      — stubbed fetch (no network).
+ *   - `endpoints`       — fake OAuth endpoints.
+ *   - `skipConsent`     — bypass the interactive consent prompt.
+ *   - `projectRoot`     — per-test tmpdir so redaction audit log is
+ *                         sandboxed.
+ */
+
+import { describe, it, expect, beforeEach } from "bun:test";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  OpenAIOAuthAdapter,
+  OPENAI_DEFAULT_MODEL,
+} from "../openai-oauth";
+import {
+  makeMemoryStore,
+  makeStubHttpClient,
+  FAKE_ENDPOINTS,
+  jsonResponse,
+} from "./_helpers";
+import type { StoredToken } from "../../credentials";
+
+let tmp: string;
+
+beforeEach(async () => {
+  tmp = await fs.mkdtemp(path.join(os.tmpdir(), "mandu-openai-adapter-"));
+});
+
+function seedToken(): StoredToken {
+  return {
+    access_token: "seed-access",
+    refresh_token: "seed-refresh",
+    expires_at: Math.floor(Date.now() / 1000) + 3600,
+    default_model: OPENAI_DEFAULT_MODEL,
+    provider: "openai",
+  };
+}
+
+describe("OpenAIOAuthAdapter — shape + defaults", () => {
+  it("reports default model gpt-5.4 and adapter name openai-oauth", async () => {
+    const store = makeMemoryStore({ openai: seedToken() });
+    const adapter = new OpenAIOAuthAdapter({
+      credentialStore: store,
+      projectRoot: tmp,
+      endpoints: FAKE_ENDPOINTS,
+      httpClient: makeStubHttpClient(() => new Response("ok")),
+      skipConsent: true,
+    });
+    expect(adapter.name).toBe("openai-oauth");
+    expect(adapter.model).toBe(OPENAI_DEFAULT_MODEL);
+    const status = await adapter.checkStatus();
+    expect(status.available).toBe(true);
+    expect(status.model).toBe(OPENAI_DEFAULT_MODEL);
+  });
+});
+
+describe("OpenAIOAuthAdapter — redaction invariant", () => {
+  it("never transmits detected secrets in the chat body and writes an audit entry", async () => {
+    const store = makeMemoryStore({ openai: seedToken() });
+    let captured = "";
+    const http = makeStubHttpClient((_url, init) => {
+      captured = (init?.body as string) ?? "";
+      return jsonResponse({
+        choices: [{ message: { content: "ok" } }],
+        usage: { prompt_tokens: 5, completion_tokens: 3, total_tokens: 8 },
+      });
+    });
+
+    const adapter = new OpenAIOAuthAdapter({
+      credentialStore: store,
+      projectRoot: tmp,
+      endpoints: FAKE_ENDPOINTS,
+      httpClient: http,
+      skipConsent: true,
+    });
+
+    const secret = "sk-proj-SECRET1234567890ABCDEFGH";
+    const res = await adapter.complete([
+      { role: "user", content: `Analyze this: key=${secret}` },
+    ]);
+
+    expect(res.content).toBe("ok");
+    expect(captured).not.toContain(secret);
+    expect(captured).toContain("[[REDACTED:");
+
+    const auditPath = path.join(tmp, ".mandu", "brain-redactions.jsonl");
+    const auditContents = await fs.readFile(auditPath, "utf8");
+    expect(auditContents).toContain("openai");
+    expect(auditContents).not.toContain(secret);
+  });
+});
+
+describe("OpenAIOAuthAdapter — 401 fallback chain", () => {
+  it("attempts silent refresh once, then returns empty and scrubs the token on persistent 401", async () => {
+    const store = makeMemoryStore({ openai: seedToken() });
+    let calls = 0;
+    const http = makeStubHttpClient((url) => {
+      calls += 1;
+      if (url === FAKE_ENDPOINTS.tokenUrl) {
+        // Refresh endpoint — hand back a new access_token.
+        return jsonResponse({
+          access_token: "refreshed-access",
+          refresh_token: "new-refresh",
+          expires_in: 3600,
+        });
+      }
+      // Chat endpoint — always 401.
+      return new Response("unauthorized", { status: 401 });
+    });
+
+    const adapter = new OpenAIOAuthAdapter({
+      credentialStore: store,
+      projectRoot: tmp,
+      endpoints: FAKE_ENDPOINTS,
+      httpClient: http,
+      skipConsent: true,
+    });
+
+    const res = await adapter.complete([{ role: "user", content: "ping" }]);
+    expect(res.content).toBe("");
+    // Expect 3 calls: chat(401) → refresh(200) → chat(401) → scrub.
+    expect(calls).toBe(3);
+    expect(await store.load("openai")).toBeNull();
+  });
+});
+
+describe("OpenAIOAuthAdapter — no-token → empty completion (not strict)", () => {
+  it("returns empty completion when no token is stored and strict=false", async () => {
+    const store = makeMemoryStore();
+    const adapter = new OpenAIOAuthAdapter({
+      credentialStore: store,
+      projectRoot: tmp,
+      endpoints: FAKE_ENDPOINTS,
+      httpClient: makeStubHttpClient(() =>
+        jsonResponse({
+          choices: [{ message: { content: "should-not-run" } }],
+        }),
+      ),
+      skipConsent: true,
+    });
+    const res = await adapter.complete([{ role: "user", content: "hi" }]);
+    expect(res.content).toBe("");
+    expect(res.usage?.totalTokens).toBe(0);
+    const status = await adapter.checkStatus();
+    expect(status.available).toBe(false);
+  });
+});
+
+describe("OpenAIOAuthAdapter — consent decline short-circuits transmission", () => {
+  it("returns empty completion and never dispatches the chat call when consent is declined", async () => {
+    const store = makeMemoryStore({ openai: seedToken() });
+    let dispatched = false;
+    const http = makeStubHttpClient(() => {
+      dispatched = true;
+      return jsonResponse({ choices: [{ message: { content: "x" } }] });
+    });
+    const adapter = new OpenAIOAuthAdapter({
+      credentialStore: store,
+      projectRoot: tmp,
+      endpoints: FAKE_ENDPOINTS,
+      httpClient: http,
+      consentDeps: {
+        ask: async () => "n",
+        write: () => {},
+        env: {} as NodeJS.ProcessEnv,
+      },
+    });
+    const res = await adapter.complete([{ role: "user", content: "hi" }]);
+    expect(res.content).toBe("");
+    expect(dispatched).toBe(false);
+  });
+});
+
+describe("OpenAIOAuthAdapter — model override flows through to the wire body", () => {
+  it("uses the configured model in the request payload", async () => {
+    const store = makeMemoryStore({ openai: seedToken() });
+    let capturedBody = "";
+    const http = makeStubHttpClient((_url, init) => {
+      capturedBody = (init?.body as string) ?? "";
+      return jsonResponse({
+        choices: [{ message: { content: "ok" } }],
+        usage: { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 },
+      });
+    });
+    const adapter = new OpenAIOAuthAdapter({
+      credentialStore: store,
+      projectRoot: tmp,
+      endpoints: FAKE_ENDPOINTS,
+      httpClient: http,
+      skipConsent: true,
+      model: "gpt-4o",
+    });
+    await adapter.complete([{ role: "user", content: "hello" }]);
+    expect(capturedBody).toContain('"model":"gpt-4o"');
+  });
+});

package/src/brain/adapters/__tests__/resolver.test.ts

@@ -0,0 +1,122 @@
+/**
+ * Tests for `resolveBrainAdapter()` in `adapters/index.ts`.
+ *
+ * Priority order under `adapter: "auto"`:
+ *   1. openai-oauth when token present
+ *   2. anthropic-oauth when token present
+ *   3. ollama when daemon reachable
+ *   4. template otherwise
+ *
+ * `telemetryOptOut: true` disables every cloud tier.
+ */
+
+import { describe, it, expect } from "bun:test";
+import { resolveBrainAdapter } from "../index";
+import { makeMemoryStore } from "./_helpers";
+import type { StoredToken } from "../../credentials";
+
+function openaiToken(): StoredToken {
+  return { access_token: "oa", provider: "openai" };
+}
+function anthropicToken(): StoredToken {
+  return { access_token: "an", provider: "anthropic" };
+}
+
+describe("resolveBrainAdapter — priority order", () => {
+  it("picks openai first when both cloud tokens + ollama are available", async () => {
+    const store = makeMemoryStore({
+      openai: openaiToken(),
+      anthropic: anthropicToken(),
+    });
+    const res = await resolveBrainAdapter({
+      adapter: "auto",
+      credentialStore: store,
+      probeOllama: async () => true,
+    });
+    expect(res.resolved).toBe("openai");
+    expect(res.adapter.name).toBe("openai-oauth");
+  });
+
+  it("falls to anthropic when only anthropic token present", async () => {
+    const store = makeMemoryStore({ anthropic: anthropicToken() });
+    const res = await resolveBrainAdapter({
+      adapter: "auto",
+      credentialStore: store,
+      probeOllama: async () => true,
+    });
+    expect(res.resolved).toBe("anthropic");
+    expect(res.adapter.name).toBe("anthropic-oauth");
+  });
+
+  it("falls to ollama when no cloud tokens but daemon is alive", async () => {
+    const store = makeMemoryStore();
+    const res = await resolveBrainAdapter({
+      adapter: "auto",
+      credentialStore: store,
+      probeOllama: async () => true,
+    });
+    expect(res.resolved).toBe("ollama");
+    expect(res.adapter.name).toBe("ollama");
+  });
+
+  it("falls to template when nothing is reachable", async () => {
+    const store = makeMemoryStore();
+    const res = await resolveBrainAdapter({
+      adapter: "auto",
+      credentialStore: store,
+      probeOllama: async () => false,
+    });
+    expect(res.resolved).toBe("template");
+    expect(res.adapter.name).toBe("noop");
+  });
+});
+
+describe("resolveBrainAdapter — telemetryOptOut", () => {
+  it("skips cloud tiers even when tokens exist", async () => {
+    const store = makeMemoryStore({
+      openai: openaiToken(),
+      anthropic: anthropicToken(),
+    });
+    const res = await resolveBrainAdapter({
+      adapter: "auto",
+      telemetryOptOut: true,
+      credentialStore: store,
+      probeOllama: async () => true,
+    });
+    expect(res.resolved).toBe("ollama");
+  });
+
+  it("falls to template when telemetryOptOut is true and ollama is down", async () => {
+    const store = makeMemoryStore({ openai: openaiToken() });
+    const res = await resolveBrainAdapter({
+      adapter: "auto",
+      telemetryOptOut: true,
+      credentialStore: store,
+      probeOllama: async () => false,
+    });
+    expect(res.resolved).toBe("template");
+  });
+});
+
+describe("resolveBrainAdapter — explicit pins degrade gracefully", () => {
+  it("explicit 'openai' without a token degrades to template (does not throw)", async () => {
+    const store = makeMemoryStore();
+    const res = await resolveBrainAdapter({
+      adapter: "openai",
+      credentialStore: store,
+    });
+    expect(res.resolved).toBe("template");
+    expect(res.reason).toContain("no token");
+  });
+
+  it("explicit 'anthropic' with telemetryOptOut forces template", async () => {
+    const store = makeMemoryStore({ anthropic: anthropicToken() });
+    const res = await resolveBrainAdapter({
+      adapter: "anthropic",
+      telemetryOptOut: true,
+      credentialStore: store,
+    });
+    expect(res.resolved).toBe("template");
+    expect(res.reason).toContain("telemetryOptOut");
+  });
+});