toolfunnel 0.7.0 → 0.8.0

package/src/tools/registry.js

@@ -1,661 +1,607 @@
-'use strict';
-
-/**
- * registry.js - the dynamic, persisted Tool Register.
- *
- * This is distinct from the in-memory
- * catalogue of tools handed to a backend at connect time. THIS one is the
- * structured, on-disk register the lean meta-tools (toolfunnel_list_tools /
- * toolfunnel_tool_instructions / toolfunnel_run_tool) read every call - so register edits
- * are visible with no reconnect ("no restart for register changes").
- *
- * Register entry shape (tools.register.json -> { version, description, tools:[] }):
- *   { id, name, summary, category, instructions, invoke, mode? }
- *   invoke is one of:
- *     { type: "script", path: "scripts/<file>" }   // run a host-local script
- *     { type: "shell",  command: "..." }            // run a shell command
- *   mode (optional) is one of:
- *     "gateway"   - execute the invoke server-side via the gated run path (default for
- *                   a script/shell invoke; the original behaviour).
- *     "reference" - do NOT execute; toolfunnel_run_tool returns the instructions so the
- *                   connected AI runs the action itself. invoke may be omitted.
- *   When mode is absent it is inferred: script/shell invoke -> "gateway", else "reference".
- *
- * Responsibilities:
- *   list({filter?, category?})  -> briefs only [{id,name,summary,category}]
- *   instructions(id)            -> the full instructions string (throws on unknown)
- *   getEntry(id)                -> the full entry (clone; throws on unknown)
- *   add(entry) / update(id,patch) / remove(id)  -> mutate + ATOMIC persist
- *   resolveExecution(id, args)  -> { type, run: () => Promise<result> }
- *                                  describes HOW to run the invoke. It does NOT
- *                                  gate - gating is gated-run.js's job.
- *
- * Pure-ish: the registry only touches its own JSON file + (for script invokes)
- * spawns node on a path resolved under this src/tools dir. Dependencies that a
- * test may want to stub (the executor) are injectable.
- *
- * CommonJS, Node built-ins only, atomic writes (temp + rename).
- */
-
-const fs = require('node:fs');
-const path = require('node:path');
-const { spawn, execFile } = require('node:child_process');
-const reaper = require('../core/child-reaper');
-const { migrateForStoreFile } = require('../core/rename-migration');
-
-// LOCAL tool execution bounds (0.7.0). The upstream path has had per-method timeouts since 0.6.0;
-// the local executor had none, and stdio serialises on one promise chain, so a hanging local tool
-// starved every later request (including `ping`, which clients use as a liveness probe). 120 s
-// matches the upstream PAYLOAD window so a slow-but-alive local tool behaves like a slow upstream.
-// Test seam: the suite proves the timeout/cap BEHAVIOUR (not just these names) by shrinking the
-// windows via env; production never sets them.
-const TOOL_TIMEOUT_MS = Number(process.env.TOOLFUNNEL_TOOL_TIMEOUT_MS) > 0
-  ? Number(process.env.TOOLFUNNEL_TOOL_TIMEOUT_MS) : 120000;
-const MAX_TOOL_OUTPUT_BYTES = Number(process.env.TOOLFUNNEL_TOOL_OUTPUT_CAP) > 0
-  ? Number(process.env.TOOLFUNNEL_TOOL_OUTPUT_CAP) : 4 * 1024 * 1024;
-
-/**
- * Kill a spawned child AND its descendants, by each platform's own mechanism: taskkill /T on
- * Windows, the process group on POSIX (the spawn sets `detached` there so the child leads one).
- * Killing only the direct child orphans grandchildren, which then hold the stdio pipes open.
- * Best-effort and never throws.
- * @param {import('node:child_process').ChildProcess} child
- */
-function killTree(child) {
-  if (!child) return;
-  try {
-    if (child.pid != null && process.platform === 'win32') {
-      execFile('taskkill', ['/pid', String(child.pid), '/T', '/F'], () => {});
-    } else if (child.pid != null) {
-      try { process.kill(-child.pid, 'SIGKILL'); } catch (_eg) { child.kill('SIGKILL'); }
-    } else {
-      child.kill('SIGKILL');
-    }
-  } catch (_e) {
-    try { child.kill(); } catch (_e2) { /* nothing more we can do */ }
-  }
-}
-
-const VALID_INVOKE_TYPES = new Set(['script', 'shell']);
-
-/**
- * Execution modes (optional per-entry "mode" field):
- *   "gateway"   - ToolFunnel EXECUTES the invoke server-side through the gated run path
- *                 (the original behaviour for every script/shell tool).
- *   "reference" - ToolFunnel does NOT execute. toolfunnel_run_tool returns the tool's
- *                 instructions so the connected AI performs the action in ITS OWN
- *                 environment. A reference tool needs no invoke (nothing runs here).
- */
-const VALID_MODES = new Set(['reference', 'gateway']);
-
-/**
- * Resolve an entry's execution mode. An explicit, valid `mode` wins. When absent it is
- * INFERRED backward-compatibly: a script/shell invoke means "gateway" (run it here, as
- * every existing tool does); anything else means "reference" (there is nothing to run).
- * @param {object} entry a register entry
- * @returns {"gateway"|"reference"}
- */
-function resolveMode(entry) {
-  if (entry && (entry.mode === 'reference' || entry.mode === 'gateway')) return entry.mode;
-  const t = entry && entry.invoke && entry.invoke.type;
-  return t === 'script' || t === 'shell' ? 'gateway' : 'reference';
-}
-
-/** Deep-ish clone for plain JSON entries (structuredClone may be absent on old node). */
-function cloneEntry(entry) {
-  return JSON.parse(JSON.stringify(entry));
-}
-
-/**
- * A sibling temp older than this is a STRANDING (a crashed/killed writer), not an
- * in-flight write - a live writer's temp exists for milliseconds. Swept on the next
- * successful write of the same target; the generous age keeps a concurrent writer safe.
- */
-const STALE_TMP_MS = 60 * 60 * 1000;
-
-/**
- * Remove STALE stranded temps for `base` in `dir` (the `.<base>.<pid>.<ts>.tmp` shape the
- * atomic writers below produce). Scoped to the target's own temp shape - never another
- * file's - and entirely best-effort: sweeping must never fail a write.
- */
-function sweepStaleTmp(dir, base) {
-  let names;
-  try { names = fs.readdirSync(dir); } catch (_e) { return; }
-  const prefix = `.${base}.`;
-  const now = Date.now();
-  for (const name of names) {
-    if (!name.startsWith(prefix) || !name.endsWith('.tmp')) continue;
-    const p = path.join(dir, name);
-    try {
-      if (now - fs.statSync(p).mtimeMs > STALE_TMP_MS) fs.unlinkSync(p);
-    } catch (_e) { /* a concurrent writer renamed/removed it - fine */ }
-  }
-}
-
-/**
- * Atomic write: serialise to a temp file in the SAME directory as the target
- * (so rename is atomic on the same filesystem/drive), fsync, then rename over
- * the target. A crash leaves either the old file or the new file, never a
- * half-written register. The temp NEVER outlives a failure: any throw (a refused
- * rename - win32 scanners hold targets briefly - a full disk, a write error)
- * unlinks it before rethrowing, and stale strandings from writers that died
- * mid-flight are swept on the next successful write (sweepStaleTmp above).
- */
-function atomicWriteJson(targetPath, obj) {
-  const dir = path.dirname(targetPath);
-  const base = path.basename(targetPath);
-  sweepStaleTmp(dir, base);
-  const tmp = path.join(dir, `.${base}.${process.pid}.${Date.now()}.tmp`);
-  const data = JSON.stringify(obj, null, 2) + '\n';
-  try {
-    const fd = fs.openSync(tmp, 'w');
-    try {
-      fs.writeSync(fd, data, 0, 'utf8');
-      fs.fsyncSync(fd);
-    } finally {
-      fs.closeSync(fd);
-    }
-    fs.renameSync(tmp, targetPath);
-  } catch (err) {
-    try { fs.unlinkSync(tmp); } catch (_e) { /* best-effort - the error below is the story */ }
-    throw err;
-  }
-}
-
-/** Validate a register entry shape; throws with a clear message on a bad shape. */
-function validateEntry(entry, { requireId = true } = {}) {
-  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
-    throw new Error('Registry: entry must be an object');
-  }
-  if (requireId && (typeof entry.id !== 'string' || entry.id.length === 0)) {
-    throw new Error('Registry: entry.id must be a non-empty string');
-  }
-  if (typeof entry.name !== 'string' || entry.name.length === 0) {
-    throw new Error(`Registry: entry.name must be a non-empty string (id=${entry.id})`);
-  }
-  // Optional execution mode. When present it must be one of the valid modes.
-  if (entry.mode !== undefined && !VALID_MODES.has(entry.mode)) {
-    throw new Error(
-      `Registry: entry.mode must be one of ${[...VALID_MODES].join('|')} (id=${entry.id})`
-    );
-  }
-  // A reference tool executes nothing server-side, so its invoke may be omitted. Only an
-  // EXPLICIT mode:"reference" relaxes this - with mode absent the invoke is still required
-  // (backward-compatible: every existing tool keeps its mandatory invoke).
-  if (entry.mode === 'reference' && entry.invoke === undefined) {
-    return entry;
-  }
-  const inv = entry.invoke;
-  if (!inv || typeof inv !== 'object') {
-    throw new Error(`Registry: entry.invoke is required (id=${entry.id})`);
-  }
-  if (!VALID_INVOKE_TYPES.has(inv.type)) {
-    throw new Error(
-      `Registry: entry.invoke.type must be one of ${[...VALID_INVOKE_TYPES].join('|')} (id=${entry.id})`
-    );
-  }
-  if (inv.type === 'script' && (typeof inv.path !== 'string' || inv.path.length === 0)) {
-    throw new Error(`Registry: script invoke needs a non-empty "path" (id=${entry.id})`);
-  }
-  if (inv.type === 'shell' && (typeof inv.command !== 'string' || inv.command.length === 0)) {
-    throw new Error(`Registry: shell invoke needs a non-empty "command" (id=${entry.id})`);
-  }
-  // Optional MCP input schema. When present it must be a plain object - a hot-promoted tool
-  // advertises it VERBATIM to MCP clients (tools/list), so a typo'd shape must fail loudly at
-  // authoring time rather than silently degrade to the free-form fallback at surface time.
-  if (
-    entry.inputSchema !== undefined &&
-    (typeof entry.inputSchema !== 'object' || entry.inputSchema === null || Array.isArray(entry.inputSchema))
-  ) {
-    throw new Error(`Registry: entry.inputSchema must be an object when present (id=${entry.id})`);
-  }
-  return entry;
-}
-
-/**
- * Default script executor: spawn `node <resolved script>` with the structured
- * args passed in env TOOLFUNNEL_TOOL_ARGS. Resolves with { ok, code, stdout, stderr }.
- * Never rejects on a non-zero exit - the caller (the gated runner / meta-tool)
- * decides how to surface a tool failure. It DOES reject only on spawn failure.
- *
- * Path safety: the script path must resolve INSIDE scriptsRoot (defense-in-depth
- * for the isolation rule - a register entry must not become a path-escape).
- */
-function defaultRunScript(scriptsRoot, invoke, args) {
-  return new Promise((resolve, reject) => {
-    const resolved = path.resolve(scriptsRoot, path.basename(invoke.path));
-    // path.basename strips any directory traversal; confirm anyway.
-    const rel = path.relative(scriptsRoot, resolved);
-    if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
-      reject(new Error(`Registry: script path escapes scripts root ("${invoke.path}")`));
-      return;
-    }
-    if (!fs.existsSync(resolved)) {
-      reject(new Error(`Registry: script not found ("${resolved}")`));
-      return;
-    }
-    const child = spawn(process.execPath, [resolved], {
-      env: { ...process.env, TOOLFUNNEL_TOOL_ARGS: JSON.stringify(args ?? null) },
-      stdio: ['ignore', 'pipe', 'pipe'],
-      windowsHide: true,
-      // POSIX process group so the timeout below can kill a whole tree; Windows uses taskkill /T.
-      detached: process.platform !== 'win32',
-    });
-    reaper.track(child); // last-resort sweep if the gateway dies without its kill path
-    let stdout = '';
-    let stderr = '';
-    let settled = false;
-    // BOUNDED + TIMED (0.7.0). The upstream call path has had per-method windows since 0.6.0
-    // (10 s control / 120 s payload) but the LOCAL executor had no clock and no output cap at all,
-    // and stdio serialises every message on one promise chain - so a single hanging local tool
-    // wedged the entire session: measured 2026-07-30, a 40 s tool left a following `ping` and
-    // `tools/list` unanswered for 12 s+, which a client using ping as its liveness probe reads as
-    // a dead gateway. Same shape as the fix in core/hook-runner.js.
-    const finish = (result) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      // Release the pipes and unref the handle - the ChildProcess itself keeps the event loop
-      // referenced until the child exits, so a tree that survives killTree would otherwise pin
-      // the process after we have already answered (same fix as core/hook-runner.js).
-      for (const s of [child.stdout, child.stderr]) {
-        try { if (s && typeof s.destroy === 'function') s.destroy(); } catch (_e) { /* ignore */ }
-      }
-      try { if (typeof child.unref === 'function') child.unref(); } catch (_e) { /* ignore */ }
-      reaper.untrack(child);
-      resolve(result);
-    };
-    const timer = setTimeout(() => {
-      killTree(child);
-      finish({
-        ok: false,
-        code: null,
-        stdout,
-        stderr: (stderr ? stderr + '\n' : '')
-          + `Registry: tool script timed out after ${TOOL_TIMEOUT_MS}ms and was terminated`,
-        timedOut: true,
-      });
-    }, TOOL_TIMEOUT_MS);
-    if (typeof timer.unref === 'function') timer.unref();
-    // setEncoding so a multi-byte UTF-8 sequence split across chunks decodes correctly (a raw
-    // d.toString() per chunk yields U+FFFD at the boundary), and count REAL bytes - String.length
-    // is UTF-16 code units, letting non-ASCII output run ~3x past a "byte" cap.
-    child.stdout.setEncoding('utf8');
-    child.stderr.setEncoding('utf8');
-    let outBytes = 0;
-    let errBytes = 0;
-    child.stdout.on('data', (d) => {
-      if (outBytes >= MAX_TOOL_OUTPUT_BYTES) return;
-      stdout += d;
-      outBytes += Buffer.byteLength(d, 'utf8');
-      if (outBytes >= MAX_TOOL_OUTPUT_BYTES) {
-        killTree(child);
-        finish({ ok: false, code: null, stdout, stderr: stderr + '\nRegistry: tool output exceeded the cap and was terminated', outputCapped: true });
-      }
-    });
-    child.stderr.on('data', (d) => {
-      if (errBytes >= MAX_TOOL_OUTPUT_BYTES) return;
-      stderr += d;
-      errBytes += Buffer.byteLength(d, 'utf8');
-    });
-    child.on('error', (err) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      reaper.untrack(child);
-      reject(err);
-    });
-    child.on('close', (code) => {
-      finish({ ok: code === 0, code, stdout, stderr });
-    });
-  });
-}
-
-class Registry {
-  /**
-   * @param {object} opts
-   * @param {string} opts.filePath          path to tools.register.json (source of truth on disk)
-   * @param {object} opts.data              parsed register data { version, description, tools }
-   * @param {string} [opts.scriptsRoot]     dir holding script-invoke targets (default: <fileDir>/scripts)
-   * @param {Function} [opts.runScript]     injectable (scriptsRoot, invoke, args) => Promise<result>
-   */
-  constructor({ filePath, data, scriptsRoot, runScript } = {}) {
-    if (!filePath) throw new Error('Registry: filePath is required');
-    this._filePath = filePath;
-    this._scriptsRoot = scriptsRoot || path.join(path.dirname(filePath), 'scripts');
-    this._runScript = runScript || defaultRunScript;
-
-    const d = data && typeof data === 'object' ? data : {};
-    this._version = typeof d.version === 'number' ? d.version : 1;
-    this._description = typeof d.description === 'string' ? d.description : '';
-    const tools = Array.isArray(d.tools) ? d.tools : [];
-
-    // Index by id; reject duplicate ids at load (a duplicate id makes
-    // instructions(id)/run(id) ambiguous).
-    this._byId = new Map();
-    for (const t of tools) {
-      validateEntry(t);
-      if (this._byId.has(t.id)) {
-        throw new Error(`Registry: duplicate tool id "${t.id}" in ${filePath}`);
-      }
-      this._byId.set(t.id, cloneEntry(t));
-    }
-  }
-
-  // ---- read API -----------------------------------------------------------
-
-  /**
-   * Briefs only - the surface toolfunnel_list_tools returns. Optional case-insensitive
-   * substring `filter` (matched against id/name/summary) and exact `category`.
-   * @returns {Array<{id,name,summary,category}>} in insertion order.
-   */
-  list({ filter, category } = {}) {
-    const needle = typeof filter === 'string' && filter.length ? filter.toLowerCase() : null;
-    const out = [];
-    for (const t of this._byId.values()) {
-      if (category && t.category !== category) continue;
-      if (needle) {
-        const hay = `${t.id} ${t.name} ${t.summary || ''}`.toLowerCase();
-        if (!hay.includes(needle)) continue;
-      }
-      out.push({
-        id: t.id,
-        name: t.name,
-        summary: t.summary || '',
-        category: t.category || '',
-      });
-    }
-    return out;
-  }
-
-  /** Full instructions string for one tool. Throws on unknown id. */
-  instructions(id) {
-    const t = this._byId.get(id);
-    if (!t) throw new Error(`Registry.instructions: unknown tool id "${id}"`);
-    return typeof t.instructions === 'string' ? t.instructions : '';
-  }
-
-  /** Full entry (cloned so callers can't mutate internal state). Throws on unknown id. */
-  getEntry(id) {
-    const t = this._byId.get(id);
-    if (!t) throw new Error(`Registry.getEntry: unknown tool id "${id}"`);
-    return cloneEntry(t);
-  }
-
-  /** @returns {boolean} */
-  has(id) {
-    return this._byId.has(id);
-  }
-
-  // ---- write API (atomic persist) ----------------------------------------
-
-  /** Add a new entry. Throws if id missing/duplicate or shape invalid. Persists. */
-  add(entry) {
-    validateEntry(entry);
-    if (this._byId.has(entry.id)) {
-      throw new Error(`Registry.add: tool id "${entry.id}" already exists`);
-    }
-    this._byId.set(entry.id, cloneEntry(entry));
-    this._persist();
-    return this.getEntry(entry.id);
-  }
-
-  /**
-   * Patch an existing entry. `id` cannot be changed via patch (it's the key).
-   * Merges shallow over the existing entry, re-validates, persists.
-   */
-  update(id, patch) {
-    const existing = this._byId.get(id);
-    if (!existing) throw new Error(`Registry.update: unknown tool id "${id}"`);
-    if (!patch || typeof patch !== 'object') {
-      throw new Error('Registry.update: patch must be an object');
-    }
-    const merged = { ...existing, ...patch, id };
-    validateEntry(merged);
-    // Rename-safety: the gate fires on `entry.name || id` for BOTH the direct and
-    // lean paths - a display-name edit renames that surface, so gate matchers must follow (or
-    // the rename refuses). The tools.state.json key must NOT: a LOCAL tool's overlay is keyed by
-    // its immutable register ID, not its display name (migrateState:false; see the namespace note
-    // in rename-migration.js). Runs BEFORE persist so a refusal leaves the register untouched.
-    const oldSurfaced = existing.name || id;
-    const newSurfaced = merged.name || id;
-    if (oldSurfaced !== newSurfaced) {
-      migrateForStoreFile(this._filePath, oldSurfaced, newSurfaced, { migrateState: false });
-    }
-    this._byId.set(id, cloneEntry(merged));
-    this._persist();
-    return this.getEntry(id);
-  }
-
-  /** Remove an entry. Throws on unknown id. Persists. */
-  remove(id) {
-    if (!this._byId.has(id)) throw new Error(`Registry.remove: unknown tool id "${id}"`);
-    this._byId.delete(id);
-    this._persist();
-    return true;
-  }
-
-  /**
-   * Re-read the register FILE and swap the in-memory index - the hot-reload seam. A running
-   * gateway holds ONE Registry instance (captured by the protocol adapter at build time), while
-   * tf_tool_add / the UI / a hand edit mutate the FILE from another process - without this, those
-   * edits are invisible until restart. LAST-GOOD semantics: the replacement index is built and
-   * fully validated FIRST; any read/parse/validation failure (including a mid-write partial file)
-   * leaves the current index untouched and returns false. NEVER throws.
-   * @returns {boolean} true when the on-disk register replaced the in-memory index
-   */
-  reload() {
-    let data;
-    try {
-      data = JSON.parse(fs.readFileSync(this._filePath, 'utf8'));
-    } catch (_e) {
-      return false; // unreadable / mid-write / bad JSON -> keep last-good
-    }
-    if (!data || typeof data !== 'object' || Array.isArray(data)) return false;
-    const tools = Array.isArray(data.tools) ? data.tools : [];
-    const next = new Map();
-    try {
-      for (const t of tools) {
-        validateEntry(t);
-        if (next.has(t.id)) throw new Error(`duplicate tool id "${t.id}"`);
-        next.set(t.id, cloneEntry(t));
-      }
-    } catch (_e) {
-      return false; // an invalid entry -> keep last-good
-    }
-    if (typeof data.version === 'number') this._version = data.version;
-    if (typeof data.description === 'string') this._description = data.description;
-    this._byId = next;
-    return true;
-  }
-
-  /**
-   * Write a host-local script's text under this scriptsRoot, atomically.
-   *
-   * Resolves path.basename(invokePath) under scriptsRoot (basename strips any
-   * directory traversal) and GUARDS that the resolved path stays inside
-   * scriptsRoot - the same path-escape defence as defaultRunScript, so a
-   * tf_tool_add(scriptText) can never write outside the isolation root. Writes
-   * `text` via a temp file in the same dir + fsync + rename (mirror of
-   * atomicWriteJson): a crash leaves either no file or the complete file.
-   *
-   * @param {string} invokePath  e.g. "scripts/foo.js" - only the basename is honoured
-   * @param {string} text        full file contents to write
-   * @returns {string} the resolved absolute path that was written
-   */
-  writeScript(invokePath, text) {
-    if (typeof invokePath !== 'string' || invokePath.length === 0) {
-      throw new Error('Registry.writeScript: invokePath (non-empty string) is required');
-    }
-    if (typeof text !== 'string') {
-      throw new Error('Registry.writeScript: text must be a string');
-    }
-    const scriptsRoot = this._scriptsRoot;
-    const resolved = path.resolve(scriptsRoot, path.basename(invokePath));
-    // path.basename strips any directory traversal; confirm anyway.
-    const rel = path.relative(scriptsRoot, resolved);
-    if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
-      throw new Error(`Registry.writeScript: script path escapes scripts root ("${invokePath}")`);
-    }
-    fs.mkdirSync(scriptsRoot, { recursive: true });
-    const dir = path.dirname(resolved);
-    const base = path.basename(resolved);
-    sweepStaleTmp(dir, base);
-    const tmp = path.join(dir, `.${base}.${process.pid}.${Date.now()}.tmp`);
-    try {
-      const fd = fs.openSync(tmp, 'w');
-      try {
-        fs.writeSync(fd, text, 0, 'utf8');
-        fs.fsyncSync(fd);
-      } finally {
-        fs.closeSync(fd);
-      }
-      fs.renameSync(tmp, resolved);
-    } catch (err) {
-      try { fs.unlinkSync(tmp); } catch (_e) { /* best-effort - the error below is the story */ }
-      throw err;
-    }
-    return resolved;
-  }
-
-  // ---- execution description (does NOT gate) ------------------------------
-
-  /**
-   * Describe HOW to run a tool's invoke. Returns { type, run } where `run` is a
-   * zero-arg function returning a Promise of the tool result. resolveExecution
-   * performs NO gating - toolfunnel_run_tool / gated-run.js fires the PreToolUse hook
-   * and only then calls `run()`. Keeping the gate
-   * out of here keeps the safety case in one auditable place.
-   *
-   * - script invoke: run() spawns node on the host-local script (via the injected
-   *   runScript), passing args in TOOLFUNNEL_TOOL_ARGS.
-   * - shell invoke: run() does NOT execute here. It returns a descriptor
-   *   { type:'shell', command, args } so the gated runner owns the actual shell
-   *   spawn (the broadest power) behind the gate. This keeps arbitrary shell
-   *   execution out of the un-gated register module by design.
-   *
-   * @param {string} id
-   * @param {any} args  structured args forwarded to the tool
-   * @returns {{ type: string, run: () => Promise<any> }}
-   */
-  resolveExecution(id, args) {
-    const entry = this._byId.get(id);
-    if (!entry) throw new Error(`Registry.resolveExecution: unknown tool id "${id}"`);
-    const mode = resolveMode(entry);
-
-    // ---- reference mode: nothing runs here. ----------------------------------
-    // The connected AI performs the action in its own environment. We hand back the
-    // tool's instructions (no `run`) so the run-path takes the no-spawn branch - a
-    // reference tool never spawns server-side. The instruction HANDOFF is still gated
-    // in protocol.runTool (a PreToolUse deny withholds the instructions); it's execution,
-    // not the gate, that's absent here.
-    if (mode === 'reference') {
-      return {
-        type: 'reference',
-        mode: 'reference',
-        instructions: typeof entry.instructions === 'string' ? entry.instructions : '',
-      };
-    }
-
-    const invoke = entry.invoke;
-
-    if (invoke.type === 'script') {
-      const scriptsRoot = this._scriptsRoot;
-      const runScript = this._runScript;
-      return {
-        type: 'script',
-        mode: 'gateway',
-        run: () => runScript(scriptsRoot, invoke, args),
-      };
-    }
-
-    if (invoke.type === 'shell') {
-      // Deliberately do NOT spawn a shell here. Hand the descriptor to the
-      // gated runner, which executes shell only after PreToolUse allows it.
-      return {
-        type: 'shell',
-        mode: 'gateway',
-        run: async () => ({
-          deferred: true,
-          type: 'shell',
-          command: invoke.command,
-          args: args ?? null,
-        }),
-      };
-    }
-
-    // validateEntry guards the load path, but guard here too for late mutation.
-    throw new Error(`Registry.resolveExecution: unsupported invoke.type for "${id}"`);
-  }
-
-  /**
-   * The resolved execution mode for a tool ("gateway" | "reference"). Exposed so callers
-   * (UI, tests) can ask without resolving a full executor. Throws on unknown id.
-   * @param {string} id
-   * @returns {"gateway"|"reference"}
-   */
-  mode(id) {
-    const entry = this._byId.get(id);
-    if (!entry) throw new Error(`Registry.mode: unknown tool id "${id}"`);
-    return resolveMode(entry);
-  }
-
-  // ---- internals ----------------------------------------------------------
-
-  /** Serialise current state back to the register file atomically. */
-  _persist() {
-    const obj = {
-      version: this._version,
-      description: this._description,
-      tools: [...this._byId.values()],
-    };
-    atomicWriteJson(this._filePath, obj);
-  }
-
-  /** @returns {number} */
-  get size() {
-    return this._byId.size;
-  }
-}
-
-/**
- * loadRegistry(path) -> Registry
- *
- * Reads + parses the register JSON at `filePath` and returns a Registry bound to
- * it. Throws a clear error on a missing/malformed file or a bad entry shape so
- * misconfiguration is caught at load time, not at model-call time.
- *
- * @param {string} filePath
- * @param {object} [opts]  forwarded to the Registry ctor (scriptsRoot, runScript)
- * @returns {Registry}
- */
-function loadRegistry(filePath, opts = {}) {
-  if (typeof filePath !== 'string' || filePath.length === 0) {
-    throw new Error('loadRegistry: filePath (non-empty string) is required');
-  }
-  let raw;
-  try {
-    raw = fs.readFileSync(filePath, 'utf8');
-  } catch (err) {
-    throw new Error(`loadRegistry: cannot read register at "${filePath}": ${err.message}`);
-  }
-  let data;
-  try {
-    data = JSON.parse(raw);
-  } catch (err) {
-    throw new Error(`loadRegistry: register at "${filePath}" is not valid JSON: ${err.message}`);
-  }
-  return new Registry({ filePath, data, ...opts });
-}
-
-module.exports = {
-  Registry,
-  loadRegistry,
-  // exported for unit tests / the gated runner
-  atomicWriteJson,
-  validateEntry,
-  defaultRunScript,
-  resolveMode,
-  VALID_INVOKE_TYPES,
-  VALID_MODES,
-};
+'use strict';
+
+/**
+ * registry.js - the dynamic, persisted Tool Register.
+ *
+ * This is distinct from the in-memory
+ * catalogue of tools handed to a backend at connect time. THIS one is the
+ * structured, on-disk register the lean meta-tools (toolfunnel_list_tools /
+ * toolfunnel_tool_instructions / toolfunnel_run_tool) read every call - so register edits
+ * are visible with no reconnect ("no restart for register changes").
+ *
+ * Register entry shape (tools.register.json -> { version, description, tools:[] }):
+ *   { id, name, summary, category, instructions, invoke, mode? }
+ *   invoke is one of:
+ *     { type: "script", path: "scripts/<file>" }   // run a host-local script
+ *     { type: "shell",  command: "..." }            // run a shell command
+ *   mode (optional) is one of:
+ *     "gateway"   - execute the invoke server-side via the gated run path (default for
+ *                   a script/shell invoke; the original behaviour).
+ *     "reference" - do NOT execute; toolfunnel_run_tool returns the instructions so the
+ *                   connected AI runs the action itself. invoke may be omitted.
+ *   When mode is absent it is inferred: script/shell invoke -> "gateway", else "reference".
+ *
+ * Responsibilities:
+ *   list({filter?, category?})  -> briefs only [{id,name,summary,category}]
+ *   instructions(id)            -> the full instructions string (throws on unknown)
+ *   getEntry(id)                -> the full entry (clone; throws on unknown)
+ *   add(entry) / update(id,patch) / remove(id)  -> mutate + ATOMIC persist
+ *   resolveExecution(id, args)  -> { type, run: () => Promise<result> }
+ *                                  describes HOW to run the invoke. It does NOT
+ *                                  gate - gating is gated-run.js's job.
+ *
+ * Pure-ish: the registry only touches its own JSON file + (for script invokes)
+ * spawns node on a path resolved under this src/tools dir. Dependencies that a
+ * test may want to stub (the executor) are injectable.
+ *
+ * CommonJS, Node built-ins only, atomic writes (temp + rename).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawn, execFile } = require('node:child_process');
+const reaper = require('../core/child-reaper');
+const { takeWithinCap } = require('../core/output-cap');
+const { migrateForStoreFile, snapshotForStoreFile, restoreSnapshot } = require('../core/rename-migration');
+
+// LOCAL tool execution bounds. The upstream path has per-method timeouts; stdio serialises on one
+// promise chain, so a local tool with no clock would starve every later request (including
+// `ping`, which clients use as a liveness probe). 120 s
+// matches the upstream PAYLOAD window so a slow-but-alive local tool behaves like a slow upstream.
+// Test seam: the suite proves the timeout/cap BEHAVIOUR (not just these names) by shrinking the
+// windows via env; production never sets them.
+const TOOL_TIMEOUT_MS = Number(process.env.TOOLFUNNEL_TOOL_TIMEOUT_MS) > 0
+  ? Number(process.env.TOOLFUNNEL_TOOL_TIMEOUT_MS) : 120000;
+const MAX_TOOL_OUTPUT_BYTES = Number(process.env.TOOLFUNNEL_TOOL_OUTPUT_CAP) > 0
+  ? Number(process.env.TOOLFUNNEL_TOOL_OUTPUT_CAP) : 4 * 1024 * 1024;
+
+/**
+ * Kill a spawned child AND its descendants, by each platform's own mechanism: taskkill /T on
+ * Windows, the process group on POSIX (the spawn sets `detached` there so the child leads one).
+ * Killing only the direct child orphans grandchildren, which then hold the stdio pipes open.
+ * Best-effort and never throws.
+ * @param {import('node:child_process').ChildProcess} child
+ */
+function killTree(child) {
+  if (!child) return;
+  try {
+    if (child.pid != null && process.platform === 'win32') {
+      execFile('taskkill', ['/pid', String(child.pid), '/T', '/F'], () => {});
+    } else if (child.pid != null) {
+      try { process.kill(-child.pid, 'SIGKILL'); } catch (_eg) { child.kill('SIGKILL'); }
+    } else {
+      child.kill('SIGKILL');
+    }
+  } catch (_e) {
+    try { child.kill(); } catch (_e2) { /* nothing more we can do */ }
+  }
+}
+
+const VALID_INVOKE_TYPES = new Set(['script', 'shell']);
+
+/**
+ * Execution modes (optional per-entry "mode" field):
+ *   "gateway"   - ToolFunnel EXECUTES the invoke server-side through the gated run path
+ *                 (the original behaviour for every script/shell tool).
+ *   "reference" - ToolFunnel does NOT execute. toolfunnel_run_tool returns the tool's
+ *                 instructions so the connected AI performs the action in ITS OWN
+ *                 environment. A reference tool needs no invoke (nothing runs here).
+ */
+const VALID_MODES = new Set(['reference', 'gateway']);
+
+/**
+ * Resolve an entry's execution mode. An explicit, valid `mode` wins. When absent it is
+ * INFERRED backward-compatibly: a script/shell invoke means "gateway" (run it here, as
+ * every existing tool does); anything else means "reference" (there is nothing to run).
+ * @param {object} entry a register entry
+ * @returns {"gateway"|"reference"}
+ */
+function resolveMode(entry) {
+  if (entry && (entry.mode === 'reference' || entry.mode === 'gateway')) return entry.mode;
+  const t = entry && entry.invoke && entry.invoke.type;
+  return t === 'script' || t === 'shell' ? 'gateway' : 'reference';
+}
+
+/** Deep-ish clone for plain JSON entries (structuredClone may be absent on old node). */
+function cloneEntry(entry) {
+  return JSON.parse(JSON.stringify(entry));
+}
+
+// THE atomic writer (temp + fsync + rename, failure-path unlink, stale sweep) - shared by every store.
+// Re-exported below for the callers that historically imported it from here.
+const { atomicWriteJson, atomicWriteText } = require('../core/atomic-write');
+
+/** Validate a register entry shape; throws with a clear message on a bad shape. */
+function validateEntry(entry, { requireId = true } = {}) {
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+    throw new Error('Registry: entry must be an object');
+  }
+  if (requireId && (typeof entry.id !== 'string' || entry.id.length === 0)) {
+    throw new Error('Registry: entry.id must be a non-empty string');
+  }
+  if (typeof entry.name !== 'string' || entry.name.length === 0) {
+    throw new Error(`Registry: entry.name must be a non-empty string (id=${entry.id})`);
+  }
+  // Optional execution mode. When present it must be one of the valid modes.
+  if (entry.mode !== undefined && !VALID_MODES.has(entry.mode)) {
+    throw new Error(
+      `Registry: entry.mode must be one of ${[...VALID_MODES].join('|')} (id=${entry.id})`
+    );
+  }
+  // A reference tool executes nothing server-side, so its invoke may be omitted. Only an
+  // EXPLICIT mode:"reference" relaxes this - with mode absent the invoke is still required
+  // (backward-compatible: every existing tool keeps its mandatory invoke).
+  if (entry.mode === 'reference' && entry.invoke === undefined) {
+    return entry;
+  }
+  const inv = entry.invoke;
+  if (!inv || typeof inv !== 'object') {
+    throw new Error(`Registry: entry.invoke is required (id=${entry.id})`);
+  }
+  if (!VALID_INVOKE_TYPES.has(inv.type)) {
+    throw new Error(
+      `Registry: entry.invoke.type must be one of ${[...VALID_INVOKE_TYPES].join('|')} (id=${entry.id})`
+    );
+  }
+  if (inv.type === 'script' && (typeof inv.path !== 'string' || inv.path.length === 0)) {
+    throw new Error(`Registry: script invoke needs a non-empty "path" (id=${entry.id})`);
+  }
+  if (inv.type === 'shell' && (typeof inv.command !== 'string' || inv.command.length === 0)) {
+    throw new Error(`Registry: shell invoke needs a non-empty "command" (id=${entry.id})`);
+  }
+  // Optional MCP input schema. When present it must be a plain object - a hot-promoted tool
+  // advertises it VERBATIM to MCP clients (tools/list), so a typo'd shape must fail loudly at
+  // authoring time rather than silently degrade to the free-form fallback at surface time.
+  if (
+    entry.inputSchema !== undefined &&
+    (typeof entry.inputSchema !== 'object' || entry.inputSchema === null || Array.isArray(entry.inputSchema))
+  ) {
+    throw new Error(`Registry: entry.inputSchema must be an object when present (id=${entry.id})`);
+  }
+  return entry;
+}
+
+/**
+ * Default script executor: spawn `node <resolved script>` with the structured
+ * args passed in env TOOLFUNNEL_TOOL_ARGS. Resolves with { ok, code, stdout, stderr }.
+ * Never rejects on a non-zero exit - the caller (the gated runner / meta-tool)
+ * decides how to surface a tool failure. It DOES reject only on spawn failure.
+ *
+ * Path safety: the script path must resolve INSIDE scriptsRoot (defense-in-depth
+ * for the isolation rule - a register entry must not become a path-escape).
+ */
+function defaultRunScript(scriptsRoot, invoke, args) {
+  return new Promise((resolve, reject) => {
+    const resolved = path.resolve(scriptsRoot, path.basename(invoke.path));
+    // path.basename strips any directory traversal; confirm anyway.
+    const rel = path.relative(scriptsRoot, resolved);
+    if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
+      reject(new Error(`Registry: script path escapes scripts root ("${invoke.path}")`));
+      return;
+    }
+    if (!fs.existsSync(resolved)) {
+      reject(new Error(`Registry: script not found ("${resolved}")`));
+      return;
+    }
+    const child = spawn(process.execPath, [resolved], {
+      env: { ...process.env, TOOLFUNNEL_TOOL_ARGS: JSON.stringify(args ?? null) },
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+      // POSIX process group so the timeout below can kill a whole tree; Windows uses taskkill /T.
+      detached: process.platform !== 'win32',
+    });
+    reaper.track(child); // last-resort sweep if the gateway dies without its kill path
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    // BOUNDED + TIMED, like the upstream call path's per-method windows (10 s control / 120 s
+    // payload). stdio serialises every message on one promise chain, so a single hanging local
+    // tool would wedge the entire session: a following `ping` goes unanswered, which a client
+    // using ping as its liveness probe reads as a dead gateway. Same shape as the timeout in
+    // core/hook-runner.js.
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      // Release the pipes and unref the handle - the ChildProcess itself keeps the event loop
+      // referenced until the child exits, so a tree that survives killTree would otherwise pin
+      // the process after we have already answered (same fix as core/hook-runner.js).
+      for (const s of [child.stdout, child.stderr]) {
+        try { if (s && typeof s.destroy === 'function') s.destroy(); } catch (_e) { /* ignore */ }
+      }
+      try { if (typeof child.unref === 'function') child.unref(); } catch (_e) { /* ignore */ }
+      reaper.untrack(child);
+      resolve(result);
+    };
+    const timer = setTimeout(() => {
+      killTree(child);
+      finish({
+        ok: false,
+        code: null,
+        stdout,
+        stderr: (stderr ? stderr + '\n' : '')
+          + `Registry: tool script timed out after ${TOOL_TIMEOUT_MS}ms and was terminated`,
+        timedOut: true,
+      });
+    }, TOOL_TIMEOUT_MS);
+    if (typeof timer.unref === 'function') timer.unref();
+    // setEncoding so a multi-byte UTF-8 sequence split across chunks decodes correctly (a raw
+    // d.toString() per chunk yields U+FFFD at the boundary), and count REAL bytes - String.length
+    // is UTF-16 code units, letting non-ASCII output run ~3x past a "byte" cap.
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    let outBytes = 0;
+    let errBytes = 0;
+    child.stdout.on('data', (d) => {
+      if (outBytes >= MAX_TOOL_OUTPUT_BYTES) return;
+      const kept = takeWithinCap(d, outBytes, MAX_TOOL_OUTPUT_BYTES);
+      stdout += kept;
+      outBytes += Buffer.byteLength(kept, 'utf8');
+      if (kept.length < d.length) outBytes = MAX_TOOL_OUTPUT_BYTES; // cut at a character: the cap is reached
+      if (outBytes >= MAX_TOOL_OUTPUT_BYTES) {
+        killTree(child);
+        finish({ ok: false, code: null, stdout, stderr: stderr + '\nRegistry: tool output exceeded the cap and was terminated', outputCapped: true });
+      }
+    });
+    child.stderr.on('data', (d) => {
+      if (errBytes >= MAX_TOOL_OUTPUT_BYTES) return;
+      const kept = takeWithinCap(d, errBytes, MAX_TOOL_OUTPUT_BYTES);
+      stderr += kept;
+      errBytes = kept.length < d.length ? MAX_TOOL_OUTPUT_BYTES : errBytes + Buffer.byteLength(kept, 'utf8');
+      if (errBytes >= MAX_TOOL_OUTPUT_BYTES) stderr += '\n[stderr truncated at cap]';
+    });
+    child.on('error', (err) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      reaper.untrack(child);
+      reject(err);
+    });
+    child.on('close', (code) => {
+      finish({ ok: code === 0, code, stdout, stderr });
+    });
+  });
+}
+
+class Registry {
+  /**
+   * @param {object} opts
+   * @param {string} opts.filePath          path to tools.register.json (source of truth on disk)
+   * @param {object} opts.data              parsed register data { version, description, tools }
+   * @param {string} [opts.scriptsRoot]     dir holding script-invoke targets (default: <fileDir>/scripts)
+   * @param {Function} [opts.runScript]     injectable (scriptsRoot, invoke, args) => Promise<result>
+   */
+  constructor({ filePath, data, scriptsRoot, runScript } = {}) {
+    if (!filePath) throw new Error('Registry: filePath is required');
+    this._filePath = filePath;
+    this._scriptsRoot = scriptsRoot || path.join(path.dirname(filePath), 'scripts');
+    this._runScript = runScript || defaultRunScript;
+
+    const d = data && typeof data === 'object' ? data : {};
+    this._version = typeof d.version === 'number' ? d.version : 1;
+    this._description = typeof d.description === 'string' ? d.description : '';
+    const tools = Array.isArray(d.tools) ? d.tools : [];
+
+    // Index by id; reject duplicate ids at load (a duplicate id makes
+    // instructions(id)/run(id) ambiguous).
+    this._byId = new Map();
+    for (const t of tools) {
+      validateEntry(t);
+      if (this._byId.has(t.id)) {
+        throw new Error(`Registry: duplicate tool id "${t.id}" in ${filePath}`);
+      }
+      this._byId.set(t.id, cloneEntry(t));
+    }
+  }
+
+  // ---- read API -----------------------------------------------------------
+
+  /**
+   * Briefs only - the surface toolfunnel_list_tools returns. Optional case-insensitive
+   * substring `filter` (matched against id/name/summary) and exact `category`.
+   * @returns {Array<{id,name,summary,category}>} in insertion order.
+   */
+  list({ filter, category } = {}) {
+    const needle = typeof filter === 'string' && filter.length ? filter.toLowerCase() : null;
+    const out = [];
+    for (const t of this._byId.values()) {
+      if (category && t.category !== category) continue;
+      if (needle) {
+        const hay = `${t.id} ${t.name} ${t.summary || ''}`.toLowerCase();
+        if (!hay.includes(needle)) continue;
+      }
+      out.push({
+        id: t.id,
+        name: t.name,
+        summary: t.summary || '',
+        category: t.category || '',
+      });
+    }
+    return out;
+  }
+
+  /** Full instructions string for one tool. Throws on unknown id. */
+  instructions(id) {
+    const t = this._byId.get(id);
+    if (!t) throw new Error(`Registry.instructions: unknown tool id "${id}"`);
+    return typeof t.instructions === 'string' ? t.instructions : '';
+  }
+
+  /** Full entry (cloned so callers can't mutate internal state). Throws on unknown id. */
+  getEntry(id) {
+    const t = this._byId.get(id);
+    if (!t) throw new Error(`Registry.getEntry: unknown tool id "${id}"`);
+    return cloneEntry(t);
+  }
+
+  /** @returns {boolean} */
+  has(id) {
+    return this._byId.has(id);
+  }
+
+  // ---- write API (atomic persist) ----------------------------------------
+
+  /** Add a new entry. Throws if id missing/duplicate or shape invalid. Persists. */
+  add(entry) {
+    validateEntry(entry);
+    if (this._byId.has(entry.id)) {
+      throw new Error(`Registry.add: tool id "${entry.id}" already exists`);
+    }
+    this._byId.set(entry.id, cloneEntry(entry));
+    this._persist();
+    return this.getEntry(entry.id);
+  }
+
+  /**
+   * Patch an existing entry. `id` cannot be changed via patch (it's the key).
+   * Merges shallow over the existing entry, re-validates, persists.
+   */
+  update(id, patch) {
+    const existing = this._byId.get(id);
+    if (!existing) throw new Error(`Registry.update: unknown tool id "${id}"`);
+    if (!patch || typeof patch !== 'object') {
+      throw new Error('Registry.update: patch must be an object');
+    }
+    const merged = { ...existing, ...patch, id };
+    validateEntry(merged);
+    // Rename-safety: the gate fires on `entry.name || id` for BOTH the direct and
+    // lean paths - a display-name edit renames that surface, so gate matchers must follow (or
+    // the rename refuses). The tools.state.json key must NOT: a LOCAL tool's overlay is keyed by
+    // its immutable register ID, not its display name (migrateState:false; see the namespace note
+    // in rename-migration.js). Runs BEFORE persist so a refusal leaves the register untouched.
+    const oldSurfaced = existing.name || id;
+    const newSurfaced = merged.name || id;
+    const snap = oldSurfaced !== newSurfaced ? snapshotForStoreFile(this._filePath) : null;
+    if (oldSurfaced !== newSurfaced) {
+      migrateForStoreFile(this._filePath, oldSurfaced, newSurfaced, { migrateState: false });
+    }
+    this._byId.set(id, cloneEntry(merged));
+    try {
+      this._persist();
+    } catch (err) {
+      // The other half of "runs BEFORE persist": a persist that fails AFTER a successful migration
+      // must not leave the manifest naming a surface the register does not. Unwind memory and
+      // migrate back (best-effort), then rethrow - a failed rename is a no-op on disk.
+      this._byId.set(id, existing);
+      if (snap) restoreSnapshot(snap); // byte-for-byte; a reverse migration would re-validate and can refuse
+      throw err;
+    }
+    return this.getEntry(id);
+  }
+
+  /** Remove an entry. Throws on unknown id. Persists. */
+  remove(id) {
+    if (!this._byId.has(id)) throw new Error(`Registry.remove: unknown tool id "${id}"`);
+    this._byId.delete(id);
+    this._persist();
+    return true;
+  }
+
+  /**
+   * Re-read the register FILE and swap the in-memory index - the hot-reload seam. A running
+   * gateway holds ONE Registry instance (captured by the protocol adapter at build time), while
+   * tf_tool_add / the UI / a hand edit mutate the FILE from another process - without this, those
+   * edits are invisible until restart. LAST-GOOD semantics: the replacement index is built and
+   * fully validated FIRST; any read/parse/validation failure (including a mid-write partial file)
+   * leaves the current index untouched and returns false. NEVER throws.
+   * @returns {boolean} true when the on-disk register replaced the in-memory index
+   */
+  reload() {
+    let data;
+    try {
+      data = JSON.parse(fs.readFileSync(this._filePath, 'utf8'));
+    } catch (_e) {
+      return false; // unreadable / mid-write / bad JSON -> keep last-good
+    }
+    if (!data || typeof data !== 'object' || Array.isArray(data)) return false;
+    const tools = Array.isArray(data.tools) ? data.tools : [];
+    const next = new Map();
+    try {
+      for (const t of tools) {
+        validateEntry(t);
+        if (next.has(t.id)) throw new Error(`duplicate tool id "${t.id}"`);
+        next.set(t.id, cloneEntry(t));
+      }
+    } catch (_e) {
+      return false; // an invalid entry -> keep last-good
+    }
+    if (typeof data.version === 'number') this._version = data.version;
+    if (typeof data.description === 'string') this._description = data.description;
+    this._byId = next;
+    return true;
+  }
+
+  /**
+   * Write a host-local script's text under this scriptsRoot, atomically.
+   *
+   * Resolves path.basename(invokePath) under scriptsRoot (basename strips any
+   * directory traversal) and GUARDS that the resolved path stays inside
+   * scriptsRoot - the same path-escape defence as defaultRunScript, so a
+   * tf_tool_add(scriptText) can never write outside the isolation root. Writes
+   * `text` via a temp file in the same dir + fsync + rename (mirror of
+   * atomicWriteJson): a crash leaves either no file or the complete file.
+   *
+   * @param {string} invokePath  e.g. "scripts/foo.js" - only the basename is honoured
+   * @param {string} text        full file contents to write
+   * @returns {string} the resolved absolute path that was written
+   */
+  writeScript(invokePath, text) {
+    if (typeof invokePath !== 'string' || invokePath.length === 0) {
+      throw new Error('Registry.writeScript: invokePath (non-empty string) is required');
+    }
+    if (typeof text !== 'string') {
+      throw new Error('Registry.writeScript: text must be a string');
+    }
+    const scriptsRoot = this._scriptsRoot;
+    const resolved = path.resolve(scriptsRoot, path.basename(invokePath));
+    // path.basename strips any directory traversal; confirm anyway.
+    const rel = path.relative(scriptsRoot, resolved);
+    if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
+      throw new Error(`Registry.writeScript: script path escapes scripts root ("${invokePath}")`);
+    }
+    fs.mkdirSync(scriptsRoot, { recursive: true });
+    atomicWriteText(resolved, text); // bytes as given (no line-ending normalisation), temp + rename
+    return resolved;
+  }
+
+  // ---- execution description (does NOT gate) ------------------------------
+
+  /**
+   * Describe HOW to run a tool's invoke. Returns { type, run } where `run` is a
+   * zero-arg function returning a Promise of the tool result. resolveExecution
+   * performs NO gating - toolfunnel_run_tool / gated-run.js fires the PreToolUse hook
+   * and only then calls `run()`. Keeping the gate
+   * out of here keeps the safety case in one auditable place.
+   *
+   * - script invoke: run() spawns node on the host-local script (via the injected
+   *   runScript), passing args in TOOLFUNNEL_TOOL_ARGS.
+   * - shell invoke: run() does NOT execute here. It returns a descriptor
+   *   { type:'shell', command, args } so the gated runner owns the actual shell
+   *   spawn (the broadest power) behind the gate. This keeps arbitrary shell
+   *   execution out of the un-gated register module by design.
+   *
+   * @param {string} id
+   * @param {any} args  structured args forwarded to the tool
+   * @returns {{ type: string, run: () => Promise<any> }}
+   */
+  resolveExecution(id, args) {
+    const entry = this._byId.get(id);
+    if (!entry) throw new Error(`Registry.resolveExecution: unknown tool id "${id}"`);
+    const mode = resolveMode(entry);
+
+    // ---- reference mode: nothing runs here. ----------------------------------
+    // The connected AI performs the action in its own environment. We hand back the
+    // tool's instructions (no `run`) so the run-path takes the no-spawn branch - a
+    // reference tool never spawns server-side. The instruction HANDOFF is still gated
+    // in protocol.runTool (a PreToolUse deny withholds the instructions); it's execution,
+    // not the gate, that's absent here.
+    if (mode === 'reference') {
+      return {
+        type: 'reference',
+        mode: 'reference',
+        instructions: typeof entry.instructions === 'string' ? entry.instructions : '',
+      };
+    }
+
+    const invoke = entry.invoke;
+
+    if (invoke.type === 'script') {
+      const scriptsRoot = this._scriptsRoot;
+      const runScript = this._runScript;
+      return {
+        type: 'script',
+        mode: 'gateway',
+        run: () => runScript(scriptsRoot, invoke, args),
+      };
+    }
+
+    if (invoke.type === 'shell') {
+      // Deliberately do NOT spawn a shell here. Hand the descriptor to the
+      // gated runner, which executes shell only after PreToolUse allows it.
+      return {
+        type: 'shell',
+        mode: 'gateway',
+        run: async () => ({
+          deferred: true,
+          type: 'shell',
+          command: invoke.command,
+          args: args ?? null,
+        }),
+      };
+    }
+
+    // validateEntry guards the load path, but guard here too for late mutation.
+    throw new Error(`Registry.resolveExecution: unsupported invoke.type for "${id}"`);
+  }
+
+  /**
+   * The resolved execution mode for a tool ("gateway" | "reference"). Exposed so callers
+   * (UI, tests) can ask without resolving a full executor. Throws on unknown id.
+   * @param {string} id
+   * @returns {"gateway"|"reference"}
+   */
+  mode(id) {
+    const entry = this._byId.get(id);
+    if (!entry) throw new Error(`Registry.mode: unknown tool id "${id}"`);
+    return resolveMode(entry);
+  }
+
+  // ---- internals ----------------------------------------------------------
+
+  /** Serialise current state back to the register file atomically. */
+  _persist() {
+    const obj = {
+      version: this._version,
+      description: this._description,
+      tools: [...this._byId.values()],
+    };
+    atomicWriteJson(this._filePath, obj);
+  }
+
+  /** @returns {number} */
+  get size() {
+    return this._byId.size;
+  }
+}
+
+/**
+ * loadRegistry(path) -> Registry
+ *
+ * Reads + parses the register JSON at `filePath` and returns a Registry bound to
+ * it. Throws a clear error on a missing/malformed file or a bad entry shape so
+ * misconfiguration is caught at load time, not at model-call time.
+ *
+ * @param {string} filePath
+ * @param {object} [opts]  forwarded to the Registry ctor (scriptsRoot, runScript)
+ * @returns {Registry}
+ */
+function loadRegistry(filePath, opts = {}) {
+  if (typeof filePath !== 'string' || filePath.length === 0) {
+    throw new Error('loadRegistry: filePath (non-empty string) is required');
+  }
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    throw new Error(`loadRegistry: cannot read register at "${filePath}": ${err.message}`);
+  }
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`loadRegistry: register at "${filePath}" is not valid JSON: ${err.message}`);
+  }
+  return new Registry({ filePath, data, ...opts });
+}
+
+module.exports = {
+  Registry,
+  loadRegistry,
+  // exported for unit tests / the gated runner
+  atomicWriteJson,
+  validateEntry,
+  defaultRunScript,
+  resolveMode,
+  VALID_INVOKE_TYPES,
+  VALID_MODES,
+};