@botiverse/k-carrier 0.1.0

package/core/src/status/reportStore.ts

@@ -0,0 +1,67 @@
+/**
+ * Report store — the LAST convergence report, persisted across restarts
+ * (M6, L5; a machine that DID converge must not report
+ * NOT_OBSERVED after a restart, AND an unreadable report must not be
+ * reported as "never observed" — the provenance three-state lesson applies
+ * here too: "I cannot read it" is not "it never happened").
+ *
+ * Three states, mechanically distinct:
+ *  - genesis: no report file — the machine never promoted. NOT_OBSERVED.
+ *  - observed: a valid, version-stamped report from the last promote.
+ *  - unreadable: the file exists but cannot be read (EACCES/EISDIR/EIO) or
+ *    is corrupt. The machine DID observe something; its record is hidden,
+ *    not absent.
+ *
+ * persistReport is durable BEFORE visible (write tmp, fsync, then rename —
+ * same promise as the provenance append): a rename alone guarantees
+ * atomic visibility, not that the bytes survived a power cut.
+ */
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import type { ConvergenceReport } from "../converge/predicates.ts";
+import { platformOpsFor } from "../platform/index.ts";
+
+const REPORT_FILE = "report.json";
+
+export type ReportRead =
+  | { kind: "genesis" }
+  | { kind: "observed"; report: ConvergenceReport }
+  | { kind: "unreadable"; reason: string };
+
+export async function persistReport(stateDir: string, report: ConvergenceReport): Promise<void> {
+  await fs.mkdir(stateDir, { recursive: true });
+  const target = path.join(stateDir, REPORT_FILE);
+  const tmp = `${target}.tmp`;
+  const fh = await fs.open(tmp, "w");
+  try {
+    await fh.writeFile(JSON.stringify(report));
+    await fh.sync(); // durable BEFORE the rename makes it visible
+  } finally {
+    await fh.close();
+  }
+  await platformOpsFor().renamePath(tmp, target);
+}
+
+export async function loadLastReport(stateDir: string): Promise<ReportRead> {
+  let text: string;
+  try {
+    text = await fs.readFile(path.join(stateDir, REPORT_FILE), "utf8");
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") return { kind: "genesis" };
+    return {
+      kind: "unreadable",
+      reason: `cannot read ${REPORT_FILE} (${code ?? (err as Error).message}); unreadable is NOT never-observed`,
+    };
+  }
+  try {
+    const parsed = JSON.parse(text) as ConvergenceReport;
+    if (typeof parsed.version !== "string") throw new Error("report carries no version stamp");
+    if (!parsed.binaryAtTarget || typeof parsed.binaryAtTarget.passed !== "boolean") {
+      throw new Error("report carries no binaryAtTarget");
+    }
+    return { kind: "observed", report: parsed };
+  } catch (err) {
+    return { kind: "unreadable", reason: `corrupt ${REPORT_FILE}: ${(err as Error).message}` };
+  }
+}

package/core/src/txn/effects.ts

@@ -0,0 +1,40 @@
+/**
+ * Effects — the txn engine's ONLY doorway to the world (sim-first
+ * constraint, harness-design §1.45).
+ *
+ * The engine is a pure state machine: no direct IO, time, or randomness.
+ * Everything durable goes through these interfaces. Production wires them
+ * to the real filesystem/platform adapters; the simulator wires them to an
+ * in-memory disk with seeded fault injection. This is a product-grade
+ * abstraction (platform adapters differ in fsync/swap semantics anyway),
+ * not a test seam.
+ *
+ * Durability contract: appendAndSync resolves only after the entry is
+ * durable (fsync'd). The engine writes intent BEFORE acting (WAL); recovery
+ * trusts the journal, never directory listings or guesses.
+ */
+import type { JournalEntry } from "./state.ts";
+import type { Slot } from "../lifecycle/hostAdapter.ts";
+
+export interface JournalStore {
+  /** Append one entry durably. Resolves only after fsync. */
+  appendAndSync(entry: JournalEntry): Promise<void>;
+  /** All entries in append order (crash-truncated tails already dropped). */
+  readAll(): Promise<JournalEntry[]>;
+}
+
+export interface SlotStore {
+  /** Populate the experiment slot with a verified artifact (atomic: visible fully or not at all). */
+  stageExperiment(artifact: { version: string; bytesRef: string }): Promise<void>;
+  /** Which version each slot holds; null = empty. */
+  slotVersions(): Promise<Record<Slot, string | null>>;
+  /** experiment -> stable, old stable dropped. Atomic. */
+  promoteExperiment(): Promise<void>;
+  /** Drop the experiment slot. Atomic, idempotent. */
+  clearExperiment(): Promise<void>;
+}
+
+export interface TxnEffects {
+  journal: JournalStore;
+  slots: SlotStore;
+}

package/core/src/txn/engine.ts

@@ -0,0 +1,275 @@
+/**
+ * Upgrade transaction engine — pure state machine over TxnEffects +
+ * HostAdapter (sim-first: zero direct IO/time/randomness; see effects.ts).
+ *
+ * Invariants (each is a harness tooth):
+ *  - WAL: intent is journaled+fsync'd BEFORE the action it names.
+ *  - Crash anywhere -> recover() lands on stable-running or completes the
+ *    transition, decided by journal replay. Never dual-run, never bricked.
+ *  - Promote only after the caller-supplied predicate evaluation passed.
+ *  - Rollback is always available until promote; its reason is journaled.
+ */
+import type { HostAdapter, ProcessEvidence } from "../lifecycle/hostAdapter.ts";
+import type { TxnEffects } from "./effects.ts";
+import type { JournalEntry, TxnPhase } from "./state.ts";
+import { STATE_FORMAT_VERSION } from "./state.ts";
+import type { Clock } from "../clock.ts";
+import { HostCallTimeout, DEFAULT_HOST_CALL_BUDGET_MS } from "./hostCallBudget.ts";
+
+
+export interface EngineDeps {
+  effects: TxnEffects;
+  host: HostAdapter;
+  clock: Clock;
+  /**
+   * Evaluate convergence for the freshly started experiment process.
+   * Returns null when converged; otherwise a human-readable refusal that
+   * becomes the rollback reason. (Full ConvergenceReport wiring lands with
+   * converge/; the engine only cares about pass/fail + reason.)
+   */
+  evaluatePredicates: (evidence: ProcessEvidence, targetVersion: string) => Promise<string | null>;
+  /**
+   * Budget for a single host call (quiesce/stop/start/probe).
+   *
+   * A host that HANGS is worse than one that crashes: nothing is journaled,
+   * the lock stays held by a process that is still alive (so stale-lock
+   * takeover does not apply), and every later attempt queues behind it
+   * forever. That is the "wedged half-way" failure, and it is the one an
+   * updater is least able to explain afterwards.
+   *
+   * Default 120s: long enough for a real service to drain sessions on a busy
+   * machine, short enough that a wedge is reported the same day it happens.
+   */
+  hostCallBudgetMs?: number;
+}
+
+export type EngineOutcome =
+  | { result: "promoted"; version: string }
+  | { result: "rolled-back"; reason: string }
+  | { result: "up-to-date" };
+
+export class UpgradeEngine {
+  private readonly deps: EngineDeps;
+  private seq = 0;
+
+  constructor(deps: EngineDeps) {
+    this.deps = deps;
+  }
+
+  private async journal(intent: TxnPhase, detail: Record<string, string> = {}): Promise<void> {
+    const entry: JournalEntry = {
+      seq: this.seq++,
+      timestampMs: this.deps.clock.nowMs(),
+      intent,
+      detail: { ...detail, formatVersion: String(STATE_FORMAT_VERSION) },
+    };
+    await this.deps.effects.journal.appendAndSync(entry);
+  }
+
+  /**
+   * Replay the journal and finish or undo whatever was in flight.
+   * Must be called before upgrade() on every process start.
+   */
+  async recover(): Promise<void> {
+    const entries = await this.deps.effects.journal.readAll();
+    const last = entries.at(-1);
+    this.seq = (last?.seq ?? -1) + 1;
+    if (!last) return; // fresh install, stable running
+
+    const version = (await this.deps.effects.slots.slotVersions()).experiment;
+    switch (last.intent) {
+      case "idle":
+        return;
+      case "promoted":
+        // WAL redo: the intent is durable but its action may not have run
+        // (crash in the after-journal window). Completing it is idempotent —
+        // promoteExperiment on an already-promoted world is a no-op because
+        // the experiment slot is empty.
+        await this.deps.effects.slots.promoteExperiment();
+        // resume is part of the terminal action too. A crash after promote()
+        // but before resume() used to leave the service alive and its hosted
+        // work permanently parked; DST found this exact effect boundary.
+        await this.deps.host.resume();
+        return;
+      case "rolled-back":
+        // The terminal journal entry is WAL intent, not proof that the host
+        // restore ran. Redo the whole idempotent rollback action: a crash
+        // immediately after journaling `rolled-back` may still have the
+        // experiment process live and workloads parked.
+        await this.deps.host.stop("experiment");
+        await this.deps.host.start("stable");
+        await this.deps.host.resume();
+        await this.deps.effects.slots.clearExperiment();
+        return;
+      case "staged":
+        // Download completed but handover never started: cheap undo.
+        await this.rollbackTo("crash before handover", { skipHostRestart: true });
+        return;
+      case "handing-over":
+      case "running-experiment":
+      case "readback": {
+        // We may have died with the experiment (partially) live -- or the
+        // handover succeeded and killed the process that was driving it.
+        // EVIDENCE decides, never a "this restart was planned" flag: a flag is
+        // a claim the crash path could make just as easily.
+        if (version !== null && (await this.handoverSucceeded(last, version))) {
+          await this.finishHandover(version);
+          return;
+        }
+        // Fail closed: stop whatever runs, restore stable, resume workloads.
+        await this.rollbackTo(`crash during ${last.intent}` + (version ? ` (experiment ${version})` : ""));
+        return;
+      }
+      default: {
+        // Unknown intent => journal written by a NEWER core. Fail closed.
+        throw new Error(
+          `journal intent ${JSON.stringify(last.intent)} is not understood by this core (state format newer than binary); refusing to act`,
+        );
+      }
+    }
+  }
+
+  /** Full transactional upgrade to targetVersion via a pre-verified artifact. */
+  async upgrade(target: { version: string; bytesRef: string }): Promise<EngineOutcome> {
+    const versions = await this.deps.effects.slots.slotVersions();
+    if (versions.stable === target.version) return { result: "up-to-date" };
+
+    await this.journal("staged", { version: target.version });
+    await this.deps.effects.slots.stageExperiment(target);
+
+    // Who is handing over. Recorded BEFORE the handover because on some hosts
+    // this very process does not survive it: a service that is replaced by
+    // exiting (its supervisor respawns it from the new bytes) dies here on the
+    // SUCCESS path, and the successor -- not us -- finishes the transaction.
+    // Without this identity the successor cannot tell "the handover worked"
+    // from "we crashed mid-handover", because both leave the same journal.
+    const priorStartId = await this.probeStartId();
+    await this.journal("handing-over", {
+      version: target.version,
+      ...(priorStartId === null ? {} : { priorStartId }),
+    });
+    await this.withBudget("quiesce", () => this.deps.host.quiesce());
+    await this.withBudget("stop", () => this.deps.host.stop("stable"));
+    await this.withBudget("start", () => this.deps.host.start("experiment"));
+
+    await this.journal("running-experiment", { version: target.version });
+    let evidence: ProcessEvidence;
+    try {
+      evidence = await this.withBudget("healthProbe", () => this.deps.host.healthProbe());
+    } catch (err) {
+      // A probe that FAILED is information: the host answered "not healthy",
+      // so rolling back (which calls stop/start/resume) is sound. A probe that
+      // WEDGED is not information -- we do not know what the host is doing, and
+      // issuing more host calls to a host that never answered the last one is
+      // how a stuck upgrade becomes two live incarnations. Let it out; the
+      // journal keeps the in-flight phase and the next start resolves it from
+      // evidence.
+      if (err instanceof HostCallTimeout) throw err;
+      return this.rollbackOutcome(`experiment probe failed: ${(err as Error).message}`);
+    }
+
+    await this.journal("readback", { version: target.version });
+    const refusal = await this.deps.evaluatePredicates(evidence, target.version);
+    if (refusal !== null) {
+      return this.rollbackOutcome(`predicates refused: ${refusal}`);
+    }
+
+    await this.journal("promoted", { version: target.version });
+    await this.deps.effects.slots.promoteExperiment();
+    await this.deps.host.resume();
+    return { result: "promoted", version: target.version };
+  }
+
+  /**
+   * Did the handover actually happen? True only when a live process reports
+   * the EXPERIMENT version from a DIFFERENT incarnation than the one that
+   * journaled the handover. Same incarnation answering => nothing was
+   * replaced, whatever it claims about its version.
+   */
+  private async handoverSucceeded(last: JournalEntry, experimentVersion: string): Promise<boolean> {
+    const priorStartId = last.detail.priorStartId;
+    // No recorded identity (older journal, or a host whose probe was
+    // unavailable) => we cannot prove a successor exists => fail closed.
+    if (priorStartId === undefined) return false;
+    let evidence: ProcessEvidence;
+    try {
+      evidence = await this.withBudget("healthProbe", () => this.deps.host.healthProbe());
+    } catch {
+      return false; // nothing alive to vouch for the handover
+    }
+    return evidence.version === experimentVersion && evidence.startId !== priorStartId;
+  }
+
+  /** Finish a transaction whose handover outlived the process that began it. */
+  private async finishHandover(experimentVersion: string): Promise<void> {
+    let evidence: ProcessEvidence;
+    try {
+      evidence = await this.withBudget("healthProbe", () => this.deps.host.healthProbe());
+    } catch (err) {
+      if (err instanceof HostCallTimeout) throw err; // same rule: do not act on a wedged host
+      await this.rollbackTo(`successor probe failed: ${(err as Error).message}`);
+      return;
+    }
+    await this.journal("readback", { version: experimentVersion });
+    const refusal = await this.deps.evaluatePredicates(evidence, experimentVersion);
+    if (refusal !== null) {
+      await this.rollbackTo(`predicates refused after handover: ${refusal}`);
+      return;
+    }
+    await this.journal("promoted", { version: experimentVersion });
+    await this.deps.effects.slots.promoteExperiment();
+    await this.deps.host.resume();
+  }
+
+  /**
+   * Bound a host call. On expiry we do NOT pretend the call failed cleanly:
+   * a pending promise cannot be cancelled in JS, so the host may still be
+   * mid-operation. The transaction gives up instead of issuing further host
+   * calls it cannot reason about, and the journal records why. Recovery is
+   * the next process start, which probes for evidence and decides from facts.
+   */
+  private async withBudget<T>(label: string, call: () => Promise<T>): Promise<T> {
+    const budgetMs = this.deps.hostCallBudgetMs ?? DEFAULT_HOST_CALL_BUDGET_MS;
+    let cancel: (() => void) | undefined;
+    try {
+      return await Promise.race([
+        call(),
+        new Promise<never>((_resolve, reject) => {
+          cancel = this.deps.clock.after(budgetMs, () => {
+            reject(new HostCallTimeout(label, budgetMs));
+          });
+        }),
+      ]);
+    } finally {
+      cancel?.();
+    }
+  }
+
+  /** Best-effort identity of the live process; null when nothing answers. */
+  private async probeStartId(): Promise<string | null> {
+    try {
+      // Budgeted like every other host call: found by the wedged-host test,
+      // which hung HERE -- an unbounded probe before the handover is the same
+      // trap one line earlier.
+      return (await this.withBudget("healthProbe", () => this.deps.host.healthProbe())).startId;
+    } catch {
+      return null;
+    }
+  }
+
+  private async rollbackOutcome(reason: string): Promise<EngineOutcome> {
+    await this.rollbackTo(reason);
+    return { result: "rolled-back", reason };
+  }
+
+  private async rollbackTo(reason: string, opts: { skipHostRestart?: boolean } = {}): Promise<void> {
+    await this.journal("rolled-back", { reason });
+    if (!opts.skipHostRestart) {
+      // Stop whatever may be running (either slot), restore stable, resume.
+      await this.deps.host.stop("experiment");
+      await this.deps.host.start("stable");
+      await this.deps.host.resume();
+    }
+    await this.deps.effects.slots.clearExperiment();
+  }
+}

package/core/src/txn/fileEffects.ts

@@ -0,0 +1,129 @@
+/**
+ * Filesystem-backed TxnEffects: the real journal and slot store.
+ *
+ * Layout under stateDir:
+ *   journal.jsonl        append-only, one intent per line, fsync'd before return
+ *   slots/stable/        the trusted version's bytes
+ *   slots/experiment/    the version on trial
+ *   slots/<slot>/VERSION the version string held by that slot
+ *
+ * Durability is the whole point of this file: appendAndSync must not resolve
+ * until the entry survives a power cut, or the WAL guarantee the engine
+ * depends on is a fiction.
+ */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import type { JournalEntry } from "./state.ts";
+import type { JournalStore, SlotStore, TxnEffects } from "./effects.ts";
+import type { Slot } from "../lifecycle/hostAdapter.ts";
+import { platformOpsFor } from "../platform/index.ts";
+
+const JOURNAL = "journal.jsonl";
+const VERSION_FILE = "VERSION";
+const ARTIFACT_FILE = "artifact.bin";
+
+function slotDir(stateDir: string, slot: Slot): string {
+  return path.join(stateDir, "slots", slot);
+}
+
+export function fileJournalStore(stateDir: string): JournalStore {
+  const journalPath = path.join(stateDir, JOURNAL);
+  return {
+    async appendAndSync(entry: JournalEntry): Promise<void> {
+      await fs.mkdir(stateDir, { recursive: true });
+      const fh = await fs.open(journalPath, "a");
+      try {
+        await fh.writeFile(`${JSON.stringify(entry)}\n`);
+        await fh.sync(); // durable BEFORE we return: the WAL promise
+      } finally {
+        await fh.close();
+      }
+    },
+    async readAll(): Promise<JournalEntry[]> {
+      let text: string;
+      try {
+        text = await fs.readFile(journalPath, "utf8");
+      } catch {
+        return [];
+      }
+      const out: JournalEntry[] = [];
+      for (const line of text.split("\n")) {
+        if (!line.trim()) continue;
+        try {
+          out.push(JSON.parse(line) as JournalEntry);
+        } catch {
+          // A torn final line is expected after a crash mid-append: the entry
+          // never completed, so it never happened. Earlier lines stand.
+          break;
+        }
+      }
+      return out;
+    },
+  };
+}
+
+export function fileSlotStore(stateDir: string): SlotStore {
+  async function readVersion(slot: Slot): Promise<string | null> {
+    try {
+      return (await fs.readFile(path.join(slotDir(stateDir, slot), VERSION_FILE), "utf8")).trim();
+    } catch {
+      return null;
+    }
+  }
+
+  return {
+    async stageExperiment(artifact: { version: string; bytesRef: string }): Promise<void> {
+      const dir = slotDir(stateDir, "experiment");
+      const staging = `${dir}.staging`;
+      await fs.rm(staging, { recursive: true, force: true });
+      await fs.mkdir(staging, { recursive: true });
+      // bytesRef is a path to the verified bytes the caller downloaded.
+      await fs.copyFile(artifact.bytesRef, path.join(staging, ARTIFACT_FILE));
+      await fs.writeFile(path.join(staging, VERSION_FILE), artifact.version);
+      // Publish the slot atomically: a half-written experiment must never be
+      // visible as a stageable slot.
+      await fs.rm(dir, { recursive: true, force: true });
+      await platformOpsFor().renamePath(staging, dir);
+    },
+
+    async slotVersions(): Promise<Record<Slot, string | null>> {
+      return { stable: await readVersion("stable"), experiment: await readVersion("experiment") };
+    },
+
+    async promoteExperiment(): Promise<void> {
+      const experiment = slotDir(stateDir, "experiment");
+      const stable = slotDir(stateDir, "stable");
+      if ((await readVersion("experiment")) === null) return; // idempotent redo
+      await fs.rm(`${stable}.old`, { recursive: true, force: true });
+      await platformOpsFor().renamePath(stable, `${stable}.old`).catch(() => {});
+      await platformOpsFor().renamePath(experiment, stable);
+      await fs.rm(`${stable}.old`, { recursive: true, force: true });
+    },
+
+    async clearExperiment(): Promise<void> {
+      await fs.rm(slotDir(stateDir, "experiment"), { recursive: true, force: true });
+    },
+  };
+}
+
+export function fileEffects(stateDir: string): TxnEffects {
+  return { journal: fileJournalStore(stateDir), slots: fileSlotStore(stateDir) };
+}
+
+/** Path of the executable a slot holds, for hosts that need to launch it. */
+export function slotArtifactPath(stateDir: string, slot: Slot): string {
+  return path.join(slotDir(stateDir, slot), ARTIFACT_FILE);
+}
+
+/** Write verified bytes into the slot layout and mark them executable. */
+export async function materializeArtifact(
+  stateDir: string,
+  bytes: Uint8Array,
+): Promise<string> {
+  const tmpDir = path.join(stateDir, "incoming");
+  await fs.mkdir(tmpDir, { recursive: true });
+  const target = path.join(tmpDir, ARTIFACT_FILE);
+  await platformOpsFor().swapExecutable(target, bytes);
+  await platformOpsFor().makeExecutable(target);
+  return target;
+}

package/core/src/txn/hostCallBudget.ts

@@ -0,0 +1,28 @@
+/**
+ * A bound on how long one host call may take.
+ *
+ * A host that HANGS is worse than one that crashes: nothing is journaled, the
+ * upgrade lock stays held by a process that is still ALIVE (so stale-lock
+ * takeover never fires), and every later attempt queues behind it forever.
+ * That is the "wedged half-way" failure, and it is the one an updater is least
+ * able to explain afterwards.
+ */
+
+/**
+ * Default budget for a single host call. Long enough for a real service to
+ * drain sessions on a busy machine, short enough that a wedge is reported the
+ * same day it happens. Adopters override it via EngineDeps.hostCallBudgetMs.
+ */
+export const DEFAULT_HOST_CALL_BUDGET_MS = 120_000;
+
+/** A host call exceeded its budget: the host is wedged, not merely failing. */
+export class HostCallTimeout extends Error {
+  readonly call: string;
+  readonly budgetMs: number;
+  constructor(call: string, budgetMs: number) {
+    super(`host ${call}() did not return within ${budgetMs}ms — treating the host as wedged`);
+    this.name = "HostCallTimeout";
+    this.call = call;
+    this.budgetMs = budgetMs;
+  }
+}

package/core/src/txn/lock.ts

@@ -0,0 +1,124 @@
+/**
+ * Upgrade lock — one transaction at a time per service identity.
+ *
+ * Every entrypoint constructs the same Upgrader (daemon loop, `self upgrade`,
+ * install script, remote drive), so two of them CAN fire at once. Without a
+ * lock the semantics of "what happened" are undefined: two transactions would
+ * interleave over one journal and one pair of slots.
+ *
+ * Deliberately simple, matching the declared scope: the lock covers ONE
+ * service identity (one stateDir). It is not a cross-instance orchestrator —
+ * running several instances means several stateDirs, each with its own lock.
+ *
+ * Crash safety: the lock file records the holder's pid and start time, so a
+ * lock left behind by a killed process is detected as stale rather than
+ * wedging the install forever. "Stale" means the OS no longer knows that pid;
+ * we never time out a lock whose holder is demonstrably alive.
+ */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { platformOpsFor } from "../platform/index.ts";
+
+/** Bounded retries: an unclaimable lock is a typed failure, never a hang. */
+const MAX_ATTEMPTS = 50;
+
+export class UpgradeLockError extends Error {
+  readonly code = "UPGRADE_IN_PROGRESS";
+
+  constructor(holderPid: number) {
+    super(
+      `[UPGRADE_IN_PROGRESS] another upgrade is running (pid ${holderPid}); ` +
+        `refusing to start a second transaction over the same state`,
+    );
+    this.name = "UpgradeLockError";
+  }
+}
+
+interface LockRecord {
+  pid: number;
+  acquiredAtMs: number;
+}
+
+export interface UpgradeLock {
+  release(): Promise<void>;
+}
+
+/**
+ * Acquire the single-transaction lock, or throw UpgradeLockError.
+ * `nowMs` is injected rather than read from Date so simulation stays
+ * deterministic (clock seam discipline).
+ */
+export async function acquireUpgradeLock(stateDir: string, nowMs: number): Promise<UpgradeLock> {
+  const lockPath = path.join(stateDir, "upgrade.lock");
+  await fs.mkdir(stateDir, { recursive: true });
+  const ops = platformOpsFor();
+
+  const record: LockRecord = { pid: process.pid, acquiredAtMs: nowMs };
+  let attempts = 0;
+  for (;;) {
+    try {
+      // wx: fails if the file exists — the atomic "claim it" primitive.
+      const fh = await fs.open(lockPath, "wx");
+      try {
+        await fh.writeFile(JSON.stringify(record));
+      } finally {
+        await fh.close();
+      }
+      return {
+        async release() {
+          await fs.rm(lockPath, { force: true });
+        },
+      };
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
+      attempts += 1;
+      if (attempts > MAX_ATTEMPTS) {
+        // Never spin forever: a lock we can neither claim nor clear is a
+        // typed failure, not a hang. (Hangs hide bugs; failures report them.)
+        throw new Error(
+          `[UPGRADE_LOCK_UNRESOLVABLE] could not acquire or clear ${lockPath} after ${MAX_ATTEMPTS} attempts`,
+          { cause: err },
+        );
+      }
+      const holder = await readHolder(lockPath);
+      if (holder === "vanished") continue; // gone between open and read: retry
+      // A non-positive pid is never a real holder — and must NEVER reach
+      // process.kill, where pid<=0 addresses process GROUPS or every process.
+      if (holder !== "unreadable" && holder.pid > 0 && ops.isProcessAlive(holder.pid)) {
+        throw new UpgradeLockError(holder.pid);
+      }
+      // Holder is gone: its transaction died mid-flight. Recovery (journal
+      // replay) will decide what to do with the state; clear the lock and
+      // take it. Removing a specific stale file is safe to race — whoever
+      // wins the next `wx` owns the lock.
+      await fs.rm(lockPath, { force: true });
+    }
+  }
+}
+
+/**
+ * "vanished"    = the file disappeared; retrying the claim is correct.
+ * "unreadable"  = present but not a lock record; no holder can be proven
+ *                 alive, so it must not block forever.
+ */
+async function readHolder(lockPath: string): Promise<LockRecord | "vanished" | "unreadable"> {
+  let text: string;
+  try {
+    text = await fs.readFile(lockPath, "utf8");
+  } catch {
+    return "vanished";
+  }
+  try {
+    const parsed: unknown = JSON.parse(text);
+    if (
+      typeof parsed === "object" &&
+      parsed !== null &&
+      typeof (parsed as LockRecord).pid === "number"
+    ) {
+      return parsed as LockRecord;
+    }
+    return "unreadable";
+  } catch {
+    return "unreadable";
+  }
+}