@lannguyensi/harness 0.64.0 → 1.0.0

package/dist/cli/apply/install-codex-config.js

@@ -4,9 +4,34 @@ import * as path from "node:path";
 import { parse as parseTomlDocument, TomlError } from "smol-toml";
 import { atomicWriteFile } from "../../io/atomic-write.js";
 import { EX_FAIL, HarnessExitError } from "../exit-codes.js";
+// Import cycle: codex-snapshot.ts imports this module too. It is safe because
+// neither module touches the other's bindings at top level; they are used only
+// inside function bodies. Keep it that way (no top-level use of these three).
+import { codexConfigFlag, listCodexSnapshots, nameInstallConfig, readCodexSnapshot, retireCodexSnapshot, } from "../gate/codex-snapshot.js";
+import { kernelEntry, linkChain, walkLinkChain } from "../gate/link-chain.js";
+import { namesSameEntry, sha256Hex } from "../gate/snapshot.js";
 export const CODEX_MANAGED_SOURCE_PREFIX = "# Harness Codex hook wiring.";
 export const CODEX_MANAGED_BEGIN = "# BEGIN harness-managed codex hooks";
 export const CODEX_MANAGED_END = "# END harness-managed codex hooks";
+/**
+ * The comment line the installer writes directly under the BEGIN fence,
+ * followed by the block's generation: the sha256 of the generated content
+ * the block holds (`codexBlockGeneration`). `harness gate disable --runtime
+ * codex` records it in its snapshot, and a snapshot whose recorded generation
+ * differs from the block's is one a later install re-rendered the block over:
+ * it is retired as superseded and never applied, wherever it sits and whatever
+ * backup files exist. A comment adds, removes and reorders no hook entry, so
+ * Codex keeps every hook at the position its trust state was recorded for.
+ * The same content renders the same line, so an install of an unchanged
+ * manifest stays a no-op.
+ */
+export const CODEX_BLOCK_GENERATION_PREFIX = "# harness block generation: ";
+const BLOCK_GENERATION_LINE_RE = /^# harness block generation: ([0-9a-f]{64})$/;
+/** The generation of a block holding `renderedContent` (the generated
+ * content as the block holds it, without its trailing newline). */
+function codexBlockGeneration(renderedContent) {
+    return sha256Hex(renderedContent);
+}
 /**
  * Thrown instead of a plain `Error` when the install refuses rather than
  * guesses (a duplicate/moved BEGIN marker, or a foreign table wedged
@@ -1159,10 +1184,12 @@ function ensureTrailingNewline(s) {
     return s.endsWith("\n") ? s : `${s}\n`;
 }
 function buildManagedBlock(generatedContent, generatedPath) {
+    const rendered = ensureTrailingNewline(generatedContent).trimEnd();
     return [
         `${CODEX_MANAGED_SOURCE_PREFIX} Generated source: ${generatedPath}`,
         CODEX_MANAGED_BEGIN,
-        ensureTrailingNewline(generatedContent).trimEnd(),
+        `${CODEX_BLOCK_GENERATION_PREFIX}${codexBlockGeneration(rendered)}`,
+        rendered,
         CODEX_MANAGED_END,
         "",
     ].join("\n");
@@ -1391,40 +1418,6 @@ export function assertConfigSemanticInvariant(currentContent, nextContent, confi
             "(if one exists), or file an issue with the config shape that triggered this.", configPath);
     }
 }
-/**
- * Follows a dangling link chain hop by hop with `readlink` and returns the
- * first path in it that does not exist, so a dangling refusal names the
- * missing file rather than the first hop (which may be an existing
- * intermediate link). Each relative link text is resolved against the
- * physical directory of the link holding it, as the kernel does. Returns
- * undefined when the chain cannot be walked (it changed under us, or a
- * hop is not readable); the caller then words the refusal generically.
- */
-function missingEndOfLinkChain(start) {
-    const MAX_HOPS = 40;
-    let current = start;
-    for (let hop = 0; hop < MAX_HOPS; hop++) {
-        let next;
-        try {
-            const linkText = fs.readlinkSync(current);
-            next = path.resolve(fs.realpathSync(path.dirname(current)), linkText);
-        }
-        catch {
-            return undefined;
-        }
-        let nextStat;
-        try {
-            nextStat = fs.lstatSync(next);
-        }
-        catch (err) {
-            return err.code === "ENOENT" ? next : undefined;
-        }
-        if (!nextStat.isSymbolicLink())
-            return undefined;
-        current = next;
-    }
-    return undefined;
-}
 /**
  * Resolves a symlinked config path to the regular file it points at (task
  * 1637fbc8). `atomicWriteFile` renames a temp file over its destination,
@@ -1433,9 +1426,13 @@ function missingEndOfLinkChain(start) {
  * resolved target instead keeps the link intact. A non-symlink path
  * (including a missing one) is returned unchanged. A dangling link, an
  * unresolvable chain (a loop, a permission error) or a link to anything
- * other than a regular file is refused before anything is written.
+ * other than a regular file is refused before anything is written. The
+ * chain is walked as the kernel walks it (`walkLinkChain`): a `..` after a
+ * directory link climbs out of the directory that link leads to, so the file
+ * written is the one a read through the path gives. The path itself is taken
+ * as given; a caller passes a spelling with `..` through `kernelEntry` first.
  */
-function resolveConfigSymlink(requestedPath) {
+export function resolveConfigSymlink(requestedPath) {
     let linkStat;
     try {
         linkStat = fs.lstatSync(requestedPath);
@@ -1448,24 +1445,41 @@ function resolveConfigSymlink(requestedPath) {
     }
     if (!linkStat.isSymbolicLink())
         return requestedPath;
-    let resolved;
+    // The gate's link walker decides where the chain ends, resolving every hop
+    // as the kernel does. The JavaScript realpath folds `d/..` before it looks at
+    // `d`: on its own it would call a link that reaches a file dangling, refuse
+    // one the kernel resolves, or resolve one that reaches nothing to another
+    // file. The refusal names the end of the chain, not the first hop (which may
+    // be an existing link).
+    const walked = walkLinkChain(requestedPath);
+    if (walked.end === "dangling") {
+        throw new CodexInstallRefusalError(`Codex config ${requestedPath} is a dangling symlink (its link chain ends at ` +
+            `${walked.chain[walked.chain.length - 1]}, which does not exist); refusing to install, ` +
+            `nothing was written. Create the link's target file (or point the link at an ` +
+            `existing config) and re-run.`, requestedPath);
+    }
+    const cannotResolve = (cause) => new CodexInstallRefusalError(`Codex config ${requestedPath} is a symlink that cannot be resolved (${cause}); ` +
+        `refusing to install, nothing was written. Fix the link chain and re-run.`, requestedPath);
+    // The kernel's own lookup of the path is what Codex reads through.
+    let read;
     try {
-        resolved = fs.realpathSync(requestedPath);
+        read = fs.statSync(requestedPath);
     }
     catch (err) {
         const e = err;
-        if (e.code === "ENOENT") {
-            const missing = missingEndOfLinkChain(requestedPath);
-            throw new CodexInstallRefusalError(`Codex config ${requestedPath} is a dangling symlink (its link chain ends at ` +
-                `${missing ?? "a missing file"}, which does not exist); refusing to install, ` +
-                `nothing was written. Create the link's target file (or point the link at an ` +
-                `existing config) and re-run.`, requestedPath);
-        }
-        throw new CodexInstallRefusalError(`Codex config ${requestedPath} is a symlink that cannot be resolved ` +
-            `(${e.code ?? "error"}: ${e.message}); refusing to install, nothing was written. ` +
-            `Fix the link chain and re-run.`, requestedPath);
-    }
-    if (!fs.statSync(resolved).isFile()) {
+        throw cannotResolve(`${e.code ?? "error"}: ${e.message}`);
+    }
+    if (walked.end !== "target")
+        throw cannotResolve(`the link chain ends in a ${walked.end}`);
+    const resolved = walked.chain[walked.chain.length - 1] ?? requestedPath;
+    const atEnd = fs.statSync(resolved);
+    // Defence in depth: the walker and the kernel have to agree on the file, and
+    // a disagreement of any kind (a walker defect, a platform difference in how
+    // a text is read) would otherwise write a file Codex never reads.
+    if (read.dev !== atEnd.dev || read.ino !== atEnd.ino) {
+        throw cannotResolve(`a read through it reaches another file than ${resolved}`);
+    }
+    if (!atEnd.isFile()) {
         throw new CodexInstallRefusalError(`Codex config ${requestedPath} is a symlink to ${resolved}, which is not a regular ` +
             `file; refusing to install, nothing was written. Point the link at a config file and re-run.`, requestedPath);
     }
@@ -1729,8 +1743,24 @@ function assertKeptHookTablesAreOperatorOwned(kept, currentContent, generatedCon
     }
 }
 export function planCodexConfigInstall(opts) {
+    try {
+        return planCodexConfigInstallUnnamed(opts);
+    }
+    catch (err) {
+        // Every refusal below names the bare install command; the call's config
+        // is added here, once, where it is known.
+        if (err instanceof CodexInstallRefusalError && opts.configPath !== undefined) {
+            throw new CodexInstallRefusalError(nameInstallConfig(err.message, kernelEntry(opts.configPath)), err.configPath);
+        }
+        throw err;
+    }
+}
+function planCodexConfigInstallUnnamed(opts) {
     validateCodexManagedConfig(opts.generatedContent);
-    const requestedPath = opts.configPath ?? defaultCodexConfigPath(opts.homeDir);
+    // A `..` after a directory link leads elsewhere than a lexical fold of the
+    // spelling: every path built from it (the temp file, the backup) goes
+    // through the directory the kernel reaches.
+    const requestedPath = kernelEntry(opts.configPath ?? defaultCodexConfigPath(opts.homeDir));
     const configPath = resolveConfigSymlink(requestedPath);
     const linkPath = configPath !== requestedPath ? requestedPath : undefined;
     const viaLink = linkPath !== undefined ? ` (via symlink ${linkPath})` : "";
@@ -1801,6 +1831,7 @@ export function planCodexConfigInstall(opts) {
     return {
         configPath,
         ...(linkPath !== undefined ? { linkPath } : {}),
+        ...(opts.configPath !== undefined ? { namedConfigPath: requestedPath } : {}),
         generatedPath: opts.generatedPath,
         currentContent,
         nextContent,
@@ -1817,13 +1848,60 @@ export function planCodexConfigInstall(opts) {
 function timestampForBackup(now) {
     return now.toISOString().replace(/[:.]/g, "-");
 }
+const INSTALL_BACKUP_STAMP_RE = /^(\d{4}-\d{2}-\d{2})T(\d{2})-(\d{2})-(\d{2})-(\d{3})Z$/;
+/** The time of the newest install that rewrote the config at `filePath`, in
+ * epoch milliseconds, read from the `<filePath>.harness-backup-<timestamp>`
+ * files `writeCodexConfigInstall` leaves beside it (one per write of an
+ * existing config), or null when there is none. `harness gate enable
+ * --runtime codex` uses it to tell a snapshot taken before a re-install
+ * (whose units that install re-rendered) from one taken after it. Reads the
+ * directory only. */
+export function latestCodexInstallBackupMs(filePath) {
+    return latestCodexInstallBackup(filePath)?.ms ?? null;
+}
+/** Like {@link latestCodexInstallBackupMs}, and also the path of the newest
+ * backup file, so a message can name the install that dated a snapshot. A
+ * backup whose name spells the file in another letter case or normalization
+ * form (an install that ran through `Config.toml` for `config.toml` on a
+ * filesystem that folds those) counts when both spellings are one entry
+ * (`namesSameEntry`); on a filesystem that keeps them apart, another file's
+ * backups never do. */
+export function latestCodexInstallBackup(filePath) {
+    const dir = path.dirname(filePath);
+    const base = path.basename(filePath);
+    const marker = ".harness-backup-";
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return null;
+    }
+    let latest = null;
+    for (const name of names) {
+        const at = name.lastIndexOf(marker);
+        if (at <= 0)
+            continue;
+        const spelled = name.slice(0, at);
+        if (!namesSameEntry(dir, spelled, base, { symlinks: true }))
+            continue;
+        const m = INSTALL_BACKUP_STAMP_RE.exec(name.slice(at + marker.length));
+        if (m === null)
+            continue;
+        const ms = Date.parse(`${m[1]}T${m[2]}:${m[3]}:${m[4]}.${m[5]}Z`);
+        if (!Number.isNaN(ms) && (latest === null || ms > latest.ms)) {
+            latest = { ms, path: path.join(dir, name) };
+        }
+    }
+    return latest;
+}
 /** The config holds operator secrets (API tokens under `[mcp_servers.*]`,
  * Codex hook trust hashes); the install must never widen its permissions.
  * Preserves the existing file's own mode for both the rewritten config and
  * its backup, and falls back to `0o600` (owner read/write only) when
  * creating a config that did not exist before this install, rather than
  * `atomicWriteFile`'s own `0o644` default. */
-function existingFileMode(filePath) {
+export function existingFileMode(filePath) {
     try {
         return fs.statSync(filePath).mode & 0o777;
     }
@@ -1834,28 +1912,325 @@ function existingFileMode(filePath) {
         return 0o600;
     }
 }
-export function writeCodexConfigInstall(plan, opts = {}) {
-    if (!plan.changed)
-        return { ...plan, written: false };
-    fs.mkdirSync(path.dirname(plan.configPath), { recursive: true });
+/** Identity of a file as the filesystem sees it, so a snapshot's recorded
+ * path (the link, the target, or a hard link) is matched to the config by
+ * what it is, not by how it is spelled. */
+function fileIdentity(filePath) {
+    try {
+        const st = fs.statSync(filePath);
+        return `${st.dev}:${st.ino}`;
+    }
+    catch {
+        return null;
+    }
+}
+/** Whether `recorded` names the file `target` with identity `targetId`
+ * (taken before the install replaced it): the same absolute path, or the
+ * same device and inode, which covers a symlink and a hard link to it. */
+function namesFile(recorded, target, targetId) {
+    if (path.resolve(recorded) === path.resolve(target))
+        return true;
+    const recordedId = fileIdentity(recorded);
+    return targetId !== null && recordedId !== null && targetId === recordedId;
+}
+/** The live Codex gate snapshots, beside the requested path, beside every
+ * further hop of its link chain and beside the target, that
+ * were taken from the config an install is about to rewrite. Read before the
+ * write: the write replaces the file, which changes its inode. A snapshot
+ * that cannot be read is not matched; it is reported so the operator knows
+ * the gate will refuse on it. */
+function findSnapshotsOfConfig(plan) {
+    const requested = plan.linkPath ?? plan.configPath;
+    const id = fileIdentity(plan.configPath);
+    // A snapshot sits beside the spelling the gate was run through, and every
+    // hop of the chain from the requested path to the target is such a spelling.
+    // One directory under two spellings (a symlinked directory) is read once:
+    // a snapshot found twice would be renamed once and then fail to rename.
+    const dirs = [];
+    const seenDirs = new Set();
+    for (const spelled of [...linkChain(requested), plan.configPath]) {
+        const dir = path.dirname(spelled);
+        let physical = dir;
+        try {
+            physical = fs.realpathSync.native(dir);
+        }
+        catch {
+            // A directory that cannot be resolved is compared by its spelling.
+        }
+        if (seenDirs.has(physical))
+            continue;
+        seenDirs.add(physical);
+        // Listed as spelled, except that a `..` is taken through the directory the
+        // kernel reaches: the listing joins names to the directory, which folds it.
+        dirs.push(dir.split(path.sep).includes("..") ? physical : dir);
+    }
+    const matched = [];
+    const unreadable = [];
+    for (const dir of dirs) {
+        for (const snapPath of listCodexSnapshots(dir)) {
+            const read = readCodexSnapshot(snapPath);
+            if (!read.ok) {
+                unreadable.push(snapPath);
+                continue;
+            }
+            const recorded = read.snapshot.configPath;
+            if (namesFile(recorded, plan.configPath, id) || namesFile(recorded, requested, id))
+                matched.push(snapPath);
+        }
+    }
+    return { matched, unreadable };
+}
+/**
+ * Writes the install. A live gate snapshot of the config holds the hook
+ * lines of the block this write replaces, so enabling it later would put an
+ * outdated line back: every such snapshot (beside every hop of the requested
+ * path's link chain and beside the target) is renamed to `*.superseded.json` right after the
+ * write, whatever backup files exist. A rename that fails never fails the
+ * install, which is already on disk: it is a warning (`snapshotWarnings`,
+ * printed by the caller) naming the snapshot and the move-aside step. A
+ * snapshot this cannot find (beside a link outside that chain) records the
+ * block's generation marker, which this write changes when the content
+ * changes, so `gate enable` and `gate disable` retire it on sight. The
+ * backup-file dating in the gate stays as a further line of defence for a
+ * snapshot without a marker (taken before the marker existed).
+ */
+export function writeCodexConfigInstall(planned, opts = {}) {
+    if (!planned.changed)
+        return { ...planned, written: false };
+    fs.mkdirSync(path.dirname(planned.configPath), { recursive: true });
+    // A config directory that did not exist at plan time, spelled with `..`
+    // after a directory link, could not be resolved then (`kernelEntry` keeps
+    // such a spelling). It exists now, so the paths built from the spelling (the
+    // temp file, the snapshot listing) go through the directory the kernel
+    // reaches instead of a lexical fold into another one.
+    const plan = { ...planned, configPath: kernelEntry(planned.configPath) };
+    // The summary was built from the plan-time spelling: name the path written.
+    if (plan.configPath !== planned.configPath) {
+        plan.summary = plan.summary.replace(planned.configPath, () => plan.configPath);
+    }
     const mode = existingFileMode(plan.configPath);
+    const snapshots = findSnapshotsOfConfig(plan);
     // Only back up a config that actually existed before this install (task
     // 461ec064): a fresh install has nothing to protect, and writing a
     // 0-byte backup for it misreported a write that never happened.
+    let result;
     if (!plan.configExisted) {
         atomicWriteFile(plan.configPath, plan.nextContent, { mode });
-        return { ...plan, written: true };
-    }
-    // A symlinked config's backup sits beside the link (task 1637fbc8), not
-    // beside the resolved target: the config holds secrets, and the target's
-    // directory is typically a dotfiles git work tree where an untracked
-    // backup is one `git add` away from being pushed. The backup is a fresh
-    // file, so it need not share the target's filesystem; only the atomic
-    // write of the target itself (temp file plus rename) must.
-    const backupBase = plan.linkPath ?? plan.configPath;
-    const backupPath = `${backupBase}.harness-backup-${timestampForBackup(opts.now ?? new Date())}`;
-    atomicWriteFile(backupPath, plan.currentContent, { mode });
-    atomicWriteFile(plan.configPath, plan.nextContent, { mode });
-    return { ...plan, backupPath, written: true };
+        result = { ...plan, written: true };
+    }
+    else {
+        // A symlinked config's backup sits beside the link (task 1637fbc8), not
+        // beside the resolved target: the config holds secrets, and the target's
+        // directory is typically a dotfiles git work tree where an untracked
+        // backup is one `git add` away from being pushed. The backup is a fresh
+        // file, so it need not share the target's filesystem; only the atomic
+        // write of the target itself (temp file plus rename) must.
+        const backupBase = plan.linkPath ?? plan.configPath;
+        const backupPath = `${backupBase}.harness-backup-${timestampForBackup(opts.now ?? new Date())}`;
+        atomicWriteFile(backupPath, plan.currentContent, { mode });
+        atomicWriteFile(plan.configPath, plan.nextContent, { mode });
+        result = { ...plan, backupPath, written: true };
+    }
+    const superseded = [];
+    const warnings = snapshots.unreadable.map((p) => `the Codex gate snapshot ${p} cannot be read, so the install could not tell whether it belongs to ` +
+        `this config; \`harness gate enable --runtime codex${codexConfigFlag(plan.namedConfigPath ?? null)}\` will refuse on it ` +
+        "until you move it out of this directory.");
+    for (const snapPath of snapshots.matched) {
+        try {
+            superseded.push(retireCodexSnapshot(snapPath, "superseded", (m) => new Error(m), "the config was installed, but "));
+        }
+        catch (err) {
+            warnings.push(err.message);
+        }
+    }
+    if (superseded.length > 0)
+        result.supersededSnapshots = superseded;
+    if (warnings.length > 0) {
+        result.snapshotWarnings = warnings;
+    }
+    return result;
+}
+const HOOK_UNIT_HEADER_RE = /^\[\[hooks\.([A-Za-z][A-Za-z0-9_]*)\]\]$/;
+/**
+ * The harness-owned hook units of the fenced managed block in `text`, with
+ * exact offsets, for `harness gate` (the operator's switch for a blocking
+ * hook). It reuses the installer's own range scan (`findManagedRange`), so
+ * the refusals that scan raises (a duplicate BEGIN marker, a foreign table
+ * wedged inside the block) apply here unchanged, and adds the stricter
+ * reading an edit needs: the block must be fenced by BEGIN and a closing END
+ * marker line, every non-blank line inside it must be a comment or part of a
+ * unit of the exact shape the generator writes, and no harness hook comment
+ * may sit outside the block (`assertNoOrphanHarnessHookTable`). Anything else
+ * refuses instead of guessing which bytes are harness-owned. Returns null
+ * when the file holds no managed block. The block's generation marker is read
+ * too, never required: a block without it reads as `generation: null`.
+ * Reads only; the file is never touched.
+ */
+export function readCodexManagedHookUnits(text, configPath) {
+    const range = findManagedRange(text, configPath);
+    if (range === null)
+        return null;
+    const refuse = (why) => refuseHookBlockEdit(configPath, why);
+    const beginLine = findMarkerLine(text, CODEX_MANAGED_BEGIN, "prefix", range.start, range.end);
+    if (beginLine === -1) {
+        return refuse(`the harness block has no '${CODEX_MANAGED_BEGIN}' fence (written by an older install); ` +
+            "re-run `harness apply --runtime codex --install` once to rewrite it with fences");
+    }
+    assertNoOrphanHarnessHookTable(text, configPath, range);
+    const endLine = lineStartAt(text, range.end - 1);
+    // A drifted END (a foreign table between the last unit and the END marker)
+    // ends the range before that table, so the range's last line is not the
+    // END marker line and the same check refuses it.
+    if (!createMarkerLineProbe(text)(endLine, CODEX_MANAGED_END, "whole")) {
+        return refuse(`the block is not closed by a '${CODEX_MANAGED_END}' marker line right after its hook tables ` +
+            "(move any table that sits between the last hook unit and the END marker to below the END " +
+            "marker, or re-run `harness apply --runtime codex --install` to rewrite the block)");
+    }
+    const isMarkerLine = createMarkerLineProbe(text);
+    const units = [];
+    let pos = lineEndAfter(text, beginLine);
+    const lineAt = (at) => text.slice(at, lineEndAfter(text, at)).trim();
+    // Only the line right under BEGIN carries the generation; it is a comment,
+    // so the scan below passes over it like the generated header.
+    const generation = pos < endLine ? (BLOCK_GENERATION_LINE_RE.exec(lineAt(pos))?.[1] ?? null) : null;
+    while (pos < endLine) {
+        const trimmed = lineAt(pos);
+        const isUnitComment = trimmed.startsWith("#") && isMarkerLine(pos, HARNESS_HOOK_COMMENT_PREFIX, "prefix");
+        if (trimmed === "" || (trimmed.startsWith("#") && !isUnitComment)) {
+            if (units.length > 0 && trimmed !== "") {
+                return refuse(`line ${lineNumberAt(text, pos)} inside the block is a comment between hook units`);
+            }
+            pos = lineEndAfter(text, pos);
+            continue;
+        }
+        if (!isUnitComment) {
+            return refuse(`line ${lineNumberAt(text, pos)} inside the block is not part of a generated hook unit`);
+        }
+        const id = HOOK_ID_LINE_RE.exec(trimmed)?.[1];
+        if (id === undefined) {
+            return refuse(`the hook comment at line ${lineNumberAt(text, pos)} is not in the generated shape`);
+        }
+        const unitStart = pos;
+        const body = [];
+        let lastLineAt = pos;
+        pos = lineEndAfter(text, pos);
+        while (pos < endLine && lineAt(pos) !== "" && !lineAt(pos).startsWith("#")) {
+            body.push(lineAt(pos));
+            lastLineAt = pos;
+            pos = lineEndAfter(text, pos);
+        }
+        units.push(parseHookUnit(id, body, unitStart, lastLineAt, text, refuse));
+    }
+    return { units, generation };
+}
+function refuseHookBlockEdit(configPath, why) {
+    throw new CodexInstallRefusalError(`Codex config ${configPath}: ${why}; refusing to edit the harness-managed hook block. ` +
+        "The file is untouched.", configPath);
+}
+function parseHookUnit(id, body, start, lastLineAt, text, refuse) {
+    const where = `the hook unit at line ${lineNumberAt(text, start)}`;
+    const header = HOOK_UNIT_HEADER_RE.exec(body[0] ?? "");
+    const shapeOk = header !== null &&
+        (body.length === 2 || (body.length === 3 && body[1].startsWith("matcher = "))) &&
+        body[body.length - 1].startsWith("hooks = [");
+    if (!shapeOk) {
+        return refuse(`${where} is not the generated shape (header, optional matcher, hooks array)`);
+    }
+    let doc;
+    try {
+        doc = parseToml(body.join("\n"));
+    }
+    catch (err) {
+        return refuse(`${where} does not parse as TOML (${describeTomlParseError(err)})`);
+    }
+    const event = header[1];
+    const hooksTable = isTomlTable(doc) ? doc.hooks : undefined;
+    const entries = isTomlTable(hooksTable) ? hooksTable[event] : undefined;
+    const entry = Array.isArray(entries) && entries.length === 1 ? entries[0] : undefined;
+    if (!isTomlTable(entry) || !Array.isArray(entry.hooks)) {
+        return refuse(`${where} does not define one ${event} entry with a hooks array`);
+    }
+    const matcher = entry.matcher;
+    if (matcher !== undefined && typeof matcher !== "string") {
+        return refuse(`${where} has a matcher that is not a string`);
+    }
+    const commands = entry.hooks.flatMap((h) => isTomlTable(h) && typeof h.command === "string" ? [h.command] : []);
+    const rawLine = text.slice(lastLineAt, lineEndAfter(text, lastLineAt));
+    return {
+        id,
+        event,
+        matcher: matcher ?? null,
+        commands,
+        disabled: entry.hooks.length === 0,
+        start,
+        hooksStart: lastLineAt + (rawLine.length - rawLine.trimStart().length),
+        hooksEnd: lastLineAt + rawLine.trimEnd().length,
+    };
+}
+/**
+ * The safety net for a gate edit of the managed block. First the installer's
+ * own semantic invariant (both documents parse, and everything outside the
+ * hook event arrays is deep-equal), then the part that invariant leaves out
+ * on purpose, compared entry by entry: per hook event the arrays have the
+ * same length, every entry is deep-equal to its counterpart except exactly
+ * `expected.counts[event]` entries, and each of those differs only in its
+ * `hooks` array (emptied by a neutralise, filled again by a restore). So a
+ * gate edit can neither drop, add or reorder an entry nor move a key from one
+ * entry to another, and Codex keeps every other hook at the position its
+ * trust state was recorded for.
+ */
+export function assertCodexHookEditInvariant(before, after, configPath, expected) {
+    assertConfigSemanticInvariant(before, after, configPath);
+    const eventArrays = (doc) => {
+        const arrays = new Map();
+        const hooks = isTomlTable(doc) ? doc.hooks : undefined;
+        if (!isTomlTable(hooks))
+            return arrays;
+        for (const [key, value] of Object.entries(hooks)) {
+            if (Array.isArray(value))
+                arrays.set(key, value);
+        }
+        return arrays;
+    };
+    const same = (a, b) => firstDifferingKeyPath(a, b, []) === null;
+    const withHooks = (entry, hooks) => isTomlTable(entry) ? { ...entry, hooks } : entry;
+    const hooksOf = (entry) => isTomlTable(entry) ? entry.hooks : undefined;
+    const emptied = (entry) => {
+        const hooks = hooksOf(entry);
+        return Array.isArray(hooks) && hooks.length === 0;
+    };
+    const filled = (entry) => {
+        const hooks = hooksOf(entry);
+        return Array.isArray(hooks) && hooks.length > 0;
+    };
+    const refuse = (event, why) => {
+        throw new CodexInstallRefusalError(`Codex config ${configPath}: the gate edit would ${why} in the '${event}' hook entries; ` +
+            "refusing to write. The file is untouched.", configPath);
+    };
+    const was = eventArrays(parseToml(before));
+    const now = eventArrays(parseToml(after));
+    for (const event of new Set([...was.keys(), ...now.keys(), ...Object.keys(expected.counts)])) {
+        const a = was.get(event) ?? [];
+        const b = now.get(event) ?? [];
+        if (a.length !== b.length) {
+            refuse(event, `change the number of entries from ${a.length} to ${b.length}`);
+        }
+        let changed = 0;
+        for (let i = 0; i < a.length; i += 1) {
+            if (same(a[i], b[i]))
+                continue;
+            changed += 1;
+            const relationHolds = expected.direction === "neutralise"
+                ? filled(a[i]) && emptied(b[i]) && same(withHooks(a[i], []), b[i])
+                : emptied(a[i]) && filled(b[i]) && same(withHooks(b[i], []), a[i]);
+            if (!relationHolds) {
+                refuse(event, `change entry ${i} by more than its hooks array`);
+            }
+        }
+        const want = expected.counts[event] ?? 0;
+        if (changed !== want) {
+            refuse(event, `change ${changed} entries, expected ${want}`);
+        }
+    }
 }
 //# sourceMappingURL=install-codex-config.js.map