toolfunnel 0.6.0 → 0.7.0

package/src/core/logger.js

@@ -15,12 +15,23 @@
  *     must never break a tool call or the gate. Everything is wrapped; failures are
  *     swallowed silently.
  *
- * Paths are resolved against the repo root (two dirs up from src/core/). The configured
- * log `path` may be relative (resolved against root) or absolute.
+ * Paths are resolved against the config home, and the resolved path MUST stay inside
+ * <home>/logs/ (0.7.0; logging.test.js step 5 is the acceptance). The log path is
+ * settable from the tf_log tool surface and the UI's POST /api/logs/config, and every
+ * other file-writing path in the repo is confined to its root (hook-loader's scripts-dir
+ * assert, registry.writeScript, sendStatic) - this one now matches. setConfig REFUSES an
+ * out-of-home path loudly; getConfig treats one already in the file as unset (default),
+ * so log() and tail() stay in-home even against a hand-edited config. An operator who
+ * wants the log on another disk can make <home>/logs a symlink/junction - containment is
+ * checked on the unfollowed path.
  *
  * Config file: <root>/logs/log.config.json
  *   { "enabled": false, "path": "logs/toolfunnel.log.jsonl" }
  *
+ * Both paths are BOUNDED (0.7.0, log-rotation.test.js): the live file rotates to `<path>.1`
+ * at MAX_LOG_BYTES (one older generation kept), and tail(n) reads a trailing slice rather
+ * than the whole file - with a whole-file fallback so bounding never changes an answer.
+ *
  * CommonJS only.
  */
 
@@ -40,12 +51,37 @@ const DEFAULT_ENABLED = false;
 const DEFAULT_PATH = 'logs/toolfunnel.log.jsonl';
 
 /**
- * Resolve a (possibly relative) log path against the repo root.
+ * The live file's size cap. An append that finds the file at/over it first renames the
+ * file to `<path>.1` (ONE older generation, overwritten by the next rotation), so disk
+ * use is bounded at ~2x the cap and the no-argument tail() (the documented all-lines
+ * mode, tf_log status's count) can never be asked to parse an unbounded file again.
+ * Rotation is best-effort: if the rename is refused (e.g. a reader holds `.1` open on
+ * win32) the append proceeds on the oversized live file and rotation retries next call -
+ * a record is never dropped for the sake of the cap.
+ */
+const MAX_LOG_BYTES = 5 * 1024 * 1024;
+
+/** tail(n)'s bounded read: bytes budgeted per requested line (generous - records run
+ *  ~100-200 bytes), with a floor so tiny n still reads one decent chunk. */
+const TAIL_BYTES_PER_LINE = 1024;
+const TAIL_READ_MIN_BYTES = 64 * 1024;
+
+/** The directory every log path must resolve inside. */
+const LOG_DIR = path.join(ROOT, 'logs');
+
+/**
+ * Resolve a (possibly relative) log path against the config home, REQUIRING the result
+ * to stay inside <home>/logs/. Returns the resolved absolute path, or null when it
+ * resolves outside (same refusal shape as registry.js defaultRunScript: '' would be the
+ * dir itself, '..'-prefixed left it, absolute rel = another drive on win32).
  * @param {string} p
- * @returns {string}
+ * @returns {string|null}
  */
 function resolveLogPath(p) {
-  return path.isAbsolute(p) ? p : path.join(ROOT, p);
+  const resolved = path.resolve(ROOT, String(p));
+  const rel = path.relative(LOG_DIR, resolved);
+  if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) return null;
+  return resolved;
 }
 
 /**
@@ -65,8 +101,11 @@ function getConfig() {
     }
     return {
       enabled: parsed.enabled === true,
+      // A path that resolves outside <home>/logs/ is treated as UNSET, not honoured: the
+      // config file can be edited directly, and the readers (log/tail) must stay in-home
+      // regardless of how the value got there. setConfig additionally refuses one loudly.
       path:
-        typeof parsed.path === 'string' && parsed.path.length > 0
+        typeof parsed.path === 'string' && parsed.path.length > 0 && resolveLogPath(parsed.path) !== null
           ? parsed.path
           : DEFAULT_PATH,
     };
@@ -96,7 +135,20 @@ function log(event) {
     );
 
     const logPath = resolveLogPath(cfg.path);
+    if (logPath === null) return; // cannot happen via getConfig (it sanitises); belt-and-braces
     fs.mkdirSync(path.dirname(logPath), { recursive: true });
+
+    // Rotate BEFORE the append when the live file has reached the cap. Its own try/catch:
+    // a refused stat/rename must never cost the record below. `logPath + '.1'` inherits
+    // logPath's containment, and rename replaces an existing `.1` (one older generation).
+    try {
+      if (fs.statSync(logPath).size >= MAX_LOG_BYTES) {
+        fs.renameSync(logPath, logPath + '.1');
+      }
+    } catch (_e) {
+      // Missing file (nothing to rotate) or a refused rename - append regardless.
+    }
+
     fs.appendFileSync(logPath, JSON.stringify(record) + '\n');
   } catch (_err) {
     // Logging must NEVER break the caller. Swallow everything.
@@ -117,6 +169,20 @@ function setConfig(patch) {
   const current = getConfig();
   const p = patch && typeof patch === 'object' && !Array.isArray(patch) ? patch : {};
 
+  // Refuse an out-of-home path LOUDLY before anything is written. Reaches every setter
+  // surface (tf_log's { ok:false }, the UI's error response) with nothing persisted.
+  // `current.path` needs no re-check - getConfig only ever returns a contained path.
+  // The code lets callers tell "you sent a bad path" (client input -> the UI's 400) apart
+  // from a genuine write failure (disk, perms -> 500) without matching on message prose.
+  if (typeof p.path === 'string' && p.path.length > 0 && resolveLogPath(p.path) === null) {
+    const err = new Error(
+      `log path refused: "${p.path}" resolves outside the config home's logs directory - ` +
+      'the activity log lives inside <home>/logs'
+    );
+    err.code = 'TF_LOG_PATH_REFUSED';
+    throw err;
+  }
+
   const next = {
     enabled: typeof p.enabled === 'boolean' ? p.enabled : current.enabled,
     path:
@@ -132,12 +198,55 @@ function setConfig(patch) {
   return next;
 }
 
+/**
+ * Read the trailing slice of a file that is expected to contain the last `wanted` lines:
+ * the final min(size, max(64 KB, wanted KB)) bytes. When the read starts mid-file the
+ * first segment may be a PARTIAL line, so it is dropped (mid-character utf8 starts land
+ * in that dropped segment too). Returns the complete lines it can vouch for, plus whether
+ * the whole file was covered - the caller falls back to a whole-file read on a shortfall
+ * (e.g. one line longer than the window), so the bounded path can never change an answer,
+ * only the bytes it took to produce it.
+ * @param {string} logPath
+ * @param {number} wanted
+ * @returns {{ lines: string[], wholeFile: boolean }}
+ */
+function readTrailingLines(logPath, wanted) {
+  const fd = fs.openSync(logPath, 'r');
+  try {
+    const size = fs.fstatSync(fd).size;
+    const budget = Math.max(TAIL_READ_MIN_BYTES, wanted * TAIL_BYTES_PER_LINE);
+    const readLen = Math.min(size, budget);
+    const position = size - readLen;
+    const buf = Buffer.alloc(readLen);
+    let got = 0;
+    while (got < readLen) {
+      const r = fs.readSync(fd, buf, got, readLen - got, position + got);
+      if (r <= 0) break; // shrank underneath us (rotation) - use what we have
+      got += r;
+    }
+    let text = buf.toString('utf8', 0, got);
+    if (position > 0) {
+      const firstNl = text.indexOf('\n');
+      text = firstNl === -1 ? '' : text.slice(firstNl + 1);
+    }
+    const lines = text.split('\n').filter(function (l) { return l.length > 0; });
+    return { lines, wholeFile: position === 0 };
+  } finally {
+    try { fs.closeSync(fd); } catch (_e) { /* ignore */ }
+  }
+}
+
 /**
  * tail - return the last n parsed JSON lines from the configured log.
  *
  * Returns [] if the log is missing or unreadable. Unparseable lines are skipped. When
  * n is not a positive finite number, all lines are returned. Never throws.
  *
+ * A finite n reads a BOUNDED trailing slice (~1 KB budgeted per requested line), not the
+ * whole file - with a whole-file fallback when the slice holds fewer than n lines, so the
+ * answer is byte-identical to the unbounded engine's in every case. The no-argument mode
+ * still reads everything by design; rotation (MAX_LOG_BYTES) bounds that file for it.
+ *
  * @param {number} [n] how many trailing lines to parse and return.
  * @returns {object[]}
  */
@@ -145,13 +254,30 @@ function tail(n) {
   try {
     const cfg = getConfig();
     const logPath = resolveLogPath(cfg.path);
-    const raw = fs.readFileSync(logPath, 'utf8');
-    const lines = raw.split('\n').filter(function (l) {
-      return l.length > 0;
-    });
+    if (logPath === null) return []; // cannot happen via getConfig (it sanitises); belt-and-braces
+
+    const bounded = typeof n === 'number' && isFinite(n) && n > 0;
+    let lines;
+    let wanted;
+    if (bounded) {
+      wanted = Math.floor(n);
+      const sliceRead = readTrailingLines(logPath, wanted);
+      if (sliceRead.lines.length >= wanted || sliceRead.wholeFile) {
+        lines = sliceRead.lines;
+      } else {
+        // Shortfall on a partial window (unusually long lines): take the exact answer
+        // over the byte bound.
+        lines = fs.readFileSync(logPath, 'utf8').split('\n').filter(function (l) {
+          return l.length > 0;
+        });
+      }
+    } else {
+      lines = fs.readFileSync(logPath, 'utf8').split('\n').filter(function (l) {
+        return l.length > 0;
+      });
+      wanted = lines.length;
+    }
 
-    const wanted =
-      typeof n === 'number' && isFinite(n) && n > 0 ? Math.floor(n) : lines.length;
     const slice = lines.slice(-wanted);
 
     const out = [];

package/src/core/matcher.js

@@ -1,7 +1,7 @@
 'use strict';
 
 /**
- * matcher.js - does a hook's matcher string fire for a given tool? (HOOK_ENGINE.md §5)
+ * matcher.js - does a hook's matcher string fire for a given tool?
  *
  * Mirrors Claude Code's matcher semantics:
  *   - ""  | undefined | "*"  -> always fire (wildcard).
@@ -13,6 +13,38 @@
  * CommonJS only. Zero host imports (core/ must run headless under node --test).
  */
 
+// One compile per distinct matcher string. matches() sits on the gate's hot path (every
+// hook x every tool call), and rebuilding `^(?:Bash|Write|Edit)$` per call was pure waste:
+// RegExp construction is a deterministic function of the string and ours carries no flags
+// (no g/y -> no lastIndex state), so memoising by the string can never change an answer.
+// Invalidation is by construction, not by event: a reloaded manifest's new matcher is a
+// NEW string -> a new key; the old entry just goes unused. Failed compiles memoise too
+// (a malformed matcher answers false without a fresh throw per call). The cap is a
+// backstop against degenerate dynamically-generated matchers: past it the memo resets -
+// worst case is exactly the old per-call compile, never unbounded growth or a wrong fire.
+const COMPILE_CACHE_MAX = 256;
+const compileCache = new Map(); // String(matcher) -> { re: RegExp|null, err: string|null }
+
+/**
+ * The memoised compile shared by matches() / matcherError(). Keyed on String(matcher) so a
+ * non-string matcher coerces exactly as the template literal always did.
+ * @param {*} matcher
+ * @returns {{ re: RegExp|null, err: string|null }}
+ */
+function compiled(matcher) {
+  const key = String(matcher);
+  let hit = compileCache.get(key);
+  if (hit) return hit;
+  try {
+    hit = { re: new RegExp(`^(?:${key})$`), err: null };
+  } catch (err) {
+    hit = { re: null, err: (err && err.message) || String(err) };
+  }
+  if (compileCache.size >= COMPILE_CACHE_MAX) compileCache.clear();
+  compileCache.set(key, hit);
+  return hit;
+}
+
 /**
  * @param {string|undefined|null} matcher  the hook's matcher string.
  * @param {string|undefined|null} toolName the tool the model requested, or
@@ -26,7 +58,7 @@ function matches(matcher, toolName) {
   }
 
   // Tool-less events: there is nothing to match against, so the matcher is
-  // ignored and the hook always fires (§5). This is checked AFTER the wildcard
+  // ignored and the hook always fires. This is checked AFTER the wildcard
   // case so a "*" matcher is handled uniformly, and BEFORE we attempt a regex
   // (which would otherwise need a string to test).
   if (toolName === undefined || toolName === null) {
@@ -36,16 +68,33 @@ function matches(matcher, toolName) {
   // Anything else is a regex, anchored as a full match against toolName.
   // We wrap in ^(?:...)$ so alternations like "Bash|Write" mean "the whole tool
   // name is one of these", not "contains one of these".
-  let re;
-  try {
-    re = new RegExp(`^(?:${matcher})$`);
-  } catch (err) {
-    // A malformed matcher must never throw out of the engine. Treat an
-    // uncompilable pattern as "does not match" - fail closed, stay defensive.
+  const c = compiled(matcher);
+  if (!c.re) {
+    // A malformed matcher must never throw out of the engine, and matches() cannot
+    // claim a fire it could not evaluate - so this answers false. That is NOT
+    // permission to proceed: callers that gate on the answer must distinguish
+    // "did not match" from "could not be read" via matcherError() (hook-engine
+    // denies the call; hook-loader.addEntry refuses to store the matcher at all).
     return false;
   }
 
-  return re.test(toolName);
+  return c.re.test(toolName);
+}
+
+/**
+ * Why does this matcher NOT compile? Returns null for a wildcard/unset matcher or one that
+ * compiles under the same ^(?:...)$ anchoring matches() applies; otherwise the compile error's
+ * message. This is the discriminator between "did not match" and "could not be read":
+ * authoring surfaces (hook-loader.addEntry, and through it the UI and tf_hook_add) use it to
+ * REFUSE a pattern that can never be evaluated, and hook-engine.fire treats a non-null answer
+ * on a tool-bearing event as an unreadable gate and denies the call (matcher-compile.test.js).
+ *
+ * @param {string|undefined|null} m the hook's matcher string.
+ * @returns {string|null} the compile problem, or null when the matcher is usable.
+ */
+function matcherError(m) {
+  if (m === undefined || m === null || m === '' || m === '*') return null;
+  return compiled(m).err;
 }
 
-module.exports = { matches };
+module.exports = { matches, matcherError };

package/src/core/rename-migration.js

@@ -0,0 +1,163 @@
+'use strict';
+
+/**
+ * rename-migration.js - keep gates and per-tool state attached across a SURFACED-NAME change
+ * (0.7.0; the rename-safety.test.js invariants are the acceptance).
+ *
+ * A tool's SURFACED name is the string the PreToolUse gate matches and the tools.state.json
+ * key is written against. 0.6.0 let that name change (an expose `as` edit, an enabled flip, a
+ * local display-name edit) while the gate matcher and the state key silently kept the OLD
+ * string - a deny gate stopped firing and a disabled tool resurrected. The policy here,
+ * MATCHER-MIGRATE-ON-RENAME:
+ *
+ *   - A WILDCARD matcher ('', '*', unset) fires for every tool name - it already covers the
+ *     new name; untouched.
+ *   - An EXACT-LITERAL matcher - the `escapeRegex(oldName)` shape every ToolFunnel surface
+ *     (tf_* tools, the UI) writes - is REWRITTEN to `escapeRegex(newName)`.
+ *   - Any OTHER matcher that would fire for the old name (same anchored-regex semantics as
+ *     core/matcher.js, the gate's own matching) is one WE DID NOT AUTHOR and cannot safely
+ *     rewrite: the rename is REFUSED with the hook named. Update the hook first, then rename.
+ *   - tools.state.json: the old key's entry (enabled/hidden/hot) MOVES to the new key. A
+ *     collision (both keys present with different content) refuses - never clobber curation.
+ *
+ * Validation runs COMPLETELY before the first write, and the caller invokes this BEFORE
+ * persisting its own rename - a refusal leaves every file untouched.
+ *
+ * CommonJS only. Node built-ins + core/matcher only (core/ stays headless).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { matches, matcherError } = require('./matcher');
+
+/** Regex-escape a literal so a matcher built from it FULL-matches the string verbatim.
+ *  (Same shape as ui/server.js escapeRegex - the shape ToolFunnel-authored matchers use.) */
+function escapeRegex(str) {
+  return String(str).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** Copied exactly from registry.js::atomicWriteJson - crash leaves old file or new, never half. */
+function atomicWriteJson(targetPath, obj) {
+  const dir = path.dirname(targetPath);
+  const base = path.basename(targetPath);
+  const tmp = path.join(dir, `.${base}.${process.pid}.${Date.now()}.tmp`);
+  const data = JSON.stringify(obj, null, 2) + '\n';
+  const fd = fs.openSync(tmp, 'w');
+  try {
+    fs.writeSync(fd, data, 0, 'utf8');
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.renameSync(tmp, targetPath);
+}
+
+function readJsonIfPresent(p) {
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch (_e) {
+    return null; // absent or unreadable -> nothing to migrate there
+  }
+}
+
+/**
+ * Migrate every gate matcher and state key from oldName to newName, or throw a refusal.
+ * @param {object} o
+ * @param {string} o.hooksPath  hooks.manifest.json path (may be absent on disk)
+ * @param {string} o.statePath  tools.state.json path (may be absent on disk)
+ * @param {string} o.oldName    the surfaced name being retired
+ * @param {string} o.newName    the surfaced name taking over
+ */
+function migrateSurfacedName(o) {
+  const { hooksPath, statePath, oldName, newName } = o || {};
+  if (typeof oldName !== 'string' || typeof newName !== 'string' || oldName === newName) return;
+
+  // ── Phase A: VALIDATE everything, write nothing ─────────────────────────────────────────────
+  const manifest = hooksPath ? readJsonIfPresent(hooksPath) : null;
+  const hooks = manifest && Array.isArray(manifest.hooks) ? manifest.hooks : [];
+  const literal = escapeRegex(oldName);
+  const rewrites = [];
+  for (const h of hooks) {
+    if (!h || typeof h !== 'object') continue;
+    const m = h.matcher;
+    if (m === undefined || m === null || m === '' || m === '*') continue; // wildcard covers both names
+    if (m === literal || m === oldName) {
+      // The exact-literal shape ToolFunnel authors (escaped, or the bare name when it contains
+      // no regex specials - the two are identical then, but hand-written manifests may carry
+      // the bare form for a name that DOES contain specials, e.g. "my.tool").
+      rewrites.push(h);
+      continue;
+    }
+    // A matcher that does not COMPILE cannot be evaluated against oldName at all - matches()
+    // would answer false, silently carrying the rename past a hook this code cannot read.
+    // Same policy as a matching non-literal: refuse, name the hook, touch nothing.
+    // (addEntry refuses these at authoring, so only a hand-edited manifest reaches here.)
+    const compileProblem = matcherError(m);
+    if (compileProblem) {
+      throw new Error(
+        `rename refused: hook "${h.id || '(unnamed)'}" matcher ${JSON.stringify(m)} does not ` +
+        `compile (${compileProblem}) - it cannot be checked against "${oldName}", so the rename ` +
+        'cannot proceed safely. Fix the hook first, then rename'
+      );
+    }
+    if (matches(m, oldName)) {
+      throw new Error(
+        `rename refused: hook "${h.id || '(unnamed)'}" matcher "${m}" matches "${oldName}" but is ` +
+        'not an exact-literal matcher ToolFunnel can rewrite - update the hook to cover ' +
+        `"${newName}" first, then rename`
+      );
+    }
+  }
+
+  const state = statePath ? readJsonIfPresent(statePath) : null;
+  const hasOldState = !!(state && Object.prototype.hasOwnProperty.call(state, oldName));
+  if (hasOldState && Object.prototype.hasOwnProperty.call(state, newName) &&
+      JSON.stringify(state[oldName]) !== JSON.stringify(state[newName])) {
+    throw new Error(
+      `rename refused: tools.state.json already has an entry for "${newName}" that differs from ` +
+      `"${oldName}"'s - resolve the curation collision first, then rename`
+    );
+  }
+
+  // ── Phase B: WRITE (all validation passed) ──────────────────────────────────────────────────
+  if (rewrites.length) {
+    for (const h of rewrites) h.matcher = escapeRegex(newName);
+    atomicWriteJson(hooksPath, manifest);
+  }
+  if (hasOldState) {
+    state[newName] = state[oldName];
+    delete state[oldName];
+    atomicWriteJson(statePath, state);
+  }
+}
+
+/**
+ * Convenience for the two stores: derive the sibling config paths from the CONFIG-HOME layout
+ * (<root>/mcp/expose.json, <root>/tools/tools.register.json, <root>/tools/tools.state.json,
+ * <root>/hooks/hooks.manifest.json) and migrate. `storeFilePath` is the calling store's own
+ * file; its grandparent is the home root.
+ *
+ * `opts.migrateState` (default TRUE) selects whether the tools.state.json key moves with the
+ * name. The gate matcher ALWAYS moves - it genuinely fires on the surfaced name for both stores.
+ * The state key does NOT, because the overlay has TWO key namespaces:
+ *   - UPSTREAM tools are keyed by their SURFACED name (server.js:638,733,924; ui:1273) - an
+ *     expose `as` edit changes that key, so ExposeStore migrates state (the default).
+ *   - LOCAL register tools are keyed by their register ID (server.js:290,337,814-815,952;
+ *     ui:326-328; tf-tool-set.js) - an id is immutable and a display-name edit does not touch
+ *     it, so Registry passes migrateState:false. Moving the key there would ORPHAN the entry:
+ *     the readers still look up the id, find nothing, and fall back to the defaults - which are
+ *     enabled - so a tool deliberately switched off would come back on (rename-safety S5).
+ *     Bites whenever name === id, i.e. every tf_* management tool.
+ */
+function migrateForStoreFile(storeFilePath, oldName, newName, opts) {
+  const root = path.dirname(path.dirname(path.resolve(storeFilePath)));
+  const migrateState = !(opts && opts.migrateState === false);
+  migrateSurfacedName({
+    hooksPath: path.join(root, 'hooks', 'hooks.manifest.json'),
+    statePath: migrateState ? path.join(root, 'tools', 'tools.state.json') : null,
+    oldName,
+    newName,
+  });
+}
+
+module.exports = { migrateSurfacedName, migrateForStoreFile, escapeRegex };

package/src/core/requires.js

@@ -98,7 +98,7 @@ function checkRequires(home) {
     const command = entry.command.trim();
     // A requires command is a bare PROGRAM NAME, never a shell string. This is load-bearing on
     // Windows: the cmd.exe shim fallback below hands the token to cmd, where an unquoted
-    // metacharacter ("x&evil") would CHAIN commands - a probe must never be able to run anything
+    // metacharacter ("x&denied") would CHAIN commands - a probe must never be able to run anything
     // beyond `<program> <versionArg>`. Reject anything shell-shaped up front (also catches paths:
     // declare tools by PATH name, which is the only portable claim a pack can make anyway).
     if (!/^[A-Za-z0-9][A-Za-z0-9._+-]*$/.test(command)) {

package/src/extend/add-hook.md

@@ -2,7 +2,7 @@
 
 This is the instruction served by `toolfunnel_howto({ topic: "add-hook" })`. It explains how to add a hook
 to the Hook Engine: the manifest entry shape, where the script goes, and how the enabled/disabled
-state is persisted separately in `hooks.state.json`. The full contract is HOOK_ENGINE.md - this is
+state is persisted separately in `hooks.state.json`. This is
 the authoring view.
 
 A hook is exactly two things:
@@ -79,7 +79,7 @@ The payload a tool event receives on stdin:
 (`PreToolUse` → `tool_name` + `tool_input`; `PostToolUse` adds `tool_response`. Tool-less
 events carry their own fields - `prompt`, `source` - instead.)
 
-Two protocols (HOOK_ENGINE.md §3):
+Two protocols:
 
 **A) Exit-code (simple):**
 - `exit 0` → success. On `SessionStart`/`UserPromptSubmit`, stdout becomes **injected context**;

package/src/extend/add-mcp.md

@@ -5,15 +5,12 @@ This is the instruction served by `toolfunnel_howto({ topic: "add-mcp" })`. It e
 tools to expose downstream** to the CLI. All of this is configured in one persisted file:
 `mcp/expose.json`.
 
-The architecture (see the architecture overview, §1): many upstream MCPs each expose many tools; the
+The architecture: many upstream MCPs each expose many tools; the
 aggregator connects to them and the **MCP Manager picks which tools to surface** to the CLI as
 *curated-direct* tools - alongside the four lean meta-tools (`toolfunnel_list_tools`,
 `toolfunnel_tool_instructions`, `toolfunnel_run_tool`, `toolfunnel_howto`). The CLI sees a small surface; everything
 else stays reachable through the register.
 
-> Phase note: the live aggregator (`src/mcp/aggregator.js`) is Phase 2. This doc defines the
-> `expose.json` shape so the config is authorable now and the aggregator reads exactly these fields
-> when it lands.
 
 ---
 
@@ -69,7 +66,7 @@ from them:
 |---|---|---|
 | `id` | string | Stable key for this upstream. Referenced by `expose[].upstream`. Unique. |
 | `transport` | string | How the aggregator connects. `"stdio"` (spawn `command`+`args`) is the baseline. |
-| `command` / `args` / `env` | string / string[] / object | The process the aggregator spawns for a `stdio` upstream. Path-shaped **args** must stay **inside the config home** - the isolation guard refuses to connect an upstream whose args escape it. (The `command` itself, an executable, is not guarded; the currently-WRAPPED upstream is exempt in transparent-wrapper mode, with a warning.) |
+| `command` / `args` / `env` | string / string[] / object | The process the aggregator spawns for a `stdio` upstream. The isolation guard refuses to connect an upstream whose path-shaped **args** (including `--flag=value` values), **cwd**, or code-loading **env** vars (`NODE_OPTIONS`, `NODE_PATH`, and their equivalents) reach outside the config home. (The `command` itself, an executable, is not guarded. Opt-outs, each warned loudly by name: the currently-WRAPPED upstream is exempt; `allowOutsidePaths: true` on the entry exempts its paths; `allowCodeLoadingEnv: true` exempts the env class.) |
 | `enabled` | boolean | Whether the aggregator connects to this upstream at startup. |
 | `description` | string | Human-facing note for the MCP Manager UI. |
 
@@ -105,7 +102,7 @@ an `expose` entry (no upstream reconnect required to *list*, though see §3 on t
 
 ## 3. Curated-direct vs. the register (update cost)
 
-This matters because the two layers refresh differently (see the architecture overview, §1):
+This matters because the two layers refresh differently:
 
 - **Curated-direct tools** (what `expose[]` produces) are negotiated with the CLI **at connect time**.
   Changing the exposed set therefore needs a **reconnect**, or a `notifications/tools/list_changed`

package/src/extend/configure.md

@@ -71,7 +71,8 @@ legacy MCP protocol permanently (opt-in, warns loudly); `"env"` passes environme
 the spawned server; `"cwd"` sets its working directory; `"timeoutMs"` raises the payload
 timeout for that upstream (default 120000 ms - applies to `tools/call`, `prompts/get` and
 `resources/read`; under a wrap, a tool that reports progress keeps its call alive regardless.
-The 10 s handshake/list window is fixed: it detects dead servers); `"modernOnly": true`
+the separate 10 s handshake/list window detects dead servers, and `"requestTimeoutMs"` raises
+it for a server that needs longer to boot); `"modernOnly": true`
 requires that upstream to speak the modern (2026-07-28) protocol - the connect fails with a
 clear error instead of falling back to legacy (the mirror of `legacyPin`; setting both on one
 upstream is refused). Server side, `"serveLegacy": false` in `toolfunnel.json` makes the

package/src/extend/create-tool.md

@@ -129,7 +129,7 @@ toolfunnel_run_tool(name, args)
 - **The PreToolUse gate is the whole safety case.** A hook denies a call by returning, on exit 0,
   `{ "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "deny",
   "permissionDecisionReason": "..." } }` - OR by `exit 2` with the reason on stderr. (PreToolUse uses
-  `permissionDecision`, NOT a top-level `decision` - see HOOK_ENGINE.md §3.) When that fires,
+  `permissionDecision`, NOT a top-level `decision` . When that fires,
   `run` returns an error result and the script is never spawned.
 - `permissionDecision: "allow"` passes; `"ask"` is non-blocking in the autonomous host (no
   interactive prompt) - the reason is captured but the tool proceeds.

package/src/extend/howto.js

@@ -1,7 +1,7 @@
 'use strict';
 
 /**
- * howto.js - the loader behind the `toolfunnel_howto` meta-tool (architecture notes §2 + §6).
+ * howto.js - the loader behind the `toolfunnel_howto` meta-tool.
  *
  * `toolfunnel_howto({ topic })` returns the self-extension instructions for one topic. This module
  * resolves a topic to its authored markdown file (the topic -> file map below) and reads it.
@@ -9,12 +9,12 @@
  *   howto(topic) -> string   // the markdown content for that topic
  *
  * Topics: create-tool | add-mcp | add-hook | package | wrap | configure
- * (the original four from §2, plus the 0.6.0 pair - the transparent wrap and the no-code
+ * (the original four topics, plus the 0.6.0 pair - the transparent wrap and the no-code
  * config map - so a primer-less agent can learn the headline feature from inside).
  * Unknown topics THROW (the protocol layer turns that into a clean tool error, not a crash).
  *
  * Isolation: reads are confined to THIS directory (src/extend). The topic map is a fixed
- * allow-list of basenames - there is no path interpolation from the caller, so a malicious
+ * allow-list of basenames - there is no path interpolation from the caller, so an untrusted
  * `topic` cannot traverse out of src/extend. We additionally re-verify the resolved path is
  * inside this directory (defense-in-depth, mirroring the hook loader's writeScript guard).
  *

package/src/extend/package.md

@@ -38,8 +38,9 @@ all three yourself in anything you install.
 The per-UNIT packaging below remains the right shape for sharing a single tool/hook/MCP selection
 rather than a whole gateway.
 
-> Phase note: packages are Phase 2 (`packages/` directory). The structure below is what the importer
-> and exporter target; defining it now means the units authored today are already package-ready.
+The per-unit package is a CONVENTION, not machinery: export and import are the structured
+hand-steps below (each one maps onto a management function), so a package needs no importer
+binary - and the whole-setup `tf_pack` above covers the common case with one call.
 
 ---
 
@@ -59,8 +60,8 @@ A package gathers one or more of these, plus the files they reference.
 
 ## 2. Package layout
 
-A package is a folder under `packages/` containing a manifest and the units' files in a mirrored
-tree so import is a structured copy, not guesswork:
+A package is a folder (conventionally `packages/<name>/` inside the config home) containing a
+manifest and the units' files in a mirrored tree so import is a structured copy, not guesswork:
 
 ```
 packages/
@@ -124,7 +125,7 @@ entries):
           "id": "notify",
           "transport": "stdio",
           "command": "node",
-          "args": ["${PACKAGE_DIR}/mcp/vendor/notify-mcp/server.js"],
+          "args": ["mcp/vendor/notify-mcp/server.js"],
           "enabled": true,
           "description": "Messaging bridge MCP."
         },
@@ -146,8 +147,9 @@ entries):
 | `units.hooks[]` | Each has the full manifest `entry`, its seed `enabled` (for `hooks.state.json`), and `files`. |
 | `units.mcp[]` | Each has an `upstream` block, its `expose[]` selections, and any vendored `files`. |
 
-`${PACKAGE_DIR}` expands to the installed package's absolute path (mirrors `${HOOKS_DIR}` /
-`${TOOLS_DIR}`), so a package's MCP/tool commands resolve wherever it lands.
+Write vendored-server paths RELATIVE and set the upstream's `cwd` to the installed package
+folder (or write the absolute inside-home path at import time) - the isolation guard requires
+them inside the config home either way.
 
 ---
 
@@ -178,7 +180,8 @@ Import is the reverse: **drop a package folder in `packages/` + register its uni
 3. **Hooks:** copy each `units.hooks[].files` into `hooks/scripts/` and add each `entry` to
    `hooks.manifest.json`; write its `enabled` into `hooks.state.json`.
 4. **MCP:** copy vendored `files` into the package's `mcp/vendor/`, add each `upstream` to
-   `expose.json` `upstreams[]` and its `expose[]` selections (path-rewritten to `${PACKAGE_DIR}`).
+   `expose.json` `upstreams[]` and its `expose[]` selections, rewriting the vendored paths for
+   their installed location (inside the config home - the isolation rule).
 
 After import: tools are live immediately (the register is read fresh on every `toolfunnel_list_tools`).
 Hooks take effect once the loader re-scans (next startup, or a reload). Curated-direct MCP tools need