@getmikie/cli 1.1.103 → 1.1.104

package/lib/update.mjs

@@ -66,6 +66,8 @@ if (
   descriptor.transaction_root !== transactionRoot ||
   descriptor.token !== journal.token ||
   journal.recovery?.descriptor_sha256 !== expectedDescriptorSha256 ||
+  descriptor.final_launcher !== journal.prepared_candidate?.final_launcher ||
+  descriptor.final_launcher_sha256 !== journal.prepared_candidate?.final_launcher_sha256 ||
   ![descriptor.runtime, descriptor.launcher].every(
     (artifactPath) => typeof artifactPath === "string" && inside(transactionRoot, artifactPath),
   )
@@ -719,7 +721,9 @@ export async function runUpdateTransaction({
     if (versionOrder < 0) {
       throw new Error("registry resolved an older Mikie version");
     }
-    if (versionOrder === 0) {
+    const reconcileCurrentInstallation =
+      versionOrder === 0 && files.requiresFinalLauncherSettlement?.() === true;
+    if (versionOrder === 0 && !reconcileCurrentInstallation) {
       output.writeLine(`Mikie is already current at ${installedCurrentVersion}.`);
       return { status: "current", version: installedCurrentVersion };
     }
@@ -757,7 +761,7 @@ export async function runUpdateTransaction({
       if (wrapperVersion !== resolved.version || candidatePlatformVersion !== resolved.version) {
         throw new Error("candidate package version verification failed");
       }
-      finalLauncher = files.finalLauncher();
+      finalLauncher = await files.finalLauncher(candidate, resolved.version);
       const externalRecovery = await files.recordPreparedCandidate(
         snapshot,
         candidate,
@@ -775,6 +779,7 @@ export async function runUpdateTransaction({
           MIKIE_DISTRIBUTION_MODE: "npm",
           MIKIE_NPM_UPDATE_TOPOLOGY: UpdateTopology.NpmGlobal,
           MIKIE_NPM_UPDATE_REPAIR_PHASE: "prepare",
+          MIKIE_UPDATE_REPAIR_LAUNCHER_STATE: "prior",
           MIKIE_UPDATE_REPAIR_CANDIDATE: candidate.binary,
           MIKIE_UPDATE_REPAIR_LAUNCHER: finalLauncher,
         },
@@ -810,8 +815,21 @@ export async function runUpdateTransaction({
       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 });
+      const settlementRequired =
+        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.
+      // Retain until a later authenticated reconciliation proves both surfaces
+      // absent/current instead of deleting a possibly referenced runtime.
+      const retainHistoricalRuntimes = ["foreign_conflict", "unavailable"].includes(
+        repairResult.receipt.before,
+      );
+      await files.decideCommit(snapshot, {
+        settlementRequired,
+        ...(retainHistoricalRuntimes ? { retainHistoricalRuntimes: true } : {}),
+      });
       commitDecided = true;
       await files.reconcileTrajectoryStore(snapshot);
       if (settlementRequired) {
@@ -822,6 +840,7 @@ export async function runUpdateTransaction({
             MIKIE_DISTRIBUTION_MODE: "npm",
             MIKIE_NPM_UPDATE_TOPOLOGY: UpdateTopology.NpmGlobal,
             MIKIE_NPM_UPDATE_REPAIR_PHASE: "commit",
+            MIKIE_UPDATE_REPAIR_LAUNCHER_STATE: "activated",
             MIKIE_UPDATE_REPAIR_CANDIDATE: candidate.binary,
             MIKIE_UPDATE_REPAIR_LAUNCHER: finalLauncher,
           },
@@ -830,9 +849,12 @@ export async function runUpdateTransaction({
           throw new Error("candidate owned-adapter settlement failed");
         }
       }
-      await files.retire(snapshot);
+      await files.retire(
+        snapshot,
+        retainHistoricalRuntimes ? { retainHistoricalRuntimes: true } : undefined,
+      );
       return {
-        status: "updated",
+        status: reconcileCurrentInstallation ? "reconciled" : "updated",
         version: resolved.version,
         providerState: repairResult.receipt.after,
         adapterAction: repairResult.skipped
@@ -853,6 +875,8 @@ export async function runUpdateTransaction({
               MIKIE_DISTRIBUTION_MODE: "npm",
               MIKIE_NPM_UPDATE_TOPOLOGY: UpdateTopology.NpmGlobal,
               MIKIE_NPM_UPDATE_REPAIR_PHASE: "rollback",
+              MIKIE_UPDATE_REPAIR_LAUNCHER_STATE:
+                files.preparedLauncherState?.(snapshot) ?? "prior",
               MIKIE_UPDATE_REPAIR_CANDIDATE: candidate.binary,
               MIKIE_UPDATE_REPAIR_LAUNCHER: finalLauncher,
             },
@@ -868,6 +892,9 @@ export async function runUpdateTransaction({
       if (!commitDecided && !restoreFailure) {
         try {
           await files.restore(snapshot);
+          if (snapshot.preparedCandidate) {
+            await files.abandonPreparedLauncher?.(snapshot);
+          }
         } catch (restoreError) {
           restoreFailure = restoreError;
         }
@@ -1135,6 +1162,33 @@ function bytesFingerprint(existed, bytes) {
   return existed ? `present:${createHash("sha256").update(bytes).digest("hex")}` : "absent";
 }
 
+async function executableDigest(filePath) {
+  if (typeof filePath !== "string" || !path.isAbsolute(filePath)) {
+    throw new Error("prepared final launcher authority is invalid");
+  }
+  await assertNoLinkedAncestors(filePath);
+  const before = await lstat(filePath);
+  if (
+    !before.isFile() ||
+    before.isSymbolicLink() ||
+    before.size <= 0 ||
+    before.size > MAX_TRANSACTION_TREE_BYTES
+  ) {
+    throw new Error("prepared final launcher authority is invalid");
+  }
+  const bytes = await readFile(filePath);
+  const after = await lstat(filePath);
+  if (
+    !after.isFile() ||
+    after.isSymbolicLink() ||
+    bytes.length !== before.size ||
+    after.size !== before.size
+  ) {
+    throw new Error("prepared final launcher changed");
+  }
+  return sha256Bytes(bytes);
+}
+
 async function directoryFingerprint(root) {
   const digest = createHash("sha256");
   let entries = 0;
@@ -1263,6 +1317,9 @@ export function createFilesystemAdapter({
   settleProviderRepair,
   reconcileTrajectoryStore,
   activationBoundary,
+  prepareFinalLauncher,
+  retireFinalLauncher,
+  abandonFinalLauncher,
 }) {
   const currentRoots = validateInstallationLayout(currentLayout);
   const currentShims = currentRoots.shims;
@@ -1276,7 +1333,10 @@ export function createFilesystemAdapter({
     !path.isAbsolute(transactionRoot) ||
     (settleProviderRepair !== undefined && typeof settleProviderRepair !== "function") ||
     (reconcileTrajectoryStore !== undefined && typeof reconcileTrajectoryStore !== "function") ||
-    (activationBoundary !== undefined && typeof activationBoundary !== "function")
+    (activationBoundary !== undefined && typeof activationBoundary !== "function") ||
+    (prepareFinalLauncher !== undefined && typeof prepareFinalLauncher !== "function") ||
+    (retireFinalLauncher !== undefined && typeof retireFinalLauncher !== "function") ||
+    (abandonFinalLauncher !== undefined && typeof abandonFinalLauncher !== "function")
   ) {
     throw new Error("unsafe Mikie update filesystem path");
   }
@@ -1300,6 +1360,7 @@ export function createFilesystemAdapter({
   }
   const lockPath = `${transactionRoot}.lock`;
   const journalPath = path.join(transactionRoot, "journal.json");
+  let preparedFinalLauncherAuthority = null;
 
   const readLock = async () => {
     try {
@@ -1348,6 +1409,7 @@ export function createFilesystemAdapter({
             platform_fingerprint: snapshot.preparedCandidate.platformFingerprint,
             shims: snapshot.preparedCandidate.shimFingerprints,
             final_launcher: snapshot.preparedCandidate.finalLauncher,
+            final_launcher_sha256: snapshot.preparedCandidate.finalLauncherSha256,
           }
         : null,
       recovery: snapshot.recovery
@@ -1436,7 +1498,10 @@ export function createFilesystemAdapter({
         "provider_rolled_back",
         "commit_decided",
         "commit_decided_no_repair",
+        "commit_decided_retain_runtime",
+        "commit_decided_no_repair_retain_runtime",
         "committed",
+        "committed_retain_runtime",
       ].includes(value.phase) ||
       !Array.isArray(value.installation) ||
       !Array.isArray(value.shims) ||
@@ -1599,6 +1664,7 @@ export function createFilesystemAdapter({
           "platform_fingerprint",
           "shims",
           "final_launcher",
+          "final_launcher_sha256",
         ]) ||
         ![prepared.wrapper_package_json, prepared.platform_package_json, prepared.binary].every(
           (candidatePath) =>
@@ -1619,7 +1685,9 @@ export function createFilesystemAdapter({
         ) ||
         new Set(prepared.shims.map((shim) => path.resolve(shim.path))).size !==
           prepared.shims.length ||
-        !sameExecutablePath(prepared.final_launcher, currentLayout.binary)
+        typeof prepared.final_launcher !== "string" ||
+        !path.isAbsolute(prepared.final_launcher) ||
+        !/^[a-f0-9]{64}$/.test(prepared.final_launcher_sha256)
       ) {
         throw new Error("invalid Mikie update transaction journal");
       }
@@ -1632,6 +1700,7 @@ export function createFilesystemAdapter({
         shims: prepared.shims.map((shim) => shim.path),
         shimFingerprints: prepared.shims,
         finalLauncher: prepared.final_launcher,
+        finalLauncherSha256: prepared.final_launcher_sha256,
       };
       const preparedRoots = validateInstallationLayout(preparedCandidate);
       if (
@@ -1648,6 +1717,13 @@ export function createFilesystemAdapter({
           throw new Error("corrupt Mikie staged candidate");
         }
       }
+      if (
+        !sameExecutablePath(preparedCandidate.finalLauncher, currentLayout.binary) &&
+        (await executableDigest(preparedCandidate.finalLauncher)) !==
+          preparedCandidate.finalLauncherSha256
+      ) {
+        throw new Error("prepared final launcher changed");
+      }
     }
     let recovery = null;
     if (value.recovery !== null) {
@@ -1715,7 +1791,10 @@ export function createFilesystemAdapter({
         "candidate_packages",
         "commit_decided",
         "commit_decided_no_repair",
+        "commit_decided_retain_runtime",
+        "commit_decided_no_repair_retain_runtime",
         "committed",
+        "committed_retain_runtime",
       ].includes(value.phase) &&
       (!preparedCandidate || !recovery)
     ) {
@@ -2223,6 +2302,45 @@ export function createFilesystemAdapter({
     }
   };
 
+  const retirePreparedLauncher = async (snapshot) => {
+    if (!retireFinalLauncher) return;
+    const authority = snapshot?.preparedCandidate;
+    if (
+      !authority ||
+      (await executableDigest(authority.finalLauncher)) !== authority.finalLauncherSha256
+    ) {
+      throw new Error("prepared final launcher changed before retirement");
+    }
+    await retireFinalLauncher({
+      path: authority.finalLauncher,
+      sha256: authority.finalLauncherSha256,
+    });
+  };
+
+  const abandonPreparedLauncher = async (snapshot) => {
+    if (!abandonFinalLauncher || !snapshot?.preparedCandidate) return;
+    const authority = snapshot.preparedCandidate;
+    if ((await executableDigest(authority.finalLauncher)) !== authority.finalLauncherSha256) {
+      throw new Error("prepared final launcher changed before abandonment");
+    }
+    await abandonFinalLauncher({
+      path: authority.finalLauncher,
+      sha256: authority.finalLauncherSha256,
+    });
+  };
+
+  const preparedLauncherState = (snapshot) => {
+    const authority = snapshot?.preparedCandidate;
+    if (!authority) throw new Error("prepared final launcher authority is unavailable");
+    if (!sameExecutablePath(authority.finalLauncher, currentLayout.binary)) return "activated";
+    const owner = snapshot.installation.find(
+      (entry) =>
+        sameExecutablePath(entry.root, currentRoots.platformRoot) ||
+        isPathInside(entry.root, currentLayout.binary),
+    );
+    return owner?.activationState === "activated" ? "activated" : "prior";
+  };
+
   const recoverInterrupted = async (lease, expectedJournalToken) => {
     try {
       const metadata = await lstat(transactionRoot);
@@ -2234,7 +2352,8 @@ export function createFilesystemAdapter({
       throw error;
     }
     const snapshot = await hydrateJournal(lease, expectedJournalToken);
-    if (snapshot.phase === "commit_decided") {
+    if (["commit_decided", "commit_decided_retain_runtime"].includes(snapshot.phase)) {
+      const retainHistoricalRuntimes = snapshot.phase === "commit_decided_retain_runtime";
       if (!reconcileTrajectoryStore) {
         throw new Error("trajectory-store reconciliation is unavailable");
       }
@@ -2242,25 +2361,39 @@ export function createFilesystemAdapter({
       if (!settleProviderRepair) {
         throw new Error("candidate owned-adapter settlement is unavailable");
       }
-      await settleProviderRepair("commit", snapshot);
-      snapshot.phase = "committed";
+      await settleProviderRepair("commit", snapshot, "activated");
+      snapshot.phase = retainHistoricalRuntimes ? "committed_retain_runtime" : "committed";
       await writeJournal(snapshot);
+      if (!retainHistoricalRuntimes) await retirePreparedLauncher(snapshot);
       await cleanupCommittedActivation(snapshot);
       await rm(transactionRoot, { recursive: true, force: true });
       return;
     }
-    if (snapshot.phase === "commit_decided_no_repair") {
+    if (
+      ["commit_decided_no_repair", "commit_decided_no_repair_retain_runtime"].includes(
+        snapshot.phase,
+      )
+    ) {
+      const retainHistoricalRuntimes =
+        snapshot.phase === "commit_decided_no_repair_retain_runtime";
       if (!reconcileTrajectoryStore) {
         throw new Error("trajectory-store reconciliation is unavailable");
       }
       await reconcileTrajectoryStore(snapshot.preparedCandidate.finalLauncher, snapshot);
-      snapshot.phase = "committed";
+      snapshot.phase = retainHistoricalRuntimes ? "committed_retain_runtime" : "committed";
       await writeJournal(snapshot);
+      if (!retainHistoricalRuntimes) await retirePreparedLauncher(snapshot);
       await cleanupCommittedActivation(snapshot);
       await rm(transactionRoot, { recursive: true, force: true });
       return;
     }
     if (snapshot.phase === "committed") {
+      await retirePreparedLauncher(snapshot);
+      await cleanupCommittedActivation(snapshot);
+      await rm(transactionRoot, { recursive: true, force: true });
+      return;
+    }
+    if (snapshot.phase === "committed_retain_runtime") {
       await cleanupCommittedActivation(snapshot);
       await rm(transactionRoot, { recursive: true, force: true });
       return;
@@ -2269,11 +2402,12 @@ export function createFilesystemAdapter({
       if (!settleProviderRepair) {
         throw new Error("candidate owned-adapter settlement is unavailable");
       }
-      await settleProviderRepair("rollback", snapshot);
+      await settleProviderRepair("rollback", snapshot, preparedLauncherState(snapshot));
       snapshot.phase = "provider_rolled_back";
       await writeJournal(snapshot);
     }
     await restoreSnapshot(snapshot);
+    await abandonPreparedLauncher(snapshot);
   };
 
   const beginTransaction = async () => {
@@ -2440,11 +2574,45 @@ export function createFilesystemAdapter({
       }
       return snapshot.stagingPrefix;
     },
-    finalLauncher() {
-      return currentLayout.binary;
+    requiresFinalLauncherSettlement() {
+      return prepareFinalLauncher !== undefined;
+    },
+    preparedLauncherState(snapshot) {
+      return preparedLauncherState(snapshot);
+    },
+    async finalLauncher(candidate, version) {
+      const candidateRoots = validateInstallationLayout(candidate);
+      if (
+        !exactPublicVersion(version) ||
+        !isPathInside(path.join(transactionRoot, "candidate-prefix"), candidateRoots.wrapperRoot) ||
+        !isPathInside(path.join(transactionRoot, "candidate-prefix"), candidateRoots.platformRoot)
+      ) {
+        throw new Error("prepared final launcher authority is invalid");
+      }
+      const finalLauncher = prepareFinalLauncher
+        ? await prepareFinalLauncher(candidate, version)
+        : currentLayout.binary;
+      const candidateSha256 = await executableDigest(candidate.binary);
+      if (
+        typeof finalLauncher !== "string" ||
+        !path.isAbsolute(finalLauncher) ||
+        isPathInside(transactionRoot, finalLauncher) ||
+        (prepareFinalLauncher && (await executableDigest(finalLauncher)) !== candidateSha256)
+      ) {
+        throw new Error("prepared final launcher authority is invalid");
+      }
+      preparedFinalLauncherAuthority = {
+        path: finalLauncher,
+        sha256: candidateSha256,
+      };
+      return finalLauncher;
     },
     async recordPreparedCandidate(snapshot, candidate, finalLauncher) {
       const candidateRoots = validateInstallationLayout(candidate);
+      const authority = preparedFinalLauncherAuthority ?? {
+        path: currentLayout.binary,
+        sha256: await executableDigest(candidate.binary),
+      };
       if (
         !isPathInside(snapshot.stagingPrefix, candidateRoots.wrapperRoot) ||
         !isPathInside(snapshot.stagingPrefix, candidateRoots.platformRoot) ||
@@ -2455,7 +2623,9 @@ export function createFilesystemAdapter({
             !isPathInside(snapshot.stagingPrefix, shim) ||
             path.basename(shim).toLowerCase() !== path.basename(currentShims[index]).toLowerCase(),
         ) ||
-        !sameExecutablePath(finalLauncher, currentLayout.binary)
+        !sameExecutablePath(finalLauncher, authority.path) ||
+        (prepareFinalLauncher && (await executableDigest(finalLauncher)) !== authority.sha256) ||
+        (await executableDigest(candidate.binary)) !== authority.sha256
       ) {
         throw new Error("unsafe Mikie staged candidate");
       }
@@ -2482,6 +2652,7 @@ export function createFilesystemAdapter({
         shims: candidateRoots.shims,
         shimFingerprints,
         finalLauncher,
+        finalLauncherSha256: authority.sha256,
       };
       const runtime = path.join(transactionRoot, "recovery-runtime.mjs");
       const launcher = path.join(transactionRoot, "recover.mjs");
@@ -2506,6 +2677,7 @@ export function createFilesystemAdapter({
         node: process.execPath,
         candidate_binary: candidate.binary,
         final_launcher: finalLauncher,
+        final_launcher_sha256: authority.sha256,
       };
       const descriptorBytes = Buffer.from(`${JSON.stringify(recoveryDescriptor)}\n`);
       await atomicWritePrivate(descriptor, descriptorBytes);
@@ -2749,8 +2921,17 @@ export function createFilesystemAdapter({
         await writeJournal(snapshot);
       }
     },
-    async decideCommit(snapshot, { settlementRequired = true } = {}) {
-      snapshot.phase = settlementRequired ? "commit_decided" : "commit_decided_no_repair";
+    async decideCommit(
+      snapshot,
+      { settlementRequired = true, retainHistoricalRuntimes = false } = {},
+    ) {
+      snapshot.phase = retainHistoricalRuntimes
+        ? settlementRequired
+          ? "commit_decided_retain_runtime"
+          : "commit_decided_no_repair_retain_runtime"
+        : settlementRequired
+          ? "commit_decided"
+          : "commit_decided_no_repair";
       await writeJournal(snapshot);
     },
     async reconcileTrajectoryStore(snapshot) {
@@ -2865,9 +3046,13 @@ export function createFilesystemAdapter({
       await restoreSnapshot(snapshot);
       if (snapshot.autoLease) await releaseLease(snapshot.lease);
     },
-    async retire(snapshot) {
-      snapshot.phase = "committed";
+    async abandonPreparedLauncher(snapshot) {
+      await abandonPreparedLauncher(snapshot);
+    },
+    async retire(snapshot, { retainHistoricalRuntimes = false } = {}) {
+      snapshot.phase = retainHistoricalRuntimes ? "committed_retain_runtime" : "committed";
       await writeJournal(snapshot);
+      if (!retainHistoricalRuntimes) await retirePreparedLauncher(snapshot);
       await cleanupCommittedActivation(snapshot);
       await rm(snapshot.backupRoot, { recursive: true, force: true });
       if (snapshot.autoLease) await releaseLease(snapshot.lease);
@@ -2908,6 +3093,7 @@ export async function recoverExternalNpmUpdate(transactionRoot, expectedAuthorit
       "node",
       "candidate_binary",
       "final_launcher",
+      "final_launcher_sha256",
     ]) ||
     descriptor.schema_version !== RECOVERY_SCHEMA ||
     descriptor.transaction_root !== transactionRoot ||
@@ -2916,7 +3102,10 @@ export async function recoverExternalNpmUpdate(transactionRoot, expectedAuthorit
       (artifactPath) =>
         typeof artifactPath === "string" && isPathInside(transactionRoot, artifactPath),
     ) ||
-    descriptor.final_launcher !== descriptor.current_layout?.binary ||
+    typeof descriptor.final_launcher !== "string" ||
+    !path.isAbsolute(descriptor.final_launcher) ||
+    !/^[a-f0-9]{64}$/.test(descriptor.final_launcher_sha256) ||
+    typeof descriptor.current_layout?.binary !== "string" ||
     descriptor.node !== process.execPath ||
     !/^[a-f0-9]{64}$/.test(descriptor.runtime_sha256) ||
     !/^[a-f0-9]{64}$/.test(descriptor.launcher_sha256) ||
@@ -2947,6 +3136,12 @@ export async function recoverExternalNpmUpdate(transactionRoot, expectedAuthorit
   ) {
     throw new Error("tampered Mikie update recovery authority");
   }
+  if (
+    !sameExecutablePath(descriptor.final_launcher, descriptor.current_layout.binary) &&
+    (await executableDigest(descriptor.final_launcher)) !== descriptor.final_launcher_sha256
+  ) {
+    throw new Error("prepared final launcher changed");
+  }
   const journal = parseJsonNoDuplicateKeys(journalBytes);
   if (journal?.token !== descriptor.token) {
     throw new Error("Mikie update recovery authority does not match the journal");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getmikie/cli",
-  "version": "1.1.103",
+  "version": "1.1.104",
   "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.103",
-    "@getmikie/darwin-x64": "1.1.103",
-    "@getmikie/linux-x64-gnu": "1.1.103",
-    "@getmikie/win32-x64": "1.1.103"
+    "@getmikie/darwin-arm64": "1.1.104",
+    "@getmikie/darwin-x64": "1.1.104",
+    "@getmikie/linux-x64-gnu": "1.1.104",
+    "@getmikie/win32-x64": "1.1.104"
   },
   "publishConfig": {
     "access": "public",