@inetafrica/open-claudia 3.0.41 → 3.0.43

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## v3.0.43 — Telegram stops rebooting into a dead network: outages now pause-and-wait instead of restart-storming
+
+- **A host-wide network blip no longer triggers a reboot storm.** v3.0.42 fixed the *in-loop* poll wedge (a poisoned reused poller) so it heals in place — but it still kept the 10-minute `process.exit(1)` backstop, which fired even when the *entire host* had lost the network (a laptop sleep/wake, or pod egress starvation where Telegram poll+send, Kazee WS and Spaces WS all drop together). Exiting into a dead network just relaunched straight back into the same outage, so you'd see "Back online and ready! Running v3.0.42" every ~14 minutes, busting the prompt cache and spamming the chat. Now the self-exit is **reachability-gated**: before it ever restarts the process it runs a fresh, connection-fresh HEAD probe to `api.telegram.org`, and only exits if that probe genuinely **succeeds** — proving the API is reachable and it's a real in-process wedge worth a clean restart, not the host being offline.
+- **When the host is actually offline, the bot now pauses and waits instead of hammering.** On a confirmed-unreachable probe the adapter enters an *outage pause*: it **stops polling entirely** (so `node-telegram-bot-api` no longer respins `getUpdates` every ~300ms into a dead socket — the "not waiting between reconnects" hammering) and re-probes on a calm **30-second** cadence. The instant connectivity returns it resumes polling cleanly from a fresh poller (the update offset is preserved, so nothing is refetched or skipped) — no process restart, no "Back online" spam. The pause also suspends the health watchdog and hiccup handler so they don't fight the slow re-probe. Poll-health transitions are now timestamped for easier post-mortem.
+- **Agent-space / OpenClaw:** no new deps, env, or schema change; Docker image builds FROM the existing `:base`. Change is confined to `channels/telegram/adapter.js` (the `_heal` backstop plus the new `_enterOutagePause`/`_armHealthyCheck` paths); covered by new cases in `test-telegram-poll-recovery.js` (the gated exit defers on a live host, pauses instead of rebooting on a dead one, and resumes when the network returns). Existing pods pick it up on their next approved upgrade.
+
+## v3.0.42 — Telegram stops rebooting itself: the long-poll wedge now heals in place
+
+- **The bot no longer restarts the whole process to recover from a stuck Telegram long-poll.** When the network stalls a poll mid-flight (a half-open socket after a laptop sleep/wake, or a NAT/IPv6 connection eviction), `node-telegram-bot-api` was left holding one reused internal poller whose abort flag got stuck "on". Restarting polling *in place* revived that same poisoned object, which fired a single `getUpdates` and then silently refused to schedule the next one — a dead loop that threw no error, so the heal looked like it "worked" while nothing was actually polling. The only thing that ever truly recovered was the 10-minute backstop calling `process.exit(1)` and letting the supervisor relaunch — i.e. the reboot storm you'd see. The heal now **discards the poisoned poller so a fresh one is built** (the update offset is preserved, so no messages are refetched or skipped), and it only declares polling "healthy again" once a `getUpdates` has genuinely **completed since the restart** — otherwise it re-arms another heal instead of blindly declaring victory. Net effect: transient poll wedges recover in seconds without a process restart; the 10-min self-exit becomes the rare true-last-resort it was meant to be.
+- **Agent-space / OpenClaw:** no new deps, env, or schema change; Docker image builds FROM the existing `:base`. Change is confined to `channels/telegram/adapter.js` (the `_heal` path); covered by three new cases in `test-telegram-poll-recovery.js` (proven to fail before the fix and pass after — the poisoned-object revival and the false "healthy" signal). Existing pods pick it up on their next approved upgrade.
+
 ## v3.0.41 — Verbose off now means a clean chat: the "Let me…" narration no longer lingers
 
 - **With `/verbose` off, the interim progress message is now removed once a turn settles, so the chat is left with only the final answer.** During a multi-step turn the bot posts a throttled "working…" preview that shows the short "Let me check…/Let me look at…" narration emitted before each tool call. That preview used to *stay* — settling into a permanent message — regardless of `/verbose`, which only ever gated the extended-thinking (🧠) stream. So even with verbose off you'd be left with the narration trail as a leftover message that reads like thinking-out-loud. `finalizeStreamPreview` now deletes that preview when verbose is off; `/verbose on` still keeps the narration trail. Live progress during long turns is unchanged either way — the cleanup only affects what remains after the turn ends.

package/channels/telegram/adapter.js

@@ -44,6 +44,8 @@ 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._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
     this._pollStartedAt = 0;
     this._conflictSince = 0;         // start of the current 409 streak
@@ -83,6 +85,7 @@ class TelegramAdapter {
   }
 
   _checkPollingHealth() {
+    if (this._pausedForOutage) return; // outage pause runs its own slow re-probe
     if (this._conflictTimer || this._conflictSince) return; // 409 backoff owns recovery
     const lastCompletedPoll = this.bot?._polling?._lastUpdate || this._pollStartedAt;
     if (!lastCompletedPoll || Date.now() - lastCompletedPoll <= 75000) return;
@@ -95,6 +98,8 @@ class TelegramAdapter {
     if (this._healthyTimer) { clearTimeout(this._healthyTimer); this._healthyTimer = null; }
     if (this._conflictTimer) { clearTimeout(this._conflictTimer); this._conflictTimer = null; }
     if (this._conflictClearTimer) { clearTimeout(this._conflictClearTimer); this._conflictClearTimer = null; }
+    if (this._outageProbeTimer) { clearTimeout(this._outageProbeTimer); this._outageProbeTimer = null; }
+    this._pausedForOutage = false;
     try { await this._stopPollingClean("adapter stop"); } catch (e) {}
   }
 
@@ -107,6 +112,7 @@ 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) {
+    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
     // would keep _wedgedSince pinned until the 10-min backstop killed us (the
@@ -116,7 +122,7 @@ class TelegramAdapter {
     if (!this._wedgedSince) this._wedgedSince = now;
     if (now - this._lastHiccupLog > 60000) {
       this._lastHiccupLog = now;
-      console.log(`Polling hiccup (${msg}) — retrying on a fresh connection.`);
+      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);
@@ -148,51 +154,159 @@ class TelegramAdapter {
     catch (e) { return false; }
   }
 
+  _stamp() {
+    return new Date().toISOString();
+  }
+
+  // Can this HOST reach Telegram AT ALL right now? A one-shot HEAD-ish probe on
+  // a brand-new connection (agent:false so it never rides our possibly-wedged
+  // poll agent), bounded so the probe itself can't hang. Any HTTP response —
+  // even a 404 — proves the TCP+TLS path is alive; a reset/timeout means it
+  // isn't. This is the fresh-process-equivalent check that lets the wedge
+  // backstop tell a genuine in-loop poll wedge (a restart fixes it) from a
+  // host-wide network outage (every outbound connection is failing together —
+  // Telegram polls + sends AND the Kazee/Spaces websockets — so a reboot just
+  // relaunches into the same dead network and spams "Back online"). Never rejects.
+  _probeTelegramReachable() {
+    return new Promise((resolve) => {
+      let settled = false;
+      const done = (v) => { if (!settled) { settled = true; resolve(v); } };
+      try {
+        const req = https.get(
+          { hostname: "api.telegram.org", port: 443, path: "/", agent: false, timeout: 8000 },
+          (res) => { res.resume(); done(true); },
+        );
+        req.on("timeout", () => { try { req.destroy(); } catch (e) {} done(false); });
+        req.on("error", () => done(false));
+      } catch (e) { done(false); }
+    });
+  }
+
   async _heal() {
     this._healTimer = null;
-    // Backstop only: if polling has been unbroken-wedged for 10 minutes, a
-    // restart-in-place won't fix it — exit for a clean launchd relaunch. On a
-    // healthy network this never fires (heals recover in seconds); it replaces
-    // the old hair-trigger ~90s exit that caused the restart storm.
-    if (this._wedgedSince && !this._conflictSince && Date.now() - this._wedgedSince > 600000) {
-      // Never fires during a 409 streak: that's a token fight, not a network
-      // wedge, and exiting busts the prompt cache (full uncached re-bill of the
-      // conversation window on the next turn).
-      if (this._anyTurnActive()) {
-        // A turn is in flight — never reboot mid-turn: it kills in-progress work
-        // and breaks the seamless resume the user expects. Defer the exit, keep
-        // attempting in-place recovery below, and let a later heal exit once the
-        // process is idle. If polling self-heals meanwhile, the wedge clears and
-        // no exit ever happens. (Recovery only touches the poll socket — the
-        // running turn's subprocess and its outbound sends dial their own.)
-        if (!this._deferredExitLogAt || Date.now() - this._deferredExitLogAt > 60000) {
-          this._deferredExitLogAt = Date.now();
-          console.error("Polling wedged >10min but a turn is in progress — deferring restart until idle.");
+    // A sustained wedge (>60s, and not a 409 streak): probe ONE fresh connection
+    // to learn WHY before we keep restarting. This both distinguishes a genuine
+    // in-loop poll wedge from a host-network outage AND lets us stop hammering
+    // when the network itself is down. On a healthy network wedges clear in
+    // seconds and never reach this branch. (Never during a 409 streak: that's a
+    // token fight, not a network wedge, and the conflict handler owns the loop.)
+    if (this._wedgedSince && !this._conflictSince && Date.now() - this._wedgedSince > 60000) {
+      if (!(await this._probeTelegramReachable())) {
+        // A fresh connection to Telegram fails too: a host-wide network outage,
+        // not a poll wedge (we've watched the Telegram poll, Telegram sends, and
+        // the Kazee + Spaces websockets all drop in lockstep). A reboot can't fix
+        // a dead network — the fresh process can't reach Telegram either and just
+        // spams "Back online". Restarting the poll loop is equally futile and only
+        // hammers getUpdates every ~300ms (which can trip a 429 the instant the
+        // link flickers back). Stop polling entirely and wait it out on a slow
+        // re-probe; resume the moment connectivity returns. Never exits.
+        this._enterOutagePause();
+        return;
+      }
+      // Telegram answers a fresh connection, yet our poll loop still hasn't
+      // completed a getUpdates. If that's dragged past 10 minutes a restart-in-
+      // place plainly isn't clearing it — exit for a clean launchd relaunch. On a
+      // healthy network this never fires (the null-restart below clears an in-loop
+      // wedge in seconds); it replaces the old hair-trigger ~90s restart storm.
+      if (Date.now() - this._wedgedSince > 600000) {
+        if (this._anyTurnActive()) {
+          // A turn is in flight — never reboot mid-turn: it kills in-progress work
+          // and breaks the seamless resume. Defer the exit, fall through to another
+          // in-place recovery attempt, and let a later idle heal exit if needed.
+          if (!this._deferredExitLogAt || Date.now() - this._deferredExitLogAt > 60000) {
+            this._deferredExitLogAt = Date.now();
+            console.error(`${this._stamp()} Polling wedged >10min but a turn is in progress — deferring restart until idle.`);
+          }
+        } else {
+          console.error(`${this._stamp()} Polling wedged >10min and Telegram is reachable — exiting for a clean restart.`);
+          try { require("../../core/restart-reason").recordExitReason("Telegram polling wedged >10min while API reachable — self-exit for a clean restart", { code: 1 }); } catch (e) {}
+          process.exit(1);
         }
-      } else {
-        console.error("Polling wedged >10min — exiting for a clean restart.");
-        try { require("../../core/restart-reason").recordExitReason("Telegram polling wedged >10min (long-poll unrecoverable) — self-exit for a clean restart", { code: 1 }); } catch (e) {}
-        process.exit(1);
       }
     }
     try {
       await this._stopPollingClean("stale Telegram long-poll recovery");
       await new Promise((r) => setTimeout(r, 500));
-      // restart:false — the lib's restart path is another cancel-stop (zombie
-      // factory); we already stopped cleanly, so only start if truly idle.
+      // THE wedge fix: the lib reuses this.bot._polling across start/stop and
+      // only reschedules the poll loop when `_abort === false`. A wedge (half-
+      // open socket after sleep/wake or a NAT/IPv6 eviction) can leave the old
+      // getUpdates unsettled past our 5s stop cap, so `_abort` stays stuck true
+      // — the restarted loop then fires ONE getUpdates and dies in its .finally,
+      // a silent dead loop that only process.exit ever cleared (the restart
+      // storm). Nulling forces startPolling to build a FRESH object with
+      // `_abort=false`; the offset survives via the shared bot.options.polling
+      // params, so no updates are refetched or skipped.
+      this.bot._polling = null;
+      // The fresh object's _lastUpdate starts at 0; startPolling below blocks up
+      // to ~30s on the first long-poll, so stamp the watchdog grace baseline NOW
+      // — else _checkPollingHealth would fall back to a stale _pollStartedAt and
+      // false-fire mid-first-poll.
+      this._pollStartedAt = Date.now();
       await this.bot.startPolling({ restart: false });
     } catch (e) {
       return; // restart didn't take — the next hiccup reschedules a heal
     }
-    // Quiet for 30s after a restart ⇒ genuinely recovered.
+    this._armHealthyCheck(this._pollStartedAt, "restart completed but no getUpdates within 35s");
+  }
+
+  // Recovery is real only if a getUpdates has actually COMPLETED since the
+  // (re)start — not merely "no throw for 35s". A dead one-shot loop throws
+  // 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.
+  _armHealthyCheck(restartedAt, reArmMsg) {
     if (this._healthyTimer) clearTimeout(this._healthyTimer);
     this._healthyTimer = setTimeout(() => {
       this._healthyTimer = null;
-      if (this._wedgedSince) console.log("Polling healthy again.");
-      this._wedgedSince = 0;
-      this._healBackoff = 0;
-      this._deferredExitLogAt = 0;
-    }, 30000);
+      const lastCompletedPoll = this.bot?._polling?._lastUpdate || 0;
+      if (lastCompletedPoll >= restartedAt) {
+        if (this._wedgedSince) console.log(`${this._stamp()} Polling healthy again.`);
+        this._wedgedSince = 0;
+        this._healBackoff = 0;
+        this._deferredExitLogAt = 0;
+      } else {
+        this._onPollingHiccup(reArmMsg);
+      }
+    }, 35000);
+  }
+
+  // Host-network outage recovery: STOP the poll loop entirely (kill the lib's
+  // ~300ms getUpdates retry spin) and re-probe Telegram on a slow ~30s cadence,
+  // resuming the instant a fresh connection succeeds. Nothing outbound can get
+  // through while the host has no network, so spinning only burns CPU and risks a
+  // 429 when the link flickers back — this is the "wait between reconnects"
+  // backoff. Polling and the socket.io adapters all auto-recover together when
+  // connectivity returns. Never exits.
+  _enterOutagePause() {
+    if (this._pausedForOutage) return;
+    this._pausedForOutage = true;
+    if (this._healthyTimer) { clearTimeout(this._healthyTimer); this._healthyTimer = null; }
+    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(() => {});
+    const tick = async () => {
+      this._outageProbeTimer = null;
+      if (!this._pausedForOutage) return;
+      if (!(await this._probeTelegramReachable())) {
+        if (this._pausedForOutage) this._outageProbeTimer = setTimeout(tick, 30000);
+        return;
+      }
+      // Connectivity is back. Resume on a FRESH poll loop object (the offset
+      // survives in bot.options.polling params, so no updates are missed or
+      // refetched), then confirm a getUpdates actually completes.
+      this._pausedForOutage = false;
+      console.log(`${this._stamp()} Telegram reachable again — resuming polling after outage.`);
+      try {
+        this.bot._polling = null;
+        this._pollStartedAt = Date.now();
+        await this.bot.startPolling({ restart: false });
+      } catch (e) {
+        this._onPollingHiccup("resume after outage failed to start");
+        return;
+      }
+      this._armHealthyCheck(this._pollStartedAt, "resume after outage completed but no getUpdates within 35s");
+    };
+    this._outageProbeTimer = setTimeout(tick, 30000);
   }
 
   // Telegram 409s a getUpdates call while ANOTHER one holds the token: a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inetafrica/open-claudia",
-  "version": "3.0.41",
+  "version": "3.0.43",
   "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

@@ -65,7 +65,28 @@ assert.match(pkg.description, /provider-agnostic coding-agent harness/i);
 // permanent message regardless of /verbose — only extended-thinking was gated.
 // finalizeStreamPreview now deletes the settled preview when /verbose is off, so
 // chat carries only the final answer; verbose ON still keeps the narration trail.
-assert.strictEqual(pkg.version, "3.0.41", "release version must remain unchanged without explicit approval");
+// 3.0.42 approved by Sumeet 2026-07-18 ("Yes please because it's restarting way
+// too much"): Telegram poll-recovery fix that stops the restart storm. A wedge
+// (half-open getUpdates after sleep/wake or NAT/IPv6 eviction) left the lib's
+// REUSED _polling object with _abort stuck true, so the in-place restart revived
+// a dead one-shot loop — the heal "succeeded" yet nothing polled, and only the
+// 10-min process.exit backstop recovered. The heal now nulls _polling so the lib
+// builds a fresh object (offset survives via the shared params), and the
+// "healthy" reset requires a getUpdates that actually COMPLETED since the restart
+// (else it re-arms a heal) instead of blindly declaring victory after 35s.
+// 3.0.43 approved by Sumeet 2026-07-18 ("Yeh push"): reachability-gated self-exit
+// + outage-pause backoff, so a host-wide network blip no longer triggers a
+// reboot storm. v3.0.42 healed the in-loop wedge but STILL rebooted after 10min
+// even when the whole host had lost the network (laptop sleep, pod egress
+// starvation) — exiting into a dead network just relaunched into the same
+// outage, spamming "Back online" every ~14min. The 10-min self-exit is now gated
+// on a fresh HEAD probe to api.telegram.org actually SUCCEEDING (proves a genuine
+// in-loop wedge, not a dead host); if the probe fails the adapter enters an
+// outage pause — it STOPS polling (no 300ms lib reconnect spin) and re-probes
+// every 30s, resuming cleanly the moment connectivity returns. Poll-health logs
+// are timestamped. Confined to channels/telegram/adapter.js; new cases in
+// test-telegram-poll-recovery.js cover the pause+resume and the gated exit.
+assert.strictEqual(pkg.version, "3.0.43", "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

@@ -190,6 +190,7 @@ async function testWedgeExitDefersWhileTurnInFlight() {
   adapter._deferredExitLogAt = 0;
   adapter._healBackoff = 0;
   adapter._anyTurnActive = () => true; // a turn is running/queued
+  adapter._probeTelegramReachable = async () => true; // reachable ⇒ genuine wedge; defer path
   adapter._agent = { destroy() { calls.push("destroy"); } };
   adapter.bot = {
     async stopPolling() { calls.push("stop"); },
@@ -217,8 +218,10 @@ async function testWedgeExitDefersWhileTurnInFlight() {
   assert.ok(adapter._deferredExitLogAt > 0, "the deferral must be logged (throttle stamp set)");
 }
 
-// Once the process is idle (no turn running/queued), the same backstop exits for
-// a clean restart exactly as before — the deferral only postpones, never cancels.
+// Once the process is idle (no turn running/queued) AND Telegram answers a fresh
+// connection — proving this is a real in-loop poll wedge, not a host-network
+// outage — the backstop exits for a clean restart exactly as before. The
+// deferral only postpones, never cancels.
 async function testWedgeExitFiresWhenIdle() {
   let exitCode;
   const adapter = Object.create(TelegramAdapter.prototype);
@@ -227,6 +230,7 @@ async function testWedgeExitFiresWhenIdle() {
   adapter._wedgedSince = Date.now() - 11 * 60 * 1000; // wedged >10min
   adapter._deferredExitLogAt = 0;
   adapter._anyTurnActive = () => false; // idle
+  adapter._probeTelegramReachable = async () => true; // Telegram reachable ⇒ genuine poll wedge
   adapter._agent = { destroy() {} };
   adapter.bot = { async stopPolling() {}, async startPolling() {} };
 
@@ -244,6 +248,269 @@ async function testWedgeExitFiresWhenIdle() {
   assert.strictEqual(exitCode, 1, "the idle wedge backstop must exit(1) for a clean restart");
 }
 
+// THE REBOOT-STORM regression, now resolved by an OUTAGE PAUSE. When the wedge is
+// a host-wide network outage — every outbound connection failing together
+// (Telegram polls + sends AND the Kazee/Spaces websockets) — a reboot can't help:
+// the fresh process can't reach Telegram either and just relaunches into the same
+// dead network, spamming "Back online". So even when idle, the backstop must NOT
+// exit while a fresh connection to Telegram also fails. Instead it STOPS the poll
+// loop entirely (no ~300ms getUpdates hammering that can trip a 429 when the link
+// flickers back) and waits on a slow re-probe. Fails before the fix because the
+// idle backstop exits unconditionally.
+async function testWedgeExitPausesInsteadOfRebootingOnHostOutage() {
+  const calls = [];
+  let exited = false;
+  const adapter = Object.create(TelegramAdapter.prototype);
+  adapter._healTimer = null;
+  adapter._healthyTimer = null;
+  adapter._conflictSince = 0;
+  adapter._wedgedSince = Date.now() - 11 * 60 * 1000; // wedged >10min
+  adapter._deferredExitLogAt = 0;
+  adapter._healBackoff = 0;
+  adapter._pausedForOutage = false;
+  adapter._outageProbeTimer = null;
+  adapter._anyTurnActive = () => false; // idle
+  adapter._probeTelegramReachable = async () => false; // host can't reach Telegram at all
+  adapter._agent = { destroy() { calls.push("destroy"); } };
+  adapter.bot = {
+    async stopPolling() { calls.push("stop"); },
+    async startPolling() { calls.push("start"); },
+  };
+
+  const realExit = process.exit;
+  process.exit = () => { exited = true; throw new Error("process.exit must not be called during a host-network outage"); };
+  const realSetTimeout = global.setTimeout;
+  const realClearTimeout = global.clearTimeout;
+  global.setTimeout = (fn, ms) => { if (ms === 500) fn(); return { ms }; };
+  global.clearTimeout = () => {};
+
+  try {
+    await adapter._heal();
+    await new Promise((r) => realSetTimeout(r, 5)); // let the fire-and-forget stop settle
+  } finally {
+    process.exit = realExit;
+    global.setTimeout = realSetTimeout;
+    global.clearTimeout = realClearTimeout;
+  }
+
+  assert.strictEqual(exited, false, "a host-network outage must NOT trigger a reboot (the fresh process can't reach the network either)");
+  assert.strictEqual(adapter._pausedForOutage, true, "an unreachable host must pause polling instead of rebooting");
+  assert.ok(calls.includes("stop") && calls.includes("destroy"),
+    "entering the outage pause must stop the poll loop and sever the socket");
+  assert.ok(!calls.includes("start"),
+    "while the host is unreachable the bot must NOT keep reconnecting (no ~300ms getUpdates hammering)");
+  assert.ok(adapter._outageProbeTimer, "the pause must schedule a slow re-probe to resume when the network returns");
+}
+
+// Companion: once the network returns, the outage pause's slow re-probe must
+// RESUME polling on a FRESH loop object (offset preserved via bot.options.polling
+// params) and leave the paused state — the bot recovers on its own, no reboot.
+async function testOutagePauseResumesPollingWhenNetworkReturns() {
+  const calls = [];
+  let reachable = false;
+  let tickFn;
+  const adapter = Object.create(TelegramAdapter.prototype);
+  adapter._healTimer = null;
+  adapter._healthyTimer = null;
+  adapter._wedgedSince = Date.now() - 2 * 60 * 1000;
+  adapter._healBackoff = 0;
+  adapter._deferredExitLogAt = 0;
+  adapter._pausedForOutage = false;
+  adapter._outageProbeTimer = null;
+  adapter._pollStartedAt = 0;
+  adapter._onPollingHiccup = () => {};
+  adapter._probeTelegramReachable = async () => reachable;
+  adapter._agent = { destroy() { calls.push("destroy"); } };
+  adapter.bot = {
+    _polling: { _abort: true, _lastUpdate: 0 },
+    async stopPolling() { calls.push("stop"); },
+    async startPolling() {
+      calls.push("start");
+      if (!this._polling) this._polling = { _abort: false, _lastUpdate: Date.now() };
+    },
+  };
+
+  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) tickFn = fn;  // capture the outage re-probe tick
+    return { ms };
+  };
+  global.clearTimeout = () => {};
+
+  try {
+    adapter._enterOutagePause();
+    await new Promise((r) => realSetTimeout(r, 5)); // let the fire-and-forget stop settle
+    assert.strictEqual(adapter._pausedForOutage, true, "an unreachable host pauses polling");
+    assert.ok(!calls.includes("start"), "no reconnecting while paused (network is down)");
+    assert.strictEqual(typeof tickFn, "function", "the pause must schedule a slow re-probe");
+
+    reachable = true;
+    adapter.bot._polling = { _abort: true, _lastUpdate: 0 }; // stale object present before resume
+    await tickFn();
+    assert.strictEqual(adapter._pausedForOutage, false, "a successful re-probe must leave the pause");
+    assert.ok(calls.includes("start"), "a successful re-probe must resume polling");
+    assert.strictEqual(adapter.bot._polling._abort, false, "resume must build a FRESH poll loop object (offset preserved)");
+  } finally {
+    global.setTimeout = realSetTimeout;
+    global.clearTimeout = realClearTimeout;
+  }
+}
+
+// THE RESTART STORM regression. A wedge (half-open getUpdates after sleep/wake
+// or a NAT/IPv6 eviction) leaves the lib's REUSED _polling object with `_abort`
+// stuck true: the hung request never settled within our stop cap, so stop()'s
+// `.finally(() => _abort = false)` never ran. node-telegram-bot-api's
+// startPolling reuses this.bot._polling when it's present, so restarting in
+// place revives the SAME poisoned object — its loop fires one getUpdates and
+// dies in .finally (sees _abort===true ⇒ no reschedule). A silent dead loop:
+// the heal "succeeds" (no throw) yet nothing polls, so only the 10-min backstop's
+// process.exit ever recovered (the reboot storm the user saw). The heal must
+// null _polling so the lib constructs a FRESH object with _abort=false; the
+// offset survives via the shared bot.options.polling params. Fails before the
+// fix because the poisoned object is revived in place.
+async function testHealNullsPoisonedPollingSoLibRebuildsFresh() {
+  const ancient = Date.now() - 5 * 60 * 1000;
+  const poisoned = { _abort: true, _lastUpdate: ancient };
+  const adapter = Object.create(TelegramAdapter.prototype);
+  adapter._healTimer = null;
+  adapter._healthyTimer = null;
+  adapter._wedgedSince = Date.now() - 60000;
+  adapter._healBackoff = 0;
+  adapter._pollStartedAt = ancient;
+  adapter._onPollingHiccup = () => {};
+  adapter._probeTelegramReachable = async () => true; // reachable ⇒ normal in-place heal path
+  adapter._agent = { destroy() {} };
+  adapter.bot = {
+    _polling: poisoned,
+    async stopPolling() { /* wedge: the hung request never settles, _abort stays true */ },
+    async startPolling() {
+      // Faithful to the lib: reuse _polling if present, else construct fresh.
+      if (!this._polling) this._polling = { _abort: false, _lastUpdate: Date.now() };
+    },
+  };
+
+  const realSetTimeout = global.setTimeout;
+  const realClearTimeout = global.clearTimeout;
+  global.setTimeout = (fn, ms) => { if (ms === 500 || ms === 5000) fn(); return { ms }; };
+  global.clearTimeout = () => {};
+  try {
+    await adapter._heal();
+  } finally {
+    global.setTimeout = realSetTimeout;
+    global.clearTimeout = realClearTimeout;
+  }
+
+  assert.notStrictEqual(adapter.bot._polling, poisoned,
+    "heal must discard the poisoned _polling object, not revive it in place");
+  assert.strictEqual(adapter.bot._polling._abort, false,
+    "the rebuilt poller must start with _abort=false so its loop reschedules");
+  assert.ok(adapter.bot._polling._lastUpdate >= adapter._pollStartedAt,
+    "the fresh poller must be able to complete a getUpdates (a live loop, not a dead one-shot)");
+}
+
+// HONEST HEALTH SIGNAL regression. "No throw for 35s" is NOT recovery — a dead
+// one-shot loop throws nothing. The old blind healthy-timer reset _wedgedSince
+// unconditionally, so a restart that never completed a single getUpdates was
+// declared healthy, hiding the wedge until the 10-min backstop rebooted. The
+// check must require a getUpdates COMPLETED since the restart; if none did, it
+// must re-arm a heal instead of declaring victory. Fails before the fix because
+// the blind timer clears the wedge with no completed poll.
+async function testHealthySignalReArmsWhenNoPollCompleted() {
+  const adapter = Object.create(TelegramAdapter.prototype);
+  adapter._healTimer = null;
+  adapter._healthyTimer = null;
+  adapter._wedgedSince = Date.now() - 60000;
+  adapter._healBackoff = 2;
+  adapter._deferredExitLogAt = 0;
+  adapter._pollStartedAt = 0;
+  adapter._probeTelegramReachable = async () => true; // reachable ⇒ normal in-place heal path
+  adapter._agent = { destroy() {} };
+  adapter.bot = {
+    _polling: { _abort: true, _lastUpdate: 0 },
+    async stopPolling() {},
+    async startPolling() {
+      // Models a restart whose loop never completes a getUpdates: _lastUpdate
+      // stays 0 (pre-fix this is the revived poisoned object; post-fix a fresh
+      // object that simply hasn't succeeded yet).
+      if (!this._polling) this._polling = { _abort: false, _lastUpdate: 0 };
+    },
+  };
+  let healthyFn;
+  const hiccups = [];
+  adapter._onPollingHiccup = (m) => hiccups.push(m);
+
+  const realSetTimeout = global.setTimeout;
+  const realClearTimeout = global.clearTimeout;
+  global.setTimeout = (fn, ms) => {
+    if (ms === 500 || ms === 5000) fn();
+    else if (ms >= 30000) healthyFn = fn; // capture the healthy check (30s pre-fix, 35s post)
+    return { ms };
+  };
+  global.clearTimeout = () => {};
+  try {
+    await adapter._heal();
+    assert.strictEqual(typeof healthyFn, "function", "heal must arm a healthy check");
+    healthyFn();
+  } finally {
+    global.setTimeout = realSetTimeout;
+    global.clearTimeout = realClearTimeout;
+  }
+
+  assert.ok(adapter._wedgedSince > 0,
+    "a restart with no completed getUpdates must NOT clear the wedge");
+  assert.match(hiccups[0] || "", /no getUpdates/i,
+    "an unrecovered restart must re-arm a heal, not declare victory");
+}
+
+// Companion happy-path guard: once a getUpdates DOES complete after the restart,
+// the same healthy check clears the wedge and resets backoff (and must NOT
+// re-arm a heal). Passes before and after the fix — it guards the fix from
+// over-correcting into a bot that never declares itself recovered.
+async function testHealthySignalClearsWedgeOnceAPollCompletes() {
+  const adapter = Object.create(TelegramAdapter.prototype);
+  adapter._healTimer = null;
+  adapter._healthyTimer = null;
+  adapter._wedgedSince = Date.now() - 60000;
+  adapter._healBackoff = 3;
+  adapter._deferredExitLogAt = 12345;
+  adapter._pollStartedAt = 0;
+  adapter._probeTelegramReachable = async () => true; // reachable ⇒ normal in-place heal path
+  adapter._agent = { destroy() {} };
+  adapter.bot = {
+    _polling: { _abort: true, _lastUpdate: 0 },
+    async stopPolling() {},
+    async startPolling() {
+      // A fresh, healthy poller that completes a getUpdates just after restart.
+      if (!this._polling) this._polling = { _abort: false, _lastUpdate: Date.now() + 1 };
+    },
+  };
+  let healthyFn;
+  const hiccups = [];
+  adapter._onPollingHiccup = (m) => hiccups.push(m);
+
+  const realSetTimeout = global.setTimeout;
+  const realClearTimeout = global.clearTimeout;
+  global.setTimeout = (fn, ms) => {
+    if (ms === 500 || ms === 5000) fn();
+    else if (ms >= 30000) healthyFn = fn;
+    return { ms };
+  };
+  global.clearTimeout = () => {};
+  try {
+    await adapter._heal();
+    healthyFn();
+  } finally {
+    global.setTimeout = realSetTimeout;
+    global.clearTimeout = realClearTimeout;
+  }
+
+  assert.strictEqual(adapter._wedgedSince, 0, "a completed getUpdates since restart must clear the wedge");
+  assert.strictEqual(adapter._healBackoff, 0, "recovery resets heal backoff");
+  assert.deepStrictEqual(hiccups, [], "a genuinely recovered restart must NOT re-arm a heal");
+}
+
 (async () => {
   await testStartDoesNotWaitForFirstLongPollAndArmsStallWatchdog();
   await testHealStopsPlainlyDestroysAgentAndRestartsIdle();
@@ -251,6 +518,11 @@ async function testWedgeExitFiresWhenIdle() {
   await test409ConflictSeversGhostSocketAndRestartsIdle();
   await testWedgeExitDefersWhileTurnInFlight();
   await testWedgeExitFiresWhenIdle();
+  await testWedgeExitPausesInsteadOfRebootingOnHostOutage();
+  await testOutagePauseResumesPollingWhenNetworkReturns();
+  await testHealNullsPoisonedPollingSoLibRebuildsFresh();
+  await testHealthySignalReArmsWhenNoPollCompleted();
+  await testHealthySignalClearsWedgeOnceAPollCompletes();
   console.log("telegram poll recovery OK");
 })().catch((err) => {
   console.error(err.stack || err);