@teamvibe/poller 0.4.3 → 0.5.0

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,68 +102,48 @@ 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;
     }
-    // Heartbeat cron — frequent, lightweight
-    logger.info(`[Heartbeat] Starting heartbeat cron: "${config.HEARTBEAT_CRON}" (tz: ${config.POLLER_TZ})`);
-    heartbeatJob = new Cron(config.HEARTBEAT_CRON, { timezone: config.POLLER_TZ, protect: true }, async () => {
-        await runHeartbeatJob(processMessageFn);
-    });
-    // Maintenance cron — daily, heavy (consolidation, memory cleanup)
-    logger.info(`[Maintenance] Starting maintenance cron: "${config.MAINTENANCE_CRON}" (tz: ${config.POLLER_TZ})`);
-    maintenanceJob = new Cron(config.MAINTENANCE_CRON, { timezone: config.POLLER_TZ, protect: true }, async () => {
+    // Croner uses the host system TZ when `timezone` option is omitted.
+    // Build options conditionally so undefined POLLER_TZ becomes "host TZ"
+    // rather than overriding it with `timezone: undefined`.
+    const cronOpts = config.POLLER_TZ
+        ? { timezone: config.POLLER_TZ, protect: true }
+        : { protect: true };
+    const tzLabel = config.POLLER_TZ ?? `host (${Intl.DateTimeFormat().resolvedOptions().timeZone})`;
+    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.3",
+  "version": "0.5.0",
   "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"