@telora/daemon 0.22.245 → 0.22.289

package/dist/focus/heartbeat-metadata.js

@@ -0,0 +1,268 @@
+// PINNED-BY-BEGIN (generated by gen:pinned-by -- do not hand-edit; checked by lint:pinned-by)
+// Pinned by: packages/daemon/src/focus/heartbeat-mcp-version.test.ts,
+//   packages/daemon/src/focus/heartbeat-per-product-branch-status.test.ts,
+//   packages/daemon/src/focus/heartbeat-product-engines.test.ts,
+//   packages/daemon/src/focus/heartbeat-version-lag.test.ts,
+//   packages/daemon/src/focus/supervision-firing-rates.test.ts,
+//   packages/daemon/src/spawn/migration-numbering-wiring.test.ts
+// PINNED-BY-END
+/**
+ * Heartbeat metadata builders.
+ *
+ * Pure/near-pure producers of individual heartbeat metadata fields. Each builder
+ * is independently testable; doHeartbeat (focus/heartbeat.ts) composes them into
+ * the metadata object.
+ */
+import { dirname, join } from 'node:path';
+import { healthEvents, MCP_PRODUCTS_PACKAGE } from '@telora/daemon-core';
+import { configForProduct } from '../config/config.js';
+import { getProductBranchConfig } from '../queries/org-config/products.js';
+import { isNewerVersion, versionDistance, isReadingAttributable, } from '../config/update-channel.js';
+import { buildProductPostureMap } from '../verify/gate-config/verification-config.js';
+import { readVerifyManifest } from '../verify/gate-config/verification-manifest.js';
+import { firingMechanisms, firingStats, isDemotionRecommended } from '../completion/team-liveness/supervision-firing-record.js';
+// ── 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. */
+export 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;
+}
+/**
+ * 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 required deps) so tests can pin the per-product claims
+ * without module mocks; the composition root binds the real dependencies
+ * (composition/runtime-heartbeat-context.ts).
+ */
+export async function buildBranchStatusByProduct(config, deps) {
+    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;
+}
+/**
+ * Build the versionLag metadata field: the running daemon vs the install
+ * registry's latest. Returns null when it cannot be computed (latest unknown, or
+ * the running version unstamped) so the key is simply absent; `behind:false` when
+ * the daemon is current. Carries the registry the reading came from and whether
+ * it is attributable to `installRegistry` (the registry npm resolves for an
+ * install) -- an unattributable reading is measured:false (UNMEASURED), never a
+ * silent false "in sync". The fields make a fix that has SHIPPED but is not
+ * RUNNING distinguishable from one that is running -- the mars 0.22.4-vs-0.22.13
+ * incident, visible from the platform without host access. Pure + testable.
+ */
+export function buildVersionLagField(running, latest, readingRegistry, installRegistry) {
+    if (!latest || running === 'unknown')
+        return null;
+    return {
+        running,
+        latest,
+        registry: readingRegistry,
+        measured: isReadingAttributable(readingRegistry, installRegistry),
+        behind: isNewerVersion(latest, running),
+        distance: versionDistance(running, latest),
+    };
+}
+/**
+ * Build the productEngines metadata field ({ [productId]: ProductEngineConfig }),
+ * mirroring the verificationPostures shape. It is local daemon.json config the
+ * app cannot otherwise see: the product-default engine decides a pass with no
+ * model selected at or above the org default, and a local-Codex product forwards
+ * its own model -- so without it the dashboard cannot name the engine and model a
+ * pass runs on. Pure.
+ */
+export function buildProductEngineMap(products) {
+    const map = {};
+    for (const product of products) {
+        map[product.id] = {
+            defaultCodingEngine: product.defaultCodingEngine ?? null,
+            localCodex: Boolean(product.codexHome),
+            codexModel: product.codexModel ?? null,
+        };
+    }
+    return map;
+}
+/**
+ * The `@telora/mcp-products` version an agent on this host ACTUALLY executes.
+ *
+ * THE DEFECT THIS REPLACES. The first cut read
+ * `<repoPath>/node_modules/@telora/mcp-products/package.json` -- the product
+ * CHECKOUT's dependency. No agent runs that copy. Every worktree's `.mcp.json`
+ * is written by `generateMcpConfigInWorktree` (worktree/provision.ts) from
+ * `resolveMcpServerPath()`, which resolves the package from the DAEMON's own
+ * module context, and the config carries that absolute path. So the reading
+ * described one install while the fleet ran another, in both directions: a
+ * checkout that happened to be current could activate a refusal against agents
+ * still on an old MCP -- exactly the harm the barrier exists to prevent -- and
+ * a checkout with no MCP at all could hold the barrier shut forever while every
+ * agent was already able to comply.
+ *
+ * It is therefore ONE reading per HOST, not one per product: the daemon bundles
+ * a single copy and every worktree points at it.
+ *
+ * Reads the package.json beside the resolved entry point, walking up until it
+ * finds the one that NAMES this package -- the entry is `dist/index.js`, so the
+ * root is a level or two up, and matching on the name means a nested package.json
+ * cannot be mistaken for it. Any failure returns null, which the barrier reads as
+ * below the floor: silence is not proof.
+ */
+export function readExecutedMcpVersion(resolveEntry, readFile) {
+    let dir;
+    try {
+        dir = dirname(resolveEntry());
+    }
+    catch {
+        return null;
+    }
+    for (let hop = 0; hop < 8; hop += 1) {
+        try {
+            const parsed = JSON.parse(readFile(join(dir, 'package.json')));
+            const { name, version } = parsed;
+            if (name === MCP_PRODUCTS_PACKAGE) {
+                return typeof version === 'string' ? version : null;
+            }
+        }
+        catch {
+            // Not a package root, or unreadable -- keep walking.
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+/**
+ * Assemble the heartbeat metadata object (version observability, verification
+ * postures, available backends, branch status, focus-scoped fields, health
+ * events, read-only mode). Split out of heartbeat.ts (at its file-size floor);
+ * the daemon's volatile version state and the two heartbeat-internal helpers
+ * (focus-scoped fields, read-only field) are passed in so this stays a pure
+ * composer with no back-import into the hot-path module. No behavior change.
+ */
+export async function buildHeartbeatMetadata(args) {
+    const { cfg, version, producers, applyFocusScopedMetadata, readOnlyMetadataField } = args;
+    const { probeBackends, buildBranchStatus, buildMigrationHeldSets } = producers;
+    const metadata = {};
+    if (version.daemonCommitSha !== 'unknown') {
+        metadata.commitSha = version.daemonCommitSha;
+    }
+    if (version.latestAvailableVersion) {
+        metadata.latestAvailableVersion = version.latestAvailableVersion;
+    }
+    // Version lag: the running daemon vs the install registry's latest, carried so
+    // a lagging host (a fix shipped but NOT running -- the mars 0.22.4-vs-0.22.13
+    // incident) is visible from the platform without host access. It names the
+    // registry the reading came from and marks measured:false (UNMEASURED) when the
+    // reading cannot be attributed to the install registry, so the platform never
+    // reads a false "in sync" against the wrong registry.
+    const versionLag = buildVersionLagField(version.daemonVersion, version.latestAvailableVersion, version.latestAvailableRegistry, version.installRegistry);
+    if (versionLag) {
+        metadata.versionLag = versionLag;
+    }
+    metadata.maxTotalSessions = cfg.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(cfg.products, cfg.defaultVerification, process.env, readVerifyManifest);
+    // Publish each product's engine config ({ [productId]: { defaultCodingEngine,
+    // localCodex, codexModel } }) so the dashboard names the engine and model a
+    // pass runs on -- the product default engine outranks the org default engine.
+    metadata.productEngines = buildProductEngineMap(cfg.products);
+    // Publish the MCP version agents on this host actually execute. The
+    // product-api rollout barrier reads it to decide whether the Nexus request
+    // refusals may activate: before this field, what MCP a host runs was a fact
+    // no automated boundary could check, so the deploy order was a thing someone
+    // had to remember. HOST-level, not per product -- the daemon bundles one copy
+    // and every worktree's .mcp.json points at it. See readExecutedMcpVersion.
+    const executedMcpVersion = producers.readExecutedMcpVersion();
+    if (executedMcpVersion) {
+        metadata.mcpProductsVersion = executedMcpVersion;
+    }
+    // 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 probeBackends(cfg);
+    }
+    catch { /* non-fatal -- omit availability rather than fail the heartbeat */ }
+    const branchStatusByProduct = await buildBranchStatus(cfg);
+    if (Object.keys(branchStatusByProduct).length > 0) {
+        metadata.branchStatus = branchStatusByProduct;
+    }
+    // Publish each product's migration held set ({ [productId]: { held, complete,
+    // readAt, tips } }) so the claim allocator at the edge can see which numbers
+    // integration and every live focus branch already hold. The edge function has
+    // no git; the daemon is the only thing that can answer this, the same split
+    // verificationPostures crosses. A product that declares no migration
+    // numbering publishes NO entry -- that absence is its opt-out, and must stay
+    // distinguishable from an empty held set.
+    const migrationHeldSets = await buildMigrationHeldSets(cfg);
+    if (Object.keys(migrationHeldSets).length > 0) {
+        metadata.migrationHeldSets = migrationHeldSets;
+    }
+    applyFocusScopedMetadata(metadata);
+    // 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);
+    }
+    // Supervision falsifiability: the per-mechanism false-positive rate from the
+    // firing-record store, so a chronically-wrong kill/hold/respawn mechanism is a
+    // READING on the heartbeat -- not something a human hand-greps from the log
+    // after the cost is paid. Omitted (key absent) until a mechanism has fired.
+    const firingRates = buildSupervisionFiringRates();
+    if (Object.keys(firingRates).length > 0) {
+        metadata.supervisionFiringRates = firingRates;
+    }
+    return metadata;
+}
+/** Per-mechanism falsifiability reading (rate + demotion recommendation) from the store. */
+export function buildSupervisionFiringRates() {
+    const rates = {};
+    for (const mechanism of firingMechanisms()) {
+        const s = firingStats(mechanism);
+        rates[mechanism] = {
+            total: s.total,
+            falsePositives: s.falsePositives,
+            falsePositiveRate: s.falsePositiveRate,
+            demotionRecommended: isDemotionRecommended(mechanism),
+            unacted: s.unacted,
+            activeTruePositives: s.activeTruePositives,
+            sweptTruePositives: s.sweptTruePositives,
+        };
+    }
+    return rates;
+}
+//# sourceMappingURL=heartbeat-metadata.js.map

package/dist/focus/heartbeat-metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat-metadata.js","sourceRoot":"","sources":["../../src/focus/heartbeat-metadata.ts"],"names":[],"mappings":"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"}

package/dist/focus/heartbeat.d.ts

@@ -0,0 +1,163 @@
+import type { DaemonConfig } from '../types/index.js';
+import type { sendHeartbeat, sendDisconnect } from '../queries/sessions/daemon-connection.js';
+import { type RetentionBeatObservation, type RetirementPreconditionVerdict } from '../drift/retention-observation.js';
+import { type TeamLivenessPhaseSources } from '../completion/team-liveness/team-liveness-phase.js';
+import type { ReadOnlyModeState } from '@telora/daemon-core';
+import { type HeartbeatProducers } from './heartbeat-metadata.js';
+/** How often a beat is sent. Exported so the lease derived from it is assertable. */
+export declare const HEARTBEAT_INTERVAL_MS = 60000;
+/**
+ * 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;
+/**
+ * Get the current event loop lag (p99) in milliseconds and reset the histogram.
+ */
+export declare function getEventLoopLagMs(): number;
+/**
+ * Load daemon version from package.json and commit SHA from build-info.json.
+ */
+export declare function loadVersionInfo(): {
+    version: string;
+    commitSha: string;
+};
+/**
+ * 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, plus the registry it
+ * was read from. The registry lets the heartbeat ATTRIBUTE the reading to the
+ * install registry so a lagging host cannot publish a false "in sync" against the
+ * wrong registry (the mars false-negative). Called by the version check module
+ * after a successful registry query.
+ */
+export declare function setLatestAvailableVersion(version: string, registry?: string): void;
+/**
+ * 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;
+/**
+ * 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;
+/**
+ * doHeartbeat's external calls: the sender and the per-product metadata
+ * producers. Required -- the production binding is made at the composition
+ * root (composition/runtime-heartbeat-context.ts); a unit test drives the real
+ * consumption path hermetically (no network, no backend probe) with fakes.
+ */
+export interface DoHeartbeatDeps extends HeartbeatProducers {
+    sendHeartbeat: typeof sendHeartbeat;
+    /** The live registries the published team-liveness phase map is composed from. */
+    teamLivenessPhaseSources: TeamLivenessPhaseSources;
+}
+/** The heartbeat's collaborators: each beat's, and the shutdown disconnect's. */
+export interface HeartbeatContext {
+    readonly beat: DoHeartbeatDeps;
+    readonly stop: StopHeartbeatDeps;
+}
+/**
+ * Gather current counters and send a heartbeat.
+ *
+ * Thin wrapper over `performHeartbeat` that registers this execution as the
+ * in-flight beat (`inFlightBeat`), so `stopHeartbeat` can await a beat that is
+ * still in flight -- possibly mid-`callApi` retry behind the 120s heartbeat
+ * breaker -- before it sends the disconnect. That ordering makes the disconnect
+ * the last writer even for a beat the pre-write flag cannot catch. Exported
+ * (with the injectable deps seam) so a unit test can drive the real consumption
+ * path; production callers pass no args.
+ */
+export declare function doHeartbeat(deps: DoHeartbeatDeps): Promise<void>;
+/**
+ * Start sending periodic heartbeats. Sends one immediately.
+ */
+export declare function startHeartbeat(deps: DoHeartbeatDeps): Promise<void>;
+/** stopHeartbeat's disconnect write, bound at the composition root (unit tests inject a spy). */
+export interface StopHeartbeatDeps {
+    sendDisconnect: typeof sendDisconnect;
+}
+/**
+ * Stop heartbeats and send a disconnect signal (best-effort).
+ *
+ * Makes the shutdown the LAST writer to the connection row, closing the race
+ * where a beat that outlives the disconnect rewrites the row back to 'online':
+ *  1. Latch `shuttingDown` FIRST, so any beat still preparing bails at its
+ *     pre-write guard instead of writing after us.
+ *  2. Await `inFlightBeat` -- a beat already inside `deps.sendHeartbeat` (which
+ *     the flag cannot stop, since it retries behind the 120s heartbeat breaker).
+ *     Its write, if any, therefore lands BEFORE the disconnect below. This can
+ *     delay a graceful stop by the beat's remaining retry budget, which is the
+ *     price of a provably-last disconnect; a bounded wait would reopen the race.
+ *  3. Send the disconnect.
+ *
+ * Exported deps seam so a unit test can drive the ordering with a spy sender.
+ */
+export declare function stopHeartbeat(deps: StopHeartbeatDeps): Promise<void>;
+//# sourceMappingURL=heartbeat.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat.d.ts","sourceRoot":"","sources":["../../src/focus/heartbeat.ts"],"names":[],"mappings":"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"}