om-memory-system 3.6.0-next.40 → 3.6.0-next.43

package/dist/cli/web-command.js

@@ -173,7 +173,7 @@ export async function runWebCommand(args, options = {}, online, handover = {}) {
     });
     console.log(`OMMS web app: ${server.getUrl()}`);
     // The Node HTTP adapter unrefs its socket for plugin use. Keep the CLI alive.
-    const keeper = setInterval(() => { }, 60_000);
+    let keeper = setInterval(() => { }, 60_000);
     const stop = () => {
         clearInterval(keeper);
         process.off("SIGINT", stop);
@@ -191,6 +191,14 @@ export async function runWebCommand(args, options = {}, online, handover = {}) {
             process.off("SIGTERM", stop);
             await server.stop();
         },
+        // A restart whose copy failed serves again from this process.
+        resumeServer: async () => {
+            keeper = setInterval(() => { }, 60_000);
+            process.once("SIGINT", stop);
+            process.once("SIGTERM", stop);
+            await server.start();
+        },
+        baseUrl: server.getUrl(),
         loginItem: action === "--login-item",
         autostart: options,
     }));

package/dist/cli/web-power.d.ts

@@ -1,10 +1,15 @@
 import type { WebAutostartOptions } from "../services/web-autostart.js";
+/** The two choices the page offers; the web server passes them through unchanged. */
 export type PowerAction = "stop" | "restart";
 interface SpawnedChild {
     pid?: number;
     unref(): void;
-    on(event: "error", listener: (error: Error) => void): unknown;
+    on(event: "error" | "exit", listener: () => void): unknown;
+    kill(signal?: NodeJS.Signals): boolean;
 }
+/** How long the old process waits for the copy to answer before it serves again. */
+export declare const HANDOFF_WAIT_MS = 15000;
+/** Injected so tests check the restart order without spawning or exiting. */
 export interface PowerDeps {
     spawn: (command: string, args: string[], options: {
         detached: true;
@@ -16,6 +21,12 @@ export interface PowerDeps {
     restartLoginItem: () => boolean | Promise<boolean>;
     /** Write the start lock, naming `pid`, so a host that starts meanwhile waits. */
     writeStartLock: (pid: number) => void | Promise<void>;
+    /** Remove the start lock when it names `pid`. */
+    removeStartLock: (pid: number) => void | Promise<void>;
+    /** True when an OMMS web app answers health at `baseUrl`. */
+    probe: (baseUrl: string) => Promise<boolean>;
+    sleep: (ms: number) => Promise<void>;
+    now: () => number;
     exit: (code: number) => void;
     /** The runtime and arguments of this process, for a detached copy. */
     execPath: string;
@@ -26,13 +37,17 @@ export interface PowerDeps {
 }
 /**
  * The callback the web server runs after it replies to Stop or Restart.
- * `stopServer` stops serving and any keep-alive timer. Restart starts a fresh
- * copy on the same port: the service manager for the login item, and a detached
- * copy otherwise. A detached child of the login item would die with its
- * launchd job or systemd control group.
+ * `stopServer` stops serving and any keep-alive timer; `resumeServer` undoes it.
+ * Restart starts a fresh copy on the same port: the service manager for the
+ * login item, and a detached copy otherwise. A detached child of the login item
+ * would die with its launchd job or systemd control group. A restart never
+ * leaves the port empty because the copy failed: the old process serves again.
  */
 export declare function createPowerAction(options: {
     stopServer: () => Promise<void>;
+    resumeServer: () => Promise<void>;
+    /** The URL this web app serves, where the copy must answer after the handoff. */
+    baseUrl: string;
     loginItem: boolean;
     autostart?: WebAutostartOptions;
     deps?: Partial<PowerDeps>;

package/dist/cli/web-power.js

@@ -1,15 +1,33 @@
 import { spawn as nodeSpawn } from "node:child_process";
 import { homedir } from "node:os";
+/** How long a fresh copy must stay up before the old process stops serving. */
+const SPAWN_CHECK_MS = 1_000;
+/** How long the old process waits for the copy to answer before it serves again. */
+export const HANDOFF_WAIT_MS = 15_000;
+const HANDOFF_POLL_MS = 250;
 function productionDeps(options) {
     return {
         spawn: nodeSpawn,
         restartLoginItem: async () => (await import("../services/web-autostart.js")).restartWebAutostart(options),
         writeStartLock: async (pid) => {
             const { nodeLockFs, startLockPath } = await import("../services/web-ensure.js");
-            const path = startLockPath();
-            nodeLockFs.remove(path);
-            nodeLockFs.createExclusive(path, JSON.stringify({ pid, at: Date.now() }));
+            nodeLockFs.replace(startLockPath(), JSON.stringify({ pid, at: Date.now() }));
         },
+        removeStartLock: async (pid) => (await import("../services/web-ensure.js")).removeStartLockFor(pid),
+        probe: async (baseUrl) => {
+            try {
+                const response = await fetch(`${baseUrl}/api/health`, {
+                    signal: AbortSignal.timeout(1_000),
+                });
+                const body = (await response.json());
+                return response.ok && body.success === true && body.status === "ok";
+            }
+            catch {
+                return false;
+            }
+        },
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        now: () => Date.now(),
         exit: (code) => process.exit(code),
         execPath: process.execPath,
         args: process.argv.slice(1),
@@ -20,42 +38,104 @@ function productionDeps(options) {
 }
 /**
  * The callback the web server runs after it replies to Stop or Restart.
- * `stopServer` stops serving and any keep-alive timer. Restart starts a fresh
- * copy on the same port: the service manager for the login item, and a detached
- * copy otherwise. A detached child of the login item would die with its
- * launchd job or systemd control group.
+ * `stopServer` stops serving and any keep-alive timer; `resumeServer` undoes it.
+ * Restart starts a fresh copy on the same port: the service manager for the
+ * login item, and a detached copy otherwise. A detached child of the login item
+ * would die with its launchd job or systemd control group. A restart never
+ * leaves the port empty because the copy failed: the old process serves again.
  */
 export function createPowerAction(options) {
     const deps = { ...productionDeps(options.autostart ?? {}), ...options.deps };
+    const logFailure = (code) => Promise.resolve(deps.log("Web app restart failed", { code })).catch(() => undefined);
+    let stopped = false;
+    /** Start the copy, check it, stop serving, and wait until the copy answers. */
+    async function handOff() {
+        let child;
+        try {
+            child = deps.spawn(deps.execPath, deps.args, {
+                detached: true,
+                stdio: "ignore",
+                cwd: deps.cwd,
+                windowsHide: true,
+            });
+        }
+        catch {
+            return giveUp("spawn-error");
+        }
+        let failed = false;
+        let exited = false;
+        child.on("error", () => (failed = true));
+        child.on("exit", () => (exited = true));
+        child.unref();
+        const copyPid = child.pid;
+        if (!copyPid)
+            return giveUp("spawn-error");
+        // A missing script or a broken runtime ends the copy within this time.
+        await deps.sleep(SPAWN_CHECK_MS);
+        if (failed)
+            return giveUp("spawn-error");
+        if (exited)
+            return giveUp("copy-exit");
+        await deps.writeStartLock(copyPid);
+        if (!stopped) {
+            await options.stopServer();
+            stopped = true;
+        }
+        // The copy waits as a non-owner and takes the port within about 7 seconds.
+        const began = deps.now();
+        while (deps.now() - began < HANDOFF_WAIT_MS) {
+            if (exited)
+                return giveUp("copy-exit", copyPid);
+            if (await deps.probe(options.baseUrl))
+                return deps.exit(0);
+            await deps.sleep(HANDOFF_POLL_MS);
+        }
+        if (exited)
+            return giveUp("copy-exit", copyPid);
+        // A copy that never answers would wait as a non-owner for ever.
+        child.kill("SIGTERM");
+        return giveUp("handoff", copyPid);
+    }
+    /** Keep or resume serving on the old process, and release the lock it wrote. */
+    async function giveUp(code, copyPid) {
+        if (copyPid !== undefined)
+            await deps.removeStartLock(copyPid);
+        else if (!options.loginItem)
+            await deps.removeStartLock(deps.pid);
+        await logFailure(code);
+        if (!stopped)
+            return;
+        try {
+            await options.resumeServer();
+            stopped = false;
+        }
+        catch (error) {
+            await logFailure(error instanceof Error ? error.name : "resume-error");
+            deps.exit(1);
+        }
+    }
     return async (action) => {
         if (action === "stop") {
             await options.stopServer();
             deps.exit(0);
             return;
         }
+        stopped = false;
         try {
-            // Hold other hosts off until the copy owns the port.
-            if (!options.loginItem)
+            if (options.loginItem) {
+                await options.stopServer();
+                stopped = true;
+                if (await deps.restartLoginItem())
+                    return deps.exit(0);
+            }
+            else {
+                // Hold other hosts off until the copy owns the port.
                 await deps.writeStartLock(deps.pid);
-            await options.stopServer();
-            if (options.loginItem && (await deps.restartLoginItem()))
-                return deps.exit(0);
-            const child = deps.spawn(deps.execPath, deps.args, {
-                detached: true,
-                stdio: "ignore",
-                cwd: deps.cwd,
-                windowsHide: true,
-            });
-            child.on("error", () => undefined);
-            child.unref();
-            if (child.pid)
-                await deps.writeStartLock(child.pid);
+            }
+            await handOff();
         }
         catch (error) {
-            await Promise.resolve(deps.log("Web app restart failed", {
-                code: error instanceof Error ? error.name : "unknown",
-            })).catch(() => undefined);
+            await giveUp(error instanceof Error ? error.name : "unknown");
         }
-        deps.exit(0);
     };
 }

package/dist/core/memory-operations.js

@@ -12,6 +12,7 @@ function formatSearchResults(query, results, limit) {
         results: memoryResults.slice(0, limit || 10).map((result) => ({
             id: result.id,
             content: result.memory || result.chunk,
+            type: result.type,
             similarity: Math.round(result.similarity * 100),
         })),
     };
@@ -198,6 +199,7 @@ export async function executeMemoryOperation(args, context) {
                     memories: result.memories?.map((memory) => ({
                         id: memory.id,
                         content: memory.summary,
+                        type: memory.type,
                         createdAt: memory.createdAt,
                     })),
                 };

package/dist/importer/claude-hook-api.js

@@ -1,5 +1,6 @@
+import { realpathSync } from "node:fs";
 import { readFile } from "node:fs/promises";
-import { isAbsolute } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { CONFIG, refreshConfigIfChanged } from "../config.js";
 import { captureConversation } from "../core/capture.js";
 import { classifyCaptureFailure, quickRetryDelayMs } from "../core/capture-retry-policy.js";
@@ -12,6 +13,7 @@ import { log } from "../services/logger.js";
 import { isFullyPrivate, stripPrivateContent } from "../services/privacy.js";
 import { getTags } from "../services/tags.js";
 import { extractClaudeWindowsAfter, parseClaudeTranscript, } from "./claude-conversation.js";
+import { defaultClaudeProjectsRoot } from "./claude-reader.js";
 // The web app's side of the Claude Code hooks (design decisions 4, 6, 7):
 // retrieval for SessionStart and UserPromptSubmit, a one-worker capture queue
 // for Stop, profile learning, and the once-per-process backfill start. Logs
@@ -61,6 +63,41 @@ function parseRetrieveRequest(body) {
         prompt: optionalString(input, "prompt"),
     };
 }
+/**
+ * Resolves symlinks and returns the letter case on disk. Node's plain
+ * `realpathSync` keeps the case it is given, which fails the root check on a
+ * case-insensitive file system. A path that does not exist yet resolves
+ * through its nearest existing parent.
+ */
+function realPathOrResolved(path) {
+    const absolute = resolve(path);
+    try {
+        return realpathSync.native(absolute);
+    }
+    catch {
+        const parent = dirname(absolute);
+        if (parent === absolute)
+            return absolute;
+        return join(realPathOrResolved(parent), basename(absolute));
+    }
+}
+/**
+ * Claude Code writes `<projects root>/<folder>/<session_id>.jsonl`. Accept only
+ * that shape, so the route cannot be used to read other `.jsonl` files. Returns
+ * the resolved path, which the capture then reads.
+ */
+function checkedTranscriptPath(transcriptPath, sessionId) {
+    const fileName = `${sessionId}.jsonl`;
+    const real = realPathOrResolved(transcriptPath);
+    if (basename(transcriptPath) !== fileName || basename(real) !== fileName) {
+        throw new ClaudeHookRequestError("transcript_path must be named <session_id>.jsonl");
+    }
+    const root = realPathOrResolved(defaultClaudeProjectsRoot());
+    if (!real.startsWith(root + sep)) {
+        throw new ClaudeHookRequestError("transcript_path must be under the Claude projects folder");
+    }
+    return real;
+}
 function parseCaptureRequest(body) {
     const input = objectBody(body);
     const transcriptPath = input.transcript_path;
@@ -69,9 +106,11 @@ function parseCaptureRequest(body) {
         !transcriptPath.endsWith(".jsonl")) {
         throw new ClaudeHookRequestError("transcript_path must be an absolute .jsonl path");
     }
+    const { sessionId, cwd } = sessionAndCwd(input);
     return {
-        ...sessionAndCwd(input),
-        transcriptPath,
+        sessionId,
+        cwd,
+        transcriptPath: checkedTranscriptPath(transcriptPath, sessionId),
         lastAssistantMessage: optionalString(input, "last_assistant_message"),
         stopHookActive: input.stop_hook_active === true,
     };

package/dist/importer/claude-reader.d.ts

@@ -16,6 +16,7 @@ import { type ImportPathMap, type ImportProjectReport, type LazyImportSource } f
  * time.
  */
 export declare const CLAUDE_HEADER_READ_LIMIT: number;
+/** `$CLAUDE_CONFIG_DIR/projects` when the variable is set, else `~/.claude/projects`. */
 export declare function defaultClaudeProjectsRoot(): string;
 export interface DiscoveredClaudeSession {
     file: string;

package/dist/importer/claude-reader.js

@@ -23,8 +23,10 @@ import { countImportableUnits, projectFilterTag, selectImportWindows, } from "./
  */
 export const CLAUDE_HEADER_READ_LIMIT = 1024 * 1024;
 const READ_CHUNK = 64 * 1024;
+/** `$CLAUDE_CONFIG_DIR/projects` when the variable is set, else `~/.claude/projects`. */
 export function defaultClaudeProjectsRoot() {
-    return join(homedir(), ".claude", "projects");
+    const configDir = process.env.CLAUDE_CONFIG_DIR?.trim();
+    return join(configDir || join(homedir(), ".claude"), "projects");
 }
 /** A missing folder is an empty history. Any other read error is reported, not hidden. */
 function readEntries(dir, unreadable) {

package/dist/services/api-handlers.js

@@ -496,7 +496,7 @@ export async function handleSearch(query, tag, page = 1, pageSize = 20) {
             type: "memory",
             id: r.id,
             content: r.memory,
-            memoryType: r.metadata?.type,
+            memoryType: r.type ?? r.metadata?.type,
             tags: r.tags,
             createdAt: safeToISOString(r.createdAt ?? r.metadata?.createdAt),
             updatedAt: r.metadata?.updatedAt ? safeToISOString(r.metadata.updatedAt) : undefined,

package/dist/services/client.d.ts

@@ -64,6 +64,7 @@ export declare class LocalMemoryClient {
         memories: {
             id: any;
             summary: any;
+            type: string | undefined;
             createdAt: string;
             metadata: any;
             displayName: any;

package/dist/services/client.js

@@ -204,6 +204,7 @@ export class LocalMemoryClient {
             const memories = allMemories.slice(0, limit).map((r) => ({
                 id: r.id,
                 summary: r.content,
+                type: r.type ? String(r.type) : undefined,
                 createdAt: safeToISOString(r.created_at),
                 metadata: safeJSONParse(r.metadata),
                 displayName: r.display_name,

package/dist/services/turso/types.d.ts

@@ -32,6 +32,7 @@ export interface SearchResult {
     similarity: number;
     createdAt?: number;
     tags?: string[];
+    type?: string;
     metadata?: Record<string, unknown>;
     displayName?: string;
     userName?: string;

package/dist/services/turso/vector-search.js

@@ -109,7 +109,7 @@ export class TursoVectorSearch {
         // hits still get a full hybrid score (missing ANN side is not forced to 0).
         const rows = await db.all(containerTag === ""
             ? `
-      SELECT id, content, tags, created_at, metadata, container_tag,
+      SELECT id, content, tags, type, created_at, metadata, container_tag,
              display_name, user_name, user_email, project_path, project_name,
              git_repo_url, is_pinned,
              vector_distance_cos(vector, vector32(?)) AS content_dist,
@@ -120,7 +120,7 @@ export class TursoVectorSearch {
       WHERE id IN (${placeholders})
     `
             : `
-      SELECT id, content, tags, created_at, metadata, container_tag,
+      SELECT id, content, tags, type, created_at, metadata, container_tag,
              display_name, user_name, user_email, project_path, project_name,
              git_repo_url, is_pinned,
              vector_distance_cos(vector, vector32(?)) AS content_dist,
@@ -158,6 +158,7 @@ export class TursoVectorSearch {
                 similarity,
                 createdAt: Number(row.created_at),
                 tags: memoryTagsStr ? memoryTagsStr.split(",") : [],
+                type: row.type ? String(row.type) : undefined,
                 metadata: parseMetadata(row.metadata),
                 containerTag: String(row.container_tag),
                 displayName: row.display_name ? String(row.display_name) : undefined,

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

@@ -1,3 +1,4 @@
+/** Each code maps to a host message or log code; none of them fails the session. */
 export type EnsureResult = "running" | "started" | "disabled" | "port-busy" | "no-runtime" | "start-timeout";
 /** Port and switch of the web app, as the caller read them from `CONFIG`. */
 export interface EnsureSettings {
@@ -14,13 +15,20 @@ type SpawnFn = (command: string, args: string[], options: {
     cwd: string;
     windowsHide: true;
 }) => SpawnedChild;
-/** The three file operations the start lock needs. */
+/** The file operations the start lock needs. */
 export interface LockFs {
     /** Create the file only when it does not exist. Returns false when it does. */
     createExclusive(path: string, text: string): boolean;
     read(path: string): string | null;
     remove(path: string): void;
+    /** Hard-link `from` to `to`. False when `to` exists or `from` is missing. */
+    link(from: string, to: string): boolean;
+    /** Time since the file's change time, or null when it is missing. A link sets the change time. */
+    ageMs(path: string): number | null;
+    /** Replace the file in one step, so a reader never finds it missing. */
+    replace(path: string, text: string): void;
 }
+/** Injected so tests run the start rule without a network, a process, or a real clock. */
 export interface EnsureDeps {
     fetch: typeof fetch;
     spawn: SpawnFn;
@@ -36,6 +44,7 @@ export interface EnsureDeps {
     pid: number;
     log: (message: string, data: Record<string, unknown>) => void | Promise<void>;
 }
+/** Hosts differ only in these values; the start rule itself has no host-specific code. */
 export interface EnsureOptions {
     settings: EnsureSettings;
     /** How long the caller may wait for the web app to answer. */
@@ -48,9 +57,18 @@ export interface EnsureOptions {
 export declare const START_LOCK_STALE_MS = 20000;
 /** Path of the start lock; the standalone command writes it for a restart copy. */
 export declare function startLockPath(home?: string): string;
+/** Lock files are private to the user (0600 in a 0700 folder), like the token file. */
 export declare const nodeLockFs: LockFs;
 /** Remove the start lock when it names `pid`. A restart copy calls this once it owns the port. */
 export declare function removeStartLockFor(pid: number, path?: string, lockFs?: LockFs): void;
+/** What taking the start lock needs; a test drives two callers through it step by step. */
+export type LockDeps = Pick<EnsureDeps, "lockPath" | "lockFs" | "pid" | "now" | "pidAlive">;
+/**
+ * Take the start lock. A stale lock is replaced by one caller only: the caller
+ * that hard-links it to a tombstone named after its text. Remove-then-create
+ * alone let two callers each remove the lock the other had just created.
+ */
+export declare function takeStartLock(deps: LockDeps): boolean;
 /**
  * Use a running OMMS web app, or start one detached `om-memory-system web`.
  * Never throws; a failed check must not block or fail the host session.

package/dist/services/web-ensure.js

@@ -1,5 +1,6 @@
 import { spawn as nodeSpawn } from "node:child_process";
-import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { linkSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -11,6 +12,7 @@ export const START_LOCK_STALE_MS = 20_000;
 export function startLockPath(home = homedir()) {
     return join(home, ".omms", "web-start.lock");
 }
+/** Lock files are private to the user (0600 in a 0700 folder), like the token file. */
 export const nodeLockFs = {
     createExclusive(path, text) {
         mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
@@ -35,6 +37,32 @@ export const nodeLockFs = {
     remove(path) {
         rmSync(path, { force: true });
     },
+    link(from, to) {
+        try {
+            linkSync(from, to);
+            return true;
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === "EEXIST" || code === "ENOENT")
+                return false;
+            throw error;
+        }
+    },
+    ageMs(path) {
+        try {
+            return Date.now() - statSync(path).ctimeMs;
+        }
+        catch {
+            return null;
+        }
+    },
+    replace(path, text) {
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        const temp = `${path}.${process.pid}.tmp`;
+        writeFileSync(temp, text, { mode: 0o600 });
+        renameSync(temp, path);
+    },
 };
 /** Remove the start lock when it names `pid`. A restart copy calls this once it owns the port. */
 export function removeStartLockFor(pid, path = startLockPath(), lockFs = nodeLockFs) {
@@ -104,19 +132,40 @@ function lockIsStale(text, deps) {
         return true;
     }
 }
-/** Take the start lock. A stale lock is removed and taken once more. */
-function takeLock(deps) {
+/**
+ * Take the start lock. A stale lock is replaced by one caller only: the caller
+ * that hard-links it to a tombstone named after its text. Remove-then-create
+ * alone let two callers each remove the lock the other had just created.
+ */
+export function takeStartLock(deps) {
     const mine = JSON.stringify({ pid: deps.pid, at: deps.now() });
     if (deps.lockFs.createExclusive(deps.lockPath, mine))
         return true;
     const seen = deps.lockFs.read(deps.lockPath);
+    if (seen === null)
+        return deps.lockFs.createExclusive(deps.lockPath, mine);
     if (!lockIsStale(seen, deps))
         return false;
-    // Another caller may have replaced the stale lock since it was read.
-    if (deps.lockFs.read(deps.lockPath) !== seen)
+    const tomb = `${deps.lockPath}.${createHash("sha256").update(seen).digest("hex").slice(0, 16)}.stale`;
+    if (!deps.lockFs.link(deps.lockPath, tomb)) {
+        // A takeover that crashed after its link leaves the tombstone behind. Clear
+        // it, and let the next caller do the takeover.
+        const age = deps.lockFs.ageMs(tomb);
+        if (age !== null && age > START_LOCK_STALE_MS)
+            deps.lockFs.remove(tomb);
         return false;
-    deps.lockFs.remove(deps.lockPath);
-    return deps.lockFs.createExclusive(deps.lockPath, mine);
+    }
+    try {
+        // A slow caller can link a lock that was replaced after it read it. That
+        // lock is live, so leave it.
+        if (deps.lockFs.read(tomb) !== seen)
+            return false;
+        deps.lockFs.remove(deps.lockPath);
+        return deps.lockFs.createExclusive(deps.lockPath, mine);
+    }
+    finally {
+        deps.lockFs.remove(tomb);
+    }
 }
 /**
  * Use a running OMMS web app, or start one detached `om-memory-system web`.
@@ -152,7 +201,7 @@ export async function ensureWebApp(options) {
             await logCode("no-runtime");
             return "no-runtime";
         }
-        held = takeLock(deps);
+        held = takeStartLock(deps);
         if (!held)
             return await waitForOther(settings.baseUrl, wait, remaining, deps);
         // Another caller may have finished its start before this one took the lock.

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

@@ -58,6 +58,7 @@ export declare class WebServer {
     setOnStepAside(callback: () => void | Promise<void>): void;
     /** Standalone web apps register this to stop or restart from the page. */
     setOnPowerAction(callback: (action: PowerAction) => void | Promise<void>): void;
+    /** Only a local caller may stop the web app; the token alone is not enough. */
     private handlePowerAction;
     private scheduleStepAside;
     private handleStepAside;

package/dist/services/web-server.js

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { createServer } from "node:http";
 import { Readable } from "node:stream";
@@ -143,6 +144,8 @@ export function nextFallbackPort(currentPort, failedTakeovers, maxFallbackPort,
 const STEP_ASIDE_HOLD_OFF_MS = 60_000;
 /** Lets the 202 reply reach the caller before the server stops. */
 const STEP_ASIDE_REPLY_GRACE_MS = 100;
+/** Differs between processes, so the page can tell a restarted web app from the old one. */
+const PROCESS_INSTANCE = randomUUID();
 export class WebServer {
     server = null;
     config;
@@ -217,6 +220,7 @@ export class WebServer {
     setOnPowerAction(callback) {
         this.onPowerActionCallback = callback;
     }
+    /** Only a local caller may stop the web app; the token alone is not enough. */
     handlePowerAction(action, remoteAddress) {
         const record = (outcome) => log("Web server power request", { action, outcome, ownVersion: packageVersion() });
         if (!isLoopbackAddress(remoteAddress)) {
@@ -440,6 +444,8 @@ export class WebServer {
                 clearTimeout(timer);
         this.stepAsideTimer = null;
         this.holdOffTimer = null;
+        // A restart whose copy failed calls start() again on this server.
+        this.startPromise = null;
         if (!this.isOwner || !this.server) {
             return;
         }
@@ -591,10 +597,12 @@ export class WebServer {
                         ? controls.resume(host, cwd)
                         : controls.runNow(host, cwd));
             }
+            // The page shows the power button only when this says the caller may control the web app.
             if (path === "/api/web/status" && method === "GET") {
                 return this.jsonResponse({
                     version: packageVersion(),
                     canControl: isLoopbackAddress(remoteAddress) && this.onPowerActionCallback !== null,
+                    instance: PROCESS_INSTANCE,
                 });
             }
             if ((path === "/api/web/stop" || path === "/api/web/restart") && method === "POST") {