@aron98/load-lock 1.2.1 → 1.3.0

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 {};

package/dist/core/state.js

@@ -830,7 +830,7 @@ export class Machine {
     }
     history = [];
     // ----------------------------------------------------------------- journal
-    /** Held permits to persist for conservative restart reconciliation. */
+    /** Held permits (first) and queued/offered requests to persist across restarts. */
     journalEntries() {
         const out = [];
         for (const e of this.entries.values()) {
@@ -845,6 +845,7 @@ export class Machine {
                 opKey: e.opKey,
                 reason: e.reason,
                 weight: e.weight,
+                state: "held",
                 permitToken: e.permitToken,
                 phase: e.phase ?? "claimed",
                 pid: e.pid,
@@ -855,21 +856,45 @@ export class Machine {
                 leaseDeadline: e.leaseDeadline,
             });
         }
+        for (const e of this.entries.values()) {
+            if (e.state !== "queued" && e.state !== "offered")
+                continue;
+            out.push({
+                requestId: e.id,
+                pool: e.pool,
+                agentId: e.agentId,
+                agentLabel: e.agentLabel,
+                cwd: e.cwd,
+                opKey: e.opKey,
+                reason: e.reason,
+                weight: e.weight,
+                state: "queued",
+                enqueuedAt: e.enqueuedAt ?? e.since,
+                claimedAt: e.since,
+            });
+        }
         return out;
     }
     /**
-     * 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, liveness) {
         let kept = 0;
         let releasedDead = 0;
+        const queuedEntries = [];
         for (const j of journal) {
+            if (j.state === "queued") {
+                queuedEntries.push({ j, at: j.enqueuedAt ?? j.claimedAt });
+                continue;
+            }
             const e = {
                 id: j.requestId,
                 pool: j.pool,
@@ -882,20 +907,20 @@ export class Machine {
                 state: "held",
                 since: j.claimedAt,
                 permitToken: j.permitToken,
-                phase: j.phase,
+                phase: j.phase ?? "claimed",
                 pid: j.pid,
                 pgid: j.pgid,
                 pidStartTime: j.pidStartTime,
                 startedAt: j.startedAt,
                 lastSeen: this.now(),
             };
-            if (j.phase === "claimed") {
+            if (e.phase === "claimed") {
                 e.startDeadline = j.claimedAt + this.config.startTimeoutMs;
             }
-            else if (j.phase === "running_untracked") {
+            else if (e.phase === "running_untracked") {
                 e.leaseDeadline = this.now() + this.config.untrackedLeaseMs; // fresh window
             }
-            else if (j.phase === "running_tracked") {
+            else if (e.phase === "running_tracked") {
                 const alive = liveness(e);
                 if (alive === false) {
                     // Confirmed dead while we were down: release, but keep a terminal
@@ -915,11 +940,40 @@ export class Machine {
             this.byKey.set(`${e.agentId}\u0000${e.opKey}`, e.id);
             kept++;
         }
+        // Re-queue queued requests, oldest first, preserving FIFO fairness.
+        queuedEntries.sort((a, b) => a.at - b.at);
+        let queued = 0;
+        for (const { j } of queuedEntries) {
+            if (!this.config.pools[j.pool])
+                continue; // pool removed while down
+            const e = {
+                id: j.requestId,
+                pool: j.pool,
+                agentId: j.agentId,
+                agentLabel: j.agentLabel,
+                cwd: j.cwd,
+                opKey: j.opKey,
+                reason: j.reason,
+                weight: j.weight,
+                state: "queued",
+                since: this.now(),
+                enqueuedAt: j.enqueuedAt ?? j.claimedAt,
+            };
+            this.entries.set(e.id, e);
+            this.byKey.set(`${e.agentId}\u0000${e.opKey}`, e.id);
+            if (!this.queues.has(e.pool))
+                this.queues.set(e.pool, []);
+            this.queues.get(e.pool).push(e.id);
+            queued++;
+        }
+        // Admit newly-eligible waiters (capacity freed while we were down).
+        for (const name of this.poolNames())
+            this.admit(name);
         this.pushEvent({
             type: "daemon_recovered",
             targetAgent: "*",
-            detail: `restored ${kept} held permit(s) from journal (${releasedDead} confirmed dead and released)`,
+            detail: `restored ${kept} held permit(s) from journal (${releasedDead} confirmed dead and released); re-queued ${queued} waiting request(s)`,
         });
-        return { kept, releasedDead };
+        return { kept, releasedDead, queued };
     }
 }

package/dist/dashboard/frame.js

@@ -59,13 +59,17 @@ export function renderFrame(view, width = 100, height = 40) {
     const syncAge = view.lastSyncAt ? fmtDuration(Math.max(0, view.now - view.lastSyncAt)) : "never";
     push(`load-lock dashboard — machine-wide heavy-work budget   ${state}   synced ${syncAge} ago`);
     if (view.daemon) {
-        push(`daemon pid ${view.daemon.pid} · uptime ${fmtDuration(view.daemon.uptimeMs)} · config v${view.daemon.configVersion} · protocol v${view.daemon.protocolVersion} · events through #${view.latestEventId}`);
+        push(`daemon pid ${view.daemon.pid} · uptime ${fmtDuration(view.daemon.uptimeMs)} · config v${view.daemon.configVersion} · protocol v${view.daemon.protocolVersion}` +
+            (view.daemon.daemonVersion ? ` · daemon v${view.daemon.daemonVersion}` : "") +
+            ` · events through #${view.latestEventId}`);
     }
     else {
         push(`daemon: unreachable — it auto-spawns on the next load-lock command`);
     }
     if (view.daemonRestartNote)
         push(`note: ${view.daemonRestartNote}`);
+    if (view.versionSkewNote)
+        push(`note: ${view.versionSkewNote}`);
     if (view.machine) {
         const m = view.machine;
         const cg = m.cgroupCpuQuota != null ? ` · cgroup ${m.cgroupVersion ?? ""} quota ${m.cgroupCpuQuota / 100} CPU` : "";

package/dist/dashboard/view.d.ts

@@ -105,6 +105,8 @@ export interface DaemonView {
     uptimeMs: number;
     protocolVersion: number;
     configVersion: number;
+    /** Package version of the daemon's code (pre-handshake daemons omit it). */
+    daemonVersion?: string;
 }
 /** The complete render-ready snapshot of the machine-wide budget. */
 export interface DashboardView {
@@ -112,6 +114,8 @@ export interface DashboardView {
     state: FeedState;
     /** False right after a daemon restart was detected (history was reset). */
     daemonRestartNote?: string;
+    /** Set when the running daemon is older than the installed copy. */
+    versionSkewNote?: string;
     daemon: DaemonView | null;
     pools: PoolView[];
     events: EventLine[];

package/dist/dashboard/view.js

@@ -1,3 +1,4 @@
+import { packageVersion, compareVersions } from "../shared/version.js";
 // ---------------------------------------------------------------- formatters
 /** Compact human duration: "412ms", "3s", "4m 12s", "2h 05m", "3d 4h". */
 export function fmtDuration(ms) {
@@ -189,6 +190,9 @@ export function buildDashboardView(inps) {
         now,
         state: inps.state,
         daemonRestartNote: inps.daemonRestartNote,
+        versionSkewNote: d && typeof d.daemonVersion === "string" && compareVersions(d.daemonVersion, packageVersion()) < 0
+            ? `daemon v${d.daemonVersion} is older than installed v${packageVersion()} — it self-restarts on newer-client contact`
+            : undefined,
         daemon: d
             ? {
                 pid: d.pid,
@@ -196,6 +200,7 @@ export function buildDashboardView(inps) {
                 uptimeMs: now - d.startedAt,
                 protocolVersion: d.protocolVersion,
                 configVersion: inps.status?.config.version ?? 0,
+                daemonVersion: d.daemonVersion,
             }
             : null,
         pools,

package/dist/shared/client.js

@@ -29,6 +29,7 @@ import { setTimeout as delay } from "node:timers/promises";
 import { ProtocolError } from "./protocol.js";
 import { socketPath as defaultSocket, stateDir as defaultStateDir } from "../core/persist.js";
 import { probeTransport } from "./transport.js";
+import { packageVersion } from "./version.js";
 export class LLClient {
     sock = null;
     nextId = 1;
@@ -170,7 +171,9 @@ export class LLClient {
                 },
             });
             const sock = this.ensureSock();
-            sock.write(JSON.stringify({ id, method, params }) + "\n");
+            // clientVersion: lets the daemon detect version skew and self-restart
+            // onto newer on-disk code (pre-handshake daemons ignore the field).
+            sock.write(JSON.stringify({ id, method, params, clientVersion: packageVersion() }) + "\n");
         });
     }
     /** Subscribe to daemon events targeted at agentId (or "*" for all). */

package/dist/shared/protocol.d.ts

@@ -6,6 +6,11 @@
  * receive unsolicited event lines.
  *
  * Request:  {"id": <number>, "method": "<name>", "params": {...}}
+ *           Newer clients also stamp the envelope with their package
+ *           version: {..., "clientVersion": "1.2.1"}. Old daemons ignore
+ *           the extra field (forward-compatible); newer daemons use it
+ *           for the update handshake: a client strictly newer than the
+ *           running daemon triggers a daemon self-restart (issue #34).
  * Response: {"id": <number>, "ok": true, "result": {...}}
  *           {"id": <number>, "ok": false, "error": {"code": "...", "message": "..."}}
  * Watch push: {"event": true, ...event fields...}
@@ -140,14 +145,40 @@ export interface JournalEntry {
     opKey: string;
     reason: string;
     weight: number;
-    permitToken: string;
-    phase: PermitPhase;
+    /** Held permits only; queued entries carry no token. */
+    permitToken?: string;
+    /** Held permits only. */
+    phase?: PermitPhase;
     pid?: number;
     pgid?: number;
     pidStartTime?: string;
+    /** When the permit was claimed (held) / the request was journaled. */
     claimedAt: number;
     startedAt?: number;
     leaseDeadline?: number;
+    /**
+     * Journaled lifecycle state (issue #34): "held" (permit — liveness is
+     * reconciled on restore) or "queued" (FIFO position preserved across
+     * restarts/self-restarts; offered entries are journaled as queued and
+     * re-offered with a fresh token after the restart). Absent in journals
+     * written before the update story => "held" (the original format).
+     */
+    state?: "held" | "queued";
+    /** Queue insertion time (queued only) — restores FIFO order. */
+    enqueuedAt?: number;
+}
+/**
+ * Result of `hello`. `daemonVersion` is the running daemon's package
+ * version. OPTIONAL in responses from daemons older than the handshake —
+ * clients must treat a missing value as "unknown (old daemon)" and warn
+ * instead of failing.
+ */
+export interface HelloResult {
+    protocolVersion: number;
+    pid: number;
+    startedAt: number;
+    configVersion: number;
+    daemonVersion?: string;
 }
 export interface PoolStatus {
     pool: string;
@@ -163,6 +194,13 @@ export interface StatusResult {
         pid: number;
         startedAt: number;
         protocolVersion: number;
+        /**
+         * Running daemon's package version (update handshake, issue #34).
+         * Optional because daemons older than the handshake never send it —
+         * clients must treat a missing value as "unknown, old daemon" and
+         * warn rather than fail.
+         */
+        daemonVersion?: string;
     };
     config: {
         version: number;

package/dist/shared/protocol.js

@@ -6,6 +6,11 @@
  * receive unsolicited event lines.
  *
  * Request:  {"id": <number>, "method": "<name>", "params": {...}}
+ *           Newer clients also stamp the envelope with their package
+ *           version: {..., "clientVersion": "1.2.1"}. Old daemons ignore
+ *           the extra field (forward-compatible); newer daemons use it
+ *           for the update handshake: a client strictly newer than the
+ *           running daemon triggers a daemon self-restart (issue #34).
  * Response: {"id": <number>, "ok": true, "result": {...}}
  *           {"id": <number>, "ok": false, "error": {"code": "...", "message": "..."}}
  * Watch push: {"event": true, ...event fields...}

package/dist/shared/version.d.ts

@@ -0,0 +1,10 @@
+/** Version of THIS copy of load-lock (the on-disk install running now). */
+export declare function packageVersion(): string;
+/**
+ * Best-effort dotted-version comparison ("1.2.1" vs "1.10.0"): numeric
+ * segments compared left to right, missing segments as 0, non-numeric
+ * prefixes of a segment ("2-beta" → 2) tolerated. Returns -1 / 0 / 1.
+ * Unparseable input never throws — it compares as 0.0.0, so the daemon
+ * never acts (restarts) on a garbage version.
+ */
+export declare function compareVersions(a: string, b: string): number;

package/dist/shared/version.js

@@ -0,0 +1,57 @@
+/**
+ * Package-version plumbing for the update story (issue #34).
+ *
+ * Every load-lock process — daemon, CLI, MCP server, plugin — learns its
+ * own on-disk package version by reading the package.json that ships next
+ * to its compiled dist/ tree. That version takes part in the client→daemon
+ * handshake: clients stamp every request envelope with it
+ * (`clientVersion`), the daemon stamps every hello with it
+ * (`daemonVersion`), and a strictly-newer client triggers a daemon
+ * self-restart (see core/daemon.ts).
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+let cached;
+/** Version of THIS copy of load-lock (the on-disk install running now). */
+export function packageVersion() {
+    if (cached === undefined) {
+        try {
+            // dist/shared/version.js → <package root>/package.json — resolves the
+            // same way in the repo checkout, a global CLI install, and an
+            // opencode cache copy. npm always ships package.json with the tarball.
+            const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json");
+            cached = String(JSON.parse(readFileSync(pkgPath, "utf8")).version ?? "0.0.0");
+        }
+        catch {
+            cached = "0.0.0";
+        }
+    }
+    return cached;
+}
+/**
+ * Best-effort dotted-version comparison ("1.2.1" vs "1.10.0"): numeric
+ * segments compared left to right, missing segments as 0, non-numeric
+ * prefixes of a segment ("2-beta" → 2) tolerated. Returns -1 / 0 / 1.
+ * Unparseable input never throws — it compares as 0.0.0, so the daemon
+ * never acts (restarts) on a garbage version.
+ */
+export function compareVersions(a, b) {
+    const pa = parse(a);
+    const pb = parse(b);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const x = pa[i] ?? 0;
+        const y = pb[i] ?? 0;
+        if (x !== y)
+            return x < y ? -1 : 1;
+    }
+    return 0;
+}
+function parse(v) {
+    return v
+        .split(".")
+        .map((seg) => {
+        const m = /^(\d+)/.exec(seg.trim());
+        return m ? Number(m[1]) : 0;
+    });
+}

package/dist/test/update.test.d.ts

@@ -0,0 +1 @@
+export {};