@getmikie/cli 1.1.124 → 1.1.126

package/bin/mikie.mjs

@@ -16,6 +16,7 @@ import {
   retireHistoricalWindowsRuntimes,
   retireHistoricalRuntimes,
   resolveDependencyPackageJson,
+  resolveInstalledPackages,
   resolveNativeBinary,
   selectPlatformPackage,
   shouldCompleteSkippedInstall,
@@ -30,8 +31,10 @@ import {
   detectUpdateTopology,
   parseUpdateHandoff,
   parseTrajectoryReconciliationReceipt,
+  pendingUpdateTransaction,
   recoverPendingNpmUpdate,
   runUpdateTransaction,
+  setAsideUpdateTransaction,
 } from "../lib/update.mjs";
 import {
   completeSkippedInstall,
@@ -40,6 +43,20 @@ import {
 } from "../scripts/reconcile-install.mjs";
 
 const require = createRequire(import.meta.url);
+
+/** One next step for the update failures a customer can act on. */
+function updateGuidance(message) {
+  if (/EBUSY|EPERM|resource busy|operation not permitted|locked/i.test(message)) {
+    return "; a running Mikie process holds a file: close Codex and Claude Code, then run `mikie update` again";
+  }
+  if (/registry did not resolve|registry/i.test(message)) {
+    return "; the npm registry could not be reached or returned no compatible version: check the connection and run `mikie update` again";
+  }
+  if (/another Mikie update transaction is active/.test(message)) {
+    return "; wait for the other `mikie update` to finish";
+  }
+  return "";
+}
 const packageMetadata = require("../package.json");
 const arguments_ = process.argv.slice(2);
 const singleFlag = arguments_.length === 1 ? arguments_[0].toLowerCase() : null;
@@ -95,7 +112,36 @@ 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({ version: packageMetadata.version });
+    let binary;
+    try {
+      binary = await resolveNativeBinary({ version: packageMetadata.version });
+    } catch (error) {
+      // A half-finished install (wrapper and native package at different
+      // versions, or a missing native package) cannot run its own updater.
+      // Reinstall the whole CLI from npm, the documented recovery.
+      const reason = error instanceof Error ? error.message : "the native package is unavailable";
+      if (topology !== UpdateTopology.NpmGlobal || !/native package|versions do not match/.test(reason)) {
+        throw error;
+      }
+      console.error(`mikie: the installed CLI is incomplete (${reason}); reinstalling it from npm.`);
+      const registry = createRegistryAdapter({ commands });
+      const resolved = await registry.resolveExactCompatibleVersion({
+        packageName: "@getmikie/cli",
+        currentVersion: packageMetadata.version,
+        nodeVersion: process.versions.node,
+      });
+      const spec = `@getmikie/cli@${resolved.version}`;
+      const reinstall = await commands.run(
+        "npm",
+        ["install", "--global", spec, "--allow-scripts=@getmikie/cli"],
+        { shell: false, capture: true },
+      );
+      if (reinstall.code !== 0) {
+        throw new Error(`reinstalling the CLI failed; run: npm install --global ${spec} --allow-scripts=@getmikie/cli`);
+      }
+      console.log(`Reinstalled Mikie ${resolved.version}. Run \`mikie doctor\` to check client setup.`);
+      process.exit(0);
+    }
     const globalPrefix = npmPrefix.stdout.trim();
     const globalShims =
       process.platform === "win32"
@@ -105,14 +151,29 @@ All commands execute the compiled Mikie native engine.`);
     const transactionRoot = path.join(customerHome, ".mikie", "npm-update-v1");
     const recoveryJournal = path.join(transactionRoot, "journal.json");
     if (topology === UpdateTopology.NpmGlobal) {
+      let pending = true;
       try {
         await access(recoveryJournal);
-        await recoverPendingNpmUpdate(transactionRoot, {
-          commands,
-          supersedingInstallation: { version: packageMetadata.version, binary },
-        });
       } catch (error) {
         if (error?.code !== "ENOENT") throw error;
+        pending = false;
+      }
+      if (pending) {
+        try {
+          await recoverPendingNpmUpdate(transactionRoot, {
+            commands,
+            supersedingInstallation: { version: packageMetadata.version, binary },
+          });
+        } catch (error) {
+          // The installed packages were verified above. An earlier transaction
+          // that cannot be finished (superseded, tampered or from an older
+          // updater) is kept byte for byte but must not block this update.
+          const reason = error instanceof Error ? error.message : "recovery failed";
+          const aside = await setAsideUpdateTransaction(transactionRoot);
+          console.error(
+            `mikie: an earlier unfinished update could not be completed (${reason}); its files were kept at ${aside} and this update continues from ${packageMetadata.version}.`,
+          );
+        }
       }
     }
     const handoffResult = await launchNativeCaptured(binary, ["update"], { topology });
@@ -150,10 +211,13 @@ All commands execute the compiled Mikie native engine.`);
                 : [path.join(stagingPrefix, "bin", "mikie")],
           };
         }
+        // The activated packages on disk: this process is still the
+        // previous wrapper, so its own version is not the one to verify.
+        const installed = await resolveInstalledPackages(wrapperPackageJson);
         return {
           wrapperPackageJson,
-          platformPackageJson: require.resolve(`${selected.packageName}/package.json`),
-          binary: await resolveNativeBinary({ version: packageMetadata.version }),
+          platformPackageJson: installed.platformPackageJson,
+          binary: installed.binary,
           shims: globalShims,
         };
       },
@@ -246,10 +310,7 @@ All commands execute the compiled Mikie native engine.`);
     }
   } catch (error) {
     const message = error instanceof Error ? error.message : "Mikie update failed";
-    const guidance = message === "invalid Mikie update recovery authority"
-      ? "; keep the recovery files and contact support before retrying"
-      : "";
-    console.error(`mikie: ${message}${guidance}`);
+    console.error(`mikie: ${message}${updateGuidance(message)}`);
     process.exitCode = 1;
   }
 } else {
@@ -276,6 +337,16 @@ All commands execute the compiled Mikie native engine.`);
         console.error(`mikie: install reconciliation is incomplete (${reason}); the command continues.`);
       }
     }
+    if (nativeArguments[0] === "doctor") {
+      const pendingUpdate = await pendingUpdateTransaction(
+        path.join(homedir(), ".mikie", "npm-update-v1"),
+      );
+      if (pendingUpdate) {
+        console.log(
+          `update transaction: pending (${pendingUpdate.phase}); run \`mikie update\` to finish it or set it aside`,
+        );
+      }
+    }
     const binary = await prepareNativeLaunch(await resolveNativeBinary(), nativeArguments, {
       version: packageMetadata.version,
     });

package/lib/launcher.mjs

@@ -809,6 +809,33 @@ export function resolveDependencyPackageJson(wrapperPackageJson, dependencyPacka
   return wrapperRequire.resolve(`${dependencyPackageName}/package.json`);
 }
 
+/**
+ * The wrapper and native package installed on disk now, checked against each
+ * other. After `mikie update` activates a new version, the running process is
+ * still the previous wrapper, so its own version must not be the reference.
+ */
+export async function resolveInstalledPackages(
+  wrapperPackageJson,
+  { platform = process.platform, arch = process.arch, glibc } = {},
+) {
+  const selected = selectPlatformPackage({ platform, arch, glibc });
+  let version;
+  try {
+    version = JSON.parse(await readFile(wrapperPackageJson, "utf8"))?.version;
+  } catch {
+    throw new Error("Mikie wrapper package metadata is invalid; reinstall the CLI");
+  }
+  const platformPackageJson = resolveDependencyPackageJson(wrapperPackageJson, selected.packageName);
+  const binary = await resolveNativeBinary({
+    platform,
+    arch,
+    glibc,
+    version,
+    resolvePackage: () => platformPackageJson,
+  });
+  return { wrapperPackageJson, platformPackageJson, binary, version };
+}
+
 export async function resolveNativeBinary({
   platform = process.platform,
   arch = process.arch,

package/lib/update.mjs

@@ -428,6 +428,55 @@ function validateHandoff(value, topology = value?.topology) {
   return value;
 }
 
+/**
+ * Move an earlier update transaction that cannot be finished out of the way,
+ * byte for byte, so it cannot block every later `mikie update`. Refuses while
+ * another update process holds the transaction lock. Returns the new path.
+ */
+export async function setAsideUpdateTransaction(
+  transactionRoot,
+  { now = new Date(), isProcessAlive = processIsAlive } = {},
+) {
+  if (typeof transactionRoot !== "string" || !path.isAbsolute(transactionRoot)) {
+    throw new Error("unsafe Mikie update transaction root");
+  }
+  await assertNoLinkedAncestors(transactionRoot);
+  try {
+    const lock = parseJsonNoDuplicateKeys(await readFile(`${transactionRoot}.lock`));
+    if (isProcessAlive(lock?.process_id)) {
+      throw new Error("another Mikie update transaction is active");
+    }
+  } catch (error) {
+    if (error?.message === "another Mikie update transaction is active") throw error;
+  }
+  const stamp = now.toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z");
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    const target = `${transactionRoot}.set-aside-${stamp}${attempt ? `-${attempt}` : ""}`;
+    try {
+      await lstat(target);
+      continue;
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+    }
+    await rename(transactionRoot, target);
+    return target;
+  }
+  throw new Error("no free name to set aside the Mikie update transaction");
+}
+
+/** The phase of a pending update transaction, or null when there is none. */
+export async function pendingUpdateTransaction(transactionRoot) {
+  try {
+    const journal = parseJsonNoDuplicateKeys(
+      await readFile(path.join(transactionRoot, "journal.json")),
+    );
+    return { phase: typeof journal?.phase === "string" ? journal.phase : "unknown" };
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    return { phase: "unreadable" };
+  }
+}
+
 export function parseUpdateHandoff(stdout, expectedTopology) {
   if (typeof stdout !== "string" || stdout.trim().split(/\r?\n/).length !== 1) {
     throw new Error("invalid Mikie update handoff");
@@ -2487,22 +2536,50 @@ export function createFilesystemAdapter({
     return true;
   };
 
+  // The recorded layout, and the same wrapper with its platform package
+  // nested under it: a later npm install can nest the platform package and
+  // leave the journal's hoisted copy behind at the older version.
+  const supersedingLayouts = () => {
+    const platformRoot = path.dirname(currentLayout.platformPackageJson);
+    const nestedRoot = path.join(
+      path.dirname(currentLayout.wrapperPackageJson),
+      "node_modules",
+      path.basename(path.dirname(platformRoot)),
+      path.basename(platformRoot),
+    );
+    const nested = {
+      platformPackageJson: path.join(nestedRoot, "package.json"),
+      binary: path.join(nestedRoot, path.relative(platformRoot, currentLayout.binary)),
+    };
+    return sameExecutablePath(nestedRoot, platformRoot) ? [currentLayout] : [currentLayout, nested];
+  };
+
   const authenticateSupersedingInstallation = async () => {
     if (!supersedingInstallation) return false;
+    let wrapperVersion;
     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
-      );
+      wrapperVersion = JSON.parse(await readFile(currentLayout.wrapperPackageJson, "utf8"))?.version;
     } catch {
       return false;
     }
+    if (wrapperVersion !== supersedingInstallation.version) return false;
+    for (const layout of supersedingLayouts()) {
+      try {
+        const [platform, binarySha256] = await Promise.all([
+          readFile(layout.platformPackageJson, "utf8"),
+          executableDigest(layout.binary),
+        ]);
+        if (
+          JSON.parse(platform)?.version === supersedingInstallation.version &&
+          binarySha256 === supersedingInstallation.binarySha256
+        ) {
+          return true;
+        }
+      } catch {
+        // Try the next layout.
+      }
+    }
+    return false;
   };
 
   const cleanupSupersededCommittedActivation = async (snapshot) => {

package/package.json

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