clawdex-mobile 5.1.3-internal.7 → 5.1.3-internal.9

package/docs/setup-and-operations.md

@@ -84,10 +84,11 @@ gh codespace ports visibility 8787:public 8788:public
 
 ### Codespaces Bootstrap
 
-The repo devcontainer now includes:
+The source repo devcontainer now includes:
 
-- `postCreateCommand`: `npm install --include=dev && npm run codespaces:bootstrap -- --prepare-only`
-- `postStartCommand`: `npm run codespaces:bootstrap`
+- `updateContentCommand`: `npm install --include=dev --prefer-offline --no-audit --fund=false && npm run codespaces:bootstrap -- --prepare-only`
+- `postStartCommand`: fire-and-forget `npm run codespaces:bootstrap`, writing setup output to `.bridge-bootstrap.log`
+- `waitFor`: `updateContentCommand`
 
 `npm run codespaces:bootstrap` does the following:
 
@@ -99,9 +100,9 @@ The repo devcontainer now includes:
 
 Clawdex-created Codespaces request a 45-minute idle timeout. The bridge emits a lightweight active-turn keepalive while a Codex, OpenCode, or Cursor turn is running, so active work has activity even if a long step is otherwise quiet. When no turn is running, the keepalive stops and GitHub can pause the Codespace normally to save cost.
 
-That means the first Codespace create now front-loads the expensive bridge compile during `postCreateCommand`, so the later `postStartCommand` can usually start the bridge much faster.
+That means prebuild-enabled Codespaces can snapshot the expensive dependency install and bridge compile during `updateContentCommand`. The later `postStartCommand` starts the runtime bridge asynchronously so Codespaces does not block editor/app access while the bridge finishes warming up.
 
-The same bootstrap script is included in the published `clawdex-mobile` npm package. That lets the `clawdex-codespace` template stay minimal: it can install `clawdex-mobile@latest` globally in the devcontainer and invoke the packaged bootstrap against the current workspace instead of copying `scripts/*` and `services/rust-bridge/*` into the template repo.
+The same bootstrap script is included in the published `clawdex-mobile` npm package. That lets the `clawdex-codespace` template stay minimal: it installs `clawdex-mobile@internal` globally in `updateContentCommand` and invokes the packaged bootstrap against the current workspace instead of copying `scripts/*` and `services/rust-bridge/*` into the template repo. Because the published package ships Linux bridge binaries, the template does not need Rust, Cargo, or a local bridge compile.
 
 Manual examples:
 
@@ -115,7 +116,7 @@ CLAWDEX_CODESPACES_ENGINES=codex,opencode,cursor npm run codespaces:bootstrap
 Minimal template equivalent:
 
 ```bash
-npm install -g clawdex-mobile@latest @openai/codex
+npm install -g --no-fund --no-audit clawdex-mobile@internal @openai/codex
 CLAWDEX_WORKSPACE_ROOT="$PWD" node "$(npm root -g)/clawdex-mobile/scripts/codespaces-bootstrap.js" --prepare-only
 CLAWDEX_WORKSPACE_ROOT="$PWD" node "$(npm root -g)/clawdex-mobile/scripts/codespaces-bootstrap.js"
 ```

package/docs/troubleshooting.md

@@ -60,7 +60,7 @@ gh codespace ports visibility 8787:public 8788:public
 
 ## GitHub Codespaces bootstrap did not start the bridge
 
-- Check the post-start command output in the Codespace terminal or rerun it manually:
+- Check `.bridge-bootstrap.log` for the post-start bootstrap and `.bridge.log` for the bridge process, or rerun the bootstrap manually:
 
 ```bash
 npm run codespaces:bootstrap -- --prepare-only
@@ -81,8 +81,9 @@ CLAWDEX_WORKSPACE_ROOT="$PWD" node "$(npm root -g)/clawdex-mobile/scripts/codesp
 - Bridge startup logs and runtime state live in the Codespace repo root:
 
 ```bash
+tail -n 200 .bridge-bootstrap.log
 tail -n 200 .bridge.log
-ls -la .bridge.pid .bridge.log .env.secure
+ls -la .bridge.pid .bridge.log .bridge-bootstrap.log .env.secure
 ```
 
 - To only rewrite `.env.secure` without starting the bridge:
@@ -102,7 +103,7 @@ npm run codespaces:bootstrap -- --no-start
 
 - The bridge can transcribe with `OPENAI_API_KEY`, `BRIDGE_CHATGPT_ACCESS_TOKEN`, a legacy bridge token cache, or the Codex-managed ChatGPT token in `$CODEX_HOME/auth.json`.
 - In GitHub Codespaces, finish the Codex login step from the app first. Codex writes the login to `$HOME/.codex/auth.json`, and `.env.secure` sets `CODEX_HOME` to that persistent location.
-- If you still see the error after logging in, restart the bridge once so app-server reloads the Codex auth home:
+- Current app builds automatically restart the Codespace Codex app-server after the Codex login step so it reloads the Codex auth home. On older builds, restart the bridge once after logging in:
 
 ```bash
 npm run secure:bridge

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawdex-mobile",
-  "version": "5.1.3-internal.7",
+  "version": "5.1.3-internal.9",
   "description": "Private-network mobile bridge and CLI for Codex and OpenCode",
   "keywords": [
     "codex",

package/scripts/start-bridge-secure.js

@@ -16,6 +16,7 @@ const {
 } = require("./bridge-binary");
 
 const DEFAULT_HEALTH_TIMEOUT_MS = 15000;
+const CODESPACES_HEALTH_TIMEOUT_MS = 60000;
 const DEV_HEALTH_TIMEOUT_MS = 60000;
 let qrcodeTerminal = null;
 let qrcodeTerminalLoaded = false;
@@ -346,6 +347,13 @@ function formatCodespacesVisibilityCommand(env, ports) {
   return ["gh", "codespace", "ports", "visibility", ...visibilityArgs, ...selectionArgs].join(" ");
 }
 
+function sleepSync(ms) {
+  if (!Number.isFinite(ms) || ms <= 0) {
+    return;
+  }
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
 function updateCodespacesBrowseUrls(env, ports) {
   if (!commandExists("gh")) {
     return;
@@ -416,38 +424,57 @@ function ensureCodespacesPortsArePublic(env, ports) {
     return notes;
   }
 
-  const result = spawnSync(
-    "gh",
-    [
-      "codespace",
-      "ports",
-      "visibility",
-      ...uniquePorts.map((port) => `${port}:public`),
-      ...codespaceSelectionArgs(env),
-    ],
-    {
-      encoding: "utf8",
-      env: ghAuthEnv(env),
-      stdio: ["ignore", "pipe", "pipe"],
+  const publishedPorts = [];
+  const failedPorts = [];
+  const selectionArgs = codespaceSelectionArgs(env);
+
+  for (const port of uniquePorts) {
+    let lastDetail = "";
+    for (let attempt = 1; attempt <= 8; attempt += 1) {
+      const result = spawnSync(
+        "gh",
+        ["codespace", "ports", "visibility", `${port}:public`, ...selectionArgs],
+        {
+          encoding: "utf8",
+          env: ghAuthEnv(env),
+          stdio: ["ignore", "pipe", "pipe"],
+        }
+      );
+
+      if ((result.status ?? 1) === 0) {
+        publishedPorts.push(port);
+        lastDetail = "";
+        break;
+      }
+
+      lastDetail = (result.stderr || result.stdout || "").trim();
+      if (attempt < 8) {
+        sleepSync(1_500);
+      }
     }
-  );
 
-  if ((result.status ?? 1) !== 0) {
-    const detail = (result.stderr || result.stdout || "").trim();
-    const suffix = detail ? ` (${detail.split(/\r?\n/, 1)[0]})` : "";
+    if (lastDetail) {
+      failedPorts.push({ port, detail: lastDetail });
+    }
+  }
+
+  if (publishedPorts.length > 0) {
+    updateCodespacesBrowseUrls(env, publishedPorts);
     notes.push(
-      `Could not set Codespaces forwarded ports public automatically${suffix}. Run '${formatCodespacesVisibilityCommand(
+      `Codespaces forwarded ports are set to public for bridge access: ${publishedPorts.join(", ")}.`
+    );
+  }
+
+  for (const failure of failedPorts) {
+    const suffix = failure.detail ? ` (${failure.detail.split(/\r?\n/, 1)[0]})` : "";
+    notes.push(
+      `Could not set Codespaces forwarded port ${failure.port} public automatically${suffix}. Run '${formatCodespacesVisibilityCommand(
         env,
-        uniquePorts
+        [failure.port]
       )}' or update the Ports panel manually.`
     );
-    return notes;
   }
 
-  updateCodespacesBrowseUrls(env, uniquePorts);
-  notes.push(
-    `Codespaces forwarded ports are set to public for bridge access: ${uniquePorts.join(", ")}.`
-  );
   return notes;
 }
 
@@ -752,6 +779,10 @@ function buildBridgeFromSource(packageDir, env, profile) {
 }
 
 function resolveLaunch(workspaceDir, packageDir, env, { devMode, forceSourceBuild }) {
+  const defaultHealthTimeoutMs = isCodespacesMode(env)
+    ? CODESPACES_HEALTH_TIMEOUT_MS
+    : DEFAULT_HEALTH_TIMEOUT_MS;
+
   if (devMode) {
     if (!commandExists("cargo")) {
       console.error("error: missing Rust/Cargo toolchain for dev bridge mode.");
@@ -779,7 +810,7 @@ function resolveLaunch(workspaceDir, packageDir, env, { devMode, forceSourceBuil
       args: [],
       cwd: workspaceDir,
       env,
-      healthTimeoutMs: DEFAULT_HEALTH_TIMEOUT_MS,
+      healthTimeoutMs: defaultHealthTimeoutMs,
     };
   }
 
@@ -792,7 +823,7 @@ function resolveLaunch(workspaceDir, packageDir, env, { devMode, forceSourceBuil
       args: [],
       cwd: workspaceDir,
       env,
-      healthTimeoutMs: DEFAULT_HEALTH_TIMEOUT_MS,
+      healthTimeoutMs: defaultHealthTimeoutMs,
     };
   }
 
@@ -804,7 +835,7 @@ function resolveLaunch(workspaceDir, packageDir, env, { devMode, forceSourceBuil
       args: [],
       cwd: workspaceDir,
       env,
-      healthTimeoutMs: DEFAULT_HEALTH_TIMEOUT_MS,
+      healthTimeoutMs: defaultHealthTimeoutMs,
     };
   }
 
@@ -833,7 +864,7 @@ function resolveLaunch(workspaceDir, packageDir, env, { devMode, forceSourceBuil
     args: [],
     cwd: workspaceDir,
     env,
-    healthTimeoutMs: DEFAULT_HEALTH_TIMEOUT_MS,
+    healthTimeoutMs: defaultHealthTimeoutMs,
   };
 }
 

package/services/rust-bridge/Cargo.lock

@@ -149,7 +149,7 @@ dependencies = [
 
 [[package]]
 name = "codex-rust-bridge"
-version = "5.1.3-internal.7"
+version = "5.1.3-internal.9"
 dependencies = [
  "axum",
  "base64",

package/services/rust-bridge/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "codex-rust-bridge"
-version = "5.1.3-internal.7"
+version = "5.1.3-internal.9"
 edition = "2021"
 
 [dependencies]

package/services/rust-bridge/src/main.rs

@@ -1266,7 +1266,7 @@ impl BrowserPreviewService {
 #[derive(Clone)]
 struct RuntimeBackend {
     preferred_engine: BridgeRuntimeEngine,
-    codex: Option<Arc<AppServerBridge>>,
+    codex: Arc<StdRwLock<Option<Arc<AppServerBridge>>>>,
     opencode: Option<Arc<OpencodeBackend>>,
     cursor: Arc<StdRwLock<Option<Arc<AppServerBridge>>>>,
 }
@@ -1281,7 +1281,7 @@ impl RuntimeBackend {
         let cursor_enabled = config
             .enabled_engines
             .contains(&BridgeRuntimeEngine::Cursor);
-        let mut codex = None;
+        let codex = Arc::new(StdRwLock::new(None));
         let mut opencode = None;
         let cursor = Arc::new(StdRwLock::new(None));
 
@@ -1291,7 +1291,7 @@ impl RuntimeBackend {
                     let app_server =
                         AppServerBridge::start_codex(&config.cli_bin, hub.clone()).await?;
                     spawn_rollout_live_sync(hub.clone());
-                    codex = Some(app_server);
+                    Self::store_codex_backend(&codex, app_server);
                 }
 
                 if opencode_enabled {
@@ -1327,7 +1327,7 @@ impl RuntimeBackend {
                     {
                         Ok(app_server) => {
                             spawn_rollout_live_sync(hub.clone());
-                            codex = Some(app_server);
+                            Self::store_codex_backend(&codex, app_server);
                         }
                         Err(error) => eprintln!(
                             "codex backend unavailable; continuing with selected harnesses only: {error}"
@@ -1358,7 +1358,7 @@ impl RuntimeBackend {
                     match AppServerBridge::start_codex(&config.cli_bin, hub.clone()).await {
                         Ok(app_server) => {
                             spawn_rollout_live_sync(hub.clone());
-                            codex = Some(app_server);
+                            Self::store_codex_backend(&codex, app_server);
                         }
                         Err(error) => eprintln!(
                             "codex backend unavailable; continuing with selected harnesses only: {error}"
@@ -1389,6 +1389,19 @@ impl RuntimeBackend {
         self.cursor.read().ok().and_then(|guard| guard.clone())
     }
 
+    fn codex_backend(&self) -> Option<Arc<AppServerBridge>> {
+        self.codex.read().ok().and_then(|guard| guard.clone())
+    }
+
+    fn store_codex_backend(
+        codex_slot: &Arc<StdRwLock<Option<Arc<AppServerBridge>>>>,
+        bridge: Arc<AppServerBridge>,
+    ) {
+        if let Ok(mut guard) = codex_slot.write() {
+            *guard = Some(bridge);
+        }
+    }
+
     fn store_cursor_backend(
         cursor_slot: &Arc<StdRwLock<Option<Arc<AppServerBridge>>>>,
         bridge: Arc<AppServerBridge>,
@@ -1398,8 +1411,31 @@ impl RuntimeBackend {
         }
     }
 
+    async fn restart_codex_app_server(
+        &self,
+        config: &Arc<BridgeConfig>,
+        hub: Arc<ClientHub>,
+    ) -> Result<(), String> {
+        if !config.enabled_engines.contains(&BridgeRuntimeEngine::Codex) {
+            return Err("codex backend is not enabled".to_string());
+        }
+
+        let next_backend = AppServerBridge::start_codex(&config.cli_bin, hub).await?;
+        let previous_backend = self
+            .codex
+            .write()
+            .map(|mut guard| guard.replace(next_backend))
+            .map_err(|_| "codex backend lock is unavailable".to_string())?;
+
+        if let Some(previous_backend) = previous_backend {
+            previous_backend.request_shutdown().await;
+        }
+
+        Ok(())
+    }
+
     async fn shutdown(&self) {
-        if let Some(codex) = &self.codex {
+        if let Some(codex) = self.codex_backend() {
             codex.request_shutdown().await;
         }
         if let Some(opencode) = &self.opencode {
@@ -1416,7 +1452,7 @@ impl RuntimeBackend {
 
     fn available_engines(&self) -> Vec<BridgeRuntimeEngine> {
         let mut engines = Vec::new();
-        if self.codex.is_some() {
+        if self.codex_backend().is_some() {
             engines.push(BridgeRuntimeEngine::Codex);
         }
         if self.opencode.is_some() {
@@ -1469,8 +1505,7 @@ impl RuntimeBackend {
     ) -> Result<RuntimeBackendRef<'_>, String> {
         match engine {
             BridgeRuntimeEngine::Codex => self
-                .codex
-                .as_ref()
+                .codex_backend()
                 .map(RuntimeBackendRef::Codex)
                 .ok_or_else(|| "codex backend is unavailable".to_string()),
             BridgeRuntimeEngine::Opencode => self
@@ -1576,7 +1611,7 @@ impl RuntimeBackend {
         let bridge_cursor = extract_thread_list_cursor(params.as_ref())
             .and_then(|cursor| decode_bridge_thread_list_cursor(&cursor));
 
-        if let Some(codex) = &self.codex {
+        if let Some(codex) = self.codex_backend() {
             if let Some(cursor_map) = bridge_cursor.as_ref() {
                 if let Some(cursor) = cursor_map.get(&BridgeRuntimeEngine::Codex) {
                     results.push((
@@ -1660,7 +1695,7 @@ impl RuntimeBackend {
     async fn aggregate_loaded_thread_ids(&self) -> Result<Value, String> {
         let mut results = Vec::new();
 
-        if let Some(codex) = &self.codex {
+        if let Some(codex) = self.codex_backend() {
             results.push((
                 BridgeRuntimeEngine::Codex,
                 codex.request_internal("thread/loaded/list", None).await?,
@@ -1688,7 +1723,7 @@ impl RuntimeBackend {
 
     async fn list_pending_approvals(&self) -> Vec<PendingApproval> {
         let mut approvals = Vec::new();
-        if let Some(codex) = &self.codex {
+        if let Some(codex) = self.codex_backend() {
             approvals.extend(codex.list_pending_approvals().await);
         }
         if let Some(opencode) = &self.opencode {
@@ -1703,7 +1738,7 @@ impl RuntimeBackend {
 
     async fn list_pending_user_inputs(&self) -> Vec<PendingUserInputRequest> {
         let mut requests = Vec::new();
-        if let Some(codex) = &self.codex {
+        if let Some(codex) = self.codex_backend() {
             requests.extend(codex.list_pending_user_inputs().await);
         }
         if let Some(opencode) = &self.opencode {
@@ -1721,7 +1756,7 @@ impl RuntimeBackend {
         approval_id: &str,
         decision: &Value,
     ) -> Result<Option<PendingApproval>, String> {
-        if let Some(codex) = &self.codex {
+        if let Some(codex) = self.codex_backend() {
             if let Some(approval) = codex.resolve_approval(approval_id, decision).await? {
                 return Ok(Some(approval));
             }
@@ -1747,7 +1782,7 @@ impl RuntimeBackend {
         request_id: &str,
         answers: &HashMap<String, UserInputAnswerPayload>,
     ) -> Result<Option<PendingUserInputRequest>, String> {
-        if let Some(codex) = &self.codex {
+        if let Some(codex) = self.codex_backend() {
             if let Some(request) = codex.resolve_user_input(request_id, answers).await? {
                 return Ok(Some(request));
             }
@@ -1792,7 +1827,7 @@ impl RuntimeBackend {
                 }
             }),
         };
-        if let Some(codex) = &self.codex {
+        if let Some(codex) = self.codex_backend() {
             codex.hub.send_json(client_id, payload).await;
         } else if let Some(opencode) = &self.opencode {
             opencode.hub.send_json(client_id, payload).await;
@@ -1892,7 +1927,7 @@ async fn terminate_process_tree_windows(pid: u32, label: &str) {
 }
 
 enum RuntimeBackendRef<'a> {
-    Codex(&'a Arc<AppServerBridge>),
+    Codex(Arc<AppServerBridge>),
     Opencode(&'a Arc<OpencodeBackend>),
     Cursor(Arc<AppServerBridge>),
 }
@@ -7468,6 +7503,17 @@ async fn handle_bridge_method(
                     .map_err(|error| BridgeError::invalid_params(&error.to_string()))?;
             forward_codex_auth_callback(state, &request.callback_url).await
         }
+        "bridge/codex/app-server/restart" => {
+            state
+                .backend
+                .restart_codex_app_server(&state.config, state.hub.clone())
+                .await
+                .map_err(|error| BridgeError::server(&error))?;
+            Ok(json!({
+                "ok": true,
+                "message": "Codex app-server restarted."
+            }))
+        }
         "bridge/update/start" => {
             let request: BridgeUpdateStartRequest =
                 serde_json::from_value(params.unwrap_or_else(|| json!({})))
@@ -8156,7 +8202,7 @@ fn thread_list_stream_request_params(include_sub_agents: bool, limit: usize) ->
     json!({
         "cursor": Value::Null,
         "limit": limit,
-        "sortKey": Value::Null,
+        "sortKey": "updated_at",
         "modelProviders": Value::Null,
         "sourceKinds": source_kinds,
         "archived": false,
@@ -8212,7 +8258,7 @@ async fn list_workspace_roots(
             Some(json!({
                 "cursor": Value::Null,
                 "limit": limit,
-                "sortKey": Value::Null,
+                "sortKey": "updated_at",
                 "modelProviders": Value::Null,
                 "sourceKinds": ["cli", "vscode", "exec", "appServer", "unknown"],
                 "archived": false,
@@ -13586,16 +13632,15 @@ mod tests {
         let _ = child.wait().await;
     }
 
-    fn test_codex_backend(backend: &Arc<RuntimeBackend>) -> &Arc<AppServerBridge> {
+    fn test_codex_backend(backend: &Arc<RuntimeBackend>) -> Arc<AppServerBridge> {
         backend
-            .codex
-            .as_ref()
+            .codex_backend()
             .expect("expected codex backend in test")
     }
 
     async fn shutdown_test_backend(backend: &Arc<RuntimeBackend>) {
-        if let Some(codex) = &backend.codex {
-            shutdown_test_bridge(codex).await;
+        if let Some(codex) = backend.codex_backend() {
+            shutdown_test_bridge(&codex).await;
         }
         if let Some(opencode) = &backend.opencode {
             shutdown_test_opencode_backend(opencode).await;
@@ -13610,7 +13655,7 @@ mod tests {
         preferred_engine: BridgeRuntimeEngine,
         include_opencode: bool,
     ) -> Arc<RuntimeBackend> {
-        let codex = Some(build_test_bridge(hub.clone()).await);
+        let codex = Arc::new(StdRwLock::new(Some(build_test_bridge(hub.clone()).await)));
         let opencode = if include_opencode {
             Some(build_test_opencode_backend(hub).await)
         } else {