sensorium-mcp 3.1.2 → 3.1.3-board.1

package/dist/services/usage/usage-inbox-notifier.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Usage inbox notifier — the one agent-touching consumer of the usage monitor.
+ *
+ * It subscribes to the poller's `onSnapshots` seam. When a source's 5h
+ * utilization crosses the ~90% threshold on a RISING EDGE (below → at/above,
+ * not on every 45 s tick), it fans a ONE-TIME graceful-park instruction out to
+ * every PERSISTENT thread (`keep_alive = 1 AND type != 'worker'` — this excludes
+ * plain workers AND board card-workers) via the pending-task mailbox.
+ *
+ * Two independent guards keep it from spamming:
+ *   1. In-memory rising-edge detection (per agentType) — suppresses re-fires on
+ *      every tick while utilization stays high within a process lifetime.
+ *   2. Persisted dedup per `${agentType}:${reset5hAt}` window — survives an MCP
+ *      restart inside the same 5h window, so a bounce cannot re-spam.
+ *
+ * Operator-first alerting invariant: the whole thing is gated behind
+ * `getUsageNotifyEnabled()` (default OFF), checked AT FIRE TIME so the live
+ * toggle needs no restart. Agent-type-agnostic (OCP): it iterates snapshots
+ * keyed by `agentType` and never branches on a specific agent name.
+ */
+import type { UsageSnapshot } from "./usage-types.js";
+/** Rising-edge threshold: 90% of the 5h budget. */
+export declare const USAGE_NOTIFY_THRESHOLD = 0.9;
+export interface UsageInboxNotifierDeps {
+    /** Toggle gate, checked at fire time (live). Default OFF (see settings). */
+    isEnabled: () => boolean;
+    /** Target thread IDs: keep-alive, non-worker persistent threads. */
+    getTargetThreadIds: () => number[];
+    /** Whether an alert already fired for this dedup key in the current window. */
+    hasNotified: (key: string) => boolean;
+    /** Record that an alert fired for `key`, expiring at `expiresAtMs`. */
+    markNotified: (key: string, expiresAtMs: number) => void;
+    /** Append a one-line message to a thread's pending-task mailbox. */
+    deliver: (threadId: number, message: string) => void;
+    log: (msg: string) => void;
+}
+export declare class UsageInboxNotifier {
+    private readonly deps;
+    /** Last concrete 5h utilization seen per agentType — the rising-edge memory. */
+    private readonly lastUtil;
+    constructor(deps: UsageInboxNotifierDeps);
+    /**
+     * Poller `onSnapshots` seam. Evaluates each source independently; a throw on
+     * one must never starve the rest, and the rising-edge memory is always
+     * advanced so a high plateau does not re-fire on the next tick.
+     */
+    handleSnapshots(snapshots: UsageSnapshot[]): void;
+    private evaluate;
+}
+//# sourceMappingURL=usage-inbox-notifier.d.ts.map

package/dist/services/usage/usage-inbox-notifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-inbox-notifier.d.ts","sourceRoot":"","sources":["../../../src/services/usage/usage-inbox-notifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,mDAAmD;AACnD,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAK1C,MAAM,WAAW,sBAAsB;IACrC,4EAA4E;IAC5E,SAAS,EAAE,MAAM,OAAO,CAAC;IACzB,oEAAoE;IACpE,kBAAkB,EAAE,MAAM,MAAM,EAAE,CAAC;IACnC,+EAA+E;IAC/E,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACtC,uEAAuE;IACvE,YAAY,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC;IACzD,oEAAoE;IACpE,OAAO,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACrD,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5B;AAED,qBAAa,kBAAkB;IAIjB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHjC,gFAAgF;IAChF,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;gBAEzB,IAAI,EAAE,sBAAsB;IAEzD;;;;OAIG;IACH,eAAe,CAAC,SAAS,EAAE,aAAa,EAAE,GAAG,IAAI;IAYjD,OAAO,CAAC,QAAQ;CAqCjB"}

package/dist/services/usage/usage-inbox-notifier.js

@@ -0,0 +1,118 @@
+/**
+ * Usage inbox notifier — the one agent-touching consumer of the usage monitor.
+ *
+ * It subscribes to the poller's `onSnapshots` seam. When a source's 5h
+ * utilization crosses the ~90% threshold on a RISING EDGE (below → at/above,
+ * not on every 45 s tick), it fans a ONE-TIME graceful-park instruction out to
+ * every PERSISTENT thread (`keep_alive = 1 AND type != 'worker'` — this excludes
+ * plain workers AND board card-workers) via the pending-task mailbox.
+ *
+ * Two independent guards keep it from spamming:
+ *   1. In-memory rising-edge detection (per agentType) — suppresses re-fires on
+ *      every tick while utilization stays high within a process lifetime.
+ *   2. Persisted dedup per `${agentType}:${reset5hAt}` window — survives an MCP
+ *      restart inside the same 5h window, so a bounce cannot re-spam.
+ *
+ * Operator-first alerting invariant: the whole thing is gated behind
+ * `getUsageNotifyEnabled()` (default OFF), checked AT FIRE TIME so the live
+ * toggle needs no restart. Agent-type-agnostic (OCP): it iterates snapshots
+ * keyed by `agentType` and never branches on a specific agent name.
+ */
+/** Rising-edge threshold: 90% of the 5h budget. */
+export const USAGE_NOTIFY_THRESHOLD = 0.9;
+/** Fallback dedup-window length when a source reports no reset instant. */
+const FALLBACK_WINDOW_MS = 5 * 60 * 60 * 1000;
+export class UsageInboxNotifier {
+    deps;
+    /** Last concrete 5h utilization seen per agentType — the rising-edge memory. */
+    lastUtil = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * Poller `onSnapshots` seam. Evaluates each source independently; a throw on
+     * one must never starve the rest, and the rising-edge memory is always
+     * advanced so a high plateau does not re-fire on the next tick.
+     */
+    handleSnapshots(snapshots) {
+        for (const snap of snapshots) {
+            try {
+                this.evaluate(snap);
+            }
+            catch (err) {
+                this.deps.log(`[usage] notifier error for ${snap.agentType}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    evaluate(snap) {
+        // A failed/absent reading is not a data point: don't disturb the rising-edge
+        // memory (a transient probe failure must not re-arm a fresh crossing).
+        if (!snap.ok || snap.utilization5h === null || !Number.isFinite(snap.utilization5h))
+            return;
+        const util = snap.utilization5h;
+        const prev = this.lastUtil.get(snap.agentType);
+        const prevBelow = prev === undefined || prev < USAGE_NOTIFY_THRESHOLD;
+        const risingEdge = prevBelow && util >= USAGE_NOTIFY_THRESHOLD;
+        // Toggle gate at fire time (operator-first alerting; default OFF). A disabled
+        // tick is treated as a NON-data-point: we return BEFORE advancing the
+        // rising-edge memory, so enabling the toggle live during an ongoing high
+        // plateau still produces one alert (prev stays below the threshold).
+        if (!this.deps.isEnabled())
+            return;
+        // Enabled from here: advance the rising-edge memory so a high plateau reads
+        // prev >= threshold on the next tick and can't re-fire until it dips and
+        // rises again. Done before the dedup/fan-out returns below on purpose.
+        this.lastUtil.set(snap.agentType, util);
+        if (!risingEdge)
+            return;
+        const { key, expiresAtMs } = dedupWindow(snap);
+        if (this.deps.hasNotified(key))
+            return;
+        const targets = this.deps.getTargetThreadIds();
+        const message = buildMessage(snap, util);
+        for (const threadId of targets) {
+            this.deps.deliver(threadId, message);
+        }
+        this.deps.markNotified(key, expiresAtMs);
+        this.deps.log(`[usage] high-utilization alert: ${snap.agentType} at ${Math.round(util * 100)}% → ${targets.length} keep-alive thread(s)`);
+    }
+}
+/**
+ * Stable per-window dedup identity + its expiry.
+ *
+ * When the source reports a reset instant, that instant IS the window boundary:
+ * key `${agentType}:${reset5hAt}`, expiring at the reset. When it doesn't
+ * (future credit models with no reset window), the key must STILL be stable
+ * across a restart — bucketing on the fluctuating utilization percent would
+ * mint a fresh key on every tick and defeat the persisted dedup. Instead
+ * quantize the probe time into fixed `FALLBACK_WINDOW_MS` buckets: identical for
+ * every probe within the same wall-clock window, independent of utilization.
+ */
+function dedupWindow(snap) {
+    if (snap.reset5hAt) {
+        const t = Date.parse(snap.reset5hAt);
+        return {
+            key: `${snap.agentType}:${snap.reset5hAt}`,
+            expiresAtMs: Number.isFinite(t) ? t : Date.now() + FALLBACK_WINDOW_MS,
+        };
+    }
+    const anchor = Date.parse(snap.probedAt);
+    const base = Number.isFinite(anchor) ? anchor : Date.now();
+    const bucket = Math.floor(base / FALLBACK_WINDOW_MS);
+    return {
+        key: `${snap.agentType}:w${bucket}`,
+        expiresAtMs: (bucket + 1) * FALLBACK_WINDOW_MS,
+    };
+}
+/**
+ * One-line graceful-park instruction, structured like other cross-thread
+ * signals. Percent / agentType / reset time interpolate from the snapshot.
+ */
+function buildMessage(snap, util) {
+    const pct = Math.round(util * 100);
+    const resetPart = snap.reset5hAt ? ` — resets ${snap.reset5hAt}` : "";
+    return (`[USAGE ALERT] ${snap.agentType} 5h utilization at ${pct}%${resetPart}. ` +
+        `Wait for your running workers to finish, send or park any pending results, then call ` +
+        `wait and stop generating until reset. Do not start new work. One-time notice for this window.`);
+}
+//# sourceMappingURL=usage-inbox-notifier.js.map

package/dist/services/usage/usage-inbox-notifier.js.map

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

package/dist/services/usage/usage-poller.service.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Usage poller — the MCP-side pull loop (one-way IPC: MCP → supervisor).
+ *
+ * A small `start()/stop()` background loop in the `KeeperService` /
+ * `BoardOrchestrator` style. Every ~45 s it calls `brokerGetUsage()` (the broker
+ * client) and writes the result into the `UsageSnapshotProvider`. It only ever
+ * PULLS — it never pushes into the supervisor.
+ *
+ * Null handling is load-bearing: `brokerGetUsage()` returns `null` for ANY
+ * failure (unreachable / non-OK / unparseable). `null` means "cannot confirm",
+ * NEVER "usage is zero". On null the poller leaves the provider untouched so the
+ * last-known snapshot survives a transient supervisor hiccup. An inert monitor
+ * answers with an empty array (a confirmed "no sources"), which IS written.
+ *
+ * Wiring gates start on `MCP_HTTP_PORT`: every stdio agent session also boots
+ * `index.ts`, so an ungated poller would spawn one loop per session. Gating it
+ * to the HTTP transport keeps exactly one poller in the server process.
+ */
+import type { InMemoryUsageSnapshotProvider } from "./usage-snapshot-provider.js";
+import type { UsageSnapshot } from "./usage-types.js";
+export interface UsagePollerDeps {
+    provider: InMemoryUsageSnapshotProvider;
+    /** Optional notifier hook — fired with the accepted batch after each write. */
+    onSnapshots?: (snapshots: UsageSnapshot[]) => void;
+    log: (msg: string) => void;
+}
+export declare class UsagePollerService {
+    private readonly deps;
+    private timer;
+    private pollInFlight;
+    constructor(deps: UsagePollerDeps);
+    /** Idempotent: poll once immediately, then every ~45 s. Re-entry is a no-op. */
+    start(): void;
+    stop(): void;
+    /**
+     * One pull cycle. A slow request must not stack ticks (the interval keeps
+     * firing), so an in-flight poll short-circuits re-entry.
+     */
+    private poll;
+}
+//# sourceMappingURL=usage-poller.service.d.ts.map

package/dist/services/usage/usage-poller.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-poller.service.d.ts","sourceRoot":"","sources":["../../../src/services/usage/usage-poller.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,8BAA8B,CAAC;AAClF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAItD,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,6BAA6B,CAAC;IACxC,+EAA+E;IAC/E,WAAW,CAAC,EAAE,CAAC,SAAS,EAAE,aAAa,EAAE,KAAK,IAAI,CAAC;IACnD,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5B;AAED,qBAAa,kBAAkB;IAIjB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHjC,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,YAAY,CAAS;gBAEA,IAAI,EAAE,eAAe;IAElD,gFAAgF;IAChF,KAAK,IAAI,IAAI;IAQb,IAAI,IAAI,IAAI;IAKZ;;;OAGG;YACW,IAAI;CAenB"}

package/dist/services/usage/usage-poller.service.js

@@ -0,0 +1,66 @@
+/**
+ * Usage poller — the MCP-side pull loop (one-way IPC: MCP → supervisor).
+ *
+ * A small `start()/stop()` background loop in the `KeeperService` /
+ * `BoardOrchestrator` style. Every ~45 s it calls `brokerGetUsage()` (the broker
+ * client) and writes the result into the `UsageSnapshotProvider`. It only ever
+ * PULLS — it never pushes into the supervisor.
+ *
+ * Null handling is load-bearing: `brokerGetUsage()` returns `null` for ANY
+ * failure (unreachable / non-OK / unparseable). `null` means "cannot confirm",
+ * NEVER "usage is zero". On null the poller leaves the provider untouched so the
+ * last-known snapshot survives a transient supervisor hiccup. An inert monitor
+ * answers with an empty array (a confirmed "no sources"), which IS written.
+ *
+ * Wiring gates start on `MCP_HTTP_PORT`: every stdio agent session also boots
+ * `index.ts`, so an ungated poller would spawn one loop per session. Gating it
+ * to the HTTP transport keeps exactly one poller in the server process.
+ */
+import { brokerGetUsage } from "../broker-client.js";
+const USAGE_POLL_INTERVAL_MS = 45_000; // spec range 30–60 s
+export class UsagePollerService {
+    deps;
+    timer = null;
+    pollInFlight = false;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Idempotent: poll once immediately, then every ~45 s. Re-entry is a no-op. */
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => void this.poll(), USAGE_POLL_INTERVAL_MS);
+        this.timer.unref();
+        void this.poll();
+        this.deps.log(`[usage] poller started (interval ${USAGE_POLL_INTERVAL_MS / 1000}s)`);
+    }
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+    }
+    /**
+     * One pull cycle. A slow request must not stack ticks (the interval keeps
+     * firing), so an in-flight poll short-circuits re-entry.
+     */
+    async poll() {
+        if (this.pollInFlight)
+            return;
+        this.pollInFlight = true;
+        try {
+            const snapshots = await brokerGetUsage();
+            // null ⇒ cannot confirm ⇒ keep last known; never zero out the provider.
+            if (snapshots === null)
+                return;
+            this.deps.provider.setSnapshots(snapshots);
+            this.deps.onSnapshots?.(snapshots);
+        }
+        catch (err) {
+            this.deps.log(`[usage] poll failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        finally {
+            this.pollInFlight = false;
+        }
+    }
+}
+//# sourceMappingURL=usage-poller.service.js.map

package/dist/services/usage/usage-poller.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-poller.service.js","sourceRoot":"","sources":["../../../src/services/usage/usage-poller.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAIrD,MAAM,sBAAsB,GAAG,MAAM,CAAC,CAAC,qBAAqB;AAS5D,MAAM,OAAO,kBAAkB;IAIA;IAHrB,KAAK,GAA0C,IAAI,CAAC;IACpD,YAAY,GAAG,KAAK,CAAC;IAE7B,YAA6B,IAAqB;QAArB,SAAI,GAAJ,IAAI,CAAiB;IAAG,CAAC;IAEtD,gFAAgF;IAChF,KAAK;QACH,IAAI,IAAI,CAAC,KAAK;YAAE,OAAO;QACvB,IAAI,CAAC,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,CAAC,IAAI,EAAE,EAAE,sBAAsB,CAAC,CAAC;QACzE,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACnB,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC;QACjB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,oCAAoC,sBAAsB,GAAG,IAAI,IAAI,CAAC,CAAC;IACvF,CAAC;IAED,IAAI;QACF,IAAI,IAAI,CAAC,KAAK;YAAE,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC1C,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED;;;OAGG;IACK,KAAK,CAAC,IAAI;QAChB,IAAI,IAAI,CAAC,YAAY;YAAE,OAAO;QAC9B,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QACzB,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,MAAM,cAAc,EAAE,CAAC;YACzC,wEAAwE;YACxE,IAAI,SAAS,KAAK,IAAI;gBAAE,OAAO;YAC/B,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC;YAC3C,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,SAAS,CAAC,CAAC;QACrC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,wBAAwB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC5F,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC;QAC5B,CAAC;IACH,CAAC;CACF"}

package/dist/services/usage/usage-snapshot-provider.d.ts

@@ -0,0 +1,29 @@
+/**
+ * In-memory `UsageSnapshotProvider` (the port's default impl) + lazy module
+ * singleton. The poller calls `setSnapshots` to upsert the latest snapshot per
+ * `agentType`; consumers read via the port interface. A lazy singleton matches
+ * the project's `initMemoryDb` idiom so dashboard route handlers can reach the
+ * provider without threading it through `DashboardContext`.
+ */
+import type { UsageSnapshot, UsageSnapshotProvider } from "./usage-types.js";
+export declare class InMemoryUsageSnapshotProvider implements UsageSnapshotProvider {
+    /** Latest snapshot per agentType — upserted, so newer probes replace older. */
+    private readonly byAgentType;
+    private readonly listeners;
+    /**
+     * Upsert each snapshot by `agentType`, then notify listeners ONCE for the
+     * whole batch. An empty batch is still a valid signal ("monitor went inert")
+     * and clears nothing implicitly — callers pass what they want stored.
+     */
+    setSnapshots(snapshots: UsageSnapshot[]): void;
+    getAll(): UsageSnapshot[];
+    getByAgentType(agentType: string): UsageSnapshot | null;
+    onUpdate(listener: (snapshots: UsageSnapshot[]) => void): () => void;
+    /** Fire every listener; one listener throwing must not starve the rest. */
+    private notify;
+}
+/** Lazy module singleton — the one provider shared by poller and consumers. */
+export declare function getUsageSnapshotProvider(): InMemoryUsageSnapshotProvider;
+/** Test hook: drop the module singleton so each test starts from a clean slate. */
+export declare function resetUsageSnapshotProviderForTest(): void;
+//# sourceMappingURL=usage-snapshot-provider.d.ts.map

package/dist/services/usage/usage-snapshot-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-snapshot-provider.d.ts","sourceRoot":"","sources":["../../../src/services/usage/usage-snapshot-provider.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAE7E,qBAAa,6BAA8B,YAAW,qBAAqB;IACzE,+EAA+E;IAC/E,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoC;IAChE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmD;IAE7E;;;;OAIG;IACH,YAAY,CAAC,SAAS,EAAE,aAAa,EAAE,GAAG,IAAI;IAO9C,MAAM,IAAI,aAAa,EAAE;IAIzB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI;IAIvD,QAAQ,CAAC,QAAQ,EAAE,CAAC,SAAS,EAAE,aAAa,EAAE,KAAK,IAAI,GAAG,MAAM,IAAI;IAOpE,2EAA2E;IAC3E,OAAO,CAAC,MAAM;CASf;AAID,+EAA+E;AAC/E,wBAAgB,wBAAwB,IAAI,6BAA6B,CAKxE;AAED,mFAAmF;AACnF,wBAAgB,iCAAiC,IAAI,IAAI,CAExD"}

package/dist/services/usage/usage-snapshot-provider.js

@@ -0,0 +1,59 @@
+/**
+ * In-memory `UsageSnapshotProvider` (the port's default impl) + lazy module
+ * singleton. The poller calls `setSnapshots` to upsert the latest snapshot per
+ * `agentType`; consumers read via the port interface. A lazy singleton matches
+ * the project's `initMemoryDb` idiom so dashboard route handlers can reach the
+ * provider without threading it through `DashboardContext`.
+ */
+export class InMemoryUsageSnapshotProvider {
+    /** Latest snapshot per agentType — upserted, so newer probes replace older. */
+    byAgentType = new Map();
+    listeners = new Set();
+    /**
+     * Upsert each snapshot by `agentType`, then notify listeners ONCE for the
+     * whole batch. An empty batch is still a valid signal ("monitor went inert")
+     * and clears nothing implicitly — callers pass what they want stored.
+     */
+    setSnapshots(snapshots) {
+        for (const snap of snapshots) {
+            this.byAgentType.set(snap.agentType, snap);
+        }
+        this.notify(snapshots);
+    }
+    getAll() {
+        return [...this.byAgentType.values()];
+    }
+    getByAgentType(agentType) {
+        return this.byAgentType.get(agentType) ?? null;
+    }
+    onUpdate(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /** Fire every listener; one listener throwing must not starve the rest. */
+    notify(snapshots) {
+        for (const listener of this.listeners) {
+            try {
+                listener(snapshots);
+            }
+            catch {
+                /* a consumer's failure must never break the update fan-out */
+            }
+        }
+    }
+}
+let singleton = null;
+/** Lazy module singleton — the one provider shared by poller and consumers. */
+export function getUsageSnapshotProvider() {
+    if (singleton === null) {
+        singleton = new InMemoryUsageSnapshotProvider();
+    }
+    return singleton;
+}
+/** Test hook: drop the module singleton so each test starts from a clean slate. */
+export function resetUsageSnapshotProviderForTest() {
+    singleton = null;
+}
+//# sourceMappingURL=usage-snapshot-provider.js.map

package/dist/services/usage/usage-snapshot-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-snapshot-provider.js","sourceRoot":"","sources":["../../../src/services/usage/usage-snapshot-provider.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,OAAO,6BAA6B;IACxC,+EAA+E;IAC9D,WAAW,GAAG,IAAI,GAAG,EAAyB,CAAC;IAC/C,SAAS,GAAG,IAAI,GAAG,EAAwC,CAAC;IAE7E;;;;OAIG;IACH,YAAY,CAAC,SAA0B;QACrC,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;YAC7B,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QAC7C,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACzB,CAAC;IAED,MAAM;QACJ,OAAO,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC;IACxC,CAAC;IAED,cAAc,CAAC,SAAiB;QAC9B,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC;IACjD,CAAC;IAED,QAAQ,CAAC,QAA8C;QACrD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC7B,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAClC,CAAC,CAAC;IACJ,CAAC;IAED,2EAA2E;IACnE,MAAM,CAAC,SAA0B;QACvC,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACtC,IAAI,CAAC;gBACH,QAAQ,CAAC,SAAS,CAAC,CAAC;YACtB,CAAC;YAAC,MAAM,CAAC;gBACP,8DAA8D;YAChE,CAAC;QACH,CAAC;IACH,CAAC;CACF;AAED,IAAI,SAAS,GAAyC,IAAI,CAAC;AAE3D,+EAA+E;AAC/E,MAAM,UAAU,wBAAwB;IACtC,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;QACvB,SAAS,GAAG,IAAI,6BAA6B,EAAE,CAAC;IAClD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,iCAAiC;IAC/C,SAAS,GAAG,IAAI,CAAC;AACnB,CAAC"}

package/dist/services/usage/usage-types.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Usage monitor — MCP-side port (OCP seam).
+ *
+ * The `UsageSnapshotProvider` is the single interface consumers depend on: the
+ * poller fills it (`setSnapshots`), while the inbox-notifier and the board read
+ * route consume it (`getAll` / `getByAgentType` / `onUpdate`). Consumers stay
+ * agent-type-agnostic — they iterate snapshots keyed by `agentType` and never
+ * branch on a specific agent (no `if (agentType === "claude")`).
+ *
+ * The snapshot shape is re-exported from the broker client so the wire contract
+ * (`GET /usage` on the supervisor) and the in-process port never drift.
+ */
+import type { BrokerUsageSnapshot } from "../broker-client.js";
+export type UsageSnapshot = BrokerUsageSnapshot;
+export interface UsageSnapshotProvider {
+    /** Latest snapshot per agentType; empty when the monitor is inert/unreachable. */
+    getAll(): UsageSnapshot[];
+    /** Latest snapshot for one agentType, or null when none is known. */
+    getByAgentType(agentType: string): UsageSnapshot | null;
+    /** Fires once per accepted update batch. Returns an unsubscribe function. */
+    onUpdate(listener: (snapshots: UsageSnapshot[]) => void): () => void;
+}
+//# sourceMappingURL=usage-types.d.ts.map

package/dist/services/usage/usage-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-types.d.ts","sourceRoot":"","sources":["../../../src/services/usage/usage-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE/D,MAAM,MAAM,aAAa,GAAG,mBAAmB,CAAC;AAEhD,MAAM,WAAW,qBAAqB;IACpC,kFAAkF;IAClF,MAAM,IAAI,aAAa,EAAE,CAAC;IAC1B,qEAAqE;IACrE,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAAC;IACxD,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,EAAE,CAAC,SAAS,EAAE,aAAa,EAAE,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CACtE"}

package/dist/services/usage/usage-types.js

@@ -0,0 +1,14 @@
+/**
+ * Usage monitor — MCP-side port (OCP seam).
+ *
+ * The `UsageSnapshotProvider` is the single interface consumers depend on: the
+ * poller fills it (`setSnapshots`), while the inbox-notifier and the board read
+ * route consume it (`getAll` / `getByAgentType` / `onUpdate`). Consumers stay
+ * agent-type-agnostic — they iterate snapshots keyed by `agentType` and never
+ * branch on a specific agent (no `if (agentType === "claude")`).
+ *
+ * The snapshot shape is re-exported from the broker client so the wire contract
+ * (`GET /usage` on the supervisor) and the in-process port never drift.
+ */
+export {};
+//# sourceMappingURL=usage-types.js.map

package/dist/services/usage/usage-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-types.js","sourceRoot":"","sources":["../../../src/services/usage/usage-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/services/worker-cleanup.service.d.ts

@@ -23,8 +23,13 @@ export declare function decommissionWorker(thread: {
     };
     chatId: string;
     threadLifecycle: ThreadLifecycleService;
-}): Promise<void>;
+}, 
+/** Real exit code when the caller observed the process die (handleProcessExit);
+ *  null/undefined on sweep paths where only "gone" is known. */
+exitCode?: number | null): Promise<void>;
 export declare const DEFAULT_WORKER_TTL_MS: number;
+export declare const CARD_WORKER_TTL_MS: number;
+export declare const CARD_WORKER_TTL_MAX_MS: number;
 export declare function cleanupExpiredWorkers(db: ReturnType<typeof import("../data/memory/index.js").initMemoryDb>, telegram: {
     deleteForumTopic(chatId: string, threadId: number): Promise<void>;
     sendMessage?(chatId: string, text: string, parseMode?: string, threadId?: number): Promise<void>;

package/dist/services/worker-cleanup.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worker-cleanup.service.d.ts","sourceRoot":"","sources":["../../src/services/worker-cleanup.service.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAe,KAAK,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAyBzF,eAAO,MAAM,eAAe,QAGxB,CAAC;AAQL;;;qFAGqF;AACrF,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;;oFAGoF;AACpF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAEvD;AAED,wBAAsB,kBAAkB,CACtC,MAAM,EAAE;IACN,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,EACD,IAAI,EAAE;IACJ,EAAE,EAAE,UAAU,CAAC,cAAc,yBAAyB,EAAE,YAAY,CAAC,CAAC;IACtE,QAAQ,EAAE;QAAE,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC;IAChF,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,sBAAsB,CAAC;CACzC,GACA,OAAO,CAAC,IAAI,CAAC,CA+Ff;AAoED,eAAO,MAAM,qBAAqB,QAAiB,CAAC;AAqEpD,wBAAsB,qBAAqB,CACzC,EAAE,EAAE,UAAU,CAAC,cAAc,yBAAyB,EAAE,YAAY,CAAC,EACrE,QAAQ,EAAE;IACR,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,WAAW,CAAC,CACV,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB,EACD,MAAM,EAAE,MAAM,EACd,eAAe,EAAE,sBAAsB,EACvC,KAAK,GAAE,MAA8B,GACpC,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAkThD"}
+{"version":3,"file":"worker-cleanup.service.d.ts","sourceRoot":"","sources":["../../src/services/worker-cleanup.service.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAe,KAAK,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AA6BzF,eAAO,MAAM,eAAe,QAGxB,CAAC;AAQL;;;qFAGqF;AACrF,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;;oFAGoF;AACpF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAEvD;AAED,wBAAsB,kBAAkB,CACtC,MAAM,EAAE;IACN,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,EACD,IAAI,EAAE;IACJ,EAAE,EAAE,UAAU,CAAC,cAAc,yBAAyB,EAAE,YAAY,CAAC,CAAC;IACtE,QAAQ,EAAE;QAAE,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC;IAChF,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,sBAAsB,CAAC;CACzC;AACD;gEACgE;AAChE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GACvB,OAAO,CAAC,IAAI,CAAC,CAoGf;AAsED,eAAO,MAAM,qBAAqB,QAAiB,CAAC;AAWpD,eAAO,MAAM,kBAAkB,QAG3B,CAAC;AAGL,eAAO,MAAM,sBAAsB,QAG/B,CAAC;AAwJL,wBAAsB,qBAAqB,CACzC,EAAE,EAAE,UAAU,CAAC,cAAc,yBAAyB,EAAE,YAAY,CAAC,EACrE,QAAQ,EAAE;IACR,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,WAAW,CAAC,CACV,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB,EACD,MAAM,EAAE,MAAM,EACd,eAAe,EAAE,sBAAsB,EACvC,KAAK,GAAE,MAA8B,GACpC,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAoVhD"}