mixdog 1.1.0 → 1.1.2

package/src/lib/rules-builder.cjs

@@ -9,7 +9,6 @@
  *   - buildAgentRoleContent             — BP3: agent role/system rules
  *   - buildAgentRetrievalInjectionContent — BP3: narrow read-only retrieval role
  *   - buildLeadMetaContent              — BP2: Lead profile/settings context
- *   - buildInjectionContent             — legacy joined Lead session content
  *
  * 4-BP cache layout (composeSystemPrompt):
  *   BP1 = shared tool policy
@@ -400,27 +399,6 @@ function buildLeadLanguageContent({ DATA_DIR }) {
   return buildLanguageSection(DATA_DIR);
 }
 
-/**
- * Build the Lead injection content.
- */
-function buildInjectionContent({ PLUGIN_ROOT, DATA_DIR }) {
-  const parts = [];
-
-  const tool = buildSharedToolContent({ PLUGIN_ROOT });
-  if (tool) parts.push(tool);
-
-  const meta = buildLeadMetaContent({ PLUGIN_ROOT, DATA_DIR });
-  if (meta) parts.push(meta);
-
-  const role = buildLeadRoleContent({ PLUGIN_ROOT, DATA_DIR });
-  if (role) parts.push(role);
-
-  const language = buildLeadLanguageContent({ DATA_DIR });
-  if (language) parts.push(language);
-
-  return parts.join('\n\n');
-}
-
 function buildAgentRoleContent({ PLUGIN_ROOT, profile = 'full' }) {
   const AGENT_DIR = path.join(PLUGIN_ROOT, 'rules', 'agent');
   if (String(profile || 'full') === 'retrieval') {
@@ -455,7 +433,6 @@ module.exports = {
   buildLeadMetaContent,
   buildLeadLanguageContent,
   buildAgentRoleContent,
-  buildInjectionContent,
   buildAgentRetrievalInjectionContent,
   omitToolRoutes,
 };

package/src/rules/lead/LEAD.md

@@ -10,8 +10,8 @@
   never per-call narration or plan repeats.
 - Mid-task: a replacement supersedes, an addition folds in, a status question
   gets a brief answer while work continues.
-- Context is managed automatically: never propose stopping or stop on your own
-  judgment.
+- Context is managed automatically: never stop or propose stopping because of
+  context size.
 - Be a grounded, candid, and attentive collaborator: natural and respectful,
   without flattery, forced humor, mimicry, or stereotyping.
 <!-- tools: agent -->

package/src/runtime/agent/orchestrator/config-storage.mjs

@@ -2,6 +2,11 @@ import { hasExtensionScopes, normalizeExtensionScopes } from '../../shared/exten
 import { agentRouteStorageNeedsMigration, canonicalizeAgentRouteStorage } from '../../shared/agent-route-config.mjs';
 import profileConfig from '../../shared/profile-config.cjs';
 import { normalizeAgentProviderId, normalizePreset } from './config-presets.mjs';
+import {
+  loadSavedCodexCatalog,
+  migrateCodexRoute,
+  supersededCodexSettingsKey,
+} from './providers/openai-oauth-catalog-store.mjs';
 
 const { normalizeProfileConfig } = profileConfig;
 const RETIRED_LOCAL_PROVIDER_IDS = new Set(['ollama', 'lmstudio']);
@@ -205,7 +210,20 @@ function retiredLocalProviderStoragePresent(value = {}) {
   );
 }
 
+// Saved routes on a model the provider catalog has superseded (see
+// openai-oauth-catalog-store.mjs) — read from the last fetched catalog.
+function supersededRouteStoragePresent(value = {}, catalog = loadSavedCodexCatalog()) {
+  const superseded = (route) => migrateCodexRoute(route, catalog) !== route;
+  return (
+    (Array.isArray(value?.presets) && value.presets.some(superseded)) ||
+    Object.values(configObject(value?.agents)).some(superseded) ||
+    Object.values(configObject(value?.maintenance)).some(superseded) ||
+    Object.keys(configObject(value?.modelSettings)).some((key) => supersededCodexSettingsKey(key, catalog))
+  );
+}
+
 export function canonicalizeAgentStorage(value = {}) {
+  const catalog = loadSavedCodexCatalog();
   const next = canonicalizeAgentRouteStorage(value);
   const removedPresetIds = new Set(
     (Array.isArray(next.presets) ? next.presets : [])
@@ -216,17 +234,26 @@ export function canonicalizeAgentStorage(value = {}) {
   next.providers = configObject(next.providers);
   for (const id of RETIRED_LOCAL_PROVIDER_IDS) delete next.providers[id];
   next.presets = Array.isArray(next.presets)
-    ? next.presets.map((preset) => normalizePreset(preset)).filter((preset) => preset && !isRetiredLocalRoute(preset))
+    ? next.presets
+        .map((preset) => normalizePreset(migrateCodexRoute(preset, catalog)))
+        .filter((preset) => preset && !isRetiredLocalRoute(preset))
     : [];
   if (removedPresetIds.has(String(next.default || '').trim())) next.default = null;
   next.agents = Object.fromEntries(
-    Object.entries(configObject(next.agents)).filter(([, route]) => !isRetiredLocalRoute(route))
+    Object.entries(configObject(next.agents))
+      .filter(([, route]) => !isRetiredLocalRoute(route))
+      .map(([id, route]) => [id, migrateCodexRoute(route, catalog)])
   );
   next.maintenance = Object.fromEntries(
-    Object.entries(configObject(next.maintenance)).filter(([, route]) => !isRetiredLocalRoute(route))
+    Object.entries(configObject(next.maintenance))
+      .filter(([, route]) => !isRetiredLocalRoute(route))
+      .map(([slot, route]) => [slot, migrateCodexRoute(route, catalog)])
   );
+  // A superseded model's own settings have no model left to apply to.
   next.modelSettings = Object.fromEntries(
-    Object.entries(normalizedModelSettings(value)).filter(([key]) => !isRetiredLocalModelKey(key))
+    Object.entries(normalizedModelSettings(value)).filter(
+      ([key]) => !isRetiredLocalModelKey(key) && !supersededCodexSettingsKey(key, catalog)
+    )
   );
   setOrDelete(next, 'autoClear', canonicalizeAutoClearStorage(next.autoClear));
   setOrDelete(next, 'compaction', canonicalizeCompactionStorage(next.compaction));
@@ -266,6 +293,7 @@ export function agentConfigStorageNeedsMigration(value = {}) {
   return (
     agentRouteStorageNeedsMigration(value) ||
     retiredLocalProviderStoragePresent(value) ||
+    supersededRouteStoragePresent(value) ||
     RETIRED_AGENT_FIELDS.some((key) => key !== 'guide' && Object.hasOwn(value || {}, key)) ||
     presets.some((preset) => !normalizePreset(preset)) ||
     (modules && typeof modules === 'object' && Object.hasOwn(modules, 'memory')) ||

package/src/runtime/agent/orchestrator/config.mjs

@@ -4,6 +4,10 @@ import { mergeStoredProviders } from './config-providers-merge.mjs';
 import { normalizeExtensionScopes } from '../../shared/extension-scopes.mjs';
 import { applyConfigPatch, diffConfig } from '../../shared/config-patch.mjs';
 import { normalizeWorkflowSelection } from '../../shared/orchestration.mjs';
+import {
+  DEFAULT_INSTRUCTION_FILES_MODE,
+  normalizeInstructionFilesMode,
+} from '../../shared/instruction-files-mode.mjs';
 import {
   DEFAULT_DISABLED_AGENT_ROSTER,
   canonicalizeAgentRouteStorage,
@@ -107,9 +111,13 @@ export function buildDefaultConfig(options = {}) {
   // stored in mixdog-config.json — enabled at runtime from the presence of
   // Mixdog-owned credentials.
   providers['grok-oauth'] = oauthEntry('grok-oauth');
+  // Muse Code subscription (Meta Muse Spark), enabled from its stored key.
+  providers['muse-code-oauth'] = oauthEntry('muse-code-oauth');
   // Dev-only providers (Settings → Developer → Providers, one option each):
   // omitted entirely from the default config while their option is off so
   // they never surface in settings.
+  // Experimental MiMo subscription: enabled from a stored platform API key.
+  if (isOAuthProviderAvailable('mimo-oauth')) providers['mimo-oauth'] = oauthEntry('mimo-oauth');
   // Experimental direct Cursor wire provider. It remains disabled unless a
   // Mixdog-owned login or CURSOR_ACCESS_TOKEN is present.
   if (isOAuthProviderAvailable('cursor-oauth')) providers['cursor-oauth'] = oauthEntry('cursor-oauth');
@@ -187,6 +195,13 @@ function normalizeRecapConfig(rawRecap) {
   return recap;
 }
 
+// `instructionFiles` (instruction-files-mode.mjs): only a valid non-default
+// mode is kept; absent means the default.
+function storedInstructionFiles(agent) {
+  const mode = normalizeInstructionFilesMode(agent?.instructionFiles);
+  return mode === DEFAULT_INSTRUCTION_FILES_MODE ? {} : { instructionFiles: mode };
+}
+
 export function loadConfig(options = {}) {
   const includeSecrets = options.secrets !== false;
   try {
@@ -245,6 +260,7 @@ export function loadConfig(options = {}) {
         // canonicalizeAgentRouteStorage drops it when empty.
         disabledAgents: legacyDisabledAgents ? disabledAgentIds(raw) : effectiveDisabledAgents(raw),
         ...(raw.memoryTools && typeof raw.memoryTools === 'object' ? { memoryTools: { ...raw.memoryTools } } : {}),
+        ...storedInstructionFiles(raw),
         ...normalizeWorkflowSelection(raw),
         profile: normalizeProfileConfig(raw.profile),
         skills: normalizeSkillsConfig(raw.skills),
@@ -420,6 +436,8 @@ function buildAgentSaveBuilder(config) {
     } else Object.assign(next, disabledAgentDelta(canonicalRoutes.disabledAgents));
     if (config.memoryTools && typeof config.memoryTools === 'object') next.memoryTools = { ...config.memoryTools };
     else delete next.memoryTools;
+    delete next.instructionFiles;
+    Object.assign(next, storedInstructionFiles(config));
     delete next.workflowRoutes;
     // Defaults live in code: values equal to the current default are not stored.
     return storedAgentForm(removeRetiredAgentFields(next));

package/src/runtime/agent/orchestrator/context/instruction-files.mjs

@@ -0,0 +1,130 @@
+// The user's instruction files (AGENTS.md / CLAUDE.md), global then project,
+// rendered as one `# Instruction Files` block for a new session's BP3 core.
+import { closeSync, constants, fstatSync, openSync, readSync, realpathSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import { readSection } from '../../../shared/config.mjs';
+import { normalizeInstructionFilesMode } from '../../../shared/instruction-files-mode.mjs';
+import { featureEnvOverride } from '../runtime-core/config-helpers.mjs';
+
+// Per-file budget in UTF-8 bytes (same byte-based cap as core memory).
+const INSTRUCTION_FILE_MAX_BYTES = 32 * 1024;
+const TRUNCATED_MARK = '\n\n[... truncated]';
+const KINDS_BY_MODE = { all: ['agents', 'claude'], agents: ['agents'], claude: ['claude'], off: [] };
+const GLOBAL_DIR = { agents: '.codex', claude: '.claude' };
+const FILE_NAME = { agents: 'AGENTS.md', claude: 'CLAUDE.md' };
+
+/** The configured mode, forced off by MIXDOG_BOOT_INSTRUCTION_FILES=0. */
+export function effectiveInstructionFilesMode(mode) {
+  if (featureEnvOverride('MIXDOG_BOOT_INSTRUCTION_FILES') === false) return 'off';
+  return normalizeInstructionFilesMode(mode);
+}
+
+/** The stored agent-config value; an unreadable config reads as the default. */
+export function configuredInstructionFilesMode() {
+  try {
+    return normalizeInstructionFilesMode(readSection('agent')?.instructionFiles);
+  } catch {
+    return normalizeInstructionFilesMode(undefined);
+  }
+}
+
+const UTF8_BOM = Buffer.from([0xef, 0xbb, 0xbf]);
+
+/** Candidate files in load order: global files first, then the project root's.
+ *  Project files are confined to the real directory of their `root`; global
+ *  files carry no root and may resolve anywhere. */
+function instructionFileCandidates({ mode, cwd, homeDir = homedir() } = {}) {
+  const kinds = KINDS_BY_MODE[effectiveInstructionFilesMode(mode)];
+  const candidates = [];
+  if (homeDir) {
+    const root = resolve(homeDir);
+    // Global files may be symlinks into a dotfiles repo: no containment root.
+    for (const kind of kinds) candidates.push({ path: join(root, GLOBAL_DIR[kind], FILE_NAME[kind]) });
+  }
+  if (cwd) {
+    const root = resolve(cwd);
+    for (const kind of kinds) candidates.push({ path: join(root, FILE_NAME[kind]), root });
+  }
+  return candidates;
+}
+
+function isInside(root, path) {
+  const rel = relative(root, path);
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+
+function skipNote(path, reason) {
+  process.stderr.write(`[instruction-files] skipped ${path}: ${reason}\n`);
+}
+
+/** At most the file's first cap bytes (plus a BOM allowance and one probe byte)
+ *  from an open fd, so a huge or endless file is never read whole. */
+function readHead(fd) {
+  const buffer = Buffer.allocUnsafe(INSTRUCTION_FILE_MAX_BYTES + UTF8_BOM.length + 1);
+  let length = 0;
+  while (length < buffer.length) {
+    const count = readSync(fd, buffer, length, buffer.length - length, null);
+    if (count === 0) break;
+    length += count;
+  }
+  return buffer.subarray(0, length);
+}
+
+/** Decode a head that may end mid-character: the incomplete tail is dropped. */
+function decodeHead(bytes) {
+  return new TextDecoder('utf-8').decode(bytes, { stream: true });
+}
+
+/** The bounded, trimmed text of one instruction file; over the budget it is cut
+ *  at a word boundary and ends with the truncation notice. */
+function boundedText(head) {
+  const bytes = head.subarray(0, UTF8_BOM.length).equals(UTF8_BOM) ? head.subarray(UTF8_BOM.length) : head;
+  if (bytes.length <= INSTRUCTION_FILE_MAX_BYTES) return decodeHead(bytes).trim();
+  const budget = INSTRUCTION_FILE_MAX_BYTES - Buffer.byteLength(TRUNCATED_MARK, 'utf8');
+  const text = decodeHead(bytes.subarray(0, budget)).trim();
+  return `${text.replace(/\s+\S*$/, '')}${TRUNCATED_MARK}`;
+}
+
+/** The file's bounded content, or '' when it is absent, unreadable, not a
+ *  regular file, or resolves (symlink/junction) outside `root` when one is set. */
+function readInstructionFile({ path, root }) {
+  let fd;
+  try {
+    const realPath = realpathSync.native(path);
+    if (root && !isInside(realpathSync.native(root), realPath)) {
+      skipNote(path, 'resolves outside its root');
+      return '';
+    }
+    if (!statSync(realPath).isFile()) return '';
+    fd = openSync(realPath, constants.O_RDONLY | (constants.O_NONBLOCK ?? 0));
+    if (!fstatSync(fd).isFile()) return '';
+    return boundedText(readHead(fd));
+  } catch (error) {
+    if (error?.code !== 'ENOENT' && error?.code !== 'ENOTDIR' && error?.code !== 'EISDIR') {
+      skipNote(path, error?.code || error?.message || 'unreadable');
+    }
+    return '';
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+/** The `# Instruction Files` block, or '' when no file has content. Files
+ *  whose bounded content repeats an included one (symlinks, copies) are dropped. */
+export function loadInstructionFilesContext({ mode, cwd, homeDir = homedir() } = {}) {
+  const seen = new Set();
+  const sections = [];
+  for (const candidate of instructionFileCandidates({ mode, cwd, homeDir })) {
+    const content = readInstructionFile(candidate);
+    if (!content || seen.has(content)) continue;
+    seen.add(content);
+    sections.push(`## ${candidate.path}\n\n${content}`);
+  }
+  if (!sections.length) return '';
+  return [
+    '# Instruction Files',
+    "The user's instruction files. Project files take precedence over global ones when they conflict.",
+    ...sections,
+  ].join('\n\n');
+}

package/src/runtime/agent/orchestrator/context/role-instructions.mjs

@@ -268,12 +268,16 @@ export function composeSystemPrompt(opts) {
   // Keep the active workflow first within BP3 so it leads the role and
   // environment material that varies with the session.
   const coreMemory = skip.memory ? '' : trimmedPromptSlice(opts.coreMemoryContext);
+  // User AGENTS.md / CLAUDE.md block (context/instruction-files.mjs), already
+  // headed `# Instruction Files`; rides right after core memory.
+  const instructionFiles = skip.claudemd ? '' : trimmedPromptSlice(opts.instructionFilesContext);
   const sessionMarkerCore = joinPromptSlices([
     trimmedPromptSlice(opts.workflowContext),
     opts.roleRules || '',
     opts.userPrompt || '',
     roleInstructionContext,
     coreMemory ? `# Core Memory\n${coreMemory}` : '',
+    instructionFiles,
   ]);
   // Response language is the LAST system text before the conversation. It
   // rides the environment block (not the tier3 core) because the `# Session`

package/src/runtime/agent/orchestrator/providers/lib/oauth-token-utils.mjs

@@ -1,3 +1,14 @@
+import { statSync } from 'node:fs';
+
+/** The file's modification time in ms; 0 when it cannot be stat-ed. */
+export function fileMtimeMs(path) {
+  try {
+    return statSync(path).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+
 export function decodeJwtPayload(token) {
   try {
     const parts = String(token || '').split('.');

package/src/runtime/agent/orchestrator/providers/lib/open-login-url.mjs

@@ -0,0 +1,9 @@
+/** Open an OAuth login URL in the browser, best effort: a failure is logged, never thrown. */
+export async function openLoginUrl(provider, url) {
+  try {
+    const { openInBrowser } = await import('../../../../shared/open-url.mjs');
+    openInBrowser(url);
+  } catch (err) {
+    process.stderr.write(`[${provider}] browser open failed: ${String(err?.message || err).slice(0, 200)}\n`);
+  }
+}

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

@@ -0,0 +1,254 @@
+// MiMo browser login. The platform encrypts the minted API key to a one-shot
+// X25519 public key we send in the authorize URL; the reply (loopback redirect
+// or a pasted code) carries `u` = ephemeralPub(32) | nonce(12) | ciphertext | tag(16).
+import { createServer } from 'node:http';
+import { lookup } from 'node:dns/promises';
+import { createDecipheriv, createHash, createPublicKey, diffieHellman, generateKeyPairSync } from 'node:crypto';
+import { openLoginUrl } from './lib/open-login-url.mjs';
+import {
+  authorizeEndpoint,
+  manualRedirectUri,
+  resultUrl,
+  LOGIN_TIMEOUT_MS,
+  ensureTokenPlanBaseUrl,
+  getKeyName,
+  normalizeMimoBaseUrl,
+  saveTokens,
+} from './mimo-oauth-tokens.mjs';
+
+// Fixed SPKI prefix for a raw 32-byte X25519 public key.
+const X25519_SPKI_PREFIX = Buffer.from('302a300506032b656e032100', 'hex');
+const EPHEMERAL_LEN = 32;
+const NONCE_LEN = 12;
+const TAG_LEN = 16;
+const MAX_API_KEY_LEN = 512;
+const MAX_UID_LEN = 128;
+
+export function generateLoginKeyPair() {
+  const { publicKey, privateKey } = generateKeyPairSync('x25519');
+  return { privateKey, publicKeyB64: publicKey.export({ type: 'spki', format: 'der' }).toString('base64url') };
+}
+
+// Decrypt the `u` payload into { apiKey, uid, baseUrl }.
+export function decryptMimoPayload(u, privateKey) {
+  const bytes = Buffer.from(String(u || '').trim(), 'base64url');
+  if (bytes.length <= EPHEMERAL_LEN + NONCE_LEN + TAG_LEN) throw new Error('[mimo-oauth] payload too short');
+  const ephemeral = bytes.subarray(0, EPHEMERAL_LEN);
+  const nonce = bytes.subarray(EPHEMERAL_LEN, EPHEMERAL_LEN + NONCE_LEN);
+  const sealed = bytes.subarray(EPHEMERAL_LEN + NONCE_LEN, bytes.length - TAG_LEN);
+  const tag = bytes.subarray(bytes.length - TAG_LEN);
+  const publicKey = createPublicKey({
+    key: Buffer.concat([X25519_SPKI_PREFIX, ephemeral]),
+    format: 'der',
+    type: 'spki',
+  });
+  const key = createHash('sha256').update(diffieHellman({ privateKey, publicKey })).digest();
+  const decipher = createDecipheriv('aes-256-gcm', key, nonce);
+  decipher.setAuthTag(tag);
+  let doc;
+  try {
+    doc = JSON.parse(Buffer.concat([decipher.update(sealed), decipher.final()]).toString('utf-8'));
+  } catch {
+    throw new Error('[mimo-oauth] could not decrypt the authorization payload');
+  }
+  if (!doc || typeof doc !== 'object' || Array.isArray(doc)) {
+    throw new Error('[mimo-oauth] authorization payload is not an object');
+  }
+  const apiKey = typeof doc.sk === 'string' ? doc.sk.trim() : '';
+  if (!apiKey) throw new Error('[mimo-oauth] authorization payload carried no API key');
+  if (apiKey.length > MAX_API_KEY_LEN || !/^[\x21-\x7e]+$/.test(apiKey)) {
+    throw new Error('[mimo-oauth] authorization payload carried a malformed API key');
+  }
+  const uidPresent = doc.uid !== undefined && doc.uid !== null && doc.uid !== '';
+  if (uidPresent && typeof doc.uid !== 'string' && !Number.isFinite(doc.uid)) {
+    throw new Error('[mimo-oauth] authorization payload carried a malformed account id');
+  }
+  const uid = uidPresent ? String(doc.uid) : '';
+  if (uid.length > MAX_UID_LEN || /[\x00-\x1f\x7f]/.test(uid)) {
+    throw new Error('[mimo-oauth] authorization payload carried a malformed account id');
+  }
+  const baseUrl = doc.url === undefined || doc.url === null || doc.url === '' ? '' : normalizeMimoBaseUrl(doc.url);
+  return { apiKey, uid, baseUrl };
+}
+
+// A pasted value may be the bare code or the full callback URL containing it.
+function codeFromInput(input) {
+  const text = String(input || '').trim();
+  if (!text) throw new Error('[mimo-oauth] authorization code is required');
+  if (/^https?:\/\//i.test(text)) {
+    const u = new URL(text).searchParams.get('u');
+    if (!u) throw new Error('[mimo-oauth] callback URL has no authorization code');
+    return u;
+  }
+  return text;
+}
+
+function authorizeUrl(pk, redirectUri, keyName) {
+  const url = new URL(authorizeEndpoint());
+  url.searchParams.set('pk', pk);
+  url.searchParams.set('redirect_uri', redirectUri);
+  url.searchParams.set('kn', 'mimocode');
+  url.searchParams.set('key_name', keyName);
+  return url.toString();
+}
+
+function resultRedirect(error) {
+  const url = new URL(resultUrl());
+  url.searchParams.set('status', error ? 'error' : 'success');
+  if (error) url.searchParams.set('message', String(error.message || error).slice(0, 200));
+  return url.toString();
+}
+
+// Every loopback address `localhost` can resolve to (IPv4 and IPv6), so the
+// browser reaches the callback whichever family it picks.
+async function loopbackAddresses() {
+  try {
+    const found = await lookup('localhost', { all: true });
+    const addresses = [...new Set(found.map((entry) => entry.address))];
+    if (addresses.length) return addresses;
+  } catch {
+    /* fall back below */
+  }
+  return ['127.0.0.1'];
+}
+
+function listenOn(server, port, host) {
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, host, () => {
+      server.off('error', reject);
+      resolve();
+    });
+  });
+}
+
+export async function beginOAuthLogin({
+  openBrowser = true,
+  timeoutMs = LOGIN_TIMEOUT_MS,
+  fetchImpl = undefined,
+  addresses = null,
+  printUrl = false,
+} = {}) {
+  const { privateKey, publicKeyB64 } = generateLoginKeyPair();
+  const keyName = getKeyName();
+
+  const servers = [];
+  const work = new AbortController();
+  let timer = null;
+  let finish = null;
+  let settled = false;
+  let url = '';
+  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 */
+        }
+      }
+      if (error) reject(error);
+      else resolve(value);
+    };
+    timer = setTimeout(
+      () => finish(null, new Error(`[mimo-oauth] login timed out after ${Math.round(timeoutMs / 1000)}s`)),
+      timeoutMs
+    );
+  });
+  // The caller may only use the pasted-code path; a later timeout/cancel must not be an unhandled rejection.
+  waitForCallback.catch(() => {});
+
+  // A Token Plan key without a gateway URL is routed to its region first. The
+  // credential is written only while the login is still open, then the login
+  // is completed in the same synchronous step.
+  const settle = async (decrypted) => {
+    const resolved = await ensureTokenPlanBaseUrl(decrypted, { fetchImpl, signal: work.signal, persist: false });
+    if (settled) throw new Error('[mimo-oauth] login is no longer active');
+    const tokens = saveTokens(resolved);
+    finish(tokens);
+    return tokens;
+  };
+
+  const onRequest = async (req, res) => {
+    const target = new URL(req.url || '/', 'http://localhost');
+    const u = target.pathname === '/' ? target.searchParams.get('u') : null;
+    if (!u || settled) {
+      res.writeHead(404);
+      res.end();
+      return;
+    }
+    // Only a payload sealed to this login's key settles it; anything else is
+    // answered with an error and the login keeps waiting.
+    let decrypted;
+    try {
+      decrypted = decryptMimoPayload(u, privateKey);
+    } catch {
+      res.writeHead(400, { 'Content-Type': 'text/plain; charset=utf-8' });
+      res.end('Invalid authorization payload');
+      return;
+    }
+    try {
+      await settle(decrypted);
+      res.writeHead(302, { Location: resultRedirect(null) });
+      res.end();
+    } catch (err) {
+      res.writeHead(302, { Location: resultRedirect(err) });
+      res.end();
+      finish(null, err instanceof Error ? err : new Error(String(err)));
+    }
+  };
+
+  let port = 0;
+  let bindError = null;
+  for (const address of addresses || (await loopbackAddresses())) {
+    const server = createServer(onRequest);
+    try {
+      await listenOn(server, port, address);
+    } catch (err) {
+      // A failed address only matters when no other listener comes up.
+      bindError = err;
+      continue;
+    }
+    // Once bound, a runtime fault on this listener ends the login.
+    server.on('error', (err) => finish(null, new Error(`[mimo-oauth] callback server failed: ${err?.message || err}`)));
+    servers.push(server);
+    port = server.address().port;
+  }
+  if (!servers.length) {
+    const err = bindError || new Error('[mimo-oauth] no loopback address to listen on');
+    finish(null, err);
+    throw err;
+  }
+  url = authorizeUrl(publicKeyB64, `http://localhost:${port}/`, keyName);
+  const manualUrl = authorizeUrl(publicKeyB64, manualRedirectUri(), keyName);
+  // The URL carries the one-shot login public key. The interactive surfaces
+  // (TUI, desktop) receive it in the returned handle and show it to the user
+  // only; it is printed to the terminal solely for the headless loginOAuth().
+  if (printUrl) {
+    process.stderr.write(
+      `\n[mimo-oauth] Open this URL to log in:\n${url}\n\nOr, if the browser is on another machine:\n${manualUrl}\n\n`
+    );
+  }
+  if (openBrowser) await openLoginUrl('mimo-oauth', url);
+
+  return {
+    provider: 'mimo-oauth',
+    url,
+    manualUrl,
+    port,
+    waitForCallback,
+    completeCode: async (input) => settle(decryptMimoPayload(codeFromInput(input), privateKey)),
+    cancel: () => {
+      finish?.(null);
+    },
+  };
+}
+
+export async function loginOAuth() {
+  const login = await beginOAuthLogin({ printUrl: true });
+  return await login.waitForCallback;
+}