@lannguyensi/harness 0.59.0 → 0.59.2

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

@@ -25,6 +25,9 @@ export class CodexInstallRefusalError extends HarnessExitError {
     }
 }
 const GENERATED_HEADER = "# Generated by harness apply --runtime codex.";
+/** How the split-block refusal names a legacy generated header as the line
+ * its block starts at (`assertNoSplitBlock`, `findManagedRange`). */
+const GENERATED_HEADER_OPENING = `the '${GENERATED_HEADER}' line`;
 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_]*\]\]$/;
 // A single, unquoted-or-quoted TOML bare/quoted key: `foo-bar_1`, a basic
@@ -45,7 +48,11 @@ const TOML_KEY = String.raw `(?:[A-Za-z0-9_-]+|"(?:[^"\\]|\\.)*"|'[^']*')`;
 // 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).
+// early (task 6a037359). A lone element on its own line (`["x"]`, `['x']`,
+// `[1]`, `[1979-05-27]`) does have the shape of a header, so this regex is
+// only a candidate filter: every caller also requires `createTopLevelProbe`
+// before treating a match as a real header (task 6b56d735), the scans
+// through `createLineClassifier` (task 01053b27).
 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
@@ -53,6 +60,16 @@ const NON_HOOK_TABLE_RE = new RegExp(String.raw `^\[(?!\[hooks\.)\[?\s*${TOML_KE
 // between two harness hook tables (see `assertNoSplitBlock`).
 const HARNESS_HOOK_COMMENT_PREFIX = "# harness hook: ";
 const HOOK_ID_LINE_RE = /^# harness hook: (.+) \(budget_ms=\d+\)$/;
+// A `[[hooks.<Event>]]` array-of-tables header, harness-written or not.
+// `NON_HOOK_TABLE_RE` deliberately excludes it, so the ownership scan tells
+// the two apart by the `# harness hook:` comment above the header instead
+// (see `scanOwnedContentEnd`).
+const HOOK_ARRAY_HEADER_RE = /^\[\[hooks\./;
+/** True when a run of comment/blank lines holds a line the generator writes
+ * above every hook table (`# harness hook: <id> (budget_ms=N)`). */
+function runHoldsHarnessHookComment(run) {
+    return run.split("\n").some((line) => line.trim().startsWith(HARNESS_HOOK_COMMENT_PREFIX));
+}
 export function defaultCodexConfigPath(homeDir) {
     return path.join(homeDir ?? os.homedir(), ".codex", "config.toml");
 }
@@ -202,9 +219,72 @@ function findExactLine(text, target, from) {
     }
     return -1;
 }
+/** Answers, for a line start in `text`, whether that line sits at the top
+ * level of the document, that is, not inside a multi-line array, a multi-line
+ * inline table or a multi-line string opened by an earlier line. The document
+ * parser is the oracle: the text before the line parses on its own exactly
+ * when nothing is still open there, whereas a prefix that ends inside an
+ * array is an unterminated array and fails. A line that merely LOOKS like a
+ * table header (an array element on its own line such as `["x"]`, `['x']`,
+ * `[1]` or `[1979-05-27]`) is therefore told apart from a real header even
+ * when a real table of the same name exists elsewhere in the document, which
+ * a lookup of the header's key path in the parsed document could not do.
+ * A line inside an open construct never has a prefix that parses, so such a
+ * line is never taken for a header.
+ *
+ * The verdict is the full-prefix verdict: a line is top level when
+ * `text.slice(0, lineStart)` parses. The probe first tries a fast path: it
+ * remembers the last line start it confirmed as top level and parses only
+ * the text from there; when that segment parses, the line is confirmed
+ * without parsing the full prefix. When the segment fails, the full prefix
+ * decides, and a line it accepts is confirmed too. The segment is not
+ * claimed to agree with the full prefix: a segment can fail where the full
+ * prefix parses (a sub-table `[hooks.Stop.meta]` confirmed, then the next
+ * `[[hooks.Stop]]` element, which is never a candidate and so stays in the
+ * segment, redefines `hooks.Stop` as seen from the segment alone), and then
+ * the full prefix is what answers. So a line is reported as not top level
+ * only when the full prefix fails, and a line whose full prefix parses is
+ * always reported as top level. The fast path can only answer "top level"
+ * where the full prefix fails if the prefix holds a conflict of its own (a
+ * table defined twice); such a document does not parse as a whole, and the
+ * install refuses it through the parse check on the config either way. Even
+ * then the segment starts at a confirmed line with nothing open, so a line
+ * inside an open array, inline table or multi-line string still fails it.
+ *
+ * Cost: a real table confirmed on the fast path costs a segment parse. Any
+ * candidate whose segment fails costs a full-prefix parse too: an array
+ * element on its own line, or a sub-table after a later element of the same
+ * array of tables. Many of those are quadratic in their number (seconds at
+ * thousands; the CHANGELOG entry for this change has the measurements).
+ * Both scans query non-decreasing line starts. A query
+ * before the last confirmed line start throws instead of answering; a line
+ * reported as not top level is never confirmed, so it never moves that
+ * bound (task 6b56d735). Exported for direct tests only. */
+export function createTopLevelProbe(text) {
+    let confirmed = 0;
+    const parses = (content) => {
+        try {
+            parseToml(content);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    return (lineStart) => {
+        if (lineStart < confirmed) {
+            throw new Error(`top-level probe queried at offset ${lineStart}, before the last confirmed line start ${confirmed}`);
+        }
+        const topLevel = parses(text.slice(confirmed, lineStart)) ||
+            (confirmed > 0 && parses(text.slice(0, lineStart)));
+        if (topLevel)
+            confirmed = lineStart;
+        return topLevel;
+    };
+}
 /** 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. */
+ * `limit`), trimmed, with the offset its line starts at. 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);
@@ -212,11 +292,59 @@ function firstContentLine(text, from, limit) {
         const lineEnd = Math.min(lineEndAfter(text, pos), end);
         const trimmed = text.slice(pos, lineEnd).trim();
         if (trimmed !== "" && !trimmed.startsWith("#"))
-            return trimmed;
+            return { line: trimmed, start: pos };
         pos = lineEnd;
     }
     return null;
 }
+/**
+ * The one line classifier every header scan of the install uses (the
+ * managed-range scan, the foreign-section listing, the kept hook table scan
+ * and the hook header map), so a line is read the same way wherever it is
+ * met (task 01053b27). Called once per line, in order, from a line start at
+ * which nothing is open. The rule, applied in this order:
+ *
+ * 1. A line that starts inside a multi-line string opened by an earlier line
+ *    (`nextTripleDelim`) is `string`: string content, whatever it looks like.
+ * 2. A blank line or a `#` comment line is `comment` (the END marker and the
+ *    `# harness hook:` lines are comment lines the callers check by text).
+ * 3. A line starting `[[hooks.` is `hookHeader`. No parse is needed: a dotted
+ *    bare key is not a TOML value, so in a config that parses such a line is
+ *    never inside an array or inline table, and a config that does not parse
+ *    is refused by the parse checks before anything is written.
+ * 4. Any other line with the shape of a table header (`NON_HOOK_TABLE_RE`)
+ *    is `foreignHeader` only when it starts at the top level of the document
+ *    (`createTopLevelProbe`); otherwise it is an array element on its own
+ *    line inside a multi-line value (`["x"]`, `['x']`, `[1]`,
+ *    `[1979-05-27]`) and is `content`, never a header.
+ * 5. Every other line is `content` (a key/value line or a continuation line
+ *    of a multi-line value).
+ *
+ * `wanted` narrows rule 4 for a scan that only uses some headers: a
+ * header-shaped line it rejects is `content` for that scan without the
+ * top-level probe, whose full-prefix parse is the cost of rule 4 (see
+ * `createTopLevelProbe`). Only the hook header map passes one, since it
+ * resolves nothing but headers whose root key is `hooks`.
+ */
+function createLineClassifier(text, wanted = () => true) {
+    let delim = null;
+    const startsAtTopLevel = createTopLevelProbe(text);
+    return (lineStart, rawLine) => {
+        const startedInsideString = delim !== null;
+        delim = nextTripleDelim(rawLine, delim);
+        if (startedInsideString)
+            return "string";
+        const trimmed = rawLine.trim();
+        if (trimmed === "" || trimmed.startsWith("#"))
+            return "comment";
+        if (HOOK_ARRAY_HEADER_RE.test(trimmed))
+            return "hookHeader";
+        if (NON_HOOK_TABLE_RE.test(trimmed) && wanted(trimmed) && startsAtTopLevel(lineStart)) {
+            return "foreignHeader";
+        }
+        return "content";
+    };
+}
 /**
  * Scans forward from `start` classifying each line as either still-owned
  * harness content or the start of foreign (non-harness) content, WITHOUT
@@ -235,7 +363,24 @@ function firstContentLine(text, from, limit) {
  * 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);
+ * of ours (`NON_HOOK_TABLE_RE`, mirroring the pre-existing legacy scan) and
+ * sits at the top level of the document (`createTopLevelProbe`: an array
+ * element on its own line inside a multi-line value has the same shape but
+ * is not a header), or
+ * a `[[hooks.<Event>]]` header without a `# harness hook:` comment above it
+ * that comes after at least one header that has one (task 01053b27).
+ * Failure modes of that second rule: a harness table whose comment an
+ * operator deleted ends the range there (a later harness table still
+ * carrying its comment, before the END marker when one follows, lands in
+ * the zone `assertNoSplitBlock` refuses on; a
+ * last table stays as an operator table, which the install names in
+ * `keptOperatorHookTables` and refuses when its command is one harness
+ * writes, see `assertKeptHookTablesAreOperatorOwned`); a
+ * block that never carried the comments (older generator output) has no
+ * marked table before its first hook table, so it is consumed whole as
+ * before. Bare `key =` lines of an operator table follow that table out of
+ * the range; bare keys placed directly under a harness table cannot be told
+ * apart from the harness table's own fields and are still consumed with it;
  * 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,
@@ -251,33 +396,66 @@ function firstContentLine(text, from, limit) {
 function scanOwnedContentEnd(text, start) {
     let pos = start;
     let commentRunStart = null;
-    let delim = null;
+    let sawOwnedContent = false;
+    let sawMarkedHookTable = false;
+    const classify = createLineClassifier(text);
     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) {
+        const kind = classify(pos, rawLine);
+        if (kind === "string") {
             commentRunStart = null;
+            sawOwnedContent = true;
             pos = lineEnd;
             continue;
         }
-        const trimmed = rawLine.trim();
-        if (trimmed === CODEX_MANAGED_END) {
+        if (rawLine.trim() === CODEX_MANAGED_END) {
             return { end: lineEnd, sawEndMarker: true };
         }
-        if (trimmed === "" || trimmed.startsWith("#")) {
+        if (kind === "comment") {
             if (commentRunStart === null)
                 commentRunStart = pos;
             pos = lineEnd;
             continue;
         }
-        if (NON_HOOK_TABLE_RE.test(trimmed)) {
+        if (kind === "foreignHeader") {
             return { end: commentRunStart ?? pos, sawEndMarker: false };
         }
+        if (kind === "hookHeader") {
+            const marked = commentRunStart !== null &&
+                runHoldsHarnessHookComment(text.slice(commentRunStart, pos));
+            if (marked) {
+                sawMarkedHookTable = true;
+            }
+            else if (sawMarkedHookTable) {
+                // An operator-authored hook table (no `# harness hook:` comment
+                // above it) after the harness tables ends the owned region, like a
+                // foreign table, and keeps a comment attached to it (task 01053b27).
+                return { end: commentRunStart ?? pos, sawEndMarker: false, endedAtOperatorHookTable: true };
+            }
+        }
         commentRunStart = null;
+        sawOwnedContent = true;
         pos = lineEnd;
     }
+    // No END marker and no foreign table: a run of blank/comment lines that
+    // reaches EOF and holds at least one comment is an operator's trailing
+    // comment, not harness content, so back off to the start of that run
+    // (task b34ed105). Not when the run holds a harness-authored line (the
+    // generated header, a `# harness hook:` line, the source prefix: the
+    // generator itself writes comment-only content, so such a run is stale
+    // harness output that must be replaced), and not before the scan has seen
+    // an owned content line. A run of only blank lines is still consumed.
+    if (commentRunStart !== null && sawOwnedContent) {
+        const run = text.slice(commentRunStart, pos);
+        const hasComment = /(^|\n)[ \t]*#/.test(run);
+        const harnessAuthored = run.includes(HARNESS_HOOK_COMMENT_PREFIX) ||
+            run.includes(CODEX_MANAGED_SOURCE_PREFIX) ||
+            run.includes(GENERATED_HEADER);
+        if (hasComment && !harnessAuthored) {
+            return { end: commentRunStart, sawEndMarker: false };
+        }
+    }
     return { end: pos, sawEndMarker: false };
 }
 /**
@@ -307,9 +485,21 @@ function scanOwnedContentEnd(text, start) {
  * 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).
+ * offered instead (task 6a037359). `blockOpening` names the line the block
+ * starts at in the delete-the-lines fix: the BEGIN marker by default; a
+ * legacy config (no BEGIN marker) whose END marker survived passes its
+ * source-prefix line or generated header instead, since a BEGIN marker it
+ * does not have is no line to delete from (task 01053b27). For the generated
+ * header the fix deletes that line and the END marker line too: a generated
+ * header left alone above END no longer marks a harness block
+ * (`findManagedRange` needs a `[[hooks.` line after it), so the install
+ * would add a fresh block and leave that pair behind as an orphan. Exported for
+ * direct tests only: the scan
+ * that feeds it never hands it a line that is not a real header, so its own
+ * naming rule is reachable in isolation only by calling it directly (task
+ * 6b56d735).
  */
-function assertNoSplitBlock(text, from, to, configPath, hasEndMarker) {
+export function assertNoSplitBlock(text, from, to, configPath, hasEndMarker, blockOpening = `'${CODEX_MANAGED_BEGIN}'`) {
     const zoneStart = Math.max(from, 0);
     const zoneEnd = Math.max(to, from);
     const zone = text.slice(zoneStart, zoneEnd);
@@ -338,13 +528,31 @@ function assertNoSplitBlock(text, from, to, configPath, hasEndMarker) {
     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`;
+    const firstForeignHeader = describeForeignHeaderLine(text, foreignHeaderLine);
+    const fixes = hasEndMarker
+        ? [
+            `move ${firstForeignHeader} below the '${CODEX_MANAGED_END}' marker`,
+            blockOpening === GENERATED_HEADER_OPENING
+                ? `delete every line from ${blockOpening} through the '${CODEX_MANAGED_END}' marker ` +
+                    "line, both included, so the install writes a fresh harness block"
+                : `delete the lines between ${blockOpening} 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})`,
+            `move ${firstForeignHeader} below the last harness hook table`,
+        ];
+    // An uncommented hook table in the middle may be a harness table whose
+    // comment line was deleted, so moving it (the operator-table fix) is only
+    // right for an operator-owned one; name the restore option first (task
+    // 01053b27).
+    const isHookTable = HOOK_ARRAY_HEADER_RE.test(foreignHeaderLine?.line ?? "");
+    const guidance = isHookTable
+        ? `If ${firstForeignHeader} is a harness hook table whose '${HARNESS_HOOK_COMMENT_PREFIX}<id> ` +
+            "(budget_ms=<n>)' comment line was deleted, restore that comment line directly above it. " +
+            `If it is an operator-owned table, ${fixes.join(", or ")}`
+        : fixes.join(", or ").replace(/^./, (c) => c.toUpperCase());
     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 " +
@@ -377,6 +585,23 @@ function parseTableHeader(line) {
 function describeTableHeader(line) {
     return parseTableHeader(line)?.header ?? "(unknown)";
 }
+/** How a refusal names the line it found where the foreign table's header
+ * should be. A verified header prints as its bracketed key path. A line that
+ * has the shape of a header but is not one (an array element on its own line
+ * inside a multi-line value) is never printed, since it can hold a config
+ * value such as a token; only its line number is. Any other line is
+ * `(unknown)`, as before. */
+function describeForeignHeaderLine(text, found) {
+    if (found === null)
+        return "(unknown)";
+    const parsed = parseTableHeader(found.line);
+    if (parsed === null)
+        return "(unknown)";
+    if (!createTopLevelProbe(text)(found.start)) {
+        return `line ${lineNumberAt(text, found.start)}`;
+    }
+    return parsed.header;
+}
 /** 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
@@ -420,18 +645,12 @@ function collectForeignSectionHeaders(text, from, to) {
     const counts = new Map();
     let pos = Math.max(from, 0);
     const limit = Math.max(to, from);
-    let delim = null;
+    const classify = createLineClassifier(text);
     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)) {
+        if (classify(pos, rawLine) === "foreignHeader") {
+            const trimmed = rawLine.trim();
             const root = foreignSectionRootKey(trimmed);
             counts.set(root, (counts.get(root) ?? 0) + 1);
             if (!seenRoots.has(root)) {
@@ -456,6 +675,107 @@ function extractHookIds(content) {
     }
     return ids;
 }
+/**
+ * The operator-authored hook tables directly after a managed range that
+ * ended at one (`scanOwnedContentEnd`'s `endedAtOperatorHookTable`): every
+ * `[[hooks.*]]` header from `from` up to the first non-hook table header or
+ * `to`, each by header, line number and offset. Lines are read by
+ * `createLineClassifier`, so an array element on its own line inside a kept
+ * table's multi-line value neither ends the run nor is named, and a hook
+ * table after it is still collected (task 01053b27). Empty for any other ending
+ * (the first header at `from` is then a non-hook table, or there is none).
+ * The caller has already refused a zone that holds a harness marker
+ * (`assertNoSplitBlock`), so no header found here carries a `# harness
+ * hook:` comment.
+ */
+function collectKeptHookTables(text, from, to) {
+    const tables = [];
+    let pos = from;
+    const classify = createLineClassifier(text);
+    while (pos < to) {
+        const lineEnd = Math.min(lineEndAfter(text, pos), to);
+        const rawLine = text.slice(pos, lineEnd);
+        const kind = classify(pos, rawLine);
+        if (kind === "foreignHeader")
+            break;
+        if (kind === "hookHeader") {
+            tables.push({ header: describeTableHeader(rawLine), line: lineNumberAt(text, pos), start: pos });
+        }
+        pos = lineEnd;
+    }
+    return tables;
+}
+/** A kept table as the install names it: its header, its 1-based line
+ * number in the config before the install and in the config the install
+ * writes (`nextLines`, same order as `kept`), never any value text. */
+function describeKeptHookTables(kept, nextLines) {
+    return kept.map((t, i) => `${t.header} (line ${t.line} before the install, line ${nextLines[i]} after it)`);
+}
+const UTF8_BOM = "\uFEFF";
+/** A leading UTF-8 BOM is not part of any managed range: a range that would
+ * start at offset 0 starts just past the BOM instead, so the splice keeps
+ * the BOM exactly once (task b34ed105). */
+function startPastBom(text, start) {
+    return start === 0 && text.startsWith(UTF8_BOM) ? UTF8_BOM.length : start;
+}
+/**
+ * The range from `start` to `end`, where the ownership scan stopped short of
+ * an END marker, plus what it keeps after `end`: when a stray END marker line
+ * follows (a drifted END), the zone up to it is checked for a split block
+ * (`assertNoSplitBlock`), its foreign sections and kept operator hook tables
+ * are collected, and that END line is excised by the splice (`strayEnd`);
+ * without one, the same happens up to the end of the document. Content below
+ * that END line is never read here and the splice leaves it untouched.
+ * `blockOpening` is the line the split-block refusal names as the start of
+ * the block (`assertNoSplitBlock`; the BEGIN marker when omitted).
+ */
+function rangeBeforeStrayEnd(text, start, end, configPath, blockOpening) {
+    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);
+        const keptHookTables = collectKeptHookTables(text, end, text.length);
+        return { start, end, foreignSectionsPreserved, keptHookTables };
+    }
+    const strayLineStart = lineStartAt(text, strayIdx);
+    const strayLineEnd = lineEndAfter(text, strayIdx);
+    assertNoSplitBlock(text, end, strayLineStart, configPath, true, blockOpening);
+    const foreignSectionsPreserved = collectForeignSectionHeaders(text, end, strayLineStart);
+    const keptHookTables = collectKeptHookTables(text, end, strayLineStart);
+    return {
+        start,
+        end,
+        strayEnd: { start: strayLineStart, end: strayLineEnd },
+        foreignSectionsPreserved,
+        keptHookTables,
+    };
+}
+/**
+ * The range of a legacy (no BEGIN marker) config: the source-prefix or
+ * generated-header paths. When the scan ended at an operator hook table,
+ * the zone after it is handled like the BEGIN path's
+ * (`rangeBeforeStrayEnd`): an END marker that survived its deleted BEGIN
+ * line, sitting after the kept tables, is excised like a drifted END, so
+ * the install leaves no orphan END line below the kept tables and the
+ * kept-table refusal offers moving an operator-owned table below that END;
+ * a harness-commented table after the kept tables refuses through the
+ * split-block check instead of being kept as if it were operator content
+ * (the fresh block would repeat it) when it sits before that END, or
+ * anywhere later when no END follows. Content below that END is untouched,
+ * as on the BEGIN path, so a harness-commented table there is kept and not
+ * named. The split-block refusal names `blockOpening` (the source-prefix
+ * line or the generated header) as the start of the block, since there is
+ * no BEGIN marker (task 01053b27). Other endings keep the legacy behaviour.
+ */
+function legacyManagedRange(text, start, scan, configPath, blockOpening) {
+    if (scan.endedAtOperatorHookTable) {
+        return rangeBeforeStrayEnd(text, start, scan.end, configPath, blockOpening);
+    }
+    const foreignSectionsPreserved = scan.sawEndMarker
+        ? []
+        : collectForeignSectionHeaders(text, scan.end, text.length);
+    return { start, end: scan.end, foreignSectionsPreserved, keptHookTables: [] };
+}
 function findManagedRange(text, configPath) {
     const begin = text.indexOf(CODEX_MANAGED_BEGIN);
     if (begin !== -1) {
@@ -478,54 +798,36 @@ function findManagedRange(text, configPath) {
         }
         let start = lineStartAt(text, begin);
         const prev = previousLine(text, start);
-        if (prev && prev.text.startsWith(CODEX_MANAGED_SOURCE_PREFIX)) {
-            start = prev.start;
+        if (prev) {
+            // A BOM sitting before the source-prefix comment on line 1 must not
+            // hide the prefix from this check (task b34ed105).
+            const prevText = prev.start === 0 ? prev.text.replace(/^\uFEFF/, "") : prev.text;
+            if (prevText.startsWith(CODEX_MANAGED_SOURCE_PREFIX))
+                start = prev.start;
         }
+        start = startPastBom(text, start);
         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 };
-        }
-        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,
-        };
+            return { start, end, foreignSectionsPreserved: [], keptHookTables: [] };
+        }
+        return rangeBeforeStrayEnd(text, start, end, configPath);
     }
     const source = text.indexOf(CODEX_MANAGED_SOURCE_PREFIX);
     if (source !== -1) {
-        const start = lineStartAt(text, source);
-        const scan = scanOwnedContentEnd(text, start);
-        const end = scan.end;
-        const foreignSectionsPreserved = scan.sawEndMarker
-            ? []
-            : collectForeignSectionHeaders(text, end, text.length);
-        return { start, end, foreignSectionsPreserved };
+        const start = startPastBom(text, lineStartAt(text, source));
+        return legacyManagedRange(text, start, scanOwnedContentEnd(text, start), configPath, `the '${CODEX_MANAGED_SOURCE_PREFIX}' source-prefix line`);
     }
     const generated = text.indexOf(GENERATED_HEADER);
     if (generated !== -1) {
-        const start = lineStartAt(text, generated);
+        const start = startPastBom(text, lineStartAt(text, generated));
         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]]")) {
-            const foreignSectionsPreserved = scan.sawEndMarker
-                ? []
-                : collectForeignSectionHeaders(text, end, text.length);
-            return { start, end, foreignSectionsPreserved };
+            return legacyManagedRange(text, start, scan, configPath, GENERATED_HEADER_OPENING);
         }
     }
     return null;
@@ -714,8 +1016,12 @@ function firstDifferingKeyPath(a, b, path) {
  * 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).
+ * the harness-managed block is therefore replaced without a refusal (task
+ * 01053b27 covers the operator table after the harness tables, which the scan
+ * now keeps and names; still replaced silently are an operator table before
+ * the first harness table inside the block, one under a comment run that
+ * holds a `# harness hook:` line, bare keys directly under a harness table,
+ * and one after an old block that never carried the comments).
  *
  * Parsing goes through `parseToml` (a leading byte order mark ignored,
  * 64-bit integers kept as `bigint`). A document that does not parse refuses
@@ -863,6 +1169,222 @@ function withBackupLocation(linkPath, check) {
             `sit beside the link, as ${linkPath}.harness-backup-* files.`, err.configPath);
     }
 }
+/** A header key segment's name as TOML reads it: a bare key as written, a
+ * literal (`'...'`) key's inner text, a basic (`"..."`) key's inner text
+ * when it holds no escape sequence. `null` for a basic key with an escape,
+ * which this scan does not decode; a header holding one is not matched to a
+ * parsed entry (see `mapHookArrayHeaders`). */
+function resolvedKeyName(segment) {
+    const quote = segment[0];
+    if (quote === "'")
+        return segment.slice(1, -1);
+    if (quote === '"') {
+        const inner = segment.slice(1, -1);
+        return inner.includes("\\") ? null : inner;
+    }
+    return segment;
+}
+/** Whether a header-shaped line's first key resolves to `hooks`, the only
+ * root `mapHookArrayHeaders` resolves. */
+function hooksRooted(trimmed) {
+    return resolvedKeyName(parseTableHeader(trimmed)?.keys[0] ?? "") === "hooks";
+}
+function subKey(event, index) {
+    return `${event}\u0000${index}`;
+}
+/**
+ * Every table header of the whole document that appends to a hook
+ * event array (`[[hooks.<Event>]]`, however its keys are spelled) or to such
+ * an entry's own `hooks` array (`[[hooks.<Event>.hooks]]`), with the entry it
+ * appends: TOML appends each header's table to its array in document order,
+ * and a sub-array header to the array's LAST entry so far. Only the lines
+ * `createLineClassifier` reads as a header are resolved: a line inside a
+ * multi-line string, and an array element on its own line, are skipped. A line resolved
+ * to such a header cannot be a value line of a document that parses (a
+ * dotted bare path is not a TOML value), and a header this scan cannot
+ * resolve (an escape in a quoted key) is not counted, so the caller compares
+ * `eventCounts` and `subCounts` with the parsed arrays' lengths and treats a
+ * mismatch as "cannot match exactly". The classifier reads a header-shaped
+ * line as a header here only when its root key resolves to `hooks`
+ * (`hooksRooted`, checked before the top-level probe), so every header this
+ * scan resolves has the root `hooks` (a `[[hooks.` line has it by its
+ * prefix), a table outside `hooks` never shifts the order match, and an
+ * array element on its own line (`["x"]`, `[1]`) costs no parse in this
+ * scan, unless the element is the string `hooks` (`["hooks"]`,
+ * `['hooks']`): that line reads as a `hooks` root, so it is probed like the
+ * `hooks`-rooted spellings that `[[hooks.` does not catch
+ * (`[[ hooks.Stop ]]`, `[["hooks".Stop]]`, `[hooks.Stop]`), and the probe
+ * finds it inside the array.
+ */
+function mapHookArrayHeaders(text) {
+    const map = { slots: new Map(), eventCounts: new Map(), subCounts: new Map() };
+    let pos = 0;
+    const classify = createLineClassifier(text, hooksRooted);
+    while (pos < text.length) {
+        const lineEnd = lineEndAfter(text, pos);
+        const rawLine = text.slice(pos, lineEnd);
+        const kind = classify(pos, rawLine);
+        const parsed = kind === "hookHeader" || kind === "foreignHeader" ? parseTableHeader(rawLine) : null;
+        // The bracket kind is not checked: a single-bracket `[hooks.<Event>]`
+        // cannot coexist with a `[[hooks.<Event>]]` array in a document that
+        // parses, and a single-bracket `[hooks.<Event>.hooks]` makes that entry's
+        // `hooks` a table, whose `command` is not a hook command either way.
+        if (parsed !== null) {
+            const [, event, sub] = parsed.keys.map(resolvedKeyName);
+            if (typeof event === "string") {
+                const count = map.eventCounts.get(event) ?? 0;
+                if (parsed.keys.length === 2) {
+                    map.slots.set(pos, { event, index: count });
+                    map.eventCounts.set(event, count + 1);
+                }
+                else if (parsed.keys.length === 3 && sub === "hooks") {
+                    // Appends to the event's last entry so far; with no entry before
+                    // it (`index` -1) TOML makes the event a table, not an array, and
+                    // the caller finds no array to match.
+                    const key = subKey(event, count - 1);
+                    const subIndex = map.subCounts.get(key) ?? 0;
+                    map.slots.set(pos, { event, index: count - 1, subIndex });
+                    map.subCounts.set(key, subIndex + 1);
+                }
+            }
+        }
+        pos = lineEnd;
+    }
+    return map;
+}
+/** The hook command of one parsed hook entry, `{ command = "..." }`, as a
+ * one-element list; empty for anything else. */
+function hookCommandOf(entry) {
+    return isTomlTable(entry) && typeof entry.command === "string" ? [entry.command] : [];
+}
+/** The hook commands of one parsed `hooks.<Event>` entry: its own `command`
+ * plus each `command` of its `hooks` array (inline `hooks = [{ ... }]` or the
+ * expanded `[[hooks.<Event>.hooks]]` form). No other `command` key counts. */
+function eventEntryCommands(entry) {
+    if (!isTomlTable(entry))
+        return [];
+    const nested = Array.isArray(entry.hooks) ? entry.hooks.flatMap(hookCommandOf) : [];
+    return [...hookCommandOf(entry), ...nested];
+}
+/** Every hook command of a parsed document's `hooks.<Event>` arrays. */
+function documentHookCommands(doc) {
+    if (!isTomlTable(doc) || !isTomlTable(doc.hooks))
+        return [];
+    return Object.values(doc.hooks).flatMap((value) => Array.isArray(value) ? value.flatMap(eventEntryCommands) : []);
+}
+/**
+ * The hook commands a kept table defines, read from the parsed whole
+ * document (`doc`) at the entry its header appends (`map`): for
+ * `[[hooks.<Event>]]` the entry's own `command`, plus its `hooks` array's
+ * commands unless `[[hooks.<Event>.hooks]]` headers build that array (each
+ * of those is its own kept table); for `[[hooks.<Event>.hooks]]` that nested
+ * entry's `command`. A header appending nowhere else (`[[hooks.<Event>.x]]`)
+ * defines none. `null` when the header cannot be matched exactly: a header
+ * the scan did not resolve, a count of headers that differs from the parsed
+ * array's length, or a nested `hooks` header with no entry before it.
+ */
+function keptTableCommands(table, doc, map) {
+    const slot = map.slots.get(table.start);
+    if (slot === undefined) {
+        // Not an append the map resolved: a `[[hooks.<Event>.x]]` table holds no
+        // hook command; a header with a key the map does not resolve cannot be
+        // matched.
+        const resolved = parseTableHeader(table.header)?.keys.every((k) => resolvedKeyName(k) !== null);
+        return resolved === true ? [] : null;
+    }
+    const hooks = isTomlTable(doc) && isTomlTable(doc.hooks) ? doc.hooks : undefined;
+    const entries = hooks?.[slot.event];
+    if (!Array.isArray(entries) || entries.length !== map.eventCounts.get(slot.event))
+        return null;
+    const entry = entries[slot.index];
+    const subCount = map.subCounts.get(subKey(slot.event, slot.index)) ?? 0;
+    if (slot.subIndex === undefined) {
+        return subCount > 0 ? hookCommandOf(entry) : eventEntryCommands(entry);
+    }
+    const nested = isTomlTable(entry) && Array.isArray(entry.hooks) ? entry.hooks : [];
+    if (nested.length !== subCount)
+        return null;
+    return hookCommandOf(nested[slot.subIndex]);
+}
+/** The move-below-END option of a kept-table refusal: only when the config
+ * has an END marker after the kept tables, since below it the install never
+ * touches a table (an operator-owned table whose command starts with
+ * `harness `, the operator's own CLI, is kept that way). Every range with
+ * kept tables and an END marker after them records that marker as
+ * `strayEnd`, on the BEGIN path and on the legacy paths alike
+ * (`rangeBeforeStrayEnd`), so the caller keys the option on it. */
+function moveBelowEndOption(hasEndMarker) {
+    return hasEndMarker
+        ? `, or, if it is an operator-owned table, move it below the '${CODEX_MANAGED_END}' marker, ` +
+            "where the install never touches it"
+        : "";
+}
+/** Parses the whole document for the kept-table check, refusing with the
+ * parser's position and one-line reason only (never its code frame). */
+function parseForKeptTableCheck(content, what, configPath) {
+    try {
+        return parseToml(content);
+    }
+    catch (err) {
+        throw new CodexInstallRefusalError(`Codex config ${configPath}: the TOML parser used by harness could not read ${what} ` +
+            `(${describeTomlParseError(err)}), so harness cannot check the operator hook tables it ` +
+            "would keep after the harness hook tables; refusing to install. The file is untouched.", configPath);
+    }
+}
+/**
+ * Refuses (file untouched) when an operator hook table the install keeps
+ * looks like one harness wrote: one of its hook commands equals a command of
+ * the fresh block, or starts with `harness `. The line scan tells a harness
+ * table from an operator one only by the `# harness hook:` comment above it,
+ * so a harness table whose comment an operator deleted, sitting last, would
+ * otherwise be kept next to the fresh block: the hook would run twice, or a
+ * hook the manifest retired would keep running after every later install
+ * (task 01053b27). A retired hook whose command does not start with
+ * `harness ` (an environment-prefixed report-dir wrap, the memory-router
+ * hook, a custom manifest hook) is not recognised: it is kept and named only.
+ *
+ * The commands come from the parsed WHOLE document (the same `parseToml` the
+ * semantic net uses), each kept table matched to its parsed entry by the
+ * order of the `[[hooks.<Event>]]` headers (`mapHookArrayHeaders`); no part
+ * of the file is parsed on its own. Only hook commands count
+ * (`hooks.<Event>[].command` and `hooks.<Event>[].hooks[].command`), not any
+ * other key named `command`. A kept table that cannot be matched exactly
+ * refuses too. Every message names the table's header and line number only,
+ * never a command or any other value text, and never a parser code frame,
+ * since a refusal is printed to stderr and into `--json` output.
+ */
+function assertKeptHookTablesAreOperatorOwned(kept, currentContent, generatedContent, configPath, hasEndMarker) {
+    if (kept.length === 0)
+        return;
+    const freshCommands = new Set(documentHookCommands(parseForKeptTableCheck(generatedContent, "the generated hook block", configPath)));
+    const doc = parseForKeptTableCheck(currentContent, "this file", configPath);
+    const map = mapHookArrayHeaders(currentContent);
+    for (const table of kept) {
+        const commands = keptTableCommands(table, doc, map);
+        if (commands === null) {
+            throw new CodexInstallRefusalError(`Codex config ${configPath} has a hook table ${table.header} (line ${table.line}) with no ` +
+                `'${HARNESS_HOOK_COMMENT_PREFIX}<id> (budget_ms=<n>)' comment line above it, placed after the ` +
+                "harness hook tables, that harness could not match to its entry in the parsed config " +
+                "(a header it does not resolve: an escape sequence in a quoted key, on this table or on " +
+                "another table of the same hook event, or a nested hooks table it cannot place), so it " +
+                "cannot check whether harness wrote that table. Spell those header keys without escape " +
+                `sequences, restore the '${HARNESS_HOOK_COMMENT_PREFIX}<id> (budget_ms=<n>)' comment line ` +
+                `directly above ${table.header} if harness wrote it${moveBelowEndOption(hasEndMarker)}, or ` +
+                "delete the table, then re-run `harness apply --runtime codex --install`. The file is untouched.", configPath);
+        }
+        const harnessShaped = commands.some((command) => freshCommands.has(command) || command.startsWith("harness "));
+        if (!harnessShaped)
+            continue;
+        throw new CodexInstallRefusalError(`Codex config ${configPath} has a hook table ${table.header} (line ${table.line}) with no ` +
+            `'${HARNESS_HOOK_COMMENT_PREFIX}<id> (budget_ms=<n>)' comment line above it, placed after the ` +
+            "harness hook tables, whose command is one harness itself writes. harness cannot tell it " +
+            "from a harness hook table whose comment line was deleted, and keeping it next to the " +
+            "fresh harness block would run that hook twice (or keep a retired harness hook running). " +
+            `Restore the comment line directly above ${table.header}, so the install replaces the table ` +
+            `with the fresh block${moveBelowEndOption(hasEndMarker)}, or delete the table, then re-run ` +
+            `\`harness apply --runtime codex --install\`. The file is untouched.`, configPath);
+    }
+}
 export function planCodexConfigInstall(opts) {
     validateCodexManagedConfig(opts.generatedContent);
     const requestedPath = opts.configPath ?? defaultCodexConfigPath(opts.homeDir);
@@ -886,16 +1408,29 @@ export function planCodexConfigInstall(opts) {
     let summary;
     let removedHookIds = [];
     let foreignSectionsPreserved = [];
+    let keptHookTables = [];
+    let keptTableDescriptions = [];
+    let hasEndMarkerAfterKept = false;
     if (range) {
         const oldHookIds = extractHookIds(currentContent.slice(range.start, range.end));
         const newHookIds = extractHookIds(managedBlock);
         removedHookIds = [...oldHookIds].filter((id) => !newHookIds.has(id));
-        foreignSectionsPreserved = range.foreignSectionsPreserved;
+        keptHookTables = range.keptHookTables;
+        hasEndMarkerAfterKept = range.strayEnd !== undefined;
         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)}`;
+        // A kept table sits right after the fresh block in the written config
+        // (it is in `middleForeign`, or at the start of the tail when there is
+        // no stray END), so its offset there follows from the splice.
+        const shift = range.start + managedBlock.length - range.end;
+        keptTableDescriptions = describeKeptHookTables(keptHookTables, keptHookTables.map((t) => lineNumberAt(nextContent, t.start + shift)));
+        // The kept operator hook tables ride the same list, so the dry-run and
+        // the install summary name them exactly like the foreign tables kept
+        // beside them (task 01053b27).
+        foreignSectionsPreserved = [...range.foreignSectionsPreserved, ...keptTableDescriptions];
         summary = `updated harness-managed Codex hook block in ${configPath}${viaLink}`;
     }
     else {
@@ -912,6 +1447,7 @@ export function planCodexConfigInstall(opts) {
     if (currentContent !== nextContent) {
         withBackupLocation(linkPath, () => assertConfigSemanticInvariant(currentContent, nextContent, configPath));
     }
+    assertKeptHookTablesAreOperatorOwned(keptHookTables, currentContent, opts.generatedContent, configPath, hasEndMarkerAfterKept);
     return {
         configPath,
         ...(linkPath !== undefined ? { linkPath } : {}),
@@ -925,6 +1461,7 @@ export function planCodexConfigInstall(opts) {
             : summary,
         removedHookIds,
         foreignSectionsPreserved,
+        keptOperatorHookTables: keptTableDescriptions,
     };
 }
 function timestampForBackup(now) {