@teamvibe/poller 0.6.2 → 0.7.1

package/dist/poller.js

@@ -10,13 +10,15 @@ import { cleanupOrphanWorktreesForAllBrains, isWorktreeIsolationEnabled } from '
 import { postMaintenanceReports } from './maintenance-reporter.js';
 import { initAuth, stopRefresh, getPollerId } from './auth-provider.js';
 import { registerBrain, startMaintenanceLoop, stopMaintenanceLoop } from './maintenance-cron.js';
+import { bootstrapTrackedBrains } from './brains-bootstrap.js';
 import { startEventQueue, stopEventQueue, flush as flushEventQueue, emitEvent, emitError } from './event-queue.js';
 import { startMetricsCron, stopMetricsCron } from './metrics/scheduler.js';
-import { writeMessage, pickNextMessage, markProcessed, markFailed, hasUnprocessed } from './inbox-manager.js';
+import { writeMessage, pickNextMessage, markProcessed, markFailed, hasUnprocessed, requeueMessage } from './inbox-manager.js';
 import { startInboxWatcher, stopInboxWatcher } from './inbox-watcher.js';
 import { Cron } from 'croner';
 import { isControlMessage, handleControlMessage } from './control-handler.js';
 import { checkForUpdate } from './auto-update.js';
+import { checkIdleRestart, reconcileBgTasksOnBoot } from './idle-restart.js';
 import { markAutoUpdateJobFired, markAutoUpdateJobSuccess } from './cron-telemetry.js';
 import { exec } from 'child_process';
 import { promisify } from 'util';
@@ -132,6 +134,101 @@ const activeLoops = new Set();
 export function isInboxLoopActive(threadId) {
     return activeLoops.has(threadId);
 }
+// Exported for testing (teamvibe.ai#32). SIGTERM (143) / SIGKILL (137) exit
+// codes are the classic 128+signal convention for "the poller itself killed
+// this process on purpose" (timeout, idle, network, zombie, or — as of #32 —
+// a compaction-ceiling watchdog kill). Historically all of these set
+// `killedByPoller` via the same `proc.kill('SIGTERM')` path in
+// claude-spawner.ts and were observed to surface as 143/137 here.
+//
+// PR#308 round-2 review (teamvibe.ai#73): this exit-code convention is
+// fragile on its own — the Claude CLI can legitimately exit 143 for
+// unrelated reasons, and #73's move to group-kill (`process.kill(-pid, ...)`
+// instead of a direct `proc.kill()`) means a signal-terminated close now
+// reports `code: null` with a separate `signal` field (verified empirically
+// against a synthetic detached child in this repo's environment — Node's
+// `close` event reports `code: null` for any signal-terminated process,
+// group-killed or not). Kept as a defensive fallback only — see
+// isPollerInitiatedFailure() below, which is what callers should actually use.
+export function isIntentionalKillExitCode(exitCode) {
+    return exitCode === 143 || exitCode === 137;
+}
+// The actual retry-classification signal (PR#308 round-2 review item 1):
+// `killedByPoller` is the purpose-built marker for "the poller killed this
+// process on purpose, not an application failure" (see SpawnResult /
+// classify-failed-iteration.ts) and is set on every poller-initiated kill
+// path this branch touches — timeout, idle watchdog, network watchdog,
+// zombie-kill, and (added by this fix) poller shutdown. Prefer it, and fall
+// back to the exit-code heuristic only when it's absent (e.g. hand-built
+// SpawnResult literals in older/unrelated call sites) so behavior doesn't
+// regress for anything not yet covered by the marker.
+export function isPollerInitiatedFailure(result) {
+    return Boolean(result.killedByPoller) || isIntentionalKillExitCode(result.exitCode);
+}
+// tv#320 DevGuru round-1 review: runInboxLoop's retry-cap decision (below)
+// no longer calls isPollerInitiatedFailure() directly — since that cap now
+// applies to everything except 'shutdown', the only distinction it needs is
+// `lastKilledByPoller === 'shutdown'`, and `killedByPoller === 'shutdown'`
+// already implies isPollerInitiatedFailure() === true, making a combined
+// check redundant there.
+//
+// tv#320 DevGuru round-2 review: isIntentionalKillExitCode() still has a real
+// caller below (describeFailureReason()) — a kill with NO `killedByPoller`
+// marker that DOES still report the legacy 143/137 exit code is an
+// intentional kill, not an unclassified application failure, and needs to be
+// labeled as such in give-up notices/logs/events (`lastKilledByPoller ??
+// 'application failure'` used to conflate the two).
+//
+// tv#320 DevGuru round-3 review: this only covers the literal 143/137 case.
+// Per the comment above (line ~185), a group-killed process's `close` event
+// reports `code: null`, NOT 143/137 — so a marker-less OOM/external-SIGTERM/
+// group-kill still falls through to "application failure" here, same as
+// before this fix. Closing that gap for real needs claude-spawner.ts's
+// `close` handler to stop discarding its `signal` argument and SpawnResult
+// to carry it (neither does today) — tracked as a follow-up, not attempted
+// here.
+export function describeFailureReason(killedByPoller, exitCode) {
+    if (killedByPoller)
+        return killedByPoller;
+    if (isIntentionalKillExitCode(exitCode))
+        return `killed (exit ${exitCode})`;
+    return 'application failure';
+}
+// teamvibe.ai#284 (poller-brain#235): end-of-turn guard. A successful Claude
+// run can end its turn having only written plain assistant text — no
+// `mcp__slack__send_message` tool call — which the platform otherwise drops
+// silently (no error, no signal; see poller-brain#235's 4x-in-one-session
+// recurrence). Decides whether this run needs the deterministic fallback
+// delivery, and if so, what text to send.
+//
+// Pure/exported (mirrors classifyFailedIteration's pattern) so the gating
+// logic — "Slack context AND no send_message call AND non-empty trailing
+// text" — is unit-testable without mocking spawnClaudeCode or sendSlackMessage.
+// Deliberately does NOT fire on a failed run (result.success === false):
+// that path already has its own delivery via classifyFailedIteration +
+// sendSlackMessage/sendSlackError, and firing here too would double-deliver.
+//
+// poller-brain#380: a turn whose only tool call is a reaction (or similar)
+// can trigger Claude Code's own forced-continuation nudge ("no visible
+// output, produce a user-visible response"), which previously always fired
+// this same fallback — double-posting even when the reaction was the
+// intended, complete reply. Base-brain CLAUDE.md instructs agents to answer
+// that nudge with this exact sentinel when nothing further is needed; an
+// exact match is treated as "nothing to deliver". Deliberately an exact
+// string match, not a content heuristic — anything else (including real
+// content an agent forgot to send via send_message) still delivers as
+// before, so this can't silently drop a forgotten reply.
+export const END_OF_TURN_NO_FURTHER_RESPONSE_SENTINEL = 'NO_FURTHER_RESPONSE_NEEDED';
+export function endOfTurnFallbackText(hasSlackContext, result) {
+    if (!hasSlackContext || !result.success || result.sawSendMessageCall) {
+        return undefined;
+    }
+    const text = result.lastPlainTextContent?.trim();
+    if (!text || text === END_OF_TURN_NO_FURTHER_RESPONSE_SENTINEL) {
+        return undefined;
+    }
+    return text;
+}
 export async function runInboxLoop(threadId, kbPath, queueMessage, sessionLog) {
     if (activeLoops.has(threadId)) {
         sessionLog.info(`Loop already running for thread ${threadId}, skipping`);
@@ -160,7 +257,25 @@ export async function runInboxLoop(threadId, kbPath, queueMessage, sessionLog) {
             activeLocks.set(threadId, lockToken);
         }
         let currentSessionId = session.session_id || undefined;
-        while (true) {
+        // PR#308 round-3 review (teamvibe.ai#73): `shuttingDown` (declared below,
+        // referenced here via the same forward-reference pattern already used by
+        // pollLoop()'s `while (!shuttingDown)`) gates every new iteration of this
+        // loop, not just the retry-classification decision inside it. Without
+        // this, a message killed with `killedByPoller: 'shutdown'` (added by this
+        // branch) falls into the same "poller-initiated, retry immediately, no
+        // backoff" bucket as timeout/idle/network/zombie (see
+        // isPollerInitiatedFailure() below) — correctly skipping markProcessed/
+        // markFailed so the message stays unprocessed for a future boot, but with
+        // nothing to stop the loop from immediately calling pickNextMessage()
+        // again and spawning a NEW `claude` process for that same message, even
+        // though killAllActiveProcesses() (shutdown()'s first step) already ran.
+        // Gating the loop *condition* itself (rather than special-casing
+        // 'shutdown' inside the retry decision) closes this for every
+        // killedByPoller reason uniformly, and — unlike a `break` — falls through
+        // to the exact same post-loop cleanup (releaseSessionLock etc., below)
+        // that the existing `if (!message) break` / `if (!hasUnprocessed(...))
+        // break` exits already use, so lock release is unaffected.
+        while (!shuttingDown) {
             const message = pickNextMessage(kbPath, threadId);
             if (!message) {
                 sessionLog.info(`[Loop] No more messages for thread ${threadId}`);
@@ -177,6 +292,7 @@ export async function runInboxLoop(threadId, kbPath, queueMessage, sessionLog) {
                 : undefined;
             let succeeded = false;
             let lastExitCode = null;
+            let lastKilledByPoller;
             try {
                 // Reconstruct queue message from stored inbox data
                 const storedData = JSON.parse(message.content);
@@ -227,6 +343,28 @@ export async function runInboxLoop(threadId, kbPath, queueMessage, sessionLog) {
                             modelSource: result.modelSource,
                         });
                     }
+                    // teamvibe.ai#284 (poller-brain#235): end-of-turn guard. A
+                    // successful run that never called send_message but left trailing
+                    // plain text would otherwise vanish silently — deliver it via the
+                    // same sendSlackMessage() helper used for the failure-path neutral
+                    // notices, and emit a warning-level event so the near-miss is
+                    // visible (today session.completed looks identical whether or not
+                    // this fired).
+                    const fallbackText = endOfTurnFallbackText(hasSlackContext, result);
+                    if (fallbackText) {
+                        sessionLog.warn(`[Loop] Iteration #${iteration}: no send_message call detected, delivering trailing assistant text via fallback`);
+                        try {
+                            await sendSlackMessage(queueMessage, fallbackText);
+                        }
+                        catch (err) {
+                            sessionLog.error(`[Loop] End-of-turn fallback delivery failed: ${err instanceof Error ? err.message : err}`);
+                        }
+                        emitError('session', 'End-of-turn guard: delivered assistant text via fallback (no send_message tool call detected)', {
+                            severity: 'warn',
+                            channelId: queueMessage.teamvibe.channelId,
+                            context: { threadId: queueMessage.thread_id },
+                        });
+                    }
                     if (queueMessage.teamvibe.brain?.brainId) {
                         await pushBrainChanges(kbPath, queueMessage.teamvibe.brain.brainId, queueMessage.teamvibe.workspaceId);
                     }
@@ -234,7 +372,28 @@ export async function runInboxLoop(threadId, kbPath, queueMessage, sessionLog) {
                 }
                 else {
                     lastExitCode = result.exitCode;
+                    lastKilledByPoller = result.killedByPoller;
                     sessionLog.error(`[Loop] Claude failed iteration #${iteration}: ${result.error}`);
+                    // tv#320 DevGuru round-2 review: a fleet-visible record of EVERY
+                    // failed iteration (not just the eventual give-up) means a future
+                    // "was this in one loop or across restarts" question is a DDB query
+                    // (this event, by thread/filename/timestamp) instead of a CloudWatch
+                    // log dig + SSO admin escalation — which is exactly what round-2's
+                    // point 3b hit a dead end on for pb#337.
+                    //
+                    // tv#320 DevGuru round-3 review: excludes 'shutdown' — that fires on
+                    // every poller restart/deploy for every in-flight message fleet-wide
+                    // and isn't a retry-cap-relevant failure (it's not counted toward
+                    // failureCounts either), so it would just be alerting noise for an
+                    // expected event with no new information (the requeue below already
+                    // covers it).
+                    if (lastKilledByPoller !== 'shutdown') {
+                        emitError('session', `Iteration #${iteration} failed for ${message.filename}`, {
+                            severity: 'warn',
+                            channelId: queueMessage.teamvibe.channelId,
+                            context: { threadId, filename: message.filename, iteration, reason: describeFailureReason(lastKilledByPoller, lastExitCode) },
+                        });
+                    }
                     if (hasSlackContext) {
                         const decision = classifyFailedIteration(result);
                         if (decision.kind === 'neutral') {
@@ -255,22 +414,139 @@ export async function runInboxLoop(threadId, kbPath, queueMessage, sessionLog) {
                 markProcessed(kbPath, threadId, message.filename);
             }
             else {
-                // SIGTERM (143) or SIGKILL (137) = intentional kill → retry immediately, no backoff
-                const isKilledSignal = lastExitCode === 143 || lastExitCode === 137;
-                if (!isKilledSignal) {
+                // Poller-initiated kill (timeout/idle/network/zombie/shutdown, via
+                // `killedByPoller`, or the legacy 143/137 exit-code fallback) never
+                // counts as an *application* failure — but tv#320 (poller-brain#337:
+                // one checkpoint file redelivered 18x/~10min, stopped only by a
+                // manual `rm`) showed that timeout/idle/network/zombie kills can be
+                // just as deterministically tied to this one message's content as a
+                // genuine app failure (e.g. an oversized file that reliably
+                // re-triggers the same idle/timeout watchdog on every immediate
+                // retry). So the same failureCounts/MAX_RETRIES/backoff cap as the
+                // application-failure path now applies to everything except
+                // 'shutdown' — not just those four named reasons: a legacy 143/137
+                // exit with no `killedByPoller` marker at all is just as capable of
+                // repeating forever and there's no reason to treat it differently.
+                // 'shutdown' alone stays excluded: `shuttingDown` is already true by
+                // the time this reads, so the loop condition above stops it from
+                // actually retrying inline — instead the branch below requeues the
+                // message from processing/ back to new/ (PR#308 round-5) so a future
+                // boot's inbox watcher finds it.
+                //
+                // tv#320 DevGuru round-1 review: this branches on `lastKilledByPoller
+                // !== 'shutdown'` directly rather than `isPollerInitiatedFailure(...)`
+                // — `killedByPoller === 'shutdown'` already implies
+                // isPollerInitiatedFailure() === true, so combining the two was a
+                // dead term. isPollerInitiatedFailure() itself is unchanged and still
+                // meaningful (exported, unit-tested in
+                // poller-retry-classification.test.ts) for any caller that needs the
+                // poller-vs-app distinction — this loop just no longer needs it,
+                // since the only distinction that changes behavior here is
+                // shutdown-vs-not.
+                if (lastKilledByPoller !== 'shutdown') {
                     const failures = (failureCounts.get(message.filename) || 0) + 1;
                     failureCounts.set(message.filename, failures);
                     const MAX_RETRIES = 3;
                     if (failures >= MAX_RETRIES) {
-                        sessionLog.error(`[Loop] Message ${message.filename} failed ${failures} times, giving up`);
+                        // tv#320 DevGuru round-1 review: the per-iteration notice sent
+                        // above (classifyFailedIteration) for idle/zombie/network reads
+                        // "send another message to resume/restart/retry" — true before
+                        // this cap existed (retry was unconditional), false now that this
+                        // is the last attempt and the message is about to be dropped.
+                        // Give the user an explicit, accurate final word instead of
+                        // leaving classifyFailedIteration's now-stale promise as the only
+                        // thing they saw, and surface it as a real error event (not just
+                        // a session-log line) so give-up isn't invisible to fleet
+                        // monitoring either.
+                        const reasonLabel = describeFailureReason(lastKilledByPoller, lastExitCode);
+                        sessionLog.error(`[Loop] Message ${message.filename} failed ${failures} times (last reason: ${reasonLabel}), giving up`);
                         markFailed(kbPath, threadId, message.filename);
+                        if (hasSlackContext) {
+                            // tv#320 DevGuru round-2 review (BLOCKING): this whole else-if
+                            // chain sits structurally after the per-iteration try/catch
+                            // above (which closes at the `catch (error)` a few lines up),
+                            // so an unhandled exception here — unlike the per-iteration
+                            // classifyFailedIteration notices, which ARE inside that
+                            // try/catch — would propagate straight out of the `while`
+                            // loop, skip releaseSessionLock() below (it's in the try body,
+                            // not a `finally`), and leave the DDB session lock held until
+                            // TTL. sendSlackError() (slack-client.ts) has no internal catch
+                            // of its own (unlike addReaction(), which does), so a Slack
+                            // rate-limit/auth/network error here needs the same explicit
+                            // try/catch the end-of-turn-guard fallback above already uses.
+                            try {
+                                await sendSlackError(queueMessage, `Giving up after ${failures} attempts (last reason: ${reasonLabel}) — this message was not processed. Please send it again.`);
+                            }
+                            catch (err) {
+                                sessionLog.error(`[Loop] Give-up notice delivery failed: ${err instanceof Error ? err.message : err}`);
+                            }
+                            await addReaction(queueMessage, 'x');
+                        }
+                        emitError('session', `Message ${message.filename} failed ${failures} times, giving up`, {
+                            severity: 'error',
+                            channelId: queueMessage.teamvibe.channelId,
+                            context: { threadId, filename: message.filename, reason: reasonLabel },
+                        });
                     }
                     else {
                         const backoffMs = Math.min(10_000 * Math.pow(2, failures - 1), 60_000);
                         sessionLog.info(`[Loop] Retry ${failures}/${MAX_RETRIES - 1} for ${message.filename}, backing off ${backoffMs}ms`);
-                        await sleep(backoffMs);
+                        // tv#320 DevGuru round-2 nit: this backoff was previously only
+                        // reachable for genuine app failures; the broadened cap above
+                        // means a timeout/idle/network/zombie kill can now land here too,
+                        // including one racing an in-progress shutdown() (e.g. the idle
+                        // watchdog and a shutdown SIGTERM firing close together). Skip
+                        // the up-to-60s wait when already shutting down so the `while
+                        // (!shuttingDown)` condition above can exit on the very next
+                        // check instead of stalling runInboxLoop's return.
+                        if (!shuttingDown) {
+                            await sleep(backoffMs);
+                        }
                     }
                 }
+                else {
+                    // PR#308 round-5 review (teamvibe.ai#73): pickNextMessage() moves a
+                    // message's file to processing/ as soon as it's picked up, not once
+                    // it completes — so a message killed here by shutdown is left
+                    // sitting in processing/, not new/. The watcher's wake condition
+                    // (hasNewMessage(), inbox-watcher.ts) only scans new/, so nothing
+                    // would start a fresh runInboxLoop() for this thread on next boot.
+                    // Requeue it back to new/ so a future boot's watcher scan actually
+                    // finds it — this is what makes "your message is saved" (the
+                    // shutdown notice text below, classify-failed-iteration.ts)
+                    // literally true. It does NOT make resumption automatic: the
+                    // watcher's checkInboxForNewSessions() (inbox-watcher.ts) only
+                    // scans brains already in the in-memory trackedBrains map. Since
+                    // teamvibe.ai#127, that map is best-effort seeded from the
+                    // backend at startup (bootstrapTrackedBrains(), before
+                    // startInboxWatcher() is called) — but it's still not a
+                    // guarantee (network failure, backend outage, brain missing a
+                    // Slack bot/token to resolve) and a brand-new brain from a real
+                    // message that arrives after bootstrap but before its own first
+                    // registerBrain() call is still momentarily untracked. See
+                    // teamvibe.ai#310 for the still-open general case. Hence the
+                    // notice text also naming "next message or scheduled run" rather
+                    // than claiming automatic resumption.
+                    //
+                    // Scoped to 'shutdown' only, deliberately not the other four
+                    // poller-initiated reasons (timeout/idle/network/zombie) — those
+                    // retry immediately within this same still-running loop iteration
+                    // (the `while (!shuttingDown)` condition above lets it come
+                    // straight back around), so the existing processing/
+                    // crash-recovery branch inside pickNextMessage() already covers
+                    // them; requeueing those too would be redundant and could
+                    // double-process.
+                    //
+                    // Safe against waking a brand-new loop for this thread before this
+                    // poller process actually exits: stopInboxWatcher() runs earlier in
+                    // shutdown() (poller.ts), BEFORE killAllActiveProcesses() (whose
+                    // completion is what unblocks this iteration and reaches this
+                    // branch) — and stopInboxWatcher() closes the real fs.watch
+                    // handlers themselves (inbox-watcher.ts stopInboxWatcher(), not
+                    // just an interval/poll timer), so by the time this requeue runs,
+                    // nothing is watching new/ to react to the file reappearing there.
+                    requeueMessage(kbPath, threadId, message.filename);
+                }
             }
             if (!hasUnprocessed(kbPath, threadId)) {
                 break;
@@ -440,6 +716,18 @@ async function pollLoop() {
                 consecutiveAuthFailures = 0;
             }
             if (messages.length === 0) {
+                // tv#317: only worth checking on an otherwise-empty poll — a poll that
+                // returned messages means activeSessions is about to go above 0 anyway.
+                // Routed through the real shutdown() (not a standalone flush+exit) so this
+                // sets shuttingDown, stops the inbox watcher, and releases locks — the same
+                // gate every other exit path goes through. DevGuru review, tv#317: a bare
+                // flushEventQueue()+process.exit(0) here let the inbox watcher spawn a new
+                // session in the window before exit, then kill it mid-work (#308's shape),
+                // and skipped releaseAllActiveLocks(), stranding locks for STALE_LOCK_TIMEOUT_MS.
+                if (checkIdleRestart()) {
+                    logger.info('[IdleRestart] Restarting to let Railway reclaim page-cache memory...');
+                    await shutdown('idle-restart', 0);
+                }
                 continue;
             }
             logger.info(`Received ${messages.length} message(s) from SQS`);
@@ -510,11 +798,33 @@ async function pollLoop() {
         }
     }
 }
+let sleepImpl = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+    return sleepImpl(ms);
+}
+// Exported for testing only (tv#320 DevGuru round-1 nit): lets a test replace
+// the real backoff delay (runInboxLoop's retry-cap path) with an immediate
+// resolve, without a `globalThis.setTimeout` override that would also swallow
+// any other real timer in the same code path. Same pattern as
+// __setShuttingDownForTest above.
+export function __setSleepForTest(impl) {
+    sleepImpl = impl;
 }
 // Graceful shutdown
 let shuttingDown = false;
+// Exported for testing only (PR#308 round-3 review item 1). `shuttingDown`
+// has no other external mutator — production code only ever flips it via
+// the real shutdown() below, which also runs killAllActiveProcesses(),
+// releaseAllActiveLocks(), the drain loop, and process.exit(). This setter
+// lets a test put runInboxLoop's `while (!shuttingDown)` gate into the
+// "shutdown in progress" state directly (mirroring the exact race
+// shutdown() itself creates — killAllActiveProcesses() kills the in-flight
+// spawn while its promise is still pending) without invoking any of those
+// real side effects. Same pattern as __resetCronTelemetryForTest /
+// __resetTrackedBrainsForTest elsewhere in this package.
+export function __setShuttingDownForTest(value) {
+    shuttingDown = value;
+}
 async function shutdown(signal, exitCode = 0) {
     if (shuttingDown)
         return;
@@ -595,11 +905,38 @@ export async function startPoller() {
     startEventQueue();
     await ensureDirectories();
     await ensureBaseBrain();
+    reconcileBgTasksOnBoot();
+    if (config.IDLE_RESTART_ENABLED) {
+        // Defaults off (tv#317 follow-up, DevGuru review): a silent disabled gate and an
+        // enabled gate that just hasn't hit its threshold yet look identical in production
+        // (same flat/growing memory graph) — logging only on enabled, matching the
+        // Worktree isolation line below, makes opt-in verifiable from boot logs instead.
+        logger.info('   Idle restart: ENABLED (IDLE_RESTART_ENABLED=true)');
+    }
     if (isWorktreeIsolationEnabled()) {
         logger.info('   Worktree isolation: ENABLED (POLLER_USE_WORKTREES=true)');
         const sweep = await cleanupOrphanWorktreesForAllBrains(config.BRAINS_PATH);
         logger.info(`   Orphan worktree sweep: scanned ${sweep.scanned} brains, removed ${sweep.removed} stale worktrees`);
     }
+    // Seed trackedBrains from the backend's authoritative brain list
+    // (teamvibe.ai#127 Option B) BEFORE the maintenance cron and the inbox
+    // watcher start — both iterate the in-memory trackedBrains map
+    // (maintenance-cron.ts's triggerAllBrains, inbox-watcher.ts's
+    // checkInboxForNewSessions), which is otherwise empty after every
+    // restart until a real message re-registers each brain one at a time.
+    // Best-effort: never throws, so a bootstrap failure here falls back to
+    // the pre-#127 behavior rather than blocking startup.
+    //
+    // This await only covers ONE short (~10s) fetch attempt (DevGuru round-3
+    // review item 2) — real message processing (pollLoop(), below) must not
+    // be blocked for up to ~62s by a backend outage, which is exactly the
+    // condition most likely to coincide with a poller restart (backend
+    // deploys). If that one attempt fails and is retryable, the retry runs
+    // detached in the background and finishes after startPoller() has
+    // already returned — see brains-bootstrap.ts's bootstrapTrackedBrains()
+    // doc comment for why that's safe (neither the maintenance cron nor the
+    // inbox watcher need trackedBrains populated synchronously here).
+    await bootstrapTrackedBrains();
     startMaintenanceLoop(processMessage);
     startAutoUpdateCron();
     startMetricsCron();

package/dist/types.d.ts

@@ -19,6 +19,12 @@ export interface TeamVibeQueueMessage {
         filename: string;
         mimetype: string;
     }>;
+    inlineImages?: Array<{
+        mediaType: string;
+        data?: string;
+        url?: string;
+        expiresAt?: string;
+    }>;
     response_context: {
         slack?: {
             channel: string;

package/package.json

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