@getmikie/cli 1.1.113 → 1.1.114

package/bin/mikie.mjs

@@ -18,6 +18,7 @@ import {
   resolveDependencyPackageJson,
   resolveNativeBinary,
   selectPlatformPackage,
+  shouldReconcileInstalledClients,
   translateArguments,
 } from "../lib/launcher.mjs";
 import {
@@ -26,9 +27,9 @@ import {
   createFilesystemAdapter,
   createRegistryAdapter,
   detectUpdateTopology,
-  externalRecoveryInvocation,
   parseUpdateHandoff,
   parseTrajectoryReconciliationReceipt,
+  recoverPendingNpmUpdate,
   runUpdateTransaction,
 } from "../lib/update.mjs";
 import {
@@ -88,33 +89,29 @@ All commands execute the compiled Mikie native engine.`);
       throw new Error("global npm installation authority is unavailable");
     }
     const topology = detectUpdateTopology({ globalNodeModules: npmRoot.stdout.trim() });
+    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 globalPrefix = npmPrefix.stdout.trim();
+    const globalShims =
+      process.platform === "win32"
+        ? ["mikie", "mikie.cmd", "mikie.ps1"].map((name) => path.join(globalPrefix, name))
+        : [path.join(globalPrefix, "bin", "mikie")];
     const customerHome = homedir();
     const transactionRoot = path.join(customerHome, ".mikie", "npm-update-v1");
     const recoveryJournal = path.join(transactionRoot, "journal.json");
     if (topology === UpdateTopology.NpmGlobal) {
       try {
         await access(recoveryJournal);
-        const invocation = await externalRecoveryInvocation(transactionRoot);
-        const recovered = await commands.run(invocation.executable, invocation.args, {
-          shell: false,
-          capture: true,
+        await recoverPendingNpmUpdate(transactionRoot, {
+          commands,
+          supersedingInstallation: { version: packageMetadata.version, binary },
         });
-        if (recovered.code !== 0) {
-          throw new Error("pending Mikie update recovery failed");
-        }
       } catch (error) {
         if (error?.code !== "ENOENT") throw error;
       }
     }
-    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 globalPrefix = npmPrefix.stdout.trim();
-    const globalShims =
-      process.platform === "win32"
-        ? ["mikie", "mikie.cmd", "mikie.ps1"].map((name) => path.join(globalPrefix, name))
-        : [path.join(globalPrefix, "bin", "mikie")];
     const handoffResult = await launchNativeCaptured(binary, ["update"], { topology });
     if (handoffResult.code !== 0) {
       if (handoffResult.stderr) process.stderr.write(handoffResult.stderr);
@@ -247,8 +244,10 @@ All commands execute the compiled Mikie native engine.`);
   }
 } else {
   try {
-    await reconcileInstalledClients({ version: packageMetadata.version });
     const nativeArguments = translateArguments(arguments_);
+    if (shouldReconcileInstalledClients(nativeArguments)) {
+      await reconcileInstalledClients({ version: packageMetadata.version });
+    }
     const binary = await prepareNativeLaunch(await resolveNativeBinary(), nativeArguments, {
       version: packageMetadata.version,
     });

package/lib/launcher.mjs

@@ -424,6 +424,11 @@ export function shouldStageWindowsRuntime(arguments_) {
   return arguments_[0] === "control" && arguments_[1] === "run";
 }
 
+/** Return whether a native runtime entrypoint needs installed client launchers reconciled first. */
+export function shouldReconcileInstalledClients(arguments_) {
+  return ["serve", "run-relay", "run-codex-hook", "run-claude-hook"].includes(arguments_[0]);
+}
+
 async function materializeRuntime(
   binary,
   { version, runtimeRoot, executableName, cleanupHistorical },

package/lib/update.mjs

@@ -19,7 +19,7 @@ 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 REPAIR_SCHEMA = "mikie.claude-hook-repair.v2";
 const TRAJECTORY_RECONCILIATION_SCHEMA = "mikie.trajectory-store-reconciliation.v1";
 const RERUN_COMMAND = "npx -y @getmikie/cli@latest update";
 const MAX_COMMAND_OUTPUT_BYTES = 1024 * 1024;
@@ -331,11 +331,70 @@ export async function externalRecoveryInvocation(transactionRoot) {
       "command",
     ]) ||
     recovery.descriptor !== path.join(transactionRoot, "recovery.json") ||
-    !/^[a-f0-9]{64}$/.test(recovery.descriptor_sha256)
+    recovery.launcher !== path.join(transactionRoot, "recover.mjs") ||
+    recovery.runtime !== path.join(transactionRoot, "recovery-runtime.mjs") ||
+    recovery.node !== process.execPath ||
+    ![
+      recovery.descriptor_sha256,
+      recovery.launcher_sha256,
+      recovery.runtime_sha256,
+    ].every((digest) => /^[a-f0-9]{64}$/.test(digest))
   ) {
     throw new Error("invalid Mikie update recovery authority");
   }
-  return authenticatedRecoveryInvocation(transactionRoot, recovery.descriptor_sha256);
+  return {
+    ...authenticatedRecoveryInvocation(transactionRoot, recovery.descriptor_sha256),
+    authority: {
+      descriptorSha256: recovery.descriptor_sha256,
+      launcherSha256: recovery.launcher_sha256,
+      runtimeSha256: recovery.runtime_sha256,
+    },
+  };
+}
+
+/** Recover with frozen transaction code first, then the authenticated current implementation. */
+export async function recoverPendingNpmUpdate(
+  transactionRoot,
+  {
+    commands = createCommandAdapter(),
+    recoverCurrent = recoverExternalNpmUpdate,
+    supersedingInstallation,
+  } = {},
+) {
+  const invocation = await externalRecoveryInvocation(transactionRoot);
+  const frozen = await commands.run(invocation.executable, invocation.args, {
+    shell: false,
+    capture: true,
+  });
+  if (frozen.code === 0) return { status: "recovered", method: "frozen" };
+  try {
+    let authenticatedSupersedingInstallation;
+    if (supersedingInstallation !== undefined) {
+      if (
+        !exactPublicVersion(supersedingInstallation?.version) ||
+        typeof supersedingInstallation?.binary !== "string" ||
+        !path.isAbsolute(supersedingInstallation.binary)
+      ) {
+        throw new Error("invalid superseding Mikie installation authority");
+      }
+      authenticatedSupersedingInstallation = {
+        version: supersedingInstallation.version,
+        binarySha256: await executableDigest(supersedingInstallation.binary),
+      };
+    }
+    await recoverCurrent(transactionRoot, invocation.authority, {
+      supersedingInstallation: authenticatedSupersedingInstallation,
+    });
+    return { status: "recovered", method: "current" };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "";
+    const reason = /tampered|invalid|unsafe|authority|corrupt|changed/i.test(message)
+      ? "recovery authority could not be authenticated"
+      : /settlement|configured client/i.test(message)
+        ? "configured client state could not be settled"
+        : "authenticated recovery could not complete";
+    throw new Error(`pending Mikie update recovery failed: ${reason}; transaction preserved`);
+  }
 }
 
 function expectedHandoff(topology) {
@@ -632,12 +691,17 @@ function parseRepairReceipt(stdout) {
     receipt.after === "current" &&
     receipt.action === "already_current" &&
     receipt.restart_required === false;
+  const absent =
+    receipt.before === "absent" &&
+    receipt.after === "absent" &&
+    receipt.action === "not_configured" &&
+    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) {
+  if (!migrated && !current && !absent && !skipped) {
     throw new Error("candidate owned-adapter repair returned an invalid receipt");
   }
   return { receipt, skipped };
@@ -779,6 +843,7 @@ export async function runUpdateTransaction({
           MIKIE_DISTRIBUTION_MODE: "npm",
           MIKIE_NPM_UPDATE_TOPOLOGY: UpdateTopology.NpmGlobal,
           MIKIE_NPM_UPDATE_REPAIR_PHASE: "prepare",
+          MIKIE_NPM_CLIENT_REPAIR_SCHEMA: REPAIR_SCHEMA,
           MIKIE_UPDATE_REPAIR_LAUNCHER_STATE: "prior",
           MIKIE_UPDATE_REPAIR_CANDIDATE: candidate.binary,
           MIKIE_UPDATE_REPAIR_LAUNCHER: finalLauncher,
@@ -816,8 +881,10 @@ export async function runUpdateTransaction({
       await files.activate(activatedCandidate);
       await files.checkpointCandidate(snapshot, { provider: true });
       const settlementRequired =
-        repairResult.receipt.action === "migrated" ||
-        files.requiresFinalLauncherSettlement?.() === true;
+        !repairResult.skipped &&
+        repairResult.receipt.action !== "not_configured" &&
+        (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
       // when hooks/ownership are absent while an MCP-only registration remains.
@@ -840,6 +907,7 @@ export async function runUpdateTransaction({
             MIKIE_DISTRIBUTION_MODE: "npm",
             MIKIE_NPM_UPDATE_TOPOLOGY: UpdateTopology.NpmGlobal,
             MIKIE_NPM_UPDATE_REPAIR_PHASE: "commit",
+            MIKIE_NPM_CLIENT_REPAIR_SCHEMA: REPAIR_SCHEMA,
             MIKIE_UPDATE_REPAIR_LAUNCHER_STATE: "activated",
             MIKIE_UPDATE_REPAIR_CANDIDATE: candidate.binary,
             MIKIE_UPDATE_REPAIR_LAUNCHER: finalLauncher,
@@ -861,7 +929,7 @@ export async function runUpdateTransaction({
           ? "skipped"
           : repairResult.receipt.action === "already_current"
             ? "verified"
-            : "migrated",
+            : repairResult.receipt.action,
         foreignSettings: verification.foreignSettings ?? [],
       };
     } catch (error) {
@@ -875,6 +943,7 @@ export async function runUpdateTransaction({
               MIKIE_DISTRIBUTION_MODE: "npm",
               MIKIE_NPM_UPDATE_TOPOLOGY: UpdateTopology.NpmGlobal,
               MIKIE_NPM_UPDATE_REPAIR_PHASE: "rollback",
+              MIKIE_NPM_CLIENT_REPAIR_SCHEMA: REPAIR_SCHEMA,
               MIKIE_UPDATE_REPAIR_LAUNCHER_STATE:
                 files.preparedLauncherState?.(snapshot) ?? "prior",
               MIKIE_UPDATE_REPAIR_CANDIDATE: candidate.binary,
@@ -1338,6 +1407,7 @@ export function createFilesystemAdapter({
   prepareFinalLauncher,
   retireFinalLauncher,
   abandonFinalLauncher,
+  supersedingInstallation,
 }) {
   const currentRoots = validateInstallationLayout(currentLayout);
   const currentShims = currentRoots.shims;
@@ -1354,7 +1424,10 @@ export function createFilesystemAdapter({
     (activationBoundary !== undefined && typeof activationBoundary !== "function") ||
     (prepareFinalLauncher !== undefined && typeof prepareFinalLauncher !== "function") ||
     (retireFinalLauncher !== undefined && typeof retireFinalLauncher !== "function") ||
-    (abandonFinalLauncher !== undefined && typeof abandonFinalLauncher !== "function")
+    (abandonFinalLauncher !== undefined && typeof abandonFinalLauncher !== "function") ||
+    (supersedingInstallation !== undefined &&
+      (!exactPublicVersion(supersedingInstallation?.version) ||
+        !/^[a-f0-9]{64}$/.test(supersedingInstallation?.binarySha256 ?? "")))
   ) {
     throw new Error("unsafe Mikie update filesystem path");
   }
@@ -2359,6 +2432,86 @@ export function createFilesystemAdapter({
     return owner?.activationState === "activated" ? "activated" : "prior";
   };
 
+  const committedActivationMatches = async (snapshot) => {
+    for (const entry of snapshot.installation) {
+      if (
+        !entry.expectedFingerprint ||
+        (await directoryFingerprint(entry.root)) !== entry.expectedFingerprint
+      ) {
+        return false;
+      }
+    }
+    for (const entry of snapshot.shims) {
+      if (
+        !entry.expectedFingerprint ||
+        (await readShimState(entry.path)).fingerprint !== entry.expectedFingerprint
+      ) {
+        return false;
+      }
+    }
+    return true;
+  };
+
+  const authenticateSupersedingInstallation = async () => {
+    if (!supersedingInstallation) return false;
+    try {
+      const [wrapper, platform, binarySha256] = await Promise.all([
+        readFile(currentLayout.wrapperPackageJson, "utf8"),
+        readFile(currentLayout.platformPackageJson, "utf8"),
+        executableDigest(currentLayout.binary),
+      ]);
+      return (
+        JSON.parse(wrapper)?.version === supersedingInstallation.version &&
+        JSON.parse(platform)?.version === supersedingInstallation.version &&
+        binarySha256 === supersedingInstallation.binarySha256
+      );
+    } catch {
+      return false;
+    }
+  };
+
+  const cleanupSupersededCommittedActivation = async (snapshot) => {
+    for (const entry of snapshot.installation) {
+      const priorFingerprint = await directoryFingerprint(entry.priorQuarantine);
+      const stagedFingerprint = await directoryFingerprint(entry.activationStaging);
+      if (
+        (priorFingerprint !== "absent" && priorFingerprint !== entry.sourceFingerprint) ||
+        (stagedFingerprint !== "absent" && stagedFingerprint !== entry.expectedFingerprint)
+      ) {
+        throw new Error("tampered Mikie superseded activation state");
+      }
+    }
+    for (const entry of snapshot.shims) {
+      const prior = await readShimState(entry.priorQuarantine);
+      const staged = await readShimState(entry.activationStaging);
+      if (
+        (prior.existed && prior.fingerprint !== entry.sourceFingerprint) ||
+        (staged.existed && staged.fingerprint !== entry.expectedFingerprint)
+      ) {
+        throw new Error("tampered Mikie superseded activation state");
+      }
+    }
+    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 providerConfigurationMatchesSnapshot = async (snapshot) => {
+    for (const entry of snapshot.providerConfig) {
+      await assertNoLinkedAncestors(entry.path);
+      const current = await readOptionalFile(entry.path);
+      if (bytesFingerprint(current.existed, current.bytes) !== entry.sourceFingerprint) {
+        return false;
+      }
+    }
+    return true;
+  };
+
   const recoverInterrupted = async (lease, expectedJournalToken) => {
     try {
       const metadata = await lstat(transactionRoot);
@@ -2370,6 +2523,33 @@ export function createFilesystemAdapter({
       throw error;
     }
     const snapshot = await hydrateJournal(lease, expectedJournalToken);
+    if (snapshot.phase === "commit_decided_retain_runtime") {
+      const activationMatches = await committedActivationMatches(snapshot);
+      if (!activationMatches && (await authenticateSupersedingInstallation())) {
+        await cleanupSupersededCommittedActivation(snapshot);
+        await rm(transactionRoot, { recursive: true, force: true });
+        return;
+      }
+    }
+    if (
+      snapshot.phase === "commit_decided_retain_runtime" &&
+      (await providerConfigurationMatchesSnapshot(snapshot))
+    ) {
+      if (!reconcileTrajectoryStore) {
+        throw new Error("trajectory-store reconciliation is unavailable");
+      }
+      await reconcileTrajectoryStore(snapshot.preparedCandidate.finalLauncher, snapshot);
+      const activationMatches = await committedActivationMatches(snapshot);
+      if (!activationMatches && !(await authenticateSupersedingInstallation())) {
+        throw new Error("committed Mikie package changed before cleanup");
+      }
+      snapshot.phase = "committed_retain_runtime";
+      await writeJournal(snapshot);
+      if (activationMatches) await cleanupCommittedActivation(snapshot);
+      else await cleanupSupersededCommittedActivation(snapshot);
+      await rm(transactionRoot, { recursive: true, force: true });
+      return;
+    }
     if (["commit_decided", "commit_decided_retain_runtime"].includes(snapshot.phase)) {
       const retainHistoricalRuntimes = snapshot.phase === "commit_decided_retain_runtime";
       if (!reconcileTrajectoryStore) {
@@ -2412,7 +2592,12 @@ export function createFilesystemAdapter({
       return;
     }
     if (snapshot.phase === "committed_retain_runtime") {
-      await cleanupCommittedActivation(snapshot);
+      const activationMatches = await committedActivationMatches(snapshot);
+      if (!activationMatches && !(await authenticateSupersedingInstallation())) {
+        throw new Error("committed Mikie package changed before cleanup");
+      }
+      if (activationMatches) await cleanupCommittedActivation(snapshot);
+      else await cleanupSupersededCommittedActivation(snapshot);
       await rm(transactionRoot, { recursive: true, force: true });
       return;
     }
@@ -3079,7 +3264,11 @@ export function createFilesystemAdapter({
   return adapter;
 }
 
-export async function recoverExternalNpmUpdate(transactionRoot, expectedAuthority) {
+export async function recoverExternalNpmUpdate(
+  transactionRoot,
+  expectedAuthority,
+  { supersedingInstallation } = {},
+) {
   if (typeof transactionRoot !== "string" || !path.isAbsolute(transactionRoot)) {
     throw new Error("unsafe Mikie update recovery root");
   }
@@ -3172,6 +3361,7 @@ export async function recoverExternalNpmUpdate(transactionRoot, expectedAuthorit
     },
     providerPaths: descriptor.provider_paths,
     transactionRoot,
+    supersedingInstallation,
     settleProviderRepair: async (phase, snapshot) => {
       if (
         snapshot?.preparedCandidate?.binary !== descriptor.candidate_binary ||
@@ -3189,6 +3379,7 @@ export async function recoverExternalNpmUpdate(transactionRoot, expectedAuthorit
             MIKIE_DISTRIBUTION_MODE: "npm",
             MIKIE_NPM_UPDATE_TOPOLOGY: UpdateTopology.NpmGlobal,
             MIKIE_NPM_UPDATE_REPAIR_PHASE: phase,
+            MIKIE_NPM_CLIENT_REPAIR_SCHEMA: REPAIR_SCHEMA,
             MIKIE_UPDATE_REPAIR_CANDIDATE: descriptor.candidate_binary,
             MIKIE_UPDATE_REPAIR_LAUNCHER: descriptor.final_launcher,
           },

package/package.json

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

package/scripts/reconcile-install.mjs

@@ -18,7 +18,7 @@ import {
 const RECONCILIATION_ARGUMENTS = ["reconcile-trajectory-store-v2", "--json"];
 const CLIENT_REPAIR_ARGUMENTS = ["repair-claude-hooks-v1", "--json"];
 const CLIENT_RECONCILIATION_SCHEMA = "mikie.npm-client-reconciliation.v2";
-const CLIENT_REPAIR_SCHEMA = "mikie.claude-hook-repair.v1";
+const CLIENT_REPAIR_SCHEMA = "mikie.claude-hook-repair.v2";
 const CLIENT_SETTLEMENT_SCHEMA = "mikie.claude-hook-repair-settlement.v1";
 const TRANSACTION_TOKEN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 const PUBLIC_VERSION = /^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?$/;
@@ -453,11 +453,12 @@ export async function reconcileInstalledClients({
       preserveSha256,
     }),
   commands = createCommandAdapter({ environment, platform }),
+  allowDeferred = false,
 } = {}) {
   if (isTransactionStagedInstall(environment, platform)) {
     return { status: "staged_candidate" };
   }
-  if (!PUBLIC_VERSION.test(version ?? "")) {
+  if (!PUBLIC_VERSION.test(version ?? "") || typeof allowDeferred !== "boolean") {
     throw new Error("installed client reconciliation authority is invalid");
   }
 
@@ -513,7 +514,9 @@ export async function reconcileInstalledClients({
     const preserved = explicitMarker
       ? [authority.runtime_sha256]
       : await retainedRuntimeDigests(markerRoot, platform);
-    await retireLauncher(launcher, authority.runtime_sha256, preserved);
+    if (!allowDeferred) {
+      await retireLauncher(launcher, authority.runtime_sha256, preserved);
+    }
     return { status: "current" };
   }
   const finalLauncher = await prepareLauncher(binary);
@@ -523,6 +526,7 @@ export async function reconcileInstalledClients({
   const baseEnvironment = {
     MIKIE_DISTRIBUTION_MODE: "npm",
     MIKIE_NPM_UPDATE_TOPOLOGY: "npm_global",
+    MIKIE_NPM_CLIENT_REPAIR_SCHEMA: CLIENT_REPAIR_SCHEMA,
     MIKIE_UPDATE_REPAIR_CANDIDATE: binary,
     MIKIE_UPDATE_REPAIR_LAUNCHER: finalLauncher,
   };
@@ -540,6 +544,9 @@ export async function reconcileInstalledClients({
   });
   parseClientSettlement(committed, settlementPhase);
   if (preparedReceipt.action === "refused") {
+    if (allowDeferred) {
+      return { status: "deferred", providerState: preparedReceipt.before };
+    }
     throw new Error(
       "Mikie could not authenticate every configured client; close active clients and run `mikie update` before reinstalling",
     );
@@ -554,7 +561,9 @@ export async function reconcileInstalledClients({
   const preserved = explicitMarker
     ? [authority.runtime_sha256]
     : await retainedRuntimeDigests(markerRoot, platform);
-  await retireLauncher(finalLauncher, authority.runtime_sha256, preserved);
+  if (!allowDeferred) {
+    await retireLauncher(finalLauncher, authority.runtime_sha256, preserved);
+  }
   return { status: "reconciled", finalLauncher };
 }
 
@@ -566,7 +575,13 @@ if (scriptIdentity !== null && scriptIdentity === invokedIdentity) {
     const packageMetadata = JSON.parse(
       await readFile(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8"),
     );
-    await reconcileInstalledClients({ version: packageMetadata.version });
+    const clients = await reconcileInstalledClients({
+      version: packageMetadata.version,
+      allowDeferred: true,
+    });
+    if (clients.status === "deferred") {
+      console.warn("Mikie install client repair deferred; run `mikie setup` or `mikie doctor`.");
+    }
   } catch (error) {
     console.error(`Mikie install reconciliation failed: ${error.message}`);
     process.exitCode = 1;