instar 1.3.633 → 1.3.635

package/dist/core/clockSkewAlarm.js

@@ -0,0 +1,68 @@
+/**
+ * B4 (multimachine-lease-poll-robustness, Decision 9) — the clock-skew alarm
+ * decision.
+ *
+ * The mesh RPC rejects a signed envelope whose timestamp is >30s off the
+ * receiver's clock (`MeshRpc.verifyEnvelope`). When two machines' clocks drift
+ * past that, the cross-machine handshake silently breaks (the 2026-06-20
+ * post-reboot incident: a transient skew 403'd every lease/heartbeat RPC, the lease
+ * couldn't settle, and nobody was told). This decides whether to raise an
+ * EARLY-WARNING — at a margin BELOW the 30s reject cliff — so an operator hears
+ * about drift before the handshake fails, not after.
+ *
+ * Two N=2 subtleties this encodes:
+ *   - Attribution: with only two machines and no third reference, a measured
+ *     offset is RELATIVE — each sees the other as skewed. So each machine checks
+ *     its OWN NTP sync and, when ITS clock is unsynced, blames ITSELF rather than
+ *     finger-pointing the peer (Decision 9). Only when our own clock is verified
+ *     synced do we point at the peer.
+ *   - Hysteresis: the measured offset is a noisy signal near the threshold;
+ *     alarm at `alarmThresholdMs`, clear only below `clearThresholdMs`, so it
+ *     doesn't flap the attention surface.
+ *
+ * Pure + deterministic → fully unit-testable. SIGNAL only — never widens the
+ * MeshRpc reject (replay-safety) and never gates; it raises an advisory alarm.
+ */
+export function evaluateClockSkew(i) {
+    const mag = Math.abs(i.observedOffsetMs);
+    // Hysteresis: once alarming, stay until below the clear threshold; otherwise
+    // only start alarming at/above the alarm threshold.
+    const alarming = i.currentlyAlarming ? mag >= i.clearThresholdMs : mag >= i.alarmThresholdMs;
+    if (!alarming) {
+        return { alarming: false, blame: 'unknown', reason: `clock offset ${Math.round(mag)}ms within tolerance` };
+    }
+    // Freeze-vs-skew disambiguation (the 2026-06-20 live lesson). If THIS machine's
+    // event loop just starved, a large apparent offset is most likely the freeze
+    // making pre-freeze timestamps look stale — NOT genuine peer clock drift. Defer
+    // to the starvation signal (which has its own surface) and SUPPRESS the peer
+    // alarm. Safe direction: a persistent genuine skew re-alarms once the freeze
+    // window ages out; we never raise a misleading "peer skew" during our own freeze.
+    const freshFreeze = i.recentLocalStarvationAgeMs !== undefined &&
+        i.recentLocalStarvationAgeMs <= (i.starvationFreshnessMs ?? 30_000);
+    if (freshFreeze) {
+        return {
+            alarming: false,
+            blame: 'local-freeze',
+            reason: `clock offset ${Math.round(mag)}ms coincides with a LOCAL event-loop starvation ${Math.round(i.recentLocalStarvationAgeMs)}ms ago — apparent staleness is freeze-induced (pre-freeze timestamps verified post-freeze), not peer skew; deferring to the starvation signal`,
+        };
+    }
+    // Attribution (N=2). If our own clock is unsynced, the fault is plausibly OURS
+    // — blame self. If ours is verified synced, point at the peer. If we couldn't
+    // probe our own sync, stay 'unknown' (never a confident finger-point).
+    let blame;
+    let reason;
+    if (i.ownNtpSynced === false) {
+        blame = 'self';
+        reason = `clock offset ${Math.round(mag)}ms AND my own clock is not NTP-synced — fix my clock`;
+    }
+    else if (i.ownNtpSynced === true) {
+        blame = 'peer';
+        reason = `clock offset ${Math.round(mag)}ms; my clock is NTP-synced, so the peer's clock is likely drifting — mesh RPC will start failing past ${30}s`;
+    }
+    else {
+        blame = 'unknown';
+        reason = `clock offset ${Math.round(mag)}ms with one of us drifting (own NTP status unknown) — mesh RPC at risk`;
+    }
+    return { alarming: true, blame, reason };
+}
+//# sourceMappingURL=clockSkewAlarm.js.map

package/dist/core/clockSkewAlarm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clockSkewAlarm.js","sourceRoot":"","sources":["../../src/core/clockSkewAlarm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAuCH,MAAM,UAAU,iBAAiB,CAAC,CAAkB;IAClD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC;IACzC,6EAA6E;IAC7E,oDAAoD;IACpD,MAAM,QAAQ,GAAG,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,gBAAgB,CAAC;IAC7F,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,gBAAgB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,qBAAqB,EAAE,CAAC;IAC7G,CAAC;IACD,gFAAgF;IAChF,6EAA6E;IAC7E,gFAAgF;IAChF,6EAA6E;IAC7E,6EAA6E;IAC7E,kFAAkF;IAClF,MAAM,WAAW,GACf,CAAC,CAAC,0BAA0B,KAAK,SAAS;QAC1C,CAAC,CAAC,0BAA0B,IAAI,CAAC,CAAC,CAAC,qBAAqB,IAAI,MAAM,CAAC,CAAC;IACtE,IAAI,WAAW,EAAE,CAAC;QAChB,OAAO;YACL,QAAQ,EAAE,KAAK;YACf,KAAK,EAAE,cAAc;YACrB,MAAM,EAAE,gBAAgB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,mDAAmD,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,0BAA2B,CAAC,+IAA+I;SACnR,CAAC;IACJ,CAAC;IACD,+EAA+E;IAC/E,8EAA8E;IAC9E,uEAAuE;IACvE,IAAI,KAAgB,CAAC;IACrB,IAAI,MAAc,CAAC;IACnB,IAAI,CAAC,CAAC,YAAY,KAAK,KAAK,EAAE,CAAC;QAC7B,KAAK,GAAG,MAAM,CAAC;QACf,MAAM,GAAG,gBAAgB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,sDAAsD,CAAC;IACjG,CAAC;SAAM,IAAI,CAAC,CAAC,YAAY,KAAK,IAAI,EAAE,CAAC;QACnC,KAAK,GAAG,MAAM,CAAC;QACf,MAAM,GAAG,gBAAgB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,yGAAyG,EAAE,GAAG,CAAC;IACzJ,CAAC;SAAM,CAAC;QACN,KAAK,GAAG,SAAS,CAAC;QAClB,MAAM,GAAG,gBAAgB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,wEAAwE,CAAC;IACnH,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;AAC3C,CAAC"}

package/dist/core/configCoherence.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Phase 2 #7 (multimachine-lease-poll-robustness audit) — startup config-coherence
+ * checks. Surfaces incoherent multi-machine config combinations that silently
+ * degrade behavior (the 2026-06-20 audit: meshTransport disabled while session
+ * transfer is live left the pair on single-rope fragility under transfer load —
+ * the worst-of-both state my morning band-aid created).
+ *
+ * SIGNAL only — these are WARNINGS, never a startup REJECT. A hard reject would
+ * refuse fleet boot on a config the audit showed is the SHIPPED default in some
+ * combinations (F-CLAMP1: default TTL 60s < tick 120s would itself trip a naive
+ * invariant). So the checker returns warnings the caller logs (+ optionally an
+ * Attention item); it never throws.
+ *
+ * Pure + deterministic → fully unit-testable.
+ */
+export interface ConfigCoherenceWarning {
+    code: string;
+    message: string;
+}
+interface MultiMachineLike {
+    meshTransport?: {
+        enabled?: boolean;
+        priorities?: Record<string, number>;
+    };
+    sessionPool?: {
+        stage?: string;
+        enabled?: boolean;
+    };
+    leaseTtlMs?: number;
+}
+/**
+ * @param mm the resolved `multiMachine` config block.
+ * @param isMultiMachine whether this agent actually runs multi-machine (has a
+ *   machine identity / a peer). On a single-machine agent these combinations are
+ *   harmless no-ops, so we don't warn.
+ */
+export declare function checkMultiMachineConfigCoherence(mm: MultiMachineLike | undefined, isMultiMachine: boolean): ConfigCoherenceWarning[];
+export {};
+//# sourceMappingURL=configCoherence.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"configCoherence.d.ts","sourceRoot":"","sources":["../../src/core/configCoherence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,UAAU,gBAAgB;IACxB,aAAa,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CAAC;IAC3E,WAAW,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAC9C,EAAE,EAAE,gBAAgB,GAAG,SAAS,EAChC,cAAc,EAAE,OAAO,GACtB,sBAAsB,EAAE,CAgC1B"}

package/dist/core/configCoherence.js

@@ -0,0 +1,52 @@
+/**
+ * Phase 2 #7 (multimachine-lease-poll-robustness audit) — startup config-coherence
+ * checks. Surfaces incoherent multi-machine config combinations that silently
+ * degrade behavior (the 2026-06-20 audit: meshTransport disabled while session
+ * transfer is live left the pair on single-rope fragility under transfer load —
+ * the worst-of-both state my morning band-aid created).
+ *
+ * SIGNAL only — these are WARNINGS, never a startup REJECT. A hard reject would
+ * refuse fleet boot on a config the audit showed is the SHIPPED default in some
+ * combinations (F-CLAMP1: default TTL 60s < tick 120s would itself trip a naive
+ * invariant). So the checker returns warnings the caller logs (+ optionally an
+ * Attention item); it never throws.
+ *
+ * Pure + deterministic → fully unit-testable.
+ */
+/**
+ * @param mm the resolved `multiMachine` config block.
+ * @param isMultiMachine whether this agent actually runs multi-machine (has a
+ *   machine identity / a peer). On a single-machine agent these combinations are
+ *   harmless no-ops, so we don't warn.
+ */
+export function checkMultiMachineConfigCoherence(mm, isMultiMachine) {
+    const warnings = [];
+    if (!mm || !isMultiMachine)
+        return warnings;
+    // 1) Mesh transport disabled while session transfer is LIVE — the worst-of-both
+    //    state: the pool actively moves sessions but the transport reverts to a
+    //    single (flaky) rope, reintroducing the lease flap under transfer load.
+    const transferLive = mm.sessionPool?.enabled !== false && mm.sessionPool?.stage === 'live-transfer';
+    if (mm.meshTransport?.enabled === false && transferLive) {
+        warnings.push({
+            code: 'mesh-off-while-live-transfer',
+            message: 'multiMachine.meshTransport.enabled=false while sessionPool.stage=live-transfer on a multi-machine agent — ' +
+                'session transfer is active but the mesh is single-rope, reintroducing the lease flap. Set meshTransport.enabled=true.',
+        });
+    }
+    // 2) Mesh rope priorities must be DISTINCT positive integers (a tie makes rope
+    //    selection nondeterministic).
+    const pri = mm.meshTransport?.priorities;
+    if (pri && typeof pri === 'object') {
+        const vals = Object.values(pri).filter((v) => typeof v === 'number');
+        const bad = vals.filter((v) => !Number.isInteger(v) || v <= 0);
+        if (bad.length > 0) {
+            warnings.push({ code: 'mesh-priority-nonpositive', message: `multiMachine.meshTransport.priorities must be positive integers; got ${JSON.stringify(bad)}.` });
+        }
+        if (new Set(vals).size !== vals.length) {
+            warnings.push({ code: 'mesh-priority-collision', message: `multiMachine.meshTransport.priorities has duplicate values (${JSON.stringify(vals)}) — rope selection is nondeterministic.` });
+        }
+    }
+    return warnings;
+}
+//# sourceMappingURL=configCoherence.js.map

package/dist/core/configCoherence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"configCoherence.js","sourceRoot":"","sources":["../../src/core/configCoherence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAaH;;;;;GAKG;AACH,MAAM,UAAU,gCAAgC,CAC9C,EAAgC,EAChC,cAAuB;IAEvB,MAAM,QAAQ,GAA6B,EAAE,CAAC;IAC9C,IAAI,CAAC,EAAE,IAAI,CAAC,cAAc;QAAE,OAAO,QAAQ,CAAC;IAE5C,gFAAgF;IAChF,4EAA4E;IAC5E,4EAA4E;IAC5E,MAAM,YAAY,GAAG,EAAE,CAAC,WAAW,EAAE,OAAO,KAAK,KAAK,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,KAAK,eAAe,CAAC;IACpG,IAAI,EAAE,CAAC,aAAa,EAAE,OAAO,KAAK,KAAK,IAAI,YAAY,EAAE,CAAC;QACxD,QAAQ,CAAC,IAAI,CAAC;YACZ,IAAI,EAAE,8BAA8B;YACpC,OAAO,EACL,4GAA4G;gBAC5G,uHAAuH;SAC1H,CAAC,CAAC;IACL,CAAC;IAED,+EAA+E;IAC/E,kCAAkC;IAClC,MAAM,GAAG,GAAG,EAAE,CAAC,aAAa,EAAE,UAAU,CAAC;IACzC,IAAI,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QACnC,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC;QACrE,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QAC/D,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACnB,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,2BAA2B,EAAE,OAAO,EAAE,wEAAwE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC;QAChK,CAAC;QACD,IAAI,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,MAAM,EAAE,CAAC;YACvC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,yBAAyB,EAAE,OAAO,EAAE,+DAA+D,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,yCAAyC,EAAE,CAAC,CAAC;QAC5L,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/core/leaseLiveness.d.ts

@@ -0,0 +1,42 @@
+/**
+ * B4 (multimachine-lease-poll-robustness, Decision 10) — skew-immune peer
+ * liveness for the lease layer.
+ *
+ * The lease's `presumedDeadHolders` / `allPeersPresumedGone` historically derive
+ * liveness from the registry `lastSeen` — the PEER's OWN wall clock. Under clock
+ * skew (the 2026-06-20 post-reboot incident) a +Ns-fast peer looks MORE alive
+ * than it is (delaying a needed failover) and a −Ns-slow peer looks DEADER than
+ * it is (triggering a false failover → the flap). The skew-immune source is the
+ * router's OWN observation clock (`routerReceivedAt`), held by MachinePoolRegistry.
+ *
+ * This pure decision keeps the conservative direction throughout: when in doubt,
+ * a peer is NOT presumed dead (a wrongful "dead" verdict causes a takeover →
+ * split-brain, the worse failure). It is flag-gated; with `skewImmune:false` it is
+ * byte-for-byte the legacy `lastSeen`-threshold behavior.
+ */
+export interface PeerLivenessInputs {
+    /** Registry `lastSeen` parsed to ms (the peer's own wall clock). null/NaN ⇒ unknown. */
+    lastSeenMs: number | null;
+    /**
+     * Does the in-process MachinePoolRegistry hold a `routerReceivedAt` for this
+     * peer THIS incarnation? false ⇒ known-on-disk-but-not-yet-observed (a fresh
+     * boot before the first heartbeat) → the skew-immune source has no opinion yet,
+     * so we fall back to lastSeen rather than wrongly presume-dead a peer we simply
+     * haven't heard from yet (the convergence-review edge).
+     */
+    routerObserved: boolean;
+    /** The registry's skew-immune online verdict (now − routerReceivedAt < failoverThreshold). */
+    routerOnline: boolean;
+    /** Caller's now (ms). */
+    nowMs: number;
+    /** Liveness horizon (ms). */
+    failoverThresholdMs: number;
+    /** Flag: use the skew-immune router source when it has an opinion. */
+    skewImmune: boolean;
+}
+/**
+ * True iff the peer should be PRESUMED DEAD (eligible for the lease to act as if
+ * it is gone). Conservative: only on positive evidence of staleness.
+ */
+export declare function isPeerPresumedDead(i: PeerLivenessInputs): boolean;
+//# sourceMappingURL=leaseLiveness.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"leaseLiveness.d.ts","sourceRoot":"","sources":["../../src/core/leaseLiveness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,kBAAkB;IACjC,wFAAwF;IACxF,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;;;;;;OAMG;IACH,cAAc,EAAE,OAAO,CAAC;IACxB,8FAA8F;IAC9F,YAAY,EAAE,OAAO,CAAC;IACtB,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,6BAA6B;IAC7B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,sEAAsE;IACtE,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAWjE"}

package/dist/core/leaseLiveness.js

@@ -0,0 +1,34 @@
+/**
+ * B4 (multimachine-lease-poll-robustness, Decision 10) — skew-immune peer
+ * liveness for the lease layer.
+ *
+ * The lease's `presumedDeadHolders` / `allPeersPresumedGone` historically derive
+ * liveness from the registry `lastSeen` — the PEER's OWN wall clock. Under clock
+ * skew (the 2026-06-20 post-reboot incident) a +Ns-fast peer looks MORE alive
+ * than it is (delaying a needed failover) and a −Ns-slow peer looks DEADER than
+ * it is (triggering a false failover → the flap). The skew-immune source is the
+ * router's OWN observation clock (`routerReceivedAt`), held by MachinePoolRegistry.
+ *
+ * This pure decision keeps the conservative direction throughout: when in doubt,
+ * a peer is NOT presumed dead (a wrongful "dead" verdict causes a takeover →
+ * split-brain, the worse failure). It is flag-gated; with `skewImmune:false` it is
+ * byte-for-byte the legacy `lastSeen`-threshold behavior.
+ */
+/**
+ * True iff the peer should be PRESUMED DEAD (eligible for the lease to act as if
+ * it is gone). Conservative: only on positive evidence of staleness.
+ */
+export function isPeerPresumedDead(i) {
+    // PRIMARY — skew-immune router liveness, but ONLY when the router actually has
+    // an observation for this peer this incarnation. observed-but-stale ⇒ dead.
+    if (i.skewImmune && i.routerObserved) {
+        return !i.routerOnline;
+    }
+    // FALLBACK — legacy lastSeen threshold (flag off, OR peer not yet observed).
+    // Unknown/unparseable lastSeen ⇒ NOT dead (conservative; a takeover on a peer
+    // we can't measure is exactly the split-brain risk we refuse).
+    if (i.lastSeenMs == null || Number.isNaN(i.lastSeenMs))
+        return false;
+    return i.nowMs - i.lastSeenMs > i.failoverThresholdMs;
+}
+//# sourceMappingURL=leaseLiveness.js.map

package/dist/core/leaseLiveness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"leaseLiveness.js","sourceRoot":"","sources":["../../src/core/leaseLiveness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAuBH;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,CAAqB;IACtD,+EAA+E;IAC/E,4EAA4E;IAC5E,IAAI,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,cAAc,EAAE,CAAC;QACrC,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC;IACzB,CAAC;IACD,6EAA6E;IAC7E,8EAA8E;IAC9E,+DAA+D;IAC/D,IAAI,CAAC,CAAC,UAAU,IAAI,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC;QAAE,OAAO,KAAK,CAAC;IACrE,OAAO,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,mBAAmB,CAAC;AACxD,CAAC"}

package/dist/core/pollIntent.d.ts

@@ -0,0 +1,65 @@
+/**
+ * B1 (multimachine-lease-poll-robustness, Decisions 4/5/6) — the cross-process
+ * poll-intent file. The SERVER (which holds the fenced lease) writes its
+ * lease-derived poll intent here on every role transition; the LIFELINE (a
+ * separate process that owns the Telegram socket) reads it to decide whether to
+ * poll (via decidePollAction). This is the bridge that makes poll-ownership
+ * FOLLOW the lease at runtime instead of a static boot-time flag.
+ *
+ * Integrity (Decision 5): the record carries the writing server's `serverPid` +
+ * `bootId` + `ts`. The lifeline IGNORES an intent (→ "no current opinion", null)
+ * that is stale (older than a bound) or whose writer pid is dead — so a stale
+ * `{shouldPoll:true}` left on disk after a crash can NOT resurrect a poller, and a
+ * stale `{shouldPoll:false}` can NOT wrongly silence a live awake machine. The
+ * server writes `{shouldPoll:false}` at boot (before its role is known), so the
+ * default on-disk state is the safe one (mute). A graceful-shutdown mute is NOT
+ * relied upon: a crashed/exited writer is covered by the consumer's dead-pid +
+ * staleness gate (`effectivePollIntent` → null → the lifeline HOLDs).
+ *
+ * Threat model: local same-uid IPC (parity with TelegramPollOwnerLease) — never
+ * network-reachable. Atomic write (tmp + rename) so the lifeline never reads a
+ * torn record.
+ */
+export interface PollIntentRecord {
+    shouldPoll: boolean;
+    leaseEpoch: number;
+    role: 'awake' | 'standby';
+    serverPid: number;
+    bootId: string;
+    /** epoch ms when written. */
+    ts: number;
+}
+/** Absolute path to the intent file under a state dir (`.instar`). */
+export declare function pollIntentPath(stateDir: string): string;
+/** Atomic write (tmp + rename). Never throws to the caller's hot path — callers wrap. */
+export declare function writePollIntent(stateDir: string, rec: PollIntentRecord): void;
+/** Read + parse the intent record. Returns null on missing/corrupt. */
+export declare function readPollIntent(stateDir: string): PollIntentRecord | null;
+export interface PollIntentFreshnessInputs {
+    nowMs: number;
+    /** Max age before the record is "no current opinion". */
+    maxStaleMs: number;
+    /** Is the writing server pid alive? (caller probes process liveness.) */
+    serverPidAlive: boolean;
+}
+/**
+ * The EFFECTIVE poll intent the lifeline should act on:
+ *   - true / false  — a fresh, live-writer record's shouldPoll.
+ *   - null          — "no current opinion": missing, stale (> maxStaleMs), or the
+ *                     writing server pid is dead. decidePollAction treats null as
+ *                     HOLD (never a surprise stop, never a blind start).
+ *
+ * Pure — the I/O (read + pid probe) is the caller's; this decides trust.
+ */
+export declare function effectivePollIntent(rec: PollIntentRecord | null, i: PollIntentFreshnessInputs): boolean | null;
+export interface PollActiveRecord {
+    pollingActive: boolean;
+    pid: number;
+    ts: number;
+}
+export declare function pollActivePath(stateDir: string): string;
+export declare function writePollActive(stateDir: string, pollingActive: boolean): void;
+export declare function readPollActive(stateDir: string): PollActiveRecord | null;
+/** True iff a pid is alive (probe). Used to discount a crashed writer's record. */
+export declare function pidAlive(pid: number): boolean;
+//# sourceMappingURL=pollIntent.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pollIntent.d.ts","sourceRoot":"","sources":["../../src/core/pollIntent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAKH,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,OAAO,GAAG,SAAS,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,6BAA6B;IAC7B,EAAE,EAAE,MAAM,CAAC;CACZ;AAID,sEAAsE;AACtE,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,yFAAyF;AACzF,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,gBAAgB,GAAG,IAAI,CAK7E;AAED,uEAAuE;AACvE,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAYxE;AAED,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,cAAc,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,gBAAgB,GAAG,IAAI,EAC5B,CAAC,EAAE,yBAAyB,GAC3B,OAAO,GAAG,IAAI,CAKhB;AASD,MAAM,WAAW,gBAAgB;IAAG,aAAa,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;CAAE;AAEtF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,GAAG,IAAI,CAK9E;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAUxE;AAED,mFAAmF;AACnF,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAM7C"}

package/dist/core/pollIntent.js

@@ -0,0 +1,112 @@
+/**
+ * B1 (multimachine-lease-poll-robustness, Decisions 4/5/6) — the cross-process
+ * poll-intent file. The SERVER (which holds the fenced lease) writes its
+ * lease-derived poll intent here on every role transition; the LIFELINE (a
+ * separate process that owns the Telegram socket) reads it to decide whether to
+ * poll (via decidePollAction). This is the bridge that makes poll-ownership
+ * FOLLOW the lease at runtime instead of a static boot-time flag.
+ *
+ * Integrity (Decision 5): the record carries the writing server's `serverPid` +
+ * `bootId` + `ts`. The lifeline IGNORES an intent (→ "no current opinion", null)
+ * that is stale (older than a bound) or whose writer pid is dead — so a stale
+ * `{shouldPoll:true}` left on disk after a crash can NOT resurrect a poller, and a
+ * stale `{shouldPoll:false}` can NOT wrongly silence a live awake machine. The
+ * server writes `{shouldPoll:false}` at boot (before its role is known), so the
+ * default on-disk state is the safe one (mute). A graceful-shutdown mute is NOT
+ * relied upon: a crashed/exited writer is covered by the consumer's dead-pid +
+ * staleness gate (`effectivePollIntent` → null → the lifeline HOLDs).
+ *
+ * Threat model: local same-uid IPC (parity with TelegramPollOwnerLease) — never
+ * network-reachable. Atomic write (tmp + rename) so the lifeline never reads a
+ * torn record.
+ */
+import { writeFileSync, readFileSync, renameSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+const FILE = 'telegram-poll-intent.json';
+/** Absolute path to the intent file under a state dir (`.instar`). */
+export function pollIntentPath(stateDir) {
+    return join(stateDir, FILE);
+}
+/** Atomic write (tmp + rename). Never throws to the caller's hot path — callers wrap. */
+export function writePollIntent(stateDir, rec) {
+    const p = pollIntentPath(stateDir);
+    const tmp = `${p}.tmp.${rec.serverPid}`;
+    writeFileSync(tmp, JSON.stringify(rec), 'utf8');
+    renameSync(tmp, p);
+}
+/** Read + parse the intent record. Returns null on missing/corrupt. */
+export function readPollIntent(stateDir) {
+    const p = pollIntentPath(stateDir);
+    if (!existsSync(p))
+        return null;
+    try {
+        const rec = JSON.parse(readFileSync(p, 'utf8'));
+        if (typeof rec?.shouldPoll !== 'boolean' || typeof rec?.serverPid !== 'number' || typeof rec?.ts !== 'number') {
+            return null; // shape check — a partial/legacy record is "no opinion"
+        }
+        return rec;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The EFFECTIVE poll intent the lifeline should act on:
+ *   - true / false  — a fresh, live-writer record's shouldPoll.
+ *   - null          — "no current opinion": missing, stale (> maxStaleMs), or the
+ *                     writing server pid is dead. decidePollAction treats null as
+ *                     HOLD (never a surprise stop, never a blind start).
+ *
+ * Pure — the I/O (read + pid probe) is the caller's; this decides trust.
+ */
+export function effectivePollIntent(rec, i) {
+    if (!rec)
+        return null;
+    if (!i.serverPidAlive)
+        return null; // writer is dead → its opinion is stale
+    if (i.nowMs - rec.ts > i.maxStaleMs)
+        return null; // too old → no current opinion
+    return rec.shouldPoll;
+}
+// ── lifeline-poll-active (B5 source — Decision 6) ───────────────────────────
+// The LIFELINE (the process that actually owns the getUpdates socket) writes its
+// REAL poll state here; B5's exactly-one-listener guard reads THIS (the truth),
+// not the server's intent (a wish). Same local-same-uid IPC + atomic-write posture.
+const POLL_ACTIVE_FILE = 'lifeline-poll-active.json';
+export function pollActivePath(stateDir) {
+    return join(stateDir, POLL_ACTIVE_FILE);
+}
+export function writePollActive(stateDir, pollingActive) {
+    const p = pollActivePath(stateDir);
+    const tmp = `${p}.tmp.${process.pid}`;
+    writeFileSync(tmp, JSON.stringify({ pollingActive, pid: process.pid, ts: Date.now() }), 'utf8');
+    renameSync(tmp, p);
+}
+export function readPollActive(stateDir) {
+    const p = pollActivePath(stateDir);
+    if (!existsSync(p))
+        return null;
+    try {
+        const rec = JSON.parse(readFileSync(p, 'utf8'));
+        if (typeof rec?.pollingActive !== 'boolean' || typeof rec?.ts !== 'number')
+            return null;
+        return rec;
+    }
+    catch {
+        return null;
+    }
+}
+/** True iff a pid is alive (probe). Used to discount a crashed writer's record. */
+export function pidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM = exists but not ours (still alive); ESRCH = gone.
+        return err.code === 'EPERM';
+    }
+}
+//# sourceMappingURL=pollIntent.js.map

package/dist/core/pollIntent.js.map

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

package/dist/core/pollerCount.d.ts

@@ -0,0 +1,61 @@
+/**
+ * B5 (multimachine-lease-poll-robustness, Decision 11) — the exactly-one-listener
+ * decision.
+ *
+ * Telegram allows exactly ONE getUpdates poller per bot token. Zero pollers =
+ * silence (the 3.5h incident); ≥2 = a 409-conflict war + split handling. This
+ * pure decision answers "how many of my machines are polling?" THREE-valued so a
+ * dark peer never produces a false alarm:
+ *   - ok            exactly one FRESH poller observed, no peer dark/unknown.
+ *   - dual          ≥2 pollers positively observed, OR a local Telegram 409
+ *                   (partition-immune evidence of a 2nd poller even when the
+ *                   peer's heartbeat is dark — the case heartbeat-counting alone
+ *                   can't see).
+ *   - silence       zero pollers, and every peer is fresh + known (so it's a real
+ *                   zero, not a visibility gap).
+ *   - indeterminate a peer is dark or reports an unknown poll state, so the exact
+ *                   count can't be confirmed — surface "can't confirm ingress",
+ *                   NEVER a false silence/ok alarm (the adversarial-review rule).
+ *
+ * Pure + deterministic → fully unit-testable. SIGNAL only (observe), never gates.
+ */
+export interface PollerObservation {
+    machineId: string;
+    /**
+     * Whether this machine's lifeline is ACTUALLY polling. `undefined` = an older
+     * peer that doesn't emit the field yet (mid-rollout) OR genuinely unknown —
+     * treated as a visibility gap (→ indeterminate), never as "not polling".
+     */
+    pollingActive: boolean | undefined;
+    /** Heartbeat-fresh (not dark). A dark peer's poll state is unknowable. */
+    fresh: boolean;
+}
+export type PollerCountVerdict = 'ok' | 'dual' | 'silence' | 'indeterminate';
+export interface PollerCountResult {
+    verdict: PollerCountVerdict;
+    /** Pollers positively observed (fresh AND pollingActive === true). */
+    activePollers: number;
+    /** True if any peer is dark or reports an unknown poll state. */
+    hasVisibilityGap: boolean;
+    /** One-line reason for the surface. */
+    reason: string;
+}
+/**
+ * @param observations one row per pool machine (INCLUDING self — self is always
+ *   fresh + a known poll state).
+ * @param localSaw409 did THIS machine's lifeline recently get a Telegram 409
+ *   (someone else is polling the same token)? Partition-immune dual evidence.
+ */
+export declare function evaluatePollerCount(observations: PollerObservation[], localSaw409: boolean): PollerCountResult;
+/**
+ * Adapter — evaluate the exactly-one-listener verdict directly over the pool's
+ * MachineCapacity rows (from `?scope=pool`). `online` is the freshness signal
+ * (a dark peer → not fresh → indeterminate), `pollingActive` the truth field
+ * (absent on an older peer → unknown). This is what a `/guards` surface calls.
+ */
+export declare function poolPollerVerdict(capacities: Array<{
+    machineId: string;
+    online?: boolean;
+    pollingActive?: boolean;
+}>, localSaw409: boolean): PollerCountResult;
+//# sourceMappingURL=pollerCount.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pollerCount.d.ts","sourceRoot":"","sources":["../../src/core/pollerCount.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,aAAa,EAAE,OAAO,GAAG,SAAS,CAAC;IACnC,0EAA0E;IAC1E,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,MAAM,kBAAkB,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,GAAG,eAAe,CAAC;AAE7E,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,kBAAkB,CAAC;IAC5B,sEAAsE;IACtE,aAAa,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,gBAAgB,EAAE,OAAO,CAAC;IAC1B,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,iBAAiB,EAAE,EACjC,WAAW,EAAE,OAAO,GACnB,iBAAiB,CAyBnB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,KAAK,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,aAAa,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC,EACnF,WAAW,EAAE,OAAO,GACnB,iBAAiB,CAKnB"}

package/dist/core/pollerCount.js

@@ -0,0 +1,62 @@
+/**
+ * B5 (multimachine-lease-poll-robustness, Decision 11) — the exactly-one-listener
+ * decision.
+ *
+ * Telegram allows exactly ONE getUpdates poller per bot token. Zero pollers =
+ * silence (the 3.5h incident); ≥2 = a 409-conflict war + split handling. This
+ * pure decision answers "how many of my machines are polling?" THREE-valued so a
+ * dark peer never produces a false alarm:
+ *   - ok            exactly one FRESH poller observed, no peer dark/unknown.
+ *   - dual          ≥2 pollers positively observed, OR a local Telegram 409
+ *                   (partition-immune evidence of a 2nd poller even when the
+ *                   peer's heartbeat is dark — the case heartbeat-counting alone
+ *                   can't see).
+ *   - silence       zero pollers, and every peer is fresh + known (so it's a real
+ *                   zero, not a visibility gap).
+ *   - indeterminate a peer is dark or reports an unknown poll state, so the exact
+ *                   count can't be confirmed — surface "can't confirm ingress",
+ *                   NEVER a false silence/ok alarm (the adversarial-review rule).
+ *
+ * Pure + deterministic → fully unit-testable. SIGNAL only (observe), never gates.
+ */
+/**
+ * @param observations one row per pool machine (INCLUDING self — self is always
+ *   fresh + a known poll state).
+ * @param localSaw409 did THIS machine's lifeline recently get a Telegram 409
+ *   (someone else is polling the same token)? Partition-immune dual evidence.
+ */
+export function evaluatePollerCount(observations, localSaw409) {
+    const activePollers = observations.filter((o) => o.fresh && o.pollingActive === true).length;
+    const hasVisibilityGap = observations.some((o) => !o.fresh || o.pollingActive === undefined);
+    // 409 is ground truth that a 2nd poller exists — even if its heartbeat is dark.
+    if (localSaw409) {
+        return { verdict: 'dual', activePollers, hasVisibilityGap,
+            reason: 'Telegram 409 conflict — a second machine is polling the same bot token' };
+    }
+    // We positively SEE ≥2 pollers → dual regardless of any unknown peers.
+    if (activePollers >= 2) {
+        return { verdict: 'dual', activePollers, hasVisibilityGap,
+            reason: `${activePollers} machines are polling Telegram (dual-poll → 409 war)` };
+    }
+    // A visibility gap means we can't assert exactly-one or zero → indeterminate.
+    if (hasVisibilityGap) {
+        return { verdict: 'indeterminate', activePollers, hasVisibilityGap,
+            reason: 'cannot confirm ingress — a peer is unreachable or on an older version' };
+    }
+    // Everyone fresh + known, <2 active.
+    if (activePollers === 1) {
+        return { verdict: 'ok', activePollers, hasVisibilityGap, reason: 'exactly one machine is polling Telegram' };
+    }
+    return { verdict: 'silence', activePollers, hasVisibilityGap,
+        reason: 'NO machine is polling Telegram — inbound is not being received' };
+}
+/**
+ * Adapter — evaluate the exactly-one-listener verdict directly over the pool's
+ * MachineCapacity rows (from `?scope=pool`). `online` is the freshness signal
+ * (a dark peer → not fresh → indeterminate), `pollingActive` the truth field
+ * (absent on an older peer → unknown). This is what a `/guards` surface calls.
+ */
+export function poolPollerVerdict(capacities, localSaw409) {
+    return evaluatePollerCount(capacities.map((c) => ({ machineId: c.machineId, pollingActive: c.pollingActive, fresh: !!c.online })), localSaw409);
+}
+//# sourceMappingURL=pollerCount.js.map

package/dist/core/pollerCount.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pollerCount.js","sourceRoot":"","sources":["../../src/core/pollerCount.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AA0BH;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CACjC,YAAiC,EACjC,WAAoB;IAEpB,MAAM,aAAa,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,aAAa,KAAK,IAAI,CAAC,CAAC,MAAM,CAAC;IAC7F,MAAM,gBAAgB,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC;IAE7F,gFAAgF;IAChF,IAAI,WAAW,EAAE,CAAC;QAChB,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,gBAAgB;YACvD,MAAM,EAAE,wEAAwE,EAAE,CAAC;IACvF,CAAC;IACD,uEAAuE;IACvE,IAAI,aAAa,IAAI,CAAC,EAAE,CAAC;QACvB,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,gBAAgB;YACvD,MAAM,EAAE,GAAG,aAAa,sDAAsD,EAAE,CAAC;IACrF,CAAC;IACD,8EAA8E;IAC9E,IAAI,gBAAgB,EAAE,CAAC;QACrB,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,gBAAgB;YAChE,MAAM,EAAE,uEAAuE,EAAE,CAAC;IACtF,CAAC;IACD,qCAAqC;IACrC,IAAI,aAAa,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,EAAE,yCAAyC,EAAE,CAAC;IAC/G,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,gBAAgB;QAC1D,MAAM,EAAE,gEAAgE,EAAE,CAAC;AAC/E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAC/B,UAAmF,EACnF,WAAoB;IAEpB,OAAO,mBAAmB,CACxB,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,aAAa,EAAE,CAAC,CAAC,aAAa,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,EACtG,WAAW,CACZ,CAAC;AACJ,CAAC"}