@teamvibe/poller 0.6.0 → 0.6.2

package/dist/claude-spawner.js

@@ -631,6 +631,9 @@ async function runClaudeCode(msg, sessionLog, cwd, sessionId, isFirstMessage = t
                     context: { channelId: msg.teamvibe.channelId, threadId: msg.thread_id },
                     channelId: msg.teamvibe.channelId,
                 });
+                // Surface a visible status so the user isn't left with a stale/generic
+                // indicator during long silent stretches (e.g. context compaction).
+                typingIndicator?.updateStatus('Still working on a long response...');
                 idleWarned = true;
             }
         }, 30000); // Check every 30 seconds

package/dist/config.d.ts

@@ -33,6 +33,8 @@ declare const configSchema: z.ZodObject<{
     MAINTENANCE_ENABLED: z.ZodEffects<z.ZodDefault<z.ZodString>, boolean, string | undefined>;
     AUTO_UPDATE_POLICY: z.ZodDefault<z.ZodEnum<["patch", "minor", "off"]>>;
     AUTO_UPDATE_SCHEDULE: z.ZodDefault<z.ZodString>;
+    INBOX_WATCH_FALLBACK_INTERVAL_MS: z.ZodDefault<z.ZodNumber>;
+    INBOX_WATCH_DEBOUNCE_MS: z.ZodDefault<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     AWS_REGION: string;
     TEAMVIBE_API_URL: string;
@@ -62,6 +64,8 @@ declare const configSchema: z.ZodObject<{
     MAINTENANCE_ENABLED: boolean;
     AUTO_UPDATE_POLICY: "patch" | "minor" | "off";
     AUTO_UPDATE_SCHEDULE: string;
+    INBOX_WATCH_FALLBACK_INTERVAL_MS: number;
+    INBOX_WATCH_DEBOUNCE_MS: number;
     SQS_QUEUE_URL?: string | undefined;
     SESSIONS_TABLE?: string | undefined;
     TEAMVIBE_POLLER_TOKEN?: string | undefined;
@@ -99,6 +103,8 @@ declare const configSchema: z.ZodObject<{
     MAINTENANCE_ENABLED?: string | undefined;
     AUTO_UPDATE_POLICY?: "patch" | "minor" | "off" | undefined;
     AUTO_UPDATE_SCHEDULE?: string | undefined;
+    INBOX_WATCH_FALLBACK_INTERVAL_MS?: number | undefined;
+    INBOX_WATCH_DEBOUNCE_MS?: number | undefined;
 }>;
 export type Config = z.infer<typeof configSchema>;
 export declare function loadConfig(): Config;
@@ -131,6 +137,8 @@ export declare const config: {
     MAINTENANCE_ENABLED: boolean;
     AUTO_UPDATE_POLICY: "patch" | "minor" | "off";
     AUTO_UPDATE_SCHEDULE: string;
+    INBOX_WATCH_FALLBACK_INTERVAL_MS: number;
+    INBOX_WATCH_DEBOUNCE_MS: number;
     SQS_QUEUE_URL?: string | undefined;
     SESSIONS_TABLE?: string | undefined;
     TEAMVIBE_POLLER_TOKEN?: string | undefined;

package/dist/config.js

@@ -55,6 +55,14 @@ const configSchema = z.object({
     // Auto-update settings
     AUTO_UPDATE_POLICY: z.enum(['patch', 'minor', 'off']).default('patch'),
     AUTO_UPDATE_SCHEDULE: z.string().default('03:00'), // HH:MM in UTC — daily check time
+    // Inbox watcher (teamvibe.ai#242): fs.watch()'s .inbox/ per tracked brain so a
+    // file dropped while no session is running (e.g. a background-task result)
+    // still starts one, instead of waiting inert for the next SQS message.
+    // The fallback sweep re-scans on an interval regardless of fs events — it
+    // catches missed/coalesced events, picks up brains whose .inbox/ didn't
+    // 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
 });
 export function loadConfig() {
     const result = configSchema.safeParse(process.env);

package/dist/inbox-watcher.d.ts

@@ -0,0 +1,67 @@
+import { SessionLogger } from './logger.js';
+import { type TrackedBrainInfo } from './maintenance-cron.js';
+import type { TeamVibeQueueMessage } from './types.js';
+/**
+ * Everything checkInboxForNewSessions/pruneEmptyInboxDirs read from other
+ * modules, gathered behind one interface so tests can pass plain fakes
+ * instead of mocking poller.js / maintenance-cron.js / claude-spawner.js
+ * (those pull in AWS clients and process-spawning at import time, and Bun's
+ * mock.module() is process-global — it would leak into every other test
+ * file in the run).
+ */
+export interface InboxWatcherDeps {
+    brainsPath: string;
+    getTrackedBrains: () => ReadonlyMap<string, TrackedBrainInfo>;
+    isAtCapacity: () => boolean;
+    isInboxLoopActive: (threadId: string) => boolean;
+    runInboxLoop: (threadId: string, kbPath: string, queueMessage: TeamVibeQueueMessage, sessionLog: SessionLogger) => Promise<void>;
+    rmThreadDir: (path: string) => void;
+}
+/**
+ * threadId is always `<botId>:<channel>:<threadTs>` for slack-originated
+ * threads (see modules-teamvibe/hooks/slack-events.ts). Synthetic threadIds
+ * used elsewhere (`maintenance_<brainId>_<ts>`, and
+ * `scheduled:<scheduleId>:<ts>` from
+ * modules-teamvibe/src/functions/scheduler.ts:86) never sit idle waiting on
+ * a background-task drop, so they're skipped rather than guessed at.
+ * `scheduled:*:*` has the same 3-colon-segment shape as a real Slack
+ * threadId, so it's rejected explicitly rather than by segment count alone
+ * — otherwise a leftover unprocessed file in a stale scheduled-session inbox
+ * dir would make this parse `scheduleId` as a Slack channel.
+ */
+export declare function parseSlackThreadId(threadId: string): {
+    channel: string;
+    threadTs: string;
+} | null;
+export declare function listThreadDirs(inboxRoot: string): string[];
+export declare function hasNewMessage(inboxRoot: string, threadId: string): boolean;
+/**
+ * Scan every tracked brain's .inbox/ for a thread that has a new message but
+ * no active runInboxLoop, and start one. This is the only config-only path
+ * that can wake a fully idle session (teamvibe.ai#242) — a file dropped into
+ * .inbox/ by e.g. a background task otherwise sits inert until the next SQS
+ * message for that thread, which may never come.
+ */
+export declare function checkInboxForNewSessions(deps?: InboxWatcherDeps): void;
+export declare function isThreadDirEmpty(inboxRoot: string, threadId: string): boolean;
+/**
+ * Remove thread dirs whose new/processing/failed subdirs are all empty (or
+ * absent) and which have no active loop right now. Safe because
+ * writeMessage() always recreates the directory tree via a recursive
+ * mkdirSync before writing (inbox-manager.ts) — deleting an empty thread dir
+ * loses nothing, and a later message for the same thread just recreates it.
+ * Bounds the number of directories fs.watch has to track, which would
+ * otherwise only grow: thread dirs are never pruned anywhere else once
+ * created.
+ */
+export declare function pruneEmptyInboxDirs(deps?: InboxWatcherDeps): void;
+/**
+ * Starts the fs.watch-driven wake path plus a sparse fallback sweep
+ * (default 5min) that (a) catches anything a missed/coalesced fs event
+ * dropped, (b) picks up brains whose .inbox/ didn't exist at watcher
+ * startup, and (c) prunes empty thread dirs. fs.watch gives near-instant
+ * wake; the fallback exists because relying on it exclusively would be a
+ * silent single point of failure with no observable "did it fire" signal.
+ */
+export declare function startInboxWatcher(deps?: InboxWatcherDeps): void;
+export declare function stopInboxWatcher(): void;

package/dist/inbox-watcher.js

@@ -0,0 +1,262 @@
+import { existsSync, readdirSync, rmSync, watch as fsWatch } from 'fs';
+import { join } from 'path';
+import { config } from './config.js';
+import { logger } from './logger.js';
+import { isAtCapacity } from './claude-spawner.js';
+import { getTrackedBrains } from './maintenance-cron.js';
+import { runInboxLoop, isInboxLoopActive } from './poller.js';
+const INBOX_SUBDIRS = ['new', 'processing', 'failed'];
+let brainWatchers = new Map();
+let fallbackInterval = null;
+let debounceTimer = null;
+function defaultDeps() {
+    return {
+        brainsPath: config.BRAINS_PATH,
+        getTrackedBrains,
+        isAtCapacity,
+        isInboxLoopActive,
+        runInboxLoop,
+        rmThreadDir: (path) => rmSync(path, { recursive: true }),
+    };
+}
+/**
+ * threadId is always `<botId>:<channel>:<threadTs>` for slack-originated
+ * threads (see modules-teamvibe/hooks/slack-events.ts). Synthetic threadIds
+ * used elsewhere (`maintenance_<brainId>_<ts>`, and
+ * `scheduled:<scheduleId>:<ts>` from
+ * modules-teamvibe/src/functions/scheduler.ts:86) never sit idle waiting on
+ * a background-task drop, so they're skipped rather than guessed at.
+ * `scheduled:*:*` has the same 3-colon-segment shape as a real Slack
+ * threadId, so it's rejected explicitly rather than by segment count alone
+ * — otherwise a leftover unprocessed file in a stale scheduled-session inbox
+ * dir would make this parse `scheduleId` as a Slack channel.
+ */
+export function parseSlackThreadId(threadId) {
+    const parts = threadId.split(':');
+    if (parts.length !== 3)
+        return null;
+    const [botId, channel, threadTs] = parts;
+    if (botId === 'scheduled')
+        return null;
+    if (!channel || !threadTs)
+        return null;
+    return { channel, threadTs };
+}
+function buildSyntheticMessage(info, threadId, parsed) {
+    return {
+        id: `inbox_watch_${threadId}`,
+        source: 'slack',
+        thread_id: threadId,
+        sender: { id: 'system', name: 'Background Task' },
+        text: '',
+        attachments: [],
+        response_context: {
+            slack: {
+                channel: parsed.channel,
+                thread_ts: parsed.threadTs,
+                message_ts: parsed.threadTs,
+            },
+        },
+        type: 'message',
+        teamvibe: {
+            workspaceId: info.workspaceId,
+            botId: info.botId,
+            botToken: info.botToken,
+            channelId: info.channelId,
+            brain: {
+                brainId: info.brainId,
+                gitRepoUrl: info.gitRepoUrl,
+                branch: info.branch,
+            },
+        },
+    };
+}
+export function listThreadDirs(inboxRoot) {
+    try {
+        return readdirSync(inboxRoot, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name);
+    }
+    catch {
+        return [];
+    }
+}
+export function hasNewMessage(inboxRoot, threadId) {
+    const newDir = join(inboxRoot, threadId, 'new');
+    try {
+        return existsSync(newDir) && readdirSync(newDir).some((f) => f.endsWith('.txt'));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Scan every tracked brain's .inbox/ for a thread that has a new message but
+ * no active runInboxLoop, and start one. This is the only config-only path
+ * that can wake a fully idle session (teamvibe.ai#242) — a file dropped into
+ * .inbox/ by e.g. a background task otherwise sits inert until the next SQS
+ * message for that thread, which may never come.
+ */
+export function checkInboxForNewSessions(deps = defaultDeps()) {
+    for (const [, info] of deps.getTrackedBrains()) {
+        if (deps.isAtCapacity()) {
+            logger.debug('[InboxWatcher] At capacity, pausing scan until next tick');
+            return;
+        }
+        const brainPath = join(deps.brainsPath, info.brainId);
+        const inboxRoot = join(brainPath, '.inbox');
+        if (!existsSync(inboxRoot))
+            continue;
+        for (const threadId of listThreadDirs(inboxRoot)) {
+            if (deps.isInboxLoopActive(threadId))
+                continue;
+            if (!hasNewMessage(inboxRoot, threadId))
+                continue;
+            const parsed = parseSlackThreadId(threadId);
+            if (!parsed) {
+                logger.debug(`[InboxWatcher] Skipping ${threadId}: not a slack-shaped threadId`);
+                continue;
+            }
+            logger.info(`[InboxWatcher] New message for idle thread ${threadId}, starting session`);
+            const sessionLog = logger.createSession(`iw_${Math.random().toString(36).slice(2, 10)}`);
+            const syntheticMessage = buildSyntheticMessage(info, threadId, parsed);
+            deps.runInboxLoop(threadId, brainPath, syntheticMessage, sessionLog).catch((error) => {
+                logger.error(`[InboxWatcher] runInboxLoop failed for ${threadId}: ${error instanceof Error ? error.message : error}`);
+            });
+        }
+    }
+}
+export function isThreadDirEmpty(inboxRoot, threadId) {
+    for (const sub of INBOX_SUBDIRS) {
+        const subDir = join(inboxRoot, threadId, sub);
+        if (!existsSync(subDir))
+            continue;
+        try {
+            if (readdirSync(subDir).length > 0)
+                return false;
+        }
+        catch {
+            return false; // unreadable — leave it alone rather than guess
+        }
+    }
+    return true;
+}
+/**
+ * Remove thread dirs whose new/processing/failed subdirs are all empty (or
+ * absent) and which have no active loop right now. Safe because
+ * writeMessage() always recreates the directory tree via a recursive
+ * mkdirSync before writing (inbox-manager.ts) — deleting an empty thread dir
+ * loses nothing, and a later message for the same thread just recreates it.
+ * Bounds the number of directories fs.watch has to track, which would
+ * otherwise only grow: thread dirs are never pruned anywhere else once
+ * created.
+ */
+export function pruneEmptyInboxDirs(deps = defaultDeps()) {
+    for (const [, info] of deps.getTrackedBrains()) {
+        const inboxRoot = join(deps.brainsPath, info.brainId, '.inbox');
+        if (!existsSync(inboxRoot))
+            continue;
+        for (const threadId of listThreadDirs(inboxRoot)) {
+            if (deps.isInboxLoopActive(threadId))
+                continue;
+            if (!isThreadDirEmpty(inboxRoot, threadId))
+                continue;
+            const threadDir = join(inboxRoot, threadId);
+            try {
+                deps.rmThreadDir(threadDir);
+                logger.debug(`[InboxWatcher] Pruned empty inbox dir: ${threadId}`);
+            }
+            catch (error) {
+                // Most likely a message landed between the emptiness check and the
+                // remove (rmSync without `force` throws on a dir that's non-empty
+                // by then) — leave it for the next sweep rather than force-delete.
+                logger.debug(`[InboxWatcher] Skipped pruning ${threadId}: ${error instanceof Error ? error.message : error}`);
+            }
+        }
+    }
+}
+function scheduleCheck(deps) {
+    if (debounceTimer)
+        return;
+    debounceTimer = setTimeout(() => {
+        debounceTimer = null;
+        checkInboxForNewSessions(deps);
+    }, config.INBOX_WATCH_DEBOUNCE_MS);
+}
+/**
+ * Ensure every currently-tracked brain that already has a .inbox/ dir has a
+ * live fs.watch on it. Called on startup and on every fallback sweep, so a
+ * brain seen for the first time (or one whose .inbox/ didn't exist yet at
+ * watcher-startup — a brand-new brain's first-ever message always arrives
+ * via the normal SQS path, so this isn't on the critical path) gets covered
+ * within one fallback interval.
+ *
+ * Watching `<brain>/.inbox` specifically — not the whole brain checkout —
+ * keeps the watch count proportional to inbox activity: the brain repo
+ * itself (skills/, memory/, .git/) can have orders of magnitude more
+ * directories than its inbox ever will, and a single fs.watch holds one
+ * inotify watch descriptor per directory in the watched tree (verified:
+ * 801 watch descriptors for 200 nested thread dirs, all on one shared fd).
+ */
+function syncBrainWatchers(deps) {
+    const seen = new Set();
+    for (const [, info] of deps.getTrackedBrains()) {
+        seen.add(info.brainId);
+        if (brainWatchers.has(info.brainId))
+            continue;
+        const inboxRoot = join(deps.brainsPath, info.brainId, '.inbox');
+        if (!existsSync(inboxRoot))
+            continue;
+        try {
+            const watcher = fsWatch(inboxRoot, { recursive: true }, () => scheduleCheck(deps));
+            watcher.on('error', (error) => {
+                logger.warn(`[InboxWatcher] Watch error for brain ${info.brainId}, dropping watcher: ${error.message}`);
+                brainWatchers.delete(info.brainId);
+            });
+            brainWatchers.set(info.brainId, watcher);
+            logger.debug(`[InboxWatcher] Watching ${inboxRoot}`);
+        }
+        catch (error) {
+            logger.debug(`[InboxWatcher] Could not watch ${inboxRoot} (${error instanceof Error ? error.message : error}), relying on fallback poll`);
+        }
+    }
+    for (const brainId of brainWatchers.keys()) {
+        if (!seen.has(brainId)) {
+            brainWatchers.get(brainId)?.close();
+            brainWatchers.delete(brainId);
+        }
+    }
+}
+/**
+ * Starts the fs.watch-driven wake path plus a sparse fallback sweep
+ * (default 5min) that (a) catches anything a missed/coalesced fs event
+ * dropped, (b) picks up brains whose .inbox/ didn't exist at watcher
+ * startup, and (c) prunes empty thread dirs. fs.watch gives near-instant
+ * wake; the fallback exists because relying on it exclusively would be a
+ * silent single point of failure with no observable "did it fire" signal.
+ */
+export function startInboxWatcher(deps = defaultDeps()) {
+    if (fallbackInterval)
+        return;
+    syncBrainWatchers(deps);
+    const fallbackMs = config.INBOX_WATCH_FALLBACK_INTERVAL_MS;
+    logger.info(`[InboxWatcher] Started (fs.watch on ${brainWatchers.size} brain inbox dir(s), fallback sweep every ${fallbackMs}ms)`);
+    fallbackInterval = setInterval(() => {
+        syncBrainWatchers(deps);
+        checkInboxForNewSessions(deps);
+        pruneEmptyInboxDirs(deps);
+    }, fallbackMs);
+}
+export function stopInboxWatcher() {
+    if (fallbackInterval) {
+        clearInterval(fallbackInterval);
+        fallbackInterval = null;
+    }
+    if (debounceTimer) {
+        clearTimeout(debounceTimer);
+        debounceTimer = null;
+    }
+    for (const watcher of brainWatchers.values())
+        watcher.close();
+    brainWatchers.clear();
+}

package/dist/maintenance-cron.d.ts

@@ -1,4 +1,19 @@
 import type { TeamVibeQueueMessage } from './types.js';
+export interface TrackedBrainInfo {
+    brainId: string;
+    gitRepoUrl: string;
+    branch: string;
+    workspaceId: string;
+    botId: string;
+    botToken: string;
+    channelId: string;
+}
+/**
+ * Read-only view of brains seen so far (via registerBrain). Used by the inbox
+ * watcher (teamvibe.ai#242) to know which brain paths to scan and which
+ * workspace/bot credentials to use when starting a session for an idle thread.
+ */
+export declare function getTrackedBrains(): ReadonlyMap<string, TrackedBrainInfo>;
 /**
  * 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

@@ -9,6 +9,14 @@ import { sendMetrics } from './metrics/sender.js';
 import { markMaintenanceJobFired, markMaintenanceJobSuccess, } from './cron-telemetry.js';
 import { join } from 'path';
 const trackedBrains = new Map();
+/**
+ * Read-only view of brains seen so far (via registerBrain). Used by the inbox
+ * watcher (teamvibe.ai#242) to know which brain paths to scan and which
+ * workspace/bot credentials to use when starting a session for an idle thread.
+ */
+export function getTrackedBrains() {
+    return trackedBrains;
+}
 let maintenanceJob = null;
 /**
  * Register a brain from a real message so the maintenance cron knows about it.

package/dist/maintenance-reporter.js

@@ -1,16 +1,72 @@
-import { readdir, readFile, unlink, writeFile } from 'fs/promises';
+import { readdir, readFile, unlink, writeFile, mkdir, rename, } from 'fs/promises';
 import { join } from 'path';
 import { execFile } from 'child_process';
 import { promisify } from 'util';
 import { config, POLLER_VERSION } from './config.js';
 import { logger } from './logger.js';
 import { emitError } from './event-queue.js';
-import { getBaseBrainCommitSha, getBaseBrainAgeHours } from './base-brain-metadata.js';
+import { getBaseBrainCommitSha, getBaseBrainAgeHours, } from './base-brain-metadata.js';
 const execFileAsync = promisify(execFile);
 const OPERATION_TO_EVENT_TYPE = {
     consolidation: 'maintenance.consolidation',
     reflection: 'maintenance.reflection',
 };
+// teamvibe.ai#222 — malformed reports used to error forever because nothing
+// ever removed them from the brain repo. They're quarantined instead of
+// deleted outright so the raw payload survives for forensic inspection
+// (why did the generator emit invalid JSON?), then purged after a retention
+// window so the quarantine folder doesn't grow unbounded.
+const QUARANTINE_DIR_NAME = '.quarantine';
+const QUARANTINE_RETENTION_DAYS = 30;
+const QUARANTINE_NAME_RE = /^(\d{4}-\d{2}-\d{2})__(.+)$/;
+function todayIso() {
+    return new Date().toISOString().slice(0, 10);
+}
+// Date is parsed from the quarantine filename prefix, never from fs mtime —
+// brains are re-checked-out from git per session, so mtime reflects the last
+// checkout, not when the file was actually quarantined.
+function daysSince(isoDate) {
+    const from = new Date(`${isoDate}T00:00:00Z`).getTime();
+    const now = new Date(`${todayIso()}T00:00:00Z`).getTime();
+    return Math.floor((now - from) / (24 * 60 * 60 * 1000));
+}
+async function quarantineFile(brainPath, file) {
+    const quarantineDir = join(brainPath, 'reports', QUARANTINE_DIR_NAME);
+    await mkdir(quarantineDir, { recursive: true });
+    const quarantineName = `${todayIso()}__${file}`;
+    await rename(join(brainPath, 'reports', file), join(quarantineDir, quarantineName));
+    return quarantineName;
+}
+/**
+ * Sweep reports/.quarantine/ for entries past the retention window and
+ * remove them from disk. Runs unconditionally (independent of whether
+ * there are any new reports/*.json to process this session) so cleanup
+ * doesn't stall on brains with a low reporting cadence.
+ */
+async function sweepExpiredQuarantine(brainPath) {
+    const quarantineDir = join(brainPath, 'reports', QUARANTINE_DIR_NAME);
+    const entries = await readdir(quarantineDir).catch(() => []);
+    const expired = [];
+    for (const entry of entries) {
+        const match = entry.match(QUARANTINE_NAME_RE);
+        const quarantinedOn = match?.[1];
+        if (!quarantinedOn)
+            continue; // unexpected name — leave alone rather than guess an age
+        if (daysSince(quarantinedOn) >= QUARANTINE_RETENTION_DAYS) {
+            try {
+                await unlink(join(quarantineDir, entry));
+                expired.push(`reports/${QUARANTINE_DIR_NAME}/${entry}`);
+            }
+            catch (err) {
+                // Don't report this entry as expired if the unlink didn't actually
+                // happen — otherwise git rm --cached untracks it while it's still
+                // sitting on disk, and future sweeps can't see it's already "gone".
+                logger.warn(`[MaintenanceReporter] Failed to purge expired quarantine entry ${entry}: ${err instanceof Error ? err.message : err}`);
+            }
+        }
+    }
+    return expired;
+}
 /**
  * Scan for JSON maintenance reports in the brain's reports/ directory
  * and POST each to the /events endpoint. Fire-and-forget — never throws.
@@ -21,109 +77,158 @@ export async function postMaintenanceReports(brainPath, channelId) {
     }
     const reportsDir = join(brainPath, 'reports');
     try {
+        const expiredQuarantineFiles = await sweepExpiredQuarantine(brainPath);
         const files = await readdir(reportsDir).catch(() => []);
         const jsonFiles = files.filter((f) => f.endsWith('.json'));
-        if (jsonFiles.length === 0)
-            return;
-        logger.info(`[MaintenanceReporter] Found ${jsonFiles.length} JSON report(s) in ${reportsDir}`);
-        // Fleet visibility fields — sampled once per run. See teamvibe.ai#129.
-        const [baseBrainCommitSha, baseBrainAgeHours] = await Promise.all([
-            getBaseBrainCommitSha(config.BASE_BRAIN_PATH),
-            getBaseBrainAgeHours(config.BASE_BRAIN_PATH),
-        ]);
         const postedFiles = [];
         const removedFiles = [];
+        const quarantinedFrom = [];
+        const quarantinedTo = [];
         let consolidationGuardTouched = false;
-        for (const file of jsonFiles) {
-            const filePath = join(reportsDir, file);
-            try {
-                const content = await readFile(filePath, 'utf-8');
-                const report = JSON.parse(content);
-                if (!report.operationType) {
-                    logger.warn(`[MaintenanceReporter] Removing invalid report ${file}: missing operationType`);
-                    emitError('maintenance', `Removing invalid report ${file}: missing operationType`, { severity: 'warn' });
-                    await unlink(filePath).catch(() => { });
-                    removedFiles.push(`reports/${file}`);
-                    continue;
-                }
-                const eventType = OPERATION_TO_EVENT_TYPE[report.operationType];
-                if (!eventType) {
-                    logger.warn(`[MaintenanceReporter] Removing report ${file}: unknown operationType "${report.operationType}"`);
-                    emitError('maintenance', `Removing report ${file}: unknown operationType "${report.operationType}"`, { severity: 'warn' });
-                    await unlink(filePath).catch(() => { });
-                    removedFiles.push(`reports/${file}`);
-                    continue;
-                }
-                const payload = {
-                    eventType,
-                    channelId,
-                    pollerVersion: POLLER_VERSION,
-                    baseBrainCommitSha,
-                    baseBrainAgeHours,
-                    metadata: report,
-                };
-                const response = await fetch(`${config.TEAMVIBE_API_URL}/events`, {
-                    method: 'POST',
-                    headers: {
-                        'Content-Type': 'application/json',
-                        Authorization: `Bearer ${config.TEAMVIBE_POLLER_TOKEN}`,
-                    },
-                    body: JSON.stringify(payload),
-                });
-                if (response.ok) {
-                    logger.info(`[MaintenanceReporter] Posted ${file} as ${eventType}`);
-                    await unlink(filePath).catch(() => { });
-                    postedFiles.push(`reports/${file}`);
-                    // Touch the consolidation guard file so the poller-local
-                    // `daysSinceMaintenance` metric reflects this successful run.
-                    // The metric reads `stat(memory/.last_consolidation).mtimeMs`, so any
-                    // skip of the consolidation skill's "update timestamp" step causes
-                    // silent drift. See poller-brain#109, poller-brain-eval#150.
-                    if (report.operationType === 'consolidation') {
-                        const guardPath = join(brainPath, 'memory', '.last_consolidation');
-                        const today = new Date().toISOString().slice(0, 10);
-                        try {
-                            await writeFile(guardPath, `${today}\n`);
-                            consolidationGuardTouched = true;
-                            logger.info(`[MaintenanceReporter] Touched ${guardPath}`);
-                        }
-                        catch (err) {
-                            logger.warn(`[MaintenanceReporter] Failed to touch ${guardPath}: ${err instanceof Error ? err.message : err}`);
+        if (jsonFiles.length > 0) {
+            logger.info(`[MaintenanceReporter] Found ${jsonFiles.length} JSON report(s) in ${reportsDir}`);
+            // Fleet visibility fields — sampled once per run. See teamvibe.ai#129.
+            const [baseBrainCommitSha, baseBrainAgeHours] = await Promise.all([
+                getBaseBrainCommitSha(config.BASE_BRAIN_PATH),
+                getBaseBrainAgeHours(config.BASE_BRAIN_PATH),
+            ]);
+            for (const file of jsonFiles) {
+                const filePath = join(reportsDir, file);
+                try {
+                    const content = await readFile(filePath, 'utf-8');
+                    let report;
+                    try {
+                        report = JSON.parse(content);
+                    }
+                    catch (parseErr) {
+                        // Unlike network/IO errors below, a JSON.parse failure is never
+                        // going to recover on retry — the payload itself is broken.
+                        // Quarantine it (not delete) so the content survives for later
+                        // inspection into why the generator emitted invalid JSON.
+                        const message = parseErr instanceof Error ? parseErr.message : String(parseErr);
+                        logger.warn(`[MaintenanceReporter] Quarantining malformed report ${file}: ${message}`);
+                        emitError('maintenance', `Quarantining malformed report ${file}: ${message}`, { severity: 'warn', channelId });
+                        const quarantineName = await quarantineFile(brainPath, file);
+                        quarantinedFrom.push(`reports/${file}`);
+                        quarantinedTo.push(`reports/${QUARANTINE_DIR_NAME}/${quarantineName}`);
+                        continue;
+                    }
+                    if (!report.operationType) {
+                        logger.warn(`[MaintenanceReporter] Removing invalid report ${file}: missing operationType`);
+                        emitError('maintenance', `Removing invalid report ${file}: missing operationType`, { severity: 'warn' });
+                        await unlink(filePath).catch(() => { });
+                        removedFiles.push(`reports/${file}`);
+                        continue;
+                    }
+                    const eventType = OPERATION_TO_EVENT_TYPE[report.operationType];
+                    if (!eventType) {
+                        logger.warn(`[MaintenanceReporter] Removing report ${file}: unknown operationType "${report.operationType}"`);
+                        emitError('maintenance', `Removing report ${file}: unknown operationType "${report.operationType}"`, { severity: 'warn' });
+                        await unlink(filePath).catch(() => { });
+                        removedFiles.push(`reports/${file}`);
+                        continue;
+                    }
+                    const payload = {
+                        eventType,
+                        channelId,
+                        pollerVersion: POLLER_VERSION,
+                        baseBrainCommitSha,
+                        baseBrainAgeHours,
+                        metadata: report,
+                    };
+                    const response = await fetch(`${config.TEAMVIBE_API_URL}/events`, {
+                        method: 'POST',
+                        headers: {
+                            'Content-Type': 'application/json',
+                            Authorization: `Bearer ${config.TEAMVIBE_POLLER_TOKEN}`,
+                        },
+                        body: JSON.stringify(payload),
+                    });
+                    if (response.ok) {
+                        logger.info(`[MaintenanceReporter] Posted ${file} as ${eventType}`);
+                        await unlink(filePath).catch(() => { });
+                        postedFiles.push(`reports/${file}`);
+                        // Touch the consolidation guard file so the poller-local
+                        // `daysSinceMaintenance` metric reflects this successful run.
+                        // The metric reads `stat(memory/.last_consolidation).mtimeMs`, so any
+                        // skip of the consolidation skill's "update timestamp" step causes
+                        // silent drift. See poller-brain#109, poller-brain-eval#150.
+                        if (report.operationType === 'consolidation') {
+                            const guardPath = join(brainPath, 'memory', '.last_consolidation');
+                            const today = new Date().toISOString().slice(0, 10);
+                            try {
+                                await writeFile(guardPath, `${today}\n`);
+                                consolidationGuardTouched = true;
+                                logger.info(`[MaintenanceReporter] Touched ${guardPath}`);
+                            }
+                            catch (err) {
+                                logger.warn(`[MaintenanceReporter] Failed to touch ${guardPath}: ${err instanceof Error ? err.message : err}`);
+                            }
                         }
                     }
+                    else {
+                        const errorBody = await response.text().catch(() => 'unknown');
+                        logger.warn(`[MaintenanceReporter] Failed to POST ${file}: ${response.status} ${errorBody}`);
+                        emitError('maintenance', `Failed to POST report ${file}: ${response.status}`, { severity: 'warn', channelId });
+                    }
                 }
-                else {
-                    const errorBody = await response.text().catch(() => 'unknown');
-                    logger.warn(`[MaintenanceReporter] Failed to POST ${file}: ${response.status} ${errorBody}`);
-                    emitError('maintenance', `Failed to POST report ${file}: ${response.status}`, { severity: 'warn', channelId });
+                catch (err) {
+                    logger.warn(`[MaintenanceReporter] Error processing ${file}: ${err instanceof Error ? err.message : err}`);
+                    emitError('maintenance', `Error processing report ${file}: ${err instanceof Error ? err.message : String(err)}`, { severity: 'warn', channelId });
                 }
             }
-            catch (err) {
-                logger.warn(`[MaintenanceReporter] Error processing ${file}: ${err instanceof Error ? err.message : err}`);
-                emitError('maintenance', `Error processing report ${file}: ${err instanceof Error ? err.message : String(err)}`, { severity: 'warn', channelId });
-            }
         }
-        // Remove posted/invalid JSON reports from git so they don't resurrect on next pull,
-        // and stage the consolidation guard file if it was touched this run.
-        const allRemovedFromGit = [...postedFiles, ...removedFiles];
-        if (allRemovedFromGit.length > 0 || consolidationGuardTouched) {
+        // Remove posted/invalid/expired-quarantine JSON reports from git so they
+        // don't resurrect on next pull, stage newly quarantined reports at their
+        // new path, and stage the consolidation guard file if it was touched.
+        // Runs regardless of jsonFiles.length so the quarantine-expiry sweep
+        // still gets committed on sessions with no new reports to process.
+        const gitRemovals = [
+            ...postedFiles,
+            ...removedFiles,
+            ...quarantinedFrom,
+            ...expiredQuarantineFiles,
+        ];
+        const gitAdditions = [...quarantinedTo];
+        if (gitRemovals.length > 0 ||
+            gitAdditions.length > 0 ||
+            consolidationGuardTouched) {
             try {
-                if (allRemovedFromGit.length > 0) {
-                    await execFileAsync('git', ['rm', '--cached', '--ignore-unmatch', ...allRemovedFromGit], { cwd: brainPath });
+                if (gitRemovals.length > 0) {
+                    await execFileAsync('git', ['rm', '--cached', '--ignore-unmatch', ...gitRemovals], { cwd: brainPath });
+                }
+                if (gitAdditions.length > 0) {
+                    // -f: quarantine payloads must survive regardless of any brain
+                    // .gitignore rule matching dotdirs (e.g. a blanket `.*`) — a
+                    // plain `git add` silently skips ignored paths, which would
+                    // defeat the whole point of quarantining (forensic survival)
+                    // the moment the next checkout drops the untracked file.
+                    await execFileAsync('git', ['add', '-f', ...gitAdditions], {
+                        cwd: brainPath,
+                    });
                 }
                 if (consolidationGuardTouched) {
-                    await execFileAsync('git', ['add', 'memory/.last_consolidation'], { cwd: brainPath });
+                    await execFileAsync('git', ['add', 'memory/.last_consolidation'], {
+                        cwd: brainPath,
+                    });
                 }
-                const message = consolidationGuardTouched && allRemovedFromGit.length > 0
-                    ? 'chore: process maintenance reports and refresh consolidation guard'
-                    : consolidationGuardTouched
-                        ? 'chore: refresh consolidation guard'
-                        : 'chore: remove processed maintenance reports';
-                await execFileAsync('git', ['commit', '-m', message], { cwd: brainPath });
-                logger.info(`[MaintenanceReporter] Committed ${allRemovedFromGit.length} report removal(s)${consolidationGuardTouched ? ' + guard refresh' : ''}`);
+                const messageParts = [];
+                if (postedFiles.length > 0 || removedFiles.length > 0)
+                    messageParts.push('process maintenance reports');
+                if (quarantinedFrom.length > 0)
+                    messageParts.push('quarantine malformed reports');
+                if (expiredQuarantineFiles.length > 0)
+                    messageParts.push('purge expired quarantine');
+                if (consolidationGuardTouched)
+                    messageParts.push('refresh consolidation guard');
+                const message = `chore: ${messageParts.join(' + ')}`;
+                await execFileAsync('git', ['commit', '-m', message], {
+                    cwd: brainPath,
+                });
+                logger.info(`[MaintenanceReporter] Committed ${gitRemovals.length} removal(s), ${gitAdditions.length} quarantine addition(s)${consolidationGuardTouched ? ' + guard refresh' : ''}`);
             }
             catch (err) {
-                logger.debug(`[MaintenanceReporter] Could not git-rm reports (may not be a git repo): ${err instanceof Error ? err.message : err}`);
+                logger.debug(`[MaintenanceReporter] Could not git-rm/add reports (may not be a git repo): ${err instanceof Error ? err.message : err}`);
             }
         }
     }

package/dist/poller.d.ts

@@ -1,3 +1,5 @@
+import { logger } from './logger.js';
+import type { TeamVibeQueueMessage } from './types.js';
 interface ReleaseLogger {
     info: (msg: string) => void;
     warn: (msg: string) => void;
@@ -13,5 +15,13 @@ export declare function releaseAllActiveLocks(locks: Map<string, string>, releas
  * in morning-check telemetry. Same DI shape as runMaintenanceJob.
  */
 export declare function runAutoUpdateJob(checkForUpdateFn?: () => Promise<boolean>): Promise<void>;
+/**
+ * Whether a runInboxLoop is currently active for this thread. Used by the
+ * inbox watcher (teamvibe.ai#242) to avoid starting a second loop for a
+ * thread that's already being served — its existing pickNextMessage() call
+ * will pick up any new file on its own.
+ */
+export declare function isInboxLoopActive(threadId: string): boolean;
+export declare function runInboxLoop(threadId: string, kbPath: string, queueMessage: TeamVibeQueueMessage, sessionLog: ReturnType<typeof logger.createSession>): Promise<void>;
 export declare function startPoller(): Promise<void>;
 export {};

package/dist/poller.js

@@ -13,6 +13,7 @@ import { registerBrain, startMaintenanceLoop, stopMaintenanceLoop } from './main
 import { startEventQueue, stopEventQueue, flush as flushEventQueue, emitEvent, emitError } from './event-queue.js';
 import { startMetricsCron, stopMetricsCron } from './metrics/scheduler.js';
 import { writeMessage, pickNextMessage, markProcessed, markFailed, hasUnprocessed } from './inbox-manager.js';
+import { startInboxWatcher, stopInboxWatcher } from './inbox-watcher.js';
 import { Cron } from 'croner';
 import { isControlMessage, handleControlMessage } from './control-handler.js';
 import { checkForUpdate } from './auto-update.js';
@@ -122,7 +123,16 @@ async function attemptDnsFlush() {
 }
 // Track which threads have an active processing loop
 const activeLoops = new Set();
-async function runInboxLoop(threadId, kbPath, queueMessage, sessionLog) {
+/**
+ * Whether a runInboxLoop is currently active for this thread. Used by the
+ * inbox watcher (teamvibe.ai#242) to avoid starting a second loop for a
+ * thread that's already being served — its existing pickNextMessage() call
+ * will pick up any new file on its own.
+ */
+export function isInboxLoopActive(threadId) {
+    return activeLoops.has(threadId);
+}
+export async function runInboxLoop(threadId, kbPath, queueMessage, sessionLog) {
     if (activeLoops.has(threadId)) {
         sessionLog.info(`Loop already running for thread ${threadId}, skipping`);
         return;
@@ -514,6 +524,7 @@ async function shutdown(signal, exitCode = 0) {
     stopMaintenanceLoop();
     stopAutoUpdateCron();
     stopMetricsCron();
+    stopInboxWatcher();
     stopEventQueue();
     // Kill all active Claude child processes
     await killAllActiveProcesses();
@@ -592,5 +603,6 @@ export async function startPoller() {
     startMaintenanceLoop(processMessage);
     startAutoUpdateCron();
     startMetricsCron();
+    startInboxWatcher();
     await pollLoop();
 }

package/package.json

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