@lannguyensi/harness 0.58.0 → 0.58.2

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

@@ -1,14 +1,58 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 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";
 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";
+/**
+ * Thrown instead of a plain `Error` when the install refuses rather than
+ * guesses (a duplicate/moved BEGIN marker, or a foreign table wedged
+ * inside the managed block). Extends `HarnessExitError` so it carries the
+ * repo's own exit-code convention (`EX_FAIL`) through `run()`'s top-level
+ * catch without the generic "return 70" branch, and the CLI action can
+ * recognize it by type to emit a structured `--json` error the same way
+ * the other apply refusals (`target-exists-refuse`, `drift-refuse`) do.
+ */
+export class CodexInstallRefusalError extends HarnessExitError {
+    configPath;
+    constructor(message, configPath) {
+        super(message, EX_FAIL);
+        this.configPath = configPath;
+        this.name = "CodexInstallRefusalError";
+    }
+}
 const GENERATED_HEADER = "# Generated by harness apply --runtime codex.";
 const LEGACY_HOOK_TABLE_RE = /^\[\[hooks\.(pre_tool_use|post_tool_use|user_prompt_submit|session_start|stop)\]\]$/;
 const CURRENT_HOOK_TABLE_RE = /^\[\[hooks\.[A-Za-z][A-Za-z0-9_]*\]\]$/;
-const NON_HOOK_TABLE_RE = /^\[(?!\[hooks\.)/;
+// A single, unquoted-or-quoted TOML bare/quoted key: `foo-bar_1`, a basic
+// `"..."` string (escapes allowed), or a literal `'...'` string (no
+// escapes, so a literal key may itself contain `[`, `]`, `"` or `#`
+// verbatim, e.g. `'a[b'`).
+const TOML_KEY = String.raw `(?:[A-Za-z0-9_-]+|"(?:[^"\\]|\\.)*"|'[^']*')`;
+// A single-line TOML table header only: `[key]`, `[[key]]`, or a dotted
+// path of keys (`[a.b."c d".'e[f']`), optionally surrounded by whitespace
+// around the brackets and each dot, and optionally followed by whitespace
+// and a trailing comment. Quote-aware so a key that itself contains `[`,
+// `]`, `.` or `#` (a real path or filename used as a TOML key, e.g.
+// `[projects."/Users/x/Photos [2024]"]`, `[plugins.'a[b']`) is still
+// recognized as one header, instead of the bracket/hash inside the quotes
+// being mistaken for the header's own delimiters. Deliberately excludes an
+// array-continuation line such as `  [1, 2],` (no trailing comma allowed,
+// and a bare numeric-looking segment such as `1` only ever matches as a
+// single key with nothing after it, never as an array element) so a
+// multi-line array/value sitting inside a still-owned harness hook table
+// is never misread as a foreign table header ending the owned region
+// early (task 6a037359).
+const NON_HOOK_TABLE_RE = new RegExp(String.raw `^\[(?!\[hooks\.)\[?\s*${TOML_KEY}(?:\s*\.\s*${TOML_KEY})*\s*\]\]?\s*(?:#.*)?$`);
+// Every emitted hook table is preceded by exactly this comment shape
+// (generate-codex-config.ts's `emitHook`); used both to name removed hook
+// blocks in the install summary and to detect a foreign table wedged
+// between two harness hook tables (see `assertNoSplitBlock`).
+const HARNESS_HOOK_COMMENT_PREFIX = "# harness hook: ";
+const HOOK_ID_LINE_RE = /^# harness hook: (.+) \(budget_ms=\d+\)$/;
 export function defaultCodexConfigPath(homeDir) {
     return path.join(homeDir ?? os.homedir(), ".codex", "config.toml");
 }
@@ -27,44 +71,461 @@ function previousLine(text, lineStart) {
     const start = lineStartAt(text, end);
     return { start, text: text.slice(start, end) };
 }
-function findLegacyRangeEnd(text, start) {
-    let pos = start;
+/** 1-based line number of `index` within `text`, for operator-facing error text. */
+function lineNumberAt(text, index) {
+    let n = 1;
+    for (let i = 0; i < index && i < text.length; i += 1) {
+        if (text[i] === "\n")
+            n += 1;
+    }
+    return n;
+}
+/** True when the character at `index` is escaped by an odd number of
+ * immediately preceding backslashes (`\"` is escaped, `\\"` is not: the
+ * first backslash escapes the second, leaving the quote bare). Only basic
+ * (double-quoted) strings support this escape; literal (single-quoted)
+ * strings never do. */
+function isEscapedAt(line, index) {
+    let backslashes = 0;
+    let j = index - 1;
+    while (j >= 0 && line[j] === "\\") {
+        backslashes += 1;
+        j -= 1;
+    }
+    return backslashes % 2 === 1;
+}
+/**
+ * Walks one physical line of TOML, tracking only what a caller needs to
+ * decide whether the NEXT line is opaque multi-line-string content: which
+ * triple-quote delimiter (if any) is open once this line ends. `delimIn`
+ * is the delimiter already open when this line STARTS (from a preceding
+ * multi-line string that has not yet closed); when non-null, this line's
+ * own content is scanned only for that SAME delimiter closing it (a basic
+ * `"""` string is closed only by another `"""`, never by `'''`, and vice
+ * versa -- naively counting either delimiter's raw
+ * occurrences, as the pre-fix code did, misreads a `'''` sitting inside an
+ * open `"""` string, or a comment/single-line-string containing `'''` or
+ * `"""`, as a real close).
+ *
+ * When `delimIn` is null, the line is scanned left to right: a bare `#`
+ * (outside any string) starts a line comment and ends scanning (its
+ * content, including any quote characters, is never code); a single-line
+ * basic (`"`) or literal (`'`) string is skipped to its own closing quote
+ * (escapes honored only for `"`) without inspecting its contents for
+ * delimiters; a `"""`/`'''` not preceded by an escaped quote opens a
+ * multi-line string of that type.
+ */
+function nextTripleDelim(rawLine, delimIn) {
+    let i = 0;
+    const n = rawLine.length;
+    let delim = delimIn;
+    while (i < n) {
+        if (delim !== null) {
+            if (rawLine.startsWith(delim, i)) {
+                if (delim === '"""' && isEscapedAt(rawLine, i)) {
+                    i += 1;
+                    continue;
+                }
+                delim = null;
+                i += 3;
+                continue;
+            }
+            if (delim === '"""' && rawLine[i] === "\\") {
+                i += 2; // an escaped char inside a basic string can never itself
+                continue; // start a real closing delimiter.
+            }
+            i += 1;
+            continue;
+        }
+        const ch = rawLine[i];
+        if (ch === "#")
+            break; // line comment: nothing after it is code.
+        if (rawLine.startsWith('"""', i)) {
+            delim = '"""';
+            i += 3;
+            continue;
+        }
+        if (rawLine.startsWith("'''", i)) {
+            delim = "'''";
+            i += 3;
+            continue;
+        }
+        if (ch === '"') {
+            i += 1;
+            while (i < n && rawLine[i] !== '"') {
+                if (rawLine[i] === "\\")
+                    i += 1;
+                i += 1;
+            }
+            i += 1; // consume the closing quote (or run to end if unterminated)
+            continue;
+        }
+        if (ch === "'") {
+            i += 1;
+            while (i < n && rawLine[i] !== "'")
+                i += 1;
+            i += 1;
+            continue;
+        }
+        i += 1;
+    }
+    return delim;
+}
+/**
+ * The first line, at or after `from`, whose TRIMMED content is byte-equal
+ * to `target` (not a raw substring search). A raw `text.indexOf(target,
+ * from)` would also match `target` sitting mid-line inside unrelated
+ * content; matching only whole trimmed lines rules that out. A line that
+ * BEGAN inside an open TOML multi-line string (tracked via
+ * `nextTripleDelim`, correctly distinguishing `"""` from `'''` and
+ * ignoring delimiters inside a comment or a single-line string) is never
+ * treated as a possible match, regardless of its trimmed text: a foreign
+ * table's own multi-line string value may legitimately contain a line
+ * that reads exactly like the harness END marker (task 6a037359) without
+ * that being a real stray END. The triple-quote state is tracked only
+ * from `from` onward (a string open before `from` is not detected), which
+ * is correct for the caller's one use: `from` is always the start of the
+ * first foreign table in the zone being searched, so any multi-line
+ * string that matters here opens inside that zone, not before it.
+ */
+function findExactLine(text, target, from) {
+    let pos = from;
+    let delim = null;
     while (pos < text.length) {
-        const end = lineEndAfter(text, pos);
-        const line = text.slice(pos, end).trim();
-        if (pos > start && NON_HOOK_TABLE_RE.test(line))
+        const lineEnd = lineEndAfter(text, pos);
+        const rawLine = text.slice(pos, lineEnd);
+        const startedInsideString = delim !== null;
+        delim = nextTripleDelim(rawLine, delim);
+        if (!startedInsideString && rawLine.trim() === target)
             return pos;
-        pos = end;
+        pos = lineEnd;
+    }
+    return -1;
+}
+/** The first non-blank, non-comment line at or after `from` (bounded by
+ * `limit`), trimmed. Used to name the offending foreign header in a
+ * refusal message. */
+function firstContentLine(text, from, limit) {
+    let pos = Math.max(from, 0);
+    const end = Math.max(limit, from);
+    while (pos < end) {
+        const lineEnd = Math.min(lineEndAfter(text, pos), end);
+        const trimmed = text.slice(pos, lineEnd).trim();
+        if (trimmed !== "" && !trimmed.startsWith("#"))
+            return trimmed;
+        pos = lineEnd;
+    }
+    return null;
+}
+/**
+ * Scans forward from `start` classifying each line as either still-owned
+ * harness content or the start of foreign (non-harness) content, WITHOUT
+ * relying on where (or whether) a `CODEX_MANAGED_END` marker sits. This is
+ * what makes the region computation safe against a stray/misplaced END
+ * (task 6a037359: `findManagedRange` used to trust `text.indexOf(END,
+ * begin)` unconditionally, so an END marker that had drifted past
+ * Codex-written tables such as `[hooks.state]` caused every foreign table
+ * between BEGIN and that END to be deleted on the next install) and
+ * against a config that has no END marker at all (the legacy shape).
+ *
+ * A run of blank/comment lines immediately followed by foreign content is
+ * excluded from the owned region (backed off to the start of that run):
+ * Codex, or an operator, may attach a comment to the table that follows,
+ * and that comment must never be misread as harness commentary and folded
+ * into the replaced block.
+ *
+ * A line is "foreign" exactly when it is a table header that is not one
+ * of ours (`NON_HOOK_TABLE_RE`, mirroring the pre-existing legacy scan);
+ * every other non-blank, non-comment line (a hook table's `matcher =` /
+ * `hooks =` field, or an older schema's bare `command =` / `match =` /
+ * `timeout_ms =` / `blocking =` field) is treated as still-owned content,
+ * same as before this fix. A line that BEGAN inside an open TOML
+ * multi-line string (`nextTripleDelim`) is always treated as still-owned
+ * content too, regardless of what it looks like: a hook table's own
+ * multi-line string value (or a foreign table's, once one is already
+ * inside the owned region by construction -- this scanner only ever runs
+ * from a position that is itself still-owned) may contain a line that
+ * reads exactly like a comment, a blank line, or even the END marker
+ * without that ending the region early (task 6a037359).
+ */
+function scanOwnedContentEnd(text, start) {
+    let pos = start;
+    let commentRunStart = null;
+    let delim = null;
+    while (pos < text.length) {
+        const lineEnd = lineEndAfter(text, pos);
+        const rawLine = text.slice(pos, lineEnd);
+        const startedInsideString = delim !== null;
+        delim = nextTripleDelim(rawLine, delim);
+        if (startedInsideString) {
+            commentRunStart = null;
+            pos = lineEnd;
+            continue;
+        }
+        const trimmed = rawLine.trim();
+        if (trimmed === CODEX_MANAGED_END) {
+            return { end: lineEnd, sawEndMarker: true };
+        }
+        if (trimmed === "" || trimmed.startsWith("#")) {
+            if (commentRunStart === null)
+                commentRunStart = pos;
+            pos = lineEnd;
+            continue;
+        }
+        if (NON_HOOK_TABLE_RE.test(trimmed)) {
+            return { end: commentRunStart ?? pos, sawEndMarker: false };
+        }
+        commentRunStart = null;
+        pos = lineEnd;
+    }
+    return { end: pos, sawEndMarker: false };
+}
+/**
+ * Refuses loudly (mirror case of the stray-END bug) when the zone between
+ * `from` and `to` still contains a recognizable fragment of a harness
+ * hook block: a second BEGIN/source-prefix marker, or a `# harness hook:`
+ * comment. Either means a foreign table was wedged between two harness
+ * hook tables, or the BEGIN marker moved, and the true block boundaries
+ * can no longer be determined by a line scan; guessing risks reordering
+ * or dropping harness- or foreign-owned bytes, so this throws instead. The
+ * message names the resolved config path (never a hard-coded `~/.codex`),
+ * the foreign table header the scan found (usually `from` itself, see
+ * `scanOwnedContentEnd`; when only blank or comment lines precede the found
+ * marker in the zone -- so the pre-marker lookup finds no content line to
+ * report -- the header is looked up again just past that marker's own
+ * line, since the wedged table then sits after it, not before; printed
+ * through `describeTableHeader`, so only the header's own bracketed key
+ * path appears, never a trailing comment), and
+ * the line number and marker of the first line beyond it
+ * that still looks like harness content. That line's own text is never
+ * echoed: the marker is found by a substring search, so the line may be
+ * foreign content (a value holding an API token, say) that merely contains
+ * the marker text, and the refusal is printed to stderr and into `--json`
+ * output. `hasEndMarker` distinguishes the two callers: when `to` was
+ * derived from a real stray `CODEX_MANAGED_END` line, the fix guidance can
+ * point at that marker; when there is no END marker anywhere in the
+ * document (`to` is `text.length`), telling the operator to move something
+ * below a marker that does not exist would be nonsensical, so a different
+ * fix (add one, or move the table below the last harness hook table) is
+ * offered instead (task 6a037359).
+ */
+function assertNoSplitBlock(text, from, to, configPath, hasEndMarker) {
+    const zoneStart = Math.max(from, 0);
+    const zoneEnd = Math.max(to, from);
+    const zone = text.slice(zoneStart, zoneEnd);
+    let markerOffset = -1;
+    let marker = "";
+    for (const candidate of [
+        CODEX_MANAGED_SOURCE_PREFIX,
+        CODEX_MANAGED_BEGIN,
+        HARNESS_HOOK_COMMENT_PREFIX,
+    ]) {
+        const idx = zone.indexOf(candidate);
+        if (idx !== -1 && (markerOffset === -1 || idx < markerOffset)) {
+            markerOffset = idx;
+            marker = candidate.trim();
+        }
+    }
+    if (markerOffset === -1)
+        return;
+    const offendingLineNumber = lineNumberAt(text, lineStartAt(text, zoneStart + markerOffset));
+    // Normally the foreign table header is the zone's own first content line,
+    // sitting before the marker (`from` starts at that header per
+    // `scanOwnedContentEnd`). But when only blank or comment lines precede the
+    // marker in the zone -- so that pre-marker lookup finds no content line --
+    // the foreign table that split the block is wedged after the marker's own
+    // line instead, so look there.
+    const markerLineEnd = lineEndAfter(text, zoneStart + markerOffset);
+    const foreignHeaderLine = firstContentLine(text, zoneStart, zoneStart + markerOffset) ??
+        firstContentLine(text, markerLineEnd, zoneEnd);
+    const firstForeignHeader = foreignHeaderLine === null ? "(unknown)" : describeTableHeader(foreignHeaderLine);
+    const guidance = hasEndMarker
+        ? `Move ${firstForeignHeader} below the '${CODEX_MANAGED_END}' marker, or delete the lines ` +
+            `between '${CODEX_MANAGED_BEGIN}' and '${CODEX_MANAGED_END}' so only harness-owned tables ` +
+            "remain between them"
+        : `Add a '${CODEX_MANAGED_END}' marker line right after the last harness hook table (before ` +
+            `${firstForeignHeader}), or move ${firstForeignHeader} below the last harness hook table`;
+    throw new CodexInstallRefusalError(`Codex config ${configPath} has a foreign table (${firstForeignHeader}) sitting before ` +
+        `more harness-owned content: line ${offendingLineNumber} contains '${marker}' and still ` +
+        "looks like part of the harness-managed hook block; refusing to guess the block " +
+        `boundaries. ${guidance}, then re-run \`harness apply --runtime codex --install\`. As a ` +
+        `last resort, restore ${configPath} from the most recent .harness-backup-* file (if one exists), but ` +
+        "that discards any Codex state (hook trust entries, marketplaces, plugins) written to " +
+        "the file since that backup.", configPath);
+}
+// A single-line TOML table header split into the header itself (brackets
+// plus dotted key path, without any trailing comment; group 1) and its
+// dotted key path (group 2). Same shape `NON_HOOK_TABLE_RE` recognizes,
+// minus the `[[hooks.` exclusion, so every header that regex accepts
+// parses here too.
+const TABLE_HEADER_PARTS_RE = new RegExp(String.raw `^(\[\[?\s*(${TOML_KEY}(?:\s*\.\s*${TOML_KEY})*)\s*\]\]?)\s*(?:#.*)?$`);
+const TOML_KEY_GLOBAL_RE = new RegExp(TOML_KEY, "g");
+/** A table header line's own bracketed key path (`header`) and its keys in
+ * order (`keys`), each as written. Keys are matched with the quote-aware
+ * `TOML_KEY`, so a quoted key containing `.`, `[`, `]` or `#` stays one
+ * key, and a trailing comment is never part of either field. `null` for a
+ * line that is not a single-line table header. */
+function parseTableHeader(line) {
+    const m = TABLE_HEADER_PARTS_RE.exec(line.trim());
+    if (m?.[1] === undefined || m[2] === undefined)
+        return null;
+    return { header: m[1], keys: [...m[2].matchAll(TOML_KEY_GLOBAL_RE)].map((k) => k[0]) };
+}
+/** A table header for operator-facing output: the bracketed key path only,
+ * with any trailing comment dropped (a comment is free text and is not
+ * echoed). `(unknown)` for a line that is not a table header. */
+function describeTableHeader(line) {
+    return parseTableHeader(line)?.header ?? "(unknown)";
+}
+/** A key segment's bare name: a literal (`'...'`) key's inner text, a basic
+ * (`"..."`) key's inner text when it holds no escape sequence, otherwise
+ * the segment as written. Used only to recognize the `hooks` root however
+ * it is spelled. */
+function bareKeyName(segment) {
+    const quote = segment[0];
+    if (segment.length >= 2 && (quote === "'" || quote === '"') && segment.endsWith(quote)) {
+        const inner = segment.slice(1, -1);
+        if (quote === "'" || !inner.includes("\\"))
+            return inner;
+    }
+    return segment;
+}
+/** The namespace a foreign table header is grouped under in
+ * `foreignSectionsPreserved`: its first key, or its first TWO keys when the
+ * first is `hooks` (`hooks.state`), since `hooks` is shared with the
+ * harness-managed event arrays and a bare `hooks` group would not tell the
+ * operator which namespace was kept. */
+function foreignSectionRootKey(headerLine) {
+    const parsed = parseTableHeader(headerLine);
+    const first = parsed?.keys[0];
+    if (parsed === null || first === undefined)
+        return headerLine.trim();
+    const second = parsed.keys[1];
+    if (bareKeyName(first) === "hooks" && second !== undefined)
+        return `${first}.${second}`;
+    return first;
+}
+/** One representative header per distinct foreign namespace found between
+ * `from` and `to` (e.g. all `[hooks.state."..."]` sub-tables collapse to
+ * one entry), in first-seen order. A namespace with more than one table
+ * under it prints its root with a wildcard and a count (e.g.
+ * `[hooks.state.*] (3 tables)`) instead of the first table's own header,
+ * so the operator reads "a whole namespace, N tables" rather than
+ * mistaking the printed header for the only table kept; exactly one table
+ * under a root prints its own header. Headers print through
+ * `describeTableHeader` (no trailing comment). */
+function collectForeignSectionHeaders(text, from, to) {
+    const seenRoots = new Set();
+    const headers = [];
+    const counts = new Map();
+    let pos = Math.max(from, 0);
+    const limit = Math.max(to, from);
+    let delim = null;
+    while (pos < limit) {
+        const lineEnd = Math.min(lineEndAfter(text, pos), limit);
+        const rawLine = text.slice(pos, lineEnd);
+        const startedInsideString = delim !== null;
+        delim = nextTripleDelim(rawLine, delim);
+        if (startedInsideString) {
+            pos = lineEnd;
+            continue;
+        }
+        const trimmed = rawLine.trim();
+        if (NON_HOOK_TABLE_RE.test(trimmed)) {
+            const root = foreignSectionRootKey(trimmed);
+            counts.set(root, (counts.get(root) ?? 0) + 1);
+            if (!seenRoots.has(root)) {
+                seenRoots.add(root);
+                headers.push(describeTableHeader(trimmed));
+            }
+        }
+        pos = lineEnd;
+    }
+    return headers.map((header) => {
+        const root = foreignSectionRootKey(header);
+        const count = counts.get(root) ?? 1;
+        return count > 1 ? `[${root}.*] (${count} tables)` : header;
+    });
+}
+function extractHookIds(content) {
+    const ids = new Set();
+    for (const rawLine of content.split(/\r?\n/)) {
+        const m = HOOK_ID_LINE_RE.exec(rawLine.trim());
+        if (m?.[1] !== undefined)
+            ids.add(m[1]);
     }
-    return text.length;
+    return ids;
 }
-function findManagedRange(text) {
+function findManagedRange(text, configPath) {
     const begin = text.indexOf(CODEX_MANAGED_BEGIN);
     if (begin !== -1) {
+        const secondBegin = text.indexOf(CODEX_MANAGED_BEGIN, begin + CODEX_MANAGED_BEGIN.length);
+        if (secondBegin !== -1) {
+            // Names the second marker's line number only, never that line's own
+            // text: the marker is found by a substring search, so the line may be
+            // foreign content (a value holding a token, say) that merely contains
+            // the marker text, and this refusal is printed to stderr and `--json`.
+            const secondBeginLineNumber = lineNumberAt(text, lineStartAt(text, secondBegin));
+            throw new CodexInstallRefusalError(`Codex config ${configPath} has more than one '${CODEX_MANAGED_BEGIN}' marker ` +
+                `(a second one at line ${secondBeginLineNumber}); refusing to ` +
+                "guess which one is current. Delete the entire unwanted BEGIN/END pair -- including " +
+                `its own '${CODEX_MANAGED_BEGIN}' and '${CODEX_MANAGED_END}' marker lines (and its ` +
+                `'${CODEX_MANAGED_SOURCE_PREFIX}' source-prefix comment line, if it has one) -- ` +
+                "keeping exactly one pair, then re-run `harness apply --runtime codex --install`. As " +
+                `a last resort, restore ${configPath} from the most recent .harness-backup-* file (if one exists), ` +
+                "but that discards any Codex state (hook trust entries, marketplaces, plugins) " +
+                "written to the file since that backup.", configPath);
+        }
         let start = lineStartAt(text, begin);
         const prev = previousLine(text, start);
         if (prev && prev.text.startsWith(CODEX_MANAGED_SOURCE_PREFIX)) {
             start = prev.start;
         }
-        const endMarker = text.indexOf(CODEX_MANAGED_END, begin);
-        if (endMarker !== -1) {
-            return { start, end: lineEndAfter(text, endMarker) };
+        const contentStart = lineEndAfter(text, begin);
+        const scan = scanOwnedContentEnd(text, contentStart);
+        const end = scan.end;
+        if (scan.sawEndMarker) {
+            return { start, end, foreignSectionsPreserved: [] };
+        }
+        const strayIdx = findExactLine(text, CODEX_MANAGED_END, end);
+        if (strayIdx === -1) {
+            assertNoSplitBlock(text, end, text.length, configPath, false);
+            const foreignSectionsPreserved = collectForeignSectionHeaders(text, end, text.length);
+            return { start, end, foreignSectionsPreserved };
         }
-        return { start, end: findLegacyRangeEnd(text, start) };
+        const strayLineStart = lineStartAt(text, strayIdx);
+        const strayLineEnd = lineEndAfter(text, strayIdx);
+        assertNoSplitBlock(text, end, strayLineStart, configPath, true);
+        const foreignSectionsPreserved = collectForeignSectionHeaders(text, end, strayLineStart);
+        return {
+            start,
+            end,
+            strayEnd: { start: strayLineStart, end: strayLineEnd },
+            foreignSectionsPreserved,
+        };
     }
     const source = text.indexOf(CODEX_MANAGED_SOURCE_PREFIX);
     if (source !== -1) {
         const start = lineStartAt(text, source);
-        return { start, end: findLegacyRangeEnd(text, start) };
+        const scan = scanOwnedContentEnd(text, start);
+        const end = scan.end;
+        const foreignSectionsPreserved = scan.sawEndMarker
+            ? []
+            : collectForeignSectionHeaders(text, end, text.length);
+        return { start, end, foreignSectionsPreserved };
     }
     const generated = text.indexOf(GENERATED_HEADER);
     if (generated !== -1) {
         const start = lineStartAt(text, generated);
-        const end = findLegacyRangeEnd(text, start);
+        const scan = scanOwnedContentEnd(text, start);
+        const end = scan.end;
         const candidate = text.slice(start, end);
         if (candidate.includes("[[hooks.") ||
             candidate.includes("[[hooks.pre_tool_use]]")) {
-            return { start, end };
+            const foreignSectionsPreserved = scan.sawEndMarker
+                ? []
+                : collectForeignSectionHeaders(text, end, text.length);
+            return { start, end, foreignSectionsPreserved };
         }
     }
     return null;
@@ -114,10 +575,198 @@ export function validateCodexManagedConfig(content) {
         }
     }
 }
+/** Parses a Codex config for the safety net below. A leading UTF-8 byte
+ * order mark is not TOML content, so it is skipped for parsing only (the
+ * bytes written are never changed here). Integers beyond JavaScript's safe
+ * range, which TOML allows (64-bit), come back as a `bigint` instead of
+ * failing the parse. */
+function parseToml(content) {
+    const body = content.startsWith("\uFEFF") ? content.slice(1) : content;
+    return parseTomlDocument(body, { integersAsBigInt: "asNeeded" });
+}
+/** Where and why the parser rejected a document, for a refusal message:
+ * the line and column it reports plus the first line of its message, and
+ * nothing else. The rest of a `TomlError` message is a code frame quoting
+ * the surrounding lines of the document verbatim; a Codex config holds
+ * secrets (API tokens under `[mcp_servers.*]`), and a refusal is printed to
+ * stderr and into `--json` output, so that frame is never included. Any
+ * other error is reduced to its name for the same reason. */
+function describeTomlParseError(err) {
+    if (err instanceof TomlError) {
+        const firstLine = err.message.split("\n", 1)[0] ?? "";
+        const reason = firstLine.replace(/^Invalid TOML document: /, "");
+        return `line ${err.line}, column ${err.column}: ${reason}`;
+    }
+    return err instanceof Error ? err.name : "unknown parse error";
+}
+/** True for a parsed TOML table: a non-array, non-date object. */
+function isTomlTable(value) {
+    return (typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Date));
+}
+/** Every ARRAY-valued key directly under `doc.hooks` (the `[[hooks.<Event>]]`
+ * event arrays, the only shape the installer writes) removed, keeping every
+ * other `hooks.*` key (single tables such as `hooks.state`, or any future
+ * non-array key) untouched. Everything the result still holds, including all
+ * of `hooks.state`, is not the installer's to change. The stripped `hooks`
+ * map is a null-prototype object, so a key literally named `__proto__`
+ * stays an own key instead of re-pointing the map's prototype and dropping
+ * out of the comparison. A non-table `doc`, and a missing or non-table
+ * `hooks` value, are returned as-is: there is nothing to strip. */
+function stripManagedHookArrays(doc) {
+    if (!isTomlTable(doc))
+        return doc;
+    const obj = doc;
+    const hooks = obj.hooks;
+    if (!isTomlTable(hooks))
+        return obj;
+    const strippedHooks = Object.create(null);
+    for (const [key, value] of Object.entries(hooks)) {
+        if (Array.isArray(value))
+            continue;
+        strippedHooks[key] = value;
+    }
+    const result = { ...obj };
+    if (Object.keys(strippedHooks).length === 0) {
+        // A document all of whose `hooks.*` keys were array-valued (the
+        // common case: nothing but harness-managed event arrays) must strip
+        // down to "no hooks key at all", the same as a document that never
+        // had one, so the comparison never flags the mere PRESENCE of an
+        // (empty, post-strip) `hooks` table as a semantic difference.
+        delete result.hooks;
+    }
+    else {
+        result.hooks = strippedHooks;
+    }
+    return result;
+}
+/** A date/time value's identity for comparison: its as-written TOML form
+ * (`TomlDate.toISOString` keeps local date, local time, local date-time
+ * and offset forms apart), or `invalid` for an unparseable date. */
+function dateIdentity(value) {
+    return Number.isNaN(value.getTime()) ? "invalid" : value.toISOString();
+}
+/** The path (as a dotted string once joined by the caller) to the first
+ * value at which `a` and `b` differ, walking tables and arrays recursively
+ * and comparing primitives (including `bigint`) with `Object.is` and
+ * date/time values by `dateIdentity`; `null` means the two are deeply
+ * equal. A key present on one side only is a difference at that key (and,
+ * when it holds a table, at that table's first key). Key
+ * order follows `a`'s own insertion order first, then any key present only
+ * in `b`, so the reported path is deterministic. */
+function firstDifferingKeyPath(a, b, path) {
+    if (a instanceof Date || b instanceof Date) {
+        if (!(a instanceof Date) || !(b instanceof Date))
+            return path;
+        return dateIdentity(a) === dateIdentity(b) ? null : path;
+    }
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return path;
+        for (let i = 0; i < a.length; i += 1) {
+            const diff = firstDifferingKeyPath(a[i], b[i], [...path, String(i)]);
+            if (diff)
+                return diff;
+        }
+        return null;
+    }
+    if (typeof a === "object" && a !== null && typeof b === "object" && b !== null) {
+        const aObj = a;
+        const bObj = b;
+        const keys = new Set([...Object.keys(aObj), ...Object.keys(bObj)]);
+        for (const key of keys) {
+            const aHas = Object.hasOwn(aObj, key);
+            if (aHas !== Object.hasOwn(bObj, key)) {
+                // A whole table present on one side only: name its first key too
+                // (`hooks.state` rather than just `hooks`), so the refusal points at
+                // what was lost.
+                const present = aHas ? aObj[key] : bObj[key];
+                const child = isTomlTable(present) ? Object.keys(present)[0] : undefined;
+                return child === undefined ? [...path, key] : [...path, key, child];
+            }
+            const diff = firstDifferingKeyPath(aObj[key], bObj[key], [...path, key]);
+            if (diff)
+                return diff;
+        }
+        return null;
+    }
+    return Object.is(a, b) ? null : path;
+}
+/**
+ * The TOML-semantic safety net (task 6a037359). The byte-preserving text
+ * splice in `planCodexConfigInstall` stays the source of truth for what gets
+ * WRITTEN; before it is written, `currentContent` and `nextContent` are
+ * both parsed and compared, and the install refuses rather than writes when
+ * the comparison finds a change outside what the installer owns. It exists
+ * to catch a scanner defect (a shape the line-based scan above mishandles)
+ * that would otherwise silently drop or alter operator- or Codex-owned
+ * content.
+ *
+ * The invariant: both documents must parse, and once every ARRAY-valued key
+ * directly under `hooks` (the `[[hooks.<Event>]]` event arrays) is removed
+ * from both, what remains must be deep-equal. What remains is everything
+ * outside the hook event arrays: `hooks.state` and every other single-table
+ * `hooks.*` key, plus all non-hooks content (top-level keys, `projects`,
+ * `plugins`, `marketplaces`, `mcp_servers`, `tui`, ...). A refusal names the
+ * first differing key path.
+ *
+ * What it does NOT check: the hook event arrays themselves. The installer
+ * rewrites its own entries there, and telling an operator-authored entry
+ * from a harness-written one would need the same line-level reading of the
+ * file this net is meant to be independent of. An operator-authored
+ * `[[hooks.<Event>]]` entry that the line scan wrongly counts as part of
+ * the harness-managed block is therefore replaced without a refusal
+ * (follow-up task 01053b27).
+ *
+ * Parsing goes through `parseToml` (a leading byte order mark ignored,
+ * 64-bit integers kept as `bigint`). A document that does not parse refuses
+ * with the parser's line, column and one-line reason only, never the
+ * document's own text (`describeTomlParseError`). This function never
+ * touches the file, and a `--dry-run` plan reports the same refusal a real
+ * install would (both go through `planCodexConfigInstall`).
+ */
+export function assertConfigSemanticInvariant(currentContent, nextContent, configPath) {
+    let currentDoc;
+    try {
+        currentDoc = parseToml(currentContent);
+    }
+    catch (err) {
+        throw new CodexInstallRefusalError(`Codex config ${configPath}: the TOML parser used by harness could not read this file ` +
+            `(${describeTomlParseError(err)}); refusing to install, because without parsing it ` +
+            "harness cannot confirm that every table outside the harness-managed hook block " +
+            "would survive the install. The file is untouched. If Codex itself loads this file, " +
+            "the construct at that position is one this parser does not support; please report " +
+            "it as a harness issue (the construct, not its value).", configPath);
+    }
+    let nextDoc;
+    try {
+        nextDoc = parseToml(nextContent);
+    }
+    catch (err) {
+        throw new CodexInstallRefusalError(`The Codex config harness would write to ${configPath} would not parse as TOML ` +
+            `(in the would-be output, ${describeTomlParseError(err)}); refusing to write a config ` +
+            "that would not load. The file is untouched. A common cause is the current file " +
+            "already defining `hooks`, or a hook event under it, in a form the generated " +
+            "`[[hooks.<Event>]]` tables cannot extend: an inline table such as `hooks = { ... }`, " +
+            "or an inline array such as `PreToolUse = []` under `[hooks]`. Rewrite that " +
+            "definition as `[hooks.<name>]` / `[[hooks.<Event>]]` tables (or remove it), then " +
+            "re-run `harness apply --runtime codex --install`. If the file has no such " +
+            "definition, this points at a harness defect (in the generated hook block, or in " +
+            "where the install placed it); please report it with the config's shape, not its values.", configPath);
+    }
+    const diffPath = firstDifferingKeyPath(stripManagedHookArrays(currentDoc), stripManagedHookArrays(nextDoc), []);
+    if (diffPath) {
+        throw new CodexInstallRefusalError(`Codex config ${configPath}: installing would change '${diffPath.join(".")}', which is ` +
+            "not a harness-managed hook event array; refusing to install rather than risk " +
+            "silently dropping or altering operator- or Codex-owned content. The file is " +
+            `untouched. If it looks wrong, restore it from the most recent .harness-backup-* file ` +
+            "(if one exists), or file an issue with the config shape that triggered this.", configPath);
+    }
+}
 export function planCodexConfigInstall(opts) {
     validateCodexManagedConfig(opts.generatedContent);
     const configPath = opts.configPath ?? defaultCodexConfigPath(opts.homeDir);
     let currentContent = "";
+    let configExisted = true;
     try {
         currentContent = fs.readFileSync(configPath, "utf8");
     }
@@ -125,13 +774,24 @@ export function planCodexConfigInstall(opts) {
         const e = err;
         if (e.code !== "ENOENT")
             throw err;
+        configExisted = false;
     }
     const managedBlock = buildManagedBlock(opts.generatedContent, opts.generatedPath);
-    const range = findManagedRange(currentContent);
+    const range = findManagedRange(currentContent, configPath);
     let nextContent;
     let summary;
+    let removedHookIds = [];
+    let foreignSectionsPreserved = [];
     if (range) {
-        nextContent = `${currentContent.slice(0, range.start)}${managedBlock}${currentContent.slice(range.end)}`;
+        const oldHookIds = extractHookIds(currentContent.slice(range.start, range.end));
+        const newHookIds = extractHookIds(managedBlock);
+        removedHookIds = [...oldHookIds].filter((id) => !newHookIds.has(id));
+        foreignSectionsPreserved = range.foreignSectionsPreserved;
+        const middleForeign = range.strayEnd
+            ? currentContent.slice(range.end, range.strayEnd.start)
+            : "";
+        const tailStart = range.strayEnd ? range.strayEnd.end : range.end;
+        nextContent = `${currentContent.slice(0, range.start)}${managedBlock}${middleForeign}${currentContent.slice(tailStart)}`;
         summary = `updated harness-managed Codex hook block in ${configPath}`;
     }
     else {
@@ -145,27 +805,58 @@ export function planCodexConfigInstall(opts) {
         nextContent = `${currentContent}${prefix}${managedBlock}`;
         summary = `installed harness-managed Codex hook block into ${configPath}`;
     }
+    if (currentContent !== nextContent) {
+        assertConfigSemanticInvariant(currentContent, nextContent, configPath);
+    }
     return {
         configPath,
         generatedPath: opts.generatedPath,
         currentContent,
         nextContent,
         changed: currentContent !== nextContent,
+        configExisted,
         summary: currentContent === nextContent
             ? `Codex config already up to date: ${configPath}`
             : summary,
+        removedHookIds,
+        foreignSectionsPreserved,
     };
 }
 function timestampForBackup(now) {
     return now.toISOString().replace(/[:.]/g, "-");
 }
+/** 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) {
+    try {
+        return fs.statSync(filePath).mode & 0o777;
+    }
+    catch (err) {
+        const e = err;
+        if (e.code !== "ENOENT")
+            throw err;
+        return 0o600;
+    }
+}
 export function writeCodexConfigInstall(plan, opts = {}) {
     if (!plan.changed)
         return { ...plan, written: false };
-    const backupPath = `${plan.configPath}.harness-backup-${timestampForBackup(opts.now ?? new Date())}`;
     fs.mkdirSync(path.dirname(plan.configPath), { recursive: true });
-    atomicWriteFile(backupPath, plan.currentContent);
-    atomicWriteFile(plan.configPath, plan.nextContent);
+    const mode = existingFileMode(plan.configPath);
+    // 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.
+    if (!plan.configExisted) {
+        atomicWriteFile(plan.configPath, plan.nextContent, { mode });
+        return { ...plan, written: true };
+    }
+    const backupPath = `${plan.configPath}.harness-backup-${timestampForBackup(opts.now ?? new Date())}`;
+    atomicWriteFile(backupPath, plan.currentContent, { mode });
+    atomicWriteFile(plan.configPath, plan.nextContent, { mode });
     return { ...plan, backupPath, written: true };
 }
 //# sourceMappingURL=install-codex-config.js.map