toolfunnel 0.7.0 → 0.7.1

package/src/core/hook-loader.js

@@ -1,824 +1,824 @@
-'use strict';
-
-/**
- * hook-loader.js - load and persist the hook manifest, resolve runnable specs.
- *
- * Contract: the manifest shape and the loader API are both specified below.
- *
- * Responsibilities:
- *   - loadManifest(path): read hooks.manifest.json, expand ${HOOKS_DIR} (the absolute
- *     src/hooks dir) inside every command string, return { version, hooksDir, hooks: Spec[] }.
- *   - enabledHooksFor(event): the enabled specs for a lifecycle event.
- *   - setEnabled(id, bool): flip a hook's enabled flag and persist ATOMICALLY (temp + rename).
- *   - readScript(id): the hook's source text (for the manager's "open").
- *   - writeScript(id, text): save to the COPY under src/hooks/scripts - and REFUSE any
- *     resolved path outside src/hooks/scripts (path-traversal guard, isolation rule).
- *
- * Hook Manager v2 additions - all ADDITIVE; the API above
- * keeps its exact behaviour so the existing loader tests still pass:
- *   - AUTO-DETECT: autodetect() scans <hooksDir>/scripts for hook scripts and reconciles
- *     them with the manifest. The FOLDER is the source of truth for what EXISTS; the
- *     manifest is CONFIG. Scripts on disk with no manifest entry surface as detected
- *     entries (enabled:false, detected:true, event/matcher unknown). Manifest entries
- *     whose script is missing on disk are flagged (present:false). Aliased as
- *     detect/reconcile/scan/inventory/reconcileScripts.
- *   - PERSIST STATE: enabled-state lives in <hooksDir>/hooks.state.json, an overlay keyed
- *     by hook id ({ "<id>": bool }). On load it is applied OVER the manifest's enabled
- *     flags (overlay WINS - documented precedence). setEnabled writes the overlay
- *     atomically (temp+rename) IN ADDITION to mutating the manifest, so toggles survive
- *     restarts and stay separate from the inventory.
- *
- * CommonJS only. Node built-ins only.
- */
-
-const fs = require('node:fs');
-const path = require('node:path');
-
-// Lifecycle event names (frozen) - used to validate addEntry specs against the
-// six supported events. events.js has zero host imports, so this cannot cycle.
-const { EVENT_NAMES } = require('./events');
-
-// The matcher-compile discriminator - addEntry refuses a matcher that can never be
-// evaluated (matcher.js has zero host imports, so this cannot cycle either).
-const { matcherError } = require('./matcher');
-
-/**
- * Extensions we treat as hook scripts during auto-detect. Everything else in the
- * scripts dir (e.g. *.conf files, READMEs) is config/data, not a hook.
- */
-const HOOK_SCRIPT_EXTS = /\.(sh|js|cjs|mjs|cmd|bat|ps1|py)$/i;
-
-/**
- * Resolve the absolute src/hooks directory from the manifest's own location and its
- * declared (possibly relative) hooksDir. The manifest lives at <hooks>/hooks.manifest.json,
- * so its directory IS the hooks dir; we honor an explicit absolute hooksDir if given but
- * otherwise anchor to the manifest file's location (robust against cwd differences).
- *
- * @param {string} manifestPath absolute path to hooks.manifest.json
- * @param {string|undefined} declaredHooksDir the manifest's "hooksDir" field
- * @returns {string} absolute path to the hooks directory
- */
-function resolveHooksDir(manifestPath, declaredHooksDir) {
-  const manifestDir = path.dirname(path.resolve(manifestPath));
-  if (!declaredHooksDir) return manifestDir;
-  if (path.isAbsolute(declaredHooksDir)) return path.resolve(declaredHooksDir);
-  // Relative hooksDir is interpreted relative to the manifest's directory's parent only
-  // when it does not simply re-point at the manifest dir; in practice the manifest sits
-  // inside the hooks dir, so the manifest directory is the source of truth.
-  return manifestDir;
-}
-
-/**
- * Expand ${HOOKS_DIR} occurrences in a string with the absolute hooks dir.
- * Defensive: returns the input unchanged for non-strings.
- *
- * @param {string} str
- * @param {string} hooksDir absolute hooks directory
- * @returns {string}
- */
-function expandHooksDir(str, hooksDir) {
-  if (typeof str !== 'string') return str;
-  // Replace every literal occurrence of ${HOOKS_DIR}. We avoid regex special-char issues
-  // by using split/join on the literal token.
-  return str.split('${HOOKS_DIR}').join(hooksDir);
-}
-
-class HookLoader {
-  /**
-   * @param {string} manifestPath absolute path to hooks.manifest.json
-   * @param {object} manifest the parsed + expanded manifest object
-   * @param {string} hooksDir absolute hooks directory
-   */
-  constructor(manifestPath, manifest, hooksDir) {
-    this.manifestPath = manifestPath;
-    this.manifest = manifest;
-    this.hooksDir = hooksDir;
-    // The scripts copy directory - the ONLY place writeScript may touch.
-    this.scriptsDir = path.join(hooksDir, 'scripts');
-    // v2: the persisted enabled-state overlay (keyed by hook id), kept separate
-    // from the manifest inventory. Lives next to the manifest in the hooks dir.
-    this.statePath = path.join(hooksDir, 'hooks.state.json');
-  }
-
-  /** @returns {number} manifest schema version */
-  get version() {
-    return this.manifest && this.manifest.version;
-  }
-
-  /** @returns {Array<object>} all hook specs (expanded) */
-  get hooks() {
-    return (this.manifest && Array.isArray(this.manifest.hooks)) ? this.manifest.hooks : [];
-  }
-
-  /**
-   * Enabled specs for a given lifecycle event, in manifest order.
-   * @param {string} event one of EVENTS
-   * @returns {Array<object>}
-   */
-  enabledHooksFor(event) {
-    return this.hooks.filter((h) => h && h.event === event && h.enabled === true);
-  }
-
-  /**
-   * Look up a single spec by id.
-   * @param {string} id
-   * @returns {object|undefined}
-   */
-  getSpec(id) {
-    return this.hooks.find((h) => h && h.id === id);
-  }
-
-  // ── v2: persisted enabled-state overlay ──────────────────────────────────
-
-  /**
-   * Read the enabled-state overlay from hooks.state.json. The overlay is a flat
-   * map of hook id -> boolean. Missing/unreadable/malformed file -> empty overlay
-   * (the manifest's own enabled flags stand). Never throws.
-   *
-   * @returns {Object<string, boolean>}
-   */
-  readState() {
-    let raw;
-    try {
-      raw = JSON.parse(fs.readFileSync(this.statePath, 'utf8'));
-    } catch (_) {
-      return {};
-    }
-    return normalizeState(raw);
-  }
-
-  /**
-   * Persist the enabled-state overlay atomically (temp + rename). Confined to the
-   * hooks dir. The overlay carries ONLY booleans keyed by hook id.
-   *
-   * @param {Object<string, boolean>} overlay
-   * @returns {void}
-   */
-  writeState(overlay) {
-    const clean = normalizeState(overlay);
-    atomicWriteJson(this.statePath, clean);
-  }
-
-  /**
-   * Apply the on-disk state overlay over the in-memory manifest specs. The overlay
-   * WINS over the manifest's own enabled flag (documented precedence). Called on
-   * load so enabledHooksFor reflects the persisted toggles. Idempotent.
-   *
-   * @returns {Object<string, boolean>} the overlay that was applied
-   */
-  applyStateOverlay() {
-    const overlay = this.readState();
-    for (const h of this.hooks) {
-      if (!h || typeof h.id !== 'string') continue;
-      if (Object.prototype.hasOwnProperty.call(overlay, h.id)) {
-        h.enabled = overlay[h.id] === true;
-      }
-    }
-    return overlay;
-  }
-
-  // ── v2: auto-detect / reconcile inventory ────────────────────────────────
-
-  /**
-   * Scan <hooksDir>/scripts for hook scripts and reconcile with the manifest.
-   *
-   * The FOLDER is the source of truth for what EXISTS; the manifest is CONFIG.
-   *   - Manifest entries are returned with `present` reflecting whether their
-   *     `script` file exists on disk (manifest entries with no script - inline
-   *     commands - are treated as present:true, since there is no file to miss).
-   *   - Scripts present on disk but absent from the manifest are surfaced as
-   *     `detected` entries: enabled:false, detected:true, event/matcher unknown.
-   *
-   * Returns a normalised inventory. `all` is the union (configured first, in
-   * manifest order, then detected). Pure read - does not mutate the manifest or
-   * touch disk beyond reading the scripts dir.
-   *
-   * @returns {{ all: object[], configured: object[], detected: object[], orphans: object[] }}
-   */
-  autodetect() {
-    const scriptFiles = this._scanScripts(); // Set of basenames present on disk
-    const referenced = new Set();
-
-    const configured = [];
-    const orphans = [];
-
-    for (const h of this.hooks) {
-      if (!h || typeof h !== 'object') continue;
-      const base = scriptBasename(h.script);
-      if (base) referenced.add(base);
-
-      // Inline-command hooks (script:null) have no file to verify -> present.
-      const present = base ? scriptFiles.has(base) : true;
-      const entry = Object.assign({}, h, {
-        detected: false,
-        configured: true,
-        present,
-      });
-      if (!present) {
-        // Orphan: manifest references a script that does not exist on disk.
-        entry.missing = true;
-        entry.scriptMissing = true;
-        entry.exists = false;
-        entry.status = 'missing';
-        orphans.push(entry);
-      }
-      configured.push(entry);
-    }
-
-    // Scripts on disk with no manifest entry -> detected, unconfigured.
-    const detected = [];
-    for (const base of scriptFiles) {
-      if (referenced.has(base)) continue;
-      detected.push({
-        id: `detected/${base.replace(/\.[^.]+$/, '')}`,
-        event: null, // unknown - not yet configured
-        matcher: null,
-        type: 'command',
-        script: path.posix.join('scripts', base),
-        command: null,
-        timeout: null,
-        enabled: false, // detected entries are never auto-enabled
-        detected: true,
-        configured: false,
-        unconfigured: true,
-        present: true,
-        source: 'disk-scan',
-        description: `Detected on disk; not yet configured in the manifest (${base}).`,
-      });
-    }
-
-    return {
-      all: configured.concat(detected),
-      configured,
-      detected,
-      orphans,
-    };
-  }
-
-  /** @returns {object} alias of {@link HookLoader#autodetect} (compatibility naming). */
-  reconcile() { return this.autodetect(); }
-  /** @returns {object} alias of {@link HookLoader#autodetect}. */
-  reconcileScripts() { return this.autodetect(); }
-  /** @returns {object} alias of {@link HookLoader#autodetect}. */
-  inventory() { return this.autodetect(); }
-  /** @returns {object} alias of {@link HookLoader#autodetect}. */
-  detect() { return this.autodetect(); }
-  /** @returns {object} alias of {@link HookLoader#autodetect}. */
-  scan() { return this.autodetect(); }
-
-  /**
-   * Scan the scripts dir for candidate hook script files. Hook scripts are
-   * executable shell/node scripts; we treat .sh/.js/.cmd/.bat/.ps1/.py as hook
-   * scripts and ignore everything else (e.g. a *.conf file is config, not a
-   * hook). Missing dir -> empty set. Never throws.
-   *
-   * @returns {Set<string>} basenames of script files present on disk
-   * @private
-   */
-  _scanScripts() {
-    const out = new Set();
-    let entries;
-    try {
-      entries = fs.readdirSync(this.scriptsDir, { withFileTypes: true });
-    } catch (_) {
-      return out; // no scripts dir yet
-    }
-    for (const ent of entries) {
-      if (!ent.isFile || !ent.isFile()) continue;
-      if (HOOK_SCRIPT_EXTS.test(ent.name)) out.add(ent.name);
-    }
-    return out;
-  }
-
-  /**
-   * Toggle a hook's enabled flag and persist the manifest atomically.
-   *
-   * v2 precedence: the authoritative persisted toggle lives in the hooks.state.json
-   * OVERLAY (keyed by hook id), which WINS over the manifest's own enabled flag at
-   * load time. setEnabled writes that overlay atomically so the toggle survives a
-   * restart and stays separate from the auto-detected inventory. For backward
-   * compatibility (and so the manifest stays a faithful default), it ALSO mirrors
-   * the flag into the manifest - writing the ORIGINAL (unexpanded) command strings
-   * so the absolute ${HOOKS_DIR} expansion never leaks into the portable on-disk
-   * manifest. We re-read the raw manifest from disk to do this.
-   *
-   * If the hook is a v2 DETECTED entry (on disk, not in the manifest), there is no
-   * manifest row to mirror into - the overlay alone carries its state.
-   *
-   * @param {string} id hook id
-   * @param {boolean} bool desired enabled state
-   * @returns {boolean} true if the toggle was applied (manifest hook OR detected hook)
-   */
-  setEnabled(id, bool) {
-    const desired = !!bool;
-
-    // Update the in-memory (expanded) spec so the live engine sees the change
-    // immediately - if this id corresponds to a configured manifest hook.
-    const liveSpec = this.getSpec(id);
-    if (liveSpec) liveSpec.enabled = desired;
-
-    // (1) Mirror into the manifest when a matching row exists (keeps the manifest a
-    //     faithful default and preserves the v1 setEnabled contract). Skipped for
-    //     detected-only ids that have no manifest row.
-    let raw;
-    try {
-      raw = JSON.parse(fs.readFileSync(this.manifestPath, 'utf8'));
-    } catch (err) {
-      // If the on-disk file is unreadable, fall back to persisting a re-collapsed copy
-      // of the in-memory manifest (best effort - still atomic).
-      raw = collapseManifest(this.manifest, this.hooksDir);
-    }
-
-    let manifestRow = false;
-    if (raw && Array.isArray(raw.hooks)) {
-      const rawSpec = raw.hooks.find((h) => h && h.id === id);
-      if (rawSpec) {
-        manifestRow = true;
-        rawSpec.enabled = desired;
-        atomicWriteJson(this.manifestPath, raw);
-      }
-    }
-
-    // (2) Persist the overlay - the authoritative, precedence-winning store - ONLY for an id
-    //     that matched something. The first correction here fixed the constant-true return
-    //     (`!!liveSpec || true`) but left this write unconditional, so a typo'd id still left a
-    //     stray key in hooks.state.json forever. Strays are not inert: applyState() lays the
-    //     overlay over the manifest at every load, so a future hook adopting the id would boot
-    //     silently in the stale recorded state - a pre-disabled gate.
-    if (liveSpec || manifestRow) {
-      const overlay = this.readState();
-      overlay[id] = desired;
-      this.writeState(overlay);
-    }
-
-    // True if we toggled a known manifest hook; also true for a detected (manifest-less) hook
-    // so the manager can persist its state. An id matching NEITHER is a miss: report false,
-    // write nothing.
-    return !!liveSpec || manifestRow;
-  }
-
-  /**
-   * Add a new hook entry to the manifest AND the live in-memory engine view.
-   *
-   * Mirrors setEnabled's persistence pattern: the RAW manifest JSON is re-read from
-   * disk (so the portable ${HOOKS_DIR} token inside command strings stays UNCOLLAPSED
-   * on disk), the validated spec is appended VERBATIM, and the file is rewritten
-   * atomically (temp + rename). In ADDITION an EXPANDED copy - ${HOOKS_DIR} resolved in
-   * the command - is pushed onto this.manifest.hooks so enabledHooksFor / the live
-   * engine observe the new hook WITHOUT a reload.
-   *
-   * @param {object} spec
-   *   - id: non-empty string; must not already exist in the manifest (rejected if it does)
-   *   - event: one of the lifecycle EVENTS (EVENT_NAMES)
-   *   - command: non-empty string
-   *   - matcher: optional string; must COMPILE under matcher.js's anchoring (rejected
-   *     otherwise - an uncompilable matcher can never be evaluated)
-   *   - script/timeout/description: optional, stored verbatim
-   *   - enabled: defaults to (spec.enabled === true)
-   * @returns {object} the stored spec (exactly as written to the manifest)
-   * @throws TypeError/Error if validation fails or the id already exists
-   */
-  addEntry(spec) {
-    if (!spec || typeof spec !== 'object') {
-      throw new TypeError('addEntry: spec must be an object');
-    }
-    if (typeof spec.id !== 'string' || spec.id.length === 0) {
-      throw new Error('addEntry: spec.id must be a non-empty string');
-    }
-    if (!EVENT_NAMES.includes(spec.event)) {
-      throw new Error(
-        `addEntry: spec.event must be one of ${EVENT_NAMES.join(', ')} (got ${JSON.stringify(spec.event)})`
-      );
-    }
-    if (typeof spec.command !== 'string' || spec.command.length === 0) {
-      throw new Error('addEntry: spec.command must be a non-empty string');
-    }
-    // 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.)
-    if (spec.matcher !== undefined && spec.matcher !== null && typeof spec.matcher !== 'string') {
-      throw new Error('addEntry: spec.matcher must be a string when provided');
-    }
-    {
-      const compileProblem = matcherError(spec.matcher);
-      if (compileProblem) {
-        throw new Error(
-          `addEntry: spec.matcher ${JSON.stringify(spec.matcher)} does not compile as a ` +
-          `regular expression (${compileProblem}) - matchers are anchored regexes ` +
-          '(e.g. "Bash|Write"), not globs'
-        );
-      }
-    }
-
-    // The stored spec: every supplied field VERBATIM, with enabled normalized to a
-    // strict boolean. The command is left untouched so a portable ${HOOKS_DIR} token
-    // (if the caller used one) stays UNCOLLAPSED on disk.
-    const stored = Object.assign({}, spec, { enabled: spec.enabled === true });
-
-    // Re-read the RAW manifest from disk (commands uncollapsed). Fall back to a
-    // re-collapsed copy of the in-memory manifest if the file is unreadable - same
-    // resilience as setEnabled, and the collapse keeps ${HOOKS_DIR} uncollapsed too.
-    let raw;
-    try {
-      raw = JSON.parse(fs.readFileSync(this.manifestPath, 'utf8'));
-    } catch (_) {
-      raw = collapseManifest(this.manifest, this.hooksDir);
-    }
-    if (!raw || typeof raw !== 'object') raw = { version: this.version, hooks: [] };
-    if (!Array.isArray(raw.hooks)) raw.hooks = [];
-
-    if (raw.hooks.some((h) => h && h.id === spec.id)) {
-      throw new Error(`addEntry: a hook with id "${spec.id}" already exists`);
-    }
-
-    // Persist the spec VERBATIM, atomically.
-    raw.hooks.push(stored);
-    atomicWriteJson(this.manifestPath, raw);
-
-    // Mirror an EXPANDED copy into the live manifest so the engine sees it NOW.
-    if (!Array.isArray(this.manifest.hooks)) this.manifest.hooks = [];
-    const expanded = Object.assign({}, stored, {
-      command: expandHooksDir(stored.command, this.hooksDir),
-    });
-    this.manifest.hooks.push(expanded);
-
-    return stored;
-  }
-
-  /**
-   * Remove a hook entry by id from the manifest, the live engine view, and the
-   * persisted enabled-state overlay. Does NOT delete the script file on disk -
-   * scripts are inventory (auto-detect's source of truth); unconfiguring a hook
-   * only drops its manifest row, leaving any file for re-detection.
-   *
-   * Mirrors setEnabled's persistence pattern: re-read the RAW manifest (commands
-   * stay UNCOLLAPSED), filter out the id, and rewrite atomically ONLY if something
-   * changed. The in-memory expanded spec is spliced out so the live engine stops
-   * firing it WITHOUT a reload, and the overlay key (when present) is purged.
-   *
-   * @param {string} id hook id to remove
-   * @returns {boolean} true if a manifest row OR a live spec was removed
-   * @throws Error if id is not a non-empty string
-   */
-  removeEntry(id) {
-    if (typeof id !== 'string' || id.length === 0) {
-      throw new Error('removeEntry: id must be a non-empty string');
-    }
-
-    // (1) Re-read the RAW manifest and drop the matching row (commands uncollapsed).
-    let raw;
-    try {
-      raw = JSON.parse(fs.readFileSync(this.manifestPath, 'utf8'));
-    } catch (_) {
-      raw = collapseManifest(this.manifest, this.hooksDir);
-    }
-    let removedFromManifest = false;
-    if (raw && Array.isArray(raw.hooks)) {
-      const before = raw.hooks.length;
-      raw.hooks = raw.hooks.filter((h) => !(h && h.id === id));
-      removedFromManifest = raw.hooks.length !== before;
-      if (removedFromManifest) atomicWriteJson(this.manifestPath, raw); // write only if changed
-    }
-
-    // (2) Splice the live expanded spec(s) so the engine stops seeing it immediately.
-    let removedFromMemory = false;
-    if (Array.isArray(this.manifest.hooks)) {
-      for (let i = this.manifest.hooks.length - 1; i >= 0; i--) {
-        const h = this.manifest.hooks[i];
-        if (h && h.id === id) {
-          this.manifest.hooks.splice(i, 1);
-          removedFromMemory = true;
-        }
-      }
-    }
-
-    // (3) Purge the overlay key. Only rewrite the overlay when it actually carried
-    //     this id, so we never create a stray state file for a never-toggled hook.
-    const overlay = this.readState();
-    if (Object.prototype.hasOwnProperty.call(overlay, id)) {
-      delete overlay[id];
-      this.writeState(overlay);
-    }
-
-    return removedFromManifest || removedFromMemory;
-  }
-
-  /**
-   * Read a hook's script source. Resolves the spec's "script" (relative to hooksDir) and
-   * reads it. Falls back to deriving the path from the script basename under scripts/.
-   *
-   * @param {string} id hook id
-   * @returns {string} file contents
-   * @throws if the hook id is unknown or the file cannot be read
-   */
-  readScript(id) {
-    const spec = this.getSpec(id);
-    if (!spec) throw new Error(`readScript: unknown hook id "${id}"`);
-    const scriptPath = this._scriptPathForSpec(spec);
-    return fs.readFileSync(scriptPath, 'utf8');
-  }
-
-  /**
-   * Write a hook's script source to the COPY under src/hooks/scripts. Refuses any path that
-   * resolves outside src/hooks/scripts (defense-in-depth for the isolation rule).
-   *
-   * @param {string} id hook id
-   * @param {string} text new source
-   * @returns {void}
-   * @throws if the id is unknown, or the resolved path escapes scripts/
-   */
-  writeScript(id, text) {
-    const spec = this.getSpec(id);
-    if (!spec) throw new Error(`writeScript: unknown hook id "${id}"`);
-    if (typeof text !== 'string') {
-      throw new TypeError('writeScript: text must be a string');
-    }
-
-    const scriptPath = this._scriptPathForSpec(spec);
-    this._assertInsideScriptsDir(scriptPath);
-
-    // Atomic write within the scripts dir (temp + rename), preserving any line endings
-    // the caller supplied (do not normalize - the shell scripts may be CRLF-sensitive).
-    atomicWriteText(scriptPath, text, this.scriptsDir);
-  }
-
-  /**
-   * Resolve the absolute filesystem path for a spec's script, anchored to hooksDir, and
-   * guard it against escaping scripts/.
-   *
-   * @param {object} spec
-   * @returns {string} absolute path inside scripts/
-   * @private
-   */
-  _scriptPathForSpec(spec) {
-    let rel = spec.script;
-    if (typeof rel !== 'string' || rel.length === 0) {
-      // Fall back to deriving from the id's basename if "script" is missing.
-      rel = path.join('scripts', `${path.basename(spec.id)}`);
-    }
-    // spec.script is documented relative to hooksDir (e.g. "scripts/on-prompt.sh").
-    const resolved = path.resolve(this.hooksDir, rel);
-    this._assertInsideScriptsDir(resolved);
-    return resolved;
-  }
-
-  /**
-   * Throw unless `target` resolves strictly inside this.scriptsDir.
-   * @param {string} target absolute candidate path
-   * @private
-   */
-  _assertInsideScriptsDir(target) {
-    const resolved = path.resolve(target);
-    const base = path.resolve(this.scriptsDir);
-    // Compare with a trailing separator so "<base>extra" cannot pass as "<base>".
-    const baseWithSep = base.endsWith(path.sep) ? base : base + path.sep;
-    const isInside = resolved === base || resolved.startsWith(baseWithSep);
-    if (!isInside) {
-      throw new Error(
-        `path-traversal blocked: "${resolved}" is outside the scripts dir "${base}"`
-      );
-    }
-  }
-}
-
-/**
- * Coerce an arbitrary parsed value into a clean { id: boolean } overlay map. Accepts
- * either a flat map ({ "<id>": bool }) or a wrapped form ({ enabled: { ... } }) for
- * forward-tolerance; non-boolean values are coerced to strict booleans; non-object
- * input yields an empty overlay. Never throws.
- *
- * @param {*} raw
- * @returns {Object<string, boolean>}
- */
-function normalizeState(raw) {
-  const src =
-    raw && typeof raw === 'object' && raw.enabled && typeof raw.enabled === 'object'
-      ? raw.enabled
-      : raw;
-  const out = {};
-  if (!src || typeof src !== 'object' || Array.isArray(src)) return out;
-  for (const key of Object.keys(src)) {
-    out[key] = src[key] === true;
-  }
-  return out;
-}
-
-/**
- * The basename of a spec's script field (e.g. "scripts/on-prompt.sh" -> "on-prompt.sh").
- * Returns null for inline-command hooks (script null/empty). Tolerates either path
- * separator since manifests use forward slashes.
- *
- * @param {*} script the spec.script field
- * @returns {string|null}
- */
-function scriptBasename(script) {
-  if (typeof script !== 'string' || script.length === 0) return null;
-  const norm = script.split('\\').join('/');
-  const base = norm.slice(norm.lastIndexOf('/') + 1);
-  return base.length ? base : null;
-}
-
-/**
- * Produce a manifest object with command strings collapsed back to ${HOOKS_DIR} so the
- * on-disk form stays machine-portable. Used only as a fallback when the raw file cannot
- * be re-read during persistence.
- *
- * @param {object} manifest expanded manifest
- * @param {string} hooksDir absolute hooks dir to collapse out of command strings
- * @returns {object} a deep-enough copy with collapsed commands
- */
-function collapseManifest(manifest, hooksDir) {
-  const copy = JSON.parse(JSON.stringify(manifest));
-  if (Array.isArray(copy.hooks)) {
-    for (const h of copy.hooks) {
-      if (h && typeof h.command === 'string' && hooksDir) {
-        h.command = h.command.split(hooksDir).join('${HOOKS_DIR}');
-      }
-    }
-  }
-  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;
-  }
-}
-
-/**
- * Load a manifest from disk, expand ${HOOKS_DIR} in every command string, and return a
- * HookLoader holding it.
- *
- * @param {string} manifestPath absolute path to hooks.manifest.json
- * @returns {HookLoader}
- */
-function loadManifest(manifestPath) {
-  if (typeof manifestPath !== 'string' || manifestPath.length === 0) {
-    throw new TypeError('loadManifest: manifestPath must be a non-empty string');
-  }
-  const absManifest = path.resolve(manifestPath);
-  const raw = JSON.parse(fs.readFileSync(absManifest, 'utf8'));
-
-  const hooksDir = resolveHooksDir(absManifest, raw && raw.hooksDir);
-
-  // Build the expanded manifest (do not mutate the raw parse beyond this copy).
-  const expanded = {
-    version: raw && raw.version,
-    hooksDir, // store the resolved ABSOLUTE hooks dir for downstream consumers
-    hooks: [],
-  };
-
-  const srcHooks = (raw && Array.isArray(raw.hooks)) ? raw.hooks : [];
-  for (const h of srcHooks) {
-    if (!h || typeof h !== 'object') continue;
-    const spec = Object.assign({}, h);
-    // Expand ${HOOKS_DIR} inside the command (and, defensively, any string field that
-    // might reference it - but command is the documented carrier).
-    if (typeof spec.command === 'string') {
-      spec.command = expandHooksDir(spec.command, hooksDir);
-    }
-    // Normalize enabled to a strict boolean (manifest authors may omit it).
-    spec.enabled = spec.enabled === true;
-    expanded.hooks.push(spec);
-  }
-
-  const loader = new HookLoader(absManifest, expanded, hooksDir);
-  // v2: apply the persisted enabled-state overlay OVER the manifest flags so the
-  // returned loader (and enabledHooksFor) reflects the durable toggles. The overlay
-  // wins; absent/unreadable overlay leaves the manifest defaults intact.
-  loader.applyStateOverlay();
-  return loader;
-}
-
-/**
- * Tiny inline self-check: add then remove a temp entry and confirm it round-trips
- * with the manifest byte-for-byte RESTORED. Runs only under `node hook-loader.js`
- * (never on import) and uses a THROWAWAY manifest in the OS temp dir, so the live
- * project manifest is never touched. Exits non-zero on any failure.
- */
-function _selfCheck() {
-  const os = require('node:os');
-  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'hookloader-selfcheck-'));
-  const manifestPath = path.join(tmpRoot, 'hooks.manifest.json');
-  const assert = (cond, msg) => { if (!cond) throw new Error('self-check FAILED: ' + msg); };
-  try {
-    // A manifest whose command uses the ${HOOKS_DIR} token, so we can prove it stays
-    // UNCOLLAPSED on disk while being EXPANDED in the live view.
-    const original =
-      JSON.stringify(
-        { version: 1, hooks: [{ id: 'existing', event: 'PreToolUse', command: '${HOOKS_DIR}/scripts/x.sh', enabled: true }] },
-        null,
-        2
-      ) + '\n';
-    fs.writeFileSync(manifestPath, original);
-
-    const loader = loadManifest(manifestPath);
-    const tmpSpec = { id: 'selfcheck/tmp', event: 'PostToolUse', command: '${HOOKS_DIR}/scripts/tmp.sh' };
-
-    const stored = loader.addEntry(tmpSpec);
-    assert(stored.enabled === false, 'enabled should default to false');
-    // On disk: VERBATIM, token uncollapsed.
-    const afterAdd = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
-    const diskRow = afterAdd.hooks.find((h) => h.id === 'selfcheck/tmp');
-    assert(!!diskRow, 'temp entry must be persisted to the manifest');
-    assert(diskRow.command === '${HOOKS_DIR}/scripts/tmp.sh', 'on-disk command must keep ${HOOKS_DIR} uncollapsed');
-    // Live: EXPANDED so the engine sees it without reload.
-    const liveRow = loader.getSpec('selfcheck/tmp');
-    assert(!!liveRow, 'temp entry must be live in this.manifest.hooks');
-    assert(liveRow.command === path.join(loader.hooksDir, 'scripts/tmp.sh') ||
-           liveRow.command === loader.hooksDir + '/scripts/tmp.sh',
-           'live command must be expanded: ' + liveRow.command);
-
-    // Duplicate id must be rejected.
-    let threw = false;
-    try { loader.addEntry(tmpSpec); } catch (_) { threw = true; }
-    assert(threw, 'adding a duplicate id must throw');
-
-    const removed = loader.removeEntry('selfcheck/tmp');
-    assert(removed === true, 'removeEntry should report a removal');
-    assert(!loader.getSpec('selfcheck/tmp'), 'temp entry must be gone from the live view');
-
-    // Manifest must be RESTORED byte-for-byte (the only other row is "existing").
-    const afterRemove = fs.readFileSync(manifestPath, 'utf8');
-    assert(afterRemove === original, 'manifest must be restored byte-for-byte after add+remove');
-
-    process.stdout.write('hook-loader self-check OK (add+remove round-trip; manifest restored)\n');
-  } finally {
-    try { fs.rmSync(tmpRoot, { recursive: true, force: true }); } catch (_) { /* ignore */ }
-  }
-}
-
-if (require.main === module) {
-  try {
-    _selfCheck();
-  } catch (err) {
-    process.stderr.write(((err && err.stack) || String(err)) + '\n');
-    process.exit(1);
-  }
-}
-
-module.exports = {
-  loadManifest,
-  HookLoader,
-  // Exported for unit tests / reuse:
-  expandHooksDir,
-  resolveHooksDir,
-  normalizeState,
-  scriptBasename,
-};
+'use strict';
+
+/**
+ * hook-loader.js - load and persist the hook manifest, resolve runnable specs.
+ *
+ * Contract: the manifest shape and the loader API are both specified below.
+ *
+ * Responsibilities:
+ *   - loadManifest(path): read hooks.manifest.json, expand ${HOOKS_DIR} (the absolute
+ *     src/hooks dir) inside every command string, return { version, hooksDir, hooks: Spec[] }.
+ *   - enabledHooksFor(event): the enabled specs for a lifecycle event.
+ *   - setEnabled(id, bool): flip a hook's enabled flag and persist ATOMICALLY (temp + rename).
+ *   - readScript(id): the hook's source text (for the manager's "open").
+ *   - writeScript(id, text): save to the COPY under src/hooks/scripts - and REFUSE any
+ *     resolved path outside src/hooks/scripts (path-traversal guard, isolation rule).
+ *
+ * Hook Manager v2 additions - all ADDITIVE; the API above
+ * keeps its exact behaviour so the existing loader tests still pass:
+ *   - AUTO-DETECT: autodetect() scans <hooksDir>/scripts for hook scripts and reconciles
+ *     them with the manifest. The FOLDER is the source of truth for what EXISTS; the
+ *     manifest is CONFIG. Scripts on disk with no manifest entry surface as detected
+ *     entries (enabled:false, detected:true, event/matcher unknown). Manifest entries
+ *     whose script is missing on disk are flagged (present:false). Aliased as
+ *     detect/reconcile/scan/inventory/reconcileScripts.
+ *   - PERSIST STATE: enabled-state lives in <hooksDir>/hooks.state.json, an overlay keyed
+ *     by hook id ({ "<id>": bool }). On load it is applied OVER the manifest's enabled
+ *     flags (overlay WINS - documented precedence). setEnabled writes the overlay
+ *     atomically (temp+rename) IN ADDITION to mutating the manifest, so toggles survive
+ *     restarts and stay separate from the inventory.
+ *
+ * CommonJS only. Node built-ins only.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// Lifecycle event names (frozen) - used to validate addEntry specs against the
+// six supported events. events.js has zero host imports, so this cannot cycle.
+const { EVENT_NAMES } = require('./events');
+
+// The matcher-compile discriminator - addEntry refuses a matcher that can never be
+// evaluated (matcher.js has zero host imports, so this cannot cycle either).
+const { matcherError } = require('./matcher');
+
+/**
+ * Extensions we treat as hook scripts during auto-detect. Everything else in the
+ * scripts dir (e.g. *.conf files, READMEs) is config/data, not a hook.
+ */
+const HOOK_SCRIPT_EXTS = /\.(sh|js|cjs|mjs|cmd|bat|ps1|py)$/i;
+
+/**
+ * Resolve the absolute src/hooks directory from the manifest's own location and its
+ * declared (possibly relative) hooksDir. The manifest lives at <hooks>/hooks.manifest.json,
+ * so its directory IS the hooks dir; we honor an explicit absolute hooksDir if given but
+ * otherwise anchor to the manifest file's location (robust against cwd differences).
+ *
+ * @param {string} manifestPath absolute path to hooks.manifest.json
+ * @param {string|undefined} declaredHooksDir the manifest's "hooksDir" field
+ * @returns {string} absolute path to the hooks directory
+ */
+function resolveHooksDir(manifestPath, declaredHooksDir) {
+  const manifestDir = path.dirname(path.resolve(manifestPath));
+  if (!declaredHooksDir) return manifestDir;
+  if (path.isAbsolute(declaredHooksDir)) return path.resolve(declaredHooksDir);
+  // Relative hooksDir is interpreted relative to the manifest's directory's parent only
+  // when it does not simply re-point at the manifest dir; in practice the manifest sits
+  // inside the hooks dir, so the manifest directory is the source of truth.
+  return manifestDir;
+}
+
+/**
+ * Expand ${HOOKS_DIR} occurrences in a string with the absolute hooks dir.
+ * Defensive: returns the input unchanged for non-strings.
+ *
+ * @param {string} str
+ * @param {string} hooksDir absolute hooks directory
+ * @returns {string}
+ */
+function expandHooksDir(str, hooksDir) {
+  if (typeof str !== 'string') return str;
+  // Replace every literal occurrence of ${HOOKS_DIR}. We avoid regex special-char issues
+  // by using split/join on the literal token.
+  return str.split('${HOOKS_DIR}').join(hooksDir);
+}
+
+class HookLoader {
+  /**
+   * @param {string} manifestPath absolute path to hooks.manifest.json
+   * @param {object} manifest the parsed + expanded manifest object
+   * @param {string} hooksDir absolute hooks directory
+   */
+  constructor(manifestPath, manifest, hooksDir) {
+    this.manifestPath = manifestPath;
+    this.manifest = manifest;
+    this.hooksDir = hooksDir;
+    // The scripts copy directory - the ONLY place writeScript may touch.
+    this.scriptsDir = path.join(hooksDir, 'scripts');
+    // v2: the persisted enabled-state overlay (keyed by hook id), kept separate
+    // from the manifest inventory. Lives next to the manifest in the hooks dir.
+    this.statePath = path.join(hooksDir, 'hooks.state.json');
+  }
+
+  /** @returns {number} manifest schema version */
+  get version() {
+    return this.manifest && this.manifest.version;
+  }
+
+  /** @returns {Array<object>} all hook specs (expanded) */
+  get hooks() {
+    return (this.manifest && Array.isArray(this.manifest.hooks)) ? this.manifest.hooks : [];
+  }
+
+  /**
+   * Enabled specs for a given lifecycle event, in manifest order.
+   * @param {string} event one of EVENTS
+   * @returns {Array<object>}
+   */
+  enabledHooksFor(event) {
+    return this.hooks.filter((h) => h && h.event === event && h.enabled === true);
+  }
+
+  /**
+   * Look up a single spec by id.
+   * @param {string} id
+   * @returns {object|undefined}
+   */
+  getSpec(id) {
+    return this.hooks.find((h) => h && h.id === id);
+  }
+
+  // ── v2: persisted enabled-state overlay ──────────────────────────────────
+
+  /**
+   * Read the enabled-state overlay from hooks.state.json. The overlay is a flat
+   * map of hook id -> boolean. Missing/unreadable/malformed file -> empty overlay
+   * (the manifest's own enabled flags stand). Never throws.
+   *
+   * @returns {Object<string, boolean>}
+   */
+  readState() {
+    let raw;
+    try {
+      raw = JSON.parse(fs.readFileSync(this.statePath, 'utf8'));
+    } catch (_) {
+      return {};
+    }
+    return normalizeState(raw);
+  }
+
+  /**
+   * Persist the enabled-state overlay atomically (temp + rename). Confined to the
+   * hooks dir. The overlay carries ONLY booleans keyed by hook id.
+   *
+   * @param {Object<string, boolean>} overlay
+   * @returns {void}
+   */
+  writeState(overlay) {
+    const clean = normalizeState(overlay);
+    atomicWriteJson(this.statePath, clean);
+  }
+
+  /**
+   * Apply the on-disk state overlay over the in-memory manifest specs. The overlay
+   * WINS over the manifest's own enabled flag (documented precedence). Called on
+   * load so enabledHooksFor reflects the persisted toggles. Idempotent.
+   *
+   * @returns {Object<string, boolean>} the overlay that was applied
+   */
+  applyStateOverlay() {
+    const overlay = this.readState();
+    for (const h of this.hooks) {
+      if (!h || typeof h.id !== 'string') continue;
+      if (Object.prototype.hasOwnProperty.call(overlay, h.id)) {
+        h.enabled = overlay[h.id] === true;
+      }
+    }
+    return overlay;
+  }
+
+  // ── v2: auto-detect / reconcile inventory ────────────────────────────────
+
+  /**
+   * Scan <hooksDir>/scripts for hook scripts and reconcile with the manifest.
+   *
+   * The FOLDER is the source of truth for what EXISTS; the manifest is CONFIG.
+   *   - Manifest entries are returned with `present` reflecting whether their
+   *     `script` file exists on disk (manifest entries with no script - inline
+   *     commands - are treated as present:true, since there is no file to miss).
+   *   - Scripts present on disk but absent from the manifest are surfaced as
+   *     `detected` entries: enabled:false, detected:true, event/matcher unknown.
+   *
+   * Returns a normalised inventory. `all` is the union (configured first, in
+   * manifest order, then detected). Pure read - does not mutate the manifest or
+   * touch disk beyond reading the scripts dir.
+   *
+   * @returns {{ all: object[], configured: object[], detected: object[], orphans: object[] }}
+   */
+  autodetect() {
+    const scriptFiles = this._scanScripts(); // Set of basenames present on disk
+    const referenced = new Set();
+
+    const configured = [];
+    const orphans = [];
+
+    for (const h of this.hooks) {
+      if (!h || typeof h !== 'object') continue;
+      const base = scriptBasename(h.script);
+      if (base) referenced.add(base);
+
+      // Inline-command hooks (script:null) have no file to verify -> present.
+      const present = base ? scriptFiles.has(base) : true;
+      const entry = Object.assign({}, h, {
+        detected: false,
+        configured: true,
+        present,
+      });
+      if (!present) {
+        // Orphan: manifest references a script that does not exist on disk.
+        entry.missing = true;
+        entry.scriptMissing = true;
+        entry.exists = false;
+        entry.status = 'missing';
+        orphans.push(entry);
+      }
+      configured.push(entry);
+    }
+
+    // Scripts on disk with no manifest entry -> detected, unconfigured.
+    const detected = [];
+    for (const base of scriptFiles) {
+      if (referenced.has(base)) continue;
+      detected.push({
+        id: `detected/${base.replace(/\.[^.]+$/, '')}`,
+        event: null, // unknown - not yet configured
+        matcher: null,
+        type: 'command',
+        script: path.posix.join('scripts', base),
+        command: null,
+        timeout: null,
+        enabled: false, // detected entries are never auto-enabled
+        detected: true,
+        configured: false,
+        unconfigured: true,
+        present: true,
+        source: 'disk-scan',
+        description: `Detected on disk; not yet configured in the manifest (${base}).`,
+      });
+    }
+
+    return {
+      all: configured.concat(detected),
+      configured,
+      detected,
+      orphans,
+    };
+  }
+
+  /** @returns {object} alias of {@link HookLoader#autodetect} (compatibility naming). */
+  reconcile() { return this.autodetect(); }
+  /** @returns {object} alias of {@link HookLoader#autodetect}. */
+  reconcileScripts() { return this.autodetect(); }
+  /** @returns {object} alias of {@link HookLoader#autodetect}. */
+  inventory() { return this.autodetect(); }
+  /** @returns {object} alias of {@link HookLoader#autodetect}. */
+  detect() { return this.autodetect(); }
+  /** @returns {object} alias of {@link HookLoader#autodetect}. */
+  scan() { return this.autodetect(); }
+
+  /**
+   * Scan the scripts dir for candidate hook script files. Hook scripts are
+   * executable shell/node scripts; we treat .sh/.js/.cmd/.bat/.ps1/.py as hook
+   * scripts and ignore everything else (e.g. a *.conf file is config, not a
+   * hook). Missing dir -> empty set. Never throws.
+   *
+   * @returns {Set<string>} basenames of script files present on disk
+   * @private
+   */
+  _scanScripts() {
+    const out = new Set();
+    let entries;
+    try {
+      entries = fs.readdirSync(this.scriptsDir, { withFileTypes: true });
+    } catch (_) {
+      return out; // no scripts dir yet
+    }
+    for (const ent of entries) {
+      if (!ent.isFile || !ent.isFile()) continue;
+      if (HOOK_SCRIPT_EXTS.test(ent.name)) out.add(ent.name);
+    }
+    return out;
+  }
+
+  /**
+   * Toggle a hook's enabled flag and persist the manifest atomically.
+   *
+   * v2 precedence: the authoritative persisted toggle lives in the hooks.state.json
+   * OVERLAY (keyed by hook id), which WINS over the manifest's own enabled flag at
+   * load time. setEnabled writes that overlay atomically so the toggle survives a
+   * restart and stays separate from the auto-detected inventory. For backward
+   * compatibility (and so the manifest stays a faithful default), it ALSO mirrors
+   * the flag into the manifest - writing the ORIGINAL (unexpanded) command strings
+   * so the absolute ${HOOKS_DIR} expansion never leaks into the portable on-disk
+   * manifest. We re-read the raw manifest from disk to do this.
+   *
+   * If the hook is a v2 DETECTED entry (on disk, not in the manifest), there is no
+   * manifest row to mirror into - the overlay alone carries its state.
+   *
+   * @param {string} id hook id
+   * @param {boolean} bool desired enabled state
+   * @returns {boolean} true if the toggle was applied (manifest hook OR detected hook)
+   */
+  setEnabled(id, bool) {
+    const desired = !!bool;
+
+    // Update the in-memory (expanded) spec so the live engine sees the change
+    // immediately - if this id corresponds to a configured manifest hook.
+    const liveSpec = this.getSpec(id);
+    if (liveSpec) liveSpec.enabled = desired;
+
+    // (1) Mirror into the manifest when a matching row exists (keeps the manifest a
+    //     faithful default and preserves the v1 setEnabled contract). Skipped for
+    //     detected-only ids that have no manifest row.
+    let raw;
+    try {
+      raw = JSON.parse(fs.readFileSync(this.manifestPath, 'utf8'));
+    } catch (err) {
+      // If the on-disk file is unreadable, fall back to persisting a re-collapsed copy
+      // of the in-memory manifest (best effort - still atomic).
+      raw = collapseManifest(this.manifest, this.hooksDir);
+    }
+
+    let manifestRow = false;
+    if (raw && Array.isArray(raw.hooks)) {
+      const rawSpec = raw.hooks.find((h) => h && h.id === id);
+      if (rawSpec) {
+        manifestRow = true;
+        rawSpec.enabled = desired;
+        atomicWriteJson(this.manifestPath, raw);
+      }
+    }
+
+    // (2) Persist the overlay - the authoritative, precedence-winning store - ONLY for an id
+    //     that matched something. The first correction here fixed the constant-true return
+    //     (`!!liveSpec || true`) but left this write unconditional, so a typo'd id still left a
+    //     stray key in hooks.state.json forever. Strays are not inert: applyState() lays the
+    //     overlay over the manifest at every load, so a future hook adopting the id would boot
+    //     silently in the stale recorded state - a pre-disabled gate.
+    if (liveSpec || manifestRow) {
+      const overlay = this.readState();
+      overlay[id] = desired;
+      this.writeState(overlay);
+    }
+
+    // True if we toggled a known manifest hook; also true for a detected (manifest-less) hook
+    // so the manager can persist its state. An id matching NEITHER is a miss: report false,
+    // write nothing.
+    return !!liveSpec || manifestRow;
+  }
+
+  /**
+   * Add a new hook entry to the manifest AND the live in-memory engine view.
+   *
+   * Mirrors setEnabled's persistence pattern: the RAW manifest JSON is re-read from
+   * disk (so the portable ${HOOKS_DIR} token inside command strings stays UNCOLLAPSED
+   * on disk), the validated spec is appended VERBATIM, and the file is rewritten
+   * atomically (temp + rename). In ADDITION an EXPANDED copy - ${HOOKS_DIR} resolved in
+   * the command - is pushed onto this.manifest.hooks so enabledHooksFor / the live
+   * engine observe the new hook WITHOUT a reload.
+   *
+   * @param {object} spec
+   *   - id: non-empty string; must not already exist in the manifest (rejected if it does)
+   *   - event: one of the lifecycle EVENTS (EVENT_NAMES)
+   *   - command: non-empty string
+   *   - matcher: optional string; must COMPILE under matcher.js's anchoring (rejected
+   *     otherwise - an uncompilable matcher can never be evaluated)
+   *   - script/timeout/description: optional, stored verbatim
+   *   - enabled: defaults to (spec.enabled === true)
+   * @returns {object} the stored spec (exactly as written to the manifest)
+   * @throws TypeError/Error if validation fails or the id already exists
+   */
+  addEntry(spec) {
+    if (!spec || typeof spec !== 'object') {
+      throw new TypeError('addEntry: spec must be an object');
+    }
+    if (typeof spec.id !== 'string' || spec.id.length === 0) {
+      throw new Error('addEntry: spec.id must be a non-empty string');
+    }
+    if (!EVENT_NAMES.includes(spec.event)) {
+      throw new Error(
+        `addEntry: spec.event must be one of ${EVENT_NAMES.join(', ')} (got ${JSON.stringify(spec.event)})`
+      );
+    }
+    if (typeof spec.command !== 'string' || spec.command.length === 0) {
+      throw new Error('addEntry: spec.command must be a non-empty string');
+    }
+    // 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.)
+    if (spec.matcher !== undefined && spec.matcher !== null && typeof spec.matcher !== 'string') {
+      throw new Error('addEntry: spec.matcher must be a string when provided');
+    }
+    {
+      const compileProblem = matcherError(spec.matcher);
+      if (compileProblem) {
+        throw new Error(
+          `addEntry: spec.matcher ${JSON.stringify(spec.matcher)} does not compile as a ` +
+          `regular expression (${compileProblem}) - matchers are anchored regexes ` +
+          '(e.g. "Bash|Write"), not globs'
+        );
+      }
+    }
+
+    // The stored spec: every supplied field VERBATIM, with enabled normalized to a
+    // strict boolean. The command is left untouched so a portable ${HOOKS_DIR} token
+    // (if the caller used one) stays UNCOLLAPSED on disk.
+    const stored = Object.assign({}, spec, { enabled: spec.enabled === true });
+
+    // Re-read the RAW manifest from disk (commands uncollapsed). Fall back to a
+    // re-collapsed copy of the in-memory manifest if the file is unreadable - same
+    // resilience as setEnabled, and the collapse keeps ${HOOKS_DIR} uncollapsed too.
+    let raw;
+    try {
+      raw = JSON.parse(fs.readFileSync(this.manifestPath, 'utf8'));
+    } catch (_) {
+      raw = collapseManifest(this.manifest, this.hooksDir);
+    }
+    if (!raw || typeof raw !== 'object') raw = { version: this.version, hooks: [] };
+    if (!Array.isArray(raw.hooks)) raw.hooks = [];
+
+    if (raw.hooks.some((h) => h && h.id === spec.id)) {
+      throw new Error(`addEntry: a hook with id "${spec.id}" already exists`);
+    }
+
+    // Persist the spec VERBATIM, atomically.
+    raw.hooks.push(stored);
+    atomicWriteJson(this.manifestPath, raw);
+
+    // Mirror an EXPANDED copy into the live manifest so the engine sees it NOW.
+    if (!Array.isArray(this.manifest.hooks)) this.manifest.hooks = [];
+    const expanded = Object.assign({}, stored, {
+      command: expandHooksDir(stored.command, this.hooksDir),
+    });
+    this.manifest.hooks.push(expanded);
+
+    return stored;
+  }
+
+  /**
+   * Remove a hook entry by id from the manifest, the live engine view, and the
+   * persisted enabled-state overlay. Does NOT delete the script file on disk -
+   * scripts are inventory (auto-detect's source of truth); unconfiguring a hook
+   * only drops its manifest row, leaving any file for re-detection.
+   *
+   * Mirrors setEnabled's persistence pattern: re-read the RAW manifest (commands
+   * stay UNCOLLAPSED), filter out the id, and rewrite atomically ONLY if something
+   * changed. The in-memory expanded spec is spliced out so the live engine stops
+   * firing it WITHOUT a reload, and the overlay key (when present) is purged.
+   *
+   * @param {string} id hook id to remove
+   * @returns {boolean} true if a manifest row OR a live spec was removed
+   * @throws Error if id is not a non-empty string
+   */
+  removeEntry(id) {
+    if (typeof id !== 'string' || id.length === 0) {
+      throw new Error('removeEntry: id must be a non-empty string');
+    }
+
+    // (1) Re-read the RAW manifest and drop the matching row (commands uncollapsed).
+    let raw;
+    try {
+      raw = JSON.parse(fs.readFileSync(this.manifestPath, 'utf8'));
+    } catch (_) {
+      raw = collapseManifest(this.manifest, this.hooksDir);
+    }
+    let removedFromManifest = false;
+    if (raw && Array.isArray(raw.hooks)) {
+      const before = raw.hooks.length;
+      raw.hooks = raw.hooks.filter((h) => !(h && h.id === id));
+      removedFromManifest = raw.hooks.length !== before;
+      if (removedFromManifest) atomicWriteJson(this.manifestPath, raw); // write only if changed
+    }
+
+    // (2) Splice the live expanded spec(s) so the engine stops seeing it immediately.
+    let removedFromMemory = false;
+    if (Array.isArray(this.manifest.hooks)) {
+      for (let i = this.manifest.hooks.length - 1; i >= 0; i--) {
+        const h = this.manifest.hooks[i];
+        if (h && h.id === id) {
+          this.manifest.hooks.splice(i, 1);
+          removedFromMemory = true;
+        }
+      }
+    }
+
+    // (3) Purge the overlay key. Only rewrite the overlay when it actually carried
+    //     this id, so we never create a stray state file for a never-toggled hook.
+    const overlay = this.readState();
+    if (Object.prototype.hasOwnProperty.call(overlay, id)) {
+      delete overlay[id];
+      this.writeState(overlay);
+    }
+
+    return removedFromManifest || removedFromMemory;
+  }
+
+  /**
+   * Read a hook's script source. Resolves the spec's "script" (relative to hooksDir) and
+   * reads it. Falls back to deriving the path from the script basename under scripts/.
+   *
+   * @param {string} id hook id
+   * @returns {string} file contents
+   * @throws if the hook id is unknown or the file cannot be read
+   */
+  readScript(id) {
+    const spec = this.getSpec(id);
+    if (!spec) throw new Error(`readScript: unknown hook id "${id}"`);
+    const scriptPath = this._scriptPathForSpec(spec);
+    return fs.readFileSync(scriptPath, 'utf8');
+  }
+
+  /**
+   * Write a hook's script source to the COPY under src/hooks/scripts. Refuses any path that
+   * resolves outside src/hooks/scripts (defense-in-depth for the isolation rule).
+   *
+   * @param {string} id hook id
+   * @param {string} text new source
+   * @returns {void}
+   * @throws if the id is unknown, or the resolved path escapes scripts/
+   */
+  writeScript(id, text) {
+    const spec = this.getSpec(id);
+    if (!spec) throw new Error(`writeScript: unknown hook id "${id}"`);
+    if (typeof text !== 'string') {
+      throw new TypeError('writeScript: text must be a string');
+    }
+
+    const scriptPath = this._scriptPathForSpec(spec);
+    this._assertInsideScriptsDir(scriptPath);
+
+    // Atomic write within the scripts dir (temp + rename), preserving any line endings
+    // the caller supplied (do not normalize - the shell scripts may be CRLF-sensitive).
+    atomicWriteText(scriptPath, text, this.scriptsDir);
+  }
+
+  /**
+   * Resolve the absolute filesystem path for a spec's script, anchored to hooksDir, and
+   * guard it against escaping scripts/.
+   *
+   * @param {object} spec
+   * @returns {string} absolute path inside scripts/
+   * @private
+   */
+  _scriptPathForSpec(spec) {
+    let rel = spec.script;
+    if (typeof rel !== 'string' || rel.length === 0) {
+      // Fall back to deriving from the id's basename if "script" is missing.
+      rel = path.join('scripts', `${path.basename(spec.id)}`);
+    }
+    // spec.script is documented relative to hooksDir (e.g. "scripts/on-prompt.sh").
+    const resolved = path.resolve(this.hooksDir, rel);
+    this._assertInsideScriptsDir(resolved);
+    return resolved;
+  }
+
+  /**
+   * Throw unless `target` resolves strictly inside this.scriptsDir.
+   * @param {string} target absolute candidate path
+   * @private
+   */
+  _assertInsideScriptsDir(target) {
+    const resolved = path.resolve(target);
+    const base = path.resolve(this.scriptsDir);
+    // Compare with a trailing separator so "<base>extra" cannot pass as "<base>".
+    const baseWithSep = base.endsWith(path.sep) ? base : base + path.sep;
+    const isInside = resolved === base || resolved.startsWith(baseWithSep);
+    if (!isInside) {
+      throw new Error(
+        `path-traversal blocked: "${resolved}" is outside the scripts dir "${base}"`
+      );
+    }
+  }
+}
+
+/**
+ * Coerce an arbitrary parsed value into a clean { id: boolean } overlay map. Accepts
+ * either a flat map ({ "<id>": bool }) or a wrapped form ({ enabled: { ... } }) for
+ * forward-tolerance; non-boolean values are coerced to strict booleans; non-object
+ * input yields an empty overlay. Never throws.
+ *
+ * @param {*} raw
+ * @returns {Object<string, boolean>}
+ */
+function normalizeState(raw) {
+  const src =
+    raw && typeof raw === 'object' && raw.enabled && typeof raw.enabled === 'object'
+      ? raw.enabled
+      : raw;
+  const out = {};
+  if (!src || typeof src !== 'object' || Array.isArray(src)) return out;
+  for (const key of Object.keys(src)) {
+    out[key] = src[key] === true;
+  }
+  return out;
+}
+
+/**
+ * The basename of a spec's script field (e.g. "scripts/on-prompt.sh" -> "on-prompt.sh").
+ * Returns null for inline-command hooks (script null/empty). Tolerates either path
+ * separator since manifests use forward slashes.
+ *
+ * @param {*} script the spec.script field
+ * @returns {string|null}
+ */
+function scriptBasename(script) {
+  if (typeof script !== 'string' || script.length === 0) return null;
+  const norm = script.split('\\').join('/');
+  const base = norm.slice(norm.lastIndexOf('/') + 1);
+  return base.length ? base : null;
+}
+
+/**
+ * Produce a manifest object with command strings collapsed back to ${HOOKS_DIR} so the
+ * on-disk form stays machine-portable. Used only as a fallback when the raw file cannot
+ * be re-read during persistence.
+ *
+ * @param {object} manifest expanded manifest
+ * @param {string} hooksDir absolute hooks dir to collapse out of command strings
+ * @returns {object} a deep-enough copy with collapsed commands
+ */
+function collapseManifest(manifest, hooksDir) {
+  const copy = JSON.parse(JSON.stringify(manifest));
+  if (Array.isArray(copy.hooks)) {
+    for (const h of copy.hooks) {
+      if (h && typeof h.command === 'string' && hooksDir) {
+        h.command = h.command.split(hooksDir).join('${HOOKS_DIR}');
+      }
+    }
+  }
+  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;
+  }
+}
+
+/**
+ * Load a manifest from disk, expand ${HOOKS_DIR} in every command string, and return a
+ * HookLoader holding it.
+ *
+ * @param {string} manifestPath absolute path to hooks.manifest.json
+ * @returns {HookLoader}
+ */
+function loadManifest(manifestPath) {
+  if (typeof manifestPath !== 'string' || manifestPath.length === 0) {
+    throw new TypeError('loadManifest: manifestPath must be a non-empty string');
+  }
+  const absManifest = path.resolve(manifestPath);
+  const raw = JSON.parse(fs.readFileSync(absManifest, 'utf8'));
+
+  const hooksDir = resolveHooksDir(absManifest, raw && raw.hooksDir);
+
+  // Build the expanded manifest (do not mutate the raw parse beyond this copy).
+  const expanded = {
+    version: raw && raw.version,
+    hooksDir, // store the resolved ABSOLUTE hooks dir for downstream consumers
+    hooks: [],
+  };
+
+  const srcHooks = (raw && Array.isArray(raw.hooks)) ? raw.hooks : [];
+  for (const h of srcHooks) {
+    if (!h || typeof h !== 'object') continue;
+    const spec = Object.assign({}, h);
+    // Expand ${HOOKS_DIR} inside the command (and, defensively, any string field that
+    // might reference it - but command is the documented carrier).
+    if (typeof spec.command === 'string') {
+      spec.command = expandHooksDir(spec.command, hooksDir);
+    }
+    // Normalize enabled to a strict boolean (manifest authors may omit it).
+    spec.enabled = spec.enabled === true;
+    expanded.hooks.push(spec);
+  }
+
+  const loader = new HookLoader(absManifest, expanded, hooksDir);
+  // v2: apply the persisted enabled-state overlay OVER the manifest flags so the
+  // returned loader (and enabledHooksFor) reflects the durable toggles. The overlay
+  // wins; absent/unreadable overlay leaves the manifest defaults intact.
+  loader.applyStateOverlay();
+  return loader;
+}
+
+/**
+ * Tiny inline self-check: add then remove a temp entry and confirm it round-trips
+ * with the manifest byte-for-byte RESTORED. Runs only under `node hook-loader.js`
+ * (never on import) and uses a THROWAWAY manifest in the OS temp dir, so the live
+ * project manifest is never touched. Exits non-zero on any failure.
+ */
+function _selfCheck() {
+  const os = require('node:os');
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'hookloader-selfcheck-'));
+  const manifestPath = path.join(tmpRoot, 'hooks.manifest.json');
+  const assert = (cond, msg) => { if (!cond) throw new Error('self-check FAILED: ' + msg); };
+  try {
+    // A manifest whose command uses the ${HOOKS_DIR} token, so we can prove it stays
+    // UNCOLLAPSED on disk while being EXPANDED in the live view.
+    const original =
+      JSON.stringify(
+        { version: 1, hooks: [{ id: 'existing', event: 'PreToolUse', command: '${HOOKS_DIR}/scripts/x.sh', enabled: true }] },
+        null,
+        2
+      ) + '\n';
+    fs.writeFileSync(manifestPath, original);
+
+    const loader = loadManifest(manifestPath);
+    const tmpSpec = { id: 'selfcheck/tmp', event: 'PostToolUse', command: '${HOOKS_DIR}/scripts/tmp.sh' };
+
+    const stored = loader.addEntry(tmpSpec);
+    assert(stored.enabled === false, 'enabled should default to false');
+    // On disk: VERBATIM, token uncollapsed.
+    const afterAdd = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    const diskRow = afterAdd.hooks.find((h) => h.id === 'selfcheck/tmp');
+    assert(!!diskRow, 'temp entry must be persisted to the manifest');
+    assert(diskRow.command === '${HOOKS_DIR}/scripts/tmp.sh', 'on-disk command must keep ${HOOKS_DIR} uncollapsed');
+    // Live: EXPANDED so the engine sees it without reload.
+    const liveRow = loader.getSpec('selfcheck/tmp');
+    assert(!!liveRow, 'temp entry must be live in this.manifest.hooks');
+    assert(liveRow.command === path.join(loader.hooksDir, 'scripts/tmp.sh') ||
+           liveRow.command === loader.hooksDir + '/scripts/tmp.sh',
+           'live command must be expanded: ' + liveRow.command);
+
+    // Duplicate id must be rejected.
+    let threw = false;
+    try { loader.addEntry(tmpSpec); } catch (_) { threw = true; }
+    assert(threw, 'adding a duplicate id must throw');
+
+    const removed = loader.removeEntry('selfcheck/tmp');
+    assert(removed === true, 'removeEntry should report a removal');
+    assert(!loader.getSpec('selfcheck/tmp'), 'temp entry must be gone from the live view');
+
+    // Manifest must be RESTORED byte-for-byte (the only other row is "existing").
+    const afterRemove = fs.readFileSync(manifestPath, 'utf8');
+    assert(afterRemove === original, 'manifest must be restored byte-for-byte after add+remove');
+
+    process.stdout.write('hook-loader self-check OK (add+remove round-trip; manifest restored)\n');
+  } finally {
+    try { fs.rmSync(tmpRoot, { recursive: true, force: true }); } catch (_) { /* ignore */ }
+  }
+}
+
+if (require.main === module) {
+  try {
+    _selfCheck();
+  } catch (err) {
+    process.stderr.write(((err && err.stack) || String(err)) + '\n');
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  loadManifest,
+  HookLoader,
+  // Exported for unit tests / reuse:
+  expandHooksDir,
+  resolveHooksDir,
+  normalizeState,
+  scriptBasename,
+};