instar 1.3.690 → 1.3.691

package/dist/core/nobodyPollingActuator.js

@@ -0,0 +1,61 @@
+/**
+ * MESH-SELF-HEAL G2 — enforce-mode ACTUATOR (dependency-injected, testable).
+ *
+ * Spec: MESH-SELF-HEAL-SPEC §3.2; build plan: MESH-SELF-HEAL-G2-BUILD.md.
+ *
+ * This is the ENFORCE half of G2: given a `claim` decision from
+ * `decideNobodyPollingClaim`, actually take poll-ownership — win the fenced
+ * epoch-CAS, RE-VERIFY live local poll-success (CAS-win is necessary-not-sufficient,
+ * Adv2-F1), then either start polling (drive the existing poll-follows-lease lever)
+ * or relinquish + self-exclude. The delicate cross-machine authority (the exact
+ * code whose hasty version caused the 2026-06-27 tug-of-war) is isolated behind
+ * INJECTED PORTS so it is unit-testable WITHOUT a live coordinator/lifeline, and so
+ * the dryRun gate is a single, auditable chokepoint.
+ *
+ * Ships DARK + dryRun-first. In dryRun it records "would actuate" and performs ZERO
+ * side effects (no CAS acquire, no poll-lever write) — pure observation. Only an
+ * explicit `dryRun:false` (the enforce promotion) ever touches the lease or polling.
+ *
+ * SECOND-PASS REVIEW REQUIRED before merge (this holds poll-ownership authority).
+ */
+import { decidePostCasSelfReverify } from './nobodyPollingRecovery.js';
+/**
+ * Actuate a G2 claim decision. Pure control-flow over injected ports; the only
+ * authority is exercised through the ports, and ONLY when `dryRun` is false and the
+ * decision is a genuine self-claim. Idempotent per call.
+ */
+export async function applyNobodyPollingRecovery(args) {
+    const { decision, dryRun, ports, ledger, nowIso, log } = args;
+    // Only a genuine self-claim actuates. stand-down / veto / fail-closed / hold /
+    // escalate / await / no-op are non-actuating (the decision recorder already
+    // counted them); the actuator must NEVER touch the lease for those.
+    if (!decision.selfClaims || decision.action !== 'claim') {
+        return { result: 'no-action', reason: `decision=${decision.action}` };
+    }
+    // DARK / dryRun: observe only. Record the counterfactual; perform NO side effect.
+    if (dryRun) {
+        log?.(`[g2-actuator] DRY-RUN would claim poll-ownership (epoch n+1) — no CAS, no poll-lever write`);
+        return { result: 'dry-run-would-claim', reason: 'dry-run-observe-only' };
+    }
+    // ENFORCE: win the fenced epoch-CAS. Losing means a peer won the same episode —
+    // stand down (the single-claimant invariant holds via the fence, not our guess).
+    const won = await ports.acquireFencedCas();
+    if (!won) {
+        return { result: 'cas-lost', reason: 'another-machine-won-the-fenced-epoch' };
+    }
+    // CAS-win is necessary but NOT sufficient (Adv2-F1): re-verify OWN live poll
+    // freshness (current+local) before committing to serve.
+    const reverify = decidePostCasSelfReverify({ localPollSucceededFresh: ports.localPollSucceededFresh() });
+    if (!reverify.commit) {
+        ports.relinquishAndSelfExclude();
+        ledger.recordSelfExclusion(nowIso);
+        log?.(`[g2-actuator] won CAS but self-unfit on re-verify → relinquished + self-excluded`);
+        return { result: 'self-excluded', reason: reverify.reason };
+    }
+    // Committed: drive the poll-follows-lease lever to START polling at the won epoch.
+    // (The caller's post-claim live-verify confirms lifeline-poll-active.json advances.)
+    ports.startPolling(ports.currentEpoch());
+    log?.(`[g2-actuator] claimed poll-ownership + started polling at epoch ${ports.currentEpoch()}`);
+    return { result: 'claimed-serving', reason: 'cas-won-self-reverified-fit' };
+}
+//# sourceMappingURL=nobodyPollingActuator.js.map

package/dist/core/nobodyPollingActuator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nobodyPollingActuator.js","sourceRoot":"","sources":["../../src/core/nobodyPollingActuator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAoCvE;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAAC,IAOhD;IACC,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAE9D,+EAA+E;IAC/E,4EAA4E;IAC5E,oEAAoE;IACpE,IAAI,CAAC,QAAQ,CAAC,UAAU,IAAI,QAAQ,CAAC,MAAM,KAAK,OAAO,EAAE,CAAC;QACxD,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;IACxE,CAAC;IAED,kFAAkF;IAClF,IAAI,MAAM,EAAE,CAAC;QACX,GAAG,EAAE,CAAC,4FAA4F,CAAC,CAAC;QACpG,OAAO,EAAE,MAAM,EAAE,qBAAqB,EAAE,MAAM,EAAE,sBAAsB,EAAE,CAAC;IAC3E,CAAC;IAED,gFAAgF;IAChF,iFAAiF;IACjF,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,gBAAgB,EAAE,CAAC;IAC3C,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,sCAAsC,EAAE,CAAC;IAChF,CAAC;IAED,6EAA6E;IAC7E,wDAAwD;IACxD,MAAM,QAAQ,GAAG,yBAAyB,CAAC,EAAE,uBAAuB,EAAE,KAAK,CAAC,uBAAuB,EAAE,EAAE,CAAC,CAAC;IACzG,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;QACrB,KAAK,CAAC,wBAAwB,EAAE,CAAC;QACjC,MAAM,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC;QACnC,GAAG,EAAE,CAAC,kFAAkF,CAAC,CAAC;QAC1F,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC;IAC9D,CAAC;IAED,mFAAmF;IACnF,qFAAqF;IACrF,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC,YAAY,EAAE,CAAC,CAAC;IACzC,GAAG,EAAE,CAAC,mEAAmE,KAAK,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;IACjG,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,EAAE,6BAA6B,EAAE,CAAC;AAC9E,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.690",
+  "version": "1.3.691",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-28T09:16:28.110Z",
-  "instarVersion": "1.3.690",
+  "generatedAt": "2026-06-28T09:47:08.176Z",
+  "instarVersion": "1.3.691",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {
@@ -1618,7 +1618,7 @@
       "type": "subsystem",
       "domain": "coordination",
       "sourcePath": "src/core/MultiMachineCoordinator.ts",
-      "contentHash": "7920e0bbe7f86ae0e4b5a2f39c6ef2e0272c3e90f1d8dccf11ced30d8bbcc76a",
+      "contentHash": "db0a3a53e3b3fc6d8c9593918944cba27c1faccd5a369d71bf1e555cf20bb028",
       "since": "2025-01-01"
     },
     "subsystem:backup-manager": {

package/upgrades/1.3.691.md

@@ -0,0 +1,28 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Mesh Self-Heal **G2 enforce** (MESH-SELF-HEAL-SPEC §3.2) — the take-over actuation for the nobody-serving alarm. When NO machine is polling Telegram (the zombie-lease-holder state behind the message-drop incidents), exactly ONE fit machine now takes over poll-ownership — never zero (drops), never two (the Telegram 409 poll-war).
+
+- `src/core/nobodyPollingActuator.ts` (`applyNobodyPollingRecovery`) — dependency-injected actuator: win the fenced epoch-CAS → re-verify own poll-freshness (CAS-win is necessary-not-sufficient) → start polling, else relinquish + self-exclude.
+- `MultiMachineCoordinator.evaluateNobodyPolling()` — wires the detector + single-claimant election to the actuator with the real lease ports (`acquireIfEligible` / `currentEpoch` / `writeLeasePollIntent` / `relinquishAndBroadcast`), debounced (confirm=3) and reentrancy-guarded.
+- `server.ts` `refreshPool` — runs it on the existing 30s pool cadence, fire-and-forget.
+
+Ships **dark + dryRun-first** (`multiMachine.nobodyPollingRecovery`, OMITS `enabled` → dev-gated). In dryRun it detects + elects + records the soak counterfactual but performs ZERO side effects (no lease acquire, no poll-lever write) — verified by an independent second-pass review (the high-risk lease-authority gate). Flipping `dryRun:false` is the deliberate enforce promotion, gated on two tracked prerequisites: the real pollSucceeded watermark + the peer-confirmed global-outage plumbing (see MESH-SELF-HEAL-G2-BUILD.md).
+
+## What to Tell Your User
+
+When this is turned on (it ships off, in observe-only mode for now), it fixes the "nobody is polling, so my messages silently drop" problem on multi-machine setups: if the in-charge machine goes quiet, exactly one healthy machine automatically takes over polling — no tug-of-war, no duplicates, no action needed from you. Single-machine setups are unaffected.
+
+## Summary of New Capabilities
+
+- `multiMachine.nobodyPollingRecovery` `{ dryRun }` — opt-in (dev-gated) nobody-polling take-over: detect → elect one machine → acquire the fenced lease → start polling. Dark + dryRun by default (observe-only; zero side effects until a deliberate enforce promotion).
+
+## Evidence
+
+- `tests/unit/nobodyPollingActuator.test.ts` — 5 tests, both sides of every boundary incl. the critical dryRun=zero-side-effects safety invariant (no CAS, no poll-write) and CAS-lost / self-excluded / claimed-serving.
+- Builds on the merged G2 core (18 unit) + observe route (4 integration). Dark-gate lint golden map updated for the +7 line shift. Typecheck clean; full G2 suite green.
+- Independent Phase-5 second-pass review: CONCUR (dryRun invariant holds; single-claimant is the fenced CAS; no tug-of-war). Its one minor concern (reentrancy guard) was fixed in this commit.

package/upgrades/side-effects/mesh-self-heal-g2-enforce.md

@@ -0,0 +1,38 @@
+# Side-Effects Review — Mesh Self-Heal G2 (enforce actuation)
+
+**Change:** The ENFORCE half of G2 (MESH-SELF-HEAL-SPEC §3.2) — actually taking over poll-ownership when nobody is polling. HIGH-RISK: it holds cross-machine poll-ownership authority (the area whose hasty version caused the 2026-06-27 tug-of-war). Pieces:
+- `src/core/nobodyPollingActuator.ts` (`applyNobodyPollingRecovery`) — dependency-injected actuator: dryRun gate → `acquireFencedCas` → `decidePostCasSelfReverify` → `startPolling` / `relinquishAndSelfExclude`. 5 unit tests.
+- `MultiMachineCoordinator.evaluateNobodyPolling()` — the wiring: gate (`nobodyPollingRecoveryCfg`) → B5 verdict → debounce (`_g2SilenceStreak`, confirm=3) → `decideNobodyPollingClaim` → record → actuate (real ports: `leaseCoordinator.acquireIfEligible` / `currentEpoch` / `writeLeasePollIntent(true)` / `relinquishAndBroadcast`). Reentrancy-guarded (`_g2Evaluating`).
+- `server.ts` `refreshPool` — the 30s cadence (fire-and-forget, gated inside the coordinator).
+- `ConfigDefaults`: `multiMachine.nobodyPollingRecovery: { dryRun: true }` (OMITS `enabled` → dev-gated). Dark-gate lint golden map updated (+7 line shift).
+
+**Decision point?** YES — it acquires the fenced lease + starts polling. Signal-vs-authority + the dryRun safety invariant are the load-bearing concerns.
+
+## 1. Over-block
+N/A (it grants poll-ownership, never blocks). It biases hard against acting: only a confirmed real silence where this machine is the deterministic single claimant AND wins the fenced CAS AND re-verifies its own poll-freshness ever serves.
+
+## 2. Under-block
+Ships dark+dryRun (default), so nothing actuates until a deliberate `dryRun:false`. **Enforce-ENABLE prerequisites (TRACKED, not orphan-deferred — see MESH-SELF-HEAL-G2-BUILD.md + the enforce note below):** (1) the real `pollSucceededMonoMs`/serve-progress watermark for `localPollSucceededFresh` (currently a lifeline-liveness approximation — consulted ONLY when dryRun:false); (2) peer-confirmed `globalOutageEvidence` plumbing (currently hard-coded false → a confirmed silence proceeds to elect, the local-failure-safe direction). Both are inert under dryRun.
+
+## 3. Level-of-abstraction fit
+The authority lives in the coordinator (it owns the leaseCoordinator); the server only supplies the cadence + capacities. The actuator isolates the delicate flow behind injected ports (testable without a live coordinator; the dryRun gate is a single chokepoint). Reuses `acquireIfEligible` (the SAME fence `tickLease` uses) — not a parallel acquire path.
+
+## 4. Signal vs authority compliance
+COMPLIANT with the safety design: the only authority (acquire CAS + start polling) is exercised through the ports ONLY when `dryRun:false` AND the decision is a genuine self-claim. The election is deterministic + machine-agnostic, but it is NOT the authority — the **fenced CAS is the single-claimant gate** (even if two machines diverge on the election under partition, `acquireIfEligible` admits exactly one; the loser gets `cas-lost` and stands down). `decidePostCasSelfReverify` enforces "CAS-win necessary-not-sufficient."
+
+## 5. Interactions
+- vs `tickLease`: a won CAS makes this machine the holder → `tickLease`'s non-holder acquire converges (doesn't fight); a successful claim flips the verdict to `ok` (self-terminating). Debounce + post-CAS reverify damp flap.
+- Reentrancy: `_g2Evaluating` prevents a >30s eval overlapping the 30s cadence (which would inflate the silence streak pre-await). Added per the 2nd-pass review.
+- Cadence: fire-and-forget with `.catch()` — a slow/failed eval never blocks or fails `refreshPool`.
+
+## 6. External surfaces
+No new route (the observe `/mesh-selfheal/g2` from the prior PR reads the same ledger). New config path `multiMachine.nobodyPollingRecovery` (dev-gated). When `dryRun:false` it WRITES the lease (poll-ownership) — the reason this is dark-first + 2nd-pass-gated.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+This IS the cross-machine recovery actuator. Coherence is the deterministic election + the fenced CAS (one winner, pool-wide). The watermarks it reads are machine-local (skew-immune). Single-machine = strict no-op (no leaseCoordinator/peers → `skipped`).
+
+## 8. Rollback cost
+Trivial — ships dark+dryRun (strict no-op until a deliberate enable). Revert the commit, or leave the flag off. No migration, no state. Even enabled-in-dryRun performs zero side effects.
+
+## Second-Pass Review (REQUIRED — high-risk: lease/poll-ownership authority)
+An independent reviewer audited the actuator + coordinator method + cadence. **Verdict: CONCUR.** Verified: (a) the dryRun invariant HOLDS — the gate sits strictly before every port call; default `dryRun:true` (`?? true`) + dev-gated dark-on-fleet; test pins zero side-effects; (b) single-claimant is genuinely the fenced CAS, not the election guess — a partition divergence still admits exactly one (loser → `cas-lost`); (c) no tug-of-war — the won CAS converges with `tickLease`, debounce + self-reverify damp flap; (d) fail directions correct, hardcoded `globalOutageEvidence:false` is the documented local-safe direction + inert under dryRun. **One concern raised (minor, non-blocking given dark+dryRun): no reentrancy guard** on `evaluateNobodyPolling` — a >30s eval could overlap the 30s tick and inflate `_g2SilenceStreak`. **RESOLVED in this commit** (added `_g2Evaluating` guard, mirroring `leaseTicking`). The reviewer's two enforce-ENABLE prerequisites (the pollSucceeded watermark; the globalOutageEvidence plumbing) are tracked in MESH-SELF-HEAL-G2-BUILD.md as the gate before `dryRun:false`.