@getmikie/cli 1.1.86 → 1.1.87

package/lib/update.mjs

@@ -0,0 +1,2944 @@
+import { spawn } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import {
+  cp,
+  chmod,
+  link,
+  lstat,
+  mkdir,
+  open,
+  readFile,
+  readdir,
+  rename,
+  rm,
+  stat,
+} from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { isDeepStrictEqual } from "node:util";
+
+const WRAPPER_PACKAGE = "@getmikie/cli";
+const HANDOFF_SCHEMA = "mikie.update-handoff.v1";
+const REPAIR_SCHEMA = "mikie.claude-hook-repair.v1";
+const RERUN_COMMAND = "npx -y @getmikie/cli@latest update";
+const MAX_COMMAND_OUTPUT_BYTES = 1024 * 1024;
+const DEFAULT_COMMAND_TIMEOUT_MS = 30_000;
+const TRANSACTION_SCHEMA = "mikie.npm-update-transaction.v1";
+const LOCK_SCHEMA = "mikie.npm-update-lock.v1";
+const MAX_TRANSACTION_TREE_ENTRIES = 16_384;
+const MAX_TRANSACTION_TREE_BYTES = 512 * 1024 * 1024;
+const MAX_TRANSACTION_JOURNAL_BYTES = 2 * 1024 * 1024;
+const RECOVERY_SCHEMA = "mikie.npm-update-recovery.v1";
+const MAX_RECOVERY_ARTIFACT_BYTES = 2 * 1024 * 1024;
+const TRANSACTION_TOKEN_PATTERN =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+const RECOVERY_LAUNCHER_SOURCE = `import { createHash } from "node:crypto";
+import { lstat, readFile } from "node:fs/promises";
+import path from "node:path";
+
+try {
+const [transactionRoot, expectedDescriptorSha256] = process.argv.slice(1);
+const digest = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const inside = (parent, candidate) => {
+  const relative = path.relative(parent, candidate);
+  return relative !== "" && !relative.startsWith("..") && !path.isAbsolute(relative);
+};
+const readBoundedFile = async (filePath, maximum) => {
+  const metadata = await lstat(filePath);
+  if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.size > maximum) {
+    throw new Error("invalid Mikie recovery artifact");
+  }
+  return readFile(filePath);
+};
+if (!path.isAbsolute(transactionRoot) || !/^[a-f0-9]{64}$/.test(expectedDescriptorSha256)) {
+  throw new Error("invalid Mikie recovery invocation");
+}
+const descriptorBytes = await readBoundedFile(path.join(transactionRoot, "recovery.json"), 2097152);
+if (digest(descriptorBytes) !== expectedDescriptorSha256) {
+  throw new Error("tampered Mikie recovery descriptor");
+}
+const descriptor = JSON.parse(descriptorBytes.toString("utf8"));
+const journalBytes = await readBoundedFile(path.join(transactionRoot, "journal.json"), 2097152);
+const journal = JSON.parse(journalBytes.toString("utf8"));
+if (
+  descriptor.transaction_root !== transactionRoot ||
+  descriptor.token !== journal.token ||
+  journal.recovery?.descriptor_sha256 !== expectedDescriptorSha256 ||
+  ![descriptor.runtime, descriptor.launcher].every(
+    (artifactPath) => typeof artifactPath === "string" && inside(transactionRoot, artifactPath),
+  )
+) {
+  throw new Error("invalid Mikie recovery authority");
+}
+const [runtimeBytes, launcherBytes] = await Promise.all([
+  readBoundedFile(descriptor.runtime, 2097152),
+  readBoundedFile(descriptor.launcher, 2097152),
+]);
+if (
+  digest(runtimeBytes) !== descriptor.runtime_sha256 ||
+  digest(launcherBytes) !== descriptor.launcher_sha256
+) {
+  throw new Error("tampered Mikie recovery authority");
+}
+const runtime = await import("data:text/javascript;base64," + runtimeBytes.toString("base64"));
+await runtime.recoverExternalNpmUpdate(transactionRoot, {
+  descriptorSha256: expectedDescriptorSha256,
+  launcherSha256: descriptor.launcher_sha256,
+  runtimeSha256: descriptor.runtime_sha256,
+});
+} catch {
+  process.stderr.write("mikie: recovery failed\\n");
+  process.exitCode = 1;
+}
+`;
+
+const RECOVERY_INLINE_EVAL = `await import('data:text/javascript;base64,${Buffer.from(
+  RECOVERY_LAUNCHER_SOURCE,
+).toString("base64")}')`;
+
+const CLAUDE_HOOK_EVENTS = [
+  ["SessionStart", "session-start"],
+  ["UserPromptSubmit", "user-prompt-submit"],
+  ["PreToolUse", "pre-tool-use"],
+  ["PostToolUse", "post-tool-use"],
+  ["PostToolUseFailure", "post-tool-use-failure"],
+  ["PostToolBatch", "post-tool-batch"],
+  ["Stop", "stop"],
+  ["StopFailure", "stop-failure"],
+  ["SessionEnd", "session-end"],
+];
+
+function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function sha256Text(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function sha256Bytes(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function parseJsonNoDuplicateKeys(input) {
+  const text = Buffer.isBuffer(input) ? input.toString("utf8") : input;
+  if (typeof text !== "string") throw new Error("invalid JSON input");
+  let index = 0;
+  const fail = () => {
+    throw new Error("invalid JSON input");
+  };
+  const skipWhitespace = () => {
+    while (index < text.length && /[\t\n\r ]/.test(text[index])) index += 1;
+  };
+  const parseString = () => {
+    if (text[index] !== '"') fail();
+    const start = index;
+    index += 1;
+    while (index < text.length) {
+      const character = text[index];
+      if (character === '"') {
+        index += 1;
+        try {
+          return JSON.parse(text.slice(start, index));
+        } catch {
+          fail();
+        }
+      }
+      if (character === "\\") {
+        index += 1;
+        if (index >= text.length) fail();
+        if (text[index] === "u") {
+          if (!/^[0-9a-fA-F]{4}$/.test(text.slice(index + 1, index + 5))) fail();
+          index += 5;
+          continue;
+        }
+        if (!'"\\/bfnrt'.includes(text[index])) fail();
+      } else if (character.charCodeAt(0) < 0x20) {
+        fail();
+      }
+      index += 1;
+    }
+    fail();
+  };
+  const parseValue = () => {
+    skipWhitespace();
+    if (text[index] === "{") {
+      index += 1;
+      skipWhitespace();
+      const keys = new Set();
+      if (text[index] === "}") {
+        index += 1;
+        return;
+      }
+      while (index < text.length) {
+        skipWhitespace();
+        const key = parseString();
+        if (keys.has(key)) throw new Error("duplicate JSON key");
+        keys.add(key);
+        skipWhitespace();
+        if (text[index] !== ":") fail();
+        index += 1;
+        parseValue();
+        skipWhitespace();
+        if (text[index] === "}") {
+          index += 1;
+          return;
+        }
+        if (text[index] !== ",") fail();
+        index += 1;
+      }
+      fail();
+    }
+    if (text[index] === "[") {
+      index += 1;
+      skipWhitespace();
+      if (text[index] === "]") {
+        index += 1;
+        return;
+      }
+      while (index < text.length) {
+        parseValue();
+        skipWhitespace();
+        if (text[index] === "]") {
+          index += 1;
+          return;
+        }
+        if (text[index] !== ",") fail();
+        index += 1;
+      }
+      fail();
+    }
+    if (text[index] === '"') {
+      parseString();
+      return;
+    }
+    for (const literal of ["true", "false", "null"]) {
+      if (text.startsWith(literal, index)) {
+        index += literal.length;
+        return;
+      }
+    }
+    const number = /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/.exec(text.slice(index));
+    if (!number) fail();
+    index += number[0].length;
+  };
+  parseValue();
+  skipWhitespace();
+  if (index !== text.length) fail();
+  return JSON.parse(text);
+}
+
+function expectedOwnership(candidateBinary) {
+  const handlers = {};
+  for (const [wireEvent, commandEvent] of CLAUDE_HOOK_EVENTS) {
+    handlers[wireEvent] = {
+      args: ["run-claude-hook", commandEvent],
+      command: candidateBinary,
+      type: "command",
+    };
+  }
+  return {
+    launcher: sha256Text(candidateBinary),
+    handlers: sha256Text(canonicalJson(handlers)),
+  };
+}
+
+export const UpdateTopology = Object.freeze({
+  NpmGlobal: "npm_global",
+  NpmEphemeral: "npm_ephemeral",
+  LegacyNative: "legacy_native",
+});
+
+function exactPublicVersion(version) {
+  return typeof version === "string" && /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(version);
+}
+
+function compareExactVersions(left, right) {
+  const leftParts = left.split(".").map(Number);
+  const rightParts = right.split(".").map(Number);
+  for (let index = 0; index < 3; index += 1) {
+    if (leftParts[index] !== rightParts[index]) return leftParts[index] - rightParts[index];
+  }
+  return 0;
+}
+
+function hasExactKeys(value, expected) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  return isDeepStrictEqual(Object.keys(value).sort(), [...expected].sort());
+}
+
+function authenticatedRecoveryInvocation(transactionRoot, descriptorSha256) {
+  const args = [
+    "--input-type=module",
+    "--eval",
+    RECOVERY_INLINE_EVAL,
+    transactionRoot,
+    descriptorSha256,
+  ];
+  return {
+    executable: process.execPath,
+    args,
+    command:
+      process.platform === "win32"
+        ? `& ${[process.execPath, ...args]
+            .map((value) => `'${value.replaceAll("'", "''")}'`)
+            .join(" ")}`
+        : [process.execPath, ...args]
+            .map((value) => `'${value.replaceAll("'", `'"'"'`)}'`)
+            .join(" "),
+  };
+}
+
+export async function externalRecoveryInvocation(transactionRoot) {
+  if (typeof transactionRoot !== "string" || !path.isAbsolute(transactionRoot)) {
+    throw new Error("unsafe Mikie update recovery root");
+  }
+  await assertNoLinkedAncestors(transactionRoot);
+  const journalPath = path.join(transactionRoot, "journal.json");
+  const metadata = await lstat(journalPath);
+  if (
+    !metadata.isFile() ||
+    metadata.isSymbolicLink() ||
+    metadata.size > MAX_TRANSACTION_JOURNAL_BYTES
+  ) {
+    throw new Error("invalid Mikie update transaction journal");
+  }
+  const journal = parseJsonNoDuplicateKeys(await readFile(journalPath));
+  const recovery = journal?.recovery;
+  if (
+    journal?.schema_version !== TRANSACTION_SCHEMA ||
+    typeof journal?.token !== "string" ||
+    !recovery ||
+    !hasExactKeys(recovery, [
+      "descriptor",
+      "descriptor_sha256",
+      "launcher",
+      "launcher_sha256",
+      "runtime",
+      "runtime_sha256",
+      "node",
+      "command",
+    ]) ||
+    recovery.descriptor !== path.join(transactionRoot, "recovery.json") ||
+    !/^[a-f0-9]{64}$/.test(recovery.descriptor_sha256)
+  ) {
+    throw new Error("invalid Mikie update recovery authority");
+  }
+  return authenticatedRecoveryInvocation(transactionRoot, recovery.descriptor_sha256);
+}
+
+function expectedHandoff(topology) {
+  if (topology === UpdateTopology.NpmGlobal) {
+    return { action: "npm_install_exact", topology };
+  }
+  if (topology === UpdateTopology.NpmEphemeral) {
+    return { action: "rerun_latest", topology };
+  }
+  throw new Error("invalid Mikie update handoff");
+}
+
+function validateHandoff(value, topology = value?.topology) {
+  const expected = expectedHandoff(topology);
+  if (
+    !hasExactKeys(value, [
+      "schema_version",
+      "topology",
+      "action",
+      "package",
+      "repair_command",
+    ]) ||
+    value.schema_version !== HANDOFF_SCHEMA ||
+    value.topology !== expected.topology ||
+    value.action !== expected.action ||
+    value.package !== WRAPPER_PACKAGE ||
+    !isDeepStrictEqual(value.repair_command, ["repair-claude-hooks-v1", "--json"])
+  ) {
+    throw new Error("invalid Mikie update handoff");
+  }
+  return value;
+}
+
+export function parseUpdateHandoff(stdout, expectedTopology) {
+  if (typeof stdout !== "string" || stdout.trim().split(/\r?\n/).length !== 1) {
+    throw new Error("invalid Mikie update handoff");
+  }
+  let value;
+  try {
+    value = JSON.parse(stdout.trim());
+  } catch {
+    throw new Error("invalid Mikie update handoff");
+  }
+  return validateHandoff(value, expectedTopology);
+}
+
+export function detectUpdateTopology({
+  environment = process.env,
+  executable = process.argv[1] ?? "",
+  globalNodeModules,
+} = {}) {
+  const normalizedExecutable = executable.replaceAll("\\", "/").toLowerCase();
+  if (environment.npm_command === "exec" || normalizedExecutable.includes("/_npx/")) {
+    return UpdateTopology.NpmEphemeral;
+  }
+  const override = environment.MIKIE_NPM_UPDATE_TOPOLOGY;
+  if (override !== undefined) {
+    if (![UpdateTopology.NpmGlobal, UpdateTopology.NpmEphemeral].includes(override)) {
+      throw new Error("unknown npm update topology");
+    }
+    if (override === UpdateTopology.NpmEphemeral) return override;
+  }
+  const normalizedGlobalRoot =
+    typeof globalNodeModules === "string"
+      ? globalNodeModules.replaceAll("\\", "/").replace(/\/$/, "").toLowerCase()
+      : null;
+  const isProvenGlobalPackage =
+    normalizedGlobalRoot !== null &&
+    normalizedExecutable.startsWith(`${normalizedGlobalRoot}/@getmikie/cli/`);
+  if (normalizedExecutable.includes("/node_modules/") && !isProvenGlobalPackage) {
+    throw new Error("project-local Mikie cannot update the global installation");
+  }
+  if (!isProvenGlobalPackage) {
+    throw new Error("Mikie is not proven to be the global Mikie package");
+  }
+  return UpdateTopology.NpmGlobal;
+}
+
+export function shouldOfferUpdatePrompt({
+  stdinIsTTY = process.stdin.isTTY === true,
+  stdoutIsTTY = process.stdout.isTTY === true,
+  environment = process.env,
+  json = false,
+  hook = false,
+  mcp = false,
+  background = false,
+} = {}) {
+  const ci = environment.CI !== undefined && !["", "0", "false"].includes(
+    String(environment.CI).toLowerCase(),
+  );
+  return stdinIsTTY && stdoutIsTTY && !ci && !json && !hook && !mcp && !background;
+}
+
+function sameExecutablePath(left, right) {
+  if (typeof left !== "string" || typeof right !== "string") return false;
+  const normalizeWindows = (value) => {
+    const separators = value.replaceAll("/", "\\");
+    const withoutDevicePrefix = separators.startsWith("\\\\?\\")
+      ? separators.slice(4)
+      : separators;
+    return withoutDevicePrefix.toLowerCase();
+  };
+  const windowsPath = /^(?:\\\\\?\\)?[a-z]:[\\/]/i;
+  if (windowsPath.test(left) || windowsPath.test(right)) {
+    return normalizeWindows(left) === normalizeWindows(right);
+  }
+  return left === right;
+}
+
+function isCandidateHandler(handler, candidateBinary, commandEvent) {
+  return (
+    hasExactKeys(handler, ["type", "command", "args"]) &&
+    handler.type === "command" &&
+    handler.command === candidateBinary &&
+    isDeepStrictEqual(handler.args, ["run-claude-hook", commandEvent])
+  );
+}
+
+function isLegacyOwnedHandler(handler, candidateBinary, wireEvent) {
+  return (
+    ["Stop", "StopFailure"].includes(wireEvent) &&
+    hasExactKeys(handler, ["type", "command", "args"]) &&
+    handler.type === "command" &&
+    handler.command === candidateBinary &&
+    isDeepStrictEqual(handler.args, ["evidence", "ingest", "--client", "claude"])
+  );
+}
+
+function foreignRegistration(registration) {
+  if (!registration || typeof registration !== "object" || Array.isArray(registration)) return null;
+  const projection = {};
+  for (const [key, value] of Object.entries(registration)) {
+    if (key !== "mcpServers") projection[key] = value;
+  }
+  const foreignServers = {};
+  const servers = registration.mcpServers;
+  if (servers && typeof servers === "object" && !Array.isArray(servers)) {
+    for (const [key, value] of Object.entries(servers)) {
+      if (key !== "mikie") foreignServers[key] = value;
+    }
+  }
+  if (Object.keys(foreignServers).length > 0) projection.mcpServers = foreignServers;
+  return projection;
+}
+
+function foreignSettings(settings, candidateBinary, { removeOwnedV1 = false } = {}) {
+  if (!settings || typeof settings !== "object" || Array.isArray(settings)) return null;
+  const projection = {};
+  for (const [key, value] of Object.entries(settings)) {
+    if (key !== "hooks") projection[key] = value;
+  }
+  const foreignHooks = {};
+  const hooks = settings.hooks;
+  if (hooks && typeof hooks === "object" && !Array.isArray(hooks)) {
+    for (const [wireEvent, groups] of Object.entries(hooks)) {
+      if (!Array.isArray(groups)) {
+        foreignHooks[wireEvent] = groups;
+        continue;
+      }
+      const commandEvent = CLAUDE_HOOK_EVENTS.find(([event]) => event === wireEvent)?.[1];
+      const retainedGroups = [];
+      for (const group of groups) {
+        if (!group || typeof group !== "object" || !Array.isArray(group.hooks)) {
+          retainedGroups.push(group);
+          continue;
+        }
+        const retainedHandlers = commandEvent
+          ? group.hooks.filter(
+              (handler) =>
+                !isCandidateHandler(handler, candidateBinary, commandEvent) &&
+                !(removeOwnedV1 && isLegacyOwnedHandler(handler, candidateBinary, wireEvent)),
+            )
+          : [...group.hooks];
+        const retainedGroup = Object.fromEntries(
+          Object.entries(group).filter(([key]) => key !== "hooks"),
+        );
+        if (retainedHandlers.length > 0) retainedGroup.hooks = retainedHandlers;
+        if (Object.keys(retainedGroup).length > 0) retainedGroups.push(retainedGroup);
+      }
+      if (retainedGroups.length > 0) foreignHooks[wireEvent] = retainedGroups;
+    }
+  }
+  if (Object.keys(foreignHooks).length > 0) projection.hooks = foreignHooks;
+  return projection;
+}
+
+function reportedForeignSettings(registration, settings, candidateBinary) {
+  const reported = [];
+  for (const server of Object.keys(foreignRegistration(registration)?.mcpServers ?? {}).sort()) {
+    reported.push(`registration.mcpServers.${server}`);
+  }
+  const hooks = settings?.hooks;
+  if (hooks && typeof hooks === "object" && !Array.isArray(hooks)) {
+    for (const [wireEvent, groups] of Object.entries(hooks).sort(([left], [right]) => left.localeCompare(right))) {
+      if (!Array.isArray(groups)) continue;
+      const commandEvent = CLAUDE_HOOK_EVENTS.find(([event]) => event === wireEvent)?.[1];
+      groups.forEach((group, index) => {
+        const handlers = Array.isArray(group?.hooks) ? group.hooks : [];
+        const hasForeignGroupFields =
+          group &&
+          typeof group === "object" &&
+          !Array.isArray(group) &&
+          Object.keys(group).some((key) => key !== "hooks");
+        if (
+          hasForeignGroupFields ||
+          !commandEvent ||
+          handlers.some((handler) => !isCandidateHandler(handler, candidateBinary, commandEvent))
+        ) {
+          reported.push(`settings.hooks.${wireEvent}[${index}]`);
+        }
+      });
+    }
+  }
+  return reported;
+}
+
+export function verifyClaudeV2Contract({
+  candidateBinary,
+  registration,
+  settings,
+  ownership,
+  foreign,
+}) {
+  const expected = expectedOwnership(candidateBinary);
+  const mikie = registration?.mcpServers?.mikie;
+  const registrationCurrent =
+    mikie &&
+    typeof mikie === "object" &&
+    !Array.isArray(mikie) &&
+    Object.keys(mikie).every((key) => ["type", "command", "args", "env"].includes(key)) &&
+    mikie.type === "stdio" &&
+    mikie.command === candidateBinary &&
+    isDeepStrictEqual(mikie.args, ["run-relay", "--adapter", "claude_code"]) &&
+    (mikie.env === undefined ||
+      (mikie.env &&
+        typeof mikie.env === "object" &&
+        !Array.isArray(mikie.env) &&
+        Object.keys(mikie.env).length === 0));
+  const hooksCurrent = CLAUDE_HOOK_EVENTS.every(([wireEvent, commandEvent]) => {
+    const groups = settings?.hooks?.[wireEvent];
+    if (!Array.isArray(groups)) return false;
+    const owned = groups.flatMap((group) => (Array.isArray(group?.hooks) ? group.hooks : []));
+    return owned.filter((handler) => isCandidateHandler(handler, candidateBinary, commandEvent)).length === 1;
+  });
+  const ownershipCurrent =
+    hasExactKeys(ownership, [
+      "version",
+      "launcher_sha256",
+      "handler_contract_sha256",
+      "mcp_owned",
+    ]) &&
+    ownership?.version === 2 &&
+    ownership.launcher_sha256 === expected.launcher &&
+    ownership.handler_contract_sha256 === expected.handlers &&
+    ownership.mcp_owned === true;
+  const foreignPreserved =
+    foreign !== undefined &&
+    isDeepStrictEqual(foreignRegistration(registration), foreign.registration) &&
+    isDeepStrictEqual(foreignSettings(settings, candidateBinary), foreign.settings);
+  return {
+    complete: registrationCurrent && hooksCurrent && ownershipCurrent && foreignPreserved,
+    foreignPreserved,
+    foreignSettings: reportedForeignSettings(registration, settings, candidateBinary),
+  };
+}
+
+function parseRepairReceipt(stdout) {
+  let receipt;
+  try {
+    receipt = JSON.parse(stdout.trim());
+  } catch {
+    throw new Error("candidate owned-adapter repair returned invalid JSON");
+  }
+  if (
+    !hasExactKeys(receipt, [
+      "schema_version",
+      "before",
+      "after",
+      "action",
+      "restart_required",
+    ]) ||
+    receipt?.schema_version !== REPAIR_SCHEMA ||
+    typeof receipt.restart_required !== "boolean"
+  ) {
+    throw new Error("candidate owned-adapter repair returned an invalid receipt");
+  }
+  const migrated =
+    receipt.before === "outdated_owned" &&
+    receipt.after === "current" &&
+    receipt.action === "migrated" &&
+    receipt.restart_required === true;
+  const current =
+    receipt.before === "current" &&
+    receipt.after === "current" &&
+    receipt.action === "already_current" &&
+    receipt.restart_required === false;
+  const skipped =
+    ["foreign_conflict", "unavailable"].includes(receipt.before) &&
+    receipt.after === receipt.before &&
+    receipt.action === "refused" &&
+    receipt.restart_required === false;
+  if (!migrated && !current && !skipped) {
+    throw new Error("candidate owned-adapter repair returned an invalid receipt");
+  }
+  return { receipt, skipped };
+}
+
+function recoveryCommand(currentVersion) {
+  return `npm install --global ${WRAPPER_PACKAGE}@${currentVersion}`;
+}
+
+export async function runUpdateTransaction({
+  handoff,
+  currentVersion,
+  platformPackage,
+  nodeVersion = process.versions.node,
+  npmExecutable = "npm",
+  registry,
+  commands,
+  files,
+  output = { writeLine: (line) => console.log(line) },
+}) {
+  validateHandoff(handoff);
+  if (handoff.topology === UpdateTopology.NpmEphemeral) {
+    output.writeLine(RERUN_COMMAND);
+    return { status: "rerun_required", command: RERUN_COMMAND };
+  }
+  if (!exactPublicVersion(currentVersion)) {
+    throw new Error("installed Mikie package version is not exact");
+  }
+  let recovery = recoveryCommand(currentVersion);
+  let lease;
+  try {
+    lease = await files.beginTransaction?.();
+  } catch (error) {
+    output.writeLine(`Recovery: ${recovery}`);
+    const reason = error instanceof Error ? error.message : "update recovery failed";
+    throw new Error(`${reason}. Recovery: ${recovery}`);
+  }
+  try {
+    const installedCurrentVersion = await files.currentInstalledVersion();
+    if (!exactPublicVersion(installedCurrentVersion)) {
+      throw new Error("installed Mikie package version is not exact");
+    }
+    recovery = recoveryCommand(installedCurrentVersion);
+    const resolved = await registry.resolveExactCompatibleVersion({
+      packageName: WRAPPER_PACKAGE,
+      currentVersion: installedCurrentVersion,
+      nodeVersion,
+    });
+    if (
+      !exactPublicVersion(resolved?.version) ||
+      resolved.public !== true ||
+      resolved.compatible !== true
+    ) {
+      throw new Error("registry did not resolve one exact compatible public version");
+    }
+    const versionOrder = compareExactVersions(resolved.version, installedCurrentVersion);
+    if (versionOrder < 0) {
+      throw new Error("registry resolved an older Mikie version");
+    }
+    if (versionOrder === 0) {
+      output.writeLine(`Mikie is already current at ${installedCurrentVersion}.`);
+      return { status: "current", version: installedCurrentVersion };
+    }
+
+    const snapshotRequest = { platformPackage };
+    if (lease !== undefined) snapshotRequest.lease = lease;
+    const snapshot = await files.snapshot(snapshotRequest);
+    let providerPrepared = false;
+    let commitDecided = false;
+    let candidate;
+    let finalLauncher;
+    try {
+      await files.markInstalling(snapshot);
+      const stagingPrefix = files.stagingPrefix(snapshot);
+      const stagedInstall = await commands.run(
+        npmExecutable,
+        ["install", "--global", `${WRAPPER_PACKAGE}@${resolved.version}`],
+        {
+          shell: false,
+          capture: true,
+          environment: { npm_config_prefix: stagingPrefix },
+        },
+      );
+      if (stagedInstall.code !== 0) throw new Error("exact staged npm install failed");
+
+      candidate = await files.locateCandidate({ platformPackage, stagingPrefix });
+      const [wrapperVersion, candidatePlatformVersion] = await Promise.all([
+        files.readPackageVersion(candidate.wrapperPackageJson),
+        files.readPackageVersion(candidate.platformPackageJson),
+      ]);
+      if (wrapperVersion !== resolved.version || candidatePlatformVersion !== resolved.version) {
+        throw new Error("candidate package version verification failed");
+      }
+      finalLauncher = files.finalLauncher();
+      const externalRecovery = await files.recordPreparedCandidate(
+        snapshot,
+        candidate,
+        finalLauncher,
+      );
+      recovery = externalRecovery;
+      output.writeLine(`Recovery: ${externalRecovery}`);
+      await files.markProviderPreparing(snapshot);
+      providerPrepared = true;
+
+      const repair = await commands.run(candidate.binary, handoff.repair_command, {
+        shell: false,
+        capture: true,
+        environment: {
+          MIKIE_DISTRIBUTION_MODE: "npm",
+          MIKIE_NPM_UPDATE_TOPOLOGY: UpdateTopology.NpmGlobal,
+          MIKIE_NPM_UPDATE_REPAIR_PHASE: "prepare",
+          MIKIE_UPDATE_REPAIR_CANDIDATE: candidate.binary,
+          MIKIE_UPDATE_REPAIR_LAUNCHER: finalLauncher,
+        },
+      });
+      const repairResult = parseRepairReceipt(repair.stdout);
+      if (
+        (!repairResult.skipped && repair.code !== 0) ||
+        (repairResult.skipped && repair.code === 0)
+      ) {
+        throw new Error("candidate owned-adapter repair failed");
+      }
+      const verification = await files.verifyClaudeV2({
+        candidate: { ...candidate, binary: finalLauncher },
+        snapshot,
+        repair: repairResult.receipt,
+      });
+      if (verification.complete !== true || verification.foreignPreserved !== true) {
+        throw new Error("candidate Claude v2 verification failed");
+      }
+      await files.prepareActivation(snapshot, candidate);
+      await files.promotePreparedCandidate(snapshot, candidate);
+      const activatedCandidate = await files.locateCandidate({ platformPackage });
+      const [activatedWrapperVersion, activatedPlatformVersion] = await Promise.all([
+        files.readPackageVersion(activatedCandidate.wrapperPackageJson),
+        files.readPackageVersion(activatedCandidate.platformPackageJson),
+      ]);
+      if (
+        activatedWrapperVersion !== resolved.version ||
+        activatedPlatformVersion !== resolved.version
+      ) {
+        throw new Error("activated package version verification failed");
+      }
+      await files.verifyActivatedCandidate(candidate, activatedCandidate);
+      await files.activate(activatedCandidate);
+      await files.checkpointCandidate(snapshot, { provider: true });
+      const settlementRequired = repairResult.receipt.action === "migrated";
+      await files.decideCommit(snapshot, { settlementRequired });
+      commitDecided = true;
+      if (settlementRequired) {
+        const settlement = await commands.run(candidate.binary, handoff.repair_command, {
+          shell: false,
+          capture: true,
+          environment: {
+            MIKIE_DISTRIBUTION_MODE: "npm",
+            MIKIE_NPM_UPDATE_TOPOLOGY: UpdateTopology.NpmGlobal,
+            MIKIE_NPM_UPDATE_REPAIR_PHASE: "commit",
+            MIKIE_UPDATE_REPAIR_CANDIDATE: candidate.binary,
+            MIKIE_UPDATE_REPAIR_LAUNCHER: finalLauncher,
+          },
+        });
+        if (settlement.code !== 0) {
+          throw new Error("candidate owned-adapter settlement failed");
+        }
+      }
+      await files.retire(snapshot);
+      return {
+        status: "updated",
+        version: resolved.version,
+        providerState: repairResult.receipt.after,
+        adapterAction: repairResult.skipped
+          ? "skipped"
+          : repairResult.receipt.action === "already_current"
+            ? "verified"
+            : "migrated",
+        foreignSettings: verification.foreignSettings ?? [],
+      };
+    } catch (error) {
+      let restoreFailure;
+      if (!commitDecided && providerPrepared) {
+        try {
+          const settlement = await commands.run(candidate.binary, handoff.repair_command, {
+            shell: false,
+            capture: true,
+            environment: {
+              MIKIE_DISTRIBUTION_MODE: "npm",
+              MIKIE_NPM_UPDATE_TOPOLOGY: UpdateTopology.NpmGlobal,
+              MIKIE_NPM_UPDATE_REPAIR_PHASE: "rollback",
+              MIKIE_UPDATE_REPAIR_CANDIDATE: candidate.binary,
+              MIKIE_UPDATE_REPAIR_LAUNCHER: finalLauncher,
+            },
+          });
+          if (settlement.code !== 0) {
+            throw new Error("candidate owned-adapter rollback failed");
+          }
+          await files.markProviderRolledBack(snapshot);
+        } catch (settlementError) {
+          restoreFailure = settlementError;
+        }
+      }
+      if (!commitDecided && !restoreFailure) {
+        try {
+          await files.restore(snapshot);
+        } catch (restoreError) {
+          restoreFailure = restoreError;
+        }
+      }
+      output.writeLine(`Recovery: ${recovery}`);
+      const reason = error instanceof Error ? error.message : "update transaction failed";
+      if (restoreFailure) {
+        const restoreReason =
+          restoreFailure instanceof Error ? restoreFailure.message : "snapshot restore failed";
+        throw new Error(`${reason}; rollback failed: ${restoreReason}. Recovery: ${recovery}`);
+      }
+      throw new Error(`${reason}. Recovery: ${recovery}`);
+    }
+  } finally {
+    await files.endTransaction?.(lease);
+  }
+}
+
+export function createCommandAdapter({
+  spawnProcess = spawn,
+  environment = process.env,
+  platform = process.platform,
+  nodeExecutable = process.execPath,
+  npmExecPath,
+  commandTimeoutMs = DEFAULT_COMMAND_TIMEOUT_MS,
+  scheduleTimeout = setTimeout,
+  cancelTimeout = clearTimeout,
+} = {}) {
+  if (!Number.isInteger(commandTimeoutMs) || commandTimeoutMs <= 0) {
+    throw new Error("Mikie update command timeout is invalid");
+  }
+  const environmentNpmCli = environment.npm_execpath;
+  const windowsNpmCli =
+    npmExecPath ??
+    (typeof environmentNpmCli === "string" &&
+      path.isAbsolute(environmentNpmCli) &&
+      /npm-cli\.(?:c?js|mjs)$/i.test(environmentNpmCli)
+      ? environmentNpmCli
+      : path.join(path.dirname(nodeExecutable), "node_modules", "npm", "bin", "npm-cli.js"));
+  return {
+    run(executable, args, { shell = false, environment: commandEnvironment = {} } = {}) {
+      if (
+        shell !== false ||
+        !Array.isArray(args) ||
+        !commandEnvironment ||
+        typeof commandEnvironment !== "object" ||
+        Array.isArray(commandEnvironment)
+      ) {
+        throw new Error("Mikie update commands require argument arrays with shell disabled");
+      }
+      return new Promise((resolve, reject) => {
+        const stdout = [];
+        const stderr = [];
+        let bytes = 0;
+        let settled = false;
+        const launchesNpm = platform === "win32" && executable === "npm";
+        const child = spawnProcess(
+          launchesNpm ? nodeExecutable : executable,
+          launchesNpm ? [windowsNpmCli, ...args] : args,
+          {
+            shell: false,
+            stdio: ["ignore", "pipe", "pipe"],
+            windowsHide: true,
+            env: { ...environment, ...commandEnvironment },
+          },
+        );
+        const deadline = scheduleTimeout(() => {
+          if (settled) return;
+          settled = true;
+          try {
+            child.kill?.("SIGKILL");
+          } catch {
+            // The child may already have exited.
+          }
+          reject(new Error("Mikie update command timed out"));
+        }, commandTimeoutMs);
+        const finish = (callback) => {
+          if (settled) return false;
+          settled = true;
+          cancelTimeout(deadline);
+          callback();
+          return true;
+        };
+        const capture = (target) => (chunk) => {
+          if (settled) return;
+          const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+          bytes += buffer.length;
+          if (bytes > MAX_COMMAND_OUTPUT_BYTES) {
+            finish(() => {
+              child.kill?.("SIGKILL");
+              reject(new Error("Mikie update command output exceeded the capture limit"));
+            });
+            return;
+          }
+          target.push(buffer);
+        };
+        child.stdout.on("data", capture(stdout));
+        child.stderr.on("data", capture(stderr));
+        child.once("error", (error) => {
+          finish(() => reject(error));
+        });
+        child.once("close", (code) => {
+          finish(() =>
+            resolve({
+              code: Number.isInteger(code) ? code : 1,
+              stdout: Buffer.concat(stdout).toString("utf8"),
+              stderr: Buffer.concat(stderr).toString("utf8"),
+            }),
+          );
+        });
+      });
+    },
+  };
+}
+
+function nodeSatisfies(engine, nodeVersion) {
+  if (engine === undefined) return true;
+  if (typeof engine !== "string") return false;
+  const match = /^>=(\d+)(?:\.(\d+))?(?:\.(\d+))?$/.exec(engine.trim());
+  if (!match) return false;
+  const required = match.slice(1).map((part) => Number(part ?? 0));
+  const actual = nodeVersion.split(".").slice(0, 3).map(Number);
+  for (let index = 0; index < 3; index += 1) {
+    if (actual[index] > required[index]) return true;
+    if (actual[index] < required[index]) return false;
+  }
+  return true;
+}
+
+function compareExactVersionsDescending(left, right) {
+  return compareExactVersions(right, left);
+}
+
+export function createRegistryAdapter({
+  commands,
+  npmExecutable = "npm",
+  registryUrl = "https://registry.npmjs.org",
+  now = Date.now,
+  resolutionTimeoutMs = 60_000,
+}) {
+  if (!Number.isInteger(resolutionTimeoutMs) || resolutionTimeoutMs <= 0) {
+    throw new Error("Mikie registry resolution timeout is invalid");
+  }
+  return {
+    async resolveExactCompatibleVersion({ packageName, nodeVersion }) {
+      const deadline = now() + resolutionTimeoutMs;
+      const versionsResponse = await commands.run(
+        npmExecutable,
+        ["view", packageName, "versions", "--json", "--registry", registryUrl],
+        { shell: false, capture: true },
+      );
+      if (versionsResponse.code !== 0) return { public: false, compatible: false };
+      let published;
+      try {
+        const parsed = JSON.parse(versionsResponse.stdout);
+        published = (Array.isArray(parsed) ? parsed : [parsed])
+          .filter(exactPublicVersion)
+          .filter((version, index, versions) => versions.indexOf(version) === index)
+          .sort(compareExactVersionsDescending);
+      } catch {
+        return { public: false, compatible: false };
+      }
+      for (const version of published.slice(0, 64)) {
+        if (now() >= deadline) break;
+        const response = await commands.run(
+          npmExecutable,
+          [
+            "view",
+            `${packageName}@${version}`,
+            "version",
+            "engines",
+            "--json",
+            "--registry",
+            registryUrl,
+          ],
+          { shell: false, capture: true },
+        );
+        if (response.code !== 0) continue;
+        let metadata;
+        try {
+          metadata = JSON.parse(response.stdout);
+        } catch {
+          continue;
+        }
+        if (metadata?.version !== version || !nodeSatisfies(metadata?.engines?.node, nodeVersion)) {
+          continue;
+        }
+        return { version, public: true, compatible: true };
+      }
+      return { public: published.length > 0, compatible: false };
+    },
+  };
+}
+
+async function readOptionalFile(filePath) {
+  try {
+    return { existed: true, bytes: await readFile(filePath) };
+  } catch (error) {
+    if (error?.code === "ENOENT") return { existed: false, bytes: Buffer.alloc(0) };
+    throw error;
+  }
+}
+
+function parseOptionalJson(snapshot) {
+  if (!snapshot?.existed) return {};
+  return parseJsonNoDuplicateKeys(snapshot.bytes);
+}
+
+function minimalRoots(paths) {
+  const absolute = [...new Set(paths.map((entry) => path.resolve(entry)))].sort(
+    (left, right) => left.length - right.length,
+  );
+  return absolute.filter(
+    (candidate, index) =>
+      !absolute.slice(0, index).some((parent) => {
+        const relative = path.relative(parent, candidate);
+        return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+      }),
+  );
+}
+
+function isPathInside(parent, candidate) {
+  const relative = path.relative(parent, candidate);
+  return relative !== "" && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+
+function validateInstallationLayout(layout) {
+  const values = [
+    layout?.wrapperPackageJson,
+    layout?.platformPackageJson,
+    layout?.binary,
+  ];
+  if (values.some((value) => typeof value !== "string" || !path.isAbsolute(value))) {
+    throw new Error("unsafe Mikie update filesystem path");
+  }
+  const shims = layout.shims ?? [];
+  if (
+    !Array.isArray(shims) ||
+    shims.length > 3 ||
+    shims.some((value) => typeof value !== "string" || !path.isAbsolute(value)) ||
+    new Set(shims.map((value) => path.resolve(value))).size !== shims.length
+  ) {
+    throw new Error("unsafe Mikie update filesystem path");
+  }
+  const wrapperRoot = path.dirname(layout.wrapperPackageJson);
+  const platformRoot = path.dirname(layout.platformPackageJson);
+  const packageNamespace = (packageRoot) =>
+    path.basename(path.dirname(packageRoot)).toLowerCase() === "@getmikie";
+  if (
+    path.basename(layout.wrapperPackageJson).toLowerCase() !== "package.json" ||
+    path.basename(layout.platformPackageJson).toLowerCase() !== "package.json" ||
+    path.basename(wrapperRoot).toLowerCase() !== "cli" ||
+    !packageNamespace(wrapperRoot) ||
+    !packageNamespace(platformRoot) ||
+    wrapperRoot === path.parse(wrapperRoot).root ||
+    platformRoot === path.parse(platformRoot).root ||
+    !isPathInside(platformRoot, layout.binary)
+  ) {
+    throw new Error("unsafe Mikie update filesystem path");
+  }
+  return { wrapperRoot, platformRoot, shims };
+}
+
+function bytesFingerprint(existed, bytes) {
+  return existed ? `present:${createHash("sha256").update(bytes).digest("hex")}` : "absent";
+}
+
+async function directoryFingerprint(root) {
+  const digest = createHash("sha256");
+  let entries = 0;
+  let bytes = 0;
+  const visit = async (directory, relativeBase = "") => {
+    const children = (await readdir(directory, { withFileTypes: true })).sort((left, right) =>
+      left.name.localeCompare(right.name),
+    );
+    for (const child of children) {
+      entries += 1;
+      if (entries > MAX_TRANSACTION_TREE_ENTRIES) {
+        throw new Error("Mikie update package tree exceeds the entry limit");
+      }
+      const relative = path.posix.join(relativeBase, child.name);
+      const childPath = path.join(directory, child.name);
+      if (child.isSymbolicLink()) throw new Error("unsafe Mikie update package tree");
+      if (child.isDirectory()) {
+        digest.update(`directory\0${relative}\0`);
+        await visit(childPath, relative);
+        continue;
+      }
+      if (!child.isFile()) throw new Error("unsafe Mikie update package tree");
+      const content = await readFile(childPath);
+      bytes += content.length;
+      if (bytes > MAX_TRANSACTION_TREE_BYTES) {
+        throw new Error("Mikie update package tree exceeds the byte limit");
+      }
+      digest.update(`file\0${relative}\0${content.length}\0`);
+      digest.update(content);
+    }
+  };
+  try {
+    const metadata = await lstat(root);
+    if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
+      throw new Error("unsafe Mikie update package tree");
+    }
+  } catch (error) {
+    if (error?.code === "ENOENT") return "absent";
+    throw error;
+  }
+  await visit(root);
+  return `present:${digest.digest("hex")}`;
+}
+
+async function assertNoLinkedAncestors(candidate) {
+  const absolute = path.resolve(candidate);
+  const parsed = path.parse(absolute);
+  let current = parsed.root;
+  for (const segment of absolute.slice(parsed.root.length).split(path.sep).filter(Boolean)) {
+    current = path.join(current, segment);
+    try {
+      const metadata = await lstat(current);
+      if (metadata.isSymbolicLink()) throw new Error("unsafe Mikie update linked path");
+    } catch (error) {
+      if (error?.code === "ENOENT") return;
+      throw error;
+    }
+  }
+}
+
+async function atomicWritePrivate(filePath, bytes) {
+  await assertNoLinkedAncestors(filePath);
+  await mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
+  await assertNoLinkedAncestors(path.dirname(filePath));
+  const temporary = path.join(
+    path.dirname(filePath),
+    `.${path.basename(filePath)}.${randomUUID()}.tmp`,
+  );
+  const handle = await open(temporary, "wx", 0o600);
+  try {
+    await handle.writeFile(bytes);
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  try {
+    await rename(temporary, filePath);
+  } catch (error) {
+    await rm(temporary, { force: true });
+    throw error;
+  }
+}
+
+async function atomicCreatePrivate(filePath, bytes) {
+  await assertNoLinkedAncestors(filePath);
+  await mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
+  const temporary = path.join(
+    path.dirname(filePath),
+    `.${path.basename(filePath)}.${randomUUID()}.tmp`,
+  );
+  const handle = await open(temporary, "wx", 0o600);
+  try {
+    await handle.writeFile(bytes);
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  try {
+    await link(temporary, filePath);
+  } finally {
+    await rm(temporary, { force: true });
+  }
+}
+
+function processIsAlive(processId) {
+  if (!Number.isInteger(processId) || processId <= 0) return false;
+  try {
+    process.kill(processId, 0);
+    return true;
+  } catch (error) {
+    return error?.code === "EPERM";
+  }
+}
+
+export function createFilesystemAdapter({
+  currentLayout,
+  locateCandidate,
+  providerPaths,
+  transactionRoot = path.join(
+    path.dirname(providerPaths?.registration ?? path.resolve(".")),
+    ".mikie",
+    "npm-update-v1",
+  ),
+  processId = process.pid,
+  isProcessAlive = processIsAlive,
+  settleProviderRepair,
+  activationBoundary,
+}) {
+  const currentRoots = validateInstallationLayout(currentLayout);
+  const currentShims = currentRoots.shims;
+  if (
+    typeof locateCandidate !== "function" ||
+    !providerPaths ||
+    Object.values(providerPaths).some(
+      (filePath) => typeof filePath !== "string" || !path.isAbsolute(filePath),
+    ) ||
+    typeof transactionRoot !== "string" ||
+    !path.isAbsolute(transactionRoot) ||
+    (settleProviderRepair !== undefined && typeof settleProviderRepair !== "function") ||
+    (activationBoundary !== undefined && typeof activationBoundary !== "function")
+  ) {
+    throw new Error("unsafe Mikie update filesystem path");
+  }
+  const installationRoots = minimalRoots([currentRoots.wrapperRoot, currentRoots.platformRoot]);
+  if (
+    installationRoots.some(
+      (root) =>
+        sameExecutablePath(root, transactionRoot) ||
+        isPathInside(root, transactionRoot) ||
+        isPathInside(transactionRoot, root),
+    ) ||
+    Object.values(providerPaths).some(
+      (filePath) =>
+        sameExecutablePath(filePath, transactionRoot) || isPathInside(transactionRoot, filePath),
+    ) ||
+    currentShims.some(
+      (shim) => sameExecutablePath(shim, transactionRoot) || isPathInside(transactionRoot, shim),
+    )
+  ) {
+    throw new Error("unsafe Mikie update filesystem path");
+  }
+  const lockPath = `${transactionRoot}.lock`;
+  const journalPath = path.join(transactionRoot, "journal.json");
+
+  const readLock = async () => {
+    try {
+      const metadata = await lstat(lockPath);
+      if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.size > 1024) {
+        throw new Error("invalid Mikie update transaction lock");
+      }
+      const value = parseJsonNoDuplicateKeys(await readFile(lockPath));
+      if (
+        !hasExactKeys(value, ["schema_version", "process_id", "token"]) ||
+        value.schema_version !== LOCK_SCHEMA ||
+        !Number.isInteger(value.process_id) ||
+        typeof value.token !== "string" ||
+        !TRANSACTION_TOKEN_PATTERN.test(value.token)
+      ) {
+        throw new Error("invalid Mikie update transaction lock");
+      }
+      return value;
+    } catch (error) {
+      if (error?.code === "ENOENT") return null;
+      throw error;
+    }
+  };
+
+  const releaseLease = async (lease) => {
+    if (!lease) return;
+    const current = await readLock();
+    if (current?.token !== lease.token || current.process_id !== lease.process_id) {
+      throw new Error("Mikie update transaction lock changed unexpectedly");
+    }
+    await rm(lockPath, { force: true });
+  };
+
+  const writeJournal = async (snapshot) => {
+    const value = {
+      schema_version: TRANSACTION_SCHEMA,
+      token: snapshot.lease.token,
+      phase: snapshot.phase,
+      staging_prefix: snapshot.stagingPrefix,
+      prepared_candidate: snapshot.preparedCandidate
+        ? {
+            wrapper_package_json: snapshot.preparedCandidate.wrapperPackageJson,
+            platform_package_json: snapshot.preparedCandidate.platformPackageJson,
+            binary: snapshot.preparedCandidate.binary,
+            wrapper_fingerprint: snapshot.preparedCandidate.wrapperFingerprint,
+            platform_fingerprint: snapshot.preparedCandidate.platformFingerprint,
+            shims: snapshot.preparedCandidate.shimFingerprints,
+            final_launcher: snapshot.preparedCandidate.finalLauncher,
+          }
+        : null,
+      recovery: snapshot.recovery
+        ? {
+            descriptor: snapshot.recovery.descriptor,
+            descriptor_sha256: snapshot.recovery.descriptorSha256,
+            launcher: snapshot.recovery.launcher,
+            launcher_sha256: snapshot.recovery.launcherSha256,
+            runtime: snapshot.recovery.runtime,
+            runtime_sha256: snapshot.recovery.runtimeSha256,
+            node: snapshot.recovery.node,
+            command: snapshot.recovery.command,
+          }
+        : null,
+      installation: snapshot.installation.map((entry) => ({
+        root: entry.root,
+        backup: entry.backup,
+        source_fingerprint: entry.sourceFingerprint,
+        expected_fingerprint: entry.expectedFingerprint ?? null,
+        activation_staging: entry.activationStaging,
+        prior_quarantine: entry.priorQuarantine,
+        activation_state: entry.activationState ?? null,
+        restore_state: entry.restoreState ?? null,
+      })),
+      shims: snapshot.shims.map((entry) => ({
+        path: entry.path,
+        backup: entry.backup,
+        source_existed: entry.existed,
+        source_fingerprint: entry.sourceFingerprint,
+        source_mode: entry.mode,
+        expected_fingerprint: entry.expectedFingerprint ?? null,
+        activation_staging: entry.activationStaging,
+        prior_quarantine: entry.priorQuarantine,
+        activation_state: entry.activationState ?? null,
+      })),
+      provider_config: snapshot.providerConfig.map((entry) => ({
+        name: entry.name,
+        path: entry.path,
+        backup: entry.backup,
+        source_existed: entry.existed,
+        source_fingerprint: entry.sourceFingerprint,
+      })),
+    };
+    await atomicWritePrivate(journalPath, Buffer.from(`${JSON.stringify(value)}\n`));
+  };
+
+  const hydrateJournal = async (lease, expectedJournalToken) => {
+    let value;
+    try {
+      const metadata = await lstat(journalPath);
+      if (
+        !metadata.isFile() ||
+        metadata.isSymbolicLink() ||
+        metadata.size > MAX_TRANSACTION_JOURNAL_BYTES
+      ) {
+        throw new Error("invalid Mikie update transaction journal");
+      }
+      value = parseJsonNoDuplicateKeys(await readFile(journalPath));
+    } catch (error) {
+      if (error?.code === "ENOENT") throw new Error("incomplete Mikie update transaction journal");
+      throw error;
+    }
+    if (
+      !hasExactKeys(value, [
+        "schema_version",
+        "token",
+        "phase",
+        "staging_prefix",
+        "prepared_candidate",
+        "recovery",
+        "installation",
+        "shims",
+        "provider_config",
+      ]) ||
+      value.schema_version !== TRANSACTION_SCHEMA ||
+      typeof value.token !== "string" ||
+      !TRANSACTION_TOKEN_PATTERN.test(value.token) ||
+      (expectedJournalToken !== null && value.token !== expectedJournalToken) ||
+      ![
+        "prepared",
+        "installing",
+        "candidate_staged",
+        "activation_prepared",
+        "candidate_packages",
+        "provider_preparing",
+        "provider_rolled_back",
+        "commit_decided",
+        "commit_decided_no_repair",
+        "committed",
+      ].includes(value.phase) ||
+      !Array.isArray(value.installation) ||
+      !Array.isArray(value.shims) ||
+      !Array.isArray(value.provider_config) ||
+      typeof value.staging_prefix !== "string" ||
+      !isPathInside(transactionRoot, value.staging_prefix)
+    ) {
+      throw new Error("invalid Mikie update transaction journal");
+    }
+    const expectedRoots = new Set(installationRoots.map((root) => path.resolve(root)));
+    const journalRoots = value.installation.map((entry) => path.resolve(entry?.root ?? ""));
+    if (
+      value.installation.length !== installationRoots.length ||
+      new Set(journalRoots).size !== expectedRoots.size ||
+      journalRoots.some((root) => !expectedRoots.has(root)) ||
+      value.installation.some(
+        (entry) =>
+          !entry ||
+          !hasExactKeys(entry, [
+            "root",
+            "backup",
+            "source_fingerprint",
+            "expected_fingerprint",
+            "activation_staging",
+            "prior_quarantine",
+            "activation_state",
+            "restore_state",
+          ]) ||
+          !expectedRoots.has(path.resolve(entry.root ?? "")) ||
+          typeof entry.backup !== "string" ||
+          !isPathInside(transactionRoot, entry.backup) ||
+          typeof entry.source_fingerprint !== "string" ||
+          typeof entry.activation_staging !== "string" ||
+          !sameExecutablePath(
+            entry.activation_staging,
+            path.join(
+              path.dirname(entry.root ?? ""),
+              `.${path.basename(entry.root ?? "")}.mikie-candidate-${value.token}`,
+            ),
+          ) ||
+          typeof entry.prior_quarantine !== "string" ||
+          !sameExecutablePath(
+            entry.prior_quarantine,
+            path.join(
+              path.dirname(entry.root ?? ""),
+              `.${path.basename(entry.root ?? "")}.mikie-prior-${value.token}`,
+            ),
+          ) ||
+          ![
+            null,
+            "copying",
+            "prepared",
+            "swapping",
+            "source_moved",
+            "activated",
+            "conflict_detected",
+            "conflict_restored",
+          ].includes(entry.activation_state ?? null) ||
+          ![null, "swapping", "restored"].includes(entry.restore_state ?? null) ||
+          ![null, "string"].includes(
+            entry.expected_fingerprint === null ? null : typeof entry.expected_fingerprint,
+          ),
+      )
+    ) {
+      throw new Error("invalid Mikie update transaction journal");
+    }
+    const expectedProviders = new Map(Object.entries(providerPaths));
+    const expectedShims = new Set(currentShims.map((shim) => path.resolve(shim)));
+    const journalShims = value.shims.map((entry) => path.resolve(entry?.path ?? ""));
+    if (
+      value.shims.length !== expectedShims.size ||
+      new Set(journalShims).size !== expectedShims.size ||
+      journalShims.some((shim) => !expectedShims.has(shim)) ||
+      value.shims.some(
+        (entry) =>
+          !entry ||
+          !hasExactKeys(entry, [
+            "path",
+            "backup",
+            "source_existed",
+            "source_fingerprint",
+            "source_mode",
+            "expected_fingerprint",
+            "activation_staging",
+            "prior_quarantine",
+            "activation_state",
+          ]) ||
+          !expectedShims.has(path.resolve(entry.path ?? "")) ||
+          (entry.backup !== null && !isPathInside(transactionRoot, entry.backup)) ||
+          typeof entry.source_existed !== "boolean" ||
+          typeof entry.source_fingerprint !== "string" ||
+          !Number.isInteger(entry.source_mode) ||
+          entry.source_mode < 0 ||
+          entry.source_mode > 0o777 ||
+          typeof entry.activation_staging !== "string" ||
+          !sameExecutablePath(
+            entry.activation_staging,
+            path.join(
+              path.dirname(entry.path ?? ""),
+              `.${path.basename(entry.path ?? "")}.mikie-candidate-${value.token}`,
+            ),
+          ) ||
+          typeof entry.prior_quarantine !== "string" ||
+          !sameExecutablePath(
+            entry.prior_quarantine,
+            path.join(
+              path.dirname(entry.path ?? ""),
+              `.${path.basename(entry.path ?? "")}.mikie-prior-${value.token}`,
+            ),
+          ) ||
+          ![
+            null,
+            "copying",
+            "prepared",
+            "swapping",
+            "source_moved",
+            "activated",
+            "conflict_detected",
+            "conflict_restored",
+          ].includes(entry.activation_state ?? null) ||
+          ![null, "string"].includes(
+            entry.expected_fingerprint === null ? null : typeof entry.expected_fingerprint,
+          ),
+      )
+    ) {
+      throw new Error("invalid Mikie update transaction journal");
+    }
+    const journalProviderNames = value.provider_config.map((entry) => entry?.name);
+    if (
+      value.provider_config.length !== expectedProviders.size ||
+      new Set(journalProviderNames).size !== expectedProviders.size ||
+      journalProviderNames.some((name) => !expectedProviders.has(name)) ||
+      value.provider_config.some(
+        (entry) =>
+          !entry ||
+          !hasExactKeys(entry, [
+            "name",
+            "path",
+            "backup",
+            "source_existed",
+            "source_fingerprint",
+          ]) ||
+          expectedProviders.get(entry.name) !== entry.path ||
+          (entry.backup !== null && !isPathInside(transactionRoot, entry.backup)) ||
+          typeof entry.source_existed !== "boolean" ||
+          typeof entry.source_fingerprint !== "string"
+      )
+    ) {
+      throw new Error("invalid Mikie update transaction journal");
+    }
+    let preparedCandidate = null;
+    if (value.prepared_candidate !== null) {
+      const prepared = value.prepared_candidate;
+      if (
+        !hasExactKeys(prepared, [
+          "wrapper_package_json",
+          "platform_package_json",
+          "binary",
+          "wrapper_fingerprint",
+          "platform_fingerprint",
+          "shims",
+          "final_launcher",
+        ]) ||
+        ![prepared.wrapper_package_json, prepared.platform_package_json, prepared.binary].every(
+          (candidatePath) =>
+            typeof candidatePath === "string" && isPathInside(value.staging_prefix, candidatePath),
+        ) ||
+        typeof prepared.wrapper_fingerprint !== "string" ||
+        typeof prepared.platform_fingerprint !== "string" ||
+        !Array.isArray(prepared.shims) ||
+        prepared.shims.length !== currentShims.length ||
+        prepared.shims.some(
+          (shim, index) =>
+            !hasExactKeys(shim, ["path", "fingerprint"]) ||
+            typeof shim.path !== "string" ||
+            !isPathInside(value.staging_prefix, shim.path) ||
+            path.basename(shim.path).toLowerCase() !==
+              path.basename(currentShims[index]).toLowerCase() ||
+            typeof shim.fingerprint !== "string",
+        ) ||
+        new Set(prepared.shims.map((shim) => path.resolve(shim.path))).size !==
+          prepared.shims.length ||
+        !sameExecutablePath(prepared.final_launcher, currentLayout.binary)
+      ) {
+        throw new Error("invalid Mikie update transaction journal");
+      }
+      preparedCandidate = {
+        wrapperPackageJson: prepared.wrapper_package_json,
+        platformPackageJson: prepared.platform_package_json,
+        binary: prepared.binary,
+        wrapperFingerprint: prepared.wrapper_fingerprint,
+        platformFingerprint: prepared.platform_fingerprint,
+        shims: prepared.shims.map((shim) => shim.path),
+        shimFingerprints: prepared.shims,
+        finalLauncher: prepared.final_launcher,
+      };
+      const preparedRoots = validateInstallationLayout(preparedCandidate);
+      if (
+        (await directoryFingerprint(preparedRoots.wrapperRoot)) !==
+          preparedCandidate.wrapperFingerprint ||
+        (await directoryFingerprint(preparedRoots.platformRoot)) !==
+          preparedCandidate.platformFingerprint
+      ) {
+        throw new Error("corrupt Mikie staged candidate");
+      }
+      for (const shim of preparedCandidate.shimFingerprints) {
+        const current = await readOptionalFile(shim.path);
+        if (bytesFingerprint(current.existed, current.bytes) !== shim.fingerprint) {
+          throw new Error("corrupt Mikie staged candidate");
+        }
+      }
+    }
+    let recovery = null;
+    if (value.recovery !== null) {
+      const persisted = value.recovery;
+      if (
+        !hasExactKeys(persisted, [
+          "descriptor",
+          "descriptor_sha256",
+          "launcher",
+          "launcher_sha256",
+          "runtime",
+          "runtime_sha256",
+          "node",
+          "command",
+        ]) ||
+        ![persisted.descriptor, persisted.launcher, persisted.runtime].every(
+          (artifactPath) =>
+            typeof artifactPath === "string" && isPathInside(transactionRoot, artifactPath),
+        ) ||
+        typeof persisted.node !== "string" ||
+        !path.isAbsolute(persisted.node) ||
+        typeof persisted.command !== "string" ||
+        !/^[a-f0-9]{64}$/.test(persisted.descriptor_sha256) ||
+        !/^[a-f0-9]{64}$/.test(persisted.launcher_sha256) ||
+        !/^[a-f0-9]{64}$/.test(persisted.runtime_sha256)
+      ) {
+        throw new Error("invalid Mikie update recovery authority");
+      }
+      const artifacts = await Promise.all(
+        [persisted.descriptor, persisted.launcher, persisted.runtime].map(async (artifactPath) => {
+          const metadata = await lstat(artifactPath);
+          if (
+            !metadata.isFile() ||
+            metadata.isSymbolicLink() ||
+            metadata.size > MAX_RECOVERY_ARTIFACT_BYTES
+          ) {
+            throw new Error("invalid Mikie update recovery authority");
+          }
+          return readFile(artifactPath);
+        }),
+      );
+      if (
+        sha256Bytes(artifacts[0]) !== persisted.descriptor_sha256 ||
+        sha256Bytes(artifacts[1]) !== persisted.launcher_sha256 ||
+        sha256Bytes(artifacts[2]) !== persisted.runtime_sha256
+      ) {
+        throw new Error("tampered Mikie update recovery authority");
+      }
+      recovery = {
+        descriptor: persisted.descriptor,
+        descriptorSha256: persisted.descriptor_sha256,
+        launcher: persisted.launcher,
+        launcherSha256: persisted.launcher_sha256,
+        runtime: persisted.runtime,
+        runtimeSha256: persisted.runtime_sha256,
+        node: persisted.node,
+        command: persisted.command,
+      };
+    }
+    if (
+      [
+        "provider_preparing",
+        "activation_prepared",
+        "provider_rolled_back",
+        "candidate_packages",
+        "commit_decided",
+        "commit_decided_no_repair",
+        "committed",
+      ].includes(value.phase) &&
+      (!preparedCandidate || !recovery)
+    ) {
+      throw new Error("incomplete Mikie update recovery authority");
+    }
+    const providerConfig = [];
+    for (const entry of value.provider_config) {
+      const bytes = entry.source_existed ? await readFile(entry.backup) : Buffer.alloc(0);
+      if (bytesFingerprint(entry.source_existed, bytes) !== entry.source_fingerprint) {
+        throw new Error("corrupt Mikie update transaction backup");
+      }
+      providerConfig.push({
+        name: entry.name,
+        path: entry.path,
+        existed: entry.source_existed,
+        bytes,
+        backup: entry.backup,
+        sourceFingerprint: entry.source_fingerprint,
+      });
+    }
+    const shims = [];
+    for (const entry of value.shims) {
+      const bytes = entry.source_existed ? await readFile(entry.backup) : Buffer.alloc(0);
+      if (bytesFingerprint(entry.source_existed, bytes) !== entry.source_fingerprint) {
+        throw new Error("corrupt Mikie update transaction backup");
+      }
+      shims.push({
+        path: entry.path,
+        existed: entry.source_existed,
+        bytes,
+        backup: entry.backup,
+        mode: entry.source_mode,
+        sourceFingerprint: entry.source_fingerprint,
+        expectedFingerprint: entry.expected_fingerprint,
+        activationStaging: entry.activation_staging,
+        priorQuarantine: entry.prior_quarantine,
+        activationState: entry.activation_state ?? null,
+      });
+    }
+    for (const entry of value.installation) {
+      if ((await directoryFingerprint(entry.backup)) !== entry.source_fingerprint) {
+        throw new Error("corrupt Mikie update transaction backup");
+      }
+    }
+    return {
+      backupRoot: transactionRoot,
+      lease,
+      phase: value.phase,
+      stagingPrefix: value.staging_prefix,
+      preparedCandidate,
+      recovery,
+      installation: value.installation.map((entry) => ({
+        root: entry.root,
+        backup: entry.backup,
+        sourceFingerprint: entry.source_fingerprint,
+        expectedFingerprint: entry.expected_fingerprint,
+        activationStaging: entry.activation_staging,
+        priorQuarantine: entry.prior_quarantine,
+        activationState: entry.activation_state ?? null,
+        restoreState: entry.restore_state ?? null,
+      })),
+      shims,
+      providerConfig,
+    };
+  };
+
+  const removePreparedActivation = async (entry) => {
+    const stagedFingerprint = await directoryFingerprint(entry.activationStaging);
+    if (stagedFingerprint === "absent") return;
+    if (
+      entry.activationState !== "copying" &&
+      (!entry.expectedFingerprint || stagedFingerprint !== entry.expectedFingerprint)
+    ) {
+      throw new Error("tampered Mikie activation staging package");
+    }
+    await rm(entry.activationStaging, { recursive: true, force: true });
+  };
+
+  const restoreRoot = async (snapshot, entry) => {
+    const currentFingerprint = await directoryFingerprint(entry.root);
+    const expected = entry.expectedFingerprint;
+    const priorFingerprint = await directoryFingerprint(entry.priorQuarantine);
+    if (priorFingerprint !== "absent") {
+      if (priorFingerprint !== entry.sourceFingerprint) {
+        if (
+          currentFingerprint !== "absent" ||
+          !["swapping", "source_moved", "conflict_detected"].includes(entry.activationState)
+        ) {
+          throw new Error("tampered Mikie prior package quarantine");
+        }
+        await rename(entry.priorQuarantine, entry.root);
+        if ((await directoryFingerprint(entry.root)) !== priorFingerprint) {
+          throw new Error("package changed while the Mikie update rollback was committing");
+        }
+        entry.activationState = "conflict_restored";
+        await writeJournal(snapshot);
+        await removePreparedActivation(entry);
+        return;
+      }
+      if (currentFingerprint === entry.sourceFingerprint) {
+        await rm(entry.priorQuarantine, { recursive: true, force: true });
+        await removePreparedActivation(entry);
+        return;
+      }
+      if (currentFingerprint !== "absent" && currentFingerprint !== expected) {
+        throw new Error("package changed after the Mikie update checkpoint");
+      }
+      if (currentFingerprint === expected) {
+        const stagedFingerprint = await directoryFingerprint(entry.activationStaging);
+        if (stagedFingerprint === "absent") {
+          await rename(entry.root, entry.activationStaging);
+          if ((await directoryFingerprint(entry.activationStaging)) !== expected) {
+            throw new Error("package changed while the Mikie update rollback was committing");
+          }
+        } else if (stagedFingerprint === expected) {
+          await rm(entry.root, { recursive: true, force: true });
+        } else {
+          throw new Error("tampered Mikie activation staging package");
+        }
+      }
+      await rename(entry.priorQuarantine, entry.root);
+      if ((await directoryFingerprint(entry.root)) !== entry.sourceFingerprint) {
+        throw new Error("Mikie update package restore verification failed");
+      }
+      await removePreparedActivation(entry);
+      entry.restoreState = "restored";
+      await writeJournal(snapshot);
+      return;
+    }
+    if (currentFingerprint === entry.sourceFingerprint) {
+      await removePreparedActivation(entry);
+      return;
+    }
+    if (
+      priorFingerprint === "absent" &&
+      ["swapping", "source_moved", "conflict_detected", "conflict_restored"].includes(
+        entry.activationState,
+      ) &&
+      currentFingerprint !== expected
+    ) {
+      await removePreparedActivation(entry);
+      entry.activationState = "conflict_restored";
+      entry.restoreState = "restored";
+      await writeJournal(snapshot);
+      return;
+    }
+    if (!expected) {
+      throw new Error("package changed before the Mikie update checkpoint");
+    }
+    if (
+      currentFingerprint !== expected &&
+      currentFingerprint !== "absent" &&
+      !(entry.restoreState === "swapping" && currentFingerprint === "absent")
+    ) {
+      throw new Error("package changed after the Mikie update checkpoint");
+    }
+    const staging = path.join(
+      path.dirname(entry.root),
+      `.${path.basename(entry.root)}.mikie-restore-${snapshot.lease.token}`,
+    );
+    await rm(staging, { recursive: true, force: true });
+    await cp(entry.backup, staging, { recursive: true, force: false, errorOnExist: true });
+    if ((await directoryFingerprint(entry.backup)) !== entry.sourceFingerprint) {
+      await rm(staging, { recursive: true, force: true });
+      throw new Error("corrupt Mikie update transaction backup");
+    }
+    if ((await directoryFingerprint(staging)) !== entry.sourceFingerprint) {
+      await rm(staging, { recursive: true, force: true });
+      throw new Error("Mikie update package restore verification failed");
+    }
+    const quarantine = entry.activationStaging;
+    const stagedFingerprint = await directoryFingerprint(quarantine);
+    if (stagedFingerprint !== "absent" && stagedFingerprint !== expected) {
+      throw new Error("tampered Mikie activation staging package");
+    }
+    if (stagedFingerprint === expected) {
+      await rm(quarantine, { recursive: true, force: true });
+    }
+    entry.restoreState = "swapping";
+    await writeJournal(snapshot);
+    try {
+      if (currentFingerprint !== "absent") {
+        await rename(entry.root, quarantine);
+        if ((await directoryFingerprint(quarantine)) !== currentFingerprint) {
+          throw new Error("package changed while the Mikie update rollback was committing");
+        }
+      }
+      await rename(staging, entry.root);
+    } catch (error) {
+      await rm(staging, { recursive: true, force: true });
+      try {
+        if (currentFingerprint !== "absent") await rename(quarantine, entry.root);
+      } catch {
+        // The durable journal retains both locations for the next recovery attempt.
+      }
+      throw error;
+    }
+    await rm(quarantine, { recursive: true, force: true });
+    entry.restoreState = "restored";
+    await writeJournal(snapshot);
+  };
+
+  const readShimState = async (filePath) => {
+    await assertNoLinkedAncestors(filePath);
+    try {
+      const metadata = await lstat(filePath);
+      if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.size > MAX_COMMAND_OUTPUT_BYTES) {
+        throw new Error("unsafe Mikie global shim");
+      }
+      const bytes = await readFile(filePath);
+      return {
+        existed: true,
+        bytes,
+        fingerprint: bytesFingerprint(true, bytes),
+        device: metadata.dev,
+        inode: metadata.ino,
+      };
+    } catch (error) {
+      if (error?.code === "ENOENT") {
+        return {
+          existed: false,
+          bytes: Buffer.alloc(0),
+          fingerprint: "absent",
+          device: null,
+          inode: null,
+        };
+      }
+      throw error;
+    }
+  };
+
+  const removePreparedShim = async (entry) => {
+    const staged = await readShimState(entry.activationStaging);
+    if (!staged.existed) return;
+    if (
+      entry.activationState !== "copying" &&
+      (!entry.expectedFingerprint || staged.fingerprint !== entry.expectedFingerprint)
+    ) {
+      throw new Error("tampered Mikie activation staging shim");
+    }
+    await rm(entry.activationStaging, { force: true });
+  };
+
+  const sameShimIdentity = (left, right) =>
+    left.existed &&
+    right.existed &&
+    left.device === right.device &&
+    left.inode === right.inode &&
+    left.inode !== 0;
+
+  const publishShimWithoutReplacement = async (
+    source,
+    destination,
+    expectedFingerprint,
+    beforeSourceUnlink,
+  ) => {
+    await link(source, destination);
+    const published = await readShimState(destination);
+    if (published.fingerprint !== expectedFingerprint) {
+      throw new Error("global shim changed while Mikie was committing");
+    }
+    await beforeSourceUnlink?.();
+    await rm(source, { force: true });
+  };
+
+  const restoreShim = async (snapshot, entry) => {
+    const current = await readShimState(entry.path);
+    const prior = await readShimState(entry.priorQuarantine);
+    let staged = await readShimState(entry.activationStaging);
+    const conflictStates = ["swapping", "source_moved", "conflict_detected", "conflict_restored"];
+    if (prior.existed) {
+      if (prior.fingerprint !== entry.sourceFingerprint) {
+        if (
+          current.fingerprint === prior.fingerprint &&
+          sameShimIdentity(current, prior) &&
+          conflictStates.includes(entry.activationState)
+        ) {
+          await rm(entry.priorQuarantine, { force: true });
+          await removePreparedShim(entry);
+          entry.activationState = "conflict_restored";
+          await writeJournal(snapshot);
+          return;
+        }
+        if (!current.existed && conflictStates.includes(entry.activationState)) {
+          await publishShimWithoutReplacement(
+            entry.priorQuarantine,
+            entry.path,
+            prior.fingerprint,
+          );
+          entry.activationState = "conflict_restored";
+          await writeJournal(snapshot);
+          await removePreparedShim(entry);
+          return;
+        }
+        throw new Error("tampered Mikie prior shim quarantine");
+      }
+      if (current.fingerprint === entry.sourceFingerprint) {
+        await rm(entry.priorQuarantine, { force: true });
+        await removePreparedShim(entry);
+        return;
+      }
+      if (!current.existed) {
+        await publishShimWithoutReplacement(
+          entry.priorQuarantine,
+          entry.path,
+          entry.sourceFingerprint,
+        );
+        await chmod(entry.path, entry.mode);
+        await removePreparedShim(entry);
+        return;
+      }
+      if (current.fingerprint === entry.expectedFingerprint) {
+        if (staged.existed) {
+          if (staged.fingerprint !== entry.expectedFingerprint) {
+            throw new Error("Mikie shim rollback staging path is not empty");
+          }
+          await rm(entry.activationStaging, { force: true });
+          staged = await readShimState(entry.activationStaging);
+        }
+        await rename(entry.path, entry.activationStaging);
+        await activationBoundary?.(
+          "shim_restore_candidate_moved",
+          entry.path,
+          entry.activationStaging,
+          entry.priorQuarantine,
+        );
+        const moved = await readShimState(entry.activationStaging);
+        if (moved.fingerprint !== entry.expectedFingerprint) {
+          await publishShimWithoutReplacement(
+            entry.activationStaging,
+            entry.path,
+            moved.fingerprint,
+          );
+          await rm(entry.priorQuarantine, { force: true });
+          entry.activationState = "conflict_restored";
+          await writeJournal(snapshot);
+          return;
+        }
+        await publishShimWithoutReplacement(
+          entry.priorQuarantine,
+          entry.path,
+          entry.sourceFingerprint,
+        );
+        await chmod(entry.path, entry.mode);
+        await removePreparedShim(entry);
+        return;
+      }
+      if (
+        staged.existed &&
+        current.fingerprint === staged.fingerprint &&
+        sameShimIdentity(current, staged) &&
+        (conflictStates.includes(entry.activationState) || entry.activationState === "activated")
+      ) {
+        await rm(entry.activationStaging, { force: true });
+        await rm(entry.priorQuarantine, { force: true });
+        entry.activationState = "conflict_restored";
+        await writeJournal(snapshot);
+        return;
+      }
+      if (conflictStates.includes(entry.activationState) || entry.activationState === "activated") {
+        await rm(entry.priorQuarantine, { force: true });
+        await removePreparedShim(entry);
+        entry.activationState = "conflict_restored";
+        await writeJournal(snapshot);
+        return;
+      }
+      throw new Error("global shim changed after the Mikie update checkpoint");
+    }
+
+    if (current.fingerprint === entry.sourceFingerprint) {
+      await removePreparedShim(entry);
+      return;
+    }
+    if (
+      staged.existed &&
+      current.fingerprint === staged.fingerprint &&
+      sameShimIdentity(current, staged)
+    ) {
+      if (
+        staged.fingerprint !== entry.expectedFingerprint &&
+        !conflictStates.includes(entry.activationState)
+      ) {
+        throw new Error("Mikie shim rollback staging path is not empty");
+      }
+      await rm(entry.activationStaging, { force: true });
+      staged = await readShimState(entry.activationStaging);
+      if (current.fingerprint !== entry.expectedFingerprint) {
+        entry.activationState = "conflict_restored";
+        await writeJournal(snapshot);
+        return;
+      }
+    }
+    if (
+      conflictStates.includes(entry.activationState) &&
+      current.fingerprint !== entry.expectedFingerprint
+    ) {
+      await removePreparedShim(entry);
+      entry.activationState = "conflict_restored";
+      await writeJournal(snapshot);
+      return;
+    }
+    if (!entry.expectedFingerprint) {
+      throw new Error("global shim changed before the Mikie update checkpoint");
+    }
+    if (current.existed && current.fingerprint !== entry.expectedFingerprint) {
+      throw new Error("global shim changed after the Mikie update checkpoint");
+    }
+    if (current.existed) {
+      if (staged.existed) throw new Error("Mikie shim rollback staging path is not empty");
+      await rename(entry.path, entry.activationStaging);
+      await activationBoundary?.(
+        "shim_restore_candidate_moved",
+        entry.path,
+        entry.activationStaging,
+        entry.priorQuarantine,
+      );
+      const moved = await readShimState(entry.activationStaging);
+      if (moved.fingerprint !== entry.expectedFingerprint) {
+        await publishShimWithoutReplacement(entry.activationStaging, entry.path, moved.fingerprint);
+        entry.activationState = "conflict_restored";
+        await writeJournal(snapshot);
+        return;
+      }
+    }
+    if (entry.existed) {
+      try {
+        await atomicCreatePrivate(entry.path, entry.bytes);
+        await chmod(entry.path, entry.mode);
+      } catch (error) {
+        const concurrent = await readShimState(entry.path);
+        if (!concurrent.existed) throw error;
+        await removePreparedShim(entry);
+        entry.activationState = "conflict_restored";
+        await writeJournal(snapshot);
+        return;
+      }
+      const restored = await readShimState(entry.path);
+      if (restored.fingerprint !== entry.sourceFingerprint) {
+        throw new Error("global shim restore verification failed");
+      }
+    }
+    await removePreparedShim(entry);
+  };
+
+  const restoreSnapshot = async (snapshot) => {
+    const failures = [];
+    for (const entry of snapshot.installation) {
+      try {
+        await restoreRoot(snapshot, entry);
+      } catch (error) {
+        failures.push(error);
+      }
+    }
+    for (const entry of snapshot.shims) {
+      try {
+        await restoreShim(snapshot, entry);
+      } catch (error) {
+        failures.push(error);
+      }
+    }
+    if (failures.length > 0) throw new AggregateError(failures, "snapshot restore was incomplete");
+    await rm(snapshot.backupRoot, { recursive: true, force: true });
+  };
+
+  const cleanupCommittedActivation = async (snapshot) => {
+    for (const entry of snapshot.installation) {
+      if (
+        !entry.expectedFingerprint ||
+        (await directoryFingerprint(entry.root)) !== entry.expectedFingerprint
+      ) {
+        throw new Error("committed Mikie package changed before cleanup");
+      }
+      const priorFingerprint = await directoryFingerprint(entry.priorQuarantine);
+      if (priorFingerprint !== "absent" && priorFingerprint !== entry.sourceFingerprint) {
+        throw new Error("tampered Mikie prior package quarantine");
+      }
+      const stagedFingerprint = await directoryFingerprint(entry.activationStaging);
+      if (stagedFingerprint !== "absent" && stagedFingerprint !== entry.expectedFingerprint) {
+        throw new Error("tampered Mikie activation staging package");
+      }
+    }
+    for (const entry of snapshot.shims) {
+      if (
+        !entry.expectedFingerprint ||
+        (await readShimState(entry.path)).fingerprint !== entry.expectedFingerprint
+      ) {
+        throw new Error("committed Mikie shim changed before cleanup");
+      }
+      const prior = await readShimState(entry.priorQuarantine);
+      if (prior.existed && prior.fingerprint !== entry.sourceFingerprint) {
+        throw new Error("tampered Mikie prior shim quarantine");
+      }
+      const staged = await readShimState(entry.activationStaging);
+      if (staged.existed && staged.fingerprint !== entry.expectedFingerprint) {
+        throw new Error("tampered Mikie activation staging shim");
+      }
+    }
+    for (const entry of snapshot.installation) {
+      await rm(entry.priorQuarantine, { recursive: true, force: true });
+      await rm(entry.activationStaging, { recursive: true, force: true });
+    }
+    for (const entry of snapshot.shims) {
+      await rm(entry.priorQuarantine, { force: true });
+      await rm(entry.activationStaging, { force: true });
+    }
+  };
+
+  const recoverInterrupted = async (lease, expectedJournalToken) => {
+    try {
+      const metadata = await lstat(transactionRoot);
+      if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
+        throw new Error("unsafe Mikie update transaction root");
+      }
+    } catch (error) {
+      if (error?.code === "ENOENT") return;
+      throw error;
+    }
+    const snapshot = await hydrateJournal(lease, expectedJournalToken);
+    if (snapshot.phase === "commit_decided") {
+      if (!settleProviderRepair) {
+        throw new Error("candidate owned-adapter settlement is unavailable");
+      }
+      await settleProviderRepair("commit", snapshot);
+      snapshot.phase = "committed";
+      await writeJournal(snapshot);
+      await cleanupCommittedActivation(snapshot);
+      await rm(transactionRoot, { recursive: true, force: true });
+      return;
+    }
+    if (snapshot.phase === "commit_decided_no_repair") {
+      snapshot.phase = "committed";
+      await writeJournal(snapshot);
+      await cleanupCommittedActivation(snapshot);
+      await rm(transactionRoot, { recursive: true, force: true });
+      return;
+    }
+    if (snapshot.phase === "committed") {
+      await cleanupCommittedActivation(snapshot);
+      await rm(transactionRoot, { recursive: true, force: true });
+      return;
+    }
+    if (["provider_preparing", "activation_prepared", "candidate_packages"].includes(snapshot.phase)) {
+      if (!settleProviderRepair) {
+        throw new Error("candidate owned-adapter settlement is unavailable");
+      }
+      await settleProviderRepair("rollback", snapshot);
+      snapshot.phase = "provider_rolled_back";
+      await writeJournal(snapshot);
+    }
+    await restoreSnapshot(snapshot);
+  };
+
+  const beginTransaction = async () => {
+    await assertNoLinkedAncestors(path.dirname(transactionRoot));
+    await mkdir(path.dirname(transactionRoot), { recursive: true, mode: 0o700 });
+    await assertNoLinkedAncestors(path.dirname(transactionRoot));
+    let recoveryToken = null;
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+      const lease = { schema_version: LOCK_SCHEMA, process_id: processId, token: randomUUID() };
+      try {
+        const handle = await open(lockPath, "wx", 0o600);
+        try {
+          await handle.writeFile(`${JSON.stringify(lease)}\n`);
+          await handle.sync();
+        } finally {
+          await handle.close();
+        }
+        try {
+          await recoverInterrupted(lease, recoveryToken);
+          return lease;
+        } catch (error) {
+          await releaseLease(lease);
+          throw error;
+        }
+      } catch (error) {
+        if (error?.code !== "EEXIST" || attempt > 0) throw error;
+        const existing = await readLock();
+        if (existing && isProcessAlive(existing.process_id)) {
+          throw new Error("another Mikie update transaction is active");
+        }
+        recoveryToken = existing?.token ?? null;
+        await rm(lockPath, { force: true });
+      }
+    }
+    throw new Error("Mikie update transaction lock is unavailable");
+  };
+
+  const adapter = {
+    beginTransaction,
+    async endTransaction(lease) {
+      await releaseLease(lease);
+    },
+    async currentInstalledVersion() {
+      const [wrapperVersion, platformVersion] = await Promise.all([
+        adapter.readPackageVersion(currentLayout.wrapperPackageJson),
+        adapter.readPackageVersion(currentLayout.platformPackageJson),
+      ]);
+      if (wrapperVersion !== platformVersion || !exactPublicVersion(wrapperVersion)) {
+        throw new Error("installed Mikie package versions do not match");
+      }
+      return wrapperVersion;
+    },
+    async snapshot(request = {}) {
+      const autoLease = request.lease === undefined;
+      const lease = request.lease ?? (await beginTransaction());
+      try {
+        await mkdir(transactionRoot, { mode: 0o700 });
+        const installation = [];
+        for (const [index, root] of installationRoots.entries()) {
+          const backup = path.join(transactionRoot, `package-${index}`);
+          const sourceFingerprint = await directoryFingerprint(root);
+          await cp(root, backup, { recursive: true, force: false, errorOnExist: true });
+          if ((await directoryFingerprint(backup)) !== sourceFingerprint) {
+            throw new Error("Mikie update package snapshot verification failed");
+          }
+          installation.push({
+            root,
+            backup,
+            sourceFingerprint,
+            expectedFingerprint: null,
+            activationStaging: path.join(
+              path.dirname(root),
+              `.${path.basename(root)}.mikie-candidate-${lease.token}`,
+            ),
+            priorQuarantine: path.join(
+              path.dirname(root),
+              `.${path.basename(root)}.mikie-prior-${lease.token}`,
+            ),
+            activationState: null,
+            restoreState: null,
+          });
+        }
+        const shims = [];
+        for (const [index, shimPath] of currentShims.entries()) {
+          await assertNoLinkedAncestors(shimPath);
+          const source = await readOptionalFile(shimPath);
+          const metadata = source.existed ? await stat(shimPath) : null;
+          if (metadata && (!metadata.isFile() || metadata.size > MAX_COMMAND_OUTPUT_BYTES)) {
+            throw new Error("unsafe Mikie global shim");
+          }
+          const backup = source.existed ? path.join(transactionRoot, `shim-${index}`) : null;
+          if (source.existed) await atomicWritePrivate(backup, source.bytes);
+          shims.push({
+            path: shimPath,
+            ...source,
+            backup,
+            mode: metadata ? metadata.mode & 0o777 : 0o600,
+            sourceFingerprint: bytesFingerprint(source.existed, source.bytes),
+            expectedFingerprint: null,
+            activationStaging: path.join(
+              path.dirname(shimPath),
+              `.${path.basename(shimPath)}.mikie-candidate-${lease.token}`,
+            ),
+            priorQuarantine: path.join(
+              path.dirname(shimPath),
+              `.${path.basename(shimPath)}.mikie-prior-${lease.token}`,
+            ),
+            activationState: null,
+          });
+        }
+        const providerConfig = [];
+        for (const [index, [name, filePath]] of Object.entries(providerPaths).entries()) {
+          await assertNoLinkedAncestors(filePath);
+          const source = await readOptionalFile(filePath);
+          const backup = source.existed ? path.join(transactionRoot, `provider-${index}`) : null;
+          if (source.existed) await atomicWritePrivate(backup, source.bytes);
+          providerConfig.push({
+            name,
+            path: filePath,
+            ...source,
+            backup,
+            sourceFingerprint: bytesFingerprint(source.existed, source.bytes),
+          });
+        }
+        const registration = providerConfig.find(({ name }) => name === "registration");
+        const settings = providerConfig.find(({ name }) => name === "settings");
+        const snapshot = {
+          backupRoot: transactionRoot,
+          lease,
+          autoLease,
+          phase: "prepared",
+          stagingPrefix: path.join(transactionRoot, "candidate-prefix"),
+          preparedCandidate: null,
+          recovery: null,
+          installation,
+          shims,
+          providerConfig,
+          foreign: {
+            registration: foreignRegistration(parseOptionalJson(registration)),
+            settings: foreignSettings(parseOptionalJson(settings), currentLayout.binary),
+          },
+          foreignOwnedV1: {
+            registration: foreignRegistration(parseOptionalJson(registration)),
+            settings: foreignSettings(parseOptionalJson(settings), currentLayout.binary, {
+              removeOwnedV1: true,
+            }),
+          },
+        };
+        await writeJournal(snapshot);
+        return snapshot;
+      } catch (error) {
+        await rm(transactionRoot, { recursive: true, force: true });
+        if (autoLease) await releaseLease(lease);
+        throw error;
+      }
+    },
+    async markInstalling(snapshot) {
+      snapshot.phase = "installing";
+      await writeJournal(snapshot);
+    },
+    stagingPrefix(snapshot) {
+      if (!snapshot || !isPathInside(transactionRoot, snapshot.stagingPrefix)) {
+        throw new Error("unsafe Mikie update staging prefix");
+      }
+      return snapshot.stagingPrefix;
+    },
+    finalLauncher() {
+      return currentLayout.binary;
+    },
+    async recordPreparedCandidate(snapshot, candidate, finalLauncher) {
+      const candidateRoots = validateInstallationLayout(candidate);
+      if (
+        !isPathInside(snapshot.stagingPrefix, candidateRoots.wrapperRoot) ||
+        !isPathInside(snapshot.stagingPrefix, candidateRoots.platformRoot) ||
+        !isPathInside(snapshot.stagingPrefix, candidate.binary) ||
+        candidateRoots.shims.length !== currentShims.length ||
+        candidateRoots.shims.some(
+          (shim, index) =>
+            !isPathInside(snapshot.stagingPrefix, shim) ||
+            path.basename(shim).toLowerCase() !== path.basename(currentShims[index]).toLowerCase(),
+        ) ||
+        !sameExecutablePath(finalLauncher, currentLayout.binary)
+      ) {
+        throw new Error("unsafe Mikie staged candidate");
+      }
+      const [wrapperFingerprint, platformFingerprint] = await Promise.all([
+        directoryFingerprint(candidateRoots.wrapperRoot),
+        directoryFingerprint(candidateRoots.platformRoot),
+      ]);
+      const shimFingerprints = await Promise.all(
+        candidateRoots.shims.map(async (shim) => {
+          const current = await readOptionalFile(shim);
+          if (!current.existed || current.bytes.length > MAX_COMMAND_OUTPUT_BYTES) {
+            throw new Error("incomplete Mikie staged candidate");
+          }
+          return { path: shim, fingerprint: bytesFingerprint(true, current.bytes) };
+        }),
+      );
+      if ([wrapperFingerprint, platformFingerprint].includes("absent")) {
+        throw new Error("incomplete Mikie staged candidate");
+      }
+      snapshot.preparedCandidate = {
+        ...candidate,
+        wrapperFingerprint,
+        platformFingerprint,
+        shims: candidateRoots.shims,
+        shimFingerprints,
+        finalLauncher,
+      };
+      const runtime = path.join(transactionRoot, "recovery-runtime.mjs");
+      const launcher = path.join(transactionRoot, "recover.mjs");
+      const descriptor = path.join(transactionRoot, "recovery.json");
+      const runtimeBytes = await readFile(fileURLToPath(import.meta.url));
+      if (runtimeBytes.length > MAX_RECOVERY_ARTIFACT_BYTES) {
+        throw new Error("Mikie update recovery runtime is too large");
+      }
+      const launcherBytes = Buffer.from(RECOVERY_LAUNCHER_SOURCE);
+      await atomicWritePrivate(runtime, runtimeBytes);
+      await atomicWritePrivate(launcher, launcherBytes);
+      const recoveryDescriptor = {
+        schema_version: RECOVERY_SCHEMA,
+        token: snapshot.lease.token,
+        transaction_root: transactionRoot,
+        current_layout: currentLayout,
+        provider_paths: providerPaths,
+        runtime,
+        runtime_sha256: sha256Bytes(runtimeBytes),
+        launcher,
+        launcher_sha256: sha256Bytes(launcherBytes),
+        node: process.execPath,
+        candidate_binary: candidate.binary,
+        final_launcher: finalLauncher,
+      };
+      const descriptorBytes = Buffer.from(`${JSON.stringify(recoveryDescriptor)}\n`);
+      await atomicWritePrivate(descriptor, descriptorBytes);
+      snapshot.recovery = {
+        descriptor,
+        descriptorSha256: sha256Bytes(descriptorBytes),
+        launcher,
+        launcherSha256: recoveryDescriptor.launcher_sha256,
+        runtime,
+        runtimeSha256: recoveryDescriptor.runtime_sha256,
+        node: process.execPath,
+        command: authenticatedRecoveryInvocation(
+          transactionRoot,
+          sha256Bytes(descriptorBytes),
+        ).command,
+      };
+      snapshot.phase = "candidate_staged";
+      await writeJournal(snapshot);
+      return snapshot.recovery.command;
+    },
+    async checkpointCandidate(snapshot) {
+      for (const entry of snapshot.installation) {
+        if (
+          !entry.expectedFingerprint ||
+          (await directoryFingerprint(entry.root)) !== entry.expectedFingerprint
+        ) {
+          throw new Error("package changed during Mikie activation");
+        }
+      }
+      for (const entry of snapshot.shims) {
+        const current = await readOptionalFile(entry.path);
+        if (
+          !entry.expectedFingerprint ||
+          bytesFingerprint(current.existed, current.bytes) !== entry.expectedFingerprint
+        ) {
+          throw new Error("global shim changed during Mikie activation");
+        }
+      }
+      snapshot.phase = "candidate_packages";
+      await writeJournal(snapshot);
+    },
+    async markProviderPreparing(snapshot) {
+      snapshot.phase = "provider_preparing";
+      await writeJournal(snapshot);
+    },
+    async markProviderRolledBack(snapshot) {
+      snapshot.phase = "provider_rolled_back";
+      await writeJournal(snapshot);
+    },
+    async prepareActivation(snapshot, candidate) {
+      if (!snapshot?.preparedCandidate || snapshot.preparedCandidate.binary !== candidate?.binary) {
+        throw new Error("staged candidate activation authority is unavailable");
+      }
+      const expectedPackages = new Map([
+        [path.resolve(currentRoots.wrapperRoot), snapshot.preparedCandidate.wrapperFingerprint],
+        [path.resolve(currentRoots.platformRoot), snapshot.preparedCandidate.platformFingerprint],
+      ]);
+      for (const entry of snapshot.installation) {
+        const expected = expectedPackages.get(path.resolve(entry.root));
+        if (!expected) throw new Error("staged candidate package authority is incomplete");
+        entry.expectedFingerprint = expected;
+      }
+      for (const [index, entry] of snapshot.shims.entries()) {
+        const prepared = snapshot.preparedCandidate.shimFingerprints[index];
+        if (
+          !prepared ||
+          path.basename(prepared.path).toLowerCase() !== path.basename(entry.path).toLowerCase()
+        ) {
+          throw new Error("staged candidate shim authority is incomplete");
+        }
+        entry.expectedFingerprint = prepared.fingerprint;
+      }
+      snapshot.phase = "activation_prepared";
+      await writeJournal(snapshot);
+    },
+    async promotePreparedCandidate(snapshot, candidate) {
+      if (
+        snapshot?.phase !== "activation_prepared" ||
+        !snapshot.preparedCandidate ||
+        !sameExecutablePath(snapshot.preparedCandidate.wrapperPackageJson, candidate?.wrapperPackageJson) ||
+        !sameExecutablePath(
+          snapshot.preparedCandidate.platformPackageJson,
+          candidate?.platformPackageJson,
+        ) ||
+        !sameExecutablePath(snapshot.preparedCandidate.binary, candidate?.binary) ||
+        snapshot.preparedCandidate.shims.length !== (candidate?.shims ?? []).length ||
+        snapshot.preparedCandidate.shims.some(
+          (shim, index) => !sameExecutablePath(shim, candidate.shims[index]),
+        )
+      ) {
+        throw new Error("staged candidate activation authority is unavailable");
+      }
+      const candidateRoots = validateInstallationLayout(candidate);
+      const packageSources = new Map([
+        [path.resolve(currentRoots.wrapperRoot), candidateRoots.wrapperRoot],
+        [path.resolve(currentRoots.platformRoot), candidateRoots.platformRoot],
+      ]);
+      for (const entry of snapshot.installation) {
+        const candidateRoot = packageSources.get(path.resolve(entry.root));
+        if (!candidateRoot || !entry.expectedFingerprint) {
+          throw new Error("staged candidate package authority is incomplete");
+        }
+        await assertNoLinkedAncestors(path.dirname(entry.root));
+        if (
+          (await directoryFingerprint(entry.activationStaging)) !== "absent" ||
+          (await directoryFingerprint(entry.priorQuarantine)) !== "absent"
+        ) {
+          throw new Error("Mikie activation staging path is not empty");
+        }
+        entry.activationState = "copying";
+        await writeJournal(snapshot);
+        await activationBoundary?.("copying", entry.root, entry.activationStaging);
+        await cp(candidateRoot, entry.activationStaging, {
+          recursive: true,
+          force: false,
+          errorOnExist: true,
+        });
+        if ((await directoryFingerprint(entry.activationStaging)) !== entry.expectedFingerprint) {
+          throw new Error("staged candidate package copy verification failed");
+        }
+        entry.activationState = "prepared";
+        await writeJournal(snapshot);
+      }
+      for (const [index, entry] of snapshot.shims.entries()) {
+        const preparedShim = snapshot.preparedCandidate.shimFingerprints[index];
+        const candidateState = await readShimState(preparedShim.path);
+        if (
+          !candidateState.existed ||
+          candidateState.fingerprint !== entry.expectedFingerprint
+        ) {
+          throw new Error("staged candidate shim authority is incomplete");
+        }
+        if (
+          (await readShimState(entry.activationStaging)).existed ||
+          (await readShimState(entry.priorQuarantine)).existed
+        ) {
+          throw new Error("Mikie shim activation staging path is not empty");
+        }
+        entry.activationState = "copying";
+        await writeJournal(snapshot);
+        await activationBoundary?.("shim_copying", entry.path, entry.activationStaging);
+        await atomicCreatePrivate(entry.activationStaging, candidateState.bytes);
+        await chmod(entry.activationStaging, entry.mode);
+        if (
+          (await readShimState(entry.activationStaging)).fingerprint !==
+          entry.expectedFingerprint
+        ) {
+          throw new Error("staged candidate shim copy verification failed");
+        }
+        entry.activationState = "prepared";
+        await writeJournal(snapshot);
+      }
+      for (const entry of snapshot.installation) {
+        if ((await directoryFingerprint(entry.root)) !== entry.sourceFingerprint) {
+          throw new Error("package changed before Mikie activation");
+        }
+        entry.activationState = "swapping";
+        await writeJournal(snapshot);
+        await rename(entry.root, entry.priorQuarantine);
+        await activationBoundary?.(
+          "source_renamed",
+          entry.root,
+          entry.activationStaging,
+          entry.priorQuarantine,
+        );
+        const movedFingerprint = await directoryFingerprint(entry.priorQuarantine);
+        if (movedFingerprint !== entry.sourceFingerprint) {
+          entry.activationState = "conflict_detected";
+          await writeJournal(snapshot);
+          if ((await directoryFingerprint(entry.root)) === "absent") {
+            await rename(entry.priorQuarantine, entry.root);
+            if ((await directoryFingerprint(entry.root)) !== movedFingerprint) {
+              throw new Error("package changed while Mikie activation was committing");
+            }
+            entry.activationState = "conflict_restored";
+            await writeJournal(snapshot);
+          }
+          throw new Error("package changed while Mikie activation was committing");
+        }
+        entry.activationState = "source_moved";
+        await writeJournal(snapshot);
+        await activationBoundary?.("source_moved", entry.root);
+        await rename(entry.activationStaging, entry.root);
+        if ((await directoryFingerprint(entry.root)) !== entry.expectedFingerprint) {
+          throw new Error("Mikie package activation verification failed");
+        }
+        entry.activationState = "activated";
+        await writeJournal(snapshot);
+      }
+      for (const entry of snapshot.shims) {
+        const current = await readShimState(entry.path);
+        if (current.fingerprint !== entry.sourceFingerprint) {
+          throw new Error("global shim changed before Mikie activation");
+        }
+        entry.activationState = "swapping";
+        await writeJournal(snapshot);
+        if (entry.existed) {
+          await rename(entry.path, entry.priorQuarantine);
+          await activationBoundary?.(
+            "shim_source_renamed",
+            entry.path,
+            entry.activationStaging,
+            entry.priorQuarantine,
+          );
+          const moved = await readShimState(entry.priorQuarantine);
+          if (moved.fingerprint !== entry.sourceFingerprint) {
+            entry.activationState = "conflict_detected";
+            await writeJournal(snapshot);
+            if (!(await readShimState(entry.path)).existed) {
+              await publishShimWithoutReplacement(
+                entry.priorQuarantine,
+                entry.path,
+                moved.fingerprint,
+              );
+              entry.activationState = "conflict_restored";
+              await writeJournal(snapshot);
+            }
+            throw new Error("global shim changed while Mikie activation was committing");
+          }
+        }
+        entry.activationState = "source_moved";
+        await writeJournal(snapshot);
+        await publishShimWithoutReplacement(
+          entry.activationStaging,
+          entry.path,
+          entry.expectedFingerprint,
+          () =>
+            activationBoundary?.(
+              "shim_published",
+              entry.path,
+              entry.activationStaging,
+              entry.priorQuarantine,
+            ),
+        );
+        await chmod(entry.path, entry.mode);
+        const activated = await readShimState(entry.path);
+        if (activated.fingerprint !== entry.expectedFingerprint) {
+          throw new Error("global shim activation verification failed");
+        }
+        entry.activationState = "activated";
+        await writeJournal(snapshot);
+      }
+    },
+    async decideCommit(snapshot, { settlementRequired = true } = {}) {
+      snapshot.phase = settlementRequired ? "commit_decided" : "commit_decided_no_repair";
+      await writeJournal(snapshot);
+    },
+    async locateCandidate(request) {
+      const candidate = await locateCandidate(request);
+      const candidateRoots = validateInstallationLayout(candidate);
+      if (request?.stagingPrefix !== undefined) {
+        const expectedStagingPrefix = path.join(transactionRoot, "candidate-prefix");
+        if (
+          !sameExecutablePath(request.stagingPrefix, expectedStagingPrefix) ||
+          !isPathInside(expectedStagingPrefix, candidateRoots.wrapperRoot) ||
+          !isPathInside(expectedStagingPrefix, candidateRoots.platformRoot) ||
+          candidateRoots.shims.some((shim) => !isPathInside(expectedStagingPrefix, shim))
+        ) {
+          throw new Error("unsafe Mikie update filesystem path");
+        }
+      } else if (
+        !sameExecutablePath(candidateRoots.wrapperRoot, currentRoots.wrapperRoot) ||
+        !sameExecutablePath(candidateRoots.platformRoot, currentRoots.platformRoot)
+      ) {
+        throw new Error("unsafe Mikie update filesystem path");
+      }
+      return candidate;
+    },
+    async verifyActivatedCandidate(prepared, activated) {
+      const preparedRoots = validateInstallationLayout(prepared);
+      const activatedRoots = validateInstallationLayout(activated);
+      if (preparedRoots.shims.length !== activatedRoots.shims.length) {
+        throw new Error("activated package does not match the staged candidate");
+      }
+      const [preparedWrapper, preparedPlatform, activatedWrapper, activatedPlatform] =
+        await Promise.all([
+          directoryFingerprint(preparedRoots.wrapperRoot),
+          directoryFingerprint(preparedRoots.platformRoot),
+          directoryFingerprint(activatedRoots.wrapperRoot),
+          directoryFingerprint(activatedRoots.platformRoot),
+        ]);
+      if (
+        preparedWrapper === "absent" ||
+        preparedPlatform === "absent" ||
+        preparedWrapper !== activatedWrapper ||
+        preparedPlatform !== activatedPlatform
+      ) {
+        throw new Error("activated package does not match the staged candidate");
+      }
+      for (const [index, preparedShim] of preparedRoots.shims.entries()) {
+        const [preparedState, activatedState] = await Promise.all([
+          readOptionalFile(preparedShim),
+          readOptionalFile(activatedRoots.shims[index]),
+        ]);
+        if (
+          !preparedState.existed ||
+          !activatedState.existed ||
+          !preparedState.bytes.equals(activatedState.bytes)
+        ) {
+          throw new Error("activated package does not match the staged candidate");
+        }
+      }
+    },
+    async readPackageVersion(packageJson) {
+      const metadata = JSON.parse(await readFile(packageJson, "utf8"));
+      return metadata.version;
+    },
+    async activate(candidate) {
+      const metadata = await stat(candidate.binary);
+      if (!metadata.isFile() || metadata.size === 0) {
+        throw new Error("candidate executable is invalid");
+      }
+    },
+    async verifyClaudeV2({ candidate, snapshot, repair }) {
+      if (
+        repair?.action === "refused" &&
+        ["foreign_conflict", "unavailable"].includes(repair.before)
+      ) {
+        const after = await Promise.all(
+          snapshot.providerConfig.map(async (entry) => ({
+            ...entry,
+            ...(await readOptionalFile(entry.path)),
+          })),
+        );
+        const preserved = after.every((entry, index) => {
+          const before = snapshot.providerConfig[index];
+          return entry.existed === before.existed && entry.bytes.equals(before.bytes);
+        });
+        return {
+          complete: preserved,
+          foreignPreserved: preserved,
+          foreignSettings: [`claude:${repair.before}`],
+        };
+      }
+      const [registration, settings, ownership] = await Promise.all([
+        readFile(providerPaths.registration).then(parseJsonNoDuplicateKeys),
+        readFile(providerPaths.settings).then(parseJsonNoDuplicateKeys),
+        readFile(providerPaths.ownership).then(parseJsonNoDuplicateKeys),
+      ]);
+      return verifyClaudeV2Contract({
+        candidateBinary: candidate.binary,
+        registration,
+        settings,
+        ownership,
+        foreign:
+          repair?.before === "outdated_owned" ? snapshot.foreignOwnedV1 : snapshot.foreign,
+      });
+    },
+    async restore(snapshot) {
+      await restoreSnapshot(snapshot);
+      if (snapshot.autoLease) await releaseLease(snapshot.lease);
+    },
+    async retire(snapshot) {
+      snapshot.phase = "committed";
+      await writeJournal(snapshot);
+      await cleanupCommittedActivation(snapshot);
+      await rm(snapshot.backupRoot, { recursive: true, force: true });
+      if (snapshot.autoLease) await releaseLease(snapshot.lease);
+    },
+  };
+  return adapter;
+}
+
+export async function recoverExternalNpmUpdate(transactionRoot, expectedAuthority) {
+  if (typeof transactionRoot !== "string" || !path.isAbsolute(transactionRoot)) {
+    throw new Error("unsafe Mikie update recovery root");
+  }
+  await assertNoLinkedAncestors(transactionRoot);
+  const descriptorPath = path.join(transactionRoot, "recovery.json");
+  const descriptorMetadata = await lstat(descriptorPath);
+  if (
+    !descriptorMetadata.isFile() ||
+    descriptorMetadata.isSymbolicLink() ||
+    descriptorMetadata.size > MAX_RECOVERY_ARTIFACT_BYTES
+  ) {
+    throw new Error("invalid Mikie update recovery descriptor");
+  }
+  const descriptorBytes = await readFile(descriptorPath);
+  const descriptor = parseJsonNoDuplicateKeys(descriptorBytes);
+  if (
+    !expectedAuthority ||
+    sha256Bytes(descriptorBytes) !== expectedAuthority.descriptorSha256 ||
+    !hasExactKeys(descriptor, [
+      "schema_version",
+      "token",
+      "transaction_root",
+      "current_layout",
+      "provider_paths",
+      "runtime",
+      "runtime_sha256",
+      "launcher",
+      "launcher_sha256",
+      "node",
+      "candidate_binary",
+      "final_launcher",
+    ]) ||
+    descriptor.schema_version !== RECOVERY_SCHEMA ||
+    descriptor.transaction_root !== transactionRoot ||
+    typeof descriptor.token !== "string" ||
+    ![descriptor.runtime, descriptor.launcher, descriptor.candidate_binary].every(
+      (artifactPath) =>
+        typeof artifactPath === "string" && isPathInside(transactionRoot, artifactPath),
+    ) ||
+    descriptor.final_launcher !== descriptor.current_layout?.binary ||
+    descriptor.node !== process.execPath ||
+    !/^[a-f0-9]{64}$/.test(descriptor.runtime_sha256) ||
+    !/^[a-f0-9]{64}$/.test(descriptor.launcher_sha256) ||
+    descriptor.runtime_sha256 !== expectedAuthority.runtimeSha256 ||
+    descriptor.launcher_sha256 !== expectedAuthority.launcherSha256
+  ) {
+    throw new Error("invalid Mikie update recovery descriptor");
+  }
+  const journalPath = path.join(transactionRoot, "journal.json");
+  const journalMetadata = await lstat(journalPath);
+  if (
+    !journalMetadata.isFile() ||
+    journalMetadata.isSymbolicLink() ||
+    journalMetadata.size > MAX_TRANSACTION_JOURNAL_BYTES
+  ) {
+    throw new Error("invalid Mikie update transaction journal");
+  }
+  const [runtimeBytes, launcherBytes, journalBytes] = await Promise.all([
+    readFile(descriptor.runtime),
+    readFile(descriptor.launcher),
+    readFile(journalPath),
+  ]);
+  if (
+    runtimeBytes.length > MAX_RECOVERY_ARTIFACT_BYTES ||
+    launcherBytes.length > MAX_RECOVERY_ARTIFACT_BYTES ||
+    sha256Bytes(runtimeBytes) !== descriptor.runtime_sha256 ||
+    sha256Bytes(launcherBytes) !== descriptor.launcher_sha256
+  ) {
+    throw new Error("tampered Mikie update recovery authority");
+  }
+  const journal = parseJsonNoDuplicateKeys(journalBytes);
+  if (journal?.token !== descriptor.token) {
+    throw new Error("Mikie update recovery authority does not match the journal");
+  }
+  const commands = createCommandAdapter();
+  const files = createFilesystemAdapter({
+    currentLayout: descriptor.current_layout,
+    locateCandidate: async () => {
+      throw new Error("candidate lookup is unavailable during recovery");
+    },
+    providerPaths: descriptor.provider_paths,
+    transactionRoot,
+    settleProviderRepair: async (phase, snapshot) => {
+      if (
+        snapshot?.preparedCandidate?.binary !== descriptor.candidate_binary ||
+        snapshot?.preparedCandidate?.finalLauncher !== descriptor.final_launcher
+      ) {
+        throw new Error("prepared candidate recovery authority changed");
+      }
+      const settlement = await commands.run(
+        descriptor.candidate_binary,
+        ["repair-claude-hooks-v1", "--json"],
+        {
+          shell: false,
+          capture: true,
+          environment: {
+            MIKIE_DISTRIBUTION_MODE: "npm",
+            MIKIE_NPM_UPDATE_TOPOLOGY: UpdateTopology.NpmGlobal,
+            MIKIE_NPM_UPDATE_REPAIR_PHASE: phase,
+            MIKIE_UPDATE_REPAIR_CANDIDATE: descriptor.candidate_binary,
+            MIKIE_UPDATE_REPAIR_LAUNCHER: descriptor.final_launcher,
+          },
+        },
+      );
+      if (settlement.code !== 0) {
+        throw new Error("candidate owned-adapter settlement failed");
+      }
+    },
+  });
+  const lease = await files.beginTransaction();
+  await files.endTransaction(lease);
+}