toolfunnel 0.3.0 → 0.5.0

package/src/mcp/server.js

@@ -53,7 +53,18 @@ const logger = require('../core/logger');
 const metrics = require('../core/metrics');
 
 // ── Path anchors (everything stays under the host root) ───────────────────────────────────────
-const ROOT = path.resolve(__dirname, '..', '..'); // <…>/<root>
+// The CODE lives in the package; the mutable CONFIG lives in the resolved config home — the same
+// directory in a git clone, distinct when TOOLFUNNEL_HOME / --config-dir points elsewhere (npm
+// installs, npm-wrapped MCPs — an `npm update` must never eat the user's tools). Every anchor
+// below derives from the HOME.
+const { PKG_ROOT, resolveConfigHome, ensureConfigHome } = require('../core/config-home');
+const ROOT = resolveConfigHome(); // <…>/<config home>
+// The process-tree contract for child tools (defaultRunScript spawns with process.env): a
+// management script SEEDED into an external home finds the engine code via TOOLFUNNEL_PKG, and
+// the resolved ABSOLUTE home is written back so no child re-resolves a relative value against a
+// different cwd.
+process.env.TOOLFUNNEL_PKG = PKG_ROOT;
+if (ROOT !== PKG_ROOT) process.env.TOOLFUNNEL_HOME = ROOT;
 const REGISTER_PATH = path.join(ROOT, 'tools', 'tools.register.json');
 // The ACTIVE/DISABLED overlay (tool-state.js). toolfunnel_list_tools filters DISABLED tools out so
 // they are not surfaced to the client. Read FRESH per list() call so UI toggles take effect with no
@@ -68,7 +79,14 @@ const SCRIPTS_ROOT = path.join(ROOT, 'tools', 'scripts');
 const EXPOSE_PATH = path.join(ROOT, 'mcp', 'expose.json');
 
 const PROTOCOL_VERSION = '2024-11-05';
-const SERVER_INFO = { name: 'toolfunnel', version: '0.3.0' };
+// Identity comes from the OPTIONAL toolfunnel.json at the root (absent → name "toolfunnel",
+// version from package.json — serverInfo can never drift from the released version). The config
+// seam is what lets a wrapped MCP introduce itself as ITSELF in the initialize handshake and
+// /health. Loaded once at module init: clients cache serverInfo from initialize, so identity is
+// deliberately NOT hot-reloaded (a mid-session identity swap would lie to connected clients).
+const { loadServerConfig } = require('../core/server-config');
+const SERVER_CONFIG = loadServerConfig(ROOT);
+const SERVER_INFO = { name: SERVER_CONFIG.serverName, version: SERVER_CONFIG.serverVersion };
 
 // ── Diagnostics → stderr only (stdout is the JSON-RPC channel; never pollute it). ─────────────
 function logErr(...parts) {
@@ -198,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',
@@ -248,6 +268,11 @@ function makeRegistryAdapter(registry, opts) {
 //   - engine, ctx: threaded into gatedRun for the curated-direct path (a curated tool runs
 //                  THROUGH the same PreToolUse gate as toolfunnel_run_tool — the safety invariant).
 function buildProtocol() {
+  // Make the config home real before anything reads from it: seeds an external home's register/
+  // scripts/expose/hooks from the shipped defaults on first use. A no-op when home === package
+  // root; idempotent and never-overwriting afterwards. A failure falls through to loadRegistry's
+  // own clear error.
+  try { ensureConfigHome(ROOT); } catch (err) { logErr('config-home init failed:', (err && err.message) || String(err)); }
   const registry = loadRegistry(REGISTER_PATH, { scriptsRoot: SCRIPTS_ROOT });
   const loader = loadManifest(MANIFEST_PATH);
 
@@ -911,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);
@@ -930,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({
@@ -947,6 +984,31 @@ async function reloadExpose(build, send) {
   logErr('reloadExpose: expose.json reloaded — upstreams reconnected');
 }
 
+/**
+ * Re-read tools.register.json and swap the ONE live Registry's index IN PLACE (Registry.reload —
+ * last-good on any failure). In-place mutation is the point: the Registry instance is CAPTURED by
+ * the protocol adapter at build time, so swapping internals means every reader — the lean
+ * meta-tools, run_tool resolution, and the top-level hot surface — sees the new entries on its
+ * next call with no rewiring. Emits list_changed: a hot-promoted local tool's definition may have
+ * appeared, changed, or gone. NEVER throws.
+ *
+ * @param {{registry?:object}} build
+ * @param {(obj:object)=>void} send  the stdio writer, for the list_changed notification
+ * @returns {void}
+ */
+function reloadRegister(build, send) {
+  try {
+    if (build && build.registry && typeof build.registry.reload === 'function' && build.registry.reload()) {
+      emitToolsListChanged(send);
+      logErr('reloadRegister: tools.register.json reloaded');
+    } else {
+      logErr('reloadRegister: reload failed (bad JSON / invalid entry / mid-write?) — keeping the last-good register');
+    }
+  } catch (err) {
+    logErr('reloadRegister: unexpected failure (keeping current register):', (err && err.message) || String(err));
+  }
+}
+
 /**
  * Re-read the hooks manifest + state overlay and swap a fresh HookEngine into `build`. The next
  * gated call (toolfunnel_run_tool / curated-direct) uses the new engine, so an added/changed/toggled
@@ -966,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;
@@ -989,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
   }
@@ -997,10 +1078,27 @@ 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(getBuild(), send); }, DEBOUNCE_MS);
+    if (registerTimer && typeof registerTimer.unref === 'function') registerTimer.unref();
+  }
+
+  // tools.state.json needs NO reload (it is read fresh per tools/list & tools/call) — but a
+  // hot/hidden/enabled toggle CHANGES the top-level surface, so a connected client must be told
+  // to re-fetch. Notification only.
+  let stateTimer = null;
+  function scheduleStateNotify() {
+    if (stateTimer) clearTimeout(stateTimer);
+    stateTimer = setTimeout(() => { stateTimer = null; emitToolsListChanged(send); }, DEBOUNCE_MS);
+    if (stateTimer && typeof stateTimer.unref === 'function') stateTimer.unref();
+  }
+
   try {
     const w = fs.watch(mcpDir, (_event, filename) => {
       // null filename (some platforms don't report it) → reload to be safe; else only expose.json.
@@ -1009,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));
@@ -1020,10 +1119,76 @@ 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));
   }
+
+  // The register + state overlay live in tools/. Register edits (tf_tool_add from its child
+  // process, the UI, a hand edit) were the ONE config surface with no watcher — a running gateway
+  // served its startup snapshot until restart, which broke the "add a tool live" story the moment
+  // the server outlived the edit. State toggles only need the list_changed nudge (read-fresh).
+  const toolsDir = path.dirname(REGISTER_PATH);
+  try {
+    const w = fs.watch(toolsDir, (_event, filename) => {
+      const base = filename ? path.basename(String(filename)) : '';
+      if (!filename || base === 'tools.register.json') scheduleRegister();
+      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/packages/packager.js

@@ -33,9 +33,11 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
-// ROOT resolution mirrors src/mcp/server.js: this file lives at
-// <root>/src/packages/packager.js, so two levels up is the project root.
-const ROOT = path.resolve(__dirname, '..', '..'); // <…> project root
+// ROOT = the CONFIG HOME (TOOLFUNNEL_HOME / --config-dir; defaults to the package root — see
+// src/core/config-home.js). Packages are config-tree citizens: they export FROM and import INTO
+// the home's register/manifest/expose stores, and the packages/ tree itself lives in the home.
+const { resolveConfigHome } = require('../core/config-home');
+const ROOT = resolveConfigHome(); // <…> config home
 
 const PACKAGE_MANIFEST = 'package.json';
 

package/src/tools/registry.js

@@ -130,6 +130,15 @@ function validateEntry(entry, { requireId = true } = {}) {
   if (inv.type === 'shell' && (typeof inv.command !== 'string' || inv.command.length === 0)) {
     throw new Error(`Registry: shell invoke needs a non-empty "command" (id=${entry.id})`);
   }
+  // Optional MCP input schema. When present it must be a plain object — a hot-promoted tool
+  // advertises it VERBATIM to MCP clients (tools/list), so a typo'd shape must fail loudly at
+  // authoring time rather than silently degrade to the free-form fallback at surface time.
+  if (
+    entry.inputSchema !== undefined &&
+    (typeof entry.inputSchema !== 'object' || entry.inputSchema === null || Array.isArray(entry.inputSchema))
+  ) {
+    throw new Error(`Registry: entry.inputSchema must be an object when present (id=${entry.id})`);
+  }
   return entry;
 }
 
@@ -284,6 +293,40 @@ class Registry {
     return true;
   }
 
+  /**
+   * Re-read the register FILE and swap the in-memory index — the hot-reload seam. A running
+   * gateway holds ONE Registry instance (captured by the protocol adapter at build time), while
+   * tf_tool_add / the UI / a hand edit mutate the FILE from another process — without this, those
+   * edits are invisible until restart. LAST-GOOD semantics: the replacement index is built and
+   * fully validated FIRST; any read/parse/validation failure (including a mid-write partial file)
+   * leaves the current index untouched and returns false. NEVER throws.
+   * @returns {boolean} true when the on-disk register replaced the in-memory index
+   */
+  reload() {
+    let data;
+    try {
+      data = JSON.parse(fs.readFileSync(this._filePath, 'utf8'));
+    } catch (_e) {
+      return false; // unreadable / mid-write / bad JSON → keep last-good
+    }
+    if (!data || typeof data !== 'object' || Array.isArray(data)) return false;
+    const tools = Array.isArray(data.tools) ? data.tools : [];
+    const next = new Map();
+    try {
+      for (const t of tools) {
+        validateEntry(t);
+        if (next.has(t.id)) throw new Error(`duplicate tool id "${t.id}"`);
+        next.set(t.id, cloneEntry(t));
+      }
+    } catch (_e) {
+      return false; // an invalid entry → keep last-good
+    }
+    if (typeof data.version === 'number') this._version = data.version;
+    if (typeof data.description === 'string') this._description = data.description;
+    this._byId = next;
+    return true;
+  }
+
   /**
    * Write a host-local script's text under this scriptsRoot, atomically.
    *
@@ -354,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',

package/src/ui/server.js

@@ -19,6 +19,9 @@
  * DIRECTLY (no MCP round-trip). Every write is atomic (temp + rename) inside the store.
  *
  * SAFETY CONTRACT (mirrors src/mcp/http-transport.js):
+ *   - start() HARD-REFUSES a non-loopback bind host. The UI has no auth path at all, and it can
+ *     spawn processes (mcp add/discover) and write scripts (tools/hooks) — off-loopback it would be
+ *     an unauthenticated remote console. Loopback-only by design; no flag overrides it.
  *   - Binds 127.0.0.1 by default; a non-loopback Host header is rejected (DNS-rebind guard).
  *   - The request listener NEVER throws — a bad request becomes a clean JSON error.
  *   - start() rejects cleanly on EADDRINUSE (caller decides); stop() is idempotent.
@@ -91,6 +94,17 @@ function isLoopbackHost(hostHeader) {
   return host === '127.0.0.1' || host === 'localhost' || host === '::1' || host === '0:0:0:0:0:0:0:1';
 }
 
+/**
+ * Is the BIND address loopback? STRICTER than the Host-header check above: a missing Host header
+ * is legitimately loopback (the bind address is the boundary), but a missing/empty BIND address is
+ * not a loopback claim — it must name a loopback host explicitly to pass.
+ * @param {string|undefined} bindHost
+ * @returns {boolean}
+ */
+function isLoopbackBindHost(bindHost) {
+  return typeof bindHost === 'string' && bindHost.trim() !== '' && isLoopbackHost(bindHost);
+}
+
 /** Regex-escape a literal so a matcher built from it FULL-matches the string verbatim. */
 function escapeRegex(str) {
   return String(str).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -183,7 +197,8 @@ function logConfigChange(fields) {
  * @param {object}  [opts]
  * @param {string}  [opts.host]  bind address (default 127.0.0.1 — loopback only).
  * @param {number}  [opts.port]  bind port (default 9777; pass 0 for an OS-assigned port).
- * @param {string}  [opts.root]  repo root holding tools/ mcp/ hooks/ (default path.resolve(__dirname,'..','..')).
+ * @param {string}  [opts.root]  config root holding tools/ mcp/ hooks/ (default: the resolved
+ *                               config home — TOOLFUNNEL_HOME / --config-dir / the package root).
  * @returns {{ start: () => Promise<{url:string, port:number}>, stop: () => Promise<void>, get url():(string|null) }}
  */
 function createUiServer(opts = {}) {
@@ -191,8 +206,11 @@ function createUiServer(opts = {}) {
   const host = typeof o.host === 'string' && o.host.length > 0 ? o.host : DEFAULT_HOST;
   // A port of 0 is VALID (OS-assigned) so distinguish "not provided" from 0.
   const requestedPort = Number.isInteger(o.port) && o.port >= 0 ? o.port : DEFAULT_PORT;
-  // The repo root: tools.register.json etc. live under <root>/tools, <root>/mcp, <root>/hooks.
-  const root = typeof o.root === 'string' && o.root.length > 0 ? o.root : path.resolve(__dirname, '..', '..');
+  // The config root: tools.register.json etc. live under <root>/tools, <root>/mcp, <root>/hooks.
+  // Default = the resolved config home (see src/core/config-home.js), so a --config-dir /
+  // TOOLFUNNEL_HOME gateway and its UI edit the SAME stores.
+  const { resolveConfigHome } = require('../core/config-home');
+  const root = typeof o.root === 'string' && o.root.length > 0 ? o.root : resolveConfigHome();
 
   // ── Path anchors (everything resolved from the repo root) ────────────────────────────────────
   const REGISTER_PATH = path.join(root, 'tools', 'tools.register.json');
@@ -990,6 +1008,23 @@ function createUiServer(opts = {}) {
       const pathName = qIndex === -1 ? rawUrl : rawUrl.slice(0, qIndex);
       const method = (req.method || 'GET').toUpperCase();
 
+      // CSRF guard. The bind address stops the NETWORK, not the browser: any web page the
+      // operator visits can fire a no-cors POST at 127.0.0.1:<port>, and the mutating routes
+      // below write tool scripts and register process-spawning upstreams. Browsers ALWAYS send
+      // an Origin header on cross-origin POSTs, so: a PRESENT Origin must itself be loopback
+      // (the UI's own pages), while an ABSENT Origin (curl, CLI clients, non-browser tools) is
+      // allowed — for those, the bind address remains the boundary. GETs stay open (read-only).
+      if (method !== 'GET') {
+        const origin = req.headers && req.headers.origin;
+        if (origin) {
+          let originHost = null;
+          try { originHost = new URL(origin).host; } catch (_e) { /* malformed → reject below */ }
+          if (!originHost || !isLoopbackHost(originHost)) {
+            return sendJson(res, 403, { ok: false, error: 'forbidden: cross-origin request (CSRF guard)' });
+          }
+        }
+      }
+
       // ── Static assets ─────────────────────────────────────────────────────────────────────────
       if (method === 'GET' && (pathName === '/' || pathName === '/index.html')) {
         return sendStatic(res, 'index.html');
@@ -1079,6 +1114,16 @@ function createUiServer(opts = {}) {
    */
   function start() {
     if (started) return Promise.resolve({ url: currentUrl(), port: boundPort });
+    // The HTTP transport refuses a non-loopback bind unless OAuth is enabled; the UI has NO auth
+    // path, so its refusal is unconditional. This endpoint spawns processes and writes scripts —
+    // "--ui --host 0.0.0.0" would hand an unauthenticated remote console to the LAN.
+    if (!isLoopbackBindHost(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 tool scripts. It is loopback-only by design; to configure ' +
+          'the gateway from another machine, use an SSH tunnel to 127.0.0.1 instead.'
+      ));
+    }
     httpServer = http.createServer(onRequest);
     return new Promise((resolve, reject) => {
       const onListenError = (err) => {
@@ -1140,5 +1185,6 @@ module.exports = {
   createUiServer,
   // Exported for unit tests / reuse — the small pure seams.
   isLoopbackHost,
+  isLoopbackBindHost,
   escapeRegex,
 };

package/tools/scripts/tf-env.js

@@ -0,0 +1,43 @@
+'use strict';
+
+/**
+ * tf-env.js — shared HOME/ENGINE resolution for the tf-* management scripts.
+ *
+ * A management script runs in one of two layouts:
+ *   1. The git-clone original: it lives at <pkg>/tools/scripts/, and TWO dirs up is a root that
+ *      holds BOTH the config (tools/ mcp/ hooks/) and the engine code (src/).
+ *   2. A copy SEEDED into an external CONFIG HOME (TOOLFUNNEL_HOME / --config-dir — see
+ *      src/core/config-home.js): the config sits beside it, but the engine code does NOT.
+ *      The gateway that spawned it wrote the process-tree contract into the env:
+ *      TOOLFUNNEL_HOME (the resolved absolute home) + TOOLFUNNEL_PKG (the package root).
+ *
+ * Resolution rules:
+ *   - ENGINE: prefer the LOCAL __dirname-derived root whenever it actually contains the engine
+ *     (layout 1) so a stale inherited TOOLFUNNEL_PKG can never shadow a real install; else the
+ *     env; else the local root anyway (the require failure is then the clearest error).
+ *   - HOME:   TOOLFUNNEL_HOME when set (the gateway always sets it), else the local root.
+ *
+ * Same-dir require ('./tf-env') keeps this working in BOTH layouts — the seeder copies the whole
+ * scripts directory, so this file always travels with its callers. Node built-ins only.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const LOCAL_ROOT = path.resolve(__dirname, '..', '..');
+const HAS_LOCAL_ENGINE = fs.existsSync(path.join(LOCAL_ROOT, 'src', 'tools', 'registry.js'));
+
+/** The package root holding the engine code (src/…). */
+const PKG = HAS_LOCAL_ENGINE ? LOCAL_ROOT : (process.env.TOOLFUNNEL_PKG || LOCAL_ROOT);
+
+/** The config home holding tools/ mcp/ hooks/ (the mutable state this script edits). */
+const HOME = typeof process.env.TOOLFUNNEL_HOME === 'string' && process.env.TOOLFUNNEL_HOME.trim().length > 0
+  ? path.resolve(process.env.TOOLFUNNEL_HOME.trim())
+  : LOCAL_ROOT;
+
+/** Require an engine module by its src-relative path, e.g. srcRequire('tools/registry'). */
+function srcRequire(rel) {
+  return require(path.join(PKG, 'src', rel));
+}
+
+module.exports = { PKG, HOME, srcRequire };

package/tools/scripts/tf-hook-add.js

@@ -37,12 +37,11 @@
  */
 
 const path = require('node:path');
-const { loadManifest } = require('../../src/core/hook-loader');
+// Shared HOME/engine resolution (see tf-env.js): config beside us, engine from the package.
+const { HOME, srcRequire } = require('./tf-env');
+const { loadManifest } = srcRequire('core/hook-loader');
 
-/**
- * ToolFunnel root, two dirs up from this script (tools/scripts -> tools -> root).
- */
-const ROOT = path.resolve(__dirname, '..', '..');
+const ROOT = HOME;
 
 /** The hook manifest, relative to ROOT. */
 const MANIFEST = path.join(ROOT, 'hooks', 'hooks.manifest.json');

package/tools/scripts/tf-hook-set.js

@@ -33,12 +33,11 @@
  */
 
 const path = require('node:path');
-const { loadManifest } = require('../../src/core/hook-loader');
+// Shared HOME/engine resolution (see tf-env.js): config beside us, engine from the package.
+const { HOME, srcRequire } = require('./tf-env');
+const { loadManifest } = srcRequire('core/hook-loader');
 
-/**
- * ToolFunnel root, two dirs up from this script (tools/scripts -> tools -> root).
- */
-const ROOT = path.resolve(__dirname, '..', '..');
+const ROOT = HOME;
 
 /** The hook manifest, relative to ROOT. */
 const MANIFEST = path.join(ROOT, 'hooks', 'hooks.manifest.json');

package/tools/scripts/tf-list.js

@@ -48,19 +48,16 @@
 
 const path = require('node:path');
 
-const { loadRegistry } = require('../../src/tools/registry');
-const { loadToolState, isToolEnabled, isToolHidden } = require('../../src/tools/tool-state');
-const { loadExposeStore } = require('../../src/mcp/expose-store');
-const { loadManifest } = require('../../src/core/hook-loader');
+// HOME/engine resolution shared by every tf-* script (see tf-env.js): the config lives beside
+// this script (the git-clone root OR a seeded external config home); the engine code is required
+// from the package that spawned us when it is not local.
+const { HOME, srcRequire } = require('./tf-env');
+const { loadRegistry } = srcRequire('tools/registry');
+const { loadToolState, isToolEnabled, isToolHidden } = srcRequire('tools/tool-state');
+const { loadExposeStore } = srcRequire('mcp/expose-store');
+const { loadManifest } = srcRequire('core/hook-loader');
 
-/**
- * The toolfunnel root, resolved from THIS file's location so the tool stays inside
- * the sandbox and is portable wherever the tree is copied.
- *
- * This script lives at:  <root>/tools/scripts/tf-list.js
- * so the root is two directories up from __dirname:  scripts -> tools -> <root>
- */
-const ROOT = path.resolve(__dirname, '..', '..');
+const ROOT = HOME;
 
 // Canonical store paths (see the script contract).
 const REGISTER_PATH = path.join(ROOT, 'tools', 'tools.register.json');

package/tools/scripts/tf-log.js

@@ -21,7 +21,10 @@
  *   failure:        { ok:false, error }
  */
 
-const logger = require('../../src/core/logger');
+// Shared HOME/engine resolution (see tf-env.js): the logger module itself resolves the config
+// home from the env the gateway set, so requiring it from the right PACKAGE is all we need.
+const { srcRequire } = require('./tf-env');
+const logger = srcRequire('core/logger');
 
 /**
  * Parse TOOLFUNNEL_TOOL_ARGS (a JSON string; {} if absent). Throws on malformed JSON

package/tools/scripts/tf-mcp-add.js

@@ -41,13 +41,11 @@
  */
 
 const path = require('node:path');
-const { loadExposeStore } = require('../../src/mcp/expose-store');
+// Shared HOME/engine resolution (see tf-env.js): config beside us, engine from the package.
+const { HOME, srcRequire } = require('./tf-env');
+const { loadExposeStore } = srcRequire('mcp/expose-store');
 
-/**
- * ToolFunnel root, resolved from THIS file's location:
- *   <root>/tools/scripts/tf-mcp-add.js -> root is two dirs up.
- */
-const ROOT = path.resolve(__dirname, '..', '..');
+const ROOT = HOME;
 
 /** The MCP config (upstreams + expose), per the host path contract. */
 const EXPOSE_PATH = path.join(ROOT, 'mcp', 'expose.json');

package/tools/scripts/tf-mcp-set.js

@@ -29,13 +29,11 @@
  */
 
 const path = require('node:path');
-const { loadExposeStore } = require('../../src/mcp/expose-store');
+// Shared HOME/engine resolution (see tf-env.js): config beside us, engine from the package.
+const { HOME, srcRequire } = require('./tf-env');
+const { loadExposeStore } = srcRequire('mcp/expose-store');
 
-/**
- * ToolFunnel root, resolved from THIS file's location:
- *   <root>/tools/scripts/tf-mcp-set.js -> root is two dirs up.
- */
-const ROOT = path.resolve(__dirname, '..', '..');
+const ROOT = HOME;
 
 /** The MCP config (upstreams + expose), per the host path contract. */
 const EXPOSE_PATH = path.join(ROOT, 'mcp', 'expose.json');