@teamvibe/poller 0.7.0 → 0.7.2

package/dist/brain-manager.d.ts

@@ -18,6 +18,14 @@ interface BrainConfig {
  * pushBrainChanges below.
  */
 export declare function cleanupStaleLocks(brainDir: string): Promise<void>;
+/**
+ * Write the local (uncommitted) merge-driver attributes for a brain checkout.
+ * Idempotent and safe to call on every `getBrainPath` invocation, not just on
+ * first clone — this also self-heals brains that were checked out before
+ * this existed. Exported for testing — production call sites go through
+ * `getBrainPath`.
+ */
+export declare function ensureGitAttributes(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

package/dist/brain-manager.js

@@ -1,7 +1,7 @@
 import { exec } from 'child_process';
 import { promisify } from 'util';
 import { existsSync, mkdirSync } from 'fs';
-import { readdir, stat, unlink } from 'fs/promises';
+import { readdir, stat, unlink, mkdir, writeFile } from 'fs/promises';
 import { join, basename } from 'path';
 import { config } from './config.js';
 import { logger } from './logger.js';
@@ -128,6 +128,47 @@ async function reportBrainSync(brainId, workspaceId, event) {
         emitError('brain', `Brain sync report error: ${error instanceof Error ? error.message : String(error)}`, { severity: 'warn', context: { brainId } });
     }
 }
+// tv#247: local-only (never committed, never synced) merge-driver config for
+// a brain checkout. `merge=union` is one of git's built-in low-level merge
+// drivers (alongside `text`/`binary`) — an attributes entry alone is enough,
+// no `[merge "union"]` section in git config is needed (verified: a rebase
+// across two branches with independent appends to a `merge=union`-attributed
+// file merges both lines automatically instead of conflicting).
+//
+// Scoped ONLY to genuinely pure-append, line-independent files. Deliberately
+// does NOT cover MEM_REGISTRY.md, MEM_REGISTRY_ARCHIVE.md, semantic/*, or
+// episodic/* — consolidation edits those in place (promotes/removes
+// entries), so a union merge there would resurrect already-promoted-and-
+// removed content instead of resolving the conflict, rather than concatenate
+// two genuinely independent additions.
+//
+// Written to `.git/info/attributes` (not a committed `.gitattributes`)
+// because this is poller-local git behavior, not brain content — channel
+// brain repos are written to only by their own sessions, never by the
+// platform directly.
+const GIT_ATTRIBUTES_CONTENT = ['memory/TODAY.md merge=union', 'memory/daily/*.md merge=union', ''].join('\n');
+/**
+ * Write the local (uncommitted) merge-driver attributes for a brain checkout.
+ * Idempotent and safe to call on every `getBrainPath` invocation, not just on
+ * first clone — this also self-heals brains that were checked out before
+ * this existed. Exported for testing — production call sites go through
+ * `getBrainPath`.
+ */
+export async function ensureGitAttributes(brainDir) {
+    try {
+        const gitDir = join(brainDir, '.git');
+        if (!existsSync(gitDir))
+            return; // not a git repo yet (defensive — getBrainPath always clones first)
+        const infoDir = join(gitDir, 'info');
+        await mkdir(infoDir, { recursive: true });
+        await writeFile(join(infoDir, 'attributes'), GIT_ATTRIBUTES_CONTENT);
+    }
+    catch (error) {
+        // Best-effort: worst case a future push-race on these files needs manual
+        // resolution same as before this existed. Not a reason to fail the caller.
+        logger.warn(`Brain ${brainDir}: failed to write .git/info/attributes: ${error instanceof Error ? error.message : error}`);
+    }
+}
 export async function getBrainPath(brain, channelId, workspaceId) {
     if (!brain?.gitRepoUrl) {
         if (channelId) {
@@ -164,6 +205,9 @@ export async function getBrainPath(brain, channelId, workspaceId) {
         if (workspaceId)
             reportBrainSync(brain.brainId, workspaceId, 'pulled');
     }
+    // Idempotent, local-only — covers both the fresh-clone and existing-dir
+    // branches above, and self-heals brains cloned before this existed.
+    await ensureGitAttributes(brainDir);
     return brainDir;
 }
 /**
@@ -263,6 +307,52 @@ async function gitStashList(brainDir) {
     const { stdout } = await gitExec('git stash list', { cwd: brainDir });
     return stdout.trim();
 }
+// Per-brainId rescue-ref name, seeded with a timestamp the first time a given
+// brainId hits an unresolved push-race conflict, then reused (force-pushed
+// to) on every later pushBrainChangesLocked invocation that still can't
+// converge — e.g. the next message's push attempt while the conflict remains
+// unresolved on disk. Without this, each retry would mint its own
+// `conflict/<brainId>-<ts>` ref and spam origin with one throwaway branch per
+// retry instead of one per actual incident. Cleared on the next successful
+// push for that brainId, since any future conflict after that point is a new,
+// unrelated incident that deserves its own ref.
+const rescueRefNames = new Map();
+/**
+ * Best-effort durability net for a `PUSH_RACE_CONFLICT`: push whatever HEAD
+ * currently points to onto a throwaway ref on origin before the caller
+ * reports the conflict, so the session's commits survive even if this
+ * checkout is lost (crash, re-clone, TTL'd container) before a human/AI does
+ * the manual resolution. Never throws — a failed rescue push just means no
+ * safety net for this occurrence, not a reason to mask the real
+ * PUSH_RACE_CONFLICT error the caller is about to report.
+ *
+ * Callers MUST ensure `HEAD` is the safe, non-mid-rebase content to rescue
+ * before calling this (e.g. after `git rebase --abort` restores the
+ * pre-rebase local branch) — this function pushes HEAD as-is.
+ */
+async function pushRescueRef(brainDir, brainId) {
+    let refName = rescueRefNames.get(brainId);
+    if (!refName) {
+        // Unix seconds (not ms) — matches the <timestamp> format documented on
+        // the consuming side (poller-brain#443's MAINTENANCE.md `oldestAgeDays`
+        // derivation), so both sides agree on how to parse the ref name.
+        refName = `conflict/${brainId}-${Math.floor(Date.now() / 1000)}`;
+        rescueRefNames.set(brainId, refName);
+    }
+    try {
+        await gitExec(`git push --force origin HEAD:refs/heads/${refName}`, { cwd: brainDir });
+        logger.info(`Brain ${brainId} push-race: rescued local commits to ${refName}`);
+        return { refName, pushed: true };
+    }
+    catch (error) {
+        // Distinct sub-case from a successful rescue (same failure class as the
+        // known pb#440 issue — e.g. broken git credentials) — logged separately
+        // so it's never mistaken for "commits are safe on origin".
+        const message = error instanceof Error ? error.message : String(error);
+        logger.error(`Brain ${brainId} push-race: rescue-ref push to ${refName} itself FAILED, local commits remain only on disk: ${message}`);
+        return { refName, pushed: false };
+    }
+}
 /**
  * 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.
@@ -382,6 +472,10 @@ async function pushBrainChangesLocked(brainDir, brainId, workspaceId, retryOptio
             attempt++;
             try {
                 await gitExec(`git push -u origin ${branch}`, { cwd: brainDir });
+                // A successful push means any earlier unresolved conflict for this
+                // brainId (if any) is now resolved — a future conflict is a new,
+                // unrelated incident, so stop reusing that rescue ref name.
+                rescueRefNames.delete(brainId);
                 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`, {
@@ -427,7 +521,15 @@ async function pushBrainChangesLocked(brainDir, brainId, workspaceId, retryOptio
                     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' } });
+                        // The rebase itself (of committed local work onto origin) succeeded
+                        // here — HEAD is the safe, non-mid-rebase content to rescue; only
+                        // the separate stash-pop of uncommitted changes is what's stuck.
+                        const { refName: rescueRef, pushed: rescuePushed } = await pushRescueRef(brainDir, brainId);
+                        emitError('brain', `Brain ${brainId} push-race autostash pop conflict — manual sync needed (stash: ${stashAfter.split('\n')[0]})` +
+                            (rescuePushed ? `, committed local work rescued to ${rescueRef}` : `, rescue push to ${rescueRef} also FAILED`), {
+                            severity: 'error',
+                            context: { brainId, errorCode: 'PUSH_RACE_CONFLICT', attempts: attempt, reason: 'autostash_pop_conflict', rescueRef, rescuePushed },
+                        });
                         return;
                     }
                 }
@@ -442,13 +544,21 @@ async function pushBrainChangesLocked(brainDir, brainId, workspaceId, retryOptio
                             severity: 'error',
                             context: { brainId, errorCode: 'PUSH_RACE_ABORT_FAILED', attempts: attempt },
                         });
+                        // Repo is left mid-rebase / in an uncertain state — do NOT push
+                        // HEAD to a rescue ref here, that would rescue the wrong
+                        // (partially-applied) content instead of the pre-conflict local work.
                         return;
                     }
+                    // `git rebase --abort` above restored HEAD to the pre-rebase local
+                    // branch — i.e. exactly the unpushed, pre-conflict work we need to
+                    // keep durable, not whatever mid-rebase state existed a moment ago.
+                    const { refName: rescueRef, pushed: rescuePushed } = await pushRescueRef(brainDir, brainId);
                     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}`, {
+                    emitError('brain', `Brain ${brainId} push-race rebase conflict — manual sync needed: ${rebaseMessage}` +
+                        (rescuePushed ? `, local commits rescued to ${rescueRef}` : `, rescue push to ${rescueRef} also FAILED`), {
                         severity: 'error',
-                        context: { brainId, errorCode: 'PUSH_RACE_CONFLICT', attempts: attempt },
+                        context: { brainId, errorCode: 'PUSH_RACE_CONFLICT', attempts: attempt, rescueRef, rescuePushed },
                     });
                     return;
                 }
@@ -457,9 +567,25 @@ async function pushBrainChangesLocked(brainDir, brainId, workspaceId, retryOptio
         }
         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}`, {
+        // PUSH_RACE_UNRESOLVED means the retry budget ran out while HEAD was still
+        // in the safe, non-mid-rebase state left by the last successful rebase
+        // (the loop only reaches here via the `attempt >= maxAttempts` break right
+        // after a push rejection, never after a failed rebase — those return
+        // earlier). Same "local commits only on disk" risk as the two conflict
+        // cases above, just a different exhaustion cause — rescue it too.
+        // PUSH_FAILED (non-NON_FF failures, e.g. auth/network) deliberately
+        // skipped: a rescue push would almost always fail for the identical
+        // reason as the push it's rescuing.
+        let rescueRef;
+        let rescuePushed;
+        if (errorCode === 'PUSH_RACE_UNRESOLVED') {
+            ;
+            ({ refName: rescueRef, pushed: rescuePushed } = await pushRescueRef(brainDir, brainId));
+        }
+        emitError('brain', `Failed to push brain ${brainId} changes: ${lastErrorMessage}` +
+            (errorCode === 'PUSH_RACE_UNRESOLVED' ? (rescuePushed ? `, local commits rescued to ${rescueRef}` : `, rescue push to ${rescueRef} also FAILED`) : ''), {
             severity: errorCode === 'PUSH_RACE_UNRESOLVED' ? 'error' : 'warn',
-            context: { brainId, errorCode, attempts: attempt },
+            context: { brainId, errorCode, attempts: attempt, ...(errorCode === 'PUSH_RACE_UNRESOLVED' ? { rescueRef, rescuePushed } : {}) },
         });
     }
     catch (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/claude-spawner.d.ts

@@ -232,6 +232,7 @@ export declare function spawnClaudeCode(msg: TeamVibeQueueMessage, sessionLog: S
     newSessionId?: string;
 }>;
 export declare function getActiveProcessCount(): number;
+export declare function getLastSessionEndTs(): number;
 /**
  * Kill a zombie process for a given thread ID.
  * Returns true if a process was found and killed.

package/dist/claude-spawner.js

@@ -1116,6 +1116,7 @@ async function runClaudeCode(msg, sessionLog, cwd, brainPath, sessionId, isFirst
             clearNotificationTimers();
             activeProcesses.delete(msg.id);
             activeProcessesByThread.delete(msg.thread_id);
+            lastSessionEndTs = Date.now();
             // #73 gap 2 (flagged independently by two reviews): `close` firing means
             // `claude` itself has exited, but its MCP server children — spawned
             // into the same detached process group, see `spawn()` above — are not
@@ -1178,6 +1179,7 @@ async function runClaudeCode(msg, sessionLog, cwd, brainPath, sessionId, isFirst
             clearInterval(idleWatchdog);
             activeProcesses.delete(msg.id);
             activeProcessesByThread.delete(msg.thread_id);
+            lastSessionEndTs = Date.now();
             emitError('session', `Claude Code process spawn error: ${error.message}`, {
                 channelId: msg.teamvibe.channelId,
                 context: { threadId: msg.thread_id },
@@ -1275,9 +1277,17 @@ export async function spawnClaudeCode(msg, sessionLog, cwd, sessionId, isFirstMe
 }
 const activeProcesses = new Map();
 const activeProcessesByThread = new Map();
+// tv#317: when the last `claude` process ended, so the idle-restart gate can require
+// a quiet period since real work last happened. Starts at module load (poller boot) so
+// a poller that never runs a session still becomes eligible once IDLE_RESTART_MIN_UPTIME_MS
+// passes, rather than being stuck at 0/undefined forever.
+let lastSessionEndTs = Date.now();
 export function getActiveProcessCount() {
     return activeProcesses.size;
 }
+export function getLastSessionEndTs() {
+    return lastSessionEndTs;
+}
 /**
  * Kill a zombie process for a given thread ID.
  * Returns true if a process was found and killed.

package/dist/config.d.ts

@@ -41,6 +41,10 @@ declare const configSchema: z.ZodObject<{
     AUTO_UPDATE_SCHEDULE: z.ZodDefault<z.ZodString>;
     INBOX_WATCH_FALLBACK_INTERVAL_MS: z.ZodDefault<z.ZodNumber>;
     INBOX_WATCH_DEBOUNCE_MS: z.ZodDefault<z.ZodNumber>;
+    IDLE_RESTART_ENABLED: z.ZodEffects<z.ZodDefault<z.ZodString>, boolean, string | undefined>;
+    IDLE_RESTART_IDLE_MS: z.ZodDefault<z.ZodNumber>;
+    IDLE_RESTART_MIN_UPTIME_MS: z.ZodDefault<z.ZodNumber>;
+    IDLE_RESTART_MEMORY_FILE_THRESHOLD_BYTES: z.ZodDefault<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     AWS_REGION: string;
     TEAMVIBE_API_URL: string;
@@ -78,6 +82,10 @@ declare const configSchema: z.ZodObject<{
     AUTO_UPDATE_SCHEDULE: string;
     INBOX_WATCH_FALLBACK_INTERVAL_MS: number;
     INBOX_WATCH_DEBOUNCE_MS: number;
+    IDLE_RESTART_ENABLED: boolean;
+    IDLE_RESTART_IDLE_MS: number;
+    IDLE_RESTART_MIN_UPTIME_MS: number;
+    IDLE_RESTART_MEMORY_FILE_THRESHOLD_BYTES: number;
     SQS_QUEUE_URL?: string | undefined;
     SESSIONS_TABLE?: string | undefined;
     TEAMVIBE_POLLER_TOKEN?: string | undefined;
@@ -123,6 +131,10 @@ declare const configSchema: z.ZodObject<{
     AUTO_UPDATE_SCHEDULE?: string | undefined;
     INBOX_WATCH_FALLBACK_INTERVAL_MS?: number | undefined;
     INBOX_WATCH_DEBOUNCE_MS?: number | undefined;
+    IDLE_RESTART_ENABLED?: string | undefined;
+    IDLE_RESTART_IDLE_MS?: number | undefined;
+    IDLE_RESTART_MIN_UPTIME_MS?: number | undefined;
+    IDLE_RESTART_MEMORY_FILE_THRESHOLD_BYTES?: number | undefined;
 }>;
 export type Config = z.infer<typeof configSchema>;
 export declare function loadConfig(): Config;
@@ -163,6 +175,10 @@ export declare const config: {
     AUTO_UPDATE_SCHEDULE: string;
     INBOX_WATCH_FALLBACK_INTERVAL_MS: number;
     INBOX_WATCH_DEBOUNCE_MS: number;
+    IDLE_RESTART_ENABLED: boolean;
+    IDLE_RESTART_IDLE_MS: number;
+    IDLE_RESTART_MIN_UPTIME_MS: number;
+    IDLE_RESTART_MEMORY_FILE_THRESHOLD_BYTES: number;
     SQS_QUEUE_URL?: string | undefined;
     SESSIONS_TABLE?: string | undefined;
     TEAMVIBE_POLLER_TOKEN?: string | undefined;

package/dist/config.js

@@ -76,6 +76,23 @@ const configSchema = z.object({
     // exist at watcher startup, and prunes empty thread dirs.
     INBOX_WATCH_FALLBACK_INTERVAL_MS: z.coerce.number().default(300_000), // 5 minutes
     INBOX_WATCH_DEBOUNCE_MS: z.coerce.number().default(300), // coalesce bursty fs events into one scan
+    // Idle restart (tv#317): Railway bills on cgroup memory usage, which includes page
+    // cache that Linux only reclaims under real memory pressure — a large Railway memory
+    // limit means that pressure never triggers, so cache from heavy sessions (bun install,
+    // vite build, apt) accumulates until something forces a restart. Rather than an
+    // external supervisor, the poller restarts itself once genuinely idle; Railway's
+    // ALWAYS restart policy brings it back up clean and any SQS message that arrives
+    // during the few-second restart window just waits in the queue.
+    //
+    // Defaults OFF: this is a Railway-specific mitigation (the memory-threshold check
+    // is gated on cgroup v2 anyway, see readReclaimableFileBytes), but the default
+    // should make that explicit rather than lean on an implicit cgroup-absence no-op —
+    // deploy targets that also happen to be cgroup v2 Linux shouldn't pick this up by
+    // just existing. Set IDLE_RESTART_ENABLED=true on Railway to opt in.
+    IDLE_RESTART_ENABLED: z.string().default('false').transform((v) => v.toLowerCase() === 'true'),
+    IDLE_RESTART_IDLE_MS: z.coerce.number().default(1_800_000), // 30 minutes since the last session ended
+    IDLE_RESTART_MIN_UPTIME_MS: z.coerce.number().default(1_800_000), // crash-loop guard — matches the idle floor above (tv#317 discussion), so it doesn't add its own separate cadence
+    IDLE_RESTART_MEMORY_FILE_THRESHOLD_BYTES: z.coerce.number().default(700 * 1024 * 1024), // cgroup memory.stat `file` (reclaimable page cache), not memory.current — gating on raw usage would also fire on a real anon leak and mask it instead of just clearing cache
 });
 export function loadConfig() {
     const result = configSchema.safeParse(process.env);

package/dist/idle-restart.d.ts

@@ -0,0 +1,12 @@
+export declare function readReclaimableFileBytes(path?: string): number | null;
+export declare function findLiveBgTask(now?: number): string | null;
+export declare function reconcileBgTasksOnBoot(): void;
+export interface CheckIdleRestartDeps {
+    now?: number;
+    startTime?: number;
+    activeProcessCount?: () => number;
+    lastSessionEndTs?: () => number;
+    reclaimableBytes?: () => number | null;
+    liveBgTask?: () => string | null;
+}
+export declare function checkIdleRestart(deps?: CheckIdleRestartDeps): boolean;