@teamvibe/poller 0.6.0 → 0.7.0

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/metrics/collector.d.ts

@@ -21,6 +21,8 @@ export interface MetricsPayload {
     daysSinceMaintenance?: number;
     lastMaintenanceJobMs?: number;
     lastMaintenanceJobSuccessMs?: number;
+    maintenanceSkippedCountLastRun?: number;
+    lastMaintenanceJobSkippedMs?: number;
     lastAutoUpdateJobMs?: number;
     lastAutoUpdateJobSuccessMs?: number;
     timestamp?: string;

package/dist/metrics/collector.js

@@ -228,6 +228,13 @@ export async function collectMetrics(brainPath, brainId) {
     if (cron.lastMaintenanceJobSuccessAt !== null) {
         payload.lastMaintenanceJobSuccessMs = now - cron.lastMaintenanceJobSuccessAt;
     }
+    // #131 — activity-based skip counter. Always sent (0 is a real "no skips
+    // this run" value, not an omission) so a stuck-high count is visible
+    // fleet-wide without per-brain digging.
+    payload.maintenanceSkippedCountLastRun = cron.maintenanceSkippedCountLastRun;
+    if (cron.lastMaintenanceJobSkippedAt !== null) {
+        payload.lastMaintenanceJobSkippedMs = now - cron.lastMaintenanceJobSkippedAt;
+    }
     if (cron.lastAutoUpdateJobFiredAt !== null) {
         payload.lastAutoUpdateJobMs = now - cron.lastAutoUpdateJobFiredAt;
     }

package/dist/poller.d.ts

@@ -1,3 +1,7 @@
+import { logger } from './logger.js';
+import { type SpawnResult } from './claude-spawner.js';
+import { type KilledByPoller } from './classify-failed-iteration.js';
+import type { TeamVibeQueueMessage } from './types.js';
 interface ReleaseLogger {
     info: (msg: string) => void;
     warn: (msg: string) => void;
@@ -13,5 +17,20 @@ 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 isIntentionalKillExitCode(exitCode: number | null): boolean;
+export declare function isPollerInitiatedFailure(result: {
+    exitCode: number | null;
+    killedByPoller?: KilledByPoller;
+}): boolean;
+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 __setShuttingDownForTest(value: boolean): void;
 export declare function startPoller(): Promise<void>;
 export {};

package/dist/poller.js

@@ -12,7 +12,8 @@ import { initAuth, stopRefresh, getPollerId } from './auth-provider.js';
 import { registerBrain, startMaintenanceLoop, stopMaintenanceLoop } from './maintenance-cron.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 } from './inbox-manager.js';
+import { writeMessage, pickNextMessage, markProcessed, markFailed, hasUnprocessed, requeueMessage } 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,67 @@ 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);
+}
+// Exported for testing (teamvibe.ai#32). SIGTERM (143) / SIGKILL (137) exit
+// codes are the classic 128+signal convention for "the poller itself killed
+// this process on purpose" (timeout, idle, network, zombie, or — as of #32 —
+// a compaction-ceiling watchdog kill). Historically all of these set
+// `killedByPoller` via the same `proc.kill('SIGTERM')` path in
+// claude-spawner.ts and were observed to surface as 143/137 here.
+//
+// PR#308 round-2 review (teamvibe.ai#73): this exit-code convention is
+// fragile on its own — the Claude CLI can legitimately exit 143 for
+// unrelated reasons, and #73's move to group-kill (`process.kill(-pid, ...)`
+// instead of a direct `proc.kill()`) means a signal-terminated close now
+// reports `code: null` with a separate `signal` field (verified empirically
+// against a synthetic detached child in this repo's environment — Node's
+// `close` event reports `code: null` for any signal-terminated process,
+// group-killed or not). Kept as a defensive fallback only — see
+// isPollerInitiatedFailure() below, which is what callers should actually use.
+export function isIntentionalKillExitCode(exitCode) {
+    return exitCode === 143 || exitCode === 137;
+}
+// The actual retry-classification signal (PR#308 round-2 review item 1):
+// `killedByPoller` is the purpose-built marker for "the poller killed this
+// process on purpose, not an application failure" (see SpawnResult /
+// classify-failed-iteration.ts) and is set on every poller-initiated kill
+// path this branch touches — timeout, idle watchdog, network watchdog,
+// zombie-kill, and (added by this fix) poller shutdown. Prefer it, and fall
+// back to the exit-code heuristic only when it's absent (e.g. hand-built
+// SpawnResult literals in older/unrelated call sites) so behavior doesn't
+// regress for anything not yet covered by the marker.
+export function isPollerInitiatedFailure(result) {
+    return Boolean(result.killedByPoller) || isIntentionalKillExitCode(result.exitCode);
+}
+// 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
+// silently (no error, no signal; see poller-brain#235's 4x-in-one-session
+// recurrence). Decides whether this run needs the deterministic fallback
+// delivery, and if so, what text to send.
+//
+// Pure/exported (mirrors classifyFailedIteration's pattern) so the gating
+// logic — "Slack context AND no send_message call AND non-empty trailing
+// text" — is unit-testable without mocking spawnClaudeCode or sendSlackMessage.
+// 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.
+export function endOfTurnFallbackText(hasSlackContext, result) {
+    if (!hasSlackContext || !result.success || result.sawSendMessageCall) {
+        return undefined;
+    }
+    const text = result.lastPlainTextContent?.trim();
+    return text ? text : undefined;
+}
+export async function runInboxLoop(threadId, kbPath, queueMessage, sessionLog) {
     if (activeLoops.has(threadId)) {
         sessionLog.info(`Loop already running for thread ${threadId}, skipping`);
         return;
@@ -150,7 +211,25 @@ async function runInboxLoop(threadId, kbPath, queueMessage, sessionLog) {
             activeLocks.set(threadId, lockToken);
         }
         let currentSessionId = session.session_id || undefined;
-        while (true) {
+        // PR#308 round-3 review (teamvibe.ai#73): `shuttingDown` (declared below,
+        // referenced here via the same forward-reference pattern already used by
+        // pollLoop()'s `while (!shuttingDown)`) gates every new iteration of this
+        // loop, not just the retry-classification decision inside it. Without
+        // this, a message killed with `killedByPoller: 'shutdown'` (added by this
+        // branch) falls into the same "poller-initiated, retry immediately, no
+        // backoff" bucket as timeout/idle/network/zombie (see
+        // isPollerInitiatedFailure() below) — correctly skipping markProcessed/
+        // markFailed so the message stays unprocessed for a future boot, but with
+        // nothing to stop the loop from immediately calling pickNextMessage()
+        // again and spawning a NEW `claude` process for that same message, even
+        // though killAllActiveProcesses() (shutdown()'s first step) already ran.
+        // Gating the loop *condition* itself (rather than special-casing
+        // 'shutdown' inside the retry decision) closes this for every
+        // killedByPoller reason uniformly, and — unlike a `break` — falls through
+        // to the exact same post-loop cleanup (releaseSessionLock etc., below)
+        // that the existing `if (!message) break` / `if (!hasUnprocessed(...))
+        // break` exits already use, so lock release is unaffected.
+        while (!shuttingDown) {
             const message = pickNextMessage(kbPath, threadId);
             if (!message) {
                 sessionLog.info(`[Loop] No more messages for thread ${threadId}`);
@@ -167,6 +246,7 @@ async function runInboxLoop(threadId, kbPath, queueMessage, sessionLog) {
                 : undefined;
             let succeeded = false;
             let lastExitCode = null;
+            let lastKilledByPoller;
             try {
                 // Reconstruct queue message from stored inbox data
                 const storedData = JSON.parse(message.content);
@@ -217,6 +297,28 @@ async function runInboxLoop(threadId, kbPath, queueMessage, sessionLog) {
                             modelSource: result.modelSource,
                         });
                     }
+                    // teamvibe.ai#284 (poller-brain#235): end-of-turn guard. A
+                    // successful run that never called send_message but left trailing
+                    // plain text would otherwise vanish silently — deliver it via the
+                    // same sendSlackMessage() helper used for the failure-path neutral
+                    // notices, and emit a warning-level event so the near-miss is
+                    // visible (today session.completed looks identical whether or not
+                    // this fired).
+                    const fallbackText = endOfTurnFallbackText(hasSlackContext, result);
+                    if (fallbackText) {
+                        sessionLog.warn(`[Loop] Iteration #${iteration}: no send_message call detected, delivering trailing assistant text via fallback`);
+                        try {
+                            await sendSlackMessage(queueMessage, fallbackText);
+                        }
+                        catch (err) {
+                            sessionLog.error(`[Loop] End-of-turn fallback delivery failed: ${err instanceof Error ? err.message : err}`);
+                        }
+                        emitError('session', 'End-of-turn guard: delivered assistant text via fallback (no send_message tool call detected)', {
+                            severity: 'warn',
+                            channelId: queueMessage.teamvibe.channelId,
+                            context: { threadId: queueMessage.thread_id },
+                        });
+                    }
                     if (queueMessage.teamvibe.brain?.brainId) {
                         await pushBrainChanges(kbPath, queueMessage.teamvibe.brain.brainId, queueMessage.teamvibe.workspaceId);
                     }
@@ -224,6 +326,7 @@ async function runInboxLoop(threadId, kbPath, queueMessage, sessionLog) {
                 }
                 else {
                     lastExitCode = result.exitCode;
+                    lastKilledByPoller = result.killedByPoller;
                     sessionLog.error(`[Loop] Claude failed iteration #${iteration}: ${result.error}`);
                     if (hasSlackContext) {
                         const decision = classifyFailedIteration(result);
@@ -245,8 +348,19 @@ async function runInboxLoop(threadId, kbPath, queueMessage, sessionLog) {
                 markProcessed(kbPath, threadId, message.filename);
             }
             else {
-                // SIGTERM (143) or SIGKILL (137) = intentional kill → retry immediately, no backoff
-                const isKilledSignal = lastExitCode === 143 || lastExitCode === 137;
+                // 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) {
                     const failures = (failureCounts.get(message.filename) || 0) + 1;
                     failureCounts.set(message.filename, failures);
@@ -261,6 +375,43 @@ async function runInboxLoop(threadId, kbPath, queueMessage, sessionLog) {
                         await sleep(backoffMs);
                     }
                 }
+                else if (lastKilledByPoller === 'shutdown') {
+                    // 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
+                    // sitting in processing/, not new/. The watcher's wake condition
+                    // (hasNewMessage(), inbox-watcher.ts) only scans new/, so nothing
+                    // would start a fresh runInboxLoop() for this thread on next boot.
+                    // Requeue it back to new/ so a future boot's watcher scan actually
+                    // finds it — this is what makes "your message is saved" (the
+                    // 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
+                    // notice text also naming "next message or scheduled run" rather
+                    // than claiming automatic resumption.
+                    //
+                    // Scoped to 'shutdown' only, deliberately not the other four
+                    // poller-initiated reasons (timeout/idle/network/zombie) — those
+                    // retry immediately within this same still-running loop iteration
+                    // (the `while (!shuttingDown)` condition above lets it come
+                    // straight back around), so the existing processing/
+                    // crash-recovery branch inside pickNextMessage() already covers
+                    // them; requeueing those too would be redundant and could
+                    // double-process.
+                    //
+                    // Safe against waking a brand-new loop for this thread before this
+                    // poller process actually exits: stopInboxWatcher() runs earlier in
+                    // shutdown() (poller.ts), BEFORE killAllActiveProcesses() (whose
+                    // completion is what unblocks this iteration and reaches this
+                    // branch) — and stopInboxWatcher() closes the real fs.watch
+                    // handlers themselves (inbox-watcher.ts stopInboxWatcher(), not
+                    // just an interval/poll timer), so by the time this requeue runs,
+                    // nothing is watching new/ to react to the file reappearing there.
+                    requeueMessage(kbPath, threadId, message.filename);
+                }
             }
             if (!hasUnprocessed(kbPath, threadId)) {
                 break;
@@ -505,6 +656,19 @@ function sleep(ms) {
 }
 // Graceful shutdown
 let shuttingDown = false;
+// Exported for testing only (PR#308 round-3 review item 1). `shuttingDown`
+// has no other external mutator — production code only ever flips it via
+// the real shutdown() below, which also runs killAllActiveProcesses(),
+// releaseAllActiveLocks(), the drain loop, and process.exit(). This setter
+// lets a test put runInboxLoop's `while (!shuttingDown)` gate into the
+// "shutdown in progress" state directly (mirroring the exact race
+// shutdown() itself creates — killAllActiveProcesses() kills the in-flight
+// spawn while its promise is still pending) without invoking any of those
+// real side effects. Same pattern as __resetCronTelemetryForTest /
+// __resetTrackedBrainsForTest elsewhere in this package.
+export function __setShuttingDownForTest(value) {
+    shuttingDown = value;
+}
 async function shutdown(signal, exitCode = 0) {
     if (shuttingDown)
         return;
@@ -514,6 +678,7 @@ async function shutdown(signal, exitCode = 0) {
     stopMaintenanceLoop();
     stopAutoUpdateCron();
     stopMetricsCron();
+    stopInboxWatcher();
     stopEventQueue();
     // Kill all active Claude child processes
     await killAllActiveProcesses();
@@ -592,5 +757,6 @@ export async function startPoller() {
     startMaintenanceLoop(processMessage);
     startAutoUpdateCron();
     startMetricsCron();
+    startInboxWatcher();
     await pollLoop();
 }

package/dist/types.d.ts

@@ -19,6 +19,12 @@ export interface TeamVibeQueueMessage {
         filename: string;
         mimetype: string;
     }>;
+    inlineImages?: Array<{
+        mediaType: string;
+        data?: string;
+        url?: string;
+        expiresAt?: string;
+    }>;
     response_context: {
         slack?: {
             channel: string;