@teamvibe/poller 0.6.0 → 0.7.0

package/dist/config.d.ts

@@ -15,6 +15,7 @@ declare const configSchema: z.ZodObject<{
     LOCK_RETRY_INTERVAL_MS: z.ZodDefault<z.ZodNumber>;
     IDLE_WATCHDOG_WARN_MS: z.ZodDefault<z.ZodNumber>;
     IDLE_WATCHDOG_KILL_MS: z.ZodDefault<z.ZodNumber>;
+    IDLE_WATCHDOG_COMPACTION_GRACE_MS: z.ZodDefault<z.ZodNumber>;
     NETWORK_ERROR_KILL_MS: z.ZodDefault<z.ZodNumber>;
     MAX_CONSECUTIVE_NET_FAILURES: z.ZodDefault<z.ZodNumber>;
     TEAMVIBE_DATA_DIR: z.ZodDefault<z.ZodString>;
@@ -28,11 +29,18 @@ declare const configSchema: z.ZodObject<{
     BASE_BRAIN_PATH: z.ZodDefault<z.ZodString>;
     BRAIN_AUTO_UPDATE: z.ZodEffects<z.ZodDefault<z.ZodString>, boolean, string | undefined>;
     BRAIN_UPDATE_COOLDOWN_MS: z.ZodDefault<z.ZodNumber>;
+    BRAIN_MAX_BLOB_BYTES: z.ZodDefault<z.ZodNumber>;
+    BRAIN_PUSH_RETRY_MAX: z.ZodDefault<z.ZodNumber>;
+    BRAIN_PUSH_RETRY_BACKOFF_MS: z.ZodDefault<z.ZodNumber>;
+    GIT_LOCK_MAX_AGE_MS: z.ZodDefault<z.ZodNumber>;
+    GIT_SUBMODULE_LOCK_MAX_AGE_MS: z.ZodDefault<z.ZodNumber>;
     POLLER_TZ: z.ZodOptional<z.ZodString>;
     MAINTENANCE_CRON: z.ZodDefault<z.ZodString>;
     MAINTENANCE_ENABLED: z.ZodEffects<z.ZodDefault<z.ZodString>, boolean, string | undefined>;
     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;
@@ -45,6 +53,7 @@ declare const configSchema: z.ZodObject<{
     LOCK_RETRY_INTERVAL_MS: number;
     IDLE_WATCHDOG_WARN_MS: number;
     IDLE_WATCHDOG_KILL_MS: number;
+    IDLE_WATCHDOG_COMPACTION_GRACE_MS: number;
     NETWORK_ERROR_KILL_MS: number;
     MAX_CONSECUTIVE_NET_FAILURES: number;
     TEAMVIBE_DATA_DIR: string;
@@ -58,10 +67,17 @@ declare const configSchema: z.ZodObject<{
     BASE_BRAIN_PATH: string;
     BRAIN_AUTO_UPDATE: boolean;
     BRAIN_UPDATE_COOLDOWN_MS: number;
+    BRAIN_MAX_BLOB_BYTES: number;
+    BRAIN_PUSH_RETRY_MAX: number;
+    BRAIN_PUSH_RETRY_BACKOFF_MS: number;
+    GIT_LOCK_MAX_AGE_MS: number;
+    GIT_SUBMODULE_LOCK_MAX_AGE_MS: number;
     MAINTENANCE_CRON: string;
     MAINTENANCE_ENABLED: boolean;
     AUTO_UPDATE_POLICY: "patch" | "minor" | "off";
     AUTO_UPDATE_SCHEDULE: string;
+    INBOX_WATCH_FALLBACK_INTERVAL_MS: number;
+    INBOX_WATCH_DEBOUNCE_MS: number;
     SQS_QUEUE_URL?: string | undefined;
     SESSIONS_TABLE?: string | undefined;
     TEAMVIBE_POLLER_TOKEN?: string | undefined;
@@ -81,6 +97,7 @@ declare const configSchema: z.ZodObject<{
     LOCK_RETRY_INTERVAL_MS?: number | undefined;
     IDLE_WATCHDOG_WARN_MS?: number | undefined;
     IDLE_WATCHDOG_KILL_MS?: number | undefined;
+    IDLE_WATCHDOG_COMPACTION_GRACE_MS?: number | undefined;
     NETWORK_ERROR_KILL_MS?: number | undefined;
     MAX_CONSECUTIVE_NET_FAILURES?: number | undefined;
     TEAMVIBE_DATA_DIR?: string | undefined;
@@ -94,11 +111,18 @@ declare const configSchema: z.ZodObject<{
     BASE_BRAIN_PATH?: string | undefined;
     BRAIN_AUTO_UPDATE?: string | undefined;
     BRAIN_UPDATE_COOLDOWN_MS?: number | undefined;
+    BRAIN_MAX_BLOB_BYTES?: number | undefined;
+    BRAIN_PUSH_RETRY_MAX?: number | undefined;
+    BRAIN_PUSH_RETRY_BACKOFF_MS?: number | undefined;
+    GIT_LOCK_MAX_AGE_MS?: number | undefined;
+    GIT_SUBMODULE_LOCK_MAX_AGE_MS?: number | undefined;
     POLLER_TZ?: string | undefined;
     MAINTENANCE_CRON?: string | undefined;
     MAINTENANCE_ENABLED?: string | undefined;
     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;
@@ -114,6 +138,7 @@ export declare const config: {
     LOCK_RETRY_INTERVAL_MS: number;
     IDLE_WATCHDOG_WARN_MS: number;
     IDLE_WATCHDOG_KILL_MS: number;
+    IDLE_WATCHDOG_COMPACTION_GRACE_MS: number;
     NETWORK_ERROR_KILL_MS: number;
     MAX_CONSECUTIVE_NET_FAILURES: number;
     TEAMVIBE_DATA_DIR: string;
@@ -127,10 +152,17 @@ export declare const config: {
     BASE_BRAIN_PATH: string;
     BRAIN_AUTO_UPDATE: boolean;
     BRAIN_UPDATE_COOLDOWN_MS: number;
+    BRAIN_MAX_BLOB_BYTES: number;
+    BRAIN_PUSH_RETRY_MAX: number;
+    BRAIN_PUSH_RETRY_BACKOFF_MS: number;
+    GIT_LOCK_MAX_AGE_MS: number;
+    GIT_SUBMODULE_LOCK_MAX_AGE_MS: number;
     MAINTENANCE_CRON: string;
     MAINTENANCE_ENABLED: boolean;
     AUTO_UPDATE_POLICY: "patch" | "minor" | "off";
     AUTO_UPDATE_SCHEDULE: string;
+    INBOX_WATCH_FALLBACK_INTERVAL_MS: number;
+    INBOX_WATCH_DEBOUNCE_MS: number;
     SQS_QUEUE_URL?: string | undefined;
     SESSIONS_TABLE?: string | undefined;
     TEAMVIBE_POLLER_TOKEN?: string | undefined;

package/dist/config.js

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

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

package/dist/cron-telemetry.js

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

package/dist/event-queue.d.ts

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

package/dist/event-queue.js

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

package/dist/inbox-manager.d.ts

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

package/dist/inbox-manager.js

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

package/dist/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;