byterover-cli 1.0.4 → 1.1.0

package/dist/infra/process/constants.d.ts

@@ -1 +1 @@
-export declare const CURATE_MAX_CONCURRENT = 1;
+export declare const CURATE_MAX_CONCURRENT = 3;

package/dist/infra/process/constants.js

@@ -1 +1 @@
-export const CURATE_MAX_CONCURRENT = 1;
+export const CURATE_MAX_CONCURRENT = 3;

package/dist/infra/process/ipc-types.d.ts

@@ -2,17 +2,22 @@
  * IPC Types - Shared types for Node.js IPC between parent and child processes.
  *
  * Architecture v0.5.0:
- * - IPC is used ONLY for process lifecycle (ready, ping/pong, shutdown, error)
+ * - IPC is used ONLY for process lifecycle (ready, ping/pong, shutdown, error, health-check)
  * - Task communication uses Socket.IO (NOT IPC)
  *
  * Message flows:
- * - Parent → Child: IPCCommand (ping, shutdown)
- * - Child → Parent: IPCResponse variants (ready, pong, stopped, error)
+ * - Parent → Child: IPCCommand (ping, shutdown, health-check)
+ * - Child → Parent: IPCResponse variants (ready, pong, stopped, error, health-check-result)
  */
 /**
  * Commands sent from parent (ProcessManager) to child processes.
+ * - ping: Heartbeat check
+ * - shutdown: Graceful shutdown request
+ * - health-check: Fix #3 - Verify connection health after sleep/wake
  */
 export type IPCCommand = {
+    type: 'health-check';
+} | {
     type: 'ping';
 } | {
     type: 'shutdown';
@@ -30,6 +35,14 @@ export type IPCErrorResponse = {
     error: string;
     type: 'error';
 };
+/**
+ * Health-check result response (agent-only).
+ * Sent after health-check command to inform ProcessManager of connection status.
+ */
+export type IPCHealthCheckResultResponse = {
+    success: boolean;
+    type: 'health-check-result';
+};
 /**
  * Ready response variants.
  * - Transport: includes port number
@@ -46,7 +59,7 @@ export type IPCReadyWithPortResponse = {
  * Composite response types for each process type.
  */
 export type TransportIPCResponse = IPCErrorResponse | IPCPongResponse | IPCReadyWithPortResponse | IPCStoppedResponse;
-export type AgentIPCResponse = IPCErrorResponse | IPCPongResponse | IPCReadyResponse | IPCStoppedResponse;
+export type AgentIPCResponse = IPCErrorResponse | IPCHealthCheckResultResponse | IPCPongResponse | IPCReadyResponse | IPCStoppedResponse;
 /**
  * Legacy aliases for gradual migration.
  * @deprecated Use IPCCommand instead

package/dist/infra/process/ipc-types.js

@@ -2,11 +2,11 @@
  * IPC Types - Shared types for Node.js IPC between parent and child processes.
  *
  * Architecture v0.5.0:
- * - IPC is used ONLY for process lifecycle (ready, ping/pong, shutdown, error)
+ * - IPC is used ONLY for process lifecycle (ready, ping/pong, shutdown, error, health-check)
  * - Task communication uses Socket.IO (NOT IPC)
  *
  * Message flows:
- * - Parent → Child: IPCCommand (ping, shutdown)
- * - Child → Parent: IPCResponse variants (ready, pong, stopped, error)
+ * - Parent → Child: IPCCommand (ping, shutdown, health-check)
+ * - Child → Parent: IPCResponse variants (ready, pong, stopped, error, health-check-result)
  */
 export {};

package/dist/infra/process/parent-heartbeat.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Parent Heartbeat Monitoring - Shared utility for worker processes.
+ *
+ * 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 module provides a reusable heartbeat monitor that:
+ * - Periodically checks if parent is still alive using signal 0
+ * - Self-terminates the child process if parent dies
+ * - Uses recursive setTimeout pattern (safer than setInterval)
+ */
+/**
+ * Configuration for the parent heartbeat monitor.
+ */
+export interface ParentHeartbeatConfig {
+    /** Async cleanup function to call before exit */
+    cleanup: () => Promise<void>;
+    /** Function to log messages */
+    log: (message: string) => void;
+    /** Optional pre-cleanup function (e.g., stopInstancePolling) */
+    preCleanup?: () => void;
+}
+/**
+ * Creates a parent heartbeat monitor.
+ *
+ * @param config - Configuration for the monitor
+ * @returns Object with start() and stop() methods
+ *
+ * @example
+ * ```typescript
+ * const heartbeat = createParentHeartbeat({
+ *   log: agentLog,
+ *   cleanup: stopAgent,
+ * })
+ *
+ * heartbeat.start()
+ * // Later...
+ * heartbeat.stop()
+ * ```
+ */
+export declare function createParentHeartbeat(config: ParentHeartbeatConfig): {
+    start: () => void;
+    stop: () => void;
+};

package/dist/infra/process/parent-heartbeat.js

@@ -0,0 +1,118 @@
+/**
+ * Parent Heartbeat Monitoring - Shared utility for worker processes.
+ *
+ * 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 module provides a reusable heartbeat monitor that:
+ * - Periodically checks if parent is still alive using signal 0
+ * - Self-terminates the child process if parent dies
+ * - Uses recursive setTimeout pattern (safer than setInterval)
+ */
+/** Parent heartbeat check interval in milliseconds */
+const PARENT_HEARTBEAT_INTERVAL_MS = 2000;
+/**
+ * Type guard for NodeJS.ErrnoException.
+ * Used to safely access error.code without unsafe type assertions.
+ */
+function isNodeError(error) {
+    return error !== null && typeof error === 'object' && 'code' in error;
+}
+/**
+ * Creates a parent heartbeat monitor.
+ *
+ * @param config - Configuration for the monitor
+ * @returns Object with start() and stop() methods
+ *
+ * @example
+ * ```typescript
+ * const heartbeat = createParentHeartbeat({
+ *   log: agentLog,
+ *   cleanup: stopAgent,
+ * })
+ *
+ * heartbeat.start()
+ * // Later...
+ * heartbeat.stop()
+ * ```
+ */
+export function createParentHeartbeat(config) {
+    const state = {
+        isRunning: false,
+        parentPid: undefined,
+    };
+    const { cleanup, log, preCleanup } = config;
+    /**
+     * Check if parent is alive and schedule next check.
+     * Uses recursive setTimeout pattern:
+     * - No callback overlap possible
+     * - Clean cancellation (just set isRunning = false)
+     * - No orphan timers
+     */
+    const checkParent = () => {
+        // Stopped - don't schedule next check
+        if (!state.isRunning || !state.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(state.parentPid, 0);
+        }
+        catch (error) {
+            // Only exit on ESRCH (No such process) - parent is genuinely dead
+            // EPERM (Operation not permitted) means parent exists but different privileges
+            const code = isNodeError(error) ? error.code : undefined;
+            if (code !== 'ESRCH') {
+                log(`Parent check failed with ${code ?? 'unknown'} (not ESRCH) - continuing`);
+                // Schedule next check (don't exit)
+                if (state.isRunning) {
+                    setTimeout(checkParent, PARENT_HEARTBEAT_INTERVAL_MS);
+                }
+                return;
+            }
+            // Parent is dead (ESRCH) - self-terminate
+            log(`Parent process (${state.parentPid}) died - shutting down to prevent zombie`);
+            state.isRunning = false;
+            // Run pre-cleanup if provided
+            preCleanup?.();
+            // Cleanup and exit
+            cleanup()
+                .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 (state.isRunning) {
+            setTimeout(checkParent, PARENT_HEARTBEAT_INTERVAL_MS);
+        }
+    };
+    return {
+        /**
+         * Start the parent heartbeat monitoring.
+         * Safe to call multiple times - only starts once.
+         */
+        start() {
+            // Already running - don't start another
+            if (state.isRunning)
+                return;
+            state.isRunning = true;
+            state.parentPid = process.ppid;
+            // Start first check after delay
+            setTimeout(checkParent, PARENT_HEARTBEAT_INTERVAL_MS);
+            log(`Parent heartbeat monitoring started (PPID: ${state.parentPid})`);
+        },
+        /**
+         * Stop the parent heartbeat monitoring.
+         * With recursive setTimeout, just set flag to false - next check won't schedule.
+         */
+        stop() {
+            state.isRunning = false;
+        },
+    };
+}

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

@@ -47,6 +47,13 @@ export type ProcessManagerConfig = {
     /** Timeout for process startup (ms) */
     startupTimeoutMs?: number;
 };
+/**
+ * Options for starting the process manager.
+ */
+export type ProcessStartOptions = {
+    /** Session ID to pass to Agent process (for stateful sessions) */
+    sessionId?: string;
+};
 /**
  * ProcessManager - Spawns and manages Transport and Agent processes.
  *
@@ -57,11 +64,30 @@ export type ProcessManagerConfig = {
  * - Crash recovery: respawn on exit
  */
 export declare class ProcessManager {
+    /** Whether an Agent health-check is pending response */
+    private agentHealthCheckPending;
+    /** Timeout for Agent health-check response */
+    private agentHealthCheckTimeout?;
+    private currentSessionId?;
     private healthCheckInterval?;
+    /** Guard to prevent concurrent Agent restarts */
+    private isRestartingAgent;
+    /** Guard to prevent concurrent Transport restarts */
+    private isRestartingTransport;
     private lastHealthCheckTime;
+    /** Periodic health check interval (30s) */
+    private periodicHealthCheckInterval?;
+    /** Stored handler ref for idempotent listener setup (prevents accumulation on respawn) */
+    private runtimeMessageHandler?;
     private readonly shutdownTimeoutMs;
     private readonly startupTimeoutMs;
     private state;
+    /** Stored handler ref for Transport runtime messages (prevents accumulation on respawn) */
+    private transportMessageHandler?;
+    /** Whether a Transport ping is pending response */
+    private transportPingPending;
+    /** Timeout for Transport ping response */
+    private transportPingTimeout?;
     constructor(config?: ProcessManagerConfig);
     /**
      * Get current state.
@@ -84,9 +110,10 @@ export declare class ProcessManager {
      * 3. Start Agent Process with TRANSPORT_PORT env
      * 4. Wait for Agent 'ready'
      *
+     * @param options - Start options including session ID for stateful sessions
      * @throws Error if startup fails or times out
      */
-    start(): Promise<void>;
+    start(options?: ProcessStartOptions): Promise<void>;
     /**
      * Stop all processes gracefully.
      *
@@ -100,11 +127,46 @@ export declare class ProcessManager {
      * In dev mode (tsx), import.meta.url points to src/ but workers need compiled .js from dist/
      */
     private getWorkerDir;
+    /**
+     * Handle runtime IPC messages from Agent process.
+     * Called by the message event handler set up in setupAgentRuntimeHandlers.
+     */
+    private handleAgentRuntimeMessage;
     /**
      * Handle system wake from sleep.
      * Verify processes are still alive and restart if needed.
+     * Triggers immediate health checks on both Transport and Agent.
      */
     private handleSystemWake;
+    /**
+     * Handle runtime IPC messages from Transport process.
+     * Called by the message event handler set up in setupTransportRuntimeHandlers.
+     */
+    private handleTransportRuntimeMessage;
+    /**
+     * 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.
+     */
+    private healthCheckAgentWithTimeout;
+    /**
+     * Send ping to Transport with timeout.
+     * If no pong received within timeout, Transport is considered zombie and restarted.
+     */
+    private pingTransportWithTimeout;
+    /**
+     * Restart Agent process gracefully.
+     * Used when health-check fails after sleep/wake or periodic check.
+     * Guarded to prevent concurrent restart race conditions.
+     */
+    private restartAgent;
+    /**
+     * 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.
+     */
+    private restartTransport;
     /**
      * Send IPC message to child process.
      */
@@ -113,10 +175,26 @@ export declare class ProcessManager {
      * Setup Agent crash recovery.
      */
     private setupAgentCrashRecovery;
+    /**
+     * 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.
+     */
+    private setupAgentRuntimeHandlers;
     /**
      * Setup Transport crash recovery.
      */
     private setupTransportCrashRecovery;
+    /**
+     * 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.
+     */
+    private setupTransportRuntimeHandlers;
     /**
      * Start Agent Process.
      */
@@ -126,6 +204,11 @@ export declare class ProcessManager {
      * Detects system sleep by monitoring for large time gaps between checks.
      */
     private startHealthCheck;
+    /**
+     * Start periodic health check for Transport and Agent.
+     * Runs every 30s to detect zombie processes mid-session (not just after wake).
+     */
+    private startPeriodicHealthCheck;
     /**
      * Start Transport Process.
      * @returns The port Transport is listening on
@@ -139,6 +222,11 @@ export declare class ProcessManager {
      * Stop health check interval.
      */
     private stopHealthCheck;
+    /**
+     * Stop periodic health check interval.
+     * Also clears any pending agent health check timeout.
+     */
+    private stopPeriodicHealthCheck;
     /**
      * Stop Transport Process.
      */