@nissyai/desktop 0.2.36 → 0.2.38

package/src/store.mjs

@@ -0,0 +1,977 @@
+/**
+ * The versioned application store.
+ *
+ * WHY THIS EXISTS
+ *
+ * The npm channel used to update itself by running `npm i -g`. That cannot be made
+ * safe. npm's global reify renames the installed package to a hidden directory before
+ * unpacking the replacement, and rolls that rename back only on a best-effort basis. On
+ * Windows the running `nissy.exe` is locked, so the unpack fails, the rollback fails
+ * too, and the package is gone from npm's view — an update that ends with no
+ * application installed at all. That has happened to a real machine.
+ *
+ * The replacement never lets anything mutate the copy that is running. Each version
+ * lives in its own directory and a pointer says which one is current:
+ *
+ *     <cacheRoot>/store/
+ *       versions/0.2.35/      one extracted application per version
+ *       versions/0.2.36/
+ *       current   ->          pointer at the version that runs
+ *       previous  ->          pointer at the one before, kept for rollback
+ *       pending.json          a staged version waiting for a restart
+ *       health.json           the last version that started successfully
+ *
+ * Updating is: download beside the running copy, verify it, then move a pointer. The
+ * worst outcome of any failure is "still on the old version", because the old version
+ * was never touched.
+ *
+ * WHAT LIVES HERE
+ *
+ * Path resolution, the small JSON state files, and the DECISIONS — seed, apply, roll
+ * back, prune — as pure functions. The filesystem work and the platform-specific
+ * pointer mechanics (a directory junction on Windows, the `~/Applications` bundle on
+ * macOS) stay in the launcher, so every rule below is unit-testable without a store on
+ * disk.
+ */
+
+import {
+  appendFileSync,
+  closeSync,
+  openSync,
+  readSync,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  linkSync,
+  readdirSync,
+  realpathSync,
+  rmSync,
+  statSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, join } from "node:path";
+
+import { cacheRootSegments } from "./resolve.mjs";
+
+/** Subdirectory of the per-user cache root that holds the whole store. */
+export const STORE_DIRNAME = "store";
+
+/**
+ * Written last inside a version directory, and required before that version is
+ * considered usable.
+ *
+ * This replaces an earlier staging-plus-rename. Renaming a freshly populated
+ * 450 MB tree fails with EPERM on Windows often enough to matter: the seed hard
+ * links from a just-extracted copy, so Defender is still scanning those inodes,
+ * and a directory containing an open handle cannot be renamed. Observed on a
+ * real machine seeding two published builds back to back. Writing in place and
+ * marking completion at the end removes the rename entirely rather than
+ * retrying it, and gives the same guarantee: a directory without this file was
+ * never finished and is treated as absent.
+ */
+export const SEED_COMPLETE_MARKER = ".seed-complete";
+
+/**
+ * Resolve every path in the store for a host.
+ *
+ * @param {{ platform: NodeJS.Platform, home: string, env: NodeJS.ProcessEnv, cacheName?: string }} input
+ * @returns {{ root: string, versionsDir: string, currentLink: string, previousLink: string, pendingFile: string, healthFile: string }}
+ */
+export function storeLayout({ platform, home, env, cacheName }) {
+  const root = join(
+    ...cacheRootSegments({ platform, home, env, ...(cacheName ? { cacheName } : {}) }),
+    STORE_DIRNAME,
+  );
+  return {
+    root,
+    versionsDir: join(root, "versions"),
+    currentLink: join(root, "current"),
+    previousLink: join(root, "previous"),
+    pendingFile: join(root, "pending.json"),
+    healthFile: join(root, "health.json"),
+    logFile: join(root, "store.log"),
+    lockDir: join(root, "store.lock"),
+  };
+}
+
+/**
+ * Directory for one version. Version strings come from a package.json we published, but
+ * this path is joined into the filesystem, so anything that could climb out of the
+ * store is refused rather than sanitised — a silently rewritten version number would be
+ * worse than a hard failure.
+ *
+ * @param {{ versionsDir: string }} layout
+ * @param {string} version
+ * @returns {string}
+ */
+export function versionDir(layout, version) {
+  if (!isSafeVersion(version)) {
+    throw new Error(`unsafe version string: ${JSON.stringify(version)}`);
+  }
+  return join(layout.versionsDir, version);
+}
+
+/** Semver-ish, and free of anything that means something to a path.
+ *
+ *  The leading character may not be a dot. Nothing publishes a version starting
+ *  with one, and the store's own bookkeeping lives in dotfiles — `.seed-complete`
+ *  is a name a "version" could otherwise claim. Mirrored in the app's
+ *  `npm-store.ts`; `npm-store.parity.test.ts` fails if the two drift, which is
+ *  how this rule got tightened. */
+export function isSafeVersion(version) {
+  return (
+    typeof version === "string" &&
+    /^[0-9A-Za-z][0-9A-Za-z.+-]{0,63}$/.test(version) &&
+    !version.includes("..")
+  );
+}
+
+// ── version comparison ────────────────────────────────────────────────────
+//
+// MIRRORS `compareVersions` in apps/desktop/src/main/features/auto-update/npx-update.ts.
+// The launcher and the app are published together but share no runtime code, so this
+// parallel copy is deliberate — the same reason `cacheRootSegments` is duplicated. The
+// test suite pins the same cases as the app's, so a divergence fails somewhere.
+
+/** @returns {{ core: [number, number, number], pre: number | null } | null} */
+function parseVersion(version) {
+  const m = /^(\d+)\.(\d+)\.(\d+)(?:-alpha\.(\d+))?$/u.exec(String(version).trim());
+  if (m === null) return null;
+  const core = [Number(m[1]), Number(m[2]), Number(m[3])];
+  const pre = m[4] === undefined ? null : Number(m[4]);
+  if (!core.every(Number.isSafeInteger)) return null;
+  if (pre !== null && !Number.isSafeInteger(pre)) return null;
+  return { core, pre };
+}
+
+/**
+ * -1 / 0 / 1. A release outranks a prerelease of the same core. An unparseable version
+ * sorts oldest, so a version we cannot read never wins a comparison and never triggers
+ * a seed or an update.
+ */
+export function compareVersions(a, b) {
+  const pa = parseVersion(a);
+  const pb = parseVersion(b);
+  if (pa === null && pb === null) return 0;
+  if (pa === null) return -1;
+  if (pb === null) return 1;
+  for (let i = 0; i < 3; i += 1) {
+    if (pa.core[i] !== pb.core[i]) return pa.core[i] < pb.core[i] ? -1 : 1;
+  }
+  if (pa.pre === pb.pre) return 0;
+  if (pa.pre === null) return 1; // release > prerelease
+  if (pb.pre === null) return -1;
+  return pa.pre < pb.pre ? -1 : 1;
+}
+
+export function isNewer(candidate, than) {
+  return compareVersions(candidate, than) > 0;
+}
+
+// ── state files ───────────────────────────────────────────────────────────
+
+/** Read and parse a JSON file, or null when absent/unreadable/malformed. */
+function readJson(path) {
+  let raw;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed !== null && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeJson(path, value) {
+  mkdirSync(join(path, ".."), { recursive: true });
+  writeFileSync(path, JSON.stringify(value), "utf8");
+}
+
+/**
+ * How many launches a newly applied version gets to prove it starts.
+ *
+ * Three, matching systemd-boot's default boot counting. ChromeOS uses five;
+ * Android leaves the count to the bootloader. The shape is the same everywhere:
+ * a bounded number of attempts, then an automatic return to the last version
+ * known to work.
+ */
+export const DEFAULT_TRIES = 3;
+
+/** @returns {{ version: string, triesLeft: number } | null} */
+export function readPending(layout) {
+  const p = readJson(layout.pendingFile);
+  if (!p || !isSafeVersion(p.version)) return null;
+  // A pending file written before tries existed is treated as having a full
+  // allowance rather than none, so an in-flight update is not rolled back by
+  // the upgrade that introduced the counter.
+  const triesLeft = Number.isInteger(p.triesLeft) ? p.triesLeft : DEFAULT_TRIES;
+  return { version: p.version, triesLeft };
+}
+
+export function writePending(layout, version, triesLeft = DEFAULT_TRIES) {
+  writeJson(layout.pendingFile, {
+    version,
+    triesLeft,
+    stagedAt: new Date().toISOString(),
+  });
+}
+
+/** Record one attempt at starting the pending version. */
+export function consumeTry(layout) {
+  const pending = readPending(layout);
+  if (pending === null) return null;
+  const next = { ...pending, triesLeft: pending.triesLeft - 1 };
+  writeJson(layout.pendingFile, { ...next, stagedAt: new Date().toISOString() });
+  return next;
+}
+
+export function clearPending(layout) {
+  try {
+    rmSync(layout.pendingFile, { force: true });
+  } catch {
+    /* best-effort: a stale pending is re-evaluated, not fatal */
+  }
+}
+
+/** @returns {{ version: string } | null} */
+export function readHealth(layout) {
+  const h = readJson(layout.healthFile);
+  return h && isSafeVersion(h.version) ? { version: h.version } : null;
+}
+
+export function writeHealth(layout, version) {
+  writeJson(layout.healthFile, { version, confirmedAt: new Date().toISOString() });
+}
+
+/** Version directories present, unsorted. */
+export function listVersions(layout) {
+  try {
+    return readdirSync(layout.versionsDir, { withFileTypes: true })
+      .filter(
+        (e) =>
+          e.isDirectory() &&
+          isSafeVersion(e.name) &&
+          isCompleteVersion(join(layout.versionsDir, e.name)),
+      )
+      .map((e) => e.name);
+  } catch {
+    return [];
+  }
+}
+
+// ── the decisions ─────────────────────────────────────────────────────────
+
+/**
+ * Should the npm payload be copied into the store as a version?
+ *
+ * The subtle case, and the reason this is not simply "they differ": after a
+ * self-update the store is AHEAD of npm. The npm payload is whatever was last
+ * installed by `npm i -g` and goes stale the moment the app updates itself. Seeding on
+ * inequality would therefore downgrade every self-updated user back to their install
+ * version on the next launch.
+ *
+ * So: seed when there is no current version at all (first run, or a store that lost
+ * its pointer), or when npm genuinely carries something NEWER — which is what happens
+ * when a user runs `npm i -g` themselves to jump forward or to repair a broken store.
+ *
+ * @param {{ currentVersion: string | null, payloadVersion: string, versionExists: boolean }} input
+ * @returns {boolean}
+ */
+export function shouldSeedFromPayload({ currentVersion, payloadVersion, versionExists }) {
+  if (!isSafeVersion(payloadVersion)) return false;
+  if (currentVersion === null) return true;
+  if (!isNewer(payloadVersion, currentVersion)) return false;
+  // Newer, but already extracted by an earlier run — point at it, don't re-extract.
+  return !versionExists;
+}
+
+/** What the launcher should do about the store before it spawns anything. */
+export const STORE_ACTION = {
+  /** Nothing to do; launch `current`. */
+  launch: "launch",
+  /** Copy/extract the npm payload in, then point `current` at it. */
+  seed: "seed",
+  /** A staged version is ready; point `current` at it before launching. */
+  applyPending: "apply-pending",
+  /** The last applied version never reported a healthy start; go back. */
+  rollback: "rollback",
+};
+
+/**
+ * The single decision the launcher makes at startup.
+ *
+ * Order matters and encodes the safety rules:
+ *
+ *  1. **Rollback wins.** A `current` that was applied from `pending` but never wrote
+ *     `health.json` did not start. Launching it again would loop a user into a version
+ *     that cannot run, which is the one failure worse than not updating.
+ *  2. **Then seeding**, so a store with no pointer — or one a user has just repaired
+ *     with `npm i -g` — becomes launchable before anything else is considered.
+ *  3. **Then a pending apply.** The user chose "later", or the app staged an update and
+ *     the process was killed before it restarted itself; either way the next launch
+ *     picks it up, the way Velopack applies on startup.
+ *
+ * @param {{
+ *   currentVersion: string | null,
+ *   previousVersion: string | null,
+ *   pending: { version: string } | null,
+ *   health: { version: string } | null,
+ *   payloadVersion: string,
+ *   versionExists: (version: string) => boolean,
+ * }} input
+ * @returns {{ action: string, version: string | null, reason: string }}
+ */
+export function decideStartupAction({
+  currentVersion,
+  previousVersion,
+  pending,
+  health,
+  payloadVersion,
+  versionExists,
+}) {
+  // 1. Did the version we last switched to fail to start, repeatedly?
+  //    `pending` still naming the CURRENT version means the swap happened but the
+  //    healthy-start handshake never completed. One failure is not enough to act
+  //    on — a machine can be rebooted mid-launch — so this waits for the attempt
+  //    allowance to run out, the way systemd-boot, ChromeOS and Android A/B all
+  //    do. Every one of those requires a POSITIVE signal from userspace and
+  //    bounds the number of attempts; none treat "the process was created" as
+  //    proof that anything started.
+  if (
+    pending !== null &&
+    currentVersion !== null &&
+    pending.version === currentVersion &&
+    (health === null || health.version !== currentVersion) &&
+    pending.triesLeft <= 0 &&
+    previousVersion !== null &&
+    previousVersion !== currentVersion &&
+    versionExists(previousVersion)
+  ) {
+    return {
+      action: STORE_ACTION.rollback,
+      version: previousVersion,
+      reason: `${currentVersion} was applied but never confirmed a start in ${DEFAULT_TRIES} attempts; going back to ${previousVersion}`,
+    };
+  }
+
+  // 2. No launchable current, or npm is genuinely ahead.
+  if (
+    shouldSeedFromPayload({
+      currentVersion,
+      payloadVersion,
+      versionExists: versionExists(payloadVersion),
+    })
+  ) {
+    return {
+      action: STORE_ACTION.seed,
+      version: payloadVersion,
+      reason:
+        currentVersion === null
+          ? `no current version; seeding ${payloadVersion} from the npm payload`
+          : `npm payload ${payloadVersion} is newer than ${currentVersion}`,
+    };
+  }
+
+  // A current version that npm is ahead of, but whose directory already exists, just
+  // needs the pointer moved.
+  if (
+    currentVersion !== null &&
+    isNewer(payloadVersion, currentVersion) &&
+    versionExists(payloadVersion)
+  ) {
+    return {
+      action: STORE_ACTION.applyPending,
+      version: payloadVersion,
+      reason: `npm payload ${payloadVersion} is already extracted; pointing current at it`,
+    };
+  }
+
+  // 3. A staged version waiting for this restart.
+  if (
+    pending !== null &&
+    pending.version !== currentVersion &&
+    versionExists(pending.version)
+  ) {
+    return {
+      action: STORE_ACTION.applyPending,
+      version: pending.version,
+      reason: `applying staged version ${pending.version}`,
+    };
+  }
+
+  return { action: STORE_ACTION.launch, version: currentVersion, reason: "current is up to date" };
+}
+
+/**
+ * Version directories safe to delete: everything that is neither current, nor the
+ * retained previous, nor a staged pending. Pruning is only ever done AFTER a healthy
+ * start, so a version that has not yet proved itself is never the thing removed.
+ *
+ * @param {{ versions: readonly string[], currentVersion: string | null, previousVersion: string | null, pending: { version: string } | null }} input
+ * @returns {string[]}
+ */
+export function prunableVersions({ versions, currentVersion, previousVersion, pending }) {
+  const keep = new Set(
+    [currentVersion, previousVersion, pending?.version].filter((v) => typeof v === "string"),
+  );
+  return versions.filter((v) => !keep.has(v)).sort();
+}
+
+/**
+ * Whether this launch should record a healthy start — i.e. `current` is the version
+ * `pending` staged and nothing has confirmed it yet. Recording it clears the rollback
+ * arming above.
+ */
+export function shouldConfirmHealth({ currentVersion, pending, health }) {
+  if (currentVersion === null) return false;
+  if (pending === null || pending.version !== currentVersion) return false;
+  return health === null || health.version !== currentVersion;
+}
+
+
+// ── the filesystem operations ─────────────────────────────────────────────
+//
+// Windows only for now. `current` is a directory JUNCTION, which is the one
+// pointer that gives a STABLE path — `<store>/current/app/nissy.exe` — for the
+// autostart Run key and the protocol handler to reference across updates.
+//
+// Verified on Windows 11 before this was built: a junction can be created
+// unelevated, re-pointed WHILE a process launched through it is running, that
+// process survives the swap, and the next launch resolves to the new target.
+// The whole swap design rests on that, so it was measured rather than assumed.
+
+/** The version `current` resolves to, or null when there is no usable pointer. */
+export function readCurrentVersion(layout) {
+  try {
+    const resolved = realpathSync(layout.currentLink);
+    const name = basename(resolved);
+    return isSafeVersion(name) ? name : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Same, for the retained rollback target. */
+export function readPreviousVersion(layout) {
+  try {
+    const name = basename(realpathSync(layout.previousLink));
+    return isSafeVersion(name) ? name : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Re-point a junction, replacing whatever is there. */
+function repoint(linkPath, targetDir) {
+  try {
+    rmSync(linkPath, { recursive: true, force: true });
+  } catch {
+    /* nothing there, or already gone */
+  }
+  symlinkSync(targetDir, linkPath, "junction");
+}
+
+/**
+ * Point `current` at `version`, demoting the outgoing one to `previous`.
+ *
+ * Not atomic — a crash between the unlink and the create leaves no `current` at
+ * all. That is survivable by construction: the startup decision treats a missing
+ * current as "seed", so the next launch repairs it from the npm payload rather
+ * than failing.
+ */
+export function pointCurrentAt(layout, version) {
+  const target = versionDir(layout, version);
+  if (!isCompleteVersion(target)) throw new Error(`version ${version} is not in the store`);
+  const outgoing = readCurrentVersion(layout);
+  if (outgoing !== null && outgoing !== version) {
+    repoint(layout.previousLink, versionDir(layout, outgoing));
+  }
+  repoint(layout.currentLink, target);
+}
+
+/**
+ * Populate `dest` from `src` using hard links, falling back to a copy per file.
+ *
+ * Measured on the real 0.2.35 payload (2,318 files, 450 MB): 2.0s hard-linked
+ * against 36.5s copied. A copy would put a 36-second stall in front of the
+ * first launch after every `npm i -g`, which is a worse experience than the
+ * problem the store is solving.
+ *
+ * Hard links also cost no extra disk — both names point at the same blocks —
+ * and they are the RIGHT semantics here, not just the fast ones. npm replaces
+ * files rather than editing them in place, so a later `npm i -g` unlinks its
+ * name and writes a new one, leaving the store's copy of the old version
+ * intact. That is precisely the independence the store needs.
+ *
+ * The fallback covers a store on a different volume from the npm prefix
+ * (EXDEV) and any filesystem without hard links.
+ */
+function linkTree(src, dest) {
+  mkdirSync(dest, { recursive: true });
+  for (const entry of readdirSync(src, { withFileTypes: true })) {
+    const from = join(src, entry.name);
+    const to = join(dest, entry.name);
+    if (entry.isDirectory()) {
+      linkTree(from, to);
+      continue;
+    }
+    try {
+      linkSync(from, to);
+    } catch {
+      copyFileSync(from, to);
+    }
+    // Do NOT mark these read-only as a defence against writing through the
+    // link. On Windows the attribute belongs to the FILE, not the link, so it
+    // would also mark npm's copy read-only — and Microsoft documents that the
+    // other links then *display* the old value, which is simply untrue. ACLs
+    // are worse: a hard link has no security descriptor of its own at all. Nix
+    // gets read-only stores by chmod plus a read-only bind mount, neither of
+    // which has an NTFS equivalent, and pnpm — the closest analogue to this —
+    // does not use permissions either. It documents the hazard and offers
+    // copy-on-write instead.
+  }
+}
+
+/**
+ * Copy an extracted application into the store as `version`.
+ *
+ * Completion is signalled by a marker file written last, NOT by renaming a
+ * staged directory into place. The rename is the obvious design and it does not
+ * work here: the seed hard links from a tree npm has just extracted, Defender
+ * still holds handles on those inodes, and a directory with an open handle
+ * cannot be renamed. It failed with EPERM on a real machine. Go hit the same
+ * wall and abandoned rename-into-place in 1.16 for a `.partial` marker; this is
+ * the same idea with the sense inverted.
+ *
+ * So an interrupted seed leaves an unmarked directory, which `isCompleteVersion`
+ * treats as absent and the next seed clears.
+ */
+export function seedVersion(layout, version, sourceDir, exeSegments = null) {
+  const target = versionDir(layout, version);
+  if (isCompleteVersion(target)) return target;
+  // An unmarked directory is the wreckage of an interrupted seed. Clear it
+  // rather than linking on top of a half-populated tree.
+  rmSync(target, { recursive: true, force: true });
+  mkdirSync(layout.versionsDir, { recursive: true });
+  try {
+    linkTree(sourceDir, target);
+    if (exeSegments !== null) {
+      const exe = join(target, ...exeSegments);
+      if (!looksExecutable(exe)) {
+        throw new Error(`seeded version ${version} has no runnable executable at ${exe}`);
+      }
+    }
+    // Written LAST, and only once the executable has been checked: a version
+    // that cannot run must never become eligible for `current`.
+    writeFileSync(join(target, SEED_COMPLETE_MARKER), new Date().toISOString());
+  } catch (err) {
+    // Leave nothing usable and nothing large behind.
+    rmSync(target, { recursive: true, force: true });
+    throw err;
+  }
+  return target;
+}
+
+/**
+ * Whether a file is plausibly a Windows executable.
+ *
+ * Reads the two-byte DOS header rather than trusting the extension. This is not
+ * a signature check and is not meant to be: it catches truncation, a failed
+ * download written to the right name, and a file replaced by text — the
+ * failures that actually happen. Anything subtler is the digest's job, upstream.
+ *
+ * Cheap on purpose: two bytes and a stat, on the launch path.
+ */
+export function looksExecutable(filePath) {
+  let fd;
+  try {
+    if (statSync(filePath).size < 1024) return false; // no real exe is this small
+    fd = openSync(filePath, "r");
+    const head = Buffer.alloc(2);
+    if (readSync(fd, head, 0, 2, 0) !== 2) return false;
+    return head[0] === 0x4d && head[1] === 0x5a; // "MZ"
+  } catch {
+    return false;
+  } finally {
+    if (fd !== undefined) {
+      try {
+        closeSync(fd);
+      } catch {
+        /* nothing to do */
+      }
+    }
+  }
+}
+
+/** A version directory that finished seeding. Anything else does not exist as
+ *  far as the rest of the store is concerned. */
+export function isCompleteVersion(dir) {
+  return existsSync(join(dir, SEED_COMPLETE_MARKER));
+}
+
+/** Delete version directories that are no longer referenced. Best-effort: a
+ *  directory still holding a running executable is locked on Windows and is
+ *  simply left for the next launch. */
+export function pruneVersions(layout, versions) {
+  for (const v of versions) {
+    try {
+      rmSync(versionDir(layout, v), { recursive: true, force: true });
+    } catch {
+      /* locked or vanished — try again next time */
+    }
+  }
+}
+
+// ── diagnostics ───────────────────────────────────────────────────────────
+
+/** Keep the log bounded. It is append-only across every launch, forever. */
+const LOG_MAX_BYTES = 128 * 1024;
+
+/**
+ * Append a line to the store's own log.
+ *
+ * ALWAYS written, not gated behind a debug flag. The store degrades silently by
+ * design — every failure falls back to running the npm payload in place — which
+ * means a store that never works looks exactly like a store that is working
+ * fine. Without a durable record, we would ship it, see updates still applying
+ * through the old path, and conclude it was doing its job.
+ *
+ * Never throws: a launch must not fail because a log could not be written.
+ */
+export function storeLog(layout, message) {
+  try {
+    mkdirSync(layout.root, { recursive: true });
+    try {
+      if (statSync(layout.logFile).size > LOG_MAX_BYTES) {
+        writeFileSync(layout.logFile, `--- truncated ${new Date().toISOString()} ---
+`);
+      }
+    } catch {
+      /* no log yet */
+    }
+    appendFileSync(layout.logFile, `${new Date().toISOString()} ${message}
+`);
+  } catch {
+    /* diagnostics must never break a launch */
+  }
+}
+
+// ── the launch lock ───────────────────────────────────────────────────────
+
+/** How long a lock may be held before another launcher treats it as abandoned. */
+const LOCK_STALE_MS = 2 * 60 * 1000;
+/** How long to wait for a lock before giving up and running in place. */
+const LOCK_WAIT_MS = 5000;
+
+function lockIsStale(lockDir) {
+  try {
+    if (Date.now() - statSync(lockDir).mtimeMs > LOCK_STALE_MS) return true;
+    const pid = Number(readFileSync(join(lockDir, "pid"), "utf8").trim());
+    if (!Number.isInteger(pid) || pid <= 0) return true;
+    try {
+      process.kill(pid, 0);
+      return false; // holder is alive
+    } catch {
+      return true; // holder is gone
+    }
+  } catch {
+    return true; // unreadable lock is not a lock
+  }
+}
+
+/**
+ * Run `fn` while holding an exclusive lock on the store, or return
+ * `LOCK_UNAVAILABLE` if another launcher holds it.
+ *
+ * Two launchers really can run at once: the login item firing while someone
+ * types `nissy`, or a double-click. Without this, one process can be mid-seed
+ * while the other re-points `current` at a directory that is still being
+ * copied into.
+ *
+ * `mkdir` is the primitive because it is atomic on every filesystem we care
+ * about and needs no dependency. A crashed holder leaves the directory behind,
+ * so a lock whose PID is dead, or which is simply old, is taken over.
+ */
+export const LOCK_UNAVAILABLE = Symbol("store-lock-unavailable");
+
+export function withStoreLock(layout, fn, { waitMs = LOCK_WAIT_MS, now = Date.now } = {}) {
+  // The lock is a directory inside the store root, so the root has to exist
+  // before `mkdir` can distinguish "somebody holds it" (EEXIST) from "there is
+  // nowhere to put it" (ENOENT).
+  try {
+    mkdirSync(layout.root, { recursive: true });
+  } catch {
+    return LOCK_UNAVAILABLE;
+  }
+
+  const deadline = now() + waitMs;
+  for (;;) {
+    try {
+      mkdirSync(layout.lockDir, { recursive: false });
+      break; // acquired
+    } catch (err) {
+      // ONLY EEXIST means another launcher holds it. Anything else (the store
+      // root is a file, the directory is not writable) means the store itself
+      // is unusable, and retrying cannot fix it. Treating those as contention
+      // is an infinite loop that hangs the launcher and leaves the user unable
+      // to start the app at all.
+      if (!err || err.code !== "EEXIST") return LOCK_UNAVAILABLE;
+      // Checked before the takeover, so no branch of this loop can outlive the
+      // deadline.
+      if (now() >= deadline) return LOCK_UNAVAILABLE;
+      if (lockIsStale(layout.lockDir)) {
+        storeLog(layout, "taking over an abandoned store lock");
+        try {
+          rmSync(layout.lockDir, { recursive: true, force: true });
+        } catch {
+          return LOCK_UNAVAILABLE; // cannot clear it; do not spin on it
+        }
+        continue;
+      }
+      // Busy-wait without a dependency. The launcher is synchronous up to this
+      // point and the wait is bounded at a few seconds.
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 120);
+    }
+  }
+  try {
+    writeFileSync(join(layout.lockDir, "pid"), String(process.pid));
+  } catch {
+    /* the directory is the lock; the pid is only for staleness */
+  }
+  try {
+    return fn();
+  } finally {
+    try {
+      rmSync(layout.lockDir, { recursive: true, force: true });
+    } catch {
+      /* a leftover lock is reclaimed as stale */
+    }
+  }
+}
+
+/**
+ * Decide what the store needs, do it, and return the executable to launch.
+ *
+ * Returns null when the store cannot be used for ANY reason — an unwritable
+ * cache root, a filesystem without junctions, a half-built store we cannot
+ * repair. The launcher then runs the npm payload in place, exactly as it did
+ * before the store existed. That fallback is the whole safety story: a bug in
+ * here must degrade to the old behaviour, never to a user who cannot start the
+ * app.
+ *
+ * @param {{
+ *   platform: NodeJS.Platform,
+ *   home: string,
+ *   env: NodeJS.ProcessEnv,
+ *   cacheName?: string,
+ *   payloadVersion: string,
+ *   payloadRoot: string,
+ *   exeSegments: readonly string[],
+ *   log?: (message: string) => void,
+ * }} input
+ * @returns {{ exePath: string, version: string, action: string } | null}
+ */
+export function prepareStore({
+  platform,
+  home,
+  env,
+  cacheName,
+  payloadVersion,
+  payloadRoot,
+  exeSegments,
+  log = () => {},
+}) {
+  // Windows only. macOS keeps its existing ~/Applications install, which already
+  // swaps a whole bundle and does not suffer the locked-executable problem this
+  // store exists to solve.
+  if (platform !== "win32") return null;
+
+  let layout = null;
+  try {
+    layout = storeLayout({ platform, home, env, ...(cacheName ? { cacheName } : {}) });
+    const currentVersion = readCurrentVersion(layout);
+    const previousVersion = readPreviousVersion(layout);
+    const pending = readPending(layout);
+    const health = readHealth(layout);
+
+    const decision = decideStartupAction({
+      currentVersion,
+      previousVersion,
+      pending,
+      health,
+      payloadVersion,
+      versionExists: (v) => isSafeVersion(v) && isCompleteVersion(versionDir(layout, v)),
+    });
+    log(`store: ${decision.action} - ${decision.reason}`);
+    storeLog(layout, `${decision.action}: ${decision.reason}`);
+
+    // Only the mutating branches need the lock; a plain launch reads and goes.
+    const mutating = decision.action !== STORE_ACTION.launch;
+    const apply = () => {
+    switch (decision.action) {
+      case STORE_ACTION.seed:
+        seedVersion(layout, decision.version, payloadRoot, exeSegments);
+        pointCurrentAt(layout, decision.version);
+        // A freshly seeded version is the one we are about to run; nothing is
+        // pending against it.
+        clearPending(layout);
+        writeHealth(layout, decision.version);
+        break;
+      case STORE_ACTION.applyPending:
+        // Re-checked at the point of use, not only at seed time: the files may
+        // have been damaged since, and pointing `current` at a broken version
+        // is what strands a user outside the app.
+        if (!looksExecutable(join(versionDir(layout, decision.version), ...exeSegments))) {
+          storeLog(layout, `refusing to apply ${decision.version}: no runnable executable`);
+          rmSync(versionDir(layout, decision.version), { recursive: true, force: true });
+          clearPending(layout);
+          break;
+        }
+        pointCurrentAt(layout, decision.version);
+        // Deliberately NOT confirmed here: health is written only once the
+        // version has actually started, which is what arms the rollback below
+        // if it never does.
+        writePending(layout, decision.version);
+        break;
+      case STORE_ACTION.rollback:
+        pointCurrentAt(layout, decision.version);
+        // Clearing `pending` is what disarms the rollback, so it cannot fire
+        // again next launch. Health is deliberately NOT written: this version
+        // has not started yet in this session, and recording a start we did not
+        // observe would put a lie in the state file that later diagnosis reads.
+        clearPending(layout);
+        break;
+      case STORE_ACTION.launch:
+      default:
+        break;
+    }
+    };
+
+    if (mutating) {
+      const held = withStoreLock(layout, apply);
+      if (held === LOCK_UNAVAILABLE) {
+        // Another launcher is seeding or swapping. Doing it concurrently is how
+        // a half-copied version gets pointed at, so this one steps back and
+        // runs the npm payload in place for this launch only.
+        storeLog(layout, "another launcher holds the store lock; running in place");
+        log("store: busy; running the npm payload in place");
+        return null;
+      }
+    }
+
+    const version = readCurrentVersion(layout);
+    if (version === null) return null;
+    const exePath = join(layout.currentLink, ...exeSegments);
+    if (!existsSync(exePath)) {
+      storeLog(layout, `no executable at ${exePath}; running the npm payload in place`);
+      log(`store: no executable at ${exePath}; running the npm payload in place`);
+      return null;
+    }
+
+    // Is this launch an ATTEMPT at an unproven version? It is whenever `pending`
+    // still names what we are about to run and no health record agrees. Spend
+    // one of its attempts now, before the spawn — a launch that never comes back
+    // to confirm must still have cost something, or a version that hard-crashes
+    // on startup would retry for ever.
+    let awaitingConfirmation = false;
+    const afterPending = readPending(layout);
+    const afterHealth = readHealth(layout);
+    if (
+      afterPending !== null &&
+      afterPending.version === version &&
+      (afterHealth === null || afterHealth.version !== version)
+    ) {
+      // If another launcher holds the lock, skip the decrement rather than wait:
+      // losing an attempt is the safe direction to err in, spending one twice is
+      // not.
+      const held = withStoreLock(layout, () => consumeTry(layout), { waitMs: 0 });
+      if (held !== LOCK_UNAVAILABLE) {
+        awaitingConfirmation = true;
+        storeLog(layout, `attempt at ${version}; ${held === null ? "?" : held.triesLeft} left`);
+      }
+    }
+    return { exePath, version, action: decision.action, awaitingConfirmation };
+  } catch (err) {
+    const detail = (err && err.stack) || String(err);
+    // Recorded, not just whispered behind a debug flag: a store that always
+    // falls back is indistinguishable from one that works.
+    if (layout !== null) storeLog(layout, `FAILED, running the npm payload in place
+${detail}`);
+    log(`store unavailable (${err && err.message}); running the npm payload in place`);
+    return null;
+  }
+}
+
+/**
+ * Record that the current version started, and prune what is no longer referenced.
+ *
+ * `confirm: false` does the pruning only. Use it on the ordinary launch, where
+ * there is nothing to confirm and no reason to wait around for a signal.
+ *
+ * WHAT COUNTS AS A START is the whole question, and the honest answer today is
+ * "the process was still alive a few seconds later" — see HEALTH_WAIT_MS in the
+ * launcher. That is weaker than the systems this design borrows from. ChromeOS
+ * waits 45 seconds and then has userspace run `chromeos-setgoodkernel`; Android
+ * A/B verifies the whole partition with dm-verity before zygote and only then
+ * marks the slot successful; systemd renames the boot-counter file at the end of
+ * a successful boot. All three take a positive signal from the thing that
+ * booted, not from whatever launched it.
+ *
+ * A short liveness check does catch the failure that actually happens — an
+ * executable that dies immediately on a missing DLL or a truncated download —
+ * and the attempt counter bounds everything it misses. The app calling this
+ * itself, once it has a window and a working database, is the real fix and is
+ * the next piece of work.
+ *
+ * Pruning is deliberately last and best-effort: the outgoing version's
+ * executable may still be locked by a process that has not exited yet.
+ */
+export function confirmHealthyStart({
+  platform,
+  home,
+  env,
+  cacheName,
+  confirm = true,
+  log = () => {},
+}) {
+  if (platform !== "win32") return;
+  try {
+    const layout = storeLayout({ platform, home, env, ...(cacheName ? { cacheName } : {}) });
+    const currentVersion = readCurrentVersion(layout);
+    if (currentVersion === null) return;
+    const pending = readPending(layout);
+    withStoreLock(layout, () => {
+      if (confirm && shouldConfirmHealth({ currentVersion, pending, health: readHealth(layout) })) {
+        writeHealth(layout, currentVersion);
+        clearPending(layout);
+        storeLog(layout, `${currentVersion} started; confirmed`);
+        log(`store: ${currentVersion} started; confirmed`);
+      }
+      const dead = prunableVersions({
+        versions: listVersions(layout),
+        currentVersion,
+        previousVersion: readPreviousVersion(layout),
+        pending: readPending(layout),
+      });
+      if (dead.length > 0) storeLog(layout, `pruning ${dead.join(", ")}`);
+      pruneVersions(layout, dead);
+    });
+  } catch (err) {
+    // Never let bookkeeping affect a launch that has already happened - but do
+    // leave a trace, so a store that silently stops confirming is findable.
+    try {
+      storeLog(
+        storeLayout({ platform, home, env, ...(cacheName ? { cacheName } : {}) }),
+        `confirm/prune failed: ${(err && err.message) || err}`,
+      );
+    } catch {
+      /* nothing further to do */
+    }
+  }
+}