@aron98/load-lock 1.2.0 → 1.3.0

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;
     /**

package/dist/core/daemon.js

@@ -20,11 +20,21 @@ import { createServer } from "node:net";
 import { existsSync, mkdirSync, unlinkSync, writeFileSync, readFileSync, rmSync } from "node:fs";
 import { readdirSync } from "node:fs";
 import { join } from "node:path";
+import { spawn } from "node:child_process";
 import { Machine } from "./state.js";
 import { loadState, saveState, loadJournal, saveJournal, socketPath as defaultSocket, stateDir as defaultStateDir } from "./persist.js";
 import { inspectMachine } from "./sysinfo.js";
 import { ProtocolError } from "../shared/protocol.js";
 import { isWindows, probeTransport } from "../shared/transport.js";
+import { packageVersion, compareVersions } from "../shared/version.js";
+/** Package version of the copy of load-lock this daemon process runs from. */
+const DAEMON_VERSION = packageVersion();
+/**
+ * Env marker set on the respawned daemon: the version this process already
+ * restarted for. Prevents restart loops when a newer client pings twice —
+ * only one respawn per version bump.
+ */
+const RESTARTED_FOR_ENV = "LOAD_LOCK_RESTARTED_FOR";
 export class Daemon {
     machine;
     server = null;
@@ -39,6 +49,7 @@ export class Daemon {
     socketPath;
     sweepTimer = null;
     expiryTimer = null;
+    restartTimer = null;
     stopped = false;
     constructor(opts = {}) {
         this.stateDirPath = defaultStateDir(opts.stateDir);
@@ -108,6 +119,8 @@ export class Daemon {
             clearInterval(this.sweepTimer);
         if (this.expiryTimer)
             clearTimeout(this.expiryTimer);
+        if (this.restartTimer)
+            clearTimeout(this.restartTimer);
         for (const w of this.watchers)
             w.socket.destroy();
         this.watchers.clear();
@@ -171,6 +184,8 @@ export class Daemon {
             this.send(sock, { id: null, ok: false, error: { code: "invalid", message: "malformed JSON line" } });
             return;
         }
+        // Version handshake: remember the client's version for skew detection.
+        const clientVersion = typeof msg.clientVersion === "string" ? msg.clientVersion : undefined;
         let result;
         let agentId;
         try {
@@ -187,6 +202,9 @@ export class Daemon {
             else {
                 this.send(sock, { id: msg.id, ok: false, error: { code: "internal", message: String(err?.message ?? err) } });
             }
+            // Respond first, then consider a self-restart — even on errors, a
+            // newer client means this daemon is running stale on-disk code.
+            this.maybeScheduleSelfRestart(clientVersion);
             return;
         }
         // Tool-boundary delivery: surface this agent's outstanding offers/queue
@@ -195,6 +213,63 @@ export class Daemon {
             result.pending = this.machine.pending(agentId);
         }
         this.send(sock, { id: msg.id, ok: true, result });
+        this.maybeScheduleSelfRestart(clientVersion);
+    }
+    // -------------------------------------------------------- version handshake
+    /**
+     * 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.
+     */
+    maybeScheduleSelfRestart(clientVersion) {
+        if (this.stopped || this.restartTimer || !clientVersion)
+            return;
+        if (compareVersions(clientVersion, DAEMON_VERSION) <= 0)
+            return;
+        const restartedFor = process.env[RESTARTED_FOR_ENV];
+        if (restartedFor && compareVersions(clientVersion, restartedFor) <= 0)
+            return; // already tried
+        this.restartTimer = setTimeout(() => {
+            this.restartTimer = null;
+            this.selfRestart(clientVersion);
+        }, 250);
+        this.restartTimer.unref?.();
+    }
+    /**
+     * 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.
+     */
+    selfRestart(clientVersion) {
+        if (this.stopped)
+            return;
+        // Best-effort persistence; a failed save must not block the restart.
+        try {
+            saveState(this.stateDirPath, this.machine.config, this.machine.history);
+            saveJournal(this.stateDirPath, this.machine.journalEntries());
+        }
+        catch {
+            /* journal is best-effort */
+        }
+        this.stop();
+        try {
+            const child = spawn(process.execPath, process.argv.slice(1), {
+                detached: true,
+                stdio: "ignore",
+                cwd: process.cwd(),
+                env: { ...process.env, [RESTARTED_FOR_ENV]: clientVersion },
+            });
+            child.unref();
+        }
+        catch {
+            /* if the respawn fails the next client contact re-triggers it */
+        }
+        process.exit(0);
     }
     // --------------------------------------------------------------- dispatch
     /** Returns [result, agentIdForPendingAttachment]. */
@@ -202,7 +277,10 @@ export class Daemon {
         const m = this.machine;
         switch (method) {
             case "hello":
-                return [{ protocolVersion: 1, pid: process.pid, startedAt: m.startedAt, configVersion: m.config.version }, undefined];
+                return [
+                    { protocolVersion: 1, pid: process.pid, startedAt: m.startedAt, configVersion: m.config.version, daemonVersion: DAEMON_VERSION },
+                    undefined,
+                ];
             case "acquire": {
                 const params = p;
                 let res = m.acquire(params);
@@ -265,8 +343,11 @@ export class Daemon {
                 const res = m.pending(String(p.agentId));
                 return [res, String(p.agentId)];
             }
-            case "status":
-                return [m.status(p.pool ? String(p.pool) : undefined), undefined];
+            case "status": {
+                const res = m.status(p.pool ? String(p.pool) : undefined);
+                res.daemon.daemonVersion = DAEMON_VERSION;
+                return [res, undefined];
+            }
             case "get_config":
                 return [m.get_config(), undefined];
             case "configure": {

package/dist/core/persist.js

@@ -3,9 +3,11 @@
  * State dir: $XDG_STATE_HOME/load-lock (default ~/.local/state/load-lock;
  * Windows: %LOCALAPPDATA%\load-lock — see shared/transport.ts).
  *
- * Only *configuration* persists across daemon restarts. Permits and queue
- * are ephemeral by design (see docs/ARCHITECTURE.md — restart behavior):
- * tokens are daemon-instance-scoped, and agents re-acquire after a restart.
+ * Configuration persists across daemon restarts, plus the journal
+ * (journal.json): held permits AND queued/offered requests. Held permits
+ * are restored conservatively (tracked jobs re-checked for liveness, same
+ * permit tokens so late releases stay idempotent); queued requests are
+ * re-queued FIFO with the same requestIds (see docs/ARCHITECTURE.md).
  */
 import { mkdirSync, writeFileSync, renameSync, readFileSync, existsSync } from "node:fs";
 import { dirname, join } from "node:path";

package/dist/core/state.d.ts

@@ -180,16 +180,18 @@ export declare class Machine {
     get_config(): GetConfigResult;
     configure(p: ConfigureParams): ConfigureResult;
     history: ConfigHistoryEntry[];
-    /** Held permits to persist for conservative restart reconciliation. */
+    /** Held permits (first) and queued/offered requests to persist across restarts. */
     journalEntries(): JournalEntry[];
     /**
-     * Restore held permits after a daemon restart (conservative reconciliation):
+     * Restore state after a daemon restart (conservative reconciliation):
+     *  - queued (incl. previously offered): re-queued FIFO by original enqueue
+     *    time, same requestIds so idempotent re-acquire still works; pools no
+     *    longer in the config are dropped. Offered entries restart as queued
+     *    and get a fresh offer (old offer tokens are invalid after restart).
      *  - tracked: re-check liveness via the supplied probe; dead => release,
      *    alive => keep (same token, so a late explicit release still works).
      *  - claimed: keep the start deadline (reclaimed by tick if already past).
      *  - untracked: keep, with a FRESH lease window from restore time.
-     * Queued/offered requests are deliberately NOT restored — queued agents
-     * re-acquire (documented restart behavior).
      */
     restore(journal: JournalEntry[], liveness: (e: {
         pid?: number;
@@ -198,6 +200,7 @@ export declare class Machine {
     }) => boolean | null): {
         kept: number;
         releasedDead: number;
+        queued: number;
     };
 }
 export {};