byterover-cli 1.0.5 → 1.2.0

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

@@ -9,8 +9,8 @@
  * - NO Socket.IO server (Transport is the only server)
  *
  * IPC messages:
- * - Receives: 'ping', 'shutdown'
- * - Sends: 'ready', 'pong', 'stopped', 'error'
+ * - Receives: 'ping', 'shutdown', 'health-check'
+ * - Sends: 'ready', 'pong', 'stopped', 'error', 'health-check-result'
  *
  * Socket.IO events (as client):
  * - Sends: 'agent:register' (identify as Agent)
@@ -20,7 +20,7 @@
 import { randomUUID } from 'node:crypto';
 import { getCurrentConfig } from '../../config/environment.js';
 import { DEFAULT_LLM_MODEL, PROJECT } from '../../constants.js';
-import { NotAuthenticatedError, ProcessorNotInitError, serializeTaskError } from '../../core/domain/errors/task-error.js';
+import { AgentNotInitializedError, NotAuthenticatedError, ProcessorNotInitError, serializeTaskError, } from '../../core/domain/errors/task-error.js';
 import { agentLog } from '../../utils/process-logger.js';
 import { CipherAgent } from '../cipher/agent/index.js';
 import { ProjectConfigStore } from '../config/file-config-store.js';
@@ -30,6 +30,7 @@ import { createTaskProcessor } from '../core/task-processor.js';
 import { createTokenStore } from '../storage/token-store.js';
 import { createTransportClient } from '../transport/transport-factory.js';
 import { CURATE_MAX_CONCURRENT } from './constants.js';
+import { createParentHeartbeat } from './parent-heartbeat.js';
 import { TaskQueueManager } from './task-queue-manager.js';
 // IPC types imported from ./ipc-types.ts
 function sendToParent(message) {
@@ -63,12 +64,40 @@ let initializationError;
 let isInitializing = false;
 /** Guard: prevent double cleanup */
 let isCleaningUp = false;
-/** Parent process PID for heartbeat monitoring */
-let parentPid;
-/** Parent heartbeat running flag (for recursive setTimeout pattern) */
-let parentHeartbeatRunning = false;
-/** Parent heartbeat check interval in milliseconds */
-const PARENT_HEARTBEAT_INTERVAL_MS = 2000;
+/** Parent heartbeat monitor - lazily initialized in runWorker() */
+let parentHeartbeat;
+// ============================================================================
+// Credentials Polling (detects auth/config changes)
+// ============================================================================
+/**
+ * Credentials polling interval in milliseconds.
+ *
+ * 5 seconds balances:
+ * - Responsiveness: User expects agent to react within ~5s after login/logout/space switch
+ * - Efficiency: Polling every 5s has minimal CPU/IO overhead (reads 2 small files)
+ * - UX: Faster than explicit restart, acceptable latency for credential changes
+ */
+const CREDENTIALS_POLL_INTERVAL_MS = 5000;
+/** Current cached credentials (set after successful init) */
+let cachedCredentials;
+/** Guard: prevent concurrent polling checks */
+let isPolling = false;
+/** Credentials polling running flag */
+let credentialsPollingRunning = false;
+/** Guard: prevent task enqueueing during reinit (fixes TOCTOU race condition) */
+let isReinitializing = false;
+/**
+ * Lazy-initialized stores for credentials polling.
+ * Avoids side effects at import time (file system access).
+ * Created once on first poll, then reused (avoid creating new instances every 5 seconds).
+ */
+let pollingTokenStore;
+let pollingConfigStore;
+function getPollingStores() {
+    pollingTokenStore ??= createTokenStore();
+    pollingConfigStore ??= new ProjectConfigStore();
+    return { pollingConfigStore, pollingTokenStore };
+}
 let eventForwarders = [];
 // ============================================================================
 // Task Queue Manager (replaces inline queue logic)
@@ -114,6 +143,7 @@ function cleanupAgentEventForwarding() {
     const eventBus = cipherAgent?.agentEventBus;
     if (eventBus) {
         for (const { event, handler } of eventForwarders) {
+            // Uses fallback signature: off(eventName: string, listener: (data?: unknown) => void)
             eventBus.off(event, handler);
         }
     }
@@ -121,6 +151,36 @@ function cleanupAgentEventForwarding() {
     eventForwarders = [];
     agentLog('Event forwarders cleaned up');
 }
+/**
+ * Check if there is pending work that would be disrupted by reinit.
+ * Returns true if tasks are active (running) OR queued (waiting).
+ */
+function hasPendingWork() {
+    return taskQueueManager.hasActiveTasks() || taskQueueManager.getQueuedCount() > 0;
+}
+/**
+ * Wait for active tasks to complete with a timeout.
+ * Used before reinit to allow in-flight tasks to finish gracefully.
+ */
+async function waitForActiveTasksToComplete(timeoutMs) {
+    const start = Date.now();
+    const checkInterval = 100;
+    // Poll until no active tasks or timeout
+    const pollUntilDone = async () => {
+        while (taskQueueManager.hasActiveTasks()) {
+            if (Date.now() - start >= timeoutMs) {
+                agentLog('Timeout waiting for active tasks - proceeding with reinit');
+                return;
+            }
+            // eslint-disable-next-line no-await-in-loop
+            await new Promise((resolve) => {
+                setTimeout(resolve, checkInterval);
+            });
+        }
+        agentLog('Task queue drained successfully');
+    };
+    await pollUntilDone();
+}
 /**
  * Setup event forwarding from CipherAgent to Transport.
  * agent-worker subscribes directly to agentEventBus (owns the agent).
@@ -137,10 +197,18 @@ function setupAgentEventForwarding(agent) {
         agentLog('No agentEventBus available for event forwarding');
         return;
     }
-    // Helper to register and track event forwarder
+    // Helper to register and track event forwarder.
+    // Wraps typed handler to match event bus fallback signature.
     const registerForwarder = (event, handler) => {
-        eventBus.on(event, handler);
-        eventForwarders.push({ event, handler: handler });
+        // Wrapper matches fallback: (data?: unknown) => void
+        // BOUNDARY CAST: Event bus delivers unknown data; handler expects T.
+        // Type guard not possible for generic T at runtime.
+        const wrappedHandler = (data) => {
+            handler(data);
+        };
+        // Uses fallback signature: on(eventName: string, listener: (data?: unknown) => void)
+        eventBus.on(event, wrappedHandler);
+        eventForwarders.push({ event, handler: wrappedHandler });
     };
     // Forward llmservice:thinking
     registerForwarder('llmservice:thinking', (payload) => {
@@ -244,46 +312,159 @@ function setupAgentEventForwarding(agent) {
 const TASK_EXECUTION_TIMEOUT_MS = 5 * 60 * 1000;
 /**
  * Setup the task executor for TaskQueueManager.
- * Called after agent is initialized.
+ * Fix #2: Now called unconditionally at startup (before tryInitializeAgent).
+ * Lazy init inside executor enables processing tasks even if initial init failed.
  */
 function setupTaskExecutor() {
     taskQueueManager.setExecutor(async (task) => {
         const { taskId, type } = task;
         const stats = taskQueueManager.getStats(type);
         agentLog(`Processing task ${taskId} (${type}), ${stats.queued} queued, ${stats.active} active`);
-        // Create timeout promise that rejects after 5 minutes
-        let timeoutId;
-        const timeoutPromise = new Promise((_, reject) => {
-            timeoutId = setTimeout(() => {
-                reject(new Error('TASK_TIMEOUT'));
-            }, TASK_EXECUTION_TIMEOUT_MS);
-        });
+        // Fix #2: Lazy initialization - if agent not ready, try to initialize now
+        // This enables processing tasks that arrived while init was failing
+        if (!isAgentInitialized) {
+            agentLog(`Task ${taskId} - agent not initialized, attempting lazy init...`);
+            const initialized = await tryInitializeAgent();
+            if (!initialized) {
+                agentLog(`Task ${taskId} rejected - lazy initialization failed`);
+                const error = serializeTaskError(initializationError ?? new AgentNotInitializedError('Agent initialization failed'));
+                transportClient?.request('task:error', { error, taskId }).catch(logTransportError);
+                return;
+            }
+            agentLog(`Task ${taskId} - lazy initialization successful, proceeding`);
+        }
+        // Pre-execution guard: Verify agent is still ready (catches race conditions)
+        // This catches the case where credentials polling stopped the agent
+        // between when lazy init succeeded and when execution starts.
+        if (!isAgentInitialized || !taskProcessor) {
+            agentLog(`Task ${taskId} rejected - agent stopped during queue wait`);
+            const error = serializeTaskError(new AgentNotInitializedError('Agent stopped during execution wait'));
+            transportClient?.request('task:error', { error, taskId }).catch(logTransportError);
+            return;
+        }
+        // Track timeout state for error handling
+        let timedOut = false;
+        const timeoutId = setTimeout(() => {
+            timedOut = true;
+            agentLog(`Task ${taskId} timed out after 5 minutes - cancelling via CipherAgent`);
+            // Cancel via CipherAgent's existing cancel() method
+            // This aborts activeStreamControllers and session, causing generate() to throw
+            if (cipherAgent) {
+                cipherAgent.cancel().catch((error) => {
+                    agentLog(`Error cancelling CipherAgent on timeout: ${error}`);
+                });
+            }
+        }, TASK_EXECUTION_TIMEOUT_MS);
         try {
-            // Race between task execution and timeout
-            await Promise.race([handleTaskExecute(task), timeoutPromise]);
+            // Execute task - if timeout fires, cipherAgent.cancel() will cause this to throw
+            await handleTaskExecute(task);
         }
         catch (error) {
-            // Handle timeout specifically
-            if (error instanceof Error && error.message === 'TASK_TIMEOUT') {
-                agentLog(`Task ${taskId} timed out after 5 minutes`);
+            // Handle timeout-triggered cancellation
+            if (timedOut) {
+                agentLog(`Task ${taskId} cancelled due to timeout`);
                 const errorData = serializeTaskError(new Error('Task exceeded 5 minute timeout'));
                 transportClient?.request('task:error', { error: errorData, taskId }).catch(logTransportError);
                 return;
             }
-            // Handle other errors
+            // Handle other errors (not timeout)
             agentLog(`Task execution failed: ${error}`);
             const errorData = serializeTaskError(error);
             transportClient?.request('task:error', { error: errorData, taskId }).catch(logTransportError);
         }
         finally {
             // Always clear timeout to prevent memory leak
-            if (timeoutId) {
-                clearTimeout(timeoutId);
-            }
+            clearTimeout(timeoutId);
         }
     });
     agentLog('Task executor setup complete');
 }
+/**
+ * Timeout for CipherAgent initialization operations.
+ * This prevents isInitializing flag from getting stuck if agent.start() or createSession() hangs.
+ * ProcessManager has 30s timeout for startup, but runtime reinit needs its own protection.
+ */
+const AGENT_INIT_TIMEOUT_MS = 30_000;
+/**
+ * Helper to wrap a promise with a timeout.
+ * Throws an error if the operation doesn't complete within the timeout.
+ */
+async function withTimeout(promise, timeoutMs, operation) {
+    let timeoutId;
+    const timeoutPromise = new Promise((_, reject) => {
+        timeoutId = setTimeout(() => {
+            reject(new Error(`${operation} timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+    });
+    try {
+        return await Promise.race([promise, timeoutPromise]);
+    }
+    finally {
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+        }
+    }
+}
+/**
+ * Validate auth token for initialization.
+ * Returns the token if valid, undefined if invalid (also sets initializationError).
+ */
+function validateAuthToken(authToken) {
+    if (!authToken) {
+        initializationError = new NotAuthenticatedError();
+        agentLog('Cannot initialize - no auth token');
+        return undefined;
+    }
+    if (authToken.isExpired()) {
+        initializationError = new NotAuthenticatedError();
+        agentLog('Cannot initialize - token expired (please run /login to re-authenticate)');
+        return undefined;
+    }
+    return authToken;
+}
+/**
+ * Check if cleanup started during init and abort if so.
+ * Returns true if should abort (cleanup started), false otherwise.
+ */
+async function shouldAbortInitForCleanup(agent, phase) {
+    if (isCleaningUp) {
+        agentLog(`Cleanup started during ${phase}, aborting`);
+        await agent.stop();
+        return true;
+    }
+    return false;
+}
+/**
+ * Stop a pending agent that was created but not yet assigned to cipherAgent.
+ * Used in catch block when timeout/error occurs during agent.start() or createSession().
+ */
+async function stopPendingAgent(agent) {
+    if (!agent)
+        return;
+    try {
+        await agent.stop();
+    }
+    catch (stopError) {
+        agentLog(`Error stopping pending agent: ${stopError}`);
+    }
+}
+/**
+ * Stop existing agent during force reinit.
+ */
+async function stopExistingAgentForReinit() {
+    if (!cipherAgent)
+        return;
+    agentLog('Reinitializing with new config...');
+    try {
+        await cipherAgent.stop();
+    }
+    catch (error) {
+        agentLog(`Error stopping previous agent: ${error}`);
+    }
+    cipherAgent = undefined;
+    taskProcessor = undefined;
+    isAgentInitialized = false;
+}
 /**
  * Try to initialize/reinitialize the CipherAgent.
  * Called on startup and lazily when tasks arrive but agent is not initialized.
@@ -292,9 +473,15 @@ function setupTaskExecutor() {
  * @param forceReinit - Force reinitialization even if already initialized (for config reload)
  */
 async function tryInitializeAgent(forceReinit = false) {
-    // Guard: prevent concurrent initialization
-    if (isInitializing) {
-        agentLog('Initialization already in progress, skipping');
+    // Guard: prevent initialization during cleanup or if already in progress
+    if (isCleaningUp || isInitializing) {
+        agentLog('Initialization blocked (cleanup or already in progress)');
+        // Clear isReinitializing if WE set it (forceReinit case)
+        // Without this, the flag would be stuck forever since we return before try block
+        // and thus finally block never runs. Next poll will re-detect and retry.
+        if (forceReinit) {
+            isReinitializing = false;
+        }
         return false;
     }
     // Already initialized and not forcing reinit
@@ -302,34 +489,30 @@ async function tryInitializeAgent(forceReinit = false) {
         return true;
     }
     isInitializing = true;
+    // Set isReinitializing flag for forceReinit to reject tasks during reinit
+    // Note: caller (pollCredentialsAndSync) may have already set this - that's OK, we'll clear in finally
+    if (forceReinit) {
+        isReinitializing = true;
+    }
+    // Declare outside try block so catch can cleanup on timeout/error
+    let pendingAgent;
     try {
-        // If forcing reinit, stop existing agent first
-        if (forceReinit && cipherAgent) {
-            agentLog('Reinitializing with new config...');
-            try {
-                await cipherAgent.stop();
-            }
-            catch (error) {
-                agentLog(`Error stopping previous agent: ${error}`);
-            }
-            cipherAgent = undefined;
-            taskProcessor = undefined;
-            isAgentInitialized = false;
+        // If forcing reinit, drain queue and stop existing agent first
+        if (forceReinit) {
+            // Drain task queue before reinit to prevent tasks executing with stale processor
+            agentLog('Draining task queue before reinit...');
+            taskQueueManager.clear(); // Clear queued (not yet started) tasks
+            // Wait for active tasks to complete (with timeout)
+            await waitForActiveTasksToComplete(10_000);
+            await stopExistingAgentForReinit();
         }
         const tokenStore = createTokenStore();
         const configStore = new ProjectConfigStore();
-        const authToken = await tokenStore.load();
+        const rawToken = await tokenStore.load();
         const brvConfig = await configStore.read();
-        // Need at least authToken to initialize
+        // Validate auth token (sets initializationError if invalid)
+        const authToken = validateAuthToken(rawToken);
         if (!authToken) {
-            initializationError = new NotAuthenticatedError();
-            agentLog('Cannot initialize - no auth token');
-            return false;
-        }
-        // Check if token is expired - fail early with clear message instead of 401 later
-        if (authToken.isExpired()) {
-            initializationError = new NotAuthenticatedError();
-            agentLog('Cannot initialize - token expired (please run /login to re-authenticate)');
             return false;
         }
         // Create Executors
@@ -353,44 +536,71 @@ async function tryInitializeAgent(forceReinit = false) {
             projectId: PROJECT,
             sessionKey: authToken.sessionKey,
         };
-        const agent = new CipherAgent(agentConfig, brvConfig ?? undefined);
-        await agent.start();
+        pendingAgent = new CipherAgent(agentConfig, brvConfig ?? undefined);
+        // Wrap agent.start() with timeout to prevent isInitializing from getting stuck
+        await withTimeout(pendingAgent.start(), AGENT_INIT_TIMEOUT_MS, 'CipherAgent.start()');
         agentLog('CipherAgent started');
-        // Create ChatSession
+        // Check if cleanup started during agent.start() (fixes zombie agent race)
+        if (await shouldAbortInitForCleanup(pendingAgent, 'agent.start()')) {
+            return false;
+        }
+        // Create ChatSession (also with timeout to prevent hanging)
         chatSessionId = `agent-session-${randomUUID()}`;
-        await agent.createSession(chatSessionId);
+        await withTimeout(pendingAgent.createSession(chatSessionId), AGENT_INIT_TIMEOUT_MS, 'CipherAgent.createSession()');
         agentLog(`ChatSession created: ${chatSessionId}`);
+        // Check if cleanup started during createSession() (fixes zombie agent race)
+        if (await shouldAbortInitForCleanup(pendingAgent, 'createSession()')) {
+            return false;
+        }
         // Setup event forwarding
-        setupAgentEventForwarding(agent);
-        cipherAgent = agent;
+        setupAgentEventForwarding(pendingAgent);
+        cipherAgent = pendingAgent;
+        pendingAgent = undefined; // Clear local ref - cipherAgent now owns it
         // Create TaskProcessor
         taskProcessor = createTaskProcessor({
             curateExecutor,
             queryExecutor,
         });
         taskProcessor.setAgent(cipherAgent);
-        // Setup task executor for queue manager (enables processing)
-        setupTaskExecutor();
+        // NOTE: setupTaskExecutor() is called once in startAgent() before tryInitializeAgent()
+        // No need to call again here - executor is already set and handles lazy init
         // Mark as initialized
         isAgentInitialized = true;
         initializationError = undefined;
+        // Cache credentials for change detection polling
+        updateCachedCredentials(authToken.accessToken, authToken.sessionKey, brvConfig ? { spaceId: brvConfig.spaceId, teamId: brvConfig.teamId } : undefined);
         if (brvConfig) {
             agentLog(`Fully initialized with auth and config (team=${brvConfig.teamId}, space=${brvConfig.spaceId})`);
         }
         else {
             agentLog('Initialized with auth only (no project config yet - will reinit when config available)');
         }
+        // Broadcast status change to Transport (init success)
+        broadcastStatusChange();
         return true;
     }
     catch (error) {
+        // Stop pendingAgent if it was created but not yet assigned to cipherAgent
+        // This handles timeout/error during agent.start() or createSession()
+        await stopPendingAgent(pendingAgent);
+        pendingAgent = undefined;
+        // Cleanup partial state before recording error
+        // This prevents stale refs from accumulating on repeated failures
+        await cleanupPartialInit();
         // Catch errors and return false instead of throwing
         // This allows lazy init to retry when tasks arrive
         initializationError = error instanceof Error ? error : new Error(String(error));
         agentLog(`Agent initialization failed: ${error}`);
+        // Broadcast status change to Transport (init failed)
+        broadcastStatusChange();
         return false;
     }
     finally {
         isInitializing = false;
+        // Clear isReinitializing flag (matches the set above for forceReinit)
+        if (forceReinit) {
+            isReinitializing = false;
+        }
     }
 }
 /**
@@ -399,20 +609,8 @@ async function tryInitializeAgent(forceReinit = false) {
 async function handleTaskExecute(data) {
     const { clientCwd, content, files, taskId, type } = data;
     agentLog(`Processing task: ${taskId} (type=${type})`);
-    // If not initialized, try to initialize now (lazy init for post-onboarding)
-    if (!isAgentInitialized) {
-        agentLog('Not initialized, attempting lazy initialization...');
-        const initialized = await tryInitializeAgent();
-        if (!initialized) {
-            agentLog('Lazy initialization failed');
-            const error = serializeTaskError(initializationError ?? new ProcessorNotInitError());
-            transportClient?.request('task:error', { error, taskId }).catch(logTransportError);
-            return;
-        }
-        agentLog('Lazy initialization successful!');
-    }
-    // NOTE: Config change detection removed - use explicit agent:restart event instead
-    // (triggered by /init command via TransportHandlers)
+    // NOTE: Lazy initialization is handled in setupTaskExecutor() executor callback.
+    // By the time we reach here, agent is already initialized (executor does lazy init first).
     if (!taskProcessor) {
         agentLog('TaskProcessor not initialized');
         const error = serializeTaskError(new ProcessorNotInitError());
@@ -483,13 +681,50 @@ async function startAgent() {
     // Register as Agent
     await transportClient.request('agent:register', {});
     agentLog('Registered with Transport');
-    // Try to initialize agent (may fail if no auth yet - that's OK, will lazy init later)
+    // Fix #1: Re-register on any reconnect (Socket.IO auto-reconnect OR force reconnect)
+    // When connection is restored, agent needs to re-register with Transport.
+    // Using onStateChange instead of 'connect' event to handle all reconnect types.
+    // Fix #4: Include status in register payload to prevent race condition window
+    let wasDisconnected = false;
+    transportClient.onStateChange(async (state) => {
+        if (state === 'disconnected' || state === 'reconnecting') {
+            wasDisconnected = true;
+        }
+        else if (state === 'connected' && wasDisconnected) {
+            agentLog('Transport reconnected - re-registering with Transport');
+            try {
+                // Include status in register payload (Transport caches it atomically)
+                await transportClient?.request('agent:register', { status: getAgentStatus() });
+                // Only clear flag after successful registration - if failed, next reconnect will retry
+                wasDisconnected = false;
+                agentLog('Re-registered with Transport after reconnect');
+            }
+            catch (error) {
+                // Keep wasDisconnected = true so next reconnect retries registration
+                agentLog(`Failed to re-register after reconnect: ${error}`);
+            }
+        }
+    });
+    // Fix #2: Setup task executor BEFORE init - enables lazy init when tasks arrive
+    // This ensures tasks don't get stuck in queue if initial init fails
+    setupTaskExecutor();
+    // Try to initialize agent (may fail if no auth yet - that's OK)
+    // tryInitializeAgent() broadcasts status on both success and failure,
+    // so Transport will have cached status before any task can arrive.
+    // If init fails, lazy init will retry when tasks arrive (handled by executor).
     const initialized = await tryInitializeAgent();
     if (!initialized) {
         agentLog('Initial setup incomplete - will retry when tasks arrive (lazy init)');
     }
     // Setup event handlers - TaskQueueManager handles queueing and deduplication
     transportClient.on('task:execute', (data) => {
+        // Reject tasks during reinit to prevent TOCTOU race condition
+        if (isReinitializing) {
+            agentLog(`Task ${data.taskId} rejected - agent reinitializing`);
+            const error = serializeTaskError(new AgentNotInitializedError('Agent is reinitializing'));
+            transportClient?.request('task:error', { error, taskId: data.taskId }).catch(logTransportError);
+            return;
+        }
         const result = taskQueueManager.enqueue(data);
         if (result.success) {
             const stats = taskQueueManager.getStats(data.type);
@@ -506,15 +741,40 @@ async function startAgent() {
     // Handle shutdown from Transport
     transportClient.on('shutdown', () => {
         agentLog('Received shutdown from Transport');
-        stopAgent().then(() => {
+        stopAgent()
+            .then(() => {
             sendToParent({ type: 'stopped' });
             // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit
             process.exit(0);
+        })
+            .catch((error) => {
+            agentLog(`Error during shutdown: ${error}`);
+            sendToParent({ type: 'stopped' });
+            // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit
+            process.exit(1);
         });
     });
     // Handle agent:restart from Transport (triggered by client, e.g., after /init)
     transportClient.on('agent:restart', async (data) => {
         agentLog(`Agent restart requested: ${data.reason ?? 'no reason'}`);
+        // Guard: reject if initialization already in progress (prevents concurrent reinit race condition)
+        if (isInitializing || isReinitializing) {
+            agentLog('Agent restart rejected - initialization already in progress');
+            await transportClient?.request('agent:restarted', {
+                error: 'Initialization already in progress',
+                success: false,
+            });
+            return;
+        }
+        // Reject restart if tasks are in progress or queued (prevents killing active tasks)
+        if (hasPendingWork()) {
+            agentLog('Agent restart rejected - tasks in progress or queued');
+            await transportClient?.request('agent:restarted', {
+                error: 'Tasks in progress. Please wait for tasks to complete.',
+                success: false,
+            });
+            return;
+        }
         try {
             // Reinitialize agent with fresh config
             const success = await tryInitializeAgent(true); // forceReinit = true
@@ -523,10 +783,21 @@ async function startAgent() {
                 // Notify Transport that restart completed
                 await transportClient?.request('agent:restarted', { success: true });
             }
+            else if (isCleaningUp) {
+                // Cleanup in progress - can't restart during shutdown
+                agentLog('Agent reinitialization rejected - cleanup in progress');
+                await transportClient?.request('agent:restarted', {
+                    error: 'Agent is shutting down',
+                    success: false,
+                });
+            }
             else {
+                // Actual failure - missing auth or config
+                // Note: isInitializing is guaranteed to be false here because tryInitializeAgent()
+                // always clears it in its finally block before returning
                 agentLog('Agent reinitialization failed - config incomplete');
                 await transportClient?.request('agent:restarted', {
-                    error: 'Config incomplete (no auth token or config)',
+                    error: initializationError?.message ?? 'Config incomplete (no auth token or config)',
                     success: false,
                 });
             }
@@ -537,72 +808,281 @@ async function startAgent() {
             await transportClient?.request('agent:restarted', { error: message, success: false });
         }
     });
+    // Handle agent:newSession from Transport (triggered by /new command)
+    transportClient.on('agent:newSession', async (data) => {
+        agentLog(`New session requested: ${data.reason ?? 'no reason'}`);
+        try {
+            if (!cipherAgent) {
+                agentLog('Cannot create new session - agent not initialized');
+                await transportClient?.request('agent:newSessionCreated', {
+                    error: 'Agent not initialized',
+                    success: false,
+                });
+                return;
+            }
+            // Generate new session ID
+            const newSessionId = `agent-session-${randomUUID()}`;
+            // Create new session
+            await cipherAgent.createSession(newSessionId);
+            // Switch the agent's default session to the new one
+            // This ensures execute()/generate()/stream() use the new session
+            cipherAgent.switchDefaultSession(newSessionId);
+            // Update the local session ID reference
+            chatSessionId = newSessionId;
+            agentLog(`New session created: ${newSessionId}`);
+            // Notify Transport that new session was created
+            await transportClient?.request('agent:newSessionCreated', {
+                sessionId: newSessionId,
+                success: true,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            agentLog(`New session creation error: ${message}`);
+            await transportClient?.request('agent:newSessionCreated', {
+                error: message,
+                success: false,
+            });
+        }
+    });
     agentLog('Ready to process tasks');
 }
 // ============================================================================
-// Parent Heartbeat Monitoring
+// Credentials Polling Functions
 // ============================================================================
 /**
- * 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)
+ * Stop CipherAgent only (does NOT exit process or disconnect transport).
+ * Used when credentials are missing/invalid but we want to keep polling.
+ */
+async function stopCipherAgent() {
+    // Cleanup event forwarders
+    cleanupAgentEventForwarding();
+    // Clear task queue (can't process without agent)
+    taskQueueManager.clear();
+    // Stop CipherAgent
+    if (cipherAgent) {
+        try {
+            await cipherAgent.stop();
+        }
+        catch (error) {
+            agentLog(`Error stopping CipherAgent: ${error}`);
+        }
+        cipherAgent = undefined;
+    }
+    taskProcessor = undefined;
+    chatSessionId = undefined;
+    isAgentInitialized = false;
+    cachedCredentials = undefined;
+    agentLog('CipherAgent stopped (credentials missing or invalid)');
+    // Broadcast status change to Transport (cipher stopped)
+    broadcastStatusChange();
+}
+/**
+ * Cleanup partial state after failed initialization.
+ * Called when tryInitializeAgent() fails partway through.
+ * Does NOT broadcast status (caller handles that).
+ */
+async function cleanupPartialInit() {
+    agentLog('Cleaning up partial initialization state...');
+    // Cleanup event forwarders (may have been partially set up)
+    cleanupAgentEventForwarding();
+    // Stop CipherAgent if it was partially started
+    if (cipherAgent) {
+        try {
+            await cipherAgent.stop();
+        }
+        catch (error) {
+            agentLog(`Error stopping partial CipherAgent: ${error}`);
+        }
+        cipherAgent = undefined;
+    }
+    // Clear partial state
+    taskProcessor = undefined;
+    chatSessionId = undefined;
+    // Note: DON'T clear cachedCredentials here - keep old credentials for comparison
+    // Note: DON'T set isAgentInitialized - it should already be false
+    agentLog('Partial initialization state cleaned up');
+}
+/**
+ * Update cached credentials after successful initialization.
+ */
+function updateCachedCredentials(accessToken, sessionKey, config) {
+    cachedCredentials = {
+        accessToken,
+        sessionKey,
+        spaceId: config?.spaceId,
+        teamId: config?.teamId,
+    };
+}
+/**
+ * Check if credentials have changed compared to cache.
+ */
+function credentialsChanged(currentToken, currentConfig) {
+    // No cached credentials = first run or was stopped
+    if (!cachedCredentials) {
+        return currentToken ? 'changed' : 'missing';
+    }
+    // Token missing = credentials gone
+    if (!currentToken) {
+        return 'missing';
+    }
+    // Compare token
+    if (currentToken.accessToken !== cachedCredentials.accessToken ||
+        currentToken.sessionKey !== cachedCredentials.sessionKey) {
+        return 'changed';
+    }
+    // Compare config (spaceId/teamId)
+    const currentSpaceId = currentConfig?.spaceId;
+    const currentTeamId = currentConfig?.teamId;
+    if (currentSpaceId !== cachedCredentials.spaceId || currentTeamId !== cachedCredentials.teamId) {
+        return 'changed';
+    }
+    return 'unchanged';
+}
+/**
+ * Poll credentials and sync CipherAgent state.
  *
- * This function periodically checks if parent is still alive.
- * If parent dies, child self-terminates to prevent zombie processes.
+ * Called periodically to detect auth/config changes:
+ * - If credentials MISSING → stop CipherAgent
+ * - If credentials CHANGED → reinit CipherAgent
+ * - If UNCHANGED → do nothing
  */
-function setupParentHeartbeat() {
-    // Already running - don't start another
-    if (parentHeartbeatRunning)
+async function pollCredentialsAndSync() {
+    // Guard: prevent concurrent polling
+    if (isPolling) {
         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
-            agentLog(`Parent process (${parentPid}) died - shutting down to prevent zombie`);
-            parentHeartbeatRunning = false;
-            // Stop agent and exit
-            stopAgent()
-                .catch(() => { })
-                .finally(() => {
-                // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit
-                process.exit(0);
-            });
-            return;
+    }
+    // Guard: don't poll during cleanup or initialization
+    if (isCleaningUp || isInitializing) {
+        return;
+    }
+    isPolling = true;
+    try {
+        // Use lazy-initialized cached stores (avoid creating new instances every poll)
+        const stores = getPollingStores();
+        const authToken = await stores.pollingTokenStore.load();
+        const brvConfig = await stores.pollingConfigStore.read();
+        // Detect change
+        const tokenInfo = authToken ? { accessToken: authToken.accessToken, sessionKey: authToken.sessionKey } : undefined;
+        const configInfo = brvConfig ? { spaceId: brvConfig.spaceId, teamId: brvConfig.teamId } : undefined;
+        const changeStatus = credentialsChanged(tokenInfo, configInfo);
+        switch (changeStatus) {
+            case 'changed': {
+                // Check RIGHT BEFORE reinit - after all awaits, to catch tasks added during awaits
+                // Must check BOTH active (running) AND queued tasks to prevent race condition
+                // where task is enqueued after this check but before stopCipherAgent() clears taskProcessor
+                if (hasPendingWork() || isReinitializing) {
+                    agentLog('Credentials changed but tasks in progress, queued, or reinit in progress - deferring');
+                    return;
+                }
+                // Set flag IMMEDIATELY after check to close TOCTOU window
+                // tryInitializeAgent will manage the flag from here (set on entry, clear in finally)
+                isReinitializing = true;
+                // Credentials changed - reinit CipherAgent
+                agentLog('Credentials changed - reinitializing CipherAgent');
+                const success = await tryInitializeAgent(true); // forceReinit
+                if (success) {
+                    agentLog('CipherAgent reinitialized with new credentials');
+                }
+                else {
+                    agentLog('CipherAgent reinitialization failed');
+                }
+                break;
+            }
+            case 'missing': {
+                // Credentials gone - stop CipherAgent if running
+                if (isAgentInitialized) {
+                    if (hasPendingWork()) {
+                        agentLog('Credentials missing but tasks in progress - deferring stop');
+                        return;
+                    }
+                    agentLog('Credentials missing - stopping CipherAgent');
+                    await stopCipherAgent();
+                }
+                break;
+            }
+            case 'unchanged': {
+                // No change - check if token expired (edge case)
+                if (authToken?.isExpired() && isAgentInitialized) {
+                    if (hasPendingWork()) {
+                        agentLog('Token expired but tasks in progress - deferring stop');
+                        return;
+                    }
+                    agentLog('Token expired - stopping CipherAgent');
+                    await stopCipherAgent();
+                }
+                break;
+            }
         }
-        // Schedule next check (only if still running)
-        if (parentHeartbeatRunning) {
-            setTimeout(checkParent, PARENT_HEARTBEAT_INTERVAL_MS);
+    }
+    catch (error) {
+        // Don't crash on poll errors - just log and continue
+        agentLog(`Credentials poll error: ${error}`);
+    }
+    finally {
+        isPolling = false;
+    }
+}
+/**
+ * Start credentials polling.
+ * Uses recursive setTimeout pattern (same as parent heartbeat).
+ */
+function startCredentialsPolling() {
+    if (credentialsPollingRunning) {
+        return;
+    }
+    credentialsPollingRunning = true;
+    const poll = () => {
+        if (!credentialsPollingRunning) {
+            return;
         }
+        pollCredentialsAndSync()
+            .catch((error) => {
+            agentLog(`Credentials poll failed: ${error}`);
+        })
+            .finally(() => {
+            // Schedule next poll (only if still running)
+            if (credentialsPollingRunning) {
+                setTimeout(poll, CREDENTIALS_POLL_INTERVAL_MS);
+            }
+        });
+    };
+    // Start first poll after delay
+    setTimeout(poll, CREDENTIALS_POLL_INTERVAL_MS);
+    agentLog('Credentials polling started');
+}
+/**
+ * Stop credentials polling.
+ */
+function stopCredentialsPolling() {
+    credentialsPollingRunning = false;
+}
+// ============================================================================
+// Agent Status Reporting
+// ============================================================================
+/**
+ * Get current agent status for health check.
+ * Used by Transport to check if agent is ready before forwarding tasks.
+ */
+function getAgentStatus() {
+    return {
+        activeTasks: taskQueueManager.getActiveCount(),
+        hasAuth: cachedCredentials !== undefined,
+        // Check both spaceId and teamId for safety (both must be set after /init)
+        hasConfig: cachedCredentials?.spaceId !== undefined && cachedCredentials?.teamId !== undefined,
+        isInitialized: isAgentInitialized,
+        lastError: initializationError?.message,
+        queuedTasks: taskQueueManager.getQueuedCount(),
     };
-    // Start first check after delay
-    setTimeout(checkParent, PARENT_HEARTBEAT_INTERVAL_MS);
-    agentLog(`Parent heartbeat monitoring started (PPID: ${parentPid})`);
 }
 /**
- * Stop the parent heartbeat monitoring.
- * With recursive setTimeout, just set flag to false - next check won't schedule.
+ * Broadcast status change to Transport.
+ * Called when cipher state changes (init success/fail, stop, credentials change).
+ * Transport will forward to all connected clients.
  */
-function stopParentHeartbeat() {
-    parentHeartbeatRunning = false;
+function broadcastStatusChange() {
+    const status = getAgentStatus();
+    transportClient?.request('agent:status:changed', status).catch(logTransportError);
 }
 /**
  * Stop Agent Process.
@@ -615,8 +1095,9 @@ async function stopAgent() {
     }
     isCleaningUp = true;
     try {
-        // Stop parent heartbeat first
-        stopParentHeartbeat();
+        // Stop polling and heartbeat first
+        stopCredentialsPolling();
+        parentHeartbeat?.stop();
         // Clear task queue
         taskQueueManager.clear();
         // Cleanup event forwarders before stopping agent
@@ -648,7 +1129,14 @@ async function runWorker() {
         sendToParent({ type: 'ready' });
         // Start parent heartbeat monitoring after ready
         // This ensures we self-terminate if parent dies (SIGKILL scenario)
-        setupParentHeartbeat();
+        parentHeartbeat = createParentHeartbeat({
+            cleanup: stopAgent,
+            log: agentLog,
+        });
+        parentHeartbeat.start();
+        // Start credentials polling to detect auth/config changes
+        // This ensures CipherAgent stays in sync with user's login state
+        startCredentialsPolling();
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -661,14 +1149,47 @@ async function runWorker() {
     }
     // IPC message handler
     process.on('message', async (msg) => {
-        if (msg.type === 'ping') {
-            sendToParent({ type: 'pong' });
-        }
-        else if (msg.type === 'shutdown') {
-            await stopAgent();
-            sendToParent({ type: 'stopped' });
-            // eslint-disable-next-line n/no-process-exit
-            process.exit(0);
+        switch (msg.type) {
+            case 'health-check': {
+                // Fix #3: Health-check after sleep/wake - verify and repair connection
+                agentLog('Received health-check from parent - verifying connection');
+                // Guard: skip health check during initialization (would interfere with startup sequence)
+                if (isInitializing) {
+                    agentLog('Health-check skipped - initialization in progress');
+                    sendToParent({ success: true, type: 'health-check-result' });
+                    break;
+                }
+                // Guard: transportClient must exist for health check
+                if (!transportClient) {
+                    agentLog('Health-check failed - transportClient not initialized');
+                    sendToParent({ success: false, type: 'health-check-result' });
+                    break;
+                }
+                try {
+                    // Re-register with Transport to ensure connection is alive
+                    // Include status in register payload (Transport caches it atomically)
+                    await transportClient.request('agent:register', { status: getAgentStatus() });
+                    agentLog('Health-check passed - connection verified');
+                    sendToParent({ success: true, type: 'health-check-result' });
+                }
+                catch (error) {
+                    agentLog(`Health-check failed - connection may be stale: ${error}`);
+                    sendToParent({ success: false, type: 'health-check-result' });
+                    // Socket.IO will attempt reconnection automatically
+                }
+                break;
+            }
+            case 'ping': {
+                sendToParent({ type: 'pong' });
+                break;
+            }
+            case 'shutdown': {
+                await stopAgent();
+                sendToParent({ type: 'stopped' });
+                // eslint-disable-next-line n/no-process-exit
+                process.exit(0);
+                // Note: break unreachable due to process.exit() above
+            }
         }
     });
     // Signal handlers