@teamvibe/poller 0.2.5 → 0.4.0

package/dist/cron-telemetry.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Module-scoped state for poller-level cron-job telemetry.
+ *
+ * Per teamvibeai/teamvibe.ai#119, the metrics collector reports six measures:
+ *   last{Heartbeat,Maintenance,AutoUpdate}Job{,Success}Ms
+ * each computed as `Date.now() - storedTs` at collection time, with the
+ * measure omitted entirely when the cron has never fired (storedTs null).
+ *
+ * Pulled out of heartbeat-manager.ts / poller.ts into a dedicated module to
+ * avoid a circular import — the metrics collector reads from these getters,
+ * and heartbeat-manager.ts already imports from the collector.
+ */
+export declare function markHeartbeatJobFired(at?: number): void;
+export declare function markHeartbeatJobSuccess(at?: number): void;
+export declare function markMaintenanceJobFired(at?: number): void;
+export declare function markMaintenanceJobSuccess(at?: number): void;
+export declare function markAutoUpdateJobFired(at?: number): void;
+export declare function markAutoUpdateJobSuccess(at?: number): void;
+export interface CronJobTimestamps {
+    lastHeartbeatJobFiredAt: number | null;
+    lastHeartbeatJobSuccessAt: number | null;
+    lastMaintenanceJobFiredAt: number | null;
+    lastMaintenanceJobSuccessAt: number | null;
+    lastAutoUpdateJobFiredAt: number | null;
+    lastAutoUpdateJobSuccessAt: number | null;
+}
+export declare function getCronJobTimestamps(): CronJobTimestamps;
+/**
+ * Test-only helper to clear telemetry between tests.
+ * @internal
+ */
+export declare function __resetCronTelemetryForTest(): void;

package/dist/cron-telemetry.js

@@ -0,0 +1,58 @@
+/**
+ * Module-scoped state for poller-level cron-job telemetry.
+ *
+ * Per teamvibeai/teamvibe.ai#119, the metrics collector reports six measures:
+ *   last{Heartbeat,Maintenance,AutoUpdate}Job{,Success}Ms
+ * each computed as `Date.now() - storedTs` at collection time, with the
+ * measure omitted entirely when the cron has never fired (storedTs null).
+ *
+ * Pulled out of heartbeat-manager.ts / poller.ts into a dedicated module to
+ * avoid a circular import — the metrics collector reads from these getters,
+ * and heartbeat-manager.ts already imports from the collector.
+ */
+let lastHeartbeatJobFiredAt = null;
+let lastHeartbeatJobSuccessAt = null;
+let lastMaintenanceJobFiredAt = null;
+let lastMaintenanceJobSuccessAt = null;
+let lastAutoUpdateJobFiredAt = null;
+let lastAutoUpdateJobSuccessAt = null;
+export function markHeartbeatJobFired(at = Date.now()) {
+    lastHeartbeatJobFiredAt = at;
+}
+export function markHeartbeatJobSuccess(at = Date.now()) {
+    lastHeartbeatJobSuccessAt = at;
+}
+export function markMaintenanceJobFired(at = Date.now()) {
+    lastMaintenanceJobFiredAt = at;
+}
+export function markMaintenanceJobSuccess(at = Date.now()) {
+    lastMaintenanceJobSuccessAt = at;
+}
+export function markAutoUpdateJobFired(at = Date.now()) {
+    lastAutoUpdateJobFiredAt = at;
+}
+export function markAutoUpdateJobSuccess(at = Date.now()) {
+    lastAutoUpdateJobSuccessAt = at;
+}
+export function getCronJobTimestamps() {
+    return {
+        lastHeartbeatJobFiredAt,
+        lastHeartbeatJobSuccessAt,
+        lastMaintenanceJobFiredAt,
+        lastMaintenanceJobSuccessAt,
+        lastAutoUpdateJobFiredAt,
+        lastAutoUpdateJobSuccessAt,
+    };
+}
+/**
+ * Test-only helper to clear telemetry between tests.
+ * @internal
+ */
+export function __resetCronTelemetryForTest() {
+    lastHeartbeatJobFiredAt = null;
+    lastHeartbeatJobSuccessAt = null;
+    lastMaintenanceJobFiredAt = null;
+    lastMaintenanceJobSuccessAt = null;
+    lastAutoUpdateJobFiredAt = null;
+    lastAutoUpdateJobSuccessAt = null;
+}

package/dist/heartbeat-manager.d.ts

@@ -15,6 +15,24 @@ export declare function startHeartbeatLoop(processMessageFn: (msg: {
     receiptHandle: string;
     messageId: string;
 }) => Promise<void>): void;
+/**
+ * Run the heartbeat cron handler with telemetry instrumentation (#119).
+ * Records last-fire timestamp on entry and last-success timestamp on completion.
+ * Exported for use by the cron registration above and tests that fire it manually.
+ */
+export declare function runHeartbeatJob(processMessageFn: (msg: {
+    queueMessage: TeamVibeQueueMessage;
+    receiptHandle: string;
+    messageId: string;
+}) => Promise<void>): Promise<void>;
+/**
+ * Run the maintenance cron handler with telemetry instrumentation (#119).
+ */
+export declare function runMaintenanceJob(processMessageFn: (msg: {
+    queueMessage: TeamVibeQueueMessage;
+    receiptHandle: string;
+    messageId: string;
+}) => Promise<void>): Promise<void>;
 /**
  * Stop the heartbeat and maintenance crons (for shutdown).
  */

package/dist/heartbeat-manager.js

@@ -3,6 +3,11 @@ import { config } from './config.js';
 import { logger } from './logger.js';
 import { isAtCapacity } from './claude-spawner.js';
 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 { markHeartbeatJobFired, markHeartbeatJobSuccess, markMaintenanceJobFired, markMaintenanceJobSuccess, } from './cron-telemetry.js';
+import { join } from 'path';
 const trackedBrains = new Map();
 let heartbeatJob = null;
 let maintenanceJob = null;
@@ -17,6 +22,7 @@ export function registerBrain(msg) {
     // Don't register from heartbeat/maintenance messages (avoid self-referential loop)
     if (msg.source === 'heartbeat' || msg.source === 'maintenance')
         return;
+    const isNew = !trackedBrains.has(brain.brainId);
     trackedBrains.set(brain.brainId, {
         brainId: brain.brainId,
         gitRepoUrl: brain.gitRepoUrl,
@@ -27,6 +33,23 @@ export function registerBrain(msg) {
         channelId: msg.teamvibe.channelId,
     });
     logger.debug(`[Heartbeat] Registered brain: ${brain.brainId}`);
+    // Metrics pipeline (teamvibe.ai#110): register for hourly collection. On the
+    // first sighting of this brain, fire one immediate collect+send so we don't
+    // wait up to an hour for the first sample.
+    registerBrainForMetrics(brain.brainId);
+    if (isNew) {
+        const brainId = brain.brainId;
+        void (async () => {
+            try {
+                const brainPath = join(config.BRAINS_PATH, brainId);
+                const payload = await collectMetrics(brainPath, brainId);
+                await sendMetrics(payload);
+            }
+            catch (err) {
+                logger.warn(`[Metrics] Initial send failed for ${brainId}: ${err instanceof Error ? err.message : err}`);
+            }
+        })();
+    }
 }
 /**
  * Send a synthetic message to all tracked brains.
@@ -93,14 +116,44 @@ export function startHeartbeatLoop(processMessageFn) {
     // Heartbeat cron — frequent, lightweight
     logger.info(`[Heartbeat] Starting heartbeat cron: "${config.HEARTBEAT_CRON}"`);
     heartbeatJob = new Cron(config.HEARTBEAT_CRON, { timezone: 'UTC', protect: true }, async () => {
-        await triggerAllBrains('heartbeat', processMessageFn);
+        await runHeartbeatJob(processMessageFn);
     });
     // Maintenance cron — daily, heavy (consolidation, memory cleanup)
     logger.info(`[Maintenance] Starting maintenance cron: "${config.MAINTENANCE_CRON}"`);
     maintenanceJob = new Cron(config.MAINTENANCE_CRON, { timezone: 'UTC', protect: true }, async () => {
-        await triggerAllBrains('maintenance', processMessageFn);
+        await runMaintenanceJob(processMessageFn);
     });
 }
+/**
+ * Run the heartbeat cron handler with telemetry instrumentation (#119).
+ * Records last-fire timestamp on entry and last-success timestamp on completion.
+ * Exported for use by the cron registration above and tests that fire it manually.
+ */
+export async function runHeartbeatJob(processMessageFn) {
+    markHeartbeatJobFired();
+    try {
+        await triggerAllBrains('heartbeat', processMessageFn);
+        markHeartbeatJobSuccess();
+    }
+    catch (e) {
+        logger.error(`[Heartbeat] heartbeatJob handler threw: ${e instanceof Error ? e.message : e}`);
+        throw e; // preserve existing behavior; croner protect handles overlap
+    }
+}
+/**
+ * Run the maintenance cron handler with telemetry instrumentation (#119).
+ */
+export async function runMaintenanceJob(processMessageFn) {
+    markMaintenanceJobFired();
+    try {
+        await triggerAllBrains('maintenance', processMessageFn);
+        markMaintenanceJobSuccess();
+    }
+    catch (e) {
+        logger.error(`[Maintenance] maintenanceJob handler threw: ${e instanceof Error ? e.message : e}`);
+        throw e;
+    }
+}
 /**
  * Stop the heartbeat and maintenance crons (for shutdown).
  */

package/dist/metrics/collector.d.ts

@@ -0,0 +1,34 @@
+/**
+ * v1 metrics payload — see teamvibeai/teamvibe.ai#110 (revised post-review 2026-05-21).
+ *
+ * All measures are OPTIONAL: a missing field means "this measure could not be
+ * collected" (file absent, glob failed, command unavailable, etc.). Timestream
+ * handles sparse measures natively — never send a zero in place of a real omission.
+ */
+export interface MetricsPayload {
+    brainId: string;
+    todayMdBytes?: number;
+    todayMdLines?: number;
+    summaryMdBytes?: number;
+    summaryMdLines?: number;
+    brainDirBytes?: number;
+    vmDiskFreeBytes?: number;
+    vmDiskUsedBytes?: number;
+    inboxUnreadFiles?: number;
+    inboxTotalFiles?: number;
+    oldestInboxMessageAgeSeconds?: number;
+    uncommittedChangeCount?: number;
+    daysSinceMaintenance?: number;
+    lastHeartbeatJobMs?: number;
+    lastHeartbeatJobSuccessMs?: number;
+    lastMaintenanceJobMs?: number;
+    lastMaintenanceJobSuccessMs?: number;
+    lastAutoUpdateJobMs?: number;
+    lastAutoUpdateJobSuccessMs?: number;
+    timestamp?: string;
+}
+/**
+ * Collect all v1 metrics for a brain. Never throws — individual collector
+ * failures cause the corresponding measure to be omitted from the result.
+ */
+export declare function collectMetrics(brainPath: string, brainId: string): Promise<MetricsPayload>;

package/dist/metrics/collector.js

@@ -0,0 +1,238 @@
+import { stat, readdir, readFile } from 'fs/promises';
+import { statfs } from 'fs';
+import { promisify } from 'util';
+import { execFile } from 'child_process';
+import { join } from 'path';
+import { getCronJobTimestamps } from '../cron-telemetry.js';
+const statfsAsync = promisify(statfs);
+const execFileAsync = promisify(execFile);
+const MS_PER_DAY = 86_400_000;
+/**
+ * Recursively sum file sizes under a directory.
+ * Skips entries we cannot stat (permission errors, broken symlinks).
+ */
+async function dirSizeBytes(path) {
+    let total = 0;
+    let entries;
+    try {
+        entries = await readdir(path, { withFileTypes: true });
+    }
+    catch {
+        return 0;
+    }
+    for (const entry of entries) {
+        const full = join(path, entry.name);
+        try {
+            if (entry.isDirectory()) {
+                total += await dirSizeBytes(full);
+            }
+            else if (entry.isFile()) {
+                const s = await stat(full);
+                total += s.size;
+            }
+            // Skip symlinks/sockets/etc.
+        }
+        catch {
+            // Single broken entry shouldn't tank the whole walk.
+        }
+    }
+    return total;
+}
+/**
+ * Count newline characters in a file. Returns line count using newline-count
+ * semantics (a trailing newline = N lines, no trailing newline = N-1 lines —
+ * matches what `wc -l` would have reported).
+ */
+async function countLines(path) {
+    const content = await readFile(path, 'utf-8');
+    let count = 0;
+    for (let i = 0; i < content.length; i++) {
+        if (content.charCodeAt(i) === 10 /* \n */)
+            count++;
+    }
+    return count;
+}
+/**
+ * Find files matching .inbox/<thread>/new/* under brainPath.
+ * Returns absolute paths. Throws if the .inbox directory itself is unreadable —
+ * caller wraps in try/catch and omits the measure on any failure.
+ */
+async function listInboxUnreadFiles(brainPath) {
+    const inboxRoot = join(brainPath, '.inbox');
+    const threads = (await readdir(inboxRoot, { withFileTypes: true }));
+    const files = [];
+    for (const t of threads) {
+        if (!t.isDirectory())
+            continue;
+        const newDir = join(inboxRoot, t.name, 'new');
+        let entries;
+        try {
+            entries = (await readdir(newDir, { withFileTypes: true }));
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (e.isFile())
+                files.push(join(newDir, e.name));
+        }
+    }
+    return files;
+}
+/**
+ * Count regular files anywhere under brainPath/.inbox.
+ */
+async function countInboxTotalFiles(brainPath) {
+    const inboxRoot = join(brainPath, '.inbox');
+    let count = 0;
+    async function walk(dir) {
+        let entries;
+        try {
+            entries = (await readdir(dir, { withFileTypes: true }));
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const full = join(dir, e.name);
+            if (e.isDirectory()) {
+                await walk(full);
+            }
+            else if (e.isFile()) {
+                count++;
+            }
+        }
+    }
+    await walk(inboxRoot);
+    return count;
+}
+/**
+ * Collect all v1 metrics for a brain. Never throws — individual collector
+ * failures cause the corresponding measure to be omitted from the result.
+ */
+export async function collectMetrics(brainPath, brainId) {
+    const payload = {
+        brainId,
+        timestamp: new Date().toISOString(),
+    };
+    // memory/TODAY.md size + line count
+    try {
+        const todayPath = join(brainPath, 'memory/TODAY.md');
+        const s = await stat(todayPath);
+        payload.todayMdBytes = s.size;
+        payload.todayMdLines = await countLines(todayPath);
+    }
+    catch {
+        // File missing or unreadable — omit both measures.
+    }
+    // memory/SUMMARY.md size + line count
+    try {
+        const summaryPath = join(brainPath, 'memory/SUMMARY.md');
+        const s = await stat(summaryPath);
+        payload.summaryMdBytes = s.size;
+        payload.summaryMdLines = await countLines(summaryPath);
+    }
+    catch {
+        // omit
+    }
+    // brain dir total size
+    try {
+        payload.brainDirBytes = await dirSizeBytes(brainPath);
+    }
+    catch {
+        // omit
+    }
+    // VM disk usage (root filesystem)
+    try {
+        const fs = await statfsAsync('/');
+        // fs.bsize × fs.bfree = free bytes
+        // fs.bsize × (fs.blocks - fs.bfree) = used bytes
+        payload.vmDiskFreeBytes = fs.bsize * fs.bfree;
+        payload.vmDiskUsedBytes = fs.bsize * (fs.blocks - fs.bfree);
+    }
+    catch {
+        // omit
+    }
+    // days since maintenance — fractional, from .last_consolidation mtime
+    try {
+        const guardPath = join(brainPath, 'memory/.last_consolidation');
+        const s = await stat(guardPath);
+        payload.daysSinceMaintenance = (Date.now() - s.mtimeMs) / MS_PER_DAY;
+    }
+    catch {
+        // Guard file may legitimately not exist (new brain, never consolidated).
+        // Omit rather than send a misleading 0.
+    }
+    // Inbox: unread files (.inbox/<thread>/new/*)
+    try {
+        const unread = await listInboxUnreadFiles(brainPath);
+        payload.inboxUnreadFiles = unread.length;
+        // Oldest unread message age — same source, single walk would be cheaper
+        // but we already have the paths and the volume is small.
+        if (unread.length === 0) {
+            payload.oldestInboxMessageAgeSeconds = 0;
+        }
+        else {
+            let minMtime = Infinity;
+            for (const f of unread) {
+                try {
+                    const s = await stat(f);
+                    if (s.mtimeMs < minMtime)
+                        minMtime = s.mtimeMs;
+                }
+                catch {
+                    // skip
+                }
+            }
+            if (minMtime !== Infinity) {
+                payload.oldestInboxMessageAgeSeconds = Math.floor((Date.now() - minMtime) / 1000);
+            }
+        }
+    }
+    catch {
+        // Per Jarvis's review: different poller versions may lay out .inbox/ differently.
+        // Omit measures rather than fail the batch.
+    }
+    // Inbox: total files (anywhere under .inbox)
+    try {
+        payload.inboxTotalFiles = await countInboxTotalFiles(brainPath);
+    }
+    catch {
+        // omit
+    }
+    // Uncommitted change count — git status --porcelain
+    try {
+        const { stdout } = await execFileAsync('git', ['-C', brainPath, 'status', '--porcelain'], {
+            timeout: 5000,
+        });
+        // Each non-empty line = one tracked change.
+        payload.uncommittedChangeCount = stdout.split('\n').filter((l) => l.length > 0).length;
+    }
+    catch {
+        // Non-git brain, missing git binary, timeout — omit.
+    }
+    // Poller-level cron-job telemetry (#119). Same six values for every brain on
+    // the poller — see issue body for storage cost rationale. Each measure is
+    // `now - storedTs`; if the cron has never fired (storedTs null), omit it.
+    const now = Date.now();
+    const cron = getCronJobTimestamps();
+    if (cron.lastHeartbeatJobFiredAt !== null) {
+        payload.lastHeartbeatJobMs = now - cron.lastHeartbeatJobFiredAt;
+    }
+    if (cron.lastHeartbeatJobSuccessAt !== null) {
+        payload.lastHeartbeatJobSuccessMs = now - cron.lastHeartbeatJobSuccessAt;
+    }
+    if (cron.lastMaintenanceJobFiredAt !== null) {
+        payload.lastMaintenanceJobMs = now - cron.lastMaintenanceJobFiredAt;
+    }
+    if (cron.lastMaintenanceJobSuccessAt !== null) {
+        payload.lastMaintenanceJobSuccessMs = now - cron.lastMaintenanceJobSuccessAt;
+    }
+    if (cron.lastAutoUpdateJobFiredAt !== null) {
+        payload.lastAutoUpdateJobMs = now - cron.lastAutoUpdateJobFiredAt;
+    }
+    if (cron.lastAutoUpdateJobSuccessAt !== null) {
+        payload.lastAutoUpdateJobSuccessMs = now - cron.lastAutoUpdateJobSuccessAt;
+    }
+    return payload;
+}

package/dist/metrics/scheduler.d.ts

@@ -0,0 +1,52 @@
+interface RegisteredBrain {
+    brainId: string;
+}
+/**
+ * Register (or update) a brain for hourly metrics collection.
+ * Safe to call repeatedly with the same brainId.
+ */
+export declare function registerBrainForMetrics(brainId: string): void;
+/**
+ * Deterministic 32-bit FNV-1a hash of a string. Used to derive a stable
+ * per-brain jitter offset for hourly cron alignment (see #110 review):
+ * at fleet scale (100+ brains) we don't want every brain to fire at exactly
+ * UTC :00:00 — Lambda cold-start storm + Timestream write throttle risk.
+ *
+ * No crypto needed; we only need a stable, well-distributed integer.
+ */
+export declare function hashBrainId(s: string): number;
+/**
+ * Per-brain deterministic jitter offset in [0, JITTER_WINDOW_MS).
+ * Two brains with different ids should normally land on different offsets;
+ * the same brain id always lands on the same offset.
+ */
+export declare function jitterMsFor(brainId: string): number;
+/**
+ * Cron handler: fan out to every registered brain on its deterministic
+ * per-brain jitter offset (0–10 min after UTC :00). This avoids a thundering
+ * herd of metric writes at the exact hour boundary while keeping the
+ * per-brain offset stable (= no clock drift across hours).
+ *
+ * Exported for tests so they can fire the handler manually.
+ */
+export declare function collectAndSendAll(): void;
+/**
+ * Start the hourly metrics cron. Fires once per UTC hour boundary; each tick
+ * fans out per-brain on a deterministic jitter offset (0–10min).
+ *
+ * Idempotent: re-invocation while already running is a no-op.
+ */
+export declare function startMetricsCron(): void;
+/**
+ * Stop the metrics cron. Safe to call multiple times.
+ */
+export declare function stopMetricsCron(): void;
+/**
+ * Test-only: clear registered brain list.
+ */
+export declare function _resetForTests(): void;
+/**
+ * Test-only: read registered brains (returns a snapshot copy).
+ */
+export declare function _getRegisteredForTests(): RegisteredBrain[];
+export {};

package/dist/metrics/scheduler.js

@@ -0,0 +1,127 @@
+import { join } from 'path';
+import { Cron } from 'croner';
+import { config } from '../config.js';
+import { logger } from '../logger.js';
+import { collectMetrics } from './collector.js';
+import { sendMetrics } from './sender.js';
+const JITTER_WINDOW_MS = 10 * 60 * 1000; // 10 minutes spread per #110 review
+const registered = new Map();
+const pendingJitterTimers = new Set();
+let metricsJob = null;
+/**
+ * Register (or update) a brain for hourly metrics collection.
+ * Safe to call repeatedly with the same brainId.
+ */
+export function registerBrainForMetrics(brainId) {
+    if (!brainId)
+        return;
+    registered.set(brainId, { brainId });
+}
+/**
+ * Collect + send metrics for a single brain. Never throws.
+ */
+async function collectAndSendOne(brain) {
+    try {
+        const brainPath = join(config.BRAINS_PATH, brain.brainId);
+        const payload = await collectMetrics(brainPath, brain.brainId);
+        await sendMetrics(payload);
+    }
+    catch (err) {
+        // Defensive: collector/sender already swallow their own errors, but if
+        // anything escapes (e.g. path resolution, unexpected runtime fault) we
+        // log and move on rather than crashing the cron tick.
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.warn(`[Metrics] Unexpected failure for brain ${brain.brainId}: ${msg}`);
+    }
+}
+/**
+ * Deterministic 32-bit FNV-1a hash of a string. Used to derive a stable
+ * per-brain jitter offset for hourly cron alignment (see #110 review):
+ * at fleet scale (100+ brains) we don't want every brain to fire at exactly
+ * UTC :00:00 — Lambda cold-start storm + Timestream write throttle risk.
+ *
+ * No crypto needed; we only need a stable, well-distributed integer.
+ */
+export function hashBrainId(s) {
+    let h = 0x811c9dc5; // FNV offset basis
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        // FNV prime is 0x01000193; use Math.imul for 32-bit overflow semantics.
+        h = Math.imul(h, 0x01000193);
+    }
+    // Coerce to unsigned 32-bit.
+    return h >>> 0;
+}
+/**
+ * Per-brain deterministic jitter offset in [0, JITTER_WINDOW_MS).
+ * Two brains with different ids should normally land on different offsets;
+ * the same brain id always lands on the same offset.
+ */
+export function jitterMsFor(brainId) {
+    return hashBrainId(brainId) % JITTER_WINDOW_MS;
+}
+/**
+ * Cron handler: fan out to every registered brain on its deterministic
+ * per-brain jitter offset (0–10 min after UTC :00). This avoids a thundering
+ * herd of metric writes at the exact hour boundary while keeping the
+ * per-brain offset stable (= no clock drift across hours).
+ *
+ * Exported for tests so they can fire the handler manually.
+ */
+export function collectAndSendAll() {
+    if (registered.size === 0)
+        return;
+    const brains = Array.from(registered.values());
+    for (const brain of brains) {
+        const delay = jitterMsFor(brain.brainId);
+        const timer = setTimeout(() => {
+            pendingJitterTimers.delete(timer);
+            void collectAndSendOne(brain);
+        }, delay);
+        pendingJitterTimers.add(timer);
+    }
+}
+/**
+ * Start the hourly metrics cron. Fires once per UTC hour boundary; each tick
+ * fans out per-brain on a deterministic jitter offset (0–10min).
+ *
+ * Idempotent: re-invocation while already running is a no-op.
+ */
+export function startMetricsCron() {
+    if (metricsJob)
+        return;
+    if (!config.TEAMVIBE_API_URL || !config.TEAMVIBE_POLLER_TOKEN) {
+        // No-op in direct (non-token) mode.
+        return;
+    }
+    logger.info('[Metrics] Starting hourly cron: "0 * * * *" UTC (per-brain jitter 0–10min)');
+    metricsJob = new Cron('0 * * * *', { timezone: 'UTC', protect: true }, () => {
+        collectAndSendAll();
+    });
+}
+/**
+ * Stop the metrics cron. Safe to call multiple times.
+ */
+export function stopMetricsCron() {
+    if (metricsJob) {
+        metricsJob.stop();
+        metricsJob = null;
+    }
+    for (const timer of pendingJitterTimers) {
+        clearTimeout(timer);
+    }
+    pendingJitterTimers.clear();
+}
+/**
+ * Test-only: clear registered brain list.
+ */
+export function _resetForTests() {
+    registered.clear();
+    stopMetricsCron();
+}
+/**
+ * Test-only: read registered brains (returns a snapshot copy).
+ */
+export function _getRegisteredForTests() {
+    return Array.from(registered.values());
+}

package/dist/metrics/sender.d.ts

@@ -0,0 +1,10 @@
+import type { MetricsPayload } from './collector.js';
+/**
+ * Send a metrics payload to the platform. Fail-safe:
+ * - 5s timeout per attempt
+ * - 1 retry after 30s on non-2xx or network failure
+ * - Never throws
+ *
+ * Returns true on success, false if both attempts failed (caller can log/ignore).
+ */
+export declare function sendMetrics(payload: MetricsPayload): Promise<boolean>;

package/dist/metrics/sender.js

@@ -0,0 +1,58 @@
+import { config } from '../config.js';
+import { logger } from '../logger.js';
+const SEND_TIMEOUT_MS = 5_000;
+const RETRY_DELAY_MS = 30_000;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function postOnce(payload) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), SEND_TIMEOUT_MS);
+    try {
+        const response = await fetch(`${config.TEAMVIBE_API_URL}/metrics`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${config.TEAMVIBE_POLLER_TOKEN}`,
+            },
+            body: JSON.stringify(payload),
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            logger.warn(`[Metrics] Send failed: ${response.status} for brain ${payload.brainId}`);
+            return false;
+        }
+        return true;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.warn(`[Metrics] Send error for brain ${payload.brainId}: ${msg}`);
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Send a metrics payload to the platform. Fail-safe:
+ * - 5s timeout per attempt
+ * - 1 retry after 30s on non-2xx or network failure
+ * - Never throws
+ *
+ * Returns true on success, false if both attempts failed (caller can log/ignore).
+ */
+export async function sendMetrics(payload) {
+    if (!config.TEAMVIBE_API_URL || !config.TEAMVIBE_POLLER_TOKEN) {
+        // Direct (non-token) mode — metrics endpoint isn't reachable. No-op.
+        return false;
+    }
+    const ok = await postOnce(payload);
+    if (ok)
+        return true;
+    await sleep(RETRY_DELAY_MS);
+    const retried = await postOnce(payload);
+    if (!retried) {
+        logger.warn(`[Metrics] Dropping payload for brain ${payload.brainId} after 1 retry`);
+    }
+    return retried;
+}

package/dist/poller.d.ts

@@ -1 +1,11 @@
+/**
+ * Run the auto-update cron handler with telemetry instrumentation (#119).
+ * Exported for tests that fire the handler manually.
+ *
+ * `checkForUpdateFn` is injected (default = real checkForUpdate) so tests
+ * can lock in the "swallow but still mark fired" contract that
+ * distinguishes scenario (A) cron-doesn't-fire from (B/C) cron-fires-but-fails
+ * in morning-check telemetry. Same DI shape as runHeartbeatJob/runMaintenanceJob.
+ */
+export declare function runAutoUpdateJob(checkForUpdateFn?: () => Promise<boolean>): Promise<void>;
 export declare function startPoller(): Promise<void>;

package/dist/poller.js

@@ -9,10 +9,12 @@ import { postMaintenanceReports } from './maintenance-reporter.js';
 import { initAuth, stopRefresh } from './auth-provider.js';
 import { registerBrain, startHeartbeatLoop, stopHeartbeatLoop } from './heartbeat-manager.js';
 import { startEventQueue, stopEventQueue, flush as flushEventQueue, emitEvent } from './event-queue.js';
+import { startMetricsCron, stopMetricsCron } from './metrics/scheduler.js';
 import { writeMessage, pickNextMessage, markProcessed, markFailed, hasUnprocessed } from './inbox-manager.js';
 import { Cron } from 'croner';
 import { isControlMessage, handleControlMessage } from './control-handler.js';
 import { checkForUpdate } from './auto-update.js';
+import { markAutoUpdateJobFired, markAutoUpdateJobSuccess } from './cron-telemetry.js';
 import { exec } from 'child_process';
 import { promisify } from 'util';
 import { platform } from 'os';
@@ -21,6 +23,30 @@ const execAsync = promisify(exec);
 const processingMessages = new Set();
 // Poller auto-update cron (separate from brain heartbeats)
 let autoUpdateJob = null;
+/**
+ * Run the auto-update cron handler with telemetry instrumentation (#119).
+ * Exported for tests that fire the handler manually.
+ *
+ * `checkForUpdateFn` is injected (default = real checkForUpdate) so tests
+ * can lock in the "swallow but still mark fired" contract that
+ * distinguishes scenario (A) cron-doesn't-fire from (B/C) cron-fires-but-fails
+ * in morning-check telemetry. Same DI shape as runHeartbeatJob/runMaintenanceJob.
+ */
+export async function runAutoUpdateJob(checkForUpdateFn = checkForUpdate) {
+    markAutoUpdateJobFired();
+    try {
+        const shouldRestart = await checkForUpdateFn();
+        markAutoUpdateJobSuccess();
+        if (shouldRestart) {
+            logger.info('[AutoUpdate] Update applied, restarting...');
+            await flushEventQueue();
+            process.exit(0);
+        }
+    }
+    catch (error) {
+        logger.error(`[AutoUpdate] Check error: ${error instanceof Error ? error.message : error}`);
+    }
+}
 function startAutoUpdateCron() {
     const schedule = config.AUTO_UPDATE_SCHEDULE;
     const match = schedule.match(/^(\d{2}):(\d{2})$/);
@@ -34,17 +60,7 @@ function startAutoUpdateCron() {
     const cronExpr = `${match[2]} ${match[1]} * * *`;
     logger.info(`[AutoUpdate] Scheduled daily at ${schedule} UTC (cron: ${cronExpr}), policy: ${config.AUTO_UPDATE_POLICY}`);
     autoUpdateJob = new Cron(cronExpr, { timezone: 'UTC' }, async () => {
-        try {
-            const shouldRestart = await checkForUpdate();
-            if (shouldRestart) {
-                logger.info('[AutoUpdate] Update applied, restarting...');
-                await flushEventQueue();
-                process.exit(0);
-            }
-        }
-        catch (error) {
-            logger.error(`[AutoUpdate] Check error: ${error instanceof Error ? error.message : error}`);
-        }
+        await runAutoUpdateJob();
     });
 }
 function stopAutoUpdateCron() {
@@ -464,6 +480,7 @@ async function shutdown(signal, exitCode = 0) {
     stopRefresh();
     stopHeartbeatLoop();
     stopAutoUpdateCron();
+    stopMetricsCron();
     stopEventQueue();
     // Kill all active Claude child processes
     await killAllActiveProcesses();
@@ -502,5 +519,6 @@ export async function startPoller() {
     await ensureBaseBrain();
     startHeartbeatLoop(processMessage);
     startAutoUpdateCron();
+    startMetricsCron();
     await pollLoop();
 }

package/package.json

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