jettypod 4.4.118 → 4.4.121

package/lib/merge-lock.js

@@ -1,18 +1,13 @@
 /**
  * Merge Lock - Coordination for Concurrent Instances
  *
- * This module provides lock acquisition and release for merge operations
- * to prevent simultaneous access to main branch across multiple Claude Code instances.
+ * Prevents simultaneous merge operations on main branch.
  *
- * Core principles:
- * - Database is coordination point (simple, reliable serialization)
- * - Polling mechanism with exponential backoff
- * - Automatic cleanup with release() function
- * - Queue position awareness for UX
- * - Process exit handlers for graceful cleanup on SIGINT/SIGTERM/SIGHUP
- * - Global error handlers (uncaughtException/unhandledRejection) prevent orphaned locks
- * - Heartbeat failure detection triggers lock release
- * - Hard timeout (5 min default) kills locks regardless of heartbeat - prevents zombie processes
+ * Stale detection uses PID liveness checks (process.kill(pid, 0)) instead of
+ * heartbeats. If the process that created the lock is dead, the lock is stale.
+ * A 5-minute absolute timeout is kept as a safety net for edge cases (PID reuse).
+ *
+ * No setInterval, no heartbeat, no timers that keep the event loop alive.
  */
 
 const os = require('os');
@@ -22,6 +17,38 @@ let activeLockCleanup = null;
 // Track if global error handlers are registered (only register once per process)
 let globalErrorHandlersRegistered = false;
 
+// Default max lock age: 5 minutes (safety net for PID reuse edge cases)
+const DEFAULT_MAX_LOCK_AGE_MS = 5 * 60 * 1000;
+
+/**
+ * Check if a process is alive by sending signal 0
+ *
+ * @param {number} pid - Process ID to check
+ * @returns {boolean} true if process is alive
+ */
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // ESRCH = no such process, EPERM = process exists but we can't signal it (still alive)
+    return err.code === 'EPERM';
+  }
+}
+
+/**
+ * Parse PID from locked_by string (format: "hostname-pid")
+ *
+ * @param {string} lockedBy - Instance identifier
+ * @returns {number|null} PID or null if unparseable
+ */
+function parsePid(lockedBy) {
+  if (!lockedBy) return null;
+  const parts = lockedBy.split('-');
+  const pid = parseInt(parts[parts.length - 1], 10);
+  return isNaN(pid) ? null : pid;
+}
+
 /**
  * Acquire merge lock for a work item
  *
@@ -43,10 +70,8 @@ async function acquireMergeLock(db, workItemId, instanceId = null, options = {})
     throw new Error('Invalid work item ID: must be a number');
   }
 
-  const maxWait = options.maxWait || 60000; // 1 minute default
-  const pollInterval = options.pollInterval || 1500; // 1.5 seconds
-  const staleThreshold = options.staleThreshold || 15000; // 15 seconds - heartbeat-based stale detection
-  const heartbeatInterval = options.heartbeatInterval || 5000; // 5 seconds default
+  const maxWait = options.maxWait || 60000;
+  const pollInterval = options.pollInterval || 1500;
   const startTime = Date.now();
 
   // Generate instance identifier
@@ -54,56 +79,42 @@ async function acquireMergeLock(db, workItemId, instanceId = null, options = {})
 
   let pollCount = 0;
   let lastStatusTime = 0;
-  const statusInterval = 10000; // Show status every 10 seconds
+  const statusInterval = 10000;
 
   while (Date.now() - startTime < maxWait) {
-    // Cleanup stale locks every 5 polls (every ~10 seconds with 2s poll interval)
-    // This ensures orphaned locks get cleaned up during the wait
+    // Cleanup stale locks every 5 polls
     if (pollCount % 5 === 0) {
       try {
-        const cleaned = await cleanupStaleLocks(db, staleThreshold);
+        const cleaned = await cleanupStaleLocks(db);
         if (cleaned > 0) {
           console.log(`🧹 Cleaned ${cleaned} stale merge lock(s)`);
         }
       } catch (cleanupErr) {
-        // Log but don't fail - cleanup is best-effort
         console.warn(`Warning: Failed to cleanup stale locks: ${cleanupErr.message}`);
       }
     }
     pollCount++;
 
-    // Check if lock exists
     const existingLock = await checkExistingLock(db);
 
     if (!existingLock) {
-      // Try to acquire lock
       try {
         const lockId = await insertLock(db, workItemId, lockedBy);
-
-        // Return lock handle with release function and heartbeat
-        return createLockHandle(db, lockId, lockedBy, workItemId, { heartbeatInterval });
+        return createLockHandle(db, lockId, lockedBy, workItemId);
       } catch (err) {
-        // Race condition - someone else got it first
-        // Continue polling
+        // Race condition - someone else got it first, continue polling
       }
     } else {
-      // Show progress when waiting for existing lock
       const now = Date.now();
       if (now - lastStatusTime >= statusInterval) {
         const waitedSeconds = Math.round((now - startTime) / 1000);
-        const lockAge = await getLockAge(db, existingLock.id);
-        const staleIn = Math.max(0, Math.round((staleThreshold - lockAge) / 1000));
-
-        if (staleIn > 0) {
-          console.log(`⏳ Waiting for merge lock... (${waitedSeconds}s elapsed, lock expires in ~${staleIn}s)`);
-        } else {
-          console.log(`⏳ Waiting for merge lock... (${waitedSeconds}s elapsed, cleaning up stale lock)`);
-        }
+        const pid = parsePid(existingLock.locked_by);
+        const alive = pid ? isProcessAlive(pid) : 'unknown';
+        console.log(`⏳ Waiting for merge lock... (${waitedSeconds}s elapsed, holder PID ${pid || '?'} alive=${alive})`);
         lastStatusTime = now;
       }
     }
 
-    // Wait before retrying
     await sleep(pollInterval);
   }
 
@@ -112,9 +123,6 @@ async function acquireMergeLock(db, workItemId, instanceId = null, options = {})
 
 /**
  * Check if any merge lock currently exists
- *
- * @param {Object} db - SQLite database connection
- * @returns {Promise<Object|null>} Existing lock or null
  */
 function checkExistingLock(db) {
   return new Promise((resolve, reject) => {
@@ -125,34 +133,8 @@ function checkExistingLock(db) {
   });
 }
 
-/**
- * Get the age of a lock based on last heartbeat in milliseconds
- *
- * @param {Object} db - SQLite database connection
- * @param {number} lockId - Lock ID
- * @returns {Promise<number>} Age since last heartbeat in milliseconds
- */
-function getLockAge(db, lockId) {
-  return new Promise((resolve, reject) => {
-    db.get(
-      `SELECT (julianday('now') - julianday(heartbeat_at)) * 86400000 as age_ms
-       FROM merge_locks WHERE id = ?`,
-      [lockId],
-      (err, row) => {
-        if (err) reject(err);
-        else resolve(row ? row.age_ms : 0);
-      }
-    );
-  });
-}
-
 /**
  * Insert lock record into database
- *
- * @param {Object} db - SQLite database connection
- * @param {number} workItemId - Work item ID
- * @param {string} lockedBy - Instance identifier
- * @returns {Promise<number>} Lock ID
  */
 function insertLock(db, workItemId, lockedBy) {
   return new Promise((resolve, reject) => {
@@ -168,76 +150,86 @@ function insertLock(db, workItemId, lockedBy) {
   });
 }
 
-// Default max lock age: 5 minutes (kills zombie processes with active heartbeats)
-const DEFAULT_MAX_LOCK_AGE_MS = 5 * 60 * 1000;
-
 /**
- * Clean up stale locks based on heartbeat timestamp OR absolute age
+ * Clean up stale locks using PID liveness checks + absolute age timeout.
  *
- * Locks are removed if EITHER condition is true:
- * 1. Heartbeat is stale (no heartbeat in staleThreshold ms) - catches dead processes
- * 2. Lock is too old (created more than maxLockAge ms ago) - catches zombie processes
- *    with active event loops that keep heartbeating but never complete
+ * A lock is stale if:
+ * 1. The holding process is dead (PID check), OR
+ * 2. The lock is older than maxLockAge (safety net for PID reuse)
  *
  * @param {Object} db - SQLite database connection
- * @param {number|Object} staleThresholdOrOptions - Age threshold in milliseconds (default: 15000), or options object
- * @param {number} staleThresholdOrOptions.staleThreshold - Heartbeat stale threshold in ms (default: 15000)
- * @param {number} staleThresholdOrOptions.maxLockAge - Maximum lock age in ms regardless of heartbeat (default: 300000 / 5 min)
+ * @param {Object} options - Optional configuration
+ * @param {number} options.maxLockAge - Maximum lock age in ms (default: 5 min)
  * @returns {Promise<number>} Count of locks removed
  */
-function cleanupStaleLocks(db, staleThresholdOrOptions = 15000) {
+function cleanupStaleLocks(db, options = {}) {
   if (!db) {
     return Promise.reject(new Error('Database connection required'));
   }
 
-  // Support both number (old API) and options object (new API)
-  let staleThresholdMs;
-  let maxLockAgeMs;
-  if (typeof staleThresholdOrOptions === 'object') {
-    staleThresholdMs = staleThresholdOrOptions.staleThreshold || 15000;
-    maxLockAgeMs = staleThresholdOrOptions.maxLockAge || DEFAULT_MAX_LOCK_AGE_MS;
-  } else {
-    staleThresholdMs = staleThresholdOrOptions;
-    maxLockAgeMs = DEFAULT_MAX_LOCK_AGE_MS;
-  }
+  const maxLockAgeMs = (typeof options === 'object' && options.maxLockAge) || DEFAULT_MAX_LOCK_AGE_MS;
 
   return new Promise((resolve, reject) => {
-    db.run(
-      `DELETE FROM merge_locks
-       WHERE (julianday('now') - julianday(heartbeat_at)) * 86400000 > ?
-          OR (julianday('now') - julianday(locked_at)) * 86400000 > ?`,
-      [staleThresholdMs, maxLockAgeMs],
-      function(err) {
-        if (err) return reject(err);
-        resolve(this.changes); // Return count of deleted locks
+    // First get all locks to check PID liveness
+    db.all('SELECT id, locked_by, locked_at FROM merge_locks', (err, rows) => {
+      if (err) return reject(err);
+      if (!rows || rows.length === 0) return resolve(0);
+
+      const staleIds = [];
+
+      for (const row of rows) {
+        const pid = parsePid(row.locked_by);
+
+        // Stale if: PID is dead, PID is unparseable, or lock is too old
+        if (!pid || !isProcessAlive(pid)) {
+          staleIds.push(row.id);
+        }
       }
-    );
+
+      // Also delete any locks older than maxLockAge regardless of PID
+      // (safety net for PID reuse - extremely unlikely but possible)
+      const deleteByAge = new Promise((res, rej) => {
+        db.run(
+          `DELETE FROM merge_locks
+           WHERE (julianday('now') - julianday(locked_at)) * 86400000 > ?`,
+          [maxLockAgeMs],
+          function(err) {
+            if (err) return rej(err);
+            res(this.changes);
+          }
+        );
+      });
+
+      // Delete PID-dead locks
+      const deleteByPid = staleIds.length > 0
+        ? new Promise((res, rej) => {
+            const placeholders = staleIds.map(() => '?').join(',');
+            db.run(
+              `DELETE FROM merge_locks WHERE id IN (${placeholders})`,
+              staleIds,
+              function(err) {
+                if (err) return rej(err);
+                res(this.changes);
+              }
+            );
+          })
+        : Promise.resolve(0);
+
+      Promise.all([deleteByPid, deleteByAge])
+        .then(([pidClean, ageClean]) => resolve(Math.max(pidClean, ageClean)))
+        .catch(reject);
+    });
   });
 }
 
 /**
- * Create lock handle object with release function and heartbeat
- *
- * @param {Object} db - SQLite database connection
- * @param {number} lockId - Lock ID
- * @param {string} lockedBy - Instance identifier
- * @param {number} workItemId - Work item ID
- * @param {Object} options - Optional configuration
- * @param {number} options.heartbeatInterval - Heartbeat interval in ms (default: 5000)
- * @param {number} options.maxHeartbeatFailures - Max consecutive failures before releasing (default: 2)
- * @returns {Object} Lock handle with release() and stopHeartbeat()
+ * Create lock handle with release function and signal handlers.
+ * No heartbeat, no setInterval — nothing that keeps the event loop alive.
  */
-function createLockHandle(db, lockId, lockedBy, workItemId, options = {}) {
-  const heartbeatInterval = options.heartbeatInterval || 5000;
-  const maxHeartbeatFailures = options.maxHeartbeatFailures || 2;
-
-  // Track if lock has been released (prevents double-release)
+function createLockHandle(db, lockId, lockedBy, workItemId) {
   let released = false;
-  // Track if we're in the middle of an exit handler (prevents re-entrancy)
   let exitInProgress = false;
 
-  // Release lock with callback - used by signal handlers
-  // Waits for DELETE to complete (with timeout) before allowing exit
   const releaseLockWithCallback = (callback) => {
     if (released) {
       callback();
@@ -250,7 +242,6 @@ function createLockHandle(db, lockId, lockedBy, workItemId, options = {}) {
       return;
     }
 
-    // Set a timeout to ensure we exit even if DELETE hangs
     const timeoutId = setTimeout(() => {
       callback();
     }, 500);
@@ -261,10 +252,7 @@ function createLockHandle(db, lockId, lockedBy, workItemId, options = {}) {
     });
   };
 
-  // Process exit handlers for graceful cleanup
-  // CRITICAL: Wait for DELETE to complete before exiting
   const exitHandler = (signal) => {
-    // Prevent re-entrancy if multiple signals arrive
     if (exitInProgress) return;
     exitInProgress = true;
 
@@ -272,7 +260,6 @@ function createLockHandle(db, lockId, lockedBy, workItemId, options = {}) {
     removeExitHandlers();
 
     releaseLockWithCallback(() => {
-      // Re-emit the signal after cleanup so process exits normally
       process.kill(process.pid, signal);
     });
   };
@@ -286,7 +273,6 @@ function createLockHandle(db, lockId, lockedBy, workItemId, options = {}) {
     });
   };
 
-  // Handler for uncaughtException/unhandledRejection
   const errorExitHandler = (errType) => (err) => {
     if (exitInProgress) return;
     exitInProgress = true;
@@ -300,67 +286,39 @@ function createLockHandle(db, lockId, lockedBy, workItemId, options = {}) {
     });
   };
 
-  // Register exit handlers
   const registerExitHandlers = () => {
     process.on('SIGINT', exitHandler);
     process.on('SIGTERM', exitHandler);
     process.on('SIGHUP', exitHandler);
     process.on('beforeExit', beforeExitHandler);
 
-    // Register global error handlers only once per process
     if (!globalErrorHandlersRegistered) {
       globalErrorHandlersRegistered = true;
       process.on('uncaughtException', errorExitHandler('Uncaught Exception'));
       process.on('unhandledRejection', errorExitHandler('Unhandled Rejection'));
     }
 
-    // Store cleanup function globally so it can be called from anywhere
     activeLockCleanup = () => releaseLockWithCallback(() => {});
   };
 
-  // Remove exit handlers (called on normal release)
   const removeExitHandlers = () => {
     process.removeListener('SIGINT', exitHandler);
     process.removeListener('SIGTERM', exitHandler);
     process.removeListener('SIGHUP', exitHandler);
     process.removeListener('beforeExit', beforeExitHandler);
     activeLockCleanup = null;
-    // Note: We don't remove global error handlers - they stay for the process lifetime
   };
 
-  // Register handlers immediately
   registerExitHandlers();
 
-  // Start heartbeat with failure detection
-  const heartbeat = startHeartbeat(db, lockId, heartbeatInterval, {
-    maxFailures: maxHeartbeatFailures,
-    onMaxFailures: () => {
-      console.error(`❌ Heartbeat failed ${maxHeartbeatFailures} consecutive times - releasing lock`);
-      removeExitHandlers();
-      releaseLockWithCallback(() => {});
-    }
-  });
-
   return {
     id: lockId,
     locked_by: lockedBy,
     work_item_id: workItemId,
-    stopHeartbeat: () => {
-      heartbeat.stop();
-    },
     release: async () => {
-      // Prevent double-release
-      if (released) {
-        return;
-      }
+      if (released) return;
 
-      // Always stop heartbeat first
-      heartbeat.stop();
-
-      // Remove exit handlers since we're releasing normally
       removeExitHandlers();
-
-      // Mark as released
       released = true;
 
       try {
@@ -368,11 +326,9 @@ function createLockHandle(db, lockId, lockedBy, workItemId, options = {}) {
           throw new Error('Database connection unavailable during release');
         }
 
-        // Attempt to delete the lock
         await new Promise((resolve, reject) => {
           db.run('DELETE FROM merge_locks WHERE id = ?', [lockId], (err) => {
             if (err) {
-              // Enhance error message for common issues
               if (err.message && err.message.includes('Database is closed')) {
                 reject(new Error('Database connection unavailable during release'));
               } else {
@@ -383,120 +339,22 @@ function createLockHandle(db, lockId, lockedBy, workItemId, options = {}) {
             }
           });
         });
-
-        // Verify lock was actually deleted (orphan detection)
-        const lockStillExists = await new Promise((resolve, reject) => {
-          db.get('SELECT id FROM merge_locks WHERE id = ?', [lockId], (err, row) => {
-            if (err) {
-              // If we can't verify, assume success (soft failure)
-              console.warn(`Warning: Could not verify lock ${lockId} was released: ${err.message}`);
-              resolve(false);
-            } else {
-              resolve(!!row);
-            }
-          });
-        });
-
-        if (lockStillExists) {
-          // Hard failure: lock persists after DELETE (orphan detected)
-          throw new Error(
-            `Failed to release merge lock ${lockId} - orphan lock detected.\n` +
-            `The lock still exists in the database after attempted deletion.\n\n` +
-            `Manual cleanup required:\n` +
-            `  jettypod work merge --release-lock`
-          );
-        }
       } catch (err) {
-        // Log error but don't crash - lock may have already been cleaned up
-        // or database may be unavailable
         console.error(`Failed to release lock ${lockId}:`, err.message);
-        throw err; // Re-throw so caller knows release failed
+        throw err;
       }
     }
   };
 }
 
-
-/**
- * Sleep for specified milliseconds
- *
- * @param {number} ms - Milliseconds to sleep
- * @returns {Promise<void>}
- */
 function sleep(ms) {
   return new Promise(resolve => setTimeout(resolve, ms));
 }
 
-/**
- * Update heartbeat timestamp for a lock
- *
- * @param {Object} db - SQLite database connection
- * @param {number} lockId - Lock ID to update
- * @returns {Promise<void>}
- */
-function updateHeartbeat(db, lockId) {
-  return new Promise((resolve, reject) => {
-    db.run(
-      `UPDATE merge_locks SET heartbeat_at = datetime('now') WHERE id = ?`,
-      [lockId],
-      (err) => {
-        if (err) reject(err);
-        else resolve();
-      }
-    );
-  });
-}
-
-/**
- * Start heartbeat interval for a lock
- *
- * @param {Object} db - SQLite database connection
- * @param {number} lockId - Lock ID to heartbeat
- * @param {number} intervalMs - Heartbeat interval in milliseconds (default: 5000)
- * @param {Object} options - Optional configuration
- * @param {number} options.maxFailures - Max consecutive failures before calling onMaxFailures (default: 2)
- * @param {Function} options.onMaxFailures - Callback when max failures reached
- * @returns {Object} Object with stop() function to clear the interval
- */
-function startHeartbeat(db, lockId, intervalMs = 5000, options = {}) {
-  const maxFailures = options.maxFailures || 2;
-  const onMaxFailures = options.onMaxFailures || null;
-
-  let consecutiveFailures = 0;
-  let stopped = false;
-
-  const intervalId = setInterval(async () => {
-    if (stopped) return;
-
-    try {
-      await updateHeartbeat(db, lockId);
-      // Reset failure count on success
-      consecutiveFailures = 0;
-    } catch (err) {
-      consecutiveFailures++;
-      console.warn(`Warning: Heartbeat update failed for lock ${lockId} (${consecutiveFailures}/${maxFailures}): ${err.message}`);
-
-      // Trigger callback if max failures reached
-      if (consecutiveFailures >= maxFailures && onMaxFailures && !stopped) {
-        stopped = true;
-        clearInterval(intervalId);
-        onMaxFailures();
-      }
-    }
-  }, intervalMs);
-
-  return {
-    stop: () => {
-      stopped = true;
-      clearInterval(intervalId);
-    }
-  };
-}
-
 module.exports = {
   acquireMergeLock,
   cleanupStaleLocks,
-  startHeartbeat,
-  updateHeartbeat,
+  isProcessAlive,
+  parsePid,
   DEFAULT_MAX_LOCK_AGE_MS
 };

package/lib/migrations/027-plan-at-creation-column.js

@@ -13,7 +13,9 @@ module.exports = {
   async up(db) {
     return new Promise((resolve, reject) => {
       db.run(`ALTER TABLE work_items ADD COLUMN plan_at_creation TEXT DEFAULT NULL`, (err) => {
-        if (err) return reject(err);
+        // Ignore "duplicate column" — column may already exist if a previous
+        // run succeeded at ALTER TABLE but crashed before recording the migration.
+        if (err && !err.message.includes('duplicate column')) return reject(err);
         // Backfill existing work items — assume free plan for all existing items
         db.run(`UPDATE work_items SET plan_at_creation = 'free' WHERE plan_at_creation IS NULL`, (err2) => {
           if (err2) return reject(err2);