@cats-inc/cats-platform 0.1.21 → 0.2.8

package/scripts/macos/test-macos-package-smoke.sh

@@ -37,10 +37,11 @@ assert_file "${RESOURCES_ROOT}/app-sidecar/build/renderer/index.html" 'bundled c
 assert_file "${RESOURCES_ROOT}/app-sidecar/package.json" 'bundled cats app package manifest'
 assert_file "${RESOURCES_ROOT}/app-sidecar/node_modules/js-yaml/package.json" 'bundled cats app js-yaml dependency marker'
 assert_file "${RESOURCES_ROOT}/app-sidecar/node_modules/argparse/package.json" 'bundled cats app argparse dependency marker'
+assert_file "${RESOURCES_ROOT}/app-sidecar/config/provider-capability-bootstrap.yaml.example" 'bundled cats capability bootstrap example'
 assert_file "${RESOURCES_ROOT}/cats-runtime/build/runtime/index.js" 'bundled cats-runtime entry'
 assert_file "${RESOURCES_ROOT}/cats-runtime/package.json" 'bundled cats-runtime package manifest'
 assert_file "${RESOURCES_ROOT}/cats-runtime/public/provider-setup.html" 'bundled cats-runtime setup UI'
-assert_file "${RESOURCES_ROOT}/cats-runtime/skills/README.md" 'bundled cats-runtime skills catalog root'
+assert_file "${RESOURCES_ROOT}/cats-runtime/runtime-skills/README.md" 'bundled cats-runtime skills catalog root'
 assert_file "${RESOURCES_ROOT}/cats-runtime/config/management.yaml.example" 'bundled cats-runtime management config example'
 assert_file "${RESOURCES_ROOT}/cats-runtime/config/providers.yaml.example" 'bundled cats-runtime provider config example'
 assert_file "${RESOURCES_ROOT}/cats-runtime/config/curated-model-catalogs.yaml.example" 'bundled cats-runtime curated model catalog example'
@@ -53,7 +54,7 @@ assert_file "${RESOURCES_ROOT}/desktop/setup-assets/macos/install-antigravity.sh
 assert_file "${RESOURCES_ROOT}/desktop/setup-assets/macos/install-grok.sh" 'bundled macOS Grok installer helper'
 assert_file "${RESOURCES_ROOT}/desktop/setup-assets/macos/install-cline.sh" 'bundled macOS Cline installer helper'
 assert_file "${RESOURCES_ROOT}/desktop/setup-assets/macos/install-devin.sh" 'bundled macOS Devin installer helper'
-assert_file "${RESOURCES_ROOT}/desktop/setup-assets/macos/install-aider.sh" 'bundled macOS Aider installer helper'
+assert_file "${RESOURCES_ROOT}/desktop/setup-assets/macos/install-meta-cli.sh" 'bundled macOS Meta Muse installer helper'
 assert_file "${RESOURCES_ROOT}/desktop/setup-assets/macos/install-copilot.sh" 'bundled macOS GitHub Copilot installer helper'
 assert_file "${RESOURCES_ROOT}/desktop/setup-assets/macos/install-opencode.sh" 'bundled macOS OpenCode installer helper'
 assert_file "${RESOURCES_ROOT}/desktop/setup-assets/macos/install-kilo.sh" 'bundled macOS Kilo Code installer helper'
@@ -102,7 +103,7 @@ assert(macTarget.artifacts.some((artifact) => artifact.id === 'macos-antigravity
 assert(macTarget.artifacts.some((artifact) => artifact.id === 'macos-grok-native-installer-script'), 'macOS target includes the bundled Grok installer asset');
 assert(macTarget.artifacts.some((artifact) => artifact.id === 'macos-cline-native-installer-script'), 'macOS target includes the bundled Cline installer asset');
 assert(macTarget.artifacts.some((artifact) => artifact.id === 'macos-devin-native-installer-script'), 'macOS target includes the bundled Devin installer asset');
-assert(macTarget.artifacts.some((artifact) => artifact.id === 'macos-aider-native-installer-script'), 'macOS target includes the bundled Aider installer asset');
+assert(macTarget.artifacts.some((artifact) => artifact.id === 'macos-muse-native-installer-script'), 'macOS target includes the bundled Meta Muse installer asset');
 assert(macTarget.artifacts.some((artifact) => artifact.id === 'macos-setup-readiness-audit-script'), 'macOS target includes the bundled readiness audit asset');
 assert(macTarget.artifacts.some((artifact) => artifact.id === 'macos-provider-cli-common-support-script'), 'macOS target includes the macOS provider helper asset');
 assert(macTarget.artifacts.some((artifact) => artifact.id === 'macos-node-cli-common-support-script'), 'macOS target includes the macOS npm helper asset');

package/scripts/macos/upgrade-cli-tools.sh

@@ -35,7 +35,7 @@ while [ $# -gt 0 ]; do
   shift
 done
 
-for script_name in install-claude-code.sh install-antigravity.sh install-cursor-agent.sh install-devin.sh install-aider.sh install-goose.sh install-junie.sh install-kiro-cli.sh install-grok.sh; do
+for script_name in install-claude-code.sh install-antigravity.sh install-cursor-agent.sh install-devin.sh install-meta-cli.sh install-goose.sh install-junie.sh install-kiro-cli.sh install-grok.sh; do
   "$SCRIPT_DIR/$script_name" -Upgrade
 done
 

package/scripts/package-desktop.mjs

@@ -4,6 +4,7 @@ import process from 'node:process';
 import { access, readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { resolveAppLock } from '#cats-app-package';
 
 const SCRIPT_PATH = fileURLToPath(import.meta.url);
 const PROJECT_ROOT = resolve(fileURLToPath(new URL('..', import.meta.url)));
@@ -36,6 +37,7 @@ Options:
   --platform <all|windows|macos|linux>  Filter staged target manifests
   --output-dir <path>                   Override packaging output root
   --sidecar-layout <split|bundle>       Choose loose-file or bundled sidecars for both app/runtime
+  --apps-lock <path>                    Exact App ID/version/SHA-256 selection (no latest resolution)
   --help                                Show this help text
 `);
 }
@@ -54,17 +56,23 @@ export function parseArgs(argv, env = process.env) {
   let platform = 'all';
   let outputDir = null;
   let sidecarLayout = resolveSidecarLayout(env.CATS_DESKTOP_SIDECAR_LAYOUT);
+  let appsLock = env.CATS_DESKTOP_APPS_LOCK?.trim() || null;
 
   for (let index = 0; index < argv.length; index += 1) {
     const value = argv[index];
     if (value === '--help' || value === '-h') {
-      return { help: true, platform, outputDir, sidecarLayout };
+      return { help: true, platform, outputDir, sidecarLayout, ...(appsLock ? { appsLock } : {}) };
     }
     if (value === '--platform') {
       platform = argv[index + 1] ?? 'all';
       index += 1;
       continue;
     }
+    if (value === '--apps-lock') {
+      appsLock = argv[++index];
+      if (!appsLock || appsLock.startsWith('--')) throw new Error('--apps-lock requires a path.');
+      continue;
+    }
     if (value === '--output-dir') {
       outputDir = argv[index + 1] ?? null;
       index += 1;
@@ -78,7 +86,7 @@ export function parseArgs(argv, env = process.env) {
     throw new Error(`Unknown option: ${value}`);
   }
 
-  return { help: false, platform, outputDir, sidecarLayout };
+  return { help: false, platform, outputDir, sidecarLayout, ...(appsLock ? { appsLock } : {}) };
 }
 
 export function resolveRequiredDesktopIconPaths(projectRoot = PROJECT_ROOT) {
@@ -176,6 +184,9 @@ async function main() {
   const { resolveDesktopHostConfig } = await import('../build/desktop/config.js');
   const { stageDesktopPackagingOutputs } = await import('../build/desktop/packaging.js');
 
+  const apps = parsed.appsLock ? await resolveAppLock(resolve(parsed.appsLock)) : [];
+  if (!parsed.appsLock) process.stderr.write('[desktop-package] No --apps-lock selected; this package contains no optional Apps.\n');
+
   await assertDesktopIconAssetsPresent(PROJECT_ROOT);
   const config = resolveDesktopHostConfig({
     env: process.env,
@@ -185,10 +196,12 @@ async function main() {
     outputRoot: parsed.outputDir ? resolve(PROJECT_ROOT, parsed.outputDir) : undefined,
     platforms: allowedPlatforms,
     sidecarLayout: parsed.sidecarLayout,
+    apps,
   });
 
   process.stdout.write(JSON.stringify({
     outputRoot: plan.outputRoot,
+    apps: plan.apps,
     sidecarLayout: plan.sidecarLayout,
     targets: plan.targets.map((target) => ({
       id: target.id,

package/scripts/testing/check-usage-app.mts

@@ -0,0 +1,266 @@
+#!/usr/bin/env node
+// Integration-only: built App archive + real host surface/route + fixture runtime.
+// Usage: node --import tsx scripts/testing/check-usage-app.mts --apps-lock <path>
+// Requires CATS_TEST_PLAYWRIGHT_MODULE (absolute module file) and CATS_TEST_BROWSER_EXECUTABLE.
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+import { mkdtemp, mkdir, readFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { build } from 'esbuild';
+import { resolveAppLock } from '#cats-app-package';
+import { installRendererPackage } from '../../src/platform/apps/packageInstaller.js';
+import { FileCatsAppRegistry } from '../../src/platform/apps/registry.js';
+import { resolveCatsAppStoragePathsFromChatState } from '../../src/platform/apps/paths.js';
+import { projectUsageSnapshot, projectUsageQuotaRefresh } from '../../src/runtime/usageSnapshot.js';
+import { toPlatformInstalledAppDescriptor } from '../../src/platform/apps/envelope.js';
+import { routeRequest } from '../../src/app/server/requestRouter.js';
+import type { ResolvedServerDependencies } from '../../src/app/server/contracts.js';
+import { loadConfig } from '../../src/config.js';
+import { createDefaultCoreState } from '../../src/core/model/index.js';
+import { MemoryCoreStore } from '../../src/core/store.js';
+import { createEmptyPlatformAuthState, createFirstAdminLocalAuthState, MemoryPlatformAuthStore } from '../../src/platform/auth/index.js';
+
+const args = process.argv.slice(2);
+if (args.includes('--help')) {
+  process.stdout.write('Usage: node --import tsx scripts/testing/check-usage-app.mts --apps-lock <path> [--renderer-root <built renderer directory>] [--electron] [--check-loading-recovery]\nRequires CATS_TEST_PLAYWRIGHT_MODULE and CATS_TEST_BROWSER_EXECUTABLE; no real user state is read.\n');
+  process.exit(0);
+}
+const lockPath = args[args.indexOf('--apps-lock') + 1];
+const rendererRoot = args.includes('--renderer-root') ? path.resolve(args[args.indexOf('--renderer-root') + 1]!) : null;
+if (args.includes('--electron') && args.includes('--check-loading-recovery')) {
+  throw new Error('Loading fault injection requires Chromium/Edge. Run Electron functional checks without --check-loading-recovery.');
+}
+if (args.indexOf('--apps-lock') < 0 || !lockPath || !process.env.CATS_TEST_PLAYWRIGHT_MODULE || !process.env.CATS_TEST_BROWSER_EXECUTABLE) throw new Error('App lock and isolated browser test inputs are required.');
+const root = await mkdtemp(path.join(tmpdir(), 'cats-usage-browser-'));
+const chatStatePath = path.join(root, 'state', 'chat-state.local.json');
+const apps = await resolveAppLock(path.resolve(lockPath));
+const usage = apps.find((app) => app.id === 'cats.usage');
+if (!usage) throw new Error('The selected lock must contain a built Usage package.');
+const entryPath = rendererRoot ? '/apps/cats.usage' : `/?appVersion=${encodeURIComponent(usage.version)}`;
+await installRendererPackage({ chatStatePath, bytes: usage.bytes, pin: usage, source: 'local-package', enable: true });
+const registry = new FileCatsAppRegistry({ registryPath: resolveCatsAppStoragePathsFromChatState(chatStatePath).registryPath });
+const bundle = rendererRoot ? null : await build({ entryPoints: [fileURLToPath(new URL('./usage-app-smoke-renderer.tsx', import.meta.url))], bundle: true,
+  format: 'esm', platform: 'browser', write: false, jsx: 'automatic', define: { 'process.env.NODE_ENV': '"production"' } });
+const js = bundle?.outputFiles[0]!.contents;
+const installed = (await registry.getInstalledApp(usage.id))!;
+const hostEnvelope = {
+  app: { name: 'cats-platform', stage: 'phase-2-shell', runtimeBoundary: 'cats-runtime' },
+  products: [], installedApps: [toPlatformInstalledAppDescriptor(installed)],
+  desktop: { startAtLogin: false, openWindowOnStartup: true, systemTrayEnabled: true,
+    mobilePairing: { enabled: false, transport: 'tailscale', installId: null, displayName: null } },
+  language: { uiLanguagePreference: 'zh-TW' },
+  lobby: { animationMode: 'reduced', cats: [] },
+  runtime: { baseUrl: 'http://127.0.0.1', reachable: true, status: 'ok', service: 'cats-runtime' },
+  runtimeSetup: { source: 'runtime', bootstrapRequired: false, status: 'ready', stateStatus: 'ready', summary: 'Ready',
+    scannedAt: null, lastManualScanAt: null, appliedAt: null, providerCount: 0, availableCount: 0,
+    providersReadyToApply: [], providersNeedingAttention: [], suggestedProviders: [], canRunManualScan: true, canApply: false, error: null },
+  metadata: { generatedAt: new Date().toISOString(), host: '127.0.0.1', port: 0 },
+  bootstrapAttemptId: null, scopeId: 'isolated-usage-smoke', setupCompleteAt: new Date().toISOString(),
+  ownerDisplayName: 'Test', ownerAvatarColor: null, ownerAvatarUrl: null, lastProductSurface: null, guideCat: null,
+};
+let offline = false; let epoch = 'fixture-epoch'; let stale = false; let reads = 0;
+const queries: string[] = [];
+const timestamp = () => new Date().toISOString();
+const totals = (totalTokens: number | null, currency = 'USD') => ({ observations: totalTokens === null ? 0 : 1,
+  inputTokens: totalTokens === null ? null : Math.floor(totalTokens * 0.8), outputTokens: totalTokens === null ? null : Math.ceil(totalTokens * 0.2),
+  totalTokens, costs: totalTokens === null ? [] : [{ currency, amount: 0.12, observations: 1 }],
+  confidence: { reported: totalTokens === null ? 0 : 1, aggregated: 0, estimated: 0, unknown: 0 }, lastObservedAt: timestamp() });
+const runtimeClient = { async getUsageSnapshot() {
+  reads++; if (offline) throw new Error('Fixture offline');
+  const observedAt = new Date(Date.now() - (stale ? 600_000 : 30_000)).toISOString();
+  const resetsAt = new Date(Date.now() + (stale ? -60_000 : 3_600_000)).toISOString();
+  const targets = ['claude', 'codex', 'copilot', 'antigravity', 'kiro'].map((provider, index) => {
+    const queried = queries.includes(provider);
+    const source = queried ? { claude: 'claude.get_usage', codex: 'codex.account/rateLimits/read',
+      copilot: 'copilot.account.getQuota', antigravity: 'antigravity.usage' }[provider]
+      : index === 0 ? 'claude.rate_limit_event' : index === 1 ? 'codex.account/rateLimits/updated' : null;
+    const windows = queried && provider === 'copilot' ? [
+      { id: 'premium_interactions', unit: 'requests', used: 0, limit: 1500, remaining: 1500, usedPercent: 0, resetsAt },
+      { id: 'chat', unit: 'requests', used: 0, unlimited: true, resetsAt },
+    ] : queried ? [{ id: provider === 'antigravity' ? 'gemini_models_weekly' : 'seven_day', unit: 'percent',
+      usedPercent: provider === 'claude' ? 6 : 22, windowMinutes: 10080, resetsAt }]
+      : index < 2 ? [{ id: index ? 'primary' : 'five_hour', unit: 'percent', usedPercent: index ? 60 : 25, resetsAt, windowMinutes: 300 }] : [];
+    return { provider, instance: 'default', backend: 'cli', usage: totals(index >= 2 ? null : 12500 + index * 1000, index ? 'EUR' : 'USD'), guardrails: [],
+      quota: { status: index === 4 ? 'unsupported' : windows.length ? 'available' : 'unavailable', freshness: stale ? 'stale' : 'fresh',
+        source, observedAt: windows.length ? observedAt : null, accountId: null, accountLinkage: 'unverified',
+        automaticRefresh: false, refreshSupported: index < 4, windows } };
+  });
+  return { schemaVersion: 1, generatedAt: timestamp(), runtime: { status: 'available', epoch },
+    coverage: { mode: 'memory', scope: 'runtime_observed_results', startedAt: observedAt, retainedRecords: 2, droppedRecords: 0, droppedQuotaTargets: 0, truncated: false, historyAvailable: false },
+    totals: { ...totals(26000), costs: [{ currency: 'USD', amount: 0.12 }, { currency: 'EUR', amount: 0.12 }] }, targets,
+    sessions: targets.slice(0, 2).map((target, index) => ({ ...target, sessionId: `fixture-session-${index + 1}` })), incidents: [], guardrails: [] };
+}, async refreshUsageQuota(target: { provider: string; instance: string }) {
+  assert.equal(target.instance, 'default'); assert.ok(['codex', 'copilot', 'claude', 'antigravity'].includes(target.provider));
+  queries.push(target.provider);
+  return { status: 'updated', nextRefreshAt: null, snapshot: await this.getUsageSnapshot() };
+} };
+const sessionSecret = 'isolated-usage-smoke-session-secret';
+const auth = await createFirstAdminLocalAuthState({ state: createEmptyPlatformAuthState(), displayName: 'Test',
+  identifier: 'test@example.test', password: 'isolated-fixture-password', sessionSecret, sessionTtlMs: 600_000 });
+const core = createDefaultCoreState(); core.setupCompleteAt = new Date().toISOString();
+const dependencies = { shared: {
+  config: loadConfig({ CATS_HOME_DIR: root, CATS_PLATFORM_DIR: root, CATS_CHAT_STATE_PATH: chatStatePath,
+    CATS_AUTH_SESSION_SECRET: sessionSecret }),
+  coreStore: new MemoryCoreStore(core), authStore: new MemoryPlatformAuthStore(auth.state),
+  runtimeClient: { getUsageSnapshot: async () => projectUsageSnapshot(await runtimeClient.getUsageSnapshot()),
+    refreshUsageQuota: async (target: { provider: string; instance: string }) => projectUsageQuotaRefresh(await runtimeClient.refreshUsageQuota(target)) },
+}, chat: {}, work: {}, code: {} } as unknown as ResolvedServerDependencies;
+// Use the same temp path as the package installer regardless of config environment aliases.
+dependencies.shared.config.chatStatePath = chatStatePath;
+const server = createServer(async (request, response) => {
+  try {
+    const url = new URL(request.url ?? '/', 'http://127.0.0.1');
+    if (rendererRoot && url.pathname === '/api/app-shell') {
+      response.writeHead(200, { 'content-type': 'application/json' }); response.end(JSON.stringify(hostEnvelope)); return;
+    }
+    if (url.pathname === '/smoke.js') { response.writeHead(200, { 'content-type': 'text/javascript' }); response.end(js); return; }
+    if (url.pathname.startsWith('/api/')) {
+      if (url.pathname.startsWith('/api/apps/') || url.pathname === '/api/auth/status') { await routeRequest(request, response, dependencies); return; }
+      response.writeHead(404); response.end(); return;
+    }
+    if (rendererRoot) {
+      const asset = url.pathname.startsWith('/assets/') ? url.pathname.slice(1) : 'index.html';
+      const assetPath = path.resolve(rendererRoot, asset);
+      if (!assetPath.startsWith(`${rendererRoot}${path.sep}`)) { response.writeHead(404); response.end(); return; }
+      const contentType = asset.endsWith('.js') ? 'text/javascript' : asset.endsWith('.css') ? 'text/css' : 'text/html';
+      response.writeHead(200, { 'content-type': contentType, 'cache-control': 'no-store' });
+      response.end(await readFile(assetPath)); return;
+    }
+    response.writeHead(200, { 'content-type': 'text/html', 'cache-control': 'no-store' });
+    response.end('<!doctype html><html><head><meta name="viewport" content="width=device-width, initial-scale=1"></head><body style="margin:0;background:#f4f5f2"><div id="root"></div><script type="module" src="/smoke.js"></script></body></html>');
+  } catch { response.writeHead(500); response.end('Fixture failure'); }
+});
+await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+const address = server.address();
+if (!address || typeof address === 'string') throw new Error('No fixture port');
+const { chromium, _electron } = await import(pathToFileURL(process.env.CATS_TEST_PLAYWRIGHT_MODULE).href);
+const electronMode = args.includes('--electron');
+await mkdir(path.join(root, 'electron-profile'), { recursive: true });
+const browser = electronMode
+  ? await _electron.launch({ executablePath: process.env.CATS_TEST_BROWSER_EXECUTABLE,
+    env: { ...process.env, CATS_USAGE_SMOKE_PROFILE_DIR: path.join(root, 'electron-profile') },
+    args: [fileURLToPath(new URL('./usage-app-smoke-electron.cjs', import.meta.url))] })
+  : await chromium.launch({ executablePath: process.env.CATS_TEST_BROWSER_EXECUTABLE, headless: true });
+try {
+  const page = electronMode ? await browser.firstWindow()
+    : await browser.newPage({ viewport: { width: 1440, height: 1200 }, locale: 'zh-TW' });
+  await page.context().addCookies([{ name: 'cats_session', value: auth.session.token, url: `http://127.0.0.1:${address.port}` }]);
+  const errors: string[] = []; page.on('pageerror', (error: Error) => errors.push(error.message));
+  await page.goto(`http://127.0.0.1:${address.port}${entryPath}`);
+  const frame = page.frameLocator('iframe[title="Usage"]');
+  try { await frame.getByText('75% 剩餘', { exact: true }).waitFor({ timeout: 15_000 }); }
+  catch (error) {
+    process.stderr.write(`${JSON.stringify({ errors, body: await page.locator('body').innerText(), secure: await page.evaluate(() => isSecureContext) })}\n`);
+    throw error;
+  }
+  assert.equal(await page.locator('iframe').getAttribute('sandbox'), 'allow-scripts');
+  process.stdout.write('Usage iframe rendered and received the fixture snapshot.\n');
+  assert.equal(await frame.getByText('尚未支援', { exact: true }).count(), 1);
+  assert.equal(queries.length, 0, 'Opening the App never queries a CLI');
+  assert.equal(await frame.locator('[data-query-provider="kiro"]').count(), 0);
+  for (const provider of ['copilot', 'claude', 'antigravity']) {
+    await new Promise((resolve) => setTimeout(resolve, 1100));
+    await frame.locator(`[data-query-provider="${provider}"]`).click();
+    try { await frame.getByText(/已透過 .* CLI 取得額度回報/).first().waitFor({ timeout: 5000 }); }
+    catch (error) {
+      process.stderr.write(`${JSON.stringify({ queries, provider, body: await page.locator('body').innerText(),
+        frame: await frame.locator('body').innerText({ timeout: 1000 }).catch(() => 'Frame unavailable'), errors })}\n`);
+      throw error;
+    }
+    const expected = provider === 'copilot' ? /1,500 requests/ : provider === 'claude' ? /^94% 剩餘$/ : /^78% 剩餘$/;
+    await frame.getByText(expected).first().waitFor();
+  }
+  assert.deepEqual(queries, ['copilot', 'claude', 'antigravity']);
+  await frame.getByText('不限額', { exact: true }).waitFor();
+  assert.equal(await frame.locator('.stat .cost').innerText(), 'USD 0.12\nEUR 0.12');
+  const innerFrame = page.frames().find((candidate: { parentFrame(): unknown }) => candidate.parentFrame() !== null);
+  assert.ok(innerFrame);
+  await innerFrame.evaluate(() => new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve))));
+  const frameBounds = await page.locator('iframe').boundingBox();
+  assert.ok(frameBounds && frameBounds.width >= 800 && frameBounds.height >= 520, 'Dashboard has a usable desktop viewport');
+  const screenshotDir = path.resolve('build', 'usage-smoke'); await mkdir(screenshotDir, { recursive: true });
+  if (!electronMode) {
+    // Viewport/frame captures keep the opaque iframe's paint surface intact.
+    // Chromium full-page resizing can mispaint that surface even with correct DOM bounds.
+    await page.screenshot({ path: path.join(screenshotDir, 'usage-desktop.png') });
+    await page.locator('iframe').screenshot({ path: path.join(screenshotDir, 'usage-frame.png') });
+  }
+  await frame.locator('#provider').selectOption('copilot');
+  assert.equal(await frame.locator('.stat').first().locator('strong').innerText(), '—');
+  await frame.locator('#provider').selectOption('claude');
+  assert.equal(await frame.locator('.provider').count(), 1);
+  assert.equal(await frame.locator('tbody tr').count(), 1);
+  await frame.locator('#provider').selectOption('');
+  const refresh = async () => {
+    // The real host deliberately permits at most one UI request per second.
+    await new Promise((resolve) => setTimeout(resolve, 1100));
+    const before = reads;
+    await frame.getByRole('button', { name: '重新整理', exact: true }).click();
+    await page.waitForFunction(() => document.querySelector('iframe') !== null);
+    for (let attempt = 0; reads === before && attempt < 30; attempt++) await new Promise((resolve) => setTimeout(resolve, 50));
+    assert.ok(reads > before, 'Refresh reached the real host route');
+  };
+  offline = true; await refresh();
+  await frame.getByText('Runtime 無法連線 · 以下保留最後快照', { exact: true }).waitFor();
+  assert.equal(await frame.getByText('94% 剩餘', { exact: true }).count(), 1);
+  offline = false; stale = true; await refresh();
+  await frame.getByText('已過回報的重設時間；目前沒有可靠的未來重設時間', { exact: true }).first().waitFor();
+  assert.equal(await frame.getByText('94% 剩餘', { exact: true }).count(), 1);
+  epoch = 'fixture-restarted'; await refresh();
+  await frame.getByText('Runtime 已重新啟動，本次用量觀測區間已重設。', { exact: true }).waitFor();
+  await page.setViewportSize({ width: 390, height: 844 });
+  if (!electronMode) await page.screenshot({ path: path.join(screenshotDir, 'usage-mobile.png'), fullPage: true });
+  assert.equal(await innerFrame.evaluate(() => document.documentElement.scrollWidth <= window.innerWidth), true);
+  assert.equal(await innerFrame.evaluate(() => { try { return !!parent.document.body; } catch { return false; } }), false);
+  assert.equal(await innerFrame.evaluate(async () => { try { await fetch('/api/apps'); return true; } catch { return false; } }), false);
+  await registry.updateAppState('cats.usage', { installState: 'disabled' });
+  await new Promise((resolve) => setTimeout(resolve, 1100));
+  await frame.getByRole('button', { name: '重新整理', exact: true }).click();
+  await page.getByRole('alert').waitFor();
+  assert.equal(await page.locator('iframe').count(), 0);
+  await registry.updateAppState('cats.usage', { installState: 'enabled' });
+  offline = false; stale = false;
+  if (rendererRoot) {
+    await page.getByRole('button', { name: '返回大廳', exact: true }).click();
+    await page.getByRole('button', { name: /Usage/ }).click();
+    await page.frameLocator('iframe[title="Usage"]').getByText('94% 剩餘', { exact: true }).waitFor();
+  }
+  if (args.includes('--check-loading-recovery')) {
+    await page.clock.install();
+    const rendererPattern = '**/api/apps/cats.usage/renderer?*';
+    let releaseRequest!: () => void;
+    await page.route(rendererPattern, async (route: any) => {
+      await new Promise<void>((resolve) => { releaseRequest = resolve; });
+      await route.abort().catch(() => {}); // The host timeout may already have aborted it.
+    });
+    await page.goto(`http://127.0.0.1:${address.port}${entryPath}`);
+    await page.getByRole('status').filter({ hasText: '載入 Usage' }).waitFor();
+    await page.clock.fastForward(15_001);
+    await page.getByRole('alert').filter({ hasText: '載入逾時' }).waitFor();
+    await page.screenshot({ path: path.join(screenshotDir, 'usage-loading-timeout.png') });
+    await page.unroute(rendererPattern);
+    releaseRequest();
+    await page.getByRole('button', { name: '重新載入', exact: true }).click();
+    await page.frameLocator('iframe[title="Usage"]').getByText('94% 剩餘', { exact: true }).waitFor();
+    await page.route(rendererPattern, async (route: any) => {
+      const response = await route.fetch();
+      await route.fulfill({ response, json: { ...await response.json(), sdk: '' } });
+    });
+    await page.goto(`http://127.0.0.1:${address.port}${entryPath}`);
+    await page.locator('iframe[title="Usage"]').waitFor();
+    await page.clock.fastForward(15_001);
+    await page.getByRole('alert').filter({ hasText: '載入逾時' }).waitFor();
+    assert.equal(await page.locator('iframe').count(), 0);
+    await page.unroute(rendererPattern);
+    await page.getByRole('button', { name: '重新載入', exact: true }).click();
+    await page.frameLocator('iframe[title="Usage"]').getByText('94% 剩餘', { exact: true }).waitFor();
+  }
+  assert.deepEqual(errors, []);
+  process.stdout.write(`${JSON.stringify({ ok: true, reads, queries, rendererRoot, electronMode, loadingRecovery: args.includes('--check-loading-recovery'),
+    app: { id: usage.id, version: usage.version, sha256: usage.sha256 }, screenshotDir: electronMode ? null : screenshotDir, isolatedRegistry: root }, null, 2)}\n`);
+} finally {
+  await browser.close();
+  await new Promise<void>((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+}

package/scripts/testing/usage-app-smoke-electron.cjs

@@ -0,0 +1,10 @@
+// Isolated Electron fixture: no Desktop supervisor, user profile, or live services.
+const { app, BrowserWindow } = require('electron');
+app.setPath('userData', process.env.CATS_USAGE_SMOKE_PROFILE_DIR);
+app.whenReady().then(async () => {
+  globalThis.testWindow = new BrowserWindow({ width: 1440, height: 1200, show: false,
+    webPreferences: { contextIsolation: true, nodeIntegration: false, sandbox: true, backgroundThrottling: false },
+  });
+  await globalThis.testWindow.loadURL('about:blank');
+});
+app.on('window-all-closed', () => app.quit());

package/scripts/testing/usage-app-smoke-renderer.tsx

@@ -0,0 +1,8 @@
+import { createRoot } from 'react-dom/client';
+import { AppRendererSurface } from '../../src/app/renderer/AppRendererSurface.js';
+import { installCsrfFetch } from '../../src/app/renderer/csrfFetch.js';
+
+installCsrfFetch();
+createRoot(document.getElementById('root')!).render(<AppRendererSurface appId="cats.usage" version={new URLSearchParams(location.search).get('appVersion') ?? ''}
+  title="Usage" locale={new URLSearchParams(location.search).get('locale') ?? 'zh-TW'}
+  onLobby={() => { document.body.textContent = 'Returned to lobby'; }} />);

package/scripts/verify-desktop-app-bundle.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+// Verify the actual unpacked installer resources and offline App activation.
+// Usage: node scripts/verify-desktop-app-bundle.mjs --release-root release --expect-lock config/desktop-apps.lock.json
+// Alternatively pass --resources <resources-directory>. Uses only a temporary registry;
+// does not start provider CLIs, download Apps, or touch the user's installed state.
+import assert from 'node:assert/strict';
+import { access, mkdtemp, readFile, readdir, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { createRequire } from 'node:module';
+import { resolveDesktopHostConfig } from '../build/desktop/config.js';
+import { buildManagedServiceSpecs } from '../build/desktop/processSupervisor.js';
+import { installBundledApps } from '../build/server/platform/apps/packageInstaller.js';
+import { FileCatsAppRegistry } from '../build/server/platform/apps/registry.js';
+import { readAppRenderer } from '../build/server/platform/apps/renderer.js';
+
+const pins = (apps) => apps.map(({ id, version, sha256 }) => ({ id, version, sha256 }));
+
+export async function verifyDesktopAppBundle(resourcesRoot, expectedLockPath) {
+  const root = await mkdtemp(path.join(tmpdir(), 'cats-packaged-app-check-'));
+  try {
+    const config = resolveDesktopHostConfig({
+      env: {}, packaged: true, resourcesPath: path.resolve(resourcesRoot),
+      userDataDir: path.join(root, 'desktop'), catsHomeDir: path.join(root, 'cats-home'),
+    });
+    const [, platform] = buildManagedServiceSpecs(config, {}, process.platform);
+    const sdk = await import(pathToFileURL(path.join(config.packageRoot, 'packages/app-sdk/package.js')).href);
+    const expected = sdk.parseAppLock(JSON.parse(await readFile(expectedLockPath, 'utf8')));
+    const bundledLock = platform.env.CATS_APP_BUNDLE_PATH;
+    assert.equal(bundledLock, path.join(config.packageRoot, 'official-apps/bundle.lock.json'));
+    assert.equal(config.paths.platformBundledConfigDir, path.join(config.packageRoot, 'config'));
+    await access(config.paths.appEntryScript);
+    await access(path.join(config.paths.platformBundledConfigDir, 'provider-capability-bootstrap.yaml.example'));
+    const bundled = sdk.parseAppLock(JSON.parse(await readFile(bundledLock, 'utf8')));
+    const plan = JSON.parse(await readFile(path.join(resourcesRoot, 'desktop-package-plan.json'), 'utf8'));
+    assert.deepEqual(pins(bundled.apps), pins(expected.apps), 'Installer must contain the selected exact App set');
+    assert.deepEqual(pins(plan.apps ?? []), pins(expected.apps), 'Packaging plan must retain the selected App set');
+    if (expected.apps.length > 0) {
+      assert.equal(createRequire(pathToFileURL(config.paths.appEntryScript)).resolve('#cats-app-package'),
+        path.join(config.packageRoot, 'packages/app-sdk/package.js'), 'Sidecar SDK alias must resolve to its shipped package');
+      if (plan.sidecarLayout?.app === 'bundle') {
+        const entry = await readFile(config.paths.appEntryScript, 'utf8');
+        assert.match(entry, /\bfrom\s+['"]#cats-app-package['"]/u,
+          'Bundled sidecar must retain the SDK package import; inlining relocates browser.js');
+      }
+    }
+    assert.ok((await sdk.readBrowserSdk()).includes('getSnapshot'), 'Shipped browser SDK must be readable');
+    for (const app of bundled.apps) {
+      assert.equal(app.artifact, `${app.id}-${app.version}.catsapp`, 'Startup must use adjacent offline archives');
+      sdk.decodeAppPackage(await readFile(path.join(path.dirname(bundledLock), app.artifact)), app);
+    }
+    // Exercise the same installer invoked before the Platform HTTP server starts.
+    // These compiled modules come from this build; bytes and SDK above come from
+    // the actual installer resources, including bundled-sidecar builds.
+    await installBundledApps(config.paths.appStatePath, bundledLock);
+    await installBundledApps(config.paths.appStatePath, bundledLock);
+    const registry = new FileCatsAppRegistry({ registryPath: path.join(config.paths.platformDir, 'apps/registry.json') });
+    const installed = await registry.listInstalledApps();
+    assert.equal(installed.length, expected.apps.length);
+    for (const app of installed) {
+      assert.equal(app.enabled, true);
+      assert.equal(app.installState, 'enabled');
+      assert.equal(app.packageSource, 'desktop-bundle');
+      assert.ok(app.manifest.contributions.lobbyApps.length > 0);
+      assert.ok((await readAppRenderer(app)).html.includes('<head>'));
+    }
+    return { resources: path.resolve(resourcesRoot), apps: pins(bundled.apps), offlineActivation: true };
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+}
+
+async function findResources(directory, depth = 0) {
+  try {
+    await access(path.join(directory, 'desktop-package-plan.json'));
+    return [directory];
+  } catch { /* Look only through unpacked distribution directories below. */ }
+  if (depth >= 6) return [];
+  const entries = await readdir(directory, { withFileTypes: true });
+  const nested = await Promise.all(entries.filter((entry) => entry.isDirectory()
+    && !['node_modules', 'app-sidecar', 'cats-runtime'].includes(entry.name))
+    .map((entry) => findResources(path.join(directory, entry.name), depth + 1)));
+  return nested.flat();
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.includes('--help')) {
+    console.log('Usage: verify-desktop-app-bundle.mjs (--release-root <directory> | --resources <directory>) --expect-lock <lock>');
+    return;
+  }
+  const options = {};
+  for (let index = 0; index < args.length; index += 2) {
+    if (!['--resources', '--release-root', '--expect-lock'].includes(args[index])
+      || !args[index + 1] || args[index + 1].startsWith('--')) throw new Error('Invalid verifier arguments. Use --help.');
+    options[args[index]] = path.resolve(args[index + 1]);
+  }
+  assert.ok(options['--expect-lock'], '--expect-lock is required');
+  assert.ok(Boolean(options['--resources']) !== Boolean(options['--release-root']), 'Select resources or release-root');
+  const roots = options['--resources'] ? [options['--resources']] : await findResources(options['--release-root']);
+  assert.ok(roots.length > 0, 'No unpacked installer resources found');
+  for (const resources of roots) console.log(JSON.stringify(await verifyDesktopAppBundle(resources, options['--expect-lock']), null, 2));
+}
+
+if (path.resolve(process.argv[1] ?? '') === fileURLToPath(import.meta.url)) {
+  main().catch((error) => { console.error(error); process.exitCode = 1; });
+}

package/scripts/windows/Build-DesktopPackage.ps1

@@ -13,6 +13,9 @@
 .PARAMETER OutputDir
     Optional override for the packaging output directory.
 
+.PARAMETER AppsLock
+    App selection lock with exact IDs, versions and SHA-256 hashes.
+
 .EXAMPLE
     .\scripts\windows\Build-DesktopPackage.ps1 -Platform windows
     Build the staged Windows packaging outputs.
@@ -20,7 +23,8 @@
 param(
   [ValidateSet('all', 'windows', 'macos', 'linux')]
   [string]$Platform = 'all',
-  [string]$OutputDir = ''
+  [string]$OutputDir = '',
+  [string]$AppsLock = ''
 )
 
 Set-StrictMode -Version Latest
@@ -34,11 +38,10 @@ try {
   if ($LASTEXITCODE -ne 0) {
     throw "npm run build failed with exit code $LASTEXITCODE"
   }
-  if ($OutputDir) {
-    node .\scripts\package-desktop.mjs --platform $Platform --output-dir $OutputDir
-  } else {
-    node .\scripts\package-desktop.mjs --platform $Platform
-  }
+  $packageArguments = @('.\scripts\package-desktop.mjs', '--platform', $Platform)
+  if ($OutputDir) { $packageArguments += @('--output-dir', $OutputDir) }
+  if ($AppsLock) { $packageArguments += @('--apps-lock', $AppsLock) }
+  node @packageArguments
   if ($LASTEXITCODE -ne 0) {
     throw "desktop packaging failed with exit code $LASTEXITCODE"
   }