instar 1.3.72 → 1.3.74

package/dist/core/SleepWakeDetector.d.ts

@@ -6,6 +6,32 @@
  * We detect this drift and fire a callback.
  *
  * Ported from Dawn's infrastructure — battle-tested in production.
+ *
+ * ## CPU-starvation guard (2026-05-28)
+ *
+ * Timer drift has TWO causes, not one:
+ *   1. Real sleep — the OS suspends the process; the wall clock jumps forward.
+ *   2. CPU starvation — the machine is so oversubscribed (load >> cores) that the
+ *      event loop can't service the `checkIntervalMs` timer on time. The wall
+ *      clock advances normally, but the callback fires seconds late.
+ *
+ * The original detector could not tell these apart, so on a heavily-loaded box
+ * (e.g. many concurrent agent sessions) it fired hundreds of false "wake" events
+ * — each triggering expensive wake-recovery (tunnel restart, re-registration,
+ * failure-counter resets) that piled MORE load on, a self-reinforcing storm.
+ *
+ * The guard distinguishes the two:
+ *   - A **long** drift (>= `longSleepFloorSeconds`) is unambiguously real sleep —
+ *     a live machine never starves its own event loop for minutes (a watchdog
+ *     would declare it dead first). Always emitted, regardless of load.
+ *   - A **short** drift under high system load (`loadavg[0] / cpuCount >
+ *     maxLoadRatio`) is treated as CPU starvation and SUPPRESSED — no `wake`.
+ *   - A short drift under normal load is a brief real sleep — emitted.
+ * On top of classification, a `minWakeIntervalMs` cooldown caps the emit rate so
+ * even a misclassified burst can't trigger a recovery storm.
+ *
+ * Suppressed events are NOT added to `wakeHistory`, so `getCumulativeSleepMsBetween`
+ * (the wake-reaper's sleep-credit source) only ever counts genuine sleep.
  */
 import { EventEmitter } from 'node:events';
 export interface SleepWakeDetectorConfig {
@@ -13,20 +39,73 @@ export interface SleepWakeDetectorConfig {
     checkIntervalMs?: number;
     /** How much drift (ms) indicates a sleep event. Default: 10000 */
     driftThresholdMs?: number;
+    /**
+     * Above this `loadavg[0] / cpuCount` ratio, a SHORT drift is classified as CPU
+     * starvation and suppressed rather than emitted as a wake. Default: 1.5.
+     * Set to `Infinity` to disable the load guard (always trust the drift).
+     */
+    maxLoadRatio?: number;
+    /**
+     * A drift at least this long (seconds) is always treated as real sleep,
+     * regardless of load — a live event loop never starves for this long.
+     * Default: 300 (5 minutes).
+     */
+    longSleepFloorSeconds?: number;
+    /**
+     * Minimum gap (ms) between EMITTED wake events. A short drift that would emit
+     * within this cooldown of the previous emitted wake is suppressed, bounding
+     * recovery storms. Long sleeps bypass the cooldown. Default: 60000 (1 min).
+     */
+    minWakeIntervalMs?: number;
+    /** Injectable system-load source (testing). Default: os.loadavg. */
+    loadAvgProvider?: () => number[];
+    /** Injectable CPU-count source (testing). Default: os.cpus().length. */
+    cpuCountProvider?: () => number;
+    /** Injectable wall-clock source (testing). Default: Date.now. */
+    nowProvider?: () => number;
 }
 export interface WakeEvent {
     sleepDurationSeconds: number;
     timestamp: string;
 }
+export type WakeSuppressionReason = 'cpu-starvation' | 'cooldown';
+export interface SuppressedWakeEvent {
+    reason: WakeSuppressionReason;
+    driftSeconds: number;
+    loadRatio: number;
+    timestamp: string;
+}
+export interface SleepWakeStats {
+    wakeCount: number;
+    totalSleepSeconds: number;
+    longestSleepSeconds: number;
+    /** Drifts classified as CPU starvation / rate-limited and NOT emitted. */
+    suppressedCount: number;
+    suppressedByReason: Record<WakeSuppressionReason, number>;
+    /** ISO timestamp of the most recent suppression, or null. */
+    lastSuppressedAt: string | null;
+}
 export declare class SleepWakeDetector extends EventEmitter {
     private interval;
     private lastTick;
+    private lastEmittedWakeAtMs;
     private checkIntervalMs;
     private driftThresholdMs;
+    private maxLoadRatio;
+    private longSleepFloorSeconds;
+    private minWakeIntervalMs;
+    private loadAvgProvider;
+    private cpuCountProvider;
+    private now;
     private wakeHistory;
+    private suppressionHistory;
     constructor(config?: SleepWakeDetectorConfig);
     start(): void;
     stop(): void;
+    /** Current `loadavg[0] / cpuCount` ratio. Returns 0 when load is unavailable
+     *  (e.g. Windows reports [0,0,0]), which disables the starvation guard there. */
+    private currentLoadRatio;
+    private recordSuppression;
     /**
      * Cumulative wall-time-asleep during the half-open window [startMs, endMs).
      * Used by the wake-reaper (UNIFIED-SESSION-LIFECYCLE §P0 #9 / SE-8) to subtract
@@ -38,13 +117,12 @@ export declare class SleepWakeDetector extends EventEmitter {
      *   [wakeTimestamp − sleepDurationSeconds, wakeTimestamp].
      * Returns the sum of overlap with the query window in milliseconds. Returns 0
      * when the history is empty or no event overlaps.
+     *
+     * Only EMITTED wakes are in `wakeHistory`; suppressed CPU-starvation drifts are
+     * deliberately excluded so starvation is never credited as real sleep.
      */
     getCumulativeSleepMsBetween(startMs: number, endMs: number): number;
     /** Get wake event stats for telemetry reporting. */
-    getStats(sinceMs?: number): {
-        wakeCount: number;
-        totalSleepSeconds: number;
-        longestSleepSeconds: number;
-    };
+    getStats(sinceMs?: number): SleepWakeStats;
 }
 //# sourceMappingURL=SleepWakeDetector.d.ts.map

package/dist/core/SleepWakeDetector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SleepWakeDetector.d.ts","sourceRoot":"","sources":["../../src/core/SleepWakeDetector.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,WAAW,uBAAuB;IACtC,uDAAuD;IACvD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,SAAS;IACxB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,iBAAkB,SAAQ,YAAY;IACjD,OAAO,CAAC,QAAQ,CAA+C;IAC/D,OAAO,CAAC,QAAQ,CAAsB;IACtC,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,WAAW,CAAmB;gBAE1B,MAAM,GAAE,uBAA4B;IAMhD,KAAK,IAAI,IAAI;IAqBb,IAAI,IAAI,IAAI;IAOZ;;;;;;;;;;;OAWG;IACH,2BAA2B,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM;IAanE,oDAAoD;IACpD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,MAAM,CAAC;QAAC,mBAAmB,EAAE,MAAM,CAAA;KAAE;CAS1G"}
+{"version":3,"file":"SleepWakeDetector.d.ts","sourceRoot":"","sources":["../../src/core/SleepWakeDetector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,MAAM,WAAW,uBAAuB;IACtC,uDAAuD;IACvD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,oEAAoE;IACpE,eAAe,CAAC,EAAE,MAAM,MAAM,EAAE,CAAC;IACjC,wEAAwE;IACxE,gBAAgB,CAAC,EAAE,MAAM,MAAM,CAAC;IAChC,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,SAAS;IACxB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,qBAAqB,GAAG,gBAAgB,GAAG,UAAU,CAAC;AAElE,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,qBAAqB,CAAC;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,0EAA0E;IAC1E,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,MAAM,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;IAC1D,6DAA6D;IAC7D,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,qBAAa,iBAAkB,SAAQ,YAAY;IACjD,OAAO,CAAC,QAAQ,CAA+C;IAC/D,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,mBAAmB,CAAuB;IAClD,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,qBAAqB,CAAS;IACtC,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,eAAe,CAAiB;IACxC,OAAO,CAAC,gBAAgB,CAAe;IACvC,OAAO,CAAC,GAAG,CAAe;IAC1B,OAAO,CAAC,WAAW,CAAmB;IACtC,OAAO,CAAC,kBAAkB,CAA6B;gBAE3C,MAAM,GAAE,uBAA4B;IAahD,KAAK,IAAI,IAAI;IAkDb,IAAI,IAAI,IAAI;IAOZ;qFACiF;IACjF,OAAO,CAAC,gBAAgB;IAiBxB,OAAO,CAAC,iBAAiB;IAezB;;;;;;;;;;;;;;OAcG;IACH,2BAA2B,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM;IAanE,oDAAoD;IACpD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,cAAc;CAkB3C"}

package/dist/core/SleepWakeDetector.js

@@ -6,36 +6,98 @@
  * We detect this drift and fire a callback.
  *
  * Ported from Dawn's infrastructure — battle-tested in production.
+ *
+ * ## CPU-starvation guard (2026-05-28)
+ *
+ * Timer drift has TWO causes, not one:
+ *   1. Real sleep — the OS suspends the process; the wall clock jumps forward.
+ *   2. CPU starvation — the machine is so oversubscribed (load >> cores) that the
+ *      event loop can't service the `checkIntervalMs` timer on time. The wall
+ *      clock advances normally, but the callback fires seconds late.
+ *
+ * The original detector could not tell these apart, so on a heavily-loaded box
+ * (e.g. many concurrent agent sessions) it fired hundreds of false "wake" events
+ * — each triggering expensive wake-recovery (tunnel restart, re-registration,
+ * failure-counter resets) that piled MORE load on, a self-reinforcing storm.
+ *
+ * The guard distinguishes the two:
+ *   - A **long** drift (>= `longSleepFloorSeconds`) is unambiguously real sleep —
+ *     a live machine never starves its own event loop for minutes (a watchdog
+ *     would declare it dead first). Always emitted, regardless of load.
+ *   - A **short** drift under high system load (`loadavg[0] / cpuCount >
+ *     maxLoadRatio`) is treated as CPU starvation and SUPPRESSED — no `wake`.
+ *   - A short drift under normal load is a brief real sleep — emitted.
+ * On top of classification, a `minWakeIntervalMs` cooldown caps the emit rate so
+ * even a misclassified burst can't trigger a recovery storm.
+ *
+ * Suppressed events are NOT added to `wakeHistory`, so `getCumulativeSleepMsBetween`
+ * (the wake-reaper's sleep-credit source) only ever counts genuine sleep.
  */
 import { EventEmitter } from 'node:events';
+import os from 'node:os';
 export class SleepWakeDetector extends EventEmitter {
     interval = null;
-    lastTick = Date.now();
+    lastTick;
+    lastEmittedWakeAtMs = null;
     checkIntervalMs;
     driftThresholdMs;
+    maxLoadRatio;
+    longSleepFloorSeconds;
+    minWakeIntervalMs;
+    loadAvgProvider;
+    cpuCountProvider;
+    now;
     wakeHistory = [];
+    suppressionHistory = [];
     constructor(config = {}) {
         super();
         this.checkIntervalMs = config.checkIntervalMs ?? 2000;
         this.driftThresholdMs = config.driftThresholdMs ?? 10000;
+        this.maxLoadRatio = config.maxLoadRatio ?? 1.5;
+        this.longSleepFloorSeconds = config.longSleepFloorSeconds ?? 300;
+        this.minWakeIntervalMs = config.minWakeIntervalMs ?? 60000;
+        this.loadAvgProvider = config.loadAvgProvider ?? (() => os.loadavg());
+        this.cpuCountProvider = config.cpuCountProvider ?? (() => os.cpus().length);
+        this.now = config.nowProvider ?? (() => Date.now());
+        this.lastTick = this.now();
     }
     start() {
         if (this.interval)
             return;
-        this.lastTick = Date.now();
+        this.lastTick = this.now();
         this.interval = setInterval(() => {
-            const now = Date.now();
+            const now = this.now();
             const elapsed = now - this.lastTick;
             this.lastTick = now;
-            if (elapsed > this.driftThresholdMs) {
-                const sleepDuration = Math.round((elapsed - this.checkIntervalMs) / 1000);
-                console.log(`[SleepWakeDetector] Wake detected after ~${sleepDuration}s sleep`);
-                const event = { sleepDurationSeconds: sleepDuration, timestamp: new Date().toISOString() };
-                this.wakeHistory.push(event);
-                if (this.wakeHistory.length > 100)
-                    this.wakeHistory.shift();
-                this.emit('wake', event);
+            if (elapsed <= this.driftThresholdMs)
+                return;
+            const sleepDuration = Math.round((elapsed - this.checkIntervalMs) / 1000);
+            const isLongSleep = sleepDuration >= this.longSleepFloorSeconds;
+            const loadRatio = this.currentLoadRatio();
+            // Short drift under heavy CPU load = event-loop starvation, not sleep.
+            if (!isLongSleep && loadRatio > this.maxLoadRatio) {
+                this.recordSuppression('cpu-starvation', sleepDuration, loadRatio, now);
+                console.warn(`[SleepWakeDetector] Drift ~${sleepDuration}s under load ratio ${loadRatio.toFixed(2)} ` +
+                    `(> ${this.maxLoadRatio}) — treating as CPU starvation, suppressing wake`);
+                return;
+            }
+            // Rate-limit emitted wakes so even a misclassified burst can't storm
+            // recovery. Long sleeps bypass the cooldown — recovery there is essential.
+            if (!isLongSleep &&
+                this.lastEmittedWakeAtMs !== null &&
+                now - this.lastEmittedWakeAtMs < this.minWakeIntervalMs) {
+                this.recordSuppression('cooldown', sleepDuration, loadRatio, now);
+                console.warn(`[SleepWakeDetector] Wake within cooldown ` +
+                    `(${now - this.lastEmittedWakeAtMs}ms < ${this.minWakeIntervalMs}ms) — suppressing duplicate recovery`);
+                return;
             }
+            console.log(`[SleepWakeDetector] Wake detected after ~${sleepDuration}s sleep`);
+            const event = { sleepDurationSeconds: sleepDuration, timestamp: new Date(now).toISOString() };
+            this.wakeHistory.push(event);
+            if (this.wakeHistory.length > 100)
+                this.wakeHistory.shift();
+            this.lastEmittedWakeAtMs = now;
+            this.emit('wake', event);
         }, this.checkIntervalMs);
         this.interval.unref(); // Don't prevent process exit in CLI contexts
     }
@@ -45,6 +107,37 @@ export class SleepWakeDetector extends EventEmitter {
             this.interval = null;
         }
     }
+    /** Current `loadavg[0] / cpuCount` ratio. Returns 0 when load is unavailable
+     *  (e.g. Windows reports [0,0,0]), which disables the starvation guard there. */
+    currentLoadRatio() {
+        let cpuCount = 1;
+        try {
+            cpuCount = Math.max(1, this.cpuCountProvider());
+        }
+        catch {
+            cpuCount = 1;
+        }
+        let load1 = 0;
+        try {
+            load1 = this.loadAvgProvider()[0] ?? 0;
+        }
+        catch {
+            load1 = 0;
+        }
+        if (!Number.isFinite(load1) || load1 <= 0)
+            return 0;
+        return load1 / cpuCount;
+    }
+    recordSuppression(reason, driftSeconds, loadRatio, nowMs) {
+        this.suppressionHistory.push({
+            reason,
+            driftSeconds,
+            loadRatio: Math.round(loadRatio * 100) / 100,
+            timestamp: new Date(nowMs).toISOString(),
+        });
+        if (this.suppressionHistory.length > 100)
+            this.suppressionHistory.shift();
+    }
     /**
      * Cumulative wall-time-asleep during the half-open window [startMs, endMs).
      * Used by the wake-reaper (UNIFIED-SESSION-LIFECYCLE §P0 #9 / SE-8) to subtract
@@ -56,6 +149,9 @@ export class SleepWakeDetector extends EventEmitter {
      *   [wakeTimestamp − sleepDurationSeconds, wakeTimestamp].
      * Returns the sum of overlap with the query window in milliseconds. Returns 0
      * when the history is empty or no event overlaps.
+     *
+     * Only EMITTED wakes are in `wakeHistory`; suppressed CPU-starvation drifts are
+     * deliberately excluded so starvation is never credited as real sleep.
      */
     getCumulativeSleepMsBetween(startMs, endMs) {
         if (endMs <= startMs)
@@ -75,10 +171,20 @@ export class SleepWakeDetector extends EventEmitter {
     getStats(sinceMs) {
         const since = sinceMs ?? 0;
         const relevant = this.wakeHistory.filter(e => new Date(e.timestamp).getTime() >= since);
+        const suppressed = this.suppressionHistory.filter(e => new Date(e.timestamp).getTime() >= since);
+        const suppressedByReason = {
+            'cpu-starvation': 0,
+            cooldown: 0,
+        };
+        for (const e of suppressed)
+            suppressedByReason[e.reason]++;
         return {
             wakeCount: relevant.length,
             totalSleepSeconds: relevant.reduce((sum, e) => sum + e.sleepDurationSeconds, 0),
             longestSleepSeconds: relevant.length > 0 ? Math.max(...relevant.map(e => e.sleepDurationSeconds)) : 0,
+            suppressedCount: suppressed.length,
+            suppressedByReason,
+            lastSuppressedAt: suppressed.length > 0 ? suppressed[suppressed.length - 1].timestamp : null,
         };
     }
 }

package/dist/core/SleepWakeDetector.js.map

@@ -1 +1 @@
-{"version":3,"file":"SleepWakeDetector.js","sourceRoot":"","sources":["../../src/core/SleepWakeDetector.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"SleepWakeDetector.js","sourceRoot":"","sources":["../../src/core/SleepWakeDetector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,MAAM,SAAS,CAAC;AA0DzB,MAAM,OAAO,iBAAkB,SAAQ,YAAY;IACzC,QAAQ,GAA0C,IAAI,CAAC;IACvD,QAAQ,CAAS;IACjB,mBAAmB,GAAkB,IAAI,CAAC;IAC1C,eAAe,CAAS;IACxB,gBAAgB,CAAS;IACzB,YAAY,CAAS;IACrB,qBAAqB,CAAS;IAC9B,iBAAiB,CAAS;IAC1B,eAAe,CAAiB;IAChC,gBAAgB,CAAe;IAC/B,GAAG,CAAe;IAClB,WAAW,GAAgB,EAAE,CAAC;IAC9B,kBAAkB,GAA0B,EAAE,CAAC;IAEvD,YAAY,SAAkC,EAAE;QAC9C,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,eAAe,GAAG,MAAM,CAAC,eAAe,IAAI,IAAI,CAAC;QACtD,IAAI,CAAC,gBAAgB,GAAG,MAAM,CAAC,gBAAgB,IAAI,KAAK,CAAC;QACzD,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,YAAY,IAAI,GAAG,CAAC;QAC/C,IAAI,CAAC,qBAAqB,GAAG,MAAM,CAAC,qBAAqB,IAAI,GAAG,CAAC;QACjE,IAAI,CAAC,iBAAiB,GAAG,MAAM,CAAC,iBAAiB,IAAI,KAAK,CAAC;QAC3D,IAAI,CAAC,eAAe,GAAG,MAAM,CAAC,eAAe,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;QACtE,IAAI,CAAC,gBAAgB,GAAG,MAAM,CAAC,gBAAgB,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,MAAM,CAAC,CAAC;QAC5E,IAAI,CAAC,GAAG,GAAG,MAAM,CAAC,WAAW,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QACpD,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC7B,CAAC;IAED,KAAK;QACH,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO;QAC1B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAE3B,IAAI,CAAC,QAAQ,GAAG,WAAW,CAAC,GAAG,EAAE;YAC/B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACvB,MAAM,OAAO,GAAG,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC;YACpC,IAAI,CAAC,QAAQ,GAAG,GAAG,CAAC;YAEpB,IAAI,OAAO,IAAI,IAAI,CAAC,gBAAgB;gBAAE,OAAO;YAE7C,MAAM,aAAa,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,IAAI,CAAC,CAAC;YAC1E,MAAM,WAAW,GAAG,aAAa,IAAI,IAAI,CAAC,qBAAqB,CAAC;YAChE,MAAM,SAAS,GAAG,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAE1C,uEAAuE;YACvE,IAAI,CAAC,WAAW,IAAI,SAAS,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;gBAClD,IAAI,CAAC,iBAAiB,CAAC,gBAAgB,EAAE,aAAa,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC;gBACxE,OAAO,CAAC,IAAI,CACV,8BAA8B,aAAa,sBAAsB,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG;oBACtF,MAAM,IAAI,CAAC,YAAY,kDAAkD,CAC5E,CAAC;gBACF,OAAO;YACT,CAAC;YAED,qEAAqE;YACrE,2EAA2E;YAC3E,IACE,CAAC,WAAW;gBACZ,IAAI,CAAC,mBAAmB,KAAK,IAAI;gBACjC,GAAG,GAAG,IAAI,CAAC,mBAAmB,GAAG,IAAI,CAAC,iBAAiB,EACvD,CAAC;gBACD,IAAI,CAAC,iBAAiB,CAAC,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC;gBAClE,OAAO,CAAC,IAAI,CACV,2CAA2C;oBACzC,IAAI,GAAG,GAAG,IAAI,CAAC,mBAAmB,QAAQ,IAAI,CAAC,iBAAiB,sCAAsC,CACzG,CAAC;gBACF,OAAO;YACT,CAAC;YAED,OAAO,CAAC,GAAG,CAAC,4CAA4C,aAAa,SAAS,CAAC,CAAC;YAChF,MAAM,KAAK,GAAc,EAAE,oBAAoB,EAAE,aAAa,EAAE,SAAS,EAAE,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;YACzG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC7B,IAAI,IAAI,CAAC,WAAW,CAAC,MAAM,GAAG,GAAG;gBAAE,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;YAC5D,IAAI,CAAC,mBAAmB,GAAG,GAAG,CAAC;YAC/B,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAC3B,CAAC,EAAE,IAAI,CAAC,eAAe,CAAC,CAAC;QACzB,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,6CAA6C;IACtE,CAAC;IAED,IAAI;QACF,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC7B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACvB,CAAC;IACH,CAAC;IAED;qFACiF;IACzE,gBAAgB;QACtB,IAAI,QAAQ,GAAG,CAAC,CAAC;QACjB,IAAI,CAAC;YACH,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,gBAAgB,EAAE,CAAC,CAAC;QAClD,CAAC;QAAC,MAAM,CAAC;YACP,QAAQ,GAAG,CAAC,CAAC;QACf,CAAC;QACD,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,IAAI,CAAC;YACH,KAAK,GAAG,IAAI,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACzC,CAAC;QAAC,MAAM,CAAC;YACP,KAAK,GAAG,CAAC,CAAC;QACZ,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC;YAAE,OAAO,CAAC,CAAC;QACpD,OAAO,KAAK,GAAG,QAAQ,CAAC;IAC1B,CAAC;IAEO,iBAAiB,CACvB,MAA6B,EAC7B,YAAoB,EACpB,SAAiB,EACjB,KAAa;QAEb,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC;YAC3B,MAAM;YACN,YAAY;YACZ,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,GAAG,CAAC,GAAG,GAAG;YAC5C,SAAS,EAAE,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE;SACzC,CAAC,CAAC;QACH,IAAI,IAAI,CAAC,kBAAkB,CAAC,MAAM,GAAG,GAAG;YAAE,IAAI,CAAC,kBAAkB,CAAC,KAAK,EAAE,CAAC;IAC5E,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,2BAA2B,CAAC,OAAe,EAAE,KAAa;QACxD,IAAI,KAAK,IAAI,OAAO;YAAE,OAAO,CAAC,CAAC;QAC/B,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACjC,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC;YAC/C,MAAM,YAAY,GAAG,MAAM,GAAG,CAAC,CAAC,oBAAoB,GAAG,IAAI,CAAC;YAC5D,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;YACrD,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;YAC3C,IAAI,UAAU,GAAG,YAAY;gBAAE,KAAK,IAAI,UAAU,GAAG,YAAY,CAAC;QACpE,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,oDAAoD;IACpD,QAAQ,CAAC,OAAgB;QACvB,MAAM,KAAK,GAAG,OAAO,IAAI,CAAC,CAAC;QAC3B,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,IAAI,KAAK,CAAC,CAAC;QACxF,MAAM,UAAU,GAAG,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,IAAI,KAAK,CAAC,CAAC;QACjG,MAAM,kBAAkB,GAA0C;YAChE,gBAAgB,EAAE,CAAC;YACnB,QAAQ,EAAE,CAAC;SACZ,CAAC;QACF,KAAK,MAAM,CAAC,IAAI,UAAU;YAAE,kBAAkB,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3D,OAAO;YACL,SAAS,EAAE,QAAQ,CAAC,MAAM;YAC1B,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,oBAAoB,EAAE,CAAC,CAAC;YAC/E,mBAAmB,EAAE,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACrG,eAAe,EAAE,UAAU,CAAC,MAAM;YAClC,kBAAkB;YAClB,gBAAgB,EAAE,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI;SAC7F,CAAC;IACJ,CAAC;CACF"}

package/dist/core/UsherActedCorrelator.d.ts

@@ -0,0 +1,96 @@
+/**
+ * UsherActedCorrelator — the precision-numerator wiring for the Usher (rung 4 of
+ * continuous-working-awareness).
+ *
+ * The Usher FIRES re-surface signals (UsherSignalStore.recordSignal). Until this
+ * module, nothing ever called markActed — so `precision = acted/fired` was pinned
+ * at 0 and the rung-5 (mid-task injection) gate could never be satisfied by data.
+ * This closes that loop via TWO correlation paths, both reducing to "does some
+ * probe text COVER a fired signal's contextText?":
+ *
+ *   (a) auto-use   — the agent's next reply on the topic uses the re-surfaced
+ *                    context. creditUsherOnOutbound(). The nudge was useful: the
+ *                    agent acted on it.
+ *   (b) miss-map   — the user later had to CORRECT the agent (a HumanAsDetector
+ *                    signal) on that same context. creditUsherOnMiss(). The nudge
+ *                    was a genuine catch the agent ignored — still a true positive
+ *                    for the Usher's precision.
+ *
+ * Matching is deliberately PRECISION-OVER-RECALL: precision gates whether the
+ * Usher earns the right to interrupt (rung 5), so a falsely-HIGH precision is the
+ * dangerous direction. We require a meaningful salient-term overlap (≥ MIN_SHARED
+ * shared content words AND ≥ MIN_COVERAGE of the context's terms) and only credit
+ * recently-fired signals. Under-crediting a fast reply is acceptable; inflating
+ * the gate is not.
+ *
+ * All exported integration fns are best-effort and NEVER throw into the
+ * message/delivery path — mirroring the Usher's own degrade-safety invariants.
+ */
+import type { UsherSignal, UsherSignalStore } from './UsherSignalStore.js';
+/** Minimal inbound-entry shape the miss path reads (matches InboundMessageEntry). */
+export interface MissEntry {
+    topicId?: number | null;
+    text?: string;
+}
+export declare const MIN_SHARED = 2;
+export declare const MIN_COVERAGE = 0.5;
+/** Window in which the agent's reply still counts as "using" a just-fired nudge. */
+export declare const USE_WINDOW_MS: number;
+/** Window in which a later user correction still credits a prior nudge. */
+export declare const MISS_WINDOW_MS: number;
+/**
+ * Salient content tokens of a text: lowercased, alphanumeric-split, ≥3 chars,
+ * stopwords removed. Pure + deterministic.
+ */
+export declare function salientTerms(text: string): Set<string>;
+/**
+ * Does `probeText` cover enough of `contextText`'s salient terms to count as a
+ * genuine reference to it? Requires ≥ minShared shared terms AND ≥ minCoverage
+ * fraction of the context's terms (so single-coincidental-word matches fail, and
+ * a long context needs proportionally more overlap).
+ */
+export declare function contextCoveredBy(contextText: string, probeText: string, opts?: {
+    minShared?: number;
+    minCoverage?: number;
+}): boolean;
+/**
+ * Pure: among NOT-yet-acted signals, which ones does `probeText` cover? Returns
+ * their ids. `maxAgeMs`+`nowMs` optionally drop signals older than the window.
+ */
+export declare function findCoveredSignalIds(signals: UsherSignal[], probeText: string, opts?: {
+    minShared?: number;
+    minCoverage?: number;
+    maxAgeMs?: number;
+    nowMs?: number;
+}): string[];
+/**
+ * Core integration: correlate `probeText` against a topic's fired signals and
+ * mark the matches acted (stamped with `via`). Best-effort, never throws.
+ * Returns the ids actually marked.
+ */
+export declare function markActedByCoverage(store: UsherSignalStore, topicId: number, probeText: string, via: 'use' | 'miss', opts?: {
+    now?: () => number;
+    maxAgeMs?: number;
+    minShared?: number;
+    minCoverage?: number;
+    onMarked?: (id: string) => void;
+}): string[];
+/**
+ * Path (a): the agent's reply just went out on `topicId`. Credit any recent
+ * faded-context nudge the reply actually used. Wire on the outbound-reply path.
+ */
+export declare function creditUsherOnOutbound(store: UsherSignalStore | null | undefined, topicId: number, replyText: string, opts?: {
+    now?: () => number;
+    maxAgeMs?: number;
+}): string[];
+/**
+ * Path (b): the user just had to correct the agent (`missSignal` non-null). If a
+ * recent nudge on this topic covers what they're correcting, that nudge was a
+ * real catch the agent ignored → credit it. Wire on the inbound human-detector
+ * seam. No-op when there was no miss, no topic, or no text.
+ */
+export declare function creditUsherOnMiss(store: UsherSignalStore | null | undefined, missSignal: unknown, entry: MissEntry, opts?: {
+    now?: () => number;
+    maxAgeMs?: number;
+}): string[];
+//# sourceMappingURL=UsherActedCorrelator.d.ts.map

package/dist/core/UsherActedCorrelator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UsherActedCorrelator.d.ts","sourceRoot":"","sources":["../../src/core/UsherActedCorrelator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE3E,qFAAqF;AACrF,MAAM,WAAW,SAAS;IACxB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAGD,eAAO,MAAM,UAAU,IAAI,CAAC;AAC5B,eAAO,MAAM,YAAY,MAAM,CAAC;AAChC,oFAAoF;AACpF,eAAO,MAAM,aAAa,QAAqB,CAAC;AAChD,2EAA2E;AAC3E,eAAO,MAAM,cAAc,QAAsB,CAAC;AAgBlD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAStD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAClD,OAAO,CAST;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,WAAW,EAAE,EACtB,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACrF,MAAM,EAAE,CAaV;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,gBAAgB,EACvB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,KAAK,GAAG,MAAM,EACnB,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GAC1H,MAAM,EAAE,CAyBV;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,EAC1C,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/C,MAAM,EAAE,CAMV;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,EAC1C,UAAU,EAAE,OAAO,EACnB,KAAK,EAAE,SAAS,EAChB,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/C,MAAM,EAAE,CASV"}

package/dist/core/UsherActedCorrelator.js

@@ -0,0 +1,175 @@
+/**
+ * UsherActedCorrelator — the precision-numerator wiring for the Usher (rung 4 of
+ * continuous-working-awareness).
+ *
+ * The Usher FIRES re-surface signals (UsherSignalStore.recordSignal). Until this
+ * module, nothing ever called markActed — so `precision = acted/fired` was pinned
+ * at 0 and the rung-5 (mid-task injection) gate could never be satisfied by data.
+ * This closes that loop via TWO correlation paths, both reducing to "does some
+ * probe text COVER a fired signal's contextText?":
+ *
+ *   (a) auto-use   — the agent's next reply on the topic uses the re-surfaced
+ *                    context. creditUsherOnOutbound(). The nudge was useful: the
+ *                    agent acted on it.
+ *   (b) miss-map   — the user later had to CORRECT the agent (a HumanAsDetector
+ *                    signal) on that same context. creditUsherOnMiss(). The nudge
+ *                    was a genuine catch the agent ignored — still a true positive
+ *                    for the Usher's precision.
+ *
+ * Matching is deliberately PRECISION-OVER-RECALL: precision gates whether the
+ * Usher earns the right to interrupt (rung 5), so a falsely-HIGH precision is the
+ * dangerous direction. We require a meaningful salient-term overlap (≥ MIN_SHARED
+ * shared content words AND ≥ MIN_COVERAGE of the context's terms) and only credit
+ * recently-fired signals. Under-crediting a fast reply is acceptable; inflating
+ * the gate is not.
+ *
+ * All exported integration fns are best-effort and NEVER throw into the
+ * message/delivery path — mirroring the Usher's own degrade-safety invariants.
+ */
+// ── Matching knobs (precision-over-recall) ───────────────────────────────────
+export const MIN_SHARED = 2; // a single coincidental word can't credit a signal
+export const MIN_COVERAGE = 0.5; // must cover at least half the context's salient terms
+/** Window in which the agent's reply still counts as "using" a just-fired nudge. */
+export const USE_WINDOW_MS = 6 * 60 * 60 * 1000; // 6h
+/** Window in which a later user correction still credits a prior nudge. */
+export const MISS_WINDOW_MS = 24 * 60 * 60 * 1000; // 24h
+// English stopwords + a few instar-conversation fillers. Kept small and stable:
+// the goal is to drop function words so overlap reflects real subject matter.
+const STOPWORDS = new Set([
+    'the', 'and', 'for', 'are', 'but', 'not', 'you', 'your', 'with', 'that', 'this',
+    'have', 'has', 'had', 'was', 'were', 'will', 'would', 'should', 'could', 'can',
+    'its', 'it', 'is', 'be', 'been', 'being', 'from', 'into', 'over', 'under', 'about',
+    'they', 'them', 'their', 'there', 'here', 'what', 'when', 'where', 'which', 'who',
+    'how', 'why', 'all', 'any', 'some', 'one', 'two', 'now', 'then', 'than', 'just',
+    'out', 'off', 'too', 'very', 'our', 'his', 'her', 'him', 'she', 'his', 'we',
+    'get', 'got', 'let', 'see', 'use', 'used', 'make', 'made', 'want', 'need',
+    'yes', 'yeah', 'okay', 'sure', 'thing', 'things', 'stuff', 'like', 'also',
+    'going', 'gonna', 'really', 'much', 'more', 'most', 'still', 'back', 'done',
+]);
+/**
+ * Salient content tokens of a text: lowercased, alphanumeric-split, ≥3 chars,
+ * stopwords removed. Pure + deterministic.
+ */
+export function salientTerms(text) {
+    const out = new Set();
+    if (!text || typeof text !== 'string')
+        return out;
+    for (const raw of text.toLowerCase().split(/[^a-z0-9]+/)) {
+        if (raw.length < 3)
+            continue;
+        if (STOPWORDS.has(raw))
+            continue;
+        out.add(raw);
+    }
+    return out;
+}
+/**
+ * Does `probeText` cover enough of `contextText`'s salient terms to count as a
+ * genuine reference to it? Requires ≥ minShared shared terms AND ≥ minCoverage
+ * fraction of the context's terms (so single-coincidental-word matches fail, and
+ * a long context needs proportionally more overlap).
+ */
+export function contextCoveredBy(contextText, probeText, opts) {
+    const ctx = salientTerms(contextText);
+    if (ctx.size === 0)
+        return false;
+    const probe = salientTerms(probeText);
+    if (probe.size === 0)
+        return false;
+    let shared = 0;
+    for (const t of ctx)
+        if (probe.has(t))
+            shared++;
+    const coverage = shared / ctx.size;
+    return shared >= (opts?.minShared ?? MIN_SHARED) && coverage >= (opts?.minCoverage ?? MIN_COVERAGE);
+}
+/**
+ * Pure: among NOT-yet-acted signals, which ones does `probeText` cover? Returns
+ * their ids. `maxAgeMs`+`nowMs` optionally drop signals older than the window.
+ */
+export function findCoveredSignalIds(signals, probeText, opts) {
+    const ids = [];
+    const maxAgeMs = opts?.maxAgeMs;
+    const nowMs = opts?.nowMs ?? Date.now();
+    for (const s of signals) {
+        if (!s || s.acted)
+            continue;
+        if (maxAgeMs !== undefined) {
+            const firedMs = Date.parse(s.at);
+            if (!Number.isNaN(firedMs) && nowMs - firedMs > maxAgeMs)
+                continue;
+        }
+        if (contextCoveredBy(s.contextText, probeText, opts))
+            ids.push(s.id);
+    }
+    return ids;
+}
+/**
+ * Core integration: correlate `probeText` against a topic's fired signals and
+ * mark the matches acted (stamped with `via`). Best-effort, never throws.
+ * Returns the ids actually marked.
+ */
+export function markActedByCoverage(store, topicId, probeText, via, opts) {
+    try {
+        if (!probeText || typeof probeText !== 'string')
+            return [];
+        if (typeof topicId !== 'number' || !Number.isFinite(topicId))
+            return [];
+        const nowMs = (opts?.now ?? (() => Date.now()))();
+        const signals = store.getSignals(topicId, 50);
+        const ids = findCoveredSignalIds(signals, probeText, {
+            minShared: opts?.minShared,
+            minCoverage: opts?.minCoverage,
+            maxAgeMs: opts?.maxAgeMs,
+            nowMs,
+        });
+        if (ids.length === 0)
+            return [];
+        const at = new Date(nowMs).toISOString();
+        const marked = [];
+        for (const id of ids) {
+            if (store.markActed(topicId, id, { via, at })) {
+                marked.push(id);
+                try {
+                    opts?.onMarked?.(id);
+                }
+                catch { /* observability hook must not break */ }
+            }
+        }
+        return marked;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Path (a): the agent's reply just went out on `topicId`. Credit any recent
+ * faded-context nudge the reply actually used. Wire on the outbound-reply path.
+ */
+export function creditUsherOnOutbound(store, topicId, replyText, opts) {
+    if (!store)
+        return [];
+    return markActedByCoverage(store, topicId, replyText, 'use', {
+        now: opts?.now,
+        maxAgeMs: opts?.maxAgeMs ?? USE_WINDOW_MS,
+    });
+}
+/**
+ * Path (b): the user just had to correct the agent (`missSignal` non-null). If a
+ * recent nudge on this topic covers what they're correcting, that nudge was a
+ * real catch the agent ignored → credit it. Wire on the inbound human-detector
+ * seam. No-op when there was no miss, no topic, or no text.
+ */
+export function creditUsherOnMiss(store, missSignal, entry, opts) {
+    if (!store || !missSignal)
+        return [];
+    const topicId = entry?.topicId;
+    const text = entry?.text;
+    if (typeof topicId !== 'number' || !text)
+        return [];
+    return markActedByCoverage(store, topicId, text, 'miss', {
+        now: opts?.now,
+        maxAgeMs: opts?.maxAgeMs ?? MISS_WINDOW_MS,
+    });
+}
+//# sourceMappingURL=UsherActedCorrelator.js.map

package/dist/core/UsherActedCorrelator.js.map

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