@cats-inc/cats-platform 0.2.8 → 0.3.4

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

@@ -0,0 +1,247 @@
+#!/usr/bin/env bash
+# Source this file for passive native version comparison and bounded vendor queries.
+# Usage: source provider-version-common.sh; cats_native_latest_version <provider>
+# Adapted from environment-bootstrap shared/posix/upstream-version.sh at 752dc13.
+# Queries return an empty value on failure; check-only mode never invokes them.
+cats_version_token() {
+    printf '%s' "$1" | tr -d '\r' | grep -oE '[0-9]+(\.[0-9]+)+(-[0-9A-Za-z]+(\.[0-9A-Za-z]+)*|\.[A-Za-z][0-9A-Za-z]*(\.[0-9]+)*)?' | head -n 1 || true
+}
+
+# cats_version_compare <a> <b>
+# 只比數字段、補滿四段：印 -1（a 較舊）、0、1（a 較新）；任一邊解析不出版本印空字串。
+# 空字串要當成「無法比較、交回原本流程」，不能當成落後，否則查不到版本時每次都會重裝。
+cats_version_compare() {
+    local a b i x y
+    a="$(printf '%s' "$1" | tr -d '\r' | grep -oE '[0-9]+(\.[0-9]+)*' | head -n 1 || true)"
+    b="$(printf '%s' "$2" | tr -d '\r' | grep -oE '[0-9]+(\.[0-9]+)*' | head -n 1 || true)"
+    if [ -z "$a" ] || [ -z "$b" ]; then
+        printf ''
+        return 0
+    fi
+
+    i=1
+    while [ "$i" -le 4 ]; do
+        x="$(printf '%s' "$a" | awk -F. -v n="$i" '{print $n}')"
+        y="$(printf '%s' "$b" | awk -F. -v n="$i" '{print $n}')"
+        [ -n "$x" ] || x=0
+        [ -n "$y" ] || y=0
+        if [ "$((10#$x))" -lt "$((10#$y))" ]; then printf -- '-1'; return 0; fi
+        if [ "$((10#$x))" -gt "$((10#$y))" ]; then printf '1'; return 0; fi
+        i=$((i + 1))
+    done
+    printf '0'
+}
+
+# _cats_json_string_field <field> ：從 stdin 的 JSON 文字撈第一個 "field":"value" 的 value
+_cats_json_string_field() {
+    grep -oE "\"$1\"[[:space:]]*:[[:space:]]*\"[^\"]*\"" | head -n 1 | sed -E 's/.*"([^"]*)"$/\1/'
+}
+
+# cats_github_latest_release <owner/repo>
+# GitHub Releases 的最新穩定版 tag（去掉開頭的 v）；失敗印空。
+cats_github_latest_release() {
+    local json
+    json="$(curl -fsSL --connect-timeout 5 --max-time 20 -H 'Accept: application/vnd.github+json' "https://api.github.com/repos/$1/releases/latest" 2>/dev/null)" || return 0
+    printf '%s' "$json" | _cats_json_string_field tag_name | sed 's/^v//' || true
+}
+
+# cats_antigravity_latest_version [已下載的官方 install.sh]
+# 官方腳本讀的是 $DOWNLOAD_BASE_URL/manifests/<platform>.json 的 version。
+# 傳入抓下來的腳本可以順便從裡面撈 base URL，官方搬家時就不必改這裡；撈不到用寫死的。
+# platform 的算法照抄官方（darwin_arm64 / linux_amd64 / linux_amd64_musl …）。
+cats_antigravity_latest_version() {
+    local base='https://antigravity-cli-auto-updater-974169037036.us-central1.run.app'
+    local found os arch platform
+
+    if [ -n "${1:-}" ] && [ -r "$1" ]; then
+        found="$(grep -oE 'DOWNLOAD_BASE_URL="https://[^"]+"' "$1" | head -n 1 | sed -E 's/^DOWNLOAD_BASE_URL="(.*)"$/\1/')"
+        [ -n "$found" ] && base="$found"
+    fi
+
+    case "$(uname -s)" in
+        Darwin) os=darwin ;;
+        Linux)  os=linux ;;
+        *) return 0 ;;
+    esac
+    case "$(uname -m)" in
+        x86_64|amd64)  arch=amd64 ;;
+        arm64|aarch64) arch=arm64 ;;
+        *) return 0 ;;
+    esac
+    if [ "$os" = linux ] && { [ -f /lib/libc.musl-x86_64.so.1 ] || [ -f /lib/libc.musl-aarch64.so.1 ] || ldd /bin/ls 2>&1 | grep -q musl; }; then
+        platform="linux_${arch}_musl"
+    else
+        platform="${os}_${arch}"
+    fi
+
+    curl -fsSL --connect-timeout 5 --max-time 20 "$base/manifests/$platform.json" 2>/dev/null | _cats_json_string_field version || true
+}
+
+# cats_cursor_agent_latest_version <已下載的官方 install 腳本>
+# 官方 https://cursor.com/install 是支寫死版本的腳本，目錄名就是版本
+# （…/versions/2026.09.10-fd3934a）。版本是「日期-commit」，cats_version_compare 只比得到
+# 日期，同日不同 commit 由呼叫端用字串相等另判。
+cats_cursor_agent_latest_version() {
+    [ -n "${1:-}" ] && [ -r "$1" ] || return 0
+    grep -oE 'versions/[0-9]{4}\.[0-9]{2}\.[0-9]{2}-[0-9A-Za-z]+' "$1" | head -n 1 | sed 's#^versions/##' || true
+}
+
+# cats_junie_latest_build
+# 官方 install.sh 讀 GitHub raw 的 update-info.jsonl：一行一個 build，version 是 build 號
+# （3110.7，也是 versions/ 底下的目錄名）、marketing 才是 26.9.7、platform 是
+# linux-amd64 / macos-aarch64 這種。印本平台最大的 build 號；失敗印空。
+cats_junie_latest_build() {
+    local os arch platform jsonl line v best=''
+
+    case "$(uname -s)" in
+        Darwin) os=macos ;;
+        Linux)  os=linux ;;
+        *) return 0 ;;
+    esac
+    case "$(uname -m)" in
+        x86_64|amd64)  arch=amd64 ;;
+        arm64|aarch64) arch=aarch64 ;;
+        *) return 0 ;;
+    esac
+    platform="${os}-${arch}"
+
+    jsonl="$(curl -fsSL --connect-timeout 5 --max-time 20 'https://raw.githubusercontent.com/jetbrains-junie/junie/main/update-info.jsonl' 2>/dev/null)" || return 0
+
+    while IFS= read -r line; do
+        case "$line" in
+            *"\"platform\":\"$platform\""*) ;;
+            *) continue ;;
+        esac
+        v="$(printf '%s' "$line" | _cats_json_string_field version || true)"
+        [ -n "$v" ] || continue
+        if [ -z "$best" ] || [ "$(cats_version_compare "$v" "$best")" = "1" ]; then
+            best="$v"
+        fi
+    done <<< "$jsonl"
+
+    printf '%s' "$best"
+}
+
+# cats_kiro_latest_version
+# Kiro 的官方 installer 讀 stable/latest/manifest.json（Windows 版 Install-KiroCLI.ps1
+# 用的是同一份），欄位 version。
+cats_kiro_latest_version() {
+    curl -fsSL --connect-timeout 5 --max-time 20 'https://prod.download.cli.kiro.dev/stable/latest/manifest.json' 2>/dev/null | _cats_json_string_field version || true
+}
+
+# cats_devin_latest_version
+# Devin 的官方 install.sh 與 Windows 版 setup.ps1 讀的都是 cli/current/manifest.json，欄位
+# version（3000.10.27）。官方腳本同版雖不重抓，POSIX 版仍會重建兩個符號連結、Windows 版更會
+# 無條件重寫 180 MB 的 devin.exe；先問這裡，同版就完全不動。
+cats_devin_latest_version() {
+    curl -fsSL --connect-timeout 5 --max-time 20 'https://static.devin.ai/cli/current/manifest.json' 2>/dev/null | _cats_json_string_field version || true
+}
+
+# cats_grok_latest_version [channel]
+# Grok 的官方 install.sh（與 Windows 的 install.ps1）決定要下載哪一版，靠的只是一個純文字端點：
+# https://x.ai/cli/<channel>（Cloudflare 前端）不通就退到 GCS 上的同名檔案，內容就是版本號
+# （1.0.30）。這裡照抄同一套順序；channel 預設跟官方一樣吃 GROK_CHANNEL（stable）。
+# 三平台都問這裡，刻意不用 `grok update --check --json`：那要執行 grok 本體去連 x.ai 做 TLS
+# 交握，而 grok 的 TLS 實作用到 SHA-512 硬體指令（sha512su0），沒有這個擴充的 aarch64
+# （Raspberry Pi 4/5 的 Cortex-A72/A76）會當場 SIGILL、輸出全空 —— 見 CLAUDE.md Known Gotchas。
+# 這個端點不必執行任何工具，問到的也正是安裝器接下來會抓的版本。失敗印空。
+cats_grok_latest_version() {
+    local channel="${1:-${GROK_CHANNEL:-stable}}" url v
+    for url in "https://x.ai/cli/${channel}" "https://storage.googleapis.com/grok-build-public-artifacts/cli/${channel}"; do
+        v="$(curl -fsSL --connect-timeout 5 --max-time 20 "$url" 2>/dev/null | tr -d '\r' | head -n 1 | tr -d '[:space:]' || true)"
+        if printf '%s' "$v" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+(-[A-Za-z0-9._]+)?$'; then
+            printf '%s' "$v"
+            return 0
+        fi
+    done
+    printf ''
+}
+
+
+cats_native_latest_version() {
+  local script
+  case "$1" in
+    antigravity) cats_antigravity_latest_version ;;
+    cursor)
+      script="$(curl -fsSL --connect-timeout 5 --max-time 20 https://cursor.com/install 2>/dev/null)" || return 0
+      printf '%s' "$script" | grep -oE 'versions/[0-9]{4}\.[0-9]{2}\.[0-9]{2}-[0-9A-Za-z]+' | head -n 1 | sed 's#^versions/##' || true
+      ;;
+    goose) cats_github_latest_release aaif-goose/goose ;;
+    junie) cats_junie_latest_build ;;
+    kiro) cats_kiro_latest_version ;;
+    devin) cats_devin_latest_version ;;
+    grok) cats_grok_latest_version ;;
+    *) return 0 ;;
+  esac
+}
+
+cats_native_version_token() {
+  if [ "$1" = junie ]; then
+    printf '%s' "$2" | sed -nE 's/.*\(([0-9]+(\.[0-9]+)+)\).*/\1/p' | head -n 1 || true
+  else
+    cats_version_token "$2"
+  fi
+}
+
+# Print current/older/unknown; Cursor same-day hashes are distinct releases.
+cats_native_version_state() {
+  local current latest comparison
+  current="$(cats_native_version_token "$1" "$2")"
+  latest="$3"
+  [ -n "$current" ] && [ -n "$latest" ] || { printf unknown; return 0; }
+  comparison="$(cats_version_compare "$current" "$latest")"
+  if [ "$comparison" = 1 ] || { [ "$comparison" = 0 ] && { [ "$1" != cursor ] || [ "$current" = "$latest" ]; }; }; then
+    printf current
+  elif [ -n "$comparison" ]; then printf older
+  else printf unknown; fi
+}
+
+# Delete only older numeric version directories in a known installer-owned tree.
+# Current/pending/newer builds, symlinks and custom locations outside HOME remain.
+cats_cleanup_native_versions() {
+  local provider="$1" version="$2" root='' data='' keep='' actual='' directory='' name='' ancestor=''
+  keep="$(cats_native_version_token "$provider" "$version")"
+  [ -n "$keep" ] || return 0
+  case "$provider" in
+    cursor)
+      root="$HOME/.local/share/cursor-agent/versions"
+      [ -L "$HOME/.local/bin/cursor-agent" ] || return 0
+      actual="$(readlink "$HOME/.local/bin/cursor-agent")" || return 0
+      [ "$(basename "$(dirname "$actual")")" = "$keep" ] || return 0
+      ;;
+    devin)
+      root="${XDG_DATA_HOME:-$HOME/.local/share}/devin/cli/_versions"
+      [ -L "$root/current" ] || return 0
+      actual="$(readlink "$root/current")" || return 0
+      [ "$(basename "$actual")" = "$keep" ] || return 0
+      ;;
+    junie)
+      data="${JUNIE_DATA_DIR:-$HOME/.local/share/junie}"
+      root="$data/versions"
+      [ ! -e "$data/updates/pending-update.json" ] && [ -L "$data/current" ] || return 0
+      actual="$(readlink "$data/current")" || return 0
+      [ "$(basename "$actual")" = "$keep" ] || return 0
+      ;;
+    *) return 0 ;;
+  esac
+  case "$root" in "$HOME"/*) ;; *) return 0 ;; esac
+  [ -d "$root" ] || return 0
+  ancestor="$root"
+  while [ "$ancestor" != / ] && [ "$ancestor" != . ]; do
+    [ ! -L "$ancestor" ] || return 0
+    ancestor="$(dirname "$ancestor")"
+  done
+  local canonical_home
+  canonical_home="$(cd -P -- "$HOME" && pwd -P)" || return 0
+  root="$(cd -P -- "$root" && pwd -P)" || return 0
+  case "$root" in "$canonical_home"/*) ;; *) return 0 ;; esac
+  for directory in "$root"/*; do
+    [ -d "$directory" ] && [ ! -L "$directory" ] || continue
+    name="$(basename "$directory")"
+    printf '%s' "$name" | grep -qE '^[0-9]+(\.[0-9]+)+(-[0-9A-Za-z]+)?$' || continue
+    [ "$(cats_version_compare "$name" "$keep")" = -1 ] || continue
+    # Skip directory trees with links rather than recurse through an unknown layout.
+    [ -z "$(find "$directory" -type l -print 2>/dev/null)" ] || continue
+    rm -rf -- "$directory" || printf 'Could not remove old %s build %s.\n' "$provider" "$name" >&2
+  done
+}

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

@@ -66,6 +66,8 @@ assert_file "${RESOURCES_ROOT}/desktop/setup-assets/macos/install-goose.sh" 'bun
 assert_file "${RESOURCES_ROOT}/desktop/setup-assets/macos/install-junie.sh" 'bundled macOS Junie installer helper'
 assert_file "${RESOURCES_ROOT}/desktop/setup-assets/macos/install-kiro-cli.sh" 'bundled macOS Kiro installer helper'
 assert_file "${RESOURCES_ROOT}/desktop/setup-assets/macos/check-installation.sh" 'bundled macOS readiness audit helper'
+assert_file "${RESOURCES_ROOT}/desktop/setup-assets/macos/provider-version-common.sh" 'bundled native version library'
+assert_file "${RESOURCES_ROOT}/desktop/setup-assets/macos/verified-npm-update.sh" 'bundled npm verification library'
 assert_file "${RESOURCES_ROOT}/desktop/setup-assets/macos/provider-cli-common.sh" 'bundled macOS provider helper library'
 assert_file "${RESOURCES_ROOT}/desktop/setup-assets/macos/node-cli-common.sh" 'bundled macOS npm helper library'
 assert_file "${RESOURCES_ROOT}/desktop/setup-assets/manifest.json" 'bundled setup-assets manifest'

package/scripts/macos/verified-npm-update.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Usage: source verified-npm-update.sh; cats_upgrade_npm
+# Explicit npm upgrade only. Adapted from environment-bootstrap 4690075.
+# Preserve the current prefix (including nvm), enforce engines, verify command and package.
+cats_upgrade_npm() {
+  local current latest installed root
+  current="$(npm --version)" || { printf 'Could not read npm version.\n' >&2; return 1; }
+  latest="$(npm view npm@latest version --fetch-retries=0 --fetch-timeout=10000 --loglevel=error)" || { printf 'npm version query failed.\n' >&2; return 1; }
+  [[ "$latest" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || { printf 'Invalid npm version metadata.\n' >&2; return 1; }
+  [ "$current" != "$latest" ] || return 0
+  [ "$(cats_version_compare "$current" "$latest")" != 1 ] || return 0
+  npm install -g "npm@$latest" --engine-strict --fetch-retries=0 --fetch-timeout=30000 || return 1
+  hash -r
+  installed="$(npm --version)" && root="$(npm root -g)" || return 1
+  [ "$installed" = "$latest" ] && node -e '
+    const path = require("path");
+    const pkg = require(path.join(process.argv[1], "npm", "package.json"));
+    process.exit(pkg.version === process.argv[2] ? 0 : 1);
+  ' "$root" "$latest" || { printf 'npm verification failed. Check PATH and prefix.\n' >&2; return 1; }
+}

package/scripts/testing/conversation-navigation-smoke-electron.cjs

@@ -0,0 +1,134 @@
+// Usage: invoked by conversation-navigation-smoke.mjs; never run against real state.
+// CATS_NAV_SMOKE_URL selects the fixture server, PROFILE isolates Electron state,
+// and OUTPUT selects the screenshot/result directory. No Desktop supervisor loads.
+const { app, BrowserWindow } = require('electron');
+const { writeFile } = require('node:fs/promises');
+const path = require('node:path');
+app.setPath('userData', process.env.CATS_NAV_SMOKE_PROFILE);
+app.whenReady().then(async () => {
+  const window = new BrowserWindow({ width: 1440, height: 1000, show: false,
+    webPreferences: { sandbox: true, contextIsolation: true, nodeIntegration: false, backgroundThrottling: false, offscreen: true } });
+  window.webContents.setFrameRate(60);
+  const errors = [];
+  window.webContents.on('console-message', (event) => { if (event.level === 'error') errors.push(event.message); });
+  try {
+    await window.loadURL(process.env.CATS_NAV_SMOKE_URL);
+    const result = await window.webContents.executeJavaScript(`(async () => {
+      const wait = async (predicate, label) => {
+        const started = performance.now();
+        while (!predicate()) {
+          if (performance.now() - started > 10000) throw new Error('Timeout: ' + label + '\\n' + document.body.innerText);
+          await new Promise(resolve => setTimeout(resolve, 10));
+        }
+        await new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)));
+      };
+      await wait(() => document.body.innerText.includes('Transcript 1'), 'initial Chat render');
+      const fixture = window.__navigationSmoke;
+      const click = (title) => {
+        const row = [...document.querySelectorAll('button,a,[role="button"],span')].find(el => el.textContent.trim() === title);
+        if (!row) throw new Error('Missing navigation control: ' + title);
+        row.click();
+      };
+      fixture.click = click;
+      fixture.wait = wait;
+      fixture.delays.shell = 60000;
+      fixture.delays.preference = 2000;
+      const timings = [];
+      const checks = [];
+      for (const index of [1, 2, 3]) {
+        const start = performance.now(); click('Conversation ' + (index + 1));
+        await wait(() => document.body.innerText.includes('Transcript ' + (index + 1)), 'cold conversation ' + index);
+        timings.push({ kind: 'cold', conversation: index + 1, ms: performance.now() - start });
+      }
+      fixture.delays.snapshot = 2000;
+      for (const index of [0, 2, 1, 3, 0]) {
+        const start = performance.now(); click('Conversation ' + (index + 1));
+        await wait(() => document.body.innerText.includes('Transcript ' + (index + 1)), 'warm conversation ' + index);
+        const ms = performance.now() - start;
+        if (ms >= 1500) throw new Error('Warm navigation waited for a delayed response: ' + ms);
+        timings.push({ kind: 'warm', conversation: index + 1, ms });
+      }
+      fixture.pushReply(fixture.ids[0], 'Background reply received');
+      await wait(() => document.body.innerText.includes('Background reply received'), 'subscription update');
+      click('Conversation 2');
+      await wait(() => document.body.innerText.includes('Transcript 2'), 'leave updated conversation');
+      click('Conversation 1');
+      await wait(() => document.body.innerText.includes('Background reply received'), 'retained updated transcript');
+      const type = (value) => {
+        const input = document.querySelector('textarea');
+        if (!input) throw new Error('Missing composer textarea');
+        Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, 'value').set.call(input, value);
+        input.dispatchEvent(new Event('input', { bubbles: true }));
+      };
+      type('Keep conversation one draft');
+      await wait(() => document.querySelector('textarea')?.value === 'Keep conversation one draft', 'composer edit');
+      click('New Chat');
+      await wait(() => location.pathname.endsWith('/new'), 'new chat');
+      if (document.querySelector('textarea')?.value) throw new Error('New chat inherited conversation draft');
+      click('Conversation 1');
+      await wait(() => document.querySelector('textarea')?.value === 'Keep conversation one draft', 'restore conversation draft after New Chat');
+      checks.push('cold/warm A/B/C/D navigation', 'background update retention', 'conversation draft after New Chat');
+      fixture.delays.snapshot = 20;
+      for (const serverClose of [false, true]) {
+        const body = serverClose ? 'Recovered server read failure' : 'Recovered disconnected stream';
+        fixture.disconnect(fixture.ids[0], serverClose);
+        if (!document.body.innerText.includes('Transcript 1')) throw new Error('Disconnect cleared retained transcript');
+        fixture.pushReply(fixture.ids[0], body, false);
+        await wait(() => document.body.innerText.includes(body), body);
+      }
+      checks.push('network and server-error reconnection');
+      click('Group Chat');
+      await wait(() => location.pathname.includes('/new'), 'group draft');
+      checks.push({ mode: 'group draft', path: location.pathname, text: document.body.innerText });
+      click('Parallel Chat');
+      await wait(() => location.pathname.includes('/new'), 'parallel draft');
+      checks.push({ mode: 'parallel draft', path: location.pathname, text: document.body.innerText });
+      click('group fixture');
+      await wait(() => document.body.innerText.includes('group transcript'), 'group room');
+      checks.push({ mode: 'group room', text: document.body.innerText });
+      click('Fixture Cat Two');
+      await wait(() => document.body.innerText.includes('direct transcript'), 'direct lane');
+      checks.push({ mode: 'direct lane', text: document.body.innerText });
+      click('Conversation 1');
+      await wait(() => document.querySelector('textarea')?.value === 'Keep conversation one draft', 'draft after other chat modes');
+      return { timings, checks, calls: fixture.calls, text: document.body.innerText };
+    })()`);
+    result.errors = errors;
+    await writeFile(path.join(process.env.CATS_NAV_SMOKE_OUTPUT, 'result.json'), JSON.stringify(result, null, 2));
+    await writeFile(path.join(process.env.CATS_NAV_SMOKE_OUTPUT, 'chat.png'), (await window.webContents.capturePage()).toPNG());
+    for (const [control, marker, name] of [
+      ['Group Chat', 'Add another model to collaborate', 'group-draft'],
+      ['Parallel Chat', 'Follows lead', 'parallel-draft'],
+      ['group fixture', 'group transcript', 'group-room'],
+      ['Fixture Cat Two', 'direct transcript', 'direct-lane'],
+    ]) {
+      await window.webContents.executeJavaScript(`(async () => {
+        const fixture = window.__navigationSmoke;
+        fixture.click(${JSON.stringify(control)});
+        await fixture.wait(() => document.body.innerText.includes(${JSON.stringify(marker)}), ${JSON.stringify(name)});
+      })()`);
+      await writeFile(path.join(process.env.CATS_NAV_SMOKE_OUTPUT, `${name}.png`), (await window.webContents.capturePage()).toPNG());
+    }
+    await window.webContents.executeJavaScript(`(async () => {
+      document.querySelector('.recentOverflowButton').click();
+      await window.__navigationSmoke.wait(() => document.querySelector('.recentOverflowMenu'), 'sidebar overflow');
+      const menu = document.querySelector('.recentOverflowMenu');
+      const bounds = menu.getBoundingClientRect();
+      const topElement = document.elementFromPoint(bounds.x + bounds.width / 2, bounds.y + bounds.height / 2);
+      if (!menu.contains(topElement)) throw new Error('Sidebar overflow is obscured');
+    })()`);
+    await writeFile(path.join(process.env.CATS_NAV_SMOKE_OUTPUT, 'sidebar-overflow.png'), (await window.webContents.capturePage()).toPNG());
+    if (errors.length) throw new Error(errors.join('\n'));
+    window.webContents.stopPainting();
+    window.destroy();
+    app.quit();
+  } catch (error) {
+    await writeFile(path.join(process.env.CATS_NAV_SMOKE_OUTPUT, 'failure.png'), (await window.webContents.capturePage()).toPNG());
+    console.error(error);
+    console.error(errors.join('\n'));
+    window.webContents.stopPainting();
+    window.destroy();
+    process.exitCode = 1;
+    app.quit();
+  }
+});

package/scripts/testing/conversation-navigation-smoke-renderer.tsx

@@ -0,0 +1,102 @@
+// Isolated production Chat renderer. All services below use synthetic fixture data.
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+import { BrowserRouter, Route, Routes } from 'react-router-dom';
+import { QueryClientProvider } from '@tanstack/react-query';
+import { GuideCatPlacementProvider } from '../../src/app/renderer/GuideCatPlacementProvider.js';
+import { sharedQueryClient } from '../../src/products/shared/renderer/queryClient.js';
+import type { AppShellPayload } from '../../src/products/shared/api/workspaceContracts.js';
+import type { ChannelSubscriptionState } from '../../src/products/shared/renderer/entitySubscriptionChannelDispatcher.js';
+import '../../src/design/index.css';
+
+const fixture = await (await fetch('/fixture.json')).json();
+const ids: string[] = fixture.ids;
+const payloads = fixture.payloads as Record<string, AppShellPayload>;
+const snapshots = fixture.snapshots as Record<string, ChannelSubscriptionState>;
+const calls: Array<{ url: string; method: string; at: number }> = [];
+const sources = new Set<FixtureEventSource>();
+const delays = { shell: 0, preference: 2_000, snapshot: 20 };
+let selected = ids[0];
+let shellCalls = 0;
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+class FixtureEventSource extends EventTarget {
+  onerror: (() => void) | null = null;
+  closed = false;
+  constructor(readonly url: string) {
+    super(); sources.add(this);
+    calls.push({ url, method: 'SSE', at: performance.now() });
+    const params = new URL(url, location.origin).searchParams;
+    const id = params.get('id');
+    if (params.get('kind') === 'channel' && id) {
+      void sleep(delays.snapshot).then(() => {
+        if (!this.closed) this.emit('snapshot', { kind: 'channel', id, version: 1, state: snapshots[id] });
+      });
+    }
+  }
+  emit(type: string, data: unknown) { this.dispatchEvent(new MessageEvent(type, { data: JSON.stringify(data) })); }
+  close() { this.closed = true; sources.delete(this); }
+}
+Object.defineProperty(globalThis, 'EventSource', { value: FixtureEventSource, configurable: true });
+globalThis.fetch = async (input, init) => {
+  const url = String(input); calls.push({ url, method: init?.method ?? 'GET', at: performance.now() });
+  if (url === '/api/app-shell') {
+    if (shellCalls++ > 0) await sleep(delays.shell);
+    return Response.json(payloads[selected]);
+  }
+  if (url === '/api/preferences') {
+    await sleep(delays.preference);
+    selected = JSON.parse(String(init?.body)).selectedChannelId ?? selected;
+    return Response.json({ preferences: { selectedChannelId: selected } });
+  }
+  if (url === '/api/core') return Response.json(fixture.core);
+  if (url === '/api/core/approvals') return Response.json({ approvals: [] });
+  if (url === '/api/providers') return Response.json({ state: 'ready', warnings: [], providers: ids.map((id, index) => {
+    const channel = snapshots[id].selectedChannel;
+    return { id: channel.pendingProvider, label: channel.pendingProvider,
+      defaultModel: channel.pendingModel, defaultInstance: 'native', defaultBackend: 'cli',
+      instances: [{ id: 'native', label: 'Native', target: 'cli/native', backend: 'cli', default: true }],
+      modelsPath: `/api/providers/${channel.pendingProvider}/models` };
+  }) });
+  const provider = /^\/api\/providers\/([^/]+)\/models/u.exec(url)?.[1];
+  if (provider) {
+    const channel = Object.values(snapshots).find((snapshot) => snapshot.selectedChannel.pendingProvider === provider)!.selectedChannel;
+    const model = { id: channel.pendingModel, label: channel.pendingModel, default: true };
+    const catalog = { provider, backend: 'cli', instance: 'cli/native', source: 'dynamic', cache: null,
+      defaultModel: channel.pendingModel, models: [model], entries: [model], presets: [], warnings: [],
+      defaultSelection: channel.pendingModelSelection, support: { tier: 'full', notes: [] },
+      controls: [{ key: `${provider}.reasoning_effort`, label: 'Reasoning effort', kind: 'enum', scope: 'both',
+        values: ['low', 'medium', 'high', 'max'].map((value) => ({ value, label: value })) }] };
+    return Response.json({ catalog });
+  }
+  if (/\/api\/channels\/[^/]+$/u.test(url) && init?.method === 'PATCH') {
+    const id = url.split('/').at(-1)!;
+    Object.assign(snapshots[id].selectedChannel, JSON.parse(String(init.body)));
+    return Response.json({ channel: payloads[id].chat.channels.find((channel) => channel.id === id) });
+  }
+  return Response.json({});
+};
+(window as any).__navigationSmoke = { ids, calls, delays, payloads, snapshots,
+  disconnect(id: string, serverClose = false) {
+    for (const source of sources) {
+      if (!source.url.includes(`id=${id}`)) continue;
+      if (serverClose) source.emit('close', { reason: 'Temporary fixture read failure', retryable: true });
+      else source.onerror?.();
+    }
+  },
+  pushReply(id: string, body: string, notify = true) {
+  const state = snapshots[id];
+  state.selectedChannel.messages.push({ ...state.selectedChannel.messages.at(-1)!, id: crypto.randomUUID(), body });
+  for (const source of sources) {
+    if (notify && source.url.includes(`id=${id}`)) source.emit('patch', { kind: 'channel', id, version: 1, patch: { kind: 'message.appended', state } });
+  }
+} };
+const { default: App } = await import('../../src/products/chat/renderer/App.js');
+createRoot(document.getElementById('root')!).render(
+  <QueryClientProvider client={sharedQueryClient}><BrowserRouter useTransitions={false}>
+    <GuideCatPlacementProvider guideCat={null} placement="docked" floatingAnchor={null}
+      sidecarMode="auto" onPersistSeen={() => {}} onCommit={() => {}}>
+      <Routes><Route path="/chat/*" element={<App />} /></Routes>
+    </GuideCatPlacementProvider>
+  </BrowserRouter></QueryClientProvider>,
+);

package/scripts/testing/conversation-navigation-smoke.mjs

@@ -0,0 +1,67 @@
+/**
+ * Usage: node scripts/testing/conversation-navigation-smoke.mjs [--help]
+ * Builds an isolated production Chat renderer and verifies navigation in hidden
+ * Electron/Chromium. All records and services are synthetic; user data is untouched.
+ * Writes build/conversation-navigation-smoke/result.json and a screenshot.
+ */
+import { build } from 'esbuild';
+import { mkdir, mkdtemp, readFile, rm } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import { spawn } from 'node:child_process';
+import { once } from 'node:events';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import electron from 'electron';
+
+if (process.argv.includes('--help')) {
+  console.log('Usage: node scripts/testing/conversation-navigation-smoke.mjs\nSynthetic Chat navigation verification in hidden Electron. Results: build/conversation-navigation-smoke/.');
+  process.exit(0);
+}
+const out = path.resolve('build/conversation-navigation-smoke');
+const temporary = await mkdtemp(path.join(tmpdir(), 'cats-navigation-browser-'));
+await mkdir(out, { recursive: true });
+await build({ entryPoints: ['tests/fixtures/conversationNavigation.ts'], outfile: path.join(out, 'fixture.mjs'),
+  platform: 'node', format: 'esm', bundle: true, packages: 'external' });
+await build({ entryPoints: ['scripts/testing/conversation-navigation-smoke-renderer.tsx'], outfile: path.join(out, 'renderer.js'),
+  platform: 'browser', format: 'esm', bundle: true, define: { 'process.env.NODE_ENV': '"production"' },
+  loader: { '.woff2': 'file', '.woff': 'file', '.png': 'file', '.svg': 'file' } });
+const { createConversationNavigationFixture } = await import(pathToFileURL(path.join(out, 'fixture.mjs')));
+const fixture = await createConversationNavigationFixture(temporary, true);
+const allIds = fixture.state.channels.map((channel) => channel.id);
+const body = JSON.stringify({ ids: fixture.ids, payloads: Object.fromEntries(allIds.map((id) => [id, fixture.payload(id)])),
+  snapshots: Object.fromEntries(allIds.map((id) => [id, fixture.snapshot(id)])), core: await fixture.store.readCore() });
+const server = createServer(async (request, response) => {
+  try {
+    if (request.url === '/fixture.json') { response.setHeader('content-type', 'application/json'); response.end(body); return; }
+    const name = path.basename(new URL(request.url, 'http://localhost').pathname);
+    if (/\.(?:js|css|woff2?|png|svg)$/u.test(name)) {
+      response.setHeader('content-type', name.endsWith('.js') ? 'text/javascript' : name.endsWith('.css') ? 'text/css' : 'application/octet-stream');
+      response.end(await readFile(path.join(out, name))); return;
+    }
+    response.setHeader('content-type', 'text/html');
+    response.end('<!doctype html><html><head><link rel="stylesheet" href="/renderer.css"></head><body><div id="root"></div><script type="module" src="/renderer.js"></script></body></html>');
+  } catch (error) { response.writeHead(500); response.end(String(error)); }
+});
+server.listen(0, '127.0.0.1');
+await once(server, 'listening');
+const url = `http://127.0.0.1:${server.address().port}/chat/chats/${fixture.ids[0]}`;
+const childEnv = { ...process.env, CATS_NAV_SMOKE_URL: url,
+  CATS_NAV_SMOKE_PROFILE: path.join(temporary, 'electron'), CATS_NAV_SMOKE_OUTPUT: out };
+delete childEnv.ELECTRON_RUN_AS_NODE;
+const child = spawn(electron, ['scripts/testing/conversation-navigation-smoke-electron.cjs'], {
+  windowsHide: true, stdio: 'inherit', env: childEnv,
+});
+try {
+  const [code] = await once(child, 'exit');
+  if (code !== 0) throw new Error(`Navigation browser verification exited ${code}`);
+  const result = JSON.parse(await readFile(path.join(out, 'result.json'), 'utf8'));
+  console.log(JSON.stringify({ timings: result.timings,
+    checks: result.checks.map((check) => typeof check === 'string' ? check : check.mode), errors: result.errors }, null, 2));
+} finally {
+  server.closeAllConnections();
+  await new Promise((resolve) => server.close(resolve));
+  if (path.dirname(path.resolve(temporary)) !== path.resolve(tmpdir())
+    || !path.basename(temporary).startsWith('cats-navigation-browser-')) throw new Error('Unexpected smoke cleanup path');
+  await rm(temporary, { recursive: true, force: true });
+}

package/scripts/validate-release-assets.mjs

@@ -34,7 +34,10 @@ const PROJECT_ROOT = resolve(dirname(SCRIPT_PATH), '..');
  */
 export const DESKTOP_RELEASE_MATRIX = [
   { platform: 'windows', formats: ['nsis'], arches: ['x64'] },
-  // macOS ships x64 only; Apple Silicon runs it under Rosetta 2.
+  // macOS ships x64 only: there is no macOS arm64 test environment, so a
+  // universal build would ship a slice nobody executed before release. Apple
+  // Silicon runs this under Rosetta 2. SPEC-111 section 8 records the exit
+  // condition for revisiting it.
   { platform: 'macos', formats: ['dmg', 'zip'], arches: ['x64'] },
   // Linux ships an arm64 .deb. electron-updater installs it with dpkg, which
   // needs elevation -- unlike the per-user Windows path.