jettypod 4.4.64 → 4.4.66

package/apps/dashboard/app/api/kanban/route.ts

@@ -0,0 +1,15 @@
+import { NextResponse } from 'next/server';
+import { getKanbanData } from '@/lib/db';
+
+export const dynamic = 'force-dynamic';
+
+export async function GET() {
+  const data = getKanbanData();
+
+  // Convert Maps to arrays for JSON serialization
+  return NextResponse.json({
+    inFlight: data.inFlight,
+    backlog: Array.from(data.backlog.entries()),
+    done: Array.from(data.done.entries()),
+  });
+}

package/apps/dashboard/app/page.tsx

@@ -1,5 +1,5 @@
 import { getKanbanData } from '@/lib/db';
-import { KanbanBoard } from '@/components/KanbanBoard';
+import { RealTimeKanbanWrapper } from '@/components/RealTimeKanbanWrapper';
 
 // Force dynamic rendering - database is only available at runtime
 export const dynamic = 'force-dynamic';
@@ -7,6 +7,13 @@ export const dynamic = 'force-dynamic';
 export default function Home() {
   const data = getKanbanData();
 
+  // Serialize Map data for client component
+  const serializedData = {
+    inFlight: data.inFlight,
+    backlog: Array.from(data.backlog.entries()),
+    done: Array.from(data.done.entries()),
+  };
+
   return (
     <div className="min-h-screen bg-zinc-50 dark:bg-zinc-950">
       <header className="border-b border-zinc-200 dark:border-zinc-800 bg-white dark:bg-zinc-900">
@@ -17,11 +24,7 @@ export default function Home() {
         </div>
       </header>
       <main className="max-w-6xl mx-auto px-4 py-8">
-        <KanbanBoard
-          inFlight={data.inFlight}
-          backlog={data.backlog}
-          done={data.done}
-        />
+        <RealTimeKanbanWrapper initialData={serializedData} />
       </main>
     </div>
   );

package/apps/dashboard/components/KanbanBoard.tsx

@@ -152,8 +152,9 @@ interface KanbanColumnProps {
 }
 
 function KanbanColumn({ title, children, count }: KanbanColumnProps) {
+  const testId = title.toLowerCase().replace(/\s+/g, '-') + '-column';
   return (
-    <div className="flex-1 min-w-[300px] max-w-[400px]">
+    <div className="flex-1 min-w-[300px] max-w-[400px]" data-testid={testId}>
       <div className="bg-zinc-100 dark:bg-zinc-900 rounded-lg p-3 h-full">
         <div className="flex items-center justify-between mb-3">
           <h2 className="font-semibold text-zinc-900 dark:text-zinc-100">{title}</h2>
@@ -189,12 +190,12 @@ export function KanbanBoard({ inFlight, backlog, done }: KanbanBoardProps) {
   }
 
   return (
-    <div className="flex gap-4 overflow-x-auto pb-4">
+    <div className="flex gap-4 overflow-x-auto pb-4" data-testid="kanban-board">
       {/* Backlog Column */}
       <KanbanColumn title="Backlog" count={backlogCount}>
         {/* In Flight Section */}
         {inFlight.length > 0 && (
-          <div className="mb-4">
+          <div className="mb-4" data-testid="in-flight-section">
             <div className="flex items-center gap-1.5 text-xs font-medium text-blue-600 dark:text-blue-400 mb-2">
               <span>🔥</span>
               <span>In Flight</span>

package/apps/dashboard/components/RealTimeKanbanWrapper.tsx

@@ -0,0 +1,85 @@
+'use client';
+
+import { useState, useCallback } from 'react';
+import { KanbanBoard } from './KanbanBoard';
+import { useWebSocket, type WebSocketMessage } from '../hooks/useWebSocket';
+import type { InFlightItem, KanbanGroup } from '@/lib/db';
+
+interface KanbanData {
+  inFlight: InFlightItem[];
+  backlog: Map<string, KanbanGroup>;
+  done: Map<string, KanbanGroup>;
+}
+
+interface RealTimeKanbanWrapperProps {
+  initialData: {
+    inFlight: InFlightItem[];
+    backlog: [string, KanbanGroup][];
+    done: [string, KanbanGroup][];
+  };
+}
+
+export function RealTimeKanbanWrapper({ initialData }: RealTimeKanbanWrapperProps) {
+  const [data, setData] = useState<KanbanData>(() => ({
+    inFlight: initialData.inFlight,
+    backlog: new Map(initialData.backlog),
+    done: new Map(initialData.done),
+  }));
+
+  const refreshData = useCallback(async () => {
+    const response = await fetch('/api/kanban');
+    const newData = await response.json();
+    setData({
+      inFlight: newData.inFlight,
+      backlog: new Map(newData.backlog),
+      done: new Map(newData.done),
+    });
+  }, []);
+
+  const handleMessage = useCallback((message: WebSocketMessage) => {
+    if (message.type === 'db_change') {
+      refreshData();
+    }
+  }, [refreshData]);
+
+  const wsUrl = typeof window !== 'undefined'
+    ? `ws://${window.location.hostname}:8080`
+    : 'ws://localhost:8080';
+
+  const { isConnected, isReconnecting } = useWebSocket({
+    url: wsUrl,
+    onMessage: handleMessage,
+  });
+
+  // Derive connection status for display
+  const connectionStatus = isConnected ? 'connected' : isReconnecting ? 'reconnecting' : 'disconnected';
+
+  return (
+    <div>
+      {/* Connection Status Indicator */}
+      <div className="mb-4 flex items-center gap-2" data-testid="connection-status">
+        <span
+          className={`w-2 h-2 rounded-full ${
+            connectionStatus === 'connected'
+              ? 'bg-green-500'
+              : connectionStatus === 'reconnecting'
+              ? 'bg-yellow-500 animate-pulse'
+              : 'bg-red-500'
+          }`}
+        />
+        <span className="text-xs text-zinc-500 dark:text-zinc-400">
+          {connectionStatus === 'connected'
+            ? 'Live updates active'
+            : connectionStatus === 'reconnecting'
+            ? 'Reconnecting...'
+            : 'Disconnected'}
+        </span>
+      </div>
+      <KanbanBoard
+        inFlight={data.inFlight}
+        backlog={data.backlog}
+        done={data.done}
+      />
+    </div>
+  );
+}

package/apps/dashboard/hooks/useWebSocket.ts

@@ -0,0 +1,118 @@
+'use client';
+
+import { useEffect, useRef, useCallback, useState } from 'react';
+
+export interface WebSocketMessage {
+  type: string;
+  timestamp: number;
+  event?: string;
+}
+
+interface UseWebSocketOptions {
+  url: string;
+  onMessage?: (message: WebSocketMessage) => void;
+  reconnectInterval?: number;
+  maxReconnectAttempts?: number;
+}
+
+interface UseWebSocketReturn {
+  isConnected: boolean;
+  isReconnecting: boolean;
+  reconnectionFailed: boolean;
+  manualReconnect: () => void;
+}
+
+export function useWebSocket({
+  url,
+  onMessage,
+  reconnectInterval = 3000,
+  maxReconnectAttempts = 5,
+}: UseWebSocketOptions): UseWebSocketReturn {
+  const [isConnected, setIsConnected] = useState(false);
+  const [isReconnecting, setIsReconnecting] = useState(false);
+  const [reconnectionFailed, setReconnectionFailed] = useState(false);
+  const wsRef = useRef<WebSocket | null>(null);
+  const reconnectTimeoutRef = useRef<NodeJS.Timeout | null>(null);
+  const reconnectAttemptsRef = useRef(0);
+
+  const connect = useCallback(() => {
+    if (wsRef.current?.readyState === WebSocket.OPEN) {
+      return;
+    }
+
+    const ws = new WebSocket(url);
+
+    ws.onopen = () => {
+      setIsConnected(true);
+      setIsReconnecting(false);
+      setReconnectionFailed(false);
+      reconnectAttemptsRef.current = 0;
+      // Expose to window for test assertions
+      if (typeof window !== 'undefined') {
+        (window as unknown as { __wsConnection: WebSocket }).__wsConnection = ws;
+        (window as unknown as { __wsReconnecting: boolean }).__wsReconnecting = false;
+      }
+    };
+
+    ws.onmessage = (event) => {
+      try {
+        const message = JSON.parse(event.data) as WebSocketMessage;
+        onMessage?.(message);
+      } catch (e) {
+        // Gracefully handle malformed messages - log but don't crash
+        console.warn('Received malformed WebSocket message:', e);
+      }
+    };
+
+    ws.onclose = () => {
+      setIsConnected(false);
+      wsRef.current = null;
+
+      // Check if max reconnection attempts reached
+      if (reconnectAttemptsRef.current >= maxReconnectAttempts) {
+        setIsReconnecting(false);
+        setReconnectionFailed(true);
+        return;
+      }
+
+      // Initiate reconnection
+      reconnectAttemptsRef.current += 1;
+      setIsReconnecting(true);
+      if (typeof window !== 'undefined') {
+        (window as unknown as { __wsReconnecting: boolean }).__wsReconnecting = true;
+      }
+
+      reconnectTimeoutRef.current = setTimeout(() => {
+        connect();
+      }, reconnectInterval);
+    };
+
+    ws.onerror = () => {
+      ws.close();
+    };
+
+    wsRef.current = ws;
+  }, [url, onMessage, reconnectInterval, maxReconnectAttempts]);
+
+  const manualReconnect = useCallback(() => {
+    // Reset reconnection state and attempt to connect
+    reconnectAttemptsRef.current = 0;
+    setReconnectionFailed(false);
+    connect();
+  }, [connect]);
+
+  useEffect(() => {
+    connect();
+
+    return () => {
+      if (reconnectTimeoutRef.current) {
+        clearTimeout(reconnectTimeoutRef.current);
+      }
+      if (wsRef.current) {
+        wsRef.current.close();
+      }
+    };
+  }, [connect]);
+
+  return { isConnected, isReconnecting, reconnectionFailed, manualReconnect };
+}

package/claude-hooks/global-guardrails.js

@@ -110,7 +110,8 @@ function evaluateRequest(hookInput) {
  */
 function stripHeredocContent(command) {
   // Match heredoc: <<'DELIM' or <<DELIM or <<"DELIM" ... DELIM
-  return command.replace(/<<-?['"]?(\w+)['"]?[\s\S]*?\n\1\b/g, '<<HEREDOC_STRIPPED');
+  // Also handles $(cat <<'EOF'...) pattern used in git commits
+  return command.replace(/<<-?['"]?(\w+)['"]?[\s\S]*?\n\s*\1\b/g, '<<HEREDOC_STRIPPED');
 }
 
 /**
@@ -193,7 +194,7 @@ function evaluateBashCommand(command, inputRef, cwd) {
       return {
         allowed: false,
         message: 'Cannot merge from inside a worktree',
-        hint: 'Merging deletes the worktree. Run from main repo: cd <main-repo-path> && jettypod work merge'
+        hint: 'Merging deletes the worktree. Run from main repo: cd <main-repo-path> && jettypod work merge\n\nNote: "cd path && jettypod work merge" won\'t work - hooks check CWD before cd runs. Run cd separately first.'
       };
     }
   }

package/jettypod.js

@@ -3,6 +3,7 @@
 const fs = require('fs');
 const path = require('path');
 const config = require('./lib/config');
+const wsServer = require('./lib/ws-server');
 // getModeBehaviorContent removed - skills now provide all mode guidance
 
 // CRITICAL: Calculate and cache the REAL git root BEFORE any worktree operations
@@ -2125,6 +2126,16 @@ switch (command) {
           }
         }
 
+        // Start WebSocket server for real-time updates
+        const WS_PORT = 8080;
+        const { getDbPath } = require('./lib/database');
+        try {
+          await wsServer.start(WS_PORT, { dbPath: getDbPath() });
+        } catch (err) {
+          // WebSocket server failed to start (port in use?) - continue without it
+          console.log('⚠️  WebSocket server unavailable (real-time updates disabled)');
+        }
+
         // Start dashboard in background with project path
         console.log('🚀 Starting dashboard...');
         const dashboardProcess = spawn('npm', ['run', 'start', '--', '-p', String(availablePort)], {
@@ -2133,7 +2144,8 @@ switch (command) {
           stdio: 'ignore',
           env: {
             ...process.env,
-            JETTYPOD_PROJECT_PATH: process.cwd()
+            JETTYPOD_PROJECT_PATH: process.cwd(),
+            JETTYPOD_WS_PORT: String(WS_PORT)
           }
         });
         dashboardProcess.unref();

package/lib/db-watcher.js

@@ -0,0 +1,116 @@
+/**
+ * Database change watcher for triggering WebSocket broadcasts.
+ *
+ * Watches the .jettypod/work.db file and its WAL file for modifications
+ * and calls a callback when changes are detected.
+ *
+ * Usage:
+ *   const dbWatcher = require('./lib/db-watcher');
+ *   dbWatcher.start((changeType) => {
+ *     wsServer.broadcast({ type: 'db_change' });
+ *   });
+ *   dbWatcher.stop();
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+let lastMtimes = { db: null, wal: null };
+let pollInterval = null;
+let onChange = null;
+let watchedPath = null;
+
+// Polling interval in milliseconds
+const POLL_MS = 50;
+
+/**
+ * Start watching the database file for changes
+ * @param {Function} callback - Called when database changes detected
+ * @param {string} dbPath - Path to database file (default: .jettypod/work.db)
+ */
+function start(callback, dbPath = null) {
+  if (pollInterval) {
+    return; // Already watching
+  }
+
+  onChange = callback;
+  watchedPath = dbPath || path.join(process.cwd(), '.jettypod', 'work.db');
+
+  // Check if file exists
+  if (!fs.existsSync(watchedPath)) {
+    return;
+  }
+
+  // Get initial mtimes for both db and WAL file
+  try {
+    const dbStats = fs.statSync(watchedPath);
+    lastMtimes.db = dbStats.mtimeMs;
+
+    // Also check WAL file (SQLite in WAL mode writes here first)
+    const walPath = watchedPath + '-wal';
+    if (fs.existsSync(walPath)) {
+      const walStats = fs.statSync(walPath);
+      lastMtimes.wal = walStats.mtimeMs;
+    }
+  } catch {
+    return;
+  }
+
+  // Use polling - most reliable for SQLite files across platforms
+  pollInterval = setInterval(() => {
+    try {
+      let changed = false;
+
+      // Check main db file
+      const dbStats = fs.statSync(watchedPath);
+      if (dbStats.mtimeMs !== lastMtimes.db) {
+        lastMtimes.db = dbStats.mtimeMs;
+        changed = true;
+      }
+
+      // Check WAL file (where SQLite writes first in WAL mode)
+      const walPath = watchedPath + '-wal';
+      if (fs.existsSync(walPath)) {
+        const walStats = fs.statSync(walPath);
+        if (walStats.mtimeMs !== lastMtimes.wal) {
+          lastMtimes.wal = walStats.mtimeMs;
+          changed = true;
+        }
+      }
+
+      if (changed && onChange) {
+        onChange('change');
+      }
+    } catch {
+      // File might be temporarily locked during writes
+    }
+  }, POLL_MS);
+}
+
+/**
+ * Stop watching the database file
+ */
+function stop() {
+  if (pollInterval) {
+    clearInterval(pollInterval);
+    pollInterval = null;
+  }
+
+  onChange = null;
+  lastMtimes = { db: null, wal: null };
+  watchedPath = null;
+}
+
+/**
+ * Check if currently watching
+ * @returns {boolean}
+ */
+function isWatching() {
+  return pollInterval !== null;
+}
+
+module.exports = {
+  start,
+  stop,
+  isWatching,
+};

package/lib/merge-lock.js

@@ -36,7 +36,8 @@ async function acquireMergeLock(db, workItemId, instanceId = null, options = {})
 
   const maxWait = options.maxWait || 60000; // 1 minute default
   const pollInterval = options.pollInterval || 1500; // 1.5 seconds
-  const staleThreshold = options.staleThreshold || 90000; // 90 seconds - locks auto-expire
+  const staleThreshold = options.staleThreshold || 15000; // 15 seconds - heartbeat-based stale detection
+  const heartbeatInterval = options.heartbeatInterval || 5000; // 5 seconds default
   const startTime = Date.now();
 
   // Generate instance identifier
@@ -70,8 +71,8 @@ async function acquireMergeLock(db, workItemId, instanceId = null, options = {})
       try {
         const lockId = await insertLock(db, workItemId, lockedBy);
 
-        // Return lock handle with release function
-        return createLockHandle(db, lockId, lockedBy, workItemId);
+        // Return lock handle with release function and heartbeat
+        return createLockHandle(db, lockId, lockedBy, workItemId, { heartbeatInterval });
       } catch (err) {
         // Race condition - someone else got it first
         // Continue polling
@@ -116,16 +117,16 @@ function checkExistingLock(db) {
 }
 
 /**
- * Get the age of a lock in milliseconds
+ * 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 in milliseconds
+ * @returns {Promise<number>} Age since last heartbeat in milliseconds
  */
 function getLockAge(db, lockId) {
   return new Promise((resolve, reject) => {
     db.get(
-      `SELECT (julianday('now') - julianday(locked_at)) * 86400000 as age_ms
+      `SELECT (julianday('now') - julianday(heartbeat_at)) * 86400000 as age_ms
        FROM merge_locks WHERE id = ?`,
       [lockId],
       (err, row) => {
@@ -159,13 +160,13 @@ function insertLock(db, workItemId, lockedBy) {
 }
 
 /**
- * Clean up stale locks that are older than the threshold
+ * Clean up stale locks based on heartbeat timestamp
  *
  * @param {Object} db - SQLite database connection
- * @param {number|Object} staleThresholdOrOptions - Age threshold in milliseconds (default: 120000), or options object with staleThreshold
+ * @param {number|Object} staleThresholdOrOptions - Age threshold in milliseconds (default: 15000), or options object with staleThreshold
  * @returns {Promise<number>} Count of locks removed
  */
-function cleanupStaleLocks(db, staleThresholdOrOptions = 90000) {
+function cleanupStaleLocks(db, staleThresholdOrOptions = 15000) {
   if (!db) {
     return Promise.reject(new Error('Database connection required'));
   }
@@ -173,7 +174,7 @@ function cleanupStaleLocks(db, staleThresholdOrOptions = 90000) {
   // Support both number (old API) and options object (new API)
   let staleThresholdMs;
   if (typeof staleThresholdOrOptions === 'object') {
-    staleThresholdMs = staleThresholdOrOptions.staleThreshold || 90000;
+    staleThresholdMs = staleThresholdOrOptions.staleThreshold || 15000;
   } else {
     staleThresholdMs = staleThresholdOrOptions;
   }
@@ -181,7 +182,7 @@ function cleanupStaleLocks(db, staleThresholdOrOptions = 90000) {
   return new Promise((resolve, reject) => {
     db.run(
       `DELETE FROM merge_locks
-       WHERE (julianday('now') - julianday(locked_at)) * 86400000 > ?`,
+       WHERE (julianday('now') - julianday(heartbeat_at)) * 86400000 > ?`,
       [staleThresholdMs],
       function(err) {
         if (err) return reject(err);
@@ -192,25 +193,39 @@ function cleanupStaleLocks(db, staleThresholdOrOptions = 90000) {
 }
 
 /**
- * Create lock handle object with release function
+ * 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
- * @returns {Object} Lock handle
+ * @param {Object} options - Optional configuration
+ * @param {number} options.heartbeatInterval - Heartbeat interval in ms (default: 5000)
+ * @returns {Object} Lock handle with release() and stopHeartbeat()
  */
-function createLockHandle(db, lockId, lockedBy, workItemId) {
+function createLockHandle(db, lockId, lockedBy, workItemId, options = {}) {
+  const heartbeatInterval = options.heartbeatInterval || 5000;
+
+  // Start heartbeat to keep lock alive
+  const heartbeat = startHeartbeat(db, lockId, heartbeatInterval);
+
   return {
     id: lockId,
     locked_by: lockedBy,
     work_item_id: workItemId,
+    stopHeartbeat: () => {
+      heartbeat.stop();
+    },
     release: async () => {
+      // Always stop heartbeat first
+      heartbeat.stop();
+
       try {
         if (!db || typeof db.run !== 'function') {
           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) {
@@ -225,12 +240,32 @@ function createLockHandle(db, lockId, lockedBy, workItemId) {
             }
           });
         });
+
+        // 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. In production, consider:
-        // - Logging to error tracking system
-        // - Alerting on repeated failures
-        // - Background cleanup task to handle orphaned locks
+        // or database may be unavailable
         console.error(`Failed to release lock ${lockId}:`, err.message);
         throw err; // Re-throw so caller knows release failed
       }
@@ -249,7 +284,55 @@ 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)
+ * @returns {Object} Object with stop() function to clear the interval
+ */
+function startHeartbeat(db, lockId, intervalMs = 5000) {
+  const intervalId = setInterval(async () => {
+    try {
+      await updateHeartbeat(db, lockId);
+    } catch (err) {
+      // Log but don't crash - heartbeat failure is not fatal
+      // The lock will eventually be cleaned up by stale detection
+      console.warn(`Warning: Heartbeat update failed for lock ${lockId}: ${err.message}`);
+    }
+  }, intervalMs);
+
+  return {
+    stop: () => {
+      clearInterval(intervalId);
+    }
+  };
+}
+
 module.exports = {
   acquireMergeLock,
-  cleanupStaleLocks
+  cleanupStaleLocks,
+  startHeartbeat,
+  updateHeartbeat
 };

package/lib/migrations/016-heartbeat-column.js

@@ -0,0 +1,103 @@
+/**
+ * Migration: Add heartbeat_at column to merge_locks table
+ *
+ * Purpose: Enable heartbeat-based stale detection for faster orphan lock cleanup.
+ * Instead of relying on locked_at timestamp (90s stale threshold), we use
+ * heartbeat_at which is updated every 5 seconds by active lock holders.
+ * This allows stale detection in ~15 seconds instead of 90 seconds.
+ */
+
+module.exports = {
+  id: '016-heartbeat-column',
+  description: 'Add heartbeat_at column to merge_locks for heartbeat-based stale detection',
+
+  async up(db) {
+    return new Promise((resolve, reject) => {
+      // Add heartbeat_at column with default of current timestamp
+      db.run(`
+        ALTER TABLE merge_locks
+        ADD COLUMN heartbeat_at TEXT NOT NULL DEFAULT (datetime('now'))
+      `, (err) => {
+        if (err) {
+          // Column might already exist from a partial migration
+          if (err.message && err.message.includes('duplicate column')) {
+            return resolve();
+          }
+          return reject(err);
+        }
+        resolve();
+      });
+    });
+  },
+
+  async down(db) {
+    // SQLite doesn't support DROP COLUMN directly
+    // We need to recreate the table without the column
+    return new Promise((resolve, reject) => {
+      db.serialize(() => {
+        db.run('BEGIN TRANSACTION', (err) => {
+          if (err) return reject(err);
+        });
+
+        // Create new table without heartbeat_at
+        db.run(`
+          CREATE TABLE merge_locks_new (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            locked_by TEXT NOT NULL,
+            locked_at TEXT NOT NULL DEFAULT (datetime('now')),
+            operation TEXT NOT NULL DEFAULT 'merging',
+            work_item_id INTEGER NOT NULL
+          )
+        `, (err) => {
+          if (err) {
+            db.run('ROLLBACK');
+            return reject(err);
+          }
+        });
+
+        // Copy data
+        db.run(`
+          INSERT INTO merge_locks_new (id, locked_by, locked_at, operation, work_item_id)
+          SELECT id, locked_by, locked_at, operation, work_item_id FROM merge_locks
+        `, (err) => {
+          if (err) {
+            db.run('ROLLBACK');
+            return reject(err);
+          }
+        });
+
+        // Drop old table
+        db.run('DROP TABLE merge_locks', (err) => {
+          if (err) {
+            db.run('ROLLBACK');
+            return reject(err);
+          }
+        });
+
+        // Rename new table
+        db.run('ALTER TABLE merge_locks_new RENAME TO merge_locks', (err) => {
+          if (err) {
+            db.run('ROLLBACK');
+            return reject(err);
+          }
+        });
+
+        // Recreate index
+        db.run(`
+          CREATE INDEX IF NOT EXISTS idx_merge_locks_locked_at
+          ON merge_locks(locked_at)
+        `, (err) => {
+          if (err) {
+            db.run('ROLLBACK');
+            return reject(err);
+          }
+        });
+
+        db.run('COMMIT', (err) => {
+          if (err) return reject(err);
+          resolve();
+        });
+      });
+    });
+  }
+};

package/lib/work-commands/index.js

@@ -1592,6 +1592,11 @@ async function mergeWork(options = {}) {
 
     // Clean up worktree if it exists
     if (worktree && worktree.worktree_path && fs.existsSync(worktree.worktree_path)) {
+      // Check if shell CWD is inside the worktree being deleted
+      const shellCwd = process.cwd();
+      const worktreePath = path.resolve(worktree.worktree_path);
+      const cwdWillBeInvalid = shellCwd.startsWith(worktreePath);
+
       console.log('Cleaning up worktree...');
       try {
         // Remove the git worktree
@@ -1613,6 +1618,13 @@ async function mergeWork(options = {}) {
         });
 
         console.log('✅ Worktree cleaned up');
+
+        // Warn if shell CWD was inside deleted worktree
+        if (cwdWillBeInvalid) {
+          console.log('');
+          console.log('⚠️  Your shell was inside the deleted worktree.');
+          console.log(`   Run this to fix: cd ${gitRoot}`);
+        }
       } catch (worktreeErr) {
         console.warn(`Warning: Failed to clean up worktree: ${worktreeErr.message}`);
         // Non-fatal - continue with merge success
@@ -1838,6 +1850,41 @@ async function testsMerge(featureId) {
     ));
   }
 
+  // Find and set scenario_file on the feature
+  // Look for .feature files that were added in the merged commits
+  try {
+    const addedFiles = execSync(`git diff --name-only --diff-filter=A HEAD~1 HEAD`, {
+      cwd: gitRoot,
+      encoding: 'utf8',
+      stdio: 'pipe'
+    }).trim();
+
+    const featureFiles = addedFiles
+      .split('\n')
+      .filter(f => f.endsWith('.feature') && f.startsWith('features/'));
+
+    if (featureFiles.length > 0) {
+      // Use the first feature file found (typically there's only one per feature)
+      const scenarioFile = featureFiles[0];
+
+      await new Promise((resolve, reject) => {
+        db.run(
+          `UPDATE work_items SET scenario_file = ? WHERE id = ?`,
+          [scenarioFile, featureId],
+          (err) => {
+            if (err) return reject(err);
+            resolve();
+          }
+        );
+      });
+
+      console.log(`✅ Set scenario_file: ${scenarioFile}`);
+    }
+  } catch (err) {
+    // Non-fatal - scenario file can be set manually
+    console.log('⚠️  Could not auto-detect scenario file:', err.message);
+  }
+
   // Push to remote
   try {
     execSync('git push', {
@@ -1851,6 +1898,11 @@ async function testsMerge(featureId) {
   }
 
   // Clean up the worktree
+  // Check if shell CWD is inside the worktree being deleted
+  const shellCwd = process.cwd();
+  const resolvedWorktreePath = path.resolve(worktreePath);
+  const cwdWillBeInvalid = shellCwd.startsWith(resolvedWorktreePath);
+
   try {
     execSync(`git worktree remove "${worktreePath}" --force`, {
       cwd: gitRoot,
@@ -1858,6 +1910,13 @@ async function testsMerge(featureId) {
       stdio: 'pipe'
     });
     console.log('✅ Removed worktree directory');
+
+    // Warn if shell CWD was inside deleted worktree
+    if (cwdWillBeInvalid) {
+      console.log('');
+      console.log('⚠️  Your shell was inside the deleted worktree.');
+      console.log(`   Run this to fix: cd ${gitRoot}`);
+    }
   } catch (err) {
     console.log('⚠️  Failed to remove worktree (non-fatal):', err.message);
   }
@@ -1887,7 +1946,7 @@ async function testsMerge(featureId) {
   });
 
   // Clear current work if it was pointing to this worktree
-  const currentWork = getCurrentWorkSync();
+  const currentWork = await getCurrentWork();
   if (currentWork && currentWork.worktreePath === worktreePath) {
     clearCurrentWork();
   }

package/lib/ws-server.js

@@ -0,0 +1,126 @@
+/**
+ * WebSocket server for broadcasting database changes to connected dashboard clients.
+ *
+ * Usage:
+ *   const wsServer = require('./lib/ws-server');
+ *   await wsServer.start();  // Start on port 8080 and watch for db changes
+ *   wsServer.broadcast({ type: 'db_change' });  // Manual broadcast to all clients
+ *   await wsServer.stop();  // Graceful shutdown
+ */
+
+const { WebSocketServer } = require('ws');
+const dbWatcher = require('./db-watcher');
+
+const DEFAULT_PORT = 8080;
+
+let wss = null;
+const clients = new Set();
+
+/**
+ * Start the WebSocket server
+ * @param {number} port - Port to listen on (default: 8080)
+ * @param {object} options - Options { dbPath: string }
+ * @returns {Promise<void>}
+ */
+async function start(port = DEFAULT_PORT, options = {}) {
+  if (wss) {
+    return; // Already running
+  }
+
+  return new Promise((resolve, reject) => {
+    wss = new WebSocketServer({ port });
+
+    wss.on('listening', () => {
+      // Start watching database for changes
+      dbWatcher.start(() => {
+        broadcast({ type: 'db_change', timestamp: Date.now() });
+      }, options.dbPath);
+      resolve();
+    });
+
+    wss.on('error', (error) => {
+      wss = null;
+      reject(error);
+    });
+
+    wss.on('connection', (ws) => {
+      clients.add(ws);
+
+      // Send connected confirmation
+      ws.send(JSON.stringify({ type: 'connected', timestamp: Date.now() }));
+
+      ws.on('close', () => {
+        clients.delete(ws);
+      });
+
+      ws.on('error', () => {
+        clients.delete(ws);
+      });
+    });
+  });
+}
+
+/**
+ * Stop the WebSocket server
+ * @returns {Promise<void>}
+ */
+async function stop() {
+  // Stop database watcher
+  dbWatcher.stop();
+
+  if (!wss) {
+    return;
+  }
+
+  return new Promise((resolve) => {
+    // Close all client connections
+    for (const client of clients) {
+      client.close();
+    }
+    clients.clear();
+
+    // Close the server
+    wss.close(() => {
+      wss = null;
+      resolve();
+    });
+  });
+}
+
+/**
+ * Broadcast a message to all connected clients
+ * @param {object} message - Message to broadcast (will be JSON stringified)
+ */
+function broadcast(message) {
+  const data = JSON.stringify(message);
+  for (const client of clients) {
+    if (client.readyState === 1) { // WebSocket.OPEN
+      client.send(data);
+    }
+  }
+}
+
+/**
+ * Get the number of connected clients
+ * @returns {number}
+ */
+function getClientCount() {
+  return clients.size;
+}
+
+/**
+ * Check if the server is running
+ * @returns {boolean}
+ */
+function isRunning() {
+  return wss !== null;
+}
+
+module.exports = {
+  start,
+  stop,
+  broadcast,
+  getClientCount,
+  isRunning,
+  DEFAULT_PORT,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jettypod",
-  "version": "4.4.64",
+  "version": "4.4.66",
   "description": "AI-powered development workflow manager with TDD, BDD, and automatic test generation",
   "main": "jettypod.js",
   "bin": {
@@ -43,7 +43,8 @@
     "@cucumber/cucumber": "^10.0.1",
     "@types/better-sqlite3": "^7.6.13",
     "chai": "^6.0.1",
-    "jest": "^30.1.3"
+    "jest": "^30.1.3",
+    "ws": "^8.18.3"
   },
   "jest": {
     "testEnvironment": "node",

package/skills-templates/chore-mode/SKILL.md

@@ -375,18 +375,21 @@ git push
 
 **🚨 CRITICAL: Shell CWD Corruption Prevention**
 
-The merge will delete the worktree. Chain commands to ensure shell is in main repo BEFORE deletion.
+The merge will delete the worktree. You must be in the main repo BEFORE merging.
 
 ```bash
-# CRITICAL: cd to main repo AND merge in SAME command
-cd $(git rev-parse --show-toplevel)/.. && jettypod work merge [chore-id]
-```
+# First, cd to the main repo (worktrees are in .jettypod-work/ inside main repo)
+cd /path/to/main/repo
 
-```bash
-# MANDATORY: Verify shell is in main repo
+# Verify you're in the main repo
 pwd && ls .jettypod
+
+# Then merge (pass the work item ID explicitly)
+jettypod work merge [chore-id]
 ```
 
+**Why not `cd $(git rev-parse --show-toplevel)/..`?** Inside a worktree, `--show-toplevel` returns the worktree path, not the main repo. Going `..` from there doesn't reach the main repo.
+
 **Display:**
 
 ```

package/skills-templates/speed-mode/SKILL.md

@@ -615,7 +615,7 @@ More speed mode chores remain. Starting next chore:
 
 **🚨 CRITICAL: Shell CWD Corruption Prevention**
 
-The merge will delete the worktree. Chain commands to ensure shell is in main repo BEFORE deletion.
+The merge will delete the worktree. You must be in the main repo BEFORE merging.
 
 ```bash
 # Commit changes in the worktree
@@ -623,13 +623,19 @@ git add . && git commit -m "feat: [brief description of what was implemented]"
 ```
 
 ```bash
-# CRITICAL: cd to main repo AND merge in SAME command
-cd $(git rev-parse --show-toplevel)/.. && jettypod work merge [current-chore-id]
+# cd to the main repo first (worktrees are in .jettypod-work/ inside main repo)
+cd /path/to/main/repo
+
+# Verify you're in the main repo
+pwd && ls .jettypod
+
+# Then merge
+jettypod work merge [current-chore-id]
 ```
 
 ```bash
-# Verify shell is valid, then start next chore
-pwd && jettypod work start [next-chore-id]
+# Start next chore
+jettypod work start [next-chore-id]
 ```
 
 The speed-mode skill will automatically re-invoke for the next chore.
@@ -670,7 +676,7 @@ npx cucumber-js <scenario-file-path> --name "User can reach" --format progress
 
 **🚨 CRITICAL: Shell CWD Corruption Prevention**
 
-The merge will delete the worktree. Chain commands to ensure shell is in main repo BEFORE deletion.
+The merge will delete the worktree. You must be in the main repo BEFORE merging.
 
 ```bash
 # Commit changes in the worktree
@@ -678,17 +684,17 @@ git add . && git commit -m "feat: [brief description of what was implemented]"
 ```
 
 ```bash
-# CRITICAL: cd to main repo AND merge in SAME command
-# Using $(git rev-parse --show-toplevel)/.. exits worktree to main repo
-cd $(git rev-parse --show-toplevel)/.. && jettypod work merge [current-chore-id] --with-transition
-```
+# cd to the main repo first (worktrees are in .jettypod-work/ inside main repo)
+cd /path/to/main/repo
 
-```bash
-# MANDATORY: Verify shell is in main repo (run immediately after merge)
+# Verify you're in the main repo
 pwd && ls .jettypod
+
+# Then merge with transition flag
+jettypod work merge [current-chore-id] --with-transition
 ```
 
-**If you see "No such file or directory" errors:** Your shell CWD was corrupted. Get the main repo path from your session context and run `cd <main-repo-path>`.
+**Why not `cd $(git rev-parse --show-toplevel)/..`?** Inside a worktree, `--show-toplevel` returns the worktree path, not the main repo. Going `..` from there doesn't reach the main repo.
 
 After merge, you are on main branch. Ready to generate stable mode scenarios.
 

package/skills-templates/stable-mode/SKILL.md

@@ -574,7 +574,7 @@ More stable mode chores remain. Starting next chore:
 
 **🚨 CRITICAL: Shell CWD Corruption Prevention**
 
-The merge will delete the worktree. Chain commands to ensure shell is in main repo BEFORE deletion.
+The merge will delete the worktree. You must be in the main repo BEFORE merging.
 
 ```bash
 # Commit changes in the worktree
@@ -582,13 +582,19 @@ git add . && git commit -m "feat: [brief description of error handling added]"
 ```
 
 ```bash
-# CRITICAL: cd to main repo AND merge in SAME command
-cd $(git rev-parse --show-toplevel)/.. && jettypod work merge [current-chore-id]
+# cd to the main repo first (worktrees are in .jettypod-work/ inside main repo)
+cd /path/to/main/repo
+
+# Verify you're in the main repo
+pwd && ls .jettypod
+
+# Then merge
+jettypod work merge [current-chore-id]
 ```
 
 ```bash
-# Verify shell is valid, then start next chore
-pwd && jettypod work start [next-chore-id]
+# Start next chore
+jettypod work start [next-chore-id]
 ```
 
 The stable-mode skill will automatically re-invoke for the next chore.
@@ -614,13 +620,14 @@ git add . && git commit -m "feat: [brief description of error handling added]"
 ```
 
 ```bash
-# CRITICAL: cd to main repo AND merge in SAME command
-cd $(git rev-parse --show-toplevel)/.. && jettypod work merge [current-chore-id]
-```
+# cd to the main repo first (worktrees are in .jettypod-work/ inside main repo)
+cd /path/to/main/repo
 
-```bash
-# MANDATORY: Verify shell is in main repo
+# Verify you're in the main repo
 pwd && ls .jettypod
+
+# Then merge
+jettypod work merge [current-chore-id]
 ```
 
 **Then check project state:**