@inetafrica/open-claudia 3.0.1 → 3.0.3

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## v3.0.3 — the lock-holder stands its ground
+
+- **A persistent 409 no longer restarts the bot.** v3.0.1 taught the poller to ride out short 409 conflicts but still `exit(1)` once a conflict outlived 2 minutes, on the theory that the survivor had to be a real second instance. In practice the rogue poller is lock-blind — a debugger-run dev checkout, a copy on another config dir, or another host on the same token — so the exit killed the *legitimate*, lock-holding service and launchd respawned it straight back into the same fight (five boot→409→exit cycles on 2026-07-12). The poller now never exits over a 409: it pauses 15s per retry, slows to 60s once the streak passes 2 minutes, sends the owner a throttled Telegram alert (max one per hour) naming the likely culprits, and posts an all-clear once the rogue goes away.
+- **The single-instance lock is atomic.** Acquisition was read-check-then-write, so two processes booting together (a launchd respawn racing a manual start) could both judge the lock stale and both claim it — each believing it was the only copy. The lock is now claimed with an exclusive-create (`O_EXCL`) in a bounded retry loop: stale, corrupt, or own-pid locks are unlinked and re-claimed atomically, a live holder still turns the newcomer away, and a process that loses every claim attempt refuses to boot rather than assuming ownership.
+- **Agent-space / OpenClaw:** no new deps, no new env, no schema change; Docker image builds identically. `test-telegram-409-grace.js` now proves the never-exit + owner-alert + all-clear path; `test-single-instance.js` passes unchanged against the atomic rewrite.
+
+## v3.0.2 — honest context numbers, dream summaries that arrive
+
+- **The context warning counts the window again, not the bill.** The v3.0.0 provider rewrite computed the live context number from the provider's *cumulative* turn usage — every tool round-trip re-counted the cached prompt prefix, so a normal turn read as 347k+ "context" (crossing 1M on busy turns), spooked the usage alert, and could prematurely force-compact sessions whose real window was fine. The number now tracks the **peak single API call** in the turn (`peakContextTokens` over per-call usage events) — true window occupancy, the same semantics v2 reported (~160k on a heavy turn). Billing is untouched: ledger records keep the cumulative figure in `billedContextTokens`, and API-reported spend was never affected (v3 bills the same or less than v2 — the display was wrong, not the meter). The usage alert says "Context this turn" whenever the peak is available.
+- **Nightly dream summaries reach the chat again.** Dreams ran every night at 04:00 — and for over a week every summary died with Telegram's `400: message is too long` (the report outgrew the 4,096-char hard cap and the adapter had no chunking), so consolidation happened invisibly. Two fixes: the Telegram adapter now splits any oversized message on paragraph → line → word boundaries and sends the chunks in order (reply anchor on the first, buttons on the last, per-chunk HTML→plain fallback preserved), and the dream's tool-health note caps long lists (unused tools, drifted docs) to a short digest in chat while the full lists still land in the on-disk dream log (`~/.open-claudia/dreams/<date>.md`).
+- **Agent-space / OpenClaw:** no new deps, no new env, no schema change; Docker image builds identically. New hermetic assertions: peak-vs-cumulative derivation in `test-usage-accounting.js`, chunk-size and content-preservation in `test-delivery-contract.js`.
+
 ## v3.0.1 — streaming restored, /stop queue survival, boot resilience
 
 - **Live streaming is back, and the final message stays clean.** The v3.0.0 provider rewrite dropped the in-chat streaming feel: no live progress while a run worked, and the settled reply concatenated every text block into one blob. Now an active run edits a throttled preview message in place with the agent's narration (and its thinking, when `/verbose` is on — new command + button toggle), and when the run settles only the **last** text segment is delivered as the final answer; earlier pre-tool text is preserved as narration instead of being glued onto the reply. Providers emit a normalized `thinking` event (Claude thinking blocks, Codex reasoning items) that feeds the preview but can never leak into settled output. On success the preview becomes the narration record (or is deleted when there was none); on failure or cancel the partial preview is kept so you can see how far the run got. Preview edits are channel-guarded, so a bubble minted on one channel is never edited from another.

package/bot.js

@@ -22,10 +22,10 @@ ensureRuntimeDirectories();
 const { acquireSingleInstanceLock } = require("./core/single-instance");
 const instanceLock = acquireSingleInstanceLock({ configDir: CONFIG_DIR });
 if (!instanceLock.acquired) {
-  const h = instanceLock.holder;
+  const h = instanceLock.holder || {};
   console.error(
     `Another Open Claudia instance already owns ${CONFIG_DIR} ` +
-    `(pid ${h.pid}, started ${h.startedAt || "?"}, ${h.entrypoint || "unknown entrypoint"}). Exiting. ` +
+    `(pid ${h.pid || "?"}, started ${h.startedAt || "?"}, ${h.entrypoint || "unknown entrypoint"}). Exiting. ` +
     "Stop it first (launchctl stop com.claude-telegram-bot), or give a dev run its own OPEN_CLAUDIA_CONFIG_DIR."
   );
   process.exit(1);

package/channels/telegram/adapter.js

@@ -10,7 +10,7 @@ const TelegramBot = require("node-telegram-bot-api");
 const { TEMP_DIR, FILES_DIR, CONFIG_DIR } = require("../../core/config");
 const { canonicalForChannel } = require("../../core/identity");
 const { portableToInlineKeyboard } = require("../types");
-const { telegramHtml, htmlToPlain } = require("./format");
+const { telegramHtml, htmlToPlain, splitMessage } = require("./format");
 
 class TelegramAdapter {
   constructor({ id = "telegram", token, ownerChatId, chatIds }) {
@@ -41,6 +41,8 @@ class TelegramAdapter {
     this._conflictSince = 0;         // start of the current 409 streak
     this._conflictTimer = null;      // pending paused retry after a 409
     this._conflictClearTimer = null; // quiet after a retry ⇒ streak over
+    this._conflictAlertAt = 0;       // last owner alert about a rogue poller (throttle: 1/h)
+    this._conflictAlerted = false;   // current streak already alerted ⇒ send the all-clear
     this._wireInbound();
   }
 
@@ -142,23 +144,31 @@ class TelegramAdapter {
     }, 30000);
   }
 
-  // Telegram 409s a getUpdates call while ANOTHER one holds the token. Two
-  // causes: a ghost long-poll left by an uncleanly-killed predecessor (clears
-  // within its ≤30s poll timeout), or a genuinely running second instance.
-  // Exiting on the first 409 turned the ghost case into a KeepAlive respawn
-  // storm (7 boot→409→die cycles on 2026-07-12). So: pause, retry inside a
-  // grace window, and exit only if the conflict outlives it — that really is
-  // a second instance, and the supervisor's throttled respawns pace the rest.
+  // Telegram 409s a getUpdates call while ANOTHER one holds the token: a
+  // ghost long-poll left by an uncleanly-killed predecessor (clears within
+  // its ≤30s poll timeout), or a genuinely running second poller. We hold
+  // the single-instance lock, so WE are the legitimate copy — the rogue is
+  // lock-blind (a pre-lock process, a checkout on another CONFIG_DIR, or
+  // another host on the same token). Exiting here just handed launchd a
+  // respawn into the same fight (the 5-boot storm of 2026-07-12), so we
+  // never exit: pause, retry, and once the streak outlives the ghost window
+  // slow to 60s retries and alert the owner (max 1/hour) until it clears.
   _on409Conflict() {
     const now = Date.now();
     if (!this._conflictSince) this._conflictSince = now;
     if (this._conflictClearTimer) { clearTimeout(this._conflictClearTimer); this._conflictClearTimer = null; }
-    if (now - this._conflictSince > 120000) {
-      console.error("Another instance is polling (409 persisted >2min). Exiting.");
-      process.exit(1);
+    const persisted = now - this._conflictSince > 120000;
+    if (persisted && this.ownerChatId && now - this._conflictAlertAt > 3600000) {
+      this._conflictAlertAt = now;
+      this._conflictAlerted = true;
+      Promise.resolve(this.bot.sendMessage(
+        this.ownerChatId,
+        "⚠️ Another poller has held my Telegram token for over 2 minutes — likely a dev checkout, a debugger run, or another host using this token. I hold the instance lock, so I'm staying up and retrying every 60s; messages may lag until it stops.",
+      )).catch(() => {});
     }
     if (this._conflictTimer) return; // a paused retry is already queued
-    console.error("409 Conflict: another poller holds this token — pausing 15s (ghost polls clear in <1min; exiting only if this persists >2min).");
+    const pauseMs = persisted ? 60000 : 15000;
+    console.error(`409 Conflict: another poller holds this token — pausing ${Math.round(pauseMs / 1000)}s, then retrying (we hold the instance lock; never exiting).`);
     // Stop hammering now; the timer below dials back in.
     Promise.resolve(this.bot.stopPolling({ cancel: true, reason: "409 conflict backoff" })).catch(() => {});
     this._conflictTimer = setTimeout(async () => {
@@ -168,8 +178,14 @@ class TelegramAdapter {
       this._conflictClearTimer = setTimeout(() => {
         this._conflictClearTimer = null;
         this._conflictSince = 0;
+        if (this._conflictAlerted) {
+          this._conflictAlerted = false;
+          if (this.ownerChatId) {
+            Promise.resolve(this.bot.sendMessage(this.ownerChatId, "✅ The competing Telegram poller is gone — normal polling resumed.")).catch(() => {});
+          }
+        }
       }, 45000);
-    }, 15000);
+    }, pauseMs);
   }
 
   _wireInbound() {
@@ -316,13 +332,23 @@ class TelegramAdapter {
   }
 
   async send(channelId, text, opts = {}) {
-    const o = {};
-    let body = opts.parseMode === "HTML" ? telegramHtml(text) : text;
-    if (opts.parseMode) o.parse_mode = opts.parseMode;
+    const body = opts.parseMode === "HTML" ? telegramHtml(text) : text;
     const kb = this._normalizeKeyboard(opts.keyboard);
-    if (kb) o.reply_markup = kb;
-    if (opts.replyTo) o.reply_to_message_id = opts.replyTo;
+    const chunks = splitMessage(body);
+    let lastId = null;
+    for (let i = 0; i < chunks.length; i++) {
+      const o = {};
+      if (opts.parseMode) o.parse_mode = opts.parseMode;
+      // Reply anchor goes on the first chunk; buttons belong on the last.
+      if (opts.replyTo && i === 0) o.reply_to_message_id = opts.replyTo;
+      if (kb && i === chunks.length - 1) o.reply_markup = kb;
+      const id = await this._sendChunk(channelId, chunks[i], o, opts);
+      if (id !== null) lastId = id;
+    }
+    return lastId;
+  }
 
+  async _sendChunk(channelId, body, o, opts = {}) {
     for (let attempt = 0; attempt < 3; attempt++) {
       try {
         const msg = await this.bot.sendMessage(channelId, body, o);

package/channels/telegram/format.js

@@ -139,4 +139,26 @@ function htmlToPlain(html) {
     .replace(/&/g, "&");
 }
 
-module.exports = { escapeHtml, stripMarkdown, telegramHtml, htmlToPlain };
+// Telegram rejects messages over 4096 chars outright ("message is too long"),
+// which silently killed long sends like the nightly dream summary. Split on
+// paragraph > line > word boundaries, with margin for entity accounting.
+function splitMessage(text, limit = 4000) {
+  const body = String(text ?? "");
+  if (body.length <= limit) return [body];
+  const chunks = [];
+  let rest = body;
+  while (rest.length > limit) {
+    const window = rest.slice(0, limit);
+    let cut = window.lastIndexOf("\n\n");
+    if (cut < limit * 0.5) cut = window.lastIndexOf("\n");
+    if (cut < limit * 0.5) cut = window.lastIndexOf(" ");
+    if (cut <= 0) cut = limit;
+    const chunk = rest.slice(0, cut).trimEnd();
+    if (chunk) chunks.push(chunk);
+    rest = rest.slice(cut).replace(/^\s+/, "");
+  }
+  if (rest) chunks.push(rest);
+  return chunks.length ? chunks : [""];
+}
+
+module.exports = { escapeHtml, stripMarkdown, telegramHtml, htmlToPlain, splitMessage };

package/core/dream.js

@@ -1246,17 +1246,29 @@ async function runDreamMutation({ trigger = "manual", provider = null, runUtilit
     // Read-only toward the tools themselves — a tool is never auto-deleted (that's
     // destructive); we just surface the breakage for the user to re-link or remove.
     let toolNote = "";
+    let toolNoteFull = "";
     try {
       const toolsLib = require("./tools");
       const tg = require("./tool-graph").tend(toolsLib, { packsLib: packs });
+      // Two variants: `bits` keeps full lists for the on-disk dream log;
+      // `chatBits` caps the long ones so the chat digest stays readable.
       const bits = [];
+      const chatBits = [];
+      const push = (full, chat = full) => { bits.push(full); chatBits.push(chat); };
+      const capList = (items, sep = ", ", max = 5) => (items.length <= max
+        ? items.join(sep)
+        : `${items.slice(0, max).join(sep)} …and ${items.length - max} more (full list in the dream log)`);
       if (tg.edges || tg.decayed || tg.pruned) {
-        bits.push(`🔧 Tool graph: ${tg.edges} edges / ${tg.nodes} nodes (decayed ${tg.decayed}, pruned ${tg.pruned}).`);
+        push(`🔧 Tool graph: ${tg.edges} edges / ${tg.nodes} nodes (decayed ${tg.decayed}, pruned ${tg.pruned}).`);
       }
       const allTools = toolsLib.listTools();
       const dangling = allTools.filter((t) => t.pack && !packs.readPack(t.pack));
       if (dangling.length) {
-        bits.push(`🔗 ${dangling.length} tool(s) link a missing skill pack: ${dangling.map((t) => `${t.name}→${t.pack}`).join(", ")} — re-link with --pack or remove.`);
+        const names = dangling.map((t) => `${t.name}→${t.pack}`);
+        push(
+          `🔗 ${dangling.length} tool(s) link a missing skill pack: ${names.join(", ")} — re-link with --pack or remove.`,
+          `🔗 ${dangling.length} tool(s) link a missing skill pack: ${capList(names)} — re-link with --pack or remove.`,
+        );
       }
       // Zero-run tools: created but never run and gone cold. Telemetry runCount
       // is authoritative; createdAt measures "how long since it was made" (a body
@@ -1271,7 +1283,11 @@ async function runDreamMutation({ trigger = "manual", provider = null, runUtilit
         try { return fs.statSync(t.file).mtimeMs < cutoff; } catch (e) { return false; }
       });
       if (coldUnused.length) {
-        bits.push(`🗃️ ${coldUnused.length} tool(s) created but never run in ${STALE_DAYS}+ days: ${coldUnused.map((t) => t.name).join(", ")} — keep, fold into another, or remove.`);
+        const names = coldUnused.map((t) => t.name);
+        push(
+          `🗃️ ${coldUnused.length} tool(s) created but never run in ${STALE_DAYS}+ days: ${names.join(", ")} — keep, fold into another, or remove.`,
+          `🗃️ ${coldUnused.length} tool(s) created but never run in ${STALE_DAYS}+ days: ${capList(names)} — keep, fold into another, or remove.`,
+        );
       }
       // Near-duplicate pairs: two tools whose name+description overlap strongly,
       // a sign one should have been a subcommand of the other. Dedupe by sorted
@@ -1284,7 +1300,11 @@ async function runDreamMutation({ trigger = "manual", provider = null, runUtilit
         for (const m of near) dupPairs.add([t.name, m.name].sort().join(" ↔ "));
       }
       if (dupPairs.size) {
-        bits.push(`👯 ${dupPairs.size} near-duplicate tool pair(s): ${[...dupPairs].join(", ")} — consider merging into one tool with subcommands.`);
+        const pairs = [...dupPairs];
+        push(
+          `👯 ${pairs.length} near-duplicate tool pair(s): ${pairs.join(", ")} — consider merging into one tool with subcommands.`,
+          `👯 ${pairs.length} near-duplicate tool pair(s): ${capList(pairs)} — consider merging into one tool with subcommands.`,
+        );
       }
       // Doc/code drift: source edited after TOOL.md, or verbs in real use that
       // the docs never mention. Flag only — the fix is a tool note.
@@ -1292,7 +1312,10 @@ async function runDreamMutation({ trigger = "manual", provider = null, runUtilit
         .map((t) => { const d = toolsLib.docDrift(t); return d ? `${t.name} (${d})` : null; })
         .filter(Boolean);
       if (drifted.length) {
-        bits.push(`📝 ${drifted.length} tool(s) with doc/code drift: ${drifted.join("; ")} — refresh the docs with tool note.`);
+        push(
+          `📝 ${drifted.length} tool(s) with doc/code drift: ${drifted.join("; ")} — refresh the docs with tool note.`,
+          `📝 ${drifted.length} tool(s) with doc/code drift: ${capList(drifted, "; ")} — refresh the docs with tool note.`,
+        );
       }
       // 5c usage KPI: what fraction of operational actions went through the
       // authorised channel, computed from telemetry stamps (state.json run
@@ -1319,10 +1342,11 @@ async function runDreamMutation({ trigger = "manual", provider = null, runUtilit
           }
           if (g.denies.length) kpiBits.push(`${g.denies.length} denied by the gate`);
           if (r.failures) kpiBits.push(`${r.failures} failed run(s) at use: ${r.failedTools.join(", ")}`);
-          bits.push(`📈 Tool usage since last dream: ${kpiBits.join(" · ")}.`);
+          push(`📈 Tool usage since last dream: ${kpiBits.join(" · ")}.`);
         }
       } catch (e) { /* KPI is best-effort */ }
-      toolNote = bits.join("\n");
+      toolNoteFull = bits.join("\n");
+      toolNote = chatBits.join("\n");
     } catch (e) { /* tool graph is best-effort (old node) */ }
 
     const staleNote = staleTaskReport();
@@ -1396,7 +1420,7 @@ async function runDreamMutation({ trigger = "manual", provider = null, runUtilit
       trigger,
       consolidation: { report: decision.report, lines: consolidationLines },
       introspection: { report: introReport, lines: introApplied, proposed: introProposed },
-      healthNote, graphNote, episodicNote, toolNote, staleNote, backupRoot,
+      healthNote, graphNote, episodicNote, toolNote: toolNoteFull || toolNote, staleNote, backupRoot,
     });
 
     // Richer chat summary: consolidation + introspection narrative + what

package/core/runner.js

@@ -84,6 +84,19 @@ function usageParts(usage, backend) {
   };
 }
 
+// The provider's final "turn" usage sums every API call's prefix, re-counting
+// the cached prefix once per tool round-trip. True window occupancy is the
+// largest single call, so track the peak across per-call usage events.
+function peakContextTokens(usageEvents, backend) {
+  let peak = 0;
+  for (const event of usageEvents || []) {
+    if (event?.scope !== "provider_call" || !event.usage) continue;
+    const context = usageParts(event.usage, backend).context;
+    if (context > peak) peak = context;
+  }
+  return peak > 0 ? peak : null;
+}
+
 function clampUsageDelta(current, previous) {
   if (!previous) return current;
   return {
@@ -192,7 +205,7 @@ function logTurnUsage(state, usage, costUsd, announce, opts = {}) {
     if (announce && usageOwnerOnly) {
       const baseline = result.trend?.baselineAvgContextTokens || 0;
       const rate = result.trend?.latestRate || 0;
-      const contextLabel = usageScope === "turn_delta" ? "Context this turn" : "Session context total";
+      const contextLabel = hasPeak || usageScope === "turn_delta" ? "Context this turn" : "Session context total";
       announce([
         "Token usage alert:",
         `${contextLabel}: ${fmtTokens(record.contextTokens)}`,
@@ -1420,7 +1433,8 @@ async function persistForegroundUsage(result, runContext, state = currentState()
     let usage = result.usage;
     let usageScope = result.usageScope || "turn_delta";
     let rawUsage = usage;
-    let liveContextTokens = usageParts(usage, runContext.provider).context;
+    let liveContextTokens = peakContextTokens(result.usageEvents, runContext.provider)
+      ?? usageParts(usage, runContext.provider).context;
     const usageSessionId = result.sessionId || runContext.sessionId;
     const usageProject = runContext.project?.name || null;
     if (runContext.provider === "codex") {
@@ -2041,6 +2055,7 @@ module.exports = {
   shouldAutoCompact,
   effectiveCompactThreshold,
   usageParts,
+  peakContextTokens,
   clampUsageDelta,
   normalizeCodexUsage,
   applyUsageToState,

package/core/single-instance.js

@@ -17,30 +17,46 @@ function pidAlive(pid) {
 
 function acquireSingleInstanceLock({ configDir, name = "bot" }) {
   const lockPath = path.join(configDir, `${name}.lock`);
-  try {
-    const prev = JSON.parse(fs.readFileSync(lockPath, "utf8"));
-    if (prev && prev.pid && prev.pid !== process.pid && pidAlive(prev.pid)) {
-      return { acquired: false, holder: prev, lockPath };
-    }
-    // Missing, corrupt, own-pid, or dead-pid (stale after SIGKILL): claim it.
-  } catch (e) {}
-  fs.writeFileSync(lockPath, JSON.stringify({
+  const payload = JSON.stringify({
     pid: process.pid,
     startedAt: new Date().toISOString(),
     entrypoint: process.argv[1] || "",
-  }));
-  let released = false;
-  const release = () => {
-    if (released) return;
-    released = true;
+  });
+  // O_EXCL creation is the only atomic claim the filesystem offers. The old
+  // read-check-then-write had a TOCTOU hole: two processes booting together
+  // (launchd respawn racing a manual start) could both read "stale" and both
+  // write, each believing it held the lock. Now a stale/corrupt lock is
+  // unlinked and the claim retried; only a wx-create that succeeds counts.
+  for (let attempt = 0; attempt < 5; attempt++) {
     try {
-      const cur = JSON.parse(fs.readFileSync(lockPath, "utf8"));
-      // Never delete a lock a successor already owns.
-      if (cur && cur.pid === process.pid) fs.unlinkSync(lockPath);
-    } catch (e) {}
-  };
-  process.on("exit", release);
-  return { acquired: true, lockPath, release };
+      fs.writeFileSync(lockPath, payload, { flag: "wx" });
+      let released = false;
+      const release = () => {
+        if (released) return;
+        released = true;
+        try {
+          const cur = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+          // Never delete a lock a successor already owns.
+          if (cur && cur.pid === process.pid) fs.unlinkSync(lockPath);
+        } catch (e) {}
+      };
+      process.on("exit", release);
+      return { acquired: true, lockPath, release };
+    } catch (e) {
+      if (e.code !== "EEXIST") throw e;
+    }
+    let prev = null;
+    try { prev = JSON.parse(fs.readFileSync(lockPath, "utf8")); } catch (e) {}
+    if (prev && prev.pid && prev.pid !== process.pid && pidAlive(prev.pid)) {
+      return { acquired: false, holder: prev, lockPath };
+    }
+    // Corrupt, own-pid, or dead-pid (stale after SIGKILL): clear and retry.
+    try { fs.unlinkSync(lockPath); } catch (e) {}
+  }
+  // Five claim attempts lost to contenders — treat it as someone else's lock.
+  let holder = null;
+  try { holder = JSON.parse(fs.readFileSync(lockPath, "utf8")); } catch (e) {}
+  return { acquired: false, holder, lockPath };
 }
 
 module.exports = { acquireSingleInstanceLock, pidAlive };

package/package.json

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

package/test-delivery-contract.js

@@ -84,5 +84,33 @@ const inChat = (adapter, fn) => runInChat({ adapter, channelId: "chan-1", transp
   assert.deepStrictEqual(io.normalizeSendResult(null), { ok: false, messageId: null, editable: false });
   assert.deepStrictEqual(io.normalizeSendResult(99), { ok: true, messageId: "99", editable: true });
 
+  // 7. Telegram splitMessage: messages over the 4096 hard cap must be chunked
+  //    instead of dying with "message is too long" (the silent dream-summary
+  //    failure). Chunks stay under the margin and preserve all content.
+  {
+    const { splitMessage } = require("./channels/telegram/format");
+
+    assert.deepStrictEqual(splitMessage("short message"), ["short message"], "under limit → single chunk untouched");
+    assert.deepStrictEqual(splitMessage(""), [""], "empty stays a single empty chunk");
+
+    const paragraphs = [];
+    for (let i = 0; i < 40; i++) paragraphs.push(`Paragraph ${i} ${"x".repeat(180)}`);
+    const longText = paragraphs.join("\n\n");
+    const chunks = splitMessage(longText);
+    assert.ok(chunks.length > 1, "long multi-paragraph text is chunked");
+    for (const c of chunks) assert.ok(c.length <= 4000, "every chunk fits Telegram's limit with margin");
+    assert.strictEqual(
+      chunks.join("\n\n").replace(/\s+/g, " "),
+      longText.replace(/\s+/g, " "),
+      "no content lost across paragraph-boundary splits",
+    );
+
+    const unbroken = "y".repeat(9500);
+    const hardChunks = splitMessage(unbroken);
+    assert.ok(hardChunks.length >= 3, "giant unbroken string hard-splits");
+    for (const c of hardChunks) assert.ok(c.length <= 4000, "hard-split chunks also fit");
+    assert.strictEqual(hardChunks.join(""), unbroken, "hard split loses nothing");
+  }
+
   console.log("delivery-contract OK");
 })().catch((e) => { console.error(e); process.exit(1); });

package/test-provider-language.js

@@ -32,9 +32,10 @@ assert.doesNotMatch(setup, /Your Claude Code bot is connected|Description=Claude
 
 const pkg = JSON.parse(read("package.json"));
 assert.match(pkg.description, /provider-agnostic coding-agent harness/i);
-// 3.0.1 approved by Sumeet 2026-07-12 ("Push v3.0.1" — streaming restored,
-// /stop queue survival, boot resilience; CHANGELOG documents it as v3.0.1).
-assert.strictEqual(pkg.version, "3.0.1", "release version must remain unchanged without explicit approval");
+// 3.0.3 approved by Sumeet 2026-07-12 ("Yes please" to patching the double-
+// poller bug as v3.0.3 — atomic single-instance lock, 409 handler never exits
+// while holding the lock, throttled owner alert; CHANGELOG documents it).
+assert.strictEqual(pkg.version, "3.0.3", "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-usage-accounting.js

@@ -9,6 +9,7 @@ const {
   normalizeCodexUsage,
   applyUsageToState,
   shouldAutoCompact,
+  peakContextTokens,
 } = require("./core/runner");
 const stateApi = require("./core/state");
 const { normalizeUsageRecord, loadUsageHistory, USAGE_HISTORY_FILE } = require("./core/usage-log");
@@ -152,5 +153,28 @@ assert.strictEqual(shouldAutoCompact(state({
   sessionUsage: { liveContextTokens: 250, lastInputTokens: 250, lastCompactedAt: Date.now() },
 })), true);
 
+// peakContextTokens: the live context number must be the LARGEST single API
+// call, not the turn-cumulative sum (the v3.0.0 347k-vs-160k regression).
+assert.strictEqual(peakContextTokens([
+  { type: "usage", scope: "provider_call", usage: { input_tokens: 1000, cache_read_input_tokens: 150000, cache_creation_input_tokens: 2000 } },
+  { type: "usage", scope: "provider_call", usage: { input_tokens: 500, cache_read_input_tokens: 158000, cache_creation_input_tokens: 1500 } },
+  { type: "usage", scope: "provider_call", usage: { input_tokens: 200, cache_read_input_tokens: 120000 } },
+], "claude"), 160000, "peak is the max single provider_call context");
+assert.strictEqual(peakContextTokens([
+  { type: "usage", scope: "provider_call", usage: { input_tokens: 100, cache_read_input_tokens: 50 } },
+  { type: "usage", scope: "turn", usage: { input_tokens: 999999, cache_read_input_tokens: 999999 } },
+], "claude"), 150, "turn-scope cumulative usage never wins over per-call peak");
+assert.strictEqual(peakContextTokens([], "claude"), null, "no events → null so callers fall back");
+assert.strictEqual(peakContextTokens([
+  { type: "usage", scope: "turn", usage: { input_tokens: 10 } },
+], "claude"), null, "only turn-scope events → null");
+assert.strictEqual(peakContextTokens([
+  { type: "usage", scope: "provider_call", usage: { output_tokens: 40 } },
+], "claude"), null, "zero-context calls → null");
+assert.strictEqual(peakContextTokens(null, "claude"), null, "missing events list tolerated");
+assert.strictEqual(peakContextTokens([
+  { type: "usage", scope: "provider_call", usage: { input_tokens: 70, cached_input_tokens: 30, output_tokens: 5 } },
+], "codex"), 70, "codex context counts input only, matching usageParts");
+
 fs.rmSync(configDir, { recursive: true, force: true });
 console.log("usage accounting OK");