@getmikie/cli 1.1.103 → 1.1.104

package/bin/mikie.mjs

@@ -9,7 +9,12 @@ import { fileURLToPath } from "node:url";
 import {
   launchNativeCaptured,
   launchNative,
+  abandonMaterializedRuntime,
+  materializeWindowsRuntime,
+  materializePortableRuntime,
   prepareNativeLaunch,
+  retireHistoricalWindowsRuntimes,
+  retireHistoricalRuntimes,
   resolveDependencyPackageJson,
   resolveNativeBinary,
   selectPlatformPackage,
@@ -26,6 +31,10 @@ import {
   parseTrajectoryReconciliationReceipt,
   runUpdateTransaction,
 } from "../lib/update.mjs";
+import {
+  installedClientRuntimeDigests,
+  reconcileInstalledClients,
+} from "../scripts/reconcile-install.mjs";
 
 const require = createRequire(import.meta.url);
 const packageMetadata = require("../package.json");
@@ -143,7 +152,31 @@ All commands execute the compiled Mikie native engine.`);
         ownership: path.join(customerHome, ".claude", "mikie-evidence-hook-ownership.json"),
       },
       transactionRoot,
-      settleProviderRepair: async (phase, snapshot) => {
+      prepareFinalLauncher: (candidate, version) =>
+        process.platform === "win32"
+          ? materializeWindowsRuntime(candidate.binary, {
+              version,
+              cleanupHistorical: false,
+            })
+          : materializePortableRuntime(candidate.binary, {
+              version,
+              cleanupHistorical: false,
+            }),
+      retireFinalLauncher: async ({ path: launcher, sha256 }) => {
+        const preserveSha256 = await installedClientRuntimeDigests();
+        return process.platform === "win32"
+          ? retireHistoricalWindowsRuntimes(launcher, {
+              expectedSha256: sha256,
+              preserveSha256,
+            })
+          : retireHistoricalRuntimes(launcher, {
+              expectedSha256: sha256,
+              preserveSha256,
+            });
+      },
+      abandonFinalLauncher: ({ path: launcher, sha256 }) =>
+        abandonMaterializedRuntime(launcher, { expectedSha256: sha256 }),
+      settleProviderRepair: async (phase, snapshot, launcherState) => {
         const settlementBinary = snapshot?.preparedCandidate?.binary;
         const finalLauncher = snapshot?.preparedCandidate?.finalLauncher;
         if (!settlementBinary || !finalLauncher) {
@@ -156,6 +189,8 @@ All commands execute the compiled Mikie native engine.`);
             MIKIE_DISTRIBUTION_MODE: "npm",
             MIKIE_NPM_UPDATE_TOPOLOGY: UpdateTopology.NpmGlobal,
             MIKIE_NPM_UPDATE_REPAIR_PHASE: phase,
+            MIKIE_UPDATE_REPAIR_LAUNCHER_STATE:
+              launcherState ?? (phase === "commit" ? "activated" : "prior"),
             MIKIE_UPDATE_REPAIR_CANDIDATE: settlementBinary,
             MIKIE_UPDATE_REPAIR_LAUNCHER: finalLauncher,
           },
@@ -191,6 +226,8 @@ All commands execute the compiled Mikie native engine.`);
       for (const setting of result.foreignSettings) {
         console.log(`Preserved foreign setting: ${setting}`);
       }
+    } else if (result.status === "reconciled") {
+      console.log(`Reconciled Mikie ${result.version} client launchers.`);
     }
   } catch (error) {
     const message = error instanceof Error ? error.message : "Mikie update failed";
@@ -199,6 +236,7 @@ All commands execute the compiled Mikie native engine.`);
   }
 } else {
   try {
+    await reconcileInstalledClients({ version: packageMetadata.version });
     const nativeArguments = translateArguments(arguments_);
     const binary = await prepareNativeLaunch(await resolveNativeBinary(), nativeArguments, {
       version: packageMetadata.version,

package/lib/launcher.mjs

@@ -1,7 +1,19 @@
 import { createRequire } from "node:module";
 import { createHash, randomUUID } from "node:crypto";
 import { constants as fsConstants, createReadStream } from "node:fs";
-import { access, copyFile, lstat, mkdir, readdir, rename, rm, stat } from "node:fs/promises";
+import {
+  access,
+  copyFile,
+  lstat,
+  mkdir,
+  open,
+  readFile,
+  readdir,
+  rename,
+  rm,
+  rmdir,
+  stat,
+} from "node:fs/promises";
 import path from "node:path";
 import { spawn } from "node:child_process";
 
@@ -22,6 +34,10 @@ const MAX_CAPTURED_OUTPUT_BYTES = 1024 * 1024;
 const SAFE_RUNTIME_VERSION = /^[0-9A-Za-z][0-9A-Za-z._-]{0,127}$/;
 const SAFE_RUNTIME_DIRECTORY = /^[0-9A-Za-z][0-9A-Za-z._-]{0,127}-[0-9a-f]{64}$/;
 const HISTORICAL_RUNTIME_GRACE_MS = 24 * 60 * 60 * 1000;
+const MAX_RETAINED_WINDOWS_RUNTIMES = 8;
+const MAX_MATERIALIZED_WINDOWS_RUNTIMES = MAX_RETAINED_WINDOWS_RUNTIMES + 1;
+const ABANDONED_RUNTIME_SCHEMA = "mikie.windows-runtime-abandonment.v1";
+const SAFE_ABANDONMENT_MARKER = /^abandon-[0-9a-f]{64}\.json$/;
 
 async function sha256File(file) {
   const digest = createHash("sha256");
@@ -47,20 +63,33 @@ async function verifyMaterializedRuntime(file, expectedSha256, { allowMissing =
   }
 }
 
-async function cleanupHistoricalWindowsRuntimes(runtimeRoot, selectedDirectory) {
+async function cleanupHistoricalWindowsRuntimes(
+  runtimeRoot,
+  selectedDirectory,
+  { graceMs = HISTORICAL_RUNTIME_GRACE_MS, preserveSha256 = [] } = {},
+) {
+  if (
+    !Array.isArray(preserveSha256) ||
+    preserveSha256.length > MAX_MATERIALIZED_WINDOWS_RUNTIMES ||
+    preserveSha256.some((digest) => !/^[0-9a-f]{64}$/.test(digest))
+  ) {
+    throw new Error("Mikie cached runtime preservation authority is invalid");
+  }
+  const preserved = new Set(preserveSha256);
   let entries;
   try {
     entries = await readdir(runtimeRoot, { withFileTypes: true });
   } catch {
     return;
   }
-  const cutoff = Date.now() - HISTORICAL_RUNTIME_GRACE_MS;
+  const cutoff = Date.now() - graceMs;
   await Promise.all(
     entries.map(async (entry) => {
       if (
         !entry.isDirectory() ||
         entry.name === selectedDirectory ||
-        !SAFE_RUNTIME_DIRECTORY.test(entry.name)
+        !SAFE_RUNTIME_DIRECTORY.test(entry.name) ||
+        [...preserved].some((digest) => entry.name.endsWith(`-${digest}`))
       ) {
         return;
       }
@@ -75,35 +104,344 @@ async function cleanupHistoricalWindowsRuntimes(runtimeRoot, selectedDirectory)
   );
 }
 
+function abandonmentMarkerForExecutable(
+  runtimeRoot,
+  selectedDirectory,
+  expectedSha256,
+  executable,
+) {
+  const value = {
+    schema_version: ABANDONED_RUNTIME_SCHEMA,
+    directory: selectedDirectory,
+    executable,
+    sha256: expectedSha256,
+  };
+  const bytes = Buffer.from(`${JSON.stringify(value)}\n`);
+  const name = `abandon-${createHash("sha256").update(bytes).digest("hex")}.json`;
+  return { path: path.join(runtimeRoot, name), value, bytes };
+}
+
+async function removeAbandonedRuntime(runtimeRoot, markerPath, value) {
+  const runtimeDirectory = path.join(runtimeRoot, value.directory);
+  const binary = path.join(runtimeDirectory, value.executable);
+  let directoryMetadata;
+  try {
+    directoryMetadata = await lstat(runtimeDirectory);
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      await rm(markerPath, { force: true });
+      return true;
+    }
+    throw error;
+  }
+  if (!directoryMetadata.isDirectory() || directoryMetadata.isSymbolicLink()) {
+    throw new Error("Mikie abandoned Windows runtime authority is invalid");
+  }
+  const entries = await readdir(runtimeDirectory, { withFileTypes: true });
+  if (entries.length === 0) {
+    try {
+      await rmdir(runtimeDirectory);
+      await rm(markerPath, { force: true });
+      return true;
+    } catch (error) {
+      if (["EACCES", "EBUSY", "EPERM", "ENOTEMPTY"].includes(error?.code)) return false;
+      throw error;
+    }
+  }
+  if (
+    entries.length !== 1 ||
+    entries[0].name !== value.executable ||
+    !entries[0].isFile() ||
+    entries[0].isSymbolicLink()
+  ) {
+    throw new Error("Mikie abandoned Windows runtime contents changed");
+  }
+  await verifyMaterializedRuntime(binary, value.sha256);
+  try {
+    await rm(binary, { force: false, maxRetries: 0 });
+    await rmdir(runtimeDirectory);
+    await rm(markerPath, { force: true });
+    return true;
+  } catch (error) {
+    if (["EACCES", "EBUSY", "EPERM", "ENOTEMPTY"].includes(error?.code)) return false;
+    throw error;
+  }
+}
+
+async function persistAbandonmentMarker(marker) {
+  const temporary = `${marker.path}.${process.pid}.${randomUUID()}.tmp`;
+  let handle;
+  try {
+    handle = await open(temporary, "wx", 0o600);
+    await handle.writeFile(marker.bytes);
+    await handle.sync();
+    await handle.close();
+    handle = undefined;
+    try {
+      await rename(temporary, marker.path);
+    } catch (error) {
+      if (
+        !["EEXIST", "EPERM"].includes(error?.code) ||
+        !(await readFile(marker.path)).equals(marker.bytes)
+      ) {
+        throw error;
+      }
+    }
+  } finally {
+    await handle?.close().catch(() => {});
+    await rm(temporary, { force: true }).catch(() => {});
+  }
+}
+
+async function scavengeAbandonedWindowsRuntimes(runtimeRoot) {
+  let entries;
+  try {
+    entries = await readdir(runtimeRoot, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === "ENOENT") return;
+    throw error;
+  }
+  const markers = entries.filter(
+    (entry) => entry.isFile() && !entry.isSymbolicLink() && SAFE_ABANDONMENT_MARKER.test(entry.name),
+  );
+  if (markers.length > MAX_MATERIALIZED_WINDOWS_RUNTIMES) {
+    throw new Error("Mikie abandoned Windows runtime inventory is invalid");
+  }
+  for (const entry of markers) {
+    const markerPath = path.join(runtimeRoot, entry.name);
+    const metadata = await lstat(markerPath);
+    if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.size > 1024) {
+      throw new Error("Mikie abandoned Windows runtime marker is invalid");
+    }
+    const bytes = await readFile(markerPath);
+    let value;
+    try {
+      value = JSON.parse(bytes.toString("utf8"));
+    } catch {
+      throw new Error("Mikie abandoned Windows runtime marker is invalid");
+    }
+    if (
+      value === null ||
+      typeof value !== "object" ||
+      Array.isArray(value) ||
+      Object.keys(value).sort().join(",") !== "directory,executable,schema_version,sha256" ||
+      value.schema_version !== ABANDONED_RUNTIME_SCHEMA ||
+      !SAFE_RUNTIME_DIRECTORY.test(value.directory ?? "") ||
+      !["mikie", "mikie.exe"].includes(value.executable) ||
+      !/^[0-9a-f]{64}$/.test(value.sha256 ?? "") ||
+      !value.directory.endsWith(`-${value.sha256}`)
+    ) {
+      throw new Error("Mikie abandoned Windows runtime marker is invalid");
+    }
+    const expected = abandonmentMarkerForExecutable(
+      runtimeRoot,
+      value.directory,
+      value.sha256,
+      value.executable,
+    );
+    if (entry.name !== path.basename(expected.path) || !bytes.equals(expected.bytes)) {
+      throw new Error("Mikie abandoned Windows runtime marker is invalid");
+    }
+    await removeAbandonedRuntime(runtimeRoot, markerPath, value);
+  }
+}
+
+async function enforceMaterializedRuntimeCapacity(runtimeRoot, selectedDirectory) {
+  await scavengeAbandonedWindowsRuntimes(runtimeRoot);
+  let entries;
+  try {
+    entries = await readdir(runtimeRoot, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === "ENOENT") return;
+    throw error;
+  }
+  const materialized = entries.filter(
+    (entry) => entry.isDirectory() && SAFE_RUNTIME_DIRECTORY.test(entry.name),
+  );
+  if (
+    materialized.some((entry) => entry.name === selectedDirectory) ||
+    materialized.length < MAX_MATERIALIZED_WINDOWS_RUNTIMES
+  ) {
+    return;
+  }
+  throw new Error(
+    "Mikie cached Windows runtime retention capacity is full; reconcile exact-owned clients before installing another runtime",
+  );
+}
+
+/** Retire one digest-pinned candidate after its update transaction fully rolled back. */
+export async function abandonMaterializedWindowsRuntime(
+  selectedBinary,
+  { expectedSha256 } = {},
+) {
+  if (
+    !path.isAbsolute(selectedBinary ?? "") ||
+    !/^[a-f0-9]{64}$/.test(expectedSha256 ?? "") ||
+    path.basename(selectedBinary).toLowerCase() !== "mikie.exe"
+  ) {
+    throw new Error("Mikie abandoned Windows runtime authority is invalid");
+  }
+  const selectedDirectory = path.dirname(selectedBinary);
+  const runtimeRoot = path.dirname(selectedDirectory);
+  const selectedName = path.basename(selectedDirectory);
+  if (
+    path.basename(runtimeRoot).toLowerCase() !== "runtime-v1" ||
+    !SAFE_RUNTIME_DIRECTORY.test(selectedName) ||
+    !selectedName.endsWith(`-${expectedSha256}`)
+  ) {
+    throw new Error("Mikie abandoned Windows runtime authority is invalid");
+  }
+  for (const directory of [runtimeRoot, selectedDirectory]) {
+    const metadata = await lstat(directory);
+    if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
+      throw new Error("Mikie abandoned Windows runtime authority is invalid");
+    }
+  }
+  await verifyMaterializedRuntime(selectedBinary, expectedSha256);
+  const marker = abandonmentMarkerForExecutable(
+    runtimeRoot,
+    selectedName,
+    expectedSha256,
+    "mikie.exe",
+  );
+  await persistAbandonmentMarker(marker);
+  await removeAbandonedRuntime(runtimeRoot, marker.path, marker.value);
+}
+
+/** Retire one cross-platform content-addressed candidate after a proven rollback. */
+export async function abandonMaterializedRuntime(selectedBinary, { expectedSha256 } = {}) {
+  if (path.basename(selectedBinary ?? "") === "mikie.exe") {
+    return abandonMaterializedWindowsRuntime(selectedBinary, { expectedSha256 });
+  }
+  if (
+    !path.isAbsolute(selectedBinary ?? "") ||
+    path.basename(selectedBinary) !== "mikie" ||
+    !/^[a-f0-9]{64}$/.test(expectedSha256 ?? "")
+  ) {
+    throw new Error("Mikie abandoned runtime authority is invalid");
+  }
+  const selectedDirectory = path.dirname(selectedBinary);
+  const runtimeRoot = path.dirname(selectedDirectory);
+  const selectedName = path.basename(selectedDirectory);
+  if (
+    path.basename(runtimeRoot) !== "runtime-v1" ||
+    !SAFE_RUNTIME_DIRECTORY.test(selectedName) ||
+    !selectedName.endsWith(`-${expectedSha256}`)
+  ) {
+    throw new Error("Mikie abandoned runtime authority is invalid");
+  }
+  await verifyMaterializedRuntime(selectedBinary, expectedSha256);
+  const marker = abandonmentMarkerForExecutable(
+    runtimeRoot,
+    selectedName,
+    expectedSha256,
+    "mikie",
+  );
+  await persistAbandonmentMarker(marker);
+  await removeAbandonedRuntime(runtimeRoot, marker.path, marker.value);
+}
+
+export async function retireHistoricalWindowsRuntimes(
+  selectedBinary,
+  { expectedSha256, preserveSha256 = [] } = {},
+) {
+  if (
+    !path.isAbsolute(selectedBinary ?? "") ||
+    !/^[a-f0-9]{64}$/.test(expectedSha256 ?? "") ||
+    path.basename(selectedBinary).toLowerCase() !== "mikie.exe"
+  ) {
+    throw new Error("Mikie cached Windows runtime retirement authority is invalid");
+  }
+  const selectedDirectory = path.dirname(selectedBinary);
+  const runtimeRoot = path.dirname(selectedDirectory);
+  const selectedName = path.basename(selectedDirectory);
+  if (
+    path.basename(runtimeRoot).toLowerCase() !== "runtime-v1" ||
+    !SAFE_RUNTIME_DIRECTORY.test(selectedName) ||
+    !selectedName.endsWith(`-${expectedSha256}`)
+  ) {
+    throw new Error("Mikie cached Windows runtime retirement authority is invalid");
+  }
+  for (const directory of [runtimeRoot, selectedDirectory]) {
+    const metadata = await lstat(directory);
+    if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
+      throw new Error("Mikie cached Windows runtime retirement authority is invalid");
+    }
+  }
+  await verifyMaterializedRuntime(selectedBinary, expectedSha256);
+  await cleanupHistoricalWindowsRuntimes(runtimeRoot, selectedName, {
+    graceMs: 0,
+    preserveSha256,
+  });
+}
+
+/** Retire content-addressed runtimes only after every owned client committed migration. */
+export async function retireHistoricalRuntimes(
+  selectedBinary,
+  { expectedSha256, preserveSha256 = [] } = {},
+) {
+  if (path.basename(selectedBinary ?? "") === "mikie.exe") {
+    return retireHistoricalWindowsRuntimes(selectedBinary, {
+      expectedSha256,
+      preserveSha256,
+    });
+  }
+  if (
+    !path.isAbsolute(selectedBinary ?? "") ||
+    path.basename(selectedBinary) !== "mikie" ||
+    !/^[a-f0-9]{64}$/.test(expectedSha256 ?? "")
+  ) {
+    throw new Error("Mikie cached runtime retirement authority is invalid");
+  }
+  const selectedDirectory = path.dirname(selectedBinary);
+  const runtimeRoot = path.dirname(selectedDirectory);
+  const selectedName = path.basename(selectedDirectory);
+  if (
+    path.basename(runtimeRoot) !== "runtime-v1" ||
+    !SAFE_RUNTIME_DIRECTORY.test(selectedName) ||
+    !selectedName.endsWith(`-${expectedSha256}`)
+  ) {
+    throw new Error("Mikie cached runtime retirement authority is invalid");
+  }
+  await verifyMaterializedRuntime(selectedBinary, expectedSha256);
+  await cleanupHistoricalWindowsRuntimes(runtimeRoot, selectedName, {
+    graceMs: 0,
+    preserveSha256,
+  });
+}
+
 export function shouldStageWindowsRuntime(arguments_) {
   if (arguments_.length === 0) return true;
-  if (["mcp", "serve", "run-relay"].includes(arguments_[0])) return true;
+  if (["mcp", "serve", "run-relay", "doctor"].includes(arguments_[0])) return true;
+  if (arguments_.length === 1 && arguments_[0] === "uninstall") return true;
+  if (
+    arguments_.length === 2 &&
+    arguments_[0] === "setup" &&
+    ["codex", "claude", "claude_code"].includes(arguments_[1])
+  ) {
+    return true;
+  }
   return arguments_[0] === "control" && arguments_[1] === "run";
 }
 
-export async function materializeWindowsRuntime(
+async function materializeRuntime(
   binary,
-  { version, localAppData = process.env.LOCALAPPDATA } = {},
+  { version, runtimeRoot, executableName, cleanupHistorical },
 ) {
-  if (
-    !path.isAbsolute(binary) ||
-    !path.isAbsolute(localAppData ?? "") ||
-    !SAFE_RUNTIME_VERSION.test(version ?? "")
-  ) {
-    throw new Error("Mikie cached Windows runtime authority is invalid");
-  }
   const sourceMetadata = await lstat(binary);
   if (!sourceMetadata.isFile() || sourceMetadata.isSymbolicLink() || sourceMetadata.size === 0) {
-    throw new Error("Mikie native Windows runtime is invalid");
+    throw new Error("Mikie native runtime is invalid");
   }
   const sourceSha256 = await sha256File(binary);
-  const runtimeRoot = path.join(localAppData, "Mikie", "runtime-v1");
   const selectedDirectory = `${version}-${sourceSha256}`;
   const runtimeDirectory = path.join(runtimeRoot, selectedDirectory);
-  const materialized = path.join(runtimeDirectory, "mikie.exe");
+  const materialized = path.join(runtimeDirectory, executableName);
+  await enforceMaterializedRuntimeCapacity(runtimeRoot, selectedDirectory);
   await mkdir(runtimeDirectory, { recursive: true });
   if (await verifyMaterializedRuntime(materialized, sourceSha256, { allowMissing: true })) {
-    await cleanupHistoricalWindowsRuntimes(runtimeRoot, selectedDirectory);
+    if (cleanupHistorical) {
+      await cleanupHistoricalWindowsRuntimes(runtimeRoot, selectedDirectory);
+    }
     return materialized;
   }
 
@@ -118,7 +456,7 @@ export async function materializeWindowsRuntime(
       sha256File(binary),
     ]);
     if (copiedSha256 !== sourceSha256 || stableSourceSha256 !== sourceSha256) {
-      throw new Error("Mikie native Windows runtime changed during materialization");
+      throw new Error("Mikie native runtime changed during materialization");
     }
     try {
       await rename(temporary, materialized);
@@ -131,13 +469,110 @@ export async function materializeWindowsRuntime(
       }
     }
     await verifyMaterializedRuntime(materialized, sourceSha256);
-    await cleanupHistoricalWindowsRuntimes(runtimeRoot, selectedDirectory);
+    if (cleanupHistorical) {
+      await cleanupHistoricalWindowsRuntimes(runtimeRoot, selectedDirectory);
+    }
     return materialized;
   } finally {
     await rm(temporary, { force: true }).catch(() => {});
   }
 }
 
+export async function materializeWindowsRuntime(
+  binary,
+  {
+    version,
+    localAppData = process.env.LOCALAPPDATA,
+    cleanupHistorical = true,
+  } = {},
+) {
+  if (
+    !path.isAbsolute(binary) ||
+    !path.isAbsolute(localAppData ?? "") ||
+    !SAFE_RUNTIME_VERSION.test(version ?? "")
+  ) {
+    throw new Error("Mikie cached Windows runtime authority is invalid");
+  }
+  return materializeRuntime(binary, {
+    version,
+    runtimeRoot: path.join(localAppData, "Mikie", "runtime-v1"),
+    executableName: "mikie.exe",
+    cleanupHistorical,
+  });
+}
+
+function portableRuntimeRoot(platform, environment) {
+  if (platform === "win32") {
+    return path.join(environment.LOCALAPPDATA ?? "", "Mikie", "runtime-v1");
+  }
+  if (platform === "darwin") {
+    return path.join(
+      environment.HOME ?? "",
+      "Library",
+      "Application Support",
+      "Mikie",
+      "runtime-v1",
+    );
+  }
+  const state = environment.XDG_STATE_HOME || path.join(environment.HOME ?? "", ".local", "state");
+  return path.join(state, "mikie", "runtime-v1");
+}
+
+/** Derive the one immutable runtime path bound to package version and bytes. */
+export function materializedRuntimePath({
+  version,
+  sha256,
+  platform = process.platform,
+  environment = process.env,
+} = {}) {
+  const runtimeRoot = portableRuntimeRoot(platform, environment);
+  if (
+    !path.isAbsolute(runtimeRoot) ||
+    !SAFE_RUNTIME_VERSION.test(version ?? "") ||
+    !/^[0-9a-f]{64}$/.test(sha256 ?? "")
+  ) {
+    throw new Error("Mikie cached runtime authority is invalid");
+  }
+  return path.join(
+    runtimeRoot,
+    `${version}-${sha256}`,
+    platform === "win32" ? "mikie.exe" : "mikie",
+  );
+}
+
+/** Materialize an immutable runtime so npm package replacement never strands a client. */
+export async function materializePortableRuntime(
+  binary,
+  {
+    version,
+    platform = process.platform,
+    environment = process.env,
+    cleanupHistorical = true,
+  } = {},
+) {
+  const runtimeRoot = portableRuntimeRoot(platform, environment);
+  if (
+    !path.isAbsolute(binary) ||
+    !path.isAbsolute(runtimeRoot) ||
+    !SAFE_RUNTIME_VERSION.test(version ?? "")
+  ) {
+    throw new Error("Mikie cached runtime authority is invalid");
+  }
+  if (platform === "win32") {
+    return materializeWindowsRuntime(binary, {
+      version,
+      localAppData: environment.LOCALAPPDATA,
+      cleanupHistorical,
+    });
+  }
+  return materializeRuntime(binary, {
+    version,
+    runtimeRoot,
+    executableName: "mikie",
+    cleanupHistorical,
+  });
+}
+
 export async function prepareNativeLaunch(
   binary,
   arguments_,
@@ -147,12 +582,14 @@ export async function prepareNativeLaunch(
     environment = process.env,
   } = {},
 ) {
-  if (platform !== "win32" || !shouldStageWindowsRuntime(arguments_)) {
+  if (!shouldStageWindowsRuntime(arguments_)) {
     return binary;
   }
-  return materializeWindowsRuntime(binary, {
+  return materializePortableRuntime(binary, {
     version,
-    localAppData: environment.LOCALAPPDATA,
+    platform,
+    environment,
+    cleanupHistorical: false,
   });
 }