fix(one): default to port 8787 and stop the double port-selection hang

Two related fixes for the "service hangs when 3000 is busy" report:

1. The shell (Rust) picked a free port and probed it, while the Node
   launcher independently re-ran its own free-port selection. When those
   diverged (a port taken in the race window), the runtime served on one
   port while the splash probed another — hanging on "Starting local
   runtime…" until the 120s deadline. The shell now sets OBJECTOS_MANAGED=1
   and one.mjs honors the exact PORT it was handed (exiting for a clean
   supervised restart if it's no longer free) instead of re-selecting.

2. Default port moved off 3000 → 8787. 3000 collides with Next.js/Vite/CRA
   and most local dev servers, causing a different port every launch and
   widening the race window. 8787 is quiet, so the URL stays stable.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: os-zhuang

apps/objectos-one/README.md

@@ -53,7 +53,7 @@ Commonly used keys:
 
 | Key             | Default          | Notes                                                            |
 |-----------------|------------------|------------------------------------------------------------------|
-| `PORT`          | auto (3000+)     | Fixed port. If in use, falls back to auto with a log line.       |
+| `PORT`          | auto (8787+)     | Fixed port. If in use, falls back to auto with a log line.       |
 | `HOST`          | `127.0.0.1`      | `0.0.0.0` exposes the server to the LAN. **Set up auth first.**  |
 | `OBJECTOS_HOME` | `~/.objectstack` | Data directory. Absolute path.                                   |
 | `LOG_LEVEL`     | —                | Forwarded to the Node server.                                    |

apps/objectos-one/src-tauri/Cargo.lock

@@ -47,6 +47,13 @@ const MAX_CRASH_RESTARTS: u32 = 5;
 /// Sidecar considered "healthy" after this much uptime; resets crash count.
 const STABLE_AFTER: Duration = Duration::from_secs(60);
 
+/// Default port to start scanning from when the user hasn't pinned `PORT`.
+/// Deliberately *not* 3000 — that range collides with Next.js, Vite, CRA and
+/// most other local dev servers, which both causes frequent fallback churn
+/// (a different port every launch) and widens the window for the
+/// pick-a-port / bind-a-port race the Node launcher used to have.
+const DEFAULT_PORT: u16 = 8787;
+
 pub fn kill_current(app: &AppHandle) {
     let state: tauri::State<Sidecar> = app.state();
     let taken = state.0.lock().unwrap().take();
@@ -146,9 +153,9 @@ fn spawn_sidecar(app: &AppHandle) -> Result<Child, String> {
                 "WARN",
                 &format!("PORT {fixed} on {host} in use; auto-selecting"),
             );
-            pick_free_port(&host, 3000)
+            pick_free_port(&host, DEFAULT_PORT)
         }
-        None => pick_free_port(&host, 3000),
+        None => pick_free_port(&host, DEFAULT_PORT),
     };
     if port == 0 {
         return Err("no free port available".into());
@@ -166,7 +173,12 @@ fn spawn_sidecar(app: &AppHandle) -> Result<Child, String> {
     cmd.env("OBJECTOS_HOME", &data_dir)
         .env("PORT", port.to_string())
         .env("HOST", &host)
-        .env("OBJECTOS_NO_OPEN", "1");
+        .env("OBJECTOS_NO_OPEN", "1")
+        // We already picked a free port above and the readiness probe below
+        // watches *this exact* port. Tell the launcher not to re-select its
+        // own port: if it bound a different one, the probe would wait out its
+        // full deadline on a dead port and the UI would hang on the splash.
+        .env("OBJECTOS_MANAGED", "1");
 
     let mut child = cmd.spawn().map_err(|e| format!("spawn node: {e}"))?;
 

apps/objectos-one/src-tauri/src/sidecar.rs

@@ -189,7 +189,7 @@ <h1>Environment variables</h1>
 
       <div class="presets">
         Quick add:
-        <button data-key="PORT" data-val="3000">PORT</button>
+        <button data-key="PORT" data-val="8787">PORT</button>
         <button data-key="HOST" data-val="0.0.0.0">HOST=0.0.0.0 (LAN)</button>
         <button data-key="OBJECTOS_HOME" data-val="">OBJECTOS_HOME</button>
         <button data-key="LOG_LEVEL" data-val="debug">LOG_LEVEL</button>

apps/objectos-one/src/prefs.html

@@ -28,6 +28,11 @@ import { fileURLToPath } from 'node:url';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const APP_NAME = 'ObjectOS';
 
+// Default port to start from when PORT isn't pinned. Deliberately off 3000 —
+// that range collides with Next.js/Vite/CRA and most local dev servers, so a
+// quieter default means a stable, predictable URL across launches.
+const DEFAULT_PORT = 8787;
+
 function userDataDir() {
   if (process.env.OBJECTOS_HOME) return process.env.OBJECTOS_HOME;
   return join(homedir(), '.objectstack');
@@ -50,21 +55,55 @@ function ensureDir(p) {
   return p;
 }
 
+function isPortFree(port) {
+  return new Promise((resolveTry) => {
+    const srv = createServer();
+    srv.once('error', () => resolveTry(false));
+    srv.once('listening', () => srv.close(() => resolveTry(true)));
+    srv.listen(port, '127.0.0.1');
+  });
+}
+
 async function findFreePort(preferred) {
-  const tryPort = (port) =>
-    new Promise((resolveTry) => {
-      const srv = createServer();
-      srv.once('error', () => resolveTry(false));
-      srv.once('listening', () => srv.close(() => resolveTry(true)));
-      srv.listen(port, '127.0.0.1');
-    });
-  if (await tryPort(preferred)) return preferred;
+  if (await isPortFree(preferred)) return preferred;
   for (let p = preferred + 1; p < preferred + 50; p++) {
-    if (await tryPort(p)) return p;
+    if (await isPortFree(p)) return p;
   }
   return 0;
 }
 
+/**
+ * Resolve the port to serve on.
+ *
+ * Two modes:
+ *   - Managed (OBJECTOS_MANAGED=1): the ObjectOS One shell already picked a
+ *     free port, set PORT, and is probing/navigating to *that exact* port.
+ *     We must honor it verbatim — re-selecting our own would strand the UI on
+ *     a port nobody serves. If it was taken in the race window since the shell
+ *     checked it, exit so the shell's supervisor respawns us with a fresh one.
+ *   - Standalone (plain `node one.mjs`): pick a free port ourselves, falling
+ *     forward from the preferred/default if it's busy.
+ */
+async function resolvePort() {
+  const preferred = Number(process.env.PORT ?? DEFAULT_PORT);
+  if (process.env.OBJECTOS_MANAGED === '1') {
+    if (await isPortFree(preferred)) return preferred;
+    console.error(
+      `[one] managed port ${preferred} no longer free; exiting for supervisor restart`,
+    );
+    process.exit(75); // EX_TEMPFAIL — supervised restart will pick a new port
+  }
+  const port = await findFreePort(preferred);
+  if (!port) {
+    console.error('[one] no free port available');
+    process.exit(1);
+  }
+  if (port !== preferred) {
+    console.log(`[one] port ${preferred} busy → using ${port}`);
+  }
+  return port;
+}
+
 function openBrowser(url) {
   const cmd =
     platform() === 'darwin' ? 'open'
@@ -118,15 +157,7 @@ async function main() {
     }
   }
 
-  const preferredPort = Number(process.env.PORT ?? 3000);
-  const port = await findFreePort(preferredPort);
-  if (!port) {
-    console.error('[one] no free port available');
-    process.exit(1);
-  }
-  if (port !== preferredPort) {
-    console.log(`[one] port ${preferredPort} busy → using ${port}`);
-  }
+  const port = await resolvePort();
   process.env.PORT = String(port);
 
   const url = `http://localhost:${port}`;

apps/objectos/one.mjs

@@ -8,7 +8,7 @@
   "scripts": {
     "dev": "objectstack dev",
     "build": "objectstack compile",
-    "start": "objectstack serve --port ${PORT:-3000}",
+    "start": "objectstack serve --port ${PORT:-8787}",
     "one": "node one.mjs",
     "type-check": "tsc --noEmit"
   },