@telora/daemon 0.21.26 → 0.21.81

package/dist/drift/staleness-sensor.js

@@ -0,0 +1,335 @@
+/**
+ * Propagation-staleness sensor (focus: "Propagation Staleness Is Invisible").
+ *
+ * The differential instrument this focus is named for: it computes
+ * newest-available MINUS actually-running for a tracked target. Its first (and
+ * directly observable) target is the running daemon vs the Gitea npm registry:
+ *
+ *   running = ~/.telora/daemon.meta.json .version   (this daemon's own build)
+ *   newest  = the warm version cache .latestVersion  (Gitea registry dist-tags.latest,
+ *             kept fresh by startVersionCacheRefreshLoop)
+ *
+ * CLOSING the gap, not reporting it. The daemon-version gap is machine-closable:
+ * the safe-seam auto-update controller (auto-update.ts) already installs a newer
+ * registry version at the next batch-safe idle seam. So when the gap is beyond
+ * threshold this sensor DEFERS to that closer -- it does NOT tell a human "the
+ * daemon is stale, restart it". Telling a human about a gap the machine is
+ * already closing converts machine signal into human chore, and firing on a
+ * healthy daemon that is merely deferring to its next safe seam is exactly the
+ * failure mode this focus exists to remove.
+ *
+ * A human is involved ONLY where the machine genuinely cannot act: auto-update
+ * is disabled for this daemon (installMode=npx, or --no-auto-update /
+ * TELORA_AUTO_UPDATE=0, reflected as autoUpdateEnabled=false in daemon.meta.json).
+ * The operator opted out of automation, so the machine cannot close the gap --
+ * and even then the deliverable is a READY ACTION handed over (the exact
+ * `npm install -g` command + restart), never an inbox item that merely says a
+ * gap exists. That handover auto-resolves once the running version catches up,
+ * and is retired immediately if auto-update is re-enabled (the machine reclaims
+ * closure).
+ *
+ * Every tick leaves a trace (delegated-to-auto-update / handed-over /
+ * back-in-sync / "measured, within threshold" / "UNMEASURED"), so an ABSENT
+ * trace positively means "measured and in sync" -- never "not measured". Wedged
+ * auto-update (enabled but not running) is made visible by the SEPARATE
+ * auto-update decision heartbeat (auto-update.ts): an absent [auto-update] trace
+ * identifies a controller that is not running. That is not re-derived here.
+ *
+ * Pure decision (computeDaemonVersionDifferential / decideStalenessAction) +
+ * injected IO, mirroring ci-sensor-loop.ts, so the loop is unit-testable without
+ * a live registry or DB. Registered in LOOP_REGISTRY under the opt-out guard
+ * TELORA_STALENESS_SENSOR_LOOP.
+ *
+ * The two infra-owned targets observed 2026-07-24 (npmjs mirror serving a stale
+ * version; Opus 5 seed merged-but-maybe-not-applied) are NOT computable from
+ * this repo (no prod DB access; infra alone publishes to npmjs). They are
+ * recorded, with their operator-facing close action, in
+ * docs/runbook-propagation-staleness-targets.md -- the sensor deliberately does
+ * NOT attempt those infra actions.
+ *
+ * @module staleness-sensor
+ */
+import { configForProduct } from '../shell/config.js';
+import { readFreshVersionCache } from './staleness.js';
+import { readDaemonMeta } from '../shell/daemon-process.js';
+import { isNewerVersion, parseVersionCore } from '../update/version-check.js';
+import { createEscalation, markEscalationResolved } from '../queries/issues.js';
+import { callApi } from '../queries/shared.js';
+import { daemonStalenessCauseKey } from '../queries/cause-key.js';
+import { ESCALATION_REASONS, ESCALATION_DISPOSITIONS } from '@telora/daemon-core';
+import { createLogger } from '../shell/log.js';
+const log = createLogger({ module: 'staleness-sensor' });
+/**
+ * escalation_kind for a stale daemon that the machine CANNOT auto-close (auto-update
+ * disabled). Carries a ready action, not a bare "gap exists" notice.
+ */
+export const PROPAGATION_STALE_ESCALATION_KIND = 'propagation_stale';
+/** Stable target id for the daemon-vs-registry differential. */
+export const DAEMON_VERSION_TARGET = 'daemon-version';
+/**
+ * Default patch-version distance that trips the signal. Any minor/major gap
+ * always trips regardless. A 1-2 patch gap is left quiet: auto-update closes it
+ * at the next idle seam, so signaling immediately would be noise. The observed
+ * failure (0.20.21 vs 0.20.28 = 7 patches) is well past this floor.
+ */
+export const DEFAULT_STALENESS_PATCH_THRESHOLD = 3;
+/** Component-wise (newest - running), clamped at 0 per component. */
+function versionDistance(running, newest) {
+    const r = parseVersionCore(running);
+    const n = parseVersionCore(newest);
+    if (!r || !n)
+        return { major: 0, minor: 0, patch: 0 };
+    return {
+        major: Math.max(0, n[0] - r[0]),
+        minor: Math.max(0, n[1] - r[1]),
+        patch: Math.max(0, n[2] - r[2]),
+    };
+}
+/**
+ * Compute the daemon-vs-registry differential. Returns null when it cannot be
+ * MEASURED (either version missing) -- the caller must then emit an explicit
+ * "UNMEASURED" trace rather than staying silent, so silence always means "in
+ * sync", never "not measured".
+ */
+export function computeDaemonVersionDifferential(running, newest, patchThreshold = DEFAULT_STALENESS_PATCH_THRESHOLD) {
+    if (!running || !newest)
+        return null;
+    const behind = isNewerVersion(newest, running);
+    const distance = versionDistance(running, newest);
+    const beyondThreshold = behind && (distance.major > 0 || distance.minor > 0 || distance.patch >= patchThreshold);
+    return { target: DAEMON_VERSION_TARGET, running, newest, behind, distance, beyondThreshold };
+}
+/**
+ * Pure decision. The pivot is `canMachineClose`: when the auto-update controller
+ * owns closing the daemon-version gap, the sensor NEVER hands a human a report --
+ * it defers (and retires any stale handover). A human is handed a ready action
+ * ONLY when the machine genuinely cannot act. A null differential (unmeasurable)
+ * never acts -- it is handled as a trace by the tick.
+ */
+export function decideStalenessAction(diff, hasOpen, canMachineClose) {
+    if (!diff)
+        return 'none';
+    if (diff.beyondThreshold) {
+        if (canMachineClose) {
+            // Auto-update closes this at the next safe seam. Defer to it. If a stale
+            // handover from a prior disabled period is still open, retire it -- the
+            // machine has reclaimed closure.
+            return hasOpen ? 'resolve' : 'delegate';
+        }
+        // Machine cannot act (auto-update off / npx). Hand over a ready action once.
+        return hasOpen ? 'none' : 'hand-over';
+    }
+    // Within threshold / in sync: retire any open handover, else stay quiet.
+    return hasOpen ? 'resolve' : 'none';
+}
+function formatDistance(d) {
+    return `${d.major}.${d.minor}.${d.patch}`;
+}
+/** The exact operator command that closes the gap when the machine cannot. */
+function readyUpdateCommand(newest) {
+    return `npm install -g @telora/daemon@${newest}   # then restart the daemon`;
+}
+/**
+ * Whether the auto-update controller can close the daemon-version gap itself.
+ * Mirrors auto-update.ts's own disable conditions: npx-cache installs never
+ * update, and --no-auto-update / TELORA_AUTO_UPDATE=0 (surfaced as
+ * autoUpdateEnabled=false in daemon.meta.json) opt the operator out.
+ *
+ * Defaults to true (the closer is opt-out and runs by default) when meta is
+ * absent or the field is unstamped, so an unknown state never manufactures a
+ * spurious human handover.
+ */
+function defaultCanMachineCloseGap() {
+    const meta = readDaemonMeta();
+    if (!meta)
+        return true;
+    if (meta.installMode === 'npx')
+        return false;
+    return meta.autoUpdateEnabled !== false;
+}
+const OPEN_STATUSES = new Set(['pending', 'in_review']);
+/** Statuses whose cause_key suppresses a re-file: open (idempotency) + dismissed (memory). */
+const SUPPRESSING_STATUSES = new Set(['pending', 'in_review', 'dismissed']);
+function isOpenPropagationStale(e) {
+    if (e.status && !OPEN_STATUSES.has(e.status))
+        return false;
+    return e.escalationKind === PROPAGATION_STALE_ESCALATION_KIND;
+}
+/**
+ * Pure suppression predicate over already-fetched rows. A re-file for THIS
+ * version gap is suppressed when an open/dismissed row carries its cause key
+ * (dismissal memory -- the incident pattern where a dismissed handover re-filed
+ * every tick), or a legacy OPEN propagation_stale row with no cause_key exists
+ * (deployment-window back-compat). A catch-up stops the signal entirely; a NEW
+ * `newest` is a different cause key and re-files. Exported for direct unit test.
+ */
+export function isStalenessRefileSuppressed(rows, params) {
+    const causeKey = daemonStalenessCauseKey(params.running, params.newest);
+    return rows.some((e) => {
+        if (SUPPRESSING_STATUSES.has(e.status ?? '')) {
+            const meta = e.metadata ?? null;
+            if (typeof meta?.cause_key === 'string' && meta.cause_key === causeKey)
+                return true;
+        }
+        // Legacy back-compat: an OPEN propagation_stale row with no cause_key suppresses.
+        return isOpenPropagationStale(e);
+    });
+}
+async function defaultHasOpenStalenessEscalation(params) {
+    const result = await callApi('escalation_list', {
+        // Include 'dismissed' so a dismissed handover keeps the same gap silent.
+        fields: { statuses: ['pending', 'in_review', 'dismissed'] },
+        limit: 500,
+    });
+    return isStalenessRefileSuppressed(result.escalations ?? [], params);
+}
+async function defaultResolveStalenessEscalations() {
+    const result = await callApi('escalation_list', {
+        fields: { statuses: ['pending', 'in_review'] },
+        limit: 500,
+    });
+    const open = (result.escalations ?? []).filter(isOpenPropagationStale);
+    let resolved = 0;
+    for (const e of open) {
+        try {
+            await markEscalationResolved(e.id, 'Auto-resolved by the daemon: the machine is closing the daemon-version gap ' +
+                '(back in sync, or auto-update re-enabled) -- no operator action needed.');
+            resolved++;
+        }
+        catch (err) {
+            log.warn(`Failed to resolve propagation_stale escalation ${e.id}: ${err.message}`);
+        }
+    }
+    return resolved;
+}
+/**
+ * Hand a human a READY ACTION (not a gap report) for a stale daemon the machine
+ * cannot auto-close. The description leads with the exact command to run; the
+ * escalation exists to carry the action, not to announce that a gap exists.
+ */
+async function defaultHandOverReadyAction(params) {
+    const { diff, readyCommand } = params;
+    await createEscalation({
+        organizationId: params.organizationId,
+        issueId: null,
+        reasonType: ESCALATION_REASONS.ERROR_ENCOUNTERED,
+        disposition: ESCALATION_DISPOSITIONS.NEEDS_OPERATOR,
+        productId: params.productId,
+        escalationKind: PROPAGATION_STALE_ESCALATION_KIND,
+        description: `Ready action -- update this daemon:\n\n    ${readyCommand}\n\n` +
+            `Auto-update is disabled on this daemon (running from an npx cache, or ` +
+            `--no-auto-update / TELORA_AUTO_UPDATE=0), so the machine cannot close the ` +
+            `daemon-version gap itself: running v${diff.running} while the Gitea registry ` +
+            `serves v${diff.newest} (behind by ${formatDistance(diff.distance)}). Running the ` +
+            `command above closes it. This resolves automatically once the running version ` +
+            `catches up, or if auto-update is re-enabled.`,
+        metadata: {
+            target: diff.target,
+            running_version: diff.running,
+            newest_version: diff.newest,
+            distance: diff.distance,
+            ready_command: readyCommand,
+            reason: 'auto_update_disabled',
+            product_id: params.productId,
+            // cause_key (running+newest) suppresses a re-file for the SAME gap across
+            // ticks AND after an operator dismissal; a new `newest` is a new cause key.
+            cause_key: daemonStalenessCauseKey(diff.running, diff.newest),
+        },
+    });
+}
+const defaultDeps = {
+    readRunningVersion: () => readDaemonMeta()?.version ?? null,
+    readNewestAvailable: () => readFreshVersionCache()?.latestVersion ?? null,
+    patchThreshold: DEFAULT_STALENESS_PATCH_THRESHOLD,
+    canMachineCloseGap: defaultCanMachineCloseGap,
+    hasOpenStalenessEscalation: defaultHasOpenStalenessEscalation,
+    handOverReadyAction: defaultHandOverReadyAction,
+    resolveStalenessEscalations: defaultResolveStalenessEscalations,
+};
+/**
+ * One propagation-staleness sensor tick. Computes the global daemon-vs-registry
+ * differential once (the running daemon has a single version). When the gap is
+ * beyond threshold the sensor DEFERS to the auto-update controller if that closer
+ * is active, and hands a human a ready action ONLY when it is not. Any handover
+ * is anchored to the first configured product for inbox visibility (the fact is
+ * process-global; all products share one org).
+ *
+ * Every path emits a trace so an absent signal means "measured and in sync".
+ */
+export async function runStalenessSensorTick(config, deps = defaultDeps) {
+    const counts = {
+        measured: false,
+        behind: false,
+        delegatedToAutoUpdate: false,
+        handoversToOperator: 0,
+        escalationsResolved: 0,
+    };
+    try {
+        const running = deps.readRunningVersion();
+        const newest = deps.readNewestAvailable();
+        const diff = computeDaemonVersionDifferential(running, newest, deps.patchThreshold);
+        if (!diff) {
+            // Not measurable this tick -- must NOT be silent (silence means in-sync).
+            log.warn(`[staleness] daemon-version differential UNMEASURED ` +
+                `(running=${running ?? 'unknown'}, newest=${newest ?? 'unknown'}); ` +
+                `cannot compute the propagation gap -- the version cache may not be warm yet.`);
+            return counts;
+        }
+        counts.measured = true;
+        counts.behind = diff.behind;
+        const anchor = config.products[0];
+        if (!anchor) {
+            log.info(`[staleness] measured: running v${diff.running} vs newest v${diff.newest} ` +
+                `(${diff.behind ? `behind ${formatDistance(diff.distance)}` : 'in sync'}); ` +
+                `no product configured to anchor a handover.`);
+            return counts;
+        }
+        const pc = configForProduct(config, anchor);
+        const canMachineClose = deps.canMachineCloseGap();
+        const hasOpen = await deps.hasOpenStalenessEscalation({ running: diff.running, newest: diff.newest });
+        const action = decideStalenessAction(diff, hasOpen, canMachineClose);
+        if (diff.beyondThreshold && canMachineClose) {
+            counts.delegatedToAutoUpdate = true;
+        }
+        if (action === 'hand-over') {
+            const readyCommand = readyUpdateCommand(diff.newest);
+            await deps.handOverReadyAction({
+                organizationId: pc.organizationId,
+                productId: pc.productId,
+                diff,
+                readyCommand,
+            });
+            counts.handoversToOperator++;
+            log.warn(`[staleness] daemon behind registry (running v${diff.running} < newest v${diff.newest}, ` +
+                `behind ${formatDistance(diff.distance)}) and auto-update is DISABLED -- the machine ` +
+                `cannot close it. Handed over ready action: ${readyCommand}`);
+        }
+        else if (action === 'delegate') {
+            log.info(`[staleness] daemon behind registry (running v${diff.running} < newest v${diff.newest}, ` +
+                `behind ${formatDistance(diff.distance)}); auto-update owns closure at the next safe ` +
+                `seam -- deferring, no operator action.`);
+        }
+        else if (action === 'resolve') {
+            counts.escalationsResolved += await deps.resolveStalenessEscalations();
+            log.info(diff.beyondThreshold
+                ? `[staleness] auto-update re-enabled while behind (v${diff.running}); the machine now ` +
+                    `owns closure -- retired the operator handover.`
+                : `[staleness] daemon back in sync with registry (v${diff.running}); ` +
+                    `retired the operator handover.`);
+        }
+        else {
+            // Positive in-sync (or within-threshold) trace: silence must never mean
+            // "not measured". This is the heartbeat that makes an absent signal
+            // diagnostic.
+            log.info(`[staleness] measured: running v${diff.running} vs newest v${diff.newest} -- ` +
+                (diff.behind
+                    ? `behind by ${formatDistance(diff.distance)} (within threshold).`
+                    : 'in sync.'));
+        }
+    }
+    catch (err) {
+        log.warn(`[staleness] tick failed: ${err.message}`);
+    }
+    return counts;
+}
+//# sourceMappingURL=staleness-sensor.js.map

package/dist/drift/staleness-sensor.js.map

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

package/dist/drift/staleness.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Staleness signal: is the RUNNING daemon behind the latest published release?
+ *
+ * Consumed by `telora-daemon status` and `telora-daemon session-state` to
+ * surface a one-line warning when the running daemon version is behind the
+ * latest published @telora/daemon. The CLI binary executing those commands may
+ * be a DIFFERENT install than the running daemon (repo checkout vs npx cache),
+ * so the running version comes from daemon.meta.json -- stamped by the daemon
+ * itself at startup -- never from the CLI's own package.json.
+ *
+ * Design constraints:
+ * - Silent degradation: never writes to stdout; any failure (no meta, legacy
+ *   meta without a version stamp, daemon not running, registry unreachable)
+ *   returns null so callers print their normal output unchanged. The
+ *   underlying checkForUpdates console.warns on failure -- that goes to
+ *   stderr, which the session-state stdout contract tolerates.
+ * - Cached: the registry answer is cached in the global state dir
+ *   (version-check-cache.json) with a 6h TTL. An EXPIRED cache is never used
+ *   as a fallback -- a failed refresh returns null rather than reporting
+ *   staleness from old data (no stale-cache false positives).
+ * - Latency split: session-state is CACHE-ONLY (zero network -- the
+ *   SessionStart hook blocks Claude Code on this command, and an unreachable
+ *   registry would otherwise hang it for the full fetch timeout). The async
+ *   half of "async or cached" lives in the RUNNING DAEMON, which refreshes
+ *   the cache on a timer (startVersionCacheRefreshLoop) in every install
+ *   mode, including npx with auto-update disabled -- the case the signal
+ *   exists for. `status` keeps the live registry fallback: it is an
+ *   interactive command where a few seconds for a fresh answer is fine.
+ */
+import { type DaemonMeta } from '../shell/daemon-process.js';
+import { type VersionCheckResult } from '../update/version-check.js';
+import type { InstallMode } from '../update/self-update.js';
+export interface StalenessInfo {
+    /** Version of the running daemon (from daemon.meta.json). */
+    runningVersion: string;
+    /** Latest published version (registry or fresh cache). */
+    latestVersion: string;
+    /** True when latestVersion is strictly newer than runningVersion. */
+    updateAvailable: boolean;
+    /** Install mode of the running daemon, when stamped. */
+    installMode?: InstallMode;
+    /** Whether the running daemon has auto-update enabled, when stamped. */
+    autoUpdateEnabled?: boolean;
+}
+/** On-disk shape of the version-check cache file. */
+export interface VersionCheckCache {
+    checkedAt: string;
+    latestVersion: string;
+}
+/** Cache freshness window. Within this, no network call is made. */
+export declare const VERSION_CHECK_CACHE_TTL_MS: number;
+/** Cache file name within the global state dir (~/.telora/). */
+export declare const VERSION_CHECK_CACHE_FILE = "version-check-cache.json";
+/** Injectable dependencies for {@link getStalenessInfoCore} (tests). */
+export interface StalenessDeps {
+    readMeta: () => DaemonMeta | null;
+    isDaemonRunning: () => boolean;
+    readCache: () => VersionCheckCache | null;
+    writeCache: (cache: VersionCheckCache) => void;
+    checkForUpdates: (currentVersion: string) => Promise<VersionCheckResult | null>;
+    now?: () => number;
+}
+export declare function resolveVersionCheckCachePath(): string;
+/**
+ * Read the version-check cache only when it is FRESH (within the TTL).
+ *
+ * The running daemon keeps this cache warm via {@link startVersionCacheRefreshLoop};
+ * the auto-update controller reads the candidate version from here instead of
+ * issuing a registry call on every idle edge, so rapid idle flapping cannot
+ * produce a registry-call storm. An expired cache returns null -- a stale
+ * answer must never drive an update decision.
+ */
+export declare function readFreshVersionCache(now?: () => number): VersionCheckCache | null;
+/** Options for {@link getStalenessInfoCore} / {@link getStalenessInfo}. */
+export interface StalenessOptions {
+    /**
+     * Never touch the network: answer from a fresh cache or return null.
+     * Used by session-state, whose stdout the SessionStart hook blocks on --
+     * an unreachable registry must not add even one fetch-timeout of latency.
+     * The running daemon's refresh loop keeps the cache warm.
+     */
+    cacheOnly?: boolean;
+}
+/**
+ * Compute staleness info for the running daemon, with injected dependencies.
+ *
+ * Returns null whenever the signal cannot be established with confidence:
+ * no meta file, legacy meta without a version stamp, daemon not running,
+ * or no fresh latest-version answer (expired cache + failed registry check,
+ * or expired cache in cacheOnly mode).
+ */
+export declare function getStalenessInfoCore(deps: StalenessDeps, opts?: StalenessOptions): Promise<StalenessInfo | null>;
+/**
+ * Compute staleness info for the running daemon (production deps).
+ * Never throws; never writes stdout. Returns null when no signal applies.
+ */
+export declare function getStalenessInfo(opts?: StalenessOptions): Promise<StalenessInfo | null>;
+/** Injectable dependencies for {@link maybeRefreshVersionCheckCacheCore} (tests). */
+export interface CacheRefreshDeps {
+    readCache: () => VersionCheckCache | null;
+    writeCache: (cache: VersionCheckCache) => void;
+    checkForUpdates: (currentVersion: string) => Promise<VersionCheckResult | null>;
+    now?: () => number;
+}
+/**
+ * Refresh the version-check cache when it is missing or expired.
+ * Returns true when a fresh registry answer was written, false when the
+ * cache was already fresh or the registry was unreachable (no write -- an
+ * expired cache stays expired rather than being re-stamped with old data).
+ */
+export declare function maybeRefreshVersionCheckCacheCore(deps: CacheRefreshDeps, currentVersion: string): Promise<boolean>;
+/** Production wrapper for {@link maybeRefreshVersionCheckCacheCore}. Never throws. */
+export declare function maybeRefreshVersionCheckCache(currentVersion: string): Promise<boolean>;
+/** Default interval for the daemon-side cache refresh loop (1h, like auto-update). */
+export declare const VERSION_CACHE_REFRESH_INTERVAL_MS: number;
+/**
+ * Start the daemon-side version-cache refresh loop.
+ *
+ * Runs in EVERY install mode regardless of the auto-update flag -- npx with
+ * auto-update disabled is precisely the configuration the staleness signal
+ * exists for. Each tick refreshes the cache only when it is missing/expired
+ * (the TTL throttles registry traffic to ~one fetch per 6h). The unref'd
+ * timer never blocks process exit. Returns a cleanup function.
+ */
+export declare function startVersionCacheRefreshLoop(currentVersion: string, intervalMs?: number): () => void;
+/**
+ * Format the one-line staleness warning, or null when no warning applies.
+ *
+ * When the daemon runs from an npx cache with auto-update disabled, the line
+ * carries the explicit escape hatch: self-update cannot replace an npx-cached
+ * binary in place, so a global install + restart is the fix.
+ */
+export declare function formatStalenessWarning(info: StalenessInfo | null): string | null;
+//# sourceMappingURL=staleness.d.ts.map

package/dist/drift/staleness.d.ts.map

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