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

package/dist/services/runtime-handoff.d.ts

@@ -0,0 +1,60 @@
+import { type RegisterResult, type RuntimeCopy, type RuntimeLog } from "./runtime-record.js";
+export declare const ommsDir: (home?: string) => string;
+/** The package folder of the running copy, found from source or `dist/`. */
+export declare function ownPackageRoot(from?: string): string | null;
+/**
+ * Record the running copy when it is the newest. A failure is logged with a
+ * code and never thrown, so it cannot stop a session or a command.
+ */
+export declare function registerOwnCopy(options?: {
+    dir?: string;
+    root?: string | null;
+    log?: RuntimeLog;
+}): RegisterResult;
+export interface HandoffOptions {
+    dir?: string;
+    ownRoot?: string | null;
+    ownVersion?: string;
+    env?: NodeJS.ProcessEnv;
+    log?: RuntimeLog;
+    /** Injected so tests run no process. Resolves to the exit code, or null when the copy cannot start. */
+    spawn?: (command: string, args: string[], env: NodeJS.ProcessEnv) => Promise<number | null>;
+}
+/** The recorded copy this command must hand off to, or null. */
+export declare function handoffTarget(options: HandoffOptions & {
+    ownVersion: string;
+}): RuntimeCopy | null;
+/**
+ * The first step of the `om-memory-system` command. When the record names a
+ * newer valid copy, run that copy's command with the same arguments and return
+ * its exit code. Otherwise record this copy and return null, and the command
+ * continues with its own code. `OMMS_HANDED_OFF` stops a loop when two records disagree.
+ */
+export declare function handOffOrRegister(argv: string[], options?: HandoffOptions): Promise<number | null>;
+/** The version of the newest valid recorded copy, or null. This is the version a launcher start runs. */
+export declare function newestRecordedVersion(options?: {
+    dir?: string;
+    log?: RuntimeLog;
+}): string | null;
+/** What `ensureWebApp` needs to replace an older running web app. */
+export interface ReplaceOlder {
+    version: string;
+    headers: Record<string, string>;
+}
+/** The browser password settings a web app request needs, as `CONFIG` holds them. */
+export interface BasicAuthSettings {
+    webServerAuthPassword?: string;
+    webServerAuthUsername?: string;
+}
+/**
+ * Headers for the version lookup and the step-aside request. They carry the local
+ * token, and Basic Auth when a browser password is set: the web server checks Basic
+ * Auth first and refuses every other API request without it.
+ */
+export declare function replaceHeaders(token: string, settings?: BasicAuthSettings): Promise<Record<string, string>>;
+/**
+ * For a host start: record this copy, then name the version a running web app
+ * must reach. A web app older than it is asked to step aside. Without a
+ * recorded copy there is no target, so any running web app is used.
+ */
+export declare function hostReplaceOlder(settings?: BasicAuthSettings): Promise<ReplaceOlder | undefined>;

package/dist/services/runtime-handoff.js

@@ -0,0 +1,134 @@
+import { spawn as nodeSpawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { recordedCopy, registerCopy, } from "./runtime-record.js";
+import { compareVersions } from "./version-compare.js";
+// The newest-copy rule for the terminal command and the hosts: an old command
+// hands off to a newer recorded copy, and every copy that runs records itself.
+// Like `runtime-record.ts`, it imports no config.
+export const ommsDir = (home = homedir()) => join(home, ".omms");
+/** The package folder of the running copy, found from source or `dist/`. */
+export function ownPackageRoot(from = import.meta.url) {
+    let dir = dirname(fileURLToPath(from));
+    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;
+    }
+}
+/** Log a code through the shared logger. A host calls this after its config is loaded. */
+const logCode = (code, data) => {
+    void import("./logger.js")
+        .then(({ log }) => log("Runtime record", { code, ...data }))
+        .catch(() => { });
+};
+/**
+ * Record the running copy when it is the newest. A failure is logged with a
+ * code and never thrown, so it cannot stop a session or a command.
+ */
+export function registerOwnCopy(options = {}) {
+    const root = options.root === undefined ? ownPackageRoot() : options.root;
+    if (!root)
+        return "skipped";
+    // Tests set this so that starting the real CLI never writes the developer's real record.
+    if (options.dir === undefined && process.env.OMMS_DISABLE_RUNTIME_RECORD === "1")
+        return "skipped";
+    try {
+        return registerCopy({ dir: options.dir ?? ommsDir(), root, log: options.log ?? logCode });
+    }
+    catch {
+        return "failed";
+    }
+}
+/**
+ * Run the child and resolve to its exit code, or null when it could not start.
+ * Standard input, output, and error flow through.
+ */
+function spawnCopy(command, args, env) {
+    return new Promise((resolve) => {
+        const child = nodeSpawn(command, args, { stdio: "inherit", env });
+        child.on("error", () => resolve(null));
+        child.on("close", (code) => resolve(code ?? 1));
+    });
+}
+/** The recorded copy this command must hand off to, or null. */
+export function handoffTarget(options) {
+    const env = options.env ?? process.env;
+    if (env.OMMS_NO_HANDOFF === "1" || env.OMMS_HANDED_OFF)
+        return null;
+    const copy = recordedCopy(options.dir ?? ommsDir(), options.log ?? logCode);
+    if (!copy || copy.root === options.ownRoot)
+        return null;
+    return (compareVersions(copy.version, options.ownVersion) ?? 0) > 0 ? copy : null;
+}
+/**
+ * The first step of the `om-memory-system` command. When the record names a
+ * newer valid copy, run that copy's command with the same arguments and return
+ * its exit code. Otherwise record this copy and return null, and the command
+ * continues with its own code. `OMMS_HANDED_OFF` stops a loop when two records disagree.
+ */
+export async function handOffOrRegister(argv, options = {}) {
+    const ownRoot = options.ownRoot === undefined ? ownPackageRoot() : options.ownRoot;
+    let ownVersion = options.ownVersion;
+    if (ownVersion === undefined) {
+        const { packageVersion } = await import("./package-version.js");
+        ownVersion = packageVersion();
+    }
+    const target = handoffTarget({ ...options, ownRoot, ownVersion });
+    if (target) {
+        const run = options.spawn ?? spawnCopy;
+        const code = await run(process.execPath, [join(target.root, "dist", "cli", "index.js"), ...argv], { ...(options.env ?? process.env), OMMS_HANDED_OFF: "1" });
+        if (code !== null)
+            return code;
+    }
+    registerOwnCopy({ dir: options.dir, root: ownRoot, log: options.log });
+    return null;
+}
+/** The version of the newest valid recorded copy, or null. This is the version a launcher start runs. */
+export function newestRecordedVersion(options = {}) {
+    return recordedCopy(options.dir ?? ommsDir(), options.log ?? logCode)?.version ?? null;
+}
+/**
+ * Headers for the version lookup and the step-aside request. They carry the local
+ * token, and Basic Auth when a browser password is set: the web server checks Basic
+ * Auth first and refuses every other API request without it.
+ */
+export async function replaceHeaders(token, settings = {}) {
+    const { AUTH_HEADER } = await import("./auth-token.js");
+    const headers = { [AUTH_HEADER]: token };
+    const password = (settings.webServerAuthPassword ?? "").trim();
+    if (!password)
+        return headers;
+    const { WebAuth } = await import("./web-auth.js");
+    const { username } = new WebAuth({
+        password,
+        username: settings.webServerAuthUsername,
+    }).getConfig();
+    headers.authorization = `Basic ${Buffer.from(`${username}:${password}`).toString("base64")}`;
+    return headers;
+}
+/**
+ * For a host start: record this copy, then name the version a running web app
+ * must reach. A web app older than it is asked to step aside. Without a
+ * recorded copy there is no target, so any running web app is used.
+ */
+export async function hostReplaceOlder(settings = {}) {
+    registerOwnCopy();
+    const version = newestRecordedVersion();
+    if (!version)
+        return undefined;
+    const { getOrCreateAuthToken } = await import("./auth-token.js");
+    // The web app runs on this machine, so the local token file is enough.
+    return { version, headers: await replaceHeaders(getOrCreateAuthToken(), settings) };
+}

package/dist/services/runtime-record.d.ts

@@ -0,0 +1,47 @@
+export interface RuntimeRecord {
+    root: string;
+    version: string;
+    updatedAt: string;
+}
+/** A valid copy: its package folder and the version in its `package.json`. */
+export interface RuntimeCopy {
+    root: string;
+    version: string;
+}
+/** A log call carries a code and identifiers only, never a path or file text. */
+export type RuntimeLog = (code: string, data: Record<string, unknown>) => void;
+export type RegisterResult = "written" | "kept" | "skipped" | "failed";
+export declare const recordPath: (dir: string) => string;
+export declare const launcherPath: (dir: string) => string;
+/**
+ * The version of a valid OMMS copy, or null. A copy is valid when its
+ * `package.json` names `om-memory-system`, its version can be compared, and it
+ * has `dist/cli/index.js`.
+ */
+export declare function copyVersion(root: string): string | null;
+/** The record as written, or null. A missing record is normal; any other failure logs a code. */
+export declare function readRuntimeRecord(dir: string, log?: RuntimeLog): RuntimeRecord | null;
+/** The copy the record names, when it is still valid. The version is read from its `package.json`. */
+export declare function recordedCopy(dir: string, log?: RuntimeLog): RuntimeCopy | null;
+/**
+ * Make sure a launcher exists at `~/.omms/bin`. An existing launcher stays, so an
+ * older copy never replaces it. When it is missing, the first source with a
+ * `bin/omms-launch.mjs` provides it. Returns whether a launcher exists afterwards.
+ */
+export declare function ensureLauncher(options: {
+    dir: string;
+    sources: readonly (string | null | undefined)[];
+    log?: RuntimeLog;
+}): boolean;
+/**
+ * Record this copy when the record is missing, names a copy that is no longer
+ * valid, or names an older version. An equal version keeps the record. The copy
+ * that holds the record also keeps the launcher at `~/.omms/bin`. A failure is
+ * logged with a code and never thrown.
+ */
+export declare function registerCopy(options: {
+    dir: string;
+    root: string;
+    log?: RuntimeLog;
+    now?: () => Date;
+}): RegisterResult;

package/dist/services/runtime-record.js

@@ -0,0 +1,143 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { compareVersions } from "./version-compare.js";
+export const recordPath = (dir) => join(dir, "runtime.json");
+export const launcherPath = (dir) => join(dir, "bin", "omms-launch.mjs");
+/**
+ * The version of a valid OMMS copy, or null. A copy is valid when its
+ * `package.json` names `om-memory-system`, its version can be compared, and it
+ * has `dist/cli/index.js`.
+ */
+export function copyVersion(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")) ? pkg.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The record as written, or null. A missing record is normal; any other failure logs a code. */
+export function readRuntimeRecord(dir, log) {
+    let text;
+    try {
+        text = readFileSync(recordPath(dir), "utf8");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            log?.("runtime-record-read-failed", { reason: "read" });
+        return null;
+    }
+    try {
+        const value = JSON.parse(text);
+        if (!value ||
+            typeof value.root !== "string" ||
+            typeof value.version !== "string" ||
+            typeof value.updatedAt !== "string")
+            throw new Error("shape");
+        return { root: value.root, version: value.version, updatedAt: value.updatedAt };
+    }
+    catch {
+        log?.("runtime-record-read-failed", { reason: "parse" });
+        return null;
+    }
+}
+/** The copy the record names, when it is still valid. The version is read from its `package.json`. */
+export function recordedCopy(dir, log) {
+    const record = readRuntimeRecord(dir, log);
+    if (!record)
+        return null;
+    const version = copyVersion(record.root);
+    return version ? { root: record.root, version } : null;
+}
+/** Write a file in one step, so a reader never finds a partial file. */
+function writeAtomic(path, write) {
+    const temp = `${path}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+    try {
+        write(temp);
+        renameSync(temp, path);
+    }
+    finally {
+        rmSync(temp, { force: true });
+    }
+}
+function sameFile(a, b) {
+    try {
+        return readFileSync(a).equals(readFileSync(b));
+    }
+    catch {
+        return false;
+    }
+}
+/** Put the copy's launcher at the fixed path when it is missing or different. */
+function placeLauncher(dir, root, log) {
+    const source = join(root, "bin", "omms-launch.mjs");
+    if (!existsSync(source))
+        return;
+    const target = launcherPath(dir);
+    if (sameFile(source, target))
+        return;
+    try {
+        mkdirSync(dirname(target), { recursive: true, mode: 0o700 });
+        writeAtomic(target, (temp) => copyFileSync(source, temp));
+    }
+    catch {
+        log?.("runtime-launcher-write-failed", {});
+    }
+}
+/**
+ * Make sure a launcher exists at `~/.omms/bin`. An existing launcher stays, so an
+ * older copy never replaces it. When it is missing, the first source with a
+ * `bin/omms-launch.mjs` provides it. Returns whether a launcher exists afterwards.
+ */
+export function ensureLauncher(options) {
+    const target = launcherPath(options.dir);
+    if (existsSync(target))
+        return true;
+    for (const root of options.sources) {
+        if (root)
+            placeLauncher(options.dir, root, options.log);
+        if (existsSync(target))
+            return true;
+    }
+    return false;
+}
+/**
+ * Record this copy when the record is missing, names a copy that is no longer
+ * valid, or names an older version. An equal version keeps the record. The copy
+ * that holds the record also keeps the launcher at `~/.omms/bin`. A failure is
+ * logged with a code and never thrown.
+ */
+export function registerCopy(options) {
+    const { dir, root, log } = options;
+    const own = copyVersion(root);
+    if (!own)
+        return "skipped";
+    try {
+        const current = recordedCopy(dir, log);
+        const newer = !current || (compareVersions(own, current.version) ?? 0) > 0;
+        if (!newer) {
+            // The recorded copy owns the launcher, so it repairs a missing or damaged one.
+            if (current?.root === root)
+                placeLauncher(dir, root, log);
+            return "kept";
+        }
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const record = {
+            root,
+            version: own,
+            updatedAt: (options.now?.() ?? new Date()).toISOString(),
+        };
+        writeAtomic(recordPath(dir), (temp) => writeFileSync(temp, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 }));
+        placeLauncher(dir, root, log);
+        return "written";
+    }
+    catch {
+        log?.("runtime-record-write-failed", {});
+        return "failed";
+    }
+}

package/dist/services/web-autostart.d.ts

@@ -1,10 +1,13 @@
 import { CONFIG } from "../config.js";
-type State = "installed" | "not-installed" | "unsupported" | "no-runtime" | "no-package";
+type State = "installed" | "not-installed" | "unsupported" | "no-runtime" | "no-package" | "no-launcher";
 export type WebAutostartStatus = {
     state: State;
     path?: string;
     runtime?: string;
+    /** The copy the launcher starts now: the newest of the record, the global install, and this copy. */
     packagePath?: string;
+    /** The fixed launcher the item runs, `~/.omms/bin/omms-launch.mjs`. */
+    launcher?: string;
     command?: string;
 };
 export interface WebAutostartOptions {
@@ -12,19 +15,18 @@ export interface WebAutostartOptions {
     platform?: string;
     runtime?: string | null;
     packageRoot?: string | null;
+    /** The running copy, a launcher source when the chosen copy has none. Defaults to `packageRoot`, then this copy. */
+    ownRoot?: string | null;
     systemctlAvailable?: boolean;
     run?: (command: string, args: string[]) => void;
     start?: boolean;
 }
 /** OpenCode's executable is not a JavaScript runtime. */
 export declare function resolveWebRuntime(execPath?: string, platform?: NodeJS.Platform): string | null;
-/** The package folder a written login item runs, read back from its command line. */
-export declare function itemPackageRoot(file: string): string | null;
 /**
- * The newest OMMS copy among this one, the global install beside the runtime,
- * and the copy the item already runs. A host starts OMMS from its own cache,
- * which can be older than the global install; that copy must not downgrade
- * the login item.
+ * The newest valid OMMS copy among the candidates. On equal versions the first
+ * wins, so a host's cached copy goes last. This is the copy the launcher starts,
+ * and it matches the launcher's own choice.
  */
 export declare function preferredPackageRoot(candidates: readonly (string | null | undefined)[]): string | null;
 /** Read the login item's state without changing any system files. */

package/dist/services/web-autostart.js

@@ -6,6 +6,7 @@ import { basename, dirname, join, delimiter, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { CONFIG } from "../config.js";
 import { log } from "./logger.js";
+import { copyVersion, ensureLauncher, launcherPath, recordedCopy, } from "./runtime-record.js";
 import { compareVersions } from "./version-compare.js";
 const MARKER = "OMMS login item";
 const NAME = "io.github.cmdaltctr.omms.web";
@@ -70,53 +71,18 @@ function packageRoot() {
         dir = parent;
     }
 }
-function packageVersionAt(root) {
-    try {
-        const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
-        if (pkg.name !== "om-memory-system" || !existsSync(join(root, "dist", "cli", "index.js"))) {
-            return null;
-        }
-        return typeof pkg.version === "string" ? pkg.version : null;
-    }
-    catch {
-        return null;
-    }
-}
-/** The package folder a written login item runs, read back from its command line. */
-export function itemPackageRoot(file) {
-    try {
-        const content = readFileSync(file, "utf8");
-        const match = /([^"<>\r\n]*?)[\\/]dist[\\/]cli[\\/]index\.js/.exec(content);
-        const path = match?.[1]?.replace(/^.*?<string>/, "").trim();
-        if (!path)
-            return null;
-        // Only plists escape XML. Decode ampersands last to preserve literal entity text.
-        return content.includes("<plist")
-            ? path
-                .replaceAll("&quot;", '"')
-                .replaceAll("&apos;", "'")
-                .replaceAll("&lt;", "<")
-                .replaceAll("&gt;", ">")
-                .replaceAll("&amp;", "&")
-            : path;
-    }
-    catch {
-        return null;
-    }
-}
 /**
- * The newest OMMS copy among this one, the global install beside the runtime,
- * and the copy the item already runs. A host starts OMMS from its own cache,
- * which can be older than the global install; that copy must not downgrade
- * the login item.
+ * The newest valid OMMS copy among the candidates. On equal versions the first
+ * wins, so a host's cached copy goes last. This is the copy the launcher starts,
+ * and it matches the launcher's own choice.
  */
 export function preferredPackageRoot(candidates) {
     let best = null;
     for (const root of candidates) {
         if (!root)
             continue;
-        const version = packageVersionAt(root);
-        if (!version || compareVersions(version, version) === null)
+        const version = copyVersion(root);
+        if (!version)
             continue;
         if (!best || (compareVersions(version, best.version) ?? 0) > 0)
             best = { root, version };
@@ -145,15 +111,20 @@ function details(options) {
     const platform = options.platform ?? process.platform;
     const path = itemPath(home, platform);
     const runtime = options.runtime === undefined ? resolveWebRuntime() : options.runtime;
-    const own = options.packageRoot === undefined ? packageRoot() : options.packageRoot;
-    const current = path && existsSync(path) ? itemPackageRoot(path) : null;
+    const dir = join(home, ".omms");
+    const own = options.ownRoot !== undefined
+        ? options.ownRoot
+        : options.packageRoot !== undefined
+            ? options.packageRoot
+            : packageRoot();
+    const recorded = recordedCopy(dir, logCode)?.root ?? null;
     const root = options.packageRoot === undefined
-        ? // On equal versions the first wins, so a host's cached copy goes last.
-            preferredPackageRoot([globalPackageRoot(runtime ?? null, platform), current, own])
-        : own;
+        ? preferredPackageRoot([recorded, globalPackageRoot(runtime ?? null, platform), own])
+        : options.packageRoot;
     const supported = platform !== "linux" || (options.systemctlAvailable ?? Boolean(executable("systemctl")));
-    return { home, platform, path, runtime, root, supported };
+    return { home, platform, path, runtime, root, own, recorded, dir, supported };
 }
+const logCode = (code, data) => log("Runtime record", { code, ...data });
 const xml = (value) => value
     .replaceAll("&", "&amp;")
     .replaceAll("<", "&lt;")
@@ -161,21 +132,21 @@ const xml = (value) => value
     .replaceAll('"', "&quot;");
 const systemd = (value) => `"${value.replaceAll("%", "%%").replaceAll('"', '\\"')}"`;
 const windows = (value) => `"${value.replaceAll("%", "%%")}"`;
-function itemContent(platform, runtime, cli) {
+function itemContent(platform, runtime, launcher) {
     if (platform === "darwin")
         return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0"><dict>
 <!-- ${MARKER} -->
 <key>Label</key><string>${NAME}</string>
-<key>ProgramArguments</key><array><string>${xml(runtime)}</string><string>${xml(cli)}</string><string>web</string><string>--login-item</string></array>
+<key>ProgramArguments</key><array><string>${xml(runtime)}</string><string>${xml(launcher)}</string><string>web</string><string>--login-item</string></array>
 <key>RunAtLoad</key><true/><key>KeepAlive</key><false/>
 <key>StandardOutPath</key><string>/dev/null</string><key>StandardErrorPath</key><string>/dev/null</string>
 </dict></plist>\n`;
     if (platform === "linux")
         return `# ${MARKER}
-[Unit]\nDescription=OMMS web app\n[Service]\nType=simple\nExecStart=${systemd(runtime)} ${systemd(cli)} web --login-item\n[Install]\nWantedBy=default.target\n`;
-    return `@echo off\r\nrem ${MARKER}\r\nstart "" /min ${windows(runtime)} ${windows(cli)} web --login-item\r\n`;
+[Unit]\nDescription=OMMS web app\n[Service]\nType=simple\nExecStart=${systemd(runtime)} ${systemd(launcher)} web --login-item\n[Install]\nWantedBy=default.target\n`;
+    return `@echo off\r\nrem ${MARKER}\r\nstart "" /min ${windows(runtime)} ${windows(launcher)} web --login-item\r\n`;
 }
 function owned(path) {
     return readFileSync(path, "utf8").includes(MARKER);
@@ -188,15 +159,16 @@ function runCommand(options, home, command, args) {
 }
 /** Read the login item's state without changing any system files. */
 export function webAutostartStatus(options = {}) {
-    const { path, runtime, root, supported } = details(options);
+    const { path, runtime, root, dir, supported } = details(options);
     if (!path || !supported)
         return { state: "unsupported" };
     if (!runtime)
         return { state: "no-runtime", path };
     if (!root)
         return { state: "no-package", path, runtime };
+    const launcher = launcherPath(dir);
     if (!existsSync(path))
-        return { state: "not-installed", path, runtime, packagePath: root };
+        return { state: "not-installed", path, runtime, packagePath: root, launcher };
     if (!owned(path))
         throw new Error("Login item at the OMMS path is not owned by OMMS");
     return {
@@ -204,6 +176,7 @@ export function webAutostartStatus(options = {}) {
         path,
         runtime,
         packagePath: root,
+        launcher,
         command: readFileSync(path, "utf8"),
     };
 }
@@ -214,9 +187,15 @@ export function installWebAutostart(options = {}) {
         status.state === "no-runtime" ||
         status.state === "no-package")
         return status;
-    const { home, platform, path, runtime, root } = details(options);
+    const { home, platform, path, runtime, root, own, recorded, dir } = details(options);
+    // The item runs a fixed launcher, so the launcher must exist before the item does.
+    if (!ensureLauncher({ dir, sources: [root, own, recorded], log: logCode })) {
+        // A valid package exists. Only the launcher is missing, so say that.
+        logCode("launcher-missing", {});
+        return { state: "no-launcher", path: path, runtime: runtime };
+    }
     const file = path;
-    const content = itemContent(platform, runtime, join(root, "dist", "cli", "index.js"));
+    const content = itemContent(platform, runtime, launcherPath(dir));
     mkdirSync(dirname(file), { recursive: true });
     const changed = !existsSync(file) || readFileSync(file, "utf8") !== content;
     if (changed) {

package/dist/services/web-ensure.d.ts

@@ -37,6 +37,8 @@ export interface EnsureDeps {
     resolveRuntime: () => Promise<string | null> | string | null;
     /** The `om-memory-system` script that `web` is run from. */
     cliScript: string;
+    /** `~/.omms/bin/omms-launch.mjs` when it exists. `web` then starts through it, on the newest recorded copy. */
+    launcherScript: string | null;
     lockPath: string;
     lockFs: LockFs;
     pidAlive: (pid: number) => boolean;
@@ -51,6 +53,15 @@ export interface EnsureOptions {
     budgetMs: number;
     /** `false` starts the web app and returns at once (session starts). Default `true`. */
     wait?: boolean;
+    /**
+     * Replace a running web app older than `version`: ask it to step aside, then
+     * start as for an empty port. `headers` are the local token headers the
+     * step-aside route needs. Without it, any running OMMS web app is used.
+     */
+    replaceOlder?: {
+        version: string;
+        headers: Record<string, string>;
+    };
     deps?: Partial<EnsureDeps>;
 }
 /** A lock older than this is stale. Also the longest a background start holds it. */