@jsonstudio/rcc 0.89.1205 → 0.89.1348

package/scripts/camoufox/launch-auth.mjs

@@ -7,6 +7,12 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
+function isTruthy(value) {
+  if (!value) return false;
+  const v = String(value).trim().toLowerCase();
+  return v === '1' || v === 'true' || v === 'yes' || v === 'on';
+}
+
 function parseArgs(argv) {
   const args = { profile: 'default', url: '', autoMode: '', devMode: false };
   const list = argv.slice(2);
@@ -65,6 +71,44 @@ async function getCamoufoxCacheRoot() {
   });
 }
 
+function resolveCamoufoxBinary(cacheRoot) {
+  const override = (process.env.ROUTECODEX_CAMOUFOX_BINARY || '').trim();
+  if (override) {
+    return override;
+  }
+
+  const isMac = process.platform === 'darwin';
+  if (!cacheRoot && isMac) {
+    // Best-effort fallback when python3 is unavailable/broken:
+    // Camoufox's packaged app is commonly placed under ~/Library/Caches/camoufox/Camoufox.app.
+    const guessed = path.join(os.homedir(), 'Library', 'Caches', 'camoufox');
+    if (fs.existsSync(path.join(guessed, 'Camoufox.app'))) {
+      cacheRoot = guessed;
+    }
+  }
+  if (cacheRoot && isMac) {
+    const appPath = path.join(cacheRoot, 'Camoufox.app');
+    const macBinary = path.join(appPath, 'Contents', 'MacOS', 'camoufox');
+    if (fs.existsSync(macBinary)) {
+      return macBinary;
+    }
+  }
+
+  try {
+    const located = spawnSync('which', ['camoufox'], { encoding: 'utf-8' });
+    if (located.status === 0) {
+      const resolved = String(located.stdout || '').trim();
+      if (resolved) {
+        return resolved;
+      }
+    }
+  } catch {
+    // ignore lookup failure
+  }
+
+  return 'camoufox';
+}
+
 async function ensureProfileDir(profileId) {
   const root = path.join(os.homedir(), '.routecodex', 'camoufox-profiles');
   const dir = path.join(root, profileId);
@@ -108,17 +152,16 @@ async function main() {
 
   const cacheRoot = await getCamoufoxCacheRoot();
   if (!cacheRoot) {
-    console.error(
-      '[camoufox-launch-auth] Failed to resolve Camoufox cache root via "python3 -m camoufox path"'
+    console.warn(
+      '[camoufox-launch-auth] Failed to resolve Camoufox cache root via "python3 -m camoufox path"; falling back to PATH/override.'
     );
-    process.exit(1);
   }
 
   const camoufoxBinary = resolveCamoufoxBinary(cacheRoot);
 
   if (autoMode && autoMode.trim().toLowerCase() === 'iflow') {
     try {
-      await runIflowAutoFlow({ url, profileDir, profileId, camoufoxBinary, devMode });
+      await runAutoFlowWithFallback('iflow', { url, profileDir, profileId, camoufoxBinary, devMode });
       process.exit(0);
     } catch (error) {
       console.error(
@@ -132,7 +175,7 @@ async function main() {
 
   if (autoMode && autoMode.trim().toLowerCase() === 'gemini') {
     try {
-      await runGeminiAutoFlow({ url, profileDir, camoufoxBinary, devMode });
+      await runAutoFlowWithFallback('gemini', { url, profileDir, profileId, camoufoxBinary, devMode });
       process.exit(0);
     } catch (error) {
       console.error(
@@ -146,7 +189,7 @@ async function main() {
 
   if (autoMode && autoMode.trim().toLowerCase() === 'antigravity') {
     try {
-      await runAntigravityAutoFlow({ url, profileDir, camoufoxBinary, devMode });
+      await runAutoFlowWithFallback('antigravity', { url, profileDir, profileId, camoufoxBinary, devMode });
       process.exit(0);
     } catch (error) {
       console.error(
@@ -166,59 +209,29 @@ main().catch((err) => {
   process.exit(1);
 });
 
-function resolveCamoufoxBinary(cacheRoot) {
-  const isMac = process.platform === 'darwin';
-  if (isMac) {
-    const appPath = path.join(cacheRoot, 'Camoufox.app');
-    const macBinary = path.join(appPath, 'Contents', 'MacOS', 'camoufox');
-    if (fs.existsSync(macBinary)) {
-      return macBinary;
-    }
-  }
-  try {
-    const located = spawnSync('which', ['camoufox'], { encoding: 'utf-8' });
-    if (located.status === 0) {
-      const resolved = located.stdout.trim();
-      if (resolved) {
-        return resolved;
+async function launchManualCamoufox({ camoufoxBinary, profileDir, url }) {
+  let browserExitCode = 0;
+  let browser = null;
+  const shutdownBrowser = (signal = 'SIGTERM') => {
+    try {
+      if (!browser) {
+        return;
       }
+      browser.kill(signal);
+    } catch {
+      // ignore
     }
-  } catch {
-    // ignore lookup failure
-  }
-  return 'camoufox';
-}
+  };
+  ['SIGTERM', 'SIGINT', 'SIGHUP'].forEach((signal) => {
+    process.on(signal, () => shutdownBrowser(signal));
+  });
 
-async function launchManualCamoufox({ camoufoxBinary, profileDir, url }) {
-  let browserExitCode = 0;
   try {
-    const browser = spawn(camoufoxBinary, ['-profile', profileDir, url], {
-      detached: true,
+    browser = spawn(camoufoxBinary, ['-profile', profileDir, url], {
+      detached: false,
       stdio: 'ignore'
     });
 
-    const shutdownBrowser = (signal = 'SIGTERM') => {
-      try {
-        if (browser.pid) {
-          try {
-            process.kill(-browser.pid, signal);
-            return;
-          } catch {
-            // process group kill may fail on non-unix systems; fall back to direct kill
-          }
-        }
-        browser.kill(signal);
-      } catch {
-        // ignore
-      }
-    };
-
-    ['SIGTERM', 'SIGINT'].forEach((signal) => {
-      process.on(signal, () => {
-        shutdownBrowser(signal);
-      });
-    });
-
     browserExitCode = await new Promise((resolve) => {
       browser.on('exit', (code) => resolve(code ?? 0));
       browser.on('error', () => resolve(1));
@@ -234,6 +247,95 @@ async function launchManualCamoufox({ camoufoxBinary, profileDir, url }) {
   process.exit(browserExitCode);
 }
 
+function isSelectorOrTimeoutError(error) {
+  const message = error instanceof Error ? error.message : String(error || '');
+  return (
+    /timeout/i.test(message) ||
+    /waiting for selector/i.test(message) ||
+    /strict mode violation/i.test(message) ||
+    message.includes('未能定位') ||
+    message.includes('无法定位')
+  );
+}
+
+async function runHeadedManualAssistFlow({ url, profileDir, camoufoxBinary, timeoutMs, label }) {
+  let firefox;
+  try {
+    ({ firefox } = await import('playwright-core'));
+  } catch (error) {
+    throw new Error(
+      `playwright-core is required for headed manual assist (${error instanceof Error ? error.message : String(error)})`
+    );
+  }
+
+  console.warn(
+    `[camoufox-launch-auth] ${label}: falling back to headed mode for manual completion (no selector match).`
+  );
+  cleanupExistingCamoufox(profileDir);
+  const context = await firefox.launchPersistentContext(profileDir, {
+    executablePath: camoufoxBinary,
+    headless: false,
+    acceptDownloads: false
+  });
+
+  let closed = false;
+  const shutdown = async () => {
+    if (closed) return;
+    closed = true;
+    await context.close().catch(() => {});
+  };
+  ['SIGTERM', 'SIGINT', 'SIGHUP'].forEach((signal) => {
+    process.on(signal, () => {
+      void shutdown().finally(() => process.exit(0));
+    });
+  });
+
+  try {
+    const page = context.pages()[0] || (await context.newPage());
+    await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 }).catch(() => {});
+    console.log('[camoufox-launch-auth] Headed browser opened. Please complete OAuth manually...');
+    const callbackPage = await waitForCallback(context, page, timeoutMs);
+    await callbackPage.waitForLoadState('load', { timeout: 120000 }).catch(() => {});
+    console.log('[camoufox-launch-auth] OAuth callback detected, manual completion finished.');
+  } finally {
+    await shutdown();
+  }
+}
+
+async function runAutoFlowWithFallback(kind, options) {
+  const mode = String(kind || '').trim().toLowerCase();
+  const label = mode || 'auto';
+  const timeoutMs = Number(process.env.ROUTECODEX_CAMOUFOX_GEMINI_TIMEOUT_MS || 120_000);
+
+  try {
+    if (mode === 'iflow') {
+      await runIflowAutoFlow(options);
+      return;
+    }
+    if (mode === 'gemini') {
+      await runGeminiAutoFlow(options);
+      return;
+    }
+    if (mode === 'antigravity') {
+      await runAntigravityAutoFlow(options);
+      return;
+    }
+    throw new Error(`Unknown auto mode: ${mode}`);
+  } catch (error) {
+    if (!options.devMode && isSelectorOrTimeoutError(error)) {
+      await runHeadedManualAssistFlow({
+        url: options.url,
+        profileDir: options.profileDir,
+        camoufoxBinary: options.camoufoxBinary,
+        timeoutMs: Number(process.env.ROUTECODEX_OAUTH_TIMEOUT_MS || 10 * 60_000),
+        label
+      });
+      return;
+    }
+    throw error;
+  }
+}
+
 async function runIflowAutoFlow({ url, profileDir, profileId, camoufoxBinary, devMode }) {
   let firefox;
   try {
@@ -252,6 +354,17 @@ async function runIflowAutoFlow({ url, profileDir, profileId, camoufoxBinary, de
     headless,
     acceptDownloads: false
   });
+  let closing = false;
+  const shutdown = async () => {
+    if (closing) return;
+    closing = true;
+    await context.close().catch(() => {});
+  };
+  ['SIGTERM', 'SIGINT', 'SIGHUP'].forEach((signal) => {
+    process.on(signal, () => {
+      void shutdown().finally(() => process.exit(0));
+    });
+  });
 
   let callbackObserved = false;
   try {
@@ -352,7 +465,7 @@ async function runIflowAutoFlow({ url, profileDir, profileId, camoufoxBinary, de
     }
     throw error;
   } finally {
-    await context.close().catch(() => {});
+    await shutdown();
   }
 }
 
@@ -374,6 +487,17 @@ async function runGeminiAutoFlow({ url, profileDir, camoufoxBinary, devMode }) {
     headless: !devMode,
     acceptDownloads: false
   });
+  let closing = false;
+  const shutdown = async () => {
+    if (closing) return;
+    closing = true;
+    await context.close().catch(() => {});
+  };
+  ['SIGTERM', 'SIGINT', 'SIGHUP'].forEach((signal) => {
+    process.on(signal, () => {
+      void shutdown().finally(() => process.exit(0));
+    });
+  });
 
   let callbackObserved = false;
   try {
@@ -440,7 +564,7 @@ async function runGeminiAutoFlow({ url, profileDir, camoufoxBinary, devMode }) {
     await callbackPage.waitForLoadState('load', { timeout: timeoutMs }).catch(() => {});
     console.log('[camoufox-launch-auth] OAuth callback detected, automation complete.');
   } finally {
-    await context.close().catch(() => {});
+    await shutdown();
   }
 }
 
@@ -462,6 +586,17 @@ async function runAntigravityAutoFlow({ url, profileDir, camoufoxBinary, devMode
     headless: !devMode,
     acceptDownloads: false
   });
+  let closing = false;
+  const shutdown = async () => {
+    if (closing) return;
+    closing = true;
+    await context.close().catch(() => {});
+  };
+  ['SIGTERM', 'SIGINT', 'SIGHUP'].forEach((signal) => {
+    process.on(signal, () => {
+      void shutdown().finally(() => process.exit(0));
+    });
+  });
 
   let callbackObserved = false;
   try {
@@ -544,7 +679,7 @@ async function runAntigravityAutoFlow({ url, profileDir, camoufoxBinary, devMode
     }
     throw error;
   } finally {
-    await context.close().catch(() => {});
+    await shutdown();
   }
 }
 
@@ -584,7 +719,7 @@ async function waitForElementInPages(context, selector, timeoutMs) {
   return null;
 }
 
-async function waitForCallback(context, fallbackPage) {
+async function waitForCallback(context, fallbackPage, timeoutMs = 120000) {
   const isCallbackUrl = (current) => {
     if (typeof current !== 'string') {
       return false;
@@ -605,13 +740,13 @@ async function waitForCallback(context, fallbackPage) {
   }
 
   try {
-    await fallbackPage.waitForURL((current) => isCallbackUrl(current), { timeout: 120000 });
+    await fallbackPage.waitForURL((current) => isCallbackUrl(current), { timeout: timeoutMs });
     return fallbackPage;
   } catch {
     // ignore and wait for popup
   }
 
-  const callback = await context.waitForEvent('page', { timeout: 120000 });
+  const callback = await context.waitForEvent('page', { timeout: timeoutMs });
   await callback.waitForLoadState('domcontentloaded', { timeout: 60000 }).catch(() => {});
   return callback;
 }

package/scripts/monitor-diff.mjs

@@ -0,0 +1,126 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+function parseArgs(argv) {
+  const args = {
+    intervalMs: 1000,
+    errorsRoot: process.env.ROUTECODEX_ERRORSAMPLES_DIR || path.join(os.homedir(), '.routecodex', 'errorsamples'),
+    once: false
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--once') args.once = true;
+    else if (a === '--interval' || a === '--intervalMs') {
+      const v = argv[i + 1];
+      i += 1;
+      const n = Number(v);
+      if (Number.isFinite(n) && n > 0) args.intervalMs = n;
+    } else if (a === '--errorsRoot') {
+      const v = argv[i + 1];
+      i += 1;
+      if (v && String(v).trim()) args.errorsRoot = path.resolve(String(v).trim());
+    }
+  }
+  return args;
+}
+
+function safeJsonRead(filePath) {
+  try {
+    const text = fs.readFileSync(filePath, 'utf8');
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+function listJsonFiles(dirPath) {
+  try {
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    return entries
+      .filter((e) => e.isFile() && e.name.endsWith('.json'))
+      .map((e) => path.join(dirPath, e.name));
+  } catch {
+    return [];
+  }
+}
+
+function summarizeRecord(record) {
+  if (!record || typeof record !== 'object') return null;
+  const kind = record.kind || 'unknown';
+  const timestamp = record.timestamp || record.time || null;
+
+  if (String(kind).includes('shadow') || String(kind).includes('diff')) {
+    return {
+      kind,
+      timestamp,
+      requestId: record.requestId,
+      entryEndpoint: record.entryEndpoint,
+      baselineMode: record.baselineMode,
+      candidateMode: record.candidateMode,
+      diffCount: record.diffCount,
+      diffPaths: Array.isArray(record.diffPaths) ? record.diffPaths.slice(0, 12) : undefined,
+      runtime: record.runtime
+    };
+  }
+  if (String(kind).includes('hub_policy') || String(kind).includes('policy')) {
+    return {
+      kind,
+      timestamp,
+      stage: record.stage,
+      requestId: record.requestId,
+      endpoint: record.endpoint,
+      providerProtocol: record.providerProtocol,
+      violationCount: Array.isArray(record.observation?.violations) ? record.observation.violations.length : undefined,
+      runtime: record.runtime
+    };
+  }
+  return { kind, timestamp };
+}
+
+function printNewFile(filePath) {
+  const record = safeJsonRead(filePath);
+  const summary = summarizeRecord(record);
+  const rel = filePath;
+  if (!summary) {
+    // eslint-disable-next-line no-console
+    console.log(`[errorsamples] ${rel}`);
+    return;
+  }
+  // eslint-disable-next-line no-console
+  console.log(`[errorsamples] ${rel} -> ${JSON.stringify(summary)}`);
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  const dirs = [
+    path.join(args.errorsRoot, 'unified-hub-shadow-runtime'),
+    path.join(args.errorsRoot, 'unified-hub-shadow-runtime-routing'),
+    path.join(args.errorsRoot, 'policy')
+  ];
+
+  // eslint-disable-next-line no-console
+  console.log('[monitor:diff] watching:', dirs.join(', '));
+  // eslint-disable-next-line no-console
+  console.log('[monitor:diff] intervalMs=', args.intervalMs, 'errorsRoot=', args.errorsRoot);
+
+  const seen = new Set();
+  const scanOnce = () => {
+    for (const dir of dirs) {
+      const files = listJsonFiles(dir);
+      for (const f of files) {
+        if (seen.has(f)) continue;
+        seen.add(f);
+        printNewFile(f);
+      }
+    }
+  };
+
+  scanOnce();
+  if (args.once) return;
+  setInterval(scanOnce, args.intervalMs);
+}
+
+await main();
+

package/scripts/pack-mode.mjs

@@ -70,12 +70,30 @@ try {
     mutated.bundledDependencies = [];
     mutated.bundleDependencies = [];
     const llmsVersion = original.dependencies?.['@jsonstudio/llms'] || '^0.6.230';
+    const deps = {
+      ...(original.dependencies || {})
+    };
+    // Avoid recursive self-dependency when packing @jsonstudio/rcc.
+    if (isRcc && deps['@jsonstudio/rcc']) {
+      delete deps['@jsonstudio/rcc'];
+    }
     mutated.dependencies = {
-      ...(original.dependencies || {}),
+      ...deps,
       ajv: original.dependencies?.ajv || '^8.17.1',
       zod: original.dependencies?.zod || '^3.23.8',
       '@jsonstudio/llms': llmsVersion
     };
+    // Ensure rcc ships bundled docs (copied to ~/.routecodex/docs by `rcc init`).
+    if (isRcc) {
+      const baseFiles = Array.isArray(original.files) ? [...original.files] : [];
+      if (!baseFiles.includes('docs/')) {
+        baseFiles.push('docs/');
+      }
+      if (!baseFiles.includes('configsamples/')) {
+        baseFiles.push('configsamples/');
+      }
+      mutated.files = baseFiles;
+    }
   } else if (isRccx) {
     // rccx: wasm-backed llms 核心，通过 npm alias 将 @jsonstudio/llms 指向 wasm 引擎包。
     mutated.bundledDependencies = [];

package/scripts/pack-rcc.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = path.resolve(__dirname, '..');
+
+const pkgPath = path.join(PROJECT_ROOT, 'package.json');
+const PACK_SCRIPT = path.join(PROJECT_ROOT, 'scripts', 'pack-mode.mjs');
+const llmsPath = path.join(PROJECT_ROOT, 'node_modules', '@jsonstudio', 'llms');
+
+function run(command, args, options = {}) {
+  const res = spawnSync(command, args, { stdio: 'inherit', ...options });
+  if ((res.status ?? 0) !== 0) {
+    throw new Error(`${command} ${args.join(' ')} failed`);
+  }
+}
+
+function isSymlink(p) {
+  try {
+    return fs.lstatSync(p).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+try {
+  const hadDevLink = isSymlink(llmsPath);
+
+  // 1) release 模式构建 dist（依赖 npm 上的 @jsonstudio/llms）
+  run('npm', ['run', 'build:min'], {
+    cwd: PROJECT_ROOT,
+    env: { ...process.env, BUILD_MODE: 'release' }
+  });
+
+  // 2) 通过 pack-mode 生成 rcc tarball（内部会临时切换 package.json.name/bin 并确保 llms 为 release 包）
+  run(process.execPath, [PACK_SCRIPT, '--name', '@jsonstudio/rcc', '--bin', 'rcc'], { cwd: PROJECT_ROOT });
+
+  const updatedPkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+  const version = updatedPkg.version;
+  const tarballName = `jsonstudio-rcc-${version}.tgz`;
+  const tarballPath = path.join(PROJECT_ROOT, tarballName);
+
+  if (!fs.existsSync(tarballPath)) {
+    throw new Error(`tarball not found: ${tarballPath}`);
+  }
+
+  console.log(`[pack-rcc] ✅ tarball ready: ${tarballPath}`);
+
+  // 3) pack 结束后恢复 dev 模式（routecodex 约定始终为 dev CLI；rcc 打包时才切 release）。
+  if (hadDevLink) {
+    run('npm', ['run', 'llmswitch:ensure'], {
+      cwd: PROJECT_ROOT,
+      env: { ...process.env, BUILD_MODE: 'dev' }
+    });
+  }
+} catch (err) {
+  console.error('[pack-rcc] failed:', err instanceof Error ? err.message : String(err));
+  process.exit(1);
+}
+

package/scripts/unified-hub-shadow-compare.mjs

@@ -141,6 +141,14 @@ function stableStringify(value) {
   );
 }
 
+function cloneJsonSafe(value) {
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch {
+    return value;
+  }
+}
+
 function diffPayloads(expected, actual, p = '<root>') {
   if (Object.is(expected, actual)) return [];
   if (typeof expected !== typeof actual) {
@@ -254,12 +262,12 @@ async function bootstrapVirtualRouterConfig(rawConfig) {
   return mod.bootstrapVirtualRouterConfig(rawConfig);
 }
 
-async function runOnce({ requestId, mode, entryEndpoint, routeHint, payload }) {
+async function runOnce({ requestId, candidateMode, baselineMode, entryEndpoint, routeHint, payload }) {
   const HubPipeline = await importHubPipelineCtor();
   const artifacts = await bootstrapVirtualRouterConfig(buildVirtualRouterConfig());
   const pipeline = new HubPipeline({
     virtualRouter: artifacts.config,
-    policy: { mode }
+    policy: { mode: candidateMode }
   });
   const providerProtocol = normalizeEntryProviderProtocol(entryEndpoint);
   const result = await pipeline.execute({
@@ -269,7 +277,10 @@ async function runOnce({ requestId, mode, entryEndpoint, routeHint, payload }) {
     metadata: {
       entryEndpoint,
       providerProtocol,
-      routeHint
+      routeHint,
+      __hubShadowCompare: {
+        baselineMode
+      }
     }
   });
   return result;
@@ -300,18 +311,24 @@ async function main() {
   const candidateMode = String(opts.candidateMode);
   const requestId = `shadow_unified_hub_${Date.now()}`;
 
-  const baseline = await runOnce({ requestId, mode: baselineMode, entryEndpoint, routeHint, payload });
-  const candidate = await runOnce({ requestId, mode: candidateMode, entryEndpoint, routeHint, payload });
+  const candidate = await runOnce({ requestId, candidateMode, baselineMode, entryEndpoint, routeHint, payload });
+  const shadow = candidate && candidate.metadata && typeof candidate.metadata === 'object'
+    ? candidate.metadata.hubShadowCompare
+    : undefined;
+  const baselineProviderPayload =
+    shadow && typeof shadow === 'object' && shadow && !Array.isArray(shadow)
+      ? shadow.baselineProviderPayload
+      : undefined;
 
   const baselineOut = {
-    providerPayload: baseline.providerPayload,
-    target: baseline.target,
+    providerPayload: baselineProviderPayload,
+    target: candidate.target,
     metadata: {
-      entryEndpoint: baseline.metadata?.entryEndpoint,
-      providerProtocol: baseline.metadata?.providerProtocol,
-      processMode: baseline.metadata?.processMode,
-      stream: baseline.metadata?.stream,
-      routeHint: baseline.metadata?.routeHint
+      entryEndpoint: candidate.metadata?.entryEndpoint,
+      providerProtocol: candidate.metadata?.providerProtocol,
+      processMode: candidate.metadata?.processMode,
+      stream: candidate.metadata?.stream,
+      routeHint: candidate.metadata?.routeHint
     }
   };
   const candidateOut = {
@@ -326,7 +343,10 @@ async function main() {
     }
   };
 
-  const diffs = diffPayloads(baselineOut, candidateOut);
+  if (!baselineProviderPayload || typeof baselineProviderPayload !== 'object') {
+    throw new Error('[unified-hub-shadow-compare] hubShadowCompare.baselineProviderPayload missing; ensure llmswitch-core is rebuilt.');
+  }
+  const diffs = diffPayloads(cloneJsonSafe(baselineOut), cloneJsonSafe(candidateOut));
   if (!diffs.length) {
     console.log('[unified-hub-shadow-compare] OK diff=0');
     return;