@teamvibe/poller 0.4.4 → 0.5.1

package/dist/brain-manager.d.ts

@@ -4,6 +4,11 @@ interface BrainConfig {
     branch: string;
 }
 export declare function getBrainPath(brain?: BrainConfig, channelId?: string, workspaceId?: string): Promise<string>;
+/**
+ * Update a brain repo (respects cooldown). Exported for testing — production
+ * call sites should go through `getBrainPath` / `ensureBaseBrain`.
+ */
+export declare function updateBrain(brainDir: string, brainId: string, branch: string): Promise<void>;
 /**
  * Ensure base brain repo is cloned and up to date.
  * Uses same cooldown pattern as channel brains.

package/dist/brain-manager.js

@@ -90,15 +90,53 @@ export async function getBrainPath(brain, channelId, workspaceId) {
     return brainDir;
 }
 /**
- * Update a brain repo (respects cooldown)
+ * Update a brain repo (respects cooldown). Exported for testing — production
+ * call sites should go through `getBrainPath` / `ensureBaseBrain`.
  */
-async function updateBrain(brainDir, brainId, branch) {
+export async function updateBrain(brainDir, brainId, branch) {
     const now = Date.now();
     const lastUpdate = lastUpdateTimes.get(brainId) || 0;
     if (now - lastUpdate < config.BRAIN_UPDATE_COOLDOWN_MS) {
         logger.debug(`Brain ${brainId} update skipped - cooldown active (${Math.round((config.BRAIN_UPDATE_COOLDOWN_MS - (now - lastUpdate)) / 1000)}s remaining)`);
         return;
     }
+    // Guard: skip `reset --hard` when the working tree has uncommitted writes or
+    // unpushed commits, otherwise an in-flight session's mid-message memory
+    // writes (e.g. memory/TODAY.md, MEM_REGISTRY.md) get silently wiped on the
+    // next message arrival after the cooldown elapses. Fail-safe direction —
+    // pushBrainChanges at session-end reconciles drift on the happy path; the
+    // structural fix is worktree isolation (see #205). Mirrors no-upstream
+    // handling in pushBrainChanges below.
+    try {
+        const { stdout: dirty } = await gitExec('git status --porcelain', { cwd: brainDir });
+        let hasLocalCommits = false;
+        try {
+            const { stdout: unpushed } = await gitExec('git log @{u}..HEAD --oneline', { cwd: brainDir });
+            hasLocalCommits = !!unpushed.trim();
+        }
+        catch {
+            // No upstream tracking (detached HEAD, mid-rebase, or `git init`-bootstrapped
+            // brain dir; a normal `git clone` always sets up tracking). Broken upstream
+            // tracking → skip aggressively; manual investigation preferred over a silent
+            // --hard reset.
+            const { stdout: commits } = await gitExec('git log --oneline -1', { cwd: brainDir });
+            hasLocalCommits = !!commits.trim();
+        }
+        if (dirty.trim() || hasLocalCommits) {
+            // TODO(#205-followup): emit operational alert if a brain skips reset for > N hours —
+            // long-term skip means pushBrainChanges is persistently failing and the brain is
+            // silently drifting away from base-brain / skills updates.
+            logger.info(`Brain ${brainId} update skipped — local changes present (dirty=${!!dirty.trim()}, hasLocalCommits=${hasLocalCommits})`);
+            return;
+        }
+    }
+    catch (error) {
+        // Pre-check itself failed (e.g. brainDir not a git repo). Fail-safe to skip;
+        // the next iteration will retry.
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.warn(`Brain ${brainId} pre-check failed, skipping update: ${errorMessage}`);
+        return;
+    }
     try {
         logger.info(`Updating brain ${brainId} at ${brainDir}...`);
         await gitExec(`git fetch origin ${branch} && git reset --hard origin/${branch} && git submodule update --init --recursive`, {

package/dist/classify-failed-iteration.d.ts

@@ -0,0 +1,16 @@
+export type KilledByPoller = 'timeout' | 'idle' | 'zombie' | 'network';
+export interface FailedIterationInput {
+    error?: string;
+    exitCode: number | null;
+    killedByPoller?: KilledByPoller;
+}
+export type FailedIterationDecision = {
+    kind: 'neutral';
+    text: string;
+    reaction: string;
+} | {
+    kind: 'error';
+    text: string;
+    reaction: string;
+};
+export declare function classifyFailedIteration(result: FailedIterationInput): FailedIterationDecision;

package/dist/classify-failed-iteration.js

@@ -0,0 +1,53 @@
+// Decides how to surface a failed claude-spawner iteration to the user.
+//
+// Background (teamvibe.ai#193): poller-induced kills (timeout, idle watchdog,
+// network watchdog, zombie cleanup) used to leak as generic
+// "Error processing your request: Process exited with code 143" via
+// sendSlackError. The explicit `killedByPoller` intent marker (set by the
+// spawner before SIGTERM) lets us emit a neutral 1-sentence notice instead —
+// "Session paused — send another message to resume." — which tells the user
+// *what happened* and *what to do*, without false-flagging an internal kill
+// as an application failure.
+//
+// Pattern: explicit intent marker > exit-code pattern matching (143/137).
+// Exit codes are fragile — the Claude binary can legitimately return 143
+// for unrelated reasons; the marker decides on poller intent, not process
+// output.
+export function classifyFailedIteration(result) {
+    switch (result.killedByPoller) {
+        case 'idle':
+            return {
+                kind: 'neutral',
+                text: 'Session paused (idle timeout) — send another message to resume.',
+                reaction: 'zzz',
+            };
+        case 'zombie':
+            return {
+                kind: 'neutral',
+                text: "Process didn't shut down cleanly — send another message to restart.",
+                reaction: 'recycle',
+            };
+        case 'network':
+            return {
+                kind: 'neutral',
+                text: 'Network connectivity lost — send another message to retry.',
+                reaction: 'satellite_antenna',
+            };
+        case 'timeout':
+        case undefined: {
+            // 'timeout' keeps the legacy ":warning: Session timed out after N
+            // minutes..." surface unchanged (the error string is set by the
+            // spawner). undefined = genuine failure → keep current behavior.
+            const text = result.error || `Process exited with code ${result.exitCode}`;
+            const isTimeout = result.killedByPoller === 'timeout' || text.includes('timed out');
+            return { kind: 'error', text, reaction: isTimeout ? 'hourglass' : 'x' };
+        }
+        default: {
+            // Exhaustiveness guard: adding a new member to KilledByPoller without
+            // handling it here will fail to compile (never assignment). Runtime
+            // throw is the fallback for tsconfigs without noImplicitReturns.
+            const _exhaustive = result.killedByPoller;
+            throw new Error(`Unhandled killedByPoller: ${String(_exhaustive)}`);
+        }
+    }
+}

package/dist/claude-spawner.d.ts

@@ -1,14 +1,28 @@
 import type { TeamVibeQueueMessage, SessionMetrics } from './types.js';
 import { type SessionLogger } from './logger.js';
 import type { TypingIndicator } from './slack-client.js';
+import type { KilledByPoller } from './classify-failed-iteration.js';
+export interface ContextHintParams {
+    isFirstMessage: boolean;
+    lastMessageTs?: string;
+    slack?: {
+        channel: string;
+        thread_ts: string;
+        message_ts: string;
+    };
+    countNewSinceTs: (channel: string, threadTs: string, sinceTs: string) => Promise<number>;
+    countPriorBeforeTs: (channel: string, threadTs: string, beforeTs: string) => Promise<number>;
+}
+export declare function buildContextHint(p: ContextHintParams): Promise<string | undefined>;
 export interface SpawnResult {
     success: boolean;
     output: string;
     exitCode: number | null;
     error?: string;
     metrics?: SessionMetrics;
+    killedByPoller?: KilledByPoller;
 }
-export declare function buildPrompt(msg: TeamVibeQueueMessage, resumeHint?: string): string;
+export declare function buildPrompt(msg: TeamVibeQueueMessage, contextHint?: string): string;
 export declare function spawnClaudeCode(msg: TeamVibeQueueMessage, sessionLog: SessionLogger, cwd: string, sessionId?: string, isFirstMessage?: boolean, lastMessageTs?: string, onMessageSent?: () => void, typingIndicator?: TypingIndicator): Promise<SpawnResult & {
     newSessionId?: string;
 }>;

package/dist/claude-spawner.js

@@ -8,6 +8,7 @@ import { getBaseBrainPath } from './brain-manager.js';
 import { getPollerId } from './auth-provider.js';
 import { emitError } from './event-queue.js';
 import { createWorktree, removeWorktree, isWorktreeIsolationEnabled } from './worktree-manager.js';
+import { fetchSecretsForSpawn, buildSecretsReminder } from './secrets-client.js';
 /**
  * Maps tool names (or prefixes) to human-readable status messages.
  * More specific patterns are checked first.
@@ -86,6 +87,68 @@ async function countNewThreadMessages(botToken, channel, threadTs, sinceTs) {
         return 0;
     }
 }
+// Count messages strictly before the message being handled. Used to hint that
+// prior thread context exists when the bot is invoked for the first time on a
+// thread that already has history. Bot-side messages are included — the bot's
+// own past replies are still context the model should be aware of (a fresh
+// session has lost what it said before).
+// TODO: detect has_more to surface a "100+" signal — conversations.replies
+// saturates at limit:100 without telling the caller, so very long threads
+// will be reported as exactly "100 previous messages".
+async function countPriorThreadMessages(botToken, channel, threadTs, currentMessageTs) {
+    try {
+        const slack = getSlackClient(botToken);
+        const result = await slack.conversations.replies({
+            channel,
+            ts: threadTs,
+            limit: 100,
+        });
+        if (!result.messages)
+            return 0;
+        const priorMessages = result.messages.filter((msg) => {
+            if (!msg.ts)
+                return false;
+            return parseFloat(msg.ts) < parseFloat(currentMessageTs);
+        });
+        return priorMessages.length;
+    }
+    catch (error) {
+        logger.warn(`Failed to count prior thread messages: ${error}`);
+        emitError('slack', `Failed to count prior thread messages: ${error instanceof Error ? error.message : String(error)}`, { severity: 'warn' });
+        return 0;
+    }
+}
+// Select and render the context hint that goes into the prompt. Pure aside
+// from the injected counters — extracted from runClaudeCode so the branching
+// (resume vs. thread-context vs. no-hint) can be unit tested without spinning
+// up a Slack WebClient.
+//
+// Branches:
+//  - resumed session (!isFirstMessage && lastMessageTs && slack thread)
+//    → "Resumed session: N new messages …" (or "No new messages" when N=0)
+//  - first-spawn on a thread reply (isFirstMessage && thread_ts !== message_ts)
+//    → "Thread context: N previous messages …" when N>0, else no hint
+//  - everything else (top-level message, resume-without-anchor)
+//    → no hint
+export async function buildContextHint(p) {
+    if (!p.isFirstMessage && p.lastMessageTs && p.slack?.channel && p.slack?.thread_ts) {
+        const newMessageCount = await p.countNewSinceTs(p.slack.channel, p.slack.thread_ts, p.lastMessageTs);
+        return newMessageCount > 0
+            ? `**Resumed session:** ${newMessageCount} new message(s) in the thread since your last response. Consider using \`read_thread\` to see what was discussed before responding.`
+            : `**Resumed session:** No new messages since your last response.`;
+    }
+    if (p.isFirstMessage &&
+        p.slack?.channel &&
+        p.slack?.thread_ts &&
+        p.slack?.message_ts &&
+        p.slack.thread_ts !== p.slack.message_ts) {
+        const priorCount = await p.countPriorBeforeTs(p.slack.channel, p.slack.thread_ts, p.slack.message_ts);
+        if (priorCount > 0) {
+            return `**Thread context:** ${priorCount} previous message(s) in this thread before yours.\nCall \`read_thread\` first to load conversation context.`;
+        }
+    }
+    return undefined;
+}
 /**
  * Read brain settings.json from the brain working directory.
  * Returns parsed settings or empty object if not found.
@@ -104,11 +167,11 @@ function readBrainSettings(cwd) {
         return {};
     }
 }
-export function buildPrompt(msg, resumeHint) {
-    // Heartbeat messages get a minimal prompt — CLAUDE.md/MAINTENANCE.md handle the rest
-    if (msg.source === 'heartbeat') {
-        return 'heartbeat';
-    }
+// Tags procs at SIGTERM time so the close handler can report poller intent.
+// WeakMap auto-cleans when proc is GC'd. Module-scope is required because
+// killZombieForThread fires outside the runClaudeCode closure.
+const killReasonByProc = new WeakMap();
+export function buildPrompt(msg, contextHint) {
     const isEmail = msg.source === 'email';
     const isWebhook = msg.source === 'webhook';
     let prompt = isEmail ? '## Incoming Email\n\n' : isWebhook ? '## Incoming Webhook\n\n' : '## Incoming Slack Message\n\n';
@@ -164,8 +227,8 @@ export function buildPrompt(msg, resumeHint) {
     if (msg.teamvibe.emailHookPrompt) {
         prompt += '\n\n**Channel Instructions:**\n' + msg.teamvibe.emailHookPrompt + '\n';
     }
-    if (resumeHint) {
-        prompt += `\n\n${resumeHint}`;
+    if (contextHint) {
+        prompt += `\n\n${contextHint}`;
     }
     if (isEmail) {
         prompt += `\n\n---\n\nProcess this email and respond appropriately using available tools.`;
@@ -234,31 +297,44 @@ 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';
-    const isHeartbeat = msg.source === 'heartbeat';
     const isMaintenance = msg.source === 'maintenance';
     const isEmailMessage = msg.source === 'email';
     const isWebhookMessage = msg.source === 'webhook';
     if (!slackContext &&
         !isCronMessage &&
-        !isHeartbeat &&
         !isMaintenance &&
         !isEmailMessage &&
         !isWebhookMessage) {
         throw new Error('No Slack context in message');
     }
-    // Build resume hint
-    let resumeHint;
-    if (!isFirstMessage && lastMessageTs && slackContext?.channel && slackContext?.thread_ts) {
-        const newMessageCount = await countNewThreadMessages(msg.teamvibe.botToken, slackContext.channel, slackContext.thread_ts, lastMessageTs);
-        if (newMessageCount > 0) {
-            resumeHint = `**Resumed session:** ${newMessageCount} new message(s) in the thread since your last response. Consider using \`read_thread\` to see what was discussed before responding.`;
-        }
-        else {
-            resumeHint = `**Resumed session:** No new messages since your last response.`;
-        }
-    }
+    // Build context hint — either resume hint (when continuing a session) or
+    // thread context hint (when first-spawning on a thread that already has
+    // prior messages). The two are mutually exclusive: a resume implies the bot
+    // already saw the thread once, so resume's "X new since last response" is
+    // the more informative signal. Logic extracted into buildContextHint for
+    // unit testability — the counters are injected so tests don't need to mock
+    // the Slack WebClient module.
+    const contextHint = await buildContextHint({
+        isFirstMessage,
+        lastMessageTs,
+        slack: slackContext,
+        countNewSinceTs: (ch, tts, since) => countNewThreadMessages(msg.teamvibe.botToken, ch, tts, since),
+        countPriorBeforeTs: (ch, tts, before) => countPriorThreadMessages(msg.teamvibe.botToken, ch, tts, before),
+    });
+    // Fetch secrets for this spawn before entering the Promise constructor —
+    // the executor callback is not async, so awaits must be hoisted out.
+    // Returns an opaque envelope; we unwrap exactly once at the spawn env
+    // construction site below. Reminder metadata (names + scope + expiration
+    // only — never values) feeds the system prompt so the session knows which
+    // ENV variables exist.
+    const spawnSecrets = await fetchSecretsForSpawn({
+        pollerId: getPollerId() || '',
+        workspaceId: msg.teamvibe.workspaceId,
+        channelId: msg.teamvibe.channelId,
+    });
+    const secretsReminder = buildSecretsReminder(spawnSecrets.reminders);
     return new Promise((resolve) => {
-        const prompt = buildPrompt(msg, resumeHint);
+        const prompt = buildPrompt(msg, contextHint);
         // MCP server config passed via --mcp-config flag (no temp files needed)
         const mcpServerPath = join(getBaseBrainPath(), 'mcp', 'slack.mjs');
         const teamvibeApiServerPath = join(getBaseBrainPath(), 'mcp', 'teamvibe-api.mjs');
@@ -302,6 +378,7 @@ async function runClaudeCode(msg, sessionLog, cwd, sessionId, isFirstMessage = t
             `If empty: continue your work.`,
             `You MUST check the inbox: (1) before starting work, (2) after EVERY tool call, (3) after finishing all work.`,
             `Never skip an inbox check. This is how the user communicates with you during long tasks.`,
+            ...(secretsReminder ? ['', secretsReminder] : []),
         ].join('\n'));
         // Handle session continuity
         if (sessionId) {
@@ -323,12 +400,27 @@ async function runClaudeCode(msg, sessionLog, cwd, sessionId, isFirstMessage = t
         const proc = spawn(config.CLAUDE_CLI_PATH, args, {
             cwd,
             env: {
+                // Secrets platform (#105) injection — SOLE call site of
+                // `SpawnSecretsEnvelope.unwrap()` in the entire poller codebase.
+                // Placed FIRST so subsequent spreads can overwrite. Belt-and-
+                // suspenders: even if the API's reserved-prefix validator fails
+                // (`AWS_`, `TEAMVIBE_`, `SLACK_`, `CLAUDE_CODE_`, `ANTHROPIC_`)
+                // a name collision is silently won by the platform variable
+                // explicit field below.
+                //
+                // Phase 2 of teamvibe.ai#215 (poller v0.5.1): the explicit
+                // `SLACK_BOT_TOKEN: msg.teamvibe.botToken` injection that used
+                // to live here was removed. `SLACK_BOT_TOKEN` now sources from
+                // the `/secrets/spawn` platform overlay (the spread above) —
+                // backend v0.2.2+ resolves it via the `Channel → SlackBot`
+                // relation. Requires backend on Phase 1; pollers on 0.5.0 still
+                // read the explicit field, so split rollout is safe.
+                ...spawnSecrets.env.unwrap(),
                 ...process.env,
                 CLAUDECODE: undefined,
                 PATH: envPath,
                 CI: 'true',
                 CLAUDE_CONFIG_DIR: getBaseBrainPath(),
-                SLACK_BOT_TOKEN: msg.teamvibe.botToken,
                 ...(config.PERSISTENT_STORAGE_PATH && {
                     PERSISTENT_STORAGE_PATH: config.PERSISTENT_STORAGE_PATH,
                 }),
@@ -439,15 +531,14 @@ async function runClaudeCode(msg, sessionLog, cwd, sessionId, isFirstMessage = t
                 networkErrorStart = null;
             }
         });
-        let timedOut = false;
         const timeoutMinutes = Math.round(config.CLAUDE_TIMEOUT_MS / 60000);
         const timeout = setTimeout(() => {
-            timedOut = true;
             logger.error(`Claude Code process timed out after ${timeoutMinutes} minutes`);
             emitError('session', `Claude Code process timed out after ${timeoutMinutes} minutes`, {
                 context: { channelId: msg.teamvibe.channelId, threadId: msg.thread_id },
                 channelId: msg.teamvibe.channelId,
             });
+            killReasonByProc.set(proc, 'timeout');
             proc.kill('SIGTERM');
             setTimeout(() => proc.kill('SIGKILL'), 5000);
         }, config.CLAUDE_TIMEOUT_MS);
@@ -465,6 +556,7 @@ async function runClaudeCode(msg, sessionLog, cwd, sessionId, isFirstMessage = t
                         context: { channelId: msg.teamvibe.channelId, threadId: msg.thread_id },
                         channelId: msg.teamvibe.channelId,
                     });
+                    killReasonByProc.set(proc, 'network');
                     proc.kill('SIGTERM');
                     setTimeout(() => proc.kill('SIGKILL'), 5000);
                     return;
@@ -477,6 +569,7 @@ async function runClaudeCode(msg, sessionLog, cwd, sessionId, isFirstMessage = t
                     context: { channelId: msg.teamvibe.channelId, threadId: msg.thread_id },
                     channelId: msg.teamvibe.channelId,
                 });
+                killReasonByProc.set(proc, 'idle');
                 proc.kill('SIGTERM');
                 setTimeout(() => proc.kill('SIGKILL'), 5000);
             }
@@ -496,15 +589,26 @@ async function runClaudeCode(msg, sessionLog, cwd, sessionId, isFirstMessage = t
             clearInterval(idleWatchdog);
             activeProcesses.delete(msg.id);
             activeProcessesByThread.delete(msg.thread_id);
+            const killReason = killReasonByProc.get(proc);
             const result = {
                 success: code === 0,
                 output: stdout,
                 exitCode: code,
                 metrics,
+                ...(killReason ? { killedByPoller: killReason } : {}),
             };
-            if (timedOut) {
+            if (killReason === 'timeout') {
                 result.error = `Session timed out after ${timeoutMinutes} minutes. The task was still running when the time limit was reached. Consider breaking complex tasks into smaller steps.`;
             }
+            else if (killReason === 'idle') {
+                result.error = `Killed by idle watchdog (no output for >${Math.round(config.IDLE_WATCHDOG_KILL_MS / 60000)} minutes)`;
+            }
+            else if (killReason === 'network') {
+                result.error = 'Killed by network watchdog (sustained network errors)';
+            }
+            else if (killReason === 'zombie') {
+                result.error = 'Killed as zombie process (stale session lock)';
+            }
             else if (code !== 0) {
                 result.error = stderr || `Process exited with code ${code}`;
             }
@@ -532,7 +636,7 @@ async function runClaudeCode(msg, sessionLog, cwd, sessionId, isFirstMessage = t
  * Sources whose sessions should run in an isolated git worktree (teamvibe.ai#120).
  * Foreground Slack messages always run in the main working dir.
  */
-const ISOLATED_SOURCES = new Set(['cron', 'heartbeat', 'maintenance']);
+const ISOLATED_SOURCES = new Set(['cron', 'maintenance']);
 function shouldIsolateInWorktree(msg) {
     return isWorktreeIsolationEnabled() && ISOLATED_SOURCES.has(msg.source);
 }
@@ -603,6 +707,7 @@ export function killZombieForThread(threadId) {
     }
     logger.warn(`Killing zombie process for thread ${threadId} (pid: ${proc.pid})`);
     emitError('session', `Killing zombie process for thread ${threadId}`, { severity: 'warn' });
+    killReasonByProc.set(proc, 'zombie');
     proc.kill('SIGTERM');
     setTimeout(() => {
         if (proc.exitCode === null) {

package/dist/config.d.ts

@@ -29,7 +29,6 @@ declare const configSchema: z.ZodObject<{
     BRAIN_AUTO_UPDATE: z.ZodEffects<z.ZodDefault<z.ZodString>, boolean, string | undefined>;
     BRAIN_UPDATE_COOLDOWN_MS: z.ZodDefault<z.ZodNumber>;
     POLLER_TZ: z.ZodOptional<z.ZodString>;
-    HEARTBEAT_CRON: z.ZodDefault<z.ZodString>;
     MAINTENANCE_CRON: z.ZodDefault<z.ZodString>;
     MAINTENANCE_ENABLED: z.ZodEffects<z.ZodDefault<z.ZodString>, boolean, string | undefined>;
     AUTO_UPDATE_POLICY: z.ZodDefault<z.ZodEnum<["patch", "minor", "off"]>>;
@@ -59,7 +58,6 @@ declare const configSchema: z.ZodObject<{
     BASE_BRAIN_PATH: string;
     BRAIN_AUTO_UPDATE: boolean;
     BRAIN_UPDATE_COOLDOWN_MS: number;
-    HEARTBEAT_CRON: string;
     MAINTENANCE_CRON: string;
     MAINTENANCE_ENABLED: boolean;
     AUTO_UPDATE_POLICY: "patch" | "minor" | "off";
@@ -97,7 +95,6 @@ declare const configSchema: z.ZodObject<{
     BRAIN_AUTO_UPDATE?: string | undefined;
     BRAIN_UPDATE_COOLDOWN_MS?: number | undefined;
     POLLER_TZ?: string | undefined;
-    HEARTBEAT_CRON?: string | undefined;
     MAINTENANCE_CRON?: string | undefined;
     MAINTENANCE_ENABLED?: string | undefined;
     AUTO_UPDATE_POLICY?: "patch" | "minor" | "off" | undefined;
@@ -130,7 +127,6 @@ export declare const config: {
     BASE_BRAIN_PATH: string;
     BRAIN_AUTO_UPDATE: boolean;
     BRAIN_UPDATE_COOLDOWN_MS: number;
-    HEARTBEAT_CRON: string;
     MAINTENANCE_CRON: string;
     MAINTENANCE_ENABLED: boolean;
     AUTO_UPDATE_POLICY: "patch" | "minor" | "off";

package/dist/config.js

@@ -43,14 +43,13 @@ const configSchema = z.object({
         .default('true')
         .transform((v) => v.toLowerCase() === 'true'),
     BRAIN_UPDATE_COOLDOWN_MS: z.coerce.number().default(300000), // 5 minutes
-    // Brain heartbeat & maintenance (cron-based)
-    // POLLER_TZ: optional IANA timezone for HEARTBEAT_CRON & MAINTENANCE_CRON.
+    // Brain maintenance (cron-based)
+    // POLLER_TZ: optional IANA timezone for MAINTENANCE_CRON.
     // When unset, croner uses the host system timezone (e.g. `Europe/Prague` on
     // a CZ Mac mini, `UTC` on a default Railway container). Set explicitly
     // (e.g. `POLLER_TZ=Europe/Prague` on Railway) when the host TZ doesn't match
     // the intended cron interpretation. DST is handled by croner automatically.
     POLLER_TZ: z.string().optional(),
-    HEARTBEAT_CRON: z.string().default('0 */6 * * *'), // Every 6 hours
     MAINTENANCE_CRON: z.string().default('30 3 * * *'), // Daily at 03:30 in POLLER_TZ (or host TZ)
     MAINTENANCE_ENABLED: z.string().default('true').transform((v) => v.toLowerCase() === 'true'),
     // Auto-update settings

package/dist/cron-telemetry.d.ts

@@ -1,24 +1,20 @@
 /**
  * Module-scoped state for poller-level cron-job telemetry.
  *
- * Per teamvibeai/teamvibe.ai#119, the metrics collector reports six measures:
- *   last{Heartbeat,Maintenance,AutoUpdate}Job{,Success}Ms
+ * Per teamvibeai/teamvibe.ai#119, the metrics collector reports four measures:
+ *   last{Maintenance,AutoUpdate}Job{,Success}Ms
  * each computed as `Date.now() - storedTs` at collection time, with the
  * measure omitted entirely when the cron has never fired (storedTs null).
  *
- * Pulled out of heartbeat-manager.ts / poller.ts into a dedicated module to
- * avoid a circular import — the metrics collector reads from these getters,
- * and heartbeat-manager.ts already imports from the collector.
+ * Lives in its own module to avoid a circular import — the metrics collector
+ * reads from these getters, and maintenance-cron.ts already imports from the
+ * collector.
  */
-export declare function markHeartbeatJobFired(at?: number): void;
-export declare function markHeartbeatJobSuccess(at?: number): void;
 export declare function markMaintenanceJobFired(at?: number): void;
 export declare function markMaintenanceJobSuccess(at?: number): void;
 export declare function markAutoUpdateJobFired(at?: number): void;
 export declare function markAutoUpdateJobSuccess(at?: number): void;
 export interface CronJobTimestamps {
-    lastHeartbeatJobFiredAt: number | null;
-    lastHeartbeatJobSuccessAt: number | null;
     lastMaintenanceJobFiredAt: number | null;
     lastMaintenanceJobSuccessAt: number | null;
     lastAutoUpdateJobFiredAt: number | null;

package/dist/cron-telemetry.js

@@ -1,27 +1,19 @@
 /**
  * Module-scoped state for poller-level cron-job telemetry.
  *
- * Per teamvibeai/teamvibe.ai#119, the metrics collector reports six measures:
- *   last{Heartbeat,Maintenance,AutoUpdate}Job{,Success}Ms
+ * Per teamvibeai/teamvibe.ai#119, the metrics collector reports four measures:
+ *   last{Maintenance,AutoUpdate}Job{,Success}Ms
  * each computed as `Date.now() - storedTs` at collection time, with the
  * measure omitted entirely when the cron has never fired (storedTs null).
  *
- * Pulled out of heartbeat-manager.ts / poller.ts into a dedicated module to
- * avoid a circular import — the metrics collector reads from these getters,
- * and heartbeat-manager.ts already imports from the collector.
+ * Lives in its own module to avoid a circular import — the metrics collector
+ * reads from these getters, and maintenance-cron.ts already imports from the
+ * collector.
  */
-let lastHeartbeatJobFiredAt = null;
-let lastHeartbeatJobSuccessAt = null;
 let lastMaintenanceJobFiredAt = null;
 let lastMaintenanceJobSuccessAt = null;
 let lastAutoUpdateJobFiredAt = null;
 let lastAutoUpdateJobSuccessAt = null;
-export function markHeartbeatJobFired(at = Date.now()) {
-    lastHeartbeatJobFiredAt = at;
-}
-export function markHeartbeatJobSuccess(at = Date.now()) {
-    lastHeartbeatJobSuccessAt = at;
-}
 export function markMaintenanceJobFired(at = Date.now()) {
     lastMaintenanceJobFiredAt = at;
 }
@@ -36,8 +28,6 @@ export function markAutoUpdateJobSuccess(at = Date.now()) {
 }
 export function getCronJobTimestamps() {
     return {
-        lastHeartbeatJobFiredAt,
-        lastHeartbeatJobSuccessAt,
         lastMaintenanceJobFiredAt,
         lastMaintenanceJobSuccessAt,
         lastAutoUpdateJobFiredAt,
@@ -49,8 +39,6 @@ export function getCronJobTimestamps() {
  * @internal
  */
 export function __resetCronTelemetryForTest() {
-    lastHeartbeatJobFiredAt = null;
-    lastHeartbeatJobSuccessAt = null;
     lastMaintenanceJobFiredAt = null;
     lastMaintenanceJobSuccessAt = null;
     lastAutoUpdateJobFiredAt = null;

package/dist/{heartbeat-manager.d.ts → maintenance-cron.d.ts}

@@ -1,39 +1,28 @@
 import type { TeamVibeQueueMessage } from './types.js';
 /**
- * Register a brain from a real message so we know about it for heartbeats.
+ * Register a brain from a real message so the maintenance cron knows about it.
  * Called from processMessage() after brain path is resolved.
  */
 export declare function registerBrain(msg: TeamVibeQueueMessage): void;
 /**
- * Start the cron-based heartbeat and maintenance schedules.
- *
- * - Heartbeat: lightweight, frequent (default: every 5 min)
- * - Maintenance: heavy, daily (default: 03:30 UTC)
+ * Start the cron-based maintenance schedule (default: daily 03:30 in POLLER_TZ).
  */
-export declare function startHeartbeatLoop(processMessageFn: (msg: {
+export declare function startMaintenanceLoop(processMessageFn: (msg: {
     queueMessage: TeamVibeQueueMessage;
     receiptHandle: string;
     messageId: string;
 }) => Promise<void>): void;
 /**
- * Run the heartbeat cron handler with telemetry instrumentation (#119).
+ * Run the maintenance cron handler with telemetry instrumentation (#119).
  * Records last-fire timestamp on entry and last-success timestamp on completion.
  * Exported for use by the cron registration above and tests that fire it manually.
  */
-export declare function runHeartbeatJob(processMessageFn: (msg: {
-    queueMessage: TeamVibeQueueMessage;
-    receiptHandle: string;
-    messageId: string;
-}) => Promise<void>): Promise<void>;
-/**
- * Run the maintenance cron handler with telemetry instrumentation (#119).
- */
 export declare function runMaintenanceJob(processMessageFn: (msg: {
     queueMessage: TeamVibeQueueMessage;
     receiptHandle: string;
     messageId: string;
 }) => Promise<void>): Promise<void>;
 /**
- * Stop the heartbeat and maintenance crons (for shutdown).
+ * Stop the maintenance cron (for shutdown).
  */
-export declare function stopHeartbeatLoop(): void;
+export declare function stopMaintenanceLoop(): void;

package/dist/{heartbeat-manager.js → maintenance-cron.js}

@@ -6,21 +6,20 @@ import { emitError } from './event-queue.js';
 import { registerBrainForMetrics } from './metrics/scheduler.js';
 import { collectMetrics } from './metrics/collector.js';
 import { sendMetrics } from './metrics/sender.js';
-import { markHeartbeatJobFired, markHeartbeatJobSuccess, markMaintenanceJobFired, markMaintenanceJobSuccess, } from './cron-telemetry.js';
+import { markMaintenanceJobFired, markMaintenanceJobSuccess, } from './cron-telemetry.js';
 import { join } from 'path';
 const trackedBrains = new Map();
-let heartbeatJob = null;
 let maintenanceJob = null;
 /**
- * Register a brain from a real message so we know about it for heartbeats.
+ * Register a brain from a real message so the maintenance cron knows about it.
  * 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/maintenance messages (avoid self-referential loop)
-    if (msg.source === 'heartbeat' || msg.source === 'maintenance')
+    // Don't register from maintenance messages (avoid self-referential loop)
+    if (msg.source === 'maintenance')
         return;
     const isNew = !trackedBrains.has(brain.brainId);
     trackedBrains.set(brain.brainId, {
@@ -32,7 +31,7 @@ export function registerBrain(msg) {
         botToken: msg.teamvibe.botToken,
         channelId: msg.teamvibe.channelId,
     });
-    logger.debug(`[Heartbeat] Registered brain: ${brain.brainId}`);
+    logger.debug(`[Maintenance] Registered brain: ${brain.brainId}`);
     // Metrics pipeline (teamvibe.ai#110): register for hourly collection. On the
     // first sighting of this brain, fire one immediate collect+send so we don't
     // wait up to an hour for the first sample.
@@ -52,25 +51,25 @@ export function registerBrain(msg) {
     }
 }
 /**
- * Send a synthetic message to all tracked brains.
+ * Send a synthetic maintenance message to all tracked brains.
  */
-async function triggerAllBrains(source, processMessageFn) {
+async function triggerAllBrains(processMessageFn) {
     const now = Date.now();
     for (const [brainId, info] of trackedBrains.entries()) {
         if (isAtCapacity()) {
-            logger.debug(`[${source}] At capacity, skipping ${brainId}`);
+            logger.debug(`[Maintenance] At capacity, skipping ${brainId}`);
             continue;
         }
-        logger.info(`[${source}] Triggering ${source} for brain ${brainId}`);
+        logger.info(`[Maintenance] Triggering maintenance for brain ${brainId}`);
         const syntheticMessage = {
-            id: `${source}_${brainId}_${now}`,
-            source,
-            thread_id: `${source}_${brainId}_${now}`,
+            id: `maintenance_${brainId}_${now}`,
+            source: 'maintenance',
+            thread_id: `maintenance_${brainId}_${now}`,
             sender: {
                 id: 'system',
                 name: 'System',
             },
-            text: source,
+            text: 'maintenance',
             attachments: [],
             response_context: {},
             type: 'message',
@@ -94,8 +93,8 @@ async function triggerAllBrains(source, processMessageFn) {
             });
         }
         catch (error) {
-            logger.error(`[${source}] Failed for ${brainId}: ${error instanceof Error ? error.message : error}`);
-            emitError('session', `${source} failed for ${brainId}: ${error instanceof Error ? error.message : String(error)}`, {
+            logger.error(`[Maintenance] Failed for ${brainId}: ${error instanceof Error ? error.message : error}`);
+            emitError('session', `maintenance failed for ${brainId}: ${error instanceof Error ? error.message : String(error)}`, {
                 channelId: info.channelId,
                 context: { brainId },
             });
@@ -103,14 +102,11 @@ async function triggerAllBrains(source, processMessageFn) {
     }
 }
 /**
- * Start the cron-based heartbeat and maintenance schedules.
- *
- * - Heartbeat: lightweight, frequent (default: every 5 min)
- * - Maintenance: heavy, daily (default: 03:30 UTC)
+ * Start the cron-based maintenance schedule (default: daily 03:30 in POLLER_TZ).
  */
-export function startHeartbeatLoop(processMessageFn) {
+export function startMaintenanceLoop(processMessageFn) {
     if (!config.MAINTENANCE_ENABLED) {
-        logger.info('[Heartbeat] Maintenance disabled via config');
+        logger.info('[Maintenance] Maintenance disabled via config');
         return;
     }
     // Croner uses the host system TZ when `timezone` option is omitted.
@@ -120,58 +116,34 @@ export function startHeartbeatLoop(processMessageFn) {
         ? { timezone: config.POLLER_TZ, protect: true }
         : { protect: true };
     const tzLabel = config.POLLER_TZ ?? `host (${Intl.DateTimeFormat().resolvedOptions().timeZone})`;
-    // Heartbeat cron — frequent, lightweight
-    logger.info(`[Heartbeat] Starting heartbeat cron: "${config.HEARTBEAT_CRON}" (tz: ${tzLabel})`);
-    heartbeatJob = new Cron(config.HEARTBEAT_CRON, cronOpts, async () => {
-        await runHeartbeatJob(processMessageFn);
-    });
-    // Maintenance cron — daily, heavy (consolidation, memory cleanup)
     logger.info(`[Maintenance] Starting maintenance cron: "${config.MAINTENANCE_CRON}" (tz: ${tzLabel})`);
     maintenanceJob = new Cron(config.MAINTENANCE_CRON, cronOpts, async () => {
         await runMaintenanceJob(processMessageFn);
     });
 }
 /**
- * Run the heartbeat cron handler with telemetry instrumentation (#119).
+ * Run the maintenance cron handler with telemetry instrumentation (#119).
  * Records last-fire timestamp on entry and last-success timestamp on completion.
  * Exported for use by the cron registration above and tests that fire it manually.
  */
-export async function runHeartbeatJob(processMessageFn) {
-    markHeartbeatJobFired();
-    try {
-        await triggerAllBrains('heartbeat', processMessageFn);
-        markHeartbeatJobSuccess();
-    }
-    catch (e) {
-        logger.error(`[Heartbeat] heartbeatJob handler threw: ${e instanceof Error ? e.message : e}`);
-        throw e; // preserve existing behavior; croner protect handles overlap
-    }
-}
-/**
- * Run the maintenance cron handler with telemetry instrumentation (#119).
- */
 export async function runMaintenanceJob(processMessageFn) {
     markMaintenanceJobFired();
     try {
-        await triggerAllBrains('maintenance', processMessageFn);
+        await triggerAllBrains(processMessageFn);
         markMaintenanceJobSuccess();
     }
     catch (e) {
         logger.error(`[Maintenance] maintenanceJob handler threw: ${e instanceof Error ? e.message : e}`);
-        throw e;
+        throw e; // preserve existing behavior; croner protect handles overlap
     }
 }
 /**
- * Stop the heartbeat and maintenance crons (for shutdown).
+ * Stop the maintenance cron (for shutdown).
  */
-export function stopHeartbeatLoop() {
-    if (heartbeatJob) {
-        heartbeatJob.stop();
-        heartbeatJob = null;
-    }
+export function stopMaintenanceLoop() {
     if (maintenanceJob) {
         maintenanceJob.stop();
         maintenanceJob = null;
     }
-    logger.info('[Heartbeat] Stopped heartbeat & maintenance crons');
+    logger.info('[Maintenance] Stopped maintenance cron');
 }

package/dist/metrics/collector.d.ts

@@ -11,8 +11,6 @@ export interface MetricsPayload {
     todayMdLines?: number;
     summaryMdBytes?: number;
     summaryMdLines?: number;
-    heartbeatMdBytes?: number;
-    heartbeatMdLines?: number;
     brainDirBytes?: number;
     vmDiskFreeBytes?: number;
     vmDiskUsedBytes?: number;
@@ -21,8 +19,6 @@ export interface MetricsPayload {
     oldestInboxMessageAgeSeconds?: number;
     uncommittedChangeCount?: number;
     daysSinceMaintenance?: number;
-    lastHeartbeatJobMs?: number;
-    lastHeartbeatJobSuccessMs?: number;
     lastMaintenanceJobMs?: number;
     lastMaintenanceJobSuccessMs?: number;
     lastAutoUpdateJobMs?: number;

package/dist/metrics/collector.js

@@ -7,6 +7,10 @@ import { getCronJobTimestamps } from '../cron-telemetry.js';
 const statfsAsync = promisify(statfs);
 const execFileAsync = promisify(execFile);
 const MS_PER_DAY = 86_400_000;
+// Directory names skipped at any depth during brainDirBytes walk.
+// Holds `du --exclude=.git --exclude=node_modules` parity for the brain dir signal.
+// See teamvibeai/teamvibe.ai#114.
+const EXCLUDED_DIR_NAMES = new Set(['.git', 'node_modules']);
 /**
  * Recursively sum file sizes under a directory.
  * Skips entries we cannot stat (permission errors, broken symlinks).
@@ -21,6 +25,8 @@ async function dirSizeBytes(path) {
         return 0;
     }
     for (const entry of entries) {
+        if (entry.isDirectory() && EXCLUDED_DIR_NAMES.has(entry.name))
+            continue;
         const full = join(path, entry.name);
         try {
             if (entry.isDirectory()) {
@@ -135,19 +141,6 @@ export async function collectMetrics(brainPath, brainId) {
     catch {
         // omit
     }
-    // HEARTBEAT.md size + line count — see poller-brain#101. The *number of
-    // items* in the file is what drives the Step 8b sweep crash risk, so we
-    // report size + line count rather than a binary presence flag. Both omitted
-    // on any error (file missing or unreadable).
-    try {
-        const heartbeatPath = join(brainPath, 'HEARTBEAT.md');
-        const s = await stat(heartbeatPath);
-        payload.heartbeatMdBytes = s.size;
-        payload.heartbeatMdLines = await countLines(heartbeatPath);
-    }
-    catch {
-        // omit
-    }
     // brain dir total size
     try {
         payload.brainDirBytes = await dirSizeBytes(brainPath);
@@ -224,17 +217,11 @@ export async function collectMetrics(brainPath, brainId) {
     catch {
         // Non-git brain, missing git binary, timeout — omit.
     }
-    // Poller-level cron-job telemetry (#119). Same six values for every brain on
+    // Poller-level cron-job telemetry (#119). Same four values for every brain on
     // the poller — see issue body for storage cost rationale. Each measure is
     // `now - storedTs`; if the cron has never fired (storedTs null), omit it.
     const now = Date.now();
     const cron = getCronJobTimestamps();
-    if (cron.lastHeartbeatJobFiredAt !== null) {
-        payload.lastHeartbeatJobMs = now - cron.lastHeartbeatJobFiredAt;
-    }
-    if (cron.lastHeartbeatJobSuccessAt !== null) {
-        payload.lastHeartbeatJobSuccessMs = now - cron.lastHeartbeatJobSuccessAt;
-    }
     if (cron.lastMaintenanceJobFiredAt !== null) {
         payload.lastMaintenanceJobMs = now - cron.lastMaintenanceJobFiredAt;
     }

package/dist/poller.d.ts

@@ -10,7 +10,7 @@ export declare function releaseAllActiveLocks(locks: Map<string, string>, releas
  * `checkForUpdateFn` is injected (default = real checkForUpdate) so tests
  * can lock in the "swallow but still mark fired" contract that
  * distinguishes scenario (A) cron-doesn't-fire from (B/C) cron-fires-but-fails
- * in morning-check telemetry. Same DI shape as runHeartbeatJob/runMaintenanceJob.
+ * in morning-check telemetry. Same DI shape as runMaintenanceJob.
  */
 export declare function runAutoUpdateJob(checkForUpdateFn?: () => Promise<boolean>): Promise<void>;
 export declare function startPoller(): Promise<void>;

package/dist/poller.js

@@ -2,13 +2,14 @@ import { config } from './config.js';
 import { logger } from './logger.js';
 import { pollMessages, deleteMessage, } from './sqs-poller.js';
 import { spawnClaudeCode, isAtCapacity, getActiveProcessCount, killAllActiveProcesses, killZombieForThread } from './claude-spawner.js';
-import { sendSlackError, addReaction, getUserInfo, startTypingIndicator } from './slack-client.js';
+import { sendSlackError, sendSlackMessage, addReaction, getUserInfo, startTypingIndicator } from './slack-client.js';
+import { classifyFailedIteration } from './classify-failed-iteration.js';
 import { acquireSessionLock, releaseSessionLock, updateSessionId } from './session-store.js';
 import { getBrainPath, ensureDirectories, ensureBaseBrain, pushBrainChanges } from './brain-manager.js';
 import { cleanupOrphanWorktreesForAllBrains, isWorktreeIsolationEnabled } from './worktree-manager.js';
 import { postMaintenanceReports } from './maintenance-reporter.js';
 import { initAuth, stopRefresh } from './auth-provider.js';
-import { registerBrain, startHeartbeatLoop, stopHeartbeatLoop } from './heartbeat-manager.js';
+import { registerBrain, startMaintenanceLoop, stopMaintenanceLoop } from './maintenance-cron.js';
 import { startEventQueue, stopEventQueue, flush as flushEventQueue, emitEvent } from './event-queue.js';
 import { startMetricsCron, stopMetricsCron } from './metrics/scheduler.js';
 import { writeMessage, pickNextMessage, markProcessed, markFailed, hasUnprocessed } from './inbox-manager.js';
@@ -39,7 +40,7 @@ export async function releaseAllActiveLocks(locks, release, log = logger) {
     })));
     locks.clear();
 }
-// Poller auto-update cron (separate from brain heartbeats)
+// Poller auto-update cron (separate from the maintenance cron)
 let autoUpdateJob = null;
 /**
  * Run the auto-update cron handler with telemetry instrumentation (#119).
@@ -48,7 +49,7 @@ let autoUpdateJob = null;
  * `checkForUpdateFn` is injected (default = real checkForUpdate) so tests
  * can lock in the "swallow but still mark fired" contract that
  * distinguishes scenario (A) cron-doesn't-fire from (B/C) cron-fires-but-fails
- * in morning-check telemetry. Same DI shape as runHeartbeatJob/runMaintenanceJob.
+ * in morning-check telemetry. Same DI shape as runMaintenanceJob.
  */
 export async function runAutoUpdateJob(checkForUpdateFn = checkForUpdate) {
     markAutoUpdateJobFired();
@@ -220,10 +221,14 @@ async function runInboxLoop(threadId, kbPath, queueMessage, sessionLog) {
                     lastExitCode = result.exitCode;
                     sessionLog.error(`[Loop] Claude failed iteration #${iteration}: ${result.error}`);
                     if (hasSlackContext) {
-                        const errorMessage = result.error || `Process exited with code ${result.exitCode}`;
-                        const isTimeout = errorMessage.includes('timed out');
-                        await sendSlackError(queueMessage, errorMessage);
-                        await addReaction(queueMessage, isTimeout ? 'hourglass' : 'x');
+                        const decision = classifyFailedIteration(result);
+                        if (decision.kind === 'neutral') {
+                            await sendSlackMessage(queueMessage, decision.text);
+                        }
+                        else {
+                            await sendSlackError(queueMessage, decision.text);
+                        }
+                        await addReaction(queueMessage, decision.reaction);
                     }
                 }
             }
@@ -275,7 +280,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' && queueMessage.source !== 'heartbeat' && queueMessage.source !== 'maintenance' &&
+    if (queueMessage.source !== 'cron' && queueMessage.source !== 'maintenance' &&
         queueMessage.sender.name === 'Unknown User' &&
         queueMessage.sender.id !== 'unknown') {
         const userInfo = await getUserInfo(queueMessage.teamvibe.botToken, queueMessage.sender.id);
@@ -311,7 +316,7 @@ async function processMessage(received) {
         }
         return;
     }
-    // Register brain for heartbeat tracking
+    // Register brain so the maintenance cron knows about it.
     registerBrain(queueMessage);
     // Write raw message to inbox (spawnClaudeCode handles prompt formatting)
     writeMessage(kbPath, threadId, JSON.stringify({
@@ -501,7 +506,7 @@ async function shutdown(signal, exitCode = 0) {
     shuttingDown = true;
     logger.info(`${signal} received, shutting down gracefully...`);
     stopRefresh();
-    stopHeartbeatLoop();
+    stopMaintenanceLoop();
     stopAutoUpdateCron();
     stopMetricsCron();
     stopEventQueue();
@@ -549,7 +554,7 @@ export async function startPoller() {
         const sweep = await cleanupOrphanWorktreesForAllBrains(config.BRAINS_PATH);
         logger.info(`   Orphan worktree sweep: scanned ${sweep.scanned} brains, removed ${sweep.removed} stale worktrees`);
     }
-    startHeartbeatLoop(processMessage);
+    startMaintenanceLoop(processMessage);
     startAutoUpdateCron();
     startMetricsCron();
     await pollLoop();

package/dist/secrets-client.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Poller-side secrets client — teamvibe.ai#105 (PR4).
+ *
+ * Fetches per-spawn secret envelopes from the Poller API
+ * (GET /secrets/spawn?pollerId=&workspaceId=&channelId=) and shapes the
+ * response into a child-process env map plus a metadata array for system
+ * reminder rendering.
+ *
+ * Defense-in-depth principles enforced here:
+ *
+ *   1. **Localized unwrap.** The decrypted env map is returned wrapped in
+ *      an opaque container with a single `unwrap()` method. The caller
+ *      (`claude-spawner.ts`) calls `unwrap()` exactly once at the child
+ *      process spawn site. No other call site touches the values.
+ *
+ *   2. **Reminder rendering never sees values.** `reminders[]` carries
+ *      only `{name, scope, expiresAt, overrodeScopes}`. A separate render
+ *      function `buildSecretsReminder` produces the system-prompt text
+ *      from this metadata; it has no access to the env map.
+ *
+ *   3. **Caller-side log redaction.** This module's logging functions
+ *      explicitly never log response bodies. Error paths log only the
+ *      HTTP status + a sanitised error message. We do NOT rely solely on
+ *      the API's `x-tv-no-log: response-body` header — the poller is its
+ *      own trust boundary.
+ *
+ * If the API call fails, `fetchSecretsForSpawn` returns an empty envelope
+ * + reminders so that spawn proceeds without secrets rather than failing
+ * the user's session. Errors are logged at warn level; production
+ * monitoring should alarm on `secrets-client.fetch_failed` metric counter.
+ */
+export type SecretScope = 'poller' | 'workspace' | 'channel';
+export interface SecretReminderEntry {
+    name: string;
+    scope: SecretScope;
+    expiresAt?: string;
+    overrodeScopes?: SecretScope[];
+}
+/**
+ * Opaque envelope around the decrypted env map. The values inside MUST NOT
+ * be read except via `unwrap()`, and `unwrap()` is intended to be called
+ * exactly once at the child-process spawn site.
+ *
+ * Default JSON / toString render `[REDACTED]`. If you ever find yourself
+ * adding a new caller of `unwrap()`, treat it as a security-relevant
+ * change and ping DevGuru.
+ */
+export declare class SpawnSecretsEnvelope {
+    #private;
+    constructor(env: Record<string, string>);
+    /** Sole legitimate value access. Single call site = `claude-spawner.ts`. */
+    unwrap(): Record<string, string>;
+    /** Number of secrets carried — safe for logging. */
+    size(): number;
+    toString(): string;
+    toJSON(): string;
+}
+export interface SpawnSecretsResult {
+    env: SpawnSecretsEnvelope;
+    reminders: SecretReminderEntry[];
+}
+export interface FetchSecretsInput {
+    pollerId: string;
+    workspaceId: string;
+    channelId: string;
+}
+/**
+ * Fetch secrets for a spawn. Returns an empty envelope (and empty
+ * reminders array) on any failure mode — spawn continues without
+ * secrets. The error is logged here so monitoring can alarm; do NOT
+ * pass error details into the spawn pipeline where they might surface
+ * to the user.
+ */
+export declare function fetchSecretsForSpawn(input: FetchSecretsInput): Promise<SpawnSecretsResult>;
+/**
+ * Render the system-reminder text from reminder metadata. This function
+ * intentionally has NO access to the env map — its inputs are name +
+ * scope + expiration only. A future code-reader who needs to add a value
+ * to the reminder body must change the function signature, which is a
+ * loud signal to think twice.
+ */
+export declare function buildSecretsReminder(reminders: SecretReminderEntry[]): string;

package/dist/secrets-client.js

@@ -0,0 +1,215 @@
+/**
+ * Poller-side secrets client — teamvibe.ai#105 (PR4).
+ *
+ * Fetches per-spawn secret envelopes from the Poller API
+ * (GET /secrets/spawn?pollerId=&workspaceId=&channelId=) and shapes the
+ * response into a child-process env map plus a metadata array for system
+ * reminder rendering.
+ *
+ * Defense-in-depth principles enforced here:
+ *
+ *   1. **Localized unwrap.** The decrypted env map is returned wrapped in
+ *      an opaque container with a single `unwrap()` method. The caller
+ *      (`claude-spawner.ts`) calls `unwrap()` exactly once at the child
+ *      process spawn site. No other call site touches the values.
+ *
+ *   2. **Reminder rendering never sees values.** `reminders[]` carries
+ *      only `{name, scope, expiresAt, overrodeScopes}`. A separate render
+ *      function `buildSecretsReminder` produces the system-prompt text
+ *      from this metadata; it has no access to the env map.
+ *
+ *   3. **Caller-side log redaction.** This module's logging functions
+ *      explicitly never log response bodies. Error paths log only the
+ *      HTTP status + a sanitised error message. We do NOT rely solely on
+ *      the API's `x-tv-no-log: response-body` header — the poller is its
+ *      own trust boundary.
+ *
+ * If the API call fails, `fetchSecretsForSpawn` returns an empty envelope
+ * + reminders so that spawn proceeds without secrets rather than failing
+ * the user's session. Errors are logged at warn level; production
+ * monitoring should alarm on `secrets-client.fetch_failed` metric counter.
+ */
+import { logger } from './logger.js';
+import { config } from './config.js';
+/**
+ * Opaque envelope around the decrypted env map. The values inside MUST NOT
+ * be read except via `unwrap()`, and `unwrap()` is intended to be called
+ * exactly once at the child-process spawn site.
+ *
+ * Default JSON / toString render `[REDACTED]`. If you ever find yourself
+ * adding a new caller of `unwrap()`, treat it as a security-relevant
+ * change and ping DevGuru.
+ */
+export class SpawnSecretsEnvelope {
+    #env;
+    constructor(env) {
+        this.#env = env;
+    }
+    /** Sole legitimate value access. Single call site = `claude-spawner.ts`. */
+    unwrap() {
+        return this.#env;
+    }
+    /** Number of secrets carried — safe for logging. */
+    size() {
+        return Object.keys(this.#env).length;
+    }
+    toString() {
+        return `[SpawnSecretsEnvelope size=${this.size()} REDACTED]`;
+    }
+    toJSON() {
+        return '[REDACTED]';
+    }
+    [Symbol.for('nodejs.util.inspect.custom')]() {
+        return this.toString();
+    }
+}
+/**
+ * Fetch secrets for a spawn. Returns an empty envelope (and empty
+ * reminders array) on any failure mode — spawn continues without
+ * secrets. The error is logged here so monitoring can alarm; do NOT
+ * pass error details into the spawn pipeline where they might surface
+ * to the user.
+ */
+export async function fetchSecretsForSpawn(input) {
+    if (!config.TEAMVIBE_API_URL || !config.TEAMVIBE_POLLER_TOKEN) {
+        logger.warn('secrets-client: TEAMVIBE_API_URL or TEAMVIBE_POLLER_TOKEN not set; skipping fetch');
+        return emptyResult();
+    }
+    // Upfront short-circuit: an empty pollerId would fail server-side
+    // validation and round-trip an HTTP error. Skip the call entirely so
+    // the warn log makes the cause obvious from poller stdout.
+    if (!input.pollerId) {
+        logger.warn('secrets-client: pollerId empty; skipping fetch (no secrets injected for spawn)');
+        return emptyResult();
+    }
+    // URL construction can throw on malformed TEAMVIBE_API_URL — must run
+    // inside the fail-soft envelope so a config typo doesn't crash the
+    // spawn pipeline. Wrapping here keeps the contract uniform with the
+    // fetch / parse error paths below.
+    let url;
+    try {
+        url = new URL('/secrets/spawn', config.TEAMVIBE_API_URL);
+        url.searchParams.set('pollerId', input.pollerId);
+        url.searchParams.set('workspaceId', input.workspaceId);
+        url.searchParams.set('channelId', input.channelId);
+    }
+    catch (err) {
+        logger.warn(`secrets-client.config_error: invalid TEAMVIBE_API_URL=${String(config.TEAMVIBE_API_URL)} ` +
+            `error=${err?.message ?? String(err)}`);
+        return emptyResult();
+    }
+    let response;
+    try {
+        response = await fetch(url.toString(), {
+            method: 'GET',
+            headers: {
+                Authorization: `Bearer ${config.TEAMVIBE_POLLER_TOKEN}`,
+                // Hint to any intermediary that this request returns sensitive
+                // data; the API itself sets `x-tv-no-log` on the response.
+                'Cache-Control': 'no-store',
+            },
+        });
+    }
+    catch (err) {
+        logger.warn(`secrets-client.fetch_failed: network error pollerId=${input.pollerId} ` +
+            `workspaceId=${input.workspaceId} channelId=${input.channelId} ` +
+            `error=${err?.message ?? String(err)}`);
+        return emptyResult();
+    }
+    if (!response.ok) {
+        // Read body to surface a useful error log, but cap the size so a
+        // misconfigured API can't dump arbitrary content into our logs.
+        // Status + a small slice is sufficient diagnostics — no body
+        // pass-through.
+        let snippet = '';
+        try {
+            snippet = (await response.text()).slice(0, 200);
+        }
+        catch {
+            snippet = '<failed-to-read-body>';
+        }
+        logger.warn(`secrets-client.fetch_failed: status=${response.status} ` +
+            `pollerId=${input.pollerId} workspaceId=${input.workspaceId} ` +
+            `channelId=${input.channelId} bodySnippet=${snippet}`);
+        return emptyResult();
+    }
+    // The response is sensitive — parse it and immediately wrap. From this
+    // point on, the env map is only accessible via `.unwrap()`.
+    let parsed;
+    try {
+        parsed = (await response.json());
+    }
+    catch (err) {
+        logger.warn(`secrets-client.parse_failed: pollerId=${input.pollerId} ` +
+            `error=${err?.message ?? String(err)}`);
+        return emptyResult();
+    }
+    const env = {};
+    if (parsed.env && typeof parsed.env === 'object') {
+        for (const [k, v] of Object.entries(parsed.env)) {
+            if (typeof v === 'string')
+                env[k] = v;
+        }
+    }
+    const reminders = [];
+    if (Array.isArray(parsed.reminders)) {
+        for (const item of parsed.reminders) {
+            if (typeof item['name'] !== 'string' || typeof item['scope'] !== 'string')
+                continue;
+            reminders.push({
+                name: item['name'],
+                scope: item['scope'],
+                expiresAt: typeof item['expiresAt'] === 'string' ? item['expiresAt'] : undefined,
+                overrodeScopes: Array.isArray(item['overrodeScopes'])
+                    ? item['overrodeScopes'].filter(s => typeof s === 'string')
+                    : undefined,
+            });
+        }
+    }
+    // Log only the size — never names or values.
+    logger.info(`secrets-client: fetched ${Object.keys(env).length} secret(s) for spawn`);
+    return {
+        env: new SpawnSecretsEnvelope(env),
+        reminders,
+    };
+}
+function emptyResult() {
+    return { env: new SpawnSecretsEnvelope({}), reminders: [] };
+}
+/**
+ * Render the system-reminder text from reminder metadata. This function
+ * intentionally has NO access to the env map — its inputs are name +
+ * scope + expiration only. A future code-reader who needs to add a value
+ * to the reminder body must change the function signature, which is a
+ * loud signal to think twice.
+ */
+export function buildSecretsReminder(reminders) {
+    if (reminders.length === 0)
+        return '';
+    const now = Date.now();
+    const lines = ['## Available Secrets'];
+    lines.push('The following ENV variables are loaded into this session:');
+    for (const r of reminders) {
+        let suffix = '';
+        if (r.expiresAt) {
+            const expMs = Date.parse(r.expiresAt);
+            if (Number.isFinite(expMs)) {
+                const daysLeft = Math.floor((expMs - now) / (24 * 60 * 60 * 1000));
+                if (daysLeft < 1) {
+                    suffix = ` — **EXPIRES IN <1d** :warning: please rotate via \`set_secret\``;
+                }
+                else if (daysLeft < 7) {
+                    suffix = ` (expires in ${daysLeft}d — please rotate via \`set_secret\`)`;
+                }
+            }
+        }
+        const overrideNote = r.overrodeScopes && r.overrodeScopes.length > 0
+            ? `, overrides ${r.overrodeScopes.join('+')}`
+            : '';
+        lines.push(`- \`${r.name}\` (${r.scope} scope${overrideNote})${suffix}`);
+    }
+    lines.push('');
+    lines.push('Access via `process.env.{NAME}` or shell `$NAME`.');
+    lines.push('Values are a snapshot taken at spawn time; long sessions may see stale values until the next spawn.');
+    return lines.join('\n');
+}

package/dist/types.d.ts

@@ -7,7 +7,7 @@ export interface ControlMessage {
 export type QueueMessage = TeamVibeQueueMessage | ControlMessage;
 export interface TeamVibeQueueMessage {
     id: string;
-    source: 'slack' | 'email' | 'cron' | 'heartbeat' | 'maintenance' | 'webhook';
+    source: 'slack' | 'email' | 'cron' | 'maintenance' | 'webhook';
     thread_id: string;
     sender: {
         id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teamvibe/poller",
-  "version": "0.4.4",
+  "version": "0.5.1",
   "type": "module",
   "main": "./dist/index.js",
   "bin": {
@@ -29,6 +29,7 @@
     "zod": "^3.22.0"
   },
   "devDependencies": {
+    "@types/bun": "^1.3.14",
     "@types/node": "^20.10.5",
     "tsx": "^4.7.0",
     "typescript": "^5.3.3"