@teamvibe/poller 0.6.2 → 0.7.1

package/dist/maintenance-cron.d.ts

@@ -7,6 +7,7 @@ export interface TrackedBrainInfo {
     botId: string;
     botToken: string;
     channelId: string;
+    lastRealMessageAt?: number;
 }
 /**
  * Read-only view of brains seen so far (via registerBrain). Used by the inbox
@@ -14,6 +15,78 @@ export interface TrackedBrainInfo {
  * workspace/bot credentials to use when starting a session for an idle thread.
  */
 export declare function getTrackedBrains(): ReadonlyMap<string, TrackedBrainInfo>;
+/**
+ * Test-only helper to clear tracked brains between tests (module-scoped
+ * state persists across tests in the same file otherwise).
+ * @internal
+ */
+export declare function __resetTrackedBrainsForTest(): void;
+/**
+ * Shape returned by GET /poller/brains (teamvibe.ai#127 Option B) — the
+ * fields registerBrain() needs to build a synthetic maintenance message,
+ * minus `lastRealMessageAt` (see seedTrackedBrains below for why that's
+ * deliberately not part of the bootstrap payload).
+ */
+export interface BootstrapBrainInfo {
+    brainId: string;
+    gitRepoUrl: string;
+    branch: string;
+    workspaceId: string;
+    botId: string;
+    botToken: string;
+    channelId: string;
+}
+/**
+ * Seed trackedBrains at startup from the backend's authoritative brain list
+ * (teamvibe.ai#127) so a "quiet" brain — one that hasn't received a real
+ * message since this poller process started — still gets included in the
+ * maintenance/heartbeat cron, instead of being silently invisible until a
+ * human happens to message it.
+ *
+ * Deliberately does NOT set `lastRealMessageAt` (left undefined). That
+ * field specifically means "we've seen a real message since our own last
+ * restart" — shouldSkipMaintenance (maintenance-activity.ts, #131) treats
+ * `undefined` as fail-open (never skip) for exactly this reason. Bootstrap
+ * seeding isn't a real message; claiming one occurred here would risk the
+ * opposite bug — a genuinely-quiet brain wrongly evaluated as "nothing new,
+ * skip" on its very first post-restart cron tick.
+ *
+ * Skips (rather than overwrites) any brainId already present in
+ * trackedBrains. This guard is load-bearing, not just defensive (DevGuru
+ * review, round 4): since round 3's critical-path detachment
+ * (brains-bootstrap.ts's `void (async () => {...})()` retry), the retry
+ * branch can finish AFTER startPoller() has already returned and real user
+ * messages have started arriving. That means a real registerBrain() call
+ * for a brain (which sets `lastRealMessageAt`) can race ahead of — and
+ * complete before — the detached bootstrap retry's seedTrackedBrains()
+ * call for that same brain. Without this skip, the late-arriving bootstrap
+ * seed would silently overwrite the real registration back to a fresh
+ * entry with `lastRealMessageAt: undefined`, losing real activity data
+ * (and, per the fail-open contract above, artificially reopening the
+ * skip-maintenance window for a brain that's actually been active).
+ *
+ * DOES also register each seeded brain for hourly metrics (see
+ * `registerBrainForMetrics` below) — DevGuru review caught that this
+ * module's original "metrics has its own disk-walk path" reasoning was
+ * wrong: `metrics/scheduler.ts`'s `registered` Map has exactly one
+ * production caller (`registerBrain()` below), with no disk-walk discovery
+ * of its own. Disk reads only happen in `collector.ts`, and only for a
+ * brain already present in that Map. Skipping the metrics seed here would
+ * reproduce the exact same restart-amnesia bug for metrics that this whole
+ * change exists to fix for maintenance: a quiet brain would get maintenance
+ * triggers again, but zero metrics until someone messages it.
+ *
+ * Deliberately does NOT replicate `registerBrain()`'s *immediate*
+ * collect+send side effect (the `if (isNew) { void (async () => ... })()`
+ * block below) — only the Map insert. Firing an immediate collect+send for
+ * every brain this poller owns, all at once, on every restart would be a
+ * fleet-wide burst; the existing hourly cron with its per-brain jitter
+ * (`collectAndSendAll`, `jitterMsFor`) already picks up newly-registered
+ * brains on its own schedule without a startup spike.
+ *
+ * Returns the number of brains actually seeded (for startup logging).
+ */
+export declare function seedTrackedBrains(brains: readonly BootstrapBrainInfo[]): number;
 /**
  * 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

@@ -6,7 +6,8 @@ import { emitError } from './event-queue.js';
 import { registerBrainForMetrics } from './metrics/scheduler.js';
 import { collectMetrics } from './metrics/collector.js';
 import { sendMetrics } from './metrics/sender.js';
-import { markMaintenanceJobFired, markMaintenanceJobSuccess, } from './cron-telemetry.js';
+import { markMaintenanceJobFired, markMaintenanceJobSuccess, markMaintenanceJobSkipped, } from './cron-telemetry.js';
+import { shouldSkipMaintenance } from './maintenance-activity.js';
 import { join } from 'path';
 const trackedBrains = new Map();
 /**
@@ -17,7 +18,84 @@ const trackedBrains = new Map();
 export function getTrackedBrains() {
     return trackedBrains;
 }
+/**
+ * Test-only helper to clear tracked brains between tests (module-scoped
+ * state persists across tests in the same file otherwise).
+ * @internal
+ */
+export function __resetTrackedBrainsForTest() {
+    trackedBrains.clear();
+}
 let maintenanceJob = null;
+/**
+ * Seed trackedBrains at startup from the backend's authoritative brain list
+ * (teamvibe.ai#127) so a "quiet" brain — one that hasn't received a real
+ * message since this poller process started — still gets included in the
+ * maintenance/heartbeat cron, instead of being silently invisible until a
+ * human happens to message it.
+ *
+ * Deliberately does NOT set `lastRealMessageAt` (left undefined). That
+ * field specifically means "we've seen a real message since our own last
+ * restart" — shouldSkipMaintenance (maintenance-activity.ts, #131) treats
+ * `undefined` as fail-open (never skip) for exactly this reason. Bootstrap
+ * seeding isn't a real message; claiming one occurred here would risk the
+ * opposite bug — a genuinely-quiet brain wrongly evaluated as "nothing new,
+ * skip" on its very first post-restart cron tick.
+ *
+ * Skips (rather than overwrites) any brainId already present in
+ * trackedBrains. This guard is load-bearing, not just defensive (DevGuru
+ * review, round 4): since round 3's critical-path detachment
+ * (brains-bootstrap.ts's `void (async () => {...})()` retry), the retry
+ * branch can finish AFTER startPoller() has already returned and real user
+ * messages have started arriving. That means a real registerBrain() call
+ * for a brain (which sets `lastRealMessageAt`) can race ahead of — and
+ * complete before — the detached bootstrap retry's seedTrackedBrains()
+ * call for that same brain. Without this skip, the late-arriving bootstrap
+ * seed would silently overwrite the real registration back to a fresh
+ * entry with `lastRealMessageAt: undefined`, losing real activity data
+ * (and, per the fail-open contract above, artificially reopening the
+ * skip-maintenance window for a brain that's actually been active).
+ *
+ * DOES also register each seeded brain for hourly metrics (see
+ * `registerBrainForMetrics` below) — DevGuru review caught that this
+ * module's original "metrics has its own disk-walk path" reasoning was
+ * wrong: `metrics/scheduler.ts`'s `registered` Map has exactly one
+ * production caller (`registerBrain()` below), with no disk-walk discovery
+ * of its own. Disk reads only happen in `collector.ts`, and only for a
+ * brain already present in that Map. Skipping the metrics seed here would
+ * reproduce the exact same restart-amnesia bug for metrics that this whole
+ * change exists to fix for maintenance: a quiet brain would get maintenance
+ * triggers again, but zero metrics until someone messages it.
+ *
+ * Deliberately does NOT replicate `registerBrain()`'s *immediate*
+ * collect+send side effect (the `if (isNew) { void (async () => ... })()`
+ * block below) — only the Map insert. Firing an immediate collect+send for
+ * every brain this poller owns, all at once, on every restart would be a
+ * fleet-wide burst; the existing hourly cron with its per-brain jitter
+ * (`collectAndSendAll`, `jitterMsFor`) already picks up newly-registered
+ * brains on its own schedule without a startup spike.
+ *
+ * Returns the number of brains actually seeded (for startup logging).
+ */
+export function seedTrackedBrains(brains) {
+    let seeded = 0;
+    for (const b of brains) {
+        if (trackedBrains.has(b.brainId))
+            continue;
+        trackedBrains.set(b.brainId, {
+            brainId: b.brainId,
+            gitRepoUrl: b.gitRepoUrl,
+            branch: b.branch,
+            workspaceId: b.workspaceId,
+            botId: b.botId,
+            botToken: b.botToken,
+            channelId: b.channelId,
+        });
+        registerBrainForMetrics(b.brainId);
+        seeded++;
+    }
+    return seeded;
+}
 /**
  * Register a brain from a real message so the maintenance cron knows about it.
  * Called from processMessage() after brain path is resolved.
@@ -38,6 +116,7 @@ export function registerBrain(msg) {
         botId: msg.teamvibe.botId,
         botToken: msg.teamvibe.botToken,
         channelId: msg.teamvibe.channelId,
+        lastRealMessageAt: Date.now(),
     });
     logger.debug(`[Maintenance] Registered brain: ${brain.brainId}`);
     // Metrics pipeline (teamvibe.ai#110): register for hourly collection. On the
@@ -68,6 +147,11 @@ async function triggerAllBrains(processMessageFn) {
             logger.debug(`[Maintenance] At capacity, skipping ${brainId}`);
             continue;
         }
+        if (await shouldSkipMaintenance(config.BRAINS_PATH, brainId, info.lastRealMessageAt)) {
+            markMaintenanceJobSkipped();
+            logger.debug(`[Maintenance] Skipping ${brainId} — no real activity since last maintenance (#131)`);
+            continue;
+        }
         logger.info(`[Maintenance] Triggering maintenance for brain ${brainId}`);
         const syntheticMessage = {
             id: `maintenance_${brainId}_${now}`,

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,4 +1,6 @@
 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;
@@ -22,6 +24,16 @@ export declare function runAutoUpdateJob(checkForUpdateFn?: () => Promise<boolea
  * 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 describeFailureReason(killedByPoller: KilledByPoller | undefined, exitCode: number | null): string;
+export declare const END_OF_TURN_NO_FURTHER_RESPONSE_SENTINEL = "NO_FURTHER_RESPONSE_NEEDED";
+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 __setSleepForTest(impl: (ms: number) => Promise<void>): void;
+export declare function __setShuttingDownForTest(value: boolean): void;
 export declare function startPoller(): Promise<void>;
 export {};