@cats-inc/cats-platform 0.1.10 → 0.2.8

package/scripts/macos/provider-cli-common.sh

@@ -52,7 +52,7 @@ provider_display_name() {
     antigravity) printf '%s\n' 'Antigravity CLI' ;;
     grok) printf '%s\n' 'Grok CLI' ;;
     devin) printf '%s\n' 'Devin CLI' ;;
-    aider) printf '%s\n' 'Aider' ;;
+    muse) printf '%s\n' 'Meta Muse CLI' ;;
     claude) printf '%s\n' 'Claude Code CLI' ;;
     cursor) printf '%s\n' 'Cursor Agent CLI' ;;
     goose) printf '%s\n' 'Goose CLI' ;;
@@ -67,7 +67,7 @@ provider_primary_command() {
     antigravity) printf '%s\n' 'agy' ;;
     grok) printf '%s\n' 'grok' ;;
     devin) printf '%s\n' 'devin' ;;
-    aider) printf '%s\n' 'aider' ;;
+    muse) printf '%s\n' 'muse' ;;
     claude) printf '%s\n' 'claude' ;;
     cursor) printf '%s\n' 'cursor-agent' ;;
     goose) printf '%s\n' 'goose' ;;
@@ -98,7 +98,7 @@ provider_install_url() {
     antigravity) printf '%s\n' 'https://antigravity.google/cli/install.sh' ;;
     grok) printf '%s\n' 'https://x.ai/cli/install.sh' ;;
     devin) printf '%s\n' 'https://cli.devin.ai/install.sh' ;;
-    aider) printf '%s\n' 'https://aider.chat/install.sh' ;;
+    muse) printf '%s\n' 'https://dev.meta.ai/install.sh' ;;
     claude) printf '%s\n' 'https://claude.ai/install.sh' ;;
     cursor) printf '%s\n' 'https://cursor.com/install' ;;
     goose) printf '%s\n' 'https://github.com/block/goose/releases/download/stable/download_cli.sh' ;;
@@ -111,6 +111,7 @@ provider_install_url() {
 provider_install_dir() {
   case "$1" in
     grok) printf '%s\n' "$HOME/.grok/bin" ;;
+    muse) muse_install_dir ;;
     *) printf '%s\n' "$HOME/.local/bin" ;;
   esac
 }
@@ -249,12 +250,59 @@ ensure_provider_alias() {
   fi
 }
 
+# muse's install directory holds the launcher, its state files, and one
+# muse-bin-<version> build per version it has downloaded.
+muse_install_dir() {
+  printf '%s\n' "${MUSE_INSTALL_DIR:-$HOME/.local/bin}"
+}
+
+# The version comes from the launcher's own state file, never from running muse.
+# The launcher forwards every argument straight to the agent binary, so a flag
+# that binary does not recognise opens the interactive TUI and hangs an
+# unattended setup run forever.
+muse_installed_version() {
+  local version_file
+  version_file="$(muse_install_dir)/.muse-version"
+  if [ -r "$version_file" ]; then
+    tr -d '\r\n' < "$version_file"
+  fi
+}
+
+# "Installed" means the launcher actually fetched a build. The official
+# installer writes the launcher first and downloads muse-bin-<version> last, so
+# a run that dies in between leaves a launcher with nothing behind it. Treating
+# that as installed would skip the reinstall that repairs it.
+muse_install_complete() {
+  local dir version
+  dir="$(muse_install_dir)"
+  [ -x "$dir/muse" ] || return 1
+  version="$(muse_installed_version)"
+  [ -n "$version" ] || return 1
+  [ -x "$dir/muse-bin-$version" ]
+}
+
 detect_provider_command() {
   local platform="$1"
   local provider="$2"
   local primary_command
   local candidate
 
+  if [ "$provider" = 'muse' ]; then
+    if muse_install_complete; then
+      prepend_path_if_missing "$(muse_install_dir)"
+      printf '%s\n' "$(muse_install_dir)/muse"
+      return 0
+    fi
+    # A muse elsewhere on PATH is someone's own install; report it rather than
+    # claiming the tool is missing, but never treat a half-written install
+    # directory as one.
+    if [ -x "$(muse_install_dir)/muse" ]; then
+      return 1
+    fi
+    command -v muse 2>/dev/null && return 0
+    return 1
+  fi
+
   primary_command="$(provider_primary_command "$provider")"
   if command -v "$primary_command" >/dev/null 2>&1; then
     command -v "$primary_command"
@@ -276,9 +324,36 @@ EOF
 
 provider_version_line() {
   local command_path="$1"
+  local provider="${2:-}"
+
+  # muse is read, never run: see muse_installed_version.
+  if [ "$provider" = 'muse' ]; then
+    muse_installed_version
+    return 0
+  fi
+
   "$command_path" --version 2>&1 | head -1 || true
 }
 
+# `curl ... | bash` returns 0 when the download itself fails, because bash reads
+# empty input and succeeds. Staging the script first is what makes a failed
+# install report as a failure.
+run_downloaded_shell_installer() {
+  local url="$1"
+  local installer_path status=0
+
+  installer_path="$(mktemp)"
+  if ! curl -fsSL "$url" -o "$installer_path"; then
+    rm -f "$installer_path"
+    printf 'Failed to download the installer from %s\n' "$url" >&2
+    return 1
+  fi
+
+  bash "$installer_path" < /dev/null || status=$?
+  rm -f "$installer_path"
+  return "$status"
+}
+
 # Devin's official install.sh ends by launching the interactive `devin setup`
 # wizard. Packaged setup runs non-interactively with no console a prompt can
 # reach, so an unstripped installer would stall the step rather than fail.
@@ -342,8 +417,10 @@ run_remote_pipe_installer() {
     goose)
       curl -fsSL "$url" | env CONFIGURE=false bash
       ;;
-    aider)
-      curl -LsSf "$url" | sh
+    muse)
+      # Download first, then run: with `curl ... | bash` a failed download still
+      # exits 0, because bash reads empty input and succeeds.
+      run_downloaded_shell_installer "$url"
       ;;
     cursor)
       curl "$url" -fsSL | bash
@@ -424,7 +501,9 @@ run_provider_install_action() {
     devin)
       run_devin_installer
       ;;
-    aider)
+    muse)
+      # The official installer always refreshes the launcher and asks it to pull
+      # the newest build, so install, upgrade, and force are the same call.
       run_remote_pipe_installer "$provider"
       ;;
     claude)
@@ -559,28 +638,22 @@ UPNP_EOF
     esac
   fi
 
-  # ~/.local/bin/aider is a uv tool shim, not the tool. Removing only the shim
-  # leaves aider-chat installed in the uv tool environment and the shim
-  # regenerable by any later `uv tool` command, so the tool is uninstalled
-  # through uv first and path removal only mops up what uv left behind.
-  #
-  # The uv binary itself is deliberately left in place: Aider's installer drops
-  # its own uv into ~/.local/bin, users commonly have another, and the helper
-  # cannot tell them apart. Removing a uv the user installed separately is a
-  # destructive false positive, so this warns instead (SPEC-112 PD4).
-  if [ "$provider" = 'aider' ]; then
-    if command -v uv >/dev/null 2>&1; then
-      if [ "$dry_run" = 'true' ]; then
-        __CATS_UNINSTALL_PLANNED+=("uv_tool_uninstall:aider-chat")
-      elif uv tool uninstall aider-chat >/dev/null 2>&1; then
-        __CATS_UNINSTALL_APPLIED+=("uv_tool_uninstalled:aider-chat")
-      else
-        __CATS_UNINSTALL_WARNINGS+=("uv_tool_uninstall_failed:aider-chat")
-      fi
-    else
-      __CATS_UNINSTALL_WARNINGS+=("uv_missing_aider_chat_may_remain")
-    fi
-    __CATS_UNINSTALL_WARNINGS+=("bundled_uv_left_in_place_provenance_unknown")
+  # The muse launcher is not the tool either: every muse-bin-<version> build it
+  # has downloaded, plus its .muse-* state files, sit in the same directory and
+  # survive removing the launcher alone. They are named deterministically, so
+  # they can be removed without guessing at unrelated files in ~/.local/bin.
+  if [ "$provider" = 'muse' ]; then
+    local muse_dir muse_leftover
+    muse_dir="$(muse_install_dir)"
+    for muse_leftover in "$muse_dir"/muse-bin-* "$muse_dir"/.muse-*; do
+      case "$muse_leftover" in
+        "$HOME"/*)
+          if [ -e "$muse_leftover" ] || [ -L "$muse_leftover" ]; then
+            planned_paths+=("$muse_leftover")
+          fi
+          ;;
+      esac
+    done
   fi
 
   for path in "${planned_paths[@]}"; do
@@ -796,7 +869,7 @@ run_native_provider_installer() {
 
   if command_path="$(detect_provider_command "$platform" "$provider")"; then
     initial_installed='true'
-    detected_version="$(provider_version_line "$command_path")"
+    detected_version="$(provider_version_line "$command_path" "$provider")"
     if [ "$check_only" = 'true' ]; then
       if [ "$emit_json" = 'true' ]; then
         printf '{'
@@ -928,7 +1001,7 @@ run_native_provider_installer() {
 
   while [ $attempt -le 3 ]; do
     if command_path="$(detect_provider_command "$platform" "$provider")"; then
-      detected_version="$(provider_version_line "$command_path")"
+      detected_version="$(provider_version_line "$command_path" "$provider")"
       if [ "$emit_json" = 'true' ]; then
         warnings=("Reload your shell if ${display_name} is not visible yet: source ${shell_rc}")
         printf '{'

package/scripts/macos/sync-agent-skills.sh

@@ -76,11 +76,33 @@ if [[ -n "$agent" ]]; then
 fi
 
 skill_dirs=()
-for entry in "$skills_dir"/*; do
-  [[ -d "$entry" ]] || continue
-  [[ -f "$entry/SKILL.md" ]] || continue
-  skill_dirs+=("$entry")
-done
+discover_skills() {
+  local entry skill_name existing existing_name
+  for entry in "$1"/*; do
+    [[ -d "$entry" ]] || continue
+    [[ "$entry" != *.bootstrap ]] || continue
+    if [[ -L "$entry" ]]; then
+      echo "Linked skill directories are not supported: $entry" >&2
+      exit 1
+    fi
+    if [[ -f "$entry/SKILL.md" ]]; then
+      skill_name="$(basename "$entry" | tr '[:upper:]' '[:lower:]')"
+      # macOS Bash 3.2 treats an empty array as unset under nounset.
+      for existing in ${skill_dirs[@]+"${skill_dirs[@]}"}; do
+        existing_name="$(basename "$existing" | tr '[:upper:]' '[:lower:]')"
+        if [[ "$skill_name" == "$existing_name" ]]; then
+          echo "Duplicate skill '$skill_name': $existing and $entry" >&2
+          exit 1
+        fi
+      done
+      skill_dirs+=("$entry")
+      # Resources inside this package are copied intact, never discovered again.
+    else
+      discover_skills "$entry"
+    fi
+  done
+}
+discover_skills "$skills_dir"
 
 if [[ ${#skill_dirs[@]} -eq 0 ]]; then
   echo "No skills found in $skills_dir (no directories with SKILL.md)" >&2

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()));
+}