@lannguyensi/harness 0.60.0 → 0.61.0

package/CHANGELOG.md

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.61.0] - 2026-10-02
+
+### Upgrade notes
+
+- Re-run `harness apply` once. The understanding gate's SubagentStart hook command is now emitted with the `UNDERSTANDING_GATE_REPORT_DIR=<dir>` prefix like the other report-reading hooks; without it the new report-hash cross-check at subagent start cannot find the reports of a global manifest.
+- Every PreToolUse gate of the pack hooks (`pre-tool-use`, `codex-pre-tool-use`, `branch-protection`, `solution-acceptance`, `solution-acceptance-writeguard`, `post-merge-gate`, `runtime-reality`) now blocks when its stdin does not deliver a complete, closed event within 3000 ms of idle time, instead of waiting for the host's hook timeout. Claude Code and Codex close stdin after writing the event, so normal use is unaffected; `harness pause` still wins.
+- `harness apply --runtime codex --install` refuses a `~/.codex/config.toml` the TOML parser cannot read when the parse error sits before an already current harness block (exit 1, file untouched); it used to report "already up to date". Fix the TOML and re-run.
+
+### Fixed
+
+- **The `harness pack hook` verbs no longer hang when stdin is never closed, and the PreToolUse gates block on a timed-out read** (task `7dfdcaaf`, follow-up to `c8cfc110`). The shared reader in `src/cli/pack/hook-bootstrap.ts` (used by the 15 pack hook verbs that read an event on stdin) and the reader in `src/cli/pack/hook-runtime-reality.ts` read to end of input, so an open pipe that never closes held the hook until the host's own hook timeout. Both now share the idle-bounded reader in `src/cli/bounded-stdin.ts` (3000 ms without a chunk; a slow but live pipe is not cut off). A PreToolUse gate (`pre-tool-use`, `codex-pre-tool-use`, `branch-protection`, `solution-acceptance`, `solution-acceptance-writeguard`, `post-merge-gate`, `runtime-reality`) fails closed on a timed-out read, whether nothing or part of the event arrived: it blocks the tool call with a reason starting `stdin timeout:` that names the 3000 ms bound (Claude Code gates emit their usual block envelope and exit 0, `codex-pre-tool-use` exits 2 with the reason on stderr, `runtime-reality` emits its deny envelope and exits 2), instead of applying its empty or malformed event handling; the operator pause still wins. Without this, a host that stalled for more than 3 s and then wrote a complete gated event and closed would have turned a block into an allow. Every other pack hook (PostToolUse, Stop, SubagentStart, SubagentStop, UserPromptSubmit and the producers) treats a timeout as the bytes it read: one stderr note (`no complete event JSON on stdin within 3000 ms (stdin never closed); continuing as an empty event`, or `stdin did not close within 3000 ms of the last data; using the N bytes read`) and it carries on with the text read so far. Nothing changes for input that arrives and closes within the bound; hook output formats are unchanged.
+
+- **The understanding gate's hook-reachable reads of the reports directory and parse-error logs are bounded (the evidence read, the PostToolUse boundary expiry, the auto-approval precondition and its consume step, the subagent-delegation lookup, the parse-error lookup), so planted files can no longer hang or kill the hooks on those reads (the consume step's write is not covered, see the last sentence of this entry); the operator commands `harness approve understanding` and `harness gc` stay unbounded on purpose** (task `4b39022f`, closes residual (4) named under 0.60.0 for the evidence read). The read behind `checkPersistedReport` (the block diagnostic of both PreToolUse hooks, on the no-marker path and after a refused marker) and behind `expirePersistedReport` (the PostToolUse boundary expiry) listed the reports directory with a separate `stat` and then `readFileSync`: a `*.json` symlink flipped to a FIFO between the two hung the hook (measured 4/20 runs on the Claude hook, 1/20 on the Codex hook), and one file of a few hundred megabytes gave a V8 fatal error and no decision on both; each ends as a non-blocking error for the runtime, i.e. the call proceeds. The same unbounded listing sat in the auto-approval precondition and the subagent-delegation lookup (reached on the same paths whenever `auto_approve` is configured, which the `harness init` default is for `bypassPermissions`), and the parse-error lookup read `parse-errors/*.log` with a `stat` and `readFileSync` too. All of them now open each entry once through `readReportFileBounded` (read-only, `O_NONBLOCK`, `fstat` on the descriptor, regular files up to 1 MiB, read through the descriptor) and skip anything else (a FIFO, a directory, a device, a symlink to one, a file over the cap, an unreadable file, one that grows while read) as if it were not in the directory. The auto-approval precondition also declines, so the call stays blocked, when its listing had to skip any entry: an oversized or unreadable newest report never lets it fall back to an older pending one. Decisions are unchanged: the same deny with the same reason on the no-marker path and after a refused marker, with a FIFO or a 2 MiB file next to the reports; a regular report within the cap is read, sorted and reported exactly as before. Consequences: a report over 1 MiB is no longer picked up as the session's evidence, so a block diagnostic that would have named it (`unsigned persisted-report approval rejected: ...`) now reads `no reports found`; the boundary expiry no longer rewrites such a file and acts on the newest report that was within the cap (when the newest approved report is oversized, the next in-cap one is expired); a parse-error log over the cap is not surfaced. `harness approve understanding` and `harness gc` keep the unbounded listing on purpose, so an oversized report is still found and refused or aged out. The auto-approval consume step no longer re-reads the report by path: it rewrites the text the precondition read through the bounded reader, and the write is a temp file renamed over the entry, which never opens what a symlink points at. Before, a report symlink retargeted to a FIFO or a few-hundred-megabyte file between the precondition and the consume hung or killed the hook in about a third of the attempts on both runtimes. `harness approve understanding` (including `--force`) still reads the report by path. Still open: the write path of the consume step, whose atomic write opens its temp file in the agent-writable reports directory without `O_EXCL`/`O_NOFOLLOW`, so a FIFO planted at the temp name can still hang the hook (pre-existing, tracked separately); the total volume of planted files (a separate residual); an agent-planted oversized report crashes `harness approve understanding` itself until the file is deleted (`docs/okf/understanding-gate-lockout-recovery.md`).
+
+- **`harness apply --runtime codex --install` no longer refuses a legacy block with no hook table in it, its no-END refusal no longer offers an END position that keeps a harness hook running, and marker text inside a value is no longer read as a managed-block marker** (task `36d962d2`, follow-up to `e8f4fc03`). (1) A legacy config (no BEGIN marker) whose source-prefix line, with or without the generated header, sits directly above an operator table was refused when that table was a hook event table spelled without the `[[hooks.` prefix (`[[ hooks.Stop ]]`) and no END followed, or when a surviving END followed any foreign table: the split-block zone started at the block's own opening line, which is itself a split-block marker. The zone now starts after that line, so these configs install (the operator table is kept and named, an orphan END is excised, a second install gives the same bytes); a harness marker past the opening line still refuses. (2) When no END marker exists and a harness-commented hook table follows the named table, in either spelling (`[[hooks.Stop]]` or `[[ hooks.Stop ]]`), the refusal said to add an END right after the last harness hook table (before the named table), which contradicts itself and, followed by its parenthetical, left the later harness table running next to the fresh block. That option is now offered only when no harness-commented hook table follows; otherwise the refusal offers moving the named table below the last harness hook table. (3) Every managed-block marker (the BEGIN and END lines, the source-prefix line, the generated header and the `# harness hook:` comment) is now found by one rule: a whole trimmed line (equal to BEGIN or END, starting with the others) at the top level of the document. Before, BEGIN was found anywhere in the text, so BEGIN text in a string value or a trailing comment of an operator hook table made the install silently delete operator content after it (a key, or the whole next operator hook table), and BEGIN text in a multi-line string had the fresh block spliced into that string, growing on every install; the source-prefix and generated-header text opened a legacy block at the closing line of a multi-line string or at a trailing comment; an END comment line inside a multi-line array ended the block there or was excised as a stray END; and a `# harness hook:` line inside a string was reported as a removed hook. Marker text in a value (a single-line or multi-line string, a trailing comment, an inline table, an element or a comment line of a multi-line array) is now operator content: the install writes a fresh block and leaves that value as it was, a second install gives the same bytes, an END line that no block owns stays, and BEGIN text in a value is no longer refused as a second BEGIN marker. The same top-level line rule now decides whether a generated-header line opens a legacy block, which needs a hook table header line (`[[hooks.`, the older `[[hooks.pre_tool_use]]` included) after it: `[[hooks.` text in a string value, a multi-line string line or a comment line below a generated-header comment in an operator hook table opened that block, and the install replaced the operator's keys after the header line with the fresh block; the block is now appended and those keys stay. Two marker searches still match marker text as substrings: the split-block refusal's candidate list, which can only refuse, and the trailing comment run at the end of the scan, whose lines are whole top-level comment lines. Known boundary, unchanged: that run (blank and comment lines ending the file after a block with no END marker) is consumed with the block when the source-prefix, generated-header or `# harness hook:` text appears anywhere in it, so an operator comment there that mentions such text mid-line is removed. Behaviour change for a config the TOML parser used by harness cannot read: when its parse error sits before an already current block, the install reported "already up to date" and now refuses (exit 1, file untouched, no backup), since a marker line after the parse error is not at the top level of a readable prefix; a parse error after a current block still reports up to date. Tests pin all three, the generated-header shapes and the unreadable-config refusal, plus the substring refusal and the escaped `hooks` root key on the legacy no-END path. The stale `# Harness Codex hook wiring. Generated source:` and `# Generated by harness apply --runtime codex.` lines of an empty legacy block still stay where they were (as before for a block followed by a foreign table); they are not removed.
+
+- **`harness record dogfood` refuses a session id with leading or trailing whitespace** (task `eed7c036`). The verb checked the trimmed session id for the `dogfood:<session>` content but wrote the fact into the untrimmed session, so `--session ' s1'` produced content `dogfood:s1` in session `' s1'`. It now exits `64` naming `--session` and writes nothing, consistent with the other record validation, rather than trimming, so content and target can never name different ids. The other record verbs and the ledger write are unchanged. Docs only alongside: the `ResolvePackOptions.reportsDir` comment says the `UNDERSTANDING_GATE_REPORT_DIR` prefix goes on each report-reading hook command (not every contributed hook), and the in-flight subagent dogfood README marks `payloads/rendered-settings.json` as a historical capture that predates the prefixed `subagent-start` command.
+
+- **`harness doctor` no longer aborts on a malformed `.last-apply` when the understanding pack is declared** (task `3128df7a`). The settings-drift check read the record unguarded, so unparseable JSON or a record without a `files` map threw out of doctor. It now skips its comparison and adds a warning naming the file (`<generated dir>/.last-apply is unreadable (...); settings drift not checked`), which counts toward `warningCount`, the same shape as the runtime-selection fallback. A well-formed record gives the same output as before.
+
+- **`harness record review` / `review-subagent` / `dogfood` reject values that would plant a second ledger tag** (task `237cc609`). The verbs write their fact as space-separated tag text and the gates match tags by substring, so `--branch "x review-subagent:master"`, `--base "x review-subagent:master"` or `--verdict "ok review-subagent:master"` also satisfied another branch's `review-subagent-before-pr-create-bash` gate. Every ref-like or id-like value embedded in a tag (`--branch`, including a branch resolved from git; `--base`; `--task`; `--pr`; the session id `record dogfood` writes as `dogfood:<session>`) is now refused when the trimmed value contains a `:` or any ASCII whitespace, which git ref names forbid anyway, so no real branch is refused and every tag namespace, custom ones included, is closed for these values without a list (free text is checked only against the six gate-opening namespaces listed here, so a custom namespace there is not refused); Unicode whitespace without a `:` stays accepted. Free text (`--verdict` and the summaries of all three verbs) stays free and is rejected (not rewritten, so the audit text is never altered) only when it carries `review-subagent:`, `review:`, `dogfood:`, `preflight:`, `risk-approved:` or `risk-override:` immediately followed by a non-whitespace character; prose like `code-review: approved` is kept. Each refusal exits `64` naming the flag, and nothing is written. Task, PR and branch values still share tag namespaces (`record review-subagent --task master` writes `review-subagent:master`, `record review --pr master` writes `review:master`), so a value that is itself a valid branch name is not stopped. Hardening of the advisory ledger only: the substring matcher and `ledger_add` are unchanged, and docs/CLI.md "Tag-injection validation" states the rules.
+
+- **`harness pack hook subagent-start` no longer mints an in-flight subagent record under an approval whose report was edited** (task `dac02d5c`, closes residual (2) named under 0.60.0). After a parent marker matched, the hook now applies the same gate-read report-hash cross-check as both PreToolUse hooks (`verifyMatchedMarkerReport`, task marker first, session marker as fallback) before `writeInflightRecord`; when no report file carries the signed content any more it writes no record and says so on stderr (`approval refused, no report in the reports directory matches the content ...; no in-flight record for agent <id>`), so the subagent has nothing to present once the parent marker stops matching (claim switch, `max_age`) and blocks. An intact approval and a null-hash marker mint exactly as before; a task marker that fails the check while the session marker behind it verifies mints a record that names the session marker. The record format and its 24 h staleness window are unchanged. Codex has no SubagentStart wiring, so this is the Claude hook only. **Upgrade:** re-run `harness apply` once. The SubagentStart hook command is now emitted with the same `UNDERSTANDING_GATE_REPORT_DIR=<manifest-anchored dir>` prefix as the other report-reading hooks, so it reads the directory `harness approve understanding` wrote to; a settings file generated before this change keeps the bare command, which falls back to `<cwd>/.understanding-gate/reports`, a directory that usually does not exist, so the cross-check there neither sees the reports nor refuses an edited one.
+
+- **A destructive command no longer escapes the risk floor or the deletion gate because one word carries a NUL-decoding ANSI-C escape** (task `5cc64860`, follow-up to `241d9e9e`). bash truncates a `$'...'` run at a NUL (measured on GNU bash 3.2.57, `printf '[%s]' <word> | od -c`; the first report measured 5.1.16), so `git push $'--force\0' origin`, `git reset $'--hard\0'`, `find / $'-delete\c@'`, `$'dd\0' of=/dev/sda` and `$'rm\0' -rf /home/x` run as their plain twins. The decoder keeps a literal U+0000 in the decoded word, so every exact comparison (a whole flag, a head name, a subcommand) in `src/runtime/destructive-shell-floor.ts` and `src/runtime/deletion-target-resolve.ts` missed them: the floor reported nothing (the plain twins are `high`, `high`, `critical`, `critical`) and the deletion gate made no decision for the `rm` form. Both scanners now examine the command a second time with every `$'...'` run that carries such an escape replaced by a single-quoted literal of the value bash passes, and keep both results: the floor keeps the hits of both scans, the resolver combines both verdicts (unresolvable if either reading is), so the second reading can only add a verdict, never remove one. `shell-word.ts` gains `decodeShellWordTruncatingNul` (each run cut at its first escape that decodes to NUL or any `\c` escape, the text around the run kept: `x$'a\0b'y` is `xay`) and `truncateNulRuns` (the rewrite of a whole command text, or `null` when no run carries such an escape, so a command without one is scanned once as before); the rewrite happens before the boundary split, so a `;`, `|` or `&` inside the cut-off part of a run (`git push $'--force\0;' origin`) disappears with it instead of tearing the word. `decodeShellWord`, its decoded values and the read-only classifier are unchanged. This is the comparison-only truncation variant, not a blanket fail-closed on any NUL word: a NUL escape in a harmless place (`echo $'a\0b'`, `git push $'origin\0' main`) stays as unclassified as before. It also gates a target that a NUL cuts back to a safe root itself (`rm -rf $'/tmp/\0x'` reaches bash as `/tmp/`, the safe root itself, which was not gated before). Over-cutting is the accepted direction: `\c` escapes other than `\c@` and `\u`/`\U` escapes that bash 3.2.57 leaves literal are cut too, which only adds a candidate reading, and a `$'` that bash reads inside single quotes is rewritten like a real run. A run without a closing quote is left as written. Measured base versus head over 276 commands (207 with a NUL escape: the read-only NUL corpus of `241d9e9e`, every NUL string in the runtime tests, the five commands above; 69 without one, among them the plain twins): no floor hit, no classified severity and no deletion verdict is lower at head, the 69 commands without a NUL escape give identical results, and 105 NUL commands are stricter; 27 of 27 sample words decode through the rewrite to exactly the bytes `/bin/bash` 3.2.57 passes. Pinned in `tests/runtime/destructive-shell-floor.test.ts`, `tests/runtime/deletion-target-resolve.test.ts`, `tests/runtime/intercept-deletion-gate.test.ts` and `tests/runtime/shell-word.test.ts`.
+
+- **`harness policy intercept`'s stdin-timeout note now says what it does when nothing was read** (task `c5831891`, follow-up to `c8cfc110`). The shared note for an idle, empty stdin ended with `falling back to the default session resolution`, which fits the session-start producers but not `policy intercept`, which continues as an empty event. `stdinTimeoutNote` takes an optional caller tail; intercept passes `continuing as an empty event`, and the session-start producers' text is unchanged byte for byte. The idle-stdin tests in `tests/cli/bounded-stdin.test.ts` also restore the working directory in their `afterEach` cleanup before the temp dir is removed, so a regressed bound fails only the bound tests instead of breaking every later test with a deleted cwd.
+
+- **`harness session-start branch-check`, `stale-base-check`, `toolchain-parity` and `harness policy intercept` no longer hang when stdin is never closed** (task `c8cfc110`). They awaited stdin's `end` with no bound, so a backgrounded compound command (or any caller holding an open pipe) left the hook idle forever. All five stdin-reading hook-style entries (these four and `preflight`) now share one idle-bounded reader (`src/cli/bounded-stdin.ts`): the 3 s idle timer restarts on every chunk, so a slow but live payload is still read in full, and a timeout writes a stderr note and carries on with what was read (an empty read is an empty event, partial text is parsed). `policy intercept` keeps its fail posture: malformed event JSON still exits 0 with no decision and a stderr note. Hook output formats are unchanged. The pack hooks (`hook-bootstrap.ts`, `runtime-reality`) keep their own readers.
+
 ## [0.60.0] - 2026-10-01
 
 ### Upgrade notes

package/README.md

@@ -98,7 +98,7 @@ steps).
 
 ## Status
 
-The current release is `v0.60.0`. All seven planned phases have
+The current release is `v0.61.0`. All seven planned phases have
 shipped; phase acceptance criteria are in
 [`docs/ROADMAP.md`](docs/ROADMAP.md), and what shipped in each version
 is in [`CHANGELOG.md`](CHANGELOG.md).

package/dist/cli/apply/install-codex-config.d.ts

@@ -164,19 +164,33 @@ export declare function createTopLevelProbe(text: string): (lineStart: number) =
  * 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
+ * offered instead (task 6a037359). Adding one is offered only when no
+ * harness-commented hook table follows the named table
+ * (`harnessHookTableFollows`): an END placed before the named table would
+ * leave that later table running next to the fresh block (task 36d962d2).
+ * 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

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,65 @@ 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`, and
+ * so does the `[[hooks.` header line that lets a generated header open a
+ * legacy block (`findManagedRange`).
+ * 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`, or -1. Candidates are visited in order, one line
+ * each, so the probe's non-decreasing-offset contract holds. */
+function findMarkerLine(text, marker, shape, from = 0) {
+    const isMarkerLine = createMarkerLineProbe(text);
     let pos = from;
-    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 && rawLine.trim() === target)
-            return pos;
-        pos = lineEnd;
+    for (;;) {
+        const idx = text.indexOf(marker, pos);
+        if (idx === -1)
+            return -1;
+        const lineStart = lineStartAt(text, idx);
+        if (isMarkerLine(lineStart, marker, shape))
+            return lineStart;
+        pos = lineEndAfter(text, lineStart);
+    }
+}
+/** 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 -1;
+    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
@@ -399,6 +424,7 @@ function scanOwnedContentEnd(text, start) {
     let sawOwnedContent = false;
     let sawMarkedHookTable = false;
     const classify = createLineClassifier(text);
+    const isMarkerLine = createMarkerLineProbe(text);
     while (pos < text.length) {
         const lineEnd = lineEndAfter(text, pos);
         const rawLine = text.slice(pos, lineEnd);
@@ -409,7 +435,7 @@ function scanOwnedContentEnd(text, start) {
             pos = lineEnd;
             continue;
         }
-        if (rawLine.trim() === CODEX_MANAGED_END) {
+        if (isMarkerLine(pos, CODEX_MANAGED_END, "whole")) {
             return { end: lineEnd, sawEndMarker: true };
         }
         if (kind === "comment") {
@@ -423,7 +449,7 @@ function scanOwnedContentEnd(text, start) {
         }
         if (kind === "hookHeader") {
             const marked = commentRunStart !== null &&
-                runHoldsHarnessHookComment(text.slice(commentRunStart, pos));
+                rangeHoldsMarkerLine(text, commentRunStart, pos, HARNESS_HOOK_COMMENT_PREFIX, isMarkerLine);
             if (marked) {
                 sawMarkedHookTable = true;
             }
@@ -449,6 +475,11 @@ 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);
@@ -458,6 +489,33 @@ function scanOwnedContentEnd(text, start) {
     }
     return { end: pos, sawEndMarker: false };
 }
+/**
+ * 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 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
@@ -486,19 +544,33 @@ 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). 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
+ * offered instead (task 6a037359). Adding one is offered only when no
+ * harness-commented hook table follows the named table
+ * (`harnessHookTableFollows`): an END placed before the named table would
+ * leave that later table running next to the fresh block (task 36d962d2).
+ * 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 +622,17 @@ 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`]
+            : [
+                `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
@@ -690,10 +768,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 +849,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 +859,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 {
@@ -803,13 +887,17 @@ function rangeBeforeStrayEnd(text, start, end, configPath, blockOpening) {
  * 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). 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`).
  */
@@ -817,8 +905,14 @@ function legacyManagedRange(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 +923,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,14 +950,14 @@ 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);
@@ -872,19 +968,24 @@ function findManagedRange(text, configPath) {
         }
         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).
+        const hookHeader = findMarkerLine(text, "[[hooks.", "prefix", start);
+        if (hookHeader !== -1 && hookHeader < scan.end) {
             return legacyManagedRange(text, start, scan, configPath, GENERATED_HEADER_OPENING);
         }
     }
@@ -1490,7 +1591,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;