@inetafrica/open-claudia 3.1.26 → 3.1.28

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## v3.1.28 — The Telegram reboot loop was self-inflicted: the heal kept tearing down its own recovery
+
+- **Symptom.** v3.1.27 shipped to all four Telegram pods and the loop continued (euvy: 6 restarts in 3h). Its fix was real but addressed a different failure — the dominant one never enters `_enterOutagePause` at all (zero "Telegram unreachable" lines in the crash logs). The decisive observation was that the bot reproduced it identically on a laptop — 155 self-exits in a local `bot.log` — which retired the cluster-network and conntrack theories outright. The shape is bursts: healthy for 2.7–4.2h, then ~10 minutes of failed heals, then `process.exit(1)`, repeat.
+- **How it was found.** Reasoning from prod logs had already produced one wrong fix, so this time the local install was instrumented directly (unthrottled lifecycle events to a side file) and a real burst was captured. Two facts invisible to the console log settled it: every polling error after the first carried `_polling._abort === true` — meaning *we* aborted it, not Telegram — and `_lastUpdate` read 0 for 200+ seconds straight across 9 successful restarts. It also retired a number the previous investigation had reported as fact: the "~62s failure cadence" was an artifact of the 1/min log throttle. The real rate was one every ~15s.
+- **Root cause — three stacked deadlocks, each independently fatal to recovery.** (1) `_heal` → `_stopPollingClean` → `_agent.destroy()` kills the in-flight `getUpdates`, which surfaces in `_onPollingHiccup` ~1ms later as `EFATAL: socket hang up`. `_healTimer` had just been nulled at the top of `_heal`, so the "a heal is already scheduled" guard didn't hold and the teardown scheduled *another* heal — which tore the socket down again. Self-sustaining. (2) The backoff capped at 15s while `polling.params.timeout` is 30s, so every restarted poll was aborted at the halfway mark: `_lastUpdate`, the only evidence of recovery, could never advance. (3) `_armHealthyCheck` cleared its own pending timer on every re-arm, so a heal every 15s starved a check that needs 35s of quiet — **zero healthy checks fired in the entire captured burst** — and that callback owns the only reset of `_wedgedSince` and `_healBackoff`. With nothing able to clear the wedge clock, it ran monotonically to the 10-minute backstop. One ordinary `ECONNRESET` was enough to cost ten minutes and a reboot.
+- **Fix.** (1) A time-boxed self-abort window opened in `_stopPollingClean` makes `_onPollingHiccup` ignore the error our own teardown raises; it is never explicitly cleared, so a path that forgets to close it cannot permanently deafen the handler — the worst case is a dropped error that `_armHealthyCheck` re-arms 35s later anyway. (2) The heal ladder (now `_scheduleHeal`) escalates to 45s, clearing the 40s request timeout that bounds one `getUpdates`, so the late rungs give a poll genuine room to land; early rungs stay short because they run while polling is down. (3) Re-arming the healthy check no longer pushes its deadline back — the first arm always fires — while the baseline tracks the newest restart, so a poll that completed *before* the latest restart can't be mistaken for proof the latest restart worked. A failed `startPolling` now schedules its own retry rather than waiting for a hiccup that the suppression window means will never come.
+- **Proof, not assertion.** `testOneNetworkBlipDoesNotSpiralIntoTheWedgeExitLoop` models the poller instead of stubbing it: `destroy()` raises the teardown error for real, a healthy poll takes the full 30s hold to complete, the library re-dials ~300ms after a fault (which is why a heal always had something to destroy), and a virtual clock runs a single `ECONNRESET` well past the 10-minute budget. Against unmodified code it reproduces the production failure exactly — a storm of `socket hang up`, then "Polling wedged >10min and Telegram is reachable — exiting for a clean restart" — and against the fix the bot recovers with the wedge cleared and the ladder reset. Three narrower tests pin each deadlock individually. The previous release's test passed against a bug it did not fix because it drove `_enterOutagePause()` directly, a path production never takes; the lesson — model the interaction, don't stub past it — is why this harness raises the error from `destroy()`.
+- **Correction to v3.1.27's closing note.** That entry wondered whether the wedge-exit backstop earned its keep, observing that "210 restarts never helped". They did: a fresh process is the only thing that escapes the loop, which is exactly why each reboot bought 2.7–4.2h of health. The backstop stays until this fix is proven in the fleet.
+
+## v3.1.27 — The outage pause stops feeding the wedge-exit clock (the fleet-wide Telegram reboot loop)
+
+- **Symptom.** Every Telegram-channel bot was rebooting itself in a loop while no other bot was: rashmi 214 restarts in 7d15h, euvy 210 in 7d17h, ruk-ai 62 in 44h, rahil-coders 11 — 4 of 4 pods running the `telegram` channel. All 12 pods running only `kazee, spaces, web` sat at 0. All 16 share one node and one egress IP, so node, address and NetworkPolicy preset were all controlled for; the *unrestricted* bot (euvy, allow-all egress) restarted most, which retired the egress theory rather than confirming it. The channel was the only discriminator.
+- **Root cause.** `_wedgedSince` is stamped on the first polling hiccup and cleared in exactly one place — `_armHealthyCheck`, on a completed `getUpdates`. `_enterOutagePause()` cleared `_healthyTimer` (the only thing that can reach that reset) and never touched `_wedgedSince`. So every second spent inside the outage pause — a state whose entire documented purpose is *"a reboot can't fix a dead network... never exits"* — still counted toward the 10-minute reboot budget. A link that flapped a few times inside ten minutes rebooted the pod anyway, moments after this very method had twice decided a reboot could not help. Both bots exited almost exactly 10 minutes after their FIRST hiccup regardless of what happened in between: ruk-ai 07:41:02 → 07:51:11 = 10m09s across three outage pauses; euvy 07:33:37 → 07:43:42 = 10m05s.
+- **Fix.** `_enterOutagePause()` now retires the wedge clock (`_wedgedSince = 0`, `_healBackoff = 0`). A failed *fresh* probe is positive evidence that the streak so far was the network, not an in-loop poll wedge — and the exit backstop exists only for the in-loop case. Clearing is safe because `_onPollingHiccup` no-ops while paused: a real in-loop wedge that survives the resume starts an honest new streak.
+- **Proof, not assertion.** New regression test `testOutagePauseDoesNotFeedTheWedgeExitClock` in `test-telegram-poll-recovery.js` replays the production sequence line for line (hiccup → three genuine outage pauses with successful re-probes → ruk-ai's exact 10m09s mark on a reachable link). It **fails against unmodified code** with the reboot firing, and passes with the fix. `testWedgeExitFiresWhenIdle` still passes, so the genuine in-loop backstop is intact, not disabled.
+- **Still open, deliberately not fixed here.** Why the path to `api.telegram.org` flaps at all is unexplained — the probe genuinely fails, three confirmed ~30s outages inside ten minutes on ruk-ai. This change stops the pointless reboots; it does not restore connectivity during a flap. Separately worth asking whether the wedge-exit backstop earns its keep at all: `_heal()` already destroys the agent, nulls `bot._polling` and dials a fresh socket — everything a new process does for the poll path — and 210 restarts never helped.
+
 ## v3.1.26 — Claude Opus 5 in the model picker
 
 - **`claude-opus-5` added to the Claude provider model list** (`CLAUDE_MODELS`), slotted between `claude-fable-5` and `claude-opus-4-8`. Opus 5 launched 2026-07-24 (near-Fable-5 capability at roughly half the price; Anthropic's new default on Max). Verified live before listing: a real CLI round-trip with `--model claude-opus-5` succeeded. Free-text `/model claude-opus-5` already worked (the `/model` handler doesn't validate against the list); this puts it on the picker buttons for `/model` and `/login`. Default model unchanged (`claude-opus-4-8`).

package/channels/telegram/adapter.js

@@ -44,6 +44,9 @@ class TelegramAdapter {
     this._deferredExitLogAt = 0; // throttle the "deferring restart, turn in progress" log (1/min)
     this._lastHiccupLog = 0;     // throttle the transient-error log (1/min)
     this._healBackoff = 0;       // grows per consecutive heal, capped
+    this._selfAbortUntil = 0;    // teardown grace: errors WE caused aren't faults
+    this._healthyBaseline = 0;   // newest restart the pending healthy-check judges
+    this._healthyReArmMsg = "";  // reason text if that check finds no completed poll
     this._pausedForOutage = false; // host-network outage: poll loop stopped, slow re-probe owns recovery
     this._outageProbeTimer = null; // the ~30s re-probe loop that runs while paused
     this._pollWatchdogTimer = null; // detects a silent first/active getUpdates stall
@@ -112,6 +115,15 @@ class TelegramAdapter {
   // old exit-for-relaunch *was* the restart the bot kept doing on every idle
   // timeout (a sleep/wake burst could exhaust all 6 attempts in seconds).
   _onPollingHiccup(msg) {
+    // OUR OWN teardown, not a fault. _stopPollingClean destroys the agent, which
+    // kills the in-flight getUpdates and surfaces here as "socket hang up" 1-5ms
+    // later. Counting it re-armed the heal that had just torn the socket down —
+    // a self-sustaining loop that ran until the 10-min backstop exited the
+    // process (root-caused 2026-08-03 from a live capture: after the ONE genuine
+    // ECONNRESET, every subsequent error carried _polling._abort === true, i.e.
+    // we aborted it). The heal re-arms its own follow-up via _armHealthyCheck,
+    // so dropping these loses no recovery.
+    if (Date.now() < (this._selfAbortUntil || 0)) return;
     if (this._pausedForOutage) return; // paused for a host outage; the slow re-probe owns recovery
     // During a 409 streak the conflict handler owns the poll lifecycle; a heal
     // here would startPolling straight back into the conflict and its errors
@@ -125,8 +137,21 @@ class TelegramAdapter {
       console.log(`${this._stamp()} Polling hiccup (${msg}) — retrying on a fresh connection.`);
     }
     if (this._healTimer) return; // a heal is already scheduled; let it run
-    this._healBackoff = Math.min(this._healBackoff + 1, 5);
-    const delay = Math.min(15000, 500 * 2 ** this._healBackoff); // 1s … 15s
+    this._scheduleHeal();
+  }
+
+  // The heal ladder MUST out-wait one getUpdates or it can never observe
+  // success: a heal tears the socket down, so an interval shorter than the poll
+  // hold aborts every attempt before it can complete and _lastUpdate (the only
+  // evidence of recovery) stays pinned at 0 forever. The old 15s cap sat at HALF
+  // the 30s long-poll hold, which made recovery structurally impossible — a
+  // burst could only ever end at the 10-min wedge-exit. The cap now clears the
+  // 40s request timeout, which bounds even a hung poll, so the last rungs give a
+  // poll genuine room to land. Early rungs stay short: they run while polling is
+  // still down, where retrying fast is free and often enough.
+  _scheduleHeal() {
+    this._healBackoff = Math.min(this._healBackoff + 1, 7);
+    const delay = Math.min(45000, 500 * 2 ** this._healBackoff); // 1s, 2s, 4s, 8s, 16s, 32s, 45s
     this._healTimer = setTimeout(() => this._heal(), delay);
   }
 
@@ -141,6 +166,13 @@ class TelegramAdapter {
   // destroying the agent forces a hung half-open getUpdates to settle NOW
   // instead of never. The 5s race caps the wait if teardown gets swallowed.
   async _stopPollingClean(reason) {
+    // Open the self-abort window BEFORE destroying the agent: the "socket hang
+    // up" it raises lands in _onPollingHiccup within milliseconds. Time-boxed
+    // (never an explicit clear) so a path that forgets to close it can't deafen
+    // the hiccup handler permanently — the worst case is that a genuine error
+    // inside the window is dropped, and _armHealthyCheck still re-arms recovery
+    // 35s later. Covers the 5s stop race + 500ms settle + startPolling.
+    this._selfAbortUntil = Date.now() + 10000;
     const stopped = Promise.resolve(this.bot.stopPolling({ reason })).catch(() => {});
     try { this._agent.destroy(); } catch (e) {}
     await Promise.race([stopped, new Promise((r) => setTimeout(r, 5000))]);
@@ -244,7 +276,12 @@ class TelegramAdapter {
       this._pollStartedAt = Date.now();
       await this.bot.startPolling({ restart: false });
     } catch (e) {
-      return; // restart didn't take — the next hiccup reschedules a heal
+      // Restart didn't take. This used to fall through to "the next hiccup
+      // reschedules a heal", but the self-abort window means the teardown we
+      // just did raises no hiccup — so nothing would be scheduled and the
+      // adapter would sit dead until the wedge-exit. Schedule it ourselves.
+      if (!this._healTimer) this._scheduleHeal();
+      return;
     }
     this._armHealthyCheck(this._pollStartedAt, "restart completed but no getUpdates within 35s");
   }
@@ -254,18 +291,29 @@ class TelegramAdapter {
   // nothing, so a blind timer would declare it healthy and reset _wedgedSince,
   // hiding the wedge until the 10-min backstop rebooted. Gate the reset on a
   // completed poll; otherwise re-arm a heal.
+  //
+  // Re-arming used to clearTimeout the pending check, which starved it: heals
+  // ran every 15s, the check needed 35s of quiet, so it NEVER fired — and it
+  // owns the only reset of _wedgedSince/_healBackoff, so the wedge clock ran
+  // unbroken to the 10-min exit (zero healthcheck events in a 200s+ live
+  // capture, 2026-08-03). Now the DEADLINE is never pushed back — the first arm
+  // wins and always fires — while the baseline tracks the newest restart, so a
+  // poll that completed before the latest restart can't be mistaken for proof
+  // that the latest restart worked.
   _armHealthyCheck(restartedAt, reArmMsg) {
-    if (this._healthyTimer) clearTimeout(this._healthyTimer);
+    this._healthyBaseline = restartedAt;
+    this._healthyReArmMsg = reArmMsg;
+    if (this._healthyTimer) return;
     this._healthyTimer = setTimeout(() => {
       this._healthyTimer = null;
       const lastCompletedPoll = this.bot?._polling?._lastUpdate || 0;
-      if (lastCompletedPoll >= restartedAt) {
+      if (lastCompletedPoll >= this._healthyBaseline) {
         if (this._wedgedSince) console.log(`${this._stamp()} Polling healthy again.`);
         this._wedgedSince = 0;
         this._healBackoff = 0;
         this._deferredExitLogAt = 0;
       } else {
-        this._onPollingHiccup(reArmMsg);
+        this._onPollingHiccup(this._healthyReArmMsg);
       }
     }, 35000);
   }
@@ -281,6 +329,17 @@ class TelegramAdapter {
     if (this._pausedForOutage) return;
     this._pausedForOutage = true;
     if (this._healthyTimer) { clearTimeout(this._healthyTimer); this._healthyTimer = null; }
+    // Retire the wedge clock. A failed fresh probe is positive evidence that the
+    // streak so far was the network, not an in-loop poll wedge — and the exit
+    // backstop exists ONLY for the in-loop case. Leaving it stamped counted every
+    // paused second toward the 10-min reboot budget, so a link that flapped a few
+    // times inside ten minutes rebooted the pod anyway, right after this very
+    // method decided a reboot couldn't help (the fleet-wide loop of 2026-08-01:
+    // rashmi 214 restarts, euvy 210, ruk-ai 62 — every Telegram pod, no kazee one).
+    // Clearing here is safe because _onPollingHiccup no-ops while paused: if a real
+    // in-loop wedge survives the resume, the next hiccup starts an honest new streak.
+    this._wedgedSince = 0;
+    this._healBackoff = 0;
     console.error(`${this._stamp()} Telegram unreachable — host-network outage; pausing polls, re-probing every 30s (no reboot, no reconnect hammering).`);
     // Stop the fast retry loop now (clean stop: no zombie loop, socket severed).
     Promise.resolve(this._stopPollingClean("host-network outage pause")).catch(() => {});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inetafrica/open-claudia",
-  "version": "3.1.26",
+  "version": "3.1.28",
   "description": "An always-on, provider-agnostic coding-agent harness for Claude Code and OpenAI Codex via chat",
   "main": "bot.js",
   "bin": {

package/test-provider-language.js

@@ -322,7 +322,26 @@ assert.match(pkg.description, /provider-agnostic coding-agent harness/i);
 // 3.1.26 approved by Sumeet 2026-07-25 ("Do it"): add claude-opus-5 (launched
 // 2026-07-24) to the Claude provider model picker; verified live via a CLI
 // round-trip with --model claude-opus-5 before listing.
-assert.strictEqual(pkg.version, "3.1.26", "release version must remain unchanged without explicit approval");
+// 3.1.27 approved by Sumeet 2026-08-02 ("Yes") after he asked for proof rather
+// than assertion ("so are you sure these are the issues and the fix or any
+// tests you can run to confirm?"): the outage pause stops feeding the
+// wedge-exit clock. _enterOutagePause cleared _healthyTimer — the only thing
+// that resets _wedgedSince — but never _wedgedSince itself, so every second
+// spent in a state whose whole purpose is "the network is down, a reboot
+// cannot help" still counted toward the 10-minute reboot budget. Reproduced by
+// a new regression test that replays the prod log line for line and fails
+// against unmodified code.
+// 3.1.28 approved by Sumeet 2026-08-03 ("Ok fix it and push our a new version
+// of open Claudia then set up a watcher to wait for the docker to complete
+// building the update across all pods starting with one then if it connects
+// fine do the rest") after v3.1.27 shipped and did NOT stop the loop. Live
+// instrumentation of his own Mac install captured a full burst and root-caused
+// it: the heal's own _agent.destroy() teardown re-entered _onPollingHiccup and
+// scheduled the next heal, the 15s backoff cap sat at HALF the 30s long-poll
+// hold so no getUpdates could ever complete, and _armHealthyCheck cleared its
+// own pending timer on every re-arm so the only code that resets _wedgedSince
+// never ran. One ordinary ECONNRESET cost 10 minutes and a process.exit.
+assert.strictEqual(pkg.version, "3.1.28", "release version must remain unchanged without explicit approval");
 for (const keyword of ["claude", "codex", "coding-agent", "provider-agnostic"]) {
   assert.ok(pkg.keywords.includes(keyword), `package keyword missing: ${keyword}`);
 }

package/test-telegram-poll-recovery.js

@@ -511,6 +511,382 @@ async function testHealthySignalClearsWedgeOnceAPollCompletes() {
   assert.deepStrictEqual(hiccups, [], "a genuinely recovered restart must NOT re-arm a heal");
 }
 
+// THE FLAPPING-NETWORK REBOOT LOOP (live 2026-08-01: rashmi 214 restarts/7d15h, euvy
+// 210/7d17h, ruk-ai 62/44h — all four Telegram pods, none of the twelve kazee-only ones).
+// _wedgedSince is stamped on the FIRST hiccup and cleared in exactly ONE place:
+// _armHealthyCheck, on a COMPLETED getUpdates. _enterOutagePause clears _healthyTimer —
+// the only thing that can reset it — and never touches _wedgedSince. So every second
+// spent inside the outage pause, a state whose whole purpose is "the network is down, a
+// reboot cannot help, never exit", still counts toward the 10-minute reboot budget. A
+// link that flaps a few times inside ten minutes therefore reboots the pod anyway, even
+// though the code twice decided a reboot was the wrong answer. In prod both bots exited
+// almost exactly 10 min after their FIRST hiccup regardless of what happened in between
+// (ruk-ai 07:41:02→07:51:11 = 10m09s with three outage pauses; euvy 07:33:37→07:43:42 =
+// 10m05s). Fails before the fix: the exit fires on accumulated flap time.
+async function testOutagePauseDoesNotFeedTheWedgeExitClock() {
+  const realNow = Date.now;
+  let now = 1_700_000_000_000;
+  Date.now = () => now;
+
+  let exited = false;
+  let reachable = true;
+  let tickFn = null;
+
+  const adapter = Object.create(TelegramAdapter.prototype);
+  adapter._healTimer = null;
+  adapter._healthyTimer = null;
+  adapter._conflictSince = 0;
+  adapter._conflictTimer = null;
+  adapter._wedgedSince = 0;
+  adapter._healBackoff = 0;
+  adapter._deferredExitLogAt = 0;
+  adapter._lastHiccupLog = 0;
+  adapter._pausedForOutage = false;
+  adapter._outageProbeTimer = null;
+  adapter._pollStartedAt = 0;
+  adapter._anyTurnActive = () => false; // idle throughout
+  adapter._probeTelegramReachable = async () => reachable;
+  adapter._agent = { destroy() {} };
+  adapter.bot = {
+    _polling: { _abort: false, _lastUpdate: 0 },
+    async stopPolling() {},
+    // A loop that never manages to complete a getUpdates while the link is flapping.
+    async startPolling() { if (!this._polling) this._polling = { _abort: false, _lastUpdate: 0 }; },
+  };
+
+  const realExit = process.exit;
+  process.exit = () => { exited = true; throw new Error("__exit__"); };
+  const realSetTimeout = global.setTimeout;
+  const realClearTimeout = global.clearTimeout;
+  global.setTimeout = (fn, ms) => {
+    if (ms === 500 || ms === 5000) fn();            // stop-clean internals fire inline
+    else if (ms === 30000) tickFn = fn;             // capture the outage re-probe tick
+    return { ms };
+  };
+  global.clearTimeout = () => {};
+
+  const heal = async () => {
+    adapter._healTimer = null;
+    try { await adapter._heal(); }
+    catch (e) { if (e.message !== "__exit__") throw e; }
+  };
+
+  try {
+    // T+0: the link starts flapping. First hiccup stamps the wedge clock.
+    adapter._onPollingHiccup("EFATAL: Error: socket hang up");
+    const firstHiccup = now;
+    assert.strictEqual(adapter._wedgedSince, firstHiccup, "the first hiccup stamps the wedge clock");
+
+    // T+3m: a fresh connection fails too ⇒ genuine host outage ⇒ pause, never reboot.
+    now += 3 * 60 * 1000;
+    reachable = false;
+    await heal();
+    assert.strictEqual(adapter._pausedForOutage, true, "an unreachable host must enter the outage pause");
+    assert.strictEqual(exited, false, "the outage pause must not reboot");
+
+    // T+3m30s: link returns, polling resumes — but the loop still can't complete a poll.
+    now += 30 * 1000;
+    reachable = true;
+    assert.strictEqual(typeof tickFn, "function", "the pause must schedule a slow re-probe");
+    await tickFn();
+    assert.strictEqual(adapter._pausedForOutage, false, "a successful re-probe leaves the pause");
+
+    // T+6m / T+9m: it flaps twice more, each correctly handled as an outage.
+    for (const _ of [1, 2]) {
+      now += 2 * 60 * 1000 + 30 * 1000;
+      adapter._onPollingHiccup("EFATAL: Error: socket hang up");
+      reachable = false;
+      tickFn = null;
+      await heal();
+      assert.strictEqual(exited, false, "each outage must be paused through, never rebooted");
+      now += 30 * 1000;
+      reachable = true;
+      if (tickFn) await tickFn();
+    }
+
+    // T+10m+: the link is up right now, but the accumulated flap time has blown the
+    // 10-minute budget. The bot must NOT reboot: nearly all of that window was spent in
+    // a state it had already, correctly, decided a reboot could not fix.
+    now = firstHiccup + 10 * 60 * 1000 + 9 * 1000; // ruk-ai's exact 10m09s
+    reachable = true;
+    adapter._onPollingHiccup("EFATAL: Error: socket hang up");
+    await heal();
+
+    assert.strictEqual(exited, false,
+      "time spent in a known host-network outage must NOT count toward the wedge-exit clock — " +
+      "this is the fleet-wide reboot loop (rashmi 214, euvy 210, ruk-ai 62 restarts)");
+  } finally {
+    Date.now = realNow;
+    process.exit = realExit;
+    global.setTimeout = realSetTimeout;
+    global.clearTimeout = realClearTimeout;
+  }
+}
+
+// The fleet reboot loop, reproduced. Everything above stubs the poller; this
+// harness MODELS it, because the bug lived in the interaction the stubs elided:
+// _stopPollingClean destroys the agent, and in production that kills the
+// in-flight getUpdates and re-enters _onPollingHiccup ~1ms later. A stub whose
+// destroy() is a no-op can never show that, which is exactly why v3.1.27's unit
+// test passed against a bug it did not fix (it drove _enterOutagePause, a path
+// the dominant failure never takes). Here destroy() raises the error for real,
+// a poll takes the full 30s hold to complete, and a virtual clock runs the
+// burst past the 10-minute wedge-exit budget.
+function makeVirtualPoller(clock) {
+  const state = { polling: null, pendingPoll: null, onSelfAbort: null, startCount: 0 };
+  const bot = {
+    _polling: null,
+    async stopPolling() {
+      // A plain stop only sets the abort flag — the HTTP request is still open
+      // on the wire. It is _agent.destroy() below that actually kills it, which
+      // is precisely why the resulting error looks like a network fault.
+      if (state.polling) state.polling._abort = true;
+    },
+    async startPolling() {
+      state.startCount += 1;
+      state.polling = { _abort: false, _lastUpdate: 0 }; // fresh object ⇒ _lastUpdate resets to 0
+      bot._polling = state.polling;
+      const mine = state.polling;
+      // A healthy getUpdates completes only after the full 30s long-poll hold.
+      state.pendingPoll = clock.at(clock.now() + 30000, () => {
+        state.pendingPoll = null;
+        if (!mine._abort) mine._lastUpdate = clock.now();
+      });
+    },
+  };
+  const agent = {
+    destroy() {
+      // The real behaviour: tearing the socket down surfaces as a polling error.
+      // No re-dial here — a plain stop set _abort, so the lib's loop does not
+      // reschedule; the heal's own startPolling is what brings polling back.
+      if (state.pendingPoll) {
+        clock.cancel(state.pendingPoll);
+        state.pendingPoll = null;
+        if (state.onSelfAbort) state.onSelfAbort("EFATAL: Error: socket hang up");
+      }
+    },
+  };
+  // A poll that dies on its own (a genuine network fault, _abort still false).
+  // node-telegram-bot-api re-dials within ~300ms, which is why a request is
+  // ALWAYS back in flight by the time a heal runs — and therefore why the heal
+  // always had something to destroy. The live capture shows exactly this:
+  // reqPending was true at every heal:start.
+  state.crash = (msg) => {
+    if (state.pendingPoll) { clock.cancel(state.pendingPoll); state.pendingPoll = null; }
+    if (state.onSelfAbort) state.onSelfAbort(msg);
+    const mine = state.polling;
+    state.pendingPoll = clock.at(clock.now() + 300, () => {
+      state.pendingPoll = clock.at(clock.now() + 30000, () => {
+        state.pendingPoll = null;
+        if (mine && !mine._abort) mine._lastUpdate = clock.now();
+      });
+    });
+  };
+  return { bot, agent, state };
+}
+
+function makeClock(start) {
+  let now = start;
+  let seq = 0;
+  const timers = new Map();
+  return {
+    now: () => now,
+    at(when, fn) { const id = ++seq; timers.set(id, { when, fn }); return id; },
+    cancel(id) { timers.delete(id); },
+    pending: () => timers.size,
+    async advanceTo(target) {
+      for (;;) {
+        let pick = null;
+        for (const [id, t] of timers) {
+          if (t.when > target) continue;
+          if (!pick || t.when < pick.t.when || (t.when === pick.t.when && id < pick.id)) pick = { id, t };
+        }
+        if (!pick) break;
+        timers.delete(pick.id);
+        now = Math.max(now, pick.t.when);
+        await pick.t.fn();
+      }
+      now = target;
+    },
+  };
+}
+
+async function testOneNetworkBlipDoesNotSpiralIntoTheWedgeExitLoop() {
+  const clock = makeClock(1_700_000_000_000);
+  const { bot, agent, state } = makeVirtualPoller(clock);
+
+  const adapter = Object.create(TelegramAdapter.prototype);
+  adapter._healTimer = null;
+  adapter._healthyTimer = null;
+  adapter._healthyBaseline = 0;
+  adapter._healthyReArmMsg = "";
+  adapter._selfAbortUntil = 0;
+  adapter._wedgedSince = 0;
+  adapter._healBackoff = 0;
+  adapter._deferredExitLogAt = 0;
+  adapter._lastHiccupLog = 0;
+  adapter._pausedForOutage = false;
+  adapter._outageProbeTimer = null;
+  adapter._conflictSince = 0;
+  adapter._conflictTimer = null;
+  adapter._pollStartedAt = 0;
+  adapter._anyTurnActive = () => false;
+  adapter._probeTelegramReachable = async () => true; // Telegram was reachable throughout the real burst
+  adapter._agent = agent;
+  adapter.bot = bot;
+  state.onSelfAbort = (msg) => adapter._onPollingHiccup(msg);
+
+  let exited = false;
+  const realExit = process.exit;
+  const realNow = Date.now;
+  const realSetTimeout = global.setTimeout;
+  const realClearTimeout = global.clearTimeout;
+  Date.now = () => clock.now();
+  process.exit = () => { exited = true; throw new Error("__exit__"); };
+  global.setTimeout = (fn, ms) => {
+    if (ms === 500 || ms === 5000) { fn(); return { inline: true }; } // stop-clean internals
+    return clock.at(clock.now() + ms, fn);
+  };
+  global.clearTimeout = (id) => { if (id && !id.inline) clock.cancel(id); };
+
+  try {
+    await bot.startPolling();                       // healthy, mid long-poll hold
+    await clock.advanceTo(clock.now() + 1000);
+    // ONE genuine socket reset — the only external event in the captured burst.
+    state.crash("EFATAL: Error: read ECONNRESET");
+    assert.ok(adapter._wedgedSince > 0, "a real error must open the wedge window");
+
+    // Run well past the 10-minute wedge-exit budget.
+    for (let i = 0; i < 40 && !exited; i += 1) {
+      try { await clock.advanceTo(clock.now() + 30000); }
+      catch (e) { if (e.message !== "__exit__") throw e; }
+    }
+
+    assert.strictEqual(exited, false,
+      "a single ECONNRESET must not end in process.exit — the heal's own teardown was " +
+      "re-triggering the heal, so the wedge clock never cleared and every burst ran to " +
+      "the 10-min backstop (155 self-exits observed locally, 210+ per pod in the fleet)");
+    assert.strictEqual(adapter._wedgedSince, 0,
+      "once a getUpdates completes again the wedge must clear");
+    assert.strictEqual(adapter._healBackoff, 0, "recovery must reset the heal ladder");
+    assert.ok(bot._polling._lastUpdate > 0,
+      "the poll loop must actually complete a getUpdates — pre-fix _lastUpdate stayed 0 forever " +
+      "because each heal aborted the 30s long-poll after 15s");
+    assert.ok(state.startCount <= 4,
+      `recovery must take a couple of restarts, not a storm (took ${state.startCount})`);
+  } finally {
+    Date.now = realNow;
+    process.exit = realExit;
+    global.setTimeout = realSetTimeout;
+    global.clearTimeout = realClearTimeout;
+  }
+}
+
+// Fix 1 in isolation: the "socket hang up" our own _agent.destroy() raises must
+// not schedule a heal. Pre-fix this was the engine of the loop.
+async function testOurOwnTeardownIsNotCountedAsAFault() {
+  const clock = makeClock(1_700_000_000_000);
+  const { bot, agent, state } = makeVirtualPoller(clock);
+
+  const adapter = Object.create(TelegramAdapter.prototype);
+  Object.assign(adapter, {
+    _healTimer: null, _healthyTimer: null, _healthyBaseline: 0, _healthyReArmMsg: "",
+    _selfAbortUntil: 0, _wedgedSince: 0, _healBackoff: 0, _deferredExitLogAt: 0,
+    _lastHiccupLog: 0, _pausedForOutage: false, _outageProbeTimer: null,
+    _conflictSince: 0, _conflictTimer: null, _pollStartedAt: 0,
+    _anyTurnActive: () => false, _probeTelegramReachable: async () => true,
+    _agent: agent, bot,
+  });
+
+  const scheduled = [];
+  const realNow = Date.now;
+  const realSetTimeout = global.setTimeout;
+  const realClearTimeout = global.clearTimeout;
+  Date.now = () => clock.now();
+  global.setTimeout = (fn, ms) => {
+    if (ms === 500 || ms === 5000) { fn(); return { inline: true }; }
+    scheduled.push(ms);
+    return clock.at(clock.now() + ms, fn);
+  };
+  global.clearTimeout = (id) => { if (id && !id.inline) clock.cancel(id); };
+
+  let selfAbortSeen = 0;
+  state.onSelfAbort = (msg) => { selfAbortSeen += 1; adapter._onPollingHiccup(msg); };
+
+  try {
+    await bot.startPolling();
+    await clock.advanceTo(clock.now() + 1000);
+    adapter._wedgedSince = clock.now();      // already in a wedge, as when a heal runs
+    scheduled.length = 0;
+    await adapter._heal();                   // tears the socket down → raises our own error
+
+    assert.strictEqual(selfAbortSeen, 1, "the harness must actually raise the teardown error");
+    assert.deepStrictEqual(scheduled, [35000],
+      "the only timer a heal may arm is its 35s healthy check — pre-fix the teardown error " +
+      "also queued another heal, which tore down the socket again, forever");
+    assert.ok(clock.now() < adapter._selfAbortUntil,
+      "the self-abort window must be open across the restart");
+  } finally {
+    Date.now = realNow;
+    global.setTimeout = realSetTimeout;
+    global.clearTimeout = realClearTimeout;
+  }
+}
+
+// Fix 2: the heal ladder must out-wait one getUpdates. A cap below the poll
+// hold makes recovery unobservable — _lastUpdate can never advance.
+function testHealLadderOutWaitsTheLongPoll() {
+  const adapter = Object.create(TelegramAdapter.prototype);
+  adapter._healBackoff = 0;
+  const delays = [];
+  const realSetTimeout = global.setTimeout;
+  global.setTimeout = (fn, ms) => { delays.push(ms); return { ms }; };
+  try {
+    for (let i = 0; i < 10; i += 1) { adapter._healTimer = null; adapter._scheduleHeal(); }
+  } finally {
+    global.setTimeout = realSetTimeout;
+  }
+  const settled = delays[delays.length - 1];
+  assert.ok(settled > 40000,
+    `the settled heal interval (${settled}ms) must exceed the 40s request timeout that bounds ` +
+    "one getUpdates; the old 15s cap was HALF the 30s long-poll hold, so every attempt was " +
+    "aborted before it could complete and recovery was structurally impossible");
+  assert.ok(delays[0] <= 1000, "early rungs must still retry fast while polling is down");
+}
+
+// Fix 3: re-arming must not push the deadline back, or a heal cadence shorter
+// than the check window starves the only code that clears the wedge.
+function testHealthyCheckCannotBeStarvedByRepeatedReArms() {
+  const adapter = Object.create(TelegramAdapter.prototype);
+  adapter._healthyTimer = null;
+  adapter._healthyBaseline = 0;
+  adapter._healthyReArmMsg = "";
+
+  let armCount = 0;
+  let cleared = 0;
+  const realSetTimeout = global.setTimeout;
+  const realClearTimeout = global.clearTimeout;
+  global.setTimeout = (fn, ms) => { armCount += 1; return { ms, fn }; };
+  global.clearTimeout = () => { cleared += 1; };
+  try {
+    adapter._armHealthyCheck(1000, "first");
+    adapter._armHealthyCheck(2000, "second");
+    adapter._armHealthyCheck(3000, "third");
+  } finally {
+    global.setTimeout = realSetTimeout;
+    global.clearTimeout = realClearTimeout;
+  }
+
+  assert.strictEqual(armCount, 1,
+    "the pending healthy check must keep its original deadline — re-arming it on every heal " +
+    "is why zero healthy checks fired in a 200s+ live capture");
+  assert.strictEqual(cleared, 0, "a pending healthy check must never be cancelled by a re-arm");
+  assert.strictEqual(adapter._healthyBaseline, 3000,
+    "the baseline must track the NEWEST restart, so a poll completed before it cannot be " +
+    "mistaken for proof that the latest restart worked");
+  assert.strictEqual(adapter._healthyReArmMsg, "third", "the re-arm reason must track the newest restart too");
+}
+
 (async () => {
   await testStartDoesNotWaitForFirstLongPollAndArmsStallWatchdog();
   await testHealStopsPlainlyDestroysAgentAndRestartsIdle();
@@ -523,6 +899,11 @@ async function testHealthySignalClearsWedgeOnceAPollCompletes() {
   await testHealNullsPoisonedPollingSoLibRebuildsFresh();
   await testHealthySignalReArmsWhenNoPollCompleted();
   await testHealthySignalClearsWedgeOnceAPollCompletes();
+  await testOutagePauseDoesNotFeedTheWedgeExitClock();
+  await testOneNetworkBlipDoesNotSpiralIntoTheWedgeExitLoop();
+  await testOurOwnTeardownIsNotCountedAsAFault();
+  testHealLadderOutWaitsTheLongPoll();
+  testHealthyCheckCannotBeStarvedByRepeatedReArms();
   console.log("telegram poll recovery OK");
 })().catch((err) => {
   console.error(err.stack || err);