@circuitwall/jarela 2.2.1 → 2.4.0

package/lib/lifecycle/surface-collect.ts

@@ -0,0 +1,64 @@
+/**
+ * Collects the live model-facing surface (see surface-snapshot.ts). Imports
+ * the agent runtime, so callers must point JARELA_DB_DIR at a scratch
+ * directory first. Used only by the release changeset generator and its
+ * tests — never by the running app.
+ */
+import { toJsonSchema } from "@langchain/core/utils/json_schema";
+import { allBuiltins } from "@/lib/tools";
+import { listStaticPrompts } from "@/lib/agents/prompt-registry";
+import { buildVariants } from "@/lib/agents/prompt-variants";
+import {
+  SURFACE_SNAPSHOT_SCHEMA_VERSION,
+  splitSystemPromptSections,
+  type SurfacePrompt,
+  type SurfaceSnapshot,
+  type SurfaceTool,
+} from "./surface-snapshot";
+
+const SYSTEM_PROMPT_SOURCE = "lib/agents/prepare/system-prompt.ts";
+/** Richest variant first so shared sections keep their fullest form. */
+const VARIANT_PRIORITY = ["pinned-tools-all-bound", "delivery-channel", "proxy-only-and-provider-cap", "minimal-agent"];
+
+function sortedRecord<T>(record: Record<string, T>): Record<string, T> {
+  return Object.fromEntries(Object.entries(record).sort(([a], [b]) => a.localeCompare(b)));
+}
+
+export async function collectSurfaceSnapshot(version: string): Promise<SurfaceSnapshot> {
+  const prompts: Record<string, SurfacePrompt> = {};
+  for (const prompt of listStaticPrompts()) {
+    prompts[`static.${prompt.id}`] = { source: prompt.source, text: prompt.text };
+  }
+
+  const variants = await buildVariants();
+  const rank = (id: string) => {
+    const index = VARIANT_PRIORITY.indexOf(id);
+    return index === -1 ? VARIANT_PRIORITY.length : index;
+  };
+  for (const variant of [...variants].sort((a, b) => rank(a.id) - rank(b.id))) {
+    for (const [title, text] of Object.entries(splitSystemPromptSections(variant.prompt))) {
+      prompts[`system.${title}`] ??= { source: SYSTEM_PROMPT_SOURCE, text };
+    }
+  }
+
+  const tools: Record<string, SurfaceTool> = {};
+  for (const tool of allBuiltins()) {
+    let parameters: unknown;
+    try {
+      parameters = toJsonSchema(tool.schema as Parameters<typeof toJsonSchema>[0]);
+    } catch {
+      parameters = {};
+    }
+    if (parameters && typeof parameters === "object") {
+      delete (parameters as Record<string, unknown>).$schema;
+    }
+    tools[tool.name] = { description: tool.description ?? "", parameters };
+  }
+
+  return {
+    schema_version: SURFACE_SNAPSHOT_SCHEMA_VERSION,
+    version,
+    prompts: sortedRecord(prompts),
+    tools: sortedRecord(tools),
+  };
+}

package/lib/lifecycle/surface-snapshot.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it } from "vitest";
+import { diffPrompts, diffTools, splitSystemPromptSections } from "./surface-snapshot";
+
+const objectSchema = (properties: Record<string, unknown>, required: string[] = []) => ({
+  type: "object",
+  properties,
+  required,
+});
+
+describe("splitSystemPromptSections", () => {
+  it("splits on section headers and drops host- and time-dependent content", () => {
+    const sections = splitSystemPromptSections([
+      "intro line",
+      "--- Tool usage SOP ---",
+      "1. Use tools.",
+      "<!-- jarela:dynamic -->",
+      "--- Host environment ---",
+      "OS: win32",
+      "--- System signals ---",
+      "[]",
+      "--- Enabled tools ---",
+      "Current time: 2026-01-01T00:00:00Z (UTC).",
+      "Current local date and time: 2026-01-01 01:00",
+      "- web_search",
+    ].join("\n"));
+    expect(sections).toEqual({
+      Preamble: "intro line",
+      "Tool usage SOP": "1. Use tools.",
+      "Enabled tools": "- web_search",
+    });
+  });
+});
+
+describe("diffPrompts", () => {
+  it("reports line-level additions and removals and ignores whitespace-only edits", () => {
+    const prev = {
+      a: { source: "a.ts", text: "keep\nold rule" },
+      b: { source: "b.ts", text: "same" },
+      gone: { source: "g.ts", text: "bye" },
+    };
+    const next = {
+      a: { source: "a.ts", text: "keep\nnew rule" },
+      b: { source: "b.ts", text: "  same  \n" },
+      fresh: { source: "f.ts", text: "hello" },
+    };
+    expect(diffPrompts(prev, next)).toEqual([
+      { id: "a", source: "a.ts", change: "changed", added_lines: ["new rule"], removed_lines: ["old rule"], omitted_lines: 0 },
+      { id: "fresh", source: "f.ts", change: "added", added_lines: [], removed_lines: [], omitted_lines: 0 },
+      { id: "gone", source: "g.ts", change: "removed", added_lines: [], removed_lines: [], omitted_lines: 0 },
+    ]);
+  });
+
+  it("caps excerpts and counts the omitted lines", () => {
+    const lines = Array.from({ length: 20 }, (_, i) => `line ${i}`).join("\n");
+    const [change] = diffPrompts({ p: { source: "p.ts", text: "x" } }, { p: { source: "p.ts", text: lines } });
+    expect(change.added_lines).toHaveLength(12);
+    expect(change.omitted_lines).toBe(8);
+  });
+});
+
+describe("diffTools", () => {
+  it("classifies parameter, requirement, and description changes", () => {
+    const prev = {
+      t: { description: "Old.", parameters: objectSchema({ a: { type: "string" }, b: { type: "number" }, gone: {} }, ["a"]) },
+      same: { description: "Same.", parameters: objectSchema({ q: { type: "string" } }) },
+    };
+    const next = {
+      t: { description: "New.", parameters: objectSchema({ a: { type: "string" }, b: { type: "string" }, c: {} }, ["a", "c"]) },
+      same: { description: "Same.", parameters: objectSchema({ q: { type: "string" } }) },
+    };
+    expect(diffTools(prev, next)).toEqual([{
+      name: "t",
+      change: "changed",
+      description_changed: true,
+      description: "New.",
+      previous_description: "Old.",
+      params_added: ["c"],
+      params_removed: ["gone"],
+      params_changed: ["b"],
+      required_added: ["c"],
+      required_removed: [],
+    }]);
+  });
+
+  it("treats property order differences as unchanged", () => {
+    const prev = { t: { description: "d", parameters: objectSchema({ a: { type: "string", description: "x" } }) } };
+    const next = { t: { description: "d", parameters: objectSchema({ a: { description: "x", type: "string" } }) } };
+    expect(diffTools(prev, next)).toEqual([]);
+  });
+
+  it("records added and removed tools", () => {
+    const tool = { description: "T.", parameters: objectSchema({ a: {} }, ["a"]) };
+    expect(diffTools({ old: tool }, { added: tool })).toEqual([
+      {
+        name: "added", change: "added", description_changed: false, description: "T.",
+        params_added: ["a"], params_removed: [], params_changed: [], required_added: ["a"], required_removed: [],
+      },
+      {
+        name: "old", change: "removed", description_changed: false,
+        params_added: [], params_removed: [], params_changed: [], required_added: [], required_removed: [],
+      },
+    ]);
+  });
+});

package/lib/lifecycle/surface-snapshot.ts

@@ -0,0 +1,210 @@
+/**
+ * The model-facing surface of a Jarela release: every prompt text Jarela
+ * sends and every built-in tool's description and parameter schema. Release
+ * changesets diff two snapshots so version adoption can tell which user
+ * instructions, skills, settings, and scheduled prompts may need adapting.
+ * Pure functions only — collection lives in surface-collect.ts.
+ */
+
+export const SURFACE_SNAPSHOT_SCHEMA_VERSION = 1;
+
+export interface SurfacePrompt {
+  source: string;
+  text: string;
+}
+
+export interface SurfaceTool {
+  description: string;
+  parameters: unknown;
+}
+
+export interface SurfaceSnapshot {
+  schema_version: number;
+  version: string;
+  prompts: Record<string, SurfacePrompt>;
+  tools: Record<string, SurfaceTool>;
+}
+
+export type SurfaceChangeKind = "added" | "removed" | "changed";
+
+export interface PromptChange {
+  id: string;
+  source: string;
+  change: SurfaceChangeKind;
+  added_lines: string[];
+  removed_lines: string[];
+  /** Lines beyond the excerpt cap, so readers know the excerpt is partial. */
+  omitted_lines: number;
+}
+
+export interface ToolChange {
+  name: string;
+  change: SurfaceChangeKind;
+  description_changed: boolean;
+  description?: string;
+  previous_description?: string;
+  params_added: string[];
+  params_removed: string[];
+  params_changed: string[];
+  required_added: string[];
+  required_removed: string[];
+}
+
+export interface SurfaceDelta {
+  prompts: PromptChange[];
+  tools: ToolChange[];
+}
+
+const SECTION_HEADER = /^--- (.+) ---$/;
+/** Sections whose content depends on the host machine or the moment of collection. */
+const VOLATILE_SECTIONS = new Set(["Host environment", "System signals"]);
+const VOLATILE_LINES = [/^Current time:/, /^Current local date and time:/];
+const MAX_EXCERPT_LINES = 12;
+const MAX_LINE_CHARS = 300;
+const MAX_DESCRIPTION_CHARS = 600;
+
+function clip(text: string, max: number): string {
+  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+
+/**
+ * Splits an assembled agent system prompt into its `--- Title ---` sections,
+ * dropping host- and time-dependent content so two snapshots of the same code
+ * compare equal on any machine.
+ */
+export function splitSystemPromptSections(prompt: string): Record<string, string> {
+  const sections: Record<string, string[]> = {};
+  let current = "Preamble";
+  for (const raw of prompt.split(/\r?\n/)) {
+    const header = SECTION_HEADER.exec(raw.trim());
+    if (header) {
+      current = header[1].trim();
+      sections[current] ??= [];
+      continue;
+    }
+    if (raw.startsWith("<!-- jarela:")) continue;
+    if (VOLATILE_LINES.some((pattern) => pattern.test(raw.trim()))) continue;
+    (sections[current] ??= []).push(raw);
+  }
+  const out: Record<string, string> = {};
+  for (const [title, lines] of Object.entries(sections)) {
+    if (VOLATILE_SECTIONS.has(title)) continue;
+    const text = lines.join("\n").trim();
+    if (text) out[title] = text;
+  }
+  return out;
+}
+
+function significantLines(text: string): string[] {
+  return text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+}
+
+function excerpt(lines: string[]): { lines: string[]; omitted: number } {
+  return {
+    lines: lines.slice(0, MAX_EXCERPT_LINES).map((line) => clip(line, MAX_LINE_CHARS)),
+    omitted: Math.max(0, lines.length - MAX_EXCERPT_LINES),
+  };
+}
+
+export function diffPrompts(
+  prev: Record<string, SurfacePrompt>,
+  next: Record<string, SurfacePrompt>,
+): PromptChange[] {
+  const ids = [...new Set([...Object.keys(prev), ...Object.keys(next)])].sort();
+  const changes: PromptChange[] = [];
+  for (const id of ids) {
+    const before = prev[id];
+    const after = next[id];
+    if (before && after && before.text === after.text) continue;
+    const beforeLines = before ? significantLines(before.text) : [];
+    const afterLines = after ? significantLines(after.text) : [];
+    const beforeSet = new Set(beforeLines);
+    const afterSet = new Set(afterLines);
+    const added = excerpt(afterLines.filter((line) => !beforeSet.has(line)));
+    const removed = excerpt(beforeLines.filter((line) => !afterSet.has(line)));
+    // Whitespace-only edits change the text but not what the model reads.
+    if (before && after && added.lines.length === 0 && removed.lines.length === 0) continue;
+    changes.push({
+      id,
+      source: (after ?? before).source,
+      change: !before ? "added" : !after ? "removed" : "changed",
+      added_lines: before ? added.lines : [],
+      removed_lines: after ? removed.lines : [],
+      omitted_lines: (before ? added.omitted : 0) + (after ? removed.omitted : 0),
+    });
+  }
+  return changes;
+}
+
+interface ObjectSchema {
+  properties: Record<string, unknown>;
+  required: string[];
+}
+
+function objectSchema(parameters: unknown): ObjectSchema {
+  const schema = parameters && typeof parameters === "object" ? parameters as Record<string, unknown> : {};
+  const properties = schema.properties && typeof schema.properties === "object"
+    ? schema.properties as Record<string, unknown>
+    : {};
+  const required = Array.isArray(schema.required)
+    ? schema.required.filter((name): name is string => typeof name === "string")
+    : [];
+  return { properties, required };
+}
+
+function stableJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b));
+    return `{${entries.map(([key, inner]) => `${JSON.stringify(key)}:${stableJson(inner)}`).join(",")}}`;
+  }
+  return JSON.stringify(value) ?? "null";
+}
+
+export function diffTools(
+  prev: Record<string, SurfaceTool>,
+  next: Record<string, SurfaceTool>,
+): ToolChange[] {
+  const names = [...new Set([...Object.keys(prev), ...Object.keys(next)])].sort();
+  const changes: ToolChange[] = [];
+  for (const name of names) {
+    const before = prev[name];
+    const after = next[name];
+    const beforeSchema = objectSchema(before?.parameters);
+    const afterSchema = objectSchema(after?.parameters);
+    const beforeParams = Object.keys(beforeSchema.properties);
+    const afterParams = Object.keys(afterSchema.properties);
+    const paramsAdded = afterParams.filter((param) => !(param in beforeSchema.properties)).sort();
+    const paramsRemoved = beforeParams.filter((param) => !(param in afterSchema.properties)).sort();
+    const paramsChanged = afterParams
+      .filter((param) => param in beforeSchema.properties)
+      .filter((param) => stableJson(beforeSchema.properties[param]) !== stableJson(afterSchema.properties[param]))
+      .sort();
+    const requiredAdded = afterSchema.required.filter((param) => !beforeSchema.required.includes(param)).sort();
+    const requiredRemoved = beforeSchema.required.filter((param) => !afterSchema.required.includes(param)).sort();
+    const descriptionChanged = Boolean(before && after && before.description.trim() !== after.description.trim());
+    const schemaChanged = paramsAdded.length + paramsRemoved.length + paramsChanged.length
+      + requiredAdded.length + requiredRemoved.length > 0;
+    if (before && after && !descriptionChanged && !schemaChanged) continue;
+    changes.push({
+      name,
+      change: !before ? "added" : !after ? "removed" : "changed",
+      description_changed: descriptionChanged,
+      ...(after && (!before || descriptionChanged) ? { description: clip(after.description.trim(), MAX_DESCRIPTION_CHARS) } : {}),
+      ...(before && after && descriptionChanged ? { previous_description: clip(before.description.trim(), MAX_DESCRIPTION_CHARS) } : {}),
+      params_added: after ? paramsAdded : [],
+      params_removed: before && after ? paramsRemoved : [],
+      params_changed: paramsChanged,
+      required_added: after ? requiredAdded : [],
+      required_removed: before && after ? requiredRemoved : [],
+    });
+  }
+  return changes;
+}
+
+export function diffSurfaces(prev: SurfaceSnapshot, next: SurfaceSnapshot): SurfaceDelta {
+  return {
+    prompts: diffPrompts(prev.prompts, next.prompts),
+    tools: diffTools(prev.tools, next.tools),
+  };
+}

package/lib/memory/record.ts

@@ -65,9 +65,7 @@ export const StructuredMemoryInputSchema = z.object({
   status: z.enum(MEMORY_STATUSES).default("active"),
 }).strict();
 
-export type StructuredMemoryInput = z.infer<typeof StructuredMemoryInputSchema>;
 export type StructuredMemoryRecord = z.infer<typeof StructuredMemoryEnvelopeV2Schema>;
-export type StructuredMemoryHistoryEntry = z.infer<typeof StructuredMemoryHistoryEntrySchema>;
 
 function normalizeStructuredMemoryCandidate(candidate: unknown): unknown {
   if (!candidate || typeof candidate !== "object") return candidate;

package/lib/pricing/snapshot.test.ts

@@ -324,3 +324,73 @@ describe("pricing snapshot refresh", () => {
     expect(modelRate?.output_per_1m_usd).toBe(0.28);
   });
 });
+
+describe("pricing snapshot edge cases", () => {
+  beforeEach(() => {
+    vi.resetModules();
+    readFileMock.mockReset();
+    mkdirMock.mockReset();
+    writeFileMock.mockReset();
+    vi.unstubAllGlobals();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("refreshes a snapshot stamped in the future instead of trusting it forever", async () => {
+    readFileMock.mockResolvedValueOnce(JSON.stringify({
+      generated_at: new Date(Date.now() + 365 * 24 * 60 * 60 * 1000).toISOString(),
+      disclaimer: "skewed",
+      ttl_days: 3,
+      sources: [],
+    }));
+    vi.stubGlobal("fetch", vi.fn(async () => new Response("input $1 / 1M tokens output $2 / 1M tokens", { status: 200 })));
+
+    const { refreshPricingSnapshot } = await import("./snapshot");
+    const res = await refreshPricingSnapshot({ providers: ["cohere"] });
+
+    expect(res).toMatchObject({ refreshed: true, reason: "stale" });
+  });
+
+  it("treats a corrupt snapshot file as missing", async () => {
+    readFileMock.mockResolvedValueOnce("{not json");
+    vi.stubGlobal("fetch", vi.fn(async () => new Response("input $1 / 1M tokens output $2 / 1M tokens", { status: 200 })));
+
+    const { refreshPricingSnapshot } = await import("./snapshot");
+    const res = await refreshPricingSnapshot({ providers: ["cohere"] });
+
+    expect(res).toMatchObject({ refreshed: true, reason: "missing" });
+  });
+
+  it("parses each source's search results independently and skips Google's own links", async () => {
+    readFileMock.mockRejectedValueOnce(new Error("ENOENT"));
+    const link = (u: string) => `<a href="/url?q=${encodeURIComponent(u)}&amp;sa=U">x</a>`;
+    const anthropicSearch = "<html>" + "x".repeat(4000)
+      + link("https://www.google.com/intl/en/policies/")
+      + Array.from({ length: 9 }, (_, i) => link(`https://a${i}.example.com/pricing`)).join("")
+      + "</html>";
+    const cohereSearch = `<html>${link("https://c.example.com/pricing")}</html>`;
+    const fetchMock = vi.fn(async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.startsWith("https://www.google.com/search")) {
+        if (url.includes("Anthropic")) return new Response(anthropicSearch, { status: 200 });
+        // Only Cohere's first query has results, so a leaked regex cursor cannot be masked by a retry.
+        return new Response(url.includes("1M") ? cohereSearch : "<html></html>", { status: 200 });
+      }
+      if (/^https:\/\/(a0|c)\.example\.com\//.test(url)) {
+        return new Response("input $3 / 1M tokens output $15 / 1M tokens", { status: 200 });
+      }
+      return new Response("not found", { status: 404 });
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const { refreshPricingSnapshot } = await import("./snapshot");
+    const res = await refreshPricingSnapshot({ force: true, providers: ["anthropic", "cohere"] });
+    const byId = new Map(res.snapshot.sources.map((s) => [s.id, s]));
+
+    expect(byId.get("anthropic")).toMatchObject({ ok: true, resolved_url: "https://a0.example.com/pricing" });
+    expect(byId.get("cohere")).toMatchObject({ ok: true, resolved_url: "https://c.example.com/pricing" });
+    expect(fetchMock.mock.calls.map(([u]) => String(u))).not.toContain("https://www.google.com/intl/en/policies/");
+  });
+});

package/lib/pricing/snapshot.ts

@@ -85,6 +85,7 @@ const PRICE_LINE_RE = new RegExp(
 );
 
 const GOOGLE_RESULT_RE = /href="\/url\?q=([^"&]+)[^"]*"/gi;
+const GOOGLE_OWN_HOST_RE = /^(?:www|accounts|support|maps|policies|webcache)?\.?google\.[a-z.]+$/i;
 
 type FetchAttempt = {
   url: string;
@@ -168,7 +169,8 @@ export async function refreshPricingSnapshot(opts?: { force?: boolean; ttlDays?:
   const existing = await readPricingSnapshot();
   if (!force && existing) {
     const ageDays = (Date.now() - Date.parse(existing.generated_at)) / (24 * 60 * 60 * 1000);
-    if (Number.isFinite(ageDays) && ageDays < ttlDays) {
+    // A future generated_at (clock skew, copied snapshot) must not pin the cache as fresh.
+    if (Number.isFinite(ageDays) && ageDays >= 0 && ageDays < ttlDays) {
       return { refreshed: false, reason: "fresh", snapshot: existing };
     }
   }
@@ -332,6 +334,8 @@ function parseGoogleResultLinks(html: string): string[] {
   const seen = new Set<string>();
 
   let m: RegExpExecArray | null;
+  // Shared /g regex: an early break leaves lastIndex mid-string for the next page.
+  GOOGLE_RESULT_RE.lastIndex = 0;
   while ((m = GOOGLE_RESULT_RE.exec(html)) !== null) {
     const raw = m[1] ?? "";
     let url = "";
@@ -341,7 +345,11 @@ function parseGoogleResultLinks(html: string): string[] {
       continue;
     }
     if (!/^https?:\/\//i.test(url)) continue;
-    if (/\/google\./i.test(url)) continue;
+    try {
+      if (GOOGLE_OWN_HOST_RE.test(new URL(url).hostname)) continue;
+    } catch {
+      continue;
+    }
     if (seen.has(url)) continue;
     seen.add(url);
     out.push(url);

package/lib/providers/external.ts

@@ -97,5 +97,3 @@ export function loadExternalProviders(
 ): Record<string, ModelProvider> {
   return loadExternalProvidersDetailed(builtins).providers;
 }
-
-export { type ExternalProviderCredentialField as ProviderCredentialField };

package/lib/proxy/dispatcher.test.ts

@@ -31,7 +31,7 @@ vi.mock("node:child_process", async () => {
 
 import { exec } from "node:child_process";
 import { readFileSync } from "node:fs";
-import { getProxyConfigRaw } from "@/lib/stores/proxy-config";
+import { getProxyConfigRaw, type ProxyConfigRaw } from "@/lib/stores/proxy-config";
 import { extractSystemKeychainCAs } from "@/lib/proxy/keychain";
 
 const mockedGetProxyConfigRaw = vi.mocked(getProxyConfigRaw);
@@ -262,3 +262,121 @@ describe("applyProxyConfigFromDb — env override", () => {
     expect(mockedExtract).not.toHaveBeenCalled();
   });
 });
+
+describe("applyProxyConfigFromDb — manual mode", () => {
+  const originalEnv = { ...process.env };
+
+  function manual(overrides: Partial<ProxyConfigRaw> = {}): ProxyConfigRaw {
+    return {
+      mode: "manual",
+      scheme: "http",
+      host: "proxy.corp",
+      port: 3128,
+      username: null,
+      password: null,
+      no_proxy: null,
+      ca_bundle: null,
+      updated_at: "2026-05-22T00:00:00.000Z",
+      ...overrides,
+    };
+  }
+
+  beforeEach(() => {
+    for (const key of ["HTTP_PROXY", "HTTPS_PROXY", "http_proxy", "https_proxy", "NO_PROXY", "no_proxy"]) delete process.env[key];
+    vi.resetModules();
+    vi.clearAllMocks();
+  });
+
+  afterEach(async () => {
+    mockedGetProxyConfigRaw.mockReturnValue(null);
+    const { applyProxyConfigFromDb } = await import("./dispatcher");
+    await applyProxyConfigFromDb();
+    process.env = { ...originalEnv };
+  });
+
+  it("percent-encodes credentials in the proxy URL and redacts the password in the result", async () => {
+    mockedGetProxyConfigRaw.mockReturnValue(manual({ username: "dom\\user", password: "p@ss:w/rd" }));
+    const { applyProxyConfigFromDb } = await import("./dispatcher");
+    const r = await applyProxyConfigFromDb();
+    expect(r.source).toBe("manual");
+    expect(process.env.HTTPS_PROXY).toBe("http://dom%5Cuser:p%40ss%3Aw%2Frd@proxy.corp:3128");
+    expect(r.proxyUrl).toBe("http://dom%5Cuser:***@proxy.corp:3128/");
+    expect(r.proxyUrl).not.toContain("p%40ss");
+  });
+
+  it("brackets an IPv6 proxy host so the URL is parseable", async () => {
+    mockedGetProxyConfigRaw.mockReturnValue(manual({ host: "fd00::1" }));
+    const { applyProxyConfigFromDb } = await import("./dispatcher");
+    const r = await applyProxyConfigFromDb();
+    expect(process.env.HTTPS_PROXY).toBe("http://[fd00::1]:3128");
+    expect(r.proxyUrl).toBe("http://[fd00::1]:3128/");
+  });
+
+  it("always bypasses loopback, merged with the user's no_proxy list", async () => {
+    mockedGetProxyConfigRaw.mockReturnValue(manual({ no_proxy: " corp.internal, .svc " }));
+    const { applyProxyConfigFromDb } = await import("./dispatcher");
+    await applyProxyConfigFromDb();
+    const entries = (process.env.NO_PROXY ?? "").split(",");
+    expect(entries).toEqual(expect.arrayContaining(["corp.internal", ".svc", "localhost", "127.0.0.1", "::1"]));
+    expect(new Set(entries).size).toBe(entries.length);
+  });
+
+  it("still reaches a local server (e.g. Ollama) directly when the proxy is unreachable", async () => {
+    const { createServer } = await import("node:http");
+    const server = createServer((_req, res) => res.end("local-ok"));
+    await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const { port } = server.address() as { port: number };
+    try {
+      // Port 9 (discard) on loopback refuses connections, so any request
+      // routed through this "proxy" fails.
+      mockedGetProxyConfigRaw.mockReturnValue(manual({ host: "127.0.0.1", port: 9 }));
+      const { applyProxyConfigFromDb } = await import("./dispatcher");
+      await applyProxyConfigFromDb();
+      for (const host of ["127.0.0.1", "localhost"]) {
+        const res = await fetch(`http://${host}:${port}/`);
+        expect(await res.text()).toBe("local-ok");
+      }
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    }
+  });
+
+  it("keeps loopback direct even when a lowercase no_proxy is inherited", async () => {
+    // undici reads lowercase no_proxy before NO_PROXY.
+    process.env.no_proxy = "corp.internal";
+    const { createServer } = await import("node:http");
+    const server = createServer((_req, res) => res.end("local-ok"));
+    await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const { port } = server.address() as { port: number };
+    try {
+      mockedGetProxyConfigRaw.mockReturnValue(manual({ host: "127.0.0.1", port: 9 }));
+      const { applyProxyConfigFromDb } = await import("./dispatcher");
+      await applyProxyConfigFromDb();
+      const res = await fetch(`http://127.0.0.1:${port}/`);
+      expect(await res.text()).toBe("local-ok");
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    }
+  });
+
+  it("reverts to no proxy when host or port is missing", async () => {
+    mockedGetProxyConfigRaw.mockReturnValue(manual({ port: null }));
+    const { applyProxyConfigFromDb } = await import("./dispatcher");
+    const r = await applyProxyConfigFromDb();
+    expect(r.source).toBe("off");
+    expect(r.note).toMatch(/missing host\/port/);
+    expect(process.env.HTTPS_PROXY).toBeUndefined();
+  });
+
+  it("clears the proxy env when switched back to off", async () => {
+    mockedGetProxyConfigRaw.mockReturnValue(manual());
+    const { applyProxyConfigFromDb } = await import("./dispatcher");
+    await applyProxyConfigFromDb();
+    expect(process.env.HTTPS_PROXY).toBeDefined();
+    mockedGetProxyConfigRaw.mockReturnValue({ ...manual(), mode: "off" });
+    const r = await applyProxyConfigFromDb();
+    expect(r.source).toBe("off");
+    expect(process.env.HTTPS_PROXY).toBeUndefined();
+    expect(process.env.NO_PROXY).toBeUndefined();
+  });
+});