@aron98/load-lock 1.2.1 → 1.4.0

package/dist/cli/main.js

@@ -6,13 +6,18 @@
  * (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 { waitForTrackedJob } from "../shared/wait-completion.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 +66,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",
@@ -77,7 +163,7 @@ const HELP_GROUPS = [
     {
         title: "waiting & running",
         items: [
-            { names: ["wait"], desc: "sleep until a queued request's turn, then auto-claim the offer: --id <request-id> [--timeout <ms>]" },
+            { names: ["wait"], desc: "sleep until a queued request's turn (--id <request-id>), auto-claiming the offer — or until a heavy job finishes (--job <request-id>): [--timeout <ms>]" },
             { names: ["run"], desc: "acquire (or reuse) a permit and run a command under it: run [--permit <token> | acquire flags] -- <cmd>" },
         ],
     },
@@ -96,8 +182,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 +243,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;
@@ -299,19 +389,43 @@ async function main() {
             out(await withClient((c) => c.request("attach_pid", { permitToken: token, pid })));
             return;
         }
-        // ------------------------------------------------------- wait (offer -> permit)
+        // ------------------------------------------------------- wait (offer -> permit / job -> done)
         case "wait": {
-            // Watches a queued request; auto-claims the offer when capacity is
-            // handed to it and prints the permit token. Honest bounded blocking
-            // for scriptable flows (aider, plain shell scripts). Shares the exact
-            // implementation with the MCP wait_for_turn tool and the OpenCode
-            // plugin (src/shared/wait-turn.ts).
-            const id = S("id") || fail("wait: --id <request-id> required");
+            // Two honest bounded sleeps sharing one command:
+            //   --id  : queue phase — watches a queued request, auto-claims the
+            //           offer when capacity reaches it, prints the permit token.
+            //   --job : execution phase — sleeps until the daemon-tracked job for
+            //           that request-id finishes (liveness sweep wake; the permit
+            //           is released before you are woken). Structured result on
+            //           every path; still_running = checkpoint, call again.
+            // Both share the exact implementations with the MCP tools and the
+            // OpenCode plugin (src/shared/wait-turn.ts / wait-completion.ts).
             const timeoutMs = N("timeout", 600_000);
-            const agent = S("agent", defaultAgent());
             const c = new LLClient();
             await c.connect();
             try {
+                const job = S("job");
+                if (job) {
+                    const r = await waitForTrackedJob({ client: c, requestId: job, timeoutMs });
+                    out({
+                        state: r.state,
+                        request_id: r.requestId ?? job,
+                        exit_code: r.exitCode,
+                        duration_ms: r.durationMs,
+                        permit_released: r.permitReleased,
+                        waited_ms: r.waitedMs,
+                        effective_wait_ms: r.effectiveWaitMs,
+                        started_at: r.startedAt,
+                        detail: r.detail ?? r.nextAction,
+                    });
+                    if (r.state === "finished")
+                        return;
+                    if (r.state === "still_running")
+                        fail(`wait: job still running after ${r.waitedMs}ms (checkpoint — call again)`, 68);
+                    fail(`wait: job is ${r.state.replace(/_/g, " ")} — ${r.nextAction}`, 69);
+                }
+                const id = S("id") || fail("wait: --id <request-id> (queue wait) or --job <request-id> (job wait) required");
+                const agent = S("agent", defaultAgent());
                 const r = await waitForTurn({ client: c, agentId: agent, requestId: id, timeoutMs });
                 if (r.state === "granted" && r.entry?.permitToken) {
                     out({ permit_token: r.entry.permitToken, state: r.state, request_id: r.requestId, auto_claimed: r.autoClaimed ?? false });
@@ -339,28 +453,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 {
+                    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 {
+                    /* ignore */
+                }
                 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`);
+                    rmSync(join(dir, "daemon.json"), { force: true });
                 }
                 catch {
-                    process.stdout.write("load-lock: no running daemon found\n");
+                    /* 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 +611,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

@@ -27,11 +27,14 @@ export declare class Daemon {
      *  restart via the event cursor) and the process can exit promptly. */
     private conns;
     private waiters;
+    /** wait_for_completion calls blocked on tracked jobs; multiple waiters per job are fine. */
+    private completionWaiters;
     private sentEventId;
     private stateDirPath;
     private socketPath;
     private sweepTimer;
     private expiryTimer;
+    private restartTimer;
     private stopped;
     constructor(opts?: {
         stateDir?: string;
@@ -50,6 +53,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;
     /**
@@ -59,6 +79,28 @@ export declare class Daemon {
      * push notifications — no model-authored busy-polling required.
      */
     private waitForAdmission;
+    /**
+     * Bounded blocking wait for a daemon-tracked job's completion. Mirrors
+     * waitForAdmission: the call is held server-side and woken by
+     * resolveCompletionWaiters() when the job is observed done — which always
+     * happens AFTER the permit has been released (finish() frees capacity
+     * before the event is emitted, and waiters are resolved after that).
+     * timeoutMs 0 is check-only. Never blocks unbounded.
+     */
+    private waitForJobCompletion;
+    /**
+     * Classify a request whose entry is no longer held (released, reclaimed,
+     * cancelled, or never started) into a structured completion result, using
+     * the most recent event for the request.
+     */
+    private classifyEntryCompletion;
+    /**
+     * Wake blocked wait_for_completion calls whose tracked job has ended.
+     * Called after every machine transition (afterOp, sweep, expiry timer) —
+     * always AFTER finish() has freed capacity and after the event flush, so
+     * a woken agent observes the pool as free. Entries still held are skipped.
+     */
+    private resolveCompletionWaiters;
     /** Runs after every dispatch: sweep deadlines, auto-claim for waiters, flush events, journal. */
     private afterOp;
     private armExpiryTimer;