@axiomatic-labs/claudeflow 2.13.58 → 2.13.60

package/lib/doctor.js

@@ -129,21 +129,66 @@ function checkStaleLockfiles(cwd) {
   };
 }
 
-// Read the browser-error-daemon observer state from its pidfile.
-// Returns { running, pid, lockfile } — running=true only when the pid is
-// alive AND the lockfile exists. Used by both doctor and panel.
-function readObserverState(cwd, cdpPort) {
-  const lockfile = path.join(cwd, '.claudeflow', 'tmp', `.browser-cdp-${cdpPort}.pid`);
-  let pid = null;
+// Read the browser-error-daemon observer state. The daemon is the Node
+// process that hosts the HTTP server at error-observer.json's `port` and
+// receives error/network reports from Chrome.
+//
+// CAVEAT — this is NOT the same as Chrome's CDP pidfile:
+//   - `.browser-cdp-{cdpPort}.pid`     → Chrome browser process (CDP port)
+//   - `error-observer.pid` / json     → Node daemon process (observer port)
+// These are two distinct processes. Previous versions of this function
+// looked at the Chrome pidfile and reported the observer "stopped" even
+// when the daemon was alive, because the cdp-port pidfile may not be
+// present when Chrome was started outside of claudeflow's openBrowser().
+//
+// Detection strategy (in order of preference):
+//   1. error-observer.json exists → read its `port` + `pid_path`.
+//   2. If pidfile exists and PID is alive → running=true.
+//   3. Else, TCP probe the observer port via `lsof -i :PORT -sTCP:LISTEN -t`.
+//      The pidfile may be missing (race) but if SOMETHING is listening on
+//      the configured port, the daemon is up.
+function readObserverState(cwd) {
+  const observerJsonPath = path.join(cwd, '.claudeflow', 'tmp', 'error-observer.json');
+  let meta;
   try {
-    pid = parseInt(fs.readFileSync(lockfile, 'utf8').trim(), 10);
+    meta = JSON.parse(fs.readFileSync(observerJsonPath, 'utf8'));
   } catch {
-    return { running: false, pid: null, lockfile };
+    return { running: false, pid: null, port: null, source: 'no-observer-json', observerJsonPath };
+  }
+  if (!meta || typeof meta.port !== 'number') {
+    return { running: false, pid: null, port: null, source: 'observer-json-malformed', observerJsonPath };
+  }
+  const port = meta.port;
+  const pidPath = typeof meta.pid_path === 'string' ? meta.pid_path : null;
+
+  // Try the pidfile first — fastest path.
+  let pid = null;
+  if (pidPath) {
+    try {
+      const p = parseInt(fs.readFileSync(pidPath, 'utf8').trim(), 10);
+      if (Number.isFinite(p) && p > 0) pid = p;
+    } catch {}
+  }
+  if (pid !== null) {
+    let alive = false;
+    try { process.kill(pid, 0); alive = true; } catch (e) { alive = e.code === 'EPERM'; }
+    if (alive) return { running: true, pid, port, source: 'pidfile', observerJsonPath };
   }
-  if (!Number.isFinite(pid) || pid <= 0) return { running: false, pid, lockfile };
-  let alive = false;
-  try { process.kill(pid, 0); alive = true; } catch (e) { alive = e.code === 'EPERM'; }
-  return { running: alive, pid, lockfile };
+
+  // Fallback: TCP probe via lsof. Catches the case where pidfile is missing
+  // but the daemon process is still listening on the port.
+  try {
+    const { spawnSync } = require('child_process');
+    const r = spawnSync('lsof', ['-i', `:${port}`, '-sTCP:LISTEN', '-t'], { encoding: 'utf8', timeout: 1500 });
+    if (r.status === 0 && r.stdout && r.stdout.trim()) {
+      const tcpPid = parseInt(r.stdout.trim().split('\n')[0], 10);
+      if (Number.isFinite(tcpPid) && tcpPid > 0) {
+        return { running: true, pid: tcpPid, port, source: 'tcp-probe', observerJsonPath };
+      }
+    }
+  } catch {}
+
+  return { running: false, pid: pid, port, source: 'no-listener', observerJsonPath };
 }
 
 // Surface as a doctor/panel issue when the browser-error-daemon observer
@@ -161,19 +206,25 @@ function checkObserverState(cwd) {
   if (!hasPlaywright) {
     return { id: 'observer-state', severity: 'info', message: 'Playwright not configured — observer not applicable.' };
   }
-  const observer = readObserverState(cwd, deriveCdpPort(cwd));
+  const observer = readObserverState(cwd);
   if (observer.running) {
     return {
       id: 'observer-state',
       severity: 'ok',
-      message: `browser-error-daemon running (pid ${observer.pid}).`,
+      message: `browser-error-daemon running on port ${observer.port} (pid ${observer.pid}, detected via ${observer.source}).`,
     };
   }
+  // Distinguish "never started" (no observer JSON) from "started then died".
+  const detailMsg = observer.source === 'no-observer-json'
+    ? 'no `.claudeflow/tmp/error-observer.json` — the daemon never started this session. Check `.claude/hooks/SessionStart/browser-error-daemon.js` for failures.'
+    : observer.source === 'observer-json-malformed'
+    ? '`.claudeflow/tmp/error-observer.json` is malformed.'
+    : 'observer JSON exists (port ' + observer.port + ') but no process is listening — the daemon crashed after startup. Tail `.claude/tmp/hooks.log` for the most recent SessionStart entry.';
   return {
     id: 'observer-state',
     severity: 'mismatch',
-    message: 'browser-error-daemon is STOPPED while Playwright is configured. Console errors / network failures from headed sessions are NOT being collected — the agent may verify a flow with console errors and miss them. The observer should auto-start at SessionStart via `.claude/hooks/SessionStart/browser-error-daemon.js`; if it keeps stopping, inspect that hook for crashes or check the pidfile at `.claudeflow/tmp/.browser-cdp-<port>.pid`.',
-    detail: [{ lockfile: observer.lockfile, pid: observer.pid }],
+    message: `browser-error-daemon is STOPPED while Playwright is configured. Console errors / network failures from headed sessions are NOT being collected — the agent may verify a flow with console errors and miss them. Diagnosis: ${detailMsg}`,
+    detail: [{ port: observer.port, source: observer.source, observerJsonPath: observer.observerJsonPath }],
   };
 }
 

package/lib/panel.js

@@ -196,7 +196,7 @@ function getMcpInfo(cwd) {
   const servers = Object.keys(cfg.mcpServers || {});
   const cdp = checkCdpPortMismatch(cwd);
   const reading = readPlaywrightCdpEndpoint(mcpPath);
-  const observer = readObserverState(cwd, deriveCdpPort(cwd));
+  const observer = readObserverState(cwd);
   const lockfiles = checkStaleLockfiles(cwd);
 
   return {
@@ -1458,7 +1458,16 @@ async function restartObserverAction(btn) {
     if (r.ok && result.ok) {
       showToast('Observer restarted — pid ' + (result.observer && result.observer.pid) + '. Refreshing…', 'ok');
     } else {
-      showToast('Restart failed: ' + (result.error || result.script_stderr || 'unknown'), 'err');
+      // The daemon often exits 0 even on failure (it logs the reason to
+      // hooks.log instead of stderr). Surface the richest signal we have.
+      const detail = result.error
+        || (result.recent_log_entry ? result.recent_log_entry.split('\\n').slice(-3).join(' | ') : null)
+        || (result.script_stderr && result.script_stderr.trim())
+        || (result.script_stdout && result.script_stdout.trim())
+        || 'unknown — check .claude/tmp/hooks.log for the most recent SessionStart:browser-error-daemon entry';
+      showToast('Restart failed: ' + detail, 'err');
+      // Also log to browser console for inspection.
+      console.error('[observer-restart] full response:', result);
     }
   } catch (e) {
     showToast('Network error: ' + e.message, 'err');
@@ -1749,7 +1758,8 @@ function handler(cwd) {
         // Re-run the SessionStart/browser-error-daemon.js hook script
         // synchronously. The script calls ensureObserver() which spawns
         // Chrome with --cdp-endpoint as a detached process. Once the
-        // script exits, the daemon is up (or the script logged the failure).
+        // script exits, the daemon is up (or the script logged the failure
+        // to hooks.log even though it exits 0).
         const daemonScript = path.join(cwd, '.claude', 'hooks', 'SessionStart', 'browser-error-daemon.js');
         if (!fs.existsSync(daemonScript)) {
           return send(404, JSON.stringify({ ok: false, error: 'daemon script not found at .claude/hooks/SessionStart/browser-error-daemon.js' }), 'application/json');
@@ -1759,15 +1769,42 @@ function handler(cwd) {
           cwd,
           env: { ...process.env, CLAUDE_PROJECT_DIR: cwd },
           encoding: 'utf8',
-          timeout: 15000,
+          // Chrome can take 5-10s to spawn cleanly; allow headroom + network probe.
+          timeout: 30000,
         });
-        const observerState = readObserverState(cwd, deriveCdpPort(cwd));
+        const observerState = readObserverState(cwd);
+        // Tail the most recent SessionStart entry from hooks.log — the
+        // daemon writes the failure reason there even when it exits 0.
+        let recentLogEntry = null;
+        try {
+          const logPath = path.join(cwd, '.claude', 'tmp', 'hooks.log');
+          const raw = fs.readFileSync(logPath, 'utf8');
+          const lines = raw.split('\n');
+          // Walk backwards, find the most recent block whose hook_file
+          // mentions browser-error-daemon.js.
+          for (let i = lines.length - 1; i >= 0; i--) {
+            if (/browser-error-daemon\.js/.test(lines[i])) {
+              recentLogEntry = lines.slice(Math.max(0, i - 1), Math.min(lines.length, i + 5)).join('\n');
+              break;
+            }
+          }
+        } catch {}
         const ok = observerState.running;
+        const reason = !ok
+          ? (r.error ? `spawn error: ${r.error.message}` :
+             r.signal ? `script killed by signal ${r.signal} (timed out?)` :
+             r.status !== 0 ? `script exit ${r.status}` :
+             'script exited 0 but observer pid still not alive — the daemon failed to bind Chrome to the CDP port. See script_stdout + recent_log_entry below.')
+          : null;
         return send(ok ? 200 : 500, JSON.stringify({
           ok,
           observer: observerState,
           script_exit: r.status,
-          script_stderr: (r.stderr || '').slice(0, 500),
+          script_signal: r.signal || null,
+          script_stdout: (r.stdout || '').slice(0, 2000),
+          script_stderr: (r.stderr || '').slice(0, 2000),
+          recent_log_entry: recentLogEntry,
+          error: reason,
         }), 'application/json');
       }
 
@@ -1802,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(() => {
@@ -1821,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');
   });
 }
 
@@ -1830,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
@@ -1845,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.58",
+  "version": "2.13.60",
   "description": "Claudeflow — AI-powered development toolkit for Claude Code. Skills, agents, hooks, and quality gates that ship production apps.",
   "bin": {
     "claudeflow": "./bin/cli.js"