akm-cli 0.9.0-rc.1 → 0.9.0-rc.13

package/dist/integrations/harnesses/openhands/agent-builder.js

@@ -56,27 +56,29 @@
  *   dropped rather than approximated — never silently widened.
  * - **resume/session** — NOT expressible: per the matrix OpenHands resumes
  *   from *workspace state*, not a session-id flag, so there is no flag-shaped
- *   `HarnessResumeSupport` to export. The extractor still captures a
+ *   resume to describe. The extractor still captures a
  *   conversation/session id opportunistically when the stream reveals one;
  *   akm's `workflow_run_units` remains the durable source of truth either way
  *   (plan §"Session, MCP, and identity across harnesses").
  * - **effort** — stays unconsumed (reserved; the shared request contract's
  *   "no builder consumes it yet" note stays true).
  *
- * NOT registered anywhere: `builders.ts` / `harnesses/index.ts` wiring is a
- * follow-up integration task (as is the registry entry declaring
- * `pattern: "local-runner"`, `structuredOutput: "native-json"`, and no
- * `resume`). Exported standalone so that task only adds a registry entry.
+ * Registered: `openhandsBuilder` is `OpenhandsHarness.agentBuilder`
+ * (`./index.ts`), one of the ten harnesses `HARNESS_REGISTRY` constructs
+ * (`harnesses/index.ts`); `agent/builders.ts` derives `BUILTIN_BUILDERS` from
+ * that registry, so this builder is reachable under the `"openhands"`
+ * platform name without any further wiring. The registry entry also declares
+ * `pattern: "local-runner"`, `structuredOutput: "native-json"` alongside it
+ * (`./index.ts`).
  */
-import { assertNotFlag } from "../../agent/builder-shared.js";
-import { resolveModel } from "../../agent/model-aliases.js";
+import { assertNotFlag, resolveDispatchModel, } from "../../agent/builder-shared.js";
 /** Canonical harness/platform id used for model-alias resolution. */
 export const OPENHANDS_PLATFORM = "openhands";
 /**
  * Env var OpenHands reads its LLM model from — the platform's documented
  * model-selection channel for headless runs (there is no headless model
- * flag). Exported so the follow-up integration task and tests share the one
- * constant.
+ * flag). Exported (re-exported from `./index.ts`) so this harness's tests
+ * share the one constant.
  */
 export const OPENHANDS_MODEL_ENV = "LLM_MODEL";
 /**
@@ -117,7 +119,7 @@ export const openhandsBuilder = {
         args.push(`--task=${buildTaskPayload(req)}`);
         let env;
         if (req.model) {
-            const resolved = resolveModel(req.model, OPENHANDS_PLATFORM, profile.modelAliases, profile.globalModelAliases);
+            const resolved = resolveDispatchModel(req, profile, OPENHANDS_PLATFORM);
             // Model travels via env, not argv — OpenHands' documented channel.
             env = { [OPENHANDS_MODEL_ENV]: resolved };
         }

package/dist/integrations/harnesses/openhands/index.js

@@ -12,22 +12,12 @@
  * that `HARNESS_REGISTRY` registers. Dispatch-only: no native session-log
  * reader or config importer yet.
  */
+import { caps } from "../shared.js";
 import { BaseHarness } from "../types.js";
 import { openhandsBuilder } from "./agent-builder.js";
 import { openhandsResultExtractor } from "./result-extractor.js";
 export { OPENHANDS_MODEL_ENV, OPENHANDS_PLATFORM, openhandsBuilder } from "./agent-builder.js";
 export { openhandsResultExtractor } from "./result-extractor.js";
-function caps(c) {
-    return {
-        sessionLogs: false,
-        agentDispatch: false,
-        detection: false,
-        configImport: false,
-        runtimeIdentity: false,
-        v1Migration: false,
-        ...c,
-    };
-}
 /**
  * OpenHands CLI.
  *
@@ -45,7 +35,7 @@ export class OpenhandsHarness extends BaseHarness {
     // `--json` emits a documented JSONL event stream akm parses, then validates
     // against the node schema ⇒ native-json tier.
     structuredOutput = "native-json";
-    // No `resume`: per the matrix OpenHands resumes from workspace state, not a
+    // No flag-shaped resume: per the matrix OpenHands resumes from workspace state, not a
     // session-id flag. The extractor still captures a conversation id
     // opportunistically; akm's `workflow_run_units` remains the durable source
     // of truth.

package/dist/integrations/harnesses/pi/agent-builder.js

@@ -12,9 +12,9 @@
  *   pi -p "<prompt>"
  *
  * with `--mode json` for structured (JSONL) output, `--model <m>` for model
- * selection, and `-c`/`-r`/`--session <id>` for resume. Resume is
- * registry-side (`AkmHarness.resume`, flag-shaped: {@link PI_RESUME_FLAG}) —
- * not built here because `AgentDispatchRequest` carries no session id.
+ * selection, and `-c`/`-r`/`--session <id>` for resume — not built here
+ * because `AgentDispatchRequest` carries no session id (akm's
+ * `workflow_run_units` is the durable resume source of truth).
  *
  * Platform-specific mapping decisions (all localized here, per the adapter
  * contract):
@@ -43,23 +43,16 @@
  * - **effort** — stays unconsumed (reserved; the shared request contract's
  *   "no builder consumes it yet" note stays true).
  *
- * NOT registered anywhere: `builders.ts` / `harnesses/index.ts` wiring is a
- * follow-up integration task (as are the `PI_*` identity-env markers, which
- * are registry-side). Exported standalone so that task only adds a registry
- * entry.
+ * Registered: `piBuilder` is `PiHarness.agentBuilder` (`./index.ts`), one of
+ * the ten harnesses `HARNESS_REGISTRY` constructs (`harnesses/index.ts`);
+ * `agent/builders.ts` derives `BUILTIN_BUILDERS` from that registry, so this
+ * builder is reachable under the `"pi"` platform name without any further
+ * wiring. The `PI_SESSION_ID` identity-env marker is declared alongside it
+ * (`./index.ts`).
  */
-import { assertNotFlag } from "../../agent/builder-shared.js";
-import { resolveModel } from "../../agent/model-aliases.js";
+import { assertNotFlag, resolveDispatchModel, } from "../../agent/builder-shared.js";
 /** Canonical harness/platform id used for model-alias resolution. */
 export const PI_PLATFORM = "pi";
-/**
- * Flag-shaped resume support per the capability matrix (`--session <id>`).
- * Exported for the integration task's `AkmHarness.resume` registry entry; the
- * harness-native session id comes from the unit row (stored opportunistically
- * by the result extractor) — akm never depends on it (plan §"Session, MCP,
- * and identity across harnesses").
- */
-export const PI_RESUME_FLAG = "--session";
 /**
  * Assemble the positional prompt payload: the task prompt and — when a schema
  * is requested — the same schema directive the workflow engine's prompt
@@ -87,7 +80,7 @@ export const piBuilder = {
             args.push("--system-prompt", req.systemPrompt);
         }
         if (req.model) {
-            const resolved = resolveModel(req.model, PI_PLATFORM, profile.modelAliases, profile.globalModelAliases);
+            const resolved = resolveDispatchModel(req, profile, PI_PLATFORM);
             args.push("--model", resolved);
         }
         if (req.schema) {

package/dist/integrations/harnesses/pi/index.js

@@ -12,22 +12,12 @@
  * `HARNESS_REGISTRY` registers. Dispatch-only: no native session-log reader or
  * config importer yet.
  */
+import { caps } from "../shared.js";
 import { BaseHarness } from "../types.js";
-import { PI_RESUME_FLAG, piBuilder } from "./agent-builder.js";
+import { piBuilder } from "./agent-builder.js";
 import { piResultExtractor } from "./result-extractor.js";
-export { PI_PLATFORM, PI_RESUME_FLAG, piBuilder } from "./agent-builder.js";
+export { PI_PLATFORM, piBuilder } from "./agent-builder.js";
 export { piResultExtractor } from "./result-extractor.js";
-function caps(c) {
-    return {
-        sessionLogs: false,
-        agentDispatch: false,
-        detection: false,
-        configImport: false,
-        runtimeIdentity: false,
-        v1Migration: false,
-        ...c,
-    };
-}
 /**
  * Pi coding-agent CLI.
  *
@@ -45,9 +35,6 @@ export class PiHarness extends BaseHarness {
     // `--mode json` emits a documented JSONL event stream akm parses, then
     // validates against the node schema ⇒ native-json tier.
     structuredOutput = "native-json";
-    // `pi --session <id>` replays a previous session (the matrix's -c/-r/
-    // --session family; the id-taking long form is the registered flag).
-    resume = { flag: PI_RESUME_FLAG, takesSessionId: true };
     // Session-id env marker only — the matrix's bare PI_* presence vars must
     // not stamp identity onto manual runs (see `AkmHarness.identityEnv`).
     identityEnv = ["PI_SESSION_ID"];

package/dist/integrations/harnesses/shared.js

@@ -0,0 +1,17 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+export function caps(c) {
+    return {
+        sessionLogs: false,
+        agentDispatch: false,
+        detection: false,
+        configImport: false,
+        runtimeIdentity: false,
+        ...c,
+    };
+}
+/** Home directory used for filesystem-only harness config detection. */
+export function homeDir() {
+    return process.env.HOME ?? process.env.USERPROFILE ?? "";
+}

package/dist/integrations/harnesses/types.js

@@ -1,14 +1,47 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Type-guard narrowing a harness to {@link SessionLogCapableHarness}.
+ *
+ * `Array.prototype.filter`'s type-predicate overload requires the predicate's
+ * inferred type to extend the array's element type — a plain
+ * `(h: AkmHarness) => h is SessionLogCapableHarness` predicate fails that
+ * constraint against `HARNESS_REGISTRY`'s element type (the union of the ten
+ * concrete harness classes, each with literal `id`s narrower than
+ * `SessionLogCapableHarness`'s `id: string`), so `.filter` would silently fall
+ * back to its non-narrowing overload. Generic over the input `H` and
+ * intersecting it into the predicate (`H & SessionLogCapableHarness`) keeps
+ * the result always a subtype of `H`, so the constraint holds regardless of
+ * what concrete harness type(s) `H` resolves to — this is what lets
+ * `HARNESS_REGISTRY.filter(isSessionLogHarness)` (in `./index.ts`) actually
+ * narrow to a type where `sessionLogProvider` is known-present, retiring the
+ * load-time throw that used to guard this in `session-logs/index.ts`.
+ */
+export function isSessionLogHarness(h) {
+    return h.capabilities.sessionLogs;
+}
 /**
  * Shared base for harness descriptors (#566).
  *
- * Provides the default v1-profile-name matcher so the inference logic lives in
- * ONE place instead of being duplicated across the old `guessAgentPlatform()`
- * (config-migration) and the `name.includes("claude")` heuristic (setup). A
- * concrete harness sets `id`/`aliases`/`capabilities` and, when its v1 profile
- * names could be decorated (e.g. `"opencode-sdk-fast"`), `v1ProfilePrefixes`.
+ * Provides shared optional descriptor fields for concrete harnesses.
+ *
+ * Deliberately implements {@link AkmHarnessCommon}, NOT the discriminated
+ * `AkmHarness` union (WI-9.7, H1): `AkmHarnessCommon` excludes `capabilities`
+ * and `sessionLogProvider`, the two fields whose pairing the union enforces.
+ * A base class shared by both branches cannot itself satisfy either specific
+ * union member — `capabilities` stays declared `abstract` at the (widened)
+ * `HarnessCapabilities` union type here, and each subclass narrows it to a
+ * literal `sessionLogs: true`/`false` variant via `caps({...})`.
+ * `sessionLogProvider` is intentionally NOT declared here at all (not even
+ * optional): the 8 non-session-log subclasses simply never declare it, which
+ * satisfies `NonSessionLogHarness`'s `sessionLogProvider?: undefined` (an
+ * absent optional property satisfies an `undefined`-typed optional); had this
+ * class declared it as `sessionLogProvider?: () => SessionLogHarness`
+ * instead, every non-session-log subclass would inherit that (function |
+ * undefined) type and fail to satisfy `NonSessionLogHarness` at the
+ * `HARNESS_REGISTRY` `satisfies` check. The two session-log subclasses
+ * (Claude, OpenCode) declare their own required `sessionLogProvider`.
  */
 export class BaseHarness {
     runtimeId;
@@ -16,36 +49,7 @@ export class BaseHarness {
     agentBuilder;
     pattern;
     structuredOutput;
-    resume;
     identityEnv;
     presenceEnv;
     resultExtractor;
-    sessionLogProvider;
-    /**
-     * Lowercase prefixes that a decorated v1 profile name may start with and
-     * still belong to this harness (e.g. `["opencode-sdk"]`). The canonical id
-     * and aliases are always matched in addition to these; an empty list means
-     * only exact id/alias matches.
-     */
-    v1ProfilePrefixes = [];
-    matchesV1ProfileName(name) {
-        // Only harnesses with a v1→v2 mapping participate; others never claim a
-        // legacy profile name (so unknown names are dropped, not misclassified).
-        if (!this.capabilities.v1Migration)
-            return false;
-        const lower = name.trim().toLowerCase();
-        if (!lower)
-            return false;
-        if (lower === this.id.toLowerCase())
-            return true;
-        for (const alias of this.aliases) {
-            if (lower === alias.toLowerCase())
-                return true;
-        }
-        for (const prefix of this.v1ProfilePrefixes) {
-            if (lower.startsWith(prefix.toLowerCase()))
-                return true;
-        }
-        return false;
-    }
 }

package/dist/integrations/lockfile.js

@@ -4,8 +4,9 @@
 import fs from "node:fs";
 import path from "node:path";
 import { writeFileAtomic } from "../core/common.js";
-import { rethrowIfTestIsolationError } from "../core/errors.js";
-import { probeLock, releaseLock, tryAcquireLockSync } from "../core/file-lock.js";
+import { ConfigError, rethrowIfTestIsolationError } from "../core/errors.js";
+import { createLockPayload, probeLock, reclaimStaleLock, releaseLock, tryAcquireLockSync } from "../core/file-lock.js";
+import { acquireMaintenanceBarrier } from "../core/maintenance-barrier.js";
 import { getDataDir, getLockfileLockPath, getLockfilePath } from "../core/paths.js";
 // ── Lock sentinel ────────────────────────────────────────────────────────────
 const LOCK_MAX_RETRIES = 3;
@@ -15,23 +16,26 @@ async function acquireLockSentinel() {
     // Ensure the directory exists before attempting to create the sentinel.
     fs.mkdirSync(path.dirname(sentinelPath), { recursive: true });
     for (let attempt = 0; attempt < LOCK_MAX_RETRIES; attempt++) {
-        if (tryAcquireLockSync(sentinelPath, String(process.pid))) {
-            return true; // Sentinel created — we own the lock.
+        const releaseBarrier = acquireMaintenanceBarrier();
+        try {
+            const ownership = tryAcquireLockSync(sentinelPath, createLockPayload());
+            if (ownership) {
+                return () => releaseLock(ownership);
+            }
+            const probe = probeLock(sentinelPath);
+            if (probe.state === "stale" && reclaimStaleLock(sentinelPath, probe)) {
+                continue; // Reclaimed — retry immediately.
+            }
         }
-        if (probeLock(sentinelPath).state === "stale") {
-            releaseLock(sentinelPath);
-            continue; // Reclaimed — retry immediately.
+        finally {
+            releaseBarrier();
         }
         // Another process holds the lock — wait briefly before retrying.
         if (attempt < LOCK_MAX_RETRIES - 1) {
             await new Promise((resolve) => setTimeout(resolve, LOCK_RETRY_DELAY_MS));
         }
     }
-    // Best-effort: proceed without the lock rather than failing the install.
-    return false;
-}
-function releaseLockSentinel() {
-    releaseLock(getLockfileLockPath());
+    throw new ConfigError(`Could not acquire lockfile sentinel at ${sentinelPath}; refusing to write without exclusive ownership.`, "INVALID_CONFIG_FILE");
 }
 // ── Read / Write ────────────────────────────────────────────────────────────
 export function readLockfile() {
@@ -50,40 +54,223 @@ export function readLockfile() {
         return [];
     }
 }
-export function writeLockfile(entries) {
+/**
+ * Like {@link readLockfile}, but THROWS instead of silently degrading to `[]`
+ * when the on-disk lockfile exists yet is not parseable JSON or not a JSON
+ * array (R-012).
+ *
+ * `readLockfile`'s fail-open contract is intentional for READ paths — a
+ * corrupt lock degrades a managed bundle to "unmanaged" rather than erroring
+ * every read-only command (`list`, `installed-stashes`, …). But
+ * {@link upsertLockEntry} and {@link removeLockEntry} read the current
+ * entries and then WRITE `[...entries, change]` back out; if that read
+ * silently returned `[]` for a corrupt file, the write would silently
+ * replace the corrupt file with one containing only the single new/changed
+ * entry — permanently destroying every other surviving lock record. Write
+ * paths use this strict variant so a corrupt lockfile fails the operation
+ * loudly (matching the guard `mergeLockEntriesSync` already applies) instead
+ * of quietly deleting user state. A missing file is NOT corruption — there
+ * is nothing to preserve, so that case still returns `[]`. Entries that fail
+ * per-entry validation are still tolerated (filtered out), matching
+ * `readLockfile`'s existing shape-tolerant behavior.
+ */
+function readLockfileOrThrow() {
+    const lockfilePath = getLockfilePath();
+    let raw;
+    try {
+        raw = fs.readFileSync(lockfilePath, "utf8");
+    }
+    catch (err) {
+        rethrowIfTestIsolationError(err);
+        return []; // File does not exist (or is otherwise unreadable) — nothing to preserve.
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new ConfigError(`Refusing to modify lockfile ${lockfilePath}: existing content is not valid JSON (${error instanceof Error ? error.message : String(error)}). Fix or remove the file by hand before retrying — every existing lock entry would otherwise be lost.`, "INVALID_CONFIG_FILE");
+    }
+    if (!Array.isArray(parsed)) {
+        throw new ConfigError(`Refusing to modify lockfile ${lockfilePath}: existing content is not a JSON array. Fix or remove the file by hand before retrying — every existing lock entry would otherwise be lost.`, "INVALID_CONFIG_FILE");
+    }
+    return parsed.filter(isValidLockfileEntry);
+}
+/**
+ * The materialized content root recorded in the lock for a managed (git/npm)
+ * bundle — spec §10.2 desired/resolved split, where the desired config carries
+ * only the source LOCATOR and the resolved `localRoot` lives here.
+ *
+ * This is the SINGLE lock-first resolution point shared by the indexer READ
+ * path (`resolveEntryContentDir` in indexer/search) and the command-layer WRITE
+ * path (`adaptConfiguredSource` in core/write-source): consulting it first makes
+ * a write land in exactly the directory a read walks. Returns `undefined` for a
+ * bundle with no lock `localRoot` (e.g. a config migrated from a `sources[]`
+ * url, whose provider re-derives the cache path) or a non-managed type, so both
+ * callers fall back to the identical provider-path derivation.
+ */
+export function lockContentRootFor(bundleId, type) {
+    if (!bundleId || (type !== "git" && type !== "npm"))
+        return undefined;
+    for (const lock of readLockfile()) {
+        if (lock.id === bundleId && typeof lock.localRoot === "string" && lock.localRoot.length > 0) {
+            return lock.localRoot;
+        }
+    }
+    return undefined;
+}
+function writeLockfileUnlocked(entries) {
     // Always write to $DATA — never to the legacy $CONFIG location.
     const lockfilePath = getLockfilePath();
     const dir = path.dirname(lockfilePath);
     fs.mkdirSync(dir, { recursive: true });
     writeFileAtomic(lockfilePath, `${JSON.stringify(entries, null, 2)}\n`);
 }
+export async function writeLockfile(entries) {
+    const release = await acquireLockSentinel();
+    try {
+        writeLockfileUnlocked(entries);
+    }
+    finally {
+        release();
+    }
+}
+/** Replace one exact parsed lock generation while the lockfile sentinel is held. */
+export async function compareAndSwapLockfile(expected, desired) {
+    const release = await acquireLockSentinel();
+    try {
+        const current = readLockfileOrThrow();
+        if (JSON.stringify(current) !== JSON.stringify(expected))
+            return false;
+        writeLockfileUnlocked(desired);
+        return true;
+    }
+    finally {
+        release();
+    }
+}
 export async function upsertLockEntry(entry) {
-    const acquired = await acquireLockSentinel();
+    const release = await acquireLockSentinel();
     try {
-        const entries = readLockfile();
+        // R-012: readLockfileOrThrow (not readLockfile) — a corrupt/malformed
+        // lockfile must abort the upsert loudly rather than read as `[]` and get
+        // silently overwritten with just this one entry.
+        const entries = readLockfileOrThrow();
         const withoutExisting = entries.filter((e) => e.id !== entry.id);
-        writeLockfile([...withoutExisting, entry]);
+        writeLockfileUnlocked([...withoutExisting, entry]);
     }
     finally {
-        if (acquired)
-            releaseLockSentinel();
+        release();
     }
 }
+/**
+ * Synchronously upsert lock entries (merge by id) WITHOUT acquiring the async
+ * sentinel — for a caller already holding an exclusive lifecycle lock (e.g.
+ * migrate-apply's config lock + maintenance barrier) whose synchronous body
+ * cannot await the sentinel's retry loop. No-op for an empty list.
+ */
+export function mergeLockEntriesSync(entries) {
+    if (entries.length === 0)
+        return;
+    let existing = [];
+    const lockfilePath = getLockfilePath();
+    if (fs.existsSync(lockfilePath)) {
+        let raw;
+        try {
+            raw = JSON.parse(fs.readFileSync(lockfilePath, "utf8"));
+        }
+        catch (error) {
+            throw new ConfigError(`Cannot merge migration lock entries into unreadable lockfile ${lockfilePath}: ${error instanceof Error ? error.message : String(error)}.`, "INVALID_CONFIG_FILE");
+        }
+        if (!Array.isArray(raw) || !raw.every(isValidLockfileEntry)) {
+            throw new ConfigError(`Cannot merge migration lock entries into malformed lockfile ${lockfilePath}.`, "INVALID_CONFIG_FILE");
+        }
+        existing = raw;
+    }
+    // MERGE per id, never replace: the migrator's entries are sparse (id/source/
+    // ref/localRoot), while an existing row may carry `resolvedVersion`,
+    // `resolvedRevision`, `integrity`, `installedAt`, … from a real install.
+    // Replacing the whole row discarded the user's recorded resolution/pin and
+    // left later update reporting comparing against an unknown prior version.
+    // Incoming DEFINED fields win; existing fields absent from the incoming
+    // entry are preserved.
+    const byId = new Map(existing.map((e) => [e.id, e]));
+    const merged = entries.map((incoming) => {
+        const prior = byId.get(incoming.id);
+        return prior ? { ...prior, ...incoming } : incoming;
+    });
+    const incomingIds = new Set(entries.map((e) => e.id));
+    writeLockfileUnlocked([...existing.filter((e) => !incomingIds.has(e.id)), ...merged]);
+}
+/** Freeze exact old/desired lockfile bytes while the migration lifecycle lock is held. */
+export function planLockMergeSync(entries) {
+    const lockfilePath = getLockfilePath();
+    let oldBytes = null;
+    let existing = [];
+    try {
+        oldBytes = fs.readFileSync(lockfilePath, "utf8");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    if (oldBytes !== null) {
+        let parsed;
+        try {
+            parsed = JSON.parse(oldBytes);
+        }
+        catch (error) {
+            throw new ConfigError(`Cannot plan migration lock entries from unreadable lockfile ${lockfilePath}: ${error instanceof Error ? error.message : String(error)}.`, "INVALID_CONFIG_FILE");
+        }
+        if (!Array.isArray(parsed) || !parsed.every(isValidLockfileEntry)) {
+            throw new ConfigError(`Cannot plan migration lock entries from malformed lockfile ${lockfilePath}.`, "INVALID_CONFIG_FILE");
+        }
+        existing = parsed;
+    }
+    if (entries.length === 0)
+        return { oldBytes, desiredBytes: oldBytes };
+    const byId = new Map(existing.map((entry) => [entry.id, entry]));
+    for (const entry of entries)
+        byId.set(entry.id, { ...byId.get(entry.id), ...entry });
+    return { oldBytes, desiredBytes: `${JSON.stringify([...byId.values()], null, 2)}\n` };
+}
+/** Publish a frozen migration lock generation, accepting only exact old or exact desired bytes. */
+export function publishPlannedLockMergeSync(plan) {
+    const lockfilePath = getLockfilePath();
+    let current = null;
+    try {
+        current = fs.readFileSync(lockfilePath, "utf8");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    if (current === plan.desiredBytes)
+        return;
+    if (current !== plan.oldBytes) {
+        throw new ConfigError(`Refusing migration lockfile publication because ${lockfilePath} is a third generation, neither the journaled old nor desired bytes.`, "INVALID_CONFIG_FILE");
+    }
+    if (plan.desiredBytes === null)
+        return;
+    fs.mkdirSync(path.dirname(lockfilePath), { recursive: true });
+    writeFileAtomic(lockfilePath, plan.desiredBytes, 0o600);
+}
 export async function removeLockEntry(id) {
     if (!fs.existsSync(getDataDir()))
         return;
-    const acquired = await acquireLockSentinel();
+    const release = await acquireLockSentinel();
     try {
-        const entries = readLockfile();
-        writeLockfile(entries.filter((e) => e.id !== id));
+        // R-012: see upsertLockEntry — same destructive-overwrite risk on a
+        // corrupt lockfile, so the same strict reader is used here.
+        const entries = readLockfileOrThrow();
+        writeLockfileUnlocked(entries.filter((e) => e.id !== id));
     }
     finally {
-        if (acquired)
-            releaseLockSentinel();
+        release();
     }
 }
 // ── Helpers ─────────────────────────────────────────────────────────────────
-function isValidLockfileEntry(value) {
+export function isValidLockfileEntry(value) {
     if (typeof value !== "object" || value === null || Array.isArray(value))
         return false;
     const obj = value;