@aron98/load-lock 1.2.1 → 1.3.0

package/dist/adapters/opencode/tui.js

@@ -89,13 +89,17 @@ function dashboardLines(v, width, f) {
     const syncAge = v.lastSyncAt ? fmtDuration(Math.max(0, v.now - v.lastSyncAt)) : "never";
     push(`load-lock dashboard   ${STATE_LABEL[v.state] ?? v.state}   synced ${syncAge} ago`, stateColor(v.state, f));
     if (v.daemon) {
-        push(`daemon pid ${v.daemon.pid} · uptime ${fmtDuration(v.daemon.uptimeMs)} · config v${v.daemon.configVersion} · protocol v${v.daemon.protocolVersion} · events through #${v.latestEventId}`, f.dim);
+        push(`daemon pid ${v.daemon.pid} · uptime ${fmtDuration(v.daemon.uptimeMs)} · config v${v.daemon.configVersion} · protocol v${v.daemon.protocolVersion}` +
+            (v.daemon.daemonVersion ? ` · daemon v${v.daemon.daemonVersion}` : "") +
+            ` · events through #${v.latestEventId}`, f.dim);
     }
     else {
         push(`daemon unreachable — it auto-spawns on the next load-lock command`, f.dim);
     }
     if (v.daemonRestartNote)
         push(`note: ${v.daemonRestartNote}`, f.warn);
+    if (v.versionSkewNote)
+        push(`note: ${v.versionSkewNote}`, f.warn);
     if (v.machine) {
         const m = v.machine;
         const cg = m.cgroupCpuQuota != null ? ` · cgroup quota ${m.cgroupCpuQuota / 100} CPU` : "";

package/dist/cli/copies.d.ts

@@ -0,0 +1,28 @@
+export interface InstalledCopy {
+    /** Where this copy was found. */
+    source: "cli" | "path" | "opencode-cache";
+    /** Path of the copy's package root (its package.json's directory). */
+    path: string;
+    /** Version string, or null when the package.json could not be read. */
+    version: string | null;
+}
+/**
+ * Find the package.json of the @aron98/load-lock copy that contains the
+ * given file, by climbing parent directories. Best-effort: returns null if
+ * no enclosing package.json matches (or is readable).
+ */
+export declare function enclosingPackage(startDir: string, maxDepth?: number): {
+    path: string;
+    version: string | null;
+} | null;
+/** The copy of load-lock this process runs from (its own package root). */
+export declare function thisCopy(): InstalledCopy | null;
+/**
+ * All installed copies of load-lock detectable on this machine:
+ *  - "cli": the copy this process runs from.
+ *  - "path": any `load-lock` binary found on PATH (deduped by real path,
+ *    so a symlink to the running copy is recognized and not double-listed
+ *    — a copy is only listed under "path" when it differs from "cli").
+ *  - "opencode-cache": copies under opencode's private npm cache.
+ */
+export declare function findInstalledCopies(platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): InstalledCopy[];

package/dist/cli/copies.js

@@ -0,0 +1,207 @@
+/**
+ * Installed-copy detection (issue #34): on a given machine several copies
+ * of load-lock commonly coexist — the globally-installed CLI on PATH, and
+ * the private copy opencode maintains under its npm cache (because
+ * `install --harness opencode` registers the bare package name, opencode
+ * installs and refreshes its own copy on its own schedule).
+ *
+ * All scanning is best-effort: missing paths, unreadable files, and
+ * unexpected layouts yield skipped entries or null versions — never a throw.
+ */
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { isWindows } from "../shared/transport.js";
+/** Package name of this package (used to find enclosing package roots). */
+const PKG_NAME = "@aron98/load-lock";
+/**
+ * Find the package.json of the @aron98/load-lock copy that contains the
+ * given file, by climbing parent directories. Best-effort: returns null if
+ * no enclosing package.json matches (or is readable).
+ */
+export function enclosingPackage(startDir, maxDepth = 12) {
+    let dir = startDir;
+    for (let i = 0; i < maxDepth; i++) {
+        const pkgPath = join(dir, "package.json");
+        try {
+            if (existsSync(pkgPath)) {
+                const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+                if (pkg?.name === PKG_NAME) {
+                    return { path: dir, version: typeof pkg.version === "string" ? pkg.version : null };
+                }
+                // A foreign package.json terminates the climb (e.g. a PATH bin
+                // inside some other tool's package).
+                return null;
+            }
+        }
+        catch {
+            return null;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+    return null;
+}
+/** The copy of load-lock this process runs from (its own package root). */
+export function thisCopy() {
+    // dist/cli/copies.js -> dist/cli -> ... -> <pkg>/package.json
+    const startDir = dirname(dirname(fileURLToPath(import.meta.url)));
+    const found = enclosingPackage(startDir);
+    if (!found)
+        return null;
+    return { source: "cli", path: found.path, version: found.version };
+}
+/**
+ * All installed copies of load-lock detectable on this machine:
+ *  - "cli": the copy this process runs from.
+ *  - "path": any `load-lock` binary found on PATH (deduped by real path,
+ *    so a symlink to the running copy is recognized and not double-listed
+ *    — a copy is only listed under "path" when it differs from "cli").
+ *  - "opencode-cache": copies under opencode's private npm cache.
+ */
+export function findInstalledCopies(platform = process.platform, env = process.env) {
+    const copies = [];
+    const seen = new Set();
+    const add = (c) => {
+        if (!c)
+            return;
+        let real;
+        try {
+            real = realpathSync(c.path);
+        }
+        catch {
+            real = c.path;
+        }
+        if (seen.has(real))
+            return;
+        seen.add(real);
+        copies.push(c);
+    };
+    add(thisCopy());
+    // --- PATH scan ------------------------------------------------------------
+    try {
+        const binNames = isWindows(platform)
+            ? ["load-lock.cmd", "load-lock.exe", "load-lock"]
+            : ["load-lock"];
+        const dirs = (env.PATH ?? "").split(isWindows(platform) ? ";" : ":").filter(Boolean);
+        for (const dir of dirs) {
+            for (const bin of binNames) {
+                try {
+                    const binPath = join(dir, bin);
+                    if (!statSync(binPath).isFile())
+                        continue;
+                    // A shim/wrapper script is not itself the copy — resolve through
+                    // its enclosing package (works for npm/bun global layouts where
+                    // the bin sits in <pkg>/bin or node_modules/.bin via a symlink).
+                    let realBin;
+                    try {
+                        realBin = realpathSync(binPath);
+                    }
+                    catch {
+                        realBin = binPath;
+                    }
+                    const found = enclosingPackage(dirname(realBin)) ?? enclosingPackage(dir);
+                    if (found)
+                        add({ source: "path", path: found.path, version: found.version });
+                }
+                catch {
+                    /* unreadable PATH entry — skip */
+                }
+            }
+        }
+    }
+    catch {
+        /* PATH scan is best-effort */
+    }
+    // --- opencode npm-cache scan ----------------------------------------------
+    // Layout (verified live): <cacheRoot>/opencode/npm/@aron98/load-lock@latest/<ts>/
+    // where "@aron98" and "load-lock@latest" are two nested directories (a
+    // normal npm scoped layout); URL-escaped single-directory variants like
+    // "@aron98%2Fload-lock@latest" also occur. Under each <ts>: either the
+    // real package at node_modules/@aron98/load-lock, or a top-level
+    // package.json (npm-install root).
+    try {
+        const cacheRoot = opencodeCacheRoot(platform, env);
+        if (cacheRoot) {
+            const npmDir = join(cacheRoot, "opencode", "npm");
+            if (existsSync(npmDir)) {
+                const scanTimestampDirs = (pkgBase) => {
+                    let tsDirs = [];
+                    try {
+                        tsDirs = readdirSync(pkgBase).filter((d) => statSync(join(pkgBase, d)).isDirectory());
+                    }
+                    catch {
+                        return;
+                    }
+                    for (const ts of tsDirs) {
+                        const nested = join(pkgBase, ts, "node_modules", "@aron98", "load-lock");
+                        const topLevel = join(pkgBase, ts);
+                        for (const cand of [nested, topLevel]) {
+                            try {
+                                const pkgPath = join(cand, "package.json");
+                                if (!existsSync(pkgPath))
+                                    continue;
+                                const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+                                if (pkg?.name !== PKG_NAME)
+                                    continue;
+                                add({
+                                    source: "opencode-cache",
+                                    path: cand,
+                                    version: typeof pkg.version === "string" ? pkg.version : null,
+                                });
+                                break;
+                            }
+                            catch {
+                                /* skip unreadable timestamp dir */
+                            }
+                        }
+                    }
+                };
+                let scopeDirs = [];
+                try {
+                    scopeDirs = readdirSync(npmDir).filter((d) => statSync(join(npmDir, d)).isDirectory());
+                }
+                catch {
+                    scopeDirs = [];
+                }
+                for (const scopeDir of scopeDirs) {
+                    if (scopeDir.startsWith("@aron98%2Fload-lock")) {
+                        // URL-escaped single-directory form.
+                        scanTimestampDirs(join(npmDir, scopeDir));
+                    }
+                    else if (scopeDir === "@aron98") {
+                        // Scoped layout: @aron98/<name>@<version-range>/<ts>/...
+                        let inner = [];
+                        try {
+                            inner = readdirSync(join(npmDir, scopeDir)).filter((d) => statSync(join(npmDir, scopeDir, d)).isDirectory());
+                        }
+                        catch {
+                            continue;
+                        }
+                        for (const nameDir of inner) {
+                            if (nameDir.startsWith("load-lock"))
+                                scanTimestampDirs(join(npmDir, scopeDir, nameDir));
+                        }
+                    }
+                }
+            }
+        }
+    }
+    catch {
+        /* cache scan is best-effort */
+    }
+    return copies;
+}
+/** Cache root the way opencode resolves it (its npm cache lives under it). */
+function opencodeCacheRoot(platform, env) {
+    if (env.XDG_CACHE_HOME)
+        return env.XDG_CACHE_HOME;
+    if (platform === "win32")
+        return env.LOCALAPPDATA ?? null;
+    if (platform === "darwin")
+        return join(env.HOME ?? homedir(), "Library", "Caches");
+    return join(env.HOME ?? homedir(), ".cache");
+}

package/dist/cli/main.js

@@ -6,13 +6,17 @@
  * (queued/registered); 69 offer/claim failed; 70 internal.
  */
 import { spawn } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, rmSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
+import { connect } from "node:net";
+import { setTimeout as delay } from "node:timers/promises";
 import { LLClient, withClient } from "../shared/client.js";
 import { ProtocolError } from "../shared/protocol.js";
 import { waitForTurn } from "../shared/wait-turn.js";
 import { stateDir, socketPath } from "../core/persist.js";
 import { isWindows, probeTransport, killProcessGroup } from "../shared/transport.js";
+import { packageVersion, compareVersions } from "../shared/version.js";
+import { findInstalledCopies } from "./copies.js";
 import { installCommand, uninstallCommand } from "./install.js";
 import { hookCommand } from "./hook.js";
 import { topCommand } from "./top.js";
@@ -61,6 +65,87 @@ function defaultAgent() {
     return (process.env.LOAD_LOCK_AGENT ||
         "cli:" + (process.env.USER || "user") + "@" + (process.env.HOSTNAME || "localhost"));
 }
+// ------------------------------------------------- daemon service helpers
+/** daemon.json contents, or null when missing/unreadable. */
+function readDaemonInfo(dir) {
+    try {
+        return JSON.parse(readFileSync(join(dir, "daemon.json"), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Version-less hello over a raw socket connection: deliberately does NOT
+ * send clientVersion, so asking a daemon for its identity never orders it
+ * to self-restart (used by `service stop` and post-restart confirmation).
+ * Best-effort: resolves null on any failure.
+ */
+function rawHello(sockPath, timeoutMs = 2000) {
+    return new Promise((resolve) => {
+        let settled = false;
+        let buf = "";
+        const done = (v) => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                sock.destroy();
+            }
+            catch {
+                /* ignore */
+            }
+            resolve(v);
+        };
+        const sock = connect(sockPath, () => {
+            sock.write(JSON.stringify({ id: 1, method: "hello", params: {} }) + "\n");
+        });
+        sock.on("data", (chunk) => {
+            buf += chunk.toString("utf8");
+            const idx = buf.indexOf("\n");
+            if (idx === -1)
+                return;
+            try {
+                const msg = JSON.parse(buf.slice(0, idx));
+                done(msg.ok ? msg.result : null);
+            }
+            catch {
+                done(null);
+            }
+        });
+        sock.on("error", () => done(null));
+        const timer = setTimeout(() => done(null), timeoutMs);
+        timer.unref?.();
+    });
+}
+/** Poll the socket until nothing answers there (bounded). */
+async function waitSocketFree(sockPath, timeoutMs) {
+    const deadline = Date.now() + Math.max(0, timeoutMs);
+    for (;;) {
+        if (!(await probeTransport(sockPath)))
+            return true;
+        if (Date.now() >= deadline)
+            return false;
+        await delay(100);
+    }
+}
+/**
+ * After ordering a self-restart, wait for the daemon to come back running
+ * at least `installed` (the version of this CLI copy). Resolves its hello
+ * result, or null if it did not come back (or an older/pre-handshake
+ * daemon answered again — e.g. the daemon's copy is not actually updated).
+ */
+async function awaitDaemonUpgraded(sockPath, timeoutMs, installed) {
+    const deadline = Date.now() + Math.max(0, timeoutMs);
+    for (;;) {
+        const h = await rawHello(sockPath, 1500);
+        if (h && typeof h.daemonVersion === "string" && compareVersions(h.daemonVersion, installed) >= 0)
+            return h;
+        if (Date.now() >= deadline)
+            return null;
+        await delay(250);
+    }
+}
 const HELP_GROUPS = [
     {
         title: "permit operations",
@@ -96,8 +181,8 @@ const HELP_GROUPS = [
     {
         title: "service & diagnostics",
         items: [
-            { names: ["service"], desc: "daemon lifecycle: start | stop | status" },
-            { names: ["doctor"], desc: "health report: state dir, socket, daemon, machine" },
+            { names: ["service"], desc: "daemon lifecycle: start | stop | status (stop/start take --timeout <ms>)" },
+            { names: ["doctor"], desc: "health report: state dir, socket, daemon, versions + copies, machine" },
             { names: ["recover"], desc: "list held permits with diagnostics; recover force-release --id <request-id>" },
         ],
     },
@@ -157,6 +242,10 @@ async function main() {
                         lines.push(`  offer: ${o.agentLabel || o.agentId} — ${o.reason} (expires in ${Math.max(0, Math.round(((o.offerExpiresAt ?? 0) - Date.now()) / 1000))}s)`);
                     p.queue.forEach((q, i) => lines.push(`  queued #${i + 1}: ${q.agentLabel || q.agentId} — ${q.reason}`));
                 }
+                const dv = r.daemon?.daemonVersion;
+                if (typeof dv === "string" && compareVersions(dv, packageVersion()) < 0) {
+                    lines.push(`note: daemon v${dv} is older than this CLI v${packageVersion()} — it self-restarts on contact; run again to confirm`);
+                }
                 return lines.join("\n");
             });
             return;
@@ -339,28 +428,149 @@ async function main() {
         case "service": {
             const sub = rest[0] ?? "status";
             if (sub === "stop") {
-                // Connect and ask... simplest: SIGTERM via daemon.json pid.
+                // Honest stop: signal the daemon, wait bounded for its socket to go
+                // silent, escalate to SIGKILL, and only report success once the
+                // endpoint is verifiably free. A leftover silent socket file or
+                // daemon.json (crash leftovers) is cleaned up either way.
                 const dir = stateDir();
+                const sock = socketPath();
+                const timeoutMs = N("timeout", 5000);
+                const info = readDaemonInfo(dir);
+                const answering = await probeTransport(sock);
+                if (!answering) {
+                    // Nothing is listening: no daemon to stop. Clean crash leftovers.
+                    try {
+                        if (!isWindows() && existsSync(sock))
+                            unlinkSync(sock);
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                    try {
+                        rmSync(join(dir, "daemon.json"), { force: true });
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                    process.stdout.write("load-lock: no running daemon found (stale files cleaned)\n");
+                    return;
+                }
+                // Identify the daemon: prefer daemon.json, else ask it directly
+                // (version-less hello — stopping must not order a self-restart).
+                let pid = typeof info?.pid === "number" ? info.pid : undefined;
+                if (!pid) {
+                    const hello = await rawHello(sock, 1500);
+                    if (hello && typeof hello.pid === "number")
+                        pid = hello.pid;
+                }
+                if (!pid) {
+                    fail(`the socket ${sock} answers but no pid could be identified (daemon did not respond and daemon.json names none) ` +
+                        `— cannot stop safely; run \`load-lock doctor\``, 70);
+                }
+                let how = "SIGTERM";
+                let stopped = false;
                 try {
-                    const info = JSON.parse(readFileSync(join(dir, "daemon.json"), "utf8"));
-                    process.kill(info.pid, "SIGTERM");
-                    process.stdout.write(`load-lock: daemon (pid ${info.pid}) stopping\n`);
+                    process.kill(pid, "SIGTERM");
+                }
+                catch (e) {
+                    if (e?.code === "ESRCH")
+                        stopped = true; // already gone
+                    else
+                        fail(`cannot signal daemon pid ${pid}: ${e?.message ?? e}`, 70);
+                }
+                if (!stopped)
+                    stopped = await waitSocketFree(sock, timeoutMs);
+                if (!stopped) {
+                    how = "SIGKILL";
+                    try {
+                        process.kill(pid, "SIGKILL");
+                    }
+                    catch {
+                        /* already dead */
+                    }
+                    stopped = await waitSocketFree(sock, timeoutMs);
+                }
+                if (!stopped) {
+                    fail(`daemon pid ${pid} did not stop within ${timeoutMs}ms even after SIGKILL — run \`load-lock doctor\``, 70);
+                }
+                try {
+                    if (!isWindows() && existsSync(sock))
+                        unlinkSync(sock);
                 }
                 catch {
-                    process.stdout.write("load-lock: no running daemon found\n");
+                    /* ignore */
+                }
+                try {
+                    rmSync(join(dir, "daemon.json"), { force: true });
                 }
+                catch {
+                    /* ignore */
+                }
+                process.stdout.write(`load-lock: daemon (pid ${pid}) stopped${how === "SIGKILL" ? " (required SIGKILL after SIGTERM)" : ""}\n`);
                 return;
             }
             if (sub === "start") {
                 // Connecting auto-spawns a detached daemon (see shared/client.ts);
-                // hello confirms it is up.
-                const r = await withClient((c) => c.request("hello", {}));
-                process.stdout.write(`load-lock: daemon running on pid ${r.pid} (${process.env.LOAD_LOCK_SOCKET || "default socket"})\n`);
+                // hello confirms it is up. Refusals name the conflicting pid.
+                const timeoutMs = N("timeout", 10_000);
+                const sock = socketPath();
+                const installed = packageVersion();
+                try {
+                    const r = (await withClient((c) => c.request("hello", {}, timeoutMs)));
+                    const dv = typeof r.daemonVersion === "string" ? r.daemonVersion : undefined;
+                    if (dv && compareVersions(dv, installed) < 0) {
+                        // The handshake just ordered this old daemon to self-restart;
+                        // confirm it comes back on updated code.
+                        const up = await awaitDaemonUpgraded(sock, 8000, installed);
+                        if (up) {
+                            process.stdout.write(`load-lock: daemon self-restarted ${r.pid} -> ${up.pid} (v${dv} -> v${up.daemonVersion}), running on ${sock}\n`);
+                        }
+                        else {
+                            process.stdout.write(`load-lock: daemon running on pid ${r.pid} (${sock}), daemon v${dv} — older than this CLI v${installed}; ` +
+                                `self-restart ordered but not confirmed (its copy may not be updated in place — see docs/OPERATIONS.md)\n`);
+                        }
+                        return;
+                    }
+                    process.stdout.write(`load-lock: daemon running on pid ${r.pid} (${sock})${dv ? `, daemon v${dv}` : ""}\n`);
+                    return;
+                }
+                catch (e) {
+                    if (await probeTransport(sock)) {
+                        // Something owns the endpoint. Name it.
+                        const hello = await rawHello(sock, 1500);
+                        if (hello && typeof hello.pid === "number") {
+                            fail(`start refused: socket answered from pid ${hello.pid} — another daemon owns ${sock}; ` +
+                                `if it is stale, run \`load-lock service stop\` first`, 70);
+                        }
+                        const info = readDaemonInfo(stateDir());
+                        if (info && typeof info.pid === "number") {
+                            fail(`socket ${sock} answers but the daemon did not respond (daemon.json names pid ${info.pid}) — likely hung; ` +
+                                `run \`load-lock service stop\``, 70);
+                        }
+                        fail(`start refused: ${sock} is in use but nothing responsive owns it — run \`load-lock doctor\``, 70);
+                    }
+                    throw e;
+                }
+            }
+            if (sub === "status") {
+                const r = (await withClient((c) => c.request("hello", {})));
+                out(r, () => {
+                    let line = `load-lock daemon: pid ${r.pid}, protocol v${r.protocolVersion}, config version ${r.configVersion}`;
+                    if (typeof r.daemonVersion === "string") {
+                        line += `, daemon v${r.daemonVersion}`;
+                        const installed = packageVersion();
+                        if (compareVersions(r.daemonVersion, installed) < 0) {
+                            line += ` — older than this CLI v${installed}; self-restarting on contact`;
+                        }
+                    }
+                    else {
+                        line += ` — pre-handshake daemon (no version report); \`load-lock service stop\` then any command restarts it on current code`;
+                    }
+                    return line;
+                });
                 return;
             }
-            // status
-            const r = await withClient((c) => c.request("hello", {}));
-            out(r, () => `load-lock daemon: pid ${r.pid}, protocol v${r.protocolVersion}, config version ${r.configVersion}`);
+            fail(`service: unknown subcommand "${sub}" (use start | stop | status)`);
             return;
         }
         case "doctor": {
@@ -376,16 +586,54 @@ async function main() {
             report.socketExists = isWindows() ? await probeTransport(sock) : existsSync(sock);
             report.configExists = existsSync(join(dir, "config.json"));
             report.journalExists = existsSync(join(dir, "journal.json"));
+            report.installedVersion = packageVersion();
+            const warnings = [];
             try {
-                report.hello = await withClient((c) => c.request("hello", {}));
-                const insp = await withClient((c) => c.request("inspect", {}));
+                // One connection for hello + inspect: if the handshake orders a
+                // self-restart (daemon older than this CLI), both requests must
+                // finish before the daemon drains and exits.
+                const { hello, insp } = await withClient(async (c) => ({
+                    hello: await c.request("hello", {}),
+                    insp: await c.request("inspect", {}),
+                }));
+                report.hello = hello;
                 report.effectiveCores = insp.cpu.effectiveCores;
                 report.pressure = insp.pressure.note;
                 report.procs = insp.cpu.cgroupVersion;
+                const dv = hello.daemonVersion;
+                if (typeof dv === "string") {
+                    const installed = packageVersion();
+                    if (compareVersions(dv, installed) < 0) {
+                        warnings.push(`daemon v${dv} is older than this CLI v${installed}; the version handshake ordered it to self-restart`);
+                        const up = await awaitDaemonUpgraded(sock, 5000, installed);
+                        if (up) {
+                            report.daemonUpgradedTo = up.daemonVersion;
+                            warnings.push(`daemon self-restarted to v${up.daemonVersion} (pid ${up.pid}) — now up to date`);
+                        }
+                        else {
+                            warnings.push(`daemon did not come back on v${installed} within 5s (its on-disk copy may not be updated in place — ` +
+                                `see docs/OPERATIONS.md "Update lifecycle"); the next client contact retries the restart`);
+                        }
+                    }
+                }
+                else {
+                    warnings.push(`pre-handshake daemon (no version in hello): restart it onto current code — \`load-lock service stop\`, then any load-lock command`);
+                }
             }
             catch (e) {
                 report.daemon = `unreachable: ${e.message}`;
             }
+            // Multi-copy reality (issue #34): list every detectable copy and warn
+            // when their versions drift apart.
+            const copies = findInstalledCopies();
+            report.copies = copies;
+            const versions = new Set(copies.map((c) => c.version).filter((v) => v !== null));
+            if (versions.size > 1) {
+                warnings.push(`multiple load-lock versions installed (${[...versions].sort().join(", ")}): ` +
+                    copies.map((c) => `${c.source}=${c.version ?? "?"} (${c.path})`).join("; ") +
+                    ` — see docs/COMPATIBILITY.md "Multiple copies of load-lock" for which copy is authoritative for what`);
+            }
+            report.warnings = warnings;
             out(report, () => JSON.stringify(report, null, 2));
             return;
         }

package/dist/core/daemon.d.ts

@@ -32,6 +32,7 @@ export declare class Daemon {
     private socketPath;
     private sweepTimer;
     private expiryTimer;
+    private restartTimer;
     private stopped;
     constructor(opts?: {
         stateDir?: string;
@@ -50,6 +51,23 @@ export declare class Daemon {
     private onConnection;
     private send;
     private handleLine;
+    /**
+     * Self-restart handshake (issue #34): if a client identifies a NEWER
+     * package version than this daemon runs, schedule a respawn so the daemon
+     * picks up the updated on-disk code (e.g. after `npm i -g
+     * @aron98/load-lock` while the daemon kept running). Skew detection is
+     * entirely daemon-side and best-effort: pre-handshake clients that send
+     * no version never trigger a restart.
+     */
+    private maybeScheduleSelfRestart;
+    /**
+     * Drain + respawn onto the updated on-disk code. Persists state and the
+     * journal FIRST, then stops (destroying all client connections — they
+     * reconnect to the fresh daemon), then spawns the replacement with the
+     * exact same argv so a daemon started via the old copy runs the new copy's
+     * code, and exits.
+     */
+    private selfRestart;
     /** Returns [result, agentIdForPendingAttachment]. */
     private dispatch;
     /**