@teamvibe/poller 0.5.3 → 0.6.2

package/dist/claude-spawner.d.ts

@@ -1,6 +1,7 @@
 import type { TeamVibeQueueMessage, SessionMetrics } from './types.js';
 import { type SessionLogger } from './logger.js';
 import type { TypingIndicator } from './slack-client.js';
+import { type ResolvedModelConfig } from './config-client.js';
 import type { KilledByPoller } from './classify-failed-iteration.js';
 export interface ContextHintParams {
     isFirstMessage: boolean;
@@ -21,7 +22,38 @@ export interface SpawnResult {
     error?: string;
     metrics?: SessionMetrics;
     killedByPoller?: KilledByPoller;
+    modelSource?: ModelSource;
 }
+/**
+ * `settings.json` and `env-default` are poller-local, not DDB-resolved
+ * scopes — kept as a superset of `services/model-config.ts`'s
+ * `ModelConfigScope` rather than importing it, since the poller package
+ * doesn't depend on `modules-teamvibe`.
+ */
+export type ModelSource = 'settings.json' | 'poller' | 'workspace' | 'channel' | 'env-default' | undefined;
+/**
+ * 3-tier model resolution — teamvibe.ai#235 PR2.
+ *
+ * Precedence (highest to lowest): brain `settings.json` > DDB-resolved
+ * scoped config (poller/workspace/channel, fetched via
+ * `fetchConfigForSpawn`) > `CLAUDE_MODEL` env default.
+ *
+ * `settings.json` staying on top is a **known, documented, accepted
+ * blind spot** (see DevGuru's tv#235 approach-review addendum): a
+ * poller-level emergency model cap set via DDB can be silently
+ * overridden by any brain's local settings.json. Not fixed here — PR3
+ * adds a read-only "last observed override source" surfaced via the
+ * `session.completed` telemetry this function's return value feeds
+ * (see the `modelSource` field on `SpawnResult` / the `poller.ts`
+ * `emitEvent` call site).
+ *
+ * Pure function — no I/O — so it's unit-testable without mocking
+ * `fetch` or `child_process.spawn`.
+ */
+export declare function resolveModel(brainSettingsModel: string | undefined, ddbConfig: Pick<ResolvedModelConfig, 'model' | 'modelSource'>, envDefaultModel: string | undefined): {
+    model: string | undefined;
+    modelSource: ModelSource;
+};
 export declare function buildPrompt(msg: TeamVibeQueueMessage, contextHint?: string): string;
 export declare function spawnClaudeCode(msg: TeamVibeQueueMessage, sessionLog: SessionLogger, cwd: string, sessionId?: string, isFirstMessage?: boolean, lastMessageTs?: string, onMessageSent?: () => void, typingIndicator?: TypingIndicator): Promise<SpawnResult & {
     newSessionId?: string;

package/dist/claude-spawner.js

@@ -9,6 +9,7 @@ import { getPollerId } from './auth-provider.js';
 import { emitError } from './event-queue.js';
 import { createWorktree, removeWorktree, isWorktreeIsolationEnabled } from './worktree-manager.js';
 import { fetchSecretsForSpawn, buildSecretsReminder } from './secrets-client.js';
+import { fetchConfigForSpawn } from './config-client.js';
 /**
  * Maps tool names (or prefixes) to human-readable status messages.
  * More specific patterns are checked first.
@@ -167,6 +168,37 @@ function readBrainSettings(cwd) {
         return {};
     }
 }
+/**
+ * 3-tier model resolution — teamvibe.ai#235 PR2.
+ *
+ * Precedence (highest to lowest): brain `settings.json` > DDB-resolved
+ * scoped config (poller/workspace/channel, fetched via
+ * `fetchConfigForSpawn`) > `CLAUDE_MODEL` env default.
+ *
+ * `settings.json` staying on top is a **known, documented, accepted
+ * blind spot** (see DevGuru's tv#235 approach-review addendum): a
+ * poller-level emergency model cap set via DDB can be silently
+ * overridden by any brain's local settings.json. Not fixed here — PR3
+ * adds a read-only "last observed override source" surfaced via the
+ * `session.completed` telemetry this function's return value feeds
+ * (see the `modelSource` field on `SpawnResult` / the `poller.ts`
+ * `emitEvent` call site).
+ *
+ * Pure function — no I/O — so it's unit-testable without mocking
+ * `fetch` or `child_process.spawn`.
+ */
+export function resolveModel(brainSettingsModel, ddbConfig, envDefaultModel) {
+    if (brainSettingsModel) {
+        return { model: brainSettingsModel, modelSource: 'settings.json' };
+    }
+    if (ddbConfig.model) {
+        return { model: ddbConfig.model, modelSource: ddbConfig.modelSource };
+    }
+    if (envDefaultModel) {
+        return { model: envDefaultModel, modelSource: 'env-default' };
+    }
+    return { model: undefined, modelSource: undefined };
+}
 // Tags procs at SIGTERM time so the close handler can report poller intent.
 // WeakMap auto-cleans when proc is GC'd. Module-scope is required because
 // killZombieForThread fires outside the runClaudeCode closure.
@@ -191,6 +223,12 @@ export function buildPrompt(msg, contextHint) {
             ? 'Direct Message'
             : `Channel ${slack.channel}`;
         prompt += `**Channel:** ${channelType}\n`;
+        // The agent's reply defaults to this thread. Stating it here is what stops
+        // the agent from reconstructing "the thread we were in" from memory and
+        // replying into a stale one — see teamvibeai/teamvibe.ai#184.
+        if (slack.thread_ts) {
+            prompt += `**Thread TS:** \`${slack.thread_ts}\` (your reply defaults here)\n`;
+        }
     }
     // Inject human-readable timestamp from Slack message ts
     if (msg.response_context.slack?.message_ts) {
@@ -333,6 +371,14 @@ async function runClaudeCode(msg, sessionLog, cwd, sessionId, isFirstMessage = t
         channelId: msg.teamvibe.channelId,
     });
     const secretsReminder = buildSecretsReminder(spawnSecrets.reminders);
+    // Fetch scoped model config for this spawn — same hoisting rationale as
+    // secrets above. Fail-soft: returns {} on any error, which resolveModel
+    // treats as "nothing at this tier" and falls through to the env default.
+    const ddbModelConfig = await fetchConfigForSpawn({
+        pollerId: getPollerId() || '',
+        workspaceId: msg.teamvibe.workspaceId,
+        channelId: msg.teamvibe.channelId,
+    });
     return new Promise((resolve) => {
         const prompt = buildPrompt(msg, contextHint);
         // MCP server config passed via --mcp-config flag (no temp files needed)
@@ -358,11 +404,15 @@ async function runClaudeCode(msg, sessionLog, cwd, sessionId, isFirstMessage = t
             '--disallowedTools',
             'NotebookEdit',
         ];
-        // Model override: brain settings.json takes priority, then CLAUDE_MODEL env var
-        const model = (typeof brainSettings['model'] === 'string' && brainSettings['model']) || config.CLAUDE_MODEL;
+        // Model override — 3-tier precedence (teamvibe.ai#235 PR2): brain
+        // settings.json > DDB-resolved scoped config (poller/workspace/channel)
+        // > CLAUDE_MODEL env default. See resolveModel's docstring for why
+        // settings.json stays on top (known, accepted blind spot).
+        const brainSettingsModel = typeof brainSettings['model'] === 'string' ? brainSettings['model'] : undefined;
+        const { model, modelSource } = resolveModel(brainSettingsModel, ddbModelConfig, config.CLAUDE_MODEL);
         if (model) {
             args.push('--model', model);
-            sessionLog.info(`Using model: ${model}`);
+            sessionLog.info(`Using model: ${model} (source: ${modelSource ?? 'unknown'})`);
         }
         // Inbox protocol: instruct Claude to check for mid-task messages (thread-scoped)
         const inboxNewDir = `.inbox/${msg.thread_id}/new`;
@@ -581,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
@@ -595,6 +648,7 @@ async function runClaudeCode(msg, sessionLog, cwd, sessionId, isFirstMessage = t
                 output: stdout,
                 exitCode: code,
                 metrics,
+                modelSource,
                 ...(killReason ? { killedByPoller: killReason } : {}),
             };
             if (killReason === 'timeout') {

package/dist/config-client.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Poller-side non-secret scoped config client — teamvibe.ai#235 (PR2).
+ *
+ * Fetches the resolved scoped config from the Poller API
+ * (GET /config/spawn?pollerId=&workspaceId=&channelId=) before spawn.
+ * Mirrors `secrets-client.ts`'s defensive-failure pattern: on any failure
+ * mode (missing config, network error, non-2xx, malformed JSON) this
+ * returns an empty result rather than throwing — spawn must never fail
+ * because this fetch failed, it just falls through to the next
+ * precedence tier (settings.json / CLAUDE_MODEL env default) in
+ * `claude-spawner.ts`.
+ *
+ * Unlike secrets, this config is NOT sensitive — no `Redacted`/opaque
+ * envelope wrapper needed, the resolved value is returned as a plain
+ * object.
+ *
+ * Wire shape is a generic `env`/`sources` envelope (see
+ * `poller-config.ts`'s `buildConfigResponse` on the server side) so
+ * future non-secret settings land as additional `env` keys without a new
+ * endpoint. This client unwraps that envelope into the typed
+ * `ResolvedModelConfig` shape `claude-spawner.ts` already consumes —
+ * today only the `MODEL`/`REASONING_EFFORT` keys exist, so the unwrap is
+ * a fixed 1:1 mapping, not a generic loop; widen it if/when a third key
+ * appears.
+ */
+export type ModelConfigScope = 'poller' | 'workspace' | 'channel';
+export interface ResolvedModelConfig {
+    model?: string;
+    reasoningEffort?: string;
+    modelSource?: ModelConfigScope;
+    reasoningEffortSource?: ModelConfigScope;
+}
+export interface FetchModelConfigInput {
+    pollerId: string;
+    workspaceId: string;
+    channelId: string;
+}
+/**
+ * Fetch the resolved config for a spawn. Returns `{}` on any failure
+ * mode — spawn continues, falling through to the env-default model tier.
+ * Errors are logged at warn level so monitoring can alarm; mirrors
+ * `fetchSecretsForSpawn`'s fail-soft contract exactly.
+ */
+export declare function fetchConfigForSpawn(input: FetchModelConfigInput): Promise<ResolvedModelConfig>;

package/dist/config-client.js

@@ -0,0 +1,113 @@
+/**
+ * Poller-side non-secret scoped config client — teamvibe.ai#235 (PR2).
+ *
+ * Fetches the resolved scoped config from the Poller API
+ * (GET /config/spawn?pollerId=&workspaceId=&channelId=) before spawn.
+ * Mirrors `secrets-client.ts`'s defensive-failure pattern: on any failure
+ * mode (missing config, network error, non-2xx, malformed JSON) this
+ * returns an empty result rather than throwing — spawn must never fail
+ * because this fetch failed, it just falls through to the next
+ * precedence tier (settings.json / CLAUDE_MODEL env default) in
+ * `claude-spawner.ts`.
+ *
+ * Unlike secrets, this config is NOT sensitive — no `Redacted`/opaque
+ * envelope wrapper needed, the resolved value is returned as a plain
+ * object.
+ *
+ * Wire shape is a generic `env`/`sources` envelope (see
+ * `poller-config.ts`'s `buildConfigResponse` on the server side) so
+ * future non-secret settings land as additional `env` keys without a new
+ * endpoint. This client unwraps that envelope into the typed
+ * `ResolvedModelConfig` shape `claude-spawner.ts` already consumes —
+ * today only the `MODEL`/`REASONING_EFFORT` keys exist, so the unwrap is
+ * a fixed 1:1 mapping, not a generic loop; widen it if/when a third key
+ * appears.
+ */
+import { logger } from './logger.js';
+import { config } from './config.js';
+const SCOPES = new Set(['poller', 'workspace', 'channel']);
+function isModelConfigScope(v) {
+    return typeof v === 'string' && SCOPES.has(v);
+}
+/**
+ * Fetch the resolved config for a spawn. Returns `{}` on any failure
+ * mode — spawn continues, falling through to the env-default model tier.
+ * Errors are logged at warn level so monitoring can alarm; mirrors
+ * `fetchSecretsForSpawn`'s fail-soft contract exactly.
+ */
+export async function fetchConfigForSpawn(input) {
+    if (!config.TEAMVIBE_API_URL || !config.TEAMVIBE_POLLER_TOKEN) {
+        logger.warn('config-client: TEAMVIBE_API_URL or TEAMVIBE_POLLER_TOKEN not set; skipping fetch');
+        return {};
+    }
+    // Upfront short-circuit: an empty pollerId would fail server-side
+    // validation and round-trip an HTTP error. Skip the call entirely so
+    // the warn log makes the cause obvious from poller stdout.
+    if (!input.pollerId) {
+        logger.warn('config-client: pollerId empty; skipping fetch (no scoped config for spawn)');
+        return {};
+    }
+    let url;
+    try {
+        url = new URL('/config/spawn', config.TEAMVIBE_API_URL);
+        url.searchParams.set('pollerId', input.pollerId);
+        url.searchParams.set('workspaceId', input.workspaceId);
+        url.searchParams.set('channelId', input.channelId);
+    }
+    catch (err) {
+        logger.warn(`config-client.config_error: invalid TEAMVIBE_API_URL=${String(config.TEAMVIBE_API_URL)} ` +
+            `error=${err?.message ?? String(err)}`);
+        return {};
+    }
+    let response;
+    try {
+        response = await fetch(url.toString(), {
+            method: 'GET',
+            headers: {
+                Authorization: `Bearer ${config.TEAMVIBE_POLLER_TOKEN}`,
+            },
+        });
+    }
+    catch (err) {
+        logger.warn(`config-client.fetch_failed: network error pollerId=${input.pollerId} ` +
+            `workspaceId=${input.workspaceId} channelId=${input.channelId} ` +
+            `error=${err?.message ?? String(err)}`);
+        return {};
+    }
+    if (!response.ok) {
+        let snippet = '';
+        try {
+            snippet = (await response.text()).slice(0, 200);
+        }
+        catch {
+            snippet = '<failed-to-read-body>';
+        }
+        logger.warn(`config-client.fetch_failed: status=${response.status} ` +
+            `pollerId=${input.pollerId} workspaceId=${input.workspaceId} ` +
+            `channelId=${input.channelId} bodySnippet=${snippet}`);
+        return {};
+    }
+    let parsed;
+    try {
+        parsed = (await response.json());
+    }
+    catch (err) {
+        logger.warn(`config-client.parse_failed: pollerId=${input.pollerId} ` +
+            `error=${err?.message ?? String(err)}`);
+        return {};
+    }
+    const env = parsed.env ?? {};
+    const sources = parsed.sources ?? {};
+    const result = {};
+    if (typeof env.MODEL === 'string' && env.MODEL)
+        result.model = env.MODEL;
+    if (typeof env.REASONING_EFFORT === 'string' && env.REASONING_EFFORT) {
+        result.reasoningEffort = env.REASONING_EFFORT;
+    }
+    if (isModelConfigScope(sources.MODEL))
+        result.modelSource = sources.MODEL;
+    if (isModelConfigScope(sources.REASONING_EFFORT))
+        result.reasoningEffortSource = sources.REASONING_EFFORT;
+    logger.info(`config-client: resolved model=${result.model ?? '(none)'} source=${result.modelSource ?? '(none)'}`);
+    return result;
+}

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;
@@ -210,6 +220,11 @@ async function runInboxLoop(threadId, kbPath, queueMessage, sessionLog) {
                             duration_api_ms: result.metrics.duration_api_ms,
                             num_turns: result.metrics.num_turns,
                             model: result.metrics.model,
+                            // Which config layer actually chose the `--model` flag
+                            // (settings.json / poller / workspace / channel / env-default)
+                            // — teamvibe.ai#235 PR2. Distinct from `model` above, which is
+                            // Claude CLI's own report of the model it used.
+                            modelSource: result.modelSource,
                         });
                     }
                     if (queueMessage.teamvibe.brain?.brainId) {
@@ -509,6 +524,7 @@ async function shutdown(signal, exitCode = 0) {
     stopMaintenanceLoop();
     stopAutoUpdateCron();
     stopMetricsCron();
+    stopInboxWatcher();
     stopEventQueue();
     // Kill all active Claude child processes
     await killAllActiveProcesses();
@@ -587,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.5.3",
+  "version": "0.6.2",
   "type": "module",
   "main": "./dist/index.js",
   "bin": {