@lannguyensi/harness 0.58.2 → 0.59.1

package/CHANGELOG.md

@@ -7,6 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.59.1] - 2026-09-29
+
+### Fixed
+
+- **The solution-acceptance deny note no longer names an unobserved cause for the never-evaluated reading, and its state table now pins what the docs claimed** (task `8fe0f633`, follow-up to the late review findings of task `799de976`; agent-facing text and tests only, no gate decision changes). The never-evaluated line said `solution_evaluate` "has not (yet) been called for this id, or a prior call never got far enough to record one", but what the gate established is only that its one marker read found nothing (the shared reader folds every `lstat` failure into `missing`) and that the lock read not-live at a later moment; a marker recorded then deleted, an attempt finishing between the two reads, and a non-`ENOENT` `lstat` failure each falsify it. It now reads `No verdict marker was found for "<id>"; no attempt reads as currently live: run solution_evaluate for this id.` (with the unknown-liveness clause, `No verdict marker was found for "<id>" and liveness could not be determined: ...`). Only that note line changed: the `evaluateGate` reason above it (`no solution-acceptance verdict recorded for "<id>" (run ... solution_evaluate first)`) is a different module surface and is unchanged, so its `recorded` and `first` wording is still open to the same three falsifiers. The state table gained the three missing liveness rows (symlink, not-a-regular-file and unreadable marker, each with an unknown-liveness fixture): it now holds fourteen rows covering the twelve reachable (note state, liveness) combinations (two combinations have a second fixture), so its "one exact line per reachable (note state, liveness) combination" claim is true; a mutant hardcoding the not-live clause into the symlink line no longer survives. Each row declares the coordinate it means to reach, and `renderNullVerdictNote` (exported, with the renderer record and the reachable set `NULL_VERDICT_NOTE_COORDINATES`) is total over reachable coordinates only: `live` renders only with the live-attempt state, the unusable-id state carries no liveness at all, and any other pair throws, so a row can no longer claim a state or a liveness its fixture never reaches, and the set of lines that must not appear is derived from the renderer instead of listed by hand. The classifier's parameter excludes the `ok` outcome by type and the hook classifies a denial only when its read yielded no verdict, which removes an arm that would have called a valid record invalid if the gate ever gained a second null return. The single marker observation now has two guards: a `dependency-cruiser` rule (`npm run check:boundaries`) forbidding the hook from importing the shared marker reader directly, and a call-count test asserting one `readVerdictDetailed` call per invocation. `readVerdict`'s doc comment no longer claims callers it does not have. The OKF log entry for task `799de976` moved to its chronological place and its commit reference now names the merge commit.
+
+- **The Codex install splice keeps a trailing operator comment at EOF when there is no END marker, and keeps a leading UTF-8 BOM exactly once** (task `b34ed105`). Two pre-existing comment-only or BOM-only effects of the managed-range detection, documented as limitations in the task `6a037359` entry, with no semantic loss (the TOML-semantic safety net saw no difference): (1) in a config with a BEGIN marker, a legacy source prefix or a legacy generated header but no END marker, the ownership scan ran to EOF and folded a trailing operator comment after the last harness hook table into the replaced block; it now backs off to the start of that trailing comment run, so the comment is kept once, after the fresh END marker (a run of only blank lines is still consumed, and so is a trailing run that holds a harness-authored line such as the generated header, a `# harness hook:` line or the source prefix, since that is stale harness output; the back-off also needs at least one owned content line before the run); (2) a BOM in front of the BEGIN marker, a legacy source-prefix comment or a legacy generated header on line 1 was dropped by the splice, and a BOM before a source-prefix line hid it from the previous-line check, so the prefix comment was duplicated; the managed range now starts just past the BOM, and the BOM is kept exactly once with no duplicate prefix line. The BOM change leaves the ranges of files without a BOM unchanged. Pinned in `tests/cli/apply/apply-codex-runtime.test.ts`, with one fixture per harness-authored clause (generated header, `# harness hook:` line, source prefix): the no-END, legacy source-prefix and legacy generated-header trailing-comment fixtures and the BOM + BEGIN, BOM + source-prefix and BOM + generated-header fixtures fail against the previous implementation and pass now. Mutation probes (`agent-primitives probe`) reverting the EOF back-off and reverting the BOM handling are killed by those fixtures.
+
+- **The solution-acceptance write-guard no longer refuses a command that only names a pack source file** (task `e8c9edaf`). `bashReferencesVerdictDir`'s glob/brace leaf-word fallback fires when the command text carries any of `*?[{` and also contains a distinctive word of the verdict directory's leaf (`solution`, `verdicts`). `solution` is the first word of the pack's own name, so any non-read-only Bash whose text named `docs/policy-packs/solution-acceptance.md`, `src/cli/pack/hook-solution-acceptance-writeguard.ts`, `src/policy-packs/builtin/solution-acceptance-runtime.ts` or one of the pack's test files was refused as a verdict-dir write as soon as a `[x]`, a `**bold**`, a `.*` in a sed expression or a `{...}` appeared anywhere in the text (a heredoc body, a `git commit -m`); for Codex `apply_patch` the `***` of every patch header made any patch that edits a pack file refuse. The fallback now scans the command with the pack name scrubbed out of each plain, whitespace-delimited word (a word with no `*?[]{}` character cannot expand at runtime, so its literal text reaches the verdict directory only through the leaf, tail or env token that the unchanged direct checks already see), but only when the command carries no runtime-construction syntax: a `$` anywhere (parameter expansion, command substitution, `$'...'`), a backtick, `<(` or `>(`, `printf -v`, a `.` in command position, or one of the words `eval`, `source`, `read`, `declare`, `typeset`, `local`, `export`, `set`, `let`, `mapfile`, `readarray`, `exec`, `xargs`, `sh`, `bash`, `zsh`, `dash`, `ksh`. A command that can build text at runtime could derive the directory leaf from the very pack-name word the scrub would erase, so it is scanned unscrubbed, exactly as before this change. Everything else is unchanged: the literal directory, the `$SOLUTION_VERDICT_DIR` token, the `agent-grounding/solution-verdicts` tail and the literal leaf are still matched on the untouched command; a word that carries a metacharacter is never scrubbed, so `solution-acceptance/../solution-ver*` and `[solution-acceptance]*` keep their leaf word; a custom directory whose own leaf contains the pack name is scanned unscrubbed; the brace/glob leaf-word fallback, `cd` target handling, the cwd-inside check and the read-only classifier are not touched. Both call sites (the Bash arm and the `apply_patch` arm) share the matcher, so both narrow. Still refused (fails closed, cannot be decided without evaluating the shell): a command with a glob/brace character that also contains the word `solution` or `verdicts` outside a plain pack-name word (prose in a heredoc body, a glob over the pack sources such as `solution-acceptance*`), and a command that carries runtime-construction syntax next to a glob/brace character and the word `solution` or `verdicts` (so a heredoc body with a `$` in it, for example, is refused again when it also carries a glob character and the pack name). A name that is built at runtime and never shows the word `solution` or `verdicts` in the command text is not caught, before or after this change; that stays an open residual, as the guard header already says. The named residuals stay open and unchanged: a backslash-escaped leaf, a case-variant leaf on a case-insensitive filesystem, a trailing backslash on a `cd` target, a path in which globs or braces obscure every segment so that neither `solution` nor `verdicts` survives in the text (for example `sol*verd*`), and a path constructed at runtime inside an interpreter. Pinned by the refuse-side fixtures (committed first, passing against the previous matcher) and the allow-side fixtures in `tests/cli/pack-hook-solution-acceptance-writeguard.test.ts` and `tests/policy-packs/solution-acceptance-runtime.test.ts`.
+
+## [0.59.0] - 2026-09-25
+
+### Upgrade notes
+
+- Outside `approval_lifecycle: { mode: session }`, a live session approval written by an earlier release carries no task binding and is refused once: run `harness approve understanding` again after upgrading. From now on a session approval stops counting when the agent claims a different task (pre-approve a batch with `--task a b c`). Under `mode: session` nothing changes.
+- Downgrading fails closed: an earlier release treats session and branch-protection markers written by 0.59.0 as forged; re-approve with the older binary after a downgrade.
+- If you keep your own `expire_on_tool_match` list, add `mcp__agent-tasks__task_merge` to it so a review-then-`task_merge` path expires the approval.
+- A plain `harness apply` now reuses the runtime the last apply used (for a record written by an earlier release it is inferred from the generated files and named in the output). If you alternate runtimes, pass `--runtime claude-code` (or `--target`) explicitly.
+
+### Changed
+
+- **The understanding gate's approval now expires on the same boundary as the active-claim marker, and the session approval marker is bound to the task it was granted for** (task `5018c0c4`, operator decisions: align, then bind the session marker to the task). Expiry: the PostToolUse expiry hooks (`harness pack hook post-tool-use` and the Codex `codex-post-tool-use` sibling) share `matchPostToolUseBoundary`, which asks the one decider, `claimEffectForAgentTasksTool`, with the event's `tool_response` for every listed agent-tasks claim lifecycle verb (`ACTIVE_CLAIM_TOOL_NAMES`); a "claim kept" answer is not a boundary. `task_finish` to `review` keeps the session and task approval markers; `task_finish` to `done`, `task_abandon`, `task_merge` and `tasks_transition` to `done` expire them; an absent or unreadable `task_finish` result expires (the decider's fail-safe `release`). The former local `tasks_transition` status filter is replaced by the same decider (same outcome), and its skip diagnostic now reads `<tool> keeps the work claim per the active-claim decider`. `pull_requests_merge`, a listed `task_submit_pr` and a listed `task_start` still expire on list membership. Binding: every session marker `writeApprovalMarker` writes (the `harness approve understanding` CLI and the hook's auto-approval path) now records, as a signed `claimTaskId` field, the task id of the active claim at that moment (`null` when none is held); outside `approval_lifecycle: { mode: session }`, the PreToolUse gates (Claude and Codex), the subagent-start in-flight hand-off and `harness delegate`'s parent check accept the session marker only while the current active claim has that same id (`checkSessionApprovalMarker`). Under `mode: session` the binding is not applied (operator decision): the session marker, bound or unbound, counts for every task until `max_age`, as that mode documents; the field is still written, so leaving `mode: session` takes effect on the next check. A different task, or no claim where one was recorded (or the reverse), blocks exactly like a missing marker, with a diagnostic that says the approval belongs to another task (on stderr for the Claude hook, whose stdout deny reason stays the generic one; in the block reason for the Codex hook), and never reads as an expired approval. So, outside `mode: session`, an approval no longer carries over to the next task when the previous one was completed outside the session (merged in the UI or on GitHub, moved to `done` by a webhook), where no PostToolUse hook can expire anything. Resuming the same task id keeps the approval; the task-scoped markers (`--task`, the active-claim auto-resolve) are unchanged. `task_merge` is added to the explicit `expire_on_tool_match` list of every `harness init` scaffold (full, team, and the interactive composer) and of `docs/examples/full-manifest.yaml`: the runtime boundary list comes from that config alone, so without it the review-then-`task_merge` path would never expire the approval in-session. `task_merge` is also in `DEFAULT_BOUNDARY_TOOL_NAMES`, which only shapes the emitted PostToolUse matcher when no explicit list is configured. Pinned by `tests/cli/pack-hook-post-tool-use.test.ts`, `tests/cli/pack-hook-codex-post-tool-use.test.ts`, `tests/cli/pack-hook-session-approval-task-binding.test.ts` and `tests/cli/init-scaffold-approval-expiry.test.ts`, driven by the real content-block PostToolUse capture `tests/fixtures/track-active-claim/real-posttooluse-task-finish-2.1.280.json`. Upgrade notes: outside `mode: session`, a session marker written by an earlier release carries no binding and is not accepted, so a live session needs one fresh `harness approve understanding` after the upgrade, and a session approval stops counting when the agent claims a different task (pre-approve a batch with `--task a b c` to avoid a prompt per task); under `approval_lifecycle: { mode: session }` nothing changes, including the documented residual that an out-of-band completion followed by a `task_start` on another task keeps the approval until `max_age`; operators with their own `expire_on_tool_match` list add `mcp__agent-tasks__task_merge` to it if they merge through `task_merge`. A downgrade to an earlier release fails closed: its binary does not know the signed `claimTaskId` field, so it rejects every session and branch-protection marker written by this release as forged (not merely unapproved); re-approve with the older binary after a downgrade.
+
+### Fixed
+
+- **`harness apply` without `--runtime` now reuses the runtime the last apply used instead of silently switching to `claude-code`** (task `b9e6d63c`). After `harness apply --runtime codex`, a plain `harness apply` used to regenerate the runtime-specific files (policy-pack `instructions.md`, `settings.json` instead of `codex/config.toml`) for `claude-code`, report `applied N file(s)`, and neither `--dry-run` nor the apply said the runtime had changed. `.last-apply` now records the runtime (`runtime` field), and apply without `--runtime` (including `--install`) reuses it and prints `runtime: codex (from last apply; pass --runtime to change)`. A `.last-apply` written by an older release has no such field: apply then reads the runtime off its files map (only `codex/config.toml` means codex, only `opencode/opencode.json` opencode, only `settings.json` claude-code) and prints `runtime: codex (inferred from the last apply's generated files; pass --runtime to change)`; when the map holds both `settings.json` and `codex/config.toml` (a machine that applied claude-code and later codex), the recorded policy-pack `instructions.md` entries decide when every one names the same runtime in its `## Runtime` section; when the map is still ambiguous it uses `claude-code` and prints `runtime: claude-code (default; the last apply did not record a runtime and generated files for claude-code and codex; pass --runtime codex to keep codex)`, or `runtime: claude-code (default; the last apply did not record a runtime, pass --runtime to choose)` when the map names no runtime. An explicit `--runtime` that differs from the previous one is honoured, and both `--dry-run` and the apply print `runtime: <old> -> <new> (switching from the last apply's runtime)`. `--target` without `--runtime` implies `claude-code` (it wires Claude Code's settings.json) and prints `runtime: claude-code (implied by --target)`, or `runtime: codex -> claude-code (--target implies claude-code)` after a codex apply; an explicit `--runtime codex` or `--runtime opencode` with `--target` is still refused. `harness smoke` and the `harness init --interactive` claude-code wire step pass `claude-code` explicitly. `harness smoke` keeps the runtime `.last-apply` records (new `apply()` option `preserveRecordedRuntime`): after a codex apply it prints `runtime: claude-code for smoke; the recorded runtime codex is kept, the next harness apply restores it`, and the next plain apply reuses codex and rewrites the codex files. `harness pack remove --force` keeps the recorded runtime when it prunes the pack's entries from `.last-apply` (it used to rebuild the record without it, so the next plain apply fell back to reading the files map). For an older record the `instructions.md` entries count only for the packs its own manifest snapshot lists (enabled ones), so an entry left over from a pack a later apply no longer had does not decide the runtime; without a readable snapshot every entry counts. An `--install` refusal for an inferred runtime says `inferred from the last apply's generated files` instead of `reused from the last apply`. With no `.last-apply` the default stays `claude-code`; an apply that changes nothing else stamps the runtime into a record that lacks it. A non-string `runtime` in `.last-apply` is ignored like an unknown value instead of failing every reader of the record. The `--json` result carries `runtime`, `runtimeSource`, `previousRuntime` and, for an ambiguous older record, `runtimeCandidates`. `harness diff --since-apply` is unchanged: it compares `.last-apply` against disk and never regenerates, so it has no runtime to select. Pinned by `tests/cli/apply/apply-runtime-reuse.test.ts` (with a fixture of the merged older record's shape), `tests/cli/smoke/smoke.test.ts` and `tests/cli/pack.test.ts`.
+
+- **`harness apply --runtime codex --install` keeps a symlinked (dotfiles-managed) `~/.codex/config.toml` a symlink** (task `1637fbc8`). The install wrote through `atomicWriteFile`, whose temp-file rename replaced the link with a regular file and left the link's target (typically a dotfiles repo) unchanged, so the two silently diverged. `planCodexConfigInstall` now resolves a symlinked config path with `realpath` and plans against the resolved regular file: the atomic write's temp file is created in the target's own directory (so the rename stays on one filesystem), the target's file mode is preserved, and every link in the chain is left untouched. The backup holds the target's previous content with the target's mode but sits beside the link (for example `~/.codex/config.toml.harness-backup-<timestamp>`), never beside the target: the config holds secrets, and the target's directory is typically a dotfiles git work tree. The plan, the `--install` result and the `--json` outcome report the real file written as `configPath` (also shown by `--dry-run`) and the link as `linkPath` (absent for a regular file); the summary and the `harness init` wizard's install line add `(via symlink <link>)`, and a refusal that points at the `.harness-backup-*` files names the link's backup location. A dangling link (the refusal names the missing end of the chain), an unresolvable chain (a loop, a permission error) or a link to anything other than a regular file (such as a directory) is refused with a `CodexInstallRefusalError` naming the link, and nothing is written. `atomicWriteFile` itself and non-symlink config paths (including a regular config inside a symlinked `~/.codex` directory) are unchanged. Pinned by fixtures in `tests/cli/apply/apply-codex-runtime.test.ts` and `tests/cli/init-interactive.test.ts`.
+
 ## [0.58.2] - 2026-09-24
 
 ### Fixed
@@ -33,9 +62,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
   **Upgrade note:** Codex tracks per-hook trust in `[hooks.state]` (`<config path>:<event>:<group index>:<handler index>` keys, `trusted_hash` computed over a normalized hook identity, not raw source text; see `codex-rs/hooks/src/engine/discovery.rs`'s `hook_hash`/`hook_trust_status` and `codex-rs/hooks/src/lib.rs`'s `hook_key`, openai/codex commit `30fc6864cc1318121eca1843c217fe00ce1212f1`). Harness never writes or forges `trusted_hash`; it only stops deleting the table that holds it. A hook whose emitted command, matcher, or `[[hooks.<Event>]]` table position changes (the key embeds the table's ordinal index for that event) gets a new hash/key and reverts to `Untrusted` until the operator re-approves it in Codex, same as any hand-edited hook; this was already true before this fix, it is just no longer masked by the whole trust table being deleted. The UG Codex `post-tool-use` hook disappearing from an install is separate and expected: it is suppressed under `approval_lifecycle: { mode: session }` (`resolveExpireOnToolMatch`, `src/policy-packs/builtin/understanding-before-execution.ts`), pinned by `tests/policy-packs/expand.test.ts` ("Codex adapter contributes..." for the default-present case, "...suppressed when approval_lifecycle.mode = session..." for the opt-out); re-running the install under `mode: session` correctly removes that stale block, it is not a regression. A command, matcher, or timeout change (also an `async`/`status_message` change) yields a new hash under the SAME key; a position change instead moves which key the entry lives under; either way the affected hook's status reads `Modified` or `Untrusted` and Codex will not run it until re-approved. Separately, a `[hooks.state]` entry can carry a positional `enabled` override for that same key; adding or removing a hook earlier in an event's list shifts every later hook's ordinal index, which can land an operator's own `enabled = false` override onto a DIFFERENT hook than the one they disabled. Review Codex's hook list after any install that changes the hook roster (adds, removes, or reorders a hook for an event), not only after one that changes a single hook's command. Also: since harness 0.57.0 (stay-in-scope became an explicit opt-in), a re-install removes the codex "stay in scope" hook block unless `stay_in_scope` is enabled in the manifest -- expected, not a regression, same class as the `post-tool-use` disappearance above.
 
-  Also hardened in the same change (task `6a037359`): a dedicated fixture in `tests/cli/apply/apply-codex-runtime.test.ts` for each guard that previously had no fixture exercising it -- an operator comment sitting directly above the first foreign table (stays attached to that table, not folded into the replaced block, and appears exactly once); two harness-managed BEGIN markers (refused, file untouched); a BEGIN with no END where a foreign table is followed further down by a real `# harness hook:` comment (refused, since the block boundaries can no longer be read as a plain line scan); a managed block whose END marker is followed by a trailing operator comment at EOF (kept, not silently replaced away; this holds only when the END marker is present: in a config with no END marker, a trailing comment after the last harness hook table is still read as part of the block and replaced, a known limitation); exact (not `arrayContaining`) equality on `foreignSectionsPreserved` and `removedHookIds`, plus one exact byte-for-byte equality on the whole installed output for the drifted fixture. A CLI-level test (through the built program, not only the library function) asserts `--dry-run`'s and the applied install's own stdout for the removed-hook-block and preserved-foreign-section lines. The refusal itself is more actionable: it names the RESOLVED config path (never a hard-coded `~/.codex`), the first foreign table (its bracketed header only) and the line number of the first line beyond it that still looks like harness content (never that line's own text), and either tells the operator to move that table below the END marker or delete the lines between BEGIN and END (when one exists), or, when there is no END marker at all, to add one after the last harness hook table or move the foreign table below it instead (telling the operator to move something below a marker that does not exist would be nonsensical); a duplicate-BEGIN refusal tells the operator to delete the entire unwanted BEGIN/END pair, including its own marker lines and source-prefix comment, not just the lines between them. Either refusal offers the `.harness-backup-*` restore only as a last resort with an explicit warning that it discards any Codex state (hook trust, marketplaces, plugins) written since that backup; it throws a dedicated `CodexInstallRefusalError` (a `HarnessExitError` at `EX_FAIL`) instead of a plain `Error`, and `--json` emits a structured `{ outcome: "codex-install-refuse", configPath, error }` object on stdout the same way `target-exists-refuse`/`drift-refuse` already do, instead of only the plain-text message reaching stderr. The install's own permissions no longer widen a secret-bearing config: it preserves the EXISTING file's mode for both the rewritten config and its `.harness-backup-*` copy (0640 as well as 0600, pinned), defaulting to `0600` (not `atomicWriteFile`'s own `0644`) only when creating a config that did not exist before. `foreignSectionsPreserved` prints a namespace's ROOT with a wildcard and its table count when more than one table collapses into it (e.g. `[marketplaces.*] (2 tables)`), instead of silently representing several preserved tables as one indistinguishable header; a single table under a root still prints its own full header. The namespace is the header's first key, or its first two keys under `hooks` (e.g. `[hooks.state.*] (27 tables)`, so Codex's trust table is not reported as `hooks`, which also holds the harness-managed hook arrays), with keys split quote-aware and a trailing comment never part of the namespace or of a printed header. Table-header recognition is a full single-line TOML header shape, quote-aware so a key containing `[`, `]`, `.` or `#` (a real path used as a TOML key, e.g. `[projects."/Users/x/Photos [2024]"]`) is still recognized as one header on every managed-range detection path (a drifted END, no END, and the legacy no-BEGIN path), instead of being misread as ending the header early or as still-owned content; a multi-line array's own continuation line inside a still-owned hook table (e.g. `  [1, 2],`) is never misread as a foreign table header ending the region early. The stray-END search matches a whole trimmed line, not a raw substring, so a foreign single-line value that merely contains the END marker text as a substring is never mistaken for the real stray END. A TOML multi-line string is now tracked by its own opening delimiter (`"""` or `'''`), closed only by that same delimiter, with an escaped quote and a delimiter inside a comment or a single-line string ignored, so a foreign table's own multi-line string value (or a still-owned hook table's own multi-line matcher) can contain a line that reads exactly like a comment, a table header, or even the END marker without corrupting the scan.
+  Also hardened in the same change (task `6a037359`): a dedicated fixture in `tests/cli/apply/apply-codex-runtime.test.ts` for each guard that previously had no fixture exercising it -- an operator comment sitting directly above the first foreign table (stays attached to that table, not folded into the replaced block, and appears exactly once); two harness-managed BEGIN markers (refused, file untouched); a BEGIN with no END where a foreign table is followed further down by a real `# harness hook:` comment (refused, since the block boundaries can no longer be read as a plain line scan); a managed block whose END marker is followed by a trailing operator comment at EOF (kept, not silently replaced away; a config with no END marker keeps a trailing operator comment too, unless the trailing run holds a harness-authored line, see the task `b34ed105` entry above); exact (not `arrayContaining`) equality on `foreignSectionsPreserved` and `removedHookIds`, plus one exact byte-for-byte equality on the whole installed output for the drifted fixture. A CLI-level test (through the built program, not only the library function) asserts `--dry-run`'s and the applied install's own stdout for the removed-hook-block and preserved-foreign-section lines. The refusal itself is more actionable: it names the RESOLVED config path (never a hard-coded `~/.codex`), the first foreign table (its bracketed header only) and the line number of the first line beyond it that still looks like harness content (never that line's own text), and either tells the operator to move that table below the END marker or delete the lines between BEGIN and END (when one exists), or, when there is no END marker at all, to add one after the last harness hook table or move the foreign table below it instead (telling the operator to move something below a marker that does not exist would be nonsensical); a duplicate-BEGIN refusal tells the operator to delete the entire unwanted BEGIN/END pair, including its own marker lines and source-prefix comment, not just the lines between them. Either refusal offers the `.harness-backup-*` restore only as a last resort with an explicit warning that it discards any Codex state (hook trust, marketplaces, plugins) written since that backup; it throws a dedicated `CodexInstallRefusalError` (a `HarnessExitError` at `EX_FAIL`) instead of a plain `Error`, and `--json` emits a structured `{ outcome: "codex-install-refuse", configPath, error }` object on stdout the same way `target-exists-refuse`/`drift-refuse` already do, instead of only the plain-text message reaching stderr. The install's own permissions no longer widen a secret-bearing config: it preserves the EXISTING file's mode for both the rewritten config and its `.harness-backup-*` copy (0640 as well as 0600, pinned), defaulting to `0600` (not `atomicWriteFile`'s own `0644`) only when creating a config that did not exist before. `foreignSectionsPreserved` prints a namespace's ROOT with a wildcard and its table count when more than one table collapses into it (e.g. `[marketplaces.*] (2 tables)`), instead of silently representing several preserved tables as one indistinguishable header; a single table under a root still prints its own full header. The namespace is the header's first key, or its first two keys under `hooks` (e.g. `[hooks.state.*] (27 tables)`, so Codex's trust table is not reported as `hooks`, which also holds the harness-managed hook arrays), with keys split quote-aware and a trailing comment never part of the namespace or of a printed header. Table-header recognition is a full single-line TOML header shape, quote-aware so a key containing `[`, `]`, `.` or `#` (a real path used as a TOML key, e.g. `[projects."/Users/x/Photos [2024]"]`) is still recognized as one header on every managed-range detection path (a drifted END, no END, and the legacy no-BEGIN path), instead of being misread as ending the header early or as still-owned content; a multi-line array's own continuation line inside a still-owned hook table (e.g. `  [1, 2],`) is never misread as a foreign table header ending the region early. The stray-END search matches a whole trimmed line, not a raw substring, so a foreign single-line value that merely contains the END marker text as a substring is never mistaken for the real stray END. A TOML multi-line string is now tracked by its own opening delimiter (`"""` or `'''`), closed only by that same delimiter, with an escaped quote and a delimiter inside a comment or a single-line string ignored, so a foreign table's own multi-line string value (or a still-owned hook table's own multi-line matcher) can contain a line that reads exactly like a comment, a table header, or even the END marker without corrupting the scan.
 
-  A TOML-parsing safety net now runs after the byte-preserving splice above computes its output, before anything is written: both the current and the about-to-be-written config are parsed with `smol-toml` (a new runtime dependency, pinned `~1.8.0`) and compared. The invariant: both must parse, and once every harness-managed hook event array (`[[hooks.<Event>]]`) is removed from both documents, everything else must come out identical: `[hooks.state]` and every other single-table `hooks.*` key, plus all non-hooks content (`[projects.*]`, `[plugins.*]`, `[marketplaces.*]`, `[mcp_servers.*]`, top-level keys). Any difference refuses via `CodexInstallRefusalError`, naming the first differing key path, with the file left untouched (a `--dry-run` plan hits the same check and reports the same refusal). For that content the net is independent of the header-recognition and multi-line-string fixes above, so a future scanner regression there refuses instead of silently dropping content. It does not cover the hook event arrays themselves: an operator-authored `[[hooks.<Event>]]` entry that the line scan counts as part of the harness-managed block (for example one sitting between the block and a drifted END marker, or after a BEGIN with no END marker) is still replaced without a refusal; tracked as follow-up task `01053b27`. An operator hook entry outside the managed block is kept whatever its header spelling (a trailing comment, a quoted event key). A leading UTF-8 byte order mark is ignored for parsing (the written file keeps it unless the harness block itself starts on the file's first line, which is harmless because Codex's own parser strips it too), and an integer beyond 2^53 (TOML integers are 64-bit) is compared exactly instead of failing the parse. A config the harness parser cannot read refuses with "the TOML parser used by harness could not read this file", the parser's line, column and one-line reason, not a claim that the operator's syntax is wrong; a would-be output that does not parse names an operator-defined inline `hooks` table or inline hook-event array as the likely cause before a harness defect. No refusal quotes a value line of the config or the parser's code frame; only table headers and key paths are named: parse refusals carry only that position and reason (never the parser's code frame, which would echo neighbouring lines such as an API token), and the split-block and duplicate-BEGIN refusals name a line number instead of that line's text.
+  A TOML-parsing safety net now runs after the byte-preserving splice above computes its output, before anything is written: both the current and the about-to-be-written config are parsed with `smol-toml` (a new runtime dependency, pinned `~1.8.0`) and compared. The invariant: both must parse, and once every harness-managed hook event array (`[[hooks.<Event>]]`) is removed from both documents, everything else must come out identical: `[hooks.state]` and every other single-table `hooks.*` key, plus all non-hooks content (`[projects.*]`, `[plugins.*]`, `[marketplaces.*]`, `[mcp_servers.*]`, top-level keys). Any difference refuses via `CodexInstallRefusalError`, naming the first differing key path, with the file left untouched (a `--dry-run` plan hits the same check and reports the same refusal). For that content the net is independent of the header-recognition and multi-line-string fixes above, so a future scanner regression there refuses instead of silently dropping content. It does not cover the hook event arrays themselves: an operator-authored `[[hooks.<Event>]]` entry that the line scan counts as part of the harness-managed block (for example one sitting between the block and a drifted END marker, or after a BEGIN with no END marker) is still replaced without a refusal; tracked as follow-up task `01053b27`. An operator hook entry outside the managed block is kept whatever its header spelling (a trailing comment, a quoted event key). A leading UTF-8 byte order mark is ignored for parsing (the splice keeps it exactly once, also when the harness block starts on the file's first line, see the task `b34ed105` entry above), and an integer beyond 2^53 (TOML integers are 64-bit) is compared exactly instead of failing the parse. A config the harness parser cannot read refuses with "the TOML parser used by harness could not read this file", the parser's line, column and one-line reason, not a claim that the operator's syntax is wrong; a would-be output that does not parse names an operator-defined inline `hooks` table or inline hook-event array as the likely cause before a harness defect. No refusal quotes a value line of the config or the parser's code frame; only table headers and key paths are named: parse refusals carry only that position and reason (never the parser's code frame, which would echo neighbouring lines such as an API token), and the split-block and duplicate-BEGIN refusals name a line number instead of that line's text.
 
 ## [0.58.0] - 2026-09-23
 
@@ -62,7 +91,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 - **`harness pack hook solution-acceptance`'s completion-gate deny text now distinguishes the three `gate.verdict === null` readings instead of appending the same reconnect-vs-retry paragraph to all three** (task `799de976`). The hook reads grounding-mcp's documented attempt-lock anchor (`<verdict dir>/<id>.attempt-lock`, README "Attempt lock anchor" row at `grounding-mcp-v0.12.0`) via `proper-lockfile`'s own read-only `checkSync` (already a harness dependency; no new one added) to tell "an attempt is live" apart from "never evaluated" and "a marker path exists but what is there was not accepted as a verdict"; liveness is three-valued (`live`, `not-live`, `unknown`, through a read-only `checkFileLock` in `src/io/lock.ts`), and a note never asserts an absent attempt or a missing marker when the check could not read; the full reconnect-vs-retry paragraph (`solution-acceptance-reconnect.ts`) is now appended only for the live-attempt reading, and the other two readings get their own short, reading-named line instead; the paragraph's own wording is corrected to say the hook itself read the anchor and detected the live-attempt reading, not that it cannot tell the three readings apart (its shared facts, `RECONNECT_FACT_*` and `renderReconnectInstructionsSection`, stay byte-identical). A lock directory left behind by a dead process is read as stale using the producer's OWN staleness window (`DEFAULT_ATTEMPT_LOCK_STALE_MS = 30_000`, `grounding-mcp-v0.12.0` `solution-attempt-log.ts:102`, the default `acquireAttemptLock` passes to `proper-lockfile` when no caller overrides `staleMs`), so this hook's "live" reading and the producer's reclamation rule agree as long as the producer keeps that default and no caller overrides it: an operational pin re-checked on every grounding-mcp bump, not a guarantee. `instructions.md` and grounding-mcp's lock layout are unchanged. See `docs/policy-packs/solution-acceptance.md`, "Reading the attempt-lock anchor to distinguish the three readings", for the full decision record and source citations. Pinned in `tests/cli/pack-hook-solution-acceptance.test.ts` (one case per reading, the overlap of a live lock with an unreadable marker, a stale-lock regression, two check-error-path regressions, a symlinked anchor) and in `tests/io/lock.test.ts` and a literal-wording pin in `tests/policy-packs/solution-acceptance-reconnect.test.ts`; mutation probes removing the live-attempt branch, neutralising the stale rule, substituting a hand-copied paragraph, flipping the check-error catch arm, and reverting the corrected wording (`agent-primitives probe --pre 'npm run build'`) all killed.
 
-  - **Review-round fixes: the deny note now states only what the hook established** (task `799de976`, commit `3d3bddf`; the same defect class recurred in four consecutive rounds, so this round closes the CLASS). Each round's note asserted something the hook had not established, and each fix replaced one guessed cause with a narrower guess that the next reachable state falsified: first "no attempt reads as currently live" where the liveness check had thrown, then "the verdict directory could not be read" where only the lock path was unreadable, then "the verdict directory or the attempt-lock path could not be read" for an id from which NEITHER path can be derived. An id `sanitizeVerdictId` rejects (`.`, `..`, anything sanitizing to an empty basename, reachable from an active claim; the `SOLUTION_VERDICT_ID` path validates through the same function and answers null instead) is now its own `NullVerdictInfo` union member, settled before anything is read and carrying no `liveness` field, so "the id was unusable" has no field left to render as "a path could not be read"; its note names that one fact, points at the active claim, and asks for a usable id instead of repeating `solution_evaluate` for an id that can never be accepted. The remaining unknown-liveness line names no cause at all. Reading (3) no longer says "could not be read or parsed" for a marker `readVerdict` refuses by policy (a symlink, a non-regular file); it names the complete set of ways that read answers null for a present path, at the hook and at the shared reading-label site (`RECONNECT_THREE_READINGS_LABELS`). A state table in `tests/cli/pack-hook-solution-acceptance.test.ts` ("null-verdict deny note: one exact line per reachable state") pins one exact expected line per reachable (id-usability, reading, liveness) combination, nine rows, and asserts no other state's line appears, so this class fails there rather than reaching an agent; it doubles as the checklist for extending the classifier. The stale-lock fixture's back-date is a literal (90 s) rather than derived from `ATTEMPT_LOCK_STALE_MS`, so it discriminates a widened window instead of staying stale under every mutation of the constant it was meant to pin. Mutation probes restoring the guessed cause, narrowing reading (3)'s wording back, and widening the stale window to 300 s (`agent-primitives probe`, the last one scoped to the stale test alone) all killed.
+  - **Review-round fixes: the deny note now states only what the hook established** (task `799de976`, commit `3d3bddf`; the same defect class recurred in four consecutive rounds, so this round closes the CLASS). Each round's note asserted something the hook had not established, and each fix replaced one guessed cause with a narrower guess that the next reachable state falsified: first "no attempt reads as currently live" where the liveness check had thrown, then "the verdict directory could not be read" where only the lock path was unreadable, then "the verdict directory or the attempt-lock path could not be read" for an id from which NEITHER path can be derived. An id `sanitizeVerdictId` rejects (`.`, `..`, anything sanitizing to an empty basename, reachable from an active claim; the `SOLUTION_VERDICT_ID` path validates through the same function and answers null instead) is now its own `NullVerdictInfo` union member, settled before anything is read and carrying no `liveness` field, so "the id was unusable" has no field left to render as "a path could not be read"; its note names that one fact, points at the active claim, and asks for a usable id instead of repeating `solution_evaluate` for an id that can never be accepted. The remaining unknown-liveness line names no cause at all. Reading (3) no longer says "could not be read or parsed" for a marker `readVerdict` refuses by policy (a symlink, a non-regular file); it names the complete set of ways that read answers null for a present path, at the hook and at the shared reading-label site (`RECONNECT_THREE_READINGS_LABELS`). A state table in `tests/cli/pack-hook-solution-acceptance.test.ts` ("null-verdict deny note: one exact line per reachable state") pins one exact expected line per reachable (id-usability, reading, liveness) combination, nine rows at that commit (eleven after the round-6 fixture additions, fourteen once the liveness axis was completed, see the `[Unreleased]` entry for task `8fe0f633`), and asserts no other state's line appears, so this class fails there rather than reaching an agent; it doubles as the checklist for extending the classifier. The stale-lock fixture's back-date is a literal (90 s) rather than derived from `ATTEMPT_LOCK_STALE_MS`, so it discriminates a widened window instead of staying stale under every mutation of the constant it was meant to pin. Mutation probes restoring the guessed cause, narrowing reading (3)'s wording back, and widening the stale window to 300 s (`agent-primitives probe`, the last one scoped to the stale test alone) all killed.
 
   - **Round-6 review fix: the deny text is classified from ONE read of the marker** (task `799de976`, commit `244f9c3`). The gate read the marker at the decision site and the deny text classified it again a few statements later, so the two could disagree: a background attempt finishing in that window, the case this pack exists for, made the note tell the agent its fresh marker had been rejected when the gate had simply not seen it yet, and the reasons the note enumerated did not include the one that actually applied. A new `readVerdictDetailed` reports WHY a read yielded no verdict (`invalid-id`, `missing`, the shared reader's `symlink` / `not-regular` / `unreadable`, plus `invalid-record`) in one observation; `readVerdict` is the same function with the reason dropped, so every caller that needs only the gate decision is unchanged. Reading (3) no longer restates a disjunction over the rejection kinds: each kind renders its own line naming what that read established. The lines are a `Record` keyed by the exported `NULL_VERDICT_NOTE_STATES`, so a state with no line fails the build, and the state table's new coverage test fails when a listed state has no fixture, which makes the table a checklist rather than a convention. Two fixtures are added (a schema-invalid record, and a regular file the process may not read), the symlink and directory fixtures now pin their own distinct lines, and the unusable-id remedy names the verb that clears the claim instead of asking for an impossible re-run. The liveness helper loses a `catch` that became unreachable once id usability was settled first: an arm no mutant can kill is worse than no arm. Mutation probes collapsing one rejection line into another, and adding a note state with no fixture, both killed; the removed race itself is not fixture-testable, which is why the fix removes the second observation rather than adding a test for it.
 

package/README.md

@@ -2,85 +2,20 @@
 
 **Declarative control plane for agent harnesses.**
 
-One zod-validated YAML manifest for grounding, tools, memory, hooks,
-policies, and workflows, plus a CLI that describes, validates, diffs,
-applies, audits, and *enforces*.
-
-> Most config tools tell you what an agent is configured to use.
-> `harness` tells you what an agent is *allowed to do*, under this
-> exact context, and why.
+## Overview
 
 A coding agent like Claude Code is configured across half a dozen
-files (`settings.json`, `CLAUDE.md`, memory notes, MCP registrations,
-hook scripts, per-project overrides), and no single file answers
-*"what can this agent do right now, and why is it set up that way?"*.
-`harness` puts all of it in one YAML you read, validate, and diff;
-generates the config the agent loads from it; and at runtime blocks
-tool calls that violate the declared rules while recording every
-decision.
-
-## See it work
-
-One rule, declared in `harness.yaml`: *no session may merge a PR
-until it has logged a review.*
-
-Claude Code goes to merge PR 42. Before the tool call runs, the
-runtime hands the event to `harness`, which checks it against the
-manifest. The hook protocol wire shape is the legacy engine-vocabulary
-envelope (operators see this on stderr; agents read it via
-`permissionDecisionReason` when the policy declares no `ux:` block):
-
-```console
-$ harness policy intercept       # Claude Code runs this before each tool call
-{"decision":"block","reason":"review-before-merge: no matching ledger entry for tag `review:42`","hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"review-before-merge: no matching ledger entry for tag `review:42`"}}
-```
-
-Built-in block-enforcement policies ship a `ux:` block since v0.17.0,
-so the agent sees a plain-language three-section form
-([`docs/for-agents.md`](docs/for-agents.md#agent-facing-block-messages-ux-block));
-the engine-vocabulary text above stays in the audit ledger.
-
-Blocked. `harness explain` says exactly why:
-
-```console
-$ harness explain review-before-merge --trace
-name: review-before-merge
-decision: deny
-enforcement: block
-reason: no matching ledger entry for tag `review:42`
-ledgerTag: review:42
-extract:
-  PR_NUMBER: "42"
-requiresEval:
-  matchedCount: 0
-  reason: no matching ledger entry for tag `review:42`
-# ... (trimmed; the full trace also shows the matched trigger, every extracted variable, and the ledger query)
-```
-
-The rule pulled `PR_NUMBER=42` out of the tool call and looked for a
-`review:42` entry in the evidence ledger. There wasn't one. So the
-reviewer (or a review subagent) logs that entry, and the *same* merge
-call, retried, goes straight through, no restart, no config edit:
-
-```console
-$ harness policy intercept       # same call, after the review was logged
-$                                # (no output, exit 0: allowed)
-```
-
-Every one of those decisions is recorded:
-
-```console
-$ harness audit --since 1h --policy review-before-merge
-timestamp            policy               outcome  reason
--------------------  -------------------  -------  --------------------------------------------
-2026-05-14 19:09:03  review-before-merge  deny     no matching ledger entry for tag `review:42`
-2026-05-14 19:09:13  review-before-merge  allow    1 matching ledger entry for tag `review:42`
-```
-
-Declare the rule once; every session is held to it, with a paper
-trail of every decision.
-
-## Concepts in six lines
+files: `settings.json`, `CLAUDE.md`, memory notes, MCP registrations,
+hook scripts, per-project overrides. No single file answers "what can
+this agent do right now, and why is it set up that way?" `harness`
+puts all of it in one zod-validated YAML manifest you read, validate,
+and diff; generates the config the agent runtime loads from it; and at
+runtime blocks tool calls that violate the declared rules while
+recording every decision to an evidence ledger. Most config tools
+describe what an agent is configured to use; `harness` decides what it
+is allowed to do, under the exact context, and records why.
+
+## Key concepts
 
 | Term | What it is |
 |------|-----------|
@@ -91,213 +26,82 @@ trail of every decision.
 | **hook** | A script the agent runtime runs at a lifecycle event (session start, before every tool call, ...). How policies get enforced. |
 | **policy pack** | A reusable bundle of policies, hooks, and templates shipped under one name and enabled with a single manifest key. |
 
-## What harness does
-
-```mermaid
-flowchart LR
-    declare["1. Declare<br/><code>harness.yaml</code>"]
-    apply["2. Apply<br/><code>harness apply</code>"]
-    enforce["3. Enforce<br/>hooks + policies<br/>at runtime"]
-    record[("4. Record<br/>evidence ledger")]
-    observe["5. Observe<br/><code>audit</code> / <code>explain</code> /<br/><code>session-export</code>"]
-
-    declare --> apply
-    apply --> enforce
-    enforce --> record
-    record --> observe
-    observe -. refine .-> declare
-```
-
-Observe → refine → declare is the whole loop. The read-side surfaces
-(`audit`, `explain --trace`, `session-export`) replay rows the runtime
-already recorded, so what flows back into the manifest is grounded in
-what actually happened.
-
-## Pick your audience
-
-- **Operator?** [`docs/for-humans.md`](docs/for-humans.md): install through first `apply`, first real policy, diagnostics cheat sheet.
-- **Agent (or onboarding one)?** [`docs/for-agents.md`](docs/for-agents.md): workflow lifecycle, policy / ledger sequence, CLI cheat sheet by side-effect class, the audit triumvirate.
-- **Writing your own policy?** [`docs/writing-custom-policies.md`](docs/writing-custom-policies.md): three tripwires, four worked recipes (each validated in CI), author loop, field reference.
-- **Guarding destructive runtime commands?** [`docs/runtime-reality-hook.md`](docs/runtime-reality-hook.md): block compose/systemctl/kill/deploy calls when the live process state has drifted from what the docs expect.
-- **Looking up a CLI verb?** [`docs/CLI.md`](docs/CLI.md): every command the `harness` binary exposes, grouped by purpose (manifest, runtime, hooks, approvals, gates, preflight).
-
-## Install
+## Quick start
 
 ```bash
-npm i -g @lannguyensi/harness
+npm i -g @lannguyensi/harness   # Node 20 or newer
+harness init --interactive      # guided wizard, or: --template solo|team|full
 ```
 
-The CLI binary is `harness`. Node 20 or newer required.
+The wizard detects your `~/.claude/` and `~/.codex/` setup, MCP
+servers already wired in `settings.json`, and the harness binary
+version, then writes a starting `harness.yaml`. Full operator
+walkthrough: [`docs/for-humans.md`](docs/for-humans.md); a five-minute
+non-interactive path plus a profile comparison table:
+[`docs/quickstart.md`](docs/quickstart.md).
 
-## First-time setup
+## Usage
 
-In a hurry? [`docs/quickstart.md`](docs/quickstart.md) is the bare
-command path, install to wired-in, no prose.
+Preview which policies would fire for a tool call, before any ledger
+I/O or file write:
 
 ```bash
-harness init --interactive
-```
-
-Guided wizard. Detects `~/.claude/` and `~/.codex/`, MCP servers
-already wired in `settings.json`, harness binary version. Picks a
-profile (`solo` / `team` / `full` / `custom`) and writes a starting
-`harness.yaml`. Ctrl-C aborts cleanly. Walkthrough +
-limitations: [`docs/init-interactive.md`](docs/init-interactive.md).
-
-Every enabled `tools.mcp[]` server is then registered with Claude
-Code via `claude mcp add-json --scope user` — the surface Claude Code
-actually reads for user-scope MCP servers; harness itself never
-writes `~/.claude.json`. This step requires the `claude` CLI on
-`$PATH`; if it's missing, the wizard warns and prints the equivalent
-`claude mcp add-json` commands to run by hand instead of failing.
-`harness doctor` includes a "Claude Code MCP Registration" section
-that re-verifies the live registration via `claude mcp list`.
-
-### Profiles at a glance
-
-| Profile | External accounts / tools required | Best for |
-|---------|------------------------------------|----------|
-| `solo`  | None. `npm` + Claude Code is enough. | Single operators who want the Understanding Gate without committing to a tasking system. |
-| `team`  | An **agent-tasks** account ([hosted](https://agent-tasks.opentriologue.ai) or [self-hosted](https://github.com/LanNguyenSi/agent-tasks)). | Teams that already use `agent-tasks` for PR review tracking. The merge gate (`review:<pr-number>` ledger tag) wires against the agent-tasks MCP. |
-| `full`  | Same as `team` plus `@lannguyensi/agent-preflight` and `gh` on PATH. | Operators who want every reference policy enforced (dogfood gate, preflight gates, review-subagent gate, merge gate). |
-
-**Not using agent-tasks?** Pick `solo`. The `team` and `full` review gates currently match only the agent-tasks MCP tool names, so a `gh pr create` workflow stays unprotected by them today. Tool-agnostic gates that also match `gh pr` are tracked in the backlog.
-
-If you prefer non-interactive (CI, fresh-VM provisioning), pick a
-template directly:
-
-```bash
-harness init --template solo   # memory-router + understanding-before-execution pack
-harness init --template team   # solo + agent-tasks MCP + review-before-merge policy
-harness init --template full   # everything from the Appendix A reference manifest
+harness dry-run "merge PR 42" \
+  --tool mcp__agent-tasks__pull_requests_merge \
+  --tool-args '{"prNumber":42}'
 ```
 
-Use `harness init --probe` for a JSON snapshot of detected runtimes
-and MCPs without writing anything.
-
-## Try it without installing
+Once a manifest is applied, the same shape runs live as
+`harness policy intercept` (invoked by the runtime's PreToolUse hook),
+and `harness explain <policy> --trace` / `harness audit --since 1h`
+replay what actually fired and why. The full install-to-audit
+walkthrough is in [`docs/quickstart.md`](docs/quickstart.md).
+
+## Documentation
+
+- [`docs/for-humans.md`](docs/for-humans.md): operator path, install through first real policy, diagnostics cheat sheet.
+- [`docs/for-agents.md`](docs/for-agents.md): agent integration contract, workflow lifecycle, CLI cheat sheet by side-effect class.
+- [`docs/quickstart.md`](docs/quickstart.md): five-minute bare-command path and profile comparison.
+- [`docs/init-interactive.md`](docs/init-interactive.md): the `harness init --interactive` wizard, walkthrough and limitations.
+- [`docs/CLI.md`](docs/CLI.md): every CLI verb, grouped by purpose.
+- [`docs/risk-gate.md`](docs/risk-gate.md): the four-way `allow / warn / require_approval / deny` Risk Gate.
+- [`docs/writing-custom-policies.md`](docs/writing-custom-policies.md): tripwires, worked recipes, and the policy field reference.
+- [`docs/runtime-reality-hook.md`](docs/runtime-reality-hook.md): blocking destructive runtime commands when live process state has drifted from what the docs expect.
+- [`docs/policy-packs/README.md`](docs/policy-packs/README.md): the built-in policy packs (`understanding-before-execution`, `branch-protection`, `solution-acceptance`, `post-merge-gate`).
+- [`docs/uninstall.md`](docs/uninstall.md): the single-command teardown, dry-run by default.
+- [`docs/examples/full-manifest.yaml`](docs/examples/full-manifest.yaml): a schema-coverage reference (not a runnable config; its header explains why).
+- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md): manifest schema, file layout, CLI surface (historical design intent; see its own note for the current shape).
+- [`docs/VISION.md`](docs/VISION.md): why a declarative control plane, not more individual tools.
+- [`docs/ROADMAP.md`](docs/ROADMAP.md): the phase-by-phase plan and the acceptance criteria each phase shipped against.
+- [`CHANGELOG.md`](CHANGELOG.md): what shipped in each version.
+
+### Related projects
+
+- [`agent-grounding`](https://github.com/LanNguyenSi/agent-grounding): evidence-ledger, claim-gate, review-claim-gate; `grounding-mcp` is the canonical client surface harness queries.
+- [`agent-memory`](https://github.com/LanNguyenSi/agent-memory): the memory surfaces the control plane inventories.
+- [`agent-tasks`](https://github.com/LanNguyenSi/agent-tasks): MCP-registered task platform whose registration and health appear in `harness describe`.
+- [`agent-preflight`](https://github.com/LanNguyenSi/agent-preflight): local preflight validator; the canonical implementation of preflight-hook content harness wires.
+- [`codebase-oracle`](https://github.com/LanNguyenSi/codebase-oracle): opt-in MCP for multi-repo RAG search; wire via `harness add mcp codebase-oracle --command codebase-oracle,mcp`.
+- [`agent-dx`](https://github.com/LanNguyenSi/agent-dx): ships `git-batch-cli`, a day-to-day tool whose inventory appears in `harness describe`.
 
-`harness dry-run` reports which hooks fire and which policies match
-for a given tool call, against the reference manifest, before any
-ledger I/O:
+## Development and contributing
 
 ```bash
-git clone https://github.com/LanNguyenSi/harness && cd harness
-npm install && npm run build
-node dist/cli/main.js dry-run "merge PR 42" \
-  --tool mcp__agent-tasks__pull_requests_merge \
-  --tool-args '{"prNumber":42}' \
-  --config docs/examples/full-manifest.yaml
+npm install
+npm run build
+npm test
 ```
 
-`docs/examples/full-manifest.yaml` is a schema-coverage example, not a
-runnable config (the file header spells out the contract). For a
-manifest tailored to your machine, install globally and run
-`harness init --interactive`.
-
-## Uninstall
-
-`harness uninstall` is the single-command teardown: dry-run by default,
-`--apply` to mutate, `--restore-from <backup>` to roll back. Full
-inventory + recommended order in [`docs/uninstall.md`](docs/uninstall.md).
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the full PR checklist
+(import-boundary and duplication gates, changelog coverage, release
+steps).
 
 ## Status
 
-harness ships in phases. All seven are released: read-only inventory →
-managed edits → declarative truth → policy layer → polish and dogfood
-lessons → the Understanding Gate Policy Pack → the Risk Gate. Phase 7
-(the Risk Gate) landed in `v0.27.0`. Operator-surface milestones along
-the way: `harness pause/resume` in `v0.22.0`, `migrate-home` in
-`v0.24.0`, Codex-runtime adapter polish in `v0.28.x` and `v0.29.0`,
-`approve risk --force` in `v0.30.0`, the opt-in `runtime-reality`
-drift gate in `v0.31.0`, the opt-in `solution-acceptance` pack in
-`v0.32.0`, the operator-only `approve branch-protection` marker in
-`v0.33.0`, the `harness gc` retention cleanup plus non-TTY-safe
-confirmations in `v0.34.0`, `apply` failing loud when policies are
-declared without `grounding-mcp` wired in `v0.35.0`, and the
-`harness doctor --rm-rogue-ledgers` cleanup mode plus the read-only
-Bash classifier re-admitting `sort` / `tree` / `file` in `v0.36.0`.
-Selected milestones since then (not exhaustive; see `CHANGELOG.md`
-for the full list): HMAC-signed understanding-gate approval markers
-in `v0.41.0`, the opt-in `post-merge-gate` policy pack in `v0.42.0`,
-the `&`-as-command-boundary trigger fix in `v0.43.0`, per-policy
-cross-repository attribution for `${REPO}`/`${BRANCH}` preflight
-facts in `v0.44.0`, and `apply --runtime codex|opencode` next-steps
-hints in `v0.46.0`.
-The current release is `v0.58.2`.
-
-The phase-by-phase plan with acceptance criteria lives in
-[`docs/ROADMAP.md`](docs/ROADMAP.md); what shipped in each version is
-in [`CHANGELOG.md`](CHANGELOG.md).
-
-## Policy Packs
-
-A *Policy Pack* is a reusable bundle of hooks, policies, instruction
-template, and permission profiles shipped under one name and enabled
-from `harness.yaml` with a single key:
-
-```yaml
-policy_packs:
-  - name: understanding-before-execution
-    config:
-      mode: grill_me                  # fast_confirm | grill_me | strict
-      permission_profile: safe-start  # safe-start | implementation-after-approval | high-risk-grill-me
-```
-
-Manage packs with `harness pack add / remove / list`. Four packs ship
-today: [`understanding-before-execution`](docs/policy-packs/understanding-before-execution.md)
-(forces an Understanding Report before any write-capable tool fires),
-[`branch-protection`](docs/policy-packs/branch-protection.md)
-(blocks source mutations on protected branches without an explicit
-override), the opt-in
-[`solution-acceptance`](docs/policy-packs/solution-acceptance.md)
-completion gate (added in `v0.32.0`; holds a task done until an
-accepted solution verdict is logged), and the opt-in
-[`post-merge-gate`](docs/policy-packs/post-merge-gate.md) pack (added
-in `v0.42.0`; denies mutating git/gh work on a branch whose tip has
-already been merged). Custom packs from `path:`, `npm:`, or `git:` sources are
-out of scope for v1 (see the pack docs for the future-vocabulary
-contract).
-
-## What's next
-
-The seven-phase roadmap is complete. The Risk Gate (Phase 7) shipped in
-`v0.27.0`: `harness policy intercept` reasons about the action itself
-(Action Envelope → Context Resolver → Risk Classifier), evaluates each
-policy's `when:` clauses, and enforces a four-way `allow / warn /
-require_approval / deny` decision, so `DROP TABLE users`, `kubectl
-delete namespace prod`, and `terraform destroy` against an unverified
-production target are blocked before the runtime fires them. See
-[`docs/risk-gate.md`](docs/risk-gate.md).
-
-Capability beyond the seven phases is not a quiet roadmap expansion: it
-lands as an explicit follow-up design doc or a separate sibling
-project, per [`docs/ROADMAP.md`](docs/ROADMAP.md) ("Out of scope across
-all phases").
-
-> Bring your favorite agent harness. Add governance.
-
-## Why this exists
-
-On 2026-04-23, an `agent-grounding` checkout that was 16 commits
-behind origin led two tasks to be incorrectly called "stale". The
-check that would have caught it already existed:
-[`agent-preflight`](https://github.com/LanNguyenSi/agent-preflight)
-runs `git fetch` + `git status` and emits a structured `ready` +
-confidence-score result. The missing piece was not the check, it was
-the deterministic *trigger*: a `SessionStart` hook that invokes
-`preflight run` and a policy that gates further work on the result.
-Building that wiring needs an agreed-upon place for harness config to
-live first. That conversation is the origin of this repo.
-
-## Related
-
-- [`agent-grounding`](https://github.com/LanNguyenSi/agent-grounding): evidence-ledger, claim-gate, review-claim-gate; `grounding-mcp` is the canonical client surface harness queries through `queryLedgerByTag`.
-- [`agent-memory`](https://github.com/LanNguyenSi/agent-memory): the memory surfaces the control plane inventories.
-- [`agent-tasks`](https://github.com/LanNguyenSi/agent-tasks): MCP-registered task platform whose registration + health appear in `harness describe`.
-- [`agent-preflight`](https://github.com/LanNguyenSi/agent-preflight): local preflight validator; the canonical implementation of preflight-hook content harness wires.
-- [`codebase-oracle`](https://github.com/LanNguyenSi/codebase-oracle): opt-in MCP for multi-repo RAG search; not in Full, wire via `harness add mcp codebase-oracle --command codebase-oracle,mcp`.
-- [`agent-dx`](https://github.com/LanNguyenSi/agent-dx): ships `git-batch-cli`, a day-to-day tool whose inventory appears in `harness describe`.
+The current release is `v0.59.1`. 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).
 
 ## License
 

package/dist/cli/apply/apply.d.ts

@@ -61,8 +61,11 @@ export interface ApplyOptions {
     /**
      * Phase 6 #6 — `--runtime <claude-code|codex>`. Selects which adapter
      * shape policy-pack hooks expand into and which artefacts apply
-     * writes. Defaults to `claude-code` (settings.json output unchanged
-     * from previous releases). When set to `codex`, settings.json is NOT
+     * writes. When omitted, `target` implies `claude-code`; otherwise the
+     * runtime recorded in `.last-apply` by the previous apply is reused
+     * (inferred from its files map for a record that predates the field);
+     * with no recorded or inferable runtime it defaults to `claude-code`
+     * (settings.json output unchanged from previous releases). When set to `codex`, settings.json is NOT
      * written; instead `harness.generated/codex/config.toml` carries the
      * Codex adapter configuration. The two runtimes are mutually
      * exclusive in a single apply for v1; cross-runtime applies are a
@@ -81,6 +84,18 @@ export interface ApplyOptions {
     now?: Date;
     /** Test-injectable confirmation prompt; defaults to a stdin readline. */
     prompt?: (message: string) => Promise<string>;
+    /**
+     * Keep the runtime `.last-apply` records instead of recording this
+     * apply's runtime. For a diagnostic apply (`harness smoke`) that must
+     * run under a fixed runtime without changing the operator's runtime
+     * selection: the files map is still updated, so the next plain apply
+     * reuses the kept runtime and rewrites that runtime's files back. A
+     * record without a runtime field gets the runtime inferred from it
+     * stamped instead (this apply's own files would otherwise change what
+     * the next apply infers); with nothing recorded or inferable the field
+     * stays absent.
+     */
+    preserveRecordedRuntime?: boolean;
 }
 export type ApplyOutcome = "no-changes" | "applied" | "drift-refuse" | "drift-discarded" | "would-apply" | "lock-drift-refuse" | "target-exists-refuse";
 export interface FileApplyOutcome {
@@ -93,7 +108,12 @@ export interface FileApplyOutcome {
     changed: boolean;
 }
 export interface CodexConfigInstallOutcome {
+    /** The regular file the install read and wrote; for a symlinked config,
+     * the link's resolved target (task 1637fbc8). */
     configPath: string;
+    /** The requested config path when it is a symlink, absent otherwise
+     * (task 1637fbc8). A backup of a symlinked config sits beside it. */
+    linkPath?: string;
     changed: boolean;
     written: boolean;
     summary: string;
@@ -152,7 +172,41 @@ export interface ApplyResult {
     targetMergeSummary?: string;
     /** Present when --runtime codex --install was requested. */
     codexConfigInstall?: CodexConfigInstallOutcome;
+    /** Adapter runtime this apply generated (or would generate) for. */
+    runtime: Runtime;
+    /**
+     * Where `runtime` came from: `explicit` (`--runtime` was passed),
+     * `target` (no `--runtime`, `--target` implies `claude-code`),
+     * `last-apply` (reused from the runtime `.last-apply` recorded),
+     * `inferred` (reused from a `.last-apply` that predates the field, read
+     * off its files map), `unrecorded` (such a record whose files map names
+     * no single runtime, so the default is used), or `default` (no
+     * `.last-apply` at all).
+     */
+    runtimeSource: RuntimeSource;
+    /**
+     * The runtime the previous apply recorded in `.last-apply`, or inferred
+     * from its files map when it predates the field. Absent when there is
+     * none.
+     */
+    previousRuntime?: Runtime;
+    /**
+     * `unrecorded` only: the runtimes the record's files map names (adapter
+     * artefacts and policy-pack instructions.md `## Runtime` sections) when
+     * they do not settle on one. Absent when the map names none.
+     */
+    runtimeCandidates?: Runtime[];
 }
+export type RuntimeSource = "explicit" | "target" | "last-apply" | "inferred" | "unrecorded" | "default";
+/**
+ * One line naming the runtime whenever it did not come from an explicit
+ * `--runtime` matching the last apply: a reused or inferred runtime, the
+ * default used for a record without one, the runtime `--target` implies,
+ * or an explicit switch away from the previous one. `null` when there is
+ * nothing to say (first apply, or an explicit `--runtime` equal to the
+ * previous one).
+ */
+export declare function formatRuntimeLine(result: Pick<ApplyResult, "runtime" | "runtimeSource" | "previousRuntime" | "runtimeCandidates">): string | null;
 declare const DRIFT_HINT_MESSAGE = "run \"harness adopt <file>\" to capture changes, or re-run with --overwrite-drift to discard them";
 export declare function apply(opts?: ApplyOptions): Promise<ApplyResult>;
 export { DRIFT_HINT_MESSAGE };