@inetafrica/open-claudia 2.6.54 → 2.6.56

package/.env.example

@@ -21,6 +21,9 @@ CLAUDE_MODEL=claude-fable-5
 CURSOR_PATH=
 CODEX_PATH=
 AUTO_COMPACT_TOKENS=280000
+# Inactivity watchdog: kill a heavy turn's child if it emits no output for
+# this many ms, so a hung tool call can't wedge the bot. Default 600000 (10min).
+OC_TURN_IDLE_MS=600000
 USAGE_ALERT_CONTEXT_TOKENS=120000
 USAGE_ALERT_RATE_MULTIPLIER=1.75
 USAGE_ALERT_BASELINE_TURNS=20

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## v2.6.56
+- **Stop a single hung child from wedging the whole bot.** Agent mode is single-flight: a heavy turn spawns one child and sets a global `runningProcess` flag; while it's set, every new message is demoted to a lightweight side-chat instead of a full turn. That flag is *only* ever cleared by the child's `close`/`error` events — so a child that hangs (a wedged tool call that never returns) pins it forever. That's exactly what happened: one turn went silent, its child never exited, and from then on the bot stayed alive (health checks passed) but answered nothing of substance — every later message fell through to a side-chat that also couldn't make progress. The fix is an **inactivity watchdog** in `runClaude` (`bot-agent.js`): track `lastActivity`, bumped on every `stdout`/`stderr` chunk from the child, and inside the existing progress-update loop (which already ticks every 2–5s while a task runs) kill the child if it produces no output for longer than the idle limit — SIGTERM to the process group, SIGKILL 3s later, plus a 10s failsafe that force-clears the flag if `close` somehow never fires. The watchdog short-circuits the close handler so the user gets one clear "task stalled — stopped it, I'm responsive again, send /continue" message instead of a confusing "(no output)". Default idle limit is 10 minutes, tunable via `OC_TURN_IDLE_MS`. Deliberately scoped to the wedge only — the v2.6.55 polling fix is healthy and untouched.
+
+## v2.6.55
+- **Make fixing a tool as cheap as creating one.** The tool subsystem was structurally tilted toward sprawl: creating a tool was a trusting one-liner with no validation, while *fixing* one had no verb at all — so the path of least resistance was always another near-duplicate. This release closes that gap from both ends. **A first-class fix verb:** `open-claudia tool set <name> [--desc|--pack|--requires|--usage]` rewrites a tool's header metadata in place (new `updateToolHeader()` in `core/tools.js`) — it refreshes only the recognised field lines, preserving the marker, any hand-written comments, and the immutable `createdAt`, and never touches the body. `open-claudia tool edit <name>` prints the source path (stdout) so the agent's Edit/Write or the user's `$EDITOR` can open it directly, with the metadata-only hint on stderr. **An add-time safety net** (all advisory, never blocking — a tool the agent just wrote is usually right): `tool add`/`tool set` now lint the source and surface (1) hardcoded secrets — `sk-ant-`/`sk-proj-`/`sk-`/`AKIA`/`gh*_`/`xox*`/PEM/inline-Bearer literals that should be `$KEYRING` refs, mirroring the redactor; (2) requires/keyring mismatches — keyring keys the script reads but `--requires` omits (with a ready-to-paste `tool set` fix), and declared keys it never reads; (3) syntax errors via the script's own interpreter (`bash -n` / `node --check` / `py_compile`, silent when the interpreter or type is unknown — never cries wolf); and (4) a dangling `--pack` link to a pack that doesn't exist. **Immutable creation telemetry:** the `.usage.json` sidecar now stamps `createdAt` once at add-time (surfaced on every tool record); the nightly dream's "cold since creation" check ages by this stamp instead of file mtime, so a body edit can no longer reset a never-run tool's staleness clock (falls back to mtime for tools created before the stamp existed). Extends `test-tools.js` (createdAt immutability, `envRefsIn`, `lintToolSource`, `checkSyntax`, `updateToolHeader`).
+- **Stop the phantom-outage restart storm — just keep polling.** The Telegram adapter was killing the bot over network blips that weren't real. A side-by-side network monitor (probing 1.1.1.1 *and* api.telegram.org every 60s) showed the connection healthy throughout, yet `bot.log` had logged 20k+ `EFATAL: read ETIMEDOUT` → "Network lost" events: the long-poll's pooled keep-alive socket goes stale on a macOS sleep/wake or an idle-NAT eviction, and every reused poll then times out instantly. The old handler treated *any* such timeout as a lost network — loudly stopping/restarting polling and, after 6 quick attempts (a sleep/wake error burst exhausts those in seconds), calling `process.exit(1)` for launchd to relaunch. That voluntary suicide *was* the "why does it keep restarting" the bot kept doing. Three changes in `channels/telegram/adapter.js`: (1) **fresh socket per poll** (`keepAlive:false`) so there's no pooled socket to go stale — the root of the ETIMEDOUT storm; (2) **gentle, throttled recovery** — a transient timeout no longer screams or tears down on the first hit (with keep-alive off the next poll self-heals on a new connection); it logs at most once a minute and only actively restarts polling if errors persist; (3) **never exit over a network blip** — only a `409 Conflict` (a second poller on the same token) exits immediately; a genuinely wedged loop now has to fail unbroken for a full 10 minutes before a clean relaunch, versus the old ~90s hair-trigger. The diagnostic `netmon.sh` that proved the network was fine stays running.
+
 ## v2.6.54
 - **Tools as first-class discoverer nodes.** Reusable tools now go through the same recall pipeline as packs and entities — seed → activate → judge → render — instead of being dumped wholesale into every prompt. Until now `buildToolIndexBlock` listed *all* ~40 tools on every turn; that flat block is gone. In its place, the discoverer (`core/recall/discoverer.js`) seeds tool candidates from a new in-memory `matchTools()` (lexical scoring over name/description = strong, requires/pack/source = weak; `core/tools.js`), activates the tools belonging to any pack already in the candidate set (read from the pack↔tool graph + tool `pack:` headers — the latency-sensitive recall `expand()` stays pack/entity-only, zero regression risk), and lets the haiku walker judge them with a "keep a tool only if running it would actually help" instruction. Survivors render into a focused **"Tools that may help here"** block; the system prompt now just states the count and points to `tool search`/`tool list` for the rest. `matchTools` is in-memory (works on every node version, unlike the SQLite graphs).
 - **`/tooltrace` toggle (default off).** Mirrors `/recall`. When on, posts short 🔧 lines around each reply: which tools were **surfaced** for the turn, which were **run**, and any **created/updated** — so you can watch the tool layer work. All three signals are now gated behind this one toggle (`settings.showToolTrace`); the run/created/updated banners were removed from the always-on path and the surfaced list was split out of the 🧠 `/recall` banner, so the two toggles are cleanly independent.

package/bin/cli.js

@@ -370,7 +370,7 @@ Memory tools:
   open-claudia transcript-window <pattern>   Search project transcript, show hits with context
                                              (alias: tw; --help for options)
   open-claudia pack list|show|match|archive|restore|archived  Context packs: living topic docs (skills + memory)
-  open-claudia tool list|search|show|add|run|remove Reusable tools: executable scripts the agent saves & re-runs (keyring preauth)
+  open-claudia tool list|search|show|add|set|edit|run|remove Reusable tools: executable scripts the agent saves & re-runs (keyring preauth)
   open-claudia entity list|show|match|note   Entity notes: people/places/projects memory
   open-claudia lessons list|add|remove|show  Always-loaded learned rules (cross-cutting, promoted after a miss)
   open-claudia ideas list|add|remove|show    Self-improvement backlog (captured by the nightly dream)

package/bin/tool.js

@@ -7,10 +7,18 @@
 //   open-claudia tool show <name>                — full docs, path, keyring status
 //   open-claudia tool add <path> [--name n]      — register a script as a tool
 //       [--pack <dir>] [--desc "..."] [--requires "k1,k2"] [--usage "..."]
+//   open-claudia tool set <name> [--desc ...]    — fix a tool's metadata in place
+//       [--pack <dir>] [--requires "k1,k2"] [--usage "..."]
+//   open-claudia tool edit <name>                — print the file path to open & edit
 //   open-claudia tool run <name> [args...]       — run it with keyring pre-loaded
 //   open-claudia tool remove <name>              — delete one
 //   open-claudia tool path                       — print the tools directory
 //
+// Fix before fork: when a tool is wrong, prefer `tool set` (metadata) or `tool
+// edit` (open the file) over adding a near-duplicate. `add` lints the source on
+// save — flags hardcoded secrets, requires/keyring mismatches, syntax errors,
+// and dangling pack links — all advisory, never blocking.
+//
 // Credentials: a tool runs with the operational keyring merged into its env, so
 // reference creds as $NAME inside the script. `open-claudia keyring list` shows
 // what's available; never hardcode secrets in a tool.
@@ -34,6 +42,48 @@ function parseFlags(argv) {
   return { positional, flags };
 }
 
+// Advisory safety report for a freshly-added or just-edited tool. Never blocks —
+// a tool the agent just wrote is usually right; we surface risks and let the
+// human/agent decide. Covers: hardcoded secrets, requires/keyring mismatch,
+// syntax errors (when we have the interpreter), and dangling pack links.
+function reportSafety(t) {
+  // Hardcoded secrets + requires/keyring reconciliation.
+  try {
+    const { secrets, undeclared, unused } = tools.lintToolSource(t.content, { requires: t.requires });
+    if (secrets.length) {
+      console.log(`\n⚠ Hardcoded secret(s) detected: ${secrets.join(", ")}.`);
+      console.log("  Replace with a $KEYRING_VAR reference — keyring perms + log redaction only protect creds stored there.");
+    }
+    if (undeclared.length) {
+      console.log(`\n⚠ Reads keyring key(s) not in --requires: ${undeclared.join(", ")}.`);
+      console.log(`  Add them so a missing key is caught up-front: open-claudia tool set ${t.name} --requires "${[...t.requires, ...undeclared].join(",")}"`);
+    }
+    if (unused.length) {
+      console.log(`\nNote: --requires lists key(s) the script never reads: ${unused.join(", ")}.`);
+    }
+  } catch (e) { /* lint optional */ }
+
+  // Syntax check (only when we recognise + have the interpreter).
+  try {
+    const syn = tools.checkSyntax(t.file, t.content);
+    if (syn && !syn.ok) {
+      console.log(`\n⚠ Syntax check failed:\n${syn.error.split("\n").map((l) => "  " + l).join("\n")}`);
+      console.log(`  Fix it: open-claudia tool edit ${t.name}`);
+    }
+  } catch (e) { /* syntax check optional */ }
+
+  // Dangling pack link.
+  if (t.pack) {
+    try {
+      const pack = require("../core/packs").readPack(t.pack);
+      if (!pack) {
+        console.log(`\n⚠ Linked skill pack "${t.pack}" doesn't exist.`);
+        console.log(`  Create it (open-claudia pack ...) or relink: open-claudia tool set ${t.name} --pack <existing-dir>`);
+      }
+    } catch (e) { /* packs optional */ }
+  }
+}
+
 function run(args) {
   const cmd = (args[0] || "list").toLowerCase();
   const rest = args.slice(1);
@@ -132,6 +182,9 @@ function run(args) {
           const missing = tools.missingRequires(t);
           if (missing.length) console.log(`Note: missing keyring keys it needs: ${missing.join(", ")}`);
         }
+        // Add-time safety net (advisory): secrets, requires/keyring mismatch,
+        // syntax, dangling pack link.
+        reportSafety(t);
         // Similarity guard (warn, don't block): if existing tools already cover
         // this, prefer extending one with a subcommand over a near-duplicate.
         try {
@@ -149,6 +202,50 @@ function run(args) {
       break;
     }
 
+    case "set":
+    case "fix": {
+      const { positional, flags } = parseFlags(rest);
+      const name = positional[0];
+      if (!name) {
+        console.error('Usage: tool set <name> [--desc "..."] [--pack dir] [--requires "k1,k2"] [--usage "..."]');
+        process.exitCode = 1; return;
+      }
+      if (!tools.findTool(name)) {
+        console.error(`No tool named "${name}". Run: open-claudia tool list`); process.exitCode = 1; return;
+      }
+      const patch = {};
+      if (typeof flags.desc === "string") patch.description = flags.desc;
+      else if (typeof flags.description === "string") patch.description = flags.description;
+      if (typeof flags.pack === "string") patch.pack = flags.pack;
+      if (typeof flags.requires === "string") patch.requires = flags.requires.split(/[,\s]+/).filter(Boolean);
+      if (typeof flags.usage === "string") patch.usage = flags.usage;
+      if (Object.keys(patch).length === 0) {
+        console.error('Nothing to set. Pass at least one of --desc / --pack / --requires / --usage. Body edits: open-claudia tool edit ' + name);
+        process.exitCode = 1; return;
+      }
+      const updated = tools.updateToolHeader(name, patch);
+      if (!updated) { console.error(`Could not update "${name}".`); process.exitCode = 1; return; }
+      console.log(`Updated tool "${updated.name}".`);
+      console.log(`  Description: ${updated.description || "(none)"}`);
+      if (updated.pack) console.log(`  Skill pack:  ${updated.pack}`);
+      if (updated.requires.length) console.log(`  Requires:    ${updated.requires.join(", ")}`);
+      if (updated.usage) console.log(`  Usage:       ${updated.usage}`);
+      reportSafety(updated);
+      break;
+    }
+
+    case "edit": {
+      const name = rest[0];
+      if (!name) { console.error("Usage: tool edit <name>"); process.exitCode = 1; return; }
+      const t = tools.findTool(name);
+      if (!t) { console.error(`No tool named "${name}". Run: open-claudia tool list`); process.exitCode = 1; return; }
+      // Body edits are an Edit/Write job — print the path so the agent (or the
+      // user's $EDITOR) can open it directly. Metadata fixes: open-claudia tool set.
+      console.log(t.file);
+      console.error(`Open and edit the source above. Header/metadata only: open-claudia tool set ${t.name} [flags]`);
+      break;
+    }
+
     case "run":
     case "exec": {
       const name = rest[0];
@@ -180,7 +277,7 @@ function run(args) {
       break;
 
     default:
-      console.log('Usage: open-claudia tool [list | search <query> | show <name> | add <path> [flags] | run <name> [args] | remove <name> | path]');
+      console.log('Usage: open-claudia tool [list | search <query> | show <name> | add <path> [flags] | set <name> [flags] | edit <name> | run <name> [args] | remove <name> | path]');
   }
 }
 

package/bot-agent.js

@@ -1259,6 +1259,16 @@ async function runClaude(prompt, cwd, replyToMsgId, opts = {}) {
   const startTime = Date.now();
   let longRunningNotified = false;
 
+  // Inactivity watchdog. The single-flight `runningProcess` flag is only
+  // cleared by this child's close/error events, so a child that hangs
+  // (e.g. a wedged tool call) pins the flag forever and demotes every later
+  // message to a side-chat. Track the last time the child produced output;
+  // if it goes silent past the idle limit, kill it so the flag clears and
+  // the bot responds again. Tune with OC_TURN_IDLE_MS (default 10min).
+  const idleLimitMs = Math.max(60000, parseInt(process.env.OC_TURN_IDLE_MS, 10) || 10 * 60 * 1000);
+  let lastActivity = Date.now();
+  let watchdogTripped = false;
+
   let lastUpdate = "";
   // Adaptive update interval: 2s for first 2min, then 5s to avoid rate limits
   const scheduleUpdate = () => {
@@ -1268,6 +1278,29 @@ async function runClaude(prompt, cwd, replyToMsgId, opts = {}) {
   };
   const updateProgress = async () => {
     const elapsed = Math.floor((Date.now() - startTime) / 1000);
+    // Inactivity watchdog: kill a child that has gone silent past the idle limit.
+    if (!watchdogTripped && runningProcess === proc && Date.now() - lastActivity > idleLimitMs) {
+      watchdogTripped = true;
+      const idleMin = Math.floor((Date.now() - lastActivity) / 60000);
+      const pid = proc.pid;
+      console.error(`[watchdog] child pid ${pid} idle ${idleMin}min (limit ${Math.floor(idleLimitMs / 60000)}min) — killing`);
+      try { process.kill(-pid, "SIGTERM"); } catch (e) {
+        try { proc.kill("SIGTERM"); } catch (e2) {}
+      }
+      setTimeout(() => { try { process.kill(-pid, "SIGKILL"); } catch (e) {} }, 3000);
+      // Failsafe: if close never fires, force-clear so the bot recovers anyway.
+      setTimeout(() => {
+        if (runningProcess === proc) {
+          runningProcess = null; runningProcessPrompt = null;
+          clearTimeout(streamInterval); streamInterval = null;
+        }
+      }, 10000);
+      try {
+        await send(`Task stalled — no activity for ${idleMin}min, so I stopped it and I'm responsive again. Send /continue to resume, or just re-ask.`);
+      } catch (e) {}
+      statusMessageId = null;
+      return; // stop the progress loop; close (or failsafe) clears state
+    }
     try {
       bot.sendChatAction(CHAT_ID, "typing").catch(() => {});
       const display = formatProgress(assistantText, toolUses, currentTool, elapsed, currentToolDetail);
@@ -1292,6 +1325,7 @@ async function runClaude(prompt, cwd, replyToMsgId, opts = {}) {
   scheduleUpdate();
 
   proc.stdout.on("data", (data) => {
+    lastActivity = Date.now();
     streamBuffer += data.toString();
     const events = parseStreamEvents(streamBuffer);
     const lastNewline = streamBuffer.lastIndexOf("\n");
@@ -1367,6 +1401,7 @@ async function runClaude(prompt, cwd, replyToMsgId, opts = {}) {
 
   let stderrBuffer = "";
   proc.stderr.on("data", (d) => {
+    lastActivity = Date.now();
     const chunk = d.toString();
     stderrBuffer += chunk;
     console.error("STDERR:", redactSensitive(chunk));
@@ -1375,6 +1410,13 @@ async function runClaude(prompt, cwd, replyToMsgId, opts = {}) {
   proc.on("close", async (code) => {
     runningProcess = null; runningProcessPrompt = null;
     clearTimeout(streamInterval); streamInterval = null;
+    if (watchdogTripped) {
+      // The inactivity watchdog already notified the user and killed the
+      // child; don't also deliver partial / "(no output)" text.
+      statusMessageId = null;
+      if (settings.budget) settings.budget = null;
+      return;
+    }
     if (settings.backend !== "cursor" && isClaudeAuthErrorText(stderrBuffer)) {
       await send(claudeAuthRecoveryMessage(stderrBuffer.trim().slice(-800)), { replyTo: replyToMsgId });
       return;

package/channels/telegram/adapter.js

@@ -19,16 +19,23 @@ class TelegramAdapter {
     this.token = token;
     this.ownerChatId = ownerChatId;
     this.chatIds = chatIds || [];
-    // Own the HTTP(S) agent so we can drop dead keep-alive sockets on reconnect.
-    this._agent = new https.Agent({ keepAlive: true });
+    // Dial a fresh socket per poll (keepAlive:false). The long-poll sits idle up
+    // to 30s; with a *pooled* keep-alive socket, a macOS sleep/wake or an idle-NAT
+    // eviction silently kills that one socket and every later poll reuses it and
+    // ETIMEDOUTs — forever. A new connection each poll (~every 30s, trivial for
+    // one bot) sidesteps the stale-socket trap that drove the old restart storm.
+    // We still own the agent so a heal can destroy any lingering socket.
+    this._agent = new https.Agent({ keepAlive: false });
     this.bot = new TelegramBot(token, {
       polling: { autoStart: false, params: { timeout: 30 } },
       request: { agent: this._agent },
     });
     this._listeners = { message: new Set(), action: new Set() };
-    this._reconnectTimer = null;
-    this._recoveryTimer = null;
-    this._reconnectAttempts = 0;
+    this._healTimer = null;      // one active recovery in flight at a time
+    this._healthyTimer = null;   // fires once polling's been quiet long enough
+    this._wedgedSince = 0;       // start of the current unrecovered error streak
+    this._lastHiccupLog = 0;     // throttle the transient-error log (1/min)
+    this._healBackoff = 0;       // grows per consecutive heal, capped
     this._wireInbound();
   }
 
@@ -50,60 +57,73 @@ class TelegramAdapter {
   }
 
   async stop() {
-    if (this._reconnectTimer) { clearTimeout(this._reconnectTimer); this._reconnectTimer = null; }
-    if (this._recoveryTimer) { clearTimeout(this._recoveryTimer); this._recoveryTimer = null; }
+    if (this._healTimer) { clearTimeout(this._healTimer); this._healTimer = null; }
+    if (this._healthyTimer) { clearTimeout(this._healthyTimer); this._healthyTimer = null; }
     try { await this.bot.stopPolling(); } catch (e) {}
   }
 
-  // Recover from a wedged poll loop. The library reuses one keep-alive socket;
-  // after a sleep/wake or network blip that socket dies and every poll then
-  // ETIMEDOUTs forever — restarting polling alone reuses the same dead socket.
-  // So we destroy the agent (forcing a fresh connection), back off, and if we
-  // still can't recover after several tries we exit so launchd (KeepAlive)
-  // relaunches a fully clean process.
-  _scheduleReconnect() {
-    if (this._reconnectTimer) return; // one cycle in flight; swallow the flood
-    if (this._recoveryTimer) { clearTimeout(this._recoveryTimer); this._recoveryTimer = null; }
-    this._reconnectAttempts += 1;
-    const MAX = 6;
-    if (this._reconnectAttempts > MAX) {
-      console.error(`Polling unrecoverable after ${MAX} attempts — exiting for supervisor restart.`);
+  // A transient network error on the long-poll. The network is almost never
+  // actually down — netmon shows it healthy while these fire — it's a single
+  // stale socket. So we DON'T scream "Network lost" and tear everything down on
+  // the first timeout the way the old code did: with keep-alive off the next
+  // poll already dials fresh and self-heals. We log at most once a minute, only
+  // actively recover if errors persist, and NEVER exit over a network blip — the
+  // 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) {
+    const now = Date.now();
+    if (!this._wedgedSince) this._wedgedSince = now;
+    if (now - this._lastHiccupLog > 60000) {
+      this._lastHiccupLog = now;
+      console.log(`Polling hiccup (${msg}) — retrying on a fresh connection.`);
+    }
+    if (this._healTimer) return; // a heal is already scheduled; let it run
+    this._healBackoff = Math.min(this._healBackoff + 1, 5);
+    const delay = Math.min(15000, 500 * 2 ** this._healBackoff); // 1s … 15s
+    this._healTimer = setTimeout(() => this._heal(), delay);
+  }
+
+  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 && Date.now() - this._wedgedSince > 600000) {
+      console.error("Polling wedged >10min — exiting for a clean restart.");
       process.exit(1);
     }
-    const delay = Math.min(30000, 1000 * 2 ** this._reconnectAttempts); // 2s,4s,8s,16s,30s,30s
-    console.log(`Network lost. Reconnecting in ${Math.round(delay / 1000)}s (attempt ${this._reconnectAttempts}/${MAX})...`);
-    this._reconnectTimer = setTimeout(async () => {
-      this._reconnectTimer = null;
-      try {
-        try { await this.bot.stopPolling(); } catch (e) {}
-        try { this._agent.destroy(); } catch (e) {} // drop the dead pooled socket
-        await new Promise((r) => setTimeout(r, 1000));
-        await this.bot.startPolling();
-        console.log("Polling restarted.");
-        // No fresh error within 30s ⇒ genuinely recovered; reset the counter.
-        this._recoveryTimer = setTimeout(() => {
-          this._recoveryTimer = null;
-          if (this._reconnectAttempts) console.log("Connection healthy again.");
-          this._reconnectAttempts = 0;
-        }, 30000);
-      } catch (e) {
-        console.error("Reconnect attempt failed:", e.message);
-        this._scheduleReconnect(); // back off and retry; don't die on first miss
-      }
-    }, delay);
+    try {
+      try { await this.bot.stopPolling(); } catch (e) {}
+      try { this._agent.destroy(); } catch (e) {} // drop any lingering pooled socket
+      await new Promise((r) => setTimeout(r, 500));
+      await this.bot.startPolling();
+    } catch (e) {
+      return; // restart didn't take — the next hiccup reschedules a heal
+    }
+    // Quiet for 30s after a restart ⇒ genuinely recovered.
+    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;
+    }, 30000);
   }
 
   _wireInbound() {
     this.bot.on("polling_error", (err) => {
       const msg = err.message || "";
-      console.error("Polling error:", msg);
       if (msg.includes("409 Conflict")) {
+        // Two pollers can't share one token — this one must bow out.
         console.error("Another instance is polling. Exiting.");
         process.exit(1);
       }
       if (/ETIMEDOUT|ECONNRESET|ENOTFOUND|ENETUNREACH|EAI_AGAIN|EFATAL|socket hang up/i.test(msg)) {
-        this._scheduleReconnect();
+        this._onPollingHiccup(msg); // transient — heal quietly, never exit
+        return;
       }
+      console.error("Polling error:", msg); // unexpected — surface, keep polling
     });
 
     this.bot.on("message", (msg) => {

package/core/dream.js

@@ -844,11 +844,15 @@ async function runDream({ trigger = "manual" } = {}) {
         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.`);
       }
       // Zero-run tools: created but never run and gone cold. Telemetry runCount
-      // is authoritative; file mtime stands in for "how long ago". Flag only —
-      // a never-used tool may still be worth keeping, so the user decides.
+      // is authoritative; createdAt measures "how long since it was made" (a body
+      // edit bumps mtime and would reset the clock, so prefer the immutable stamp
+      // and fall back to mtime only for tools added before createdAt existed).
+      // Flag only — a never-used tool may still be worth keeping, user decides.
       const STALE_DAYS = Number(process.env.TOOL_STALE_DAYS || 30);
       const cutoff = Date.now() - STALE_DAYS * 86400000;
       const coldUnused = allTools.filter((t) => !(t.runCount > 0) && !t.lastUsed).filter((t) => {
+        const born = t.createdAt ? Date.parse(t.createdAt) : NaN;
+        if (!Number.isNaN(born)) return born < cutoff;
         try { return fs.statSync(t.file).mtimeMs < cutoff; } catch (e) { return false; }
       });
       if (coldUnused.length) {

package/core/tools.js

@@ -66,6 +66,20 @@ function recordRun(name) {
   writeUsage(u);
 }
 
+// Stamp an immutable createdAt the first time a tool is registered. Kept in the
+// sidecar (not the header) so editing the file never disturbs it — unlike file
+// mtime, which resets on every edit and would make an edited-but-never-run tool
+// look freshly minted. The dream's zero-run hygiene ages tools from this.
+function recordCreate(name) {
+  const n = sanitizeName(name);
+  if (!n) return;
+  const u = readUsage();
+  const cur = u[n] || { runCount: 0, lastUsed: "" };
+  if (!cur.createdAt) cur.createdAt = new Date().toISOString();
+  u[n] = cur;
+  writeUsage(u);
+}
+
 // ── Lexical matching (in-memory) ─────────────────────────────────────────────
 // Tools are few and short, so we score in memory rather than standing up a third
 // FTS index — and unlike the recall/tool graphs this then works on every node
@@ -184,6 +198,7 @@ function readTool(name, usageMap) {
     file,
     executable: stat ? !!(stat.mode & 0o111) : false,
     updatedAt: stat ? stat.mtime.toISOString() : "",
+    createdAt: usage.createdAt || "",
     runCount: usage.runCount || 0,
     lastUsed: usage.lastUsed || "",
     content,
@@ -229,6 +244,82 @@ function commentPrefixFor(content, srcPath) {
   return "#";
 }
 
+// ── Creation-time guards ─────────────────────────────────────────────────────
+// Cheap static checks surfaced when a tool is registered, so a broken, insecure,
+// or mis-declared tool is caught at `tool add` time instead of at first run. All
+// advisory — they shape warnings, they never block the save (a tool the agent
+// just wrote is usually right; we surface the risk and let the human/agent act).
+
+// Hardcoded-secret shapes (mirrors the redactor, plus a few common providers). A
+// match means a literal secret is baked into the file — it should be a $KEYRING
+// reference instead, so the keyring's perms + log redaction actually protect it.
+const SECRET_PATTERNS = [
+  [/sk-ant-[A-Za-z0-9._-]{8,}/, "Anthropic key (sk-ant-…)"],
+  [/sk-proj-[A-Za-z0-9._-]{8,}/, "OpenAI project key (sk-proj-…)"],
+  [/\bsk-[A-Za-z0-9]{20,}/, "OpenAI-style key (sk-…)"],
+  [/\bAKIA[0-9A-Z]{16}\b/, "AWS access key id (AKIA…)"],
+  [/\bgh[pousr]_[A-Za-z0-9]{20,}/, "GitHub token (ghp_…)"],
+  [/\bxox[baprs]-[A-Za-z0-9-]{10,}/, "Slack token (xox…)"],
+  [/-----BEGIN [A-Z ]*PRIVATE KEY-----/, "private key block"],
+  [/(?:Bearer\s+)[A-Za-z0-9._=-]{20,}/, "inline Bearer token"],
+];
+
+// Names a script reads from the environment: $VAR, ${VAR}, process.env.VAR,
+// process.env["VAR"], os.environ["VAR"], os.getenv("VAR"). Used to reconcile a
+// tool's actual credential use against its declared --requires.
+function envRefsIn(content) {
+  const refs = new Set();
+  const text = String(content || "");
+  let m;
+  const res = [
+    /\$\{?([A-Za-z_][A-Za-z0-9_]*)\}?/g,
+    /process\.env\.([A-Za-z_][A-Za-z0-9_]*)/g,
+    /process\.env\[\s*["']([A-Za-z_][A-Za-z0-9_]*)["']\s*\]/g,
+    /os\.environ(?:\.get)?[\[(]\s*["']([A-Za-z_][A-Za-z0-9_]*)["']/g,
+    /os\.getenv\(\s*["']([A-Za-z_][A-Za-z0-9_]*)["']/g,
+  ];
+  for (const re of res) while ((m = re.exec(text))) refs.add(m[1]);
+  return refs;
+}
+
+// Static lint of a tool's source against the keyring + its declared requires.
+// Returns { secrets, undeclared, unused } — all advisory:
+//   secrets    — hardcoded credential literals that should be $VAR refs
+//   undeclared — keyring keys the script reads but --requires omits (so
+//                missingRequires can't pre-warn → cryptic runtime failure)
+//   unused     — --requires keys the script never references
+function lintToolSource(content, { requires = [], keyringKeys = null } = {}) {
+  const text = String(content || "");
+  const secrets = [];
+  for (const [re, label] of SECRET_PATTERNS) if (re.test(text)) secrets.push(label);
+  let keys = keyringKeys;
+  if (!keys) { try { keys = require("./keyring").keys(); } catch (e) { keys = []; } }
+  const keySet = new Set(keys);
+  const refs = envRefsIn(text);
+  const declared = new Set((requires || []).map((s) => String(s).trim()).filter(Boolean));
+  const undeclared = [...refs].filter((r) => keySet.has(r) && !declared.has(r));
+  const unused = [...declared].filter((d) => !refs.has(d));
+  return { secrets, undeclared, unused };
+}
+
+// Syntax-check a tool via its interpreter, if we recognise one. Returns
+// { ok, error } or null when we can't check (unknown type or interpreter not
+// installed) — never cry wolf over a checker we don't have.
+function checkSyntax(file, content) {
+  const first = String(content || "").split("\n")[0] || "";
+  let cmd = null, args = null;
+  if (/\b(bash|sh)\b/.test(first) || /\.sh$/i.test(file)) { cmd = "bash"; args = ["-n", file]; }
+  else if (/\b(node|deno|bun)\b/.test(first) || /\.(c?js|mjs)$/i.test(file)) { cmd = "node"; args = ["--check", file]; }
+  else if (/\bpython3?\b/.test(first) || /\.py$/i.test(file)) { cmd = "python3"; args = ["-m", "py_compile", file]; }
+  if (!cmd) return null;
+  try {
+    const r = require("child_process").spawnSync(cmd, args, { encoding: "utf-8" });
+    if (r.error) return null;
+    if (r.status === 0) return { ok: true, error: "" };
+    return { ok: false, error: (r.stderr || r.stdout || "").trim().split("\n").slice(0, 3).join("\n") };
+  } catch (e) { return null; }
+}
+
 // Register a script as a tool. Copies it into TOOLS_DIR under a sanitized name,
 // ensures it carries a header (synthesising one from opts if absent), and makes
 // it executable. Returns the stored tool.
@@ -272,6 +363,7 @@ function addTool(srcPath, opts = {}) {
   const dest = toolFile(name);
   fs.writeFileSync(dest, content, { mode: 0o700 });
   try { fs.chmodSync(dest, 0o700); } catch (e) {}
+  recordCreate(name);
   return readTool(name);
 }
 
@@ -282,6 +374,57 @@ function removeTool(name) {
   return tool;
 }
 
+// Update a registered tool's header metadata in place (description/pack/requires
+// /usage) without touching its body, name, or createdAt — the "fix" verb, so
+// improving a tool is as cheap as creating one (reinforces extend-don't-
+// duplicate). Preserves the marker line and any hand-written comments in the
+// header; only the recognised field lines are refreshed. Body edits stay the job
+// of Edit/Write. Returns the updated tool, or null if no such tool.
+function updateToolHeader(name, opts = {}) {
+  const t = findTool(name);
+  if (!t) return null;
+  const prefix = commentPrefixFor(t.content, t.file);
+  const description = opts.description !== undefined ? opts.description : t.description;
+  const pack = opts.pack !== undefined ? opts.pack : t.pack;
+  const usage = opts.usage !== undefined ? opts.usage : t.usage;
+  let requires = opts.requires !== undefined ? opts.requires : t.requires;
+  if (!Array.isArray(requires)) requires = String(requires || "").split(/[,\s]+/).filter(Boolean);
+
+  const lines = t.content.split("\n");
+  let headStart = 0;
+  if (lines[0] && lines[0].startsWith("#!")) headStart = 1;
+  while (headStart < lines.length && lines[headStart].trim() === "") headStart++;
+
+  const kept = [];        // preserved comment lines (marker + any hand notes)
+  let markerIdx = -1;
+  let j = headStart;
+  for (; j < lines.length; j++) {
+    const body = uncomment(lines[j]);
+    if (body === null) break; // comment block ended
+    const kv = body.match(/^([a-zA-Z-]+)\s*:\s*(.*)$/);
+    const key = kv ? kv[1].toLowerCase() : null;
+    if (key === MARKER) { markerIdx = kept.length; kept.push(lines[j]); }
+    else if (key && HEADER_KEYS.includes(key)) { /* drop — re-added below */ }
+    else kept.push(lines[j]); // keep arbitrary comment
+  }
+  const blockEnd = j;
+
+  const fieldLines = [];
+  if (description) fieldLines.push(`${prefix} description: ${description}`);
+  if (pack) fieldLines.push(`${prefix} pack: ${pack}`);
+  if (requires.length) fieldLines.push(`${prefix} requires: ${requires.join(", ")}`);
+  if (usage) fieldLines.push(`${prefix} usage: ${usage}`);
+
+  let newBlock;
+  if (markerIdx >= 0) newBlock = [...kept.slice(0, markerIdx + 1), ...fieldLines, ...kept.slice(markerIdx + 1)];
+  else newBlock = [`${prefix} ${MARKER}: ${t.name}`, ...fieldLines, ...kept];
+
+  const next = [...lines.slice(0, headStart), ...newBlock, ...lines.slice(blockEnd)].join("\n");
+  fs.writeFileSync(t.file, next, { mode: 0o700 });
+  try { fs.chmodSync(t.file, 0o700); } catch (e) {}
+  return readTool(t.name);
+}
+
 // Env for running a tool: the bot's standard subprocess env (PATH + keyring
 // creds merged) so tools are pre-authed the same way the agent is. Falls back to
 // a plain keyring merge if config isn't importable (e.g. standalone test).
@@ -317,7 +460,8 @@ function toolNameFromPath(filePath) {
 
 module.exports = {
   TOOLS_DIR, MARKER, USAGE_FILE,
-  parseHeader, readTool, listTools, findTool, addTool, removeTool,
+  parseHeader, readTool, listTools, findTool, addTool, removeTool, updateToolHeader,
   runEnv, missingRequires, toolNameFromPath, sanitizeName, ensureDir,
-  matchTools, recordRun, readUsage,
+  matchTools, recordRun, recordCreate, readUsage,
+  lintToolSource, checkSyntax, envRefsIn,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inetafrica/open-claudia",
-  "version": "2.6.54",
+  "version": "2.6.56",
   "description": "Your always-on AI coding assistant — Claude Code, Cursor Agent, and OpenAI Codex via Telegram or Kazee Chat",
   "main": "bot.js",
   "bin": {

package/test-tools.js

@@ -115,6 +115,65 @@ tools.recordRun("beta");
 const ranked = tools.matchTools("common widget gadget").map((m) => m.name);
 assert.ok(ranked.indexOf("beta") < ranked.indexOf("alpha"), "on equal score, the more-run tool ranks first");
 
+// ── createdAt: stamped once at add, surfaced on the record, immutable across a
+//    body rewrite (so dream's "cold since creation" clock can't be reset by an
+//    edit) ──
+assert.ok(tools.findTool("hello").createdAt, "addTool stamps createdAt");
+const bornHello = tools.findTool("hello").createdAt;
+tools.recordCreate("hello"); // a second create-record must NOT move the stamp
+assert.strictEqual(tools.findTool("hello").createdAt, bornHello, "createdAt is immutable once set");
+
+// ── envRefsIn: pulls every shape of env read out of a script ──
+const refs = tools.envRefsIn('echo $FOO ${BAR}\nx=process.env.BAZ\ny=process.env["QUX"]\n');
+for (const k of ["FOO", "BAR", "BAZ", "QUX"]) assert.ok(refs.has(k), `envRefsIn finds ${k}`);
+
+// ── lintToolSource: hardcoded secrets, undeclared keyring reads, unused requires
+//    (all advisory; keyringKeys passed explicitly so the test is hermetic) ──
+const lint = tools.lintToolSource(
+  'curl -H "Authorization: Bearer sk-ant-abcdefgh12345678" "$inet_central_user" "$missing_decl"\n',
+  { requires: ["unused_key"], keyringKeys: ["inet_central_user", "unused_key"] }
+);
+assert.ok(lint.secrets.some((s) => /Anthropic/.test(s)), "lint flags the sk-ant- literal");
+assert.ok(lint.secrets.some((s) => /Bearer/.test(s)), "lint flags the inline Bearer token");
+assert.ok(lint.undeclared.includes("inet_central_user"), "a keyring key read but not declared is 'undeclared'");
+assert.ok(!lint.undeclared.includes("missing_decl"), "a non-keyring env read is not flagged undeclared");
+assert.ok(lint.unused.includes("unused_key"), "a declared key the script never reads is 'unused'");
+
+// ── checkSyntax: catches a broken bash script, passes a good one, and returns
+//    null for a type it can't check ──
+const goodSh = path.join(tmp, "good.sh");
+fs.writeFileSync(goodSh, "#!/usr/bin/env bash\necho ok\n");
+assert.deepStrictEqual(tools.checkSyntax(goodSh, fs.readFileSync(goodSh, "utf-8")), { ok: true, error: "" }, "valid bash → ok");
+const badSh = path.join(tmp, "bad.sh");
+fs.writeFileSync(badSh, "#!/usr/bin/env bash\nif [ ; then echo hi\n");
+const badRes = tools.checkSyntax(badSh, fs.readFileSync(badSh, "utf-8"));
+assert.ok(badRes && badRes.ok === false && badRes.error, "broken bash → { ok:false, error }");
+assert.strictEqual(tools.checkSyntax("/tmp/x.txt", "plain text, no shebang\n"), null, "unknown type → null (no crying wolf)");
+
+// ── updateToolHeader (the 'fix' verb): refreshes recognised field lines in place,
+//    preserves the marker (exactly once), hand-written comments, and createdAt;
+//    leaves the body untouched ──
+const fixSrc = path.join(tmp, "fixme.sh");
+fs.writeFileSync(
+  fixSrc,
+  "#!/usr/bin/env bash\n# open-claudia-tool: fixme\n# description: old desc\n# a hand note worth keeping\necho \"$WIDGET_KEY\"\n"
+);
+const fixed0 = tools.addTool(fixSrc, {});
+const bornFix = fixed0.createdAt;
+const fixed = tools.updateToolHeader("fixme", { description: "new desc", requires: ["WIDGET_KEY"], usage: "fixme <x>" });
+assert.strictEqual(fixed.description, "new desc", "updateToolHeader rewrites the description");
+assert.deepStrictEqual(fixed.requires, ["WIDGET_KEY"], "updateToolHeader sets requires");
+assert.strictEqual(fixed.usage, "fixme <x>", "updateToolHeader sets usage");
+assert.strictEqual(fixed.createdAt, bornFix, "updateToolHeader preserves createdAt");
+assert.ok(/a hand note worth keeping/.test(fixed.content), "updateToolHeader keeps hand-written comments");
+assert.strictEqual((fixed.content.match(/open-claudia-tool: fixme/g) || []).length, 1, "marker survives exactly once");
+assert.ok(/echo "\$WIDGET_KEY"/.test(fixed.content), "updateToolHeader leaves the body untouched");
+// requires-string form is normalised to a list
+const fixed2 = tools.updateToolHeader("fixme", { requires: "WIDGET_KEY, OTHER_KEY" });
+assert.deepStrictEqual(fixed2.requires, ["WIDGET_KEY", "OTHER_KEY"], "string requires split into a list");
+// a body that now reads OTHER_KEY would no longer be 'unused' — lint stays in sync
+assert.strictEqual(tools.updateToolHeader("does-not-exist", { description: "x" }), null, "updateToolHeader on a missing tool → null");
+
 // ── remove ──
 assert.ok(tools.removeTool("hello"), "removeTool returns the removed tool");
 assert.strictEqual(tools.findTool("hello"), null, "removed tool is gone");