toolfunnel 0.7.1 → 0.8.0

package/README.md

@@ -10,7 +10,7 @@
 
 ![ToolFunnel in 60 seconds: scripts → register → identity → live MCP server → npm package](demo/toolfunnel-demo.gif)
 
-**📖 Full documentation: [the ToolFunnel User Manual](docs/MANUAL.pdf)** - installation, the web UI, writing tools, attaching MCP servers, the policy gate, packaging, and troubleshooting, all illustrated with screenshots and worked examples. This README is the overview; the manual is the reference.
+**📖 Full documentation: [the ToolFunnel User Manual](docs/MANUAL.pdf)** - installation, the web UI, writing tools, attaching MCP servers, the policy gate, packaging, and troubleshooting, all illustrated with screenshots and worked examples. This README is the overview; the manual is the reference. The manual covers 0.7.0, with a supplement for what changed in 0.8.0.
 
 ## The problem
 
@@ -112,25 +112,35 @@ gatedRun({ engine, ctx, toolName, args, execute })
 
 Hooks speak the Claude-Code hook protocol (event JSON on stdin, exit `2` to block), so an existing hook travels here unchanged. The load-bearing invariant, proven by test: a PreToolUse deny means `execute()` is never called. The shipped example hooks are **disabled by default** - enable one in `hooks/hooks.manifest.json` (or the UI's Hooks tab) to turn policy on. Writing hooks, matchers, and worked examples: [manual](docs/MANUAL.pdf).
 
+### Tool changes wait for you
+
+A tool's description goes straight into your model's context whether or not the tool is ever called, so an MCP server that quietly changes what its tools *say* after you've attached it can steer your model. ToolFunnel records every upstream tool's description and schema the first time it connects, and from then on:
+
+- **Same server version, changed or new tool** - held. The gateway keeps serving the text you approved (a new tool stays hidden), and calls to that tool are refused until you accept the change. Everything else keeps working.
+- **New server version** - approved and reported, because that is what an update looks like. Set `"strictApproval": true` on an upstream to hold every change for acceptance instead.
+
+The refusal tells the model which tool changed and which fields - never the new text. You read that with `toolfunnel changes` or in the UI, and accept it there, with `toolfunnel accept <upstream> [tool]`, or through the agent: a 2026-07-28 client that supports elicitation just asks you in the chat, and any other client can run `tf_accept_change` once you've said yes. Either way an agent-side accept passes your PreToolUse gate as `tf_accept_change`, so a hook can forbid them.
+
 ## Why it's different
 
 Hosting tools and proxying other MCP servers is a crowded space - but for my own use case, which is why I rolled my own solution, I wanted something different.
 
-A quick feature comparison as of Aug 2nd 2026:
+A quick feature comparison as of Aug 2nd 2026 (the tool-approval, protocol and wrap rows re-checked against each project's own docs on Sep 24th 2026):
 
 | Capability | ToolFunnel | FastMCP | mcpproxy-go | MetaMCP | mcp-anything |
 |---|:--:|:--:|:--:|:--:|:--:|
 | Config-declared polyglot tools (no SDK) | ✓ | ✗ (decorators) | partial (proxy only) | ✗ | ✓ |
 | Lean server-side exposure (briefs + schema on demand) | ✓ | partial | ✓ | ✗ | ✗ |
 | Server-side fail-closed policy gate (Pre/Post) | ✓ | ✓ | ✓ | ✓ | ✗ |
+| Changed tool descriptions held for your approval | ✓ | ✗ | ✓ | ✗ | ✗ |
 | Live attach / hot-reload, no restart | ✓ | ✗ | partial | partial | ✓ |
 | Non-Docker self-healing reconnect | ✓ | ✗ | partial (Docker) | partial (circuit-breaker) | ✗ |
 | Visibility **matrix** - lean default + per-tool promote-to-every-turn + hide | ✓ | ✗ | filter only | cherry-pick only | ✗ |
 | Zero runtime dependencies\* | ✓ (Node, no SDK) | ✗ (framework) | ✓ (Go) | ✗ (Docker) | ✓ (Go) |
 | Runtime dependencies (installed / bundled) | **0\*** | many | 40+ (bundled) | many | bundled (Go) |
 | Config web UI | ✓ | ✗ | ✓ | ✓ | ✗ |
-| Dual-era protocol (2026-07-28 + legacy), client & server side | ✓ | ✗<br>✓(beta) | ✗ | ✗ | ✗ |
-| Transparent single-server wrap (invisible, era-bridging) | ✓ | ✗ | ✗ | ✗ | ✗ |
+| Dual-era protocol (2026-07-28 + legacy), client & server side | ✓ | ✓ (4.0) | ✗ | ✗ | ✗ |
+| Transparent single-server wrap (invisible, era-bridging) | ✓ | partial (4.0: era pinning, no bridge) | ✗ | ✗ | ✗ |
 
 Beyond the dependency count, four capability choices set ToolFunnel apart from a pure proxy like mcpproxy-go:
 

package/bin/toolfunnel.js

@@ -23,11 +23,9 @@
 const args = process.argv.slice(2);
 
 /**
- * Read a flag's value, accepting BOTH `--flag value` and `--flag=value` (0.7.0). Only the
- * space-separated form was handled, so `--config-dir=/my/home` was silently ignored and the config
- * home fell back to the package root - exactly the class of quiet misconfiguration the resolved-home
- * stderr line and the positional parsing below exist to prevent. The `=` form is what most people
- * type first, and getting it wrong wrote config somewhere they were not looking.
+ * Read a flag's value, accepting BOTH `--flag value` and `--flag=value`. The `=` form is what most
+ * people type first; ignoring it would silently fall back to the package root as the config home,
+ * writing config somewhere they were not looking.
  */
 function flagValue(name, fallback) {
   // ONE left-to-right scan, LAST occurrence wins whichever form it uses. Scanning the = form
@@ -48,25 +46,31 @@ function flagValue(name, fallback) {
         process.exit(2);
       }
       value = v;
-    } else if (a === name && i + 1 < args.length) {
-      value = args[i + 1];
+    } else if (a === name) {
+      // The space form needs a value too: a following FLAG, or nothing at all, is not one. Reading
+      // the next flag as the value made `--config-dir --port 0` a config home named "--port", and
+      // a trailing bare flag a silent fallback to the package root.
+      const v = i + 1 < args.length ? args[i + 1] : undefined;
+      if (typeof v !== 'string' || v.length === 0 || v[0] === '-') {
+        process.stderr.write(`toolfunnel: ${name} requires a value (write ${name}=<value> or ${name} <value>)\n`);
+        process.exit(2);
+      }
+      value = v;
     }
   }
   return value;
 }
 
 // POSITIONAL arguments - the subcommand and its target - recognised regardless of where global
-// flags sit. `toolfunnel --config-dir X wrap Y` used to silently start a normal server: args[0]
-// was the flag, the wrap branch never matched, and the user got a running gateway instead of a
-// wrap with zero feedback (cold-start field test, 2026-07-18). Value-taking flags are skipped
-// WITH their value; any other -/-- token is skipped alone.
-const VALUE_FLAGS = new Set(['--config-dir', '--port', '--host', '--as']);
+// flags sit, so `toolfunnel --config-dir X wrap Y` wraps Y instead of reading args[0] as the
+// command. Value-taking flags are skipped WITH their value; any other -/-- token is skipped alone.
+const VALUE_FLAGS = new Set(['--config-dir', '--port', '--host', '--as', '--hash']);
 const positionals = [];
 for (let i = 0; i < args.length; i++) {
   const a = args[i];
   // `--flag value` consumes the next token; `--flag=value` is self-contained and is skipped by the
   // generic leading-dash rule below, so it must NOT also eat the following token.
-  if (VALUE_FLAGS.has(a)) { i++; continue; }
+  if (VALUE_FLAGS.has(a)) { if (typeof args[i + 1] === 'string' && args[i + 1][0] !== '-') i++; continue; } // a following flag is not its value
   if (typeof a === 'string' && a.length && a[0] === '-') continue;
   positionals.push(a);
 }
@@ -92,6 +96,10 @@ if (args.includes('--help') || args.includes('-h')) {
       '                                surface (meta-tools hidden), every call still gated. The',
       '                                gateway answers both MCP eras, so a legacy-only MCP keeps',
       '                                working with modern clients. `wrap --off` restores normal.',
+      '  toolfunnel changes            List tool description changes held back for acceptance',
+      '  toolfunnel accept <upstream> [tool] [--hash <h>]',
+      '                                Accept a held change (every one of that upstream without',
+      '                                a tool). --hash: only if it is still the change you saw.',
       '  toolfunnel install-oauth      Install the optional OAuth 2.1 dependency (jose)',
       '  toolfunnel --config-dir <dir> Use <dir> as the CONFIG HOME (see below)',
       '  toolfunnel --version          Print the version',
@@ -101,7 +109,8 @@ if (args.includes('--help') || args.includes('-h')) {
       'the config home - by default the package root (a git clone works as before), or the value',
       'of --config-dir / the TOOLFUNNEL_HOME env var. An empty home is seeded from the shipped',
       'defaults on first use and is NEVER overwritten after - so an npm update cannot eat your',
-      'tools. This is also how a wrapped MCP ships its own bundled setup.',
+      'tools. (A tool new in a release is added to your register once; nothing else changes.)',
+      'This is also how a wrapped MCP ships its own bundled setup.',
       '',
       'Identity + port defaults can be set in an OPTIONAL toolfunnel.json in the config home:',
       '  { "serverName": "my-mcp", "serverVersion": "1.0.0", "httpPort": 9998, "uiPort": 9777 }',
@@ -117,18 +126,18 @@ if (args.includes('--help') || args.includes('-h')) {
 // same resolved home. Precedence: --config-dir > TOOLFUNNEL_HOME env > the package root.
 // Whether the user EXPLICITLY placed the home must be captured BEFORE init: initConfigHome
 // exports the resolved home into process.env.TOOLFUNNEL_HOME for the child tools it spawns,
-// so reading the env afterwards is always-true and the hint branch was dead (0.7.0).
+// so reading the env afterwards would always be true.
 const explicitHome = !!(flagValue('--config-dir', '') || process.env.TOOLFUNNEL_HOME);
 const { initConfigHome } = require('../src/core/config-home');
-const configHome = initConfigHome({ dir: flagValue('--config-dir', '') }).home;
+const { home: configHome, added: addedTools } = initConfigHome({ dir: flagValue('--config-dir', '') });
 
-// One honest stderr line so nobody discovers the config home by accident - before this, a bare
-// `git status` after running from a clone was the discovery mechanism. Defaulted homes get
-// the relocation hint.
+// One stderr line so nobody discovers the config home by accident. Defaulted homes get the
+// relocation hint.
 process.stderr.write('[toolfunnel] config home: ' + configHome +
   (explicitHome
     ? '\n'
     : ' (default: the package root - use --config-dir <dir> or TOOLFUNNEL_HOME to relocate)\n'));
+if (addedTools.length) process.stderr.write('[toolfunnel] added tool(s) new in this release to the register: ' + addedTools.join(', ') + '\n');
 
 // Advisory runtime preflight: the home's toolfunnel.json may declare `requires` (python, git, ...)
 // for the tools it ships. A missing/old runtime breaks only the tools that need it, so each
@@ -285,8 +294,14 @@ if (positionals[0] === 'wrap') {
           const versions = disc && Array.isArray(disc.supportedVersions) ? disc.supportedVersions : [];
           const who = (disc && disc._meta && disc._meta['io.modelcontextprotocol/serverInfo'] &&
             disc._meta['io.modelcontextprotocol/serverInfo'].name) || target;
-          const legacyCapable = versions.some((v) => typeof v === 'string' && v < '2026-07-28');
-          if (legacyCapable) {
+          const { MODERN_PROTOCOL_VERSION } = require('../src/mcp/modern');
+          const legacyCapable = versions.some((v) => typeof v === 'string' && v < MODERN_PROTOCOL_VERSION);
+          if (versions.length === 0) {
+            // An answered discover with NO version list is neither dual-era nor modern-only: say so
+            // instead of reporting "MODERN-ONLY (speaks )".
+            process.stderr.write('[toolfunnel] era probe: "' + who + '" answered server/discover without a supportedVersions list - ' +
+              'treating it as MODERN (it answered the modern probe); check the server if that is unexpected.\n');
+          } else if (legacyCapable) {
             process.stderr.write('[toolfunnel] era probe: "' + who + '" is DUAL-ERA (speaks ' + versions.join(', ') +
               ') - it already survives the 2026-07-28 cutover on its own; the wrap still curates + gates it.\n');
           } else {
@@ -371,6 +386,71 @@ if (positionals[0] === 'wrap') {
     process.stderr.write('[toolfunnel] wrap failed: ' + ((err && err.message) || err) + '\n');
     process.exit(1);
   });
+} else if (positionals[0] === 'changes') {
+  // Tool descriptor approval: what waits for acceptance, straight from the approvals file
+  // (the gateway writes pending entries there), plus recent upgrade approvals. Read-only.
+  const path = require('node:path');
+  const approvals = require('../src/mcp/tool-approvals');
+  const file = path.join(configHome, 'mcp', 'tool-approvals.json');
+  let doc;
+  try {
+    doc = approvals.loadApprovals(file);
+  } catch (err) {
+    process.stderr.write('[toolfunnel] ' + ((err && err.message) || err) + '\n');
+    process.exit(1);
+  }
+  const arg = (s) => (/^[A-Za-z0-9_.:@/-]+$/.test(s) ? s : JSON.stringify(s));
+  const lines = [];
+  for (const p of approvals.listPending(doc)) {
+    lines.push(`  ${p.upstream} / ${p.tool}  (${p.reason}, waiting since ${p.since || 'unknown'})`);
+    lines.push(`    approved:     ${p.approvedDescription == null ? '(none - a new tool)' : (p.approvedDescription || '(no description)')}`);
+    lines.push(`    new:          ${p.newDescription || '(no description)'}`);
+    lines.push(`    changed:      ${p.changed.join(', ')}`);
+    for (const [f, v] of Object.entries(p.fields)) {
+      lines.push(`    ${f} approved: ${JSON.stringify(v.approved)}`);
+      lines.push(`    ${f} new:      ${JSON.stringify(v.new)}`);
+    }
+    lines.push(`    accept:       toolfunnel accept ${arg(p.upstream)} ${arg(p.tool)} --hash ${p.hash}`);
+  }
+  const upgrades = approvals.listUpgrades(doc, 10);
+  if (lines.length) {
+    process.stdout.write('Tool changes waiting for acceptance (the server version did not change, or strictApproval is on):\n' + lines.map(approvals.printable).join('\n') + '\n');
+  } else {
+    process.stdout.write('No tool changes are waiting.\n');
+  }
+  if (upgrades.length) {
+    process.stdout.write('Approved automatically on a server version upgrade (latest first):\n' +
+      upgrades.map((u) => approvals.printable(`  ${u.upstream} / ${u.tool}  (${u.at || 'unknown'})`)).join('\n') + '\n');
+  }
+  process.exit(0);
+} else if (positionals[0] === 'accept') {
+  // Accept a held tool change through the same engine function every route uses (acceptInFile).
+  // A running gateway applies it from the next call.
+  const path = require('node:path');
+  const approvals = require('../src/mcp/tool-approvals');
+  const upstream = positionals[1];
+  const tool = positionals[2];
+  if (!upstream) {
+    process.stderr.write('Usage: toolfunnel accept <upstream> [tool] [--hash <sha256:...>]\n');
+    process.exit(1);
+  }
+  const hash = flagValue('--hash', undefined);
+  let res;
+  try {
+    res = approvals.acceptInFile(path.join(configHome, 'mcp', 'tool-approvals.json'), upstream, tool, hash);
+  } catch (err) {
+    process.stderr.write('[toolfunnel] ' + ((err && err.message) || err) + '\n');
+    process.exit(1);
+  }
+  const why = approvals.acceptFailure(res, upstream, tool);
+  if (why) {
+    process.stderr.write(approvals.printable('[toolfunnel] ' + why + (res.stale ? '. Run `toolfunnel changes` to see the current one.' : '')) + '\n');
+    process.exit(1);
+  }
+  process.stdout.write(approvals.printable('Accepted: ' + res.accepted.join(', ') + '.' +
+    (res.pending.length ? ' Still waiting: ' + res.pending.join(', ') + '.' : '') +
+    ' A running gateway applies this from the next call.') + '\n');
+  process.exit(0);
 } else if (positionals[0] === 'install-oauth') {
   // Opt-in OAuth: pull the single audited dependency (jose) on demand. Keeps the default install
   // at zero runtime dependencies - you only ever fetch jose if you decide you need OAuth.
@@ -392,9 +472,8 @@ if (positionals[0] === 'wrap') {
       process.exit(1);
     });
 } else if (positionals.length) {
-  // An unrecognised COMMAND word must refuse loudly - starting the default server instead left
-  // a mistyped/misplaced subcommand running a gateway the user never asked for, with zero
-  // feedback (cold-start field test, 2026-07-18).
+  // An unrecognised COMMAND word must refuse loudly - starting the default server instead would
+  // leave a mistyped/misplaced subcommand running a gateway the user never asked for.
   process.stderr.write('[toolfunnel] unknown command "' + positionals[0] + '" - nothing started. See toolfunnel --help.\n');
   process.exit(1);
 } else if (args.includes('--ui')) {

package/docs/KNOWN_BUGS.md

@@ -1,8 +1,7 @@
 # Known bugs
 
-The **Open** list is what remains open as of 0.7.0. **Fixed in 0.7.0** marks the items from
-0.6.0's file that this release closed - kept and marked rather than silently deleted, so a
-0.6.0 reader can see their fate. The full change list is in the
+The **Open** list is what remains open as of 0.8.0. **Fixed in 0.8.0** marks the defects a
+0.7.x user could meet that this release closed. The full change list is in the
 [release notes](https://github.com/Rendeverance/toolfunnel/releases).
 
 ## Open
@@ -13,7 +12,7 @@ The **Open** list is what remains open as of 0.7.0. **Fixed in 0.7.0** marks the
   upstream is in scope.
 - **OPEN - The elicitation bridge does not cover legacy clients.** A wrapped upstream's mid-call
   `elicitation/create` bridges to MODERN clients as MRTR (`input_required` + retry), form and url
-  mode, gated on the caller's declared capability (0.7.0). A LEGACY client gets an automatic
+  mode, gated on the caller's declared capability. A LEGACY client gets an automatic
   decline instead - relaying backwards requests to legacy clients is unbuilt - and
   `sampling/createMessage` / `roots/list` from upstreams are answered `-32601`. An elicitation can
   only be bound to a call when exactly ONE wrapped call is in flight for that upstream (always
@@ -26,32 +25,45 @@ The **Open** list is what remains open as of 0.7.0. **Fixed in 0.7.0** marks the
   and wrapped tool calls; the remaining best-effort windows there are sub-millisecond (a cancel
   racing the instant a forward is issued) plus the PreToolUse gate-evaluation phase of a tool
   call (registered at upstream-issue time, post-gate).
+- **OPEN - A wrapped server's `instructions` are not covered by tool approval.** Tool descriptor
+  approval pins each tool's model-facing fields (`name`, `title`, `description`, `inputSchema`,
+  `outputSchema`, `annotations`). In wrap mode the wrapped server's `instructions` also reach the
+  model, unpinned, and a tool's `_meta`, `execution` and `icons` are forwarded without being
+  hashed. Pinning `instructions` is planned.
+- **OPEN - A command on a drive mounted after startup stops being retried.** A missing command is a
+  permanent failure: about five minutes of retries, then the upstream stops (named on stderr and
+  in `/health.stopped`) until `expose.json` is saved, the gateway restarts, or the upstream is
+  reconnected. A drive or share that appears later than that is not noticed on its own.
+- **OPEN (minor) - A very large approvals file slows refused calls.** Each refused call re-reads
+  `mcp/tool-approvals.json`; at 22 MB that costs about half a second per refused call. A home
+  with two real upstreams holds about 250 KB.
 
-## Fixed in 0.7.0
+## Fixed in 0.8.0
 
-- ***FIXED*** - **Legacy version negotiation.** 0.6.0 answered every `initialize` with
-  2024-11-05 whatever the client asked for, and supported exactly one legacy revision. The
-  gateway now echoes the requested version when it supports it (else answers its latest legacy),
-  and the legacy set spans 2024-11-05 / 2025-03-26 / 2025-06-18 / 2025-11-25. Pinned by
-  `test/negotiation.test.js`. One direction remains conservative: the client still offers
-  2024-11-05 to legacy upstreams (field fidelity is unaffected; only the advertised version
-  string is older than either end requires).
-- ***FIXED*** - **Header validation used a generic error code for an unsupported version.** An
-  unsupported `MCP-Protocol-Version` header answered the generic `-32600`; it now answers
-  `-32022` with `data.supported` and `data.requested` - the same code and shape the `_meta`
-  path already used for the same condition, so a client can renegotiate without parsing prose.
-  Pinned by `test/header-enforcement.test.js`.
-- ***FIXED*** - **The wrap's identity-mirror reconnect re-ran the full era negotiation** (worst
-  case roughly 3 s per respawn against an upstream that ignores `server/discover`). The
-  negotiated era is now remembered per upstream, and a death-driven reconnect goes straight to
-  the era it knows. A failed hinted connect or an explicit reconnect re-negotiates in full, so
-  an upstream upgraded across a restart is never pinned down an era. Pinned by
-  `test/reconnect-era-memo.test.js`.
-- ***FIXED*** - **`io.modelcontextprotocol/logLevel` was stripped on wrapped forwards.** Now
-  era-keyed at the client boundary: a modern upstream gets the caller's level verbatim in
-  `_meta`; a legacy upstream that declared the `logging` capability gets `logging/setLevel`
-  issued before the call (and the key never leaks into legacy `_meta`). Pinned by
-  `test/loglevel.test.js`.
+- ***FIXED*** - **A hook's decision was ignored when the hook printed anything before its JSON.**
+  The exit code decided instead, so a gate that logged a line and then denied, exiting 0, let the
+  call through. The decision is now read wherever it sits, and two different decisions (a hook
+  that echoes model-supplied text after its own answer) fail closed. Pinned by
+  `test/gate-semantics.test.js`.
+- ***FIXED*** - **The hook engine substituted stand-ins when one of its parts failed to load.** It
+  now refuses to load and names the missing part. Pinned by `test/hook-engine-requires.test.js`.
+- ***FIXED*** - **Child hooks saw the wrong `HOOKS_DIR` and `CLAUDE_PROJECT_DIR`.** Both now point
+  at the config home. Pinned by `test/hook-env.test.js`.
+- ***FIXED*** - **A relative upstream `cwd` was checked against one directory and spawned in
+  another.** The isolation guard and the spawn now both resolve it against the config home.
+  Pinned by `test/upstream-cwd.test.js`.
+- ***FIXED*** - **Stopping a stdio gateway could leave its upstreams running (POSIX).** SIGINT or
+  SIGTERM now closes every upstream, then exits 130 or 143. Pinned by
+  `test/stdio-shutdown.test.js`.
+- ***FIXED*** - **A permanent startup failure retried forever, and on Windows a missing command
+  looked like a crashing server.** A missing command, a missing working directory or an isolation
+  refusal now stops after about five minutes with one line naming the cause, and shows in
+  `/health.stopped`. Pinned by `test/permanent-failure-ceiling.test.js`.
+- ***FIXED*** - **A wrong-typed config field was coerced or dropped silently.** The config now
+  refuses to load, naming the file, the entry and the field. Pinned by
+  `test/fail-loud-config.test.js`.
+- ***FIXED*** - **The legacy dispatcher answered notifications.** A notification now never gets a
+  reply. Pinned by `test/legacy-notifications.test.js`.
 
 ## By design (not bugs)
 
@@ -76,5 +88,13 @@ These answer "why doesn't it do X". They are considered decisions, not defects.
 - **Discover works on a DISABLED upstream**, so its tools can be inspected before enabling. An
   explicit allowance on the discover path only; the disabled upstream never reaches the tool
   surface.
+- **Upstreams connect all at once, with no concurrency cap.** Right for the handful to tens of
+  upstreams a gateway holds.
+- **The legacy SSE transport's dead-client prune branch never runs.** The stream's close and error
+  handlers already clean up; the only effect is a counter that reads high. Cosmetic.
+- **Tool approval trusts a version bump.** A change at the same server version waits for
+  acceptance; a changed version is approved and reported, because that is what an update looks
+  like. A maintainer can bump the version too: `strictApproval: true` on an upstream holds every
+  change for acceptance.
 
 Found a bug, or want to help with the open work? Issues and PRs are welcome.

package/docs/design.md

@@ -63,7 +63,7 @@ caller speaks - stripping a server's own fields would be data loss and a wrapper
 
 Everything mutable (tools, upstreams, hooks, identity, logs) lives in the config home,
 relocatable with `--config-dir` or `TOOLFUNNEL_HOME`, seeded once, never overwritten by
-updates. One folder to back up, one folder to package, one folder to hand a colleague. The
+updates (a tool new in a release is added to the register once). One folder to back up, one folder to package, one folder to hand a colleague. The
 gateway prints the resolved home at every start so there is never any doubt about where state
 lives.
 

package/docs/packaging.md

@@ -19,7 +19,8 @@ TOOLFUNNEL_HOME=D:\my-setup toolfunnel  # env var
 An empty home is **seeded** on first use from the shipped defaults (the register + management
 scripts, an empty `mcp/expose.json`, the default hooks manifest) and is **never overwritten**
 afterwards - which is the point: with the home outside the package, `npm update toolfunnel`
-can never eat your tools.
+can never eat your tools. The one thing an update adds is a tool new in that release, appended
+to your register once; a shipped tool you removed is never put back.
 
 ```
 <home>/

package/mcp/servers/mock-modern/server.js

@@ -21,7 +21,7 @@
  * Tools (real upstream names): ping -> "pong", add {a,b} -> a+b, echo {text} -> text.
  *
  * JSON-RPC 2.0 over stdio, newline-delimited (one compact JSON object per line). Node built-ins
- * only, CommonJS. Built to the RC spec (locked 2026-05-21); reconcile minor final deltas 28 July.
+ * only, CommonJS.
  */
 
 const MODERN_VERSION = '2026-07-28';

package/mcp/servers/mock-upstream/server.js

@@ -15,8 +15,7 @@
  *
  * Protocol: JSON-RPC 2.0 over stdio with NEWLINE-DELIMITED framing - one compact JSON object per
  *   line, "\n"-terminated, the MCP stdio transport every real SDK-based server speaks. We read lines
- *   on stdin and answer in kind on stdout. (This fixture used to parse LSP Content-Length framing,
- *   matching an old client bug; both were corrected together so the mock represents a REAL server.)
+ *   on stdin and answer in kind on stdout.
  *
  * Tools exposed (real upstream names):
  *   - ping              -> "pong"
@@ -33,7 +32,7 @@
 
 const PROTOCOL_VERSION = '2024-11-05';
 // `title` is a fidelity fixture: the 2025-06-18 spec added serverInfo.title, and the wrap must
-// deliver it VERBATIM (a whitelist in wrappedIdentity used to eat it - found wire-testing the wrap, 2026-07-17).
+// deliver it VERBATIM.
 const SERVER_INFO = { name: 'mock-upstream', version: '1.0.0', title: 'Mock Upstream Fixture' };
 
 const TOOLS = [
@@ -44,7 +43,7 @@ const TOOLS = [
   },
   {
     // title + annotations are fidelity fixtures: real servers ship them (and newer fields), and a
-    // transparent wrap must advertise the def BYTE-IDENTICAL (a projection used to drop both).
+    // transparent wrap must advertise the def BYTE-IDENTICAL.
     name: 'add',
     title: 'Add Numbers',
     description: 'Add two numbers and return the sum.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolfunnel",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "A zero-dependency MCP gateway: host your own tools, forward and curate tools from other MCP servers, expose them leanly to cut agent token cost, and gate every call through your own policy hooks before it runs.",
   "keywords": [
     "mcp",

package/src/auth/config.js

@@ -39,6 +39,7 @@ const path = require('node:path');
 /** The CONFIG HOME (TOOLFUNNEL_HOME / --config-dir; defaults to the package root - see
  *  src/core/config-home.js). Auth config is user-state, so it lives with the home. */
 const { resolveConfigHome } = require('../core/config-home');
+const { atomicWriteJson } = require('../core/atomic-write'); // THE atomic writer, shared by every store
 const ROOT = resolveConfigHome();
 
 /** The toggle/config file. NOT created until setConfig() writes it. */
@@ -163,10 +164,7 @@ function setConfig(patch) {
   };
 
   fs.mkdirSync(path.dirname(CONFIG_PATH), { recursive: true });
-  // Atomic write: unique temp file in the same dir, then rename over the target.
-  const tmp = CONFIG_PATH + '.' + process.pid + '.' + Date.now() + '.tmp';
-  fs.writeFileSync(tmp, JSON.stringify(next, null, 2) + '\n');
-  fs.renameSync(tmp, CONFIG_PATH);
+  atomicWriteJson(CONFIG_PATH, next); // temp + fsync + rename, failure-path unlink, stale sweep
 
   return next;
 }

package/src/auth/resource-server.js

@@ -125,16 +125,21 @@ async function resolveJwksUri(cfg, timeoutMs) {
           /* malformed URL on either side -> treat as cross-origin -> refuse */
         }
         if (!sameOrigin) {
-          throw new Error(
+          const refusal = new Error(
             `discovered jwks_uri "${doc.jwks_uri}" is not on the issuer origin - refusing the ` +
               'cross-origin discovery result. If your IdP intentionally hosts JWKS on a separate ' +
               'origin, state that trust explicitly by setting "jwksUri" in auth/auth.config.json.'
           );
+          refusal.code = 'JWKS_ORIGIN_REFUSED'; // an operator-config verdict: no later candidate can remedy it
+          throw refusal;
         }
         return doc.jwks_uri;
       }
       lastErr = new Error(`discovery doc at ${url} has no jwks_uri`);
     } catch (e) {
+      // Last-error-wins hid the actionable refusal behind whatever the LAST candidate said (usually a
+      // plain 404). The refusal is final: surface it now.
+      if (e && e.code === 'JWKS_ORIGIN_REFUSED') throw e;
       lastErr = e;
     }
   }

package/src/core/atomic-write.js

@@ -0,0 +1,97 @@
+'use strict';
+
+/**
+ * atomic-write.js - THE atomic file writer (temp in the same directory + fsync + rename).
+ *
+ * One implementation for every store the gateway persists: the tool register and its scripts,
+ * the tool-state overlay, the expose store, the hooks manifest / state / scripts, toolfunnel.json
+ * and the rename migration. Four copies of this pattern had drifted apart (one lacked the
+ * failure-path unlink and the stale sweep; three wrote with a single writeSync where the loader's
+ * looped) - the exact "hardening decision made in one place and never carried to its sibling"
+ * fingerprint. orphan-tmp.test.js pins both the contract below and the fact that this is the
+ * ONLY module under src/ that performs the rename.
+ *
+ * Contract:
+ *   - A crash leaves either the old file or the complete new file, never a half-written one: the
+ *     data goes to `.<base>.<pid>.<ts>.tmp` beside the target (same volume, so the rename is
+ *     atomic), is fsync'd, then renamed over the target.
+ *   - 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.
+ *   - STALE strandings from writers that died mid-flight (same temp shape, older than
+ *     STALE_TMP_MS) are swept on the next write of the same target; a FRESH sibling (a concurrent
+ *     writer's in-flight temp) is left alone. Sweeping is best-effort and never fails a write.
+ *   - writeFileSync(fd, ...) loops until every byte is written (a bare writeSync may return short).
+ *   - Bytes are written exactly as given (no line-ending normalisation - shell scripts may be
+ *     CRLF-sensitive).
+ *
+ * CommonJS, Node built-ins only.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * 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. 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
+ * writer below produces). 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 */ }
+  }
+}
+
+/**
+ * Atomically write text to `targetPath`. See the module contract.
+ * @param {string} targetPath  absolute destination
+ * @param {string|Buffer} data
+ * @param {string} [tmpDir]    directory for the temp file (default: the target's own; must be the
+ *                             same volume as the target for the rename to be atomic)
+ */
+function atomicWriteText(targetPath, data, tmpDir) {
+  const dir = tmpDir || path.dirname(targetPath);
+  const base = path.basename(targetPath);
+  sweepStaleTmp(dir, base);
+  const tmp = path.join(dir, `.${base}.${process.pid}.${Date.now()}.tmp`);
+  try {
+    const fd = fs.openSync(tmp, 'w');
+    try {
+      fs.writeFileSync(fd, data); // loops until every byte is written
+      try { fs.fsyncSync(fd); } catch (_e) { /* fsync may be refused on some filesystems; the rename is still ordered */ }
+    } finally {
+      try { fs.closeSync(fd); } catch (_e) { /* ignore */ }
+    }
+    // rename is atomic on the same filesystem and overwrites the destination on POSIX; on Windows
+    // it overwrites too as long as the target isn't locked.
+    fs.renameSync(tmp, targetPath);
+  } catch (err) {
+    try { fs.unlinkSync(tmp); } catch (_e) { /* best-effort - the error below is the story */ }
+    throw err;
+  }
+}
+
+/**
+ * Atomically write a JS object as pretty JSON (2-space, trailing newline). See the module contract.
+ * @param {string} targetPath absolute destination
+ * @param {object} obj
+ */
+function atomicWriteJson(targetPath, obj) {
+  atomicWriteText(targetPath, JSON.stringify(obj, null, 2) + '\n');
+}
+
+module.exports = { atomicWriteJson, atomicWriteText, sweepStaleTmp, STALE_TMP_MS };