@aron98/load-lock 1.3.0 → 1.5.0

package/dist/core/daemon.js

@@ -44,6 +44,8 @@ export class Daemon {
      *  restart via the event cursor) and the process can exit promptly. */
     conns = new Set();
     waiters = new Map();
+    /** wait_for_completion calls blocked on tracked jobs; multiple waiters per job are fine. */
+    completionWaiters = new Map();
     sentEventId;
     stateDirPath;
     socketPath;
@@ -115,6 +117,22 @@ export class Daemon {
         if (this.stopped)
             return;
         this.stopped = true;
+        // Resolve blocked wait_for_completion calls first so no promise dangles.
+        // Responses may not make it out (conns are destroyed below) — that is
+        // fine: clients see the disconnect, reconnect, and re-issue the wait.
+        for (const [, waiters] of this.completionWaiters) {
+            for (const w of waiters) {
+                clearTimeout(w.timer);
+                w.resolve({
+                    state: "job_unknown",
+                    requestId: w.requestId,
+                    waitedMs: this.machine.now() - w.registeredAt,
+                    nextAction: "daemon is stopping — call wait_for_completion again after it is back",
+                    detail: "daemon stopping",
+                });
+            }
+        }
+        this.completionWaiters.clear();
         if (this.sweepTimer)
             clearInterval(this.sweepTimer);
         if (this.expiryTimer)
@@ -395,6 +413,24 @@ export class Daemon {
                 m.adminRelease(String(p.requestId));
                 return [{ ok: true }, undefined];
             }
+            case "wait_for_completion": {
+                // Bounded "sleep until the job finishes" for a daemon-tracked job
+                // (issue #36) — the execution-phase counterpart of wait_for_turn.
+                const requestId = String(p.requestId ?? "");
+                if (!requestId)
+                    throw new ProtocolError("invalid", "wait_for_completion: requestId is required");
+                const requested = Number(p.timeoutMs ?? 0);
+                if (!Number.isFinite(requested) || requested < 0) {
+                    throw new ProtocolError("invalid", "wait_for_completion: timeoutMs must be a non-negative number of milliseconds");
+                }
+                // Same bounded-sleep contract as wait_for_turn: one call is capped by
+                // maxTurnWaitMs; longer waits are checkpointed (still_running) and re-issued.
+                const timeoutMs = Math.min(requested, m.config.maxTurnWaitMs);
+                const res = await this.waitForJobCompletion(requestId, timeoutMs);
+                if (timeoutMs !== requested)
+                    res.effectiveWaitMs = timeoutMs;
+                return [res, undefined];
+            }
             default:
                 throw new ProtocolError("invalid", `unknown method "${method}"`);
         }
@@ -414,6 +450,181 @@ export class Daemon {
             this.waiters.set(requestId, { requestId, resolve, timer });
         });
     }
+    // ---------------------------------------------- wait_for_completion (issue #36)
+    /**
+     * 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.
+     */
+    async waitForJobCompletion(requestId, timeoutMs) {
+        const m = this.machine;
+        let entry;
+        try {
+            entry = m.entryById(requestId);
+        }
+        catch {
+            return {
+                state: "job_unknown",
+                requestId,
+                waitedMs: 0,
+                nextAction: "no request with this id exists (yet) — check the id, or acquire first",
+                detail: "unknown request id",
+            };
+        }
+        if (entry.state === "held") {
+            if (entry.phase !== "running_tracked") {
+                const why = entry.phase === "claimed"
+                    ? "permit is held but no process is attached yet — start the job (run_with_permit / attach_pid / start_job) first"
+                    : "permit is running untracked (no process association) — completion is not observable; attach a pid or poll your job directly";
+                return { state: "job_unknown", requestId, waitedMs: 0, startedAt: entry.startedAt, nextAction: why, detail: `held permit in phase "${entry.phase}"` };
+            }
+            if (timeoutMs === 0) {
+                return {
+                    state: "still_running",
+                    requestId,
+                    waitedMs: 0,
+                    startedAt: entry.startedAt,
+                    nextAction: "job still running — call wait_for_completion again (with a timeout) to sleep until it finishes",
+                    detail: "check-only",
+                };
+            }
+            // Register a completion waiter; woken by resolveCompletionWaiters()
+            // when the job ends, or checkpointed by the bounded timer below.
+            return await new Promise((resolve) => {
+                const registeredAt = m.now();
+                const waiter = {
+                    requestId,
+                    resolve,
+                    timer: null,
+                    registeredAt,
+                };
+                waiter.timer = setTimeout(() => {
+                    const arr = this.completionWaiters.get(requestId);
+                    if (arr) {
+                        const idx = arr.indexOf(waiter);
+                        if (idx >= 0)
+                            arr.splice(idx, 1);
+                        if (arr.length === 0)
+                            this.completionWaiters.delete(requestId);
+                    }
+                    resolve({
+                        state: "still_running",
+                        requestId,
+                        waitedMs: m.now() - registeredAt,
+                        startedAt: entry.startedAt,
+                        nextAction: "job still running — call wait_for_completion again to keep sleeping honestly",
+                        detail: "wait budget elapsed",
+                    });
+                }, timeoutMs);
+                waiter.timer.unref?.();
+                const arr = this.completionWaiters.get(requestId) ?? [];
+                arr.push(waiter);
+                this.completionWaiters.set(requestId, arr);
+            });
+        }
+        // Terminal or pre-execution states: classify from the entry's last event.
+        return this.classifyEntryCompletion(requestId, 0);
+    }
+    /**
+     * 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.
+     */
+    classifyEntryCompletion(requestId, waitedMs) {
+        const m = this.machine;
+        const ev = m.lastEventForRequest(requestId, 0);
+        const startedAt = ev?.entry?.startedAt;
+        if (!ev) {
+            return {
+                state: "job_unknown",
+                requestId,
+                waitedMs,
+                nextAction: "no completion is observable for this request id — verify the id or re-acquire",
+                detail: "entry is no longer held and no matching event was found",
+            };
+        }
+        switch (ev.type) {
+            case "released":
+            case "auto_released":
+                return {
+                    state: "finished",
+                    requestId,
+                    durationMs: startedAt !== undefined ? ev.ts - startedAt : undefined,
+                    permitReleased: true,
+                    waitedMs,
+                    startedAt,
+                    nextAction: "job finished and the permit is released — capacity is free; proceed with the next step",
+                    detail: ev.detail,
+                };
+            case "reclaimed":
+                if ((ev.detail ?? "").includes("admin")) {
+                    return {
+                        state: "stopped_by_request",
+                        requestId,
+                        waitedMs,
+                        startedAt,
+                        nextAction: "the permit was force-released by an admin while you were waiting — re-acquire before running more heavy work",
+                        detail: ev.detail,
+                    };
+                }
+                return {
+                    state: "job_unknown",
+                    requestId,
+                    waitedMs,
+                    startedAt,
+                    nextAction: "the permit was reclaimed before completion could be observed — re-acquire before running more heavy work",
+                    detail: ev.detail,
+                };
+            case "cancelled":
+                return {
+                    state: "job_unknown",
+                    requestId,
+                    waitedMs,
+                    startedAt,
+                    nextAction: "the request was cancelled — re-acquire before running more heavy work",
+                    detail: ev.detail,
+                };
+            default:
+                return {
+                    state: "job_unknown",
+                    requestId,
+                    waitedMs,
+                    startedAt,
+                    nextAction: "no completion is observable for this request id — verify the id or re-acquire",
+                    detail: `entry is in state "${ev.entry?.state ?? "unknown"}" (last event: ${ev.type})`,
+                };
+        }
+    }
+    /**
+     * 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.
+     */
+    resolveCompletionWaiters() {
+        if (this.completionWaiters.size === 0)
+            return;
+        const m = this.machine;
+        for (const [requestId, waiters] of [...this.completionWaiters]) {
+            let entry;
+            try {
+                entry = m.entryById(requestId);
+            }
+            catch {
+                entry = undefined;
+            }
+            if (entry && entry.state === "held")
+                continue; // job still running
+            this.completionWaiters.delete(requestId);
+            for (const w of waiters) {
+                clearTimeout(w.timer);
+                w.resolve(this.classifyEntryCompletion(requestId, m.now() - w.registeredAt));
+            }
+        }
+    }
     // ------------------------------------------------------------- post-op pass
     /** Runs after every dispatch: sweep deadlines, auto-claim for waiters, flush events, journal. */
     afterOp() {
@@ -448,6 +659,10 @@ export class Daemon {
             for (const ev of fresh)
                 this.broadcast(ev);
         }
+        // Wake completion waiters whose job ended in this op — after the events
+        // flushed, i.e. after finish() already freed the capacity (ordering
+        // guarantee: a woken agent sees the pool as free).
+        this.resolveCompletionWaiters();
         // Persist held permits for restart reconciliation.
         try {
             saveJournal(this.stateDirPath, m.journalEntries());
@@ -474,6 +689,8 @@ export class Daemon {
                 for (const ev of fresh)
                     this.broadcast(ev);
             }
+            // Reclaims performed by the tick above must also wake waiters.
+            this.resolveCompletionWaiters();
             try {
                 saveJournal(this.stateDirPath, this.machine.journalEntries());
             }
@@ -533,6 +750,10 @@ export class Daemon {
             for (const ev of fresh)
                 this.broadcast(ev);
         }
+        // Wake completion waiters woken by this sweep (tracked job confirmed
+        // dead => auto-released above) — after capacity was freed and events
+        // flushed, per the wake ordering guarantee.
+        this.resolveCompletionWaiters();
     }
 }
 // --------------------------------------------------------------------- helpers

package/dist/core/state.d.ts

@@ -75,6 +75,11 @@ export declare class Machine {
     /** Events with id > since, newest last. */
     eventsSince(since: number, agentId?: string, limit?: number): MachineEvent[];
     latestEventId(): number;
+    /**
+     * Newest event with id > `since` whose entry is the given request, or null.
+     * Scans backwards, so the first match is the most recent one.
+     */
+    lastEventForRequest(requestId: string, since: number): MachineEvent | null;
     private emit;
     snapshot(e: Entry): EntrySnapshot;
     private ownerSnapshot;

package/dist/core/state.js

@@ -87,6 +87,20 @@ export class Machine {
     latestEventId() {
         return this.nextEventId - 1;
     }
+    /**
+     * Newest event with id > `since` whose entry is the given request, or null.
+     * Scans backwards, so the first match is the most recent one.
+     */
+    lastEventForRequest(requestId, since) {
+        for (let i = this.events.length - 1; i >= 0; i--) {
+            const ev = this.events[i];
+            if (ev.id <= since)
+                break;
+            if (ev.entry?.requestId === requestId)
+                return ev;
+        }
+        return null;
+    }
     emit(type, entry, extra) {
         const targetAgent = entry ? entry.agentId : "*";
         const ev = {
@@ -134,6 +148,8 @@ export class Machine {
             s.leaseDeadline = e.leaseDeadline;
         if (e.lastSeen)
             s.lastSeen = e.lastSeen;
+        if (e.startedAt !== undefined)
+            s.startedAt = e.startedAt;
         return s;
     }
     ownerSnapshot(e) {

package/dist/dashboard/feed.d.ts

@@ -18,6 +18,19 @@ export interface FeedOptions {
     inspectEveryMs?: number;
     /** Reconnect backoff base (default 250 ms). */
     reconnectBaseMs?: number;
+    /**
+     * How often to re-check install drift between this running copy and the
+     * PATH-resolved `load-lock` CLI (default 15_000 ms; 0 disables). A harness
+     * that loads plugin code once at startup keeps running the OLD copy after
+     * an update — this makes that visible on the dashboard (issue #39).
+     */
+    driftCheckMs?: number;
+    /**
+     * Wording of the drift hint: "opencode" says "restart opencode to pick up
+     * vX" (the plugin cannot hot-reload), "cli" (default) says the running
+     * copy is stale relative to the PATH CLI.
+     */
+    driftSurface?: "cli" | "opencode";
 }
 export declare class DashboardFeed {
     private client;
@@ -33,10 +46,14 @@ export declare class DashboardFeed {
     private daemonStartedAt;
     private refreshTimer;
     private slowTimer;
+    private driftTimer;
+    private drift;
     private stopped;
     private unsub;
     private connecting;
     private viewSeq;
+    /** daemonVersion seen at the previous resync — powers the "restarted onto" note. */
+    private lastDaemonVersion;
     /** Fired whenever the rendered view might have changed (state or data). */
     onChange?: () => void;
     /** Fired on connection-state transitions. */
@@ -69,6 +86,12 @@ export declare class DashboardFeed {
      * Returns the reclaimed request's one-line description for toasts.
      */
     forceRelease(requestId: string): Promise<void>;
+    /**
+     * Re-probe install drift (running copy vs PATH-resolved CLI) and surface
+     * it on the next view. Public so surfaces can trigger it on demand
+     * (e.g. right after a plugin's panel regains focus).
+     */
+    refreshDrift(): void;
     /** Render-ready snapshot; countdowns are computed at `now`. */
     view(now?: number): DashboardView;
 }

package/dist/dashboard/feed.js

@@ -1,10 +1,13 @@
 import { buildDashboardView } from "./view.js";
+import { detectInstallDrift } from "../shared/installs.js";
 const DEFAULTS = {
     eventHistory: 60,
     slowRefreshMs: 15_000,
     refreshDebounceMs: 40,
     inspectEveryMs: 60_000,
     reconnectBaseMs: 250,
+    driftCheckMs: 15_000,
+    driftSurface: "cli",
 };
 export class DashboardFeed {
     client;
@@ -20,10 +23,14 @@ export class DashboardFeed {
     daemonStartedAt = 0;
     refreshTimer = null;
     slowTimer = null;
+    driftTimer = null;
+    drift = null;
     stopped = false;
     unsub = null;
     connecting = null;
     viewSeq = 0;
+    /** daemonVersion seen at the previous resync — powers the "restarted onto" note. */
+    lastDaemonVersion;
     /** Fired whenever the rendered view might have changed (state or data). */
     onChange;
     /** Fired on connection-state transitions. */
@@ -63,7 +70,9 @@ export class DashboardFeed {
             typeof this.client.onDisconnect === "function"
                 ? (this.client.onDisconnect(() => void this.handleDisconnect()) ?? undefined)
                 : null;
-        await this.connectAndSync();
+        // Timers are installed BEFORE the first connect: a failed initial
+        // connect must not leave the feed without its slow-refresh/drift
+        // timers once the reconnect loop eventually recovers (issue #39 H3).
         this.slowTimer =
             this.opts.slowRefreshMs > 0
                 ? setInterval(() => {
@@ -72,6 +81,27 @@ export class DashboardFeed {
                 }, this.opts.slowRefreshMs)
                 : null;
         this.slowTimer?.unref?.();
+        this.driftTimer =
+            this.opts.driftCheckMs > 0
+                ? setInterval(() => {
+                    void this.refreshDrift();
+                }, this.opts.driftCheckMs)
+                : null;
+        this.driftTimer?.unref?.();
+        void this.refreshDrift();
+        try {
+            await this.connectAndSync();
+        }
+        catch (e) {
+            // Issue #39 (hypothesis 3): previously a failed initial connect
+            // rejected start() with no socket ever attached, so no close event
+            // could ever fire handleDisconnect and the feed wedged in
+            // "connecting" forever. Enter the standard reconnect loop instead —
+            // the loop owns recovery, and start() still reports the failure.
+            this.setState("reconnecting");
+            void this.reconnectLoop();
+            throw e;
+        }
     }
     async stop() {
         this.stopped = true;
@@ -79,8 +109,11 @@ export class DashboardFeed {
             clearTimeout(this.refreshTimer);
         if (this.slowTimer)
             clearInterval(this.slowTimer);
+        if (this.driftTimer)
+            clearInterval(this.driftTimer);
         this.refreshTimer = null;
         this.slowTimer = null;
+        this.driftTimer = null;
         this.unsub?.();
         this.unsub = null;
         this.client.close();
@@ -112,12 +145,23 @@ export class DashboardFeed {
         let restartNote;
         if (daemonStartChanged || evRes.latestEventId < this.latestEventId) {
             // Daemon restarted: ids restarted from scratch. Reset and re-pull.
-            restartNote = `daemon restarted (pid ${status.daemon?.pid ?? "?"}); event history re-synced`;
+            const pid = status.daemon?.pid ?? "?";
+            const newVersion = status.daemon?.daemonVersion;
+            // Issue #39 (deliverable d): when the v1.3.0 handshake reports a
+            // DIFFERENT version than the daemon we were talking to, say which
+            // version the daemon restarted onto (e.g. after an update).
+            if (this.lastDaemonVersion && newVersion && newVersion !== this.lastDaemonVersion) {
+                restartNote = `daemon restarted onto v${newVersion} (was v${this.lastDaemonVersion}; pid ${pid}); event history re-synced`;
+            }
+            else {
+                restartNote = `daemon restarted (pid ${pid}); event history re-synced`;
+            }
             this.events = [];
             this.latestEventId = 0;
             const fresh = await this.client.request("events", { sinceEventId: 0 });
             this.mergeEvents(fresh.events, fresh.latestEventId);
         }
+        this.lastDaemonVersion = status.daemon?.daemonVersion;
         this.restartNote = restartNote;
         if (this.inspectAt === 0 || Date.now() - this.inspectAt > this.opts.inspectEveryMs) {
             await this.refreshInspect();
@@ -240,6 +284,22 @@ export class DashboardFeed {
         await this.client.request("admin_release", { requestId });
         await this.refresh().catch(() => { });
     }
+    /**
+     * Re-probe install drift (running copy vs PATH-resolved CLI) and surface
+     * it on the next view. Public so surfaces can trigger it on demand
+     * (e.g. right after a plugin's panel regains focus).
+     */
+    refreshDrift() {
+        if (this.stopped || this.opts.driftCheckMs === 0)
+            return;
+        try {
+            this.drift = detectInstallDrift();
+        }
+        catch {
+            this.drift = null;
+        }
+        this.emitChange();
+    }
     /** Render-ready snapshot; countdowns are computed at `now`. */
     view(now = Date.now()) {
         return buildDashboardView({
@@ -250,6 +310,8 @@ export class DashboardFeed {
             state: this.state,
             lastSyncAt: this.lastSyncAt,
             daemonRestartNote: this.restartNote,
+            installDrift: this.drift,
+            driftSurface: this.opts.driftSurface,
             now,
         });
     }

package/dist/dashboard/frame.js

@@ -70,6 +70,8 @@ export function renderFrame(view, width = 100, height = 40) {
         push(`note: ${view.daemonRestartNote}`);
     if (view.versionSkewNote)
         push(`note: ${view.versionSkewNote}`);
+    if (view.installDriftNote)
+        push(`note: ${view.installDriftNote}`);
     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

@@ -9,6 +9,7 @@
  * "now" is always an explicit parameter, which makes countdowns testable.
  */
 import type * as P from "../shared/protocol.js";
+import type { InstallDrift } from "../shared/installs.js";
 /** Connection state of the dashboard's daemon feed. */
 export type FeedState = "connecting" | "live" | "reconnecting" | "down";
 export interface HolderCard {
@@ -116,6 +117,12 @@ export interface DashboardView {
     daemonRestartNote?: string;
     /** Set when the running daemon is older than the installed copy. */
     versionSkewNote?: string;
+    /**
+     * Set when the RUNNING copy is older than the PATH-resolved CLI install
+     * (issue #39: harnesses like opencode load plugin code once and never
+     * hot-reload it, so an update leaves this session running stale code).
+     */
+    installDriftNote?: string;
     daemon: DaemonView | null;
     pools: PoolView[];
     events: EventLine[];
@@ -148,6 +155,10 @@ export interface DashboardInputs {
     state: FeedState;
     lastSyncAt: number;
     daemonRestartNote?: string;
+    /** Running-copy vs PATH-install drift probe result (null = unknown). */
+    installDrift?: InstallDrift | null;
+    /** Wording hint for the drift note; the TUI plugin passes "opencode". */
+    driftSurface?: "cli" | "opencode";
     now: number;
 }
 export declare function buildDashboardView(inps: DashboardInputs): DashboardView;

package/dist/dashboard/view.js

@@ -186,10 +186,23 @@ export function buildDashboardView(inps) {
         : null;
     // Newest first; keep the tail (feed already bounds history length).
     const evs = [...inps.events].reverse();
+    // Issue #39: make in-memory staleness visible. A harness that loads
+    // plugin code once (opencode never hot-reloads plugins) keeps running
+    // the OLD copy after `npm i -g @aron98/load-lock@latest`; the panel can
+    // only hint at the recovery action, which differs per surface.
+    const drift = inps.installDrift;
+    let installDriftNote;
+    if (drift?.stale && drift.pathVersion) {
+        installDriftNote =
+            inps.driftSurface === "opencode"
+                ? `plugin updated — restart opencode to pick up v${drift.pathVersion} (this session still runs v${drift.ownVersion}; opencode does not hot-reload plugins)`
+                : `PATH CLI v${drift.pathVersion} is newer than this copy v${drift.ownVersion} — you are running a stale install`;
+    }
     return {
         now,
         state: inps.state,
         daemonRestartNote: inps.daemonRestartNote,
+        installDriftNote,
         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,

package/dist/mcp/server.d.ts

@@ -16,11 +16,18 @@
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { LLClient } from "../shared/client.js";
+import { type CliDrift } from "../shared/drift.js";
 export interface McpServerOptions {
     client: LLClient;
     serverName?: string;
     /** Overridden by OpenCode's per-request session metadata when present. */
     agentId?: string;
+    /**
+     * CLI-drift notice to surface (issue #38). Defaults to auto-detection at
+     * build time (this adapter copy vs. the PATH-resolved CLI copy);
+     * pass null to suppress / a value to inject in tests.
+     */
+    drift?: CliDrift | null;
 }
 export declare function buildServer(opts: McpServerOptions): McpServer;
 export declare function runStdioMcp(opts?: {