@inetafrica/open-claudia 2.6.53 → 2.6.55

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 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.
+- **Tool usage telemetry.** A JSON sidecar (`.usage.json` in the tools dir: `runCount` + `lastUsed` per tool, recorded at end-of-turn for each successful run) works on every node version. `matchTools` breaks score ties by `runCount` so well-worn tools surface first.
+- **`tool search` + add-time duplicate guard.** New `open-claudia tool search <query>` for finding a tool on demand; `tool add` now warns (non-blocking) when an existing tool looks similar, nudging toward extending it with a subcommand over spawning a near-duplicate.
+- **Dream tool hygiene.** The nightly pass now also flags tools created-but-never-run for 30+ days and near-duplicate tool pairs (alongside the existing dangling-`--pack` flag). Flag-only — a tool is never auto-deleted. Extends `test-tools.js` (matchTools/telemetry) and `test-recall-discoverer.js` (tool seeding). Degrades to a graceful no-op where `node:sqlite` is unavailable.
+
 ## v2.6.53
 - **Pack↔tool contextual edges — surface how a tool is used in a topic.** Completes the v2.6.49 tool story. The directed tool-graph answers "what runs *next*"; this adds the orthogonal question "how is a tool *used in this context*". A new `pack_tool_edges` table (`core/tool-graph.js`, sharing the existing SQLite store, decay and pruning) records, for each turn, the reusable tools that ran while a context pack was open — keyed by `(pack, tool, command-shape)` so distinct invocations of the same tool coexist and the strongest surface. Capture is automatic and deterministic (no hand-authoring): `runner.js` already tracks the tools run and the packs opened each turn, so at end-of-turn it records a pack↔tool edge per (opened-pack × run-tool), Hebbian-reinforced. Commands are stored as **shapes, not literals** — a new `shapeCommand()` strips ids, paths, numbers and quoted text to placeholders (`spaces docs --task-id <id> <path>`) so the memory is a reusable pattern, not a stale one-off; `parseToolRuns()` extracts `{name, shape}` from a shell command (split across chained invocations) and feeds both graphs. Surfacing: when a pack is injected into context, `formatPackForContext` appends a **"Tools used in this pack"** block with the 1–2 strongest invocations, so the agent sees the concrete command instead of re-deriving it; `tool show` gains the inverse "Used in packs" view; an optional `intent` column lets a one-line *why* be enriched later without a migration. The nightly dream tends these edges alongside the follows-edges (decay + prune orphaned tools/packs). Degrades to a graceful no-op where `node:sqlite` is unavailable, exactly like the existing tool-graph. Extends `test-tool-graph.js`.
 

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|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

@@ -3,13 +3,22 @@
 // heredoc. The executable sibling of context packs (`open-claudia pack`).
 //
 //   open-claudia tool list                       — index (name — description [skill])
+//   open-claudia tool search <query>             — lexical match (find before adding a dup)
 //   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.
@@ -33,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);
@@ -53,6 +104,25 @@ function run(args) {
       break;
     }
 
+    case "search":
+    case "find": {
+      const query = rest.join(" ").trim();
+      if (!query) { console.error("Usage: tool search <query>"); process.exitCode = 1; return; }
+      const matches = tools.matchTools(query, { limit: 10 });
+      if (!matches.length) {
+        console.log(`No tools match "${query}". See all: open-claudia tool list`);
+        return;
+      }
+      console.log(`${matches.length} tool(s) matching "${query}":\n`);
+      for (const m of matches) {
+        const t = tools.findTool(m.name);
+        const needs = t && t.requires && t.requires.length ? `  (keyring: ${t.requires.join(", ")})` : "";
+        console.log(`• ${m.name} — ${m.description || "(no description)"}${needs}`);
+      }
+      console.log(`\nRun: open-claudia tool run <name> [args]   ·   Docs: open-claudia tool show <name>`);
+      break;
+    }
+
     case "show":
     case "cat": {
       const name = rest[0];
@@ -112,12 +182,70 @@ 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 {
+          const near = tools.matchTools([t.name, t.description].filter(Boolean).join(" "), { limit: 3 })
+            .filter((m) => m.name !== t.name);
+          if (near.length) {
+            console.log(`\nHeads up — ${near.length} existing tool(s) look similar:`);
+            for (const m of near) console.log(`  • ${m.name} — ${m.description || "(no description)"}`);
+            console.log("Consider extending one with a new subcommand instead of keeping a near-duplicate (open-claudia tool show <name>).");
+          }
+        } catch (e) { /* best-effort */ }
       } catch (e) {
         console.error(`Could not add tool: ${e.message}`); process.exitCode = 1;
       }
       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];
@@ -149,7 +277,7 @@ function run(args) {
       break;
 
     default:
-      console.log('Usage: open-claudia tool [list | 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/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/actions.js

@@ -290,6 +290,12 @@ async function handleAction(envelope) {
     await send(`Recall debug: ${state.settings.showRecall ? "on" : "off"}`);
     return;
   }
+  if (d.startsWith("tt:")) {
+    state.settings.showToolTrace = d.slice(3) === "on";
+    saveState();
+    await send(`Tool trace: ${state.settings.showToolTrace ? "on" : "off"}`);
+    return;
+  }
   if (d.startsWith("cw:")) {
     const v = d.slice(3);
     if (v === "default") state.settings.compactWindow = null;

package/core/dream.js

@@ -838,10 +838,39 @@ async function runDream({ trigger = "manual" } = {}) {
       if (tg.edges || tg.decayed || tg.pruned) {
         bits.push(`🔧 Tool graph: ${tg.edges} edges / ${tg.nodes} nodes (decayed ${tg.decayed}, pruned ${tg.pruned}).`);
       }
-      const dangling = toolsLib.listTools().filter((t) => t.pack && !packs.readPack(t.pack));
+      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.`);
       }
+      // Zero-run tools: created but never run and gone cold. Telemetry runCount
+      // 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) {
+        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.`);
+      }
+      // Near-duplicate pairs: two tools whose name+description overlap strongly,
+      // a sign one should have been a subcommand of the other. Dedupe by sorted
+      // pair key; flag only (consolidating is a judgement call for the user).
+      const DUP_THRESHOLD = Number(process.env.TOOL_DUP_THRESHOLD || 4);
+      const dupPairs = new Set();
+      for (const t of allTools) {
+        const near = toolsLib.matchTools([t.name, t.description].filter(Boolean).join(" "), { threshold: DUP_THRESHOLD, limit: 5 })
+          .filter((m) => m.name !== t.name);
+        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.`);
+      }
       toolNote = bits.join("\n");
     } catch (e) { /* tool graph is best-effort (old node) */ }
 

package/core/handlers.js

@@ -123,7 +123,7 @@ register({
     if (!authorized(env)) return;
     send([
       "Session: /session /sessions /projects /continue /status /stop /end",
-      "Settings: /model /effort /budget /plan /compact /compactwindow /worktree /mode /engine /recall",
+      "Settings: /model /effort /budget /plan /compact /compactwindow /worktree /mode /engine /recall /tooltrace",
       "Identity: /whoami /link",
       "Team: /people /intros /auth (owner)",
       "Automation: /cron /vault /soul /dreamsummary",
@@ -743,6 +743,29 @@ register({
   },
 });
 
+register({
+  name: "tooltrace", description: "Show tool activity each turn (surfaced/ran/updated)", args: "[on|off]",
+  handler: async (env, { tail }) => {
+    if (!authorized(env)) return;
+    const { settings } = currentState();
+    if (tail) {
+      const v = tail.trim().toLowerCase();
+      if (v === "on" || v === "true") settings.showToolTrace = true;
+      else if (v === "off" || v === "false") settings.showToolTrace = false;
+      else return send(`Usage: /tooltrace [on|off]. Currently ${settings.showToolTrace ? "on" : "off"}.`);
+      saveState();
+      return send(`Tool trace: ${settings.showToolTrace ? "on" : "off"}`);
+    }
+    send(
+      `Tool trace: ${settings.showToolTrace ? "on" : "off"}\n\n` +
+      "When on, I post short 🔧 lines around each reply: which reusable tools were surfaced for the turn, which I actually ran, and any I created or updated. Lets you watch the tool layer work. Off by default.",
+      { keyboard: { inline_keyboard: [
+        [{ text: "On", callback_data: "tt:on" }, { text: "Off", callback_data: "tt:off" }],
+      ] } },
+    );
+  },
+});
+
 register({
   name: "budget", description: "Set max spend for next task", args: "[$N]",
   handler: async (env, { tail }) => {

package/core/recall/discoverer.js

@@ -19,6 +19,13 @@ const graph = require("./graph");
 const metrics = require("./metrics");
 const { spawnSubagent } = require("../subagent");
 const warmWalker = require("./warm-walker");
+const toolsLib = require("../tools");
+// Tool-graph is the directed-usage source of truth (pack↔tool edges). The
+// discoverer READS it to activate tools that belong to a surfaced pack; it never
+// writes the recall graph with tool nodes (keeps the hot expand() path pack/
+// entity-only). Optional — absent on old node where node:sqlite is missing.
+let toolGraph = null;
+try { toolGraph = require("../tool-graph"); } catch (e) { /* old node */ }
 
 const WALKER_MODEL = process.env.RECALL_DISCOVERER_MODEL || "haiku";
 const WALKER_TIMEOUT_MS = Number(process.env.RECALL_DISCOVERER_TIMEOUT_MS || 25000);
@@ -64,6 +71,18 @@ function excerptFor(id, packsLib, entitiesLib) {
       const body = [p.sections.Stance, p.sections.State].filter(Boolean).join("\n").trim();
       return { id, name: p.name, description: p.description, excerpt: clip(body, EXCERPT_CHARS) };
     }
+    if (id.startsWith("tool:")) {
+      const name = id.slice(5);
+      const t = toolsLib.findTool(name);
+      if (!t) return null;
+      // Excerpt the walker judges a tool against: what it does (usage) plus the
+      // concrete command shapes it's actually been run as in a topic, so "would
+      // this help here?" is answerable without reading the source.
+      let shapes = [];
+      if (toolGraph) { try { shapes = toolGraph.toolPacks(name, 2).map((p) => p.command).filter(Boolean); } catch (e) {} }
+      const excerpt = [t.usage, shapes.length ? `e.g. ${shapes.join(" | ")}` : ""].filter(Boolean).join(" — ");
+      return { id, name, description: t.description, excerpt: clip(excerpt, EXCERPT_CHARS) };
+    }
     const e = entitiesLib.readEntity(id.slice(7));
     if (!e) return null;
     return { id, name: e.name, description: e.description, excerpt: clip((e.sections.Notes || "").trim(), EXCERPT_CHARS) };
@@ -75,6 +94,7 @@ const WALKER_SYSTEM = [
   "You are given the user's message, recent conversation, and candidate memory nodes (some matched by keyword, some pulled in by graph links).",
   "Decide which nodes are GENUINELY relevant to what the user is doing now.",
   "Keep graph-linked nodes ONLY if they actually bear on the task (e.g. a shared theme/commit-style that governs the thing being worked on). Drop incidental keyword overlaps.",
+  "Some candidates are reusable tools (id starts `tool:`). Keep a tool ONLY if running it would actually help with THIS task; drop tools merely related by keyword.",
   "For each kept node write a terse why (≤12 words). Quote concrete facts verbatim; never invent.",
   'Reply with ONLY a JSON array: [{"id":"pack:foo","why":"shared lime theme governs this app"}]. Use [] if none.',
 ].join("\n");
@@ -154,12 +174,22 @@ async function run(ctx) {
     );
   } catch (e) {}
 
-  const seedCount = packSeeds.length + entSeeds.length;
+  // Tool seeds: direct FTS-style match of the user's words (and context) against
+  // the tool corpus — the SEED stage for tools, peer to pack/entity seeding.
+  const toolSeedByName = new Map();
+  try {
+    for (const t of toolsLib.matchTools(userText, { limit: 5 })) toolSeedByName.set(t.name, { ...t, origin: "user" });
+    if (fullContext) for (const t of toolsLib.matchTools(fullContext, { limit: 5 })) {
+      if (!toolSeedByName.has(t.name)) toolSeedByName.set(t.name, { ...t, origin: "context" });
+    }
+  } catch (e) {}
+
+  const seedCount = packSeeds.length + entSeeds.length + toolSeedByName.size;
 
   // 1: pre-gate.
   if (!needsRecall(userText, seedCount)) {
     metrics.logTurn({ engine: "discoverer", query: userText, gated: true, latencyMs: Date.now() - started });
-    return { packBlock: "", entityBlock: "", packMatches: [], entityMatches: [], why: {}, gated: true };
+    return { packBlock: "", entityBlock: "", toolBlock: "", packMatches: [], entityMatches: [], toolMatches: [], why: {}, gated: true };
   }
 
   // 3: spreading activation from seeds across the graph.
@@ -182,6 +212,47 @@ async function run(ctx) {
     candidates.push({ ...base, activated: !seedIds.has(id), via: act ? act.via : null });
   }
 
+  // Tool candidates = direct tool seeds + tools that belong to any candidate
+  // pack (declared via the tool's `pack:` header, or used-in-topic per the
+  // tool-graph). This is the tool "activation": tools ride on whatever packs the
+  // FTS+graph already surfaced, so a pack seed pulls in its tools the user never
+  // named — then the walker decides which actually help. via != null => activated.
+  const candPackDirs = new Set();
+  for (const id of candIds) if (id.startsWith("pack:")) candPackDirs.add(id.slice(5));
+  const toolCand = new Map();
+  for (const [name, t] of toolSeedByName) toolCand.set(name, { name, description: t.description, via: null });
+  if (candPackDirs.size) {
+    try {
+      const byPack = new Map();
+      for (const t of toolsLib.listTools()) {
+        if (!t.pack) continue;
+        if (!byPack.has(t.pack)) byPack.set(t.pack, []);
+        byPack.get(t.pack).push(t);
+      }
+      for (const dir of candPackDirs) {
+        for (const t of (byPack.get(dir) || [])) {
+          if (!toolCand.has(t.name)) toolCand.set(t.name, { name: t.name, description: t.description, via: `pack:${dir}` });
+        }
+      }
+    } catch (e) {}
+    if (toolGraph) {
+      try {
+        for (const dir of candPackDirs) {
+          for (const u of toolGraph.packTools(dir, 3)) {
+            if (toolCand.has(u.tool)) continue;
+            const t = toolsLib.findTool(u.tool);
+            if (t) toolCand.set(u.tool, { name: u.tool, description: t.description, via: `pack:${dir}` });
+          }
+        }
+      } catch (e) {}
+    }
+  }
+  for (const c of toolCand.values()) {
+    const base = excerptFor(`tool:${c.name}`, packsLib, entitiesLib);
+    if (!base) continue;
+    candidates.push({ ...base, activated: !!c.via, via: c.via });
+  }
+
   const whyById = (await walk(userText, contextText || fullContext, candidates)) || null;
 
   // Decide the kept set. Walker result wins; on fail-open keep the user-origin
@@ -192,7 +263,8 @@ async function run(ctx) {
   } else {
     keptIds = new Set(
       [...packSeeds.filter((m) => m.origin === "user").map((m) => `pack:${m.dir}`),
-       ...entSeeds.filter((m) => m.origin === "user").map((m) => `entity:${m.slug}`)],
+       ...entSeeds.filter((m) => m.origin === "user").map((m) => `entity:${m.slug}`),
+       ...[...toolSeedByName.values()].filter((t) => t.origin === "user").map((t) => `tool:${t.name}`)],
     );
   }
 
@@ -229,6 +301,25 @@ async function run(ctx) {
     if (bullets.length) packBlock = `\n\n### Why these surfaced (discoverer)\n${bullets.join("\n")}${packBlock}`;
   }
 
+  // Tools the walker kept (or, on fail-open, user-origin tool seeds). Rendered as
+  // their own contextual block — this replaces the old flat "all 40 tools every
+  // turn" dump: tools surface only when they bear on the task, with a why.
+  const toolMatches = [];
+  for (const c of toolCand.values()) {
+    if (keptIds.has(`tool:${c.name}`)) {
+      toolMatches.push({ name: c.name, description: c.description, why: whyById ? whyById.get(`tool:${c.name}`) || "" : "" });
+    }
+  }
+  let toolBlock = "";
+  if (toolMatches.length) {
+    const lines = toolMatches.map((m) => {
+      const t = toolsLib.findTool(m.name);
+      const needs = t && t.requires && t.requires.length ? ` (keyring: ${t.requires.join(", ")})` : "";
+      return `- ${m.name} — ${m.description || "(no description)"}${needs}${m.why ? ` — ${m.why}` : ""}`;
+    });
+    toolBlock = `\n\n## Tools that may help here\nSurfaced for this turn — run with \`open-claudia tool run <name> [args]\`; read docs/source with \`open-claudia tool show <name>\`:\n${lines.join("\n")}\n`;
+  }
+
   metrics.logTurn({
     engine: "discoverer",
     query: userText,
@@ -240,8 +331,8 @@ async function run(ctx) {
   });
 
   return {
-    packBlock, entityBlock, packMatches: finalPacks, entityMatches: finalEnts,
-    why: whyById ? Object.fromEntries(whyById) : {}, gated: false,
+    packBlock, entityBlock, toolBlock, packMatches: finalPacks, entityMatches: finalEnts,
+    toolMatches, why: whyById ? Object.fromEntries(whyById) : {}, gated: false,
   };
 }
 

package/core/runner.js

@@ -889,6 +889,13 @@ async function runClaude(prompt, cwd, replyToMsgId, opts = {}) {
     skillNotified.add(key);
     chatContext.run(store, () => send(text).catch(() => {}));
   };
+  // Tool-activity visibility (surfaced / ran / created-updated). Off by default,
+  // toggled per-channel with /tooltrace — mirrors /recall's showRecall. Dedup +
+  // delivery reuse notifySkill so a tool touched twice a turn announces once.
+  const notifyToolTrace = (key, text) => {
+    if (!settings.showToolTrace) return;
+    notifySkill(key, text);
+  };
   const noteSkillToolUse = (toolName, input) => {
     try {
       if (toolName === "Skill" && input?.skill) {
@@ -918,8 +925,8 @@ async function runClaude(prompt, cwd, replyToMsgId, opts = {}) {
         }
         const toolName2 = toolsLib.toolNameFromPath(filePath);
         if (toolName2) {
-          if (toolsLib.findTool(toolName2)) notifySkill(`tool:${toolName2}`, `🔧 Updating tool: ${toolName2} — open-claudia tool show ${toolName2} to inspect.`);
-          else notifySkill(`tool:${toolName2}`, `🔧 New tool: ${toolName2} — open-claudia tool run ${toolName2} to use it.`);
+          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);
@@ -971,8 +978,23 @@ async function runClaude(prompt, cwd, replyToMsgId, opts = {}) {
       // next); the sanitized command shape feeds pack↔tool capture (how a tool
       // is used in a topic). Parsing lives in tool-graph so it stays testable.
       try {
-        for (const run of require("./tool-graph").parseToolRuns(cmd)) toolRunsThisTurn.push(run);
+        for (const run of require("./tool-graph").parseToolRuns(cmd)) {
+          toolRunsThisTurn.push(run);
+          // Visibility (gated by /tooltrace): one 🔧 line per distinct tool run
+          // this turn. Telemetry (recordRun) fires at end-of-turn on success.
+          notifyToolTrace(`ran:${run.name}`, `🔧 Ran tool: ${run.name}`);
+        }
       } catch (e) { /* graph optional (old node) */ }
+      // `open-claudia tool add <src> [--name X]` — a tool being saved/updated.
+      // The Write/Edit path above only catches direct edits to TOOLS_DIR; `tool
+      // add` copies an external file in, so detect it here. Gated by /tooltrace.
+      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 */ }
   };
 
@@ -1007,13 +1029,21 @@ async function runClaude(prompt, cwd, replyToMsgId, opts = {}) {
   // drained here to keep the per-turn buffer from leaking into the next turn.)
   try {
     const injected = require("./system-prompt").consumeLastInjected();
-    if (settings.showRecall && injected && injected.recall) {
+    if (injected && injected.recall) {
       const r = injected.recall;
       const esc = (s) => String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
       const fmt = (arr, icon) => arr.map((x) => (x.why ? `${icon} <b>${esc(x.name)}</b> — ${esc(x.why)}` : `${icon} <b>${esc(x.name)}</b>`));
-      const lines = [...fmt(r.packs || [], "📦"), ...fmt(r.entities || [], "👤")];
-      if (lines.length) send(`🧠 <b>Recall this turn</b> (${esc(r.engine)})\n${lines.join("\n")}`, telegramHtmlOpts()).catch(() => {});
-      else if (r.gated) send(`🧠 <b>Recall</b> (${esc(r.engine)}): skipped by pre-gate — trivial turn.`, telegramHtmlOpts()).catch(() => {});
+      // 🧠 packs/entities recall — gated by /recall.
+      if (settings.showRecall) {
+        const lines = [...fmt(r.packs || [], "📦"), ...fmt(r.entities || [], "👤")];
+        if (lines.length) send(`🧠 <b>Recall this turn</b> (${esc(r.engine)})\n${lines.join("\n")}`, telegramHtmlOpts()).catch(() => {});
+        else if (r.gated) send(`🧠 <b>Recall</b> (${esc(r.engine)}): skipped by pre-gate — trivial turn.`, telegramHtmlOpts()).catch(() => {});
+      }
+      // 🔧 tools surfaced this turn (first-class discoverer nodes) — gated by /tooltrace.
+      if (settings.showToolTrace) {
+        const toolLines = fmt(r.tools || [], "🔧");
+        if (toolLines.length) send(`🔧 <b>Tools surfaced this turn</b>\n${toolLines.join("\n")}`, telegramHtmlOpts()).catch(() => {});
+      }
     }
   } catch (e) { /* best-effort */ }
   // /stop landed during the pre-spawn window (recall/compaction): bail before
@@ -1369,6 +1399,15 @@ async function runClaude(prompt, cwd, replyToMsgId, opts = {}) {
       catch (e) { /* best-effort */ }
     }
 
+    // Tool usage telemetry: a JSON sidecar (runCount + lastUsed per tool) that
+    // works on every node version (unlike the SQLite graphs above). matchTools
+    // breaks score ties by runCount so well-worn tools surface first, and dream
+    // hygiene flags tools created-but-never-run. Fires for any successful run.
+    if (turnSucceeded && toolRunsThisTurn.length) {
+      try { for (const t of toolRunsThisTurn) toolsLib.recordRun(t.name); }
+      catch (e) { /* best-effort */ }
+    }
+
     // Pack↔tool contextual edges: a reusable tool run while a context pack was
     // open this turn records "this tool was used in this topic, as `<shape>`",
     // so next time the pack is active the discoverer can surface the concrete

package/core/system-prompt.js

@@ -66,37 +66,18 @@ function buildSkillIndexBlock() {
   }
 }
 
-// Always-on tool index: the executable sibling of the skill index. Each entry
-// is a real script the agent crystallised from a working procedure, surfaced by
-// name+description every turn (progressive disclosure — full docs/source load on
-// demand via `open-claudia tool show <name>`). Tools run pre-authed: the
-// operational keyring is merged into their env, so a tool references a credential
-// as $NAME and never hardcodes a secret.
+// Always-on tool guidance: teaches the BEHAVIOUR (crystallise procedures into
+// tools; how to find and run them). It does NOT dump the tool list — that used to
+// inject all ~40 tools every turn regardless of relevance. Tools now surface
+// contextually as first-class discoverer nodes (see discoverer.js → toolBlock),
+// the same seed→activate→judge→render path as packs/entities; this block only
+// names the count and the lookup commands (`tool list` / `tool search`).
 function buildToolIndexBlock() {
   let listing = "";
   try {
-    const all = require("./tools").listTools();
-    if (all.length) {
-      // Directed tool-graph: surface the strongest "runs next" follower per tool
-      // so a known chain (auth → list → download) is visible inline. Optional —
-      // absent on old node where node:sqlite is missing.
-      let graph = null;
-      try { graph = require("./tool-graph"); } catch (e) {}
-      listing = "\nTools you already have (run with `open-claudia tool run <name> [args]`; read docs/source with `open-claudia tool show <name>`):\n\n" +
-        all.slice(0, 40)
-          .map((t) => {
-            const skill = t.pack ? ` [skill: ${t.pack}]` : "";
-            const needs = t.requires && t.requires.length ? ` (keyring: ${t.requires.join(", ")})` : "";
-            let next = "";
-            if (graph) {
-              try {
-                const after = graph.followers(t.name, 2).map((r) => r.name);
-                if (after.length) next = ` → usually followed by: ${after.join(", ")}`;
-              } catch (e) {}
-            }
-            return `- ${t.name} — ${t.description || "(no description)"}${needs}${skill}${next}`;
-          })
-          .join("\n") + "\n";
+    const count = require("./tools").listTools().length;
+    if (count) {
+      listing = `\nYou have ${count} reusable tool${count === 1 ? "" : "s"}. The ones relevant to a turn are surfaced automatically below (\"Tools that may help here\"). To find others on demand: \`open-claudia tool search <query>\` (lexical match) or \`open-claudia tool list\`; read docs/source with \`open-claudia tool show <name>\`; run with \`open-claudia tool run <name> [args]\`.\n`;
     } else {
       listing = "\nNo reusable tools saved yet — the first time you work out how to hit an API or drive an interface, save it as one.\n";
     }
@@ -761,18 +742,23 @@ async function promptWithDynamicContext(prompt, opts = {}) {
       userText, contextText, fullContext, packLimit, budget, helpers,
     });
     const { packBlock, entityBlock } = result;
+    const toolBlock = result.toolBlock || "";
     const why = result.why || {};
     lastInjected.recall = {
       engine: engine.name || recall.activeEngineName(settings),
       gated: !!result.gated,
       packs: (result.packMatches || []).map((m) => ({ name: m.name || m.dir, why: why[`pack:${m.dir}`] || "" })),
       entities: (result.entityMatches || []).map((m) => ({ name: m.name || m.slug, why: why[`entity:${m.slug}`] || "" })),
+      // Tools surfaced as first-class discoverer nodes this turn (name + why).
+      // Drives the /tooltrace "surfaced" banner; the toolBlock below is the
+      // context the agent actually sees.
+      tools: (result.toolMatches || []).map((m) => ({ name: m.name, why: m.why || why[`tool:${m.name}`] || "" })),
     };
     const budgetNote = budget.omitted > 0
       ? `\n\n## Memory budget\n${budget.omitted} matched memory item${budget.omitted === 1 ? " was" : "s were"} omitted to keep this turn under the recall budget (${budget.maxChars} chars). Use \`open-claudia pack show <dir>\`, \`entity show <slug>\`, or transcript search if deeper context is needed.`
       : "";
     const transcriptPointer = opts.includeTranscriptPointer ? `${transcriptPointerNote(state)}\n\n` : "";
-    return `${transcriptPointer}${buildDynamicContextBlock()}${packBlock}${entityBlock}${budgetNote}${voiceReplyGuidance()}\n\nCurrent user request:\n${prompt}`;
+    return `${transcriptPointer}${buildDynamicContextBlock()}${packBlock}${entityBlock}${toolBlock}${budgetNote}${voiceReplyGuidance()}\n\nCurrent user request:\n${prompt}`;
   } catch (e) {
     return prompt;
   }

package/core/tool-graph.js

@@ -5,9 +5,18 @@
 // Why separate: the recall graph spreads activation over packs+entities to pick
 // which MEMORY to surface. Tools are a different corpus with different physics —
 // the useful signal is the ORDER a chain runs in (auth → list → download), not
-// symmetric "these are related". Mixing tool nodes into the recall graph would
-// let a tool fire a pack headline (and vice-versa), which is noise. So tools get
-// their own tiny graph.
+// symmetric "these are related". So tools get their own tiny graph and the recall
+// graph's hot expand() path stays pack/entity-only (no tuning, no crowding of
+// structural pack edges, works unchanged on every node version).
+//
+// How tools still reach the discoverer: this graph is the directed-usage source
+// of truth, and the discoverer READS it (recordPackTool → packTools/toolPacks) to
+// activate the tools belonging to a pack it already surfaced — then its haiku
+// walker judges each tool with a why and drops incidental ones. That walker is
+// the noise filter an earlier "mixing would be noise" worry assumed didn't exist;
+// because the discoverer judges candidates, tools participate as first-class
+// nodes (seed via matchTools → activate via this graph → judge → render) WITHOUT
+// ever being written into the recall graph as nodes.
 //
 // Why directed: A→B ("B follows A") carries real information that B→A does not.
 // auth-then-fetch is a pipeline; fetch-then-auth is nonsense. Edges are stored

package/core/tools.js

@@ -35,6 +35,111 @@ function sanitizeName(name) {
     .replace(/[^a-z0-9._-]+/g, "-").replace(/^[-.]+|[-.]+$/g, "").slice(0, 60);
 }
 
+// ── Run telemetry ────────────────────────────────────────────────────────────
+// A tiny JSON sidecar (name -> { runCount, lastUsed }) kept beside the tools.
+// Deliberately NOT a SQLite graph: telemetry must work on the node:20 pods where
+// node:sqlite is absent, and it's a flat counter, not a graph. Dotfile so
+// listTools (which skips ".") never mistakes it for a tool.
+const USAGE_FILE = path.join(TOOLS_DIR, ".usage.json");
+
+function readUsage() {
+  try { return JSON.parse(fs.readFileSync(USAGE_FILE, "utf-8")) || {}; }
+  catch (e) { return {}; }
+}
+
+function writeUsage(u) {
+  try { ensureDir(); fs.writeFileSync(USAGE_FILE, JSON.stringify(u), { mode: 0o600 }); }
+  catch (e) { /* best-effort */ }
+}
+
+// Bump a tool's run counter. Called at end of turn from the runner when it parses
+// an `open-claudia tool run <name>` out of the shell. Feeds matchTools' tiebreak
+// (popular tools rank up) and the dream's zero-run hygiene flag.
+function recordRun(name) {
+  const n = sanitizeName(name);
+  if (!n) return;
+  const u = readUsage();
+  const cur = u[n] || { runCount: 0, lastUsed: "" };
+  cur.runCount = (cur.runCount || 0) + 1;
+  cur.lastUsed = new Date().toISOString();
+  u[n] = cur;
+  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
+// version. Mirrors matchPacks' semantics: a hit in a strong field (name /
+// description / usage) counts 2, a weak-field hit (requires / pack / source) 1,
+// tools at/above the threshold win. This is the SEED stage of the discoverer for
+// the tool corpus — keyword feeds the agentic walker, it does not replace it.
+const TOOL_STOPWORDS = new Set(("a an and are as at be but by can did do for from had has have how i if in is it its " +
+  "me my no not of on or our so that the their then there this to up us was we what when where which who why " +
+  "will with you your yes yeah ok okay please thanks just like dont im its run tool use").split(" "));
+
+function toolQueryTerms(text) {
+  const seen = new Set();
+  const terms = [];
+  for (const raw of String(text || "").toLowerCase().split(/[^a-z0-9_.-]+/)) {
+    const t = raw.replace(/^[.-]+|[.-]+$/g, "");
+    if (t.length < 2 || TOOL_STOPWORDS.has(t) || seen.has(t)) continue;
+    seen.add(t);
+    terms.push(t);
+    if (terms.length >= 40) break;
+  }
+  return terms;
+}
+
+function wordsOf(s) {
+  return new Set(String(s || "").toLowerCase().split(/[^a-z0-9_.-]+/).filter(Boolean));
+}
+
+// A term hits a word set on exact match, or a light prefix stem (deploy~deploys,
+// upload~uploads) for terms long enough that a prefix isn't noise.
+function termHits(term, wordSet) {
+  if (wordSet.has(term)) return true;
+  if (term.length >= 4) {
+    for (const w of wordSet) if (w.startsWith(term) || term.startsWith(w)) return true;
+  }
+  return false;
+}
+
+// Score registered tools against free text. Returns [{ name, description, score,
+// runCount }] over the threshold, strongest first (runCount breaks ties so a
+// well-worn tool outranks a never-run namesake).
+function matchTools(text, { limit = 5, threshold = null } = {}) {
+  const terms = toolQueryTerms(text);
+  if (!terms.length) return [];
+  const min = threshold ?? Number(process.env.TOOL_MATCH_THRESHOLD || 2);
+  const out = [];
+  for (const t of listTools()) {
+    const strong = wordsOf([t.name, t.description, t.usage].filter(Boolean).join(" "));
+    const weak = wordsOf([(t.requires || []).join(" "), t.pack, t.content].filter(Boolean).join(" "));
+    let score = 0;
+    for (const term of terms) {
+      if (termHits(term, strong)) score += 2;
+      else if (termHits(term, weak)) score += 1;
+    }
+    if (score >= min) out.push({ name: t.name, description: t.description, score, runCount: t.runCount || 0 });
+  }
+  out.sort((a, b) => b.score - a.score || (b.runCount || 0) - (a.runCount || 0) || a.name.localeCompare(b.name));
+  return out.slice(0, Math.max(1, Math.min(10, limit)));
+}
+
 // Strip a leading comment prefix ("# " / "// ") from a header line. Returns the
 // remainder, or null if the line is not a comment (header block has ended).
 function uncomment(line) {
@@ -75,7 +180,7 @@ function toolFile(name) {
   return path.join(TOOLS_DIR, sanitizeName(name));
 }
 
-function readTool(name) {
+function readTool(name, usageMap) {
   const file = toolFile(name);
   let content;
   try { content = fs.readFileSync(file, "utf-8"); } catch (e) { return null; }
@@ -83,6 +188,7 @@ function readTool(name) {
   if (!header) return null;
   let stat = null;
   try { stat = fs.statSync(file); } catch (e) {}
+  const usage = (usageMap || readUsage())[header.name || sanitizeName(name)] || {};
   return {
     name: header.name || sanitizeName(name),
     description: header.description || "",
@@ -92,6 +198,9 @@ function readTool(name) {
     file,
     executable: stat ? !!(stat.mode & 0o111) : false,
     updatedAt: stat ? stat.mtime.toISOString() : "",
+    createdAt: usage.createdAt || "",
+    runCount: usage.runCount || 0,
+    lastUsed: usage.lastUsed || "",
     content,
   };
 }
@@ -99,12 +208,13 @@ function readTool(name) {
 function listTools() {
   let entries;
   try { entries = fs.readdirSync(TOOLS_DIR); } catch (e) { return []; }
+  const usage = readUsage();
   const tools = [];
   for (const name of entries) {
     if (name.startsWith(".")) continue;
     try { if (!fs.statSync(path.join(TOOLS_DIR, name)).isFile()) continue; }
     catch (e) { continue; }
-    const t = readTool(name);
+    const t = readTool(name, usage);
     if (t) tools.push(t);
   }
   tools.sort((a, b) => a.name.localeCompare(b.name));
@@ -134,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.
@@ -177,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);
 }
 
@@ -187,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).
@@ -221,7 +459,9 @@ function toolNameFromPath(filePath) {
 }
 
 module.exports = {
-  TOOLS_DIR, MARKER,
-  parseHeader, readTool, listTools, findTool, addTool, removeTool,
+  TOOLS_DIR, MARKER, USAGE_FILE,
+  parseHeader, readTool, listTools, findTool, addTool, removeTool, updateToolHeader,
   runEnv, missingRequires, toolNameFromPath, sanitizeName, ensureDir,
+  matchTools, recordRun, recordCreate, readUsage,
+  lintToolSource, checkSyntax, envRefsIn,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inetafrica/open-claudia",
-  "version": "2.6.53",
+  "version": "2.6.55",
   "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-recall-discoverer.js

@@ -10,8 +10,19 @@ const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "recall-disc-"));
 process.env.RECALL_GRAPH_DB = path.join(tmp, "graph.db");
 process.env.RECALL_DISCOVERER_WALKER = "off";
 process.env.RECALL_METRICS = "off";
+process.env.TOOLS_DIR = path.join(tmp, "tools");
 
 const disc = require("./core/recall/discoverer");
+const toolsLib = require("./core/tools");
+
+// A reusable tool whose description matches a query should seed the discoverer
+// as a first-class candidate (origin user), survive the walker-off fail-open,
+// and render into the toolBlock — exactly like a pack/entity seed.
+toolsLib.addTool((() => {
+  const s = path.join(tmp, "mikrotik-audit.sh");
+  fs.writeFileSync(s, "#!/usr/bin/env bash\necho audit\n");
+  return s;
+})(), { name: "mikrotik-audit", description: "audit the mikrotik router fleet inventory" });
 
 // --- pre-gate ---
 assert.strictEqual(disc.needsRecall("", 0), false, "empty → no recall");
@@ -82,5 +93,22 @@ const helpers = { packsLib, entitiesLib, mergeMatches, buildPackBlock, buildEnti
   });
   assert.strictEqual(typeof out2.packBlock, "string");
 
+  // tool seeding: a tool matching the user text surfaces as a kept tool match and
+  // renders into toolBlock; a turn that matches no tool yields an empty toolBlock
+  const outTool = await disc.run({
+    userText: "audit the mikrotik router fleet", contextText: "",
+    fullContext: "audit the mikrotik router fleet", packLimit: 6, budget: {}, helpers,
+  });
+  assert.ok(outTool.toolMatches.some((m) => m.name === "mikrotik-audit"), "matching tool is kept (fail-open user seed)");
+  assert.ok(/mikrotik-audit/.test(outTool.toolBlock), "kept tool renders into the toolBlock");
+  assert.ok(/Tools that may help here/.test(outTool.toolBlock), "toolBlock carries its heading");
+
+  const outNoTool = await disc.run({
+    userText: "help with the mobile app", contextText: "", fullContext: "help with the mobile app",
+    packLimit: 6, budget: {}, helpers,
+  });
+  assert.strictEqual(outNoTool.toolBlock, "", "no tool match → empty toolBlock");
+  assert.strictEqual(outNoTool.toolMatches.length, 0, "no tool match → no toolMatches");
+
   console.log("recall discoverer OK");
 })().catch((e) => { console.error(e); process.exit(1); });

package/test-tools.js

@@ -85,6 +85,95 @@ assert.strictEqual(
 // ── parseHeader returns null for a script with no marker line ──
 assert.strictEqual(tools.parseHeader("#!/bin/sh\necho hi\n"), null, "no marker → not a tool");
 
+// ── matchTools: lexical scoring over name/description (strong) vs requires/pack
+//    /source (weak); a non-matching query returns nothing ──
+const mHello = tools.matchTools("say hi");
+assert.ok(mHello.some((m) => m.name === "hello"), "matchTools finds 'hello' by its description terms");
+const mFetch = tools.matchTools("fetch a thing");
+assert.ok(mFetch.some((m) => m.name === "fetch"), "matchTools finds 'fetch'");
+assert.ok(!mFetch.some((m) => m.name === "hello"), "an unrelated tool does not match");
+assert.deepStrictEqual(tools.matchTools("zzzznomatchatall"), [], "no terms hit → empty match");
+assert.deepStrictEqual(tools.matchTools(""), [], "empty query → empty match");
+
+// ── recordRun telemetry: bumps runCount + stamps lastUsed, visible via readUsage
+//    and surfaced on the tool record itself ──
+assert.strictEqual(tools.findTool("hello").runCount, 0, "fresh tool has runCount 0");
+tools.recordRun("hello");
+assert.strictEqual(tools.readUsage().hello.runCount, 1, "recordRun bumps the usage sidecar");
+assert.ok(tools.readUsage().hello.lastUsed, "recordRun stamps lastUsed");
+assert.strictEqual(tools.findTool("hello").runCount, 1, "runCount surfaces on the tool record");
+tools.recordRun("hello");
+assert.strictEqual(tools.findTool("hello").runCount, 2, "a second run increments again");
+
+// ── matchTools tie-break: equal score → more-run tool ranks first ──
+for (const n of ["alpha", "beta"]) {
+  const s = path.join(tmp, `${n}.sh`);
+  fs.writeFileSync(s, "#!/usr/bin/env bash\necho x\n");
+  tools.addTool(s, { name: n, description: "common widget gadget" });
+}
+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");