@telora/daemon 0.21.26 → 0.21.82

package/dist/staleness-sensor.js

@@ -1,335 +0,0 @@
-/**
- * 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 './config.js';
-import { readFreshVersionCache } from './staleness.js';
-import { readDaemonMeta } from './daemon-process.js';
-import { isNewerVersion, parseVersionCore } from './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 './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/staleness-sensor.js.map

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

package/dist/staleness.d.ts

@@ -1,134 +0,0 @@
-/**
- * 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 './daemon-process.js';
-import { type VersionCheckResult } from './version-check.js';
-import type { InstallMode } from './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/staleness.d.ts.map

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