@teamvibe/poller 0.7.0 → 0.7.1

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;

package/dist/idle-restart.js

@@ -0,0 +1,200 @@
+import { appendFileSync, readdirSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { config } from './config.js';
+import { logger } from './logger.js';
+import { getActiveProcessCount, getLastSessionEndTs } from './claude-spawner.js';
+import { emitEvent } from './event-queue.js';
+// tv#317: self-restart once genuinely idle, to let Railway reclaim page-cache RAM that
+// Linux never proactively frees under our large memory limit. See config.ts for the
+// IDLE_RESTART_* thresholds this checks against.
+const processStartTime = Date.now();
+// cgroup v2 only. Railway containers run cgroup v2; on anything else (local dev, a
+// future cgroup v1 host) this just returns null and the gate never fires — the memory
+// pressure this exists to relieve is Railway-specific, so failing closed is correct
+// rather than guessing at a v1 path/format.
+const MEMORY_STAT_PATH = '/sys/fs/cgroup/memory.stat';
+export function readReclaimableFileBytes(path = MEMORY_STAT_PATH) {
+    let text;
+    try {
+        text = readFileSync(path, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    for (const line of text.split('\n')) {
+        const spaceIdx = line.indexOf(' ');
+        if (spaceIdx > 0 && line.slice(0, spaceIdx) === 'file') {
+            const value = Number(line.slice(spaceIdx + 1));
+            return Number.isFinite(value) ? value : null;
+        }
+    }
+    return null;
+}
+// --- bg-task liveness ---------------------------------------------------------------
+//
+// Reimplemented (not imported): bg-task.mjs lives in poller-brain and runs inside a
+// Claude session, not the poller process — there's no shared module to import here.
+// This mirrors its parseStatus/lifecycleOf classification (poller-brain
+// skills/background-task/scripts/bg-task.mjs) rather than a raw /proc scan, which
+// false-negatives on interpreter/path variations and can't distinguish "stuck past TTL"
+// from "healthy" the way the status file's own started/ttl fields can.
+const ABANDON_GRACE_SEC = 60; // mirrors bg-task.mjs's ABANDON_GRACE_SEC
+function parseStatus(text) {
+    const kv = {};
+    for (const line of text.split('\n')) {
+        const i = line.indexOf('=');
+        if (i > 0)
+            kv[line.slice(0, i)] = line.slice(i + 1);
+    }
+    return kv;
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// Same four-way classification as bg-task.mjs's lifecycleOf, minus the tests-only
+// `alive` injection point (this module has its own dedicated tests instead).
+function lifecycleOf(kv, now) {
+    // Trust the runner's own claim, whatever it says (bg-task.mjs:139) — not just the two
+    // values the runner writes today (`finished`/`timed-out`, bg-task-runner.mjs:403).
+    // Mirroring the check itself, not just its current output, means the two
+    // implementations of this format can't quietly diverge if the runner ever starts
+    // writing a state value this list doesn't happen to enumerate — hardcoding a closed
+    // set here would silently fall through to the pid/TTL heuristics below instead.
+    if (kv.state)
+        return kv.state;
+    if (kv.runner_crashed)
+        return 'crashed';
+    if (Object.keys(kv).length === 0)
+        return 'unknown';
+    const pid = Number(kv.pid);
+    if (!Number.isInteger(pid) || pid <= 0 || !pidAlive(pid))
+        return 'abandoned';
+    const started = kv.started ? Date.parse(kv.started) : NaN;
+    const ttl = Number(String(kv.ttl ?? '').replace(/s$/, ''));
+    if (Number.isFinite(started) && Number.isFinite(ttl) && now - started > (ttl + ABANDON_GRACE_SEC) * 1000) {
+        return 'abandoned';
+    }
+    return 'running';
+}
+function bgTaskRoot() {
+    // Mirrors bg-task.mjs's taskRoot() default exactly, minus the per-channel
+    // namespace — the poller checks liveness across every channel it serves, not just
+    // one, so it walks the parent directory instead of joining a single channel ID.
+    return process.env['BG_TASK_ROOT'] || join(config.PERSISTENT_STORAGE_PATH || '/tmp', 'bg-tasks');
+}
+function listDirs(path) {
+    try {
+        return readdirSync(path, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name);
+    }
+    catch {
+        return [];
+    }
+}
+// Returns a "channel/taskId" label for the first live (running or unknown-state) task
+// found, or null if none. `unknown` (no status written yet) is treated as live —
+// deliberately conservative, per tv#317: a task a few milliseconds from its first
+// status line looks identical to an orphaned dir, and "skip this idle cycle" is cheap
+// while restarting mid-launch is not recoverable.
+export function findLiveBgTask(now = Date.now()) {
+    const root = bgTaskRoot();
+    for (const channel of listDirs(root)) {
+        const channelPath = join(root, channel);
+        for (const taskDir of listDirs(channelPath)) {
+            let statusText = '';
+            try {
+                statusText = readFileSync(join(channelPath, taskDir, 'status'), 'utf-8');
+            }
+            catch {
+                // No status file at all — same "unknown" treatment as an empty one below.
+            }
+            const state = lifecycleOf(parseStatus(statusText), now);
+            if (state === 'running' || state === 'unknown') {
+                return `${channel}/${taskDir}`;
+            }
+        }
+    }
+    return null;
+}
+// tv#317 "Startup reconciliation": bg-tasks don't survive a poller restart (their
+// runner is a child of the container that just went away), but a status file on a
+// persistent volume has no way to know that on its own. Without this, a task dir
+// whose runner never wrote a terminal line looks identical to a live one — worse,
+// after a restart the fresh container's own low PIDs can coincidentally collide with
+// a stale recorded `pid=`, so pidAlive() alone isn't reliable evidence either. Called
+// once at boot so every pre-restart dir is unambiguously stamped before the idle-restart
+// gate (or `--list`) ever reads it again.
+export function reconcileBgTasksOnBoot() {
+    const root = bgTaskRoot();
+    let stamped = 0;
+    for (const channel of listDirs(root)) {
+        const channelPath = join(root, channel);
+        for (const taskDir of listDirs(channelPath)) {
+            const statusPath = join(channelPath, taskDir, 'status');
+            let statusText;
+            try {
+                statusText = readFileSync(statusPath, 'utf-8');
+            }
+            catch {
+                continue; // no status file yet — nothing to stamp
+            }
+            const kv = parseStatus(statusText);
+            if (kv.state || kv.runner_crashed)
+                continue; // already terminal
+            try {
+                appendFileSync(statusPath, 'runner_crashed=container_restart\n');
+                stamped++;
+            }
+            catch (err) {
+                logger.warn(`[IdleRestart] Failed to stamp stale bg-task ${channel}/${taskDir}: ${err instanceof Error ? err.message : err}`);
+            }
+        }
+    }
+    if (stamped > 0) {
+        logger.info(`[IdleRestart] Reconciled ${stamped} bg-task dir(s) left over from before this boot`);
+    }
+}
+export function checkIdleRestart(deps = {}) {
+    const now = deps.now ?? Date.now();
+    const startTime = deps.startTime ?? processStartTime;
+    const activeProcessCount = deps.activeProcessCount ?? getActiveProcessCount;
+    const lastSessionEndTs = deps.lastSessionEndTs ?? getLastSessionEndTs;
+    const reclaimableBytesFn = deps.reclaimableBytes ?? readReclaimableFileBytes;
+    const liveBgTask = deps.liveBgTask ?? findLiveBgTask;
+    if (!config.IDLE_RESTART_ENABLED)
+        return false;
+    const uptimeMs = now - startTime;
+    if (uptimeMs < config.IDLE_RESTART_MIN_UPTIME_MS)
+        return false;
+    if (activeProcessCount() > 0)
+        return false;
+    const idleMs = now - lastSessionEndTs();
+    if (idleMs < config.IDLE_RESTART_IDLE_MS)
+        return false;
+    const reclaimableBytes = reclaimableBytesFn();
+    if (reclaimableBytes === null || reclaimableBytes < config.IDLE_RESTART_MEMORY_FILE_THRESHOLD_BYTES)
+        return false;
+    if (liveBgTask())
+        return false; // skip this cycle, recheck next time — never cut a bg-task short just to free memory sooner
+    // Re-verify the two liveness conditions right before signaling restart — a
+    // session or bg-task could have started in the time it took to reach this point.
+    if (activeProcessCount() > 0)
+        return false;
+    if (liveBgTask())
+        return false;
+    logger.info(`[IdleRestart] Idle ${Math.round(idleMs / 60000)}min, reclaimable page cache ` +
+        `${Math.round(reclaimableBytes / 1024 / 1024)}MB — restarting to let Railway reclaim it`);
+    emitEvent('poller.idle_restart', 'system', {
+        idleMs,
+        uptimeMs,
+        reclaimableBytes,
+    });
+    return true;
+}

package/dist/maintenance-cron.d.ts

@@ -21,6 +21,72 @@ export declare function getTrackedBrains(): ReadonlyMap<string, TrackedBrainInfo
  * @internal
  */
 export declare function __resetTrackedBrainsForTest(): void;
+/**
+ * Shape returned by GET /poller/brains (teamvibe.ai#127 Option B) — the
+ * fields registerBrain() needs to build a synthetic maintenance message,
+ * minus `lastRealMessageAt` (see seedTrackedBrains below for why that's
+ * deliberately not part of the bootstrap payload).
+ */
+export interface BootstrapBrainInfo {
+    brainId: string;
+    gitRepoUrl: string;
+    branch: string;
+    workspaceId: string;
+    botId: string;
+    botToken: string;
+    channelId: string;
+}
+/**
+ * Seed trackedBrains at startup from the backend's authoritative brain list
+ * (teamvibe.ai#127) so a "quiet" brain — one that hasn't received a real
+ * message since this poller process started — still gets included in the
+ * maintenance/heartbeat cron, instead of being silently invisible until a
+ * human happens to message it.
+ *
+ * Deliberately does NOT set `lastRealMessageAt` (left undefined). That
+ * field specifically means "we've seen a real message since our own last
+ * restart" — shouldSkipMaintenance (maintenance-activity.ts, #131) treats
+ * `undefined` as fail-open (never skip) for exactly this reason. Bootstrap
+ * seeding isn't a real message; claiming one occurred here would risk the
+ * opposite bug — a genuinely-quiet brain wrongly evaluated as "nothing new,
+ * skip" on its very first post-restart cron tick.
+ *
+ * Skips (rather than overwrites) any brainId already present in
+ * trackedBrains. This guard is load-bearing, not just defensive (DevGuru
+ * review, round 4): since round 3's critical-path detachment
+ * (brains-bootstrap.ts's `void (async () => {...})()` retry), the retry
+ * branch can finish AFTER startPoller() has already returned and real user
+ * messages have started arriving. That means a real registerBrain() call
+ * for a brain (which sets `lastRealMessageAt`) can race ahead of — and
+ * complete before — the detached bootstrap retry's seedTrackedBrains()
+ * call for that same brain. Without this skip, the late-arriving bootstrap
+ * seed would silently overwrite the real registration back to a fresh
+ * entry with `lastRealMessageAt: undefined`, losing real activity data
+ * (and, per the fail-open contract above, artificially reopening the
+ * skip-maintenance window for a brain that's actually been active).
+ *
+ * DOES also register each seeded brain for hourly metrics (see
+ * `registerBrainForMetrics` below) — DevGuru review caught that this
+ * module's original "metrics has its own disk-walk path" reasoning was
+ * wrong: `metrics/scheduler.ts`'s `registered` Map has exactly one
+ * production caller (`registerBrain()` below), with no disk-walk discovery
+ * of its own. Disk reads only happen in `collector.ts`, and only for a
+ * brain already present in that Map. Skipping the metrics seed here would
+ * reproduce the exact same restart-amnesia bug for metrics that this whole
+ * change exists to fix for maintenance: a quiet brain would get maintenance
+ * triggers again, but zero metrics until someone messages it.
+ *
+ * Deliberately does NOT replicate `registerBrain()`'s *immediate*
+ * collect+send side effect (the `if (isNew) { void (async () => ... })()`
+ * block below) — only the Map insert. Firing an immediate collect+send for
+ * every brain this poller owns, all at once, on every restart would be a
+ * fleet-wide burst; the existing hourly cron with its per-brain jitter
+ * (`collectAndSendAll`, `jitterMsFor`) already picks up newly-registered
+ * brains on its own schedule without a startup spike.
+ *
+ * Returns the number of brains actually seeded (for startup logging).
+ */
+export declare function seedTrackedBrains(brains: readonly BootstrapBrainInfo[]): number;
 /**
  * Register a brain from a real message so the maintenance cron knows about it.
  * Called from processMessage() after brain path is resolved.

package/dist/maintenance-cron.js

@@ -27,6 +27,75 @@ export function __resetTrackedBrainsForTest() {
     trackedBrains.clear();
 }
 let maintenanceJob = null;
+/**
+ * Seed trackedBrains at startup from the backend's authoritative brain list
+ * (teamvibe.ai#127) so a "quiet" brain — one that hasn't received a real
+ * message since this poller process started — still gets included in the
+ * maintenance/heartbeat cron, instead of being silently invisible until a
+ * human happens to message it.
+ *
+ * Deliberately does NOT set `lastRealMessageAt` (left undefined). That
+ * field specifically means "we've seen a real message since our own last
+ * restart" — shouldSkipMaintenance (maintenance-activity.ts, #131) treats
+ * `undefined` as fail-open (never skip) for exactly this reason. Bootstrap
+ * seeding isn't a real message; claiming one occurred here would risk the
+ * opposite bug — a genuinely-quiet brain wrongly evaluated as "nothing new,
+ * skip" on its very first post-restart cron tick.
+ *
+ * Skips (rather than overwrites) any brainId already present in
+ * trackedBrains. This guard is load-bearing, not just defensive (DevGuru
+ * review, round 4): since round 3's critical-path detachment
+ * (brains-bootstrap.ts's `void (async () => {...})()` retry), the retry
+ * branch can finish AFTER startPoller() has already returned and real user
+ * messages have started arriving. That means a real registerBrain() call
+ * for a brain (which sets `lastRealMessageAt`) can race ahead of — and
+ * complete before — the detached bootstrap retry's seedTrackedBrains()
+ * call for that same brain. Without this skip, the late-arriving bootstrap
+ * seed would silently overwrite the real registration back to a fresh
+ * entry with `lastRealMessageAt: undefined`, losing real activity data
+ * (and, per the fail-open contract above, artificially reopening the
+ * skip-maintenance window for a brain that's actually been active).
+ *
+ * DOES also register each seeded brain for hourly metrics (see
+ * `registerBrainForMetrics` below) — DevGuru review caught that this
+ * module's original "metrics has its own disk-walk path" reasoning was
+ * wrong: `metrics/scheduler.ts`'s `registered` Map has exactly one
+ * production caller (`registerBrain()` below), with no disk-walk discovery
+ * of its own. Disk reads only happen in `collector.ts`, and only for a
+ * brain already present in that Map. Skipping the metrics seed here would
+ * reproduce the exact same restart-amnesia bug for metrics that this whole
+ * change exists to fix for maintenance: a quiet brain would get maintenance
+ * triggers again, but zero metrics until someone messages it.
+ *
+ * Deliberately does NOT replicate `registerBrain()`'s *immediate*
+ * collect+send side effect (the `if (isNew) { void (async () => ... })()`
+ * block below) — only the Map insert. Firing an immediate collect+send for
+ * every brain this poller owns, all at once, on every restart would be a
+ * fleet-wide burst; the existing hourly cron with its per-brain jitter
+ * (`collectAndSendAll`, `jitterMsFor`) already picks up newly-registered
+ * brains on its own schedule without a startup spike.
+ *
+ * Returns the number of brains actually seeded (for startup logging).
+ */
+export function seedTrackedBrains(brains) {
+    let seeded = 0;
+    for (const b of brains) {
+        if (trackedBrains.has(b.brainId))
+            continue;
+        trackedBrains.set(b.brainId, {
+            brainId: b.brainId,
+            gitRepoUrl: b.gitRepoUrl,
+            branch: b.branch,
+            workspaceId: b.workspaceId,
+            botId: b.botId,
+            botToken: b.botToken,
+            channelId: b.channelId,
+        });
+        registerBrainForMetrics(b.brainId);
+        seeded++;
+    }
+    return seeded;
+}
 /**
  * Register a brain from a real message so the maintenance cron knows about it.
  * Called from processMessage() after brain path is resolved.

package/dist/poller.d.ts

@@ -29,8 +29,11 @@ export declare function isPollerInitiatedFailure(result: {
     exitCode: number | null;
     killedByPoller?: KilledByPoller;
 }): boolean;
+export declare function describeFailureReason(killedByPoller: KilledByPoller | undefined, exitCode: number | null): string;
+export declare const END_OF_TURN_NO_FURTHER_RESPONSE_SENTINEL = "NO_FURTHER_RESPONSE_NEEDED";
 export declare function endOfTurnFallbackText(hasSlackContext: boolean, result: Pick<SpawnResult, 'success' | 'sawSendMessageCall' | 'lastPlainTextContent'>): string | undefined;
 export declare function runInboxLoop(threadId: string, kbPath: string, queueMessage: TeamVibeQueueMessage, sessionLog: ReturnType<typeof logger.createSession>): Promise<void>;
+export declare function __setSleepForTest(impl: (ms: number) => Promise<void>): void;
 export declare function __setShuttingDownForTest(value: boolean): void;
 export declare function startPoller(): Promise<void>;
 export {};

package/dist/poller.js

@@ -10,6 +10,7 @@ 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, requeueMessage } from './inbox-manager.js';
@@ -17,6 +18,7 @@ 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';
@@ -163,6 +165,35 @@ export function isIntentionalKillExitCode(exitCode) {
 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
@@ -176,12 +207,27 @@ export function isPollerInitiatedFailure(result) {
 // 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();
-    return text ? text : undefined;
+    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)) {
@@ -328,6 +374,26 @@ export async function runInboxLoop(threadId, kbPath, queueMessage, sessionLog) {
                     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') {
@@ -349,33 +415,96 @@ export async function runInboxLoop(threadId, kbPath, queueMessage, sessionLog) {
             }
             else {
                 // Poller-initiated kill (timeout/idle/network/zombie/shutdown, via
-                // `killedByPoller`, or the legacy 143/137 exit-code fallback) → never
-                // counts as an application failure, so markFailed/backoff is skipped
-                // below regardless of reason. For timeout/idle/network/zombie this
-                // really does mean "retry immediately" — the `while (!shuttingDown)`
-                // condition above lets the loop come straight back around. For
-                // 'shutdown' specifically, `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. See isPollerInitiatedFailure() and the
-                // loop-condition comment above.
-                const isKilledSignal = isPollerInitiatedFailure({ exitCode: lastExitCode, killedByPoller: lastKilledByPoller });
-                if (!isKilledSignal) {
+                // `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 if (lastKilledByPoller === 'shutdown') {
+                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
@@ -387,9 +516,15 @@ export async function runInboxLoop(threadId, kbPath, queueMessage, sessionLog) {
                     // 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, which
-                    // is empty after a fresh poller start until some SQS activity for
-                    // this brain re-registers it (see teamvibe.ai#310) — hence the
+                    // 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.
                     //
@@ -581,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`);
@@ -651,8 +798,17 @@ 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;
@@ -749,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/package.json

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