git-watchtower 1.12.1 → 1.12.3

package/bin/git-watchtower.js

@@ -101,7 +101,7 @@ const store = new Store();
 
 // Web dashboard server
 const { WebDashboardServer } = require('../src/server/web');
-const { Coordinator, Worker, generateProjectId, getActiveCoordinator, writeLock, removeLock } = require('../src/server/coordinator');
+const { Coordinator, Worker, generateProjectId, getActiveCoordinator, tryAcquireLock, finalizeLock, removeLock, removeSocket } = require('../src/server/coordinator');
 
 const PROJECT_ROOT = process.cwd();
 
@@ -419,6 +419,10 @@ let worker = null;
 let projectId = null;
 let webStateInterval = null;
 
+// Periodic update check controller — hoisted to module scope so the exit
+// handler can clean it up regardless of where in start() we are.
+let periodicUpdateCheck = null;
+
 function applyConfig(config) {
   // Server settings
   SERVER_MODE = config.server?.mode || 'static';
@@ -481,6 +485,17 @@ function openInBrowser(url) {
   });
 }
 
+/**
+ * Build a localhost URL for the given port.
+ * Centralizes the `http://localhost:${port}` pattern so it's easy to adjust
+ * (e.g. switch protocol or host) in one place.
+ * @param {number} port
+ * @returns {string}
+ */
+function localhostUrl(port) {
+  return `http://localhost:${port}`;
+}
+
 // parseRemoteUrl, buildBranchUrl, detectPlatform, buildWebUrl, extractSessionUrl
 // imported from src/git/remote.js
 
@@ -2123,7 +2138,7 @@ function createStaticServer() {
     return;
   }
 
-  const url = new URL(req.url, `http://localhost:${PORT}`);
+  const url = new URL(req.url, localhostUrl(PORT));
   let pathname = url.pathname;
   const logPath = pathname; // Keep original for logging
 
@@ -2773,7 +2788,7 @@ function setupKeyboardInput() {
 
       case 'o': // Open live server in browser
         if (!NO_SERVER) {
-          const serverUrl = `http://localhost:${PORT}`;
+          const serverUrl = localhostUrl(PORT);
           addLog(`Opening ${serverUrl} in browser...`, 'info');
           openInBrowser(serverUrl);
           render();
@@ -3016,7 +3031,7 @@ async function handleWebAction(action, payload) {
         break;
       case 'openBrowser':
         if (!NO_SERVER) {
-          openInBrowser(`http://localhost:${PORT}`);
+          openInBrowser(localhostUrl(PORT));
           sendResult(true, 'Opened in browser');
         }
         break;
@@ -3089,44 +3104,64 @@ async function startWebDashboard(openBrowser) {
     if (url) webDashboard.setRepoWebUrl(url);
   }).catch(() => {});
 
-  // Check if a coordinator is already running
-  const existing = getActiveCoordinator();
+  // Atomically try to claim the coordinator role. If another live instance
+  // already owns the lock, connect as a worker instead. This prevents a
+  // TOCTOU race where two instances both pass a "no coordinator" check and
+  // then clobber each other's socket in Coordinator.start().
+  const lockResult = tryAcquireLock(process.pid);
 
-  if (existing) {
-    // Connect as a worker to the existing coordinator
-    try {
-      worker = new Worker({
-        id: projectId,
-        projectPath: PROJECT_ROOT,
-        projectName: path.basename(PROJECT_ROOT),
-        socketPath: existing.socketPath,
-      });
-      worker.onCommand = (action, payload) => handleWebAction(action, payload);
-      await worker.connect();
-      addLog(`Joined web dashboard at http://localhost:${existing.port} (tab)`, 'success');
-
-      // Push state periodically
-      webStateInterval = setInterval(() => {
-        if (worker && worker.isConnected()) {
-          worker.pushState(webDashboard.getSerializableState());
-        } else {
-          clearInterval(webStateInterval);
-          webStateInterval = null;
-        }
-      }, 500);
+  if (!lockResult.acquired) {
+    const existing = lockResult.existing || getActiveCoordinator();
+    if (existing) {
+      try {
+        worker = new Worker({
+          id: projectId,
+          projectPath: PROJECT_ROOT,
+          projectName: path.basename(PROJECT_ROOT),
+          socketPath: existing.socketPath,
+        });
+        worker.onCommand = (action, payload) => handleWebAction(action, payload);
+        await worker.connect();
+        addLog(`Joined web dashboard at ${localhostUrl(existing.port)} (tab)`, 'success');
+
+        // Push state periodically
+        webStateInterval = setInterval(() => {
+          if (worker && worker.isConnected()) {
+            worker.pushState(webDashboard.getSerializableState());
+          } else {
+            clearInterval(webStateInterval);
+            webStateInterval = null;
+          }
+        }, 500);
 
-      // Don't start our own server — piggyback on the coordinator's.
-      // Don't open browser either — the existing tab will show this project automatically.
-      WEB_PORT = existing.port;
-      render();
-      return;
-    } catch (err) {
-      // Couldn't connect — become coordinator instead
-      worker = null;
+        // Don't start our own server — piggyback on the coordinator's.
+        // Don't open browser either — the existing tab will show this project automatically.
+        WEB_PORT = existing.port;
+        render();
+        return;
+      } catch (err) {
+        // Another coordinator owns the lock but we can't talk to it. Do NOT
+        // take over (that would unlink the live coordinator's socket). Run
+        // without a web dashboard for this instance.
+        worker = null;
+        addLog(`Could not join web dashboard at ${localhostUrl(existing.port)}: ${err.message}`, 'error');
+        webDashboard = null;
+        render();
+        return;
+      }
     }
+    // Lock exists but we couldn't claim it and couldn't read the owner.
+    // Bail out rather than race a concurrent startup.
+    addLog('Web dashboard unavailable: could not acquire coordinator lock', 'error');
+    webDashboard = null;
+    render();
+    return;
   }
 
-  // We are the coordinator
+  // We hold the lock — it is now safe to remove any leftover socket and
+  // start listening. The lock file contains a placeholder pid-only entry
+  // until finalizeLock() writes the real port/socketPath after a successful
+  // bind.
   try {
     coordinator = new Coordinator();
     coordinator.onProjectsChanged = (projects) => {
@@ -3140,7 +3175,12 @@ async function startWebDashboard(openBrowser) {
     await coordinator.start();
     coordinator.registerLocal(projectId, PROJECT_ROOT, path.basename(PROJECT_ROOT), webDashboard.getSerializableState());
 
-    // Update coordinator with our latest state periodically
+    const { port } = await webDashboard.start();
+    WEB_PORT = port;
+    finalizeLock(process.pid, port, coordinator.socketPath);
+
+    // Update coordinator with our latest state periodically. Started only
+    // after a successful bind so a failed start doesn't leak an interval.
     webStateInterval = setInterval(() => {
       if (coordinator && webDashboard) {
         coordinator.updateLocal(projectId, webDashboard.getSerializableState());
@@ -3150,15 +3190,16 @@ async function startWebDashboard(openBrowser) {
       }
     }, 500);
 
-    const { port } = await webDashboard.start();
-    WEB_PORT = port;
-    writeLock(process.pid, port, coordinator.socketPath);
-
-    addLog(`Web dashboard: http://localhost:${port}`, 'success');
-    if (openBrowser) openInBrowser(`http://localhost:${port}`);
+    addLog(`Web dashboard: ${localhostUrl(port)}`, 'success');
+    if (openBrowser) openInBrowser(localhostUrl(port));
     render();
   } catch (err) {
     addLog(`Web dashboard failed: ${err.message}`, 'error');
+    if (coordinator) {
+      try { coordinator.stop(); } catch (_) { /* ignore */ }
+    }
+    removeLock();
+    removeSocket();
     webDashboard = null;
     coordinator = null;
     render();
@@ -3285,6 +3326,11 @@ async function shutdown() {
 
 process.on('SIGINT', shutdown);
 process.on('SIGTERM', shutdown);
+// Clean up long-lived timers on exit, regardless of which code path got us
+// here (normal exit, uncaught exception, early failure in start()).
+process.on('exit', () => {
+  if (periodicUpdateCheck) periodicUpdateCheck.stop();
+});
 process.on('uncaughtException', async (err) => {
   telemetry.captureError(err);
   write(ansi.showCursor);
@@ -3413,11 +3459,11 @@ async function start() {
     // Static mode
     server = createStaticServer();
     server.listen(PORT, '127.0.0.1', () => {
-      addLog(`Server started on http://localhost:${PORT}`, 'success');
+      addLog(`Server started on ${localhostUrl(PORT)}`, 'success');
       addLog(`Serving ${STATIC_DIR.replace(PROJECT_ROOT, '.')}`, 'info');
       addLog(`Current branch: ${store.get('currentBranch')}`, 'info');
       // Add server log entries for static server
-      addServerLog(`Static server started on http://localhost:${PORT}`);
+      addServerLog(`Static server started on ${localhostUrl(PORT)}`);
       addServerLog(`Serving files from: ${STATIC_DIR.replace(PROJECT_ROOT, '.')}`);
       addServerLog(`Live reload enabled - waiting for browser connections...`);
       render();
@@ -3468,8 +3514,9 @@ async function start() {
     }
   }).catch(() => {});
 
-  // Re-check for updates periodically (every 4 hours) while running
-  const periodicCheck = startPeriodicUpdateCheck((latestVersion) => {
+  // Re-check for updates periodically (every 4 hours) while running.
+  // Assigned to module scope so the top-level exit handler can stop it.
+  periodicUpdateCheck = startPeriodicUpdateCheck((latestVersion) => {
     const alreadyKnown = store.get('updateAvailable');
     store.setState({ updateAvailable: latestVersion });
     if (!alreadyKnown) {
@@ -3479,9 +3526,6 @@ async function start() {
     }
     render();
   });
-
-  // Clean up periodic check on exit
-  process.on('exit', () => periodicCheck.stop());
 }
 
 start().catch(err => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "git-watchtower",
-  "version": "1.12.1",
+  "version": "1.12.3",
   "description": "Terminal-based Git branch monitor with activity sparklines and optional dev server with live reload",
   "main": "bin/git-watchtower.js",
   "bin": {

package/src/cli/args.js

@@ -175,7 +175,15 @@ function parseArgs(argv, options = {}) {
  * @returns {object} Merged config
  */
 function applyCliArgsToConfig(config, cliArgs) {
-  const merged = JSON.parse(JSON.stringify(config)); // deep clone
+  // Shallow clone with nested object spreading — the config is at most two
+  // levels deep and all values are primitives, so this is equivalent to a deep
+  // clone but avoids the JSON round-trip (which silently drops `undefined`,
+  // functions, and throws on circular refs).
+  const merged = {
+    ...config,
+    server: { ...config.server },
+    web: { ...config.web },
+  };
 
   // Server settings
   if (cliArgs.mode !== null) {

package/src/server/coordinator.js

@@ -68,13 +68,18 @@ function isProcessAlive(pid) {
 
 /**
  * Read the lock file.
- * @returns {{ pid: number, port: number, socketPath: string } | null}
+ *
+ * A lock may be a placeholder (pid only, no port/socketPath) while a new
+ * coordinator is still binding its socket. Callers that need a connectable
+ * coordinator should use getActiveCoordinator(), which rejects placeholders.
+ *
+ * @returns {{ pid: number, port?: number, socketPath?: string, pending?: boolean } | null}
  */
 function readLock() {
   try {
     if (!fs.existsSync(LOCK_FILE)) return null;
     const data = JSON.parse(fs.readFileSync(LOCK_FILE, 'utf8'));
-    if (!data || !data.pid || !data.port) return null;
+    if (!data || !data.pid) return null;
     return data;
   } catch (e) {
     return null;
@@ -92,6 +97,66 @@ function writeLock(pid, port, socketPath) {
   fs.writeFileSync(LOCK_FILE, JSON.stringify({ pid, port, socketPath }, null, 2) + '\n', 'utf8');
 }
 
+/**
+ * Atomically reserve the coordinator lock.
+ *
+ * Uses `fs.openSync(..., 'wx')` to create the lock file exclusively, so two
+ * instances racing to become coordinator cannot both succeed. A placeholder
+ * entry ({ pid, pending: true }) is written immediately so that any process
+ * reading the lock while we bind our socket still sees a valid owning PID.
+ *
+ * If the lock already exists but the owning process is dead, the stale lock
+ * (and socket) are cleaned up and the acquisition is retried once.
+ *
+ * @param {number} pid - PID of the acquiring process
+ * @returns {{acquired: true} | {acquired: false, existing: {pid: number, port?: number, socketPath?: string, pending?: boolean} | null}}
+ */
+function tryAcquireLock(pid) {
+  ensureDir();
+
+  // One retry after stale-lock cleanup; avoids looping if another process
+  // keeps recreating the lock faster than we can clean it up.
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const fd = fs.openSync(LOCK_FILE, 'wx');
+      try {
+        fs.writeSync(fd, JSON.stringify({ pid, pending: true }) + '\n');
+      } finally {
+        fs.closeSync(fd);
+      }
+      return { acquired: true };
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+
+      // Lock file exists — check if the owner is alive.
+      const existing = readLock();
+      if (existing && isProcessAlive(existing.pid)) {
+        return { acquired: false, existing };
+      }
+      // Stale or unreadable — clean up and retry the exclusive create.
+      removeLock();
+      removeSocket();
+    }
+  }
+
+  // Another process raced us to re-create the lock. Treat it as active.
+  const existing = readLock();
+  return { acquired: false, existing: existing || null };
+}
+
+/**
+ * Replace the placeholder lock with the final port/socket details after the
+ * coordinator has successfully bound its IPC socket and the web server has
+ * started listening. Caller must already own the lock via tryAcquireLock().
+ *
+ * @param {number} pid
+ * @param {number} port
+ * @param {string} socketPath
+ */
+function finalizeLock(pid, port, socketPath) {
+  writeLock(pid, port, socketPath);
+}
+
 /**
  * Remove the lock file.
  */
@@ -107,18 +172,25 @@ function removeSocket() {
 }
 
 /**
- * Check if a coordinator is already running.
- * Cleans up stale lock if the process is dead.
+ * Check if a coordinator is already running and reachable.
+ *
+ * Returns null for stale locks (cleans them up) and for placeholder locks
+ * that haven't finished binding yet — callers shouldn't try to connect to
+ * a coordinator that isn't listening.
+ *
  * @returns {{ pid: number, port: number, socketPath: string } | null}
  */
 function getActiveCoordinator() {
   const lock = readLock();
   if (!lock) return null;
-  if (isProcessAlive(lock.pid)) return lock;
-  // Stale lock — clean up
-  removeLock();
-  removeSocket();
-  return null;
+  if (!isProcessAlive(lock.pid)) {
+    removeLock();
+    removeSocket();
+    return null;
+  }
+  // Placeholder (pending) — coordinator is still binding.
+  if (!lock.port || !lock.socketPath) return null;
+  return /** @type {{pid:number,port:number,socketPath:string}} */ (lock);
 }
 
 // ─── Coordinator (first instance) ────────────────────────────────
@@ -533,6 +605,8 @@ module.exports = {
   getActiveCoordinator,
   readLock,
   writeLock,
+  tryAcquireLock,
+  finalizeLock,
   removeLock,
   removeSocket,
   isProcessAlive,