@aron98/load-lock 1.3.0 → 1.5.0

package/dist/mcp/server.js

@@ -21,7 +21,10 @@ import { spawn } from "node:child_process";
 import { LLClient } from "../shared/client.js";
 import { POLICY_BRIEF } from "../policy/text.js";
 import { waitForTurn, WaitAbortedError } from "../shared/wait-turn.js";
+import { waitForLocalJob, waitForTrackedJob } from "../shared/wait-completion.js";
 import { killProcessGroup } from "../shared/transport.js";
+import { detectCliDrift } from "../shared/drift.js";
+import { packageVersion } from "../shared/version.js";
 const ACQUIRE_DESC = `Acquire a machine-wide permit before starting resource-intensive local work (full builds, test suites, big compiles/containers).
 
 Pass a short reason and a stable op_key identifying the pending operation (duplicate acquires for the same op_key return the existing request — do not invent a new key while one is live). Set wait_ms (default a few seconds) to block briefly for capacity instead of returning queued immediately; keep doing light work while queued. You will receive an offer to claim when capacity frees. Never start heavy work while merely queued.`;
@@ -30,7 +33,14 @@ const RELEASE_DESC = `Release a held permit immediately after the heavy work fin
 export function buildServer(opts) {
     const client = opts.client;
     const defaultAgent = opts.agentId ?? "agt_" + process.pid.toString(36) + Math.random().toString(36).slice(2, 8);
-    const server = new McpServer({ name: opts.serverName ?? "load-lock", version: "0.1.0" }, { instructions: POLICY_BRIEF });
+    // Drift notice (issue #38): one clear notice naming the exact command when
+    // this adapter copy is newer than the PATH-installed CLI. Notify only —
+    // never auto-install. Printed to stderr at init and embedded in the
+    // initialize instructions so any MCP client sees it exactly once.
+    const drift = opts.drift !== undefined ? opts.drift : detectCliDrift(packageVersion());
+    if (drift)
+        process.stderr.write(drift.message + "\n");
+    const server = new McpServer({ name: opts.serverName ?? "load-lock", version: "0.1.0" }, { instructions: POLICY_BRIEF + (drift ? "\n\n" + drift.message : "") });
     const json = (v) => ({
         content: [{ type: "text", text: JSON.stringify(v, null, 2) }],
     });
@@ -263,13 +273,15 @@ Input: request_id (default: your oldest offered, then front-most queued, then ol
     const jobs = new Map();
     server.registerTool("run_with_permit", {
         title: "Run heavy command under permit",
-        description: "Run the heavy command you hold a permit for, with full lifecycle ownership: spawns the command in its own process group, atomically associates it with your claimed permit, returns a job_id immediately (background execution — do NOT release the permit merely because this returned), and auto-releases the permit when the job exits (success, failure, or kill). Survives this tool call and your session: if this server dies, the daemon still watches the job's process group. Poll job_status for completion and output.",
+        description: "Run the heavy command you hold a permit for, with full lifecycle ownership: spawns the command in its own process group, atomically associates it with your claimed permit, returns a job_id immediately (background execution — do NOT release the permit merely because this returned), and auto-releases the permit when the job exits (success, failure, or kill). Survives this tool call and your session: if this server dies, the daemon still watches the job's process group. Set wait:true to sleep through execution in this one call (bounded by wait_timeout_ms; returns still_running on timeout — re-call), otherwise sleep via wait_for_completion(job_id) and quick-check via job_status.",
         inputSchema: {
             permit_token: z.string().describe("Permit token from acquire/claim"),
             command: z.string().describe("Shell command to run (the heavy work you acquired the permit for — do not pass unrelated light commands)"),
             cwd: z.string().optional().describe("Working directory (default: this server's cwd)"),
+            wait: z.boolean().optional().describe("true = sleep through execution in this one call: wake promptly when the job finishes (bounded by wait_timeout_ms), returning exit code + output tail"),
+            wait_timeout_ms: z.number().int().optional().describe("Bounded sleep for wait:true (ms); default 600000. Returns still_running (a checkpoint) on timeout — call wait_for_completion again."),
         },
-    }, async (input) => {
+    }, async (input, extra) => {
         const child = spawn(input.command, {
             shell: true,
             detached: true, // own process group => pgid === child.pid on Linux
@@ -277,6 +289,7 @@ Input: request_id (default: your oldest offered, then front-most queued, then ol
             env: process.env,
             stdio: ["ignore", "pipe", "pipe"],
         });
+        let resolveExit;
         const job = {
             id: "job_" + child.pid + "_" + Math.random().toString(36).slice(2, 8),
             child,
@@ -286,6 +299,9 @@ Input: request_id (default: your oldest offered, then front-most queued, then ol
             exited: false,
             exitCode: null,
             output: [],
+            exitPromise: new Promise((resolve) => {
+                resolveExit = resolve;
+            }),
         };
         // Watch for exit BEFORE associating (no awaits in between): a job that
         // exits instantly must not lose its exit event while we round-trip to
@@ -299,22 +315,29 @@ Input: request_id (default: your oldest offered, then front-most queued, then ol
         child.stderr?.on("data", push);
         child.on("exit", (code) => {
             job.exited = true;
+            job.exitedAt = Date.now();
             job.exitCode = code;
             // Auto-release on completion: success, failure, or termination.
-            client
+            // releasePromise is assigned BEFORE resolveExit so a woken waiter
+            // sees the release round-trip in flight (see waitForLocalJob).
+            job.releasePromise = client
                 .request("release", { permitToken: job.permitToken, outcome: code === 0 ? "success" : "failure" })
-                .catch(() => {
+                .then(() => {
+                job.permitReleased = true;
+            }, () => {
                 /* already released/reclaimed — idempotent path */
             });
+            resolveExit(code);
         });
         // Atomic association; if the permit was reclaimed already, kill the job
         // before it can do meaningful work and report the failure.
         try {
-            await client.request("start_job", {
+            const res = await client.request("start_job", {
                 permitToken: input.permit_token,
                 pid: child.pid,
                 pgid: child.pid,
             });
+            job.requestId = res.entry?.requestId;
         }
         catch (err) {
             killProcessGroup(child.pid, "SIGKILL");
@@ -323,12 +346,31 @@ Input: request_id (default: your oldest offered, then front-most queued, then ol
             });
         }
         jobs.set(job.id, job);
+        const note = `Background job started under permit. Do NOT release the permit manually — it auto-releases when the job exits. Sleep through the execution with wait_for_completion(job_id); job_status(job_id) for a quick check; job_stop(job_id) to terminate.`;
+        if (!input.wait) {
+            return json({
+                job_id: job.id,
+                pid: child.pid,
+                pgid: child.pid,
+                state: "running",
+                note,
+            });
+        }
+        // Fire-and-wait: sleep honestly through execution in this one call.
+        const r = await waitForLocalJob(job, { timeoutMs: input.wait_timeout_ms, signal: extra?.signal });
         return json({
             job_id: job.id,
             pid: child.pid,
             pgid: child.pid,
-            state: "running",
-            note: `Background job started under permit. Do NOT release the permit manually — it auto-releases when the job exits. Poll job_status(job_id) for completion; job_stop(job_id) to terminate.`,
+            command: job.command,
+            state: r.state,
+            exit_code: r.exitCode,
+            output_tail: r.outputTail,
+            duration_ms: r.durationMs,
+            permit_released: r.permitReleased,
+            waited_ms: r.waitedMs,
+            next_action: r.nextAction,
+            detail: r.detail,
         });
     });
     server.registerTool("job_status", {
@@ -356,6 +398,7 @@ Input: request_id (default: your oldest offered, then front-most queued, then ol
         if (!job)
             return json({ error: "unknown job_id" });
         if (!job.exited) {
+            job.stopRequested = true;
             killProcessGroup(job.child.pid, "SIGTERM");
             setTimeout(() => {
                 if (!job.exited) {
@@ -365,6 +408,72 @@ Input: request_id (default: your oldest offered, then front-most queued, then ol
         }
         return json({ job_id: job.id, stopping: true });
     });
+    server.registerTool("wait_for_completion", {
+        title: "Sleep until the job finishes",
+        description: `Bounded blocking sleep for the EXECUTION phase — "sleep honestly until my heavy job finishes", replacing sleep-and-poll cycles. Two mechanisms, selected by identifier:
+- job_id of a run_with_permit job (adapter-parented): resolves on the child's exact exit event — no polling, prompt wake, exact exit code + output tail;
+- request_id of any daemon-tracked permit (attach_pid etc.): the daemon holds the wait and wakes it when its liveness sweep observes the process gone (worst-case promptness: one sweep interval, default 5s; the permit is released BEFORE you are woken).
+Returns a STRUCTURED result on every path — never an error for a normal resolution:
+- finished: exit_code, output_tail, duration_ms, permit_released — the work is done, the permit is (being) freed;
+- still_running: timed out mid-execution — a checkpoint; call wait_for_completion again (long jobs = a handful of long sleeps, not a poll loop);
+- timeout: this wait call was aborted/cancelled (harness tool timeout, AbortSignal) — the job is UNTOUCHED; call again;
+- job_unknown: no such job/request, or the permit was reclaimed/expired meanwhile;
+- stopped_by_request: the job/permit was stopped by an explicit admin action.
+Input: job_id OR request_id (one of them), timeout_ms (default 600000, clamped to the machine's maxTurnWaitMs cap for daemon-tracked waits; 0 = check-only). The wait itself holds NO permit and NO capacity. A daemon restart mid-wait is handled transparently (tracked permits survive restarts via the journal); worst case it resolves with job_unknown + re-check instructions.`,
+        inputSchema: {
+            job_id: z.string().optional().describe("A run_with_permit job_id (adapter-parented; exact exit wake)"),
+            request_id: z.string().optional().describe("A daemon-tracked permit's request_id (attach_pid etc.; liveness-sweep wake)"),
+            timeout_ms: z.number().int().optional().describe("Bounded sleep (ms); default 600000. 0 = check-only. still_running on timeout — re-call."),
+            agent_id: z.string().optional().describe("Override agent identity (rarely needed)"),
+        },
+    }, async (input, extra) => {
+        if (!input.job_id && !input.request_id) {
+            return json({
+                state: "job_unknown",
+                waited_ms: 0,
+                next_action: "Pass job_id (a run_with_permit job) or request_id (a daemon-tracked permit).",
+                detail: "no identifier given",
+            });
+        }
+        if (input.job_id && jobs.has(input.job_id)) {
+            const job = jobs.get(input.job_id);
+            const r = await waitForLocalJob(job, { timeoutMs: input.timeout_ms, signal: extra?.signal });
+            return json({
+                state: r.state,
+                job_id: job.id,
+                request_id: job.requestId,
+                exit_code: r.exitCode,
+                output_tail: r.outputTail,
+                duration_ms: r.durationMs,
+                permit_released: r.permitReleased,
+                waited_ms: r.waitedMs,
+                started_at: r.startedAt,
+                next_action: r.nextAction,
+                detail: r.detail,
+            });
+        }
+        // Daemon-tracked permit (request_id), or a job_id from another/previous
+        // server process (unknown here -> falls through to job_unknown).
+        const requestId = input.request_id ?? input.job_id;
+        const r = await waitForTrackedJob({
+            client,
+            requestId,
+            timeoutMs: input.timeout_ms,
+            signal: extra?.signal,
+        });
+        return json({
+            state: r.state,
+            request_id: r.requestId ?? requestId,
+            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,
+            next_action: r.nextAction,
+            detail: r.detail,
+        });
+    });
     // Automatic adapter heartbeat: while this server process lives, untracked
     // permits of this agent keep their lease; if the harness session dies, the
     // lease lapses and the daemon reclaims. The model never has to remember.

package/dist/policy/text.d.ts

@@ -11,7 +11,7 @@
  * Deliberately SHORT (spec: no noisy reminders). The detailed playbook lives
  * in the skill / docs/AGENT_GUIDE.md.
  */
-export declare const POLICY_BRIEF = "# load-lock: machine-wide heavy-work budget\n\nMultiple coding agents share this machine. Before resource-intensive local work\n(builds, test suites, bulky containers, big compiles), get a permit from the\nshared, machine-wide counting semaphore. While queued, keep doing useful light\nwork (reading, editing, searching, planning); you will be offered capacity.\n\nRules:\n1. Heavy vs light: judge by expected CPU/memory/IO cost for the whole machine.\n   A quick lint or single-file check is light. Full builds/tests are heavy.\n   When unsure, call the status tool \u2014 it shows current machine pressure.\n2. Immediately before starting heavy work: acquire a permit\n   (tool: load-lock acquire, CLI: load-lock acquire). Pass a short reason and\n   a stable op_key for the pending operation.\n3. If you are queued: keep working on light tasks. When you receive an offer\n   (in any load-lock tool result or a wakeup message), claim it promptly \u2014\n   offers expire (default 30s) and capacity passes to the next waiter.\n   Out of light work? Sleep honestly with wait_for_turn (MCP/plugin) or\n   'load-lock wait' (CLI) \u2014 a bounded sleep until your turn that\n   auto-claims and holds no capacity.\n4. Start heavy work ONLY after acquire/claim succeeds. Never start heavy work\n   on a \"queued\" result; never treat a notification as authorization.\n5. Hold the permit until the heavy process actually finishes \u2014 including when\n   it runs in the background beyond this tool call or session. Optionally\n   attach its pid (load-lock attach_pid) so a dead process auto-releases.\n6. Release immediately when done (success or failure), and cancel queued\n   requests you no longer need.\n7. Capacity is a cooperative budget, not an enforced one. If the budget seems\n   wrong for this machine, check load-lock inspect_machine (real cores/memory,\n   including container limits) and adjust with configure (explain why). Don't\n   assume N cores = N parallel heavy jobs.\n\nDetailed guide: the \"load-lock\" skill or `load-lock agent-guide`.";
+export declare const POLICY_BRIEF = "# load-lock: machine-wide heavy-work budget\n\nMultiple coding agents share this machine. Before resource-intensive local work\n(builds, test suites, bulky containers, big compiles), get a permit from the\nshared, machine-wide counting semaphore. While queued, keep doing useful light\nwork (reading, editing, searching, planning); you will be offered capacity.\n\nRules:\n1. Heavy vs light: judge by expected CPU/memory/IO cost for the whole machine.\n   A quick lint or single-file check is light. Full builds/tests are heavy.\n   When unsure, call the status tool \u2014 it shows current machine pressure.\n2. Immediately before starting heavy work: acquire a permit\n   (tool: load-lock acquire, CLI: load-lock acquire). Pass a short reason and\n   a stable op_key for the pending operation.\n3. If you are queued: keep working on light tasks. When you receive an offer\n   (in any load-lock tool result or a wakeup message), claim it promptly \u2014\n   offers expire (default 30s) and capacity passes to the next waiter.\n   Out of light work? Sleep honestly with wait_for_turn (MCP/plugin) or\n   'load-lock wait' (CLI) \u2014 a bounded sleep until your turn that\n   auto-claims and holds no capacity.\n4. Start heavy work ONLY after acquire/claim succeeds. Never start heavy work\n   on a \"queued\" result; never treat a notification as authorization.\n5. Hold the permit until the heavy process actually finishes \u2014 including when\n   it runs in the background beyond this tool call or session. Optionally\n   attach its pid (load-lock attach_pid) so a dead process auto-releases.\n   Out of light work while it runs? Sleep honestly with wait_for_completion\n   (MCP/plugin: run_with_permit job_id or tracked request_id; or run_with_permit\n   with wait:true) or 'load-lock wait --job <request-id>' (CLI) \u2014 a bounded\n   sleep that wakes promptly when the job finishes (exit code + output tail;\n   the permit is freed before you are woken). On still_running it is a\n   checkpoint: call again. Do NOT guess sleeps or poll job_status in a loop.\n6. Release immediately when done (success or failure), and cancel queued\n   requests you no longer need.\n7. Capacity is a cooperative budget, not an enforced one. If the budget seems\n   wrong for this machine, check load-lock inspect_machine (real cores/memory,\n   including container limits) and adjust with configure (explain why). Don't\n   assume N cores = N parallel heavy jobs.\n\nDetailed guide: the \"load-lock\" skill or `load-lock agent-guide`.";
 export declare function policyWithContext(statusSummary: string, configSummary?: string): string;
 export declare function statusLine(st: {
     pools: {

package/dist/policy/text.js

@@ -36,6 +36,12 @@ Rules:
 5. Hold the permit until the heavy process actually finishes — including when
    it runs in the background beyond this tool call or session. Optionally
    attach its pid (load-lock attach_pid) so a dead process auto-releases.
+   Out of light work while it runs? Sleep honestly with wait_for_completion
+   (MCP/plugin: run_with_permit job_id or tracked request_id; or run_with_permit
+   with wait:true) or 'load-lock wait --job <request-id>' (CLI) — a bounded
+   sleep that wakes promptly when the job finishes (exit code + output tail;
+   the permit is freed before you are woken). On still_running it is a
+   checkpoint: call again. Do NOT guess sleeps or poll job_status in a loop.
 6. Release immediately when done (success or failure), and cancel queued
    requests you no longer need.
 7. Capacity is a cooperative budget, not an enforced one. If the budget seems

package/dist/shared/client.js

@@ -30,6 +30,7 @@ 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";
+import { resolveDaemonEntry } from "./installs.js";
 export class LLClient {
     sock = null;
     nextId = 1;
@@ -230,7 +231,12 @@ function daemonMainPath() {
     if (process.env.LOAD_LOCK_DAEMON_BIN)
         return process.env.LOAD_LOCK_DAEMON_BIN;
     const here = dirname(fileURLToPath(import.meta.url)); // .../dist/shared
-    return join(here, "..", "core", "daemon-main.js");
+    const own = join(here, "..", "core", "daemon-main.js");
+    // Issue #39: a harness (e.g. opencode's timestamped plugin cache) may
+    // prune this copy's directory while a session still executes it from
+    // memory — resolve to the PATH-installed CLI's daemon entry instead of
+    // spawning an ENOENT forever.
+    return resolveDaemonEntry(own);
 }
 /** Idempotently ensure a daemon is running and listening on `sockPath`. */
 export async function ensureDaemon(stateDir, sockPath) {
@@ -274,6 +280,10 @@ export async function ensureDaemon(stateDir, sockPath) {
                     stdio: "ignore",
                     env: { ...process.env, LOAD_LOCK_DAEMON_SPAWNED: "1" },
                 });
+                // Issue #39: an unreadable/vanished entry must surface as the
+                // "did not come up" probe failure below, not crash the host process
+                // with an uncaught ENOENT 'error' event.
+                child.on("error", () => { });
                 child.unref();
             }
         }

package/dist/shared/drift.d.ts

@@ -0,0 +1,21 @@
+export interface CliDrift {
+    /** Version of this (adapter) copy — the newer one. */
+    ownVersion: string;
+    /** Version of the PATH-resolved `load-lock` CLI copy — the older one. */
+    cliVersion: string;
+    /** Package root of the PATH-resolved CLI copy. */
+    cliPath: string;
+    /** The one clear notice, with the exact command. */
+    message: string;
+}
+/** The notice text (exported for tests and doc-sync checks). */
+export declare function driftMessage(ownVersion: string, cliVersion: string): string;
+/**
+ * Compare `ownVersion` (this adapter copy) with the version of the
+ * `load-lock` binary that PATH resolves to, by reading that copy's
+ * package.json — never by spawning the old CLI, which may predate any
+ * introspection. Returns a drift notice when the PATH CLI is strictly
+ * older; null when it is the same or newer, absent, or unreadable.
+ * Best-effort: never throws.
+ */
+export declare function detectCliDrift(ownVersion: string, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): CliDrift | null;

package/dist/shared/drift.js

@@ -0,0 +1,77 @@
+/**
+ * Adapter-init drift notice (issue #38): when a harness adapter copy NEWER
+ * than the PATH-installed `load-lock` CLI initializes — typically because
+ * opencode refreshed its private cache copy — surface ONE clear notice
+ * naming the exact command (`load-lock update`).
+ *
+ * Notify-first, NEVER auto-install: spawning a package manager from inside
+ * a harness plugin needs explicit opt-in; the default is to tell the
+ * agent/user, who can run `load-lock update` as an ordinary command or
+ * tool call.
+ *
+ * Honest limitation (documented in docs/OPERATIONS.md): a harness session
+ * that was already running keeps the OLD adapter code in memory until the
+ * harness restarts — this notice is emitted by the NEW copy at its init,
+ * which is the best it can do for sessions started before the refresh.
+ *
+ * Pure and synchronous (PATH scan + package.json reads only) so both the
+ * OpenCode plugin setup and the MCP server startup can call it inline.
+ */
+import { existsSync, realpathSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { isWindows } from "./transport.js";
+import { enclosingPackage, PKG_NAME } from "./pkginfo.js";
+import { compareVersions } from "./version.js";
+/** The notice text (exported for tests and doc-sync checks). */
+export function driftMessage(ownVersion, cliVersion) {
+    return (`load-lock: this load-lock adapter copy (v${ownVersion}) is newer than the installed CLI (v${cliVersion}). ` +
+        `Run \`load-lock update\` to update the CLI on PATH and restart the daemon. ` +
+        `(Notify only — nothing is auto-installed; if your CLI predates the \`update\` command, run ` +
+        `\`npm i -g ${PKG_NAME}@latest\` instead.)`);
+}
+/**
+ * Compare `ownVersion` (this adapter copy) with the version of the
+ * `load-lock` binary that PATH resolves to, by reading that copy's
+ * package.json — never by spawning the old CLI, which may predate any
+ * introspection. Returns a drift notice when the PATH CLI is strictly
+ * older; null when it is the same or newer, absent, or unreadable.
+ * Best-effort: never throws.
+ */
+export function detectCliDrift(ownVersion, env = process.env, platform = process.platform) {
+    try {
+        const sep = isWindows(platform) ? ";" : ":";
+        const binNames = isWindows(platform) ? ["load-lock.cmd", "load-lock.exe", "load-lock"] : ["load-lock"];
+        const dirs = (env.PATH ?? "").split(sep).filter(Boolean);
+        for (const dir of dirs) {
+            for (const bin of binNames) {
+                const binPath = join(dir, bin);
+                if (!existsSync(binPath) || !statSync(binPath).isFile())
+                    continue;
+                // Resolve through symlinks/shims to the copy that owns the bin.
+                let realBin;
+                try {
+                    realBin = realpathSync(binPath);
+                }
+                catch {
+                    realBin = binPath;
+                }
+                const found = enclosingPackage(dirname(realBin)) ?? enclosingPackage(dir);
+                if (!found || found.version === null)
+                    return null; // first PATH hit wins; cannot compare honestly
+                if (compareVersions(found.version, ownVersion) < 0) {
+                    return {
+                        ownVersion,
+                        cliVersion: found.version,
+                        cliPath: found.path,
+                        message: driftMessage(ownVersion, found.version),
+                    };
+                }
+                return null; // PATH CLI is same/newer — no drift
+            }
+        }
+    }
+    catch {
+        /* best-effort: unreadable PATH entries are skipped, never fatal */
+    }
+    return null; // no load-lock on PATH — nothing to compare against
+}

package/dist/shared/installs.d.ts

@@ -0,0 +1,39 @@
+/** All `load-lock` binaries found on PATH, in PATH order (files only). */
+export declare function pathBinCandidates(platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): string[];
+export interface PathInstall {
+    /** Package root of the install (the directory containing package.json). */
+    path: string;
+    /** Version from that package.json, or null when unreadable. */
+    version: string | null;
+}
+/**
+ * The FIRST PATH-resolved `load-lock`'s enclosing install. Symlinks are
+ * resolved (npm/bun global layouts symlink the bin into the install), and a
+ * plain shim script falls back to the PATH directory itself.
+ */
+export declare function pathInstall(platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): PathInstall | null;
+export interface InstallDrift {
+    /** Version of THIS running copy (src/shared/version.ts, cached). */
+    ownVersion: string;
+    /** Version of the PATH-resolved CLI install, or null when unresolvable. */
+    pathVersion: string | null;
+    /** True when the PATH install is strictly newer than this running copy. */
+    stale: boolean;
+}
+/**
+ * In-memory staleness probe (issue #39): a harness that loads plugin code
+ * once at startup (opencode never hot-reloads plugins) keeps executing the
+ * old copy after `npm i -g @aron98/load-lock@latest` — this detects exactly
+ * that: the running copy vs. what the PATH `load-lock` resolves to.
+ */
+export declare function detectInstallDrift(platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): InstallDrift;
+/**
+ * Daemon entry to auto-spawn (issue #39, hypothesis 2): normally the running
+ * copy's own dist/core/daemon-main.js. When that file has vanished — a
+ * harness may prune its old plugin-cache timestamped dir while a session
+ * still runs that copy in memory — spawn from the PATH-installed CLI's copy
+ * instead, which is what the user most recently installed. If nothing on
+ * PATH resolves either, the own path is returned unchanged so the spawn
+ * fails with the original error rather than a misleading one.
+ */
+export declare function resolveDaemonEntry(ownEntry: string, platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): string;

package/dist/shared/installs.js

@@ -0,0 +1,101 @@
+/**
+ * Shared install-location helpers (issue #39): resolving the PATH-installed
+ * copy of the CLI, detecting version drift between the running copy and that
+ * install, and finding a usable daemon entry when the running copy's own
+ * entry has vanished (e.g. a harness pruned an old plugin-cache copy while a
+ * session still executes it from memory).
+ *
+ * `enclosingPackage` / `PKG_NAME` live in `./pkginfo.js` (shipped by #38's
+ * adapter-init drift notice) and are reused here; this module adds the
+ * PATH-install scan and the two #39-specific probes on top of them:
+ * `detectInstallDrift` (running copy OLDER than the PATH CLI — the mirror
+ * image of pkginfo-neighbor `drift.ts`'s `detectCliDrift`, which flags the
+ * PATH CLI being older) and `resolveDaemonEntry` (spawn fallback when this
+ * copy's own entry has vanished).
+ *
+ * Everything here is best-effort and never throws: missing paths, unreadable
+ * files, and unexpected layouts yield null / false / the input unchanged.
+ */
+import { existsSync, realpathSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { isWindows } from "./transport.js";
+import { compareVersions, packageVersion } from "./version.js";
+import { enclosingPackage } from "./pkginfo.js";
+/** All `load-lock` binaries found on PATH, in PATH order (files only). */
+export function pathBinCandidates(platform = process.platform, env = process.env) {
+    const binNames = isWindows(platform) ? ["load-lock.cmd", "load-lock.exe", "load-lock"] : ["load-lock"];
+    const sep = isWindows(platform) ? ";" : ":";
+    const out = [];
+    for (const dir of (env.PATH ?? "").split(sep).filter(Boolean)) {
+        for (const bin of binNames) {
+            try {
+                const binPath = join(dir, bin);
+                if (statSync(binPath).isFile())
+                    out.push(binPath);
+            }
+            catch {
+                /* unreadable PATH entry — skip */
+            }
+        }
+    }
+    return out;
+}
+/**
+ * The FIRST PATH-resolved `load-lock`'s enclosing install. Symlinks are
+ * resolved (npm/bun global layouts symlink the bin into the install), and a
+ * plain shim script falls back to the PATH directory itself.
+ */
+export function pathInstall(platform = process.platform, env = process.env) {
+    for (const binPath of pathBinCandidates(platform, env)) {
+        let realBin = binPath;
+        try {
+            realBin = realpathSync(binPath);
+        }
+        catch {
+            /* keep the raw path */
+        }
+        // A shim/wrapper script is not itself the copy — resolve through its
+        // enclosing package, falling back to the PATH dir (same logic the
+        // doctor's multi-copy scan uses).
+        const found = enclosingPackage(dirname(realBin)) ?? enclosingPackage(dirname(binPath));
+        if (found)
+            return { path: found.path, version: found.version };
+    }
+    return null;
+}
+/**
+ * In-memory staleness probe (issue #39): a harness that loads plugin code
+ * once at startup (opencode never hot-reloads plugins) keeps executing the
+ * old copy after `npm i -g @aron98/load-lock@latest` — this detects exactly
+ * that: the running copy vs. what the PATH `load-lock` resolves to.
+ */
+export function detectInstallDrift(platform = process.platform, env = process.env) {
+    const ownVersion = packageVersion();
+    const inst = pathInstall(platform, env);
+    const pathVersion = inst?.version ?? null;
+    return {
+        ownVersion,
+        pathVersion,
+        stale: pathVersion != null && compareVersions(pathVersion, ownVersion) > 0,
+    };
+}
+/**
+ * Daemon entry to auto-spawn (issue #39, hypothesis 2): normally the running
+ * copy's own dist/core/daemon-main.js. When that file has vanished — a
+ * harness may prune its old plugin-cache timestamped dir while a session
+ * still runs that copy in memory — spawn from the PATH-installed CLI's copy
+ * instead, which is what the user most recently installed. If nothing on
+ * PATH resolves either, the own path is returned unchanged so the spawn
+ * fails with the original error rather than a misleading one.
+ */
+export function resolveDaemonEntry(ownEntry, platform = process.platform, env = process.env) {
+    if (existsSync(ownEntry))
+        return ownEntry;
+    const inst = pathInstall(platform, env);
+    if (inst) {
+        const candidate = join(inst.path, "dist", "core", "daemon-main.js");
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return ownEntry;
+}

package/dist/shared/pkginfo.d.ts

@@ -0,0 +1,16 @@
+/** Package name of this package (used to find enclosing package roots). */
+export declare const PKG_NAME = "@aron98/load-lock";
+export interface PkgRootInfo {
+    /** Package root (the directory holding the matching package.json). */
+    path: string;
+    /** Version string, or null when the package.json has no/invalid version. */
+    version: string | null;
+}
+/**
+ * Find the package.json of the @aron98/load-lock copy that contains the
+ * given file, by climbing parent directories. Best-effort: returns null if
+ * no enclosing package.json matches (or is readable).
+ */
+export declare function enclosingPackage(startDir: string, maxDepth?: number): PkgRootInfo | null;
+/** Cache root the way opencode resolves it (its npm cache lives under it). */
+export declare function opencodeCacheRoot(platform: NodeJS.Platform, env: NodeJS.ProcessEnv): string | null;

package/dist/shared/pkginfo.js

@@ -0,0 +1,54 @@
+/**
+ * Package-identity plumbing shared by copy detection (cli/copies.ts), the
+ * update command (cli/update.ts), and the adapter drift notice
+ * (shared/drift.ts): the package name and the "which package root
+ * contains this file" climb.
+ *
+ * Pure functions of their arguments (no process.env / import.meta at call
+ * time beyond what callers pass in) so tests can plant layouts.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+/** Package name of this package (used to find enclosing package roots). */
+export const PKG_NAME = "@aron98/load-lock";
+/**
+ * Find the package.json of the @aron98/load-lock copy that contains the
+ * given file, by climbing parent directories. Best-effort: returns null if
+ * no enclosing package.json matches (or is readable).
+ */
+export function enclosingPackage(startDir, maxDepth = 12) {
+    let dir = startDir;
+    for (let i = 0; i < maxDepth; i++) {
+        const pkgPath = join(dir, "package.json");
+        try {
+            if (existsSync(pkgPath)) {
+                const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+                if (pkg?.name === PKG_NAME) {
+                    return { path: dir, version: typeof pkg.version === "string" ? pkg.version : null };
+                }
+                // A foreign package.json terminates the climb (e.g. a PATH bin
+                // inside some other tool's package).
+                return null;
+            }
+        }
+        catch {
+            return null;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+    return null;
+}
+/** Cache root the way opencode resolves it (its npm cache lives under it). */
+export function opencodeCacheRoot(platform, env) {
+    if (env.XDG_CACHE_HOME)
+        return env.XDG_CACHE_HOME;
+    if (platform === "win32")
+        return env.LOCALAPPDATA ?? null;
+    if (platform === "darwin")
+        return join(env.HOME ?? homedir(), "Library", "Caches");
+    return join(env.HOME ?? homedir(), ".cache");
+}

package/dist/shared/protocol.d.ts

@@ -130,6 +130,8 @@ export interface EntrySnapshot {
     leaseDeadline?: number;
     lastSeen?: number;
     heldFor?: number;
+    /** When execution started (start_job / mark_started), epoch ms. Absent before that. */
+    startedAt?: number;
 }
 /** Owner-scoped snapshot: includes tokens. Never returned to non-owners. */
 export interface OwnerEntrySnapshot extends EntrySnapshot {
@@ -394,6 +396,36 @@ export interface WaitForTurnResult {
     nextAction: string;
     detail?: string;
 }
+export type WaitForCompletionState = "finished" | "still_running" | "timeout" | "job_unknown" | "stopped_by_request";
+export interface WaitForCompletionParams {
+    /** Request id whose tracked job to wait for. */
+    requestId: string;
+    /** Bounded wait budget for this call, ms. 0 = check-only (immediate return). */
+    timeoutMs?: number;
+}
+export interface WaitForCompletionResult {
+    state: WaitForCompletionState;
+    /** The job id (adapter-parented run_with_permit job). */
+    jobId?: string;
+    /** The request/permit id whose job was waited on. */
+    requestId?: string;
+    /** Adapter-parented jobs only: the child's exit code. */
+    exitCode?: number | null;
+    /** Adapter-parented jobs only: last lines of combined output. */
+    outputTail?: string;
+    /** Wall time from execution start to job end (ms). */
+    durationMs?: number;
+    /** True when the daemon confirms the permit is no longer held. */
+    permitReleased?: boolean;
+    /** How long the wait actually ran before resolving (ms). */
+    waitedMs: number;
+    /** The clamped budget actually applied, when it differed from the requested one. */
+    effectiveWaitMs?: number;
+    /** When execution started, when known (epoch ms). */
+    startedAt?: number;
+    nextAction: string;
+    detail?: string;
+}
 /** Recovery diagnostics: held permits with holder + job information. */
 export interface HolderDiag {
     entry: EntrySnapshot;