om-memory-system 4.4.0-next.67 → 4.4.0-next.70

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/claude-code/hook-command.d.ts

@@ -1,6 +1,7 @@
 import { type ClaudeHookOptions } from "./hook-client.js";
+import { type ClaudeStatusOptions } from "./status.js";
 /**
  * `om-memory-system claude-hook <event>`. Always returns 0: a hook must never
  * block or break a Claude Code session, whatever goes wrong.
  */
-export declare function runClaudeHookCommand(argv: string[], io?: ClaudeHookOptions): Promise<number>;
+export declare function runClaudeHookCommand(argv: string[], io?: ClaudeHookOptions & ClaudeStatusOptions): Promise<number>;

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

@@ -1,7 +1,14 @@
 import { CLAUDE_HOOK_EVENTS, runClaudeHook, } from "./hook-client.js";
+import { buildClaudeStatus, loadClaudeStatusInputs } from "./status.js";
 function isHookEvent(value) {
     return CLAUDE_HOOK_EVENTS.includes(value ?? "");
 }
+/** `claude-hook status`: one JSON line for the status line mod. Prints nothing on failure. */
+async function printStatus(io) {
+    const inputs = await (io.statusInputs ?? loadClaudeStatusInputs)();
+    const status = await buildClaudeStatus({ ...inputs, fetch: io.fetch ?? globalThis.fetch });
+    (io.writeStdout ?? ((text) => process.stdout.write(text)))(`${JSON.stringify(status)}\n`);
+}
 /**
  * `om-memory-system claude-hook <event>`. Always returns 0: a hook must never
  * block or break a Claude Code session, whatever goes wrong.
@@ -9,6 +16,10 @@ function isHookEvent(value) {
 export async function runClaudeHookCommand(argv, io = {}) {
     try {
         const [event] = argv;
+        if (event === "status") {
+            await printStatus(io);
+            return 0;
+        }
         if (isHookEvent(event)) {
             await runClaudeHook(event, io);
             return 0;

package/dist/adapters/claude-code/status.d.ts

@@ -0,0 +1,25 @@
+export interface ClaudeStatus {
+    healthUrl: string;
+    /** The version of the OMMS copy that ran this command. */
+    version: string;
+    /** The `latest` version on npm, or null when the check is off or fails. */
+    latest: string | null;
+}
+export interface ClaudeStatusInputs {
+    config: {
+        webServerHost: string;
+        webServerPort: number;
+    };
+    version: string;
+    checkUpdates: boolean;
+}
+/** Options for tests; production reads the global config and the package version. */
+export interface ClaudeStatusOptions {
+    statusInputs?: () => Promise<ClaudeStatusInputs>;
+}
+/** Pure: `CONFIG` is passed in, because tests stub `src/config.js`. */
+export declare function buildClaudeStatus(inputs: ClaudeStatusInputs & {
+    fetch: typeof fetch;
+}): Promise<ClaudeStatus>;
+/** The global config and this copy's version, as `om-memory-system web` reads them. */
+export declare function loadClaudeStatusInputs(): Promise<ClaudeStatusInputs>;

package/dist/adapters/claude-code/status.js

@@ -0,0 +1,33 @@
+import { homedir } from "node:os";
+import { latestNpmVersion } from "../../services/update-check.js";
+/** Pure: `CONFIG` is passed in, because tests stub `src/config.js`. */
+export async function buildClaudeStatus(inputs) {
+    const { webServerHost, webServerPort } = inputs.config;
+    const host = webServerHost === "0.0.0.0" ? "127.0.0.1" : webServerHost;
+    const urlHost = host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
+    return {
+        healthUrl: `http://${urlHost}:${webServerPort}/api/health`,
+        version: inputs.version,
+        latest: inputs.checkUpdates ? await latestNpmVersion(inputs.fetch) : null,
+    };
+}
+/** The global config and this copy's version, as `om-memory-system web` reads them. */
+export async function loadClaudeStatusInputs() {
+    // Importing the config on a first run prints "Created config template" with
+    // console.log. Stdout must hold only the JSON line, so that goes to stderr.
+    const log = console.log;
+    console.log = console.error;
+    try {
+        const config = await import("../../config.js");
+        config.initConfig(homedir());
+        const { packageVersion } = await import("../../services/package-version.js");
+        return {
+            config: config.CONFIG,
+            version: packageVersion(),
+            checkUpdates: process.env.OMMS_DISABLE_UPDATE_CHECK !== "1",
+        };
+    }
+    finally {
+        console.log = log;
+    }
+}

package/dist/adapters/opencode/tui-status.d.ts

@@ -4,10 +4,6 @@ export interface TuiStatusState {
     update: string | null;
 }
 export declare function tuiStatusText(state: TuiStatusState): string;
-/** The `latest` version on npm, or null when the registry cannot be reached. */
-export declare function latestNpmVersion(fetchFn: typeof fetch, timeoutMs?: number): Promise<string | null>;
-/** A newer release than `current`, ignoring prereleases; null otherwise. */
-export declare function availableUpdate(current: string, latest: string | null): string | null;
 export interface TuiStatusDeps {
     currentVersion: string;
     healthUrl: string;

package/dist/adapters/opencode/tui-status.js

@@ -1,30 +1,8 @@
-import { isOlderVersion } from "../../services/version-compare.js";
+import { availableUpdate, latestNpmVersion } from "../../services/update-check.js";
 export function tuiStatusText(state) {
     const web = state.web === "offline" ? "omms:web app off" : `omms:${state.web}`;
     return state.update ? `${web} · ${state.update} available` : web;
 }
-/** The `latest` version on npm, or null when the registry cannot be reached. */
-export async function latestNpmVersion(fetchFn, timeoutMs = 5_000) {
-    try {
-        const response = await fetchFn("https://registry.npmjs.org/om-memory-system/latest", {
-            signal: AbortSignal.timeout(timeoutMs),
-            headers: { accept: "application/json" },
-        });
-        if (!response.ok)
-            return null;
-        const body = (await response.json());
-        return typeof body.version === "string" ? body.version : null;
-    }
-    catch {
-        return null;
-    }
-}
-/** A newer release than `current`, ignoring prereleases; null otherwise. */
-export function availableUpdate(current, latest) {
-    if (!latest || latest.includes("-"))
-        return null;
-    return isOlderVersion(current, latest) ? latest : null;
-}
 /**
  * Keep the footer text current: the web app is polled, and npm is asked for a
  * newer release at start and then every few hours. Returns a stop function.

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;