byterover-cli 1.0.5 → 1.1.0

package/dist/infra/process/process-manager.js

@@ -26,8 +26,11 @@ import { fileURLToPath } from 'node:url';
 import { crashLog, getSessionLogPath, processManagerLog } from '../../utils/process-logger.js';
 const DEFAULT_SHUTDOWN_TIMEOUT_MS = 5000;
 const DEFAULT_STARTUP_TIMEOUT_MS = 30_000;
-const HEALTH_CHECK_INTERVAL_MS = 5000; // Check every 5 seconds
+const HEALTH_CHECK_INTERVAL_MS = 5000; // Check every 5 seconds for sleep detection
 const SLEEP_DETECTION_THRESHOLD_MS = 30_000; // If 30s passed when expecting 5s, likely slept
+const TRANSPORT_PING_TIMEOUT_MS = 5000; // Timeout for Transport ping response
+const AGENT_HEALTH_CHECK_TIMEOUT_MS = 5000; // Timeout for Agent health-check response
+const PERIODIC_HEALTH_CHECK_INTERVAL_MS = 30_000; // Periodic health check every 30s
 /**
  * Creates a system error with crash log.
  * Logs error details to session log and returns user-friendly message.
@@ -46,9 +49,21 @@ function createSystemError(error, context) {
  * - Crash recovery: respawn on exit
  */
 export class ProcessManager {
+    /** Whether an Agent health-check is pending response */
+    agentHealthCheckPending = false;
+    /** Timeout for Agent health-check response */
+    agentHealthCheckTimeout;
     currentSessionId;
     healthCheckInterval;
+    /** Guard to prevent concurrent Agent restarts */
+    isRestartingAgent = false;
+    /** Guard to prevent concurrent Transport restarts */
+    isRestartingTransport = false;
     lastHealthCheckTime = Date.now();
+    /** Periodic health check interval (30s) */
+    periodicHealthCheckInterval;
+    /** Stored handler ref for idempotent listener setup (prevents accumulation on respawn) */
+    runtimeMessageHandler;
     shutdownTimeoutMs;
     startupTimeoutMs;
     state = {
@@ -56,6 +71,12 @@ export class ProcessManager {
         running: false,
         transportReady: false,
     };
+    /** Stored handler ref for Transport runtime messages (prevents accumulation on respawn) */
+    transportMessageHandler;
+    /** Whether a Transport ping is pending response */
+    transportPingPending = false;
+    /** Timeout for Transport ping response */
+    transportPingTimeout;
     constructor(config) {
         this.startupTimeoutMs = config?.startupTimeoutMs ?? DEFAULT_STARTUP_TIMEOUT_MS;
         this.shutdownTimeoutMs = config?.shutdownTimeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT_MS;
@@ -106,6 +127,8 @@ export class ProcessManager {
         this.state.running = true;
         // Step 3: Start health check for sleep/wake detection
         this.startHealthCheck();
+        // Step 4: Start periodic health check (30s) for zombie detection mid-session
+        this.startPeriodicHealthCheck();
     }
     /**
      * Stop all processes gracefully.
@@ -119,8 +142,9 @@ export class ProcessManager {
             return;
         }
         this.state.running = false;
-        // Stop health check first
+        // Stop health checks first
         this.stopHealthCheck();
+        this.stopPeriodicHealthCheck();
         // Step 1: Stop Agent Process
         await this.stopAgentProcess();
         this.state.agentReady = false;
@@ -141,9 +165,34 @@ export class ProcessManager {
         }
         return currentDir;
     }
+    /**
+     * Handle runtime IPC messages from Agent process.
+     * Called by the message event handler set up in setupAgentRuntimeHandlers.
+     */
+    handleAgentRuntimeMessage(message) {
+        if (message.type === 'health-check-result') {
+            // Clear pending flag and timeout (for periodic health check)
+            if (this.agentHealthCheckTimeout) {
+                clearTimeout(this.agentHealthCheckTimeout);
+                this.agentHealthCheckTimeout = undefined;
+            }
+            this.agentHealthCheckPending = false;
+            if (message.success) {
+                processManagerLog('Agent health-check passed');
+            }
+            else {
+                processManagerLog('Agent health-check FAILED - Socket.IO connection stale, restarting agent');
+                // Restart agent to force reconnection
+                this.restartAgent().catch((error) => {
+                    processManagerLog(`Failed to restart agent after health-check failure: ${error}`);
+                });
+            }
+        }
+    }
     /**
      * Handle system wake from sleep.
      * Verify processes are still alive and restart if needed.
+     * Triggers immediate health checks on both Transport and Agent.
      */
     handleSystemWake() {
         const { agentProcess, transportProcess } = this.state;
@@ -165,7 +214,139 @@ export class ProcessManager {
             }
         }
         else {
-            processManagerLog('Processes healthy after wake');
+            processManagerLog('Processes healthy after wake - triggering immediate health check');
+            // Trigger immediate health checks (reuse the timeout-based methods)
+            // Check Transport (if not already pinging)
+            if (this.state.transportReady && !this.transportPingPending) {
+                this.pingTransportWithTimeout();
+            }
+            // Check Agent (if not already checking)
+            if (this.state.agentReady && !this.agentHealthCheckPending) {
+                this.healthCheckAgentWithTimeout();
+            }
+        }
+    }
+    /**
+     * Handle runtime IPC messages from Transport process.
+     * Called by the message event handler set up in setupTransportRuntimeHandlers.
+     */
+    handleTransportRuntimeMessage(message) {
+        if (message.type === 'pong' && this.transportPingPending) {
+            // Clear timeout and flag
+            if (this.transportPingTimeout) {
+                clearTimeout(this.transportPingTimeout);
+                this.transportPingTimeout = undefined;
+            }
+            this.transportPingPending = false;
+            processManagerLog('Transport ping successful - process healthy');
+        }
+    }
+    /**
+     * Send health-check to Agent with timeout.
+     * If no response within timeout, Agent is considered stuck and restarted.
+     * Used by periodic health check and after system wake.
+     */
+    healthCheckAgentWithTimeout() {
+        const { agentProcess } = this.state;
+        if (!agentProcess || this.agentHealthCheckPending)
+            return;
+        this.agentHealthCheckPending = true;
+        processManagerLog('Sending health-check to agent');
+        this.sendToChild(agentProcess, { type: 'health-check' });
+        this.agentHealthCheckTimeout = setTimeout(() => {
+            if (this.agentHealthCheckPending) {
+                processManagerLog('Agent health-check timeout - process may be stuck, restarting');
+                this.agentHealthCheckPending = false;
+                this.agentHealthCheckTimeout = undefined;
+                this.restartAgent().catch((error) => {
+                    processManagerLog(`Failed to restart agent after health-check timeout: ${error}`);
+                });
+            }
+        }, AGENT_HEALTH_CHECK_TIMEOUT_MS);
+        // Don't block process exit
+        this.agentHealthCheckTimeout.unref();
+    }
+    /**
+     * Send ping to Transport with timeout.
+     * If no pong received within timeout, Transport is considered zombie and restarted.
+     */
+    pingTransportWithTimeout() {
+        const { transportProcess } = this.state;
+        if (!transportProcess || this.transportPingPending)
+            return;
+        this.transportPingPending = true;
+        processManagerLog('Sending ping to transport after wake');
+        this.sendToChild(transportProcess, { type: 'ping' });
+        this.transportPingTimeout = setTimeout(() => {
+            if (this.transportPingPending) {
+                processManagerLog('Transport ping timeout - process may be zombie, restarting');
+                this.transportPingPending = false;
+                this.transportPingTimeout = undefined;
+                this.restartTransport().catch((error) => {
+                    processManagerLog(`Failed to restart transport after ping timeout: ${error}`);
+                });
+            }
+        }, TRANSPORT_PING_TIMEOUT_MS);
+        // Don't block process exit
+        this.transportPingTimeout.unref();
+    }
+    /**
+     * Restart Agent process gracefully.
+     * Used when health-check fails after sleep/wake or periodic check.
+     * Guarded to prevent concurrent restart race conditions.
+     */
+    async restartAgent() {
+        // Guard: prevent concurrent restarts
+        if (!this.state.running || !this.state.port || this.isRestartingAgent)
+            return;
+        this.isRestartingAgent = true;
+        try {
+            processManagerLog('Restarting agent process...');
+            // Stop existing agent
+            await this.stopAgentProcess();
+            this.state.agentReady = false;
+            // Start new agent
+            await this.startAgentProcess(this.state.port);
+            this.state.agentReady = true;
+            processManagerLog('Agent process restarted successfully');
+        }
+        finally {
+            this.isRestartingAgent = false;
+        }
+    }
+    /**
+     * Restart Transport process gracefully.
+     * Used when ping timeout detects zombie process after sleep/wake or periodic check.
+     * Note: Agent must also be restarted since Transport port changes.
+     * Guarded to prevent concurrent restart race conditions.
+     */
+    async restartTransport() {
+        // Guard: prevent concurrent restarts
+        if (!this.state.running || this.isRestartingTransport)
+            return;
+        this.isRestartingTransport = true;
+        try {
+            processManagerLog('Restarting transport process...');
+            // Stop existing transport
+            await this.stopTransportProcess();
+            this.state.transportReady = false;
+            // Start new transport (gets new port)
+            const newPort = await this.startTransportProcess();
+            this.state.port = newPort;
+            this.state.transportReady = true;
+            processManagerLog(`Transport process restarted on port ${newPort}`);
+            // Agent needs to reconnect to new port - restart Agent too
+            if (this.state.agentProcess) {
+                await this.stopAgentProcess();
+                this.state.agentReady = false;
+                await this.startAgentProcess(newPort);
+                this.state.agentReady = true;
+                processManagerLog('Agent reconnected to new Transport');
+            }
+            processManagerLog('Transport process restarted successfully');
+        }
+        finally {
+            this.isRestartingTransport = false;
         }
     }
     /**
@@ -199,6 +380,29 @@ export class ProcessManager {
                 });
             }
         });
+        // Setup runtime message handler for health-check results
+        this.setupAgentRuntimeHandlers();
+    }
+    /**
+     * Setup runtime message handlers for Agent process.
+     * Handles IPC messages that arrive during normal operation (not just startup).
+     *
+     * IMPORTANT: Uses stored handler reference to prevent listener accumulation.
+     * Each respawn calls this method, so we must remove the old listener first.
+     */
+    setupAgentRuntimeHandlers() {
+        const { agentProcess } = this.state;
+        if (!agentProcess)
+            return;
+        // Remove old listener FIRST (prevents accumulation on respawn)
+        if (this.runtimeMessageHandler) {
+            agentProcess.off('message', this.runtimeMessageHandler);
+        }
+        // Create and store new handler
+        this.runtimeMessageHandler = (message) => {
+            this.handleAgentRuntimeMessage(message);
+        };
+        agentProcess.on('message', this.runtimeMessageHandler);
     }
     /**
      * Setup Transport crash recovery.
@@ -232,6 +436,29 @@ export class ProcessManager {
                 processManagerLog(`Failed to respawn Transport: ${error}`);
             });
         });
+        // Setup runtime message handler for ping/pong health checks
+        this.setupTransportRuntimeHandlers();
+    }
+    /**
+     * Setup runtime message handlers for Transport process.
+     * Handles IPC messages that arrive during normal operation (pong for health check).
+     *
+     * IMPORTANT: Uses stored handler reference to prevent listener accumulation.
+     * Each respawn calls this method, so we must remove the old listener first.
+     */
+    setupTransportRuntimeHandlers() {
+        const { transportProcess } = this.state;
+        if (!transportProcess)
+            return;
+        // Remove old listener FIRST (prevents accumulation on respawn)
+        if (this.transportMessageHandler) {
+            transportProcess.off('message', this.transportMessageHandler);
+        }
+        // Create and store new handler
+        this.transportMessageHandler = (message) => {
+            this.handleTransportRuntimeMessage(message);
+        };
+        transportProcess.on('message', this.transportMessageHandler);
     }
     /**
      * Start Agent Process.
@@ -312,6 +539,27 @@ export class ProcessManager {
         // Don't prevent process exit
         this.healthCheckInterval.unref();
     }
+    /**
+     * Start periodic health check for Transport and Agent.
+     * Runs every 30s to detect zombie processes mid-session (not just after wake).
+     */
+    startPeriodicHealthCheck() {
+        this.periodicHealthCheckInterval = setInterval(() => {
+            if (!this.state.running)
+                return;
+            // Check Transport (if ready and not already pinging)
+            if (this.state.transportReady && !this.transportPingPending) {
+                this.pingTransportWithTimeout();
+            }
+            // Check Agent (if ready and not already checking)
+            if (this.state.agentReady && !this.agentHealthCheckPending) {
+                this.healthCheckAgentWithTimeout();
+            }
+        }, PERIODIC_HEALTH_CHECK_INTERVAL_MS);
+        // Don't prevent process exit
+        this.periodicHealthCheckInterval.unref();
+        processManagerLog('Periodic health check started (30s interval)');
+    }
     /**
      * Start Transport Process.
      * @returns The port Transport is listening on
@@ -385,6 +633,8 @@ export class ProcessManager {
                 clearTimeout(timeout);
                 agentProcess.off('message', onMessage);
                 agentProcess.off('exit', onExit);
+                // Clear stored handler reference (prevents stale refs on respawn)
+                this.runtimeMessageHandler = undefined;
             };
             const timeout = setTimeout(() => {
                 cleanup();
@@ -419,6 +669,22 @@ export class ProcessManager {
             this.healthCheckInterval = undefined;
         }
     }
+    /**
+     * Stop periodic health check interval.
+     * Also clears any pending agent health check timeout.
+     */
+    stopPeriodicHealthCheck() {
+        if (this.periodicHealthCheckInterval) {
+            clearInterval(this.periodicHealthCheckInterval);
+            this.periodicHealthCheckInterval = undefined;
+        }
+        // Clear any pending agent health check
+        if (this.agentHealthCheckTimeout) {
+            clearTimeout(this.agentHealthCheckTimeout);
+            this.agentHealthCheckTimeout = undefined;
+        }
+        this.agentHealthCheckPending = false;
+    }
     /**
      * Stop Transport Process.
      */
@@ -431,6 +697,14 @@ export class ProcessManager {
                 clearTimeout(timeout);
                 transportProcess.off('message', onMessage);
                 transportProcess.off('exit', onExit);
+                // Clear stored handler reference (prevents stale refs on respawn)
+                this.transportMessageHandler = undefined;
+                // Clear ping state
+                if (this.transportPingTimeout) {
+                    clearTimeout(this.transportPingTimeout);
+                    this.transportPingTimeout = undefined;
+                }
+                this.transportPingPending = false;
             };
             const timeout = setTimeout(() => {
                 cleanup();

package/dist/infra/process/task-queue-manager.d.ts

@@ -81,14 +81,27 @@ export declare class TaskQueueManager {
      * Returns success with queue position, or failure reason.
      */
     enqueue(task: TaskExecute): EnqueueResult;
+    /**
+     * Get total active task count across all queues.
+     */
+    getActiveCount(): number;
     /**
      * Get all queue statistics.
      */
     getAllStats(): Record<TaskType, TaskQueueStats>;
+    /**
+     * Get total queued task count across all queues.
+     */
+    getQueuedCount(): number;
     /**
      * Get statistics for a specific queue.
      */
     getStats(type: TaskType): TaskQueueStats;
+    /**
+     * Check if there are any active tasks (currently being processed).
+     * Used to prevent reinit during task execution.
+     */
+    hasActiveTasks(): boolean;
     /**
      * Check if a taskId is known (queued or processing).
      */

package/dist/infra/process/task-queue-manager.js

@@ -91,6 +91,12 @@ export class TaskQueueManager {
         this.tryProcessNext('query');
         return { position: this.queryQueue.length, success: true };
     }
+    /**
+     * Get total active task count across all queues.
+     */
+    getActiveCount() {
+        return this.activeCurateTasks + this.activeQueryTasks;
+    }
     /**
      * Get all queue statistics.
      */
@@ -100,6 +106,12 @@ export class TaskQueueManager {
             query: this.getStats('query'),
         };
     }
+    /**
+     * Get total queued task count across all queues.
+     */
+    getQueuedCount() {
+        return this.curateQueue.length + this.queryQueue.length;
+    }
     /**
      * Get statistics for a specific queue.
      */
@@ -117,6 +129,13 @@ export class TaskQueueManager {
             queued: this.queryQueue.length,
         };
     }
+    /**
+     * Check if there are any active tasks (currently being processed).
+     * Used to prevent reinit during task execution.
+     */
+    hasActiveTasks() {
+        return this.activeCurateTasks > 0 || this.activeQueryTasks > 0;
+    }
     /**
      * Check if a taskId is known (queued or processing).
      */

package/dist/infra/process/transport-handlers.d.ts

@@ -40,6 +40,8 @@ import type { ITransportServer } from '../../core/interfaces/transport/i-transpo
 export declare class TransportHandlers {
     /** The Agent's client ID (set when Agent registers) */
     private agentClientId;
+    /** Cached agent status from last status:changed broadcast */
+    private cachedAgentStatus;
     /** Track active tasks */
     private tasks;
     /** Transport server reference */
@@ -56,6 +58,7 @@ export declare class TransportHandlers {
     /**
      * Handle Agent registration.
      * Agent connects as Socket.IO client and sends 'agent:register'.
+     * Fix #4: Accepts optional status in payload to cache atomically with registration.
      */
     private handleAgentRegister;
     /**

package/dist/infra/process/transport-handlers.js

@@ -30,9 +30,16 @@
  * - agent:connected / agent:disconnected: Broadcast to all clients
  * - broadcast-room: TUI joins this room to monitor all events
  */
-import { AgentDisconnectedError, AgentNotAvailableError, serializeTaskError, } from '../../core/domain/errors/task-error.js';
-import { LlmEventNames, TransportAgentEventNames, TransportLlmEventList, TransportTaskEventNames, } from '../../core/domain/transport/schemas.js';
+import { AgentDisconnectedError, AgentNotAvailableError, AgentNotInitializedError, serializeTaskError, } from '../../core/domain/errors/task-error.js';
+import { AgentStatusEventNames, LlmEventNames, TransportAgentEventNames, TransportLlmEventList, TransportTaskEventNames, } from '../../core/domain/transport/schemas.js';
 import { eventLog, transportLog } from '../../utils/process-logger.js';
+/**
+ * Type guard for valid task types.
+ * Replaces unsafe `as` assertion per CLAUDE.md standards.
+ */
+function isValidTaskType(type) {
+    return type === 'curate' || type === 'query';
+}
 // All message types are imported from core/domain/transport/schemas.ts
 // - TaskExecute: Transport → Agent (command)
 // - TaskStartedEvent, TaskCompletedEvent, TaskErrorEvent: Agent → Transport (task lifecycle events)
@@ -49,6 +56,8 @@ import { eventLog, transportLog } from '../../utils/process-logger.js';
 export class TransportHandlers {
     /** The Agent's client ID (set when Agent registers) */
     agentClientId;
+    /** Cached agent status from last status:changed broadcast */
+    cachedAgentStatus;
     /** Track active tasks */
     tasks = new Map();
     /** Transport server reference */
@@ -62,6 +71,7 @@ export class TransportHandlers {
     cleanup() {
         this.tasks.clear();
         this.agentClientId = undefined;
+        this.cachedAgentStatus = undefined;
     }
     /**
      * Setup all message handlers.
@@ -75,10 +85,15 @@ export class TransportHandlers {
     /**
      * Handle Agent registration.
      * Agent connects as Socket.IO client and sends 'agent:register'.
+     * Fix #4: Accepts optional status in payload to cache atomically with registration.
      */
-    handleAgentRegister(clientId) {
+    handleAgentRegister(clientId, data) {
         transportLog(`Agent registered: ${clientId}`);
         this.agentClientId = clientId;
+        // Cache status if provided (prevents race window between register and status broadcast)
+        if (data?.status) {
+            this.cachedAgentStatus = data.status;
+        }
         // Broadcast to all clients that Agent is online
         this.transport.broadcast(TransportAgentEventNames.CONNECTED, {});
     }
@@ -169,6 +184,26 @@ export class TransportHandlers {
         });
         // Forward to Agent
         if (this.agentClientId) {
+            // Pre-task check: verify cipher is initialized before forwarding
+            // Reject if: (1) no status cached yet, OR (2) status shows not initialized
+            // This prevents race condition where task arrives before agent broadcasts initial status
+            if (!this.cachedAgentStatus || !this.cachedAgentStatus.isInitialized) {
+                transportLog(`Agent not initialized, cannot process task ${taskId}`);
+                const error = serializeTaskError(new AgentNotInitializedError(this.cachedAgentStatus?.lastError ?? 'Agent status unknown'));
+                this.transport.sendTo(clientId, TransportTaskEventNames.ERROR, { error, taskId });
+                this.transport.broadcastTo('broadcast-room', TransportTaskEventNames.ERROR, { error, taskId });
+                this.tasks.delete(taskId);
+                return { taskId };
+            }
+            // Validate task type before forwarding (type guard replaces unsafe `as` assertion)
+            if (!isValidTaskType(data.type)) {
+                transportLog(`Invalid task type: ${data.type}`);
+                const error = serializeTaskError(new Error(`Invalid task type: ${data.type}`));
+                this.transport.sendTo(clientId, TransportTaskEventNames.ERROR, { error, taskId });
+                this.transport.broadcastTo('broadcast-room', TransportTaskEventNames.ERROR, { error, taskId });
+                this.tasks.delete(taskId);
+                return { taskId };
+            }
             const executeMsg = {
                 clientId,
                 content: data.content,
@@ -323,8 +358,9 @@ export class TransportHandlers {
      */
     setupAgentHandlers() {
         // Agent registration
-        this.transport.onRequest(TransportAgentEventNames.REGISTER, (_data, clientId) => {
-            this.handleAgentRegister(clientId);
+        // Fix #4: Accept optional status in payload for atomic caching
+        this.transport.onRequest(TransportAgentEventNames.REGISTER, (data, clientId) => {
+            this.handleAgentRegister(clientId, data);
             return { success: true };
         });
         // Task lifecycle events (Transport-generated names)
@@ -344,6 +380,15 @@ export class TransportHandlers {
         for (const eventName of TransportLlmEventList) {
             this.registerLlmEvent(eventName);
         }
+        // Agent status events
+        // agent:status:changed - Agent broadcasts status changes
+        this.transport.onRequest(AgentStatusEventNames.STATUS_CHANGED, (data) => {
+            transportLog(`Agent status changed: initialized=${data.isInitialized}, auth=${data.hasAuth}, config=${data.hasConfig}`);
+            // Cache status for pre-task check
+            this.cachedAgentStatus = data;
+            // Broadcast status change to all clients
+            this.transport.broadcast(AgentStatusEventNames.STATUS_CHANGED, data);
+        });
     }
     /**
      * Setup client-related handlers.
@@ -368,6 +413,7 @@ export class TransportHandlers {
             if (clientId === this.agentClientId) {
                 transportLog('Agent disconnected!');
                 this.agentClientId = undefined;
+                this.cachedAgentStatus = undefined;
                 // Broadcast to all clients
                 this.transport.broadcast(TransportAgentEventNames.DISCONNECTED, {});
                 // Fail all pending tasks - send to client AND broadcast-room for TUI monitoring

package/dist/infra/process/transport-worker.js

@@ -24,6 +24,7 @@ import { transportLog } from '../../utils/process-logger.js';
 import { FileInstanceManager } from '../instance/file-instance-manager.js';
 import { findAvailablePort } from '../transport/port-utils.js';
 import { createTransportServer } from '../transport/transport-factory.js';
+import { createParentHeartbeat } from './parent-heartbeat.js';
 import { TransportHandlers } from './transport-handlers.js';
 // IPC types imported from ./ipc-types.ts
 function sendToParent(message) {
@@ -35,13 +36,10 @@ function sendToParent(message) {
 let transportServer;
 let transportHandlers;
 let instancePollingInterval;
-let parentHeartbeatRunning = false;
-let parentPid;
+let parentHeartbeat;
 const instanceManager = new FileInstanceManager();
 /** Polling interval in milliseconds */
 const INSTANCE_POLLING_INTERVAL_MS = 2000;
-/** Parent heartbeat check interval in milliseconds */
-const PARENT_HEARTBEAT_INTERVAL_MS = 2000;
 /**
  * Setup polling to detect instance.json deletion and recreate it.
  *
@@ -83,69 +81,6 @@ function stopInstancePolling() {
         instancePollingInterval = undefined;
     }
 }
-/**
- * Setup parent process heartbeat monitoring.
- *
- * Why this is needed:
- * - When main process receives SIGKILL, it dies immediately
- * - SIGKILL cannot be caught, so no cleanup happens
- * - IPC 'disconnect' event may not fire
- * - Child processes become orphans (PPID = 1)
- *
- * This function periodically checks if parent is still alive.
- * If parent dies, child self-terminates to prevent zombie processes.
- */
-function setupParentHeartbeat() {
-    // Already running - don't start another
-    if (parentHeartbeatRunning)
-        return;
-    parentHeartbeatRunning = true;
-    parentPid = process.ppid;
-    /**
-     * Recursive setTimeout pattern - safer than setInterval:
-     * - No callback overlap possible
-     * - Clean cancellation (just set flag = false)
-     * - No orphan timers
-     */
-    const checkParent = () => {
-        // Stopped - don't schedule next check
-        if (!parentHeartbeatRunning || !parentPid)
-            return;
-        // Check if parent is still alive using signal 0
-        // Signal 0 doesn't send any signal, just checks if process exists
-        try {
-            process.kill(parentPid, 0);
-        }
-        catch {
-            // Parent is dead - self-terminate
-            transportLog(`Parent process (${parentPid}) died - shutting down to prevent zombie`);
-            parentHeartbeatRunning = false;
-            stopInstancePolling();
-            // Release instance lock and exit
-            stopTransport()
-                .catch(() => { })
-                .finally(() => {
-                // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit
-                process.exit(0);
-            });
-            return;
-        }
-        // Schedule next check (only if still running)
-        if (parentHeartbeatRunning) {
-            setTimeout(checkParent, PARENT_HEARTBEAT_INTERVAL_MS);
-        }
-    };
-    // Start first check after delay
-    setTimeout(checkParent, PARENT_HEARTBEAT_INTERVAL_MS);
-    transportLog(`Parent heartbeat monitoring started (PPID: ${parentPid})`);
-}
-/**
- * Stop the parent heartbeat monitoring.
- * With recursive setTimeout, just set flag to false - next check won't schedule.
- */
-function stopParentHeartbeat() {
-    parentHeartbeatRunning = false;
-}
 async function startTransport() {
     // Create Socket.IO server
     transportServer = createTransportServer();
@@ -171,7 +106,7 @@ async function startTransport() {
 }
 async function stopTransport() {
     // Stop heartbeat and polling first
-    stopParentHeartbeat();
+    parentHeartbeat?.stop();
     stopInstancePolling();
     // Release instance.json
     const projectRoot = process.cwd();
@@ -195,7 +130,12 @@ async function runWorker() {
         sendToParent({ port, type: 'ready' });
         // Start parent heartbeat monitoring after ready
         // This ensures we self-terminate if parent dies (SIGKILL scenario)
-        setupParentHeartbeat();
+        parentHeartbeat = createParentHeartbeat({
+            cleanup: stopTransport,
+            log: transportLog,
+            preCleanup: stopInstancePolling,
+        });
+        parentHeartbeat.start();
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);