@stravica-ai/digital-operator-pa 0.1.49 → 0.1.50

package/dist/engineering-pa-workspace/src/ws.mjs

@@ -96,6 +96,7 @@ function hasFlag(name) {
 function resolvePort() {
   // 1. Default
   let port = 4200;
+  let explicit = false;
 
   // 2. Preferences override — device-local overlay wins over the shared base
   // (see @stravica-ai/engineering-pa-core/src/preferences.mjs).
@@ -104,7 +105,9 @@ function resolvePort() {
     if (prefs && prefs.workspacePort) port = prefs.workspacePort;
   } catch { /* no prefs — use default */ }
 
-  // 3. CLI flag override
+  // 3. CLI flag override — an explicit `--port` disables the auto-probe
+  // (item 3, 0.1.50). The operator asked for this exact port, so we
+  // hard-fail on collision rather than picking a different one silently.
   const flagPort = getFlag('--port');
   if (flagPort) {
     const parsed = parseInt(flagPort, 10);
@@ -113,9 +116,10 @@ function resolvePort() {
       process.exit(1);
     }
     port = parsed;
+    explicit = true;
   }
 
-  return port;
+  return { port, explicit };
 }
 
 // --- PID file helpers ---
@@ -148,6 +152,45 @@ function isProcessAlive(pid) {
   }
 }
 
+// 0.1.50 (item 3): probe upward from `startPort` until a free port is
+// found or `maxAttempts` is exhausted. Returns the chosen port or null
+// when the whole window is busy. Bounded so a runaway loop cannot
+// happen; 20 attempts is plenty for a solo instance's usual crowding.
+async function probeFreePortUpward(startPort, maxAttempts) {
+  for (let i = 0; i < maxAttempts; i++) {
+    const p = startPort + i;
+    if (p > 65535) return null;
+    // eslint-disable-next-line no-await-in-loop
+    const busy = await checkPort(p);
+    if (!busy) return p;
+  }
+  return null;
+}
+
+// 0.1.50 (item 3): write the chosen workspace port back to
+// `operator/config/preferences.json:workspacePort`. Preserves field
+// order and 2-space indent so a git diff of preferences shows only
+// the port change.
+function writeWorkspacePortToPreferences(repoRoot, port) {
+  const path = join(repoRoot, 'operator', 'config', 'preferences.json');
+  let raw;
+  try {
+    raw = readFileSync(path, 'utf8');
+  } catch (e) {
+    if (e && e.code === 'ENOENT') {
+      // No preferences at all yet — write a minimal file. The scaffold
+      // ships one for every solo instance so this branch is rare.
+      writeFileSync(path, JSON.stringify({ workspacePort: port }, null, 2) + '\n');
+      return;
+    }
+    throw e;
+  }
+  const parsed = JSON.parse(raw);
+  parsed.workspacePort = port;
+  const hadTrailingNewline = raw.endsWith('\n');
+  writeFileSync(path, JSON.stringify(parsed, null, 2) + (hadTrailingNewline ? '\n' : ''));
+}
+
 function checkPort(port, timeoutMs = 1000) {
   return new Promise((resolve) => {
     const sock = createConnection({ host: '127.0.0.1', port }, () => {
@@ -282,7 +325,10 @@ function formatUptime(ms) {
 // --- Commands ---
 
 async function cmdStart() {
-  const port = resolvePort();
+  const resolved = resolvePort();
+  let { port } = resolved;
+  const explicitPort = resolved.explicit;
+  const noProbe = hasFlag('--no-probe');
   const noOpen = hasFlag('--no-open');
 
   // Supervisor-aware short-circuit. When launchd / systemd is managing the
@@ -342,11 +388,34 @@ async function cmdStart() {
     removePid();
   }
 
-  // Check if port is already in use by something else
+  // Check if port is already in use by something else.
+  //
+  // 0.1.50 (item 3): when neither `--port <N>` nor `--no-probe` was
+  // passed, probe upward from max(configured+1, 4210) up to 20
+  // attempts. Persist the chosen port back to
+  // `operator/config/preferences.json:workspacePort` so subsequent
+  // `pa status` / `pa workspace open` calls read the same port. An
+  // explicit `--port` or `--no-probe` keeps the strict hard-fail.
   if (await checkPort(port)) {
-    console.error(`Error: Port ${port} is already in use by another process.`);
-    console.error('Hint: run `pa workspace start --port <N>` with a free port, or set `workspacePort` in operator/config/preferences.json.');
-    process.exit(1);
+    if (explicitPort || noProbe) {
+      console.error(`Error: Port ${port} is already in use by another process.`);
+      console.error('Hint: run `pa workspace start --port <N>` with a free port, or set `workspacePort` in operator/config/preferences.json.');
+      process.exit(1);
+    }
+    const configuredPort = port;
+    const chosen = await probeFreePortUpward(Math.max(port + 1, 4210), 20);
+    if (chosen === null) {
+      console.error(`Error: Port ${configuredPort} is busy and no free port was found in 20 attempts starting from ${Math.max(configuredPort + 1, 4210)}.`);
+      console.error('Hint: run `pa workspace start --port <N>` with a free port, or set `workspacePort` in operator/config/preferences.json.');
+      process.exit(1);
+    }
+    port = chosen;
+    try {
+      writeWorkspacePortToPreferences(REPO_ROOT, port);
+    } catch (e) {
+      console.error(`Warning: failed to persist chosen port to preferences: ${e.message}`);
+    }
+    console.log(`Port ${configuredPort} busy; started on ${port} instead (persisted to operator/config/preferences.json).`);
   }
 
   // Build spawn args
@@ -473,7 +542,7 @@ async function cmdRestart() {
       // launchctl kickstart -k can return before the new PID is published.
       console.log(`Workspace server restart requested (supervised by ${supervisor.kind}).`);
     }
-    const port = resolvePort();
+    const { port } = resolvePort();
     console.log(`  http://127.0.0.1:${port}`);
     return;
   }
@@ -489,7 +558,7 @@ async function cmdStatus() {
   // itself spawned the server, so a supervised process is invisible to the
   // pidfile-only check (bug 1 of 2 in this PR).
   if (supervisor.kind) {
-    const port = resolvePort();
+    const { port } = resolvePort();
     const sup = readSupervisorState(supervisor);
     const listener = findPortListener(port);
     const portUp = await checkPort(port);
@@ -574,7 +643,7 @@ async function cmdOpen() {
   // socket directly.
   const supervisor = getSupervisor();
   if (supervisor.kind) {
-    const port = resolvePort();
+    const { port } = resolvePort();
     const portUp = await checkPort(port);
     if (!portUp) {
       console.error(`Error: Workspace is ${supervisor.kind}-managed but port ${port} is not responding.`);

package/docs/onboarding-solo.md

@@ -8,7 +8,7 @@ Working installs of the following, then sign in to Claude Code:
 
 - Node.js 24 or newer: https://nodejs.org (or your platform's Node 24 channel; on macOS `brew install node@24`)
 - pnpm: https://pnpm.io/installation (or `brew install pnpm`)
-- git: https://git-scm.com (or `brew install git`) with your identity already configured
+- git: https://git-scm.com (or `brew install git`). `pa-init` runs `git init` inside the instance; you will need `user.name` and `user.email` set globally (via `git config --global user.name / user.email`) before your first commit, but the scaffold itself does not commit.
 - Claude Code CLI: https://claude.ai/install (or `brew install --cask claude-code`). Run `claude` once, sign in, then Ctrl-C.
 
 Do not install Claude Code with `npm -g` or `sudo npm -g`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stravica-ai/digital-operator-pa",
-  "version": "0.1.49",
+  "version": "0.1.50",
   "description": "Digital Operator PA — single-bundled public package surface (bins + library) for the platform.",
   "type": "module",
   "main": "./index.mjs",