toolfunnel 0.7.1 → 0.8.0

package/src/core/config-home.js

@@ -14,7 +14,8 @@
  * empty directory makes the gateway SEED it on first use - the shipped register + its scripts, an
  * empty expose.json, the default hooks manifest - and every mutable path (tools/ mcp/ hooks/
  * auth/ logs/ toolfunnel.json packages/) anchors there from then on. Seeding never overwrites an
- * existing file, so a home survives package updates by construction.
+ * existing file, so a home survives package updates by construction; the one addition is a tool
+ * new in a release, appended to the register once (offerNewShippedTools).
  *
  * Two env vars are the process-tree contract (children inherit them via defaultRunScript's
  * spawn env):
@@ -31,6 +32,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { atomicWriteJson } = require('./atomic-write');
 
 /** The package root: this file lives at <pkg>/src/core/config-home.js. */
 const PKG_ROOT = path.resolve(__dirname, '..', '..');
@@ -58,23 +60,90 @@ function copyTreeIfAbsent(srcDir, destDir, seeded) {
   } catch (_e) {
     return; // a missing source dir seeds nothing (defensive)
   }
-  fs.mkdirSync(destDir, { recursive: true });
+  // A home the user has made read-only still starts: what cannot be written is not seeded, and the
+  // gateway runs with the files the home already has. Any other failure is real and is thrown.
+  if (!writeOrSkip(() => fs.mkdirSync(destDir, { recursive: true }))) return;
   for (const e of entries) {
     const from = path.join(srcDir, e.name);
     const to = path.join(destDir, e.name);
     if (e.isDirectory()) {
       copyTreeIfAbsent(from, to, seeded);
     } else if (e.isFile() && !fs.existsSync(to)) {
-      fs.copyFileSync(from, to);
-      seeded.push(to);
+      if (writeOrSkip(() => fs.copyFileSync(from, to))) seeded.push(to);
     }
   }
 }
 
+/** Runs a write; false when the file system refuses it for permission (the caller skips that file). */
+function writeOrSkip(write) {
+  try {
+    write();
+    return true;
+  } catch (e) {
+    if (e && (e.code === 'EACCES' || e.code === 'EPERM' || e.code === 'EROFS')) return false;
+    throw e;
+  }
+}
+
+// The shipped register ids of 0.7.x, the releases before tools/tools.seeded.json existed: a home
+// upgraded from one of them has already been offered these, so only tools shipped since are added.
+const SHIPPED_BEFORE_LEDGER = ['echo', 'base64', 'hash', 'uuid', 'json', 'text-stats', 'danger',
+  'tf_tool_add', 'tf_tool_set', 'tf_mcp_add', 'tf_mcp_set', 'tf_wrap', 'tf_hook_add', 'tf_hook_set',
+  'tf_list', 'tf_log', 'tf_pack'];
+
+// Windows paths are case-insensitive: g:\dev\toolfunnel IS the package root.
+const samePath = (a, b) => (process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b);
+const readJson = (file) => { try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch (_e) { return null; } };
+
+/**
+ * Add the shipped register entries this home has never been offered, once each. The ledger
+ * (tools/tools.seeded.json) records every id offered, so a shipped tool the user deleted is never
+ * added back; existing entries are never touched, and an unreadable register or ledger is left
+ * alone. Seeding alone cannot do this: it never overwrites a file, and the register is one file.
+ * @param {string}  home
+ * @param {boolean} registerSeeded  the register was copied in on this call (a fresh home)
+ * @returns {string[]} the ids added to the register
+ */
+function offerNewShippedTools(home, registerSeeded) {
+  const regPath = path.join(home, 'tools', 'tools.register.json');
+  const ledgerPath = path.join(home, 'tools', 'tools.seeded.json');
+  const shipped = readJson(path.join(PKG_ROOT, 'tools', 'tools.register.json'));
+  const reg = readJson(regPath);
+  if (!shipped || !Array.isArray(shipped.tools) || !reg || !Array.isArray(reg.tools)) return [];
+  const shippedIds = shipped.tools.map((t) => t && t.id).filter((id) => typeof id === 'string');
+  const hadLedger = fs.existsSync(ledgerPath);
+  let offered;
+  if (hadLedger) {
+    const ledger = readJson(ledgerPath);
+    if (!ledger || !Array.isArray(ledger.ids)) return [];
+    offered = new Set(ledger.ids);
+  } else {
+    offered = new Set(registerSeeded ? shippedIds : SHIPPED_BEFORE_LEDGER);
+  }
+  const offeredBefore = offered.size;
+  const present = new Set(reg.tools.map((t) => t && t.id));
+  const added = [];
+  for (const t of shipped.tools) {
+    if (!t || offered.has(t.id)) continue;
+    if (!present.has(t.id)) { reg.tools.push(t); added.push(t.id); }
+    offered.add(t.id);
+  }
+  try {
+    if (added.length) atomicWriteJson(regPath, reg);
+    if (!hadLedger || offered.size !== offeredBefore) atomicWriteJson(ledgerPath, { version: 1, ids: [...offered] });
+  } catch (err) {
+    // A home that cannot be rewritten (read-only file or mount) ran fine before: keep it running,
+    // without the new tools, and try again next start.
+    process.stderr.write(`[toolfunnel] could not add new shipped tools to ${regPath}: ${(err && err.message) || err}\n`);
+    return [];
+  }
+  return added;
+}
+
 /**
  * Make `home` a working config home, seeding whatever is ABSENT from the shipped defaults.
  * Idempotent and never destructive: an existing file is NEVER overwritten (a home must survive
- * package updates - that is the whole point). home === package root -> a no-op (the git-clone
+ * package updates - that is the whole point), bar the register gaining a new shipped tool once. home === package root -> a no-op (the git-clone
  * layout is already complete). Throws only if the home cannot be created at all.
  *
  * Deliberately NOT seeded: tools.state.json (absent = default visibility), auth/ (absent = auth
@@ -82,16 +151,18 @@ function copyTreeIfAbsent(srcDir, destDir, seeded) {
  * npm-wrap ships its OWN copy inside its bundled home).
  *
  * @param {string} home  absolute config-home path (from resolveConfigHome)
- * @returns {{home: string, seeded: string[]}} the files seeded on THIS call (empty = was complete)
+ * @returns {{home: string, seeded: string[], added: string[]}} the files seeded on THIS call (empty =
+ *   was complete) and the shipped tool ids newly added to an existing register
  */
 function ensureConfigHome(home) {
   const seeded = [];
-  if (path.resolve(home) === PKG_ROOT) return { home: PKG_ROOT, seeded };
+  if (samePath(path.resolve(home), PKG_ROOT)) return { home: PKG_ROOT, seeded, added: [] };
   fs.mkdirSync(home, { recursive: true });
 
   // The register + every shipped script (management tf_* + demo tools). The management scripts
   // are config-tree citizens (the register's invoke paths point at them), so they travel.
   copyTreeIfAbsent(path.join(PKG_ROOT, 'tools'), path.join(home, 'tools'), seeded);
+  const added = offerNewShippedTools(home, seeded.includes(path.join(home, 'tools', 'tools.register.json')));
   // The state overlay is user-state, not a shipped default - drop a copied one if the package
   // tree happened to carry local toggles (dev clone); a FRESH home starts with default visibility.
   const strayState = path.join(home, 'tools', 'tools.state.json');
@@ -106,6 +177,19 @@ function ensureConfigHome(home) {
   // the example is a POPULATED demo (it attaches the mock upstream), and a fresh home must start
   // connected to nothing, exactly like a fresh clone.
   copyTreeIfAbsent(path.join(PKG_ROOT, 'mcp'), path.join(home, 'mcp'), seeded);
+  // That tarball fact does not hold for a git clone: the package tree then carries the LIVE
+  // store (mcp/expose.json) and any operator backups of it, both user-state, and the copy above
+  // brought them across - so the "synthesise EMPTY when absent" guard below was dead and a fresh
+  // home started attached to the developer's real upstreams. Same class as the tools.state.json
+  // case above, same remedy: at this level the package ships ONLY expose.example.json (see
+  // package.json "files"), so drop anything else the copy seeded here.
+  const mcpHome = path.join(home, 'mcp');
+  for (const copied of seeded.slice()) {
+    if (path.dirname(copied) === mcpHome && path.basename(copied) !== 'expose.example.json') {
+      try { fs.unlinkSync(copied); } catch (_e) { /* best-effort */ }
+      seeded.splice(seeded.indexOf(copied), 1);
+    }
+  }
   const exposePath = path.join(home, 'mcp', 'expose.json');
   if (!fs.existsSync(exposePath)) {
     fs.mkdirSync(path.dirname(exposePath), { recursive: true });
@@ -113,7 +197,15 @@ function ensureConfigHome(home) {
     seeded.push(exposePath);
   }
   copyTreeIfAbsent(path.join(PKG_ROOT, 'hooks'), path.join(home, 'hooks'), seeded);
-  return { home, seeded };
+  // hooks.state.json is user state too - the live hook toggles - same class as tools.state.json above:
+  // a git clone's copy must not travel into a fresh home, which starts from the shipped manifest's own
+  // enabled flags (config-home-hookstate.test.js).
+  const strayHookState = path.join(home, 'hooks', 'hooks.state.json');
+  if (seeded.includes(strayHookState)) {
+    try { fs.unlinkSync(strayHookState); } catch (_e) { /* best-effort */ }
+    seeded.splice(seeded.indexOf(strayHookState), 1);
+  }
+  return { home, seeded, added };
 }
 
 /**

package/src/core/hook-engine.js

@@ -25,7 +25,7 @@
  *     contributes a synthetic BLOCKING result (its command never runs) - an unreadable gate is
  *     never permission, mirroring the runner's unreadable-decision rule. Authoring surfaces
  *     refuse such a matcher up front (hook-loader.addEntry), so this only fires for a
- *     hand-edited manifest. (0.7.0; matcher-compile.test.js is the acceptance.)
+ *     hand-edited manifest.
  *   - Build the stdin payload once via events.buildPayload(event, ctx, extra).
  *   - Run selected hooks CONCURRENTLY (they are independent) with a global concurrency cap
  *     (default 8) so a big event cannot fork-bomb, but return results in MANIFEST ORDER.
@@ -48,56 +48,22 @@ const hookRunner = require('./hook-runner');
 
 const DEFAULT_CONCURRENCY = 8;
 
-/**
- * Resolve the matcher function from matcher.js regardless of whether it is the default or
- * a named export, so we interlock with the contract's `matches(matcher, toolName)`.
- * @returns {(m: string|undefined, toolName: string) => boolean}
- */
-function getMatchesFn() {
-  if (typeof matcher === 'function') return matcher;
-  if (matcher && typeof matcher.matches === 'function') return matcher.matches;
-  // Defensive fallback: if matcher.js is unavailable, fire everything (never crash).
-  return () => true;
-}
-
-/**
- * Resolve matcherError from matcher.js (named export). Falls back to "no problem" so an older
- * matcher module degrades to the previous behaviour rather than crashing the engine.
- * @returns {(m: string|undefined) => (string|null)}
- */
-function getMatcherErrorFn() {
-  if (matcher && typeof matcher.matcherError === 'function') return matcher.matcherError;
-  return () => null;
-}
-
-/**
- * Resolve buildPayload from events.js (named export per contract).
- * @returns {(event: string, ctx: object, extra: object) => object}
- */
-function getBuildPayloadFn() {
-  if (events && typeof events.buildPayload === 'function') return events.buildPayload;
-  // Defensive fallback: assemble a minimal common payload.
-  return (event, ctx, extra) =>
-    Object.assign(
-      {
-        session_id: (ctx && ctx.session_id) || '',
-        transcript_path: (ctx && ctx.transcript_path) || '',
-        cwd: (ctx && ctx.cwd) || process.cwd(),
-        hook_event_name: event,
-      },
-      extra || {}
-    );
-}
-
-/**
- * Resolve runHook from hook-runner.js (named export per contract).
- * @returns {(spec: object, payload: object, opts: object) => Promise<object>}
- */
-function getRunHookFn() {
-  if (hookRunner && typeof hookRunner.runHook === 'function') return hookRunner.runHook;
-  if (typeof hookRunner === 'function') return hookRunner;
-  throw new Error('hook-engine: hook-runner.runHook is unavailable');
+// The engine's dependencies, bound directly, with no stand-ins: firing every hook, reading every
+// matcher as valid or building a payload by hand would change what a gate means, and the one case
+// that reaches them (a broken or mismatched install) is exactly when it must not. Refuse to LOAD
+// instead, naming what is missing
+// (hook-engine-requires.test.js).
+function required(mod, name, from) {
+  const fn = mod && mod[name];
+  if (typeof fn !== 'function') {
+    throw new Error(`hook-engine: ${from} must export ${name}() - refusing to load without it`);
+  }
+  return fn;
 }
+const matchesFn = required(matcher, 'matches', './matcher');
+const matcherErrorFn = required(matcher, 'matcherError', './matcher');
+const buildPayloadFn = required(events, 'buildPayload', './events');
+const runHookFn = required(hookRunner, 'runHook', './hook-runner');
 
 /**
  * Build a synthetic "failed" result matching the runner's result shape, used when the runner rejects
@@ -180,10 +146,10 @@ class HookEngine {
     this.env = opts.env || null;
 
     // Resolve contract functions once.
-    this._matches = getMatchesFn();
-    this._matcherError = getMatcherErrorFn();
-    this._buildPayload = getBuildPayloadFn();
-    this._runHook = getRunHookFn();
+    this._matches = matchesFn;
+    this._matcherError = matcherErrorFn;
+    this._buildPayload = buildPayloadFn;
+    this._runHook = runHookFn;
   }
 
   /**
@@ -224,6 +190,15 @@ class HookEngine {
     const runCwd = (payload && payload.cwd) || this.cwd;
     const runOpts = { cwd: runCwd };
     if (this.env) runOpts.env = this.env;
+    // The home the hooks were loaded from, so the runner sets HOOKS_DIR for the child from THIS
+    // tree (a relocated --config-dir home) rather than its package default - the same value the
+    // engine already uses for the child cwd above. CLAUDE_PROJECT_DIR: a value INHERITED from the
+    // gateway's own environment (a host's project - hooks ported from Claude Code read it that way)
+    // wins; the home is the fallback when nothing set it.
+    if (this.loader.hooksDir) {
+      runOpts.hooksDir = this.loader.hooksDir;
+      runOpts.projectDir = process.env.CLAUDE_PROJECT_DIR || path.dirname(this.loader.hooksDir);
+    }
 
     // Select enabled hooks for this event and build task factories, in MANIFEST ORDER.
     //

package/src/core/hook-loader.js

@@ -396,7 +396,7 @@ class HookLoader {
     // A matcher that does not compile can never be evaluated - storing it would author a
     // hook whose gate the engine must refuse on every tool-bearing call (hook-engine's
     // unreadable-gate rule). Refuse HERE so the UI's POST /api/hooks/add and tf_hook_add
-    // both answer with the problem instead of 200/ok. (0.7.0; matcher-compile.test.js.)
+    // both answer with the problem instead of 200/ok.
     if (spec.matcher !== undefined && spec.matcher !== null && typeof spec.matcher !== 'string') {
       throw new Error('addEntry: spec.matcher must be a string when provided');
     }
@@ -640,66 +640,8 @@ function collapseManifest(manifest, hooksDir) {
   return copy;
 }
 
-/**
- * Atomically write a JS object as pretty JSON: write to a temp file in the SAME directory
- * as the target (so rename is atomic on the same filesystem), then rename over the target.
- *
- * @param {string} targetPath absolute destination
- * @param {object} obj
- */
-function atomicWriteJson(targetPath, obj) {
-  const data = JSON.stringify(obj, null, 2) + '\n';
-  atomicWriteText(targetPath, data, path.dirname(targetPath));
-}
-
-/**
- * Atomically write text: temp file in `tmpDir` (must be on the same volume as the target),
- * fsync, then rename over the target. Cleans up the temp file on failure.
- *
- * @param {string} targetPath absolute destination
- * @param {string} data
- * @param {string} tmpDir directory to place the temp file (same FS as target)
- */
-function atomicWriteText(targetPath, data, tmpDir) {
-  const dir = tmpDir || path.dirname(targetPath);
-  const tmpName = `.${path.basename(targetPath)}.${process.pid}.${Date.now()}.${Math.random()
-    .toString(36)
-    .slice(2)}.tmp`;
-  const tmpPath = path.join(dir, tmpName);
-
-  let fd;
-  try {
-    fd = fs.openSync(tmpPath, 'w');
-    fs.writeFileSync(fd, data);
-    try {
-      fs.fsyncSync(fd);
-    } catch (_) {
-      // fsync may fail on some platforms/filesystems; the rename is still ordered.
-    }
-  } finally {
-    if (fd !== undefined) {
-      try {
-        fs.closeSync(fd);
-      } catch (_) {
-        /* ignore */
-      }
-    }
-  }
-
-  try {
-    // rename is atomic on the same filesystem and overwrites the destination on POSIX;
-    // on Windows it overwrites too as long as the target isn't locked.
-    fs.renameSync(tmpPath, targetPath);
-  } catch (err) {
-    // Best-effort cleanup so we don't leave temp files behind.
-    try {
-      fs.unlinkSync(tmpPath);
-    } catch (_) {
-      /* ignore */
-    }
-    throw err;
-  }
-}
+// THE atomic writer (temp + fsync + rename, failure-path unlink, stale sweep) - shared by every store.
+const { atomicWriteJson, atomicWriteText } = require('./atomic-write');
 
 /**
  * Load a manifest from disk, expand ${HOOKS_DIR} in every command string, and return a

package/src/core/hook-runner.js

@@ -14,21 +14,35 @@
 
 const { spawn, execFile } = require('node:child_process');
 const reaper = require('./child-reaper');
+const { takeWithinCap } = require('./output-cap');
 const path = require('node:path');
 
-// Default HOOKS_DIR: <root>/src/hooks. __dirname is <root>/src/core, so up one.
-const DEFAULT_HOOKS_DIR = path.resolve(__dirname, '..', 'hooks');
+// Default HOOKS_DIR: <root>/hooks (the shipped hooks tree). __dirname is <root>/src/core, so up two.
+// The engine always passes the loaded home's hooksDir, so only a direct runHook() call without
+// options sees this default.
+const DEFAULT_HOOKS_DIR = path.resolve(__dirname, '..', '..', 'hooks');
 
 // Events whose exit-0 stdout is treated as injected context (the exit-code protocol's injection half).
 const INJECTABLE_EVENTS = new Set(['SessionStart', 'UserPromptSubmit']);
 
-// Returned by tryParseJsonProtocol when stdout was clearly meant to be a protocol object (it opens
-// with '{') but does not parse. This is DISTINCT from null: null means "no protocol was attempted,
+// Returned by tryParseJsonProtocol when stdout clearly carried an ATTEMPTED decision (it opens with
+// '{', or a line-opening '{' block after other output names a protocol key) that does not parse. This is DISTINCT from null: null means "no protocol was attempted,
 // use the exit-code protocol", whereas this means "a decision was attempted but could not be read".
 // The two must be handled differently - an unreadable decision fails closed, the same as output
 // past the cap, so a decision that loses a character is never mistaken for "allow".
 const CORRUPT_PROTOCOL = Symbol('corrupt-protocol');
 
+// A line-opening '{' block that will not parse counts as an ATTEMPTED decision only when it names a
+// protocol key - otherwise it is a diagnostic dump, not an answer.
+// Keys may be double-quoted (JSON), single-quoted (a printed Python dict) or bare (a Node object printed
+// without JSON.stringify) - all three are a hook TRYING to answer, and an unreadable answer is never allow.
+const PROTOCOL_KEY_RE = /(^|[{,\s])(["']?)(continue|decision|reason|hookSpecificOutput|permissionDecision)\2\s*:/;
+// The prefixed scan is BOUNDED: it inspects at most this many line-opening '{' lines from the tail, and
+// tries the block-to-end parse (a pretty-printed decision) only for the last few of them. Unbounded, a
+// hook dumping tens of thousands of object lines stalled the gateway's event loop for seconds per call.
+const MAX_CANDIDATE_LINES = 64;
+const MAX_BLOCK_CANDIDATES = 4;
+
 // Output ceilings. A hook's decision is a small JSON object and its diagnostics are a few lines;
 // anything approaching these is a runaway, and accumulating it unbounded would OOM the gateway
 // itself. Hitting either cap is treated as a WIRING FAILURE and fails closed (see the accumulator
@@ -59,10 +73,24 @@ function isKnownJsonProtocol(parsed) {
 }
 
 /**
- * Try to parse stdout as the JSON protocol. Returns the parsed object if it is
- * valid JSON AND carries known protocol keys; CORRUPT_PROTOCOL if stdout opened
- * with '{' (a protocol object was attempted) but did not parse; otherwise null
- * (no protocol attempt - use the exit-code protocol).
+ * Try to read stdout as the JSON protocol. Returns the parsed decision object when one is found;
+ * CORRUPT_PROTOCOL when a decision was ATTEMPTED but cannot be read; otherwise null (no protocol
+ * attempt - use the exit-code protocol).
+ *
+ * When the whole of stdout is one JSON value, that is the answer (a decision if it names a
+ * protocol key, otherwise none). Otherwise - a startup line before the decision, log lines after
+ * it - the decision is a block that opens with '{' at the start of a line: the block running to
+ * the end of stdout (a pretty-printed decision) or that one line. A block that opens with '{' and
+ * parses as something else (an inspect-style dump, a JSON log line) is not a decision. An
+ * unparseable block that NAMES a protocol key (quoted or bare) AFTER the last readable decision is
+ * an attempted answer -> CORRUPT: the hook's last word could not be read. Unparseable chatter is
+ * chatter; without that narrowing an allow-gate that printed `{ tool: 'x' }` denied every call.
+ *
+ * Two readable decisions that disagree are CORRUPT too: a hook that echoes what it was given (tool
+ * arguments, an audit line) prints text the MODEL controls, and that text must never outvote the
+ * hook's own answer, before or after it. For the same reason a scan cut short by its bound
+ * (MAX_CANDIDATE_LINES, so a hook dumping thousands of object lines cannot stall the event loop)
+ * is CORRUPT when anything it did not read names a protocol key - that could be the real answer.
  *
  * @param {string} stdout
  * @returns {object|symbol|null}
@@ -70,19 +98,42 @@ function isKnownJsonProtocol(parsed) {
 function tryParseJsonProtocol(stdout) {
   const trimmed = (stdout || '').trim();
   if (!trimmed) return null;
-  // Cheap pre-check: protocol output is always a JSON object. Anything not opening with '{' made
-  // no protocol attempt and belongs to the exit-code protocol (arbitrary text a hook prints).
-  if (trimmed[0] !== '{') return null;
-  let parsed;
-  try {
-    parsed = JSON.parse(trimmed);
-  } catch (_e) {
-    // Opened with '{' but is not valid JSON: an attempted decision that could not be read. Signal
-    // CORRUPT (fail closed) rather than null - falling through to exit-code here would let a
-    // truncated or malformed deny be read as "allow".
-    return CORRUPT_PROTOCOL;
+  const asObject = (text) => {
+    let v;
+    try { v = JSON.parse(text); } catch (_e) { return undefined; } // undefined = did not parse
+    return v !== null && typeof v === 'object' && !Array.isArray(v) ? v : null; // null = parsed, not an object
+  };
+  if (trimmed[0] === '{') {
+    const whole = asObject(trimmed);
+    if (whole !== undefined) return whole && isKnownJsonProtocol(whole) ? whole : null;
+  }
+  const lines = trimmed.split('\n');
+  const decisions = [];
+  let attempted = false;
+  let seen = 0;
+  let blocks = 0;
+  let i = lines.length - 1;
+  for (; i >= 0 && seen < MAX_CANDIDATE_LINES; i -= 1) {
+    if (lines[i][0] !== '{') continue;
+    seen += 1;
+    const candidates = blocks < MAX_BLOCK_CANDIDATES ? [lines.slice(i).join('\n'), lines[i]] : [lines[i]];
+    if (blocks < MAX_BLOCK_CANDIDATES) blocks += 1;
+    let readable = false;
+    for (const candidate of candidates) {
+      const obj = asObject(candidate);
+      if (obj === undefined) continue;
+      readable = true;
+      if (obj && isKnownJsonProtocol(obj)) decisions.push(obj);
+      break;
+    }
+    // Scanned from the tail: before any decision is found, an unreadable answer is the LAST word.
+    if (!readable && decisions.length === 0 && PROTOCOL_KEY_RE.test(candidates[0])) attempted = true;
   }
-  return isKnownJsonProtocol(parsed) ? parsed : null;
+  // Cut short by the bound: an unread line that names a protocol key could be the hook's answer.
+  if (attempted || lines.slice(0, i + 1).some((l) => PROTOCOL_KEY_RE.test(l))) return CORRUPT_PROTOCOL;
+  if (decisions.length === 0) return null;
+  const first = JSON.stringify(decisions[0]);
+  return decisions.every((d) => JSON.stringify(d) === first) ? decisions[0] : CORRUPT_PROTOCOL;
 }
 
 /**
@@ -94,7 +145,7 @@ function tryParseJsonProtocol(stdout) {
  * @param {string} [opts.cwd]              child working directory.
  * @param {object} [opts.env]             extra env merged over process.env.
  * @param {string} [opts.projectDir]      value for CLAUDE_PROJECT_DIR.
- * @param {string} [opts.hooksDir]        value for HOOKS_DIR (default <root>/src/hooks).
+ * @param {string} [opts.hooksDir]        value for HOOKS_DIR (default <root>/hooks).
  * @param {AbortSignal} [opts.signal]      external cancellation; aborts the child.
  * @returns {Promise<object>}  the full result shape. Never rejects.
  */
@@ -142,8 +193,9 @@ function runHook(hookSpec, payload, opts = {}) {
       opts.projectDir ||
       (opts.env && opts.env.CLAUDE_PROJECT_DIR) ||
       process.env.CLAUDE_PROJECT_DIR ||
-      // Project root is two levels above the hooks dir (<root>/src/hooks -> <root>).
-      path.resolve(hooksDir, '..', '..');
+      // The project root is the tree the hooks dir sits in (<root>/hooks -> <root>; a config home's
+      // <home>/hooks -> <home>).
+      path.dirname(hooksDir);
 
     const childEnv = Object.assign({}, process.env, opts.env || {}, {
       CLAUDE_PROJECT_DIR: projectDir,
@@ -244,9 +296,9 @@ function runHook(hookSpec, payload, opts = {}) {
     //
     // 'close' fires only when every stdio pipe is closed, and a GRANDCHILD that inherited those
     // pipes keeps them open for its own lifetime even after the shell is dead. Waiting for 'close'
-    // therefore made the timeout unenforceable in exactly the case it exists for: measured
-    // 2026-07-30, a hook whose grandchild slept 60 s resolved at 60 s against a 2.5 s timeout, on
-    // Windows, WITH taskkill /T. The tree kill still matters (it stops us leaking processes), but
+    // would make the timeout unenforceable in exactly the case it exists for: a hook whose
+    // grandchild sleeps 60 s resolves at 60 s against a 2.5 s timeout, on Windows, even WITH
+    // taskkill /T. The tree kill still matters (it stops us leaking processes), but
     // the timeout contract must not depend on it succeeding on any platform.
     const timer = setTimeout(() => {
       timedOut = true;
@@ -309,13 +361,11 @@ function runHook(hookSpec, payload, opts = {}) {
       child.stdout.setEncoding('utf8');
       child.stdout.on('data', (chunk) => {
         if (hrOutBytes >= MAX_STDOUT_BYTES) return;
-        hrOutBytes += Buffer.byteLength(chunk, 'utf8');
-        // Trim the final chunk to the byte budget - streams deliver whole chunks, so appending
-        // before checking retained up to cap+chunkSize (seen: +64KB on win node 18/20, where
-        // chunk boundaries do not align with the cap). Chars trimmed by a byte overshoot can
-        // only under-retain (a char is >= 1 byte), which is the safe side of the ceiling.
-        const outOver = hrOutBytes - MAX_STDOUT_BYTES;
-        stdout += outOver > 0 ? chunk.slice(0, Math.max(0, chunk.length - outOver)) : chunk;
+        // Streams deliver whole chunks (64 KB on Windows), so the chunk that crosses the cap is cut to the bytes
+        // left, at a whole character: never past the cap, never half a character or half a surrogate pair.
+        const kept = takeWithinCap(chunk, hrOutBytes, MAX_STDOUT_BYTES);
+        stdout += kept;
+        hrOutBytes = kept.length < chunk.length ? MAX_STDOUT_BYTES : hrOutBytes + Buffer.byteLength(kept, 'utf8');
         if (hrOutBytes >= MAX_STDOUT_BYTES) {
           outputCapped = 'stdout';
           killChildTree();
@@ -327,9 +377,9 @@ function runHook(hookSpec, payload, opts = {}) {
       child.stderr.setEncoding('utf8');
       child.stderr.on('data', (chunk) => {
         if (hrErrBytes >= MAX_STDERR_BYTES) return;
-        hrErrBytes += Buffer.byteLength(chunk, 'utf8');
-        const errOver = hrErrBytes - MAX_STDERR_BYTES;
-        stderr += errOver > 0 ? chunk.slice(0, Math.max(0, chunk.length - errOver)) : chunk;
+        const kept = takeWithinCap(chunk, hrErrBytes, MAX_STDERR_BYTES);
+        stderr += kept;
+        hrErrBytes = kept.length < chunk.length ? MAX_STDERR_BYTES : hrErrBytes + Buffer.byteLength(kept, 'utf8');
         if (hrErrBytes >= MAX_STDERR_BYTES) {
           stderr += '\n[hook-runner: stderr truncated at cap]';
           if (!outputCapped) outputCapped = 'stderr';
@@ -420,11 +470,11 @@ function runHook(hookSpec, payload, opts = {}) {
       // B) Advanced / JSON protocol - honored only on exit 0.
       const json = r.exitCode === 0 ? tryParseJsonProtocol(stdout) : null;
 
-      // A protocol object that FAILED TO PARSE (stdout opened with '{' but is not valid JSON) is an
-      // unreadable decision. It fails closed - denied - the same as output past the cap: the runner
-      // saw an attempted answer it could not read, and an unreadable answer is never "allow". Only
-      // stdout that made no protocol attempt (no leading '{', or valid JSON that is not a decision)
-      // falls through to the exit-code protocol below.
+      // An ATTEMPTED decision that FAILED TO PARSE (see tryParseJsonProtocol for what counts as an
+      // attempt) is an unreadable decision. It fails closed - denied - the same as output past the
+      // cap: the runner saw an attempted answer it could not read, and an unreadable answer is never
+      // "allow". Only stdout that made no protocol attempt (plain text, valid JSON that is not a
+      // decision) falls through to the exit-code protocol below.
       if (json === CORRUPT_PROTOCOL) {
         r.blocked = true;
         r.reason = `hook-runner: ${event || 'hook'}${id ? ` "${id}"` : ''} emitted a protocol `
@@ -448,8 +498,7 @@ function runHook(hookSpec, payload, opts = {}) {
         // output caps). A key marks an attempt ONLY when it carries a value: `null` is the
         // readable spelling of "no value" - what typed-struct and dataclass serialisers
         // emit for an unset optional field - so a null slot is no decision and falls
-        // through exactly as the absent key does. (0.7.0; gate-semantics.test.js pins
-        // both halves.)
+        // through exactly as the absent key does.
         const permAttempted =
           hso !== null &&
           Object.prototype.hasOwnProperty.call(hso, 'permissionDecision') &&

package/src/core/logger.js

@@ -16,10 +16,10 @@
  *     swallowed silently.
  *
  * 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
+ * <home>/logs/. 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
+ * assert, registry.writeScript, sendStatic), and so is this one. 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
@@ -28,7 +28,7 @@
  * 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`
+ * Both paths are BOUNDED: 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.
  *
@@ -41,6 +41,7 @@ const path = require('node:path');
 /** The CONFIG HOME (TOOLFUNNEL_HOME / --config-dir; defaults to the package root - see
  *  config-home.js). Logs + their toggle are user-state, so they live with the home. */
 const { resolveConfigHome } = require('./config-home');
+const { atomicWriteJson } = require('./atomic-write'); // THE atomic writer, shared by every store
 const ROOT = resolveConfigHome();
 
 /** The toggle/config file. NOT created until setConfig() writes it. */
@@ -190,10 +191,7 @@ function setConfig(patch) {
   };
 
   fs.mkdirSync(path.dirname(CONFIG_PATH), { recursive: true });
-  // Atomic write: write a unique temp file, then rename over the target.
-  const tmp = CONFIG_PATH + '.' + process.pid + '.' + Date.now() + '.tmp';
-  fs.writeFileSync(tmp, JSON.stringify(next, null, 2) + '\n');
-  fs.renameSync(tmp, CONFIG_PATH);
+  atomicWriteJson(CONFIG_PATH, next); // temp + fsync + rename, failure-path unlink, stale sweep
 
   return next;
 }