@lannguyensi/harness 0.58.1 → 0.59.0

package/CHANGELOG.md

@@ -7,6 +7,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [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
+
+- **`scripts/check-changelog-coverage.mjs`, `check-no-only.mjs`, `check-readme-release-version.mjs`, `check-release-notes-size.mjs` and `check-ug-schema-drift.mjs` now each have a CLI-spawn smoke test pinning their direct-run guard and exit-code wiring** (task `3aa81802`). Each script already exported testable pure functions (and, for the first four, an exported `main(repoDir)` covered in-process), but importing a module from a test never sets `isDirectRun` true, so nothing exercised the top-level `if (isDirectRun) { main(...); }` guard or, for `check-ug-schema-drift.mjs`, the `.catch()` handler's `process.exit(2)` wiring: the same untested shape `check-shipped-unreleased-pointer.mjs` had before task `ba7958e1`'s fix. Each of the five scripts now has a real green and a real red spawn fixture (`node scripts/<name>.mjs` as a child process) asserting the process's own exit code and stdout/stderr, so a mutant disabling the guard or forcing the exit code to 0 fails a test instead of letting CI print nothing and pass silently. For the first four scripts these fixtures never depend on the live repo's own state or the network. `check-ug-schema-drift.mjs`'s fixtures cover the OK exit, the drift-detected exit, the zero-keys extraction-failure exit and the missing-mirror build hint through the top-level catch, and are hermetic against the network and the live repo: a fake `npm` binary on the spawned process's own PATH supplies the upstream tarball, so no registry is contacted, while the live comparison against the published package stays in CI's own `check:ug-schema-drift` step.
+
+- **`harness apply --runtime codex --install` no longer creates and announces an empty backup file when no `~/.codex/config.toml` existed before the install** (task `461ec064`). `planCodexConfigInstall` now records whether the config path already held a file (`configExisted`, distinguishing "no prior file" from "an existing, possibly empty, prior file"), and `writeCodexConfigInstall` skips the `.harness-backup-*` write entirely when it did not, leaving `backupPath` unset on the result; the CLI's applied-output line and `formatNextSteps`'s next-steps lede were already gated on `backupPath` being present, so a fresh install now reports the write with no backup line. Installing over an existing config, including one that is empty, still backs it up unchanged (pinned by its own test), and the install refusal messages now say to restore from the most recent `.harness-backup-*` file only if one exists. Pinned by a fresh-install test in `tests/cli/apply/apply-codex-runtime.test.ts` for the library result (no `backupPath`, no `.harness-backup-*` sibling file) and for the CLI's applied output and next-steps text (no backup line), both failing at the pre-fix implementation and passing at head.
+
+- **The solution-acceptance completion-gate's deny text no longer names `solution_evaluate` as the next action when an attempt for the same id is already live** (task `58c65bc9`). The converge list's step 2 previously read `mcp__grounding-mcp__solution_evaluate({ id: "<id>" })` for every null-verdict reading, including reading (2) (an attempt is live), sitting directly above the reconnect paragraph's own "do not call it again" / "Never re-call `solution_evaluate`" sentences appended right below it for that same reading, so the agent-facing deny disagreed with itself on the one action it named twice. `convergeStep2For` in `src/cli/pack/hook-solution-acceptance.ts` now renders step 2 as a function of the reading: readings (1) (never evaluated) and (3) (an unreadable marker), and every non-null-verdict deny, keep the unqualified `solution_evaluate` step (wording unchanged apart from a colon in place of a dash); reading (2) instead names `solution_evaluate_status` / `solution_evaluate_result` (the same poll tools the reconnect paragraph itself names) and points at the reconnect paragraph, with no `solution_evaluate(` call instruction anywhere in that reading's deny text. `solution-acceptance-reconnect.ts` and its rendered `instructions.md` "Reconnecting vs. retrying" section are unchanged. Pinned by a dedicated test asserting the reading-(2) deny carries no `solution_evaluate(` call instruction and that its step 2 itself names both poll tools, plus assertions on the reading-(1) and reading-(3) fixtures that step 2 still names `solution_evaluate` unqualified.
+
+- `harness apply --runtime codex --install`'s split-block refusal now always names the actual foreign table header, including when the table is wedged directly between a `# harness hook:` comment and the `[[hooks.*]]` table that comment belongs to (previously printed `(unknown)` in that shape, because the owned-region scan had already backed the zone start off to only blank or comment lines preceding the found marker, so the pre-marker header lookup found no content line there; it now also looks just past the marker's own line when that happens). Covered for a table wedged after a lone `# harness hook:` comment and for a second hook's comment directly following the first hook's content line. Safety was unaffected in every case (refusal still fires, exit `EX_FAIL`, file left untouched, no secret value ever echoed, now also pinned for this wedged-after-comment shape in the no-echo matrix): only the naming in the message text was wrong. (task `25a4c53f`)
+
+- **The stay-in-scope hook's audit row and reminder now carry the created task id under the real Claude Code MCP `tool_response` shape** (task `b5e65f5e`). `extractTaskId` in `src/cli/pack/hook-stay-in-scope.ts` used to read `tool_response.task.id` and `tool_response.id` as a plain object only, but Claude Code sends MCP `tool_response` as a content-block array (`[{ type: "text", text: "<json>" }]`); the watched tool is a create verb without a `taskId` input, so the audit row's `taskId` was always `null` and the reminder omitted `task=<id>`. It now reuses the shared unwrap already pinned for the active-claim tracker (`taskIdFromToolResponse`, `src/runtime/task-providers/agent-tasks.ts`) instead of a second, plain-object-only parser; the plain-object shape stays supported through the same unwrap. The bare top-level `tool_response.id` fallback (never a real Claude Code or Codex shape) is dropped: only `task.id` is read now. Pinned by a real-shape fixture (`tests/fixtures/pack-hook-stay-in-scope/real-posttooluse-task-create-2.1.280.json`, shaped like the genuine capture `tests/fixtures/track-active-claim/real-posttooluse-task-finish-2.1.280.json`) that fails at the pre-fix implementation and passes at head, asserting both the audit row and the reminder text; `agent-primitives probe --pre 'npm run build'` on the hook's test file kills both reverting to the plain-object-only read and computing the reminder note through that old read alone.
+
+- **Four shipped source comments citing this changelog's now-emptied post-release-cut section pointed at nothing, once the entries they described shipped in 0.49.0** (task `ba7958e1`): `src/cli/policy/intercept.ts`, `src/runtime/kubectl-target-parse.ts`, `src/cli/doctor/types.ts` and `src/cli/validate/checks.ts` now cite the shift-proof `CHANGELOG.md:#0.49.0` anchor instead, matching the convention already used elsewhere (e.g. `src/cli/approve/understanding.ts`). A new `check:shipped-unreleased-pointer` gate (`scripts/check-shipped-unreleased-pointer.mjs`, wired into CI right after Changelog coverage) scans every shipped file (`src/`, README.md, `scripts/runtime-reality-docker-probe.mjs`) for a dangling pointer to that section, unconditionally, so a new one cannot land again; this changelog's own file is excluded from the scan (its history legitimately narrates past states in prose; see the script's own header for the measured false positive that drove that exclusion).
+
+- **`harness apply --runtime codex --install`'s next-steps hint no longer says "Nothing is installed into Codex yet" right after a successful install** (task `dd7a3f23`). `formatNextSteps` (`src/cli/apply/next-steps.ts`) previously decided the Codex lede from `anyChanged` (whether the generated files changed), never from the install outcome itself, so the always-"nothing installed" text survived a real write. The CLI (`src/cli/index.ts`) now passes the `--install` result (`codexConfigInstall.configPath`, `.written`, `.backupPath`) through as a new optional `codexInstall` field on `NextStepsContext`; when present the hint reports what was installed, where, and the backup path on a write, or states the config already has the harness-managed block on a no-op install (config already current), and neither branch claims a write that did not happen. Without `--install` the text is unchanged. Pinned by formatter tests in `tests/cli/apply/next-steps.test.ts` and CLI-level tests in `tests/cli/apply/apply-codex-runtime.test.ts`. Mutation probe (`agent-primitives probe --pre 'npm run build'`) collapsing the install branch back to the plain generated text killed by the new tests.
+
 ## [0.58.1] - 2026-09-23
 
 ### Fixed

package/README.md

@@ -224,7 +224,7 @@ 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.1`.
+The current release is `v0.59.0`.
 
 The phase-by-phase plan with acceptance criteria lives in
 [`docs/ROADMAP.md`](docs/ROADMAP.md); what shipped in each version is

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 };

package/dist/cli/apply/apply.js

@@ -37,7 +37,7 @@ import { unifiedDiff } from "../../io/patch.js";
 import { emitRestartHints } from "../../io/restart-hints.js";
 import { compare } from "../../io/three-state.js";
 import { reportsDirForManifest } from "../../policy-packs/builtin/understanding-before-execution-runtime.js";
-import { checkPolicyPackSources, expandPolicyPacks, DEFAULT_RUNTIME, } from "../../policy-packs/index.js";
+import { checkPolicyPackSources, expandPolicyPacks, DEFAULT_RUNTIME, KNOWN_RUNTIMES, isRuntime, } from "../../policy-packs/index.js";
 import { parseManifest } from "../../schema/index.js";
 import { withDerivedPolicies, withoutDerivedPolicies } from "../../runtime/workflow-policies.js";
 import { checkPolicyGroundingMcp } from "../validate/checks.js";
@@ -57,6 +57,183 @@ export const MEMORY_BASENAME = "MEMORY.md";
 export const MANIFEST_BASENAME = "harness.yaml";
 export const CODEX_CONFIG_BASENAME = "codex/config.toml";
 export const OPENCODE_CONFIG_BASENAME = "opencode/opencode.json";
+/**
+ * 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 function formatRuntimeLine(result) {
+    if (result.runtimeSource === "last-apply") {
+        return `runtime: ${result.runtime} (from last apply; pass --runtime to change)`;
+    }
+    if (result.runtimeSource === "inferred") {
+        return `runtime: ${result.runtime} (inferred from the last apply's generated files; pass --runtime to change)`;
+    }
+    if (result.runtimeSource === "unrecorded") {
+        const candidates = result.runtimeCandidates ?? [];
+        const others = candidates.filter((r) => r !== result.runtime);
+        if (others.length > 0) {
+            const keep = others.length === 1 ? others[0] : "one of them";
+            return `runtime: ${result.runtime} (default; the last apply did not record a runtime and generated files for ${joinRuntimes(candidates)}; pass --runtime ${others.join(" or --runtime ")} to keep ${keep})`;
+        }
+        return `runtime: ${result.runtime} (default; the last apply did not record a runtime, pass --runtime to choose)`;
+    }
+    if (result.runtimeSource === "target") {
+        if (result.previousRuntime !== undefined && result.previousRuntime !== result.runtime) {
+            return `runtime: ${result.previousRuntime} -> ${result.runtime} (--target implies claude-code)`;
+        }
+        return `runtime: ${result.runtime} (implied by --target)`;
+    }
+    if (result.runtimeSource === "explicit" &&
+        result.previousRuntime !== undefined &&
+        result.previousRuntime !== result.runtime) {
+        return `runtime: ${result.previousRuntime} -> ${result.runtime} (switching from the last apply's runtime)`;
+    }
+    return null;
+}
+function joinRuntimes(runtimes) {
+    if (runtimes.length <= 1)
+        return runtimes.join("");
+    return `${runtimes.slice(0, -1).join(", ")} and ${runtimes[runtimes.length - 1]}`;
+}
+const PACK_INSTRUCTIONS_KEY_RE = /^policy-packs\/([^/]+)\/instructions\.md$/;
+// Every builtin pack's instructions.md opens its body with this section and
+// names the runtime it was generated for as the first word, e.g.
+// "## Runtime\n\ncodex" or "## Runtime\n\ncodex (UNSUPPORTED ...)".
+const RUNTIME_SECTION_RE = /^## Runtime\n\n([a-z-]+)/m;
+// The policy packs the last apply generated: the enabled `policy_packs[]`
+// names in the record's own manifest snapshot. `undefined` when the record
+// has no snapshot or it does not parse; the caller then counts every
+// recorded pack entry.
+function snapshotPackNames(record) {
+    const content = record.manifest?.content;
+    if (content === undefined)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch {
+        return undefined;
+    }
+    const packs = parsed?.policy_packs;
+    if (!Array.isArray(packs))
+        return undefined;
+    const names = new Set();
+    for (const pack of packs) {
+        if (pack === null || typeof pack !== "object")
+            continue;
+        const { name, enabled } = pack;
+        if (typeof name === "string" && enabled !== false)
+            names.add(name);
+    }
+    return names;
+}
+// What the recorded policy-pack instructions.md entries name in their
+// `## Runtime` section. With a readable manifest snapshot only the packs
+// it lists count: the map keeps entries of packs a later apply no longer
+// had, and those still name the runtime of an older apply.
+function packInstructionsRuntimes(record) {
+    const listed = snapshotPackNames(record);
+    const named = new Set();
+    let unreadable = false;
+    for (const [key, entry] of Object.entries(record.files)) {
+        const pack = PACK_INSTRUCTIONS_KEY_RE.exec(key)?.[1];
+        if (pack === undefined)
+            continue;
+        if (listed !== undefined && !listed.has(pack))
+            continue;
+        const runtime = RUNTIME_SECTION_RE.exec(entry.content)?.[1];
+        if (isRuntime(runtime))
+            named.add(runtime);
+        else
+            unreadable = true;
+    }
+    return { named, unreadable };
+}
+// The runtime every recorded pack instructions.md entry agrees on, or
+// `undefined` when there is none, one is unreadable, or two disagree.
+function agreedPackRuntime(packs) {
+    if (packs.unreadable || packs.named.size !== 1)
+        return undefined;
+    return [...packs.named][0];
+}
+function soleAdapterRuntime(found) {
+    return found.length === 1 ? found[0] : undefined;
+}
+// A `.last-apply` written before the `runtime` field existed still names
+// the runtime through its files map: each runtime writes its own adapter
+// artefact (`settings.json`, `codex/config.toml`, `opencode/opencode.json`).
+// Exactly one of them present means that runtime. The map keeps entries
+// from earlier applies, so a machine that applied claude-code and later
+// codex carries both adapter artefacts; the recorded policy-pack
+// instructions.md entries then settle it, since each apply rewrites them
+// with the runtime it generated for (only the packs the record's manifest
+// snapshot lists, when it has a readable one). They count only when every
+// entry names the same runtime and that runtime is one of the adapter
+// artefacts' (or there are none); anything else is ambiguous.
+function inferRuntimeFromFiles(record) {
+    const { files } = record;
+    const has = (key) => Object.prototype.hasOwnProperty.call(files, key);
+    const found = [];
+    if (has(SETTINGS_BASENAME))
+        found.push("claude-code");
+    if (has(CODEX_CONFIG_BASENAME))
+        found.push("codex");
+    if (has(OPENCODE_CONFIG_BASENAME))
+        found.push("opencode");
+    const packs = packInstructionsRuntimes(record);
+    const candidates = KNOWN_RUNTIMES.filter((r) => found.includes(r) || packs.named.has(r));
+    const fromAdapter = soleAdapterRuntime(found);
+    if (fromAdapter !== undefined)
+        return { runtime: fromAdapter, candidates };
+    const fromPacks = agreedPackRuntime(packs);
+    if (fromPacks !== undefined && (found.length === 0 || found.includes(fromPacks))) {
+        return { runtime: fromPacks, candidates };
+    }
+    return { candidates };
+}
+// `--runtime` omitted: reuse the runtime the previous apply recorded, so a
+// plain `harness apply` after `harness apply --runtime codex` keeps
+// generating the Codex variant instead of silently switching every
+// runtime-specific file back to the default (agent-tasks b9e6d63c).
+// `--target` wires Claude Code's settings.json, so it implies claude-code
+// instead of reusing another runtime. A record without the field (or with
+// an unknown value) falls back to inferring from its files map, then to
+// the default; the caller names every non-explicit choice in its output.
+function selectRuntime(explicit, lastApply, hasTarget) {
+    const recorded = lastApply?.runtime;
+    const recordedRuntime = isRuntime(recorded) ? recorded : undefined;
+    const inference = recordedRuntime === undefined && lastApply !== null
+        ? inferRuntimeFromFiles(lastApply)
+        : undefined;
+    const inferredRuntime = inference?.runtime;
+    const previousRuntime = recordedRuntime ?? inferredRuntime;
+    const base = previousRuntime !== undefined ? { previousRuntime } : {};
+    if (explicit !== undefined) {
+        return { runtime: explicit, runtimeSource: "explicit", ...base };
+    }
+    if (hasTarget) {
+        return { runtime: "claude-code", runtimeSource: "target", ...base };
+    }
+    if (inferredRuntime !== undefined) {
+        return { runtime: inferredRuntime, runtimeSource: "inferred", ...base };
+    }
+    if (previousRuntime !== undefined) {
+        return { runtime: previousRuntime, runtimeSource: "last-apply", ...base };
+    }
+    if (lastApply !== null) {
+        const runtimeCandidates = inference?.candidates ?? [];
+        if (runtimeCandidates.length > 0) {
+            return { runtime: DEFAULT_RUNTIME, runtimeSource: "unrecorded", runtimeCandidates };
+        }
+        return { runtime: DEFAULT_RUNTIME, runtimeSource: "unrecorded" };
+    }
+    return { runtime: DEFAULT_RUNTIME, runtimeSource: "default" };
+}
 const DRIFT_HINT_MESSAGE = 'run "harness adopt <file>" to capture changes, or re-run with --overwrite-drift to discard them';
 // Pinned to the same literal the Codex generator emits as line 1.
 // Single source of truth lives in generate-codex-config.ts so a future
@@ -110,6 +287,7 @@ function serializeJson(obj) {
 function codexInstallOutcome(result) {
     return {
         configPath: result.configPath,
+        ...(result.linkPath !== undefined ? { linkPath: result.linkPath } : {}),
         changed: result.changed,
         written: "written" in result ? result.written : false,
         summary: result.summary,
@@ -187,8 +365,10 @@ function buildExpectedFiles(manifest, opts, manifestPath, generatedDir) {
     if (runtime === "codex") {
         // Codex apply: emit Codex config artefact instead of settings.json.
         // settings.json is Claude Code's contract and meaningless to Codex.
-        // MEMORY.md and pack instructions.md are runtime-agnostic and ship
-        // unchanged.
+        // MEMORY.md is runtime-agnostic and ships unchanged. Pack
+        // instructions.md ships too, but its content differs per runtime
+        // (builtin packs' buildInstructions() branch on the runtime), which is
+        // why a re-apply under another runtime rewrites it.
         const codexConfig = generateCodexConfig(augmentedManifest);
         const codexWarnings = [...codexConfig.warnings];
         if (packExpansion.permissions) {
@@ -320,7 +500,7 @@ function recoverMissingLastApplyContent(basename, onDisk) {
         return null;
     return onDisk.startsWith(CODEX_GENERATED_HEADER) ? onDisk : null;
 }
-function buildMergedLastApplyRecord(expected, previous, manifest, memoryDirSnapshots) {
+function buildMergedLastApplyRecord(expected, previous, manifest, memoryDirSnapshots, runtime) {
     const next = buildLastApply(Object.fromEntries(expected.map((f) => [f.basename, f.content])));
     if (previous !== null) {
         for (const [relPath, entry] of Object.entries(previous.files)) {
@@ -340,10 +520,13 @@ function buildMergedLastApplyRecord(expected, previous, manifest, memoryDirSnaps
     if (Object.keys(memoryDirSnapshots).length > 0) {
         next.memoryDirs = memoryDirSnapshots;
     }
+    // Absent only for `preserveRecordedRuntime` over a record with no
+    // recorded or inferable runtime: the field then stays absent.
+    if (runtime !== undefined)
+        next.runtime = runtime;
     return next;
 }
 export async function apply(opts = {}) {
-    const runtime = opts.runtime ?? DEFAULT_RUNTIME;
     const manifestPath = resolveManifestPath(opts);
     if (!fs.existsSync(manifestPath)) {
         throw new HarnessExitError(`harness manifest not found at ${manifestPath}; run \`harness init\` first`, EX_NOINPUT);
@@ -388,10 +571,28 @@ export async function apply(opts = {}) {
             `policy, set the workflow's spawn to "optional" or "skip" instead). Run \`harness ` +
             "validate` for the full report.", EX_FAIL);
     }
-    const { files: expected, warnings } = buildExpectedFiles(manifest, opts, manifestPath, generatedDir);
     const lastApply = readLastApply(generatedDir);
+    const runtimeInfo = selectRuntime(opts.runtime, lastApply, Boolean(opts.target));
+    const { runtime } = runtimeInfo;
+    const { files: expected, warnings } = buildExpectedFiles(manifest, { ...opts, runtime }, manifestPath, generatedDir);
+    // The runtime this apply records: its own, or with
+    // `preserveRecordedRuntime` the previous one (recorded or inferred, else
+    // whatever the field held), so a diagnostic apply leaves the operator's
+    // runtime selection alone.
+    const recordRuntime = opts.preserveRecordedRuntime
+        ? (runtimeInfo.previousRuntime ?? lastApply?.runtime)
+        : runtime;
+    // The recorded runtime is missing or differs from the one to record:
+    // persist it on the next .last-apply write even when no generated file
+    // changed, so the next plain apply reuses it.
+    const runtimeRecordStale = lastApply !== null && recordRuntime !== undefined && lastApply.runtime !== recordRuntime;
+    const reusedHint = runtimeInfo.runtimeSource === "last-apply" || runtimeInfo.runtimeSource === "inferred"
+        ? ` (runtime ${runtime} ${runtimeInfo.runtimeSource === "inferred" ? "inferred from the last apply's generated files" : "reused from the last apply"}; pass --runtime codex to change)`
+        : runtimeInfo.runtimeSource === "target"
+            ? " (--target implies claude-code)"
+            : "";
     if (opts.installCodex && runtime !== "codex") {
-        throw new HarnessExitError("--install requires --runtime codex", EX_NOINPUT);
+        throw new HarnessExitError(`--install requires --runtime codex${reusedHint}`, EX_NOINPUT);
     }
     // Asset-content drift detection (Phase 3 #6): if a previous apply wrote
     // harness.lock, re-hash every locked asset / memory-dir Merkle and report
@@ -419,6 +620,7 @@ export async function apply(opts = {}) {
         return {
             manifestPath,
             generatedDir,
+            ...runtimeInfo,
             files: [],
             warnings,
             restartHints: [],
@@ -440,15 +642,16 @@ export async function apply(opts = {}) {
     // Phase 6 #6: --target wires the generated settings.json into a
     // Claude Code path. The runtime=codex branch does not produce
     // settings.json at all, so the combination is incoherent. Reject
-    // early instead of writing a half-broken state.
-    if (targetPath && opts.runtime === "codex") {
+    // early instead of writing a half-broken state. Only an explicit
+    // --runtime reaches this: without one, --target implies claude-code.
+    if (targetPath && runtime === "codex") {
         throw new HarnessExitError("--target is incompatible with --runtime codex (target wires Claude Code's settings.json)", EX_NOINPUT);
     }
     // Batch 18 / task f34eb233: same incoherence for --runtime opencode --
     // see generate-opencode-config.ts's header for why it does not produce
     // settings.json (or write into any operator-owned opencode config at
     // all). Reject symmetrically to the codex branch above.
-    if (targetPath && opts.runtime === "opencode") {
+    if (targetPath && runtime === "opencode") {
         throw new HarnessExitError("--target is incompatible with --runtime opencode (target wires Claude Code's settings.json)", EX_NOINPUT);
     }
     let targetContent;
@@ -519,6 +722,7 @@ export async function apply(opts = {}) {
                 return {
                     manifestPath,
                     generatedDir,
+                    ...runtimeInfo,
                     files: [],
                     warnings,
                     restartHints: [],
@@ -603,6 +807,7 @@ export async function apply(opts = {}) {
         const result = {
             manifestPath,
             generatedDir,
+            ...runtimeInfo,
             files: fileOutcomes,
             warnings,
             restartHints: [],
@@ -637,6 +842,7 @@ export async function apply(opts = {}) {
             const result = {
                 manifestPath,
                 generatedDir,
+                ...runtimeInfo,
                 files: fileOutcomes,
                 warnings,
                 restartHints: [],
@@ -662,6 +868,7 @@ export async function apply(opts = {}) {
         const result = {
             manifestPath,
             generatedDir,
+            ...runtimeInfo,
             files: fileOutcomes,
             warnings,
             restartHints,
@@ -704,11 +911,17 @@ export async function apply(opts = {}) {
                 ...(opts.homeDir !== undefined ? { homeDir: opts.homeDir } : {}),
                 ...(opts.project !== undefined ? { projectName: opts.project } : {}),
             }));
-            writeLastApply(generatedDir, buildMergedLastApplyRecord(expected, lastApply, manifest, refreshedMemoryDirs));
+            writeLastApply(generatedDir, buildMergedLastApplyRecord(expected, lastApply, manifest, refreshedMemoryDirs, recordRuntime));
+        }
+        else if (runtimeRecordStale) {
+            // Nothing else to refresh: only stamp the runtime so the next plain
+            // apply reuses it.
+            writeLastApply(generatedDir, { ...lastApply, runtime: recordRuntime });
         }
         const result = {
             manifestPath,
             generatedDir,
+            ...runtimeInfo,
             files: fileOutcomes,
             warnings,
             restartHints,
@@ -772,14 +985,15 @@ export async function apply(opts = {}) {
         codexInstallResult = { ...codexInstallPlan, written: false };
     }
     const lockEntriesWithTarget = appendTargetEntry(lockEntries, targetPath, targetContent, previousLock);
-    if (anyChanged || recoveredMissingLastApply) {
+    if (anyChanged || recoveredMissingLastApply || runtimeRecordStale) {
         const memoryDirSnapshots = collectMemoryDirSnapshots(lockEntries);
-        writeLastApply(generatedDir, buildMergedLastApplyRecord(expected, lastApply, manifest, memoryDirSnapshots));
+        writeLastApply(generatedDir, buildMergedLastApplyRecord(expected, lastApply, manifest, memoryDirSnapshots, recordRuntime));
     }
     writeLock(lockPath, lockEntriesWithTarget);
     const result = {
         manifestPath,
         generatedDir,
+        ...runtimeInfo,
         files: fileOutcomes,
         warnings,
         restartHints,