@lannguyensi/harness 0.60.0 → 0.62.0

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

@@ -65,11 +65,6 @@ const HOOK_ID_LINE_RE = /^# harness hook: (.+) \(budget_ms=\d+\)$/;
 // 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");
 }
@@ -189,35 +184,120 @@ function nextTripleDelim(rawLine, delimIn) {
     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.
+ * The one rule every managed-block marker is located by (task 36d962d2): a
+ * line is a marker line only when its trimmed text is the marker (`whole`)
+ * or starts with it (`prefix`) AND it sits at the top level of the document
+ * (`createTopLevelProbe`). Marker text anywhere else is operator content:
+ * inside a single-line or multi-line string (basic or literal), after a
+ * content line as a trailing comment, inside an inline table, or on a line
+ * inside a multi-line array (an element, or a comment line between
+ * elements). Treating such text as a marker made the install replace,
+ * delete, or splice a fresh block into the operator's value. Every lookup
+ * of BEGIN, END, the source prefix, the generated header and the
+ * `# harness hook:` comment goes through this probe or `findMarkerLine` (or
+ * `findMarkerAboveHookTable`, which calls the probe for its one candidate),
+ * and so does the `[[hooks.` header line that lets a generated header open a
+ * legacy block (`findManagedRange`), searched only up to the end of the range
+ * the scan owns.
+ * Two marker searches stay outside it on purpose: the split-block refusal's
+ * candidate list (`assertNoSplitBlock`), which can only refuse, never
+ * install, and the trailing comment run of `scanOwnedContentEnd`, whose
+ * lines are whole top-level comment lines by construction. That run (blank
+ * and comment lines ending the file after a block with no END marker) is
+ * consumed as stale harness output when the source prefix, the generated
+ * header or the `# harness hook:` text appears anywhere in it, so an
+ * operator comment there that mentions such text mid-line is removed with
+ * the block.
+ *
+ * The returned probe answers for line starts queried in non-decreasing
+ * order (the top-level probe's contract, which a line that fails the text
+ * test never touches).
  */
-function findExactLine(text, target, from) {
+function createMarkerLineProbe(text) {
+    const topLevel = createTopLevelProbe(text);
+    return (lineStart, marker, shape) => {
+        const trimmed = text.slice(lineStart, lineEndAfter(text, lineStart)).trim();
+        const textMatches = shape === "whole" ? trimmed === marker : trimmed.startsWith(marker);
+        return textMatches && topLevel(lineStart);
+    };
+}
+/** The start of the first marker line (`createMarkerLineProbe`) at or after
+ * the line start `from` and before `to`, or -1. Candidates are visited in
+ * order, one line each, so the probe's non-decreasing-offset contract holds.
+ * Every candidate that fails the text test is free, but one that passes it
+ * costs a parse of the document before it (`createTopLevelProbe`), so a caller
+ * that only needs a marker inside a known range passes that range's end as
+ * `to`: the search stops there instead of probing every candidate past it. */
+function findMarkerLine(text, marker, shape, from = 0, to = text.length) {
+    const isMarkerLine = createMarkerLineProbe(text);
     let pos = from;
+    for (;;) {
+        const idx = text.indexOf(marker, pos);
+        if (idx === -1)
+            return -1;
+        const lineStart = lineStartAt(text, idx);
+        if (lineStart >= to)
+            return -1;
+        if (isMarkerLine(lineStart, marker, shape))
+            return lineStart;
+        pos = lineEndAfter(text, lineStart);
+    }
+}
+/**
+ * The marker line (`createMarkerLineProbe`, prefix shape) that sits in the run
+ * of blank and comment lines directly above a hook table header, searched from
+ * the line start `from` (a line at which nothing is open) to the end of the
+ * document, with the header's offset; null when there is none. `isHookTable`
+ * says which header lines count as a hook table. This is how the two orphan
+ * shapes are found: a generated-header line above a hook table past a foreign
+ * table, and a `# harness hook:` comment line above a hook table with no block
+ * marker around it. The scan is linear and parses nothing for a line that is
+ * not such a pair: a line inside a multi-line string is skipped
+ * (`nextTripleDelim`), a content line ends the run, and only a marker-text
+ * line directly above a header reaches the probe, once, which confirms the
+ * line is at the top level. A comment run directly above a hook table header
+ * is at the top level in any config that parses (a header line is never inside
+ * an array), so the probe only turns away a config that does not parse, which
+ * the parse checks refuse anyway.
+ */
+function findMarkerAboveHookTable(text, marker, from, isHookTable) {
+    const isMarkerLine = createMarkerLineProbe(text);
     let delim = null;
+    let runMarker = null;
+    let pos = from;
     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 && rawLine.trim() === target)
-            return pos;
+        if (startedInsideString) {
+            runMarker = null;
+            pos = lineEnd;
+            continue;
+        }
+        const trimmed = rawLine.trim();
+        if (trimmed === "" || trimmed.startsWith("#")) {
+            if (runMarker === null && trimmed.startsWith(marker))
+                runMarker = pos;
+        }
+        else {
+            if (runMarker !== null && isHookTable(trimmed) && isMarkerLine(runMarker, marker, "prefix")) {
+                return { marker: runMarker, header: pos };
+            }
+            runMarker = null;
+        }
         pos = lineEnd;
     }
-    return -1;
+    return null;
+}
+/** True when a line in `[from, to)` is a marker line for the prefix
+ * `marker`. */
+function rangeHoldsMarkerLine(text, from, to, marker, isMarkerLine) {
+    for (let pos = from; pos < to; pos = lineEndAfter(text, pos)) {
+        if (isMarkerLine(pos, marker, "prefix"))
+            return true;
+    }
+    return false;
 }
 /** 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
@@ -398,7 +478,15 @@ function scanOwnedContentEnd(text, start) {
     let commentRunStart = null;
     let sawOwnedContent = false;
     let sawMarkedHookTable = false;
+    let firstContentLine = null;
+    let firstHookHeader = null;
+    // A key line before the first hook table header of the range, with that
+    // header, when both exist: see `OwnedContentScan.operatorLineBeforeHookTable`.
+    const keyBeforeHookTable = () => firstContentLine !== null && firstHookHeader !== null
+        ? { operatorLineBeforeHookTable: { line: firstContentLine, header: firstHookHeader } }
+        : {};
     const classify = createLineClassifier(text);
+    const isMarkerLine = createMarkerLineProbe(text);
     while (pos < text.length) {
         const lineEnd = lineEndAfter(text, pos);
         const rawLine = text.slice(pos, lineEnd);
@@ -409,8 +497,8 @@ function scanOwnedContentEnd(text, start) {
             pos = lineEnd;
             continue;
         }
-        if (rawLine.trim() === CODEX_MANAGED_END) {
-            return { end: lineEnd, sawEndMarker: true };
+        if (isMarkerLine(pos, CODEX_MANAGED_END, "whole")) {
+            return { end: lineEnd, sawEndMarker: true, ...keyBeforeHookTable() };
         }
         if (kind === "comment") {
             if (commentRunStart === null)
@@ -419,11 +507,12 @@ function scanOwnedContentEnd(text, start) {
             continue;
         }
         if (kind === "foreignHeader") {
-            return { end: commentRunStart ?? pos, sawEndMarker: false };
+            return { end: commentRunStart ?? pos, sawEndMarker: false, ...keyBeforeHookTable() };
         }
         if (kind === "hookHeader") {
+            firstHookHeader ??= pos;
             const marked = commentRunStart !== null &&
-                runHoldsHarnessHookComment(text.slice(commentRunStart, pos));
+                rangeHoldsMarkerLine(text, commentRunStart, pos, HARNESS_HOOK_COMMENT_PREFIX, isMarkerLine);
             if (marked) {
                 sawMarkedHookTable = true;
             }
@@ -431,9 +520,17 @@ function scanOwnedContentEnd(text, start) {
                 // 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 };
+                return {
+                    end: commentRunStart ?? pos,
+                    sawEndMarker: false,
+                    endedAtOperatorHookTable: true,
+                    ...keyBeforeHookTable(),
+                };
             }
         }
+        else if (firstHookHeader === null) {
+            firstContentLine ??= pos;
+        }
         commentRunStart = null;
         sawOwnedContent = true;
         pos = lineEnd;
@@ -449,14 +546,46 @@ function scanOwnedContentEnd(text, start) {
     if (commentRunStart !== null && sawOwnedContent) {
         const run = text.slice(commentRunStart, pos);
         const hasComment = /(^|\n)[ \t]*#/.test(run);
+        // Matched as substrings on purpose, outside `createMarkerLineProbe`:
+        // every line of this run is a whole comment or blank line at the top
+        // level (a string line resets the run, and at the end of a document that
+        // parses nothing is still open), so marker text here is never inside a
+        // value, and a comment that mentions a marker is stale harness output.
         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: commentRunStart, sawEndMarker: false, ...keyBeforeHookTable() };
+        }
+    }
+    return { end: pos, sawEndMarker: false, ...keyBeforeHookTable() };
+}
+/**
+ * True when a harness-commented hook table (a `# harness hook:` comment line
+ * followed, later in the zone, by a `[[hooks.` header or a hook event array
+ * header spelled without that prefix, `[[ hooks.SessionStart ]]`) lies after the named
+ * table's header line, before `to`. The comment is found as a marker line
+ * (`createMarkerLineProbe`), so a value that merely contains the marker text
+ * does not count. Used only to pick the fix guidance of a refusal (task
+ * 36d962d2).
+ */
+function harnessHookTableFollows(text, header, to) {
+    if (header === null)
+        return false;
+    let pos = lineEndAfter(text, header.start);
+    let sawComment = false;
+    const isMarkerLine = createMarkerLineProbe(text);
+    while (pos < to) {
+        const lineEnd = Math.min(lineEndAfter(text, pos), to);
+        const trimmed = text.slice(pos, lineEnd).trim();
+        if (isMarkerLine(pos, HARNESS_HOOK_COMMENT_PREFIX, "prefix"))
+            sawComment = true;
+        else if (sawComment && (HOOK_ARRAY_HEADER_RE.test(trimmed) || isHookEventArrayHeader(trimmed))) {
+            return true;
         }
+        pos = lineEnd;
     }
-    return { end: pos, sawEndMarker: false };
+    return false;
 }
 /**
  * Refuses loudly (mirror case of the stray-END bug) when the zone between
@@ -485,20 +614,37 @@ function scanOwnedContentEnd(text, start) {
  * 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). When the named table is a hook event
- * table spelled without the `[[hooks.` prefix, the guidance offers deleting
- * it if harness wrote it, since the scan reads such a table as foreign with
- * or without a comment line above it (task e8f4fc03). The legacy paths call
+ * fix is offered instead (task 6a037359): adding one right after the last
+ * harness hook table, unless a harness-commented hook table follows the named
+ * table (`harnessHookTableFollows`), since an END placed before the named table
+ * would leave that later table running next to the fresh block, and then only
+ * moving the named table below the last harness hook table is offered (task
+ * 36d962d2). With no such table after it the named table already sits below
+ * the last harness hook table, so that move is never offered next to the END
+ * fix: it would change nothing and bring the same refusal back.
+ * When the named table is a hook event table spelled without the `[[hooks.`
+ * prefix, the guidance offers deleting it if harness wrote it, since the scan
+ * reads such a table as foreign with or without a comment line above it
+ * (task e8f4fc03). The legacy paths call
  * this too, so the substring matching above applies there as well: a value
- * holding marker text refuses. `blockOpening` names the line the block
+ * holding marker text refuses. This candidate list and the trailing comment
+ * run of `scanOwnedContentEnd` are the two marker searches that do not go
+ * through `createMarkerLineProbe`, on purpose. This one can only refuse,
+ * never install, so matching marker text in a value costs a refusal, never
+ * operator content. The comment run's lines are whole top-level comment
+ * lines, so marker text there is never inside a value, but that run (blank
+ * and comment lines ending the file after a block with no END marker) is
+ * consumed when the source prefix, the generated header or the
+ * `# harness hook:` text appears anywhere in it, so an operator comment
+ * there that mentions such text mid-line is removed with the block.
+ * `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
+ * (`findManagedRange` needs a top-level `[[hooks.` header 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
@@ -550,11 +696,20 @@ export function assertNoSplitBlock(text, from, to, configPath, hasEndMarker, blo
                 : `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`,
-        ];
+        : harnessHookTableFollows(text, foreignHeaderLine, zoneEnd)
+            ? // An END marker placed before the named table would leave the
+                // harness-commented hook table after it running next to the fresh
+                // block, so the only fix offered is moving the named table past it
+                // (task 36d962d2).
+                [`move ${firstForeignHeader} below the last harness hook table`]
+            : // No harness-commented hook table follows the named table, so it
+                // already sits below the last harness hook table and moving it there
+                // changes nothing (the same refusal would come back): only the END
+                // marker is offered.
+                [
+                    `add a '${CODEX_MANAGED_END}' marker line right after the last harness hook table ` +
+                        `(before ${firstForeignHeader})`,
+                ];
     // 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
@@ -690,10 +845,16 @@ function collectForeignSectionHeaders(text, from, to, kept = []) {
         return count > 1 ? `[${root}.*] (${count} tables)` : header;
     });
 }
-function extractHookIds(content) {
+/** The hook ids named by the `# harness hook:` marker lines
+ * (`createMarkerLineProbe`) in `[from, to)` of `text`, so a value holding
+ * that text is never reported as a removed hook. */
+function extractHookIds(text, from = 0, to = text.length) {
     const ids = new Set();
-    for (const rawLine of content.split(/\r?\n/)) {
-        const m = HOOK_ID_LINE_RE.exec(rawLine.trim());
+    const isMarkerLine = createMarkerLineProbe(text);
+    for (let pos = from; pos < to; pos = lineEndAfter(text, pos)) {
+        if (!isMarkerLine(pos, HARNESS_HOOK_COMMENT_PREFIX, "prefix"))
+            continue;
+        const m = HOOK_ID_LINE_RE.exec(text.slice(pos, lineEndAfter(text, pos)).trim());
         if (m?.[1] !== undefined)
             ids.add(m[1]);
     }
@@ -765,8 +926,8 @@ function startPastBom(text, start) {
  * `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);
+function rangeBeforeStrayEnd(text, start, end, configPath, blockOpening, zoneFrom = end) {
+    const strayIdx = findMarkerLine(text, CODEX_MANAGED_END, "whole", end);
     if (strayIdx === -1) {
         assertNoSplitBlock(text, end, text.length, configPath, false);
         const keptHookTables = collectKeptHookTables(text, end, text.length).tables;
@@ -775,7 +936,7 @@ function rangeBeforeStrayEnd(text, start, end, configPath, blockOpening) {
     }
     const strayLineStart = lineStartAt(text, strayIdx);
     const strayLineEnd = lineEndAfter(text, strayIdx);
-    assertNoSplitBlock(text, end, strayLineStart, configPath, true, blockOpening);
+    assertNoSplitBlock(text, zoneFrom, strayLineStart, configPath, true, blockOpening);
     const keptHookTables = collectKeptHookTables(text, end, strayLineStart).tables;
     const foreignSectionsPreserved = collectForeignSectionHeaders(text, end, strayLineStart, keptHookTables);
     return {
@@ -786,6 +947,25 @@ function rangeBeforeStrayEnd(text, start, end, configPath, blockOpening) {
         keptHookTables,
     };
 }
+/** Refuses operator key/value content before the first hook table on every
+ * locator path. The ownership scan supplies offsets; diagnostics print no values. */
+function assertNoOperatorLineBeforeHookTable(text, start, scan, configPath, blockOpening) {
+    if (scan.operatorLineBeforeHookTable !== undefined) {
+        const { line, header } = scan.operatorLineBeforeHookTable;
+        // Names line numbers only, never the line's own text: it is a key or a
+        // value, which can hold a token, and the refusal is printed to stderr and
+        // `--json`.
+        throw new CodexInstallRefusalError(`Codex config ${configPath} has a key or value line (line ${lineNumberAt(text, line)}) between ` +
+            `${blockOpening} (line ${lineNumberAt(text, start)}) and the first hook table below it (line ` +
+            `${lineNumberAt(text, header)}). A block harness wrote has only comment lines there, so that ` +
+            "line is yours, a key of whatever table is open where the opening line sits (an operator " +
+            "hook table, say), and the install, which replaces everything from the opening line " +
+            "through the harness hook tables, would delete it; refusing to guess. Move that line (with " +
+            "any value lines it continues) above the opening line, so it stays in the table it " +
+            "belongs to, then re-run " +
+            "`harness apply --runtime codex --install`. The file is untouched.", configPath);
+    }
+}
 /**
  * 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,
@@ -799,26 +979,37 @@ function rangeBeforeStrayEnd(text, start, end, configPath, blockOpening) {
  * kept as if it were operator content (the fresh block would repeat it)
  * when it sits before that END, or, after kept tables, anywhere later when
  * no END follows (task e8f4fc03 extends the END case to a foreign table).
- * 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
+ * Content below that END is kept, as on the BEGIN path; the global orphan
+ * check refuses a harness-commented hook table outside the owned range. 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). A scan that ended at a foreign table with no END marker
- * anywhere after it keeps the legacy behaviour (no split-block check), except
- * that hook event tables directly after the block are collected, named and
+ * 01053b27); the split-block zone starts after that opening line, so a block
+ * with no hook table in it (the source prefix directly above an operator
+ * table) is not refused for its own opening line (task 36d962d2). The opening
+ * line is a marker line (`createMarkerLineProbe`), so marker text inside a
+ * value or after a content line opens no block.
+ * A scan that ended at a foreign table with no END marker anywhere after it
+ * keeps the legacy behaviour (no split-block check), except that hook event tables directly after the block are collected, named and
  * checked (`collectKeptHookTables`), and a harness marker in their run
  * refuses through the split-block check. The END marker is looked up as a
- * whole line outside multi-line strings (`findExactLine`), so END text in a
- * foreign table's value does not route a config here. Like the BEGIN path,
+ * marker line too, so END text in a foreign table's value does not route a
+ * config here. Like the BEGIN path,
  * the split-block check matches its markers as substrings, so a value in the
  * zone that holds marker text refuses too (see `assertNoSplitBlock`).
  */
 function legacyManagedRange(text, start, scan, configPath, blockOpening) {
+    assertNoOperatorLineBeforeHookTable(text, start, scan, configPath, blockOpening);
     if (scan.sawEndMarker) {
         return { start, end: scan.end, foreignSectionsPreserved: [], keptHookTables: [] };
     }
-    if (scan.endedAtOperatorHookTable || findExactLine(text, CODEX_MANAGED_END, scan.end) !== -1) {
-        return rangeBeforeStrayEnd(text, start, scan.end, configPath, blockOpening);
+    // The split-block zone starts after the block's own opening line: when the
+    // scan owned nothing (the generated header or a foreign table directly
+    // follows the source prefix), `scan.end` is that opening line itself, which
+    // is a split-block marker and would refuse a block with nothing in it
+    // (task 36d962d2).
+    const zoneFrom = Math.max(scan.end, lineEndAfter(text, start));
+    if (scan.endedAtOperatorHookTable || findMarkerLine(text, CODEX_MANAGED_END, "whole", scan.end) !== -1) {
+        return rangeBeforeStrayEnd(text, start, scan.end, configPath, blockOpening, zoneFrom);
     }
     const run = collectKeptHookTables(text, scan.end, text.length);
     // The scan ended at a hook table spelled without the `[[hooks.` prefix: a
@@ -829,21 +1020,23 @@ function legacyManagedRange(text, start, scan, configPath, blockOpening) {
     // as one without (task e8f4fc03). The run stops at the first non-hook table:
     // past it the legacy reading below stays unchanged.
     if (run.tables.length > 0)
-        assertNoSplitBlock(text, scan.end, run.end, configPath, false);
+        assertNoSplitBlock(text, zoneFrom, run.end, configPath, false);
     const keptHookTables = run.tables;
     const foreignSectionsPreserved = collectForeignSectionHeaders(text, scan.end, text.length, keptHookTables);
     return { start, end: scan.end, foreignSectionsPreserved, keptHookTables };
 }
 function findManagedRange(text, configPath) {
-    const begin = text.indexOf(CODEX_MANAGED_BEGIN);
+    // BEGIN is found as a marker line (`createMarkerLineProbe`): BEGIN text in
+    // an operator value (a string, a trailing comment) is neither the block nor
+    // a second marker, so the install neither deletes operator content after
+    // it nor splices the fresh block into the value (task 36d962d2).
+    const begin = findMarkerLine(text, CODEX_MANAGED_BEGIN, "prefix");
     if (begin !== -1) {
-        const secondBegin = text.indexOf(CODEX_MANAGED_BEGIN, begin + CODEX_MANAGED_BEGIN.length);
+        const secondBegin = findMarkerLine(text, CODEX_MANAGED_BEGIN, "prefix", lineEndAfter(text, begin));
         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));
+            // text, since this refusal is printed to stderr and `--json`.
+            const secondBeginLineNumber = lineNumberAt(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 " +
@@ -854,42 +1047,114 @@ function findManagedRange(text, configPath) {
                 "but that discards any Codex state (hook trust entries, marketplaces, plugins) " +
                 "written to the file since that backup.", configPath);
         }
-        let start = lineStartAt(text, begin);
+        let start = begin;
         const prev = previousLine(text, 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;
+        // Only a marker line is the block's source prefix: the closing line of a
+        // multi-line string that ends with the prefix text is the operator's
+        // value, not part of the block (task 36d962d2). Trimming also drops a BOM
+        // sitting before the source-prefix comment on line 1 (task b34ed105).
+        if (prev && createMarkerLineProbe(text)(prev.start, CODEX_MANAGED_SOURCE_PREFIX, "prefix")) {
+            start = prev.start;
         }
         start = startPastBom(text, start);
         const contentStart = lineEndAfter(text, begin);
         const scan = scanOwnedContentEnd(text, contentStart);
+        assertNoOperatorLineBeforeHookTable(text, begin, scan, configPath, `the '${CODEX_MANAGED_BEGIN}' line`);
         const end = scan.end;
         if (scan.sawEndMarker) {
             return { start, end, foreignSectionsPreserved: [], keptHookTables: [] };
         }
         return rangeBeforeStrayEnd(text, start, end, configPath);
     }
-    const source = text.indexOf(CODEX_MANAGED_SOURCE_PREFIX);
+    const source = findMarkerLine(text, CODEX_MANAGED_SOURCE_PREFIX, "prefix");
     if (source !== -1) {
-        const start = startPastBom(text, lineStartAt(text, source));
+        const start = startPastBom(text, source);
         return legacyManagedRange(text, start, scanOwnedContentEnd(text, start), configPath, `the '${CODEX_MANAGED_SOURCE_PREFIX}' source-prefix line`);
     }
-    const generated = text.indexOf(GENERATED_HEADER);
+    const generated = findMarkerLine(text, GENERATED_HEADER, "prefix");
     if (generated !== -1) {
-        const start = startPastBom(text, lineStartAt(text, generated));
+        const start = startPastBom(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]]")) {
+        // The generated header opens a legacy block only when a hook table header
+        // line (`[[hooks.`, the older `[[hooks.pre_tool_use]]` included) follows
+        // it inside the scanned range, found by the same top-level line rule as
+        // the markers: `[[hooks.` text in a value, a multi-line string line or a
+        // comment under an operator table is operator content, and taking it for
+        // a header made the install replace the operator's keys after the header
+        // line with the fresh block (task 36d962d2).
+        // The search stops at the end of the scanned range: a candidate past it
+        // cannot open the block, and each one the text test lets through costs a
+        // parse of the document before it.
+        const hookHeader = findMarkerLine(text, "[[hooks.", "prefix", start, scan.end);
+        if (hookHeader !== -1) {
             return legacyManagedRange(text, start, scan, configPath, GENERATED_HEADER_OPENING);
         }
+        assertNoLaterGeneratedHeaderBlock(text, generated, scan.end, configPath);
     }
+    assertNoOrphanHarnessHookTable(text, configPath);
     return null;
 }
+/**
+ * Refuses when a generated-header line outside the range being replaced sits
+ * directly above a hook table, either after a stale first header or after a
+ * genuine block: that is a genuine legacy block, and the install
+ * reads only the first generated-header line, so it would add the fresh block
+ * and leave the genuine one running next to it. Which of the two lines to
+ * trust is not something the file says, so the install names both lines and
+ * refuses. A later block whose first hook table is not directly under its
+ * generated-header line (a key or value line in between) is not recognised
+ * here, a documented boundary. Line numbers only, never a line's text.
+ */
+function assertNoLaterGeneratedHeaderBlock(text, firstHeader, from, configPath, firstBlockOwned = false) {
+    const later = findMarkerAboveHookTable(text, GENERATED_HEADER, from, (t) => HOOK_ARRAY_HEADER_RE.test(t));
+    if (later === null)
+        return;
+    const firstDescription = firstBlockOwned
+        ? `the one at line ${lineNumberAt(text, firstHeader)} belongs to the block being replaced`
+        : `the one at line ${lineNumberAt(text, firstHeader)} has no hook table of its own (a table of yours follows it)`;
+    const fix = firstBlockOwned
+        ? `Delete the unwanted later block, including its generated-header line and hook tables`
+        : `Delete the line at line ${lineNumberAt(text, firstHeader)} (it is a comment, and no block hangs on it)`;
+    throw new CodexInstallRefusalError(`Codex config ${configPath} has two '${GENERATED_HEADER}' lines and the install can replace ` +
+        `only one block: ${firstDescription}, the one at line ${lineNumberAt(text, later.marker)} sits ` +
+        `above the hook table at line ${lineNumberAt(text, later.header)}. Installing would add the ` +
+        "fresh block and leave that hook table running next to it, so the install refuses to guess " +
+        `which line is current. ${fix}, then re-run ` +
+        "`harness apply --runtime codex --install`. The file is untouched.", configPath);
+}
+/**
+ * Refuses outside the range being replaced (including the append path) when
+ * a `# harness hook:` comment line sits directly above a hook table: that is a hook table an earlier install
+ * wrote whose opening lines are gone, and the install would add the fresh block
+ * and leave it running next to it (the hook would run twice, or a hook the
+ * manifest retired would keep running). The comment line is found as a marker
+ * line (`createMarkerLineProbe`), above a `[[hooks.` header or a hook event
+ * header spelled another way (`isHookEventArrayHeader`). A table of the
+ * operator's own that carries such a comment is refused too, since the two
+ * cannot be told apart; the guidance offers rewording the comment. Line numbers
+ * and the table's own header only, never a line's text.
+ */
+function assertNoOrphanHarnessHookTable(text, configPath, range = null) {
+    let orphan = findMarkerAboveHookTable(text, HARNESS_HOOK_COMMENT_PREFIX, 0, (t) => HOOK_ARRAY_HEADER_RE.test(t) || isHookEventArrayHeader(t));
+    // An owned pair is replaced together. Search the unowned tail from a known
+    // top-level boundary; a pair before the range must still refuse.
+    if (orphan !== null && range !== null && orphan.header >= range.start && orphan.header < range.end) {
+        orphan = findMarkerAboveHookTable(text, HARNESS_HOOK_COMMENT_PREFIX, range.end, (t) => HOOK_ARRAY_HEADER_RE.test(t) || isHookEventArrayHeader(t));
+    }
+    if (orphan === null)
+        return;
+    const header = describeTableHeader(text.slice(orphan.header, lineEndAfter(text, orphan.header)));
+    throw new CodexInstallRefusalError(`Codex config ${configPath} has a '${HARNESS_HOOK_COMMENT_PREFIX}<id> (budget_ms=<n>)' comment ` +
+        `line (line ${lineNumberAt(text, orphan.marker)}) directly above the hook table ${header} (line ` +
+        `${lineNumberAt(text, orphan.header)}), but no harness block marker (the '${CODEX_MANAGED_BEGIN}' ` +
+        "line, the source-prefix line, or the generated-header line above a hook table) opens a block " +
+        "around it. harness cannot tell that table from one an earlier install wrote, and the install " +
+        "would add its fresh block next to it, so that hook would run twice (or a hook the manifest " +
+        "retired would keep running). If harness wrote the table, delete it together with its comment " +
+        "line. If it is your own table, delete or reword the comment line, since the install reads a " +
+        `comment line that starts with '${HARNESS_HOOK_COMMENT_PREFIX}' as harness-owned. Then re-run ` +
+        "`harness apply --runtime codex --install`. The file is untouched.", configPath);
+}
 function ensureTrailingNewline(s) {
     return s.endsWith("\n") ? s : `${s}\n`;
 }
@@ -1482,6 +1747,13 @@ export function planCodexConfigInstall(opts) {
     }
     const managedBlock = buildManagedBlock(opts.generatedContent, opts.generatedPath);
     const range = withBackupLocation(linkPath, () => findManagedRange(currentContent, configPath));
+    if (range !== null) {
+        assertNoOrphanHarnessHookTable(currentContent, configPath, range);
+        const firstGenerated = findMarkerLine(currentContent, GENERATED_HEADER, "prefix", range.start, range.end);
+        if (firstGenerated !== -1) {
+            assertNoLaterGeneratedHeaderBlock(currentContent, firstGenerated, range.end, configPath, true);
+        }
+    }
     let nextContent;
     let summary;
     let removedHookIds = [];
@@ -1490,7 +1762,7 @@ export function planCodexConfigInstall(opts) {
     let keptTableDescriptions = [];
     let hasEndMarkerAfterKept = false;
     if (range) {
-        const oldHookIds = extractHookIds(currentContent.slice(range.start, range.end));
+        const oldHookIds = extractHookIds(currentContent, range.start, range.end);
         const newHookIds = extractHookIds(managedBlock);
         removedHookIds = [...oldHookIds].filter((id) => !newHookIds.has(id));
         keptHookTables = range.keptHookTables;