@axiomatic-labs/claudeflow 2.13.59 → 2.13.61

package/lib/doctor.js

@@ -149,13 +149,36 @@ function checkStaleLockfiles(cwd) {
 //      the configured port, the daemon is up.
 function readObserverState(cwd) {
   const observerJsonPath = path.join(cwd, '.claudeflow', 'tmp', 'error-observer.json');
-  let meta;
-  try {
-    meta = JSON.parse(fs.readFileSync(observerJsonPath, 'utf8'));
-  } catch {
-    return { running: false, pid: null, port: null, source: 'no-observer-json', observerJsonPath };
+  // Defense-in-depth retry: even though the daemon now writes atomically
+  // (rename-after-write), older daemon versions and any future non-atomic
+  // writer would expose a 0-byte window during overwrite. We retry up to
+  // 3 times with a tiny pause between attempts so a transient empty read
+  // doesn't flip the panel UI between running/stopped every refresh.
+  let meta = null;
+  let lastErr = null;
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    try {
+      const raw = fs.readFileSync(observerJsonPath, 'utf8');
+      if (raw.trim()) {
+        meta = JSON.parse(raw);
+        break;
+      }
+      lastErr = new Error('empty file');
+    } catch (e) {
+      lastErr = e;
+      if (e.code === 'ENOENT') break; // file genuinely missing — no retry helps
+    }
+    if (attempt < 2) {
+      // Sync sleep (~30ms) via spawnSync — sufficient to outlast a writeFile race.
+      const { spawnSync } = require('child_process');
+      spawnSync('sleep', ['0.03']);
+    }
+  }
+  if (!meta) {
+    const source = (lastErr && lastErr.code === 'ENOENT') ? 'no-observer-json' : 'observer-json-malformed';
+    return { running: false, pid: null, port: null, source, observerJsonPath };
   }
-  if (!meta || typeof meta.port !== 'number') {
+  if (typeof meta.port !== 'number') {
     return { running: false, pid: null, port: null, source: 'observer-json-malformed', observerJsonPath };
   }
   const port = meta.port;

package/lib/panel.js

@@ -1839,14 +1839,47 @@ function openInBrowser(url) {
   } catch {}
 }
 
-function start({ cwd = process.cwd(), port = 0, openBrowser = true } = {}) {
+// Derive a stable port from the cwd. Without this, every panel restart picks
+// a different random port and any open browser tab pointing at the OLD port
+// becomes a dead bookmark — confusingly, the bookmark keeps rendering the
+// last-known UI state because /api/status fails silently. Range 9300-9399
+// (above Chrome CDP's 9200-9299).
+function derivePanelPort(projectPath) {
+  const crypto = require('crypto');
+  const hash = crypto.createHash('sha1').update(projectPath).digest();
+  return 9300 + (hash.readUInt16BE(0) % 100);
+}
+
+function start({ cwd = process.cwd(), port = null, openBrowser = true } = {}) {
   const server = http.createServer(handler(cwd));
   let lastActivity = Date.now();
   server.on('request', () => { lastActivity = Date.now(); });
 
+  // Port resolution:
+  //   - explicit port arg (e.g. --port=9999) → use as-is
+  //   - port === 0 → OS-assigned random (legacy behavior, retained for tests)
+  //   - default (null) → derive from cwd; on EADDRINUSE fall back to OS-assigned
+  const explicitPort = typeof port === 'number' && port > 0;
+  const derivedPort = port === null ? derivePanelPort(cwd) : null;
+  const initialPort = explicitPort ? port : (derivedPort !== null ? derivedPort : 0);
+
   return new Promise((resolve, reject) => {
-    server.once('error', reject);
-    server.listen(port, '127.0.0.1', () => {
+    let usingFallback = false;
+    server.on('error', (err) => {
+      if (err.code === 'EADDRINUSE' && !usingFallback && !explicitPort) {
+        // Another process holds the derived port. Fall back to OS-assigned
+        // so the panel can still start, but warn the user — they may have
+        // another panel running for this project, or unrelated process took
+        // the port.
+        usingFallback = true;
+        console.error(`\n  [panel] derived port ${initialPort} is in use — falling back to OS-assigned port.`);
+        console.error(`  [panel] If another \`claudeflow panel\` is running for this project, kill it first to recover URL stability.\n`);
+        server.listen(0, '127.0.0.1');
+        return;
+      }
+      reject(err);
+    });
+    server.on('listening', () => {
       const addr = server.address();
       const url = `http://127.0.0.1:${addr.port}`;
       const idleTimer = setInterval(() => {
@@ -1858,8 +1891,9 @@ function start({ cwd = process.cwd(), port = 0, openBrowser = true } = {}) {
       }, 60 * 1000);
       idleTimer.unref();
       if (openBrowser) openInBrowser(url);
-      resolve({ url, server });
+      resolve({ url, server, derivedPort, usedFallback: usingFallback });
     });
+    server.listen(initialPort, '127.0.0.1');
   });
 }
 
@@ -1867,13 +1901,18 @@ async function run(argv = []) {
   const cwd = process.cwd();
   const noOpen = argv.includes('--no-open');
   const portArg = argv.find((a) => a.startsWith('--port='));
-  const port = portArg ? parseInt(portArg.split('=')[1], 10) : 0;
+  // Default port (null) → derive from cwd so the URL is stable across restarts.
+  // --port=N overrides; --port=0 keeps the legacy OS-assigned behavior.
+  const port = portArg ? parseInt(portArg.split('=')[1], 10) : null;
 
   ui.banner();
   console.log(`  Starting panel for ${ui.CYAN}${cwd}${ui.RESET}`);
-  const { url } = await start({ cwd, port, openBrowser: !noOpen });
+  const { url, derivedPort, usedFallback } = await start({ cwd, port, openBrowser: !noOpen });
   console.log('');
   console.log(`  ${ui.GREEN}▸${ui.RESET} ${ui.CYAN}${url}${ui.RESET}`);
+  if (derivedPort !== null && !usedFallback) {
+    console.log(`  ${ui.DIM}Port ${derivedPort} is derived from the cwd — same URL across restarts.${ui.RESET}`);
+  }
   console.log(`  ${ui.DIM}Ctrl+C to stop. Auto-shutdown after 30 min idle.${ui.RESET}`);
   console.log('');
   return new Promise(() => {}); // keep alive
@@ -1882,6 +1921,7 @@ async function run(argv = []) {
 module.exports = run;
 module.exports.start = start;
 module.exports.createPanelServer = handler;
+module.exports.derivePanelPort = derivePanelPort;
 module.exports.collectStatus = collectStatus;
 module.exports.getClaudeMdInfo = getClaudeMdInfo;
 module.exports.getHooksInfo = getHooksInfo;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiomatic-labs/claudeflow",
-  "version": "2.13.59",
+  "version": "2.13.61",
   "description": "Claudeflow — AI-powered development toolkit for Claude Code. Skills, agents, hooks, and quality gates that ship production apps.",
   "bin": {
     "claudeflow": "./bin/cli.js"