mixdog 0.9.2 → 0.9.4

package/src/runtime/shared/transcript-writer.mjs

@@ -14,8 +14,14 @@
  * `mixdog: transcript-writer: `) and suppress duplicates so a broken path
  * cannot spam the terminal.
  */
-import { appendFileSync, mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, renameSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
+import { appendBuffered, drainPathSync, hasInFlightWrite } from './buffered-appender.mjs';
+
+// Rotate the JSONL transcript once it exceeds this size, keeping one prior
+// generation (`<path>.1`). Checked on each append; the check itself is a
+// cheap statSync so no extra timer/interval is needed.
+const TRANSCRIPT_ROTATE_BYTES = 10 * 1024 * 1024;
 
 // Byte-identical to cwdToProjectSlug() in
 // src/runtime/channels/lib/session-discovery.mjs. Inlined to avoid a
@@ -56,10 +62,31 @@ export function createTranscriptWriter({ mixdogHome, sessionId, cwd, pid } = {})
     }
   }
 
+  function rotateIfNeeded() {
+    try {
+      if (!existsSync(transcriptPath)) return;
+      const { size } = statSync(transcriptPath);
+      if (size < TRANSCRIPT_ROTATE_BYTES) return;
+      // An async appendFile may be in flight for this path; renaming out
+      // from under it races the write on Windows. Skip this round and
+      // retry rotation on the next append instead.
+      if (hasInFlightWrite(transcriptPath)) return;
+      // Force any still-buffered bytes onto disk before renaming, so the
+      // rotated-out file ends with everything queued for it and the fresh
+      // file post-rename doesn't inherit stale in-memory chunks.
+      drainPathSync(transcriptPath);
+      const rotatedPath = `${transcriptPath}.1`;
+      try { renameSync(transcriptPath, rotatedPath); } catch (err) { logOnce(err); }
+    } catch (err) {
+      logOnce(err);
+    }
+  }
+
   function appendLine(entry) {
     ensureProjectDir();
+    rotateIfNeeded();
     try {
-      appendFileSync(transcriptPath, `${JSON.stringify(entry)}\n`);
+      appendBuffered(transcriptPath, `${JSON.stringify(entry)}\n`);
     } catch (err) {
       logOnce(err);
     }
@@ -117,10 +144,33 @@ export function createTranscriptWriter({ mixdogHome, sessionId, cwd, pid } = {})
     });
   }
 
+  // Idempotently create the transcript file as an empty 0-byte file if it
+  // does not already exist. Called on every remote turn (before the first
+  // append) so the channel worker's fs.watch can attach to the path right
+  // away instead of waiting on schedulePendingTranscriptRearm(). Never
+  // truncates an existing transcript: guarded by existsSync + the 'wx'
+  // (exclusive-create) flag, and any EEXIST/other error is swallowed via
+  // logOnce like the other writers.
+  function ensureTranscriptFile() {
+    try {
+      ensureProjectDir();
+      if (existsSync(transcriptPath)) return;
+      try {
+        writeFileSync(transcriptPath, '', { flag: 'wx' });
+      } catch (err) {
+        if (err && err.code === 'EEXIST') return;
+        logOnce(err);
+      }
+    } catch (err) {
+      logOnce(err);
+    }
+  }
+
   return {
     transcriptPath,
     sessionRecordPath,
     writeSessionRecord,
+    ensureTranscriptFile,
     refresh,
     appendAssistant,
     appendToolUse,

package/src/runtime/shared/update-checker.mjs

@@ -154,12 +154,15 @@ export async function checkLatestVersion({ force = false, dataDir } = {}) {
   }
   // Registry unreachable: fall back to a stale cache (if any) rather than
   // reporting "no update info" every time the network hiccups.
-  if (cache && cache.latestVersion) {
+  // Re-read the cache here: a force:true call skips the read above, but a
+  // stale answer still beats none when the network is down.
+  const staleCache = cache || readCache(dataDir);
+  if (staleCache && staleCache.latestVersion) {
     return {
       currentVersion,
-      latestVersion: cache.latestVersion,
-      updateAvailable: isNewerVersion(cache.latestVersion, currentVersion),
-      lastCheckedAt: cache.lastCheckedAt || now,
+      latestVersion: staleCache.latestVersion,
+      updateAvailable: isNewerVersion(staleCache.latestVersion, currentVersion),
+      lastCheckedAt: staleCache.lastCheckedAt || now,
       fromCache: true,
     };
   }

package/src/session-runtime/config-helpers.mjs

@@ -0,0 +1,291 @@
+// Config normalization helpers: default provider, presets/routes, module
+// enable flags, shell/auto-clear/compaction config, and duration formatting.
+import { clean, hasOwn } from './session-text.mjs';
+import { normalizeEffortInput, normalizeSavedEffort } from './effort.mjs';
+import { routeFastKey, fastPreferenceFor } from './model-capabilities.mjs';
+
+export const DEFAULT_PROVIDER = 'anthropic-oauth';
+export const DEFAULT_MODEL = '';
+
+// Resolve the provider to use when a route carries no explicit provider.
+// Priority: config.defaultProvider (when it names a known provider) > DEFAULT_PROVIDER.
+export function makeResolveDefaultProvider(isKnownProvider) {
+  return function resolveDefaultProvider(config) {
+    const configured = clean(config?.defaultProvider);
+    if (configured && isKnownProvider(configured)) return configured;
+    return DEFAULT_PROVIDER;
+  };
+}
+
+export function modelSettingsFor(config, provider, model) {
+  const key = routeFastKey(provider, model);
+  const value = key ? config?.modelSettings?.[key] : null;
+  return value && typeof value === 'object' ? value : {};
+}
+
+export function findPreset(config, key) {
+  const wanted = clean(key).toLowerCase();
+  if (!wanted) return null;
+  const presets = Array.isArray(config?.presets) ? config.presets : [];
+  return presets.find((p) => {
+    const id = clean(p?.id).toLowerCase();
+    const name = clean(p?.name).toLowerCase();
+    return id === wanted || name === wanted;
+  }) || null;
+}
+
+export function makeResolveRoute(resolveDefaultProvider) {
+  return function resolveRoute(config, { provider, model, effort, fast } = {}) {
+    const explicitProvider = clean(provider);
+    const explicitModel = clean(model);
+    const hasExplicitEffort = effort !== undefined;
+    const explicitEffort = hasExplicitEffort ? normalizeEffortInput(effort) : undefined;
+    const hasExplicitFast = fast !== undefined;
+    const explicitFast = fast === true;
+
+    if (explicitModel && !explicitProvider) {
+      const preset = findPreset(config, explicitModel);
+      if (preset) {
+        const p = clean(preset.provider) || DEFAULT_PROVIDER;
+        const m = clean(preset.model) || DEFAULT_MODEL;
+        const saved = modelSettingsFor(config, p, m);
+        return {
+          provider: p,
+          model: m,
+          preset,
+          effort: hasExplicitEffort ? explicitEffort : normalizeSavedEffort(saved.effort ?? preset.effort),
+          fast: hasExplicitFast ? explicitFast : (hasOwn(saved, 'fast') ? saved.fast === true : (preset.fast === true || fastPreferenceFor(config, p, m))),
+        };
+      }
+    }
+
+    if (!explicitProvider && !explicitModel) {
+      const defaultKey = config?.default;
+      const preset = findPreset(config, defaultKey);
+      if (preset) {
+        const p = clean(preset.provider) || DEFAULT_PROVIDER;
+        const m = clean(preset.model) || DEFAULT_MODEL;
+        const saved = modelSettingsFor(config, p, m);
+        return {
+          provider: p,
+          model: m,
+          preset,
+          effort: hasExplicitEffort ? explicitEffort : normalizeSavedEffort(saved.effort ?? preset.effort),
+          fast: hasExplicitFast ? explicitFast : (hasOwn(saved, 'fast') ? saved.fast === true : (preset.fast === true || fastPreferenceFor(config, p, m))),
+        };
+      }
+    }
+
+    const p = explicitProvider || resolveDefaultProvider(config);
+    const m = explicitModel || DEFAULT_MODEL;
+    const saved = modelSettingsFor(config, p, m);
+    return {
+      provider: p,
+      model: m,
+      preset: null,
+      effort: hasExplicitEffort ? explicitEffort : normalizeSavedEffort(saved.effort),
+      fast: hasExplicitFast ? explicitFast : (hasOwn(saved, 'fast') ? saved.fast === true : fastPreferenceFor(config, p, m)),
+    };
+  };
+}
+
+export function isLikelyRawModelId(value) {
+  const model = clean(value);
+  if (!model || model.length > 160) return false;
+  if (/\s/.test(model)) return false;
+  return /^[A-Za-z0-9][A-Za-z0-9._:/@+-]*$/.test(model);
+}
+
+export function validateRequestedModelSelector(config, requested = {}) {
+  const model = clean(requested.model);
+  if (!model) return;
+  if (findPreset(config, model)) return;
+  if (isLikelyRawModelId(model)) return;
+  throw new Error(`Invalid model selector "${model}". Use a preset or a model id; free-form text cannot be used as a model.`);
+}
+
+export function ensureProviderEnabled(config, provider) {
+  const providers = { ...(config?.providers || {}) };
+  providers[provider] = { ...(providers[provider] || {}), enabled: true };
+  return providers;
+}
+
+const AUTO_CLEAR_DEFAULT_IDLE_MS = 60 * 60 * 1000;
+
+// Provider-aware auto-clear idle-sweep defaults. Rationale mirrors the
+// provider cache TTLs documented in agent-runtime/cache-strategy.mjs
+// (explicit breakpoint / managed-cache windows): Anthropic, Gemini, xAI and
+// Mistral caches run ~1h, Groq's implicit cache persists ~2h, OpenAI/
+// DeepSeek key-prefix/implicit caches persist far longer (~24h), and OpenAI
+// OAuth's in-memory server cache is short-lived (~5-10min), so we round up
+// slightly to 10m to avoid sweeping a still-warm cache. Unknown/
+// unrecognized providers fall back to the 'default' 1h entry.
+export const AUTO_CLEAR_PROVIDER_IDLE_MS = Object.freeze({
+  'anthropic': 60 * 60 * 1000,
+  'anthropic-oauth': 60 * 60 * 1000,
+  'gemini': 60 * 60 * 1000,
+  'groq': 2 * 60 * 60 * 1000,
+  'openai': 24 * 60 * 60 * 1000,
+  'deepseek': 24 * 60 * 60 * 1000,
+  'xai': 60 * 60 * 1000,
+  'openai-oauth': 10 * 60 * 1000,
+  'mistral': 60 * 60 * 1000,
+  'default': AUTO_CLEAR_DEFAULT_IDLE_MS,
+});
+export const AUTO_CLEAR_UNKNOWN_PROVIDER_IDLE_MS = AUTO_CLEAR_PROVIDER_IDLE_MS.default;
+
+// Resolve the auto-clear idle-sweep threshold for a given provider id.
+// Unknown/missing providers fall back to the 'default' 1h entry (above).
+export function autoClearIdleMsForProvider(provider) {
+  const key = clean(provider).toLowerCase();
+  return AUTO_CLEAR_PROVIDER_IDLE_MS[key] ?? AUTO_CLEAR_PROVIDER_IDLE_MS.default;
+}
+
+// Resolve the effective auto-clear idle window for a config + provider:
+// an explicit user-set idleMs (config.autoClear.idleMs) always wins; else
+// fall back to the provider's default; else the global 1h default.
+export function resolveAutoClearIdleMs(config, provider) {
+  const raw = config?.autoClear && typeof config.autoClear === 'object' ? config.autoClear : {};
+  const idleMs = Number(raw.idleMs ?? raw.thresholdMs ?? raw.idleMillis);
+  if (Number.isFinite(idleMs) && idleMs > 0) return Math.max(60_000, Math.round(idleMs));
+  return autoClearIdleMsForProvider(provider);
+}
+
+export function normalizeSystemShellConfig(value = {}) {
+  const raw = value && typeof value === 'object' ? value : {};
+  const command = clean(raw.command ?? raw.path ?? raw.executable ?? raw.shell);
+  const envCommand = clean(process.env.MIXDOG_SHELL);
+  return {
+    command,
+    effective: command || envCommand || '',
+    source: command ? 'config' : (envCommand ? 'env' : 'auto'),
+  };
+}
+
+export function normalizeSystemShellCommand(value) {
+  const command = clean(value).replace(/^auto$/i, '').replace(/^['"](.+)['"]$/, '$1').trim();
+  if (!command) return '';
+  if (process.platform === 'win32') {
+    const stem = command.split(/[\\/]/).pop().toLowerCase().replace(/\.exe$/, '');
+    if (stem !== 'powershell' && stem !== 'pwsh') {
+      throw new Error('system shell command must be powershell.exe or pwsh on Windows');
+    }
+  }
+  return command;
+}
+
+export function normalizeAutoClearConfig(value = {}) {
+  const raw = value && typeof value === 'object' ? value : {};
+  const idleMs = Number(raw.idleMs ?? raw.thresholdMs ?? raw.idleMillis);
+  const hasExplicitIdle = Number.isFinite(idleMs) && idleMs > 0;
+  // idleMs: null means "no explicit override" — callers resolve the
+  // effective window via resolveAutoClearIdleMs/provider default. `custom`
+  // tells UI whether the stored idleMs is a user override (true) or the
+  // provider-default mode (false, idleMs null).
+  return {
+    enabled: raw.enabled !== false,
+    idleMs: hasExplicitIdle ? Math.max(60_000, Math.round(idleMs)) : null,
+    custom: hasExplicitIdle,
+  };
+}
+
+export function normalizeCompactTypeSetting(value, fallback = 'semantic') {
+  const raw = clean(value).toLowerCase().replace(/_/g, '-');
+  if (!raw) return fallback;
+  if (raw === '1' || raw === 'type1' || raw === 'type-1' || raw === 'semantic' || raw === 'summary' || raw === 'default') return 'semantic';
+  if (raw === '2' || raw === 'type2' || raw === 'type-2' || raw === 'recall' || raw === 'recall-fast' || raw === 'recall-fasttrack' || raw === 'recall-fast-track' || raw === 'fasttrack' || raw === 'fast-track') return 'recall-fasttrack';
+  return fallback;
+}
+
+export function normalizeCompactionConfig(value = {}, { memoryEnabled = true } = {}) {
+  const raw = value && typeof value === 'object' ? value : {};
+  let compactType = normalizeCompactTypeSetting(raw.compactType ?? raw.compact_type ?? raw.type, 'semantic');
+  // Memory is now always-on, so recall-fasttrack no longer downgrades to
+  // semantic. `memoryEnabled` is retained as a param for API compatibility but
+  // is intentionally ignored (fasttrack drains run on-demand regardless of the
+  // recap/background-cycle toggle).
+  void memoryEnabled;
+  return {
+    ...raw,
+    auto: raw.auto !== false && raw.enabled !== false,
+    type: compactType,
+    compactType,
+  };
+}
+
+export function moduleEnabled(configLike, name, fallback = true) {
+  const entry = configLike?.modules?.[name];
+  if (entry && typeof entry === 'object' && entry.enabled === false) return false;
+  return fallback !== false;
+}
+
+// Recap toggle: gates ONLY the background memory cycles (1/2/3). The memory
+// module itself (transcript watcher/ingest, on-demand recall/fasttrack drains)
+// is always-on. Default enabled. Reads the dedicated `recap` section; if a
+// legacy `modules.memory === false` flag is present it is honored as recap off
+// (migration folds it into `recap.enabled` on config load).
+export function recapEnabled(configLike, fallback = true) {
+  const entry = configLike?.recap;
+  if (entry && typeof entry === 'object' && entry.enabled === false) return false;
+  // Legacy fallback: pre-migration configs may still carry modules.memory=false.
+  if (configLike?.modules?.memory === false) return false;
+  if (moduleEnabled(configLike, 'memory', true) === false) return false;
+  return fallback !== false;
+}
+
+export function setRecapEnabledInConfig(configLike, enabled) {
+  const next = { ...(configLike || {}) };
+  next.recap = { ...(next.recap || {}), enabled: enabled !== false };
+  // Drop the legacy flag if it was carrying the disabled state.
+  if (next.modules && next.modules.memory === false) {
+    const modules = { ...next.modules };
+    delete modules.memory;
+    next.modules = modules;
+  } else if (next.modules && next.modules.memory && typeof next.modules.memory === 'object') {
+    const modules = { ...next.modules };
+    const memoryMod = { ...modules.memory };
+    delete memoryMod.enabled;
+    if (Object.keys(memoryMod).length === 0) delete modules.memory;
+    else modules.memory = memoryMod;
+    next.modules = modules;
+  }
+  return next;
+}
+
+export function setModuleEnabledInConfig(configLike, name, enabled) {
+  const next = { ...(configLike || {}) };
+  next.modules = { ...(next.modules || {}) };
+  next.modules[name] = {
+    ...(next.modules[name] || {}),
+    enabled: enabled !== false,
+  };
+  return next;
+}
+
+export function formatDurationMs(ms) {
+  const value = Math.max(0, Number(ms) || 0);
+  if (value % 3_600_000 === 0) return `${value / 3_600_000}h`;
+  if (value % 60_000 === 0) return `${value / 60_000}m`;
+  return `${Math.round(value / 1000)}s`;
+}
+
+export function parseDurationMs(input) {
+  const text = clean(input).toLowerCase();
+  if (!text) return null;
+  const match = /^(\d+(?:\.\d+)?)(ms|s|m|h)?$/.exec(text);
+  if (!match) return null;
+  const n = Number(match[1]);
+  if (!Number.isFinite(n) || n <= 0) return null;
+  const unit = match[2] || 'm';
+  const mult = unit === 'h' ? 3_600_000 : unit === 'm' ? 60_000 : unit === 's' ? 1000 : 1;
+  return Math.max(60_000, Math.round(n * mult));
+}
+
+// A resolved model meta carries catalog-derived fields (contextWindow, pricing,
+// capabilities, …). The lookupModelMeta() fallback for an unknown id is the
+// bare shape `{ id, provider }`, so "more than id/provider" reliably tells a
+// real catalog hit apart from that placeholder.
+export function modelMetaLooksResolved(meta) {
+  if (!meta || typeof meta !== 'object') return false;
+  return Object.keys(meta).some((key) => key !== 'id' && key !== 'provider');
+}

package/src/session-runtime/config-lifecycle.mjs

@@ -0,0 +1,232 @@
+// config-lifecycle.mjs — config reload/save/adopt family + output-style status
+// cache, extracted from mixdog-session-runtime.mjs. Dependency-injected factory:
+// closes over config/searchRoute mutable state via getter/setter injection
+// (getConfig/setConfig/getSearchRoute/setSearchRoute) and shared helpers, so the
+// facade keeps ownership of the mutable locals while the debounce/adopt logic
+// lives here.
+//
+// Debounce rationale (unchanged from the original inline implementation):
+// persisting mixdog-config.json is heavy (cross-process lock, atomic
+// temp+rename, win32 icacls owner-only ACL). Adopt in-memory IMMEDIATELY so
+// same-tick readers see fresh state, and DEBOUNCE the disk write so a burst of
+// toggles collapses into one persist. Three independent debounce channels:
+//   - config save  (cfgMod.saveConfig, agent-section serialize)
+//   - backend save (channel-admin setBackend, file-locked RMW)
+//   - outputStyle  (sharedCfgMod.updateConfig whole-root RMW — cfgMod.saveConfig
+//                   only serializes agent-section fields, so a top-level
+//                   outputStyle would never reach disk via that path)
+
+export const CONFIG_SAVE_DEBOUNCE_MS = 150;
+
+export function createConfigLifecycle({
+  // config mutable-state injection
+  getConfig,
+  setConfig,
+  getSearchRoute,
+  setSearchRoute,
+  getConfigHasSecrets,
+  setConfigHasSecrets,
+  getRoute,
+  // shared modules / helpers
+  cfgMod,
+  sharedCfgMod,
+  setBackend,
+  setConfiguredShell,
+  normalizeSystemShellConfig,
+  normalizeSearchRouteConfig,
+  outputStyleStatus,
+  LAZY_SECRET_PROVIDERS,
+  clean,
+  resolve,
+  performanceNow = () => performance.now(),
+  STANDALONE_DATA_DIR,
+}) {
+  // --- output-style status cache (short TTL, keyed on plugin data dir) --------
+  let outputStyleStatusCache = null;
+  let outputStyleStatusCacheAt = 0;
+  let outputStyleStatusCacheDir = '';
+
+  const getOutputStyleStatusCached = ({ fresh = false } = {}) => {
+    const dataDir = cfgMod.getPluginData?.() || STANDALONE_DATA_DIR;
+    const cacheDir = resolve(dataDir);
+    const now = performanceNow();
+    if (
+      !fresh
+      && outputStyleStatusCache
+      && outputStyleStatusCacheDir === cacheDir
+      && now - outputStyleStatusCacheAt < 2500
+    ) {
+      return outputStyleStatusCache;
+    }
+    outputStyleStatusCache = outputStyleStatus(dataDir);
+    outputStyleStatusCacheAt = now;
+    outputStyleStatusCacheDir = cacheDir;
+    return outputStyleStatusCache;
+  };
+  const invalidateOutputStyleStatusCache = () => {
+    outputStyleStatusCache = null;
+    outputStyleStatusCacheAt = 0;
+    outputStyleStatusCacheDir = '';
+  };
+  // In-memory seed of the status cache after an outputStyle select (avoids a
+  // second forced-fresh filesystem scan during the debounce window).
+  const seedOutputStyleStatusCache = (status) => {
+    outputStyleStatusCache = status;
+    outputStyleStatusCacheAt = performanceNow();
+    outputStyleStatusCacheDir = resolve(cfgMod.getPluginData?.() || STANDALONE_DATA_DIR);
+  };
+
+  // --- config adopt -----------------------------------------------------------
+  function adoptConfig(nextConfig, { hasSecrets = getConfigHasSecrets() } = {}) {
+    setConfig(nextConfig);
+    setConfigHasSecrets(hasSecrets === true);
+    const config = getConfig();
+    setConfiguredShell(normalizeSystemShellConfig(config.shell).command);
+    setSearchRoute(
+      normalizeSearchRouteConfig(config.searchRoute)
+        || normalizeSearchRouteConfig(getSearchRoute()),
+    );
+    return config;
+  }
+
+  // --- debounced config save --------------------------------------------------
+  let pendingConfigToSave = null;
+  let configSaveTimer = null;
+
+  function flushConfigSave() {
+    if (configSaveTimer) {
+      clearTimeout(configSaveTimer);
+      configSaveTimer = null;
+    }
+    if (pendingConfigToSave === null) return;
+    const snapshot = pendingConfigToSave;
+    pendingConfigToSave = null;
+    try {
+      cfgMod.saveConfig(snapshot);
+    } catch (err) {
+      process.stderr.write(`[config] debounced saveConfig failed: ${err?.message || err}\n`);
+    }
+  }
+
+  function saveConfigAndAdopt(nextConfig, { hasSecrets = getConfigHasSecrets() } = {}) {
+    // In-memory adopt is synchronous and first so callers that read back the
+    // value immediately (e.g. setProfile -> getProfile) see the new state.
+    const adopted = adoptConfig(nextConfig, { hasSecrets });
+    // Persist the adopted object; coalesce rapid successive changes into one
+    // disk write after CONFIG_SAVE_DEBOUNCE_MS of quiet.
+    pendingConfigToSave = getConfig();
+    if (configSaveTimer) clearTimeout(configSaveTimer);
+    configSaveTimer = setTimeout(flushConfigSave, CONFIG_SAVE_DEBOUNCE_MS);
+    configSaveTimer.unref?.();
+    return adopted;
+  }
+
+  // --- debounced backend switch ----------------------------------------------
+  let pendingBackendName = null;
+  let backendSaveTimer = null;
+
+  function flushBackendSave() {
+    if (backendSaveTimer) {
+      clearTimeout(backendSaveTimer);
+      backendSaveTimer = null;
+    }
+    if (pendingBackendName === null) return;
+    const name = pendingBackendName;
+    pendingBackendName = null;
+    try {
+      setBackend(name);
+    } catch (err) {
+      process.stderr.write(`[channels] debounced setBackend failed: ${err?.message || err}\n`);
+    }
+  }
+
+  function scheduleBackendSave(name) {
+    pendingBackendName = name;
+    if (backendSaveTimer) clearTimeout(backendSaveTimer);
+    backendSaveTimer = setTimeout(flushBackendSave, CONFIG_SAVE_DEBOUNCE_MS);
+    backendSaveTimer.unref?.();
+  }
+
+  // --- debounced top-level outputStyle persist -------------------------------
+  let pendingOutputStyleId = null;
+  let outputStyleSaveTimer = null;
+
+  function flushOutputStyleSave() {
+    if (outputStyleSaveTimer) {
+      clearTimeout(outputStyleSaveTimer);
+      outputStyleSaveTimer = null;
+    }
+    if (pendingOutputStyleId === null) return;
+    const styleId = pendingOutputStyleId;
+    pendingOutputStyleId = null;
+    try {
+      sharedCfgMod.updateConfig((root) => {
+        const next = { ...(root || {}), outputStyle: styleId };
+        if (next.agent && typeof next.agent === 'object' && !Array.isArray(next.agent)) {
+          const agent = { ...next.agent };
+          delete agent.outputStyle;
+          next.agent = agent;
+        }
+        return next;
+      });
+    } catch (err) {
+      process.stderr.write(`[config] debounced outputStyle save failed: ${err?.message || err}\n`);
+    }
+  }
+
+  function scheduleOutputStyleSave(styleId) {
+    pendingOutputStyleId = styleId;
+    if (outputStyleSaveTimer) clearTimeout(outputStyleSaveTimer);
+    outputStyleSaveTimer = setTimeout(flushOutputStyleSave, CONFIG_SAVE_DEBOUNCE_MS);
+    outputStyleSaveTimer.unref?.();
+  }
+
+  // --- reload / ensure --------------------------------------------------------
+  function reloadFullConfig() {
+    // A pending debounced write holds the only copy of the latest change.
+    // Flush it before re-reading from disk so loadConfig() observes (and the
+    // subsequent adopt preserves) that change instead of reverting to a stale
+    // on-disk snapshot.
+    flushConfigSave();
+    return adoptConfig(cfgMod.loadConfig(), { hasSecrets: true });
+  }
+
+  function ensureFullConfig() {
+    if (getConfigHasSecrets()) return getConfig();
+    return reloadFullConfig();
+  }
+
+  function displayConfig() {
+    return getConfig();
+  }
+
+  function ensureConfigForRouteProvider() {
+    const config = getConfig();
+    const providerId = clean(getRoute().provider);
+    const providerCfg = config?.providers?.[providerId];
+    if (getConfigHasSecrets() || LAZY_SECRET_PROVIDERS.has(providerId) || providerCfg?.apiKey) {
+      return config;
+    }
+    return ensureFullConfig();
+  }
+
+  return {
+    // output-style cache
+    getOutputStyleStatusCached,
+    invalidateOutputStyleStatusCache,
+    seedOutputStyleStatusCache,
+    // adopt / save
+    adoptConfig,
+    saveConfigAndAdopt,
+    flushConfigSave,
+    flushBackendSave,
+    scheduleBackendSave,
+    flushOutputStyleSave,
+    scheduleOutputStyleSave,
+    // reload / ensure
+    reloadFullConfig,
+    ensureFullConfig,
+    displayConfig,
+    ensureConfigForRouteProvider,
+  };
+}