toolfunnel 0.4.0 → 0.5.0

package/docs/KNOWN_BUGS.md

@@ -1,225 +1,33 @@
-# ToolFunnel — 0.4.0 Board (bugs + features)
+# Known issues & roadmap
 
-> Items 1–5: findings from a full source review on **2026-07-03** (v0.3.0, commit `1c5841c`),
-> each ranked, located, explained, and paired with a proposed fix.
-> **All five FIXED 2026-07-06** in commit `6c9821c` (suite 23/23) — the detail sections below are
-> kept as the record of what was wrong and why the fix took the shape it did.
-> Items 6–9: the 0.4.0 feature board (identity, verification passes, packaging).
->
-> **Context for future-me:** the core gate architecture reviewed as *sound* — see
-> "What is already solid" at the bottom before re-auditing. Do not re-review the
-> whole tree; start from this list.
+ToolFunnel has no known correctness bugs at this release. This file tracks the upcoming
+compatibility work and any limitations worth knowing about.
 
----
+## Coming in 0.6.0 — the 2026-07-28 MCP specification
 
-## The board
+The 2026-07-28 MCP revision is a **breaking** change to the protocol: it removes the `initialize`
+handshake, protocol-level sessions, and the standalone GET/SSE endpoint, and adds new required
+behaviours — per-request protocol metadata, `Mcp-Method` / `Mcp-Name` request headers, a
+`server/discover` endpoint, a `subscriptions/listen` change-notification stream, and
+`resultType` / `ttlMs` / `cacheScope` result fields.
 
-| # | Kind | Area | One-liner | Status |
-|---|------|------|-----------|--------|
-| 1 | **High** bug | UI server | Config UI could bind off-loopback with NO auth and NO refusal — unauthenticated LAN RCE surface | **FIXED** `6c9821c` |
-| 2 | Low bug | mcp-client (win) | `winLaunch` cmd.exe metacharacter interpretation — "no injection surface" comment was overstated | **FIXED** `6c9821c` (honest caveat) |
-| 3 | Low bug | aggregator | `_scheduleReconnect` logged `reconnect_slow` every 30s forever instead of once at the transition | **FIXED** `6c9821c` |
-| 4 | Low bug | http-transport | Streaming (chunked) over-cap body didn't get the clean `-32700` — and the "engineered" declared-CL path had the same RST flaw | **FIXED** `6c9821c` (half-close) |
-| 5 | Defensive | auth/resource-server | OIDC discovery followed redirects with no origin-check on the discovered `jwks_uri` | **FIXED** `6c9821c` (origin pin) |
-| 6 | Feature | mcp/server | Configurable server identity — `serverName`/`serverVersion` **and the default `--http`/`--ui` ports** — so a wrapped MCP introduces itself under ITS name and ships its own port defaults. Defaults unchanged. | **DONE** `a734f4b` (toolfunnel.json) |
-| 7 | Verify | protocol/register | Confirm the SCHEMA a hot-promoted register tool advertises is the author's real inputSchema (README promises "your own tools and schemas") | **DONE** `4c219e4` — plumbing was sound; tf_tool_add DROPPED the field (fixed), validated + documented now |
-| 8 | Verify | reload | Confirm `tools.register.json` edits are picked up live — the file-watchers are proven for `mcp/expose.json` + hooks; direct register edits may need a reload path | **DONE** `4c219e4` — was a REAL BUG (startup snapshot); Registry.reload() + tools/ watcher + state list_changed |
-| 9 | Feature | packaging | External config home (`TOOLFUNNEL_HOME` / `--config-dir`) + the full packaging story — see below | **DONE** `108db4e` (home) + `bc88c53` (tf_pack + requires) + `a1fa845` (docs) |
+ToolFunnel 0.5.0 speaks the current `2024-11-05` protocol and works with every MCP client shipping
+today. **0.6.0** will add **dual-era** support — answering both the current handshake-based clients
+*and* the 2026-07-28 modern clients — built against the finalised spec after 28 July.
 
----
+Planned for 0.6.0:
 
-## 9. The packaging story (the 0.4.0 headline)
+- **Dual-era transport** (current + 2026-07-28) so old and new clients both keep working.
+- `server/discover`, the new request-header validation, and the `subscriptions/listen` stream.
+- An **opt-in, per-upstream legacy-protocol shim**: keep an ageing MCP server working past the
+  cutover by pinning the protocol version ToolFunnel speaks *to that upstream* — off by default,
+  it names the exact version it drops to and warns at startup and on every call.
 
-**The problem:** an npm/npx install keeps its config *inside the package directory* — an
-`npm update` EATS the user's tools, hooks, and curation. Config must live in a home of its own.
+## Current limitations
 
-**Four pieces, in dependency order:**
+- The OAuth 2.1 resource-server and Streamable-HTTP support are recent and less battle-tested than
+  the core — test your setup before relying on them in a networked deployment.
+- No Prometheus / OpenTelemetry metrics — a toggleable JSONL audit log and in-memory `/health`
+  call counters only.
 
-1. **Config home** — `TOOLFUNNEL_HOME` env var / `--config-dir` flag; default stays the repo root
-   for a git clone (unchanged), but an npm-installed gateway defaults to a per-user home. The
-   enabler for everything below.
-2. **Tool-pack** — a pack IS a zipped config home. Docs, not code: the layout already travels
-   (`tools/` + `tools.register.json` + `mcp/expose.json` + `hooks/`).
-3. **npm-wrap** — docs + a worked example, no core code: a third party publishes THEIR package
-   with **`toolfunnel` as a dependency (caret range — DEPEND, NEVER COPY)**, their pack bundled,
-   and a 2-line `bin` that points toolfunnel at the bundled config home → `npx their-mcp`.
-   - Their own runtime deps go in THEIR `package.json` — npm installs the whole tree on npx;
-     script tools resolve `require()` relative to themselves. We add no machinery.
-   - Why depend-not-copy: every install of their MCP is a toolfunnel download; our security
-     fixes reach every wrapped MCP via normal `npm update`; no stale forks. (This batch's UI-bind
-     fix is the worked example of why.)
-4. **requires-preflight** — a `requires` field in the pack manifest (JSON only) checked with
-   `child_process` version probes + a hand-rolled version compare; friendly missing-runtime
-   errors ("this pack needs python ≥3.10").
-
-**★ HARD CONSTRAINT: ToolFunnel itself gains ZERO runtime dependencies from any of this.**
-JSON manifest (no yaml), hand-rolled version compare (no semver), node built-ins only.
-
-**Packs are COMPOSITE** (already true today — `mcp/expose.json` lives in the config home):
-own scripts + upstream MCP references + curation in one pack.
-- Upstreams travel as REFERENCES (npx self-fetches them; pin versions in the pack).
-- Curation travels — ship the 4 chosen tools, not the whole upstream server.
-- **THE GATE TRAVELS** — a shipped pack enforces its policy hooks on the recipient's machine
-  regardless of which MCP client they use. Nobody else can say this sentence.
-- Audit honesty: packs spawn commands. The docs say it plainly — read the `expose.json` of
-  anything you install.
-
----
-
-## 1. [HIGH] UI server binds off-loopback with no auth and no refusal
-
-**Files:** `src/ui/server.js` (`createUiServer().start()`, `isLoopbackHost`), `bin/toolfunnel.js` (`--ui --host`)
-
-**The asymmetry.** `src/mcp/http-transport.js` `start()` refuses to bind a non-loopback host
-unless OAuth is enabled:
-
-> `refusing to bind non-loopback host "<host>" without OAuth enabled — enable auth (and install jose) before exposing the gateway off localhost.`
-
-The **UI server has no equivalent guard.** `createUiServer().start()` binds whatever `host`
-it is handed, and `bin/toolfunnel.js` passes `--ui --host <anything>` straight through to it.
-
-**Why the existing check does not cover it.** `isLoopbackHost()` inside the UI's `onRequest`
-tests only the **`Host` request header**, which is fully attacker-controlled. It defends against
-*browser* DNS-rebinding (the browser sets the Host to the attacker's domain), but does **nothing**
-against a direct, non-browser client that simply sends `Host: localhost` / `Host: 127.0.0.1`.
-
-**Why it matters more than the transport.** The config UI is the one surface that can *spawn
-processes and mutate the security posture*:
-- `POST /api/mcp/add` + `POST /api/mcp/discover` construct an `Aggregator` and **connect the
-  configured upstream — i.e. spawn the configured command** (`aggregator.discover` → `_connectOne`
-  → `clientFactory` → `McpClient.connect`).
-- `POST /api/tools/add` / `/api/tools/update` **write tool scripts** to `tools/scripts/`.
-- `POST /api/tools/hook` / `/api/hooks/*` **toggle the gate hooks.**
-
-So `toolfunnel --ui --host 0.0.0.0` (a plausible "let me reach the config UI from my other
-machine" move) exposes an **unauthenticated, process-spawning, script-writing console to the
-LAN**. The HTTP transport learned this exact lesson; the UI never got the same stitch.
-
-**Fix.** The UI has no auth path at all, so the correct behaviour is a hard refusal, mirroring the
-transport's guard. In `createUiServer().start()`, before `httpServer.listen(...)`:
-
-```js
-if (!isLoopbackHost(host)) {
-  return Promise.reject(new Error(
-    `refusing to bind the config UI to non-loopback host "${host}" — the UI is ` +
-    `unauthenticated and can spawn processes / write scripts. It is loopback-only by design.`
-  ));
-}
-```
-
-(Note: `isLoopbackHost` currently returns `true` for an *empty/missing* value — fine for a Host
-*header*, but for a *bind address* an empty host should not be treated as loopback. Use a stricter
-check on the bind arg, or default-and-validate the bind host explicitly.)
-
-**Test to add:** `createUiServer({ host: '0.0.0.0' }).start()` rejects; `'127.0.0.1'`, `'localhost'`,
-`'::1'` resolve.
-
----
-
-## 2. [LOW] `winLaunch` cmd.exe metacharacter interpretation — comment overstates safety
-
-**File:** `src/mcp/mcp-client.js` (`winLaunch`)
-
-On Windows, a non-`.exe` upstream command is routed through `cmd.exe /c <command> <args…>` with
-`shell:false` (the CVE-2024-27980 `.cmd` workaround). The code comment claims:
-
-> "The args stay DISCRETE (Node escapes each one under shell:false) so nothing is shell-concatenated
-> — no injection surface on this privileged path."
-
-**That guarantee is not quite real.** With `shell:false` and the command being `cmd.exe` (an
-`.exe`), Node applies its *standard argv quoting*, **not** cmd.exe metacharacter (`^`) escaping —
-that special-casing only fires when the *command itself* is the `.cmd`/`.bat`. So a config arg
-containing `& | > < "` can be reinterpreted by cmd.exe.
-
-**Real-world risk: near-zero.** These args come from `expose.json`, authored by the operator — the
-"attacker" would be the person who owns the config. But the comment claims a property the code does
-not provide.
-
-**Fix (pick one):**
-- Downgrade the comment to state the residual cmd.exe-parsing caveat honestly, **or**
-- Defensively quote each arg for cmd.exe, **or**
-- Prefer resolving the real interpreter path (`where npx` → the `node` + `npm-cli.js` shape, as
-  `auth/install.js` already does for npm) and spawn that directly with `shell:false`, avoiding
-  `cmd.exe` entirely.
-
----
-
-## 3. [LOW] `_scheduleReconnect` spams `reconnect_slow` every 30s forever
-
-**File:** `src/mcp/aggregator.js` (`_scheduleReconnect`)
-
-Past `MAX_FAST_ATTEMPTS` (6) the method re-schedules with `Math.min(attempt + 1, MAX_FAST_ATTEMPTS)`
-→ the attempt counter **sticks at 6**. The entry logs `if (attempt === MAX_FAST_ATTEMPTS)`, so a
-permanently-dead-but-enabled upstream emits a `reconnect_slow` log line **every 30 seconds
-indefinitely**, rather than once at the fast→slow transition.
-
-**Fix.** Log the transition only. E.g. only log when entering the slow phase from the fast phase
-(track the previous attempt, or log inside the `attempt + 1` escalation exactly when it crosses
-`MAX_FAST_ATTEMPTS`, not on every subsequent capped re-entry).
-
----
-
-## 4. [LOW] Streaming over-cap body misses the clean `-32700` the declared-CL path produces
-
-**File:** `src/mcp/http-transport.js` (`readBody`, `handleMcpPost`)
-
-The **declared-Content-Length** over-cap path is carefully engineered (`sendJsonAndClose`: announce
-`Connection: close`, flush the `-32700` body, *then* destroy the request in the `res.end` callback)
-so the client receives a clean parse-error before the close.
-
-The **streaming/chunked** over-cap path is not held to the same standard: `readBody` rejects and
-immediately `req.destroy()`s. Because `req` and `res` share the socket, the follow-up
-`sendJson(res, 200, makeError(...))` in `handleMcpPost`'s catch writes to a torn-down socket → the
-client sees `ECONNRESET` instead of the tidy `-32700`.
-
-**Not a crash** — every path here is defensive and the server survives. It is an inconsistency: two
-over-cap paths that should behave identically don't.
-
-**Fix.** Route the streaming over-cap case through the same flush-then-close sequence as
-`sendJsonAndClose` (don't `req.destroy()` before the response body has flushed).
-
----
-
-## 5. [DEFENSIVE] OIDC discovery follows redirects with no origin-check on discovered `jwks_uri`
-
-**File:** `src/auth/resource-server.js` (`resolveJwksUri`, `fetchJson`)
-
-`fetchJson` uses `redirect: 'follow'`, and `resolveJwksUri` accepts whatever `jwks_uri` the issuer's
-discovery document advertises with no check that it shares the issuer's origin. The issuer is
-operator-configured (trusted), and audience binding is still enforced on the verified token, so this
-is standard OIDC behaviour and low-risk — but a defensive origin-pin on the discovered `jwks_uri`
-(and/or `redirect: 'error'` on discovery) would tighten the SSRF-adjacent surface.
-
-**Fix (optional hardening):** assert the discovered `jwks_uri` origin matches the issuer origin, or
-make it opt-out-able. Document the decision either way.
-
----
-
-## What is already solid (do NOT re-audit from scratch)
-
-The review found the **gate architecture sound**. Confirmed on 2026-07-03:
-
-- **`gatedRun` fails CLOSED on every bad-wiring path** — no engine / junk engine return / engine
-  throw all → `blocked:true`, `execute()` never called. The load-bearing invariant ("a PreToolUse
-  deny prevents `execute()` from ever running") is real and centralised in one auditable place
-  (`src/mcp/gated-run.js`).
-- **The engine proxy reads `build.engine` live** (`src/mcp/server.js`), so a hot-reloaded hook gates
-  BOTH the `toolfunnel_run_tool`/lean path AND the curated-direct path — no stale-engine gap.
-- **OAuth validator does the things that matter** (`src/auth/resource-server.js`): pins the algorithm
-  allowlist (blocks alg-confusion + `alg:none`), enforces `audience` (RFC 8707 confused-deputy
-  defence) and `issuer`, requires `exp` present, never reads the token header to choose the alg.
-- **Isolation guard on path-shaped upstream args** (`aggregator.defaultClientFactory` / `isInside` /
-  `looksLikePath`) — a vendored upstream can't point outside the gateway root; the interpreter slot
-  is correctly exempt.
-- **Path-escape defences** in `registry.writeScript` and `defaultRunScript` (basename + in-root
-  assertion), and **atomic temp+rename writes** across registry / tool-state / expose-store / auth
-  config / logger.
-- **The hook matcher is correctly full-anchored** (`^(?:…)$` in `src/core/matcher.js`), so a gate on
-  `read` does NOT leak onto `read_file`; combined with the UI's `escapeRegex` on gate writes, that
-  path is right.
-- **`McpClient` framing was fixed** in v0.3.0 to newline-delimited JSON (was LSP `Content-Length`),
-  with dual-drain read tolerance — proven against `server-everything` / `server-filesystem` + the
-  official SDK client. Zombie-guard tree-kill on close.
-
-The v0.3.0 adversarial pass (backlog task #49) did real work on the OAuth/transport surface. Finding
-#1 above is the one gap that pass did not close (it hardened the *transport*, not the *UI*).
+Found a bug, or want to help with the 0.6.0 work? Issues and PRs are welcome.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolfunnel",
-  "version": "0.4.0",
+  "version": "0.5.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/mcp/http-transport.js

@@ -300,6 +300,8 @@ function createHttpMcpServer(opts = {}) {
   /** @type {boolean} latch so stop() is idempotent and start() can't double-bind. */
   let started = false;
   let stopping = false;
+  /** @type {(() => void)|null} teardown for the config hot-reload watchers (armed in start()). */
+  let configWatchersStop = null;
   /**
    * The result of the LAST connectAll() (from start() or reload()), surfaced by health() so a
    * silent upstream connect-failure becomes VISIBLE (otherwise it only reaches stderr via log()).
@@ -414,6 +416,16 @@ function createHttpMcpServer(opts = {}) {
     return pushToSse({ jsonrpc: JSONRPC, method: 'notifications/tools/list_changed' });
   }
 
+  /**
+   * Wire the CURRENT build's aggregator "tools changed" signal (a background reconnect finally
+   * winning an upstream) to the SSE broadcast, so an HTTP client honouring listChanged re-fetches.
+   * Re-called after every build (re)creation because a fresh aggregator has no listener — the stdio
+   * path does the equivalent in main(). NEVER throws.
+   */
+  function wireAggregatorNotify() {
+    if (build && build.aggregator) build.aggregator.onToolsChanged = () => broadcastToolsListChanged();
+  }
+
   // ── OAuth 2.1 resource-server gate (OPTIONAL; default OFF) ──────────────────────────────────
   // The validator is memoised and rebuilt ONLY when the relevant auth config changes — so a live
   // enable/disable/edit takes effect on the next request WITHOUT discarding jose's JWKS cache in
@@ -782,6 +794,7 @@ function createHttpMcpServer(opts = {}) {
     // the very first request. connectAll() NEVER throws (failures land in failed[]); with the
     // default EMPTY expose.json it is an instant no-op.
     build = buildFactory();
+    wireAggregatorNotify();
     if (build && build.aggregator && typeof build.aggregator.connectAll === 'function') {
       try {
         const res = await build.aggregator.connectAll();
@@ -829,6 +842,15 @@ function createHttpMcpServer(opts = {}) {
         boundPort = addr && typeof addr === 'object' ? addr.port : requestedPort;
         started = true;
         stopping = false;
+        // Arm config hot-reload now the build is live + bound. Pass a GETTER so the reloaders
+        // always target the CURRENT build (reload() rebuilds it); send = pushToSse so a
+        // hook/register/expose change broadcasts notifications/tools/list_changed to SSE clients.
+        // This is the wiring the HTTP host was missing — stdio's main() has always done it.
+        try {
+          configWatchersStop = require('./server').startConfigWatchers(() => build, (n) => pushToSse(n));
+        } catch (e) {
+          log('config watchers failed to arm (host runs, without hot-reload):', (e && e.message) || String(e));
+        }
         // Swap the one-shot bind-error handler for a steady-state one so a later socket error
         // (a client RST, etc.) is logged, not thrown.
         httpServer.on('error', (e) => log('http server error:', (e && e.message) || String(e)));
@@ -855,6 +877,14 @@ function createHttpMcpServer(opts = {}) {
     }
     stopping = true;
 
+    // 0. Disarm the config watchers FIRST, so no debounced reload can fire against the build we're
+    //    about to tear down (a reload mutating a half-closed aggregator would be a benign no-op, but
+    //    disarming first is the clean order).
+    if (configWatchersStop) {
+      try { configWatchersStop(); } catch (_e) { /* never throw */ }
+      configWatchersStop = null;
+    }
+
     // 1. Tear down SSE clients: clear their keep-alive timers and end the responses so their
     //    sockets close (an open SSE socket would otherwise keep the server from closing).
     for (const res of Array.from(sseClients)) {
@@ -934,6 +964,7 @@ function createHttpMcpServer(opts = {}) {
     await closeAggregatorSafely();
     // 2. Rebuild from the edited config + reconnect.
     build = buildFactory();
+    wireAggregatorNotify();
     if (build && build.aggregator && typeof build.aggregator.connectAll === 'function') {
       try {
         const res = await build.aggregator.connectAll();

package/src/mcp/server.js

@@ -216,7 +216,9 @@ function makeRegistryAdapter(registry, opts) {
         if (!desc) return null;
 
         // Reference mode: nothing executes here. Hand back the instructions (no execute thunk)
-        // so protocol.runTool short-circuits BEFORE gatedRun — no spawn, no gate.
+        // so protocol.runTool takes the no-spawn path (execute() is never called). Note this is
+        // NOT ungated: protocol.runTool still fires PreToolUse on the instruction handoff, so a
+        // deny withholds the instructions. What's absent is server-side EXECUTION, not the gate.
         if (desc.mode === 'reference') {
           return {
             mode: 'reference',
@@ -934,6 +936,10 @@ function emitToolsListChanged(send) {
  * @returns {Promise<void>}
  */
 async function reloadExpose(build, send) {
+  // NEVER-throws contract. A null/absent build means the caller (e.g. the HTTP host mid-teardown,
+  // which nulls its build) has moved on — do nothing rather than deref null. (reloadHooks/
+  // reloadRegister already guard this; expose was the one unguarded reloader — a proven crash.)
+  if (!build || typeof build !== 'object') return;
   let store;
   try {
     store = loadExposeStore(EXPOSE_PATH);
@@ -953,12 +959,20 @@ async function reloadExpose(build, send) {
   } catch (err) {
     logErr('reloadExpose: connectAll threw (ignored):', (err && err.message) || String(err));
   }
-  const prev = build.aggregator;
-  build.aggregator = next; // swap BEFORE closing the old one (handleMessage reads build fresh)
-  if (prev && typeof prev.closeAll === 'function') {
-    try { await prev.closeAll(); } catch (_e) { /* closeAll never throws, but guard teardown */ }
+  // The swap/close/notify is guarded too: even a surprise (a build torn down DURING the async
+  // connectAll above) must be a caught no-op, not an escaped rejection that crashes the host.
+  try {
+    const prev = build.aggregator;
+    build.aggregator = next; // swap BEFORE closing the old one (handleMessage reads build fresh)
+    if (prev && typeof prev.closeAll === 'function') {
+      try { await prev.closeAll(); } catch (_e) { /* closeAll never throws, but guard teardown */ }
+    }
+    emitToolsListChanged(send);
+  } catch (err) {
+    logErr('reloadExpose: swap failed (keeping last-good):', (err && err.message) || String(err));
+    try { await next.closeAll(); } catch (_e) { /* orphan-avoidance; never throw */ }
+    return;
   }
-  emitToolsListChanged(send);
   // Activity log (self-gating): mark the reload trigger; the per-upstream connect/disconnect lines
   // (from the aggregator) carry the detail. Together they record the reconnect.
   logger.log({
@@ -1014,20 +1028,34 @@ function reloadHooks(build) {
 }
 
 /**
- * Watch the config directories and hot-reload on change. Watches the DIRECTORIES (robust to the
- * atomic temp+rename writes expose-store / hook-loader use, which replace the file inode) and
- * filters by basename. Debounced (a temp+rename burst → one reload), with a re-entrancy guard so a
- * mid-flight expose reload can't overlap itself. A watch failure (an fs that doesn't support
- * fs.watch) is logged and ignored — the server still runs, just without auto-reload. NEVER throws.
+ * Watch the config and hot-reload on change. TWO mechanisms, belt-and-braces:
+ *   1. fs.watch on the DIRECTORIES — fast, event-driven, filtered by basename.
+ *   2. fs.watchFile POLLING on each specific config file — the reliable fallback.
+ * The directory watch alone is NOT enough: fs.watch is event-based and on Windows frequently
+ * MISSES the atomic temp+rename writes the stores use (the target's inode is replaced without a
+ * usable change event on the directory), so a `tf_hook_set` / UI toggle could fail to hot-reload
+ * until restart. fs.watchFile polls each file's stat, so it catches every create/modify (including
+ * atomic rename) on every platform. Both paths feed the SAME debounced schedulers, so a change
+ * that trips both still collapses to one reload. Debounced (a temp+rename burst → one reload),
+ * with a re-entrancy guard so a mid-flight expose reload can't overlap itself. A watch failure (an
+ * fs that supports neither) is logged and ignored — the server still runs, just without
+ * auto-reload. NEVER throws.
  *
  * @param {object} build  the live build object (mutated by the reloaders)
  * @param {(obj:object)=>void} send  the stdio writer
  * @returns {void}
  */
-function startConfigWatchers(build, send) {
+function startConfigWatchers(buildArg, send) {
+  // buildArg may be the build OBJECT (stdio: one stable object, mutated in place) OR a GETTER
+  // () => build. The HTTP host REBUILDS its build (reload()/stop() reassign it), so it passes a
+  // getter — the reloaders then always target the LIVE build and a rebuild can never desync the
+  // watchers. Backward-compatible: a plain object is wrapped in a getter, so stdio is unchanged.
+  const getBuild = typeof buildArg === 'function' ? buildArg : () => buildArg;
   const DEBOUNCE_MS = 150;
   const mcpDir = path.dirname(EXPOSE_PATH);
   const hooksDir = path.dirname(MANIFEST_PATH);
+  const openWatchers = []; // fs.watch handles, closed by the returned stop()
+  const polledFiles = [];  // fs.watchFile paths, unwatched by the returned stop()
 
   let exposeTimer = null;
   let reloadingExpose = false;
@@ -1037,7 +1065,12 @@ function startConfigWatchers(build, send) {
       exposeTimer = null;
       if (reloadingExpose) { scheduleExpose(); return; } // a reload is mid-flight; re-arm
       reloadingExpose = true;
-      try { await reloadExpose(build, send); } finally { reloadingExpose = false; }
+      // reloadExpose is contracted never to throw, but a debounced setTimeout callback has no
+      // caller to catch an escaped rejection — so guard here too (an unhandled rejection would
+      // crash the host on default Node). Belt and braces.
+      try { await reloadExpose(getBuild(), send); }
+      catch (e) { logErr('scheduleExpose: reload rejected (should not):', (e && e.message) || String(e)); }
+      finally { reloadingExpose = false; }
     }, DEBOUNCE_MS);
     if (exposeTimer && typeof exposeTimer.unref === 'function') exposeTimer.unref(); // don't pin the loop
   }
@@ -1045,14 +1078,14 @@ function startConfigWatchers(build, send) {
   let hooksTimer = null;
   function scheduleHooks() {
     if (hooksTimer) clearTimeout(hooksTimer);
-    hooksTimer = setTimeout(() => { hooksTimer = null; reloadHooks(build); }, DEBOUNCE_MS);
+    hooksTimer = setTimeout(() => { hooksTimer = null; reloadHooks(getBuild()); }, DEBOUNCE_MS);
     if (hooksTimer && typeof hooksTimer.unref === 'function') hooksTimer.unref();
   }
 
   let registerTimer = null;
   function scheduleRegister() {
     if (registerTimer) clearTimeout(registerTimer);
-    registerTimer = setTimeout(() => { registerTimer = null; reloadRegister(build, send); }, DEBOUNCE_MS);
+    registerTimer = setTimeout(() => { registerTimer = null; reloadRegister(getBuild(), send); }, DEBOUNCE_MS);
     if (registerTimer && typeof registerTimer.unref === 'function') registerTimer.unref();
   }
 
@@ -1074,6 +1107,7 @@ function startConfigWatchers(build, send) {
     // unref so an FSWatcher never keeps the process alive after the client closes stdin — the
     // gateway must still exit naturally when its transport closes (it did before this feature).
     if (w && typeof w.unref === 'function') w.unref();
+    openWatchers.push(w);
     logErr('startConfigWatchers: watching', mcpDir, 'for expose.json changes');
   } catch (err) {
     logErr('startConfigWatchers: cannot watch', mcpDir + ':', (err && err.message) || String(err));
@@ -1085,6 +1119,7 @@ function startConfigWatchers(build, send) {
       if (!filename || base === 'hooks.manifest.json' || base === 'hooks.state.json') scheduleHooks();
     });
     if (w && typeof w.unref === 'function') w.unref();
+    openWatchers.push(w);
     logErr('startConfigWatchers: watching', hooksDir, 'for hook changes');
   } catch (err) {
     logErr('startConfigWatchers: cannot watch', hooksDir + ':', (err && err.message) || String(err));
@@ -1102,10 +1137,58 @@ function startConfigWatchers(build, send) {
       if (!filename || base === 'tools.state.json') scheduleStateNotify();
     });
     if (w && typeof w.unref === 'function') w.unref();
+    openWatchers.push(w);
     logErr('startConfigWatchers: watching', toolsDir, 'for register/state changes');
   } catch (err) {
     logErr('startConfigWatchers: cannot watch', toolsDir + ':', (err && err.message) || String(err));
   }
+
+  // ── Reliable fallback: fs.watchFile POLLS each config file's stat, so it catches every
+  // create/modify — including the atomic temp+rename writes that fs.watch misses on Windows.
+  // A 1s interval is ample for config (no sub-second reload need); the schedulers debounce, so a
+  // change caught by BOTH the directory watch and the file poll still yields a single reload.
+  // The state overlays (hooks.state.json / tools.state.json) may not exist yet — watchFile fires
+  // when they first appear (a tf_hook_set / tf_tool_set toggle CREATES them), which is the case
+  // the directory watch was dropping.
+  const pollWatch = (file, schedule) => {
+    try {
+      // Retain the listener ref so stop() can unwatchFile(file, listener) — a bare
+      // unwatchFile(file) would remove ALL listeners on that path, clobbering a second host/watcher
+      // set in the same process (parallel tests, an embedder running two hosts).
+      const listener = (curr, prev) => {
+        if (curr.mtimeMs !== prev.mtimeMs || curr.size !== prev.size) schedule();
+      };
+      const sw = fs.watchFile(file, { interval: 1000 }, listener);
+      if (sw && typeof sw.unref === 'function') sw.unref(); // never pin the event loop
+      polledFiles.push({ file, listener });
+    } catch (err) {
+      logErr('startConfigWatchers: cannot poll-watch', file + ':', (err && err.message) || String(err));
+    }
+  };
+  pollWatch(EXPOSE_PATH, scheduleExpose);
+  pollWatch(MANIFEST_PATH, scheduleHooks);
+  pollWatch(path.join(hooksDir, 'hooks.state.json'), scheduleHooks);
+  pollWatch(REGISTER_PATH, scheduleRegister);
+  pollWatch(path.join(toolsDir, 'tools.state.json'), scheduleStateNotify);
+  logErr('startConfigWatchers: fs.watchFile polling fallback armed (Windows-safe)');
+
+  // Teardown handle. The stdio path never calls it (the process dies when stdin closes and the
+  // watchers are all unref'd); the HTTP host calls it in stop() so a started→stopped host leaves
+  // no dangling directory watchers or file pollers.
+  return function stopConfigWatchers() {
+    // Clear any PENDING debounced reload so a change caught just before teardown can't fire a
+    // reload against a torn-down build after the caller has moved on. (It would be a caught no-op,
+    // but a truly-stopped watcher must not schedule work.)
+    for (const t of [exposeTimer, hooksTimer, registerTimer, stateTimer]) {
+      if (t) { try { clearTimeout(t); } catch (_e) { /* ignore */ } }
+    }
+    for (const w of openWatchers) {
+      try { if (w && typeof w.close === 'function') w.close(); } catch (_e) { /* ignore */ }
+    }
+    for (const p of polledFiles) {
+      try { fs.unwatchFile(p.file, p.listener); } catch (_e) { /* ignore */ }
+    }
+  };
 }
 
 // ─────────────────────────────────────────────────────────────────────────────────────────────

package/src/tools/registry.js

@@ -397,8 +397,10 @@ class Registry {
 
     // ---- 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 can short-circuit BEFORE the gate
-    // — a reference tool never spawns and never needs gating (nothing executes).
+    // 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',