@nissyai/desktop 0.2.55 → 0.2.59

package/src/mac-store.mjs

@@ -0,0 +1,664 @@
+/**
+ * The versioned store on macOS.
+ *
+ * Windows keeps `current` as a directory junction. macOS cannot: the app has to
+ * live at a real path in `~/Applications` for Spotlight, Launchpad, the Dock and
+ * the LaunchAgent, and LaunchServices treats a symlinked `.app` as a different
+ * item. So on macOS `current` IS the installed bundle, and the store holds
+ * everything else:
+ *
+ *     ~/Applications/Nissy.app          current — its Info.plist says which version
+ *     <cacheRoot>/store/
+ *       versions/0.2.57/app/Nissy.app   staged by the app, waiting for a restart
+ *       versions/0.2.56/app/Nissy.app   the bundle this one replaced (previous)
+ *       previous -> versions/0.2.56
+ *       pending.json, health.json, store.log, store.lock   (same as Windows)
+ *
+ * THE ONE RULE: the bundle is swapped only when nothing runs from it.
+ *
+ * Electron finds its helper apps (`Nissy Helper (Renderer).app` and friends) by
+ * path on disk every time it starts one. Replacing the bundle under a live
+ * process lets the old main process start the NEW version's helpers — "Unable to
+ * find helper app", or two framework versions talking to each other. Every Mac
+ * updater worth copying swaps after the app has gone: Squirrel.Mac's ShipIt
+ * installs on termination, Sparkle's Autoupdate waits for the host to exit,
+ * Velopack's UpdateMac closes the app first. This launcher is our ShipIt: the app
+ * relaunches it with its own pid and quits, and the launcher waits for the pid and
+ * for every process under the bundle before it touches anything.
+ *
+ * The decisions — seed, apply, roll back — are `store.mjs`'s `decideStartupAction`,
+ * fed the installed bundle's version. Only the pointer mechanics differ.
+ */
+
+import { execFileSync } from "node:child_process";
+import {
+  closeSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  readFileSync,
+  readSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  statSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, isAbsolute, join, relative } from "node:path";
+
+import { unsafeArchiveEntries } from "./resolve.mjs";
+import {
+  consumeTry,
+  decideStartupAction,
+  isCompleteVersion,
+  isNewer,
+  isSafeVersion,
+  listVersions,
+  LOCK_UNAVAILABLE,
+  prunableVersions,
+  pruneVersions,
+  readHealth,
+  readPending,
+  readPreviousVersion,
+  SEED_COMPLETE_MARKER,
+  STORE_ACTION,
+  clearPending,
+  storeLayout,
+  storeLog,
+  versionDir,
+  withStoreLock,
+  writeHealth,
+  writePending,
+} from "./store.mjs";
+
+/** How long the launcher waits for the app it was handed to exit. Generous: a
+ *  quit flushes the database and stops hosted services, and a swap that gives
+ *  up early only costs a later launch the same work. */
+export const EXIT_WAIT_MS = 30_000;
+
+/** What `prepareMacStore` did. `deferred` means a swap was needed and NOT done
+ *  because the bundle was in use; the caller tells the user. */
+export const MAC_STORE_OUTCOME = {
+  launch: "launch",
+  applied: "applied",
+  seeded: "seeded",
+  rolledBack: "rolled-back",
+  deferred: "deferred",
+  /** The npm payload was newer but the app was running: it was staged into the
+   *  store and requested, so the app's quit (or the next launcher run) applies it. */
+  stagedForLater: "staged-for-later",
+};
+
+// ── reading what is installed ─────────────────────────────────────────────
+
+/**
+ * The version of an installed `.app`, from its Info.plist, or null.
+ *
+ * The bundle itself is the authority. The `applications-darwin.version` marker
+ * is only what the last launcher wrote, and a user can replace the app by hand.
+ * Forge writes an XML plist, read with a regex; a binary plist (someone ran it
+ * through a tool) is handed to `plutil`, which ships with every macOS.
+ */
+export function readBundleVersion(bundlePath, { exec = execFileSync } = {}) {
+  const plist = join(bundlePath, "Contents", "Info.plist");
+  let raw;
+  try {
+    raw = readFileSync(plist);
+  } catch {
+    return null;
+  }
+  let version = null;
+  if (raw.subarray(0, 6).toString("latin1") === "bplist") {
+    try {
+      version = String(
+        exec("/usr/bin/plutil", ["-extract", "CFBundleShortVersionString", "raw", "-o", "-", plist], {
+          encoding: "utf8",
+          stdio: ["ignore", "pipe", "ignore"],
+        }),
+      ).trim();
+    } catch {
+      return null;
+    }
+  } else {
+    const m = /<key>CFBundleShortVersionString<\/key>\s*<string>([^<]+)<\/string>/u.exec(
+      raw.toString("utf8"),
+    );
+    version = m === null ? null : m[1].trim();
+  }
+  return version !== null && isSafeVersion(version) ? version : null;
+}
+
+/**
+ * The installed version: the bundle's own, falling back to the marker only when
+ * the bundle has an executable but an unreadable plist. No executable, no
+ * version — the store then seeds, which is the repair.
+ */
+export function installedMacVersion({ installedApp, exePath, markerPath }) {
+  if (!existsSync(exePath)) return null;
+  const fromBundle = readBundleVersion(installedApp);
+  if (fromBundle !== null) return fromBundle;
+  try {
+    const marker = readFileSync(markerPath, "utf8").trim();
+    return isSafeVersion(marker) ? marker : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Whether a file is plausibly a Mach-O executable: thin 64-bit, thin 32-bit, or
+ * universal. The macOS counterpart of `looksExecutable`'s "MZ" check, and for
+ * the same failures — truncation, a text file under the right name.
+ */
+export function looksMachO(filePath) {
+  let fd;
+  try {
+    if (statSync(filePath).size < 1024) return false;
+    fd = openSync(filePath, "r");
+    const head = Buffer.alloc(4);
+    if (readSync(fd, head, 0, 4, 0) !== 4) return false;
+    const magic = head.toString("hex");
+    return (
+      magic === "cffaedfe" || // MH_MAGIC_64, little-endian
+      magic === "cefaedfe" || // MH_MAGIC, little-endian
+      magic === "cafebabe" || // FAT_MAGIC (universal)
+      magic === "cafebabf" // FAT_MAGIC_64
+    );
+  } catch {
+    return false;
+  } finally {
+    if (fd !== undefined) {
+      try {
+        closeSync(fd);
+      } catch {
+        /* nothing to do */
+      }
+    }
+  }
+}
+
+/** `versions/<ver>/app/<Bundle>.app` — the same shape the Windows store and
+ *  the app's `payloadExeSegments` use, so both sides find one executable. */
+export function stagedBundlePath(layout, version, bundleName) {
+  return join(versionDir(layout, version), "app", bundleName);
+}
+
+/** A version directory that finished staging AND holds a runnable bundle. */
+export function isStagedMacVersion(layout, version, exeSegments) {
+  if (!isSafeVersion(version)) return false;
+  const dir = versionDir(layout, version);
+  return isCompleteVersion(dir) && looksMachO(join(dir, ...exeSegments));
+}
+
+// ── is anything running from the bundle? ─────────────────────────────────
+
+/** Every running executable's path. `comm` is the full path on macOS. */
+export function listProcessPaths({ exec = execFileSync } = {}) {
+  try {
+    return String(exec("/bin/ps", ["-axo", "comm="], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }))
+      .split("\n")
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0);
+  } catch {
+    // If we cannot tell, we must assume the worst: something is running.
+    return null;
+  }
+}
+
+/**
+ * Processes running from the installed bundle — the main binary, its Helper
+ * apps, the crash handler. Null when `ps` could not be read, which callers treat
+ * as busy: swapping blind is the one thing this module exists not to do.
+ */
+export function bundleProcesses(installedApp, list = listProcessPaths) {
+  const paths = list();
+  if (paths === null) return null;
+  const prefix = `${installedApp}/`;
+  return paths.filter((p) => p.startsWith(prefix));
+}
+
+function isAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // EPERM means it exists but is not ours — still alive.
+    return err && err.code === "EPERM";
+  }
+}
+
+function sleepMs(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/**
+ * Wait until `pid` (if given) has exited and nothing runs from the bundle.
+ * Returns whether the bundle is idle. Bounded, and synchronous like the rest of
+ * the launcher.
+ */
+export function waitForBundleIdle({
+  pid = null,
+  installedApp,
+  timeoutMs = EXIT_WAIT_MS,
+  list = listProcessPaths,
+  alive = isAlive,
+  sleep = sleepMs,
+  now = Date.now,
+}) {
+  const deadline = now() + timeoutMs;
+  for (;;) {
+    const pidGone = pid === null || !alive(pid);
+    const running = bundleProcesses(installedApp, list);
+    if (pidGone && running !== null && running.length === 0) return true;
+    if (now() >= deadline) return false;
+    sleep(250);
+  }
+}
+
+// ── moving bundles ────────────────────────────────────────────────────────
+
+/**
+ * Move a bundle. A rename when both paths share a device — always, in practice,
+ * since the store and ~/Applications both live under the home directory — and
+ * otherwise `ditto` (which preserves the framework symlinks and extended
+ * attributes a bundle depends on) to a sibling path, then a same-directory
+ * rename, so the destination only ever appears complete.
+ */
+export function moveBundle(src, dest, { rename = renameSync, exec = execFileSync } = {}) {
+  mkdirSync(dirname(dest), { recursive: true });
+  try {
+    rename(src, dest);
+    return;
+  } catch (err) {
+    if (!err || err.code !== "EXDEV") throw err;
+  }
+  const sibling = `${dest}.moving.${process.pid}`;
+  rmSync(sibling, { recursive: true, force: true });
+  exec("/usr/bin/ditto", [src, sibling], { stdio: "ignore" });
+  rename(sibling, dest);
+  rmSync(src, { recursive: true, force: true });
+}
+
+function repointSymlink(linkPath, targetDir) {
+  try {
+    rmSync(linkPath, { recursive: false, force: true });
+  } catch {
+    /* nothing there */
+  }
+  symlinkSync(targetDir, linkPath, "dir");
+}
+
+/**
+ * Make `version` (already staged under `versions/<version>/app/`) the installed
+ * bundle, keeping whatever was installed as `previous`.
+ *
+ * Two renames. The second can fail — a full disk, a permissions surprise — and
+ * a failure between them is the moment an updater can lose a user's app: the
+ * Tauri updater did exactly that, with its backup in a temporary directory that
+ * deleted itself. So the backup lives in the store, and a failed second rename
+ * puts it straight back before the error propagates. Sparkle closes the gap
+ * entirely with `renamex_np(RENAME_SWAP)`, which Node cannot reach; the window
+ * here is two syscalls wide.
+ *
+ * The CALLER guarantees nothing runs from the bundle.
+ */
+export function swapInBundle({
+  layout,
+  version,
+  bundleName,
+  installedApp,
+  markerPath,
+  fsOps = {},
+  log = () => {},
+}) {
+  const incomingDir = versionDir(layout, version);
+  const incoming = join(incomingDir, "app", bundleName);
+  if (!existsSync(incoming)) throw new Error(`version ${version} has no ${bundleName} in the store`);
+
+  const outgoingVersion = existsSync(installedApp) ? readBundleVersion(installedApp) : null;
+  let aside = null;
+  let retainedDir = null;
+  if (existsSync(installedApp)) {
+    if (outgoingVersion !== null && outgoingVersion !== version) {
+      retainedDir = versionDir(layout, outgoingVersion);
+      try {
+        rmSync(retainedDir, { recursive: true, force: true });
+        aside = join(retainedDir, "app", bundleName);
+      } catch (err) {
+        // A leftover copy we cannot delete — macOS App Management can refuse to
+        // modify a bundle that has been launched. Losing the rollback target is
+        // survivable; failing the update over it is not.
+        log(`could not clear ${retainedDir} (${err.message}); not keeping ${outgoingVersion} as previous`);
+        retainedDir = null;
+      }
+    }
+    if (aside === null) {
+      // Unreadable, or the same version being reinstalled: keep it only for the
+      // length of the swap, as a way back if the second rename fails.
+      // A fresh name every time, so nothing has to be deleted before the move.
+      aside = join(layout.root, "displaced", `${String(process.pid)}-${String(Date.now())}`, bundleName);
+    }
+    moveBundle(installedApp, aside, fsOps);
+  }
+
+  try {
+    moveBundle(incoming, installedApp, fsOps);
+  } catch (err) {
+    if (aside !== null) {
+      try {
+        moveBundle(aside, installedApp, fsOps);
+        log(`swap to ${version} failed; restored the installed bundle`);
+      } catch (restoreErr) {
+        log(`swap to ${version} failed AND the restore failed: ${restoreErr.message}; the bundle is at ${aside}`);
+      }
+    }
+    throw err;
+  }
+
+  // Past the point of no return: the new bundle is installed. Everything below
+  // is bookkeeping, and a failure in it must not be reported as a failed swap.
+  try {
+    mkdirSync(dirname(markerPath), { recursive: true });
+    writeFileSync(markerPath, version);
+  } catch {
+    /* the Info.plist is the authority; the marker is for older launchers */
+  }
+  if (retainedDir !== null) {
+    try {
+      writeFileSync(join(retainedDir, SEED_COMPLETE_MARKER), new Date().toISOString());
+      repointSymlink(layout.previousLink, retainedDir);
+    } catch (err) {
+      log(`could not record ${outgoingVersion} as previous: ${err.message}`);
+    }
+  } else if (aside !== null) {
+    rmSync(dirname(aside), { recursive: true, force: true });
+  }
+  // The staged version's directory is now an empty shell; its bundle is installed.
+  rmSync(incomingDir, { recursive: true, force: true });
+  try {
+    execFileSync("/usr/bin/mdimport", [installedApp], { stdio: "ignore" });
+  } catch {
+    /* Spotlight indexes ~/Applications on its own schedule too */
+  }
+  return { previousVersion: retainedDir === null ? null : outgoingVersion };
+}
+
+// ── unpacking the npm payload into the store ─────────────────────────────
+
+function isPathInside(root, candidate) {
+  const escaped = relative(root, candidate);
+  return escaped !== "" && !escaped.startsWith("..") && !isAbsolute(escaped);
+}
+
+/**
+ * Whether an extracted bundle is a real directory inside `root` whose every
+ * symlink resolves inside `root` too. The name check in `unsafeArchiveEntries`
+ * cannot see where a symlink POINTS; this walks the tree without following
+ * directories and asks. MIRRORED in the app's `mac-bundle.ts`, with a parity test.
+ */
+export function isExtractedBundleInside(root, bundlePath) {
+  try {
+    const rootReal = realpathSync(root);
+    const bundleStat = lstatSync(bundlePath);
+    if (bundleStat.isSymbolicLink() || !bundleStat.isDirectory()) return false;
+    if (!isPathInside(rootReal, realpathSync(bundlePath))) return false;
+    const pending = [bundlePath];
+    while (pending.length > 0) {
+      const current = pending.pop();
+      if (current === undefined) continue;
+      const stat = lstatSync(current);
+      if (stat.isSymbolicLink()) {
+        if (!isPathInside(rootReal, realpathSync(current))) return false;
+        continue;
+      }
+      if (!stat.isDirectory()) continue;
+      for (const entry of readdirSync(current)) pending.push(join(current, entry));
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Refuse an archive with any entry that would escape the extraction directory. */
+export function validateArchive(archivePath, { exec = execFileSync } = {}) {
+  const listing = String(
+    exec("tar", ["-tzf", archivePath], { encoding: "utf8", stdio: ["ignore", "pipe", "inherit"] }),
+  );
+  const entries = listing
+    .split(/\r?\n/u)
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+  const unsafe = unsafeArchiveEntries(entries);
+  if (unsafe.length > 0) {
+    throw new Error(`payload archive contains unsafe entries: ${unsafe.slice(0, 5).join(", ")}`);
+  }
+}
+
+/**
+ * Extract the npm payload's `app.tar.gz` into the store as `version`, marked
+ * complete only once the bundle is verified. An interrupted run leaves an
+ * unmarked directory, which is treated as absent and cleared next time.
+ */
+export function seedMacVersion({ layout, version, archivePath, bundleName, exeSegments }) {
+  const dir = versionDir(layout, version);
+  rmSync(dir, { recursive: true, force: true });
+  const appDir = join(dir, "app");
+  mkdirSync(appDir, { recursive: true });
+  try {
+    validateArchive(archivePath);
+    execFileSync("tar", ["-xzf", archivePath, "-C", appDir], { stdio: "inherit" });
+    const bundle = join(appDir, bundleName);
+    if (!isExtractedBundleInside(dir, bundle)) {
+      throw new Error(`payload archive did not contain a safe ${bundleName}`);
+    }
+    if (!looksMachO(join(dir, ...exeSegments))) {
+      throw new Error(`payload ${version} has no runnable executable`);
+    }
+    writeFileSync(join(dir, SEED_COMPLETE_MARKER), new Date().toISOString());
+  } catch (err) {
+    rmSync(dir, { recursive: true, force: true });
+    throw err;
+  }
+}
+
+// ── the startup decision, macOS edition ──────────────────────────────────
+
+/**
+ * Decide what the macOS store needs, do it if nothing is running from the
+ * bundle, and report what happened.
+ *
+ * Never throws: a failure is logged to the store log and reported as `launch`,
+ * because the installed bundle — whatever version it is — is still there and
+ * still the right thing to open. The one exception is a bundle that does not
+ * exist and cannot be seeded; the caller fails with a clear message then.
+ *
+ * @param {{
+ *   home: string, env: NodeJS.ProcessEnv, cacheName?: string,
+ *   installedApp: string, exePath: string, bundleName: string,
+ *   exeSegments: readonly string[], markerPath: string,
+ *   payloadVersion: string, archivePath: string | null,
+ *   afterPid?: number | null,
+ *   willLaunch?: boolean,
+ *   list?: () => string[] | null,
+ *   log?: (message: string) => void,
+ * }} input
+ */
+export function prepareMacStore({
+  home,
+  env,
+  cacheName,
+  installedApp,
+  exePath,
+  bundleName,
+  exeSegments,
+  markerPath,
+  payloadVersion,
+  archivePath,
+  afterPid = null,
+  // Whether the caller will open the app after this. An attempt at an unproven
+  // version is spent only when it is actually launched: apply-only runs on
+  // every quit, and spending an attempt there rolled good updates back after
+  // three quits without the app ever getting a chance to confirm itself.
+  willLaunch = true,
+  list = listProcessPaths,
+  waitMs = EXIT_WAIT_MS,
+  log = () => {},
+}) {
+  let layout = null;
+  try {
+    layout = storeLayout({ platform: "darwin", home, env, ...(cacheName ? { cacheName } : {}) });
+    const L = layout;
+    const note = (message) => {
+      log(`store: ${message}`);
+      storeLog(L, message);
+    };
+
+    // Handed a pid by the app that is quitting: wait for it, and for its
+    // helpers, before looking at anything. Outside the lock, because the wait
+    // can be long and other launchers must not time out behind it.
+    const idleAfterWait =
+      afterPid === null
+        ? null
+        : waitForBundleIdle({ pid: afterPid, installedApp, timeoutMs: waitMs, list });
+    if (idleAfterWait === false) note(`pid ${String(afterPid)} or the bundle was still running after ${String(waitMs)}ms`);
+
+    const canSeed = archivePath !== null && existsSync(archivePath);
+    const decide = () =>
+      decideStartupAction({
+        currentVersion: installedMacVersion({ installedApp, exePath, markerPath }),
+        previousVersion: readPreviousVersion(L),
+        pending: readPending(L),
+        health: readHealth(L),
+        // An empty string never seeds (it is not a safe version), which is how a
+        // missing npm payload says "nothing to seed from".
+        payloadVersion: canSeed ? payloadVersion : "",
+        versionExists: (v) => isStagedMacVersion(L, v, exeSegments),
+      });
+
+    let decision = decide();
+    note(`${decision.action}: ${decision.reason}`);
+    if (decision.action === STORE_ACTION.launch) {
+      return { outcome: MAC_STORE_OUTCOME.launch, version: installedMacVersion({ installedApp, exePath, markerPath }), awaitingConfirmation: willLaunch && spendAttempt(L, installedApp, exePath, markerPath) };
+    }
+
+    // Every other action swaps the bundle. Not while anything runs from it.
+    const running = bundleProcesses(installedApp, list);
+    const busy = running === null || running.length > 0;
+    if (busy) {
+      if (decision.action === STORE_ACTION.seed && canSeed && decision.version !== null) {
+        // npm has something newer and the app is up. Stage it instead, so the
+        // app's quit — or the next launcher run — applies it without anyone
+        // having to remember to come back.
+        const staged = withStoreLock(L, () => {
+          if (!isStagedMacVersion(L, decision.version, exeSegments)) {
+            seedMacVersion({ layout: L, version: decision.version, archivePath, bundleName, exeSegments });
+          }
+          const pending = readPending(L);
+          if (pending === null || isNewer(decision.version, pending.version)) writePending(L, decision.version);
+          return true;
+        });
+        if (staged !== LOCK_UNAVAILABLE) {
+          note(`Nissy is running; staged ${decision.version} to apply when it quits`);
+          return { outcome: MAC_STORE_OUTCOME.stagedForLater, version: decision.version, awaitingConfirmation: false };
+        }
+      }
+      note(`${decision.action} ${decision.version ?? ""} deferred: Nissy is running`);
+      return { outcome: MAC_STORE_OUTCOME.deferred, version: decision.version, awaitingConfirmation: false };
+    }
+
+    let outcome = MAC_STORE_OUTCOME.launch;
+    const held = withStoreLock(L, () => {
+      // Re-decided under the lock: another launcher may have acted while this
+      // one was waiting for it.
+      decision = decide();
+      switch (decision.action) {
+        case STORE_ACTION.seed:
+          if (!isStagedMacVersion(L, decision.version, exeSegments)) {
+            seedMacVersion({ layout: L, version: decision.version, archivePath, bundleName, exeSegments });
+          }
+          swapInBundle({ layout: L, version: decision.version, bundleName, installedApp, markerPath, log: note });
+          // A freshly seeded version came from the user's own `npm i -g`; nothing
+          // is pending against it.
+          clearPending(L);
+          writeHealth(L, decision.version);
+          outcome = MAC_STORE_OUTCOME.seeded;
+          break;
+        case STORE_ACTION.applyPending:
+          swapInBundle({ layout: L, version: decision.version, bundleName, installedApp, markerPath, log: note });
+          // Not confirmed here: the app writes health once it has actually
+          // started, and until then the version is on trial.
+          writePending(L, decision.version);
+          outcome = MAC_STORE_OUTCOME.applied;
+          break;
+        case STORE_ACTION.rollback:
+          swapInBundle({ layout: L, version: decision.version, bundleName, installedApp, markerPath, log: note });
+          clearPending(L);
+          outcome = MAC_STORE_OUTCOME.rolledBack;
+          break;
+        default:
+          break;
+      }
+    });
+    if (held === LOCK_UNAVAILABLE) {
+      note("another launcher holds the store lock; opening the installed bundle as it is");
+      return { outcome: MAC_STORE_OUTCOME.deferred, version: decision.version, awaitingConfirmation: false };
+    }
+    note(`${outcome} ${decision.version ?? ""}`);
+    return {
+      outcome,
+      version: installedMacVersion({ installedApp, exePath, markerPath }),
+      awaitingConfirmation: willLaunch && spendAttempt(L, installedApp, exePath, markerPath),
+    };
+  } catch (err) {
+    const detail = (err && err.stack) || String(err);
+    if (layout !== null) storeLog(layout, `FAILED, opening the installed bundle as it is\n${detail}`);
+    log(`store unavailable (${err && err.message}); opening the installed bundle as it is`);
+    return { outcome: MAC_STORE_OUTCOME.launch, version: null, awaitingConfirmation: false, error: err };
+  }
+}
+
+/** Spend one attempt when the installed version is on trial — exactly the
+ *  Windows rule, so a version that never confirms is rolled back after three
+ *  launcher-started launches. */
+function spendAttempt(layout, installedApp, exePath, markerPath) {
+  const current = installedMacVersion({ installedApp, exePath, markerPath });
+  const pending = readPending(layout);
+  const health = readHealth(layout);
+  if (current === null || pending === null || pending.version !== current) return false;
+  if (health !== null && health.version === current) return false;
+  const held = withStoreLock(layout, () => consumeTry(layout), { waitMs: 0 });
+  return held !== LOCK_UNAVAILABLE;
+}
+
+/**
+ * Prune versions nothing refers to. On macOS the APP confirms its own start
+ * (the launcher hands off to LaunchServices and cannot watch the process), so
+ * this only tidies — current is the installed bundle, which is never in
+ * `versions/`, so what is kept is `previous` and anything pending.
+ */
+export function pruneMacStore({ home, env, cacheName }) {
+  try {
+    const layout = storeLayout({ platform: "darwin", home, env, ...(cacheName ? { cacheName } : {}) });
+    withStoreLock(
+      layout,
+      () => {
+        const dead = prunableVersions({
+          versions: listVersions(layout),
+          currentVersion: null,
+          previousVersion: readPreviousVersion(layout),
+          pending: readPending(layout),
+        });
+        if (dead.length > 0) storeLog(layout, `pruning ${dead.join(", ")}`);
+        pruneVersions(layout, dead);
+        rmSync(join(layout.root, "displaced"), { recursive: true, force: true });
+      },
+      { waitMs: 0 },
+    );
+  } catch {
+    /* tidying must never affect a launch */
+  }
+}

package/src/resolve.d.mts

@@ -12,3 +12,7 @@ export declare const PAYLOADS: Record<
   string,
   { pkg: string; exe: readonly string[] }
 >;
+
+/** Archive entries that would escape the extraction directory. Mirrored by the
+ *  app's `mac-bundle.ts`; enforced by `mac-bundle.test.ts`. */
+export declare function unsafeArchiveEntries(entries: readonly string[]): string[];

package/src/resolve.mjs

@@ -247,20 +247,3 @@ export function resolveLaunchCommand({
     viaLaunchServices: false,
   };
 }
-
-/**
- * Whether the macOS ~/Applications install needs (re)writing: when the recorded
- * install-version marker doesn't match the payload version, or the installed
- * bundle's executable is missing. Pure so the decision is unit-testable; the
- * launcher does the filesystem work.
- *
- * @param {{ markerVersion: string | null, payloadVersion: string, exeExists: boolean }} input
- * @returns {boolean}
- */
-export function needsMacReinstall({
-  markerVersion,
-  payloadVersion,
-  exeExists,
-}) {
-  return !exeExists || markerVersion !== payloadVersion;
-}