@inetafrica/open-claudia 3.0.5 → 3.0.7

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## v3.0.6 — cache-bust burn is now a one-line query
+
+- **Usage records carry a `coldStart` flag.** The restart→cache-bust burn (each bot restart re-bills the whole accumulated window as cache *writes* instead of ~13×-cheaper cache *reads*) was invisible to every token-count analysis — same token counts, different price class — and took a forensic reconstruction of the 22-day usage history to quantify (~8% of all spend, ~$12/day at its worst). Now the first usage record a process writes for each session is tagged `coldStart: true`: a cold start mid-conversation is the restart fingerprint, so the burn is one jq filter away instead of a modelling exercise. Records already carried `cacheReadTokens`/`cacheCreationTokens`; this adds the missing "was the cache necessarily cold?" dimension.
+- **Agent-space / OpenClaw:** no new deps, no new env, no schema change (additive JSONL field); Docker image builds identically. `usageSessionColdStart` covered by new assertions in `test-usage-accounting.js`.
+
 ## v3.0.5 — the conflict handler owns the poll
 
 - **Hiccup heals no longer fight the 409 backoff.** During a 409 conflict streak the conflict handler pauses polling and retries on its own schedule — but a network hiccup (`ECONNRESET`) arriving mid-streak would schedule its own heal, which called `startPolling` straight back into the conflict and reset the streak clock. This was the live v2.15 burn mechanism: its own ghost long-poll after an ECONNRESET heal raised a 409, the old code exited on any 409, launchd respawned it (~1/hr, 208 lifetime startups), and every restart busted the prompt cache so the next turn re-billed the whole accumulated window uncached. Hiccup handling is now a no-op while a conflict streak is active — the conflict handler owns the poll lifecycle.

package/channels/telegram/adapter.js

@@ -66,7 +66,7 @@ class TelegramAdapter {
     // remaining adapters can boot, and let the independent watchdog recover a
     // poll that never completes and emits no polling_error.
     this._pollStartedAt = Date.now();
-    Promise.resolve(this.bot.startPolling()).catch((error) => {
+    Promise.resolve(this.bot.startPolling({ restart: false })).catch((error) => {
       this._onPollingHiccup(error?.message || "Telegram polling failed to start");
     });
     if (!this._pollWatchdogTimer) {
@@ -87,7 +87,7 @@ 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; }
-    try { await this.bot.stopPolling(); } catch (e) {}
+    try { await this._stopPollingClean("adapter stop"); } catch (e) {}
   }
 
   // A transient network error on the long-poll. The network is almost never
@@ -116,6 +116,22 @@ class TelegramAdapter {
     this._healTimer = setTimeout(() => this._heal(), delay);
   }
 
+  // stopPolling({cancel:true}) in node-telegram-bot-api LEAKS the poll loop:
+  // Bluebird cancellation skips .then/.catch but still runs the chain's
+  // .finally, which sees `_abort === false` and reschedules _polling() — so
+  // every cancel-stop left a zombie loop behind. Each zombie's getUpdates
+  // 409'd the live one, every 409 triggered another cancel-stop/start, and
+  // the pile-up (15+ concurrent Telegram sockets on 2026-07-12) presented as
+  // a phantom "second poller" that only a process restart cleared. A PLAIN
+  // stop sets `_abort = true` before the request settles (no zombie), and
+  // 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) {
+    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))]);
+  }
+
   async _heal() {
     this._healTimer = null;
     // Backstop only: if polling has been unbroken-wedged for 10 minutes, a
@@ -130,15 +146,11 @@ class TelegramAdapter {
       process.exit(1);
     }
     try {
-      try {
-        // `stopPolling()` without cancellation waits for the active getUpdates
-        // request to settle. A half-open socket may never settle, which wedges
-        // this recovery routine itself. Abort the request before restarting.
-        await this.bot.stopPolling({ cancel: true, reason: "stale Telegram long-poll recovery" });
-      } catch (e) {}
-      try { this._agent.destroy(); } catch (e) {} // drop any lingering pooled socket
+      await this._stopPollingClean("stale Telegram long-poll recovery");
       await new Promise((r) => setTimeout(r, 500));
-      await this.bot.startPolling();
+      // restart:false — the lib's restart path is another cancel-stop (zombie
+      // factory); we already stopped cleanly, so only start if truly idle.
+      await this.bot.startPolling({ restart: false });
     } catch (e) {
       return; // restart didn't take — the next hiccup reschedules a heal
     }
@@ -177,11 +189,12 @@ class TelegramAdapter {
     if (this._conflictTimer) return; // a paused retry is already queued
     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(() => {});
+    // Stop hammering now (clean stop: no zombie loop, ghost socket severed);
+    // the timer below dials back in.
+    Promise.resolve(this._stopPollingClean("409 conflict backoff")).catch(() => {});
     this._conflictTimer = setTimeout(async () => {
       this._conflictTimer = null;
-      try { await this.bot.startPolling(); } catch (e) {}
+      try { await this.bot.startPolling({ restart: false }); } catch (e) {}
       // No further 409 for 45s ⇒ the other poller is gone; end the streak.
       this._conflictClearTimer = setTimeout(() => {
         this._conflictClearTimer = null;

package/core/runner.js

@@ -183,6 +183,7 @@ function logTurnUsage(state, usage, costUsd, announce, opts = {}) {
     billedContextTokens: parts.context,
     costUsd: typeof costUsd === "number" ? costUsd : 0,
   };
+  if (typeof opts.coldStart === "boolean") record.coldStart = opts.coldStart;
   if (opts.rawUsage && opts.rawUsage !== usage) {
     const raw = usageParts(opts.rawUsage, backend);
     record.rawInputTokens = raw.input;
@@ -775,6 +776,12 @@ function createRunnerService(dependencies = {}) {
       return immediateFailure(provider, error);
     }
 
+    // Prompt bundle is final: let the service render pre-spawn debug banners
+    // (/recall, /tooltrace) from its recall metadata. Best-effort by contract.
+    if (dependencies.onPromptBundle) {
+      try { await dependencies.onPromptBundle(bundle, runContext); } catch (e) {}
+    }
+
     // Pre-spawn cancel checkpoint: /stop during recall/prompt-build sets a
     // flag instead of killing a process (there is none yet). Honour it here,
     // after the slow prompt build and before anything spawns. Persistence
@@ -1425,6 +1432,18 @@ async function persistForegroundTranscript(result, runContext, state = currentSt
   );
 }
 
+// Sessions this PROCESS has already recorded usage for. The first record per
+// session since boot is a cold start: the prompt cache is necessarily cold, so
+// the whole accumulated window re-bills as cache writes (~13x the read rate).
+// Restart burn is therefore one query away: coldStart=true mid-conversation.
+const warmUsageSessions = new Set();
+function usageSessionColdStart(sessionId, warmSet = warmUsageSessions) {
+  if (!sessionId) return true;
+  if (warmSet.has(sessionId)) return false;
+  warmSet.add(sessionId);
+  return true;
+}
+
 async function persistForegroundUsage(result, runContext, state = currentState(), store = chatContext.getStore()) {
   if (!result.usage) return;
   const previousUsageBySession = structuredClone(state.usageBySession || {});
@@ -1468,6 +1487,7 @@ async function persistForegroundUsage(result, runContext, state = currentState()
         usageScope,
         liveContextTokens,
         rawUsage,
+        coldStart: usageSessionColdStart(usageSessionId),
         strict: true,
       },
     );
@@ -1748,7 +1768,10 @@ function createStreamPreview({ state, store }) {
 function createForegroundService({ state, store, stopTyping, capture, ownsAdmissionLock, persistCapture = true }) {
   const persistEffects = !capture || persistCapture;
   const preview = capture ? null : createStreamPreview({ state, store });
-  return createRunnerService({
+  // Chat-visibility + learning-signal layer (skill/pack/tool announcements,
+  // /recall + /tooltrace banners, recall/tool graph feeding). Foreground only.
+  const observer = capture ? null : require("./turn-observer").createTurnObserver({ state, store });
+  const service = createRunnerService({
     getState: () => state,
     getStore: () => store,
     resolveProvider: resolveForegroundProvider,
@@ -1774,12 +1797,19 @@ function createForegroundService({ state, store, stopTyping, capture, ownsAdmiss
       state.cancelRequested = false;
       return true;
     },
+    onPromptBundle(bundle, runContext) {
+      if (!observer || runContext.purpose !== "foreground") return;
+      observer.onRecallSurfaced(bundle.recallMetadata);
+    },
     onEvent(event, runContext) {
       if (["text_delta", "text_final", "tool_start", "result", "error"].includes(event.type)) state.thinkingPhase = false;
       if (event.type === "tool_start" && ["Shell", "Bash"].includes(event.name)) {
         const command = typeof event.detail === "string" ? event.detail : event.detail?.command;
         if (command) { try { require("./tool-guard").noteRawOp(command); } catch (_) {} }
       }
+      if (observer && event.type === "tool_start" && runContext.purpose === "foreground") {
+        try { observer.onToolStart(event.name, event.detail); } catch (_) {}
+      }
       if (preview && event.type === "text_final" && typeof event.text === "string" && event.text) {
         preview.append(event.text, runContext);
       }
@@ -1800,6 +1830,8 @@ function createForegroundService({ state, store, stopTyping, capture, ownsAdmiss
     },
     idleTimeoutMs: Math.max(60000, parseInt(config.OC_TURN_IDLE_MS || process.env.OC_TURN_IDLE_MS || "", 10) || 10 * 60 * 1000),
   });
+  service.turnObserver = observer;
+  return service;
 }
 
 async function handoffMemoryReview(result, runContext, store) {
@@ -1877,6 +1909,11 @@ async function executeAdmittedRun(runContext, state, store, capture, ownsAdmissi
       finalizeSideChatQueueItem(item, runContext, result);
     }
   }
+  // Feed the recall/tool graphs from what this turn actually did — before the
+  // async reviewer runs, so it sees applied_on already set (no double-announce).
+  if (!capture && service.turnObserver && runContext.purpose === "foreground") {
+    try { service.turnObserver.onTurnSettled(!!result.ok); } catch (e) { /* best-effort */ }
+  }
   if (!internalCapture) await handoffMemoryReview(result, runContext, store);
   if (!internalCapture && state.settings?.backend === runContext.provider && state.settings.budget) {
     state.settings.budget = null;
@@ -2056,6 +2093,7 @@ module.exports = {
   effectiveCompactThreshold,
   usageParts,
   peakContextTokens,
+  usageSessionColdStart,
   clampUsageDelta,
   normalizeCodexUsage,
   applyUsageToState,

package/core/turn-observer.js

@@ -0,0 +1,244 @@
+// Turn observer — the chat-visibility + learning-signal layer for a
+// foreground run, ported from the v2.15 runner (dropped wholesale in the v3
+// rewrite, which left /recall and /tooltrace as dead toggles and the recall +
+// tool graphs starving: read by the discoverer and the dream, written by
+// no-one). One observer is created per foreground run and wired to three
+// moments: prompt-bundle ready (banners), each tool_start event
+// (announcements + activity capture), and turn settled (graph feeding).
+//
+// Everything here is best-effort and owner-only: traces and announcements
+// must never leak to a guarded external speaker, and no failure in this layer
+// may break the turn.
+
+const { chatContext, currentAdapter } = require("./context");
+const { send } = require("./io");
+
+function esc(s) {
+  return String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+function htmlOpts(store) {
+  try {
+    const adapter = chatContext.run(store, () => currentAdapter());
+    return adapter?.type === "telegram" ? { parseMode: "HTML" } : {};
+  } catch (e) { return {}; }
+}
+
+function createTurnObserver({ state, store }) {
+  const settings = state.settings || {};
+  // Fail closed: if the speaker can't be classified, treat them as guarded
+  // and emit nothing — internal activity must never reach a non-owner.
+  let guarded = true;
+  try { guarded = chatContext.run(store, () => require("./relationship").isCurrentSpeakerGuarded()); }
+  catch (e) { guarded = true; }
+
+  const packsLib = require("./packs");
+  const entitiesLib = require("./entities");
+  const toolsLib = require("./tools");
+  const skillsLib = require("./skills");
+
+  // Deduped per turn: a node touched twice announces once.
+  const notified = new Set();
+  const notify = (key, text, opts) => {
+    if (guarded) return;
+    if (notified.has(key)) return;
+    notified.add(key);
+    try { chatContext.run(store, () => send(text, opts).catch(() => {})); }
+    catch (e) { /* announcements are best-effort */ }
+  };
+  const notifyToolTrace = (key, text) => {
+    if (!settings.showToolTrace) return;
+    notify(key, text);
+  };
+
+  // Nodes the agent actually OPENED this turn (📖) — the co-use signal the
+  // recall graph reinforces on: actually-read, not merely surfaced.
+  const openedThisTurn = new Set();
+  // Reusable tools the agent RAN this turn, in order, as { name, shape }.
+  // Order matters (a tool chain is a pipeline) — feeds the follows-graph.
+  const toolRunsThisTurn = [];
+
+  // 🧠 /recall + 🔧 /tooltrace banners, fired once the prompt bundle (and its
+  // recall metadata) exists — before the provider spawns, like v2.15.
+  const onRecallSurfaced = (metadata) => {
+    if (guarded) return;
+    const r = metadata;
+    if (!r || r.omitted) return;
+    const fmt = (arr, icon) => (arr || []).map((x) => (x.why ? `${icon} <b>${esc(x.name)}</b> — ${esc(x.why)}` : `${icon} <b>${esc(x.name)}</b>`));
+    if (settings.showRecall) {
+      const lines = [...fmt(r.packs, "📦"), ...fmt(r.entities, "👤"), ...fmt(r.episodes, "📓")];
+      if (lines.length) notify("banner:recall", `🧠 <b>Recall this turn</b> (${esc(r.engine || "")})\n${lines.join("\n")}`, htmlOpts(store));
+      else if (r.gated) notify("banner:recall", `🧠 <b>Recall</b> (${esc(r.engine || "")}): skipped by pre-gate — trivial turn.`, htmlOpts(store));
+    }
+    if (settings.showToolTrace) {
+      const toolLines = fmt(r.tools, "🔧");
+      if (toolLines.length) notify("banner:tools", `🔧 <b>Tools surfaced this turn</b>\n${toolLines.join("\n")}`, htmlOpts(store));
+    }
+  };
+
+  // Write-side announcements: a Skill invocation, or a Write/Edit landing in
+  // a pack / entity / tool / legacy-skill directory.
+  const noteWriteTool = (toolName, input) => {
+    try {
+      if (toolName === "Skill" && input?.skill) {
+        notify(`use:${input.skill}`, `Using skill: ${input.skill}`);
+        return;
+      }
+      const filePath = input?.file_path || input?.filePath;
+      if ((toolName === "Write" || toolName === "Edit") && filePath) {
+        const packDir = packsLib.packNameFromPath(filePath);
+        if (packDir) {
+          if (packsLib.readPack(packDir)) notify(`pack:${packDir}`, `✏️ Updating my notes on ${packDir}…`);
+          else notify(`pack:${packDir}`, `📦 Starting a new pack: ${packDir} — open-claudia pack show ${packDir} to peek.`);
+          try {
+            packsLib.recordForegroundWrite(packDir, {
+              tool: toolName,
+              oldString: input?.old_string ?? input?.oldString,
+              content: input?.content,
+            });
+          } catch (e) {}
+          return;
+        }
+        const entSlug = entitiesLib.entityNameFromPath(filePath);
+        if (entSlug) {
+          if (entitiesLib.readEntity(entSlug)) notify(`entity:${entSlug}`, `👤 Updating what I know about ${entSlug}…`);
+          else notify(`entity:${entSlug}`, `👤 New entity noted: ${entSlug} — open-claudia entity show ${entSlug} to peek.`);
+          return;
+        }
+        const toolName2 = toolsLib.toolNameFromPath(filePath);
+        if (toolName2) {
+          if (toolsLib.findTool(toolName2)) notifyToolTrace(`tool:${toolName2}`, `🔧 Updating tool: ${toolName2} — open-claudia tool show ${toolName2} to inspect.`);
+          else notifyToolTrace(`tool:${toolName2}`, `🔧 New tool: ${toolName2} — open-claudia tool run ${toolName2} to use it.`);
+          return;
+        }
+        const dir = skillsLib.skillNameFromPath(filePath);
+        if (!dir) return;
+        // The tool_use event precedes the actual write, so existence now
+        // distinguishes a brand-new skill from a patch.
+        if (skillsLib.skillExists(dir)) notify(`write:${dir}`, `Updating skill: ${dir}`);
+        else notify(`write:${dir}`, `Learning new skill: ${dir} — /skills show ${dir} to inspect, /skills remove ${dir} to drop it.`);
+      }
+    } catch (e) { /* announcements are best-effort */ }
+  };
+
+  // Read-side recall from shell: "📖 Recalled my notes on …" fires when the
+  // agent actually pulls a full pack/entity via the CLI (it decided it was
+  // worth reading), not when a headline was auto-injected. Also records tool
+  // runs (🔧 lines gated by /tooltrace) and `tool add` saves.
+  const noteRecallFromShell = (command) => {
+    try {
+      const cmd = String(command || "");
+      if (!cmd.includes("open-claudia")) return;
+      let m;
+      const packRe = /\bpack\s+show\s+["']?([a-z0-9][\w.-]*)/gi;
+      while ((m = packRe.exec(cmd))) {
+        const dir = m[1];
+        const pack = packsLib.readPack(dir);
+        const name = (pack && (pack.name || pack.dir)) || dir;
+        openedThisTurn.add(`pack:${dir}`);
+        notify(`recall:pack:${dir}`, `📖 Recalled my notes on: ${name}`);
+      }
+      const entRe = /\bentity\s+show\s+["']?([a-z0-9][\w.-]*)/gi;
+      while ((m = entRe.exec(cmd))) {
+        const slug = m[1];
+        const ent = entitiesLib.readEntity(slug);
+        const name = (ent && (ent.name || ent.slug)) || slug;
+        openedThisTurn.add(`entity:${slug}`);
+        notify(`recall:entity:${slug}`, `📖 Recalled my notes on: ${name}`);
+      }
+      try {
+        for (const run of require("./tool-graph").parseToolRuns(cmd)) {
+          toolRunsThisTurn.push(run);
+          const verb = (String(run.shape || "").split(/\s+/)[1] || "");
+          let doc = "";
+          try { doc = toolsLib.verbDoc(run.name, verb); } catch (e) {}
+          notifyToolTrace(`ran:${run.name}:${verb}`, `🔧 ${run.shape || run.name}${doc ? ` — ${doc}` : ""}`);
+        }
+      } catch (e) { /* graph optional (old node) */ }
+      // `open-claudia tool add <src> [--name X]` copies an external file in,
+      // so the Write/Edit path above can't see it — detect it here.
+      const addRe = /\btool\s+add\s+(\S+)([^\n;|&]*)/gi;
+      while ((m = addRe.exec(cmd))) {
+        let name = (m[2].match(/--name\s+["']?([^\s"']+)/i) || [])[1];
+        if (!name) name = (String(m[1]).split(/[\\/]/).pop() || "").replace(/\.[^.]+$/, "");
+        name = toolsLib.sanitizeName(name);
+        if (name) notifyToolTrace(`added:${name}`, `🛠️ Saved tool: ${name} — open-claudia tool show ${name} to inspect.`);
+      }
+    } catch (e) { /* announcements are best-effort */ }
+  };
+
+  // The same 📖 signal when the agent opens a note with the Read tool instead
+  // of the CLI. Deduped against the CLI path via the shared notify key.
+  const noteRecallFromReadPath = (filePath) => {
+    try {
+      const node = require("./recall/read-signal").recallNodeFromPath(filePath);
+      if (!node) return;
+      openedThisTurn.add(`${node.kind}:${node.id}`);
+      notify(`recall:${node.kind}:${node.id}`, `📖 Recalled my notes on: ${node.name}`);
+    } catch (e) { /* announcements are best-effort */ }
+  };
+
+  const onToolStart = (name, detail) => {
+    const input = detail && typeof detail === "object" ? detail : {};
+    if (["Bash", "Shell"].includes(name)) {
+      const command = typeof detail === "string" ? detail : input.command;
+      if (command) noteRecallFromShell(command);
+      return;
+    }
+    if (name === "Read") {
+      const filePath = input.file_path || input.filePath;
+      if (filePath) noteRecallFromReadPath(filePath);
+      return;
+    }
+    noteWriteTool(name, input);
+  };
+
+  // End-of-turn graph feeding. Only learn from turns that actually completed:
+  // an errored turn is not evidence a recalled pattern "helped".
+  const onTurnSettled = (succeeded) => {
+    if (!succeeded) return;
+    // Hebbian co-use: nodes actually opened together get their `related`
+    // edges reinforced — co-USE (📖), never co-recall.
+    if (openedThisTurn.size > 0) {
+      try {
+        const recallGraph = require("./recall/graph");
+        if (openedThisTurn.size > 1) recallGraph.reinforceSet([...openedThisTurn]);
+        require("./recall/metrics").logUse([...openedThisTurn]);
+      } catch (e) { /* best-effort */ }
+    }
+    // Directed tool-graph: tools run in succession become follows-edges.
+    if (toolRunsThisTurn.length > 1) {
+      try { require("./tool-graph").reinforceSequence(toolRunsThisTurn.map((t) => t.name)); }
+      catch (e) { /* best-effort */ }
+    }
+    // Tool usage telemetry (runCount + lastUsed sidecar).
+    if (toolRunsThisTurn.length) {
+      try { for (const t of toolRunsThisTurn) toolsLib.recordRun(t.name); }
+      catch (e) { /* best-effort */ }
+    }
+    // Pack↔tool contextual edges: "this tool was used in this topic, as `…`".
+    if (toolRunsThisTurn.length && openedThisTurn.size) {
+      try {
+        const tg = require("./tool-graph");
+        const packDirs = [...openedThisTurn].filter((n) => n.startsWith("pack:")).map((n) => n.slice(5));
+        for (const dir of packDirs) {
+          for (const run of toolRunsThisTurn) tg.recordPackTool(dir, run.name, { command: run.shape, bump: 1 });
+        }
+      } catch (e) { /* best-effort */ }
+    }
+    // Ability transfer: an ability pack opened alongside a project pack was
+    // demonstrably applied there — grow applied_on now, before the reviewer.
+    if (openedThisTurn.size > 1) {
+      try {
+        for (const t of packsLib.recordCoUse([...openedThisTurn])) {
+          notify(`applied:${t.ability}:${t.project}`,
+            `🧩 Reused the "${t.abilityName}" ability on ${t.projectName} — it transfers there now too.`);
+        }
+      } catch (e) { /* best-effort */ }
+    }
+  };
+
+  return { onRecallSurfaced, onToolStart, onTurnSettled };
+}
+
+module.exports = { createTurnObserver };

package/package.json

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

@@ -32,11 +32,12 @@ 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.5 approved by Sumeet 2026-07-12 ("no do it on the latest co0de and push
-// a new version" — 409-conflict/heal/wedge guards so a token fight never
-// restarts the bot and busts the prompt cache; walker stays on per his call
-// that v2's walker was fine and v3's is identical).
-assert.strictEqual(pkg.version, "3.0.5", "release version must remain unchanged without explicit approval");
+// 3.0.7 approved by Sumeet 2026-07-12 ("Do the full fix and I'll upgrade" —
+// plain-stop + agent-destroy kills the zombie poll loop behind the recurring
+// "another poller" 409 storms, and the v2.15 turn-observer trace layer is
+// restored so /tooltrace and /recall work again and the recall/tool graphs
+// are fed).
+assert.strictEqual(pkg.version, "3.0.7", "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

@@ -39,9 +39,16 @@ async function testStartDoesNotWaitForFirstLongPollAndArmsStallWatchdog() {
   }
 }
 
-async function testHealCancelsWedgedLongPollBeforeRestarting() {
+// stopPolling({cancel:true}) leaks the poll loop (Bluebird runs the chain's
+// .finally on cancel with `_abort` still false, rescheduling _polling) — the
+// zombie loops then 409 each other forever (the 15-socket pile-up of
+// 2026-07-12). Recovery must therefore use a PLAIN stop (sets _abort before
+// the request settles) and destroy the agent so a hung half-open getUpdates
+// settles now instead of never.
+async function testHealStopsPlainlyDestroysAgentAndRestartsIdle() {
   const calls = [];
   let stopOptions;
+  let startOptions;
   const adapter = Object.create(TelegramAdapter.prototype);
   adapter._healTimer = null;
   adapter._healthyTimer = null;
@@ -55,7 +62,8 @@ async function testHealCancelsWedgedLongPollBeforeRestarting() {
       stopOptions = options;
       calls.push("stop");
     },
-    async startPolling() {
+    async startPolling(options) {
+      startOptions = options;
       calls.push("start");
     },
   };
@@ -75,17 +83,93 @@ async function testHealCancelsWedgedLongPollBeforeRestarting() {
     global.clearTimeout = realClearTimeout;
   }
 
-  assert.deepStrictEqual(
-    stopOptions,
-    { cancel: true, reason: "stale Telegram long-poll recovery" },
-    "recovery must cancel a wedged getUpdates request rather than await it forever",
-  );
-  assert.deepStrictEqual(calls, ["stop", "destroy", "start"]);
+  assert.strictEqual(stopOptions && stopOptions.cancel, undefined,
+    "recovery must NOT cancel-stop: Bluebird cancellation leaks a zombie poll loop that 409s the next one");
+  assert.strictEqual(stopOptions && stopOptions.reason, "stale Telegram long-poll recovery");
+  assert.deepStrictEqual(calls, ["stop", "destroy", "start"],
+    "recovery must sever the hung socket (agent.destroy) between stop and start");
+  assert.strictEqual(startOptions && startOptions.restart, false,
+    "restart must be idle-only: the lib's restart path is another cancel-stop (zombie factory)");
+}
+
+async function testStopPollingCleanDoesNotHangOnAWedgedStop() {
+  const adapter = Object.create(TelegramAdapter.prototype);
+  adapter._agent = { destroy() {} };
+  adapter.bot = {
+    stopPolling() { return new Promise(() => {}); }, // never settles
+  };
+
+  const realSetTimeout = global.setTimeout;
+  global.setTimeout = (fn, ms) => {
+    if (ms === 5000) fn(); // the cap fires
+    return { ms };
+  };
+  try {
+    const outcome = await Promise.race([
+      adapter._stopPollingClean("test").then(() => "returned"),
+      new Promise((resolve) => realSetTimeout(() => resolve("hung"), 25)),
+    ]);
+    assert.strictEqual(outcome, "returned", "_stopPollingClean must cap the wait when the stop promise never settles");
+  } finally {
+    global.setTimeout = realSetTimeout;
+  }
+}
+
+async function test409ConflictSeversGhostSocketAndRestartsIdle() {
+  const calls = [];
+  let stopOptions;
+  let startOptions;
+  const adapter = Object.create(TelegramAdapter.prototype);
+  adapter.ownerChatId = null;
+  adapter._conflictSince = 0;
+  adapter._conflictTimer = null;
+  adapter._conflictClearTimer = null;
+  adapter._conflictAlertAt = 0;
+  adapter._conflictAlerted = false;
+  adapter._agent = {
+    destroy() { calls.push("destroy"); },
+  };
+  adapter.bot = {
+    async stopPolling(options) {
+      stopOptions = options;
+      calls.push("stop");
+    },
+    async startPolling(options) {
+      startOptions = options;
+      calls.push("start");
+    },
+  };
+
+  const timers = [];
+  const realSetTimeout = global.setTimeout;
+  const realClearTimeout = global.clearTimeout;
+  global.setTimeout = (fn, ms) => { timers.push({ fn, ms }); return { ms }; };
+  global.clearTimeout = () => {};
+
+  try {
+    adapter._on409Conflict();
+    // Let the fire-and-forget clean stop settle.
+    await new Promise((resolve) => realSetTimeout(resolve, 5));
+    assert.strictEqual(stopOptions && stopOptions.cancel, undefined,
+      "409 backoff must NOT cancel-stop (zombie loop leak)");
+    assert.ok(calls.includes("destroy"),
+      "409 backoff must destroy the agent to sever the ghost getUpdates holding the token");
+    const retry = timers.find((t) => t.ms === 15000);
+    assert.ok(retry, "409 backoff must queue a paused retry");
+    await retry.fn();
+    assert.strictEqual(startOptions && startOptions.restart, false,
+      "409 retry must restart idle-only, never through the lib's cancel-restart path");
+  } finally {
+    global.setTimeout = realSetTimeout;
+    global.clearTimeout = realClearTimeout;
+  }
 }
 
 (async () => {
   await testStartDoesNotWaitForFirstLongPollAndArmsStallWatchdog();
-  await testHealCancelsWedgedLongPollBeforeRestarting();
+  await testHealStopsPlainlyDestroysAgentAndRestartsIdle();
+  await testStopPollingCleanDoesNotHangOnAWedgedStop();
+  await test409ConflictSeversGhostSocketAndRestartsIdle();
   console.log("telegram poll recovery OK");
 })().catch((err) => {
   console.error(err.stack || err);

package/test-usage-accounting.js

@@ -10,6 +10,7 @@ const {
   applyUsageToState,
   shouldAutoCompact,
   peakContextTokens,
+  usageSessionColdStart,
 } = require("./core/runner");
 const stateApi = require("./core/state");
 const { normalizeUsageRecord, loadUsageHistory, USAGE_HISTORY_FILE } = require("./core/usage-log");
@@ -176,5 +177,17 @@ 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");
 
+// usageSessionColdStart: the first usage record per session since process boot
+// is a cold start (prompt cache empty — the restart-burn fingerprint); every
+// later record for that session in the same process is warm.
+{
+  const warm = new Set();
+  assert.strictEqual(usageSessionColdStart("sess-a", warm), true, "first record for a session is cold");
+  assert.strictEqual(usageSessionColdStart("sess-a", warm), false, "second record for the same session is warm");
+  assert.strictEqual(usageSessionColdStart("sess-b", warm), true, "a different session is cold on its first record");
+  assert.strictEqual(usageSessionColdStart(null, warm), true, "no session id → always treated cold");
+  assert.strictEqual(usageSessionColdStart(null, warm), true, "null never warms");
+}
+
 fs.rmSync(configDir, { recursive: true, force: true });
 console.log("usage accounting OK");