om-memory-system 4.4.0-next.65 → 4.4.0-next.69

package/README.md

@@ -17,8 +17,8 @@ It runs inside [OpenCode](https://opencode.ai) and the
 Both share one memory per project, so a note written in one is available in
 the other. Everything is stored locally on your machine.
 
-Claude Code is also supported, through a plugin of hooks. It needs a global
-install and your own external API for capture. See the
+Claude Code is also supported, through a plugin of hooks. It needs Node.js and
+your own external API for capture. A global install is optional. See the
 [Claude Code adapter](docs/claude-code-adapter.md) guide.
 
 ## What it does
@@ -81,8 +81,12 @@ pi install npm:om-memory-system
 
 Restart Pi. You can install OMMS in both agents; they share the same memory.
 
-**Terminal command (optional, recommended).** A global install lets the login
-web app and the `om-memory-system` terminal commands run without `npx`:
+**Terminal command (optional).** A global install puts the `om-memory-system`
+command on your `PATH`. You do not need it. OMMS runs the newest copy it finds on
+the machine, so updating one host is enough. A global install from 4.3 or earlier
+needs one update. See
+[Updating and upgrading](docs/upgrading.md#one-update-updates-every-host).
+To install it:
 
 ```bash
 npm i -g om-memory-system      # or: bun add -g om-memory-system

package/bin/omms-launch.mjs

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+// Runs the newest valid OMMS copy on the machine. It needs only Node.js and its
+// built-in modules, so the Claude Code plugin (which has no `dist/`) and the
+// login item can both run it.
+//
+//   node omms-launch.mjs [--at-least-own-version] <om-memory-system arguments>
+//
+// Candidates: the copy named in ~/.omms/runtime.json, the global install beside
+// the running Node.js, and the copy that holds this file. With
+// `--at-least-own-version`, the version in the `package.json` beside this file is
+// the minimum. When no candidate reaches it, the launcher runs
+// `npx --yes om-memory-system@<that version>`.
+
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SEMVER = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+
+function parse(version) {
+  const match = SEMVER.exec(String(version).trim());
+  if (!match) return null;
+  return {
+    core: [Number(match[1]), Number(match[2]), Number(match[3])],
+    pre: match[4] ? match[4].split(".") : [],
+  };
+}
+
+function comparePart(a, b) {
+  const aNumeric = /^\d+$/.test(a);
+  const bNumeric = /^\d+$/.test(b);
+  if (aNumeric && bNumeric) return Math.sign(Number(a) - Number(b));
+  if (aNumeric) return -1;
+  if (bNumeric) return 1;
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/**
+ * SemVer order, the same as `compareVersions` in `src/services/version-compare.ts`.
+ * It cannot import that file, because the plugin has no `dist/`;
+ * `tests/omms-launch.test.ts` keeps the two the same. Returns null when either
+ * version cannot be parsed.
+ */
+export function compareVersions(a, b) {
+  const left = parse(a);
+  const right = parse(b);
+  if (!left || !right) return null;
+  for (let i = 0; i < 3; i++) {
+    const diff = left.core[i] - right.core[i];
+    if (diff) return Math.sign(diff);
+  }
+  if (!left.pre.length || !right.pre.length) return right.pre.length - left.pre.length;
+  for (let i = 0; i < Math.max(left.pre.length, right.pre.length); i++) {
+    const l = left.pre[i];
+    const r = right.pre[i];
+    if (l === undefined) return -1;
+    if (r === undefined) return 1;
+    const diff = comparePart(l, r);
+    if (diff) return diff;
+  }
+  return 0;
+}
+
+/** A valid copy has the package name, a comparable version, and `dist/cli/index.js`. */
+function readCopy(root) {
+  try {
+    const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+    if (pkg.name !== "om-memory-system" || typeof pkg.version !== "string") return null;
+    if (compareVersions(pkg.version, pkg.version) === null) return null;
+    return existsSync(join(root, "dist", "cli", "index.js"))
+      ? { root, version: pkg.version }
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The package folder of a global npm install beside the given Node.js binary. */
+export function globalPackageRoot(execPath, platform = process.platform) {
+  if (!execPath) return null;
+  if (platform === "win32") return join(dirname(execPath), "node_modules", "om-memory-system");
+  return join(dirname(dirname(execPath)), "lib", "node_modules", "om-memory-system");
+}
+
+/**
+ * Every place a global install can be for this Node.js binary. Homebrew runs Node
+ * from a versioned `Cellar/node/<version>` folder, but npm installs under the
+ * prefix above `Cellar`, so that prefix counts too.
+ */
+export function globalPackageRoots(execPath, platform = process.platform) {
+  const direct = globalPackageRoot(execPath, platform);
+  if (!direct) return [];
+  const brew = /^(.*)[\\/]Cellar[\\/][^\\/]+[\\/][^\\/]+[\\/]bin[\\/][^\\/]+$/.exec(execPath);
+  return brew ? [direct, join(brew[1], "lib", "node_modules", "om-memory-system")] : [direct];
+}
+
+/** The record's copy, the global installs, and the own copy, in that order. Invalid ones are null. */
+export function findCandidates({ dir, execPath, ownRoot }) {
+  let recorded = null;
+  try {
+    const record = JSON.parse(readFileSync(join(dir, "runtime.json"), "utf8"));
+    if (record && typeof record.root === "string") recorded = readCopy(record.root);
+  } catch {
+    /* No record, or an unreadable one: the other candidates still work. */
+  }
+  const globals = globalPackageRoots(execPath).map((root) => readCopy(root));
+  return [recorded, ...globals, ownRoot ? readCopy(ownRoot) : null];
+}
+
+/**
+ * The newest candidate. On a tie the first one wins. With `minVersion`, a newest
+ * candidate that is older asks for `npx` at that version instead.
+ */
+export function chooseCopy(candidates, minVersion) {
+  let best = null;
+  for (const candidate of candidates) {
+    if (!candidate) continue;
+    if (!best || (compareVersions(candidate.version, best.version) ?? 0) > 0) best = candidate;
+  }
+  const wanted = minVersion && parse(minVersion) ? minVersion : null;
+  if (wanted && (!best || (compareVersions(best.version, wanted) ?? 0) < 0))
+    return { kind: "npx", version: wanted };
+  return best ? { kind: "copy", copy: best } : { kind: "none" };
+}
+
+export function parseLauncherArgs(argv) {
+  return argv[0] === "--at-least-own-version"
+    ? { atLeastOwnVersion: true, args: argv.slice(1) }
+    : { atLeastOwnVersion: false, args: [...argv] };
+}
+
+/** Run a command with inherited input and output, and resolve to its exit code. */
+function spawnInherit(command, args, options = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, { stdio: "inherit", ...options });
+    child.on("error", () => resolve(1));
+    child.on("close", (code) => resolve(code ?? 1));
+  });
+}
+
+/** The version in the `package.json` beside this file, or null when there is none. */
+function ownVersion(ownRoot) {
+  try {
+    const pkg = JSON.parse(readFileSync(join(ownRoot, "package.json"), "utf8"));
+    return pkg.name === "om-memory-system" && typeof pkg.version === "string" ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Choose a copy and run it. Resolves to the exit code. */
+export async function runLauncher(argv, options = {}) {
+  const dir = options.dir ?? join(homedir(), ".omms");
+  const execPath = options.execPath ?? process.execPath;
+  const ownRoot = options.ownRoot ?? dirname(dirname(fileURLToPath(import.meta.url)));
+  const run = options.spawn ?? spawnInherit;
+  const { atLeastOwnVersion, args } = parseLauncherArgs(argv);
+  const choice = chooseCopy(
+    findCandidates({ dir, execPath, ownRoot }),
+    atLeastOwnVersion ? ownVersion(ownRoot) : null
+  );
+  if (choice.kind === "copy")
+    return run(execPath, [join(choice.copy.root, "dist", "cli", "index.js"), ...args]);
+  if (choice.kind === "npx") {
+    // npm installs npx as a .cmd wrapper on Windows, which only a shell can run.
+    const windows = process.platform === "win32";
+    // Run from the temp folder. npx prefers a project in the current folder, so a project
+    // named om-memory-system (such as this repository) would win over the npm package.
+    // The hook input carries the real folder, so nothing else needs the current folder.
+    return run(
+      windows ? "npx.cmd" : "npx",
+      ["--yes", `om-memory-system@${choice.version}`, ...args],
+      {
+        shell: windows,
+        cwd: tmpdir(),
+      }
+    );
+  }
+  process.stderr.write("omms-launch: no OMMS copy found. Install om-memory-system.\n");
+  return 1;
+}
+
+/** True when this file is the program Node.js started. A path that cannot be resolved is not. */
+function runDirectly() {
+  try {
+    const entry = process.argv[1];
+    return Boolean(entry) && realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    // A loader or wrapper can leave argv[1] pointing at a file that is not there.
+    return false;
+  }
+}
+
+if (runDirectly()) {
+  runLauncher(process.argv.slice(2)).then((code) => process.exit(code));
+}

package/dist/adapters/claude-code/hook-client.d.ts

@@ -33,6 +33,8 @@ export interface ClaudeHookOptions {
     sleep?: (ms: number) => Promise<void>;
     log?: (message: string, data: Record<string, unknown>) => void | Promise<void>;
     readToken?: () => Promise<string>;
+    /** The version of the newest recorded OMMS copy, or null. Tests inject it. */
+    recordedVersion?: () => string | null;
     resolveRuntime?: () => Promise<string | null>;
     loadSettings?: () => Promise<HookServerSettings>;
     /** The `om-memory-system` script that `web` is run from. */

package/dist/adapters/claude-code/hook-client.js

@@ -182,7 +182,7 @@ async function runSteps(event, deps, result) {
     if (!settings.enabled)
         return "server-disabled";
     const budget = BUDGETS[event];
-    const ready = await ensureServer(settings, budget.startMs, deps, result);
+    const ready = await ensureServer(event, settings, budget.startMs, deps, result);
     if (ready !== "ok")
         return ready;
     const headers = {
@@ -230,13 +230,38 @@ async function runSteps(event, deps, result) {
     result.outputBytes = Buffer.byteLength(output);
     return "ok";
 }
+/**
+ * The newest recorded copy's version with the local token and, when the web app has
+ * a browser password, Basic Auth. Undefined when no copy is recorded.
+ */
+async function replaceOlderFor(settings, deps) {
+    try {
+        const handoff = await import("../../services/runtime-handoff.js");
+        const version = deps.recordedVersion ? deps.recordedVersion() : handoff.newestRecordedVersion();
+        if (!version)
+            return undefined;
+        return {
+            version,
+            headers: await handoff.replaceHeaders(await deps.readToken(), {
+                webServerAuthPassword: settings.basicAuth?.password,
+                webServerAuthUsername: settings.basicAuth?.username,
+            }),
+        };
+    }
+    catch {
+        // Without a target, any running web app is used.
+        return undefined;
+    }
+}
 /** Use a running web app, or start one through the shared rule and wait for it within the budget. */
-async function ensureServer(settings, budgetMs, deps, result) {
+async function ensureServer(event, settings, budgetMs, deps, result) {
     const { ensureWebApp } = await import("../../services/web-ensure.js");
     const answer = await ensureWebApp({
         settings: { enabled: settings.enabled, baseUrl: settings.baseUrl },
         budgetMs,
         wait: true,
+        // Only a new session replaces an older web app. A prompt or a stop uses any running one.
+        ...(event === "session-start" ? { replaceOlder: await replaceOlderFor(settings, deps) } : {}),
         deps: {
             fetch: deps.fetch,
             now: deps.now,

package/dist/adapters/pi/extension.js

@@ -105,6 +105,10 @@ export default function ommsPiExtension(pi) {
             // Runs even with tracing off, so turning it off does not leave old traces behind.
             pruneTraces(CONFIG);
             captureState = createPiCaptureState();
+            // Record this copy first: the login item and the other hosts run the newest recorded copy.
+            void import("../../services/runtime-handoff.js")
+                .then(({ registerOwnCopy }) => registerOwnCopy())
+                .catch((error) => log("Pi runtime record failed", { code: error instanceof Error ? error.name : "unknown" }));
             if (CONFIG.webServerAutoStart !== undefined &&
                 process.env.OMMS_DISABLE_WEB_AUTOSTART !== "1") {
                 void import("../../services/web-autostart.js")
@@ -118,15 +122,21 @@ export default function ommsPiExtension(pi) {
                 void Promise.all([
                     import("../../services/web-ensure.js"),
                     import("../../services/web-api-auth.js"),
+                    import("../../services/runtime-handoff.js"),
                 ])
-                    .then(([{ ensureWebApp }, { webServerUrl }]) => ensureWebApp({
-                    settings: {
-                        enabled: CONFIG.webServerEnabled,
-                        baseUrl: webServerUrl(CONFIG.webServerHost, CONFIG.webServerPort),
-                    },
-                    budgetMs: 0,
-                    wait: false,
-                }))
+                    .then(async ([{ ensureWebApp }, { webServerUrl }, { hostReplaceOlder }]) => {
+                    // A web app older than the newest recorded copy steps aside for it.
+                    const replaceOlder = await hostReplaceOlder(CONFIG).catch(() => undefined);
+                    return ensureWebApp({
+                        settings: {
+                            enabled: CONFIG.webServerEnabled,
+                            baseUrl: webServerUrl(CONFIG.webServerHost, CONFIG.webServerPort),
+                        },
+                        budgetMs: 0,
+                        wait: false,
+                        ...(replaceOlder ? { replaceOlder } : {}),
+                    });
+                })
                     .catch((error) => log("Pi web app start failed", {
                     code: error instanceof Error ? error.name : "unknown",
                 }));

package/dist/cli/index.js

@@ -38,6 +38,11 @@ export function parseImportArgs(argv) {
     return { host, args };
 }
 export async function runCli(argv) {
+    // An older copy runs the newest recorded copy instead; otherwise it records itself.
+    const { handOffOrRegister } = await import("../services/runtime-handoff.js");
+    const handedOff = await handOffOrRegister(argv);
+    if (handedOff !== null)
+        return handedOff;
     if (argv[0] === "--version" || argv[0] === "-v") {
         const { packageVersion } = await import("../services/package-version.js");
         console.log(packageVersion());

package/dist/cli/web-command.js

@@ -1,63 +1,5 @@
 import { homedir } from "node:os";
-const POLL_MS = 250;
-const POLL_LIMIT = 40;
-const REQUEST_TIMEOUT_MS = 2_000;
-/** The version an OMMS web app reports on `url`, or null when none answers with one. */
-async function readWebVersion(fetchFn, url, headers) {
-    try {
-        const response = await fetchFn(`${url}/api/settings/version`, {
-            headers,
-            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
-        });
-        if (!response.ok)
-            return null;
-        const body = (await response.json());
-        return typeof body.running === "string" ? body.running : null;
-    }
-    catch {
-        return null;
-    }
-}
-async function portAnswers(fetchFn, url) {
-    try {
-        await fetchFn(`${url}/api/health`, { signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/** Ask an older OMMS web app on the configured port to step aside, and wait for the port. */
-async function negotiateOwner(ctx) {
-    const { compareVersions } = await import("../services/version-compare.js");
-    const owner = await readWebVersion(ctx.fetchFn, ctx.url, ctx.headers);
-    const order = owner === null ? null : compareVersions(owner, ctx.version);
-    // A version that cannot be placed is never stopped.
-    if (owner === null || order === null)
-        return { kind: "none" };
-    if (order === 0)
-        return { kind: "same", owner };
-    if (order > 0)
-        return { kind: "newer", owner };
-    try {
-        const reply = await ctx.fetchFn(`${ctx.url}/api/web/step-aside`, {
-            method: "POST",
-            headers: { ...ctx.headers, "content-type": "application/json" },
-            body: JSON.stringify({ version: ctx.version }),
-            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
-        });
-        if (reply.status !== 202)
-            return { kind: "stuck", owner };
-    }
-    catch {
-        return { kind: "stuck", owner };
-    }
-    // If the old app is slow to stop, the login item still takes the port later.
-    for (let i = 0; i < POLL_LIMIT && (await portAnswers(ctx.fetchFn, ctx.url)); i++) {
-        await ctx.sleep(POLL_MS);
-    }
-    return { kind: "handed" };
-}
+import { negotiateOwner, POLL_LIMIT, POLL_MS, readWebVersion, } from "../services/web-handover.js";
 /** Print which version serves the port after `web install`. */
 async function announceHandover(ctx, handover) {
     const { url, port, version } = ctx;

package/dist/index.js

@@ -183,6 +183,12 @@ export const OmmsPlugin = async (ctx) => {
     initConfigWithLegacyMigration(directory);
     // Runs even with tracing off, so turning it off does not leave old traces behind.
     pruneTraces(CONFIG);
+    // Record this copy first: the login item and the other hosts run the newest recorded copy.
+    void import("./services/runtime-handoff.js")
+        .then(({ registerOwnCopy }) => registerOwnCopy())
+        .catch((error) => log("OpenCode runtime record failed", {
+        code: error instanceof Error ? error.name : "unknown",
+    }));
     if (CONFIG.webServerAutoStart !== undefined && process.env.OMMS_DISABLE_WEB_AUTOSTART !== "1") {
         void import("./services/web-autostart.js")
             .then(({ reconcileWebAutostart }) => reconcileWebAutostart(CONFIG))
@@ -300,12 +306,19 @@ export const OmmsPlugin = async (ctx) => {
                 .catch(() => { });
         };
         // The shared web app serves the page. This plugin starts it only when none runs.
-        void Promise.all([import("./services/web-ensure.js"), import("./services/web-api-auth.js")])
-            .then(([{ ensureWebApp }, { webServerUrl }]) => {
+        void Promise.all([
+            import("./services/web-ensure.js"),
+            import("./services/web-api-auth.js"),
+            import("./services/runtime-handoff.js"),
+        ])
+            .then(async ([{ ensureWebApp }, { webServerUrl }, { hostReplaceOlder }]) => {
             const baseUrl = webServerUrl(CONFIG.webServerHost, CONFIG.webServerPort);
+            // A web app older than the newest recorded copy steps aside for it.
+            const replaceOlder = await hostReplaceOlder(CONFIG).catch(() => undefined);
             return ensureWebApp({
                 settings: { enabled: CONFIG.webServerEnabled, baseUrl },
                 budgetMs: 10_000,
+                ...(replaceOlder ? { replaceOlder } : {}),
             }).then((result) => {
                 if (result === "running" || result === "started") {
                     showToast(`Web UI available at ${baseUrl}`, "info", 3000);

package/dist/services/global-version.d.ts

@@ -1,31 +1,22 @@
 export interface GlobalCommandVersion {
-    /** The version the global `om-memory-system --version` printed, or null when not installed. */
+    /** The version in the global install's `package.json`, or null when not installed or unreadable. */
     version: string | null;
     path: string | null;
-    error?: "timeout" | "failed";
+    error?: "failed";
 }
-type Runner = (file: string, args: string[], options: {
-    timeout: number;
-    windowsHide: boolean;
-    shell: false;
-}) => Promise<string>;
 /** The first `om-memory-system` on PATH; on Windows npm installs a `.cmd` wrapper. */
 export declare function findGlobalCommand(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, exists?: (path: string) => boolean): string | null;
 /**
- * The command and arguments that print the version without a user-controlled
- * shell. A Windows `.cmd` wrapper can only run through cmd.exe, so it runs
- * through the system's own cmd.exe with fixed arguments.
+ * The global command's version, read from its install's `package.json`. The
+ * command does not run: after a hand-off it would print the newest copy's version.
+ * The login item runs with a minimal PATH, so with no command on PATH the install
+ * beside the running Node.js counts too.
  */
-export declare function versionInvocation(path: string, platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): {
-    file: string;
-    args: string[];
-};
-/** Look up the global command's version, at most once every 10 minutes. */
 export declare function globalCommandVersion(options?: {
-    now?: () => number;
-    runner?: Runner;
     find?: () => string | null;
     platform?: NodeJS.Platform;
-}): Promise<GlobalCommandVersion>;
-export declare function resetGlobalVersionCache(): void;
-export {};
+    execPath?: string;
+}): GlobalCommandVersion;
+export type GlobalRelation = "missing" | "same" | "older" | "newer" | "unknown";
+/** How the global install compares with the running OMMS. */
+export declare function globalRelation(running: string, global: string | null): GlobalRelation;

package/dist/services/global-version.js

@@ -1,11 +1,6 @@
-import { execFile } from "node:child_process";
-import { accessSync, constants } from "node:fs";
-import { delimiter, isAbsolute, join } from "node:path";
-const TIMEOUT_MS = 3_000;
-const CACHE_MS = 10 * 60_000;
-const run = (file, args, options) => new Promise((resolve, reject) => {
-    execFile(file, args, { ...options, encoding: "utf8" }, (error, stdout) => error ? reject(error) : resolve(String(stdout)));
-});
+import { accessSync, constants, readFileSync, realpathSync } from "node:fs";
+import { delimiter, dirname, isAbsolute, join } from "node:path";
+import { compareVersions } from "./version-compare.js";
 function executable(path) {
     try {
         accessSync(path, constants.X_OK);
@@ -31,48 +26,83 @@ export function findGlobalCommand(env = process.env, platform = process.platform
     }
     return null;
 }
+/** The package folder of the install the command belongs to, or null. */
+function packageFolder(command, platform) {
+    // npm's Windows layout: the wrapper sits beside node_modules.
+    if (platform === "win32")
+        return join(dirname(command), "node_modules", "om-memory-system");
+    let dir = dirname(realpathSync(command));
+    for (;;) {
+        try {
+            const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+            if (pkg.name === "om-memory-system")
+                return dir;
+        }
+        catch {
+            /* Try the parent. */
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
 /**
- * The command and arguments that print the version without a user-controlled
- * shell. A Windows `.cmd` wrapper can only run through cmd.exe, so it runs
- * through the system's own cmd.exe with fixed arguments.
+ * Where a global npm install can be for a Node.js binary, the same places the
+ * launcher looks. Homebrew runs Node from a versioned `Cellar/node/<version>`
+ * folder, but npm installs under the prefix above `Cellar`.
  */
-export function versionInvocation(path, platform = process.platform, env = process.env) {
-    if (platform === "win32" && path.toLowerCase().endsWith(".cmd")) {
-        const cmd = env.SystemRoot ? `${env.SystemRoot}\\System32\\cmd.exe` : "cmd.exe";
-        return { file: cmd, args: ["/d", "/s", "/c", `"${path}" --version`] };
-    }
-    return { file: path, args: ["--version"] };
+function installsBesideRuntime(execPath, platform) {
+    if (!execPath)
+        return [];
+    if (platform === "win32")
+        return [join(dirname(execPath), "node_modules", "om-memory-system")];
+    const direct = join(dirname(dirname(execPath)), "lib", "node_modules", "om-memory-system");
+    const brew = /^(.*)[\\/]Cellar[\\/][^\\/]+[\\/][^\\/]+[\\/]bin[\\/][^\\/]+$/.exec(execPath);
+    return brew ? [direct, join(brew[1], "lib", "node_modules", "om-memory-system")] : [direct];
 }
-let cached = null;
-/** Look up the global command's version, at most once every 10 minutes. */
-export async function globalCommandVersion(options = {}) {
-    const now = (options.now ?? Date.now)();
-    if (cached && now - cached.at < CACHE_MS)
-        return cached.value;
+/** The version in an install's `package.json`, or null when it is not an OMMS install. */
+function installVersion(folder) {
+    const pkg = JSON.parse(readFileSync(join(folder, "package.json"), "utf8"));
+    return pkg.name === "om-memory-system" && typeof pkg.version === "string" ? pkg.version : null;
+}
+/**
+ * The global command's version, read from its install's `package.json`. The
+ * command does not run: after a hand-off it would print the newest copy's version.
+ * The login item runs with a minimal PATH, so with no command on PATH the install
+ * beside the running Node.js counts too.
+ */
+export function globalCommandVersion(options = {}) {
+    const platform = options.platform ?? process.platform;
     const path = (options.find ?? (() => findGlobalCommand()))();
-    let value;
     if (!path) {
-        value = { version: null, path: null };
-    }
-    else {
-        const { file, args } = versionInvocation(path, options.platform);
-        try {
-            const output = await (options.runner ?? run)(file, args, {
-                timeout: TIMEOUT_MS,
-                windowsHide: true,
-                shell: false,
-            });
-            const version = /\d+\.\d+\.\d+(?:[-+][\w.]+)?/.exec(output)?.[0] ?? null;
-            value = version ? { version, path } : { version: null, path, error: "failed" };
-        }
-        catch (error) {
-            const killed = error.killed;
-            value = { version: null, path, error: killed ? "timeout" : "failed" };
+        for (const folder of installsBesideRuntime(options.execPath ?? process.execPath, platform)) {
+            try {
+                const version = installVersion(folder);
+                if (version)
+                    return { version, path: folder };
+            }
+            catch {
+                /* No install there. */
+            }
         }
+        return { version: null, path: null };
+    }
+    try {
+        const folder = packageFolder(path, platform);
+        const version = folder ? installVersion(folder) : null;
+        return version ? { version, path } : { version: null, path, error: "failed" };
+    }
+    catch {
+        return { version: null, path, error: "failed" };
     }
-    cached = { at: now, value };
-    return value;
 }
-export function resetGlobalVersionCache() {
-    cached = null;
+/** How the global install compares with the running OMMS. */
+export function globalRelation(running, global) {
+    if (global === null)
+        return "missing";
+    const order = compareVersions(global, running);
+    if (order === null)
+        return "unknown";
+    return order === 0 ? "same" : order < 0 ? "older" : "newer";
 }