@telora/daemon 0.21.26 → 0.21.82

package/dist/shell/heartbeat.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Heartbeat module — periodically reports daemon presence and work status to Telora.
+ *
+ * Sends an initial heartbeat on startup, then every HEARTBEAT_INTERVAL_MS.
+ * On shutdown, sends a disconnect signal (best-effort).
+ *
+ * Counters are bootstrapped from the DB on startup so the heartbeat
+ * reflects cumulative history rather than resetting to zero.
+ *
+ * Also provides activity tracking and event loop watchdog metrics
+ * for stuck daemon detection.
+ */
+import type { DaemonConfig } from '../types/index.js';
+import { sendHeartbeat } from '../queries/daemon-connection.js';
+import { type RetentionBeatObservation, type RetirementPreconditionVerdict } from '../drift/retention-observation.js';
+import { recordSessionCompleted, recordActivity, getLastActivityAt } from './agent-state.js';
+import type { ReadOnlyModeState } from '@telora/daemon-core';
+import { computeBranchStatus, type BranchStatusPayload } from './branch-status.js';
+import { type ProductBranchConfig } from '../queries/products.js';
+/**
+ * Compute a stable, display-meaningful repo identity from a product set: the
+ * sorted, deduplicated basenames of each product's repo path, joined by ', '.
+ * Sorting + dedup make the result invariant to product order and duplicates, so
+ * the same configured set always yields the same string. Pure.
+ */
+export declare function computeStableRepoIdentity(products: ReadonlyArray<{
+    repoPath: string;
+}>): string;
+/**
+ * Record the stable repo identity for this daemon instance. Called once at boot
+ * from the CONFIGURED product set BEFORE `claimProducts` mutates it, so the very
+ * first heartbeat already carries the claim-invariant value.
+ */
+export declare function setStableRepoIdentity(label: string): void;
+/** The boot-captured stable repo identity, or null if none was set. */
+export declare function getStableRepoIdentity(): string | null;
+/**
+ * Update the narration for a focus. Called by ActivityTracker callback.
+ */
+export declare function setNarration(focusId: string, text: string): void;
+/**
+ * Clear narration for a focus (called when team shuts down).
+ */
+export declare function clearNarration(focusId: string): void;
+export { recordActivity, getLastActivityAt };
+/**
+ * Get the current event loop lag (p99) in milliseconds and reset the histogram.
+ */
+export declare function getEventLoopLagMs(): number;
+/**
+ * Initialize the heartbeat module.
+ * Bootstraps counters from the DB (single query, graceful fallback).
+ * Initializes event loop monitoring.
+ */
+export declare function initHeartbeat(daemonConfig: DaemonConfig): Promise<void>;
+/**
+ * Get the current daemon version (loaded at init time).
+ */
+export declare function getVersions(): {
+    daemon: string;
+};
+/**
+ * Store the latest available version from the npm registry.
+ * Called by the version check module after a successful registry query.
+ */
+export declare function setLatestAvailableVersion(version: string): void;
+export { recordSessionCompleted };
+/**
+ * Record a completed issue (called when an issue transitions to Done).
+ */
+export declare function recordIssueCompleted(): void;
+/**
+ * Build the read-only-mode contribution to the heartbeat metadata.
+ *
+ * Returns `{ readOnlyMode }` only when the daemon is currently in read-only
+ * mode (schema-version gate, warn path), so the dashboard can mark stuck
+ * foci/deliveries and surface the missing migrations + recovery path. In
+ * normal operation returns null, so the `readOnlyMode` key is absent from
+ * the heartbeat metadata entirely. Pure (reads the daemon-core state getter)
+ * and independently testable.
+ */
+export declare function readOnlyMetadataField(): {
+    readOnlyMode: ReadOnlyModeState;
+} | null;
+/** Injectable seam for buildBranchStatusByProduct (unit tests inject fakes). */
+export interface BranchStatusProducerDeps {
+    computeBranchStatus: typeof computeBranchStatus;
+    getBranchConfig: (productId: string) => Promise<ProductBranchConfig>;
+}
+/**
+ * Publish branch status per product ({ [productId]: BranchStatusPayload }),
+ * mirroring the verificationPostures shape. Each product's payload is
+ * computed against ITS OWN repository (configForProduct) with ITS OWN
+ * mainBranch/branchMonitors resolved from its own product record — the root
+ * config always mirrors products[0] and must never be used to describe the
+ * others. One product failing is non-fatal to the rest (its entry is omitted).
+ *
+ * Exported (with injectable deps) so tests can pin the per-product claims
+ * without module mocks; doHeartbeat calls it with the real dependencies.
+ */
+export declare function buildBranchStatusByProduct(config: DaemonConfig, deps?: BranchStatusProducerDeps): Promise<Record<string, BranchStatusPayload>>;
+/**
+ * Pure presence-gap detector for the heartbeat.
+ *
+ * A successful beat writes nothing on its own, so a daemon can stop
+ * heart-beating for hours and leave no trace in ~/.telora/daemon.log. This
+ * function turns the silence into a measurable fact: given the current time,
+ * the time of the last SUCCESSFUL beat, and the normal interval, it reports the
+ * elapsed gap when a beat lands MORE than two intervals late.
+ *
+ * Threshold is strictly greater than two intervals -- two beats is also the
+ * dashboard's whole `online` budget, so the warning fires at exactly the point
+ * the UI stops calling the daemon online. Exactly two intervals is within
+ * budget and is NOT a gap.
+ *
+ * The first beat after startup has no prior successful beat (`lastSuccessMs`
+ * null), so it is never reported as a gap. Pure and independently testable with
+ * an injected clock -- no timers, no module state.
+ */
+export declare function detectHeartbeatGap(nowMs: number, lastSuccessMs: number | null, intervalMs: number): {
+    gapMs: number;
+} | null;
+/**
+ * Read-only view of the recorded retention observation window (most recent last).
+ * Exposed for diagnostics and tests that assert the daemon actually consumed the
+ * `retentionSchedules` field rather than discarding it.
+ */
+export declare function getRetentionObservationWindow(): readonly RetentionBeatObservation[];
+/**
+ * The current verdict on the pg_cron-retirement precondition, evaluated from the
+ * recorded observation window. This is the fact the daemon establishes on every
+ * beat -- "are this environment's declared horizons being held by the app-side
+ * sweep?" -- without any human query against the environment's database.
+ */
+export declare function getRetirementPreconditionVerdict(): RetirementPreconditionVerdict;
+/** Reset the retention observation window. For test isolation. */
+export declare function resetRetentionObservationWindow(): void;
+/**
+ * Injectable seam for doHeartbeat's external calls, so a unit test can drive the
+ * real consumption path hermetically (no network, no backend probe) and assert
+ * that a response carrying `retentionSchedules` lands in the recorded window.
+ * Defaults are the real implementations; production callers pass nothing.
+ */
+export interface DoHeartbeatDeps {
+    sendHeartbeat: typeof sendHeartbeat;
+    probeBackends: (config: DaemonConfig) => Promise<unknown>;
+    buildBranchStatus: (config: DaemonConfig) => Promise<Record<string, BranchStatusPayload>>;
+}
+/**
+ * Gather current counters and send a heartbeat.
+ *
+ * Exported (with an injectable deps seam) so a unit test can drive the real
+ * consumption path and assert the daemon records the retention field rather than
+ * discarding it. Production callers pass no args.
+ */
+export declare function doHeartbeat(deps?: DoHeartbeatDeps): Promise<void>;
+/**
+ * Start sending periodic heartbeats. Sends one immediately.
+ */
+export declare function startHeartbeat(): Promise<void>;
+/**
+ * Stop heartbeats and send a disconnect signal (best-effort).
+ */
+export declare function stopHeartbeat(): Promise<void>;
+//# sourceMappingURL=heartbeat.d.ts.map

package/dist/shell/heartbeat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat.d.ts","sourceRoot":"","sources":["../../src/shell/heartbeat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAQH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAkB,MAAM,iCAAiC,CAAC;AAEhF,OAAO,EAIL,KAAK,wBAAwB,EAC7B,KAAK,6BAA6B,EACnC,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAA0C,sBAAsB,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAIrI,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,mBAAmB,EAA4B,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC7G,OAAO,EAA0B,KAAK,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAkE1F;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,aAAa,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,GAC5C,MAAM,CAER;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAEzD;AAED,uEAAuE;AACvE,wBAAgB,qBAAqB,IAAI,MAAM,GAAG,IAAI,CAErD;AAOD;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAEhE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAEpD;AAGD,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,CAAC;AAmB7C;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAM1C;AAmFD;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAO7E;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAEhD;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE/D;AAGD,OAAO,EAAE,sBAAsB,EAAE,CAAC;AAElC;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,IAAI;IAAE,YAAY,EAAE,iBAAiB,CAAA;CAAE,GAAG,IAAI,CAGlF;AAwDD,gFAAgF;AAChF,MAAM,WAAW,wBAAwB;IACvC,mBAAmB,EAAE,OAAO,mBAAmB,CAAC;IAChD,eAAe,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACtE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,0BAA0B,CAC9C,MAAM,EAAE,YAAY,EACpB,IAAI,GAAE,wBAGL,GACA,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAc9C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,GAAG,IAAI,EAC5B,UAAU,EAAE,MAAM,GACjB;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAI1B;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,IAAI,SAAS,wBAAwB,EAAE,CAEnF;AAED;;;;;GAKG;AACH,wBAAgB,gCAAgC,IAAI,6BAA6B,CAEhF;AAED,kEAAkE;AAClE,wBAAgB,+BAA+B,IAAI,IAAI,CAEtD;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,OAAO,aAAa,CAAC;IACpC,aAAa,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1D,iBAAiB,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAAC;CAC3F;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,IAAI,GAAE,eAIL,GACA,OAAO,CAAC,IAAI,CAAC,CA+If;AAED;;GAEG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAcpD;AAED;;GAEG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAanD"}

package/dist/shell/heartbeat.js

@@ -0,0 +1,502 @@
+/**
+ * Heartbeat module — periodically reports daemon presence and work status to Telora.
+ *
+ * Sends an initial heartbeat on startup, then every HEARTBEAT_INTERVAL_MS.
+ * On shutdown, sends a disconnect signal (best-effort).
+ *
+ * Counters are bootstrapped from the DB on startup so the heartbeat
+ * reflects cumulative history rather than resetting to zero.
+ *
+ * Also provides activity tracking and event loop watchdog metrics
+ * for stuck daemon detection.
+ */
+import { readFileSync } from 'node:fs';
+import { hostname as osHostname } from 'node:os';
+import { join, dirname, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { monitorEventLoopDelay } from 'node:perf_hooks';
+import { sendHeartbeat, sendDisconnect } from '../queries/daemon-connection.js';
+import { getCompletedSessionAggregates } from '../queries/sessions.js';
+import { observeRetentionBeat, recordRetentionObservation, evaluateRetirementPrecondition, } from '../drift/retention-observation.js';
+import { getSessionCounters, setSessionCounters, recordSessionCompleted, recordActivity, getLastActivityAt } from './agent-state.js';
+import { getActiveTeamCount } from '../focus/focus-team-state.js';
+import { safeInterval, healthEvents, getReadOnlyModeState } from '@telora/daemon-core';
+import { buildProductPostureMap } from '../verify/verification-config.js';
+import { computeBranchStatus } from './branch-status.js';
+import { getProductBranchConfig } from '../queries/products.js';
+import { configForProduct } from './config.js';
+import { probeAllBackends } from '../backends/index.js';
+import { createLogger } from './log.js';
+const log = createLogger({ module: 'watchdog' });
+const HEARTBEAT_INTERVAL_MS = 60_000; // 60 seconds
+const INACTIVITY_THRESHOLD_MS = 600_000; // 10 minutes
+const EVENT_LOOP_LAG_WARNING_MS = 30_000; // 30 seconds
+let config = null;
+let heartbeatInterval = null;
+let completedIssueCount = 0;
+// Timestamp (ms) of the last SUCCESSFUL heartbeat send; null until the first
+// success. Compared against on each resumed beat to detect a presence gap that
+// would otherwise leave no trace in the daemon log.
+let lastSuccessfulHeartbeatAtMs = null;
+// Rolling window of per-beat retention observations, read from each successful
+// heartbeat's response body. This is the recorded evidence the pg_cron-retirement
+// precondition is evaluated against -- established by the daemon itself, without
+// any human query against the environment's database. Bounded (see
+// RETENTION_WINDOW_SIZE); older/malformed responses record an "unknown"
+// observation and never disturb the beat.
+let retentionObservationWindow = [];
+let daemonVersion = 'unknown';
+let daemonCommitSha = 'unknown';
+let latestAvailableVersion = null;
+const daemonStartedAt = new Date().toISOString();
+// ── Product branch config cache (per product) ────────────────────────
+const branchConfigCache = new Map();
+const BRANCH_CONFIG_REFRESH_MS = 300_000; // 5 minutes
+/** Fetch (with 5-minute cache) the branch config for one product. */
+async function getCachedBranchConfig(productId) {
+    const now = Date.now();
+    const cached = branchConfigCache.get(productId);
+    if (cached && now - cached.fetchedAt <= BRANCH_CONFIG_REFRESH_MS) {
+        return cached.config;
+    }
+    const fresh = await getProductBranchConfig(productId);
+    branchConfigCache.set(productId, { config: fresh, fetchedAt: now });
+    return fresh;
+}
+// ── Stable daemon repo identity ──────────────────────────────────────
+//
+// The heartbeat's `repo_path` field doubles as the key the edge handler
+// (handleDaemonHeartbeat) uses to retire a restarted daemon's prior rows
+// (hostname AND repo_path AND neq pid). It MUST be stable across restarts, or
+// prior rows are never retired and the table grows without bound.
+//
+// The naive derivation -- basenames of `config.products` -- is NOT stable: by
+// the time the heartbeat runs, `claimProducts` has mutated `config.products`
+// in place to only the CLAIMED subset (unified-engine-lifecycle.ts). A transient
+// claim failure (or any change to the claimed set) therefore changes the label,
+// stranding the previous run's rows. The fix: derive the identity from the
+// CONFIGURED product set captured once at boot (before claim), sorted + deduped
+// so it is invariant to product order. Co-hosted daemons keep their separation
+// (migration 20260215134249) because distinct configured repo sets yield
+// distinct labels.
+let stableRepoIdentity = null;
+/**
+ * Compute a stable, display-meaningful repo identity from a product set: the
+ * sorted, deduplicated basenames of each product's repo path, joined by ', '.
+ * Sorting + dedup make the result invariant to product order and duplicates, so
+ * the same configured set always yields the same string. Pure.
+ */
+export function computeStableRepoIdentity(products) {
+    return [...new Set(products.map((p) => basename(p.repoPath)))].sort().join(', ');
+}
+/**
+ * Record the stable repo identity for this daemon instance. Called once at boot
+ * from the CONFIGURED product set BEFORE `claimProducts` mutates it, so the very
+ * first heartbeat already carries the claim-invariant value.
+ */
+export function setStableRepoIdentity(label) {
+    stableRepoIdentity = label || null;
+}
+/** The boot-captured stable repo identity, or null if none was set. */
+export function getStableRepoIdentity() {
+    return stableRepoIdentity;
+}
+// ── Narration store (in-memory only) ─────────────────────────────────
+/** Focus ID -> latest narration text from team lead. */
+const narrations = new Map();
+/**
+ * Update the narration for a focus. Called by ActivityTracker callback.
+ */
+export function setNarration(focusId, text) {
+    narrations.set(focusId, text);
+}
+/**
+ * Clear narration for a focus (called when team shuts down).
+ */
+export function clearNarration(focusId) {
+    narrations.delete(focusId);
+}
+// Re-export activity tracking from agent-state for backward compatibility
+export { recordActivity, getLastActivityAt };
+// ── Event loop watchdog ──────────────────────────────────────────────
+let eventLoopHistogram = null;
+/**
+ * Initialize the event loop delay monitor.
+ * Uses perf_hooks.monitorEventLoopDelay() for passive, low-overhead measurement.
+ */
+function initEventLoopMonitor() {
+    try {
+        eventLoopHistogram = monitorEventLoopDelay({ resolution: 20 });
+        eventLoopHistogram.enable();
+    }
+    catch {
+        log.warn('Event loop delay monitoring not available on this runtime');
+    }
+}
+/**
+ * Get the current event loop lag (p99) in milliseconds and reset the histogram.
+ */
+export function getEventLoopLagMs() {
+    if (!eventLoopHistogram)
+        return 0;
+    // Histogram values are in nanoseconds
+    const p99Ns = eventLoopHistogram.percentile(99);
+    eventLoopHistogram.reset();
+    return Math.round(p99Ns / 1_000_000); // Convert ns to ms
+}
+/**
+ * Check event loop lag and log a warning if it exceeds the threshold.
+ */
+function checkEventLoopLag(lagMs) {
+    if (lagMs > EVENT_LOOP_LAG_WARNING_MS) {
+        log.error(`[watchdog] CRITICAL: Event loop lag ${lagMs}ms exceeds ${EVENT_LOOP_LAG_WARNING_MS}ms threshold. ` +
+            `The daemon may have been blocked. Stack: ${new Error().stack}`);
+    }
+}
+/**
+ * Load daemon version from package.json and commit SHA from build-info.json.
+ */
+function loadVersionInfo() {
+    let version = 'unknown';
+    let sha = 'unknown';
+    const thisDir = dirname(fileURLToPath(import.meta.url));
+    try {
+        const pkgPath = join(thisDir, '..', 'package.json');
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+        version = pkg.version || 'unknown';
+    }
+    catch (e) {
+        log.debug('[heartbeat] Failed to load daemon version from package.json:', e.message);
+    }
+    try {
+        const buildInfoPath = join(thisDir, '..', 'build-info.json');
+        const buildInfo = JSON.parse(readFileSync(buildInfoPath, 'utf-8'));
+        sha = buildInfo.commitSha || 'unknown';
+    }
+    catch (err) {
+        // build-info.json not present in dev — only stamped at publish time
+        log.debug('build-info.json not present in dev — only stamped at publish time', { error: String(err?.message ?? err) });
+    }
+    return { version, commitSha: sha };
+}
+/**
+ * Bootstrap counters from the database.
+ *
+ * Queries completed session aggregates for this product so the heartbeat
+ * starts with cumulative totals instead of zero. Falls back gracefully
+ * to zero on any error.
+ */
+async function bootstrapCountersFromDb(daemonConfig) {
+    try {
+        // Aggregate across all configured products
+        let totalCompleted = 0;
+        let totalTokens = 0;
+        let totalCostAgg = 0;
+        for (const product of daemonConfig.products) {
+            const aggregates = await getCompletedSessionAggregates(product.id);
+            totalCompleted += aggregates.completedCount;
+            totalTokens += aggregates.totalTokens;
+            totalCostAgg += aggregates.totalCost;
+        }
+        setSessionCounters({
+            completedSessionCount: totalCompleted,
+            totalTokensUsed: totalTokens,
+            totalCost: totalCostAgg,
+        });
+        log.info(`Bootstrapped heartbeat counters from DB (${daemonConfig.products.length} products): ` +
+            `${totalCompleted} sessions, ` +
+            `${totalTokens} tokens, ` +
+            `$${totalCostAgg.toFixed(2)} cost`);
+    }
+    catch (err) {
+        log.warn(`Failed to bootstrap heartbeat counters from DB (starting at zero): ` +
+            `${err.message}`);
+        // Counters remain at 0 — same as previous behavior
+    }
+}
+/**
+ * Initialize the heartbeat module.
+ * Bootstraps counters from the DB (single query, graceful fallback).
+ * Initializes event loop monitoring.
+ */
+export async function initHeartbeat(daemonConfig) {
+    config = daemonConfig;
+    const info = loadVersionInfo();
+    daemonVersion = info.version;
+    daemonCommitSha = info.commitSha;
+    await bootstrapCountersFromDb(daemonConfig);
+    initEventLoopMonitor();
+}
+/**
+ * Get the current daemon version (loaded at init time).
+ */
+export function getVersions() {
+    return { daemon: daemonVersion };
+}
+/**
+ * Store the latest available version from the npm registry.
+ * Called by the version check module after a successful registry query.
+ */
+export function setLatestAvailableVersion(version) {
+    latestAvailableVersion = version;
+}
+// Re-export recordSessionCompleted from agent-state for backward compatibility
+export { recordSessionCompleted };
+/**
+ * Record a completed issue (called when an issue transitions to Done).
+ */
+export function recordIssueCompleted() {
+    completedIssueCount++;
+}
+/**
+ * Build the read-only-mode contribution to the heartbeat metadata.
+ *
+ * Returns `{ readOnlyMode }` only when the daemon is currently in read-only
+ * mode (schema-version gate, warn path), so the dashboard can mark stuck
+ * foci/deliveries and surface the missing migrations + recovery path. In
+ * normal operation returns null, so the `readOnlyMode` key is absent from
+ * the heartbeat metadata entirely. Pure (reads the daemon-core state getter)
+ * and independently testable.
+ */
+export function readOnlyMetadataField() {
+    const state = getReadOnlyModeState();
+    return state.active ? { readOnlyMode: state } : null;
+}
+/**
+ * Publish branch status per product ({ [productId]: BranchStatusPayload }),
+ * mirroring the verificationPostures shape. Each product's payload is
+ * computed against ITS OWN repository (configForProduct) with ITS OWN
+ * mainBranch/branchMonitors resolved from its own product record — the root
+ * config always mirrors products[0] and must never be used to describe the
+ * others. One product failing is non-fatal to the rest (its entry is omitted).
+ *
+ * Exported (with injectable deps) so tests can pin the per-product claims
+ * without module mocks; doHeartbeat calls it with the real dependencies.
+ */
+export async function buildBranchStatusByProduct(config, deps = {
+    computeBranchStatus,
+    getBranchConfig: getCachedBranchConfig,
+}) {
+    const branchStatusByProduct = {};
+    for (const product of config.products) {
+        try {
+            const productConfig = configForProduct(config, product);
+            const branchConfig = await deps.getBranchConfig(product.id);
+            const branchOpts = {
+                mainBranch: branchConfig.mainBranch,
+                branchMonitors: branchConfig.branchMonitors,
+            };
+            branchStatusByProduct[product.id] = deps.computeBranchStatus(productConfig, branchOpts);
+        }
+        catch { /* non-fatal — omit this product's entry */ }
+    }
+    return branchStatusByProduct;
+}
+/**
+ * Pure presence-gap detector for the heartbeat.
+ *
+ * A successful beat writes nothing on its own, so a daemon can stop
+ * heart-beating for hours and leave no trace in ~/.telora/daemon.log. This
+ * function turns the silence into a measurable fact: given the current time,
+ * the time of the last SUCCESSFUL beat, and the normal interval, it reports the
+ * elapsed gap when a beat lands MORE than two intervals late.
+ *
+ * Threshold is strictly greater than two intervals -- two beats is also the
+ * dashboard's whole `online` budget, so the warning fires at exactly the point
+ * the UI stops calling the daemon online. Exactly two intervals is within
+ * budget and is NOT a gap.
+ *
+ * The first beat after startup has no prior successful beat (`lastSuccessMs`
+ * null), so it is never reported as a gap. Pure and independently testable with
+ * an injected clock -- no timers, no module state.
+ */
+export function detectHeartbeatGap(nowMs, lastSuccessMs, intervalMs) {
+    if (lastSuccessMs === null)
+        return null;
+    const gapMs = nowMs - lastSuccessMs;
+    return gapMs > intervalMs * 2 ? { gapMs } : null;
+}
+/**
+ * Read-only view of the recorded retention observation window (most recent last).
+ * Exposed for diagnostics and tests that assert the daemon actually consumed the
+ * `retentionSchedules` field rather than discarding it.
+ */
+export function getRetentionObservationWindow() {
+    return retentionObservationWindow;
+}
+/**
+ * The current verdict on the pg_cron-retirement precondition, evaluated from the
+ * recorded observation window. This is the fact the daemon establishes on every
+ * beat -- "are this environment's declared horizons being held by the app-side
+ * sweep?" -- without any human query against the environment's database.
+ */
+export function getRetirementPreconditionVerdict() {
+    return evaluateRetirementPrecondition(retentionObservationWindow);
+}
+/** Reset the retention observation window. For test isolation. */
+export function resetRetentionObservationWindow() {
+    retentionObservationWindow = [];
+}
+/**
+ * Gather current counters and send a heartbeat.
+ *
+ * Exported (with an injectable deps seam) so a unit test can drive the real
+ * consumption path and assert the daemon records the retention field rather than
+ * discarding it. Production callers pass no args.
+ */
+export async function doHeartbeat(deps = {
+    sendHeartbeat,
+    probeBackends: probeAllBackends,
+    buildBranchStatus: buildBranchStatusByProduct,
+}) {
+    if (!config)
+        return;
+    const activeTeamCount = getActiveTeamCount();
+    // Event loop watchdog: measure and check lag
+    const eventLoopLagMs = getEventLoopLagMs();
+    checkEventLoopLag(eventLoopLagMs);
+    // Inactivity detection: warn if no activity for 10+ minutes
+    const lastActivity = getLastActivityAt();
+    const inactivityMs = Date.now() - lastActivity.getTime();
+    if (inactivityMs > INACTIVITY_THRESHOLD_MS) {
+        log.warn(`[watchdog] Daemon inactive for ${Math.round(inactivityMs / 1000)}s. ` +
+            `Active teams: ${activeTeamCount}. ` +
+            `Last activity: ${lastActivity.toISOString()}`);
+    }
+    // Build metadata with version observability fields
+    const metadata = {};
+    if (daemonCommitSha !== 'unknown') {
+        metadata.commitSha = daemonCommitSha;
+    }
+    if (latestAvailableVersion) {
+        metadata.latestAvailableVersion = latestAvailableVersion;
+    }
+    metadata.maxTotalSessions = config.maxTotalSessions;
+    // Publish per-product verification posture ({ [productId]: { posture, command } })
+    // so the web app's product settings can surface how each product's deliveries
+    // are gated -- posture is local daemon.json config the app cannot otherwise see.
+    // Declarative state, derived at read time; never an escalation.
+    metadata.verificationPostures = buildProductPostureMap(config.products, config.defaultVerification);
+    // Publish which engines are installed + authenticated on this host so the
+    // app's engine picker can grey out unavailable ones (probe is cached).
+    try {
+        metadata.availableBackends = await deps.probeBackends(config);
+    }
+    catch { /* non-fatal -- omit availability rather than fail the heartbeat */ }
+    const branchStatusByProduct = await deps.buildBranchStatus(config);
+    if (Object.keys(branchStatusByProduct).length > 0) {
+        metadata.branchStatus = branchStatusByProduct;
+    }
+    if (narrations.size > 0) {
+        metadata.narrations = Object.fromEntries(narrations);
+    }
+    // Include health events in metadata for dashboard visibility
+    const events = healthEvents.getEvents();
+    if (events.length > 0) {
+        metadata.healthEvents = events;
+    }
+    // Surface read-only mode (schema-version gate, warn path) so the dashboard
+    // can mark stuck foci/deliveries and show the recovery path. The heartbeat
+    // is allowlisted in read-only mode, so this write always lands. Only emit
+    // when active -- in normal operation the key is absent.
+    const readOnlyField = readOnlyMetadataField();
+    if (readOnlyField) {
+        Object.assign(metadata, readOnlyField);
+    }
+    // Derive health_status from event buffer severity
+    const healthStatus = healthEvents.getUnresolvedCount('error') > 0
+        ? 'error'
+        : healthEvents.getUnresolvedCount('warn') > 0
+            ? 'degraded'
+            : 'healthy';
+    const counters = getSessionCounters();
+    try {
+        // repo label AND restart-cleanup key: prefer the boot-captured stable
+        // identity (derived from the CONFIGURED product set, invariant to claim
+        // outcomes) so a restart or a claim failure never strands the prior run's
+        // rows. Fall back to the current (possibly claim-filtered) set only if the
+        // stable identity was never set, then to products[0]'s repo basename.
+        const repoLabel = getStableRepoIdentity()
+            || computeStableRepoIdentity(config.products)
+            || basename(config.repoPath);
+        const response = await deps.sendHeartbeat(process.pid, osHostname(), repoLabel, daemonVersion, {
+            activeSessions: activeTeamCount,
+            completedSessions: counters.completedSessionCount,
+            plannedIssues: 0, // Could be enriched later by querying ready deliveries
+            inProgressIssues: activeTeamCount,
+            completedIssues: completedIssueCount,
+            totalTokensUsed: counters.totalTokensUsed,
+            totalCost: counters.totalCost,
+            daemonStartedAt,
+            lastActivityAt: getLastActivityAt().toISOString(),
+            eventLoopLagMs,
+            productId: config.productId,
+            productIds: config.products.map(p => p.id),
+            healthStatus,
+        }, Object.keys(metadata).length > 0 ? metadata : undefined);
+        // Establish the retention picture from the response the daemon already
+        // received -- no extra round trip. Record this beat's per-horizon
+        // classification into the bounded window so the pg_cron-retirement
+        // precondition is evaluable from a recorded observation rather than a psql
+        // session run against production. An absent field (older edge bundle) or a
+        // malformed one records an "unknown" observation. Guarded so a retention
+        // read can never disturb the heartbeat or the daemon's own liveness.
+        try {
+            const observation = observeRetentionBeat(response, Date.now());
+            retentionObservationWindow = recordRetentionObservation(retentionObservationWindow, observation);
+        }
+        catch (obsErr) {
+            log.debug('[watchdog] retention observation skipped (non-fatal):', String(obsErr?.message ?? obsErr));
+        }
+        // Presence self-observation: a successful send means beats are live. If
+        // this beat resumed after a gap (the interval stalled, or the send failed /
+        // was breaker-suppressed for a stretch, regardless of cause), leave a
+        // durable, timestamped trace naming the elapsed duration -- the one record
+        // of the outage that survives independently of daemon_connections. Emitted
+        // once, the moment beats resume; the normal cadence updates the marker
+        // below and never warns.
+        const nowMs = Date.now();
+        const gap = detectHeartbeatGap(nowMs, lastSuccessfulHeartbeatAtMs, HEARTBEAT_INTERVAL_MS);
+        if (gap) {
+            log.warn(`[watchdog] Heartbeat presence gap: no successful beat for ${Math.round(gap.gapMs / 1000)}s ` +
+                `(> ${(HEARTBEAT_INTERVAL_MS * 2) / 1000}s threshold). Beats have resumed.`);
+        }
+        lastSuccessfulHeartbeatAtMs = nowMs;
+    }
+    catch (error) {
+        log.error('Heartbeat failed:', error.message);
+    }
+}
+/**
+ * Start sending periodic heartbeats. Sends one immediately.
+ */
+export async function startHeartbeat() {
+    if (!config) {
+        throw new Error('Heartbeat not initialized. Call initHeartbeat first.');
+    }
+    // Send initial heartbeat immediately
+    await doHeartbeat();
+    // Start periodic heartbeats with error boundary
+    heartbeatInterval = safeInterval(() => {
+        return doHeartbeat();
+    }, HEARTBEAT_INTERVAL_MS, 'heartbeat');
+    log.info(`Started heartbeat (every ${HEARTBEAT_INTERVAL_MS / 1000}s)`);
+}
+/**
+ * Stop heartbeats and send a disconnect signal (best-effort).
+ */
+export async function stopHeartbeat() {
+    if (heartbeatInterval) {
+        clearInterval(heartbeatInterval);
+        heartbeatInterval = null;
+    }
+    // Best-effort disconnect — don't block shutdown
+    try {
+        await sendDisconnect(process.pid);
+        log.info('Sent disconnect signal');
+    }
+    catch (error) {
+        log.error('Failed to send disconnect (non-fatal):', error.message);
+    }
+}
+//# sourceMappingURL=heartbeat.js.map