@webpieces/ai-hook-rules 0.4.710 → 0.4.712

package/src/bin/hook-registration.js

@@ -1,8 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ENV_SURFACE = exports.REGISTRATION_SURFACE = exports.SHIM_SURFACE = exports.SettingsRepair = exports.GUARDS_MATCHER = exports.RULES_MATCHER = exports.GUARDS_BIN = exports.RULES_BIN = exports.HookRegistrationEntry = exports.LEGACY_MARKER_REMOVE_AFTER = exports.LEGACY_GUARANTEE_ROOT_MARKER = void 0;
-exports.shimCommand = shimCommand;
-exports.guardHookEntry = guardHookEntry;
+exports.ENV_SURFACE = exports.CODEX_REGISTRATION_SURFACE = exports.REGISTRATION_SURFACE = exports.SHIM_SURFACE = exports.SettingsRepair = exports.HARNESS_REGISTRATIONS = exports.CODEX_REGISTRATION = exports.CLAUDE_REGISTRATION = exports.HarnessRegistration = exports.GUARDS_BIN = exports.RULES_BIN = exports.HookRegistrationEntry = exports.LEGACY_MARKER_REMOVE_AFTER = exports.LEGACY_GUARANTEE_ROOT_MARKER = void 0;
 exports.isManagedCommand = isManagedCommand;
 exports.managedEntries = managedEntries;
 exports.registeredBins = registeredBins;
@@ -13,7 +11,6 @@ exports.addHookEntry = addHookEntry;
 exports.envStale = envStale;
 exports.applyManagedEnv = applyManagedEnv;
 exports.repairRegistration = repairRegistration;
-exports.projectSettingsPaths = projectSettingsPaths;
 exports.readSettings = readSettings;
 exports.writeSettings = writeSettings;
 exports.registrationStaleAt = registrationStaleAt;
@@ -27,12 +24,20 @@ const to_error_1 = require("../core/to-error");
 const shim_1 = require("./shim");
 const managed_env_1 = require("./managed-env");
 /**
- * THE INSTALLED HOOK SURFACE — two hooks, both ABSOLUTE, and the ONE place their spelling is defined.
+ * THE INSTALLED HOOK SURFACE — two hooks per harness, all ABSOLUTE, and the ONE place their spelling is
+ * defined. See `HarnessRegistration` below, which is what makes "per harness" data rather than four
+ * module constants that were only ever true of Claude Code.
  *
  * ─── ONE GOVERNOR: the MAIN tree judges every tree ─────────────────────────────────────────────────
  *
- *   H1  sh "$CLAUDE_PROJECT_DIR/.claude/webpieces/ai-hook.sh" wp-ai-guards-hook   Write|…|Bash|Read
- *   H2  sh "$CLAUDE_PROJECT_DIR/.claude/webpieces/ai-hook.sh" wp-ai-rules-hook    Write|Edit|MultiEdit
+ *   Claude Code — .claude/settings.json
+ *     H1  sh "$CLAUDE_PROJECT_DIR/.claude/webpieces/ai-hook.sh" wp-ai-guards-hook  Write|…|Bash|Read
+ *     H2  sh "$CLAUDE_PROJECT_DIR/.claude/webpieces/ai-hook.sh" wp-ai-rules-hook   Write|Edit|MultiEdit
+ *   Codex — .codex/hooks.json (the SAME `hooks.PreToolUse` JSON shape, measured)
+ *     H1  sh "$PWD/.claude/webpieces/ai-hook.sh" wp-ai-guards-hook                 Bash|apply_patch
+ *     H2  sh "$PWD/.claude/webpieces/ai-hook.sh" wp-ai-rules-hook                  apply_patch
+ *
+ * ONE shim file serves all four: `.claude/` there is a path, not a claim about who is calling.
  *
  * This REPLACES a three-hook form in which these two were RELATIVE (`sh ".claude/webpieces/ai-hook.sh"`)
  * and a third hook, L-1 `guarantee-root.sh`, existed solely to guarantee that relative path resolved.
@@ -109,43 +114,137 @@ class HookRegistrationEntry {
 exports.HookRegistrationEntry = HookRegistrationEntry;
 exports.RULES_BIN = 'wp-ai-rules-hook';
 exports.GUARDS_BIN = 'wp-ai-guards-hook';
-exports.RULES_MATCHER = 'Write|Edit|MultiEdit';
-// Guards match Bash (git/PR guards), Write|Edit|MultiEdit (file-scoped guards) AND Read — Read carries
-// no guard, but the guards hook owns the per-invocation audit log, so matching Read records every file
-// the AI opens (log-and-allow fast path in hook-core.ts; a Read is never blocked).
-exports.GUARDS_MATCHER = 'Write|Edit|MultiEdit|Bash|Read';
 /**
- * The guard-hook command — `sh "$CLAUDE_PROJECT_DIR/.claude/webpieces/ai-hook.sh" <bin>`.
- *
- * ABSOLUTE. This replaced a RELATIVE spelling, and the reversal is the whole point of this release.
- *
- * The relative form existed to give each git tree its own release, binary and pin. **It never delivered
- * that.** Measured 2026-08-10: a linked worktree has no `node_modules`, so ai-hook.sh's upward walk
- * executes the PRIMARY's binary — `readlink -f` resolved a worktree agent's bin to
- * `<primary>/node_modules/@webpieces/ai-hook-rules`. A worktree ran its own SCRIPT and its own CONFIG,
- * never its own release. The property was fiction, and paying for it cost an entire guard layer: a
- * relative path only resolves at a tree root, so L-1 (guarantee-root.sh) had to deny every `cd` into a
- * project subdirectory, which produced the force-to-root bug class, the reaped-worktree `cd`
- * prescription, and a measured hard deadlock where L-1 told a worktree-isolated agent to `cd` to the
- * primary clone — which the harness refuses for an isolated agent.
- *
- * Absolute resolves from ANY cwd, so L-1 has no job left and is deleted. One governor: the MAIN tree
- * judges every tree, which is what was already happening via the borrowed binary — the design now says
- * so out loud, and `VersionSyncGuard` blocks the case where that is the wrong answer.
- *
- * Invoked via `sh <file>` rather than executed directly so a missing executable bit on the checked-in
- * shim (fresh clone, a filesystem that drops the bit, git core.fileMode quirks) can never break the hook
- * with a raw `Permission denied` on every tool call. Quoted to survive spaces in the path.
+ * ONE HARNESS'S registration surface — where its hooks live, what they match, and how they name the
+ * shim. Data-only → a class, per CLAUDE.md.
+ *
+ * ─── Why this exists ──────────────────────────────────────────────────────────────────────────────
+ * The matchers and the shim command used to be four module constants written for Claude Code alone.
+ * Applied to Codex they are wrong in both halves, and the way they are wrong is SILENT:
+ *
+ *   - MATCHER. Codex's file-editing tool is `apply_patch` (MEASURED, codex-cli 0.151.0). A matcher of
+ *     `Write|Edit|MultiEdit` matches it never, so every file rule is unreachable while the settings file
+ *     looks perfectly installed. Its shell tool IS called `Bash` — Codex reuses Claude's name — which is
+ *     the trap: half the matcher works, so the hooks appear to be running.
+ *   - ANCHOR. `$CLAUDE_PROJECT_DIR` does not exist in a Codex hook's environment (measured: 46 vars, no
+ *     such key), so the command expands to `sh "/.claude/webpieces/ai-hook.sh"`, which dies — and per the
+ *     hooks protocol a non-2 non-zero exit is a NON-BLOCKING error, i.e. a silent unguarded allow.
+ *
+ * Both halves of that were live in real repos, written by a Codex Desktop sync that transliterated the
+ * Claude setup. Making the registration per-harness DATA is what stops a future harness inheriting a
+ * matcher that was never true for it.
+ *
+ * ─── ONE SHIM, both harnesses ─────────────────────────────────────────────────────────────────────
+ * `SHIM_MARKER` is shared deliberately: `.claude/webpieces/ai-hook.sh` is the single fail-closed entry
+ * point, and moving or duplicating it would double the L0 allowlist regexes, the drift surfaces and the
+ * cures. The `.claude/` prefix is a path, not a claim about which agent is calling.
  */
-// webpieces-disable no-function-outside-class -- this module must load on a tree too broken to build a DI container (upgrade-shim.ts depends on that), so it is module-scope like its siblings shim.ts
-function shimCommand(bin) {
-    return `sh "$CLAUDE_PROJECT_DIR/${shim_1.SHIM_MARKER}" ${bin}`;
-}
-/** The registration entry for one guard bin. */
-// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above
-function guardHookEntry(bin) {
-    return new HookRegistrationEntry(bin === exports.RULES_BIN ? exports.RULES_MATCHER : exports.GUARDS_MATCHER, shimCommand(bin));
+class HarnessRegistration {
+    aiType;
+    label;
+    rulesMatcher;
+    guardsMatcher;
+    settingsFiles;
+    shimAnchor;
+    managesEnv;
+    registrationSurface;
+    // eslint-disable-next-line @typescript-eslint/max-params
+    constructor(aiType, 
+    /** How the installer and the drift report name this harness to a human. */
+    label, 
+    /** Which tool names the RULES hook (code-style, file-scoped) must see. */
+    rulesMatcher, 
+    /**
+     * Which tool names the GUARDS hook must see. Wider than the rules matcher by the shell tool and,
+     * for Claude Code, by `Read` — Read carries no guard, but the guards hook owns the
+     * per-invocation audit log, so matching it records every file the AI opens (log-and-allow fast
+     * path in hook-core.ts; a Read is never blocked). Codex has no Read tool at all: a read arrives
+     * as `Bash` running a pager, which the shell matcher already covers and read-parity synthesizes.
+     */
+    guardsMatcher, 
+    /** The settings files this harness's hooks can be installed into, relative to the repo root. */
+    settingsFiles, 
+    /**
+     * THE PREFIX THE SHIM PATH IS ANCHORED ON, and the reason each harness needs its own.
+     *
+     * **BYTE-STABILITY IS A HARD CONSTRAINT ON THE CODEX VALUE.** Codex trusts a hook entry
+     * TOFU — `~/.codex/config.toml` records a `trusted_hash` per entry — so ANY change to these bytes
+     * invalidates that trust and re-prompts the human, whose third option is `Continue without
+     * trusting (hooks won't run)`: one keystroke to a silently unguarded session. Changing this
+     * string is therefore never a cosmetic edit. The hash is NOT reproducible from outside Codex
+     * (16 encodings tried against a file we authored), so the installer can never repair trust for
+     * itself — see ./codex-trust.ts, which REPORTS and never writes.
+     */
+    shimAnchor, 
+    /**
+     * True when this harness's settings file also carries the managed `env` block. Claude Code's
+     * settings `env` is inherited by every subagent, which is what makes it the right home for the
+     * Bash-cwd pin (see managed-env.ts). Codex has no equivalent surface — and needs none: its cwd
+     * is MEASURED not to drift at all (`cd x && pwd` prints x, the next call is back at the repo
+     * root, for the coordinator and for subagents alike).
+     */
+    managesEnv, 
+    /** What `managedSurfaceDrift()` calls this harness's registration when it has moved. */
+    registrationSurface) {
+        this.aiType = aiType;
+        this.label = label;
+        this.rulesMatcher = rulesMatcher;
+        this.guardsMatcher = guardsMatcher;
+        this.settingsFiles = settingsFiles;
+        this.shimAnchor = shimAnchor;
+        this.managesEnv = managesEnv;
+        this.registrationSurface = registrationSurface;
+    }
+    /** Which matcher one guard bin registers under. */
+    matcherFor(bin) {
+        return bin === exports.RULES_BIN ? this.rulesMatcher : this.guardsMatcher;
+    }
+    /**
+     * The guard-hook command — `sh "<anchor>/.claude/webpieces/ai-hook.sh" <bin>`.
+     *
+     * ABSOLUTE, in both harnesses. Claude's anchor replaced a RELATIVE spelling and that reversal is
+     * documented at length in this file's header: relative resolves only at a tree root, a hook that
+     * cannot resolve exits 127, and per the hooks reference that is a NON-BLOCKING error — a silent
+     * unguarded allow. It also cost an entire guard layer (L-1) whose only job was to police the `cd`
+     * that made the relative path resolvable.
+     *
+     * Invoked via `sh <file>` rather than executed directly so a missing executable bit on the
+     * checked-in shim (fresh clone, a filesystem that drops the bit, git core.fileMode quirks) can never
+     * break the hook with a raw `Permission denied` on every tool call. Quoted to survive spaces.
+     */
+    shimCommand(bin) {
+        return `sh "${this.shimAnchor}/${shim_1.SHIM_MARKER}" ${bin}`;
+    }
+    /** The registration entry for one guard bin under this harness. */
+    entryFor(bin) {
+        return new HookRegistrationEntry(this.matcherFor(bin), this.shimCommand(bin));
+    }
+    /** This harness's settings files under one repo root, absolute. */
+    settingsPaths(projectRoot) {
+        return this.settingsFiles.map((file) => path.join(projectRoot, ...file.split('/')));
+    }
 }
+exports.HarnessRegistration = HarnessRegistration;
+exports.CLAUDE_REGISTRATION = new HarnessRegistration('claude-code', 'Claude Code', 'Write|Edit|MultiEdit', 'Write|Edit|MultiEdit|Bash|Read', ['.claude/settings.json', '.claude/settings.local.json'], '$CLAUDE_PROJECT_DIR', true, '.claude/settings.json hook registration');
+/**
+ * Codex's registration, every value of it MEASURED against codex-cli 0.151.0 rather than assumed.
+ *
+ * `$PWD` is the anchor because there is no project-dir variable to use and none is needed: the payload
+ * `cwd` and the hook process's own `PWD` are both the repo root on EVERY call — for the coordinator and
+ * for subagents — and a `cd` inside one command never survives into the next. That was measured, not
+ * hoped for, and it is the same effect Claude Code gets from the managed
+ * `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR` env entry. See `shimAnchor` for why these exact bytes are
+ * not free to change.
+ */
+exports.CODEX_REGISTRATION = new HarnessRegistration('codex', 'Codex', 'apply_patch', 'Bash|apply_patch', ['.codex/hooks.json'], '$PWD', false, '.codex/hooks.json hook registration');
+/**
+ * Every harness webpieces arms, in installer order.
+ *
+ * The drift check, the repair and the installer all iterate THIS, so a harness cannot be armed by the
+ * installer and then left unvalidated — which is exactly the state `.codex/hooks.json` was in before it
+ * was a managed surface: written by something else, silently wrong, and invisible to every check.
+ */
+exports.HARNESS_REGISTRATIONS = [exports.CLAUDE_REGISTRATION, exports.CODEX_REGISTRATION];
 /**
  * True when this PreToolUse command is one webpieces owns — in ANY spelling it has ever shipped.
  *
@@ -194,9 +293,9 @@ function registeredBins(settings) {
  * whenever the GUARDS bin was present; it is retired, and a settings file still carrying it is STALE —
  * `repairRegistration()` removes it via isManagedCommand()'s legacy marker.
  */
-// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above
-function expectedEntries(bins) {
-    return bins.map((bin) => guardHookEntry(bin));
+// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as HarnessRegistration's siblings
+function expectedEntries(harness, bins) {
+    return bins.map((bin) => harness.entryFor(bin));
 }
 /**
  * True when a settings file registers webpieces hooks in a shape this release does not expect: a
@@ -206,12 +305,12 @@ function expectedEntries(bins) {
  * carries no meaning and reordering must not read as drift.
  */
 // webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above
-function registrationStale(settings) {
+function registrationStale(harness, settings) {
     const bins = registeredBins(settings);
     if (bins.length === 0)
         return false;
     const have = managedEntries(settings);
-    const want = expectedEntries(bins);
+    const want = expectedEntries(harness, bins);
     if (have.length !== want.length)
         return true;
     return want.some((w) => !have.some((h) => h.sameAs(w)));
@@ -310,29 +409,24 @@ function applyManagedEnv(settings) {
  * that skips half the surface is the failure mode `upgrade-shim.ts`'s header exists to prevent.
  */
 // webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above
-function repairRegistration(settings) {
+function repairRegistration(harness, settings) {
     const bins = registeredBins(settings);
     if (bins.length === 0)
         return false;
     let changed = false;
-    if (registrationStale(settings)) {
+    if (registrationStale(harness, settings)) {
         dropManagedEntries(settings);
-        for (const entry of expectedEntries(bins))
+        for (const entry of expectedEntries(harness, bins))
             addHookEntry(settings, entry);
         changed = true;
     }
-    if (applyManagedEnv(settings))
+    // Only where the harness HAS that surface. Codex's hooks.json has no `env` block to manage, and
+    // inventing one there would write a key Codex does not read — a managed surface nothing consumes is
+    // a surface that can drift with no consequence and no way to notice.
+    if (harness.managesEnv && applyManagedEnv(settings))
         changed = true;
     return changed;
 }
-/** The two project settings files the installer can write. */
-// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above
-function projectSettingsPaths(projectRoot) {
-    return [
-        path.join(projectRoot, '.claude', 'settings.json'),
-        path.join(projectRoot, '.claude', 'settings.local.json'),
-    ];
-}
 // webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above
 function readSettings(settingsPath) {
     if (!fs.existsSync(settingsPath))
@@ -354,14 +448,24 @@ function writeSettings(settingsPath, settings) {
     fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
     fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 4) + '\n');
 }
-/** True when either project settings file under `root` carries a stale registration. */
-// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above
-function registrationStaleAt(root) {
+/**
+ * True when any settings file ONE HARNESS owns under `root` carries a stale registration.
+ *
+ * Per harness, not per repo, so the drift report can NAME which one moved — `.claude/settings.json` and
+ * `.codex/hooks.json` have different cures, and a fault that says only "the registration is stale" sends
+ * the reader to the wrong file half the time.
+ *
+ * A file that does not exist, or exists and registers no webpieces hooks, is never judged (see
+ * `registrationStale`). That is what keeps a repo which has never armed Codex from suddenly faulting on
+ * a `.codex/hooks.json` it does not have.
+ */
+// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as HarnessRegistration's siblings
+function registrationStaleAt(harness, root) {
     if (root === null)
         return false;
     // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
     try {
-        return projectSettingsPaths(root).some((p) => registrationStale(readSettings(p)));
+        return harness.settingsPaths(root).some((p) => registrationStale(harness, readSettings(p)));
     }
     catch (err) {
         const error = (0, to_error_1.toError)(err);
@@ -369,14 +473,20 @@ function registrationStaleAt(root) {
         return false;
     }
 }
-/** True when either project settings file under `root` is missing the managed `env` entry. */
-// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above
+/**
+ * True when either Claude project settings file under `root` is missing the managed `env` entry.
+ *
+ * CLAUDE-ONLY by construction, and stated as such rather than looped over the harnesses: `env` is a
+ * Claude Code settings surface, Codex has no equivalent, and Codex's cwd is measured not to drift, which
+ * is the whole thing the entry is for. See HarnessRegistration.managesEnv.
+ */
+// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as HarnessRegistration's siblings
 function envStaleAt(root) {
     if (root === null)
         return false;
     // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
     try {
-        return projectSettingsPaths(root).some((p) => envStale(readSettings(p)));
+        return exports.CLAUDE_REGISTRATION.settingsPaths(root).some((p) => envStale(readSettings(p)));
     }
     catch (err) {
         const error = (0, to_error_1.toError)(err);
@@ -402,49 +512,68 @@ class SettingsRepair {
     }
 }
 exports.SettingsRepair = SettingsRepair;
-/** Rewrite every stale project settings file under `root`; returns what changed, per file. */
-// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above
+/**
+ * Rewrite every stale settings file under `root`, for EVERY harness; returns what changed, per file.
+ *
+ * Existing files only — this never CREATES a registration. Arming a harness is the installer's decision
+ * (`wp-install-ai-hooks`); this is the cure for one that has already been armed and has drifted, so a
+ * repo that has never armed Codex is left exactly as it was.
+ */
+// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as HarnessRegistration's siblings
 function repairRegistrationAt(root) {
     const repairs = [];
-    for (const settingsPath of projectSettingsPaths(root)) {
-        if (!fs.existsSync(settingsPath))
-            continue;
-        const settings = readSettings(settingsPath);
-        const neededRegistration = registrationStale(settings);
-        const neededEnv = envStale(settings);
-        if (!repairRegistration(settings))
-            continue;
-        writeSettings(settingsPath, settings);
-        repairs.push(new SettingsRepair(settingsPath, neededRegistration, neededEnv));
+    for (const harness of exports.HARNESS_REGISTRATIONS) {
+        for (const settingsPath of harness.settingsPaths(root)) {
+            if (!fs.existsSync(settingsPath))
+                continue;
+            const settings = readSettings(settingsPath);
+            const neededRegistration = registrationStale(harness, settings);
+            const neededEnv = harness.managesEnv && envStale(settings);
+            if (!repairRegistration(harness, settings))
+                continue;
+            writeSettings(settingsPath, settings);
+            repairs.push(new SettingsRepair(settingsPath, neededRegistration, neededEnv));
+        }
     }
     return repairs;
 }
 /**
- * The THREE names the drift check reports, so a deny can say WHICH of them moved.
+ * The names the drift check reports, so a deny can say WHICH surface moved.
  *
- * There were four. `GUARANTEE_ROOT_SURFACE` is gone with L-1 itself: an absolutely-registered shim
- * resolves from any cwd, so there is no launch guarantee left to police and no second .sh file to keep
- * byte-locked. A settings file still carrying the retired H1 entry is not its own surface any more —
- * it is ordinary REGISTRATION drift, which `registrationStaleAt()` already reports and
- * `repairRegistration()` already fixes by removing it.
+ * There were four, then three, and there are now FOUR again — but the fourth is not the one that was
+ * deleted. `GUARANTEE_ROOT_SURFACE` went with L-1 itself: an absolutely-registered shim resolves from
+ * any cwd, so there is no launch guarantee left to police and no second .sh file to keep byte-locked. A
+ * settings file still carrying the retired H1 entry is not its own surface — it is ordinary REGISTRATION
+ * drift, which `registrationStaleAt()` reports and `repairRegistration()` fixes by removing it.
+ *
+ * The new fourth is `.codex/hooks.json`, and it is here because of what happened while it was NOT a
+ * managed surface: something else wrote it, with a matcher that matched no Codex file tool and a shim
+ * path anchored on a variable Codex does not set, and no check in this package could see it. A file the
+ * guards depend on and nothing validates is the exact shape of that incident.
+ *
+ * Each harness's registration surface is its own name, from HarnessRegistration.registrationSurface, so
+ * the deny sends the reader to the file that actually moved.
  */
 exports.SHIM_SURFACE = shim_1.SHIM_MARKER;
-exports.REGISTRATION_SURFACE = '.claude/settings.json hook registration';
+exports.REGISTRATION_SURFACE = exports.CLAUDE_REGISTRATION.registrationSurface;
+exports.CODEX_REGISTRATION_SURFACE = exports.CODEX_REGISTRATION.registrationSurface;
 exports.ENV_SURFACE = `.claude/settings.json env.${managed_env_1.BASH_CWD_ENV_KEY}`;
 /**
- * WHICH of the three managed surfaces disagree with this release — the input to fault S.
+ * WHICH of the managed surfaces disagree with this release — the input to fault S.
  *
- * All three are checked against the SAME root, resolved from the RUNNING MODULE (governingShimRoot),
+ * All of them are checked against the SAME root, resolved from the RUNNING MODULE (governingShimRoot),
  * never from cwd and never from `$CLAUDE_PROJECT_DIR`: the files we compare and the renderers we
  * compare them TO must come from one install, or the check straddles two trees and can never converge.
  */
-// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above
+// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as HarnessRegistration's siblings
 function managedSurfaceDrift(root) {
     const drifted = [];
     if ((0, shim_1.committedShimStale)(root))
         drifted.push(exports.SHIM_SURFACE);
-    if (registrationStaleAt(root))
-        drifted.push(exports.REGISTRATION_SURFACE);
+    for (const harness of exports.HARNESS_REGISTRATIONS) {
+        if (registrationStaleAt(harness, root))
+            drifted.push(harness.registrationSurface);
+    }
     if (envStaleAt(root))
         drifted.push(exports.ENV_SURFACE);
     return drifted;

package/src/bin/hook-registration.js.map

@@ -1 +1 @@
-{"version":3,"file":"hook-registration.js","sourceRoot":"","sources":["../../../../../../packages/tooling/ai-hook-rules/src/bin/hook-registration.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'fs';\nimport * as path from 'path';\n\nimport { toError } from '../core/to-error';\nimport { SHIM_MARKER, committedShimStale } from './shim';\nimport { BASH_CWD_ENV_KEY, BASH_CWD_ENV_VALUE } from './managed-env';\n\n/**\n * THE INSTALLED HOOK SURFACE — two hooks, both ABSOLUTE, and the ONE place their spelling is defined.\n *\n * ─── ONE GOVERNOR: the MAIN tree judges every tree ─────────────────────────────────────────────────\n *\n *   H1  sh \"$CLAUDE_PROJECT_DIR/.claude/webpieces/ai-hook.sh\" wp-ai-guards-hook   Write|…|Bash|Read\n *   H2  sh \"$CLAUDE_PROJECT_DIR/.claude/webpieces/ai-hook.sh\" wp-ai-rules-hook    Write|Edit|MultiEdit\n *\n * This REPLACES a three-hook form in which these two were RELATIVE (`sh \".claude/webpieces/ai-hook.sh\"`)\n * and a third hook, L-1 `guarantee-root.sh`, existed solely to guarantee that relative path resolved.\n *\n * ─── Why the relative experiment was reversed ──────────────────────────────────────────────────────\n * Relative registration was adopted so each git tree would be governed by \"its own release, binary and\n * pin\". MEASURED 2026-08-10: it never delivered that. A linked worktree has NO `node_modules`, so\n * ai-hook.sh's upward walk executes the PRIMARY's binary — `readlink -f` resolved a worktree agent's bin\n * to `<primary>/node_modules/@webpieces/ai-hook-rules`. A worktree ran its own SCRIPT and its own\n * CONFIG; it never ran its own release. Governance was already the primary's, in every tree, the whole\n * time.\n *\n * The price of that fiction was an entire guard layer. A relative path only resolves at a tree root, and\n * a hook that cannot resolve exits 127 — per the hooks reference a NON-BLOCKING error, i.e. a SILENT\n * UNGUARDED ALLOW. So L-1 had to deny every `cd` into a project subdirectory. That denial produced the\n * force-to-root bug class, the reaped-worktree `cd` prescription, and a measured hard deadlock: L-1 told\n * a worktree-isolated agent to `cd` to the primary clone, which the harness refuses for an isolated\n * agent, leaving it unable to stay or to follow the cure.\n *\n * An absolute path resolves from ANY cwd. So the launch guarantee is structural, L-1 has no job left and\n * is deleted, and `cd` into a subdirectory is simply allowed. What used to be true only by policing the\n * shell is now true by construction.\n *\n * ─── What replaces the property that was lost ──────────────────────────────────────────────────────\n * Nothing is lost that was ever delivered — but the case relative registration WANTED to handle (a tree\n * that genuinely needs a different @webpieces) is now DETECTED instead of silently mis-governed:\n * `VersionSyncGuard` (L1 row 8) blocks when a worktree's pin disagrees with the main tree's, and\n * prescribes either aligning the pins (same git hash → same tracked pin → install in each tree that has\n * a node_modules) or using a separate CLONE, which — unlike a worktree — gets its own GOVERNANCE. Note\n * what that does NOT say: a worktree may perfectly well have its own node_modules, and usually does the\n * moment anything installs in it. What it may not have is a DIFFERENT @webpieces version.\n *\n * ─── Why the registration is a DRIFT SURFACE, not just an install step ─────────────────────────────\n * Nothing used to validate `.claude/settings.json` at all, so a settings file left on a superseded form\n * silently changed who governs. The installed surface is THREE things (ai-hook.sh, the registration, and\n * the managed `env` entry — see managed-env.ts), all three are compared against this release, and\n * `wp-upgrade-shim` regenerates all three. A cure that fixes two of three is worse than no cure, because\n * it reports success.\n */\n\n/**\n * The RETIRED L-1 hook's committed path. Named here, in the one module that must still recognise it, and\n * matched ONLY by isManagedCommand() so repairRegistration() can delete the stale entry. There is no\n * guarantee-root.ts any more — this literal is all that remains of it, deliberately.\n *\n * It is a one-way RECOGNISER, not a shim: nothing emits it, `expectedEntries()` never returns it, and a\n * settings file carrying it is reported STALE. Its only job is to make the retired entry findable so it\n * can be REMOVED.\n */\nexport const LEGACY_GUARANTEE_ROOT_MARKER = '.claude/webpieces/guarantee-root.sh';\n\n/**\n * When this recogniser may be deleted, as a value rather than a comment nobody re-reads.\n *\n * A removal-only migration is still dead weight once no consumer can be carrying the old shape. The\n * hazard of deleting it EARLY is severe and silent — repair would stop stripping the retired entry, and\n * a hook registered against a deleted file exits 127, which the Claude Code hooks reference defines as a\n * NON-BLOCKING error, i.e. every `cd` unjudged while the cure reports success. So it gets a stated date\n * and a test that fails once the date passes, instead of an intention.\n *\n * `legacy-marker-expiry.spec.ts` reads this and fails after it, which is the reminder.\n */\nexport const LEGACY_MARKER_REMOVE_AFTER = '2026-12-01';\n\n/** One PreToolUse hook entry as webpieces registers it. Data-only → a class, per CLAUDE.md. */\nexport class HookRegistrationEntry {\n    constructor(\n        readonly matcher: string,\n        readonly command: string,\n    ) {}\n\n    sameAs(other: HookRegistrationEntry): boolean {\n        return this.matcher === other.matcher && this.command === other.command;\n    }\n}\n\n// webpieces-disable no-any-unknown -- settings.json is opaque consumer JSON\nexport interface HookCommand { type: string; command: string; }\nexport interface HookEntry { matcher: string; hooks: HookCommand[]; }\nexport interface ClaudeSettings {\n    hooks?: { PreToolUse?: HookEntry[] };\n    // Claude Code's settings `env` block: every key is exported into the environment of the session AND\n    // of every subagent it spawns. That inheritance is precisely why webpieces pins its managed entry\n    // here rather than in a shell profile — see managed-env.ts.\n    env?: Record<string, string>;\n    // webpieces-disable no-any-unknown -- opaque settings bag; arbitrary keys allowed\n    [key: string]: unknown;\n}\n\nexport const RULES_BIN = 'wp-ai-rules-hook';\nexport const GUARDS_BIN = 'wp-ai-guards-hook';\nexport const RULES_MATCHER = 'Write|Edit|MultiEdit';\n// Guards match Bash (git/PR guards), Write|Edit|MultiEdit (file-scoped guards) AND Read — Read carries\n// no guard, but the guards hook owns the per-invocation audit log, so matching Read records every file\n// the AI opens (log-and-allow fast path in hook-core.ts; a Read is never blocked).\nexport const GUARDS_MATCHER = 'Write|Edit|MultiEdit|Bash|Read';\n\n/**\n * The guard-hook command — `sh \"$CLAUDE_PROJECT_DIR/.claude/webpieces/ai-hook.sh\" <bin>`.\n *\n * ABSOLUTE. This replaced a RELATIVE spelling, and the reversal is the whole point of this release.\n *\n * The relative form existed to give each git tree its own release, binary and pin. **It never delivered\n * that.** Measured 2026-08-10: a linked worktree has no `node_modules`, so ai-hook.sh's upward walk\n * executes the PRIMARY's binary — `readlink -f` resolved a worktree agent's bin to\n * `<primary>/node_modules/@webpieces/ai-hook-rules`. A worktree ran its own SCRIPT and its own CONFIG,\n * never its own release. The property was fiction, and paying for it cost an entire guard layer: a\n * relative path only resolves at a tree root, so L-1 (guarantee-root.sh) had to deny every `cd` into a\n * project subdirectory, which produced the force-to-root bug class, the reaped-worktree `cd`\n * prescription, and a measured hard deadlock where L-1 told a worktree-isolated agent to `cd` to the\n * primary clone — which the harness refuses for an isolated agent.\n *\n * Absolute resolves from ANY cwd, so L-1 has no job left and is deleted. One governor: the MAIN tree\n * judges every tree, which is what was already happening via the borrowed binary — the design now says\n * so out loud, and `VersionSyncGuard` blocks the case where that is the wrong answer.\n *\n * Invoked via `sh <file>` rather than executed directly so a missing executable bit on the checked-in\n * shim (fresh clone, a filesystem that drops the bit, git core.fileMode quirks) can never break the hook\n * with a raw `Permission denied` on every tool call. Quoted to survive spaces in the path.\n */\n// webpieces-disable no-function-outside-class -- this module must load on a tree too broken to build a DI container (upgrade-shim.ts depends on that), so it is module-scope like its siblings shim.ts\nexport function shimCommand(bin: string): string {\n    return `sh \"$CLAUDE_PROJECT_DIR/${SHIM_MARKER}\" ${bin}`;\n}\n\n/** The registration entry for one guard bin. */\n// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above\nexport function guardHookEntry(bin: string): HookRegistrationEntry {\n    return new HookRegistrationEntry(bin === RULES_BIN ? RULES_MATCHER : GUARDS_MATCHER, shimCommand(bin));\n}\n\n/**\n * True when this PreToolUse command is one webpieces owns — in ANY spelling it has ever shipped.\n *\n * THE SINGLE MOST IMPORTANT LINE IN THIS RELEASE. `LEGACY_GUARANTEE_ROOT_MARKER` is matched here and\n * NOWHERE else: it is how `repairRegistration()` finds and REMOVES the retired H1 entry from a settings\n * file written by an older release. Drop it and the repair silently leaves a live L-1 hook registered\n * against a file this release deletes — exit 127, which the Claude Code hooks reference defines as a\n * NON-BLOCKING error, so every `cd` goes unjudged while `wp-upgrade-shim` reports success and no drift\n * check can name it. Removal-only, never emitted: it appears in no `expectedEntries()` result, so it is\n * a one-way migration and not a second accepted spelling.\n */\n// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above\nexport function isManagedCommand(command: string): boolean {\n    return command.includes(SHIM_MARKER) || command.includes(LEGACY_GUARANTEE_ROOT_MARKER);\n}\n\n// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above\nfunction preToolUse(settings: ClaudeSettings): readonly HookEntry[] {\n    return settings.hooks?.PreToolUse ?? [];\n}\n\n/** Every webpieces-managed entry of one settings file, flattened to matcher + command pairs. */\n// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above\nexport function managedEntries(settings: ClaudeSettings): readonly HookRegistrationEntry[] {\n    const found: HookRegistrationEntry[] = [];\n    for (const entry of preToolUse(settings)) {\n        for (const hook of entry.hooks) {\n            if (isManagedCommand(hook.command)) found.push(new HookRegistrationEntry(entry.matcher, hook.command));\n        }\n    }\n    return found;\n}\n\n/**\n * Which guard bins this settings file registers, in installer order. A file registering NEITHER is not\n * a project (relative) install and is therefore never judged — a global/absolute install names the bin\n * path directly and carries no shim marker at all.\n */\n// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above\nexport function registeredBins(settings: ClaudeSettings): readonly string[] {\n    const commands = managedEntries(settings).map((e: HookRegistrationEntry): string => e.command);\n    return [GUARDS_BIN, RULES_BIN].filter((bin: string): boolean => commands.some((c: string): boolean => c.includes(bin)));\n}\n\n/**\n * The exact set of entries THIS RELEASE expects in a settings file that registers `bins`.\n *\n * ONE entry per registered bin, and nothing else. There used to be a third, `guarantee-root.sh`, added\n * whenever the GUARDS bin was present; it is retired, and a settings file still carrying it is STALE —\n * `repairRegistration()` removes it via isManagedCommand()'s legacy marker.\n */\n// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above\nexport function expectedEntries(bins: readonly string[]): readonly HookRegistrationEntry[] {\n    return bins.map((bin: string): HookRegistrationEntry => guardHookEntry(bin));\n}\n\n/**\n * True when a settings file registers webpieces hooks in a shape this release does not expect: a\n * RELATIVE shim command, a leftover guarantee-root entry, a stray duplicate, or a wrong matcher.\n *\n * Compared as a SET, not a sequence: Claude Code runs all matching hooks in parallel, so array order\n * carries no meaning and reordering must not read as drift.\n */\n// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above\nexport function registrationStale(settings: ClaudeSettings): boolean {\n    const bins = registeredBins(settings);\n    if (bins.length === 0) return false;\n    const have = managedEntries(settings);\n    const want = expectedEntries(bins);\n    if (have.length !== want.length) return true;\n    return want.some((w: HookRegistrationEntry): boolean => !have.some((h: HookRegistrationEntry): boolean => h.sameAs(w)));\n}\n\n/** Drop every webpieces-managed PreToolUse command; returns true if anything was removed. */\n// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above\nexport function dropManagedEntries(settings: ClaudeSettings): boolean {\n    const entries = settings.hooks?.PreToolUse;\n    if (!entries) return false;\n    let changed = false;\n    const kept: HookEntry[] = [];\n    for (const entry of entries) {\n        const hooks = entry.hooks.filter((h: HookCommand): boolean => !isManagedCommand(h.command));\n        if (hooks.length !== entry.hooks.length) changed = true;\n        if (hooks.length > 0) kept.push({ matcher: entry.matcher, hooks });\n    }\n    if (changed) settings.hooks!.PreToolUse = kept;\n    return changed;\n}\n\n/** Append one PreToolUse entry. */\n// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above\nexport function addHookEntry(settings: ClaudeSettings, entry: HookRegistrationEntry): void {\n    if (!settings.hooks) settings.hooks = {};\n    if (!Array.isArray(settings.hooks.PreToolUse)) settings.hooks.PreToolUse = [];\n    settings.hooks.PreToolUse.push({ matcher: entry.matcher, hooks: [{ type: 'command', command: entry.command }] });\n}\n\n/** The settings `env` block, or null when the file carries none (or carries junk in its place). */\n// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above\nfunction settingsEnv(settings: ClaudeSettings): Record<string, string> | null {\n    // webpieces-disable no-any-unknown -- settings.json is opaque consumer JSON; `env` is only typed after this check\n    const env: unknown = settings.env;\n    if (typeof env !== 'object' || env === null || Array.isArray(env)) return null;\n    return env as Record<string, string>;\n}\n\n/**\n * True when a settings file that registers webpieces hooks is missing the managed `env` entry, or\n * carries any value other than the one required one.\n *\n * Gated on `registeredBins()` for the SAME reason `registrationStale()` is: a settings file that\n * registers no webpieces hooks is not a project install and is never judged — a global install names\n * the bin path directly and carries no shim marker at all, so there is nothing here to keep in step.\n *\n * NOTE what this entry is for NOW. It was originally justified by keeping the then-RELATIVE hook path\n * resolvable; that job is retired, because both hooks are absolute and resolve from any cwd. It is kept\n * for VERDICT STABILITY — a guard's answer must depend on the command, not on where an earlier `cd` left\n * the shell — and because settings `env` is inherited, every subagent shares that cwd and therefore that\n * verdict. See managed-env.ts, which states this at length.\n */\n// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above\nexport function envStale(settings: ClaudeSettings): boolean {\n    if (registeredBins(settings).length === 0) return false;\n    const env = settingsEnv(settings);\n    return env === null || env[BASH_CWD_ENV_KEY] !== BASH_CWD_ENV_VALUE;\n}\n\n/**\n * Set the managed `env` entry IN PLACE, whatever was there before. Returns true when it changed.\n *\n * A user-set `\"0\"` is BROUGHT TO `\"1\"`, not honoured: this is a managed surface, and \"webpieces sets it\n * unless you disagreed\" would be a second, invisible spelling of the decision. Turning it off means\n * uninstalling the hooks, exactly as it does for every other managed thing.\n *\n * UNGATED on purpose — the installer calls it for the file it is writing hooks into, and the gate lives\n * at the caller (repairRegistration / applyHook), so a file with no webpieces hooks is never touched.\n */\n// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above\nexport function applyManagedEnv(settings: ClaudeSettings): boolean {\n    const existing = settingsEnv(settings);\n    if (existing !== null && existing[BASH_CWD_ENV_KEY] === BASH_CWD_ENV_VALUE) return false;\n    const env = existing ?? {};\n    env[BASH_CWD_ENV_KEY] = BASH_CWD_ENV_VALUE;\n    settings.env = env;\n    return true;\n}\n\n/**\n * Bring one settings object to the two-hook ABSOLUTE form AND the managed `env` entry IN PLACE. Returns\n * true when it changed anything.\n *\n * REMOVE-then-ADD for the hooks, never add-beside: two spellings of one registration is exactly the\n * compatibility shim the backwards-compat reviewer rejects, and leaving a RELATIVE entry beside the\n * absolute one would run two shims per call — the\n * straddle this whole change exists to delete.\n *\n * THE TWO REPAIRS ARE EVALUATED INDEPENDENTLY, and that is load-bearing rather than tidy: this used to\n * early-return on `!registrationStale(settings)`, so a repo whose hooks are already current but whose\n * `env` entry is missing — the state EVERY existing consumer is in the moment this release lands — would\n * have been reported as drifted by fault S and then left unrepaired by its own prescribed cure. A cure\n * that skips half the surface is the failure mode `upgrade-shim.ts`'s header exists to prevent.\n */\n// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above\nexport function repairRegistration(settings: ClaudeSettings): boolean {\n    const bins = registeredBins(settings);\n    if (bins.length === 0) return false;\n    let changed = false;\n    if (registrationStale(settings)) {\n        dropManagedEntries(settings);\n        for (const entry of expectedEntries(bins)) addHookEntry(settings, entry);\n        changed = true;\n    }\n    if (applyManagedEnv(settings)) changed = true;\n    return changed;\n}\n\n/** The two project settings files the installer can write. */\n// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above\nexport function projectSettingsPaths(projectRoot: string): readonly string[] {\n    return [\n        path.join(projectRoot, '.claude', 'settings.json'),\n        path.join(projectRoot, '.claude', 'settings.local.json'),\n    ];\n}\n\n// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above\nexport function readSettings(settingsPath: string): ClaudeSettings {\n    if (!fs.existsSync(settingsPath)) return {};\n    const raw = fs.readFileSync(settingsPath, 'utf8');\n    if (raw.trim() === '') return {};\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        return JSON.parse(raw) as ClaudeSettings;\n    } catch (err: unknown) {\n        const error = toError(err);\n        throw new Error(`${settingsPath} has invalid JSON — fix it, then retry: ${error.message}`, { cause: error });\n    }\n}\n\n// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above\nexport function writeSettings(settingsPath: string, settings: ClaudeSettings): void {\n    fs.mkdirSync(path.dirname(settingsPath), { recursive: true });\n    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 4) + '\\n');\n}\n\n/** True when either project settings file under `root` carries a stale registration. */\n// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above\nexport function registrationStaleAt(root: string | null): boolean {\n    if (root === null) return false;\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        return projectSettingsPaths(root).some((p: string): boolean => registrationStale(readSettings(p)));\n    } catch (err: unknown) {\n        const error = toError(err);\n        void error; // best-effort: unreadable/invalid settings counts as \"not stale\" so it never wedges a call\n        return false;\n    }\n}\n\n/** True when either project settings file under `root` is missing the managed `env` entry. */\n// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above\nexport function envStaleAt(root: string | null): boolean {\n    if (root === null) return false;\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        return projectSettingsPaths(root).some((p: string): boolean => envStale(readSettings(p)));\n    } catch (err: unknown) {\n        const error = toError(err);\n        void error; // best-effort: unreadable/invalid settings counts as \"not stale\" so it never wedges a call\n        return false;\n    }\n}\n\n/**\n * WHAT was rewritten in ONE settings file. Data-only → a class, per CLAUDE.md.\n *\n * Two independent flags rather than one path, because the cure has to be able to SAY which repair it\n * made: \"rewrote the hook registration\" printed for a file whose registration was already current and\n * whose `env` entry was the only thing missing is a cure lying about its own work.\n */\nexport class SettingsRepair {\n    constructor(\n        readonly settingsPath: string,\n        readonly registration: boolean,\n        readonly env: boolean,\n    ) {}\n}\n\n/** Rewrite every stale project settings file under `root`; returns what changed, per file. */\n// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above\nexport function repairRegistrationAt(root: string): readonly SettingsRepair[] {\n    const repairs: SettingsRepair[] = [];\n    for (const settingsPath of projectSettingsPaths(root)) {\n        if (!fs.existsSync(settingsPath)) continue;\n        const settings = readSettings(settingsPath);\n        const neededRegistration = registrationStale(settings);\n        const neededEnv = envStale(settings);\n        if (!repairRegistration(settings)) continue;\n        writeSettings(settingsPath, settings);\n        repairs.push(new SettingsRepair(settingsPath, neededRegistration, neededEnv));\n    }\n    return repairs;\n}\n\n/**\n * The THREE names the drift check reports, so a deny can say WHICH of them moved.\n *\n * There were four. `GUARANTEE_ROOT_SURFACE` is gone with L-1 itself: an absolutely-registered shim\n * resolves from any cwd, so there is no launch guarantee left to police and no second .sh file to keep\n * byte-locked. A settings file still carrying the retired H1 entry is not its own surface any more —\n * it is ordinary REGISTRATION drift, which `registrationStaleAt()` already reports and\n * `repairRegistration()` already fixes by removing it.\n */\nexport const SHIM_SURFACE = SHIM_MARKER;\nexport const REGISTRATION_SURFACE = '.claude/settings.json hook registration';\nexport const ENV_SURFACE = `.claude/settings.json env.${BASH_CWD_ENV_KEY}`;\n\n/**\n * WHICH of the three managed surfaces disagree with this release — the input to fault S.\n *\n * All three are checked against the SAME root, resolved from the RUNNING MODULE (governingShimRoot),\n * never from cwd and never from `$CLAUDE_PROJECT_DIR`: the files we compare and the renderers we\n * compare them TO must come from one install, or the check straddles two trees and can never converge.\n */\n// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above\nexport function managedSurfaceDrift(root: string | null): readonly string[] {\n    const drifted: string[] = [];\n    if (committedShimStale(root)) drifted.push(SHIM_SURFACE);\n    if (registrationStaleAt(root)) drifted.push(REGISTRATION_SURFACE);\n    if (envStaleAt(root)) drifted.push(ENV_SURFACE);\n    return drifted;\n}\n"]}
+{"version":3,"file":"hook-registration.js","sourceRoot":"","sources":["../../../../../../packages/tooling/ai-hook-rules/src/bin/hook-registration.ts"],"names":[],"mappings":";;;AAgRA,4CAEC;AASD,wCAQC;AAQD,wCAGC;AAUD,0CAEC;AAUD,8CAOC;AAID,gDAYC;AAID,oCAIC;AA0BD,4BAIC;AAaD,0CAOC;AAkBD,gDAcC;AAGD,oCAWC;AAGD,sCAGC;AAcD,kDAUC;AAUD,gCAUC;AAyBD,oDAcC;AAgCD,kDAQC;;AApkBD,+CAAyB;AACzB,mDAA6B;AAE7B,+CAA2C;AAE3C,iCAAyD;AACzD,+CAAqE;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH;;;;;;;;GAQG;AACU,QAAA,4BAA4B,GAAG,qCAAqC,CAAC;AAElF;;;;;;;;;;GAUG;AACU,QAAA,0BAA0B,GAAG,YAAY,CAAC;AAEvD,+FAA+F;AAC/F,MAAa,qBAAqB;IAEjB;IACA;IAFb,YACa,OAAe,EACf,OAAe;QADf,YAAO,GAAP,OAAO,CAAQ;QACf,YAAO,GAAP,OAAO,CAAQ;IACzB,CAAC;IAEJ,MAAM,CAAC,KAA4B;QAC/B,OAAO,IAAI,CAAC,OAAO,KAAK,KAAK,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,KAAK,KAAK,CAAC,OAAO,CAAC;IAC5E,CAAC;CACJ;AATD,sDASC;AAqBY,QAAA,SAAS,GAAG,kBAAkB,CAAC;AAC/B,QAAA,UAAU,GAAG,mBAAmB,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAa,mBAAmB;IAGf;IAEA;IAEA;IAQA;IAEA;IAYA;IAQA;IAEA;IAtCb,yDAAyD;IACzD,YACa,MAAc;IACvB,2EAA2E;IAClE,KAAa;IACtB,0EAA0E;IACjE,YAAoB;IAC7B;;;;;;OAMG;IACM,aAAqB;IAC9B,gGAAgG;IACvF,aAAgC;IACzC;;;;;;;;;;OAUG;IACM,UAAkB;IAC3B;;;;;;OAMG;IACM,UAAmB;IAC5B,wFAAwF;IAC/E,mBAA2B;QApC3B,WAAM,GAAN,MAAM,CAAQ;QAEd,UAAK,GAAL,KAAK,CAAQ;QAEb,iBAAY,GAAZ,YAAY,CAAQ;QAQpB,kBAAa,GAAb,aAAa,CAAQ;QAErB,kBAAa,GAAb,aAAa,CAAmB;QAYhC,eAAU,GAAV,UAAU,CAAQ;QAQlB,eAAU,GAAV,UAAU,CAAS;QAEnB,wBAAmB,GAAnB,mBAAmB,CAAQ;IACrC,CAAC;IAEJ,mDAAmD;IACnD,UAAU,CAAC,GAAW;QAClB,OAAO,GAAG,KAAK,iBAAS,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC;IACtE,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,GAAW;QACnB,OAAO,OAAO,IAAI,CAAC,UAAU,IAAI,kBAAW,KAAK,GAAG,EAAE,CAAC;IAC3D,CAAC;IAED,mEAAmE;IACnE,QAAQ,CAAC,GAAW;QAChB,OAAO,IAAI,qBAAqB,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;IAClF,CAAC;IAED,mEAAmE;IACnE,aAAa,CAAC,WAAmB;QAC7B,OAAO,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,IAAY,EAAU,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACxG,CAAC;CACJ;AAzED,kDAyEC;AAEY,QAAA,mBAAmB,GAAG,IAAI,mBAAmB,CACtD,aAAa,EAAE,aAAa,EAC5B,sBAAsB,EACtB,gCAAgC,EAChC,CAAC,uBAAuB,EAAE,6BAA6B,CAAC,EACxD,qBAAqB,EACrB,IAAI,EACJ,yCAAyC,CAC5C,CAAC;AAEF;;;;;;;;;GASG;AACU,QAAA,kBAAkB,GAAG,IAAI,mBAAmB,CACrD,OAAO,EAAE,OAAO,EAChB,aAAa,EACb,kBAAkB,EAClB,CAAC,mBAAmB,CAAC,EACrB,MAAM,EACN,KAAK,EACL,qCAAqC,CACxC,CAAC;AAEF;;;;;;GAMG;AACU,QAAA,qBAAqB,GAAmC,CAAC,2BAAmB,EAAE,0BAAkB,CAAC,CAAC;AAE/G;;;;;;;;;;GAUG;AACH,uHAAuH;AACvH,SAAgB,gBAAgB,CAAC,OAAe;IAC5C,OAAO,OAAO,CAAC,QAAQ,CAAC,kBAAW,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,oCAA4B,CAAC,CAAC;AAC3F,CAAC;AAED,uHAAuH;AACvH,SAAS,UAAU,CAAC,QAAwB;IACxC,OAAO,QAAQ,CAAC,KAAK,EAAE,UAAU,IAAI,EAAE,CAAC;AAC5C,CAAC;AAED,gGAAgG;AAChG,uHAAuH;AACvH,SAAgB,cAAc,CAAC,QAAwB;IACnD,MAAM,KAAK,GAA4B,EAAE,CAAC;IAC1C,KAAK,MAAM,KAAK,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QACvC,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;YAC7B,IAAI,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC;gBAAE,KAAK,CAAC,IAAI,CAAC,IAAI,qBAAqB,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;QAC3G,CAAC;IACL,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC;AAED;;;;GAIG;AACH,uHAAuH;AACvH,SAAgB,cAAc,CAAC,QAAwB;IACnD,MAAM,QAAQ,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAwB,EAAU,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IAC/F,OAAO,CAAC,kBAAU,EAAE,iBAAS,CAAC,CAAC,MAAM,CAAC,CAAC,GAAW,EAAW,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAS,EAAW,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAC5H,CAAC;AAED;;;;;;GAMG;AACH,oIAAoI;AACpI,SAAgB,eAAe,CAAC,OAA4B,EAAE,IAAuB;IACjF,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAW,EAAyB,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;AACnF,CAAC;AAED;;;;;;GAMG;AACH,uHAAuH;AACvH,SAAgB,iBAAiB,CAAC,OAA4B,EAAE,QAAwB;IACpF,MAAM,IAAI,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;IACtC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACpC,MAAM,IAAI,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;IACtC,MAAM,IAAI,GAAG,eAAe,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAC5C,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IAC7C,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,CAAwB,EAAW,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAwB,EAAW,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC5H,CAAC;AAED,6FAA6F;AAC7F,uHAAuH;AACvH,SAAgB,kBAAkB,CAAC,QAAwB;IACvD,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3C,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAC3B,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,MAAM,IAAI,GAAgB,EAAE,CAAC;IAC7B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC1B,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAc,EAAW,EAAE,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;QAC5F,IAAI,KAAK,CAAC,MAAM,KAAK,KAAK,CAAC,KAAK,CAAC,MAAM;YAAE,OAAO,GAAG,IAAI,CAAC;QACxD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;YAAE,IAAI,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;IACvE,CAAC;IACD,IAAI,OAAO;QAAE,QAAQ,CAAC,KAAM,CAAC,UAAU,GAAG,IAAI,CAAC;IAC/C,OAAO,OAAO,CAAC;AACnB,CAAC;AAED,mCAAmC;AACnC,uHAAuH;AACvH,SAAgB,YAAY,CAAC,QAAwB,EAAE,KAA4B;IAC/E,IAAI,CAAC,QAAQ,CAAC,KAAK;QAAE,QAAQ,CAAC,KAAK,GAAG,EAAE,CAAC;IACzC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,UAAU,CAAC;QAAE,QAAQ,CAAC,KAAK,CAAC,UAAU,GAAG,EAAE,CAAC;IAC9E,QAAQ,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC;AACrH,CAAC;AAED,mGAAmG;AACnG,uHAAuH;AACvH,SAAS,WAAW,CAAC,QAAwB;IACzC,kHAAkH;IAClH,MAAM,GAAG,GAAY,QAAQ,CAAC,GAAG,CAAC;IAClC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAC/E,OAAO,GAA6B,CAAC;AACzC,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,uHAAuH;AACvH,SAAgB,QAAQ,CAAC,QAAwB;IAC7C,IAAI,cAAc,CAAC,QAAQ,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACxD,MAAM,GAAG,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;IAClC,OAAO,GAAG,KAAK,IAAI,IAAI,GAAG,CAAC,8BAAgB,CAAC,KAAK,gCAAkB,CAAC;AACxE,CAAC;AAED;;;;;;;;;GASG;AACH,uHAAuH;AACvH,SAAgB,eAAe,CAAC,QAAwB;IACpD,MAAM,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;IACvC,IAAI,QAAQ,KAAK,IAAI,IAAI,QAAQ,CAAC,8BAAgB,CAAC,KAAK,gCAAkB;QAAE,OAAO,KAAK,CAAC;IACzF,MAAM,GAAG,GAAG,QAAQ,IAAI,EAAE,CAAC;IAC3B,GAAG,CAAC,8BAAgB,CAAC,GAAG,gCAAkB,CAAC;IAC3C,QAAQ,CAAC,GAAG,GAAG,GAAG,CAAC;IACnB,OAAO,IAAI,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,uHAAuH;AACvH,SAAgB,kBAAkB,CAAC,OAA4B,EAAE,QAAwB;IACrF,MAAM,IAAI,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;IACtC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACpC,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,iBAAiB,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,CAAC;QACvC,kBAAkB,CAAC,QAAQ,CAAC,CAAC;QAC7B,KAAK,MAAM,KAAK,IAAI,eAAe,CAAC,OAAO,EAAE,IAAI,CAAC;YAAE,YAAY,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QAClF,OAAO,GAAG,IAAI,CAAC;IACnB,CAAC;IACD,gGAAgG;IAChG,oGAAoG;IACpG,qEAAqE;IACrE,IAAI,OAAO,CAAC,UAAU,IAAI,eAAe,CAAC,QAAQ,CAAC;QAAE,OAAO,GAAG,IAAI,CAAC;IACpE,OAAO,OAAO,CAAC;AACnB,CAAC;AAED,uHAAuH;AACvH,SAAgB,YAAY,CAAC,YAAoB;IAC7C,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC;QAAE,OAAO,EAAE,CAAC;IAC5C,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IAClD,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,EAAE,CAAC;IACjC,8DAA8D;IAC9D,IAAI,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAmB,CAAC;IAC7C,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,IAAA,kBAAO,EAAC,GAAG,CAAC,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,GAAG,YAAY,2CAA2C,KAAK,CAAC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACjH,CAAC;AACL,CAAC;AAED,uHAAuH;AACvH,SAAgB,aAAa,CAAC,YAAoB,EAAE,QAAwB;IACxE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9D,EAAE,CAAC,aAAa,CAAC,YAAY,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;AAC7E,CAAC;AAED;;;;;;;;;;GAUG;AACH,oIAAoI;AACpI,SAAgB,mBAAmB,CAAC,OAA4B,EAAE,IAAmB;IACjF,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAChC,8DAA8D;IAC9D,IAAI,CAAC;QACD,OAAO,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAS,EAAW,EAAE,CAAC,iBAAiB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACjH,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,IAAA,kBAAO,EAAC,GAAG,CAAC,CAAC;QAC3B,KAAK,KAAK,CAAC,CAAC,2FAA2F;QACvG,OAAO,KAAK,CAAC;IACjB,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,oIAAoI;AACpI,SAAgB,UAAU,CAAC,IAAmB;IAC1C,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAChC,8DAA8D;IAC9D,IAAI,CAAC;QACD,OAAO,2BAAmB,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAS,EAAW,EAAE,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3G,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,IAAA,kBAAO,EAAC,GAAG,CAAC,CAAC;QAC3B,KAAK,KAAK,CAAC,CAAC,2FAA2F;QACvG,OAAO,KAAK,CAAC;IACjB,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,MAAa,cAAc;IAEV;IACA;IACA;IAHb,YACa,YAAoB,EACpB,YAAqB,EACrB,GAAY;QAFZ,iBAAY,GAAZ,YAAY,CAAQ;QACpB,iBAAY,GAAZ,YAAY,CAAS;QACrB,QAAG,GAAH,GAAG,CAAS;IACtB,CAAC;CACP;AAND,wCAMC;AAED;;;;;;GAMG;AACH,oIAAoI;AACpI,SAAgB,oBAAoB,CAAC,IAAY;IAC7C,MAAM,OAAO,GAAqB,EAAE,CAAC;IACrC,KAAK,MAAM,OAAO,IAAI,6BAAqB,EAAE,CAAC;QAC1C,KAAK,MAAM,YAAY,IAAI,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC;YACrD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC;gBAAE,SAAS;YAC3C,MAAM,QAAQ,GAAG,YAAY,CAAC,YAAY,CAAC,CAAC;YAC5C,MAAM,kBAAkB,GAAG,iBAAiB,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;YAChE,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,IAAI,QAAQ,CAAC,QAAQ,CAAC,CAAC;YAC3D,IAAI,CAAC,kBAAkB,CAAC,OAAO,EAAE,QAAQ,CAAC;gBAAE,SAAS;YACrD,aAAa,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;YACtC,OAAO,CAAC,IAAI,CAAC,IAAI,cAAc,CAAC,YAAY,EAAE,kBAAkB,EAAE,SAAS,CAAC,CAAC,CAAC;QAClF,CAAC;IACL,CAAC;IACD,OAAO,OAAO,CAAC;AACnB,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACU,QAAA,YAAY,GAAG,kBAAW,CAAC;AAC3B,QAAA,oBAAoB,GAAG,2BAAmB,CAAC,mBAAmB,CAAC;AAC/D,QAAA,0BAA0B,GAAG,0BAAkB,CAAC,mBAAmB,CAAC;AACpE,QAAA,WAAW,GAAG,6BAA6B,8BAAgB,EAAE,CAAC;AAE3E;;;;;;GAMG;AACH,oIAAoI;AACpI,SAAgB,mBAAmB,CAAC,IAAmB;IACnD,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,IAAA,yBAAkB,EAAC,IAAI,CAAC;QAAE,OAAO,CAAC,IAAI,CAAC,oBAAY,CAAC,CAAC;IACzD,KAAK,MAAM,OAAO,IAAI,6BAAqB,EAAE,CAAC;QAC1C,IAAI,mBAAmB,CAAC,OAAO,EAAE,IAAI,CAAC;YAAE,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACtF,CAAC;IACD,IAAI,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,CAAC,IAAI,CAAC,mBAAW,CAAC,CAAC;IAChD,OAAO,OAAO,CAAC;AACnB,CAAC","sourcesContent":["import * as fs from 'fs';\nimport * as path from 'path';\n\nimport { toError } from '../core/to-error';\nimport { AiType } from '../core/agent-event';\nimport { SHIM_MARKER, committedShimStale } from './shim';\nimport { BASH_CWD_ENV_KEY, BASH_CWD_ENV_VALUE } from './managed-env';\n\n/**\n * THE INSTALLED HOOK SURFACE — two hooks per harness, all ABSOLUTE, and the ONE place their spelling is\n * defined. See `HarnessRegistration` below, which is what makes \"per harness\" data rather than four\n * module constants that were only ever true of Claude Code.\n *\n * ─── ONE GOVERNOR: the MAIN tree judges every tree ─────────────────────────────────────────────────\n *\n *   Claude Code — .claude/settings.json\n *     H1  sh \"$CLAUDE_PROJECT_DIR/.claude/webpieces/ai-hook.sh\" wp-ai-guards-hook  Write|…|Bash|Read\n *     H2  sh \"$CLAUDE_PROJECT_DIR/.claude/webpieces/ai-hook.sh\" wp-ai-rules-hook   Write|Edit|MultiEdit\n *   Codex — .codex/hooks.json (the SAME `hooks.PreToolUse` JSON shape, measured)\n *     H1  sh \"$PWD/.claude/webpieces/ai-hook.sh\" wp-ai-guards-hook                 Bash|apply_patch\n *     H2  sh \"$PWD/.claude/webpieces/ai-hook.sh\" wp-ai-rules-hook                  apply_patch\n *\n * ONE shim file serves all four: `.claude/` there is a path, not a claim about who is calling.\n *\n * This REPLACES a three-hook form in which these two were RELATIVE (`sh \".claude/webpieces/ai-hook.sh\"`)\n * and a third hook, L-1 `guarantee-root.sh`, existed solely to guarantee that relative path resolved.\n *\n * ─── Why the relative experiment was reversed ──────────────────────────────────────────────────────\n * Relative registration was adopted so each git tree would be governed by \"its own release, binary and\n * pin\". MEASURED 2026-08-10: it never delivered that. A linked worktree has NO `node_modules`, so\n * ai-hook.sh's upward walk executes the PRIMARY's binary — `readlink -f` resolved a worktree agent's bin\n * to `<primary>/node_modules/@webpieces/ai-hook-rules`. A worktree ran its own SCRIPT and its own\n * CONFIG; it never ran its own release. Governance was already the primary's, in every tree, the whole\n * time.\n *\n * The price of that fiction was an entire guard layer. A relative path only resolves at a tree root, and\n * a hook that cannot resolve exits 127 — per the hooks reference a NON-BLOCKING error, i.e. a SILENT\n * UNGUARDED ALLOW. So L-1 had to deny every `cd` into a project subdirectory. That denial produced the\n * force-to-root bug class, the reaped-worktree `cd` prescription, and a measured hard deadlock: L-1 told\n * a worktree-isolated agent to `cd` to the primary clone, which the harness refuses for an isolated\n * agent, leaving it unable to stay or to follow the cure.\n *\n * An absolute path resolves from ANY cwd. So the launch guarantee is structural, L-1 has no job left and\n * is deleted, and `cd` into a subdirectory is simply allowed. What used to be true only by policing the\n * shell is now true by construction.\n *\n * ─── What replaces the property that was lost ──────────────────────────────────────────────────────\n * Nothing is lost that was ever delivered — but the case relative registration WANTED to handle (a tree\n * that genuinely needs a different @webpieces) is now DETECTED instead of silently mis-governed:\n * `VersionSyncGuard` (L1 row 8) blocks when a worktree's pin disagrees with the main tree's, and\n * prescribes either aligning the pins (same git hash → same tracked pin → install in each tree that has\n * a node_modules) or using a separate CLONE, which — unlike a worktree — gets its own GOVERNANCE. Note\n * what that does NOT say: a worktree may perfectly well have its own node_modules, and usually does the\n * moment anything installs in it. What it may not have is a DIFFERENT @webpieces version.\n *\n * ─── Why the registration is a DRIFT SURFACE, not just an install step ─────────────────────────────\n * Nothing used to validate `.claude/settings.json` at all, so a settings file left on a superseded form\n * silently changed who governs. The installed surface is THREE things (ai-hook.sh, the registration, and\n * the managed `env` entry — see managed-env.ts), all three are compared against this release, and\n * `wp-upgrade-shim` regenerates all three. A cure that fixes two of three is worse than no cure, because\n * it reports success.\n */\n\n/**\n * The RETIRED L-1 hook's committed path. Named here, in the one module that must still recognise it, and\n * matched ONLY by isManagedCommand() so repairRegistration() can delete the stale entry. There is no\n * guarantee-root.ts any more — this literal is all that remains of it, deliberately.\n *\n * It is a one-way RECOGNISER, not a shim: nothing emits it, `expectedEntries()` never returns it, and a\n * settings file carrying it is reported STALE. Its only job is to make the retired entry findable so it\n * can be REMOVED.\n */\nexport const LEGACY_GUARANTEE_ROOT_MARKER = '.claude/webpieces/guarantee-root.sh';\n\n/**\n * When this recogniser may be deleted, as a value rather than a comment nobody re-reads.\n *\n * A removal-only migration is still dead weight once no consumer can be carrying the old shape. The\n * hazard of deleting it EARLY is severe and silent — repair would stop stripping the retired entry, and\n * a hook registered against a deleted file exits 127, which the Claude Code hooks reference defines as a\n * NON-BLOCKING error, i.e. every `cd` unjudged while the cure reports success. So it gets a stated date\n * and a test that fails once the date passes, instead of an intention.\n *\n * `legacy-marker-expiry.spec.ts` reads this and fails after it, which is the reminder.\n */\nexport const LEGACY_MARKER_REMOVE_AFTER = '2026-12-01';\n\n/** One PreToolUse hook entry as webpieces registers it. Data-only → a class, per CLAUDE.md. */\nexport class HookRegistrationEntry {\n    constructor(\n        readonly matcher: string,\n        readonly command: string,\n    ) {}\n\n    sameAs(other: HookRegistrationEntry): boolean {\n        return this.matcher === other.matcher && this.command === other.command;\n    }\n}\n\n// webpieces-disable no-any-unknown -- settings.json is opaque consumer JSON\nexport interface HookCommand { type: string; command: string; }\nexport interface HookEntry { matcher: string; hooks: HookCommand[]; }\n/**\n * One settings file as webpieces reads it. MEASURED: Codex's `.codex/hooks.json` uses the IDENTICAL\n * `hooks.PreToolUse[].hooks[].command` shape, so one reader, one writer and one repair serve both files\n * — the difference between the harnesses is entirely in the VALUES (matcher, shim anchor), which is what\n * `HarnessRegistration` carries. The `env` block below is Claude Code's alone.\n */\nexport interface ClaudeSettings {\n    hooks?: { PreToolUse?: HookEntry[] };\n    // Claude Code's settings `env` block: every key is exported into the environment of the session AND\n    // of every subagent it spawns. That inheritance is precisely why webpieces pins its managed entry\n    // here rather than in a shell profile — see managed-env.ts.\n    env?: Record<string, string>;\n    // webpieces-disable no-any-unknown -- opaque settings bag; arbitrary keys allowed\n    [key: string]: unknown;\n}\n\nexport const RULES_BIN = 'wp-ai-rules-hook';\nexport const GUARDS_BIN = 'wp-ai-guards-hook';\n\n/**\n * ONE HARNESS'S registration surface — where its hooks live, what they match, and how they name the\n * shim. Data-only → a class, per CLAUDE.md.\n *\n * ─── Why this exists ──────────────────────────────────────────────────────────────────────────────\n * The matchers and the shim command used to be four module constants written for Claude Code alone.\n * Applied to Codex they are wrong in both halves, and the way they are wrong is SILENT:\n *\n *   - MATCHER. Codex's file-editing tool is `apply_patch` (MEASURED, codex-cli 0.151.0). A matcher of\n *     `Write|Edit|MultiEdit` matches it never, so every file rule is unreachable while the settings file\n *     looks perfectly installed. Its shell tool IS called `Bash` — Codex reuses Claude's name — which is\n *     the trap: half the matcher works, so the hooks appear to be running.\n *   - ANCHOR. `$CLAUDE_PROJECT_DIR` does not exist in a Codex hook's environment (measured: 46 vars, no\n *     such key), so the command expands to `sh \"/.claude/webpieces/ai-hook.sh\"`, which dies — and per the\n *     hooks protocol a non-2 non-zero exit is a NON-BLOCKING error, i.e. a silent unguarded allow.\n *\n * Both halves of that were live in real repos, written by a Codex Desktop sync that transliterated the\n * Claude setup. Making the registration per-harness DATA is what stops a future harness inheriting a\n * matcher that was never true for it.\n *\n * ─── ONE SHIM, both harnesses ─────────────────────────────────────────────────────────────────────\n * `SHIM_MARKER` is shared deliberately: `.claude/webpieces/ai-hook.sh` is the single fail-closed entry\n * point, and moving or duplicating it would double the L0 allowlist regexes, the drift surfaces and the\n * cures. The `.claude/` prefix is a path, not a claim about which agent is calling.\n */\nexport class HarnessRegistration {\n    // eslint-disable-next-line @typescript-eslint/max-params\n    constructor(\n        readonly aiType: AiType,\n        /** How the installer and the drift report name this harness to a human. */\n        readonly label: string,\n        /** Which tool names the RULES hook (code-style, file-scoped) must see. */\n        readonly rulesMatcher: string,\n        /**\n         * Which tool names the GUARDS hook must see. Wider than the rules matcher by the shell tool and,\n         * for Claude Code, by `Read` — Read carries no guard, but the guards hook owns the\n         * per-invocation audit log, so matching it records every file the AI opens (log-and-allow fast\n         * path in hook-core.ts; a Read is never blocked). Codex has no Read tool at all: a read arrives\n         * as `Bash` running a pager, which the shell matcher already covers and read-parity synthesizes.\n         */\n        readonly guardsMatcher: string,\n        /** The settings files this harness's hooks can be installed into, relative to the repo root. */\n        readonly settingsFiles: readonly string[],\n        /**\n         * THE PREFIX THE SHIM PATH IS ANCHORED ON, and the reason each harness needs its own.\n         *\n         * **BYTE-STABILITY IS A HARD CONSTRAINT ON THE CODEX VALUE.** Codex trusts a hook entry\n         * TOFU — `~/.codex/config.toml` records a `trusted_hash` per entry — so ANY change to these bytes\n         * invalidates that trust and re-prompts the human, whose third option is `Continue without\n         * trusting (hooks won't run)`: one keystroke to a silently unguarded session. Changing this\n         * string is therefore never a cosmetic edit. The hash is NOT reproducible from outside Codex\n         * (16 encodings tried against a file we authored), so the installer can never repair trust for\n         * itself — see ./codex-trust.ts, which REPORTS and never writes.\n         */\n        readonly shimAnchor: string,\n        /**\n         * True when this harness's settings file also carries the managed `env` block. Claude Code's\n         * settings `env` is inherited by every subagent, which is what makes it the right home for the\n         * Bash-cwd pin (see managed-env.ts). Codex has no equivalent surface — and needs none: its cwd\n         * is MEASURED not to drift at all (`cd x && pwd` prints x, the next call is back at the repo\n         * root, for the coordinator and for subagents alike).\n         */\n        readonly managesEnv: boolean,\n        /** What `managedSurfaceDrift()` calls this harness's registration when it has moved. */\n        readonly registrationSurface: string,\n    ) {}\n\n    /** Which matcher one guard bin registers under. */\n    matcherFor(bin: string): string {\n        return bin === RULES_BIN ? this.rulesMatcher : this.guardsMatcher;\n    }\n\n    /**\n     * The guard-hook command — `sh \"<anchor>/.claude/webpieces/ai-hook.sh\" <bin>`.\n     *\n     * ABSOLUTE, in both harnesses. Claude's anchor replaced a RELATIVE spelling and that reversal is\n     * documented at length in this file's header: relative resolves only at a tree root, a hook that\n     * cannot resolve exits 127, and per the hooks reference that is a NON-BLOCKING error — a silent\n     * unguarded allow. It also cost an entire guard layer (L-1) whose only job was to police the `cd`\n     * that made the relative path resolvable.\n     *\n     * Invoked via `sh <file>` rather than executed directly so a missing executable bit on the\n     * checked-in shim (fresh clone, a filesystem that drops the bit, git core.fileMode quirks) can never\n     * break the hook with a raw `Permission denied` on every tool call. Quoted to survive spaces.\n     */\n    shimCommand(bin: string): string {\n        return `sh \"${this.shimAnchor}/${SHIM_MARKER}\" ${bin}`;\n    }\n\n    /** The registration entry for one guard bin under this harness. */\n    entryFor(bin: string): HookRegistrationEntry {\n        return new HookRegistrationEntry(this.matcherFor(bin), this.shimCommand(bin));\n    }\n\n    /** This harness's settings files under one repo root, absolute. */\n    settingsPaths(projectRoot: string): readonly string[] {\n        return this.settingsFiles.map((file: string): string => path.join(projectRoot, ...file.split('/')));\n    }\n}\n\nexport const CLAUDE_REGISTRATION = new HarnessRegistration(\n    'claude-code', 'Claude Code',\n    'Write|Edit|MultiEdit',\n    'Write|Edit|MultiEdit|Bash|Read',\n    ['.claude/settings.json', '.claude/settings.local.json'],\n    '$CLAUDE_PROJECT_DIR',\n    true,\n    '.claude/settings.json hook registration',\n);\n\n/**\n * Codex's registration, every value of it MEASURED against codex-cli 0.151.0 rather than assumed.\n *\n * `$PWD` is the anchor because there is no project-dir variable to use and none is needed: the payload\n * `cwd` and the hook process's own `PWD` are both the repo root on EVERY call — for the coordinator and\n * for subagents — and a `cd` inside one command never survives into the next. That was measured, not\n * hoped for, and it is the same effect Claude Code gets from the managed\n * `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR` env entry. See `shimAnchor` for why these exact bytes are\n * not free to change.\n */\nexport const CODEX_REGISTRATION = new HarnessRegistration(\n    'codex', 'Codex',\n    'apply_patch',\n    'Bash|apply_patch',\n    ['.codex/hooks.json'],\n    '$PWD',\n    false,\n    '.codex/hooks.json hook registration',\n);\n\n/**\n * Every harness webpieces arms, in installer order.\n *\n * The drift check, the repair and the installer all iterate THIS, so a harness cannot be armed by the\n * installer and then left unvalidated — which is exactly the state `.codex/hooks.json` was in before it\n * was a managed surface: written by something else, silently wrong, and invisible to every check.\n */\nexport const HARNESS_REGISTRATIONS: readonly HarnessRegistration[] = [CLAUDE_REGISTRATION, CODEX_REGISTRATION];\n\n/**\n * True when this PreToolUse command is one webpieces owns — in ANY spelling it has ever shipped.\n *\n * THE SINGLE MOST IMPORTANT LINE IN THIS RELEASE. `LEGACY_GUARANTEE_ROOT_MARKER` is matched here and\n * NOWHERE else: it is how `repairRegistration()` finds and REMOVES the retired H1 entry from a settings\n * file written by an older release. Drop it and the repair silently leaves a live L-1 hook registered\n * against a file this release deletes — exit 127, which the Claude Code hooks reference defines as a\n * NON-BLOCKING error, so every `cd` goes unjudged while `wp-upgrade-shim` reports success and no drift\n * check can name it. Removal-only, never emitted: it appears in no `expectedEntries()` result, so it is\n * a one-way migration and not a second accepted spelling.\n */\n// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above\nexport function isManagedCommand(command: string): boolean {\n    return command.includes(SHIM_MARKER) || command.includes(LEGACY_GUARANTEE_ROOT_MARKER);\n}\n\n// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above\nfunction preToolUse(settings: ClaudeSettings): readonly HookEntry[] {\n    return settings.hooks?.PreToolUse ?? [];\n}\n\n/** Every webpieces-managed entry of one settings file, flattened to matcher + command pairs. */\n// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above\nexport function managedEntries(settings: ClaudeSettings): readonly HookRegistrationEntry[] {\n    const found: HookRegistrationEntry[] = [];\n    for (const entry of preToolUse(settings)) {\n        for (const hook of entry.hooks) {\n            if (isManagedCommand(hook.command)) found.push(new HookRegistrationEntry(entry.matcher, hook.command));\n        }\n    }\n    return found;\n}\n\n/**\n * Which guard bins this settings file registers, in installer order. A file registering NEITHER is not\n * a project (relative) install and is therefore never judged — a global/absolute install names the bin\n * path directly and carries no shim marker at all.\n */\n// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above\nexport function registeredBins(settings: ClaudeSettings): readonly string[] {\n    const commands = managedEntries(settings).map((e: HookRegistrationEntry): string => e.command);\n    return [GUARDS_BIN, RULES_BIN].filter((bin: string): boolean => commands.some((c: string): boolean => c.includes(bin)));\n}\n\n/**\n * The exact set of entries THIS RELEASE expects in a settings file that registers `bins`.\n *\n * ONE entry per registered bin, and nothing else. There used to be a third, `guarantee-root.sh`, added\n * whenever the GUARDS bin was present; it is retired, and a settings file still carrying it is STALE —\n * `repairRegistration()` removes it via isManagedCommand()'s legacy marker.\n */\n// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as HarnessRegistration's siblings\nexport function expectedEntries(harness: HarnessRegistration, bins: readonly string[]): readonly HookRegistrationEntry[] {\n    return bins.map((bin: string): HookRegistrationEntry => harness.entryFor(bin));\n}\n\n/**\n * True when a settings file registers webpieces hooks in a shape this release does not expect: a\n * RELATIVE shim command, a leftover guarantee-root entry, a stray duplicate, or a wrong matcher.\n *\n * Compared as a SET, not a sequence: Claude Code runs all matching hooks in parallel, so array order\n * carries no meaning and reordering must not read as drift.\n */\n// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above\nexport function registrationStale(harness: HarnessRegistration, settings: ClaudeSettings): boolean {\n    const bins = registeredBins(settings);\n    if (bins.length === 0) return false;\n    const have = managedEntries(settings);\n    const want = expectedEntries(harness, bins);\n    if (have.length !== want.length) return true;\n    return want.some((w: HookRegistrationEntry): boolean => !have.some((h: HookRegistrationEntry): boolean => h.sameAs(w)));\n}\n\n/** Drop every webpieces-managed PreToolUse command; returns true if anything was removed. */\n// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above\nexport function dropManagedEntries(settings: ClaudeSettings): boolean {\n    const entries = settings.hooks?.PreToolUse;\n    if (!entries) return false;\n    let changed = false;\n    const kept: HookEntry[] = [];\n    for (const entry of entries) {\n        const hooks = entry.hooks.filter((h: HookCommand): boolean => !isManagedCommand(h.command));\n        if (hooks.length !== entry.hooks.length) changed = true;\n        if (hooks.length > 0) kept.push({ matcher: entry.matcher, hooks });\n    }\n    if (changed) settings.hooks!.PreToolUse = kept;\n    return changed;\n}\n\n/** Append one PreToolUse entry. */\n// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above\nexport function addHookEntry(settings: ClaudeSettings, entry: HookRegistrationEntry): void {\n    if (!settings.hooks) settings.hooks = {};\n    if (!Array.isArray(settings.hooks.PreToolUse)) settings.hooks.PreToolUse = [];\n    settings.hooks.PreToolUse.push({ matcher: entry.matcher, hooks: [{ type: 'command', command: entry.command }] });\n}\n\n/** The settings `env` block, or null when the file carries none (or carries junk in its place). */\n// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above\nfunction settingsEnv(settings: ClaudeSettings): Record<string, string> | null {\n    // webpieces-disable no-any-unknown -- settings.json is opaque consumer JSON; `env` is only typed after this check\n    const env: unknown = settings.env;\n    if (typeof env !== 'object' || env === null || Array.isArray(env)) return null;\n    return env as Record<string, string>;\n}\n\n/**\n * True when a settings file that registers webpieces hooks is missing the managed `env` entry, or\n * carries any value other than the one required one.\n *\n * Gated on `registeredBins()` for the SAME reason `registrationStale()` is: a settings file that\n * registers no webpieces hooks is not a project install and is never judged — a global install names\n * the bin path directly and carries no shim marker at all, so there is nothing here to keep in step.\n *\n * NOTE what this entry is for NOW. It was originally justified by keeping the then-RELATIVE hook path\n * resolvable; that job is retired, because both hooks are absolute and resolve from any cwd. It is kept\n * for VERDICT STABILITY — a guard's answer must depend on the command, not on where an earlier `cd` left\n * the shell — and because settings `env` is inherited, every subagent shares that cwd and therefore that\n * verdict. See managed-env.ts, which states this at length.\n */\n// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above\nexport function envStale(settings: ClaudeSettings): boolean {\n    if (registeredBins(settings).length === 0) return false;\n    const env = settingsEnv(settings);\n    return env === null || env[BASH_CWD_ENV_KEY] !== BASH_CWD_ENV_VALUE;\n}\n\n/**\n * Set the managed `env` entry IN PLACE, whatever was there before. Returns true when it changed.\n *\n * A user-set `\"0\"` is BROUGHT TO `\"1\"`, not honoured: this is a managed surface, and \"webpieces sets it\n * unless you disagreed\" would be a second, invisible spelling of the decision. Turning it off means\n * uninstalling the hooks, exactly as it does for every other managed thing.\n *\n * UNGATED on purpose — the installer calls it for the file it is writing hooks into, and the gate lives\n * at the caller (repairRegistration / applyHook), so a file with no webpieces hooks is never touched.\n */\n// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above\nexport function applyManagedEnv(settings: ClaudeSettings): boolean {\n    const existing = settingsEnv(settings);\n    if (existing !== null && existing[BASH_CWD_ENV_KEY] === BASH_CWD_ENV_VALUE) return false;\n    const env = existing ?? {};\n    env[BASH_CWD_ENV_KEY] = BASH_CWD_ENV_VALUE;\n    settings.env = env;\n    return true;\n}\n\n/**\n * Bring one settings object to the two-hook ABSOLUTE form AND the managed `env` entry IN PLACE. Returns\n * true when it changed anything.\n *\n * REMOVE-then-ADD for the hooks, never add-beside: two spellings of one registration is exactly the\n * compatibility shim the backwards-compat reviewer rejects, and leaving a RELATIVE entry beside the\n * absolute one would run two shims per call — the\n * straddle this whole change exists to delete.\n *\n * THE TWO REPAIRS ARE EVALUATED INDEPENDENTLY, and that is load-bearing rather than tidy: this used to\n * early-return on `!registrationStale(settings)`, so a repo whose hooks are already current but whose\n * `env` entry is missing — the state EVERY existing consumer is in the moment this release lands — would\n * have been reported as drifted by fault S and then left unrepaired by its own prescribed cure. A cure\n * that skips half the surface is the failure mode `upgrade-shim.ts`'s header exists to prevent.\n */\n// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above\nexport function repairRegistration(harness: HarnessRegistration, settings: ClaudeSettings): boolean {\n    const bins = registeredBins(settings);\n    if (bins.length === 0) return false;\n    let changed = false;\n    if (registrationStale(harness, settings)) {\n        dropManagedEntries(settings);\n        for (const entry of expectedEntries(harness, bins)) addHookEntry(settings, entry);\n        changed = true;\n    }\n    // Only where the harness HAS that surface. Codex's hooks.json has no `env` block to manage, and\n    // inventing one there would write a key Codex does not read — a managed surface nothing consumes is\n    // a surface that can drift with no consequence and no way to notice.\n    if (harness.managesEnv && applyManagedEnv(settings)) changed = true;\n    return changed;\n}\n\n// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above\nexport function readSettings(settingsPath: string): ClaudeSettings {\n    if (!fs.existsSync(settingsPath)) return {};\n    const raw = fs.readFileSync(settingsPath, 'utf8');\n    if (raw.trim() === '') return {};\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        return JSON.parse(raw) as ClaudeSettings;\n    } catch (err: unknown) {\n        const error = toError(err);\n        throw new Error(`${settingsPath} has invalid JSON — fix it, then retry: ${error.message}`, { cause: error });\n    }\n}\n\n// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as shimCommand above\nexport function writeSettings(settingsPath: string, settings: ClaudeSettings): void {\n    fs.mkdirSync(path.dirname(settingsPath), { recursive: true });\n    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 4) + '\\n');\n}\n\n/**\n * True when any settings file ONE HARNESS owns under `root` carries a stale registration.\n *\n * Per harness, not per repo, so the drift report can NAME which one moved — `.claude/settings.json` and\n * `.codex/hooks.json` have different cures, and a fault that says only \"the registration is stale\" sends\n * the reader to the wrong file half the time.\n *\n * A file that does not exist, or exists and registers no webpieces hooks, is never judged (see\n * `registrationStale`). That is what keeps a repo which has never armed Codex from suddenly faulting on\n * a `.codex/hooks.json` it does not have.\n */\n// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as HarnessRegistration's siblings\nexport function registrationStaleAt(harness: HarnessRegistration, root: string | null): boolean {\n    if (root === null) return false;\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        return harness.settingsPaths(root).some((p: string): boolean => registrationStale(harness, readSettings(p)));\n    } catch (err: unknown) {\n        const error = toError(err);\n        void error; // best-effort: unreadable/invalid settings counts as \"not stale\" so it never wedges a call\n        return false;\n    }\n}\n\n/**\n * True when either Claude project settings file under `root` is missing the managed `env` entry.\n *\n * CLAUDE-ONLY by construction, and stated as such rather than looped over the harnesses: `env` is a\n * Claude Code settings surface, Codex has no equivalent, and Codex's cwd is measured not to drift, which\n * is the whole thing the entry is for. See HarnessRegistration.managesEnv.\n */\n// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as HarnessRegistration's siblings\nexport function envStaleAt(root: string | null): boolean {\n    if (root === null) return false;\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        return CLAUDE_REGISTRATION.settingsPaths(root).some((p: string): boolean => envStale(readSettings(p)));\n    } catch (err: unknown) {\n        const error = toError(err);\n        void error; // best-effort: unreadable/invalid settings counts as \"not stale\" so it never wedges a call\n        return false;\n    }\n}\n\n/**\n * WHAT was rewritten in ONE settings file. Data-only → a class, per CLAUDE.md.\n *\n * Two independent flags rather than one path, because the cure has to be able to SAY which repair it\n * made: \"rewrote the hook registration\" printed for a file whose registration was already current and\n * whose `env` entry was the only thing missing is a cure lying about its own work.\n */\nexport class SettingsRepair {\n    constructor(\n        readonly settingsPath: string,\n        readonly registration: boolean,\n        readonly env: boolean,\n    ) {}\n}\n\n/**\n * Rewrite every stale settings file under `root`, for EVERY harness; returns what changed, per file.\n *\n * Existing files only — this never CREATES a registration. Arming a harness is the installer's decision\n * (`wp-install-ai-hooks`); this is the cure for one that has already been armed and has drifted, so a\n * repo that has never armed Codex is left exactly as it was.\n */\n// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as HarnessRegistration's siblings\nexport function repairRegistrationAt(root: string): readonly SettingsRepair[] {\n    const repairs: SettingsRepair[] = [];\n    for (const harness of HARNESS_REGISTRATIONS) {\n        for (const settingsPath of harness.settingsPaths(root)) {\n            if (!fs.existsSync(settingsPath)) continue;\n            const settings = readSettings(settingsPath);\n            const neededRegistration = registrationStale(harness, settings);\n            const neededEnv = harness.managesEnv && envStale(settings);\n            if (!repairRegistration(harness, settings)) continue;\n            writeSettings(settingsPath, settings);\n            repairs.push(new SettingsRepair(settingsPath, neededRegistration, neededEnv));\n        }\n    }\n    return repairs;\n}\n\n/**\n * The names the drift check reports, so a deny can say WHICH surface moved.\n *\n * There were four, then three, and there are now FOUR again — but the fourth is not the one that was\n * deleted. `GUARANTEE_ROOT_SURFACE` went with L-1 itself: an absolutely-registered shim resolves from\n * any cwd, so there is no launch guarantee left to police and no second .sh file to keep byte-locked. A\n * settings file still carrying the retired H1 entry is not its own surface — it is ordinary REGISTRATION\n * drift, which `registrationStaleAt()` reports and `repairRegistration()` fixes by removing it.\n *\n * The new fourth is `.codex/hooks.json`, and it is here because of what happened while it was NOT a\n * managed surface: something else wrote it, with a matcher that matched no Codex file tool and a shim\n * path anchored on a variable Codex does not set, and no check in this package could see it. A file the\n * guards depend on and nothing validates is the exact shape of that incident.\n *\n * Each harness's registration surface is its own name, from HarnessRegistration.registrationSurface, so\n * the deny sends the reader to the file that actually moved.\n */\nexport const SHIM_SURFACE = SHIM_MARKER;\nexport const REGISTRATION_SURFACE = CLAUDE_REGISTRATION.registrationSurface;\nexport const CODEX_REGISTRATION_SURFACE = CODEX_REGISTRATION.registrationSurface;\nexport const ENV_SURFACE = `.claude/settings.json env.${BASH_CWD_ENV_KEY}`;\n\n/**\n * WHICH of the managed surfaces disagree with this release — the input to fault S.\n *\n * All of them are checked against the SAME root, resolved from the RUNNING MODULE (governingShimRoot),\n * never from cwd and never from `$CLAUDE_PROJECT_DIR`: the files we compare and the renderers we\n * compare them TO must come from one install, or the check straddles two trees and can never converge.\n */\n// webpieces-disable no-function-outside-class -- module-scope for the same dependency-free reason as HarnessRegistration's siblings\nexport function managedSurfaceDrift(root: string | null): readonly string[] {\n    const drifted: string[] = [];\n    if (committedShimStale(root)) drifted.push(SHIM_SURFACE);\n    for (const harness of HARNESS_REGISTRATIONS) {\n        if (registrationStaleAt(harness, root)) drifted.push(harness.registrationSurface);\n    }\n    if (envStaleAt(root)) drifted.push(ENV_SURFACE);\n    return drifted;\n}\n"]}