toolfunnel 0.7.1 → 0.8.0

package/src/mcp/tool-approvals.js

@@ -0,0 +1,396 @@
+'use strict';
+
+/**
+ * tool-approvals.js - tool descriptor approval ("hash-pinning").
+ *
+ * An upstream can change what its tools SAY after you attached it. The description (and every
+ * parameter description inside the input schema) goes straight into the model's context, so a
+ * changed descriptor is the attack whether or not the tool is ever called. This module holds the
+ * PURE rules plus the state file; the aggregator applies them at its single listing chokepoint
+ * (_listAndCache) so every listing shows only approved text and every execution path can refuse.
+ *
+ * Rules, per upstream (evaluate):
+ *   - no record yet                      -> FIRST USE: approve every tool as listed.
+ *   - same version, a tool changed/new   -> PENDING: the listing keeps the APPROVED descriptor (a new
+ *                                           tool stays hidden) and calls refuse until accepted.
+ *   - version changed                    -> UPGRADE: auto-approved and reported, unless `strict`
+ *                                           (expose.json strictApproval) - then pending as above.
+ *   - the server NAME changed            -> the same as a version change (reported as server-changed);
+ *                                           never a fresh first use, or a rename would get past strict.
+ *   - a server that reports no version   -> the stricter branch (treated as "same version").
+ *   - a removed tool                     -> its approval stays (harmless); a pending entry for it goes.
+ * Known limit, documented: a hostile maintainer can bump the version too - that is what strict is for.
+ *
+ * What is hashed: the model-facing fields, as canonical JSON (sorted keys): HASHED_FIELDS. `_meta`
+ * and `icons` are presentation and excluded. sha256 from node:crypto (zero-dep).
+ *
+ * The state file (mcp/tool-approvals.json) is USER STATE, never seeded or shipped. It carries the
+ * pending entries too, because the UI and CLI (separate processes) accept by moving pending ->
+ * approved in the file. Missing = empty. Unreadable = THROW: treating it as empty would silently
+ * approve everything as first use, which is exactly what corrupting it would be for.
+ *
+ * Tool names and upstream ids come from outside, so every map write goes through put() (an own
+ * data property even for "__proto__") and every read through own().
+ *
+ * CommonJS, node built-ins only.
+ */
+
+const fs = require('node:fs');
+const crypto = require('node:crypto');
+const { atomicWriteJson } = require('../core/atomic-write');
+
+const HASHED_FIELDS = ['name', 'title', 'description', 'inputSchema', 'outputSchema', 'annotations'];
+const FILE_VERSION = 1;
+
+const hasOwn = (o, k) => o !== null && typeof o === 'object' && Object.prototype.hasOwnProperty.call(o, k);
+const own = (o, k) => (hasOwn(o, k) ? o[k] : undefined);
+function put(o, k, v) {
+  Object.defineProperty(o, k, { value: v, enumerable: true, writable: true, configurable: true });
+}
+const clone = (v) => (v === undefined ? undefined : JSON.parse(JSON.stringify(v)));
+const str = (v) => (typeof v === 'string' ? v : '');
+
+/** Stable JSON: object keys sorted at every level, undefined members dropped (as JSON does). */
+function canonical(v) {
+  if (v === null || typeof v !== 'object') return JSON.stringify(v === undefined ? null : v);
+  if (Array.isArray(v)) return '[' + v.map(canonical).join(',') + ']';
+  const keys = Object.keys(v).filter((k) => v[k] !== undefined).sort();
+  return '{' + keys.map((k) => JSON.stringify(k) + ':' + canonical(v[k])).join(',') + '}';
+}
+
+/** The hashed, stored and served part of a tool: its HASHED_FIELDS that are present. */
+function descriptorOf(tool) {
+  const d = {};
+  for (const f of HASHED_FIELDS) {
+    if (tool && tool[f] !== undefined) put(d, f, clone(tool[f]));
+  }
+  return d;
+}
+
+/** 'sha256:<hex>' over the canonical descriptor. */
+function hashTool(tool) {
+  return 'sha256:' + crypto.createHash('sha256').update(canonical(descriptorOf(tool)), 'utf8').digest('hex');
+}
+
+// C0, DEL, C1 and the bidi controls: a server's text must not drive a terminal or reorder a line.
+const UNPRINTABLE = /[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g;
+const NAMED_ESCAPES = { '\n': '\\n', '\r': '\\r', '\t': '\\t' };
+
+/** A server's text made safe to print: control and bidi characters shown as escapes. */
+function printable(s) {
+  return String(s).replace(UNPRINTABLE, (c) => NAMED_ESCAPES[c] || '\\u' + c.charCodeAt(0).toString(16).padStart(4, '0'));
+}
+
+/** The HASHED_FIELDS that differ between two descriptors (every present one when `approved` is null). */
+function changedFields(approved, current) {
+  return HASHED_FIELDS.filter((f) => hasOwn(approved, f) !== hasOwn(current, f) || canonical(own(approved, f)) !== canonical(own(current, f)));
+}
+
+/**
+ * Apply the rules to one upstream's current listing.
+ * @param {object}   o
+ * @param {object}   [o.record]      this upstream's stored record, or undefined (never approved)
+ * @param {object}   [o.serverInfo]  { name, version } the upstream reported this connect
+ * @param {object[]} o.tools         the raw tools/list result
+ * @param {boolean}  [o.strict]      strictApproval: a version change does not auto-approve
+ * @param {string}   [o.now]         ISO time for new entries (tests pass a fixed one)
+ * @param {object}   [o.writer]      { pid, id } of the gateway evaluating, stamped on each pending
+ *                                   entry as `by` so another run can tell a live writer from a gone one
+ * @returns {{ record: object, effective: object[], pending: object[], events: object[], changed: boolean }}
+ *   record    the new record to store; effective the tools to SERVE (approved descriptors, in the
+ *   upstream's order; unapproved new tools absent); pending [{tool, reason, approved, current,
+ *   changed}] for the refusal; events [{kind:'first-use'|'server-changed'|'upgrade', ...}];
+ *   changed = the record differs from the one passed in (save it).
+ */
+function evaluate({ record, serverInfo, tools, strict, now, writer } = {}) {
+  const at = typeof now === 'string' && now ? now : new Date().toISOString();
+  const seen = { name: str(serverInfo && serverInfo.name), version: str(serverInfo && serverInfo.version) };
+  const current = new Map(); // name -> { tool, hash, descriptor }, first occurrence wins (listing order)
+  for (const t of Array.isArray(tools) ? tools : []) {
+    if (!t || typeof t.name !== 'string' || !t.name.length || current.has(t.name)) continue;
+    current.set(t.name, { tool: t, hash: hashTool(t), descriptor: descriptorOf(t) });
+  }
+  const before = record ? canonical(record) : null;
+  const events = [];
+
+  if (!record) {
+    const approved = {};
+    for (const [n, c] of current) put(approved, n, { hash: c.hash, descriptor: c.descriptor, at, how: 'first-use' });
+    const rec = { server: { ...seen }, seen: { ...seen }, approved, pending: {} };
+    events.push({ kind: 'first-use', tools: [...current.keys()] });
+    return { record: rec, effective: [...current.values()].map((c) => c.tool), pending: [], events, changed: true };
+  }
+
+  const rec = { server: { ...record.server }, seen: { ...seen }, approved: {}, pending: {} };
+  for (const k of Object.keys(record.approved || {})) put(rec.approved, k, record.approved[k]);
+  const versionChanged = !!seen.version && !!record.server.version && seen.version !== record.server.version;
+  // A different server NAME is an identity change like a version change: approved (and reported)
+  // when not strict, pending under strictApproval. It is never a fresh first use - that let a
+  // server rename itself past strictApproval, or release a pending change by flipping its name.
+  const nameChanged = !!seen.name && !!record.server.name && seen.name !== record.server.name;
+  const autoApprove = (versionChanged || nameChanged) && !strict;
+  const effective = [];
+  const pending = [];
+  const upgraded = [];
+  for (const [n, c] of current) {
+    const a = own(rec.approved, n);
+    if (a && a.hash === c.hash) { effective.push(c.tool); continue; }
+    const reason = a ? 'changed' : 'new';
+    if (autoApprove) {
+      put(rec.approved, n, { hash: c.hash, descriptor: c.descriptor, at, how: 'upgrade' });
+      effective.push(c.tool);
+      upgraded.push({ tool: n, reason });
+      continue;
+    }
+    const prior = own(record.pending, n);
+    put(rec.pending, n, {
+      hash: c.hash,
+      descriptor: c.descriptor,
+      since: prior && prior.hash === c.hash && prior.since ? prior.since : at,
+      reason,
+      ...(writer ? { by: writer } : {}),
+    });
+    pending.push({
+      tool: n,
+      hash: c.hash, // what an accept must match: the descriptor the user was shown, not a later one
+      reason,
+      approved: a ? clone(a.descriptor) : null,
+      current: clone(c.descriptor),
+      changed: changedFields(a && a.descriptor, c.descriptor),
+    });
+    if (a) effective.push(clone(a.descriptor)); // serve the APPROVED text; the name is unchanged
+  }
+  // The approved identity follows the server only while nothing is waiting: a pending change was
+  // seen at the new version, and accepting it (accept) is what moves the identity forward.
+  if (Object.keys(rec.pending).length === 0) {
+    if (seen.name) rec.server.name = seen.name;
+    if (seen.version) rec.server.version = seen.version;
+  }
+  if (upgraded.length && nameChanged) events.push({ kind: 'server-changed', from: record.server.name, to: seen.name, tools: upgraded });
+  else if (upgraded.length) events.push({ kind: 'upgrade', from: record.server.version, to: seen.version, tools: upgraded });
+  return { record: rec, effective, pending, events, changed: canonical(rec) !== before };
+}
+
+/**
+ * Several gateways can share one home, each with its own child of an upstream, so each can see a
+ * different listing. Before this process writes its record, carry over the pending entries in the
+ * STORED record that another process wrote: an entry this record neither holds as pending nor has
+ * approved at that hash, and that this process did not write itself (`ownWritten(tool, hash)`; its
+ * own entry that it no longer sees means its server reverted, so that one goes), and whose writer
+ * is still running (`isAlive(by)`; an entry left by a gateway that has exited - this gateway's own
+ * previous run, say - is no one's view any more, and kept it would never clear). One pending slot
+ * per tool: this process's own pending entry for a tool wins.
+ * @returns {object} a NEW record
+ */
+function keepForeignPending(stored, next, ownWritten, isAlive) {
+  const rec = clone(next);
+  if (!rec.pending || typeof rec.pending !== 'object') rec.pending = {};
+  const sp = stored && stored.pending && typeof stored.pending === 'object' ? stored.pending : {};
+  for (const n of Object.keys(sp)) {
+    const e = sp[n];
+    if (!e || typeof e.hash !== 'string' || hasOwn(rec.pending, n)) continue;
+    const a = own(rec.approved, n);
+    if (a && a.hash === e.hash) continue; // accepted since
+    if (typeof ownWritten === 'function' && ownWritten(n, e.hash)) continue;
+    if (e.by && typeof isAlive === 'function' && !isAlive(e.by)) continue;
+    put(rec.pending, n, clone(e));
+  }
+  return rec;
+}
+
+/**
+ * Accept pending descriptors: one tool, or every pending one when `toolName` is undefined.
+ * @returns {{ record: object, accepted: string[] }} a NEW record (the input is not modified)
+ */
+function accept(record, toolName, now) {
+  const at = typeof now === 'string' && now ? now : new Date().toISOString();
+  const rec = clone(record || {});
+  if (!rec.approved || typeof rec.approved !== 'object') rec.approved = {};
+  if (!rec.pending || typeof rec.pending !== 'object') rec.pending = {};
+  const names = toolName === undefined ? Object.keys(rec.pending) : (hasOwn(rec.pending, toolName) ? [toolName] : []);
+  for (const n of names) {
+    const p = rec.pending[n];
+    put(rec.approved, n, { hash: p.hash, descriptor: p.descriptor, at, how: 'accepted' });
+    delete rec.pending[n];
+  }
+  if (Object.keys(rec.pending).length === 0 && rec.seen && rec.server) {
+    if (rec.seen.name) rec.server.name = rec.seen.name;
+    if (rec.seen.version) rec.server.version = rec.seen.version;
+  }
+  return { record: rec, accepted: names };
+}
+
+// ── the state file ────────────────────────────────────────────────────────────────────────────
+
+function emptyApprovals() {
+  return { version: FILE_VERSION, upstreams: {} };
+}
+
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/** Throw, naming the file and the field, on anything that is not a well-formed approvals file. */
+function validateApprovals(doc, filePath) {
+  const fail = (what) => { throw new Error(`tool approvals: ${filePath}: ${what}`); };
+  if (!isPlainObject(doc)) fail('must be a JSON object');
+  if (typeof doc.version !== 'number') fail('"version" must be a number');
+  if (!isPlainObject(doc.upstreams)) fail('"upstreams" must be an object keyed by upstream id');
+  for (const id of Object.keys(doc.upstreams)) {
+    const r = doc.upstreams[id];
+    const where = `upstream ${JSON.stringify(id)}`;
+    if (!isPlainObject(r)) fail(`${where} must be an object`);
+    if (!isPlainObject(r.server) || typeof r.server.name !== 'string' || typeof r.server.version !== 'string') {
+      fail(`${where}: "server" must be { name: string, version: string }`);
+    }
+    for (const part of ['approved', 'pending']) {
+      if (!isPlainObject(r[part])) fail(`${where}: "${part}" must be an object keyed by tool name`);
+      for (const n of Object.keys(r[part])) {
+        const e = r[part][n];
+        if (!isPlainObject(e) || typeof e.hash !== 'string' || !e.hash.startsWith('sha256:') || !isPlainObject(e.descriptor)) {
+          fail(`${where}: "${part}" entry ${JSON.stringify(n)} must be { hash: "sha256:...", descriptor: {...} }`);
+        }
+        if (e.descriptor.name !== n) fail(`${where}: "${part}" entry ${JSON.stringify(n)} has a descriptor named ${JSON.stringify(e.descriptor.name)}`);
+      }
+    }
+  }
+}
+
+/** Read the approvals file. Missing -> empty. Unreadable or malformed -> throw naming the file. */
+function loadApprovals(filePath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return emptyApprovals();
+    throw new Error(`tool approvals: cannot read ${filePath}: ${(err && err.message) || String(err)}`);
+  }
+  let doc;
+  try {
+    doc = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`tool approvals: ${filePath} is not valid JSON: ${(err && err.message) || String(err)}`);
+  }
+  validateApprovals(doc, filePath);
+  return doc;
+}
+
+/** Write the approvals file atomically (the shared temp + fsync + rename writer). */
+function saveApprovals(filePath, doc) {
+  // A home without an mcp/ folder must still record first use (else nothing is ever remembered).
+  fs.mkdirSync(require('node:path').dirname(filePath), { recursive: true });
+  atomicWriteJson(filePath, doc);
+}
+
+/**
+ * The ONE accept every route shares - the tf_accept_change management tool, the CLI, the UI server
+ * and the gateway itself: read the CURRENT file, accept, write it back atomically. With
+ * `expectHash`, only if the pending descriptor is still the one the user was shown (a server that
+ * changed again is not approved sight unseen). Living in the engine, it reaches every install -
+ * including an external config home, whose copied scripts and register never refresh.
+ * Throws on an unreadable file.
+ * @returns {{ accepted: string[], pending: string[], stale?: true, unknown?: true }}
+ */
+function acceptInFile(filePath, upstreamId, toolName, expectHash, now) {
+  const doc = loadApprovals(filePath);
+  const rec = getRecord(doc, upstreamId);
+  if (!rec) return { accepted: [], pending: [], unknown: true };
+  if (expectHash !== undefined && expectHash !== null) {
+    const p = toolName !== undefined ? own(rec.pending, toolName) : undefined;
+    if (!p || p.hash !== expectHash) return { accepted: [], pending: Object.keys(rec.pending || {}), stale: true };
+  }
+  const res = accept(rec, toolName, now);
+  if (res.accepted.length) {
+    setRecord(doc, upstreamId, res.record);
+    saveApprovals(filePath, doc);
+  }
+  return { accepted: res.accepted, pending: Object.keys(res.record.pending || {}) };
+}
+
+/**
+ * Every change waiting for acceptance in a loaded doc, flat - the one view the CLI (`changes`) and
+ * the UI (/api/tool-changes) both render. Descriptions are the SERVER's text: render as text only.
+ * `fields` holds { approved, new } for every other changed field (a schema's parameter descriptions
+ * reach the model too, so the user must be able to read them before accepting).
+ * @returns {Array<{upstream, tool, reason, since, hash, approvedDescription, newDescription, changed, fields}>}
+ */
+function listPending(doc) {
+  const out = [];
+  const ups = (doc && doc.upstreams) || {};
+  for (const id of Object.keys(ups)) {
+    const rec = ups[id] || {};
+    const pend = rec.pending || {};
+    for (const name of Object.keys(pend)) {
+      const p = pend[name] || {};
+      const a = own(rec.approved, name);
+      const changed = changedFields(a && a.descriptor, p.descriptor);
+      out.push({
+        upstream: id,
+        tool: name,
+        reason: p.reason || (a ? 'changed' : 'new'),
+        since: p.since || null,
+        hash: p.hash,
+        approvedDescription: a && a.descriptor && typeof a.descriptor.description === 'string' ? a.descriptor.description : null,
+        newDescription: p.descriptor && typeof p.descriptor.description === 'string' ? p.descriptor.description : null,
+        changed,
+        fields: Object.fromEntries(changed.filter((f) => f !== 'name' && f !== 'description')
+          .map((f) => [f, { approved: a ? own(a.descriptor, f) ?? null : null, new: own(p.descriptor, f) ?? null }])),
+      });
+    }
+  }
+  return out;
+}
+
+/** Tools approved automatically on a server version upgrade, latest first (at most `limit`). */
+function listUpgrades(doc, limit) {
+  const out = [];
+  const ups = (doc && doc.upstreams) || {};
+  for (const id of Object.keys(ups)) {
+    const appr = (ups[id] && ups[id].approved) || {};
+    for (const name of Object.keys(appr)) {
+      if (appr[name] && appr[name].how === 'upgrade') out.push({ upstream: id, tool: name, at: appr[name].at || null });
+    }
+  }
+  out.sort((x, y) => String(y.at).localeCompare(String(x.at)));
+  return typeof limit === 'number' ? out.slice(0, limit) : out;
+}
+
+/** Why an acceptInFile result accepted nothing (the wording every route shares), or null when it did. */
+function acceptFailure(res, upstreamId, toolName) {
+  if (res && res.unknown) return `no tool approvals are recorded for upstream "${upstreamId}"`;
+  if (res && res.stale) return 'that change is no longer the one pending - the server changed the tool again';
+  if (!res || !res.accepted || res.accepted.length === 0) {
+    return toolName ? `tool "${toolName}" has no change waiting on upstream "${upstreamId}"` : `upstream "${upstreamId}" has no changes waiting`;
+  }
+  return null;
+}
+
+/** One upstream's record from a loaded doc (own property only), or undefined. */
+function getRecord(doc, upstreamId) {
+  return own(doc && doc.upstreams, upstreamId);
+}
+
+/** Set one upstream's record on a loaded doc (an own property, whatever the id). */
+function setRecord(doc, upstreamId, record) {
+  put(doc.upstreams, upstreamId, record);
+}
+
+module.exports = {
+  HASHED_FIELDS,
+  canonical,
+  descriptorOf,
+  hashTool,
+  changedFields,
+  printable,
+  evaluate,
+  keepForeignPending,
+  accept,
+  emptyApprovals,
+  validateApprovals,
+  loadApprovals,
+  saveApprovals,
+  getRecord,
+  setRecord,
+  acceptInFile,
+  listPending,
+  listUpgrades,
+  acceptFailure,
+};

package/src/tools/registry.js

@@ -41,11 +41,12 @@ 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');
+const { takeWithinCap } = require('../core/output-cap');
+const { migrateForStoreFile, snapshotForStoreFile, restoreSnapshot } = 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
+// 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.
@@ -106,61 +107,9 @@ 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;
-  }
-}
+// 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 } = {}) {
@@ -245,12 +194,11 @@ function defaultRunScript(scriptsRoot, invoke, args) {
     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.
+    // 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;
@@ -286,8 +234,10 @@ function defaultRunScript(scriptsRoot, invoke, args) {
     let errBytes = 0;
     child.stdout.on('data', (d) => {
       if (outBytes >= MAX_TOOL_OUTPUT_BYTES) return;
-      stdout += d;
-      outBytes += Buffer.byteLength(d, 'utf8');
+      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 });
@@ -295,8 +245,10 @@ function defaultRunScript(scriptsRoot, invoke, args) {
     });
     child.stderr.on('data', (d) => {
       if (errBytes >= MAX_TOOL_OUTPUT_BYTES) return;
-      stderr += d;
-      errBytes += Buffer.byteLength(d, 'utf8');
+      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;
@@ -419,11 +371,21 @@ class Registry {
     // 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));
-    this._persist();
+    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);
   }
 
@@ -498,23 +460,7 @@ class Registry {
       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;
-    }
+    atomicWriteText(resolved, text); // bytes as given (no line-ending normalisation), temp + rename
     return resolved;
   }
 

package/src/tools/tool-state.js

@@ -24,7 +24,7 @@
  *
  * Shape of tools.state.json:  { "<id>": { "enabled": false, "hidden": true, "hot": true }, ... }
  *
- * PASSTHROUGH (0.6.0): one RESERVED top-level key, `"passthrough": "<upstreamId>"` (a STRING,
+ * PASSTHROUGH: one RESERVED top-level key, `"passthrough": "<upstreamId>"` (a STRING,
  * unambiguous against the per-tool object entries). When set, the gateway becomes a transparent
  * wrapper for that one upstream: its tools ARE the advertised surface (real schemas, implicitly
  * hot), the meta-tools and everything else are hidden and uncallable, and every call still fires

package/src/ui/public/app.js

@@ -35,6 +35,15 @@
     return node;
   }
 
+  // A server's text shown with its control and bidi characters visible, so it cannot reorder a line.
+  // Same escapes as the engine's printable(): a newline HTML would collapse stays visible.
+  var NAMED_ESCAPES = { '\n': '\\n', '\r': '\\r', '\t': '\\t' };
+  function printable(s) {
+    return String(s).replace(/[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g, function (c) {
+      return NAMED_ESCAPES[c] || '\\u' + ('000' + c.charCodeAt(0).toString(16)).slice(-4);
+    });
+  }
+
   // ── fetch wrappers ──────────────────────────────────────────────────────────
   function getJson(url) {
     return fetch(url, { headers: { Accept: 'application/json' } }).then(function (r) { return r.json(); });
@@ -503,7 +512,7 @@
         function () { input.checked = !want; });
     });
 
-    // legacyPin (0.6.0): keep speaking MCP 2024-11-05 to this upstream forever - never auto-
+    // legacyPin: keep speaking MCP 2024-11-05 to this upstream forever - never auto-
     // upgrades, warns at startup and per call. Opt-in; takes effect on the next (re)connect.
     var pinSwitch = makeSwitch(u.legacyPin === true, true, function (input) {
       var want = input.checked;
@@ -656,7 +665,57 @@
     list.parentNode.insertBefore(banner, list);
   }
 
+  // Tool descriptor changes held back for acceptance. Descriptions are the SERVER's own,
+  // unverified text: rendered with textContent only (el's `text`), never as HTML.
+  function renderToolChanges(data) {
+    var existing = document.getElementById('tool-changes');
+    if (existing) existing.remove();
+    var list = $('#mcp-list');
+    if (!list || !list.parentNode) return;
+    if (data && data.ok === false) {
+      list.parentNode.insertBefore(el('div', { id: 'tool-changes', class: 'row' }, [
+        el('p', { text: 'TOOL APPROVALS UNREADABLE: ' + (data.error || 'unknown error') + ' - the gateway withholds the ' +
+          'affected tools until the file is repaired (removing it, or an upstream\'s entry, approves the current tools as first use).' }),
+      ]), list);
+      return;
+    }
+    var pending = (data && Array.isArray(data.pending)) ? data.pending : [];
+    if (!pending.length) return;
+    var box = el('div', { id: 'tool-changes' }, [
+      el('p', { text: pending.length + ' tool change(s) held back: the server changed what these tools say without ' +
+        'changing its version (or strictApproval is on). Until you accept, the gateway keeps showing the approved text ' +
+        'and refuses calls to them. Accept only if you recognise the change.' }),
+    ]);
+    pending.forEach(function (p) {
+      var acceptBtn = el('button', { class: 'btn btn-sm', type: 'button' }, ['Accept']);
+      acceptBtn.addEventListener('click', function () {
+        acceptBtn.disabled = true;
+        postJson('/api/tool-changes/accept', { upstream: p.upstream, tool: p.tool, hash: p.hash }).then(function (res) {
+          acceptBtn.disabled = false;
+          if (!res || res.ok !== true) { toast((res && res.error) || 'Accept failed', 'error'); loadToolChanges(); return; }
+          toast('Accepted ' + p.upstream + ' / ' + printable(p.tool), 'good');
+          loadToolChanges();
+        }).catch(function (e) { acceptBtn.disabled = false; toast('Request failed: ' + errText(e), 'error'); });
+      });
+      box.appendChild(el('div', { class: 'row' }, [
+        el('p', { text: p.upstream + ' / ' + printable(p.tool) + ' (' + (p.reason === 'new' ? 'new tool' : 'changed: ' + p.changed.join(', ')) + ')' }),
+        el('p', { class: 'muted', text: 'Approved: ' + (p.approvedDescription == null ? '(none - a new tool)' : printable(p.approvedDescription)) }),
+        el('p', { text: 'New (the server\'s text): ' + (p.newDescription == null ? '(no description)' : printable(p.newDescription)) }),
+        el('div', {}, Object.keys(p.fields || {}).map(function (f) {
+          return el('p', { style: 'font-family: var(--mono)', text: 'New ' + f + ': ' + printable(JSON.stringify(p.fields[f].new)) });
+        })),
+        acceptBtn,
+      ]));
+    });
+    list.parentNode.insertBefore(box, list);
+  }
+
+  function loadToolChanges() {
+    return getJson('/api/tool-changes').then(renderToolChanges).catch(function () { /* the list below still loads */ });
+  }
+
   function loadMcps() {
+    loadToolChanges();
     return getJson('/api/upstreams').then(function (data) {
       upstreams = (data && Array.isArray(data.upstreams)) ? data.upstreams : [];
       var expose = (data && Array.isArray(data.expose)) ? data.expose : [];