@teamvibe/poller 0.6.2 → 0.7.1

package/dist/config.d.ts

@@ -15,6 +15,7 @@ declare const configSchema: z.ZodObject<{
     LOCK_RETRY_INTERVAL_MS: z.ZodDefault<z.ZodNumber>;
     IDLE_WATCHDOG_WARN_MS: z.ZodDefault<z.ZodNumber>;
     IDLE_WATCHDOG_KILL_MS: z.ZodDefault<z.ZodNumber>;
+    IDLE_WATCHDOG_COMPACTION_GRACE_MS: z.ZodDefault<z.ZodNumber>;
     NETWORK_ERROR_KILL_MS: z.ZodDefault<z.ZodNumber>;
     MAX_CONSECUTIVE_NET_FAILURES: z.ZodDefault<z.ZodNumber>;
     TEAMVIBE_DATA_DIR: z.ZodDefault<z.ZodString>;
@@ -28,6 +29,11 @@ declare const configSchema: z.ZodObject<{
     BASE_BRAIN_PATH: z.ZodDefault<z.ZodString>;
     BRAIN_AUTO_UPDATE: z.ZodEffects<z.ZodDefault<z.ZodString>, boolean, string | undefined>;
     BRAIN_UPDATE_COOLDOWN_MS: z.ZodDefault<z.ZodNumber>;
+    BRAIN_MAX_BLOB_BYTES: z.ZodDefault<z.ZodNumber>;
+    BRAIN_PUSH_RETRY_MAX: z.ZodDefault<z.ZodNumber>;
+    BRAIN_PUSH_RETRY_BACKOFF_MS: z.ZodDefault<z.ZodNumber>;
+    GIT_LOCK_MAX_AGE_MS: z.ZodDefault<z.ZodNumber>;
+    GIT_SUBMODULE_LOCK_MAX_AGE_MS: z.ZodDefault<z.ZodNumber>;
     POLLER_TZ: z.ZodOptional<z.ZodString>;
     MAINTENANCE_CRON: z.ZodDefault<z.ZodString>;
     MAINTENANCE_ENABLED: z.ZodEffects<z.ZodDefault<z.ZodString>, boolean, string | undefined>;
@@ -35,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;
@@ -47,6 +57,7 @@ declare const configSchema: z.ZodObject<{
     LOCK_RETRY_INTERVAL_MS: number;
     IDLE_WATCHDOG_WARN_MS: number;
     IDLE_WATCHDOG_KILL_MS: number;
+    IDLE_WATCHDOG_COMPACTION_GRACE_MS: number;
     NETWORK_ERROR_KILL_MS: number;
     MAX_CONSECUTIVE_NET_FAILURES: number;
     TEAMVIBE_DATA_DIR: string;
@@ -60,12 +71,21 @@ declare const configSchema: z.ZodObject<{
     BASE_BRAIN_PATH: string;
     BRAIN_AUTO_UPDATE: boolean;
     BRAIN_UPDATE_COOLDOWN_MS: number;
+    BRAIN_MAX_BLOB_BYTES: number;
+    BRAIN_PUSH_RETRY_MAX: number;
+    BRAIN_PUSH_RETRY_BACKOFF_MS: number;
+    GIT_LOCK_MAX_AGE_MS: number;
+    GIT_SUBMODULE_LOCK_MAX_AGE_MS: number;
     MAINTENANCE_CRON: string;
     MAINTENANCE_ENABLED: boolean;
     AUTO_UPDATE_POLICY: "patch" | "minor" | "off";
     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;
@@ -85,6 +105,7 @@ declare const configSchema: z.ZodObject<{
     LOCK_RETRY_INTERVAL_MS?: number | undefined;
     IDLE_WATCHDOG_WARN_MS?: number | undefined;
     IDLE_WATCHDOG_KILL_MS?: number | undefined;
+    IDLE_WATCHDOG_COMPACTION_GRACE_MS?: number | undefined;
     NETWORK_ERROR_KILL_MS?: number | undefined;
     MAX_CONSECUTIVE_NET_FAILURES?: number | undefined;
     TEAMVIBE_DATA_DIR?: string | undefined;
@@ -98,6 +119,11 @@ declare const configSchema: z.ZodObject<{
     BASE_BRAIN_PATH?: string | undefined;
     BRAIN_AUTO_UPDATE?: string | undefined;
     BRAIN_UPDATE_COOLDOWN_MS?: number | undefined;
+    BRAIN_MAX_BLOB_BYTES?: number | undefined;
+    BRAIN_PUSH_RETRY_MAX?: number | undefined;
+    BRAIN_PUSH_RETRY_BACKOFF_MS?: number | undefined;
+    GIT_LOCK_MAX_AGE_MS?: number | undefined;
+    GIT_SUBMODULE_LOCK_MAX_AGE_MS?: number | undefined;
     POLLER_TZ?: string | undefined;
     MAINTENANCE_CRON?: string | undefined;
     MAINTENANCE_ENABLED?: string | undefined;
@@ -105,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;
@@ -120,6 +150,7 @@ export declare const config: {
     LOCK_RETRY_INTERVAL_MS: number;
     IDLE_WATCHDOG_WARN_MS: number;
     IDLE_WATCHDOG_KILL_MS: number;
+    IDLE_WATCHDOG_COMPACTION_GRACE_MS: number;
     NETWORK_ERROR_KILL_MS: number;
     MAX_CONSECUTIVE_NET_FAILURES: number;
     TEAMVIBE_DATA_DIR: string;
@@ -133,12 +164,21 @@ export declare const config: {
     BASE_BRAIN_PATH: string;
     BRAIN_AUTO_UPDATE: boolean;
     BRAIN_UPDATE_COOLDOWN_MS: number;
+    BRAIN_MAX_BLOB_BYTES: number;
+    BRAIN_PUSH_RETRY_MAX: number;
+    BRAIN_PUSH_RETRY_BACKOFF_MS: number;
+    GIT_LOCK_MAX_AGE_MS: number;
+    GIT_SUBMODULE_LOCK_MAX_AGE_MS: number;
     MAINTENANCE_CRON: string;
     MAINTENANCE_ENABLED: boolean;
     AUTO_UPDATE_POLICY: "patch" | "minor" | "off";
     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

@@ -20,10 +20,11 @@ const configSchema = z.object({
     VISIBILITY_TIMEOUT_SECONDS: z.coerce.number().default(60),
     HEARTBEAT_INTERVAL_MS: z.coerce.number().default(40000), // 40 seconds
     CLAUDE_TIMEOUT_MS: z.coerce.number().default(3600000), // 60 minutes
-    STALE_LOCK_TIMEOUT_MS: z.coerce.number().default(900000), // 15 minutes (above idle watchdog kill time of 10 min)
+    STALE_LOCK_TIMEOUT_MS: z.coerce.number().default(1800000), // 30 minutes (comfortable margin above the ~15min worst-case compaction kill deadline below)
     LOCK_RETRY_INTERVAL_MS: z.coerce.number().default(30000), // 30 seconds
     IDLE_WATCHDOG_WARN_MS: z.coerce.number().default(300000), // 5 minutes
-    IDLE_WATCHDOG_KILL_MS: z.coerce.number().default(600000), // 10 minutes
+    IDLE_WATCHDOG_KILL_MS: z.coerce.number().default(600000), // 10 minutes (default; on a compact_boundary event, becomes max(this-from-silence-start, event-time + IDLE_WATCHDOG_COMPACTION_GRACE_MS) — tv#32)
+    IDLE_WATCHDOG_COMPACTION_GRACE_MS: z.coerce.number().default(300000), // 5 minutes — fixed grace from compact_boundary arrival, not a large speculative ceiling (compact_boundary only proves compaction STARTED, never that it finishes in bounded time)
     NETWORK_ERROR_KILL_MS: z.coerce.number().default(120000), // Per-session: kill stuck session after 2 min of network errors
     MAX_CONSECUTIVE_NET_FAILURES: z.coerce.number().default(5), // Poll loop: DNS flush at N, exit(1) at 2×N consecutive failures
     // Paths
@@ -43,6 +44,18 @@ const configSchema = z.object({
         .default('true')
         .transform((v) => v.toLowerCase() === 'true'),
     BRAIN_UPDATE_COOLDOWN_MS: z.coerce.number().default(300000), // 5 minutes
+    // Push guard: refuse to push unpushed commits that carry a blob over this size.
+    // Prevents a single oversized scratch file (e.g. agent .local/tmp/ writes) from
+    // getting permanently rejected by GitHub's pre-receive hook (tv#246).
+    BRAIN_MAX_BLOB_BYTES: z.coerce.number().default(50 * 1024 * 1024), // 50 MB
+    // Brain push-race retry (tv#232): fetch+rebase+retry on non-fast-forward push rejection
+    BRAIN_PUSH_RETRY_MAX: z.coerce.number().default(3),
+    BRAIN_PUSH_RETRY_BACKOFF_MS: z.coerce.number().default(500), // linear backoff: backoffMs * attempt
+    // Stale git lock cleanup (tv#76): orphaned locks from killed processes
+    // (e.g. the 2026-05-01 outage) block all future brain updates indefinitely
+    // unless removed. Distinct from STALE_LOCK_TIMEOUT_MS above (DDB session lock).
+    GIT_LOCK_MAX_AGE_MS: z.coerce.number().default(120000), // 2 minutes — .git/index.lock
+    GIT_SUBMODULE_LOCK_MAX_AGE_MS: z.coerce.number().default(300000), // 5 minutes — .git/modules/*/config.lock
     // Brain maintenance (cron-based)
     // POLLER_TZ: optional IANA timezone for MAINTENANCE_CRON.
     // When unset, croner uses the host system timezone (e.g. `Europe/Prague` on
@@ -63,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/cron-telemetry.d.ts

@@ -12,11 +12,14 @@
  */
 export declare function markMaintenanceJobFired(at?: number): void;
 export declare function markMaintenanceJobSuccess(at?: number): void;
+export declare function markMaintenanceJobSkipped(at?: number): void;
 export declare function markAutoUpdateJobFired(at?: number): void;
 export declare function markAutoUpdateJobSuccess(at?: number): void;
 export interface CronJobTimestamps {
     lastMaintenanceJobFiredAt: number | null;
     lastMaintenanceJobSuccessAt: number | null;
+    lastMaintenanceJobSkippedAt: number | null;
+    maintenanceSkippedCountLastRun: number;
     lastAutoUpdateJobFiredAt: number | null;
     lastAutoUpdateJobSuccessAt: number | null;
 }

package/dist/cron-telemetry.js

@@ -14,12 +14,24 @@ let lastMaintenanceJobFiredAt = null;
 let lastMaintenanceJobSuccessAt = null;
 let lastAutoUpdateJobFiredAt = null;
 let lastAutoUpdateJobSuccessAt = null;
+// teamvibeai/teamvibe.ai#131 — activity-based skip observability. Count
+// resets on each markMaintenanceJobFired() (i.e. once per cron run), so it
+// reflects "brains skipped in the most recently started run", not a
+// lifetime total. Without this, a `shouldSkipMaintenance` edge-case bug
+// that over-skips would be invisible short of manual per-brain digging.
+let lastMaintenanceJobSkippedAt = null;
+let maintenanceSkippedCountLastRun = 0;
 export function markMaintenanceJobFired(at = Date.now()) {
     lastMaintenanceJobFiredAt = at;
+    maintenanceSkippedCountLastRun = 0;
 }
 export function markMaintenanceJobSuccess(at = Date.now()) {
     lastMaintenanceJobSuccessAt = at;
 }
+export function markMaintenanceJobSkipped(at = Date.now()) {
+    lastMaintenanceJobSkippedAt = at;
+    maintenanceSkippedCountLastRun += 1;
+}
 export function markAutoUpdateJobFired(at = Date.now()) {
     lastAutoUpdateJobFiredAt = at;
 }
@@ -30,6 +42,8 @@ export function getCronJobTimestamps() {
     return {
         lastMaintenanceJobFiredAt,
         lastMaintenanceJobSuccessAt,
+        lastMaintenanceJobSkippedAt,
+        maintenanceSkippedCountLastRun,
         lastAutoUpdateJobFiredAt,
         lastAutoUpdateJobSuccessAt,
     };
@@ -41,6 +55,8 @@ export function getCronJobTimestamps() {
 export function __resetCronTelemetryForTest() {
     lastMaintenanceJobFiredAt = null;
     lastMaintenanceJobSuccessAt = null;
+    lastMaintenanceJobSkippedAt = null;
+    maintenanceSkippedCountLastRun = 0;
     lastAutoUpdateJobFiredAt = null;
     lastAutoUpdateJobSuccessAt = null;
 }

package/dist/event-queue.d.ts

@@ -1,5 +1,32 @@
 export type ErrorCategory = 'sqs' | 'brain' | 'auth' | 'session' | 'slack' | 'maintenance';
 export type ErrorSeverity = 'warn' | 'error';
+interface ErrorEvent {
+    eventType: 'poller.error';
+    channelId: string;
+    metadata: {
+        category: ErrorCategory;
+        severity: ErrorSeverity;
+        message: string;
+        count: number;
+        context?: Record<string, unknown>;
+    };
+    error: {
+        code: string;
+        message: string;
+    };
+    timestamp: string;
+}
+interface GenericEvent {
+    eventType: string;
+    channelId: string;
+    metadata?: Record<string, unknown>;
+    error?: {
+        code: string;
+        message: string;
+    };
+    timestamp: string;
+}
+type QueuedEvent = ErrorEvent | GenericEvent;
 export declare function emitEvent(eventType: string, channelId: string, metadata?: Record<string, unknown>): void;
 export declare function flush(): Promise<void>;
 export declare function startEventQueue(): void;
@@ -11,5 +38,8 @@ export declare function emitError(category: ErrorCategory, message: string, opti
 }): void;
 /** For testing: get current queue length */
 export declare function getQueueLength(): number;
+/** For testing: inspect queued events (e.g. assert on errorCode/severity) without flushing */
+export declare function peekQueue(): QueuedEvent[];
 /** For testing: clear the queue */
 export declare function clearQueue(): void;
+export {};

package/dist/event-queue.js

@@ -124,6 +124,10 @@ export function emitError(category, message, options) {
 export function getQueueLength() {
     return queue.length;
 }
+/** For testing: inspect queued events (e.g. assert on errorCode/severity) without flushing */
+export function peekQueue() {
+    return [...queue];
+}
 /** For testing: clear the queue */
 export function clearQueue() {
     queue = [];

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/inbox-manager.d.ts

@@ -20,6 +20,31 @@ export declare function markFailed(brainPath: string, threadId: string, filename
  * Delete a message file from processing/ (marks it as done).
  */
 export declare function markProcessed(brainPath: string, threadId: string, filename: string): void;
+/**
+ * Move a message from processing/ back to new/.
+ *
+ * Used specifically for a poller-initiated *shutdown* kill (teamvibe.ai#73,
+ * PR#308 round-5): pickNextMessage() above moves a file to processing/ as
+ * soon as it's picked up, not once it completes, so a message killed
+ * mid-flight by shutdown() is left sitting in processing/. The inbox
+ * watcher's wake condition (hasNewMessage(), inbox-watcher.ts) only scans
+ * new/ — a thread whose only pending message is in processing/ has nothing
+ * to start a fresh runInboxLoop() for it on the next boot, so it could sit
+ * stuck indefinitely. Moving it back to new/ here is what makes the
+ * shutdown-kill notice text ("your message is saved and will resume
+ * automatically", classify-failed-iteration.ts) literally true.
+ *
+ * Deliberately NOT used for timeout/idle/network/zombie kills — those retry
+ * immediately within the same still-running loop iteration (see
+ * isPollerInitiatedFailure() / the loop condition in poller.ts), so the
+ * existing processing/ crash-recovery branch in pickNextMessage() already
+ * covers them; requeueing those too would be redundant.
+ *
+ * Tolerant of the source file already being gone (e.g. a concurrent
+ * markProcessed/markFailed pass, or this being invoked twice for the same
+ * iteration) — that's a no-op, not an error.
+ */
+export declare function requeueMessage(brainPath: string, threadId: string, filename: string): void;
 /**
  * Check if there are unprocessed messages in new/ or processing/.
  */

package/dist/inbox-manager.js

@@ -93,6 +93,53 @@ export function markProcessed(brainPath, threadId, filename) {
         logger.warn(`[Inbox] Failed to delete ${filename}: ${error}`);
     }
 }
+/**
+ * Move a message from processing/ back to new/.
+ *
+ * Used specifically for a poller-initiated *shutdown* kill (teamvibe.ai#73,
+ * PR#308 round-5): pickNextMessage() above moves a file to processing/ as
+ * soon as it's picked up, not once it completes, so a message killed
+ * mid-flight by shutdown() is left sitting in processing/. The inbox
+ * watcher's wake condition (hasNewMessage(), inbox-watcher.ts) only scans
+ * new/ — a thread whose only pending message is in processing/ has nothing
+ * to start a fresh runInboxLoop() for it on the next boot, so it could sit
+ * stuck indefinitely. Moving it back to new/ here is what makes the
+ * shutdown-kill notice text ("your message is saved and will resume
+ * automatically", classify-failed-iteration.ts) literally true.
+ *
+ * Deliberately NOT used for timeout/idle/network/zombie kills — those retry
+ * immediately within the same still-running loop iteration (see
+ * isPollerInitiatedFailure() / the loop condition in poller.ts), so the
+ * existing processing/ crash-recovery branch in pickNextMessage() already
+ * covers them; requeueing those too would be redundant.
+ *
+ * Tolerant of the source file already being gone (e.g. a concurrent
+ * markProcessed/markFailed pass, or this being invoked twice for the same
+ * iteration) — that's a no-op, not an error.
+ */
+export function requeueMessage(brainPath, threadId, filename) {
+    const inbox = getInboxPath(brainPath, threadId);
+    const srcPath = join(inbox, PROCESSING_DIR, filename);
+    const newDir = join(inbox, NEW_DIR);
+    mkdirSync(newDir, { recursive: true });
+    const dstPath = join(newDir, filename);
+    try {
+        if (existsSync(srcPath)) {
+            renameSync(srcPath, dstPath);
+            logger.info(`[Inbox] Requeued shutdown-killed message to new/: ${filename}`);
+        }
+        else {
+            logger.info(`[Inbox] Requeue skipped, ${filename} already gone from processing/`);
+        }
+    }
+    catch (error) {
+        // e.g. ENOENT from a race between the existsSync check above and the
+        // rename itself — same tolerance as the existsSync guard, just covering
+        // the narrower window. Log and continue; never let a requeue failure
+        // crash the shutdown path.
+        logger.warn(`[Inbox] Failed to requeue ${filename} to new/: ${error}`);
+    }
+}
 /**
  * Check if there are unprocessed messages in new/ or processing/.
  */

package/dist/maintenance-activity.d.ts

@@ -0,0 +1,18 @@
+export interface ActivityCheckDeps {
+    statFn: (path: string) => Promise<{
+        mtimeMs: number;
+    }>;
+}
+/**
+ * Poller-side half of teamvibe.ai#131: skip the nightly maintenance trigger
+ * for a brain that has had zero real (non-maintenance-sourced) activity
+ * since its last maintenance run, so a quiet brain doesn't pay for a Claude
+ * spawn just to no-op inside the session's own time-debounce guard.
+ *
+ * `lastRealMessageAt` is set by registerBrain() (maintenance-cron.ts) on
+ * every non-maintenance message. It is undefined when the poller hasn't
+ * seen one since its own last restart (trackedBrains is in-memory, #127) —
+ * in that case we fail open (never skip) rather than risk starving a brain
+ * of maintenance because of a poller restart, not actual inactivity.
+ */
+export declare function shouldSkipMaintenance(brainsPath: string, brainId: string, lastRealMessageAt: number | undefined, deps?: ActivityCheckDeps): Promise<boolean>;

package/dist/maintenance-activity.js

@@ -0,0 +1,28 @@
+import { stat } from 'fs/promises';
+import { join } from 'path';
+const defaultDeps = { statFn: stat };
+/**
+ * Poller-side half of teamvibe.ai#131: skip the nightly maintenance trigger
+ * for a brain that has had zero real (non-maintenance-sourced) activity
+ * since its last maintenance run, so a quiet brain doesn't pay for a Claude
+ * spawn just to no-op inside the session's own time-debounce guard.
+ *
+ * `lastRealMessageAt` is set by registerBrain() (maintenance-cron.ts) on
+ * every non-maintenance message. It is undefined when the poller hasn't
+ * seen one since its own last restart (trackedBrains is in-memory, #127) —
+ * in that case we fail open (never skip) rather than risk starving a brain
+ * of maintenance because of a poller restart, not actual inactivity.
+ */
+export async function shouldSkipMaintenance(brainsPath, brainId, lastRealMessageAt, deps = defaultDeps) {
+    if (lastRealMessageAt === undefined)
+        return false;
+    try {
+        const guardPath = join(brainsPath, brainId, 'memory/.last_consolidation');
+        const s = await deps.statFn(guardPath);
+        return lastRealMessageAt < s.mtimeMs;
+    }
+    catch {
+        // No guard file yet (brand-new brain, never consolidated) — never skip.
+        return false;
+    }
+}