mixdog 1.2.0 → 1.2.1

package/src/runtime/agent/orchestrator/providers/account-pool.mjs

@@ -3,9 +3,11 @@ import {
   accountScopedSessionId,
   readProviderAccountPool,
   chooseProviderAccount,
-  changeProviderAccounts,
+  selectProviderAccountIf,
   blockProviderAccount,
   providerAccountExhausted,
+  providerAccountExhaustedForModelOnly,
+  providerAccountPolicy,
   providerAccountsResetAt,
 } from '../../../shared/provider-accounts.mjs';
 import { withProviderAccount, hasExplicitProviderAuthBinding } from '../../../shared/provider-auth-binding.mjs';
@@ -116,13 +118,82 @@ function boundAccountSend(providerName, row, messages, options) {
   return { opts, history, emitted: () => emitted };
 }
 
-// Commit only a successful fallback, without overwriting a newer selection.
-function commitFallbackAccount(providerName, pool, row) {
-  if (row.id === pool.selectedId) return;
-  const current = readProviderAccountPool(providerName);
-  if (current.selectedId === pool.selectedId && current.accounts.some((entry) => entry.id === row.id)) {
-    return changeProviderAccounts(providerName, { selectedId: row.id });
+// Commit only a successful fallback, without overwriting a newer selection:
+// the selection is compared under the write's lock, not before it. A fallback
+// forced by a model-scoped limit ("7D Fable" full, or a block attributed to
+// one family) serves this request only: the selected account still serves
+// every other model, so it stays the provider's account of record.
+async function commitFallbackAccount(providerName, pool, row, model, refusalScoped, policy) {
+  if (row.id === pool.selectedId || refusalScoped) return null;
+  if (accountExhaustedForModelOnly(providerName, pool.selectedId, model)) return null;
+  return selectProviderAccountIf(providerName, pool.selectedId, row.id, policy);
+}
+
+// The account each session runs on under the headroom policy. Every answer
+// records its provider and account in the assistant message's
+// `providerMetadata` (and in provider state when the adapter keeps one), so
+// the binding survives a restart and eviction from this map, which only
+// spares the history walk. Bounded, oldest binding first out.
+const SESSION_ACCOUNT_LIMIT = 1000;
+const ROUTING_METADATA_KEY = 'accountRouting';
+const sessionAccounts = new Map();
+
+// Forget every in-memory binding, as a restart does (tests).
+export function resetSessionAccountBindings() {
+  sessionAccounts.clear();
+}
+
+function rememberSessionAccount(key, id) {
+  sessionAccounts.delete(key);
+  sessionAccounts.set(key, id);
+  if (sessionAccounts.size > SESSION_ACCOUNT_LIMIT) sessionAccounts.delete(sessionAccounts.keys().next().value);
+}
+
+function accountExhaustedForModelOnly(providerName, id, model) {
+  const pool = readProviderAccountPool(providerName);
+  const row = pool.accounts.find((entry) => entry.id === id);
+  return (
+    Boolean(row) &&
+    providerAccountExhaustedForModelOnly(row, Date.now(), model, { useCredits: pool.useCredits === true })
+  );
+}
+
+// Only a binding recorded for THIS provider counts: a session that switched
+// providers carries another roster's account ids (every roster has a `default`).
+// The session's binding is read before the serving account, which differs
+// when a model-scoped limit lent this one answer to another account.
+function sessionAccountId(providerName, key, messages, options) {
+  if (key && sessionAccounts.has(key)) return sessionAccounts.get(key);
+  const state = options.providerState;
+  if (state?.providerAccountId && state.providerAccountProvider === providerName) {
+    return state.providerSessionAccountId || state.providerAccountId;
+  }
+  for (let index = (messages?.length || 0) - 1; index >= 0; index -= 1) {
+    const routing = messages[index]?.providerMetadata?.[ROUTING_METADATA_KEY];
+    if (routing?.accountId && routing.provider === providerName) return routing.sessionAccountId || routing.accountId;
+  }
+  return null;
+}
+
+// Stamp the serving account on the answer, independent of transport state,
+// with the account the session stays bound to (`bindingId`).
+function recordServingAccount(providerName, result, id, bindingId) {
+  if (!result || typeof result !== 'object') return;
+  if (result.providerReplay) result.providerReplay = { ...result.providerReplay, accountId: id };
+  if (result.providerState) {
+    result.providerState = {
+      ...result.providerState,
+      providerAccountId: id,
+      providerSessionAccountId: bindingId,
+      providerAccountProvider: providerName,
+    };
   }
+  const metadata =
+    result.providerMetadata && typeof result.providerMetadata === 'object' ? result.providerMetadata : {};
+  result.providerMetadata = {
+    ...metadata,
+    [ROUTING_METADATA_KEY]: { provider: providerName, accountId: id, sessionAccountId: bindingId },
+  };
 }
 
 // Whether the failed account's quota window is exhausted, plus the server's
@@ -158,12 +229,18 @@ function poolSend(providerName, account) {
     let lastError;
     let probed = false;
     const evidenced = new Set();
+    const sessionKey = options.sessionId ? `${providerName}:${options.sessionId}` : null;
+    const boundId = sessionAccountId(providerName, sessionKey, messages, options);
+    // Whether this send already left an account, and whether the latest quota
+    // refusal held only for this model's family.
+    let switched = false;
+    let refusalScoped = false;
     // Mark `error` only when every account in `ids` (default: the roster) is
     // exhausted with quota evidence: observed in this send, or a full window.
     const markExhausted = (error, ids) => {
       const pool = readProviderAccountPool(providerName);
-      // Auto switching off: the eligible set is the selected account alone.
-      const scope = ids || (pool.auto === false ? [pool.selectedId] : null);
+      // Manual policy: the eligible set is the selected account alone.
+      const scope = ids || (providerAccountPolicy(pool) === 'manual' ? [pool.selectedId] : null);
       const rows = scope ? pool.accounts.filter((entry) => scope.includes(entry.id)) : pool.accounts;
       const opts = { useCredits: pool.useCredits === true };
       const now = Date.now();
@@ -194,7 +271,8 @@ function poolSend(providerName, account) {
         }
         return account('default').send(messages, model, tools, options);
       }
-      const row = chooseProviderAccount(pool, attempted, Date.now(), model);
+      const policy = providerAccountPolicy(pool);
+      const row = chooseProviderAccount(pool, attempted, Date.now(), model, { sessionAccountId: boundId });
       if (!row) {
         // Once per send: a refusal built on a stale meter must not outlive the
         // meter. Re-measuring can only widen the roster, so it is tried before
@@ -209,9 +287,18 @@ function poolSend(providerName, account) {
       const bound = boundAccountSend(providerName, row, messages, options);
       try {
         const result = await account(row.id).send(bound.history, model, tools, bound.opts);
-        if (result?.providerReplay) result.providerReplay = { ...result.providerReplay, accountId: row.id };
-        if (result?.providerState) result.providerState = { ...result.providerState, providerAccountId: row.id };
-        if (commitFallbackAccount(providerName, pool, row)) {
+        // Headroom policy: a session's first pick, or its move off its account
+        // on a limit, becomes the selection; continuing on its account does
+        // not, so concurrent sessions never flip the selection back and forth.
+        // A move forced by a model-scoped limit serves this request only.
+        const leftBound = Boolean(boundId) && row.id !== boundId;
+        const scoped = switched
+          ? refusalScoped
+          : policy === 'headroom' && leftBound && accountExhaustedForModelOnly(providerName, boundId, model);
+        recordServingAccount(providerName, result, row.id, scoped && boundId ? boundId : row.id);
+        if (sessionKey && policy === 'headroom' && !scoped) rememberSessionAccount(sessionKey, row.id);
+        const commit = policy !== 'headroom' || !boundId || leftBound;
+        if (commit && (await commitFallbackAccount(providerName, pool, row, model, scoped, policy))) {
           // Publish only a committed selection, never a speculative retry or
           // one superseded by a manual switch. The existing progress channel
           // carries this across runtime shards to the attached UI.
@@ -230,7 +317,7 @@ function poolSend(providerName, account) {
         if (options.signal?.aborted) throw error;
         if (error?.reauthRequired === true) {
           if (
-            pool.auto === false ||
+            policy === 'manual' ||
             bound.emitted() ||
             error.unsafeToRetry ||
             error.liveTextEmitted ||
@@ -238,13 +325,15 @@ function poolSend(providerName, account) {
           )
             throw error;
           lastError = error;
+          switched = true;
+          refusalScoped = false;
           options.onStageChange?.('reconnecting', { message: 'Sign-in expired — switching to the next account' });
           continue;
         }
         const { exhausted, delay, evidence } = await accountQuotaExhausted(providerName, row, model, error, account);
         if (options.signal?.aborted || !exhausted) throw error;
         if (evidence) evidenced.add(row.id);
-        blockProviderAccount(
+        await blockProviderAccount(
           providerName,
           row.id,
           Date.now() + (delay > 0 ? delay : 5 * 60_000),
@@ -253,9 +342,11 @@ function poolSend(providerName, account) {
           { quota: evidence === true }
         );
         if (bound.emitted() || error.unsafeToRetry || error.liveTextEmitted || error.emittedToolCall) throw error;
-        // Auto switching off: the eligible set is the selected account alone.
-        if (pool.auto === false) throw markExhausted(error, [row.id]);
+        // Manual policy: the eligible set is the selected account alone.
+        if (policy === 'manual') throw markExhausted(error, [row.id]);
         lastError = error;
+        switched = true;
+        refusalScoped = accountExhaustedForModelOnly(providerName, row.id, model);
         options.onStageChange?.('reconnecting', { message: 'Quota exhausted — switching to the next account' });
       }
     }

package/src/runtime/agent/orchestrator/providers/anthropic-oauth-client-version.mjs

@@ -10,7 +10,7 @@ import { createNpmVersionSource, maxSemver } from './npm-cli-version.mjs';
 // source release just to advance the user-agent version.
 // Claude Opus 5.5 requires 2.1.280 or newer. The release workflow raises this
 // to the published CLI version (scripts/sync-client-version-floors.mjs).
-export const DEFAULT_CLI_VERSION = '2.1.296';
+export const DEFAULT_CLI_VERSION = '2.1.299';
 export const CLAUDE_CLI_NPM_PACKAGE = '@anthropic-ai/claude-code';
 
 const CACHE_SCHEMA_VERSION = 1;

package/src/runtime/agent/orchestrator/providers/anthropic.mjs

@@ -1,4 +1,4 @@
-import { getAgentApiKey } from '../../../shared/provider-api-key.mjs';
+import { reloadProviderApiKey, resolveProviderApiKey } from '../../../shared/provider-api-key.mjs';
 import { sanitizeToolPairs } from '../session/context-utils.mjs';
 import { AnthropicFallbackTriggeredError } from './retry-classifier.mjs';
 import { readStreamOutcome } from './lib/stream-outcome.mjs';
@@ -42,9 +42,19 @@ export class AnthropicProvider {
   constructor(config) {
     this.config = config || {};
     this.name = this.config.name || 'anthropic';
-    this.apiKey = this.config.apiKey || (this.name === 'anthropic' ? process.env.ANTHROPIC_API_KEY : null);
+    this.apiKey = resolveProviderApiKey(this.name, this.config) || null;
     this.client = this._createClient(this.apiKey);
   }
+  // Client for the currently resolved key; rebuilt when the key changed since
+  // it was built (e.g. a keyless-constructed instance).
+  _currentClient() {
+    const key = resolveProviderApiKey(this.name, this.config) || null;
+    if (key && key !== this.apiKey) {
+      this.apiKey = key;
+      this.client = this._createClient(key);
+    }
+    return this.client;
+  }
   // Tool-search is a request capability, not an account capability. Keep it
   // off the client defaults and add it only on turns that actually serialize
   // defer_loading tools.
@@ -55,8 +65,10 @@ export class AnthropicProvider {
     const custom = isCustomProviderName(this.name);
     const keyless = custom && this.config.keyless === true;
     const betaHeaders = this.config.disableBetaHeaders || custom ? null : buildAnthropicBetaHeaders();
+    let credentials = { apiKey };
+    if (custom) credentials = { apiKey: keyless ? '' : apiKey || '', authToken: null };
     return new (loadAnthropic())({
-      ...(custom ? { apiKey: keyless ? '' : apiKey || '', authToken: null } : { apiKey }),
+      ...credentials,
       ...(this.config.baseURL ? { baseURL: this.config.baseURL } : {}),
       defaultHeaders: {
         ...(betaHeaders ? { 'anthropic-beta': betaHeaders } : {}),
@@ -68,10 +80,7 @@ export class AnthropicProvider {
   }
   reloadApiKey() {
     try {
-      const newKey =
-        getAgentApiKey(this.name) ||
-        this.config.apiKey ||
-        (this.name === 'anthropic' ? process.env.ANTHROPIC_API_KEY : null);
+      const newKey = reloadProviderApiKey(this.name, this.config);
       if (newKey) {
         this.config = { ...(this.config || {}), apiKey: newKey };
         this.apiKey = newKey;
@@ -160,7 +169,7 @@ export class AnthropicProvider {
     // The SDK calls and their initial-response retry policy
     // (anthropic-api-transport.mjs).
     const transport = createAnthropicApiTransport({
-      client: this.client,
+      client: this._currentClient(),
       label: this.name,
       opts,
       useModel,
@@ -296,8 +305,7 @@ export class AnthropicProvider {
     }
   }
   async listModels() {
-    const apiKey =
-      this.apiKey || this.config?.apiKey || (this.name === 'anthropic' ? process.env.ANTHROPIC_API_KEY : null);
+    const apiKey = resolveProviderApiKey(this.name, this.config);
     if (!apiKey) return MODELS;
     try {
       const base = String(this.config?.baseURL || 'https://api.anthropic.com').replace(/\/+$/, '');
@@ -329,6 +337,6 @@ export class AnthropicProvider {
   async isAvailable() {
     // Availability probes must not spend tokens or depend on a live
     // network. Dispatch owns authentication validation and 401 reload.
-    return !!(this.apiKey || this.config?.apiKey || (this.name === 'anthropic' && process.env.ANTHROPIC_API_KEY));
+    return !!resolveProviderApiKey(this.name, this.config);
   }
 }

package/src/runtime/agent/orchestrator/providers/auto-effort.mjs

@@ -89,6 +89,15 @@ export function resolveAutoEffort({ base, options, probs }) {
   const ladder = autoEffortLadder(options);
   const at = ladder.indexOf(String(base ?? '').toLowerCase());
   if (at < 0) return null;
+  return resolveOnLadder(ladder, at, probs);
+}
+
+/** True when some judged outcome could apply: the base lies on the model's ladder. */
+export function autoEffortApplicable({ base, options }) {
+  return autoEffortLadder(options).includes(String(base ?? '').toLowerCase());
+}
+
+function resolveOnLadder(ladder, at, probs) {
   const { step, level, confidence } = judgedStep(probs);
   const effort = ladder[Math.max(0, Math.min(ladder.length - 1, at + step))];
   return { base: ladder[at], effort, step, level, confidence: Number(confidence.toFixed(3)) };

package/src/runtime/agent/orchestrator/providers/command-code-oauth-login.mjs

@@ -0,0 +1,337 @@
+// Command Code browser sign-in. The Studio CLI auth page mints a Provider API
+// key and POSTs it (with our one-shot state) as JSON to a loopback callback.
+// A pasted key or pasted callback JSON completes the same login by hand. The
+// first sign-in on a machine adopts an existing Command Code CLI login instead.
+import { createServer } from 'node:http';
+import { randomBytes } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { openLoginUrl } from './lib/open-login-url.mjs';
+import { readProviderAccountPool } from '../../../shared/provider-accounts.mjs';
+import { withProviderAccount } from '../../../shared/provider-auth-binding.mjs';
+import {
+  LOGIN_TIMEOUT_MS,
+  PROVIDER_ID,
+  STUDIO_ORIGIN,
+  fetchCommandCodeIdentity,
+  isWellFormedApiKey,
+  loadTokens,
+  saveTokens,
+} from './command-code-oauth-tokens.mjs';
+
+export const CALLBACK_PORT = 5959;
+const CALLBACK_PATH = '/callback';
+const MAX_CALLBACK_BYTES = 16 * 1024;
+const CALLBACK_FIELDS = Object.freeze(['apiKey', 'userId', 'userName', 'keyName']);
+
+const CORS_HEADERS = Object.freeze({
+  'Access-Control-Allow-Origin': STUDIO_ORIGIN,
+  'Access-Control-Allow-Methods': 'POST, OPTIONS',
+  'Access-Control-Allow-Headers': 'Content-Type',
+  // The Studio page is public and the callback is loopback: Chromium asks first.
+  'Access-Control-Allow-Private-Network': 'true',
+  Vary: 'Origin',
+});
+
+export const defaultLocalAuthPath = () => join(homedir(), '.commandcode', 'auth.json');
+
+/** Validate the Studio callback body against this login's state. */
+export function parseCallbackPayload(value, expectedState) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('[command-code-oauth] callback body must be an object');
+  }
+  if (typeof value.state !== 'string' || !expectedState || value.state !== expectedState) {
+    throw new Error('[command-code-oauth] callback state mismatch');
+  }
+  for (const field of CALLBACK_FIELDS) {
+    if (typeof value[field] !== 'string' || !value[field].trim()) {
+      throw new Error(`[command-code-oauth] callback is missing ${field}`);
+    }
+  }
+  const apiKey = value.apiKey.trim();
+  if (!isWellFormedApiKey(apiKey)) throw new Error('[command-code-oauth] callback carried a malformed API key');
+  return { apiKey, userId: value.userId.trim(), userName: value.userName.trim(), keyName: value.keyName.trim() };
+}
+
+/** A paste is either the callback JSON (state-checked) or a bare API key. */
+export function parsePastedInput(input, expectedState) {
+  const pasted = String(input ?? '').trim();
+  if (!pasted) throw new Error('[command-code-oauth] API key is required');
+  if (pasted.startsWith('{')) {
+    let doc;
+    try {
+      doc = JSON.parse(pasted);
+    } catch {
+      throw new Error('[command-code-oauth] pasted callback is not valid JSON');
+    }
+    return parseCallbackPayload(doc, expectedState);
+  }
+  if (!isWellFormedApiKey(pasted)) throw new Error('[command-code-oauth] pasted API key is malformed');
+  return { apiKey: pasted, userId: '', userName: '', keyName: '' };
+}
+
+// No account of this provider is connected yet: no roster entry and no
+// credential in the default slot. Adding a second account or reconnecting an
+// existing one must pick a fresh browser identity, never the local CLI login.
+function isFirstSignIn() {
+  try {
+    if (readProviderAccountPool(PROVIDER_ID).accounts.length) return false;
+    return !withProviderAccount(PROVIDER_ID, 'default', () => loadTokens());
+  } catch {
+    // An unreadable roster cannot prove this is the first account.
+    return false;
+  }
+}
+
+function readLocalAuth(path) {
+  try {
+    const doc = JSON.parse(readFileSync(path, 'utf-8'));
+    const apiKey = typeof doc?.apiKey === 'string' ? doc.apiKey.trim() : '';
+    const userId = typeof doc?.userId === 'string' ? doc.userId.trim() : '';
+    return apiKey && userId && isWellFormedApiKey(apiKey) ? { apiKey, userId } : null;
+  } catch {
+    return null;
+  }
+}
+
+function listenOn(server, port, host) {
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, host, () => {
+      server.off('error', reject);
+      resolve();
+    });
+  });
+}
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    req.on('data', (chunk) => {
+      size += chunk.length;
+      if (size > MAX_CALLBACK_BYTES) {
+        reject(new Error('[command-code-oauth] callback body too large'));
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
+    req.on('error', reject);
+  });
+}
+
+function reply(res, status, body) {
+  res.writeHead(status, { ...CORS_HEADERS, ...(body ? { 'Content-Type': 'application/json' } : {}) });
+  res.end(body ? JSON.stringify(body) : undefined);
+}
+
+function authorizeUrl(port, state) {
+  const url = new URL('/studio/auth/cli', STUDIO_ORIGIN);
+  url.searchParams.set('callback', `http://127.0.0.1:${port}${CALLBACK_PATH}`);
+  url.searchParams.set('state', state);
+  return url.toString();
+}
+
+export async function beginOAuthLogin({
+  openBrowser = true,
+  timeoutMs = LOGIN_TIMEOUT_MS,
+  fetchImpl = fetch,
+  port: preferredPort = CALLBACK_PORT,
+  importLocal = isFirstSignIn(),
+  localAuthPath = defaultLocalAuthPath(),
+  printUrl = false,
+} = {}) {
+  // Validate and store a key under its whoami identity.
+  const store = async (candidate, signal) => {
+    const identity = await fetchCommandCodeIdentity(candidate.apiKey, { fetchImpl, signal });
+    return { apiKey: candidate.apiKey, userId: identity.userId, userName: identity.userName || candidate.userName };
+  };
+
+  if (importLocal) {
+    const local = readLocalAuth(localAuthPath);
+    if (local) {
+      let tokens = null;
+      try {
+        tokens = saveTokens(await store(local));
+      } catch {
+        /* a stale or rejected CLI login falls through to the browser */
+      }
+      if (tokens) {
+        return {
+          provider: PROVIDER_ID,
+          url: '',
+          manualUrl: null,
+          imported: true,
+          waitForCallback: Promise.resolve(tokens),
+          cancel: () => {},
+        };
+      }
+    }
+  }
+
+  const state = randomBytes(32).toString('base64url');
+  const servers = [];
+  // Open client connections, and the ones still owed a reply by a request
+  // that is completing the login.
+  const sockets = new Set();
+  const replying = new Set();
+  const work = new AbortController();
+  let timer = null;
+  let finish = null;
+  let settled = false;
+  const waitForCallback = new Promise((resolve, reject) => {
+    finish = (value, error = null) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      work.abort();
+      for (const server of servers) {
+        try {
+          server.close();
+        } catch {
+          /* already closed */
+        }
+      }
+      // close() only stops accepting: drop every connection (a stalled
+      // partial POST included) except those about to get their reply.
+      for (const socket of sockets) if (!replying.has(socket)) socket.destroy();
+      if (error) reject(error);
+      else resolve(value);
+    };
+    timer = setTimeout(
+      () => finish(null, new Error(`[command-code-oauth] login timed out after ${Math.round(timeoutMs / 1000)}s`)),
+      timeoutMs
+    );
+  });
+  // A caller may only use the paste path; a later timeout/cancel must not be an unhandled rejection.
+  waitForCallback.catch(() => {});
+
+  // The credential is written only while the login is still open, and the
+  // login completes in the same synchronous step.
+  const settle = async (candidate) => {
+    const tokens = await store(candidate, work.signal);
+    if (settled) throw new Error('[command-code-oauth] login is no longer active');
+    const saved = saveTokens(tokens);
+    finish(saved);
+    return saved;
+  };
+
+  const handleRequest = async (req, res) => {
+    const origin = req.headers.origin;
+    if (origin && origin !== STUDIO_ORIGIN) return reply(res, 403, { success: false, error: 'Forbidden origin' });
+    if (req.method === 'OPTIONS') return reply(res, 204, null);
+    let pathname;
+    try {
+      pathname = new URL(req.url || '/', 'http://127.0.0.1').pathname;
+    } catch {
+      return reply(res, 400, { success: false, error: 'Bad request' });
+    }
+    if (pathname !== CALLBACK_PATH || settled) {
+      return reply(res, 404, { success: false, error: 'Not found' });
+    }
+    if (req.method !== 'POST') return reply(res, 405, { success: false, error: 'Method not allowed' });
+    // Anything that is not this login's well-formed callback is refused and
+    // the login keeps waiting.
+    let doc;
+    try {
+      doc = JSON.parse(await readBody(req));
+    } catch {
+      return reply(res, 400, { success: false, error: 'Invalid JSON body' });
+    }
+    let candidate;
+    try {
+      candidate = parseCallbackPayload(doc, state);
+    } catch (err) {
+      return reply(res, 400, { success: false, error: String(err.message).replace(/^\[command-code-oauth\]\s*/, '') });
+    }
+    replying.add(req.socket);
+    try {
+      await settle(candidate);
+      reply(res, 200, { success: true });
+    } catch (err) {
+      reply(res, 400, { success: false, error: 'API key validation failed' });
+      finish(null, err instanceof Error ? err : new Error(String(err)));
+    }
+  };
+
+  // No request can fail outside this handler; once the login is over, a
+  // connection closes as soon as its reply is flushed.
+  const onRequest = (req, res) => {
+    res.on('finish', () => {
+      replying.delete(req.socket);
+      if (settled) req.socket.destroy();
+    });
+    handleRequest(req, res).catch(() => {
+      replying.delete(req.socket);
+      if (res.headersSent) res.destroy();
+      else reply(res, 400, { success: false, error: 'Bad request' });
+    });
+  };
+  const trackSockets = (server) => {
+    server.on('connection', (socket) => {
+      if (settled) {
+        socket.destroy();
+        return;
+      }
+      sockets.add(socket);
+      socket.on('close', () => {
+        sockets.delete(socket);
+        replying.delete(socket);
+      });
+    });
+    return server;
+  };
+
+  // The advertised callback is 127.0.0.1; ::1 is bound on the same port when
+  // possible because `localhost` may resolve to it first.
+  let primary = trackSockets(createServer(onRequest));
+  try {
+    try {
+      await listenOn(primary, preferredPort, '127.0.0.1');
+    } catch (err) {
+      // The fixed port is taken (another login, another app): any free port.
+      if (!preferredPort) throw err;
+      primary = trackSockets(createServer(onRequest));
+      await listenOn(primary, 0, '127.0.0.1');
+    }
+  } catch (err) {
+    finish(null, err);
+    throw err;
+  }
+  const port = primary.address().port;
+  servers.push(primary);
+  const secondary = trackSockets(createServer(onRequest));
+  try {
+    await listenOn(secondary, port, '::1');
+    servers.push(secondary);
+  } catch {
+    /* no IPv6 loopback: the IPv4 listener is enough */
+  }
+  for (const server of servers) {
+    server.on('error', (err) =>
+      finish(null, new Error(`[command-code-oauth] callback server failed: ${err?.message || err}`))
+    );
+  }
+
+  const url = authorizeUrl(port, state);
+  if (printUrl) process.stderr.write(`\n[command-code-oauth] Open this URL to sign in:\n${url}\n\n`);
+  if (openBrowser) await openLoginUrl(PROVIDER_ID, url);
+
+  return {
+    provider: PROVIDER_ID,
+    url,
+    manualUrl: null,
+    port,
+    waitForCallback,
+    completeCode: async (input) => settle(parsePastedInput(input, state)),
+    cancel: () => finish(null),
+  };
+}
+
+export async function loginOAuth() {
+  const login = await beginOAuthLogin({ printUrl: true });
+  return await login.waitForCallback;
+}