@teamvibe/poller 0.6.2 → 0.7.1

package/dist/brain-manager.d.ts

@@ -1,8 +1,23 @@
+export declare function withBrainLock<T>(brainId: string, fn: () => Promise<T>): Promise<T>;
 interface BrainConfig {
     brainId: string;
     gitRepoUrl: string;
     branch: string;
 }
+/**
+ * Remove stale git lock files (tv#76) so an orphaned lock from a killed
+ * process (e.g. the 2026-05-01 outage) doesn't block brain updates/pushes
+ * indefinitely. Fresh locks (younger than the threshold) are left alone —
+ * they may belong to a git operation that's genuinely still running.
+ * A missing lock (stat fails) is a silent no-op. A genuine removal failure
+ * (unlink fails, e.g. permission denied) is logged via logger.warn with the
+ * path and error — that's the exact "lock exists but can't be cleared"
+ * scenario this fix exists to make visible.
+ *
+ * Exported for testing — production call sites go through updateBrain /
+ * pushBrainChanges below.
+ */
+export declare function cleanupStaleLocks(brainDir: string): Promise<void>;
 export declare function getBrainPath(brain?: BrainConfig, channelId?: string, workspaceId?: string): Promise<string>;
 /**
  * Update a brain repo (respects cooldown). Exported for testing — production
@@ -18,11 +33,38 @@ export declare function ensureBaseBrain(): Promise<void>;
  * Get the path to the base brain directory.
  */
 export declare function getBaseBrainPath(): string;
+/**
+ * Scan the commits about to be pushed for blobs over `maxBytes`. Returns the
+ * offending paths/sizes, or an empty array if everything is under the limit.
+ *
+ * Scans `@{u}..HEAD` when an upstream exists (the actual new content being
+ * pushed); falls back to all objects reachable from HEAD for a branch's first
+ * push (no upstream yet), which is equivalent since nothing has been pushed.
+ */
+export declare function findOversizedBlobs(brainDir: string, maxBytes: number): Promise<Array<{
+    path: string;
+    size: number;
+}>>;
 /**
  * Commit and push any changes in a brain repo.
  * Silently skips if there are no changes or no remote.
+ *
+ * On non-fast-forward rejection (tv#232 push-race — remote advanced between
+ * local commit and push, e.g. a concurrent session or scheduled-tick already
+ * pushed), fetch+rebase and retry, bounded by BRAIN_PUSH_RETRY_MAX. A genuine
+ * rebase conflict (or an autostash pop that silently leaves changes stashed —
+ * git does not surface that as a rebase error) is treated as a hard failure
+ * needing manual sync, not retried further.
+ *
+ * `retryOptions` defaults to the BRAIN_PUSH_RETRY_* config; exposed as a
+ * parameter (rather than reading `config` directly inline) so tests can
+ * exercise the retry-exhaustion boundary deterministically without relying on
+ * process-wide env/module-load-order tricks.
  */
-export declare function pushBrainChanges(brainDir: string, brainId: string, workspaceId?: string): Promise<void>;
+export declare function pushBrainChanges(brainDir: string, brainId: string, workspaceId?: string, retryOptions?: {
+    maxAttempts?: number;
+    backoffMs?: number;
+}): Promise<void>;
 /**
  * Ensure base paths exist
  */

package/dist/brain-manager.js

@@ -1,7 +1,8 @@
 import { exec } from 'child_process';
 import { promisify } from 'util';
 import { existsSync, mkdirSync } from 'fs';
-import { join } from 'path';
+import { readdir, stat, unlink } from 'fs/promises';
+import { join, basename } from 'path';
 import { config } from './config.js';
 import { logger } from './logger.js';
 import { emitError } from './event-queue.js';
@@ -20,8 +21,84 @@ if (config.PERSISTENT_STORAGE_PATH) {
 function gitExec(command, options) {
     return execAsync(command, { ...options, env: gitEnv });
 }
+// Node's child_process.exec() defaults to a 1MB stdout cap. This bounds the
+// text output of a git plumbing command (e.g. one line per object listed),
+// not any single blob's size -- it has no relationship to
+// config.BRAIN_MAX_BLOB_BYTES and must stay its own named constant so the
+// two don't drift into looking coupled just because they're both 50MB today.
+const GIT_SCAN_MAX_BUFFER_BYTES = 50 * 1024 * 1024;
 // Cooldown tracker per brain
 const lastUpdateTimes = new Map();
+// Per-brainId mutex serializing updateBrain/pushBrainChanges for a given
+// brain. Two threads of the SAME brain running concurrently in this process
+// share one brainDir (tv#76/tv#277 review) — without this, cleanupStaleLocks()
+// can unlink a git lock file that a still-in-flight sibling call's own git
+// operation legitimately holds, corrupting the index. Poller instances never
+// share a physical brainDir across processes/machines (BRAINS_PATH is
+// $HOME-derived and each poller is a single process — see tv#287), so this
+// in-process mutex fully closes the race; no DynamoDB-level lock is needed.
+const brainLocks = new Map();
+// Exported for testing — production call sites go through updateBrain / pushBrainChanges above.
+export function withBrainLock(brainId, fn) {
+    const prior = brainLocks.get(brainId) ?? Promise.resolve();
+    const run = prior.then(fn, fn);
+    brainLocks.set(brainId, run.then(() => undefined, () => undefined));
+    return run;
+}
+/**
+ * Remove stale git lock files (tv#76) so an orphaned lock from a killed
+ * process (e.g. the 2026-05-01 outage) doesn't block brain updates/pushes
+ * indefinitely. Fresh locks (younger than the threshold) are left alone —
+ * they may belong to a git operation that's genuinely still running.
+ * A missing lock (stat fails) is a silent no-op. A genuine removal failure
+ * (unlink fails, e.g. permission denied) is logged via logger.warn with the
+ * path and error — that's the exact "lock exists but can't be cleared"
+ * scenario this fix exists to make visible.
+ *
+ * Exported for testing — production call sites go through updateBrain /
+ * pushBrainChanges below.
+ */
+export async function cleanupStaleLocks(brainDir) {
+    const candidates = [
+        { path: join(brainDir, '.git', 'index.lock'), maxAgeMs: config.GIT_LOCK_MAX_AGE_MS },
+    ];
+    const modulesDir = join(brainDir, '.git', 'modules');
+    try {
+        const entries = await readdir(modulesDir, { recursive: true });
+        for (const entry of entries) {
+            if (basename(entry) === 'config.lock') {
+                candidates.push({ path: join(modulesDir, entry), maxAgeMs: config.GIT_SUBMODULE_LOCK_MAX_AGE_MS });
+            }
+        }
+    }
+    catch {
+        // No .git/modules dir (no submodules yet) — nothing to scan.
+    }
+    for (const { path: lockPath, maxAgeMs } of candidates) {
+        let lockStat;
+        try {
+            lockStat = await stat(lockPath);
+        }
+        catch {
+            // Lock doesn't exist — normal no-op, nothing worth logging.
+            continue;
+        }
+        const ageMs = Date.now() - lockStat.mtimeMs;
+        if (ageMs <= maxAgeMs)
+            continue;
+        try {
+            await unlink(lockPath);
+            logger.warn(`Removed stale git lock: ${lockPath} (age: ${Math.round(ageMs / 1000)}s, threshold: ${Math.round(maxAgeMs / 1000)}s)`);
+        }
+        catch (error) {
+            // Real removal failure (e.g. permission denied) — this is the exact
+            // 2026-05-01 outage scenario, so it must leave a diagnostic trail
+            // instead of silently skipping like a plain "lock doesn't exist".
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            logger.warn(`Failed to remove stale git lock: ${lockPath} (age: ${Math.round(ageMs / 1000)}s): ${errorMessage}`);
+        }
+    }
+}
 /**
  * Get or clone brain repo. Returns the working directory path.
  */
@@ -94,6 +171,9 @@ export async function getBrainPath(brain, channelId, workspaceId) {
  * call sites should go through `getBrainPath` / `ensureBaseBrain`.
  */
 export async function updateBrain(brainDir, brainId, branch) {
+    return withBrainLock(brainId, () => updateBrainLocked(brainDir, brainId, branch));
+}
+async function updateBrainLocked(brainDir, brainId, branch) {
     const now = Date.now();
     const lastUpdate = lastUpdateTimes.get(brainId) || 0;
     if (now - lastUpdate < config.BRAIN_UPDATE_COOLDOWN_MS) {
@@ -137,6 +217,7 @@ export async function updateBrain(brainDir, brainId, branch) {
         logger.warn(`Brain ${brainId} pre-check failed, skipping update: ${errorMessage}`);
         return;
     }
+    await cleanupStaleLocks(brainDir);
     try {
         logger.info(`Updating brain ${brainId} at ${brainDir}...`);
         await gitExec(`git fetch origin ${branch} && git reset --hard origin/${branch} && git submodule update --init --recursive`, {
@@ -173,11 +254,73 @@ export async function ensureBaseBrain() {
 export function getBaseBrainPath() {
     return config.BASE_BRAIN_PATH;
 }
+// Matches git's non-fast-forward push rejection ("! [rejected] ... (fetch first)"
+// or "... (non-fast-forward)"). Distinguishes a push-race (remote advanced,
+// reconcilable via rebase) from other push failures (network, auth, oversized
+// blob pre-receive decline — see tv#246) which retrying can never fix.
+const NON_FF_REJECTION_RE = /\[rejected\][\s\S]*(fetch first|non-fast-forward)/;
+async function gitStashList(brainDir) {
+    const { stdout } = await gitExec('git stash list', { cwd: brainDir });
+    return stdout.trim();
+}
+/**
+ * Scan the commits about to be pushed for blobs over `maxBytes`. Returns the
+ * offending paths/sizes, or an empty array if everything is under the limit.
+ *
+ * Scans `@{u}..HEAD` when an upstream exists (the actual new content being
+ * pushed); falls back to all objects reachable from HEAD for a branch's first
+ * push (no upstream yet), which is equivalent since nothing has been pushed.
+ */
+export async function findOversizedBlobs(brainDir, maxBytes) {
+    let range = 'HEAD';
+    try {
+        await gitExec('git rev-parse @{u}', { cwd: brainDir });
+        range = '@{u}..HEAD';
+    }
+    catch {
+        // No upstream tracking ref yet — first push for this branch, scan all of HEAD.
+    }
+    // A full-HEAD scan (the fallback path this guard needs to work on) can
+    // exceed Node's default 1MB stdout cap on a repo with many objects.
+    // Without a larger maxBuffer the scan throws ENOBUFS and the guard
+    // silently disables itself (see catch below) on exactly the histories most
+    // likely to contain an oversized blob.
+    const { stdout } = await gitExec(`git rev-list --objects ${range} | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)'`, { cwd: brainDir, maxBuffer: GIT_SCAN_MAX_BUFFER_BYTES });
+    const oversized = [];
+    for (const line of stdout.split('\n')) {
+        if (!line.trim())
+            continue;
+        const [type, , sizeStr, ...pathParts] = line.split(' ');
+        if (type !== 'blob')
+            continue;
+        const size = Number(sizeStr);
+        if (size > maxBytes) {
+            oversized.push({ path: pathParts.join(' ') || '(unknown path)', size });
+        }
+    }
+    return oversized;
+}
 /**
  * Commit and push any changes in a brain repo.
  * Silently skips if there are no changes or no remote.
+ *
+ * On non-fast-forward rejection (tv#232 push-race — remote advanced between
+ * local commit and push, e.g. a concurrent session or scheduled-tick already
+ * pushed), fetch+rebase and retry, bounded by BRAIN_PUSH_RETRY_MAX. A genuine
+ * rebase conflict (or an autostash pop that silently leaves changes stashed —
+ * git does not surface that as a rebase error) is treated as a hard failure
+ * needing manual sync, not retried further.
+ *
+ * `retryOptions` defaults to the BRAIN_PUSH_RETRY_* config; exposed as a
+ * parameter (rather than reading `config` directly inline) so tests can
+ * exercise the retry-exhaustion boundary deterministically without relying on
+ * process-wide env/module-load-order tricks.
  */
-export async function pushBrainChanges(brainDir, brainId, workspaceId) {
+export async function pushBrainChanges(brainDir, brainId, workspaceId, retryOptions) {
+    return withBrainLock(brainId, () => pushBrainChangesLocked(brainDir, brainId, workspaceId, retryOptions));
+}
+async function pushBrainChangesLocked(brainDir, brainId, workspaceId, retryOptions) {
+    await cleanupStaleLocks(brainDir);
     try {
         // Check if this is a git repo with a remote
         try {
@@ -203,11 +346,121 @@ export async function pushBrainChanges(brainDir, brainId, workspaceId) {
             logger.debug(`Brain ${brainId} has no unpushed commits`);
             return;
         }
+        // Guard: refuse to push if any blob about to be pushed exceeds the size limit.
+        // GitHub hard-rejects blobs over its limit, and once such a blob is committed
+        // the push can never succeed by retrying — it needs a history rewrite (tv#246).
+        // Skipping the push here keeps the brain retrying safely (and alerting) instead
+        // of hammering GitHub with a doomed push and losing the failure into poller.error.
+        try {
+            const oversized = await findOversizedBlobs(brainDir, config.BRAIN_MAX_BLOB_BYTES);
+            if (oversized.length > 0) {
+                const limitMb = (config.BRAIN_MAX_BLOB_BYTES / (1024 * 1024)).toFixed(0);
+                const details = oversized.map((o) => `${o.path} (${(o.size / (1024 * 1024)).toFixed(1)} MB)`).join(', ');
+                const message = `Brain ${brainId} push blocked — blob(s) over ${limitMb}MB limit in unpushed commits: ${details}`;
+                logger.error(message);
+                emitError('brain', message, { context: { brainId, oversizedPaths: oversized.map((o) => o.path) } });
+                return;
+            }
+        }
+        catch (error) {
+            // Guard itself failed (e.g. git plumbing hiccup) — don't block a legitimate
+            // push on that; fall through to the push attempt as before this guard existed.
+            // Still surface it as an error (not just a warn log): a silently-disabled
+            // guard defeats the whole point of tv#246, so it needs the same alerting
+            // visibility as the case it's meant to catch.
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            const message = `Brain ${brainId} oversized-blob guard failed, proceeding without it: ${errorMessage}`;
+            logger.error(message);
+            emitError('brain', message, { context: { brainId } });
+        }
         const branch = (await gitExec('git branch --show-current', { cwd: brainDir })).stdout.trim() || 'main';
-        await gitExec(`git push -u origin ${branch}`, { cwd: brainDir });
-        logger.info(`Brain ${brainId} changes pushed successfully`);
-        if (workspaceId)
-            reportBrainSync(brainId, workspaceId, 'pushed');
+        const maxAttempts = retryOptions?.maxAttempts ?? config.BRAIN_PUSH_RETRY_MAX;
+        const backoffMs = retryOptions?.backoffMs ?? config.BRAIN_PUSH_RETRY_BACKOFF_MS;
+        let attempt = 0;
+        let lastErrorMessage = '';
+        while (attempt < maxAttempts) {
+            attempt++;
+            try {
+                await gitExec(`git push -u origin ${branch}`, { cwd: brainDir });
+                if (attempt > 1) {
+                    logger.info(`Brain ${brainId} push-race auto-resolved after ${attempt} attempts`);
+                    emitError('brain', `Brain ${brainId} push-race auto-resolved after ${attempt} attempts`, {
+                        severity: 'warn',
+                        context: { brainId, errorCode: 'PUSH_RACE_CONVERGED', attempts: attempt },
+                    });
+                }
+                else {
+                    logger.info(`Brain ${brainId} changes pushed successfully`);
+                }
+                if (workspaceId)
+                    reportBrainSync(brainId, workspaceId, 'pushed');
+                return;
+            }
+            catch (error) {
+                lastErrorMessage = error instanceof Error ? error.message : String(error);
+                if (!NON_FF_REJECTION_RE.test(lastErrorMessage) || attempt >= maxAttempts)
+                    break;
+                logger.info(`Brain ${brainId} push rejected (non-fast-forward), rebasing and retrying (attempt ${attempt}/${maxAttempts})...`);
+                try {
+                    await gitExec(`git fetch origin ${branch}`, { cwd: brainDir });
+                }
+                catch (fetchError) {
+                    // No rebase has started yet at this point, so `git rebase --abort`
+                    // below would itself fail ("no rebase in progress") and mislabel a
+                    // plain network/fetch failure as PUSH_RACE_ABORT_FAILED. Keep fetch
+                    // failures in their own errorCode instead.
+                    const fetchMessage = fetchError instanceof Error ? fetchError.message : String(fetchError);
+                    logger.error(`Brain ${brainId} push-race: git fetch failed: ${fetchMessage}`);
+                    emitError('brain', `Brain ${brainId} push-race: fetch failed, cannot rebase: ${fetchMessage}`, {
+                        severity: 'error',
+                        context: { brainId, errorCode: 'PUSH_RACE_FETCH_FAILED', attempts: attempt },
+                    });
+                    return;
+                }
+                const stashBefore = await gitStashList(brainDir);
+                try {
+                    await gitExec(`git rebase --autostash origin/${branch}`, { cwd: brainDir });
+                    // `git rebase --autostash` does NOT surface a stash-pop conflict as a
+                    // rebase error — it just leaves the change stashed and warns on
+                    // stderr. Detect that silently-failed pop by diffing the stash list;
+                    // otherwise the loop would proceed to push with local work missing.
+                    const stashAfter = await gitStashList(brainDir);
+                    if (stashAfter !== stashBefore) {
+                        logger.error(`Brain ${brainId} push-race: autostash pop left changes stashed after rebase, treating as conflict`);
+                        emitError('brain', `Brain ${brainId} push-race autostash pop conflict — manual sync needed (stash: ${stashAfter.split('\n')[0]})`, { severity: 'error', context: { brainId, errorCode: 'PUSH_RACE_CONFLICT', attempts: attempt, reason: 'autostash_pop_conflict' } });
+                        return;
+                    }
+                }
+                catch (rebaseError) {
+                    try {
+                        await gitExec('git rebase --abort', { cwd: brainDir });
+                    }
+                    catch (abortError) {
+                        const abortMessage = abortError instanceof Error ? abortError.message : String(abortError);
+                        logger.error(`Brain ${brainId} push-race: git rebase --abort itself failed, repo may be left mid-rebase: ${abortMessage}`);
+                        emitError('brain', `Brain ${brainId} push-race: rebase abort failed, repo possibly stuck mid-rebase: ${abortMessage}`, {
+                            severity: 'error',
+                            context: { brainId, errorCode: 'PUSH_RACE_ABORT_FAILED', attempts: attempt },
+                        });
+                        return;
+                    }
+                    const rebaseMessage = rebaseError instanceof Error ? rebaseError.message : String(rebaseError);
+                    logger.error(`Brain ${brainId} push-race rebase conflict: ${rebaseMessage}`);
+                    emitError('brain', `Brain ${brainId} push-race rebase conflict — manual sync needed: ${rebaseMessage}`, {
+                        severity: 'error',
+                        context: { brainId, errorCode: 'PUSH_RACE_CONFLICT', attempts: attempt },
+                    });
+                    return;
+                }
+                await new Promise((resolve) => setTimeout(resolve, backoffMs * attempt));
+            }
+        }
+        const errorCode = NON_FF_REJECTION_RE.test(lastErrorMessage) ? 'PUSH_RACE_UNRESOLVED' : 'PUSH_FAILED';
+        logger.warn(`Failed to push brain ${brainId} changes: ${lastErrorMessage}`);
+        emitError('brain', `Failed to push brain ${brainId} changes: ${lastErrorMessage}`, {
+            severity: errorCode === 'PUSH_RACE_UNRESOLVED' ? 'error' : 'warn',
+            context: { brainId, errorCode, attempts: attempt },
+        });
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);

package/dist/brains-bootstrap.d.ts

@@ -0,0 +1,45 @@
+/** @internal test-only */
+export declare function __detachedRetryForTest(): Promise<void> | undefined;
+/**
+ * Fetch the full list of brains this poller is responsible for from the
+ * backend (GET /poller/brains, source of truth = DDB — teamvibe.ai#127
+ * Option B) and seed `trackedBrains` (maintenance-cron.ts) before the
+ * maintenance/heartbeat cron starts, so a brain that's been quiet since
+ * before this poller's most recent restart is still picked up instead of
+ * staying invisible until a human happens to message it.
+ *
+ * Best-effort: on any failure (network, timeout, non-2xx, malformed body,
+ * missing pollerId/token) this logs a warning, emits a telemetry event, and
+ * returns without throwing. Startup must not hang or crash on this — the
+ * pre-#127 behavior (trackedBrains starts empty until real messages
+ * trickle in) is the fallback here, not a fatal state.
+ *
+ * DevGuru round-3 review: the awaited part of this function does exactly
+ * ONE fetch attempt, bounded by CRITICAL_PATH_TIMEOUT_MS (~10s) — not the
+ * full 30s client timeout, and not the retry. Every poller restart during a
+ * backend outage was blocking real user-message processing (pollLoop(),
+ * called after this in startPoller()) for up to ~62s (2 attempts * 30s +
+ * 2s delay) — and restarts correlate with backend deploys, exactly when
+ * this is most likely to happen. If the first attempt fails and is
+ * retryable (network error, timeout, or 5xx — not a 4xx or malformed body,
+ * which a retry can't fix), the retry is kicked off detached — an
+ * immediately-invoked async function whose promise is stored in a
+ * module-level variable (see `__detachedRetryForTest` below; test-only,
+ * production code never reads it) rather than `void`-discarded, but never
+ * awaited by this function — the same fire-and-forget shape
+ * maintenance-cron.ts's registerBrain() already uses for its immediate
+ * metrics collect+send — so `bootstrapTrackedBrains()` returns and
+ * startPoller() can proceed to
+ * startMaintenanceLoop/startAutoUpdateCron/startMetricsCron/pollLoop()
+ * without waiting on it. This is safe because neither downstream consumer
+ * needs bootstrap complete synchronously: the maintenance cron only fires
+ * at its own scheduled time (default 03:30, not at startup), and the inbox
+ * watcher just needs trackedBrains populated "one tick later" — both read
+ * the same shared, mutable Map (getTrackedBrains()) whenever their own tick
+ * fires, not a snapshot taken at startup.
+ *
+ * No-ops in direct (non-token) mode, same gating as sendMetrics
+ * (metrics/sender.ts) — there's no backend endpoint to call without
+ * TEAMVIBE_API_URL + TEAMVIBE_POLLER_TOKEN.
+ */
+export declare function bootstrapTrackedBrains(): Promise<void>;

package/dist/brains-bootstrap.js

@@ -0,0 +1,217 @@
+import { config } from './config.js';
+import { logger } from './logger.js';
+import { getPollerId } from './auth-provider.js';
+import { seedTrackedBrains } from './maintenance-cron.js';
+import { emitEvent, emitError } from './event-queue.js';
+// Client-side timeout kept comfortably above the server-side route timeout
+// (infra/poller-auth.ts: GET /poller/brains, 25s) so the poller never aborts
+// a request the Lambda could still have answered (DevGuru round-2 review —
+// with the old 10s client timeout vs a 20s route timeout, a transient slow
+// response aborted client-side while the Lambda kept running to nothing,
+// burning the one bootstrap attempt with no retry until the next restart).
+// Used ONLY for the off-critical-path retry attempt below — DevGuru round-3:
+// "don't touch the 25s/30s numbers themselves", so this stays exactly as
+// round-2 left it, just no longer used for the first attempt.
+const FETCH_TIMEOUT_MS = 30_000;
+// Short deadline for the ONE attempt that's actually awaited on
+// startPoller()'s critical path (DevGuru round-3 review item 2). Judgment
+// call — not spelled out beyond "~10s" — picked 10s exactly as suggested.
+// Rationale for why a short deadline is safe here even though it's shorter
+// than the 25s the Lambda might legitimately take: this is only the FIRST
+// attempt. If it doesn't finish inside 10s, we don't conclude failure and
+// give up — we fall through to the same retry path used for any other
+// transient failure, just detached from startup so a slow-but-alive
+// backend doesn't cost the poller a lost user-message-processing minute.
+const CRITICAL_PATH_TIMEOUT_MS = 10_000;
+// Judgment call (not specified by DevGuru's review, flagged for reviewer):
+// one retry, 2s fixed delay, unchanged from round 2. Since the retry is now
+// off the critical path (see bootstrapTrackedBrains below), the 2s delay no
+// longer costs startup time — it only affects how soon the detached retry
+// fires, which is not time-critical (the maintenance cron doesn't run until
+// its own scheduled time, and the inbox watcher just needs trackedBrains
+// populated "one tick later", not synchronously — DevGuru round-3).
+const RETRY_DELAY_MS = 2_000;
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+// Test-only handle to the detached retry promise (see bootstrapTrackedBrains
+// below) kicked off by the most recent call. Undefined until a retryable
+// first-attempt failure schedules one; reset to undefined at the top of
+// every bootstrapTrackedBrains() call so a stale promise from a PRIOR call
+// is never mistaken for the current one. Same test-only-export convention
+// as maintenance-cron.ts's __resetTrackedBrainsForTest() — never read by
+// production code, exists purely so tests can deterministically wait for
+// the detached background work to finish instead of guessing with a fixed
+// sleep (DevGuru review: the fixed-sleep approach was two separate
+// latent-flakiness bugs — see brains-bootstrap.test.ts).
+let detachedRetryForTest;
+/** @internal test-only */
+export function __detachedRetryForTest() {
+    return detachedRetryForTest;
+}
+async function attemptFetch(url, token, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, {
+            headers: { Authorization: `Bearer ${token}` },
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            return {
+                ok: false,
+                reason: 'non-2xx',
+                detail: `status ${response.status}`,
+                retryable: response.status >= 500,
+            };
+        }
+        let body;
+        try {
+            body = await response.json();
+        }
+        catch (err) {
+            return {
+                ok: false,
+                reason: 'invalid-json',
+                detail: err instanceof Error ? err.message : String(err),
+                retryable: false,
+            };
+        }
+        if (!body || typeof body !== 'object' || !Array.isArray(body.brains)) {
+            return { ok: false, reason: 'malformed-body', detail: 'missing brains array', retryable: false };
+        }
+        return { ok: true, brains: body.brains };
+    }
+    catch (err) {
+        const isTimeout = err instanceof Error && err.name === 'AbortError';
+        return {
+            ok: false,
+            reason: isTimeout ? 'timeout' : 'network-error',
+            detail: err instanceof Error ? err.message : String(err),
+            retryable: true,
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Seed trackedBrains from a successful fetch and emit success telemetry.
+ * Shared by both the critical-path attempt and the detached retry below. */
+function applySuccess(brains) {
+    const seeded = seedTrackedBrains(brains);
+    logger.info(`[Bootstrap] Seeded ${seeded} brain(s) into trackedBrains from backend (${brains.length} returned)`);
+    emitEvent('poller.brains_bootstrap.success', 'system', {
+        seeded,
+        returned: brains.length,
+    });
+}
+/** Report a terminal (no-more-retries) failure. Distinct telemetry artifact
+ * (DevGuru round-2 review) — from outside, "bootstrap crashed" and
+ * "bootstrap ran fine, no quiet brains to seed" were previously
+ * indistinguishable (both show seeded=0 in a log line nobody's watching).
+ * This feeds the same FLEET_ERROR pipeline as maintenance-cron.ts's
+ * emitError call (triggerAllBrains, per-brain maintenance failure) — same
+ * category, same shape. Only called once per bootstrap attempt sequence
+ * (non-retryable first-attempt failure, or a failed retry) — never for a
+ * retryable first-attempt failure, since that one isn't terminal yet. */
+function reportFailure(outcome) {
+    emitError('maintenance', `trackedBrains bootstrap failed: ${outcome.reason}`, {
+        severity: 'warn',
+        context: { reason: outcome.reason, detail: outcome.detail },
+    });
+}
+/**
+ * Fetch the full list of brains this poller is responsible for from the
+ * backend (GET /poller/brains, source of truth = DDB — teamvibe.ai#127
+ * Option B) and seed `trackedBrains` (maintenance-cron.ts) before the
+ * maintenance/heartbeat cron starts, so a brain that's been quiet since
+ * before this poller's most recent restart is still picked up instead of
+ * staying invisible until a human happens to message it.
+ *
+ * Best-effort: on any failure (network, timeout, non-2xx, malformed body,
+ * missing pollerId/token) this logs a warning, emits a telemetry event, and
+ * returns without throwing. Startup must not hang or crash on this — the
+ * pre-#127 behavior (trackedBrains starts empty until real messages
+ * trickle in) is the fallback here, not a fatal state.
+ *
+ * DevGuru round-3 review: the awaited part of this function does exactly
+ * ONE fetch attempt, bounded by CRITICAL_PATH_TIMEOUT_MS (~10s) — not the
+ * full 30s client timeout, and not the retry. Every poller restart during a
+ * backend outage was blocking real user-message processing (pollLoop(),
+ * called after this in startPoller()) for up to ~62s (2 attempts * 30s +
+ * 2s delay) — and restarts correlate with backend deploys, exactly when
+ * this is most likely to happen. If the first attempt fails and is
+ * retryable (network error, timeout, or 5xx — not a 4xx or malformed body,
+ * which a retry can't fix), the retry is kicked off detached — an
+ * immediately-invoked async function whose promise is stored in a
+ * module-level variable (see `__detachedRetryForTest` below; test-only,
+ * production code never reads it) rather than `void`-discarded, but never
+ * awaited by this function — the same fire-and-forget shape
+ * maintenance-cron.ts's registerBrain() already uses for its immediate
+ * metrics collect+send — so `bootstrapTrackedBrains()` returns and
+ * startPoller() can proceed to
+ * startMaintenanceLoop/startAutoUpdateCron/startMetricsCron/pollLoop()
+ * without waiting on it. This is safe because neither downstream consumer
+ * needs bootstrap complete synchronously: the maintenance cron only fires
+ * at its own scheduled time (default 03:30, not at startup), and the inbox
+ * watcher just needs trackedBrains populated "one tick later" — both read
+ * the same shared, mutable Map (getTrackedBrains()) whenever their own tick
+ * fires, not a snapshot taken at startup.
+ *
+ * No-ops in direct (non-token) mode, same gating as sendMetrics
+ * (metrics/sender.ts) — there's no backend endpoint to call without
+ * TEAMVIBE_API_URL + TEAMVIBE_POLLER_TOKEN.
+ */
+export async function bootstrapTrackedBrains() {
+    detachedRetryForTest = undefined;
+    if (!config.TEAMVIBE_API_URL || !config.TEAMVIBE_POLLER_TOKEN) {
+        return;
+    }
+    const pollerId = getPollerId();
+    if (!pollerId) {
+        logger.warn('[Bootstrap] Skipping trackedBrains bootstrap: no pollerId (auth not completed?)');
+        return;
+    }
+    const token = config.TEAMVIBE_POLLER_TOKEN;
+    const url = `${config.TEAMVIBE_API_URL}/poller/brains?pollerId=${encodeURIComponent(pollerId)}`;
+    const outcome = await attemptFetch(url, token, CRITICAL_PATH_TIMEOUT_MS);
+    if (outcome.ok) {
+        applySuccess(outcome.brains);
+        return;
+    }
+    logger.warn(`[Bootstrap] GET /poller/brains failed on first attempt: ${outcome.reason} (${outcome.detail})`);
+    if (!outcome.retryable) {
+        reportFailure(outcome);
+        return;
+    }
+    // Off the critical path from here — startPoller() is not waiting on this
+    // promise. Wrapped in try/catch (DevGuru round-4 review) rather than just
+    // asserting "nothing below throws": attemptFetch() itself always returns
+    // an outcome object instead of throwing, but applySuccess() (seedTrackedBrains
+    // + emitEvent) and reportFailure() (emitError) are still real function
+    // calls — if either ever throws for any reason (a future refactor, an
+    // unexpected edge case), an uncaught throw inside this detached function
+    // becomes an unhandled promise rejection and crashes the whole poller
+    // process. Cheap insurance: catch and log a warning, matching this file's
+    // existing logger.warn style, instead of letting it propagate.
+    //
+    // Stored in detachedRetryForTest (DevGuru round-5 review) rather than
+    // `void`-discarded, purely so tests can await it deterministically — see
+    // that variable's own comment above. Storing the reference doesn't change
+    // runtime behavior here: this function still never awaits it itself.
+    detachedRetryForTest = (async () => {
+        try {
+            await sleep(RETRY_DELAY_MS);
+            const retryOutcome = await attemptFetch(url, token, FETCH_TIMEOUT_MS);
+            if (retryOutcome.ok) {
+                applySuccess(retryOutcome.brains);
+                return;
+            }
+            logger.warn(`[Bootstrap] GET /poller/brains failed on retry: ${retryOutcome.reason} (${retryOutcome.detail})`);
+            reportFailure(retryOutcome);
+        }
+        catch (err) {
+            logger.warn(`[Bootstrap] Detached retry threw unexpectedly: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    })();
+}

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

@@ -1,4 +1,4 @@
-export type KilledByPoller = 'timeout' | 'idle' | 'zombie' | 'network';
+export type KilledByPoller = 'timeout' | 'idle' | 'zombie' | 'network' | 'shutdown';
 export interface FailedIterationInput {
     error?: string;
     exitCode: number | null;