@getmikie/cli 1.1.120 → 1.1.123

package/README.md

@@ -9,7 +9,7 @@ npx --yes --ignore-scripts --registry=https://registry.npmjs.org @getmikie/cli@1
 For a persistent command path on Windows PowerShell:
 
 ```powershell
-npm.cmd install --global @getmikie/cli@1.1.108 --ignore-scripts --registry=https://registry.npmjs.org
+npm.cmd install --global @getmikie/cli@1.1.108 --allow-scripts=@getmikie/cli --registry=https://registry.npmjs.org
 ```
 
 Mikie does not change your PowerShell execution policy. Keep the exact package
@@ -19,11 +19,13 @@ incorrectly targets the current directory.
 For a persistent command path on macOS or Linux:
 
 ```sh
-npm install --global @getmikie/cli@1.1.108 --ignore-scripts --registry=https://registry.npmjs.org
+npm install --global @getmikie/cli@1.1.108 --allow-scripts=@getmikie/cli --registry=https://registry.npmjs.org
 ```
 
-These portable npm commands disable every lifecycle script and pin the public
-npm registry. The public OS installers additionally authenticate exact wrapper
+These persistent npm commands allow only `@getmikie/cli`'s reconciliation
+script and pin the public npm registry. npm 11.5.1 or newer is required for
+`--allow-scripts`; the temporary `npx` command above keeps scripts disabled.
+The public OS installers additionally authenticate exact wrapper
 and native tarball bytes, install them offline, and explicitly run only Mikie's
 authenticated reconciliation script.
 

package/bin/mikie.mjs

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 import { createRequire } from "node:module";
 import { homedir } from "node:os";
@@ -48,6 +48,7 @@ if (["--version", "-v"].includes(singleFlag)) {
   console.log(`Mikie ${packageMetadata.version}
 
 Usage:
+  mikie activity --mode solo|ai_assisted|unknown --language <category>
   mikie savings history [options]
   mikie savings export-meter-history
   mikie mcp [--adapter codex|claude_code]
@@ -92,7 +93,7 @@ All commands execute the compiled Mikie native engine.`);
     const selected = selectPlatformPackage();
     const platformPackageJson = require.resolve(`${selected.packageName}/package.json`);
     const wrapperPackageJson = fileURLToPath(new URL("../package.json", import.meta.url));
-    const binary = await resolveNativeBinary();
+    const binary = await resolveNativeBinary({ version: packageMetadata.version });
     const globalPrefix = npmPrefix.stdout.trim();
     const globalShims =
       process.platform === "win32"
@@ -150,7 +151,7 @@ All commands execute the compiled Mikie native engine.`);
         return {
           wrapperPackageJson,
           platformPackageJson: require.resolve(`${selected.packageName}/package.json`),
-          binary: await resolveNativeBinary(),
+          binary: await resolveNativeBinary({ version: packageMetadata.version }),
           shims: globalShims,
         };
       },
@@ -160,16 +161,20 @@ All commands execute the compiled Mikie native engine.`);
         ownership: path.join(customerHome, ".claude", "mikie-evidence-hook-ownership.json"),
       },
       transactionRoot,
-      prepareFinalLauncher: (candidate, version) =>
-        process.platform === "win32"
+      prepareFinalLauncher: async (candidate, version) => {
+        const preserveSha256 = await installedClientRuntimeDigests();
+        return process.platform === "win32"
           ? materializeWindowsRuntime(candidate.binary, {
               version,
               cleanupHistorical: false,
+              preserveSha256,
             })
           : materializePortableRuntime(candidate.binary, {
               version,
               cleanupHistorical: false,
-            }),
+              preserveSha256,
+            });
+      },
       retireFinalLauncher: async ({ path: launcher, sha256 }) => {
         const preserveSha256 = await installedClientRuntimeDigests();
         return process.platform === "win32"
@@ -239,19 +244,31 @@ All commands execute the compiled Mikie native engine.`);
     }
   } catch (error) {
     const message = error instanceof Error ? error.message : "Mikie update failed";
-    console.error(`mikie: ${message}`);
+    const guidance = message === "invalid Mikie update recovery authority"
+      ? "; keep the recovery files and contact support before retrying"
+      : "";
+    console.error(`mikie: ${message}${guidance}`);
     process.exitCode = 1;
   }
 } else {
   try {
     const nativeArguments = translateArguments(arguments_);
     if (shouldReconcileInstalledClients(nativeArguments)) {
-      await reconcileInstalledClients({ version: packageMetadata.version });
+      const clients = await reconcileInstalledClients({
+        version: packageMetadata.version,
+        allowDeferred: nativeArguments[0] === "serve",
+      });
+      if (clients.status === "deferred") {
+        console.error("mikie: client repair deferred; relay startup continues. Run `mikie doctor` to inspect client registration.");
+      }
     }
     const binary = await prepareNativeLaunch(await resolveNativeBinary(), nativeArguments, {
       version: packageMetadata.version,
     });
     process.exitCode = await launchNative(binary, nativeArguments);
+    if (nativeArguments[0] === "serve" && process.exitCode !== 0) {
+      console.error(`mikie: Mikie relay exited with status ${process.exitCode}; run \`mikie doctor\`, then retry the MCP session`);
+    }
   } catch (error) {
     const message = error instanceof Error ? error.message : "Mikie is unavailable";
     console.error(`mikie: ${message}`);

package/lib/launcher.mjs

@@ -20,7 +20,6 @@ import { spawn } from "node:child_process";
 const PLATFORM_PACKAGES = new Map([
   ["win32-x64", { packageName: "@getmikie/win32-x64", binaryPath: "bin/mikie.exe" }],
   ["darwin-arm64", { packageName: "@getmikie/darwin-arm64", binaryPath: "bin/mikie" }],
-  ["darwin-x64", { packageName: "@getmikie/darwin-x64", binaryPath: "bin/mikie" }],
   ["linux-x64-gnu", { packageName: "@getmikie/linux-x64-gnu", binaryPath: "bin/mikie" }],
 ]);
 
@@ -68,13 +67,7 @@ async function cleanupHistoricalWindowsRuntimes(
   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");
-  }
+  validateRuntimePreservation(preserveSha256);
   const preserved = new Set(preserveSha256);
   let entries;
   try {
@@ -104,6 +97,68 @@ async function cleanupHistoricalWindowsRuntimes(
   );
 }
 
+function validateRuntimePreservation(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");
+  }
+}
+
+async function evictStaleUnreferencedWindowsRuntimes(
+  runtimeRoot,
+  selectedDirectory,
+  preserveSha256,
+) {
+  validateRuntimePreservation(preserveSha256);
+  let entries;
+  try {
+    entries = await readdir(runtimeRoot, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  const materialized = entries.filter(
+    (entry) => entry.isDirectory() && SAFE_RUNTIME_DIRECTORY.test(entry.name),
+  );
+  const preserved = new Set(preserveSha256);
+  const cutoff = Date.now() - HISTORICAL_RUNTIME_GRACE_MS;
+  const candidates = [];
+  for (const entry of materialized) {
+    if (
+      entry.name === selectedDirectory ||
+      [...preserved].some((digest) => entry.name.endsWith(`-${digest}`))
+    ) {
+      continue;
+    }
+    const candidate = path.join(runtimeRoot, entry.name);
+    try {
+      const metadata = await lstat(candidate);
+      if (metadata.mtimeMs <= cutoff) {
+        candidates.push({ candidate, mtimeMs: metadata.mtimeMs });
+      }
+    } catch {
+      // A concurrent removal is already freeing capacity; re-count below.
+    }
+  }
+  candidates.sort((left, right) => left.mtimeMs - right.mtimeMs);
+  const required = Math.max(
+    0,
+    materialized.length - (MAX_MATERIALIZED_WINDOWS_RUNTIMES - 1),
+  );
+  let removed = 0;
+  for (const { candidate } of candidates) {
+    if (removed >= required) break;
+    try {
+      await rm(candidate, { recursive: true, force: true, maxRetries: 0 });
+      removed += 1;
+    } catch {
+      // Active Windows executables remain locked and are retained safely.
+    }
+  }
+}
+
 function abandonmentMarkerForExecutable(
   runtimeRoot,
   selectedDirectory,
@@ -246,7 +301,12 @@ async function scavengeAbandonedWindowsRuntimes(runtimeRoot) {
   }
 }
 
-async function enforceMaterializedRuntimeCapacity(runtimeRoot, selectedDirectory) {
+async function enforceMaterializedRuntimeCapacity(
+  runtimeRoot,
+  selectedDirectory,
+  { preserveSha256 = [] } = {},
+) {
+  validateRuntimePreservation(preserveSha256);
   await scavengeAbandonedWindowsRuntimes(runtimeRoot);
   let entries;
   try {
@@ -264,6 +324,25 @@ async function enforceMaterializedRuntimeCapacity(runtimeRoot, selectedDirectory
   ) {
     return;
   }
+  await evictStaleUnreferencedWindowsRuntimes(
+    runtimeRoot,
+    selectedDirectory,
+    preserveSha256,
+  );
+  let remaining;
+  try {
+    remaining = (await readdir(runtimeRoot, { withFileTypes: true })).filter(
+      (entry) => entry.isDirectory() && SAFE_RUNTIME_DIRECTORY.test(entry.name),
+    );
+  } catch {
+    remaining = materialized;
+  }
+  if (
+    remaining.some((entry) => entry.name === selectedDirectory) ||
+    remaining.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",
   );
@@ -412,7 +491,7 @@ export async function retireHistoricalRuntimes(
 
 export function shouldStageWindowsRuntime(arguments_) {
   if (arguments_.length === 0) return true;
-  if (["mcp", "serve", "run-relay", "doctor"].includes(arguments_[0])) return true;
+  if (["mcp", "serve", "run-relay"].includes(arguments_[0])) return true;
   if (arguments_.length === 1 && arguments_[0] === "uninstall") return true;
   if (
     arguments_.length === 2 &&
@@ -421,6 +500,17 @@ export function shouldStageWindowsRuntime(arguments_) {
   ) {
     return true;
   }
+  if (arguments_[0] === "mode" && arguments_[1] === "codex") {
+    const modeArguments = arguments_.slice(2);
+    return (
+      modeArguments.length === 0 ||
+      (modeArguments.length === 1 &&
+        ["active", "shadow", "--json"].includes(modeArguments[0])) ||
+      (modeArguments.length === 2 &&
+        ["active", "shadow"].includes(modeArguments[0]) &&
+        modeArguments[1] === "--json")
+    );
+  }
   return arguments_[0] === "control" && arguments_[1] === "run";
 }
 
@@ -431,7 +521,7 @@ export function shouldReconcileInstalledClients(arguments_) {
 
 async function materializeRuntime(
   binary,
-  { version, runtimeRoot, executableName, cleanupHistorical },
+  { version, runtimeRoot, executableName, cleanupHistorical, preserveSha256 },
 ) {
   const sourceMetadata = await lstat(binary);
   if (!sourceMetadata.isFile() || sourceMetadata.isSymbolicLink() || sourceMetadata.size === 0) {
@@ -441,11 +531,15 @@ async function materializeRuntime(
   const selectedDirectory = `${version}-${sourceSha256}`;
   const runtimeDirectory = path.join(runtimeRoot, selectedDirectory);
   const materialized = path.join(runtimeDirectory, executableName);
-  await enforceMaterializedRuntimeCapacity(runtimeRoot, selectedDirectory);
+  await enforceMaterializedRuntimeCapacity(runtimeRoot, selectedDirectory, {
+    preserveSha256,
+  });
   await mkdir(runtimeDirectory, { recursive: true });
   if (await verifyMaterializedRuntime(materialized, sourceSha256, { allowMissing: true })) {
     if (cleanupHistorical) {
-      await cleanupHistoricalWindowsRuntimes(runtimeRoot, selectedDirectory);
+      await cleanupHistoricalWindowsRuntimes(runtimeRoot, selectedDirectory, {
+        preserveSha256,
+      });
     }
     return materialized;
   }
@@ -475,7 +569,9 @@ async function materializeRuntime(
     }
     await verifyMaterializedRuntime(materialized, sourceSha256);
     if (cleanupHistorical) {
-      await cleanupHistoricalWindowsRuntimes(runtimeRoot, selectedDirectory);
+      await cleanupHistoricalWindowsRuntimes(runtimeRoot, selectedDirectory, {
+        preserveSha256,
+      });
     }
     return materialized;
   } finally {
@@ -489,6 +585,7 @@ export async function materializeWindowsRuntime(
     version,
     localAppData = process.env.LOCALAPPDATA,
     cleanupHistorical = true,
+    preserveSha256 = [],
   } = {},
 ) {
   if (
@@ -503,6 +600,7 @@ export async function materializeWindowsRuntime(
     runtimeRoot: path.join(localAppData, "Mikie", "runtime-v1"),
     executableName: "mikie.exe",
     cleanupHistorical,
+    preserveSha256,
   });
 }
 
@@ -553,6 +651,7 @@ export async function materializePortableRuntime(
     platform = process.platform,
     environment = process.env,
     cleanupHistorical = true,
+    preserveSha256 = [],
   } = {},
 ) {
   const runtimeRoot = portableRuntimeRoot(platform, environment);
@@ -568,6 +667,7 @@ export async function materializePortableRuntime(
       version,
       localAppData: environment.LOCALAPPDATA,
       cleanupHistorical,
+      preserveSha256,
     });
   }
   return materializeRuntime(binary, {
@@ -575,9 +675,46 @@ export async function materializePortableRuntime(
     runtimeRoot,
     executableName: "mikie",
     cleanupHistorical,
+    preserveSha256,
   });
 }
 
+/** Inspect the existing pinned runtime without creating or reconciling any state. */
+async function inspectMaterializedRuntime(binary, { platform, version, environment }) {
+  if (!path.isAbsolute(binary)) {
+    throw new Error("Mikie packaged runtime authority is invalid");
+  }
+  const sourceMetadata = await lstat(binary);
+  if (!sourceMetadata.isFile() || sourceMetadata.isSymbolicLink() || sourceMetadata.size === 0) {
+    throw new Error("Mikie packaged runtime is invalid; reinstall the CLI before retrying doctor");
+  }
+  const sourceSha256 = await sha256File(binary);
+  const selected = materializedRuntimePath({ version, sha256: sourceSha256, platform, environment });
+  const repair = "run `mikie update`; if it cannot restore the runtime, contact support";
+  try {
+    for (const directory of [path.dirname(path.dirname(selected)), path.dirname(selected)]) {
+      const metadata = await lstat(directory);
+      if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
+        throw new Error("invalid runtime directory");
+      }
+    }
+    await verifyMaterializedRuntime(selected, sourceSha256);
+    if (platform !== "win32") await access(selected, fsConstants.X_OK);
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      throw new Error("Mikie installed runtime is missing; run `mikie setup codex` or `mikie setup claude` for your configured client, then retry `mikie doctor`");
+    }
+    if (error?.message === "Mikie cached Windows runtime hash does not match") {
+      throw new Error(`Mikie installed runtime does not match the packaged engine; ${repair}`);
+    }
+    throw new Error(`Mikie installed runtime is invalid or unreadable; ${repair}`);
+  }
+  if ((await sha256File(binary)) !== sourceSha256) {
+    throw new Error("Mikie packaged runtime changed during doctor inspection; retry after installation finishes");
+  }
+  return selected;
+}
+
 export async function prepareNativeLaunch(
   binary,
   arguments_,
@@ -585,8 +722,12 @@ export async function prepareNativeLaunch(
     platform = process.platform,
     version,
     environment = process.env,
+    preserveSha256 = [],
   } = {},
 ) {
+  if (arguments_[0] === "doctor") {
+    return inspectMaterializedRuntime(binary, { platform, version, environment });
+  }
   if (!shouldStageWindowsRuntime(arguments_)) {
     return binary;
   }
@@ -595,6 +736,7 @@ export async function prepareNativeLaunch(
     platform,
     environment,
     cleanupHistorical: false,
+    preserveSha256,
   });
 }
 
@@ -614,6 +756,12 @@ export function selectPlatformPackage({
 } = {}) {
   const key = platform === "linux" && glibc ? `${platform}-${arch}-gnu` : `${platform}-${arch}`;
   const selected = PLATFORM_PACKAGES.get(key);
+  if (!selected && key === "darwin-x64") {
+    throw new Error(
+      "Mikie no longer supports Intel Macs. The last version for this Mac is 1.1.121: " +
+        "npm install --global @getmikie/cli@1.1.121",
+    );
+  }
   if (!selected) {
     throw new Error("Mikie does not publish a native npm engine for this platform");
   }
@@ -645,6 +793,7 @@ export async function resolveNativeBinary({
   arch = process.arch,
   glibc,
   resolvePackage,
+  version,
 } = {}) {
   const selected = selectPlatformPackage({ platform, arch, glibc });
   const require = createRequire(import.meta.url);
@@ -657,6 +806,27 @@ export async function resolveNativeBinary({
     throw new Error(`Required Mikie native package ${selected.packageName} is unavailable`);
   }
 
+  let metadata;
+  try {
+    const handle = await open(packageJson, "r");
+    try {
+      const bytes = Buffer.alloc(65537);
+      const { bytesRead } = await handle.read(bytes, 0, bytes.length, 0);
+      if (bytesRead > 65536) throw new Error("oversized metadata");
+      metadata = JSON.parse(bytes.subarray(0, bytesRead).toString("utf8"));
+    } finally {
+      await handle.close();
+    }
+    if (metadata?.name !== selected.packageName) throw new Error("wrong package identity");
+  } catch {
+    throw new Error(`Required Mikie native package ${selected.packageName} metadata is invalid; reinstall the CLI`);
+  }
+  const wrapperVersion = version ?? require("../package.json").version;
+  if (typeof wrapperVersion !== "string" || !SAFE_RUNTIME_VERSION.test(wrapperVersion)
+      || metadata.version !== wrapperVersion) {
+    throw new Error("Mikie wrapper and native package versions do not match; reinstall the CLI before retrying");
+  }
+
   const binary = path.join(path.dirname(packageJson), ...selected.binaryPath.split("/"));
   try {
     const metadata = await stat(binary);

package/lib/update.mjs

@@ -611,6 +611,38 @@ function reportedForeignSettings(registration, settings, candidateBinary) {
   return reported;
 }
 
+function snapshotHasNoClaudeOwnedState(snapshot) {
+  const providers = new Map(snapshot.providerConfig.map((entry) => [entry.name, entry]));
+  const registration = parseOptionalJson(providers.get("registration"));
+  const settings = parseOptionalJson(providers.get("settings"));
+  if (providers.get("ownership")?.existed) return false;
+  if (
+    registration?.mcpServers &&
+    typeof registration.mcpServers === "object" &&
+    !Array.isArray(registration.mcpServers) &&
+    Object.hasOwn(registration.mcpServers, "mikie")
+  ) {
+    return false;
+  }
+  const hooks = settings?.hooks;
+  if (!hooks || typeof hooks !== "object" || Array.isArray(hooks)) return true;
+  return !Object.entries(hooks).some(([wireEvent, groups]) =>
+    Array.isArray(groups) &&
+    groups.some((group) =>
+      Array.isArray(group?.hooks) &&
+      group.hooks.some((handler) => {
+        if (handler?.type !== "command" || !Array.isArray(handler.args)) return false;
+        const commandEvent = CLAUDE_HOOK_EVENTS.find(([event]) => event === wireEvent)?.[1];
+        return (
+          (commandEvent && isDeepStrictEqual(handler.args, ["run-claude-hook", commandEvent])) ||
+          (["Stop", "StopFailure"].includes(wireEvent) &&
+            isDeepStrictEqual(handler.args, ["evidence", "ingest", "--client", "claude"]))
+        );
+      }),
+    ),
+  );
+}
+
 export function verifyClaudeV2Contract({
   candidateBinary,
   registration,
@@ -826,13 +858,16 @@ export async function runUpdateTransaction({
         throw new Error("candidate package version verification failed");
       }
       finalLauncher = await files.finalLauncher(candidate, resolved.version);
-      const externalRecovery = await files.recordPreparedCandidate(
+      await files.recordPreparedCandidate(
         snapshot,
         candidate,
         finalLauncher,
       );
-      recovery = externalRecovery;
-      output.writeLine(`Recovery: ${externalRecovery}`);
+      // The authenticated external recovery program remains in the transaction
+      // journal. The installed entrypoint loads it before resolving a runtime;
+      // its internal Node/bootstrap payload is not a customer-facing command.
+      recovery = "mikie update";
+      output.writeLine(`Recovery: ${recovery}`);
       await files.markProviderPreparing(snapshot);
       providerPrepared = true;
 
@@ -886,7 +921,7 @@ export async function runUpdateTransaction({
         (repairResult.receipt.action === "migrated" ||
           files.requiresFinalLauncherSettlement?.() === true);
       // A skipped receipt does not prove that no client still references a
-      // historical launcher. In particular, Claude can report unavailable
+      // historical launcher. In particular, Claude reports foreign_conflict
       // when hooks/ownership are absent while an MCP-only registration remains.
       // Retain until a later authenticated reconciliation proves both surfaces
       // absent/current instead of deleting a possibly referenced runtime.
@@ -3211,10 +3246,14 @@ export function createFilesystemAdapter({
       }
     },
     async verifyClaudeV2({ candidate, snapshot, repair }) {
-      if (
+      const refused =
         repair?.action === "refused" &&
-        ["foreign_conflict", "unavailable"].includes(repair.before)
-      ) {
+        ["foreign_conflict", "unavailable"].includes(repair.before);
+      const provenNoClaudeState =
+        snapshotHasNoClaudeOwnedState(snapshot) &&
+        ((repair?.action === "not_configured" && repair.before === "absent") ||
+          (repair?.action === "already_current" && repair.before === "current"));
+      if (refused || provenNoClaudeState) {
         const after = await Promise.all(
           snapshot.providerConfig.map(async (entry) => ({
             ...entry,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getmikie/cli",
-  "version": "1.1.120",
+  "version": "1.1.123",
   "description": "Native Mikie relay launcher for MCP clients",
   "license": "Apache-2.0",
   "repository": {
@@ -24,10 +24,9 @@
     "node": ">=22"
   },
   "optionalDependencies": {
-    "@getmikie/darwin-arm64": "1.1.120",
-    "@getmikie/darwin-x64": "1.1.120",
-    "@getmikie/linux-x64-gnu": "1.1.120",
-    "@getmikie/win32-x64": "1.1.120"
+    "@getmikie/darwin-arm64": "1.1.123",
+    "@getmikie/linux-x64-gnu": "1.1.123",
+    "@getmikie/win32-x64": "1.1.123"
   },
   "publishConfig": {
     "access": "public",

package/scripts/reconcile-install.mjs

@@ -456,8 +456,7 @@ export async function reconcileInstalledClients({
   version,
   markerPath,
   resolveBinary = resolveNativeBinary,
-  prepareLauncher = (binary) =>
-    prepareNativeLaunch(binary, ["setup", "codex"], { platform, version, environment }),
+  prepareLauncher,
   retireLauncher = (launcher, runtimeSha256, preserveSha256) =>
     retireHistoricalRuntimes(launcher, {
       expectedSha256: runtimeSha256,
@@ -487,11 +486,21 @@ export async function reconcileInstalledClients({
     throw new Error("installed client reconciliation authority is invalid");
   }
   const markerRoot = path.dirname(scopedMarker);
+  const preservedRuntimeSha256 = explicitMarker
+    ? []
+    : await retainedRuntimeDigests(markerRoot, platform);
+  const prepareLauncherForInstall = prepareLauncher ?? ((candidate) =>
+    prepareNativeLaunch(candidate, ["setup", "codex"], {
+      platform,
+      version,
+      environment,
+      preserveSha256: preservedRuntimeSha256,
+    }));
   if (!explicitMarker) {
     await retainedRuntimeDigests(markerRoot, platform, {
-        replacementName: path.basename(scopedMarker),
-        replacementSha256: authority.runtime_sha256,
-      });
+      replacementName: path.basename(scopedMarker),
+      replacementSha256: authority.runtime_sha256,
+    });
   }
   if (await readClientMarker(scopedMarker, authority)) {
     const expectedLauncher = materializedRuntimePath({
@@ -510,7 +519,7 @@ export async function reconcileInstalledClients({
       if ((await sha256File(binary)) !== initialRuntimeSha256) {
         throw new Error("installed Mikie runtime changed during client reconciliation");
       }
-      launcher = await prepareLauncher(binary);
+      launcher = await prepareLauncherForInstall(binary);
       if (
         pathIdentity(launcher, platform) !== pathIdentity(expectedLauncher, platform) ||
         (await sha256File(binary)) !== initialRuntimeSha256 ||
@@ -530,7 +539,7 @@ export async function reconcileInstalledClients({
     }
     return { status: "current" };
   }
-  const finalLauncher = await prepareLauncher(binary);
+  const finalLauncher = await prepareLauncherForInstall(binary);
   if (![binary, finalLauncher].every((value) => typeof value === "string" && path.isAbsolute(value))) {
     throw new Error("installed client reconciliation authority is invalid");
   }