llm-switcher 1.6.11 → 1.6.13

package/tests/shim.test.mjs

@@ -34,7 +34,10 @@ if (process.platform !== 'win32') {
 // Only node, never the directory it lives in: an npm install puts the real claude and codex next to it.
 const NODE_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'shimnode-'));
 if (process.platform !== 'win32') fs.symlinkSync(process.execPath, path.join(NODE_DIR, 'node'));
+// Per-test fake binaries live here, so one teardown removes them even when a test fails.
+const SCRATCH = fs.mkdtempSync(path.join(os.tmpdir(), 'shimscratch-'));
 test.after(() => {
+  fs.rmSync(SCRATCH, { recursive: true, force: true });
   fs.rmSync(NODE_DIR, { recursive: true, force: true });
   fs.rmSync(RENDER_DIR, { recursive: true, force: true });
   fs.rmSync(STATE, { recursive: true, force: true });
@@ -61,7 +64,7 @@ function runShim(name, args, { active, fakeDir, extraPath = '', env = {}, files
 // Prints every value the switcher could have touched, so a test can see both what was scrubbed
 // and what must have been kept.
 function makeEnvBin(name) {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'shimenv-'));
+  const dir = fs.mkdtempSync(path.join(SCRATCH, 'shimenv-'));
   fs.writeFileSync(path.join(dir, name),
     '#!/usr/bin/env bash\n'
     + 'echo "HTTPS_PROXY=${HTTPS_PROXY:-NONE} BASE=${ANTHROPIC_BASE_URL:-NONE} OPENAI=${OPENAI_BASE_URL:-NONE} MODEL=${ANTHROPIC_MODEL:-NONE} DEFOPUS=${ANTHROPIC_DEFAULT_OPUS_MODEL:-NONE} CA=${NODE_EXTRA_CA_CERTS:-NONE}"\n'
@@ -73,14 +76,14 @@ function makeEnvBin(name) {
 
 // A fake binary that prints every argument on its own line, so the test sees argument boundaries.
 function makeArgvBin(name) {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'shimargv-'));
+  const dir = fs.mkdtempSync(path.join(SCRATCH, 'shimargv-'));
   fs.writeFileSync(path.join(dir, name), '#!/usr/bin/env bash\necho "HTTPS_PROXY=${HTTPS_PROXY:-NONE}"\nprintf \'%s\\n\' "$@"\n');
   fs.chmodSync(path.join(dir, name), 0o755);
   return dir;
 }
 
 function makeFakeBin(name) {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'shimtest-'));
+  const dir = fs.mkdtempSync(path.join(SCRATCH, 'shimtest-'));
   fs.writeFileSync(path.join(dir, name),
     '#!/usr/bin/env bash\necho "BASE=${ANTHROPIC_BASE_URL:-NONE} ARGS=$*"\n');
   fs.chmodSync(path.join(dir, name), 0o755);
@@ -118,7 +121,7 @@ test('shim never recurses into itself', (t) => {
 
 test('shim fails loudly (127) when the real binary is missing', (t) => {
   if (process.platform === 'win32') return t.skip('posix only');
-  const empty = fs.mkdtempSync(path.join(os.tmpdir(), 'shimempty-'));
+  const empty = fs.mkdtempSync(path.join(SCRATCH, 'shimempty-'));
   assert.throws(
     () => runShim('claude', [], { active: true, fakeDir: empty }),
     (err) => err.status === 127,
@@ -538,19 +541,22 @@ async function agyListener(kind) {
 async function runAgyWindowsShim(port) {
   const shimDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agyshim-'));
   const fakeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agyfake-'));
-  fs.writeFileSync(path.join(fakeDir, 'agy.cmd'), `@echo off\r\necho CCU=[%CLOUD_CODE_URL%]\r\nnode "${AGY_REQUEST}"\r\n`);
-  for (const f of fs.readdirSync(STATE)) if (fs.statSync(path.join(STATE, f)).isFile()) fs.rmSync(path.join(STATE, f), { force: true });
-  fs.writeFileSync(path.join(STATE, 'active.flag'), 'active');
-  fs.writeFileSync(path.join(STATE, 'env-agy.cmd'), `SET "CLOUD_CODE_URL=http://127.0.0.1:${port}"\r\n`);
-  const shim = path.join(shimDir, 'agy.cmd');
-  fs.writeFileSync(shim, renderShim('agy', 'win32'), 'utf8');
-  const started = Date.now();
-  const child = await runAsync('cmd.exe', ['/d', '/c', shim], {
-    env: { ...process.env, LLM_SWITCHER_CONFIG: AGY_CONFIG, PATH: [fakeDir, shimDir, path.join(process.env.SystemRoot, 'System32'), path.dirname(process.execPath)].join(path.delimiter) }
-  });
-  fs.rmSync(shimDir, { recursive: true, force: true });
-  fs.rmSync(fakeDir, { recursive: true, force: true });
-  return { out: child.stdout || '', err: child.stderr || '', ms: Date.now() - started };
+  try {
+    fs.writeFileSync(path.join(fakeDir, 'agy.cmd'), `@echo off\r\necho CCU=[%CLOUD_CODE_URL%]\r\nnode "${AGY_REQUEST}"\r\n`);
+    for (const f of fs.readdirSync(STATE)) if (fs.statSync(path.join(STATE, f)).isFile()) fs.rmSync(path.join(STATE, f), { force: true });
+    fs.writeFileSync(path.join(STATE, 'active.flag'), 'active');
+    fs.writeFileSync(path.join(STATE, 'env-agy.cmd'), `SET "CLOUD_CODE_URL=http://127.0.0.1:${port}"\r\n`);
+    const shim = path.join(shimDir, 'agy.cmd');
+    fs.writeFileSync(shim, renderShim('agy', 'win32'), 'utf8');
+    const started = Date.now();
+    const child = await runAsync('cmd.exe', ['/d', '/c', shim], {
+      env: { ...process.env, LLM_SWITCHER_CONFIG: AGY_CONFIG, PATH: [fakeDir, shimDir, path.join(process.env.SystemRoot, 'System32'), path.dirname(process.execPath)].join(path.delimiter) }
+    });
+    return { out: child.stdout || '', err: child.stderr || '', ms: Date.now() - started };
+  } finally {
+    fs.rmSync(shimDir, { recursive: true, force: true });
+    fs.rmSync(fakeDir, { recursive: true, force: true });
+  }
 }
 
 for (const [kind, routed] of [['forged', false], ['silent', false], ['real', true]]) {
@@ -583,7 +589,7 @@ for (const [kind, routed] of [['forged', false], ['silent', false], ['real', tru
     const server = await agyListener(kind);
     t.after(() => server.close());
     const port = server.address().port;
-    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'agyposix-'));
+    const dir = fs.mkdtempSync(path.join(SCRATCH, 'agyposix-'));
     fs.writeFileSync(path.join(dir, 'agy'), `#!/usr/bin/env bash\necho "CCU=[\${CLOUD_CODE_URL:-}]"\nnode "${AGY_REQUEST}"\n`);
     fs.chmodSync(path.join(dir, 'agy'), 0o755);
     for (const f of fs.readdirSync(STATE)) if (fs.statSync(path.join(STATE, f)).isFile()) fs.rmSync(path.join(STATE, f), { force: true });

package/tests/switch.test.mjs

@@ -21,9 +21,14 @@ const freePort = () => new Promise(r => {
   const s = net.createServer().listen(0, '127.0.0.1', () => { const { port } = s.address(); s.close(() => r(port)); });
 });
 
+// Every temp directory goes once more after the file, so a setup that fails early leaves none behind.
+const made = [];
+after(() => { for (const d of made) fs.rmSync(d, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }); });
+
 // A free interceptor port too: the default 3457 belongs to a switcher that may run on this machine.
 async function workspace(t, port, profiles) {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'llmsw-cli-'));
+  made.push(dir);
   const cfgPath = path.join(dir, 'config.json');
   fs.writeFileSync(cfgPath, JSON.stringify({
     port, blindfold: { port: await freePort() }, activeProfiles: { anthropic: null, responses: null, 'openai-chat': null, vertex: null },
@@ -661,3 +666,44 @@ test('switch port leaves the installed service of another port unchanged', { ski
   const log = fs.existsSync(calls) ? fs.readFileSync(calls, 'utf8') : '';
   assert.doesNotMatch(log, /\b(stop|restart|start|enable)\b/, `systemctl was told to act on the other instance:\n${log}`);
 });
+
+// Bare `switch on` brings back what `switch off` turned off; it never turns on a target the user had
+// switched off, and never moves a target to another profile.
+const twoProfiles = () => ({
+  c1: { name: 'One', mode: 'convert', tool: 'claude', baseURL: 'http://127.0.0.1:9/v1', apiKey: 'k', defaultModels: { opus: 'o' } },
+  c2: { name: 'Two', mode: 'convert', tool: 'claude', baseURL: 'http://127.0.0.1:9/v1', apiKey: 'k', defaultModels: { opus: 'o' } },
+  x1: { name: 'Codex', mode: 'convert', tool: 'codex', baseURL: 'http://127.0.0.1:9/v1', apiKey: 'k', defaultModels: { default: 'o' } }
+});
+const setActive = (ws, map) => {
+  const cfg = readCfg(ws);
+  cfg.activeProfiles = map;
+  fs.writeFileSync(ws.cfgPath, JSON.stringify(cfg, null, 2), { mode: 0o600 });
+};
+const pointers = (ws) => { const a = readCfg(ws).activeProfiles; return { claude: a.claude ?? null, codex: a.codex ?? null, agy: a.agy ?? null }; };
+
+test('switch on after switch off brings back each target as it was', { skip: !POSIX && 'posix' }, async (t) => {
+  const ws = await workspace(t, await freePort(), twoProfiles());
+  setActive(ws, { claude: null, codex: 'x1', agy: null });
+  assert.equal((await run(ws, ['off'])).status, 0);
+  const r = await run(ws, ['on']);
+  assert.equal(r.status, 0, r.stdout + r.stderr);
+  assert.deepEqual(pointers(ws), { claude: null, codex: 'x1', agy: null });
+});
+
+test('switch on keeps every target off when all were off before switch off', { skip: !POSIX && 'posix' }, async (t) => {
+  const ws = await workspace(t, await freePort(), twoProfiles());
+  setActive(ws, { claude: null, codex: null, agy: null });
+  assert.equal((await run(ws, ['off'])).status, 0);
+  const r = await run(ws, ['on']);
+  assert.equal(r.status, 0, r.stdout + r.stderr);
+  assert.deepEqual(pointers(ws), { claude: null, codex: null, agy: null });
+  assert.match(r.stdout, /switch <profile>/);
+});
+
+test('switch on keeps a target on the profile it already uses', { skip: !POSIX && 'posix' }, async (t) => {
+  const ws = await workspace(t, await freePort(), twoProfiles());
+  setActive(ws, { claude: 'c2', codex: null, agy: null });
+  const r = await run(ws, ['on']);
+  assert.equal(r.status, 0, r.stdout + r.stderr);
+  assert.deepEqual(pointers(ws), { claude: 'c2', codex: null, agy: null });
+});

package/tests/update.e2e.test.mjs

@@ -1,7 +1,7 @@
 // A real gateway, run from a copy of this checkout that tracks a local bare repository. A release
 // pushed there must reach the running gateway through POST /api/update, and through --autoupdate at
 // start. Nothing here reaches the network or the real home directory.
-import { test } from 'node:test';
+import { test, after } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import http from 'node:http';
@@ -44,8 +44,13 @@ async function registry(t, version) {
   return `http://127.0.0.1:${srv.address().port}/`;
 }
 
+// Every temp directory goes once more after the file, so a setup that fails early leaves none behind.
+const made = [];
+after(() => { for (const d of made) fs.rmSync(d, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }); });
+
 async function fixture(t, { registryUrl = 'http://127.0.0.1:9/' } = {}) {
   const base = fs.mkdtempSync(path.join(os.tmpdir(), 'llmsw-update-e2e-'));
+  made.push(base);
   const upstream = path.join(base, 'upstream.git');
   const install = path.join(base, 'install');
   const publisher = path.join(base, 'publisher');

package/tests/version.test.mjs

@@ -1,5 +1,5 @@
 // The running version and the update notice. The registry is a local server, never npm.
-import { test } from 'node:test';
+import { test, after } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -15,7 +15,10 @@ async function registry(handler) {
   await new Promise(r => server.listen(0, '127.0.0.1', r));
   return { url: `http://127.0.0.1:${server.address().port}/llm-switcher/latest`, hits: () => hits, close: () => server.close() };
 }
-const tmpState = () => fs.mkdtempSync(path.join(os.tmpdir(), 'lsw-version-'));
+// Every state dir is removed after the file, also the ones a failed test did not reach.
+const made = [];
+after(() => { for (const d of made) fs.rmSync(d, { recursive: true, force: true }); });
+const tmpState = () => { const d = fs.mkdtempSync(path.join(os.tmpdir(), 'lsw-version-')); made.push(d); return d; };
 
 test('the current version is the one in package.json', () => {
   assert.equal(CURRENT_VERSION, pkg.version);

package/tests/windows.test.mjs

@@ -1,4 +1,4 @@
-import test from 'node:test';
+import test, { after } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import os from 'node:os';
@@ -6,10 +6,18 @@ import path from 'node:path';
 import http from 'node:http';
 import {
   parseModelWindows, parseModelList, fetchProfileWindows,
-  resolveProfileWindows, readWindowsCache, readLocalCodexWindows
+  resolveProfileWindows, readWindowsCache, readLocalCodexWindows,
+  windowsCacheKey, cachedProfileWindows, createWindowsRefresher
 } from '../windows.mjs';
 
-const tmpDir = () => fs.mkdtempSync(path.join(os.tmpdir(), 'lsw-windows-'));
+// Every temp directory goes once more after the file, so a setup that fails early leaves none behind.
+const made = [];
+after(() => { for (const d of made) fs.rmSync(d, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }); });
+const tmpDir = () => {
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), 'lsw-windows-'));
+  made.push(d);
+  return d;
+};
 
 // A Codex model publishes both windows; intact names the threshold itself. Neither is guessed.
 test('a list entry gives the whole window and the window to compress at', () => {
@@ -152,3 +160,139 @@ test('the Codex CLI own cache is a fallback, not a source of truth', () => {
     fs.rmSync(home, { recursive: true, force: true });
   }
 });
+
+// A profile whose baseURL is spelled with another case or a trailing slash is the same address.
+test('the cache key of a profile ignores the case of scheme and host and a trailing slash', () => {
+  assert.equal(windowsCacheKey('p', 'HTTP://Api.Example.COM:8080/v1/'), 'p@http://api.example.com:8080/v1');
+  assert.equal(windowsCacheKey('p', 'http://api.example.com:8080/v1'), 'p@http://api.example.com:8080/v1');
+  assert.equal(windowsCacheKey('p', 'https://api.example.com/V1//'), 'p@https://api.example.com/V1', 'the path keeps its case');
+  assert.equal(windowsCacheKey(null, 'https://h/v1'), 'profile@https://h/v1');
+});
+
+// The output clamp reads the cache without a refresh, so it trusts only what this profile read within the hour.
+test('cachedProfileWindows answers only for its own key and only while the entry is fresh', () => {
+  const dir = tmpDir();
+  try {
+    const models = { m: { context: 200000, compact: 0, output: 8192 } };
+    fs.writeFileSync(path.join(dir, 'model-windows.json'), JSON.stringify({ 'a@http://h/v1': { at: 1_000, baseURL: 'http://h/v1', models } }));
+    assert.deepEqual(cachedProfileWindows(dir, 'a@http://h/v1', { now: 1_000 + 60_000 }), models);
+    assert.deepEqual(cachedProfileWindows(dir, 'b@http://h/v1', { now: 1_000 + 60_000 }), {}, 'another profile on the same baseURL');
+    assert.deepEqual(cachedProfileWindows(dir, 'a@http://h/v1', { now: 1_000 + 3_600_000 }), {}, 'an entry an hour old');
+    assert.deepEqual(cachedProfileWindows(dir, 'a@http://h/v1', { now: 2_000, ttlMs: 500 }), {});
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// A list that names only an output limit must not erase the windows an earlier read found, and an
+// output limit lives only as long as the newest list still states it.
+test('a refresh merges each model into the cached windows, but never carries an output limit forward', async () => {
+  const dir = tmpDir();
+  const lists = [
+    [{ id: 'm', context_length: 200000, compact_window: 150000, max_output_tokens: 4096 }, { id: 'n', context_length: 100000, max_output_tokens: 2048 }],
+    [{ id: 'm', context_length: 300000 }, { id: 'o', context_length: 50000 }],
+    [{ id: 'm', max_output_tokens: 8192 }]
+  ];
+  let hits = 0;
+  const sink = http.createServer((req, res) => {
+    res.writeHead(200, { 'content-type': 'application/json' });
+    res.end(JSON.stringify({ data: lists[hits++] }));
+  });
+  await new Promise(r => sink.listen(0, '127.0.0.1', r));
+  const base = `http://127.0.0.1:${sink.address().port}/v1`;
+  try {
+    await resolveProfileWindows(dir, 'p', base, 'k', { now: 1_000 });
+    const second = await resolveProfileWindows(dir, 'p', base, 'k', { now: 1_000 + 3_600_000 });
+    const expected = {
+      m: { context: 300000, compact: 150000 },
+      n: { context: 100000, compact: 0 },
+      o: { context: 50000, compact: 0 }
+    };
+    assert.deepEqual(second, expected, 'a changed window replaces the cached one; no output limit the list did not state');
+    assert.deepEqual(readWindowsCache(dir).p.models, expected);
+    const fresh = cachedProfileWindows(dir, 'p', { now: 1_000 + 3_600_000 + 60_000 });
+    assert.equal(fresh.m.output, undefined);
+    assert.equal(fresh.m.context, 300000);
+    const third = await resolveProfileWindows(dir, 'p', base, 'k', { now: 1_000 + 7_200_000 });
+    assert.equal(hits, 3);
+    assert.deepEqual(third.m, { context: 300000, compact: 150000, output: 8192 }, 'an output-only list keeps the windows');
+  } finally {
+    sink.close();
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// A clock that moved back, or a hand-edited file, must not make an entry fresh forever.
+test('a cache entry stamped in the future is stale', async () => {
+  const dir = tmpDir();
+  let hits = 0;
+  const sink = http.createServer((req, res) => {
+    hits++;
+    res.writeHead(200, { 'content-type': 'application/json' });
+    res.end(JSON.stringify({ data: [{ id: 'm', context_length: 200000, max_output_tokens: 2048 }] }));
+  });
+  await new Promise(r => sink.listen(0, '127.0.0.1', r));
+  const base = `http://127.0.0.1:${sink.address().port}/v1`;
+  try {
+    const models = { m: { context: 200000, compact: 0, output: 8192 } };
+    fs.writeFileSync(path.join(dir, 'model-windows.json'), JSON.stringify({ p: { at: 10_000_000, baseURL: base, models } }));
+    assert.deepEqual(cachedProfileWindows(dir, 'p', { now: 1_000 }), {});
+    const listed = await resolveProfileWindows(dir, 'p', base, 'k', { now: 1_000 });
+    assert.equal(hits, 1, 'the list is read again');
+    assert.equal(listed.m.output, 2048);
+    assert.equal(readWindowsCache(dir).p.at, 1_000);
+  } finally {
+    sink.close();
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// A converted request with no fresh entry asks for one read in the background; it never waits for it.
+test('the background refresh reads a list once per profile, keeps each profile apart, and logs a failure', async () => {
+  const dir = tmpDir();
+  const reads = [];
+  const sink = http.createServer((req, res) => {
+    reads.push(req.headers.authorization);
+    const output = req.headers.authorization === 'Bearer kb' ? 2048 : 8192;
+    setTimeout(() => {
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ data: [{ id: 'm', context_length: 200000, max_output_tokens: output }] }));
+    }, req.headers.authorization === 'Bearer ka' ? 150 : 20);
+  });
+  await new Promise(r => sink.listen(0, '127.0.0.1', r));
+  const base = `http://127.0.0.1:${sink.address().port}/v1`;
+  const logged = [];
+  const refresh = createWindowsRefresher(dir, { debug: (...a) => logged.push(a.join(' ')) });
+  try {
+    const a = windowsCacheKey('a', base);
+    const b = windowsCacheKey('b', base);
+    const first = refresh(a, base, 'ka');
+    assert.equal(refresh(a, base, 'ka'), first, 'a second request joins the read in flight');
+    await Promise.all([first, refresh(b, base, 'kb')]);
+    assert.deepEqual(reads, ['Bearer ka', 'Bearer kb']);
+    assert.equal(cachedProfileWindows(dir, a).m.output, 8192);
+    assert.equal(cachedProfileWindows(dir, b).m.output, 2048, 'two profiles on one baseURL keep their own limits');
+    assert.equal(refresh(a, base, 'ka'), null, 'no second read soon after the first');
+
+    const dead = windowsCacheKey('dead', 'http://127.0.0.1:9/v1');
+    await refresh(dead, 'http://127.0.0.1:9/v1', 'k');
+    assert.equal(logged.length, 1);
+    assert.match(logged[0], /dead@http:\/\/127\.0\.0\.1:9\/v1/);
+    assert.equal(refresh(dead, 'http://127.0.0.1:9/v1', 'k'), null, 'a failed read is not retried at once');
+  } finally {
+    sink.close();
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// The gateway calls refresh() without awaiting it, so a rejection would be an unhandled rejection there.
+test('the background refresh never rejects, even when its logger throws', async () => {
+  const dir = tmpDir();
+  const dead = 'http://127.0.0.1:9/v1';
+  const refresh = createWindowsRefresher(dir, { debug: () => { throw new Error('logger down'); } });
+  try {
+    await assert.doesNotReject(refresh(windowsCacheKey('dead', dead), dead, 'k'));
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});

package/windows.mjs

@@ -18,9 +18,13 @@ import os from 'node:os';
 const ONE_HOUR_MS = 60 * 60 * 1000;
 const DEFAULT_TTL_MS = ONE_HOUR_MS;
 const FETCH_TIMEOUT_MS = 15000;
+const REFRESH_RETRY_MS = 5 * 60 * 1000;
 
 const n = v => (Number.isFinite(v) && v > 0 ? Math.round(v) : 0);
 
+// An entry stamped after `now` came from a clock that moved back or a hand edit: stale, not fresh forever.
+const isFresh = (entry, now, ttlMs) => Number.isFinite(entry?.at) && entry.at > 0 && entry.at <= now && now - entry.at < ttlMs;
+
 // One entry of a provider's list -> the two windows, plus `output` (the most the model writes)
 // when the list names it; null when it names none.
 export function parseModelWindows(m) {
@@ -82,17 +86,70 @@ export async function fetchProfileWindows(baseURL, apiKey, { timeoutMs = FETCH_T
 export async function resolveProfileWindows(stateDir, cacheKey, baseURL, apiKey, { ttlMs = DEFAULT_TTL_MS, now = Date.now() } = {}) {
   const cache = readWindowsCache(stateDir);
   const entry = cache[cacheKey] || {};
-  const fresh = entry.at && now - entry.at < ttlMs;
-  if (fresh) return entry.models || {};
-  const models = await fetchProfileWindows(baseURL, apiKey);
-  if (Object.keys(models).length) {
-    cache[cacheKey] = { at: now, baseURL, models };
-    writeWindowsCache(stateDir, cache);
+  if (isFresh(entry, now, ttlMs)) return entry.models || {};
+  const listed = await fetchProfileWindows(baseURL, apiKey);
+  if (Object.keys(listed).length) {
+    // Merged per model and per number: a list that names only an output limit keeps the cached windows.
+    // An output limit is never carried forward: the entry is stamped now, so it must be one this list states.
+    const models = {};
+    for (const [id, w] of Object.entries(entry.models || {})) {
+      const { output: _output, ...windows } = w && typeof w === 'object' ? w : {};
+      models[id] = windows;
+    }
+    for (const [id, w] of Object.entries(listed)) {
+      const merged = { ...(models[id] || {}) };
+      for (const [k, v] of Object.entries(w)) if (v > 0 || !(merged[k] > 0)) merged[k] = v;
+      models[id] = merged;
+    }
+    // Read again just before the write: another profile's refresh may have written while this list loaded.
+    const latest = readWindowsCache(stateDir);
+    latest[cacheKey] = { at: now, baseURL, models };
+    writeWindowsCache(stateDir, latest);
     return models;
   }
   return entry.models || {};
 }
 
+/**
+ * Reads a profile's list in the background, so a request that found no fresh entry is clamped from
+ * the next request on. One read per cache key at a time, and none again within retryMs of the last,
+ * so a provider with no usable list costs one read per interval. Returns the read, which never rejects, or null.
+ */
+export function createWindowsRefresher(stateDir, { retryMs = REFRESH_RETRY_MS, debug = () => {} } = {}) {
+  const running = new Map();
+  const lastTry = new Map();
+  // The caller does not await the read, so a logger that throws must not turn it into a rejection.
+  const log = (msg) => { try { debug(msg); } catch {} };
+  return function refresh(cacheKey, baseURL, apiKey) {
+    if (running.has(cacheKey)) return running.get(cacheKey);
+    if (Date.now() - (lastTry.get(cacheKey) ?? -Infinity) < retryMs) return null;
+    lastTry.set(cacheKey, Date.now());
+    const read = resolveProfileWindows(stateDir, cacheKey, baseURL, apiKey)
+      .then(() => {
+        if (!Object.keys(cachedProfileWindows(stateDir, cacheKey)).length) log(`model list refresh for ${cacheKey}: no limits read`);
+      })
+      .catch(err => log(`model list refresh for ${cacheKey} failed: ${err?.message}`))
+      .finally(() => running.delete(cacheKey));
+    running.set(cacheKey, read);
+    return read;
+  };
+}
+
+// One address however it is spelled: scheme and host are case-blind, and a trailing slash adds nothing.
+export function normalizeBaseURL(baseURL) {
+  return String(baseURL || '').trim().replace(/\/+$/, '').replace(/^[a-z][a-z0-9+.-]*:\/\/[^/]*/i, m => m.toLowerCase());
+}
+
+export function windowsCacheKey(profileKey, baseURL) {
+  return `${profileKey || 'profile'}@${normalizeBaseURL(baseURL)}`;
+}
+
+// The cached windows of one profile while they are fresh, without reading the list again.
+export function cachedProfileWindows(stateDir, cacheKey, { ttlMs = DEFAULT_TTL_MS, now = Date.now() } = {}) {
+  const entry = readWindowsCache(stateDir)[cacheKey];
+  return isFresh(entry, now, ttlMs) ? entry.models || {} : {};
+}
+
 export function windowsCachePath(stateDir) {
   return path.join(stateDir, 'model-windows.json');
 }