@telora/daemon 0.22.4 → 0.22.42

package/dist/drift/staleness-sensor.d.ts

@@ -1,55 +1,5 @@
-/**
- * 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 type { DaemonConfig } from '../types/index.js';
+import { type VersionDistance } from '../update/version-check.js';
 /**
  * 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.
@@ -64,12 +14,7 @@ export declare const DAEMON_VERSION_TARGET = "daemon-version";
  * failure (0.20.21 vs 0.20.28 = 7 patches) is well past this floor.
  */
 export declare const DEFAULT_STALENESS_PATCH_THRESHOLD = 3;
-/** Component-wise magnitude of how far `running` is behind `newest` (clamped at 0). */
-export interface VersionDistance {
-    major: number;
-    minor: number;
-    patch: number;
-}
+export type { VersionDistance };
 /** The computed newest-vs-running differential for a tracked target. */
 export interface StalenessDifferential {
     target: string;
@@ -92,8 +37,11 @@ export declare function computeDaemonVersionDifferential(running: string | null,
  * What the sensor should do with the current differential.
  *  - `delegate`   -- gap is beyond threshold and the machine closes it itself
  *                    (auto-update enabled): defer to that closer, no human.
- *  - `hand-over`  -- gap is beyond threshold but the machine cannot act
- *                    (auto-update disabled): hand a human a ready action.
+ *  - `hand-over`  -- gap is beyond threshold and a human signal is owed: either
+ *                    the machine cannot act (auto-update disabled -> a ready
+ *                    action), OR the machine SHOULD act but the gap has persisted
+ *                    past the wedge window without the running version advancing
+ *                    (auto-update wedged -> a needs_operator signal).
  *  - `resolve`    -- an open handover exists but the machine is now closing the
  *                    gap (back within threshold, OR auto-update re-enabled).
  *  - `none`       -- nothing to do.
@@ -101,12 +49,30 @@ export declare function computeDaemonVersionDifferential(running: string | null,
 export type StalenessAction = 'delegate' | 'hand-over' | 'resolve' | 'none';
 /**
  * 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.
+ * owns closing the daemon-version gap, the sensor normally DEFERS and never hands
+ * a human a report (and retires any stale handover). Two things pull a human in:
+ * the machine genuinely cannot act (`!canMachineClose`), OR the machine can act
+ * but the SAME beyond-threshold gap has persisted past the wedge window without
+ * the running version advancing (`wedged`) -- a closer that is enabled but not
+ * applying is a failed close, a legitimate operator signal, not an in-flight one
+ * to stay silent about. A null differential (unmeasurable) never acts.
  */
-export declare function decideStalenessAction(diff: StalenessDifferential | null, hasOpen: boolean, canMachineClose: boolean): StalenessAction;
+export declare function decideStalenessAction(diff: StalenessDifferential | null, hasOpen: boolean, canMachineClose: boolean, wedged?: boolean): StalenessAction;
+/**
+ * Record that `causeKey` is currently a beyond-threshold, machine-closable gap
+ * and report whether it has persisted at/past `thresholdMs`. Prunes any other
+ * key so the store stays single-entry (a new cause_key -- running advanced or a
+ * new newest -- starts a fresh clock). Pure over the injected store, so a unit
+ * test drives it with a fresh Map and a fixed clock.
+ */
+export declare function recordAndCheckGapWedged(store: Map<string, number>, causeKey: string, nowMs: number, thresholdMs: number): boolean;
+/**
+ * Default wedge window in hours: how long a machine-closable, beyond-threshold
+ * gap may persist without the running version advancing before the closer is
+ * treated as wedged. Kept ABOVE the auto-update drain threshold (6h default) so a
+ * legitimately-busy daemon that will drain-and-update on its own is never flagged.
+ */
+export declare const DEFAULT_STALENESS_WEDGE_THRESHOLD_HOURS = 12;
 /** Minimal open-escalation row shape the sensor's dedup / resolve reads. */
 interface StalenessEscalationRow {
     id: string;
@@ -126,10 +92,24 @@ export declare function isStalenessRefileSuppressed(rows: readonly StalenessEsca
     running: string;
     newest: string;
 }): boolean;
+/**
+ * Why a human is owed a signal for a beyond-threshold gap:
+ *  - `auto_update_disabled` -- the machine cannot act; hand a READY ACTION.
+ *  - `auto_update_wedged`   -- the machine SHOULD act but the gap has persisted
+ *                              past the wedge window without the running version
+ *                              advancing; the closer is enabled but not applying.
+ */
+export type StalenessHandoverReason = 'auto_update_disabled' | 'auto_update_wedged';
 /** Injected IO for the sensor tick. Defaults reach for the real implementations. */
 export interface StalenessSensorDeps {
     readRunningVersion: () => string | null;
     readNewestAvailable: () => string | null;
+    /** The registry the `newest` reading was consulted from (warm cache), or null
+     *  (legacy cache with no registry) -- used to ATTRIBUTE the reading. */
+    readReadingRegistry: () => string | null;
+    /** The registry npm resolves for an install of @telora/daemon -- the reading
+     *  must attribute to THIS for its agreement to count. */
+    readInstallRegistry: () => string;
     patchThreshold: number;
     /**
      * True when the auto-update controller can close the daemon-version gap itself.
@@ -141,14 +121,28 @@ export interface StalenessSensorDeps {
         running: string;
         newest: string;
     }) => Promise<boolean>;
-    /** Hand a human a READY ACTION when (and only when) the machine cannot act. */
+    /**
+     * Hand a human a signal for a beyond-threshold gap: a READY ACTION when the
+     * machine cannot act (reason auto_update_disabled), or a WEDGED-CLOSER signal
+     * when auto-update is enabled but not applying (reason auto_update_wedged).
+     */
     handOverReadyAction: (params: {
         organizationId: string;
         productId: string;
         diff: StalenessDifferential;
         readyCommand: string;
+        reason: StalenessHandoverReason;
+        registry: string;
     }) => Promise<void>;
     resolveStalenessEscalations: () => Promise<number>;
+    /**
+     * Whether a machine-closable, beyond-threshold gap for `causeKey` has persisted
+     * past the wedge window (auto-update enabled but the running version not
+     * advancing). Records first-seen on the way, so persistence is a code/state
+     * fact -- a test drives it with a stub returning true/false.
+     */
+    checkGapWedged: (causeKey: string, nowMs: number) => boolean;
+    now: () => number;
 }
 export interface StalenessSensorTickCounts {
     /** True when the differential could be computed (both versions known). */
@@ -157,8 +151,10 @@ export interface StalenessSensorTickCounts {
     behind: boolean;
     /** True when the machine (auto-update) owns closing the measured gap this tick. */
     delegatedToAutoUpdate: boolean;
-    /** Ready-action handovers filed -- only when the machine genuinely cannot act. */
+    /** Handovers filed this tick (auto-update disabled OR wedged). */
     handoversToOperator: number;
+    /** Of the handovers, those filed because auto-update is enabled but WEDGED. */
+    wedgedSignalsFiled: number;
     escalationsResolved: number;
 }
 /**
@@ -172,5 +168,4 @@ export interface StalenessSensorTickCounts {
  * Every path emits a trace so an absent signal means "measured and in sync".
  */
 export declare function runStalenessSensorTick(config: DaemonConfig, deps?: StalenessSensorDeps): Promise<StalenessSensorTickCounts>;
-export {};
 //# sourceMappingURL=staleness-sensor.d.ts.map

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

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

package/dist/drift/staleness-sensor.js

@@ -1,10 +1,72 @@
 // PINNED-BY-BEGIN (generated by gen:pinned-by -- do not hand-edit; checked by lint:pinned-by)
 // Pinned by: packages/daemon/src/drift/staleness-sensor.test.ts
 // PINNED-BY-END
+/**
+ * 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 INSTALL registry --
+ * the registry npm resolves for `npm install -g @telora/daemon@latest`, which is
+ * npmjs or Gitea or a mirror depending on the host's npm config, NOT a fixed host:
+ *
+ *   running = ~/.telora/daemon.meta.json .version   (this daemon's own build)
+ *   newest  = the warm version cache .latestVersion  (dist-tags.latest from the
+ *             registry checkForUpdates resolved, kept fresh by
+ *             startVersionCacheRefreshLoop)
+ *
+ * ATTRIBUTED readings only. The cache records WHICH registry produced `newest`;
+ * a reading is trusted only when that registry is the one npm resolves for an
+ * install. A reading from any other registry (an operator's TELORA_REGISTRY_URL
+ * override, a legacy cache with no registry) is reported UNMEASURED, never
+ * "in sync" -- a host cannot certify the installed version is current by reading
+ * a registry the installer does not use.
+ *
+ * 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 { hostname as osHostname } from 'node:os';
 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 { isNewerVersion, versionDistance, resolveInstallRegistryUrl, isReadingAttributable, } from '../update/version-check.js';
 import { createEscalation, markEscalationResolved } from '../queries/escalations.js';
 import { callApi } from '../queries/shared.js';
 import { daemonStalenessCauseKey } from '../queries/cause-key.js';
@@ -25,18 +87,6 @@ export const DAEMON_VERSION_TARGET = 'daemon-version';
  * 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
@@ -53,16 +103,24 @@ export function computeDaemonVersionDifferential(running, newest, patchThreshold
 }
 /**
  * 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.
+ * owns closing the daemon-version gap, the sensor normally DEFERS and never hands
+ * a human a report (and retires any stale handover). Two things pull a human in:
+ * the machine genuinely cannot act (`!canMachineClose`), OR the machine can act
+ * but the SAME beyond-threshold gap has persisted past the wedge window without
+ * the running version advancing (`wedged`) -- a closer that is enabled but not
+ * applying is a failed close, a legitimate operator signal, not an in-flight one
+ * to stay silent about. A null differential (unmeasurable) never acts.
  */
-export function decideStalenessAction(diff, hasOpen, canMachineClose) {
+export function decideStalenessAction(diff, hasOpen, canMachineClose, wedged = false) {
     if (!diff)
         return 'none';
     if (diff.beyondThreshold) {
         if (canMachineClose) {
+            if (wedged) {
+                // Enabled but not applying: the running version has not advanced past the
+                // wedge window. Hand a human a signal once (dedup by cause_key).
+                return hasOpen ? 'none' : 'hand-over';
+            }
             // 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.
@@ -74,6 +132,51 @@ export function decideStalenessAction(diff, hasOpen, canMachineClose) {
     // Within threshold / in sync: retire any open handover, else stay quiet.
     return hasOpen ? 'resolve' : 'none';
 }
+/**
+ * First-seen wall-clock (ms) per beyond-threshold, machine-closable cause_key,
+ * for wedge detection. Module state: it persists for the life of THIS running
+ * daemon -- which is exactly the wedged case (a closer that is not applying never
+ * restarts), while a successful update restarts the process and clears it. A
+ * genuine catch-up changes the running version and thus the cause_key, resetting
+ * the clock on its own.
+ */
+const gapFirstSeen = new Map();
+/**
+ * Record that `causeKey` is currently a beyond-threshold, machine-closable gap
+ * and report whether it has persisted at/past `thresholdMs`. Prunes any other
+ * key so the store stays single-entry (a new cause_key -- running advanced or a
+ * new newest -- starts a fresh clock). Pure over the injected store, so a unit
+ * test drives it with a fresh Map and a fixed clock.
+ */
+export function recordAndCheckGapWedged(store, causeKey, nowMs, thresholdMs) {
+    for (const k of [...store.keys()])
+        if (k !== causeKey)
+            store.delete(k);
+    const firstSeen = store.get(causeKey) ?? nowMs;
+    if (!store.has(causeKey))
+        store.set(causeKey, firstSeen);
+    return nowMs - firstSeen >= thresholdMs;
+}
+/**
+ * Default wedge window in hours: how long a machine-closable, beyond-threshold
+ * gap may persist without the running version advancing before the closer is
+ * treated as wedged. Kept ABOVE the auto-update drain threshold (6h default) so a
+ * legitimately-busy daemon that will drain-and-update on its own is never flagged.
+ */
+export const DEFAULT_STALENESS_WEDGE_THRESHOLD_HOURS = 12;
+/**
+ * The configured wedge window in ms. Read straight from process.env (the knob is
+ * declared in daemon-core env-config for discoverability, but read directly here
+ * so the daemon does not depend on a daemon-core republish to honor it), with a
+ * safe fallback to {@link DEFAULT_STALENESS_WEDGE_THRESHOLD_HOURS} on absent /
+ * non-numeric / non-positive input.
+ */
+function loadWedgeThresholdMs() {
+    const raw = process.env.TELORA_STALENESS_WEDGE_THRESHOLD_HOURS;
+    const hours = raw !== undefined && raw.trim() !== '' ? Number(raw) : DEFAULT_STALENESS_WEDGE_THRESHOLD_HOURS;
+    const safe = Number.isFinite(hours) && hours > 0 ? hours : DEFAULT_STALENESS_WEDGE_THRESHOLD_HOURS;
+    return safe * 3_600_000;
+}
 function formatDistance(d) {
     return `${d.major}.${d.minor}.${d.patch}`;
 }
@@ -155,12 +258,30 @@ async function defaultResolveStalenessEscalations() {
     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.
+ * Hand a human a signal for a stale daemon: a READY ACTION when the machine
+ * cannot auto-close (`auto_update_disabled`), or a WEDGED-CLOSER signal when
+ * auto-update is enabled but has not advanced the running version past the wedge
+ * window (`auto_update_wedged`). Both carry running/newest/distance and share the
+ * cause_key dedup + auto-resolve path, so either auto-resolves once the running
+ * version catches up.
  */
 async function defaultHandOverReadyAction(params) {
-    const { diff, readyCommand } = params;
+    const { diff, readyCommand, reason, registry } = params;
+    const description = reason === 'auto_update_wedged'
+        ? `Auto-update appears WEDGED on this daemon (host ${osHostname()}): it is ENABLED ` +
+            `but the running version has not advanced past v${diff.running} while the install ` +
+            `registry ${registry} serves v${diff.newest} (behind by ${formatDistance(diff.distance)}), and ` +
+            `the gap has persisted past the wedge window. A fix has shipped but is not running. ` +
+            `Check the [auto-update] trace in ~/.telora/daemon.log and restart the daemon; if ` +
+            `it still will not advance, install manually:\n\n    ${readyCommand}\n\n` +
+            `This resolves automatically once the running version catches up.`
+        : `Ready action -- update this daemon (host ${osHostname()}):\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 install registry ` +
+            `${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.`;
     await createEscalation({
         organizationId: params.organizationId,
         issueId: null,
@@ -168,20 +289,16 @@ async function defaultHandOverReadyAction(params) {
         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.`,
+        description,
         metadata: {
             target: diff.target,
             running_version: diff.running,
             newest_version: diff.newest,
             distance: diff.distance,
+            registry,
             ready_command: readyCommand,
-            reason: 'auto_update_disabled',
+            reason,
+            host: osHostname(),
             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.
@@ -192,12 +309,72 @@ async function defaultHandOverReadyAction(params) {
 const defaultDeps = {
     readRunningVersion: () => readDaemonMeta()?.version ?? null,
     readNewestAvailable: () => readFreshVersionCache()?.latestVersion ?? null,
+    readReadingRegistry: () => readFreshVersionCache()?.registryUrl ?? null,
+    readInstallRegistry: () => resolveInstallRegistryUrl(),
     patchThreshold: DEFAULT_STALENESS_PATCH_THRESHOLD,
     canMachineCloseGap: defaultCanMachineCloseGap,
     hasOpenStalenessEscalation: defaultHasOpenStalenessEscalation,
     handOverReadyAction: defaultHandOverReadyAction,
     resolveStalenessEscalations: defaultResolveStalenessEscalations,
+    checkGapWedged: (causeKey, nowMs) => recordAndCheckGapWedged(gapFirstSeen, causeKey, nowMs, loadWedgeThresholdMs()),
+    now: Date.now,
 };
+/**
+ * Act on the decided staleness action (hand-over / delegate / resolve / none)
+ * and emit its trace, mutating `counts`. Extracted verbatim from
+ * runStalenessSensorTick so that function stays within the per-function size
+ * limit -- a cohesive "apply the decision" step, no behavior change.
+ */
+async function applyStalenessAction(args) {
+    const { action, diff, pc, canMachineClose, installRegistry, counts, deps } = args;
+    if (action === 'hand-over') {
+        const readyCommand = readyUpdateCommand(diff.newest);
+        // canMachineClose + hand-over can only mean wedged (decideStalenessAction);
+        // !canMachineClose means auto-update is disabled.
+        const reason = canMachineClose ? 'auto_update_wedged' : 'auto_update_disabled';
+        await deps.handOverReadyAction({
+            organizationId: pc.organizationId,
+            productId: pc.productId,
+            diff,
+            readyCommand,
+            reason,
+            registry: installRegistry,
+        });
+        counts.handoversToOperator++;
+        if (reason === 'auto_update_wedged')
+            counts.wedgedSignalsFiled++;
+        log.warn(reason === 'auto_update_wedged'
+            ? `[staleness] daemon behind registry ${installRegistry} (running v${diff.running} < newest ` +
+                `v${diff.newest}, behind ${formatDistance(diff.distance)}) and auto-update is ENABLED but ` +
+                `WEDGED (not advancing past the wedge window) -- filed a needs_operator signal.`
+            : `[staleness] daemon behind registry ${installRegistry} (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 ${installRegistry} (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 ${installRegistry} (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. Names the registry the reading was attributed to.
+        log.info(`[staleness] measured against registry ${installRegistry}: running v${diff.running} vs ` +
+            `newest v${diff.newest} -- ` +
+            (diff.behind
+                ? `behind by ${formatDistance(diff.distance)} (within threshold).`
+                : 'in sync.'));
+    }
+}
 /**
  * One propagation-staleness sensor tick. Computes the global daemon-vs-registry
  * differential once (the running daemon has a single version). When the gap is
@@ -214,6 +391,7 @@ export async function runStalenessSensorTick(config, deps = defaultDeps) {
         behind: false,
         delegatedToAutoUpdate: false,
         handoversToOperator: 0,
+        wedgedSignalsFiled: 0,
         escalationsResolved: 0,
     };
     try {
@@ -227,57 +405,44 @@ export async function runStalenessSensorTick(config, deps = defaultDeps) {
                 `cannot compute the propagation gap -- the version cache may not be warm yet.`);
             return counts;
         }
+        // Attribution gate: the `newest` reading must be attributable to the registry
+        // npm resolves for an install. A reading from any other registry (a
+        // TELORA_REGISTRY_URL override, a legacy cache with no registry) is UNMEASURED
+        // -- reporting "in sync" here would certify the installed version against a
+        // registry the installer does not use (the mars false-negative, on the
+        // platform). Silence still means "measured and in sync", never "not measured".
+        const readingRegistry = deps.readReadingRegistry();
+        const installRegistry = deps.readInstallRegistry();
+        if (!isReadingAttributable(readingRegistry, installRegistry)) {
+            log.warn(`[staleness] daemon-version differential UNMEASURED: the newest reading (v${diff.newest}) ` +
+                `came from registry ${readingRegistry ?? 'unknown'}, but an install of @telora/daemon ` +
+                `resolves ${installRegistry} -- cannot attribute the reading to the install registry, ` +
+                `so NOT asserting in sync.`);
+            return counts; // measured stays false -- unattributable is UNMEASURED.
+        }
         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} ` +
+            log.info(`[staleness] measured against registry ${installRegistry}: 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();
+        // Wedge check only where the machine SHOULD be closing the gap: enabled but
+        // the same beyond-threshold gap has persisted past the wedge window without
+        // the running version advancing. Records first-seen as a side effect.
+        const causeKey = daemonStalenessCauseKey(diff.running, diff.newest);
+        const wedged = diff.beyondThreshold && canMachineClose ? deps.checkGapWedged(causeKey, deps.now()) : false;
         const hasOpen = await deps.hasOpenStalenessEscalation({ running: diff.running, newest: diff.newest });
-        const action = decideStalenessAction(diff, hasOpen, canMachineClose);
-        if (diff.beyondThreshold && canMachineClose) {
+        const action = decideStalenessAction(diff, hasOpen, canMachineClose, wedged);
+        if (diff.beyondThreshold && canMachineClose && !wedged) {
             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.'));
-        }
+        await applyStalenessAction({ action, diff, pc, canMachineClose, installRegistry, counts, deps });
     }
     catch (err) {
         log.warn(`[staleness] tick failed: ${err.message}`);