@teamvibe/poller 0.1.45 → 0.1.47

package/dist/claude-spawner.js

@@ -82,6 +82,10 @@ async function countNewThreadMessages(botToken, channel, threadTs, sinceTs) {
     }
 }
 function buildPrompt(msg, resumeHint) {
+    // Heartbeat messages get a minimal prompt — CLAUDE.md/MAINTENANCE.md handle the rest
+    if (msg.source === 'heartbeat') {
+        return 'heartbeat';
+    }
     let prompt = '## Incoming Slack Message\n\n';
     prompt += `**From:** ${msg.sender.name}`;
     if (msg.sender.id && msg.sender.id !== msg.sender.name) {
@@ -173,7 +177,8 @@ function formatStreamEvent(event) {
 async function runClaudeCode(msg, sessionLog, cwd, sessionId, isFirstMessage = true, lastMessageTs, onMessageSent, typingIndicator) {
     const slackContext = msg.response_context.slack;
     const isCronMessage = msg.source === 'cron';
-    if (!slackContext && !isCronMessage) {
+    const isHeartbeat = msg.source === 'heartbeat';
+    if (!slackContext && !isCronMessage && !isHeartbeat) {
         throw new Error('No Slack context in message');
     }
     // Build resume hint

package/dist/config.d.ts

@@ -12,6 +12,7 @@ declare const configSchema: z.ZodObject<{
     HEARTBEAT_INTERVAL_MS: z.ZodDefault<z.ZodNumber>;
     CLAUDE_TIMEOUT_MS: z.ZodDefault<z.ZodNumber>;
     STALE_LOCK_TIMEOUT_MS: z.ZodDefault<z.ZodNumber>;
+    LOCK_RETRY_INTERVAL_MS: z.ZodDefault<z.ZodNumber>;
     TEAMVIBE_DATA_DIR: z.ZodDefault<z.ZodString>;
     BRAINS_PATH: z.ZodDefault<z.ZodString>;
     DEFAULT_BRAIN_PATH: z.ZodDefault<z.ZodString>;
@@ -22,6 +23,9 @@ declare const configSchema: z.ZodObject<{
     BASE_BRAIN_PATH: z.ZodDefault<z.ZodString>;
     BRAIN_AUTO_UPDATE: z.ZodEffects<z.ZodDefault<z.ZodString>, boolean, string | undefined>;
     BRAIN_UPDATE_COOLDOWN_MS: z.ZodDefault<z.ZodNumber>;
+    MAINTENANCE_INTERVAL_MS: z.ZodDefault<z.ZodNumber>;
+    MAINTENANCE_CHECK_INTERVAL_MS: z.ZodDefault<z.ZodNumber>;
+    MAINTENANCE_ENABLED: z.ZodEffects<z.ZodDefault<z.ZodString>, boolean, string | undefined>;
 }, "strip", z.ZodTypeAny, {
     AWS_REGION: string;
     TEAMVIBE_API_URL: string;
@@ -31,6 +35,7 @@ declare const configSchema: z.ZodObject<{
     HEARTBEAT_INTERVAL_MS: number;
     CLAUDE_TIMEOUT_MS: number;
     STALE_LOCK_TIMEOUT_MS: number;
+    LOCK_RETRY_INTERVAL_MS: number;
     TEAMVIBE_DATA_DIR: string;
     BRAINS_PATH: string;
     DEFAULT_BRAIN_PATH: string;
@@ -41,6 +46,9 @@ declare const configSchema: z.ZodObject<{
     BASE_BRAIN_PATH: string;
     BRAIN_AUTO_UPDATE: boolean;
     BRAIN_UPDATE_COOLDOWN_MS: number;
+    MAINTENANCE_INTERVAL_MS: number;
+    MAINTENANCE_CHECK_INTERVAL_MS: number;
+    MAINTENANCE_ENABLED: boolean;
     SQS_QUEUE_URL?: string | undefined;
     SESSIONS_TABLE?: string | undefined;
     TEAMVIBE_POLLER_TOKEN?: string | undefined;
@@ -56,6 +64,7 @@ declare const configSchema: z.ZodObject<{
     HEARTBEAT_INTERVAL_MS?: number | undefined;
     CLAUDE_TIMEOUT_MS?: number | undefined;
     STALE_LOCK_TIMEOUT_MS?: number | undefined;
+    LOCK_RETRY_INTERVAL_MS?: number | undefined;
     TEAMVIBE_DATA_DIR?: string | undefined;
     BRAINS_PATH?: string | undefined;
     DEFAULT_BRAIN_PATH?: string | undefined;
@@ -66,6 +75,9 @@ declare const configSchema: z.ZodObject<{
     BASE_BRAIN_PATH?: string | undefined;
     BRAIN_AUTO_UPDATE?: string | undefined;
     BRAIN_UPDATE_COOLDOWN_MS?: number | undefined;
+    MAINTENANCE_INTERVAL_MS?: number | undefined;
+    MAINTENANCE_CHECK_INTERVAL_MS?: number | undefined;
+    MAINTENANCE_ENABLED?: string | undefined;
 }>;
 export type Config = z.infer<typeof configSchema>;
 export declare function loadConfig(): Config;
@@ -78,6 +90,7 @@ export declare const config: {
     HEARTBEAT_INTERVAL_MS: number;
     CLAUDE_TIMEOUT_MS: number;
     STALE_LOCK_TIMEOUT_MS: number;
+    LOCK_RETRY_INTERVAL_MS: number;
     TEAMVIBE_DATA_DIR: string;
     BRAINS_PATH: string;
     DEFAULT_BRAIN_PATH: string;
@@ -88,6 +101,9 @@ export declare const config: {
     BASE_BRAIN_PATH: string;
     BRAIN_AUTO_UPDATE: boolean;
     BRAIN_UPDATE_COOLDOWN_MS: number;
+    MAINTENANCE_INTERVAL_MS: number;
+    MAINTENANCE_CHECK_INTERVAL_MS: number;
+    MAINTENANCE_ENABLED: boolean;
     SQS_QUEUE_URL?: string | undefined;
     SESSIONS_TABLE?: string | undefined;
     TEAMVIBE_POLLER_TOKEN?: string | undefined;

package/dist/config.js

@@ -21,6 +21,7 @@ const configSchema = z.object({
     HEARTBEAT_INTERVAL_MS: z.coerce.number().default(40000), // 40 seconds
     CLAUDE_TIMEOUT_MS: z.coerce.number().default(3600000), // 60 minutes
     STALE_LOCK_TIMEOUT_MS: z.coerce.number().default(3900000), // 65 minutes
+    LOCK_RETRY_INTERVAL_MS: z.coerce.number().default(30000), // 30 seconds
     // Paths
     TEAMVIBE_DATA_DIR: z.string().default(DEFAULT_DATA_DIR),
     BRAINS_PATH: z.string().default(''),
@@ -37,6 +38,10 @@ const configSchema = z.object({
         .default('true')
         .transform((v) => v.toLowerCase() === 'true'),
     BRAIN_UPDATE_COOLDOWN_MS: z.coerce.number().default(300000), // 5 minutes
+    // Maintenance heartbeat
+    MAINTENANCE_INTERVAL_MS: z.coerce.number().default(21600000), // 6 hours between maintenance per brain
+    MAINTENANCE_CHECK_INTERVAL_MS: z.coerce.number().default(300000), // 5 min check loop
+    MAINTENANCE_ENABLED: z.string().default('true').transform((v) => v.toLowerCase() === 'true'),
 });
 export function loadConfig() {
     const result = configSchema.safeParse(process.env);

package/dist/heartbeat-manager.d.ts

@@ -0,0 +1,19 @@
+import type { TeamVibeQueueMessage } from './types.js';
+/**
+ * Register a brain from a real message so we know about it for heartbeats.
+ * Called from processMessage() after brain path is resolved.
+ */
+export declare function registerBrain(msg: TeamVibeQueueMessage): void;
+/**
+ * Start the periodic heartbeat check loop.
+ * Checks every MAINTENANCE_CHECK_INTERVAL_MS whether any brain needs maintenance.
+ */
+export declare function startHeartbeatLoop(processMessageFn: (msg: {
+    queueMessage: TeamVibeQueueMessage;
+    receiptHandle: string;
+    messageId: string;
+}) => Promise<void>): void;
+/**
+ * Stop the heartbeat loop (for shutdown).
+ */
+export declare function stopHeartbeatLoop(): void;

package/dist/heartbeat-manager.js

@@ -0,0 +1,101 @@
+import { config } from './config.js';
+import { logger } from './logger.js';
+import { isAtCapacity } from './claude-spawner.js';
+const trackedBrains = new Map();
+let heartbeatInterval = null;
+/**
+ * Register a brain from a real message so we know about it for heartbeats.
+ * Called from processMessage() after brain path is resolved.
+ */
+export function registerBrain(msg) {
+    const brain = msg.teamvibe.brain;
+    if (!brain?.brainId)
+        return;
+    // Don't register from heartbeat messages (avoid self-referential loop)
+    if (msg.source === 'heartbeat')
+        return;
+    const existing = trackedBrains.get(brain.brainId);
+    // Update brain info but preserve lastHeartbeat if it exists
+    trackedBrains.set(brain.brainId, {
+        brainId: brain.brainId,
+        gitRepoUrl: brain.gitRepoUrl,
+        branch: brain.branch,
+        workspaceId: msg.teamvibe.workspaceId,
+        botId: msg.teamvibe.botId,
+        botToken: msg.teamvibe.botToken,
+        channelId: msg.teamvibe.channelId,
+        lastHeartbeat: existing?.lastHeartbeat ?? 0,
+    });
+    logger.debug(`[Heartbeat] Registered brain: ${brain.brainId}`);
+}
+/**
+ * Start the periodic heartbeat check loop.
+ * Checks every MAINTENANCE_CHECK_INTERVAL_MS whether any brain needs maintenance.
+ */
+export function startHeartbeatLoop(processMessageFn) {
+    if (!config.MAINTENANCE_ENABLED) {
+        logger.info('[Heartbeat] Maintenance disabled via config');
+        return;
+    }
+    logger.info(`[Heartbeat] Starting heartbeat loop (check every ${config.MAINTENANCE_CHECK_INTERVAL_MS}ms, interval ${config.MAINTENANCE_INTERVAL_MS}ms)`);
+    heartbeatInterval = setInterval(async () => {
+        const now = Date.now();
+        for (const [brainId, info] of trackedBrains.entries()) {
+            const elapsed = now - info.lastHeartbeat;
+            if (elapsed < config.MAINTENANCE_INTERVAL_MS) {
+                continue;
+            }
+            if (isAtCapacity()) {
+                logger.debug(`[Heartbeat] At capacity, skipping heartbeat for ${brainId}`);
+                continue;
+            }
+            logger.info(`[Heartbeat] Triggering maintenance for brain ${brainId} (last: ${info.lastHeartbeat === 0 ? 'never' : `${Math.round(elapsed / 60000)}m ago`})`);
+            // Update lastHeartbeat immediately to prevent double-triggering
+            info.lastHeartbeat = now;
+            const syntheticMessage = {
+                id: `heartbeat_${brainId}_${now}`,
+                source: 'heartbeat',
+                thread_id: `heartbeat_${brainId}_${now}`,
+                sender: {
+                    id: 'system',
+                    name: 'System',
+                },
+                text: 'heartbeat',
+                attachments: [],
+                response_context: {},
+                type: 'message',
+                teamvibe: {
+                    workspaceId: info.workspaceId,
+                    botId: info.botId,
+                    botToken: info.botToken,
+                    channelId: info.channelId,
+                    brain: {
+                        brainId: info.brainId,
+                        gitRepoUrl: info.gitRepoUrl,
+                        branch: info.branch,
+                    },
+                },
+            };
+            try {
+                await processMessageFn({
+                    queueMessage: syntheticMessage,
+                    receiptHandle: '', // No SQS receipt for synthetic messages
+                    messageId: syntheticMessage.id,
+                });
+            }
+            catch (error) {
+                logger.error(`[Heartbeat] Failed maintenance for ${brainId}: ${error instanceof Error ? error.message : error}`);
+            }
+        }
+    }, config.MAINTENANCE_CHECK_INTERVAL_MS);
+}
+/**
+ * Stop the heartbeat loop (for shutdown).
+ */
+export function stopHeartbeatLoop() {
+    if (heartbeatInterval) {
+        clearInterval(heartbeatInterval);
+        heartbeatInterval = null;
+        logger.info('[Heartbeat] Stopped heartbeat loop');
+    }
+}

package/dist/poller.js

@@ -6,6 +6,7 @@ import { sendSlackError, addReaction, getUserInfo, startTypingIndicator } from '
 import { acquireSessionLock, releaseSessionLock, updateSessionId } from './session-store.js';
 import { getBrainPath, ensureDirectories, ensureBaseBrain, pushBrainChanges } from './brain-manager.js';
 import { initAuth, stopRefresh } from './auth-provider.js';
+import { registerBrain, startHeartbeatLoop, stopHeartbeatLoop } from './heartbeat-manager.js';
 // Track active message processing
 const processingMessages = new Set();
 // Per-thread completion signals
@@ -27,7 +28,9 @@ function logQueueState(context) {
     logger.info(`[Queue] ${context} | Processing: ${stats.processing}, Threads with waiting: ${stats.threadsWithWaiting}, Total waiting: ${stats.totalWaiting}`);
 }
 function waitForThreadCompletion(threadId) {
-    return new Promise((resolve) => {
+    let resolveFn;
+    const promise = new Promise((resolve) => {
+        resolveFn = resolve;
         const signals = threadCompletionSignals.get(threadId) || [];
         signals.push(resolve);
         threadCompletionSignals.set(threadId, signals);
@@ -36,6 +39,25 @@ function waitForThreadCompletion(threadId) {
         logger.info(`[Queue] Thread ${threadId}: ${currentCount + 1} message(s) now waiting`);
         logQueueState('After enqueue');
     });
+    const cancel = () => {
+        // Remove this specific resolve from the signals array
+        const signals = threadCompletionSignals.get(threadId);
+        if (signals) {
+            const idx = signals.indexOf(resolveFn);
+            if (idx !== -1)
+                signals.splice(idx, 1);
+            if (signals.length === 0)
+                threadCompletionSignals.delete(threadId);
+        }
+        const count = waitingCountByThread.get(threadId) || 0;
+        if (count <= 1) {
+            waitingCountByThread.delete(threadId);
+        }
+        else {
+            waitingCountByThread.set(threadId, count - 1);
+        }
+    };
+    return { promise, cancel };
 }
 function signalThreadCompletion(threadId) {
     const signals = threadCompletionSignals.get(threadId);
@@ -65,7 +87,7 @@ async function processMessage(received) {
     const threadId = queueMessage.thread_id;
     const sessionLog = logger.createSession(logSessionId);
     // Fetch user info if we only have ID
-    if (queueMessage.source !== 'cron' &&
+    if (queueMessage.source !== 'cron' && queueMessage.source !== 'heartbeat' &&
         queueMessage.sender.name === 'Unknown User' &&
         queueMessage.sender.id !== 'unknown') {
         const userInfo = await getUserInfo(queueMessage.teamvibe.botToken, queueMessage.sender.id);
@@ -96,22 +118,40 @@ async function processMessage(received) {
                 sessionLog.error(`Failed to send Slack error: ${slackError}`);
             }
         }
-        await deleteMessage(receiptHandle);
+        if (receiptHandle) {
+            await deleteMessage(receiptHandle);
+        }
         return;
     }
+    // Register brain for heartbeat tracking
+    registerBrain(queueMessage);
     // Try to acquire session lock
     let lockResult = await acquireSessionLock(threadId, kbPath);
     if (!lockResult.success) {
         sessionLog.info(`Session ${threadId} is processing, waiting for completion...`);
         const waitHeartbeat = startHeartbeat(receiptHandle, sessionLog);
         try {
-            await waitForThreadCompletion(threadId);
-            sessionLog.info(`Thread ${threadId} completed, retrying lock acquisition`);
-            lockResult = await acquireSessionLock(threadId, kbPath);
+            const maxWaitMs = config.STALE_LOCK_TIMEOUT_MS;
+            const retryIntervalMs = config.LOCK_RETRY_INTERVAL_MS;
+            const waitStart = Date.now();
+            while (Date.now() - waitStart < maxWaitMs) {
+                const waiter = waitForThreadCompletion(threadId);
+                // Wait for either: completion signal OR retry interval timeout
+                await Promise.race([
+                    waiter.promise,
+                    sleep(retryIntervalMs),
+                ]);
+                // Clean up the waiter (handles the timeout case where signal didn't fire)
+                waiter.cancel();
+                lockResult = await acquireSessionLock(threadId, kbPath);
+                if (lockResult.success)
+                    break;
+                sessionLog.info(`Lock still held for ${threadId}, retrying in ${retryIntervalMs / 1000}s...`);
+            }
             if (!lockResult.success) {
-                sessionLog.info('Lock still held, re-queuing for next completion');
-                clearInterval(waitHeartbeat);
-                return processMessage(received);
+                sessionLog.error(`Gave up waiting for lock on ${threadId} after ${maxWaitMs / 1000}s`);
+                await deleteMessage(receiptHandle);
+                return;
             }
         }
         finally {
@@ -160,7 +200,9 @@ async function processMessage(received) {
                 await releaseSessionLock(threadId, lockToken, 'idle');
             }
         }
-        await deleteMessage(receiptHandle);
+        if (receiptHandle) {
+            await deleteMessage(receiptHandle);
+        }
         sessionLog.info('Message processed and deleted');
     }
     catch (error) {
@@ -198,6 +240,25 @@ async function processMessage(received) {
         signalThreadCompletion(threadId);
     }
 }
+function deduplicateMessages(messages) {
+    const byThread = new Map();
+    for (const msg of messages) {
+        const threadId = msg.queueMessage.thread_id;
+        const existing = byThread.get(threadId) || [];
+        existing.push(msg);
+        byThread.set(threadId, existing);
+    }
+    const unique = [];
+    const duplicates = [];
+    for (const [, msgs] of byThread) {
+        // Keep the last message (most recent), mark rest as duplicates
+        unique.push(msgs[msgs.length - 1]);
+        for (let i = 0; i < msgs.length - 1; i++) {
+            duplicates.push(msgs[i]);
+        }
+    }
+    return { unique, duplicates };
+}
 async function pollLoop() {
     logger.info('Poll loop started');
     while (!shuttingDown) {
@@ -215,7 +276,16 @@ async function pollLoop() {
             }
             logger.info(`Received ${messages.length} message(s) from SQS`);
             logQueueState('After SQS poll');
-            const processPromises = messages.map((msg) => processMessage(msg).catch((error) => {
+            // Deduplicate: if multiple messages for the same thread, keep only the latest
+            const { unique, duplicates } = deduplicateMessages(messages);
+            for (const dup of duplicates) {
+                logger.info(`Deleting duplicate message for thread ${dup.queueMessage.thread_id} (messageId: ${dup.messageId})`);
+                await deleteMessage(dup.receiptHandle);
+            }
+            if (duplicates.length > 0) {
+                logger.info(`Deduplicated: ${messages.length} -> ${unique.length} message(s)`);
+            }
+            const processPromises = unique.map((msg) => processMessage(msg).catch((error) => {
                 logger.error(`Failed to process message ${msg.messageId}:`, error);
             }));
             // Don't await - let them run in parallel
@@ -238,6 +308,7 @@ async function shutdown(signal) {
     shuttingDown = true;
     logger.info(`${signal} received, shutting down gracefully...`);
     stopRefresh();
+    stopHeartbeatLoop();
     // Unblock all messages waiting on thread completion so they can exit
     for (const [threadId, signals] of threadCompletionSignals.entries()) {
         logger.info(`Unblocking ${signals.length} waiting message(s) on thread ${threadId}`);
@@ -277,5 +348,22 @@ export async function startPoller() {
     }
     await ensureDirectories();
     await ensureBaseBrain();
-    await pollLoop();
+    startHeartbeatLoop(processMessage);
+    // Periodic queue health check — surfaces stuck messages in logs
+    const healthCheckInterval = setInterval(() => {
+        const stats = getQueueStats();
+        if (stats.totalWaiting > 0) {
+            logger.warn(`[Queue Health] ${stats.totalWaiting} message(s) waiting across ${stats.threadsWithWaiting} thread(s), ` +
+                `${stats.processing} actively processing`);
+            for (const [threadId, count] of waitingCountByThread.entries()) {
+                logger.warn(`[Queue Health]   Thread ${threadId}: ${count} waiting`);
+            }
+        }
+    }, 60000);
+    try {
+        await pollLoop();
+    }
+    finally {
+        clearInterval(healthCheckInterval);
+    }
 }

package/dist/types.d.ts

@@ -1,6 +1,6 @@
 export interface TeamVibeQueueMessage {
     id: string;
-    source: 'slack' | 'cron';
+    source: 'slack' | 'cron' | 'heartbeat';
     thread_id: string;
     sender: {
         id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teamvibe/poller",
-  "version": "0.1.45",
+  "version": "0.1.47",
   "type": "module",
   "main": "./dist/index.js",
   "bin": {