llm-switcher 1.3.8 → 1.4.1

package/tests/state.test.mjs

@@ -797,6 +797,7 @@ test('A5: migration splits shared auto profile into -claude and -codex halves wi
         name: 'Shared Profile',
         apiKey: 'secret-key',
         defaultModels: { opus: 'opus-model', sonnet: 'sonnet-model', subagent: 'sub-model' },
+        // The retired 1M flags are in an old config: the split must not carry them into a half.
         model1M: { opus: true, sonnet: false }
       }
     }
@@ -819,10 +820,8 @@ test('A5: migration splits shared auto profile into -claude and -codex halves wi
   assert.equal(codex.defaultModels.main, 'opus-model');
   assert.equal(codex.defaultModels.review, 'sonnet-model');
   assert.equal(codex.defaultModels.subagent, 'sub-model');
-  assert.equal(claude.model1M.opus, true);
-  assert.equal(claude.model1M.sonnet, false);
-  assert.equal(codex.model1M.main, true);
-  assert.equal(codex.model1M.review, false);
+  assert.equal(claude.model1M, undefined, 'the retired 1M flags do not survive the split');
+  assert.equal(codex.model1M, undefined);
 });
 
 test('A5: R7 row 4 splits profile with Claude/no-tool fields active for responses with slot fallbacks', () => {
@@ -881,7 +880,7 @@ test('A5: migration preserves legacy "default" key on both halves during split',
   assert.equal(res.config.profiles['combo-codex'].defaultModels.default, 'chat-default');
 });
 
-test('A5: migration never fills slot whose value is empty string or false', () => {
+test('A5: migration never fills slot whose value is empty string', () => {
   const raw = {
     activeProfile: 'combo',
     profiles: {
@@ -895,7 +894,7 @@ test('A5: migration never fills slot whose value is empty string or false', () =
   const res = migrateConfigInMemory(raw);
   const codex = res.config.profiles['combo-codex'];
   assert.equal(codex.defaultModels.main, '');
-  assert.equal(codex.model1M.main, false);
+  assert.equal(codex.model1M, undefined, 'and the retired flags do not come along');
 });
 
 test('A5: migration splits renamed command-word profile as <key>-profile-claude and <key>-profile-codex', () => {
@@ -1610,7 +1609,7 @@ test('each routed tool gets a route line; a tool that is off gets an empty one',
   assert.match(r.on.claude, /\bcl\b/, 'the line names the profile that serves claude');
   assert.match(r.on.claude, /intact\.example\.io/, 'and the host the traffic goes to');
   assert.match(r.on.claude, /gemini-3\.8-flash/, 'and the model it maps to');
-  assert.match(r.on.claude, /1M/, 'and the 1M window, because that changes what the session costs');
+  assert.doesNotMatch(r.on.claude, /1M/, 'and no window: the tool sizes the session from the model');
   assert.match(r.on.codex, /\bcx\b/);
   assert.match(r.on.codex, /other\.example\.io/);
   assert.doesNotMatch(r.on.codex, /intact\.example\.io/, 'one tool never shows the other tool route');

package/tests/tool-repair.test.mjs

@@ -0,0 +1,280 @@
+// The tool-name layer: a model answers in the vocabulary it knows, the caller only runs the tools it
+// declared. Sources for every name here are collected in docs/tool-vocabulary.md.
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createToolVocab, NULL_TOOL_VOCAB, tokenize } from '../toolvocab.mjs';
+import {
+  anthropicToIR, responsesToIR, irToChatBody, buildAnthropicMessage, buildChatMessage, buildResponsesMessage,
+  createAnthropicStream, createChatStream, createResponsesStream
+} from '../formats.mjs';
+
+const claudeTools = () => anthropicToIR({
+  model: 'claude-opus-4-6', messages: [{ role: 'user', content: 'go' }],
+  tools: [
+    { name: 'Read', input_schema: { properties: { file_path: { type: 'string' }, offset: { type: 'number' } } } },
+    { name: 'Bash', input_schema: { properties: { command: { type: 'string' } } } },
+    { name: 'Edit', input_schema: { properties: { file_path: { type: 'string' }, old_string: { type: 'string' }, new_string: { type: 'string' } } } }
+  ]
+});
+
+// A model that answers `read` when the caller declared `Read` ends the turn with
+// "No such tool available: read". The name comes back in the caller's words.
+test('a name the model reached for comes back in the caller own words', () => {
+  const vocab = createToolVocab(claudeTools().tools);
+  assert.equal(vocab.name('read'), 'Read');
+  assert.equal(vocab.name('shell'), 'Bash');
+  assert.equal(vocab.name('str_replace_editor'), 'Edit');
+  assert.equal(vocab.name('read_file'), 'Read', 'the name Codex is trained on');
+  assert.equal(vocab.name('run_shell_command'), 'Bash', 'the name Gemini is trained on');
+  assert.equal(vocab.name('execute_command'), 'Bash');
+});
+
+test('a name the caller already declared is never touched', () => {
+  const vocab = createToolVocab(claudeTools().tools);
+  for (const own of ['Read', 'Bash', 'Edit']) assert.equal(vocab.name(own), own);
+  assert.equal(vocab.name('WebFetch'), 'WebFetch', 'a name it did not declare and that says nothing');
+  assert.equal(vocab.name('totally_unknown'), 'totally_unknown');
+});
+
+// Two declared tools of the same kind: which one the model meant is not knowable, and the wrong one
+// runs. Claude Code on Windows declares both Bash and PowerShell.
+test('two tools of the same kind are left alone rather than one being chosen', () => {
+  const ir = anthropicToIR({
+    model: 'x', messages: [],
+    tools: [
+      { name: 'Bash', input_schema: { properties: {} } },
+      { name: 'PowerShell', input_schema: { properties: {} } },
+      { name: 'Read', input_schema: { properties: {} } }
+    ]
+  });
+  const vocab = createToolVocab(ir.tools);
+  assert.equal(vocab.name('shell'), 'shell', 'no shell tool was renamed');
+  assert.equal(vocab.name('read'), 'Read', 'the unambiguous one still is');
+});
+
+// mcp__github__create_issue becoming a local Write produces a call the caller cannot detect as wrong:
+// it runs, and it writes a file instead of opening an issue.
+test('a namespaced name never leaves its namespace', () => {
+  const ir = anthropicToIR({
+    model: 'x', messages: [],
+    tools: [
+      { name: 'Write', input_schema: { properties: {} } },
+      { name: 'mcp__github__create_issue', input_schema: { properties: {} } }
+    ]
+  });
+  const vocab = createToolVocab(ir.tools);
+  assert.equal(vocab.name('mcp__github__create_issue'), 'mcp__github__create_issue');
+  assert.equal(vocab.name('mcp__github__write_file'), 'mcp__github__write_file');
+});
+
+// Who runs the tool decides whether a name may move at all. Anthropic runs a server tool and its
+// result reaches the caller without the caller executing anything; handing it back as a client tool
+// moves the work to the user's machine, where nothing can see that it happened.
+test('a tool the provider runs is neither renamed nor offered as a client tool', () => {
+  const ir = anthropicToIR({
+    model: 'claude-opus-4-6', messages: [],
+    tools: [
+      { name: 'Read', input_schema: { properties: { file_path: { type: 'string' } } } },
+      { name: 'Bash', input_schema: { properties: { command: { type: 'string' } } } },
+      { type: 'web_search_20260209', name: 'web_search' }
+    ]
+  });
+  assert.deepEqual(ir.tools.map(t => [t.name, t.side]), [
+    ['Read', 'client'], ['Bash', 'client'], ['web_search', 'provider']
+  ]);
+  const vocab = createToolVocab(ir.tools);
+  assert.equal(vocab.name('web_search'), 'web_search', 'a server tool is never a rename target');
+});
+
+// The schema is the caller's to declare, so the argument keys are matched against it rather than
+// against a table of what each tool is called.
+test('arguments are renamed only against the caller own schema, and a falsy value survives', () => {
+  const vocab = createToolVocab(claudeTools().tools);
+  const read = vocab.args('read', JSON.stringify({ path: 'a.ts', offset: 0 }));
+  assert.deepEqual(JSON.parse(read), { file_path: 'a.ts', offset: 0 }, 'offset 0 is a value, not an absence');
+
+  // A tool whose schema already has the key: nothing is touched.
+  const bash = vocab.args('shell', JSON.stringify({ command: 'ls' }));
+  assert.deepEqual(JSON.parse(bash), { command: 'ls' });
+
+  // A key the schema does not name stays: the caller may still read it.
+  const edit = vocab.args('Edit', JSON.stringify({ file_path: 'a', note: 'keep me' }));
+  assert.deepEqual(JSON.parse(edit), { file_path: 'a', note: 'keep me' });
+
+  // Arguments cut off by the upstream are passed through, not rewritten.
+  const broken = vocab.args('read', '{"path": "a.t');
+  assert.equal(broken, '{"path": "a.t');
+});
+
+// The whole turn, non-streaming, through the emitter the caller reads.
+test('a non-streaming answer hands the caller its own tool name and its own arguments', () => {
+  const ir = claudeTools();
+  const vocab = createToolVocab(ir.tools);
+  const body = buildAnthropicMessage({
+    model: 'claude-opus-4-6', text: [], think: [], finish: 'tool_calls',
+    tools: [{ id: 't1', name: 'read', args: '{"path":"a.ts","offset":0}' }], vocab
+  });
+  const use = body.content.find(c => c.type === 'tool_use');
+  assert.equal(use.name, 'Read');
+  assert.deepEqual(use.input, { file_path: 'a.ts', offset: 0 });
+  assert.equal(body.stop_reason, 'tool_use');
+
+  const chat = buildChatMessage({ model: 'm', text: [], tools: [{ id: 't1', name: 'shell', args: '{"command":"ls"}' }], vocab });
+  const call = chat.choices[0].message.tool_calls[0].function;
+  assert.equal(call.name, 'Bash');
+  assert.equal(call.arguments, '{"command":"ls"}');
+
+  const codex = buildResponsesMessage({ model: 'm', text: [], tools: [{ id: 'c1', name: 'read', args: '{"path":"a"}' }], vocab });
+  assert.equal(codex.output.find(i => i.type === 'function_call').name, 'Read');
+});
+
+// With no declared tools there is nothing to map, so the layer costs nothing and changes nothing.
+test('a request that declared no tools is passed through untouched', () => {
+  const vocab = createToolVocab([]);
+  assert.equal(vocab.name('read'), 'read');
+  assert.equal(vocab.args('read', '{"path":"a"}'), '{"path":"a"}');
+  const body = buildAnthropicMessage({ model: 'm', text: [], tools: [{ id: 't', name: 'read', args: '{}' }], vocab });
+  assert.equal(body.content[0].name, 'read');
+  assert.equal(NULL_TOOL_VOCAB.name('x'), 'x');
+});
+
+// Streaming: the name arrives first and is fixed at once. The arguments arrive in pieces, so a call
+// whose keys are renamed is held back and handed over whole, before the block closes.
+test('a streamed answer renames the name at once and holds the arguments only when it must', () => {
+  const vocab = createToolVocab(claudeTools().tools);
+
+  const plain = [];
+  const a = createAnthropicStream((e, d) => plain.push([e, d]), 'm', { vocab });
+  a.start();
+  a.tool({ index: 0, id: 't1', name: 'Bash', args: '{"command":' });
+  a.tool({ index: 0, args: '"ls"}' });
+  a.finish('tool_calls', {});
+  assert.deepEqual(plain.find(([e]) => e === 'content_block_start')[1].content_block.name, 'Bash');
+  // A call the caller already names is not buffered at all: every fragment goes straight out.
+  assert.deepEqual(
+    plain.filter(([, d]) => d.delta?.type === 'input_json_delta').map(([, d]) => d.delta.partial_json),
+    ['{"command":', '"ls"}']
+  );
+
+  const fixed = [];
+  const b = createAnthropicStream((e, d) => fixed.push([e, d]), 'm', { vocab });
+  b.start();
+  b.tool({ index: 0, id: 't1', name: 'read', args: '{"path"' });
+  b.tool({ index: 0, args: ':"a.ts","offset":0}' });
+  b.finish('tool_calls', {});
+  assert.equal(fixed.find(([e]) => e === 'content_block_start')[1].content_block.name, 'Read');
+  const deltas = fixed.filter(([, d]) => d.delta?.type === 'input_json_delta').map(([, d]) => d.delta.partial_json);
+  assert.deepEqual(deltas, ['{"file_path":"a.ts","offset":0}'], 'one delta, with the caller own key');
+  // The block never closes with arguments still pending.
+  const stopAt = fixed.findIndex(([e, d]) => e === 'content_block_stop' && d.type === 'content_block_stop');
+  const lastArgAt = fixed.findIndex(([, d]) => d.delta?.type === 'input_json_delta');
+  assert.ok(lastArgAt < stopAt, 'the arguments arrive before the block stops');
+});
+
+// Codex runs a tool when the whole item arrives, so a renamed call carries its repaired arguments
+// with that item and streams no argument deltas of its own.
+test('a streamed Codex call is repaired in the item Codex runs', () => {
+  const ir = responsesToIR({
+    model: 'gpt-5.6-sol', input: 'go',
+    tools: [{ type: 'function', name: 'Read', parameters: { properties: { file_path: { type: 'string' } } } },
+            { type: 'function', name: 'Bash', parameters: { properties: { command: { type: 'string' } } } }]
+  });
+  const vocab = createToolVocab(ir.tools);
+  const events = [];
+  const r = createResponsesStream((e, d) => events.push([e, d]), 'm', { vocab, toolMeta: ir.toolMeta });
+  r.start();
+  r.tool({ index: 0, id: 'c1', name: 'read', args: '{"path":"a.ts"' });
+  r.tool({ index: 0, args: '}' });
+  r.finish('tool_calls', {});
+  const added = events.find(([e]) => e === 'response.output_item.added')[1].item;
+  const done = events.find(([e]) => e === 'response.output_item.done')[1].item;
+  assert.equal(added.name, 'Read');
+  assert.equal(added.arguments, '', 'nothing is streamed for a call whose keys are renamed');
+  assert.equal(done.arguments, '{"file_path":"a.ts"}');
+  assert.equal(events.some(([e]) => e === 'response.function_call_arguments.delta'), false);
+});
+
+test('tokenize reads a name the way the model that coined it saw it', () => {
+  assert.deepEqual(tokenize('TodoWrite'), ['Todo', 'Write']);
+  assert.deepEqual(tokenize('str_replace_editor'), ['str', 'replace', 'editor']);
+  assert.deepEqual(tokenize('mcp__fs__read'), ['mcp', 'fs', 'read']);
+  assert.deepEqual(tokenize('filePath'), ['file', 'Path']);
+});
+
+// ---- steering the model instead of repairing every call ----
+//
+// A model answers with the tool names it was trained on, whatever the caller declared. Naming the
+// caller's names in the prompt is cheaper than repairing each such call, but only where the caller
+// has not already named them: a second list for a prompt that already carries one is a second thing
+// for the model to weigh, and this is where the collision would come from.
+
+function noticeIn(system, toolNames, opts = {}) {
+  const ir = anthropicToIR({
+    model: 'gpt-5.6-sol', messages: [{ role: 'user', content: 'go' }],
+    ...(system ? { system } : {}),
+    tools: toolNames.map(n => ({ name: n, input_schema: { properties: {} } }))
+  });
+  const body = irToChatBody(ir, 'gpt-5.6-sol', opts);
+  const sys = body.messages.find(m => m.role === 'system');
+  return sys ? sys.content : '';
+}
+
+test('a caller that never names its tools gets the list, and nothing else changes', () => {
+  const sys = noticeIn('', ['Read', 'Bash', 'Edit']);
+  assert.match(sys, /use exactly these names/i);
+  for (const n of ['Read', 'Bash', 'Edit']) assert.ok(sys.includes(n), `${n} is missing from the notice`);
+});
+
+// Claude Code names its tools at length in its own prompt. A second list would compete with it, so
+// nothing is added and the caller's text is passed through byte for byte.
+test('a prompt that already names every tool gets nothing added', () => {
+  const prompt = 'You are Claude Code. Use Read to view a file, Bash to run a command, Edit to change one.';
+  assert.equal(noticeIn(prompt, ['Read', 'Bash', 'Edit']), prompt);
+});
+
+test('a prompt that names some of them gets only the rest', () => {
+  const sys = noticeIn('Use Read to view a file.', ['Read', 'Bash']);
+  assert.match(sys, /^Use Read to view a file\./);
+  assert.ok(sys.includes('Bash'), 'the name the prompt did not carry is added');
+  assert.ok(!/Read, Bash/.test(sys), 'and the one it already had is not repeated');
+});
+
+test('one tool cannot be confused with another, so nothing is said', () => {
+  assert.equal(noticeIn('', ['Read']), '');
+  assert.equal(noticeIn('', []), '');
+});
+
+// A tool the provider runs is not in the list: the caller never executes it, so naming it would only
+// invite the model to call something the gateway dropped.
+test('a tool the provider runs is never named', () => {
+  const ir = anthropicToIR({
+    model: 'x', messages: [],
+    tools: [
+      { name: 'Read', input_schema: { properties: {} } },
+      { name: 'Bash', input_schema: { properties: {} } },
+      { type: 'web_search_20260209', name: 'web_search' }
+    ]
+  });
+  const sys = irToChatBody(ir, 'gpt-5.6-sol').messages.find(m => m.role === 'system').content;
+  assert.ok(!sys.includes('web_search'), `a server tool was named: ${sys}`);
+});
+
+// native never touches the system prompt, and that is a contract with the people who chose it; off
+// sends no reasoning parameters at all, and a tool name is neither.
+test('native and off add nothing, whatever the caller declared', () => {
+  assert.equal(noticeIn('', ['Read', 'Bash'], { thinkingMode: 'native' }), '');
+  assert.equal(noticeIn('', ['Read', 'Bash'], { thinkingMode: 'off' }), '');
+});
+
+// The notice and the think guide are two different instructions about two different things, and a
+// non-reasoning model that was asked to think gets both.
+test('the notice and the think guide coexist', () => {
+  const ir = anthropicToIR({
+    model: 'gpt-4o', messages: [{ role: 'user', content: 'go' }],
+    thinking: { type: 'enabled', budget_tokens: 2048 },
+    tools: [{ name: 'Read', input_schema: { properties: {} } }, { name: 'Bash', input_schema: { properties: {} } }]
+  });
+  const sys = irToChatBody(ir, 'gpt-4o').messages.find(m => m.role === 'system').content;
+  assert.ok(sys.includes('<think> and </think>'), `the think guide is missing: ${sys}`);
+  assert.match(sys, /use exactly these names/i);
+});

package/tests/ui.test.mjs

@@ -89,22 +89,29 @@ test('a profile without outFormat keeps auto routing through a save', () => {
   assert.match(html, /getElementById\('p-outformat'\)\.value = p\.outFormat \|\| '';/);
 });
 
-// The 1M box is locked only when the model's window is known and under 1M. An unknown window
-// only warns: many gateways list no limits at all.
-test('contextVerdict locks only a window known to be under 1M', () => {
-  const verdict = new Function(functionBody('contextVerdict') + '\n    }\n    return contextVerdict;')();
-  assert.equal(verdict(undefined).kind, 'unknown');
-  assert.equal(verdict({ output: 32000 }).kind, 'unknown');
-  assert.equal(verdict({ context: 200000 }).kind, 'small');
-  assert.equal(verdict({ context: 200000 }).window, 200000);
-  assert.equal(verdict({ input: 1000000 }).kind, 'ok');
-  assert.equal(verdict({ context: 1048576 }).kind, 'ok');
+// The window is the model's own, so the dashboard reports it and offers no switch. A model the
+// gateway lists with no window says nothing, and a compact window below the whole one is the
+// point the tool compresses at.
+test('windowLine reports the window the gateway lists, and nothing when it lists none', () => {
+  // functionBody stops before the closing brace, so a helper it calls is closed here.
+  const source = `${functionBody('fmtTokens')}\n    }\n${functionBody('windowLine')}\n    }\n    return windowLine;`;
+  const withLimits = limits => new Function('loadedLimits', source)(limits);
+  const line = withLimits({});
+  assert.equal(line(undefined), '');
+  assert.equal(line('bare'), '', 'a model with no limits says nothing');
+  const loaded = { bare: { output: 32000 }, big: { context: 1048576 }, codex: { context: 872000, compact: 272000 } };
+  const listed = withLimits(loaded);
+  assert.equal(listed('big'), '1M context');
+  assert.equal(listed('codex'), '872K context, compacts at 272K');
+  assert.equal(listed('bare'), '', 'limits without a window are not a window');
 });
 
-test('each 1M box names its slot and points at its note', () => {
+test('the 1M switch is gone from the slots, the card and the payload', () => {
   const slots = functionBody('renderModelSlots');
-  assert.match(slots, /aria-label="1M context for \$\{escapeHtml\(s\.name\)\}"/);
-  assert.match(slots, /aria-describedby="p-\$\{s\.id\}-1m-note"/);
-  assert.match(slots, /class="slot-1m-note" id="p-\$\{s\.id\}-1m-note" role="status"/);
-  assert.doesNotMatch(html, /\.slot-1m-note:empty \{ display: none/);
+  assert.doesNotMatch(slots, /type="checkbox"/, 'a model slot offers no window switch');
+  assert.match(slots, /class="slot-note" id="p-\$\{s\.id\}-note" role="status"/);
+  assert.match(slots, /oninput="updateWindowNotes\(\)"/, 'typing a model refreshes its window');
+  assert.doesNotMatch(html, /id="warn-1m-callout"/);
+  assert.doesNotMatch(functionBody('collectCurrentSlotValues'), /model1M\s*[,}]/);
+  assert.doesNotMatch(html, /profilePayload\.model1M/);
 });

package/tests/update.test.mjs

@@ -1,14 +1,29 @@
-// The update itself: a git checkout pulls fast-forward only, an npm install asks the registry.
-// Every remote here is a local bare repository or a local HTTP server.
+// The update itself: npm is asked first and installs the version the registry names; a git
+// checkout is the fallback, and pulls fast-forward only. Every remote here is a local bare
+// repository or a local HTTP server.
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import http from 'node:http';
 import os from 'node:os';
 import path from 'node:path';
-import { execFileSync } from 'node:child_process';
+import { execFile, execFileSync } from 'node:child_process';
+import { promisify } from 'node:util';
 import { applyUpdate } from '../update.mjs';
 
+const execFileAsync = promisify(execFile);
+
+// Records every command in the order it is asked. git runs for real, because the checkout has to
+// move before the fallback can be observed. npm's install is recorded and not run: the version a
+// fixture registry names is a number from the test, not one the real registry serves, and a real
+// install would put a package on the machine running the suite.
+const recording = (calls) => async (cmd, args, opts) => {
+  calls.push([cmd, ...args]);
+  if (cmd === 'npm' || cmd === 'cmd.exe') return '';
+  const { stdout } = await execFileAsync(cmd, args, { encoding: 'utf8', ...opts });
+  return stdout;
+};
+
 const git = (cwd, ...args) => execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
 const ID = ['-c', 'user.name=t', '-c', 'user.email=t@t', '-c', 'commit.gpgsign=false'];
 
@@ -50,14 +65,14 @@ function fixture(t) {
 test('a checkout behind its upstream pulls and reports the new version', async (t) => {
   const fx = fixture(t);
   fx.release('1.0.1');
-  const r = await applyUpdate({ root: fx.install });
+  const r = await applyUpdate({ root: fx.install, registryUrl: await registry(t, '1.0.0') });
   assert.deepEqual({ updated: r.updated, from: r.from, to: r.to }, { updated: true, from: '1.0.0', to: '1.0.1' });
   assert.equal(JSON.parse(fs.readFileSync(path.join(fx.install, 'package.json'), 'utf8')).version, '1.0.1');
 });
 
 test('a checkout level with its upstream does nothing', async (t) => {
   const fx = fixture(t);
-  const r = await applyUpdate({ root: fx.install });
+  const r = await applyUpdate({ root: fx.install, registryUrl: await registry(t, '1.0.0') });
   assert.equal(r.updated, false);
   assert.match(r.reason, /latest/i);
 });
@@ -66,7 +81,7 @@ test('a gateway that runs older code than its checkout restarts into it, with no
   const fx = fixture(t);
   fx.release('1.0.1');
   git(fx.install, 'pull', '-q', '--ff-only');
-  const r = await applyUpdate({ root: fx.install, running: '1.0.0' });
+  const r = await applyUpdate({ root: fx.install, running: '1.0.0', registryUrl: await registry(t, '1.0.1') });
   assert.deepEqual({ updated: r.updated, from: r.from, to: r.to }, { updated: true, from: '1.0.0', to: '1.0.1' });
 });
 
@@ -75,7 +90,7 @@ test('a checkout with local edits is left alone, even when upstream moved', asyn
   fx.release('1.0.1');
   const before = fx.head();
   fs.appendFileSync(path.join(fx.install, 'package.json'), ' ');
-  const r = await applyUpdate({ root: fx.install });
+  const r = await applyUpdate({ root: fx.install, registryUrl: await registry(t, '1.0.0') });
   assert.equal(r.updated, false);
   assert.match(r.reason, /local changes/i);
   assert.equal(fx.head(), before);
@@ -85,7 +100,7 @@ test('a checkout that is only ahead of upstream does nothing', async (t) => {
   const fx = fixture(t);
   fs.writeFileSync(path.join(fx.install, 'local.txt'), 'x');
   commit(fx.install, 'local work');
-  const r = await applyUpdate({ root: fx.install });
+  const r = await applyUpdate({ root: fx.install, registryUrl: await registry(t, '1.0.0') });
   assert.equal(r.updated, false);
 });
 
@@ -95,7 +110,7 @@ test('a diverged checkout fails and is never merged', async (t) => {
   commit(fx.install, 'local work');
   fx.release('1.0.1');
   const before = fx.head();
-  await assert.rejects(applyUpdate({ root: fx.install }), /fast-forward|diverged/i);
+  await assert.rejects(applyUpdate({ root: fx.install, registryUrl: await registry(t, '1.0.0') }), /fast-forward|diverged/i);
   assert.equal(fx.head(), before);
 });
 
@@ -159,3 +174,71 @@ test('an unreachable registry is not an update', async (t) => {
   assert.equal(r.updated, false);
   assert.match(r.reason, /registry/i);
 });
+
+// ---- npm first, and the checkout only when npm cannot serve it ----
+
+test('a release on npm is installed before the checkout is asked at all', async (t) => {
+  const fx = fixture(t);
+  fx.release('1.0.1');
+  const calls = [];
+  const r = await applyUpdate({ root: fx.install, registryUrl: await registry(t, '1.0.1'), run: recording(calls) });
+
+  const order = calls.map(c => c[0]);
+  assert.deepEqual(order.slice(0, 2), ['npm', 'git'], `npm first, then the checkout: ${order.join(' ')}`);
+  assert.deepEqual(calls[0].slice(-3), ['install', '-g', 'llm-switcher@1.0.1']);
+  // npm put the release in the global prefix, which is not this directory, so the checkout is what
+  // moved -- and that is the version this gateway runs, which is the only reason the pull happened.
+  assert.match(r.reason, /Pulled 1 commit/);
+  assert.deepEqual({ updated: r.updated, from: r.from, to: r.to }, { updated: true, from: '1.0.0', to: '1.0.1' });
+});
+
+test('a checkout level with its upstream runs no git pull when npm had nothing newer', async (t) => {
+  const fx = fixture(t);
+  const calls = [];
+  const r = await applyUpdate({ root: fx.install, registryUrl: await registry(t, '1.0.0'), run: recording(calls) });
+
+  assert.equal(calls.some(c => c[0] === 'npm' && c.includes('install')), false, 'no install when npm is not newer');
+  assert.equal(calls.some(c => c.includes('pull')), false, 'nothing to pull');
+  assert.match(r.reason, /latest/i);
+});
+
+test('npm holding a release the checkout cannot take is said plainly, not hidden by "latest"', async (t) => {
+  const fx = fixture(t);
+  // The checkout is level, and the registry is a version ahead of it: the two answers disagree.
+  const r = await applyUpdate({ root: fx.install, registryUrl: await registry(t, '1.4.0'), run: recording([]) });
+
+  assert.equal(r.updated, false);
+  assert.match(r.reason, /npm installed v1\.4\.0, but not into/);
+  assert.match(r.reason, /latest/i, 'the checkout answer is kept as well');
+});
+
+test('a checkout is still updated by git when the registry cannot be reached', async (t) => {
+  const fx = fixture(t);
+  fx.release('1.0.1');
+  const r = await applyUpdate({ root: fx.install, registryUrl: 'http://127.0.0.1:9/' });
+
+  assert.deepEqual({ updated: r.updated, from: r.from, to: r.to }, { updated: true, from: '1.0.0', to: '1.0.1' });
+});
+
+test('an npm install that fails does not stop a checkout from updating', async (t) => {
+  const fx = fixture(t);
+  fx.release('1.0.1');
+  const logs = [];
+  // npm refuses the version a fixture registry names, the way a real registry would.
+  const run = async (cmd, args, opts) => {
+    if (cmd === 'npm') throw new Error('npm install failed: notarget No matching version found');
+    return recording([])(cmd, args, opts);
+  };
+  const r = await applyUpdate({ root: fx.install, registryUrl: await registry(t, '1.0.1'), run, logger: m => logs.push(m) });
+
+  assert.deepEqual({ updated: r.updated, from: r.from, to: r.to }, { updated: true, from: '1.0.0', to: '1.0.1' });
+  assert.match(r.reason, /Pulled 1 commit/);
+  // The npm failure is said out loud, not swallowed into a success nobody can explain.
+  assert.match(logs.join('\n'), /npm could not install it here/);
+});
+
+test('an npm install behind the registry still fails loudly when there is no checkout', async (t) => {
+  const root = npmInstall(t, '1.0.0');
+  const run = async () => { throw new Error('npm install failed: EACCES'); };
+  await assert.rejects(applyUpdate({ root, registryUrl: await registry(t, '1.0.1'), run }), /npm install failed/);
+});