coding-tool-x 3.7.5 → 3.7.7

package/src/config/loader.js

@@ -3,7 +3,7 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const DEFAULT_CONFIG = require('./default');
-const { PATHS, ensureStorageDirMigrated } = require('./paths');
+const { PATHS, NATIVE_PATHS, ensureStorageDirMigrated } = require('./paths');
 const { resolvePreferredHomeDir } = require('../utils/home-dir');
 const eventBus = require('../plugins/event-bus');
 
@@ -23,12 +23,79 @@ function getConfigFilePath() {
  * 展开 ~ 为用户主目录
  */
 function expandHome(filepath) {
+  if (typeof filepath !== 'string') {
+    return filepath;
+  }
   if (filepath.startsWith('~')) {
     return path.join(HOME_DIR, filepath.slice(1));
   }
   return filepath;
 }
 
+function collapseHome(filepath) {
+  if (typeof filepath !== 'string') {
+    return filepath;
+  }
+  if (filepath === HOME_DIR) {
+    return '~';
+  }
+  const prefix = `${HOME_DIR}${path.sep}`;
+  if (filepath.startsWith(prefix)) {
+    return path.join('~', filepath.slice(prefix.length));
+  }
+  return filepath;
+}
+
+function getNativeClaudeProjectsDir() {
+  return NATIVE_PATHS?.claude?.projects || path.join(HOME_DIR, '.claude', 'projects');
+}
+
+function hasExplicitProjectsDir(config = {}) {
+  return Object.prototype.hasOwnProperty.call(config, 'projectsDir') &&
+    typeof config.projectsDir === 'string' &&
+    config.projectsDir.trim() !== '';
+}
+
+function resolveClaudeProjectsDir(config = {}) {
+  if (!hasExplicitProjectsDir(config) || isDefaultProjectsDir(config.projectsDir)) {
+    return getNativeClaudeProjectsDir();
+  }
+  return expandHome(config.projectsDir);
+}
+
+function normalizeComparablePath(filepath) {
+  if (typeof filepath !== 'string' || !filepath.trim()) {
+    return '';
+  }
+  return path.normalize(expandHome(filepath.trim()));
+}
+
+function isDefaultProjectsDir(projectsDir) {
+  const normalized = normalizeComparablePath(projectsDir);
+  if (!normalized) {
+    return true;
+  }
+  const nativeDefault = normalizeComparablePath(getNativeClaudeProjectsDir());
+  const legacyHomeDefault = normalizeComparablePath(path.join(HOME_DIR, '.claude', 'projects'));
+  if (normalized === nativeDefault || normalized === legacyHomeDefault) {
+    return true;
+  }
+  const normalizedParts = normalized.replace(/\\/g, '/').split('/').filter(Boolean);
+  const last = normalizedParts[normalizedParts.length - 1];
+  const previous = normalizedParts[normalizedParts.length - 2];
+  return previous === '.claude' && last === 'projects' && !fs.existsSync(normalized);
+}
+
+function normalizeConfigForSave(config = {}) {
+  const normalized = { ...config };
+  if (isDefaultProjectsDir(normalized.projectsDir)) {
+    delete normalized.projectsDir;
+  } else if (typeof normalized.projectsDir === 'string') {
+    normalized.projectsDir = collapseHome(normalized.projectsDir);
+  }
+  return normalized;
+}
+
 function mergePricing(defaultPricing, overrides = {}) {
   const merged = {};
   Object.keys(defaultPricing).forEach((key) => {
@@ -96,7 +163,7 @@ function loadConfig() {
     if (fs.existsSync(configFilePath)) {
       const userConfig = readJsonFile(configFilePath);
       const config = { ...DEFAULT_CONFIG, ...userConfig };
-      config.projectsDir = expandHome(config.projectsDir || DEFAULT_CONFIG.projectsDir);
+      config.projectsDir = resolveClaudeProjectsDir(userConfig);
 
       // 合并 ports 配置
       config.ports = { ...DEFAULT_CONFIG.ports, ...userConfig.ports };
@@ -120,7 +187,7 @@ function loadConfig() {
   }
   const defaultConfig = {
     ...DEFAULT_CONFIG,
-    projectsDir: expandHome(DEFAULT_CONFIG.projectsDir),
+    projectsDir: resolveClaudeProjectsDir(),
     currentProject: DEFAULT_CONFIG.defaultProject
   };
   eventBus.emitSync('config:loaded', { config: defaultConfig });
@@ -137,8 +204,9 @@ function saveConfig(config) {
     if (!fs.existsSync(dir)) {
       fs.mkdirSync(dir, { recursive: true });
     }
-    fs.writeFileSync(configFilePath, JSON.stringify(config, null, 2), 'utf8');
-    eventBus.emitSync('config:saved', { config });
+    const normalizedConfig = normalizeConfigForSave(config);
+    fs.writeFileSync(configFilePath, JSON.stringify(normalizedConfig, null, 2), 'utf8');
+    eventBus.emitSync('config:saved', { config: normalizedConfig });
   } catch (error) {
     console.error(`保存配置失败 (${configFilePath}):`, error.message);
   }
@@ -148,5 +216,8 @@ module.exports = {
   loadConfig,
   saveConfig,
   expandHome,
+  resolveClaudeProjectsDir,
+  normalizeConfigForSave,
+  isDefaultProjectsDir,
   getConfigFilePath
 };

package/src/index.js

@@ -17,6 +17,7 @@ const { ensureStorageDirMigrated } = require('./config/paths');
 const { normalizePlatformKey } = require('./shared/platforms');
 const PluginManager = require('./plugins/plugin-manager');
 const eventBus = require('./plugins/event-bus');
+const { hasHostFlag } = require('./utils/cli-flags');
 const chalk = require('chalk');
 const path = require('path');
 const fs = require('fs');
@@ -54,9 +55,12 @@ function showHelp() {
   console.log('  ctx ui                  前台启动 Web UI（仅本地访问）');
   console.log('  ctx ui --https          前台启动 Web UI（本地 HTTPS）');
   console.log('  ctx ui --host           前台启动 Web UI（允许 LAN 访问，默认允许远程写操作）');
+  console.log('  ctx ui --hosts          前台启动 Web UI（同 --host）');
+  console.log('  ctx --hosts             前台启动 Web UI（同 ctx ui --host）');
   console.log('  ctx ui start            后台启动 Web UI');
   console.log('  ctx ui start --https    后台启动 Web UI（本地 HTTPS）');
   console.log('  ctx ui start --host     后台启动 Web UI（允许 LAN 访问，默认允许远程写操作）');
+  console.log('  ctx ui start --hosts    后台启动 Web UI（同 --host）');
   console.log('  ctx ui stop             停止 Web UI');
   console.log('  ctx ui restart          重启 Web UI\n');
   console.log(chalk.gray('  提示: 如需禁止 LAN 远程写操作，可设置 CC_TOOL_ALLOW_REMOTE_WRITE=false\n'));
@@ -149,6 +153,13 @@ async function main() {
   // 处理命令行参数
   const args = process.argv.slice(2);
 
+  // LAN 快捷入口，等同于 ctx ui --host/--hosts
+  if (hasHostFlag(process.argv) && !args.some((arg) => arg && !arg.startsWith('-'))) {
+    const { handleUI } = require('./commands/ui');
+    await handleUI();
+    return;
+  }
+
   // --version 或 -v - 显示版本号
   if (args[0] === '--version' || args[0] === '-v') {
     console.log(getVersion());

package/src/server/api/config.js

@@ -330,7 +330,6 @@ router.post('/default-models', (req, res) => {
     // Save config
     const newConfig = {
       ...config,
-      projectsDir: config.projectsDir.replace(require('os').homedir(), '~'),
       defaultModels: newDefaultModels
     };
 
@@ -378,7 +377,6 @@ router.post('/default-models/reset', (req, res) => {
     // Save config
     const newConfig = {
       ...config,
-      projectsDir: config.projectsDir.replace(require('os').homedir(), '~'),
       defaultModels: newDefaultModels
     };
 
@@ -490,7 +488,6 @@ router.post('/advanced', (req, res) => {
     // 更新配置
     const newConfig = {
       ...config,
-      projectsDir: config.projectsDir.replace(require('os').homedir(), '~'),
       ports: normalizedPorts,
       maxLogs: maxLogs !== undefined ? parseInt(maxLogs) : config.maxLogs,
       statsInterval: statsInterval !== undefined ? parseInt(statsInterval) : config.statsInterval,

package/src/server/api/omp-channels.js

@@ -23,9 +23,13 @@ const {
 } = require('../services/model-detector');
 const {
   findAuthProviderForKey,
-  getOmpAuthProviderSnapshot
+  getCachedOmpAuthProviderSnapshot,
+  getOmpAuthProviderCacheMeta,
+  warmOmpAuthProviderSnapshot
 } = require('../services/omp-auth-providers');
 
+const CHANNEL_LIST_AUTH_OPTIONS = { accountCheck: false, includeStatus: false };
+
 function uniqueModels(models = []) {
   const seen = new Set();
   const result = [];
@@ -136,19 +140,53 @@ function attachAuthProvider(channel, snapshot) {
   };
 }
 
+function getAuthSnapshotForChannelList() {
+  const snapshot = getCachedOmpAuthProviderSnapshot(CHANNEL_LIST_AUTH_OPTIONS);
+  const shouldWarm = !snapshot || snapshot.stale;
+  if (shouldWarm) {
+    warmOmpAuthProviderSnapshot(CHANNEL_LIST_AUTH_OPTIONS);
+  }
+  const meta = getOmpAuthProviderCacheMeta(CHANNEL_LIST_AUTH_OPTIONS);
+  return {
+    snapshot,
+    meta: {
+      ...meta,
+      stale: !snapshot || Boolean(snapshot.stale),
+      refreshing: shouldWarm || meta.refreshing,
+      fallback: !snapshot
+    }
+  };
+}
+
+function buildUnavailableAuthProviderMeta(error) {
+  return {
+    cached: false,
+    stale: false,
+    refreshing: false,
+    fallback: true,
+    checkedAt: new Date().toISOString(),
+    error: error || 'omp-not-available'
+  };
+}
+
 module.exports = () => {
   router.get('/', (req, res) => {
     try {
       if (!isOmpInstalled()) {
-        return res.json({ channels: [], installed: false, error: 'OMP CLI not installed' });
+        return res.json({
+          channels: [],
+          installed: false,
+          error: 'OMP CLI not installed',
+          authProviderMeta: buildUnavailableAuthProviderMeta('OMP CLI not installed')
+        });
       }
       const data = getChannels();
-      const authSnapshot = getOmpAuthProviderSnapshot({ accountCheck: false, includeStatus: false });
+      const { snapshot: authSnapshot, meta: authProviderMeta } = getAuthSnapshotForChannelList();
       const channels = (data.channels || []).map(ch => ({
         ...attachAuthProvider(ch, authSnapshot),
         health: getChannelHealthStatus(ch.id, 'omp')
       }));
-      res.json({ channels, installed: true });
+      res.json({ channels, installed: true, authProviderMeta });
     } catch (err) {
       console.error('[OMP Channels API] Failed to get channels:', err);
       res.status(500).json({ error: err.message });
@@ -158,14 +196,19 @@ module.exports = () => {
   router.get('/enabled', (req, res) => {
     try {
       if (!isOmpInstalled()) {
-        return res.json({ channels: [], installed: false, error: 'OMP CLI not installed' });
+        return res.json({
+          channels: [],
+          installed: false,
+          error: 'OMP CLI not installed',
+          authProviderMeta: buildUnavailableAuthProviderMeta('OMP CLI not installed')
+        });
       }
       const data = getChannels();
-      const authSnapshot = getOmpAuthProviderSnapshot({ accountCheck: false, includeStatus: false });
+      const { snapshot: authSnapshot, meta: authProviderMeta } = getAuthSnapshotForChannelList();
       const channels = (data.channels || [])
         .filter(ch => ch.enabled !== false)
         .map(ch => ({ ...attachAuthProvider(ch, authSnapshot), health: getChannelHealthStatus(ch.id, 'omp') }));
-      res.json({ channels, installed: true });
+      res.json({ channels, installed: true, authProviderMeta });
     } catch (err) {
       console.error('[OMP Channels API] Failed to get enabled channels:', err);
       res.status(500).json({ error: err.message });

package/src/server/api/settings.js

@@ -90,7 +90,6 @@ function handleSaveModelSettings(req, res) {
     const config = loadConfig();
     const newConfig = {
       ...config,
-      projectsDir: config.projectsDir.replace(require('os').homedir(), '~'),
       modelMetadataOverrides: overrides && typeof overrides === 'object'
         ? overrides
         : (config.modelMetadataOverrides || {})
@@ -124,7 +123,6 @@ function handleDeleteModelOverride(req, res) {
 
     const newConfig = {
       ...config,
-      projectsDir: config.projectsDir.replace(require('os').homedir(), '~'),
       modelMetadataOverrides: overrides
     };
     saveConfig(newConfig);

package/src/server/api/workspaces.js

@@ -33,6 +33,24 @@ function validateBranchName(branchName) {
   }
 }
 
+function normalizeBranchMode(branchMode) {
+  if (typeof branchMode !== 'string' || !branchMode.trim()) {
+    return '';
+  }
+  return branchMode.trim();
+}
+
+function validateBranchMode(branchMode) {
+  const normalized = normalizeBranchMode(branchMode);
+  if (!normalized) {
+    return { valid: true, normalized: '' };
+  }
+  if (normalized !== 'existing' && normalized !== 'new') {
+    return { valid: false, normalized, message: `分支模式不合法: ${normalized}` };
+  }
+  return { valid: true, normalized };
+}
+
 /**
  * GET /api/workspaces
  * 获取所有工作区列表
@@ -226,6 +244,17 @@ router.post('/', (req, res) => {
         });
       }
 
+      const branchModeValidation = validateBranchMode(proj.branchMode);
+      if (!branchModeValidation.valid) {
+        return res.status(400).json({
+          success: false,
+          message: branchModeValidation.message
+        });
+      }
+      if (branchModeValidation.normalized) {
+        proj.branchMode = branchModeValidation.normalized;
+      }
+
       const normalizedBranch = normalizeBranchName(proj.branch);
       if (normalizedBranch) {
         const branchValidation = validateBranchName(normalizedBranch);
@@ -329,9 +358,10 @@ router.put('/:id/last-used', (req, res) => {
 router.post('/:id/projects', (req, res) => {
   try {
     const { id } = req.params;
-    const { sourcePath, name, createWorktree, branch, baseBranch } = req.body;
+    const { sourcePath, name, createWorktree, branch, baseBranch, branchMode } = req.body;
     const normalizedBranch = normalizeBranchName(branch);
     const normalizedBaseBranch = normalizeBranchName(baseBranch);
+    const branchModeValidation = validateBranchMode(branchMode);
 
     if (!sourcePath || !sourcePath.trim()) {
       return res.status(400).json({
@@ -340,6 +370,13 @@ router.post('/:id/projects', (req, res) => {
       });
     }
 
+    if (!branchModeValidation.valid) {
+      return res.status(400).json({
+        success: false,
+        message: branchModeValidation.message
+      });
+    }
+
     if (normalizedBranch) {
       const branchValidation = validateBranchName(normalizedBranch);
       if (!branchValidation.valid) {
@@ -364,6 +401,7 @@ router.post('/:id/projects', (req, res) => {
       sourcePath,
       name,
       createWorktree,
+      branchMode: branchModeValidation.normalized || branchMode,
       branch: normalizedBranch || branch,
       baseBranch: normalizedBaseBranch || baseBranch
     });

package/src/server/services/dashboard-snapshot-worker.js

@@ -2,7 +2,7 @@
 
 const { fork } = require('child_process');
 
-const DASHBOARD_SNAPSHOT_WORKER_TIMEOUT_MS = 120 * 1000;
+const DASHBOARD_SNAPSHOT_WORKER_TIMEOUT_MS = 180 * 1000;
 
 function sortClaudeProjects(projects, order = []) {
   if (!Array.isArray(order) || order.length === 0) {
@@ -130,6 +130,7 @@ function runDashboardSnapshotWorker(kind, source, config = {}, options = {}) {
   return new Promise((resolve, reject) => {
     const child = fork(__filename, [], {
       stdio: ['ignore', 'ignore', 'pipe', 'ipc'],
+      windowsHide: true,
       env: {
         ...process.env,
         CC_TOOL_DASHBOARD_SNAPSHOT_WORKER: '1'

package/src/server/services/https-cert.js

@@ -42,7 +42,7 @@ function resolveOpenSslCommand() {
 
   for (const command of commands) {
     try {
-      execFileSync(command, ['version'], { stdio: 'ignore' });
+      execFileSync(command, ['version'], { stdio: 'ignore', windowsHide: true });
       return command;
     } catch {
       // Try next candidate.
@@ -96,7 +96,8 @@ function generatePemCertificateWithOpenSsl(command) {
     '-config',
     configPath
   ], {
-    stdio: 'ignore'
+    stdio: 'ignore',
+    windowsHide: true
   });
 
   writeMeta({

package/src/server/services/native-oauth-adapters.js

@@ -1029,7 +1029,8 @@ function runOmpCommand(args = [], options = {}) {
       ...process.env,
       ...(options.env || {})
     },
-    timeout: options.timeout || 10000
+    timeout: options.timeout || 10000,
+    windowsHide: true
   });
   const status = result?.status === undefined || result?.status === null ? 0 : result.status;
   return {

package/src/server/services/omp-auth-provider-worker.js

@@ -0,0 +1,29 @@
+'use strict';
+
+const { getOmpAuthProviderSnapshot } = require('./omp-auth-providers');
+
+function attachWorkerHandler() {
+  process.on('message', (options = {}) => {
+    try {
+      const value = getOmpAuthProviderSnapshot(options);
+      if (process.send) {
+        process.send({ ok: true, value }, () => process.exit(0));
+        return;
+      }
+    } catch (error) {
+      if (process.send) {
+        process.send({ ok: false, error: error?.message || String(error) }, () => process.exit(1));
+        return;
+      }
+    }
+    process.exit(1);
+  });
+}
+
+if (process.env.CC_TOOL_OMP_AUTH_PROVIDER_WORKER === '1' || require.main === module) {
+  attachWorkerHandler();
+}
+
+module.exports = {
+  attachWorkerHandler
+};

package/src/server/services/omp-auth-providers.js

@@ -1,9 +1,11 @@
-const { spawnSync } = require('child_process');
+const path = require('path');
+const { fork, spawnSync } = require('child_process');
 const ompConfig = require('./omp-config');
 
 const COMMAND_TIMEOUT_MS = 5000;
 const TOKEN_LIST_TIMEOUT_MS = 3000;
 const CACHE_TTL_MS = 15000;
+const WARMUP_WORKER_TIMEOUT_MS = COMMAND_TIMEOUT_MS + 1000;
 
 const LOGIN_PROVIDER_IDS = new Set([
   'openai-codex',
@@ -50,6 +52,20 @@ const PROVIDER_ALIASES = {
 };
 
 let snapshotCache = {};
+const warmupTimers = new Map();
+const warmupErrors = new Map();
+
+function getSnapshotCacheKey(options = {}) {
+  return options.accountCheck === false
+    ? (options.includeStatus === false ? 'metadata' : 'metadata-status')
+    : 'full';
+}
+
+function writeSnapshotCache(cacheKey, loadedAt, value) {
+  snapshotCache[cacheKey] = { loadedAt, value };
+  warmupErrors.delete(cacheKey);
+  return value;
+}
 
 function normalizeProviderId(value = '') {
   return String(value || '')
@@ -95,7 +111,8 @@ function runCommand(command, args = [], options = {}) {
       ...process.env,
       ...(options.env || {})
     },
-    timeout: options.timeout || COMMAND_TIMEOUT_MS
+    timeout: options.timeout || COMMAND_TIMEOUT_MS,
+    windowsHide: true
   });
   if (typeof result === 'string' || Buffer.isBuffer(result)) {
     return { status: 0, stdout: normalizeCommandOutput(result), stderr: '' };
@@ -205,9 +222,7 @@ function buildEmptySnapshot(runtime, reason) {
 
 function getOmpAuthProviderSnapshot(options = {}) {
   const now = Date.now();
-  const cacheKey = options.accountCheck === false
-    ? (options.includeStatus === false ? 'metadata' : 'metadata-status')
-    : 'full';
+  const cacheKey = getSnapshotCacheKey(options);
   const cached = snapshotCache[cacheKey];
   if (!options.forceRefresh && cached && now - cached.loadedAt < CACHE_TTL_MS) {
     return cached.value;
@@ -217,16 +232,14 @@ function getOmpAuthProviderSnapshot(options = {}) {
   const runtime = options.runtime || ompConfig.resolveOmpRuntime(env, options.runtimeOptions || {});
   if (!runtime || runtime.runtime !== 'omp' || !runtime.installed) {
     const value = buildEmptySnapshot(runtime || null, 'omp-not-available');
-    snapshotCache[cacheKey] = { loadedAt: now, value };
-    return value;
+    return writeSnapshotCache(cacheKey, now, value);
   }
 
   const command = runtime.command;
   const listResult = parseJsonCommand(command, ['auth-broker', 'list', '--json'], options);
   if (!listResult.ok || !Array.isArray(listResult.value)) {
     const value = buildEmptySnapshot(runtime, listResult.error || listResult.stderr || 'auth-provider-list-failed');
-    snapshotCache[cacheKey] = { loadedAt: now, value };
-    return value;
+    return writeSnapshotCache(cacheKey, now, value);
   }
 
   const supportedProviders = listResult.value
@@ -268,8 +281,113 @@ function getOmpAuthProviderSnapshot(options = {}) {
     aliases: { ...PROVIDER_ALIASES },
     checkedAt: new Date().toISOString()
   };
-  snapshotCache[cacheKey] = { loadedAt: now, value };
-  return value;
+  return writeSnapshotCache(cacheKey, now, value);
+}
+
+function getCachedOmpAuthProviderSnapshot(options = {}) {
+  const cacheKey = getSnapshotCacheKey(options);
+  const cached = snapshotCache[cacheKey];
+  if (!cached) return null;
+  return {
+    ...cached.value,
+    stale: Date.now() - cached.loadedAt >= CACHE_TTL_MS
+  };
+}
+
+function getOmpAuthProviderCacheMeta(options = {}) {
+  const cacheKey = getSnapshotCacheKey(options);
+  const cached = snapshotCache[cacheKey];
+  const stale = !cached || Date.now() - cached.loadedAt >= CACHE_TTL_MS;
+  const cachedReason = cached?.value?.available === false ? cached.value.reason || null : null;
+  return {
+    cached: Boolean(cached),
+    stale,
+    refreshing: warmupTimers.has(cacheKey),
+    fallback: !cached,
+    checkedAt: cached?.value?.checkedAt || null,
+    error: warmupErrors.get(cacheKey) || cachedReason || null
+  };
+}
+
+function warmOmpAuthProviderSnapshot(options = {}) {
+  const cacheKey = getSnapshotCacheKey(options);
+  if (warmupTimers.has(cacheKey)) return;
+
+  const finishWarmup = (task, error = null, value = null) => {
+    if (!warmupTimers.has(cacheKey)) return;
+    if (task.timeout) clearTimeout(task.timeout);
+    if (task.child) {
+      task.child.removeAllListeners();
+      if (!task.child.killed) task.child.kill();
+    }
+    warmupTimers.delete(cacheKey);
+    if (error) {
+      warmupErrors.set(cacheKey, sanitizeIdentity(error?.message || String(error || 'auth-provider-warmup-failed')));
+      return;
+    }
+    if (value) {
+      writeSnapshotCache(cacheKey, Date.now(), value);
+    }
+  };
+
+  // Tests and callers that supply a function-based command runner cannot cross
+  // the process boundary. Production channel-list warmups use the worker path.
+  if (process.env.NODE_ENV === 'test' || options.commandRunner) {
+    const task = { timeout: null, child: null };
+    const timer = setTimeout(() => {
+      try {
+        finishWarmup(task, null, getOmpAuthProviderSnapshot(options));
+      } catch (error) {
+        finishWarmup(task, error);
+      }
+    }, 0);
+    task.timeout = timer;
+    warmupTimers.set(cacheKey, task);
+    return;
+  }
+
+  const workerPath = path.join(__dirname, 'omp-auth-provider-worker.js');
+  const task = { timeout: null, child: null };
+  try {
+    const child = fork(workerPath, [], {
+      stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
+      windowsHide: true,
+      env: {
+        ...process.env,
+        CC_TOOL_OMP_AUTH_PROVIDER_WORKER: '1'
+      }
+    });
+    task.child = child;
+    task.timeout = setTimeout(() => {
+      finishWarmup(task, new Error('auth-provider-warmup-timed-out'));
+    }, WARMUP_WORKER_TIMEOUT_MS);
+    warmupTimers.set(cacheKey, task);
+
+    child.on('message', (message) => {
+      if (message?.ok) {
+        finishWarmup(task, null, message.value);
+      } else {
+        finishWarmup(task, new Error(message?.error || 'auth-provider-warmup-failed'));
+      }
+    });
+    child.on('error', (error) => finishWarmup(task, error));
+    child.on('exit', (code, signal) => {
+      if (warmupTimers.get(cacheKey) === task) {
+        finishWarmup(task, new Error(`auth-provider-warmup-worker-exited-${code || signal || 'unknown'}`));
+      }
+    });
+    child.send({
+      accountCheck: options.accountCheck,
+      includeStatus: options.includeStatus,
+      forceRefresh: options.forceRefresh === true,
+      runtime: options.runtime,
+      runtimeOptions: options.runtimeOptions
+    });
+  } catch (error) {
+    // `fork` itself can fail before the task is registered. Preserve the
+    // failure for the non-blocking status endpoint instead of dropping it.
+    warmupErrors.set(cacheKey, sanitizeIdentity(error?.message || String(error || 'auth-provider-warmup-failed')));
+  }
 }
 
 function findAuthProviderForKey(providerKey, snapshot) {
@@ -280,6 +398,12 @@ function findAuthProviderForKey(providerKey, snapshot) {
 
 function clearOmpAuthProviderCache() {
   snapshotCache = {};
+  for (const task of warmupTimers.values()) {
+    if (task.timeout) clearTimeout(task.timeout);
+    if (task.child && !task.child.killed) task.child.kill();
+  }
+  warmupTimers.clear();
+  warmupErrors.clear();
 }
 
 module.exports = {
@@ -287,7 +411,10 @@ module.exports = {
   ACCOUNT_CHECK_PROVIDER_IDS,
   clearOmpAuthProviderCache,
   findAuthProviderForKey,
+  getCachedOmpAuthProviderSnapshot,
+  getOmpAuthProviderCacheMeta,
   getOmpAuthProviderSnapshot,
+  warmOmpAuthProviderSnapshot,
   normalizeProviderId,
   resolveProviderAlias,
   sanitizeIdentity