@seemseam/ccb 8.4.2 → 8.5.0

package/README/ar.md

@@ -6,7 +6,7 @@
 **نسّق Codex وClaude وGemini وغيرهم من وكلاء CLI ضمن سير عمل مرئي وقابل للتحكم والتدخل المباشر**
 
 <p>
-  <img src="https://img.shields.io/badge/version-8.4.2-orange.svg" alt="version">
+  <img src="https://img.shields.io/badge/version-8.5.0-orange.svg" alt="version">
   <img src="https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20WSL-lightgrey.svg" alt="platform">
   <img src="https://img.shields.io/badge/providers-17%20CLI%20families-0B7285.svg" alt="providers">
 </p>
@@ -182,9 +182,9 @@ ccb update mobile
 <details>
 <summary><b>تفاصيل Mobile App وحدود الأمان والمصدر</b></summary>
 
-يتضمن CCB 8.4.2 مصدر Flutter الخاص بـ CCB Mobile داخل [`mobile/`](../mobile/) وينشر Android APK عبر GitHub Releases:
+يتضمن CCB 8.5.0 مصدر Flutter الخاص بـ CCB Mobile داخل [`mobile/`](../mobile/) وينشر Android APK عبر GitHub Releases:
 
-- [تنزيل CCB Mobile v8.4.2 APK](https://github.com/SeemSeam/claude_codex_bridge/releases/download/v8.4.2/ccb-mobile-v8.4.2.apk)
+- [تنزيل CCB Mobile v8.5.0 APK](https://github.com/SeemSeam/claude_codex_bridge/releases/download/v8.5.0/ccb-mobile-v8.5.0.apk)
 - مصدر التطبيق: [`mobile/app`](../mobile/app)
 - مصدر gateway الخادم: [`lib/mobile_gateway`](../lib/mobile_gateway)
 

package/README/de.md

@@ -6,7 +6,7 @@
 **Koordiniere Codex, Claude, Gemini und andere CLI-Agenten in sichtbaren, steuerbaren Workflows, die du direkt uebernehmen kannst**
 
 <p>
-  <img src="https://img.shields.io/badge/version-8.4.2-orange.svg" alt="version">
+  <img src="https://img.shields.io/badge/version-8.5.0-orange.svg" alt="version">
   <img src="https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20WSL-lightgrey.svg" alt="platform">
   <img src="https://img.shields.io/badge/providers-17%20CLI%20families-0B7285.svg" alt="providers">
 </p>
@@ -182,9 +182,9 @@ Dieser Befehl fuehrt durch Installation und Konfiguration.
 <details>
 <summary><b>Mobile-App-Details, Sicherheitsgrenze und Source</b></summary>
 
-CCB 8.4.2 enthaelt den Flutter-Quellcode von CCB Mobile in [`mobile/`](../mobile/) und veroeffentlicht das Android APK ueber GitHub Releases:
+CCB 8.5.0 enthaelt den Flutter-Quellcode von CCB Mobile in [`mobile/`](../mobile/) und veroeffentlicht das Android APK ueber GitHub Releases:
 
-- [CCB Mobile v8.4.2 APK herunterladen](https://github.com/SeemSeam/claude_codex_bridge/releases/download/v8.4.2/ccb-mobile-v8.4.2.apk)
+- [CCB Mobile v8.5.0 APK herunterladen](https://github.com/SeemSeam/claude_codex_bridge/releases/download/v8.5.0/ccb-mobile-v8.5.0.apk)
 - App-Source: [`mobile/app`](../mobile/app)
 - Server-gateway-Source: [`lib/mobile_gateway`](../lib/mobile_gateway)
 

package/README/es.md

@@ -6,7 +6,7 @@
 **Coordina Codex, Claude, Gemini y otros agentes CLI en flujos visibles y controlables que puedes tomar directamente**
 
 <p>
-  <img src="https://img.shields.io/badge/version-8.4.2-orange.svg" alt="version">
+  <img src="https://img.shields.io/badge/version-8.5.0-orange.svg" alt="version">
   <img src="https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20WSL-lightgrey.svg" alt="platform">
   <img src="https://img.shields.io/badge/providers-17%20CLI%20families-0B7285.svg" alt="providers">
 </p>
@@ -182,9 +182,9 @@ Este comando guía la instalación y configuración.
 <details>
 <summary><b>Detalles de Mobile App, límite de seguridad y fuente</b></summary>
 
-CCB 8.4.2 incluye el código Flutter de CCB Mobile en [`mobile/`](../mobile/) y publica el APK Android mediante GitHub Releases:
+CCB 8.5.0 incluye el código Flutter de CCB Mobile en [`mobile/`](../mobile/) y publica el APK Android mediante GitHub Releases:
 
-- [Descargar CCB Mobile v8.4.2 APK](https://github.com/SeemSeam/claude_codex_bridge/releases/download/v8.4.2/ccb-mobile-v8.4.2.apk)
+- [Descargar CCB Mobile v8.5.0 APK](https://github.com/SeemSeam/claude_codex_bridge/releases/download/v8.5.0/ccb-mobile-v8.5.0.apk)
 - Fuente de la app: [`mobile/app`](../mobile/app)
 - Fuente del gateway del servidor: [`lib/mobile_gateway`](../lib/mobile_gateway)
 

package/README/fr.md

@@ -6,7 +6,7 @@
 **Coordonne Codex, Claude, Gemini et d'autres agents CLI dans des workflows visibles, contrôlables et reprenables directement**
 
 <p>
-  <img src="https://img.shields.io/badge/version-8.4.2-orange.svg" alt="version">
+  <img src="https://img.shields.io/badge/version-8.5.0-orange.svg" alt="version">
   <img src="https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20WSL-lightgrey.svg" alt="platform">
   <img src="https://img.shields.io/badge/providers-17%20CLI%20families-0B7285.svg" alt="providers">
 </p>
@@ -182,9 +182,9 @@ Cette commande guide l'installation et la configuration.
 <details>
 <summary><b>Détails de l'app mobile, frontière de sécurité et source</b></summary>
 
-CCB 8.4.2 inclut le code source Flutter de CCB Mobile dans [`mobile/`](../mobile/) et publie l'APK Android via GitHub Releases :
+CCB 8.5.0 inclut le code source Flutter de CCB Mobile dans [`mobile/`](../mobile/) et publie l'APK Android via GitHub Releases :
 
-- [Télécharger l'APK CCB Mobile v8.4.2](https://github.com/SeemSeam/claude_codex_bridge/releases/download/v8.4.2/ccb-mobile-v8.4.2.apk)
+- [Télécharger l'APK CCB Mobile v8.5.0](https://github.com/SeemSeam/claude_codex_bridge/releases/download/v8.5.0/ccb-mobile-v8.5.0.apk)
 - Source de l'app : [`mobile/app`](../mobile/app)
 - Source du gateway serveur : [`lib/mobile_gateway`](../lib/mobile_gateway)
 

package/README/ja.md

@@ -6,7 +6,7 @@
 **Codex、Claude、Gemini などの CLI Agent を、見える・制御できる・直接引き継げるワークフローで連携**
 
 <p>
-  <img src="https://img.shields.io/badge/version-8.4.2-orange.svg" alt="version">
+  <img src="https://img.shields.io/badge/version-8.5.0-orange.svg" alt="version">
   <img src="https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20WSL-lightgrey.svg" alt="platform">
   <img src="https://img.shields.io/badge/providers-17%20CLI%20families-0B7285.svg" alt="providers">
 </p>
@@ -182,9 +182,9 @@ ccb update mobile
 <details>
 <summary><b>Mobile App の詳細、安全境界、ソース</b></summary>
 
-CCB 8.4.2 では Flutter 版 CCB Mobile のソースが [`mobile/`](../mobile/) に含まれ、Android APK は GitHub Releases で公開されています。
+CCB 8.5.0 では Flutter 版 CCB Mobile のソースが [`mobile/`](../mobile/) に含まれ、Android APK は GitHub Releases で公開されています。
 
-- [CCB Mobile v8.4.2 APK をダウンロード](https://github.com/SeemSeam/claude_codex_bridge/releases/download/v8.4.2/ccb-mobile-v8.4.2.apk)
+- [CCB Mobile v8.5.0 APK をダウンロード](https://github.com/SeemSeam/claude_codex_bridge/releases/download/v8.5.0/ccb-mobile-v8.5.0.apk)
 - App ソース：[`mobile/app`](../mobile/app)
 - サーバー gateway ソース：[`lib/mobile_gateway`](../lib/mobile_gateway)
 

package/README/ko.md

@@ -6,7 +6,7 @@
 **Codex, Claude, Gemini 등 CLI Agent를 보이고 제어 가능하며 직접 이어받을 수 있는 워크플로로 조율**
 
 <p>
-  <img src="https://img.shields.io/badge/version-8.4.2-orange.svg" alt="version">
+  <img src="https://img.shields.io/badge/version-8.5.0-orange.svg" alt="version">
   <img src="https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20WSL-lightgrey.svg" alt="platform">
   <img src="https://img.shields.io/badge/providers-17%20CLI%20families-0B7285.svg" alt="providers">
 </p>
@@ -182,9 +182,9 @@ ccb update mobile
 <details>
 <summary><b>Mobile App 세부 정보, 안전 경계, 소스</b></summary>
 
-CCB 8.4.2은 Flutter CCB Mobile 소스를 [`mobile/`](../mobile/)에 포함하며 Android APK를 GitHub Releases로 배포합니다.
+CCB 8.5.0은 Flutter CCB Mobile 소스를 [`mobile/`](../mobile/)에 포함하며 Android APK를 GitHub Releases로 배포합니다.
 
-- [CCB Mobile v8.4.2 APK 다운로드](https://github.com/SeemSeam/claude_codex_bridge/releases/download/v8.4.2/ccb-mobile-v8.4.2.apk)
+- [CCB Mobile v8.5.0 APK 다운로드](https://github.com/SeemSeam/claude_codex_bridge/releases/download/v8.5.0/ccb-mobile-v8.5.0.apk)
 - 앱 소스: [`mobile/app`](../mobile/app)
 - 서버 gateway 소스: [`lib/mobile_gateway`](../lib/mobile_gateway)
 

package/README/pt.md

@@ -6,7 +6,7 @@
 **Coordene Codex, Claude, Gemini e outros agentes CLI em fluxos visíveis e controláveis que você pode assumir diretamente**
 
 <p>
-  <img src="https://img.shields.io/badge/version-8.4.2-orange.svg" alt="version">
+  <img src="https://img.shields.io/badge/version-8.5.0-orange.svg" alt="version">
   <img src="https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20WSL-lightgrey.svg" alt="platform">
   <img src="https://img.shields.io/badge/providers-17%20CLI%20families-0B7285.svg" alt="providers">
 </p>
@@ -182,9 +182,9 @@ Esse comando orienta a instalação e a configuração.
 <details>
 <summary><b>Detalhes do Mobile App, limite de segurança e fonte</b></summary>
 
-O CCB 8.4.2 inclui o código Flutter do CCB Mobile em [`mobile/`](../mobile/) e publica o APK Android pelo GitHub Releases:
+O CCB 8.5.0 inclui o código Flutter do CCB Mobile em [`mobile/`](../mobile/) e publica o APK Android pelo GitHub Releases:
 
-- [Baixar CCB Mobile v8.4.2 APK](https://github.com/SeemSeam/claude_codex_bridge/releases/download/v8.4.2/ccb-mobile-v8.4.2.apk)
+- [Baixar CCB Mobile v8.5.0 APK](https://github.com/SeemSeam/claude_codex_bridge/releases/download/v8.5.0/ccb-mobile-v8.5.0.apk)
 - Fonte do app: [`mobile/app`](../mobile/app)
 - Fonte do gateway servidor: [`lib/mobile_gateway`](../lib/mobile_gateway)
 

package/README/ru.md

@@ -6,7 +6,7 @@
 **Координируйте Codex, Claude, Gemini и другие CLI Agent в видимых и управляемых процессах, которые можно напрямую взять под контроль**
 
 <p>
-  <img src="https://img.shields.io/badge/version-8.4.2-orange.svg" alt="version">
+  <img src="https://img.shields.io/badge/version-8.5.0-orange.svg" alt="version">
   <img src="https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20WSL-lightgrey.svg" alt="platform">
   <img src="https://img.shields.io/badge/providers-17%20CLI%20families-0B7285.svg" alt="providers">
 </p>
@@ -182,9 +182,9 @@ ccb update mobile
 <details>
 <summary><b>Детали Mobile App, граница безопасности и исходники</b></summary>
 
-CCB 8.4.2 включает Flutter source CCB Mobile в [`mobile/`](../mobile/) и публикует Android APK через GitHub Releases:
+CCB 8.5.0 включает Flutter source CCB Mobile в [`mobile/`](../mobile/) и публикует Android APK через GitHub Releases:
 
-- [Скачать CCB Mobile v8.4.2 APK](https://github.com/SeemSeam/claude_codex_bridge/releases/download/v8.4.2/ccb-mobile-v8.4.2.apk)
+- [Скачать CCB Mobile v8.5.0 APK](https://github.com/SeemSeam/claude_codex_bridge/releases/download/v8.5.0/ccb-mobile-v8.5.0.apk)
 - Исходники app: [`mobile/app`](../mobile/app)
 - Исходники server gateway: [`lib/mobile_gateway`](../lib/mobile_gateway)
 

package/README/zh.md

@@ -6,7 +6,7 @@
 **让 Codex、Claude、Gemini 等 CLI Agent 可见、可控、可接管地协同工作**
 
 <p>
-  <img src="https://img.shields.io/badge/version-8.4.2-orange.svg" alt="version">
+  <img src="https://img.shields.io/badge/version-8.5.0-orange.svg" alt="version">
   <img src="https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20WSL-lightgrey.svg" alt="platform">
   <img src="https://img.shields.io/badge/providers-17%20CLI%20families-0B7285.svg" alt="providers">
 </p>
@@ -211,9 +211,9 @@ ccb update mobile
 <details>
 <summary><b>Mobile App 详情、安全边界和源码</b></summary>
 
-CCB 8.4.2 已把 Flutter 版 CCB Mobile 源码放入 [`mobile/`](../mobile/)，并在 GitHub Release 中发布 Android APK：
+CCB 8.5.0 已把 Flutter 版 CCB Mobile 源码放入 [`mobile/`](../mobile/)，并在 GitHub Release 中发布 Android APK：
 
-- [下载 CCB Mobile v8.4.2 APK](https://github.com/SeemSeam/claude_codex_bridge/releases/download/v8.4.2/ccb-mobile-v8.4.2.apk)
+- [下载 CCB Mobile v8.5.0 APK](https://github.com/SeemSeam/claude_codex_bridge/releases/download/v8.5.0/ccb-mobile-v8.5.0.apk)
 - App 源码：[`mobile/app`](../mobile/app)
 - 服务端 gateway 源码：[`lib/mobile_gateway`](../lib/mobile_gateway)
 
@@ -300,6 +300,42 @@ CCB 支持 [Agent Roles Spec](https://github.com/SeemSeam/agent-roles-spec)：
 ## 新版本记录
 
 <details open>
+<summary><b>v8.5.0</b> - 精确 Pi/OMP 终止、自修复 npm 运行时、同步 Mobile 活动与更安全的托管资源</summary>
+
+- 将 Pi 完成信号绑定到最新的 `agent_settled`，将 OMP 完成信号绑定到 `agent_end.isTerminal=true`，并在进程退出且输出关闭后才进入终态。
+- 对缺少原生终止证据、缺少最终结果、JSONL 损坏或截断、Provider 错误和非零退出安全拒绝；OMP 的终态 `yield` 仍作为受支持的成功结果。
+- 安装时自动创建并修复 npm 托管 Python 环境，正式版运行依赖不再依靠不完整的系统 Python 兜底；linked Git worktree 仍会被正确识别为源码安装。
+- 让 sidebar 设置入口能够恢复正式版受管运行时，并可靠打开 Config UI。
+- 将 Mobile 的 ask/Provider 活动与服务端精确状态同步，稳定完成通知，并隐藏自动重连过程中的无意义提示。
+- 收紧托管 Provider 资源的单向投影边界，并加入内置 Qoder 控制技能，托管侧不会获得改写用户全局状态的通道。
+
+</details>
+
+<details>
+<summary><b>v8.4.3</b> - Provider 认证隔离、必备控制技能与可靠的 Mobile 配对和终端恢复</summary>
+
+- 将可变认证、账号、session 和存储状态隔离到每个托管 Provider 的私有 home，visible 与 headless 执行使用同一边界。
+- 外部凭据只作为单向继承来源，托管 Provider 的刷新或退出不会改写用户 shell、IDE、其他 Agent 或其他项目的登录态。
+- 即使关闭可选 skill 继承，也会为受支持的托管 Agent 提供内置 `ask` 与 `ccb-clear`；托管 Codex 还会保留 `reconnect`。
+- 可选 skill 改为逐项投影，一个损坏的外部条目不会阻断 CCB 控制技能或其他有效 skill。
+- 新增经过校验的紧凑 Relay 配对二维码，可放入 97 列终端，同时保留仅所有者可读的 PNG 兜底。
+- 通过同步 snapshot、完整重绘和自动更新 terminal handle，修复 Mobile 终端 resize 与流错误恢复竞态。
+
+</details>
+
+<details>
+<summary><b>v8.4.2</b> - Config UI 主题持久化、Relay 终端稳定传输与安全 Provider 更新</summary>
+
+- 即使 sidebar 继承到失效 Python 路径，也会使用正式版受管解释器打开 Config UI。
+- 新增可持久化的 CCB 主题选择，包括跟随系统，并在 Config UI、Rich WezTerm 与 sidebar 重启后保持一致。
+- 通过有界背压、稳定快照、增量更新和宽字符计算加固 Relay 终端流。
+- 密集配对内容无法在当前终端安全显示时，生成仅所有者可读的 PNG 二维码。
+- Provider 更新保持 npm/NVM 与 Bun 的包管理器所有权。
+- 对不可写系统安装和解析到本地依赖的异常 Registry 版本只报告、不更新。
+
+</details>
+
+<details>
 <summary><b>v8.4.0</b> - 加密 Mobile Relay、简化配对、稳定项目身份与 Codex 重连</summary>
 
 - 新增端到端加密的 CCB Mobile Relay，支持运营方签发的一次性邀请码、有边界的接入控制、多路复用流，以及官方或自建 Relay 两种部署方式。

package/README.md

@@ -6,7 +6,7 @@
 **Coordinate Codex, Claude, Gemini, and other CLI agents in visible, controllable workflows you can take over**
 
 <p>
-  <img src="https://img.shields.io/badge/version-8.4.2-orange.svg" alt="version">
+  <img src="https://img.shields.io/badge/version-8.5.0-orange.svg" alt="version">
   <img src="https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20WSL-lightgrey.svg" alt="platform">
   <img src="https://img.shields.io/badge/providers-17%20CLI%20families-0B7285.svg" alt="providers">
 </p>
@@ -220,9 +220,9 @@ This command guides installation and configuration.
 <details>
 <summary><b>Mobile App details, safety boundary, and source</b></summary>
 
-CCB 8.4.2 includes the Flutter CCB Mobile source in [`mobile/`](mobile/) and publishes the Android APK through GitHub Releases:
+CCB 8.5.0 includes the Flutter CCB Mobile source in [`mobile/`](mobile/) and publishes the Android APK through GitHub Releases:
 
-- [Download CCB Mobile v8.4.2 APK](https://github.com/SeemSeam/claude_codex_bridge/releases/download/v8.4.2/ccb-mobile-v8.4.2.apk)
+- [Download CCB Mobile v8.5.0 APK](https://github.com/SeemSeam/claude_codex_bridge/releases/download/v8.5.0/ccb-mobile-v8.5.0.apk)
 - App source: [`mobile/app`](mobile/app)
 - Server gateway source: [`lib/mobile_gateway`](lib/mobile_gateway)
 
@@ -309,6 +309,42 @@ Thanks to [tmux-agent-sidebar](https://github.com/hiroppy/tmux-agent-sidebar) fo
 ## Release Notes
 
 <details open>
+<summary><b>v8.5.0</b> - Exact Pi/OMP completion, self-healing npm runtime, synchronized Mobile activity, and safer managed assets</summary>
+
+- Bound Pi completion to the latest `agent_settled` event and OMP completion to `agent_end.isTerminal=true`, while waiting for process exit and output closure before terminalizing.
+- Failed closed on missing native terminal evidence, missing final outcomes, malformed or truncated JSONL, provider errors, and nonzero exits; terminal OMP `yield` remains a supported successful result.
+- Bootstrapped and repaired the npm-managed Python environment during install, so release runtime dependencies no longer depend on an incomplete system Python fallback; linked Git worktrees remain correctly classified as source installs.
+- Made the sidebar settings launcher recover its release-managed runtime and reliably open Config UI.
+- Synchronized Mobile ask/provider activity with exact server-side state, stable completion notifications, and quieter automatic reconnect behavior.
+- Tightened one-way managed Provider asset projection and added packaged Qoder control skills without exposing user-global state to managed mutation.
+
+</details>
+
+<details>
+<summary><b>v8.4.3</b> - Isolated Provider auth, guaranteed control skills, and reliable Mobile pairing and terminal recovery</summary>
+
+- Isolated mutable authentication, account, session, and storage state inside each managed Provider home for visible and headless execution.
+- Made external credentials one-way inheritance input, so managed refresh or logout cannot modify the user's shell, IDE, another Agent, or another project.
+- Guaranteed packaged `ask` and `ccb-clear` controls for supported managed Agents even when optional skill inheritance is disabled; managed Codex also keeps `reconnect`.
+- Projected optional skills independently so one broken external entry cannot suppress CCB controls or unrelated valid skills.
+- Added a compact, validated Relay pairing QR that fits a 97-column terminal while retaining the owner-only PNG fallback.
+- Made Mobile terminal resize and stream recovery race-safe with synchronized snapshots, clean repaint, and automatic handle renewal.
+
+</details>
+
+<details>
+<summary><b>v8.4.2</b> - Persistent Config UI themes, stable Relay terminal streaming, and safe Provider updates</summary>
+
+- Opened Config UI with the release-managed interpreter even when the sidebar inherited a stale Python path.
+- Added persistent CCB theme selection, including system-default behavior, across Config UI, Rich WezTerm, and sidebar restarts.
+- Stabilized Relay terminal snapshots and incremental updates with bounded backpressure and correct wide-character accounting.
+- Generated owner-only PNG pairing codes when dense payloads cannot render safely in the current terminal.
+- Preserved npm/NVM and Bun package-manager ownership during Provider updates.
+- Reported non-writable system installs and unsafe local registry dependencies without attempting an update.
+
+</details>
+
+<details>
 <summary><b>v8.4.0</b> - Encrypted Mobile Relay, simpler pairing, stable project identity, and Codex reconnect</summary>
 
 - Added end-to-end encrypted CCB Mobile Relay transport with operator-issued one-time invitations, bounded admission, multiplexed streams, and official or self-hosted deployment modes.

package/VERSION

@@ -1 +1 @@
-8.4.2
+8.5.0

package/bin/ccb-npm-install.js

@@ -12,6 +12,19 @@ const root = path.resolve(__dirname, "..");
 const manifest = require(path.join(root, "package.json"));
 const version = manifest.version;
 const vendorRoot = path.join(root, ".ccb-release");
+const installLock = path.join(root, ".ccb-install.lock");
+const runtimeProbe = [
+  "import sys",
+  "if sys.version_info < (3, 10):",
+  "    raise SystemExit(1)",
+  "try:",
+  "    import tomllib",
+  "except ModuleNotFoundError:",
+  "    import tomli",
+  "import aiohttp",
+  "from cryptography.hazmat.primitives.asymmetric import ed25519, x25519",
+  "from cryptography.hazmat.primitives.ciphers.aead import ChaCha20Poly1305",
+].join("\n");
 
 function artifactForHost() {
   if (process.platform === "darwin") {
@@ -42,14 +55,39 @@ function executablePath(command = "ccb") {
   return command === "ccb" ? path.join(base, "ccb") : path.join(base, "bin", command);
 }
 
-function isInstalled(info) {
+function runtimePythonPath(info) {
+  return path.join(installDir(info), ".venv", "bin", "python");
+}
+
+function isReleaseInstalled(info) {
   const dir = installDir(info);
   const versionFile = path.join(dir, "VERSION");
   const ccbPath = path.join(dir, "ccb");
   if (!fs.existsSync(versionFile) || !fs.existsSync(ccbPath)) {
     return false;
   }
-  return fs.readFileSync(versionFile, "utf8").trim() === version;
+  try {
+    fs.accessSync(ccbPath, fs.constants.X_OK);
+    return fs.readFileSync(versionFile, "utf8").trim() === version;
+  } catch (_error) {
+    return false;
+  }
+}
+
+function isRuntimeReady(info) {
+  const pythonPath = runtimePythonPath(info);
+  if (!fs.existsSync(pythonPath)) {
+    return false;
+  }
+  const completed = childProcess.spawnSync(pythonPath, ["-c", runtimeProbe], {
+    stdio: "ignore",
+    timeout: 15000,
+  });
+  return !completed.error && completed.status === 0;
+}
+
+function isInstalled(info) {
+  return isReleaseInstalled(info) && isRuntimeReady(info);
 }
 
 function download(url, destination, redirects = 0) {
@@ -100,9 +138,10 @@ function sha256File(filePath) {
   return hash.digest("hex");
 }
 
-function run(command, args) {
+function run(command, args, options = {}) {
   const completed = childProcess.spawnSync(command, args, {
     stdio: "inherit",
+    ...options,
   });
   if (completed.error) {
     throw completed.error;
@@ -112,16 +151,119 @@ function run(command, args) {
   }
 }
 
-async function install() {
-  const info = artifactForHost();
-  if (isInstalled(info)) {
-    return;
+function bootstrapRuntime(info) {
+  const dir = installDir(info);
+  const installerPath = path.join(dir, "install.sh");
+  if (!isReleaseInstalled(info)) {
+    throw new Error(`Cannot bootstrap an incomplete CCB release at ${dir}`);
   }
-  if (process.env.CCB_NPM_SKIP_DOWNLOAD === "1") {
-    console.warn("Skipping CCB release download because CCB_NPM_SKIP_DOWNLOAD=1.");
-    return;
+  if (!fs.existsSync(installerPath)) {
+    throw new Error(`CCB runtime bootstrap installer not found at ${installerPath}`);
+  }
+
+  const env = {
+    ...process.env,
+    CODEX_INSTALL_PREFIX: dir,
+    CODEX_BIN_DIR: path.join(dir, ".npm-runtime-bin"),
+    CCB_SOURCE_KIND: "release",
+    CCB_USE_MANAGED_VENV: "1",
+    CCB_INSTALL_TOMLI: "1",
+    CCB_INSTALL_MOBILE_RELAY_DEPS: "1",
+    CCB_INSTALL_ROLES: "0",
+    CCB_INSTALL_NEOVIM: "0",
+  };
+  run("bash", [installerPath, "runtime-bootstrap"], { env });
+  if (!isRuntimeReady(info)) {
+    throw new Error(`CCB managed Python runtime is not usable at ${runtimePythonPath(info)}`);
+  }
+}
+
+function sleep(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+function processIsAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) {
+    return false;
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error && error.code === "EPERM";
+  }
+}
+
+function readLockOwner() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(installLock, "owner.json"), "utf8"));
+  } catch (_error) {
+    return null;
+  }
+}
+
+function reclaimStaleInstallLock() {
+  const owner = readLockOwner();
+  if (owner && processIsAlive(Number(owner.pid))) {
+    return false;
+  }
+  try {
+    const ageMs = Date.now() - fs.statSync(installLock).mtimeMs;
+    if (!owner && ageMs < 30000) {
+      return false;
+    }
+    fs.rmSync(installLock, { recursive: true, force: true });
+    return true;
+  } catch (_error) {
+    return false;
+  }
+}
+
+async function acquireInstallLock() {
+  const configuredTimeout = Number(process.env.CCB_NPM_INSTALL_LOCK_TIMEOUT_MS);
+  const timeoutMs =
+    Number.isFinite(configuredTimeout) && configuredTimeout > 0
+      ? configuredTimeout
+      : 15 * 60 * 1000;
+  const deadline = Date.now() + timeoutMs;
+  const token = crypto.randomBytes(16).toString("hex");
+
+  while (true) {
+    try {
+      fs.mkdirSync(installLock);
+    } catch (error) {
+      if (!error || error.code !== "EEXIST") {
+        throw error;
+      }
+      if (reclaimStaleInstallLock()) {
+        continue;
+      }
+      if (Date.now() >= deadline) {
+        throw new Error(`Timed out waiting for CCB npm install lock: ${installLock}`);
+      }
+      await sleep(200);
+      continue;
+    }
+
+    try {
+      fs.writeFileSync(
+        path.join(installLock, "owner.json"),
+        JSON.stringify({ pid: process.pid, token, createdAt: new Date().toISOString() })
+      );
+    } catch (error) {
+      fs.rmSync(installLock, { recursive: true, force: true });
+      throw error;
+    }
+    return () => {
+      const owner = readLockOwner();
+      if (owner && owner.token === token) {
+        fs.rmSync(installLock, { recursive: true, force: true });
+      }
+    };
   }
+}
 
+async function downloadRelease(info) {
   const baseUrl =
     process.env.CCB_NPM_RELEASE_BASE_URL ||
     `https://github.com/SeemSeam/claude_codex_bridge/releases/download/v${version}`;
@@ -154,6 +296,32 @@ async function install() {
   }
 }
 
+async function install() {
+  const info = artifactForHost();
+  if (isInstalled(info)) {
+    return;
+  }
+
+  const releaseLock = await acquireInstallLock();
+  try {
+    if (isInstalled(info)) {
+      return;
+    }
+    if (!isReleaseInstalled(info)) {
+      if (process.env.CCB_NPM_SKIP_DOWNLOAD === "1") {
+        console.warn("Skipping CCB release download because CCB_NPM_SKIP_DOWNLOAD=1.");
+        return;
+      }
+      await downloadRelease(info);
+    }
+    if (!isRuntimeReady(info)) {
+      bootstrapRuntime(info);
+    }
+  } finally {
+    releaseLock();
+  }
+}
+
 if (require.main === module) {
   install().catch((error) => {
     console.error(error.message || error);
@@ -162,6 +330,13 @@ if (require.main === module) {
 }
 
 module.exports = {
+  artifactForHost,
+  bootstrapRuntime,
   executablePath,
   install,
+  installDir,
+  isInstalled,
+  isReleaseInstalled,
+  isRuntimeReady,
+  runtimePythonPath,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seemseam/ccb",
-  "version": "8.4.2",
+  "version": "8.5.0",
   "description": "Lightweight multi-agent TUI and stable cross-provider collaboration layer for Codex, Claude, Gemini, Grok, Kimi, DeepSeek, and other CLI agents.",
   "license": "AGPL-3.0-only",
   "homepage": "https://github.com/SeemSeam/claude_codex_bridge#readme",