@aron98/load-lock 1.2.1 → 1.4.0

package/dist/adapters/opencode/plugin.d.ts

@@ -4,7 +4,8 @@
  * Installed to ~/.config/opencode/plugins/load-lock/ (see cli/install.ts).
  * Provides:
  *  - native tools in the `load_lock` namespace (acquire/claim/release/...)
- *  - run_with_permit / job_status / job_stop: full execution lifecycle
+ *  - run_with_permit / job_status / job_stop / wait_for_completion:
+ *    full execution lifecycle incl. honest execution-phase sleeping
  *  - automatic policy injection on every model call via the session
  *    "context" hook (compaction-proof by construction)
  *  - idle wakeup: daemon watch -> ctx.session.synthetic when an offer

package/dist/adapters/opencode/plugin.js

@@ -4,7 +4,8 @@
  * Installed to ~/.config/opencode/plugins/load-lock/ (see cli/install.ts).
  * Provides:
  *  - native tools in the `load_lock` namespace (acquire/claim/release/...)
- *  - run_with_permit / job_status / job_stop: full execution lifecycle
+ *  - run_with_permit / job_status / job_stop / wait_for_completion:
+ *    full execution lifecycle incl. honest execution-phase sleeping
  *  - automatic policy injection on every model call via the session
  *    "context" hook (compaction-proof by construction)
  *  - idle wakeup: daemon watch -> ctx.session.synthetic when an offer
@@ -21,6 +22,7 @@ import path from "node:path";
 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";
 const client = new LLClient();
 const knownSessions = new Set();
@@ -156,10 +158,12 @@ export default Plugin.define({
                 reason: input.reason,
                 author: "opencode:" + context.sessionID,
             }));
-            add("run_with_permit", "Run the heavy command you hold a permit for, with full lifecycle ownership: spawns it in its own process group, atomically associates it with the permit, returns a job_id immediately (background), and auto-releases the permit when the job exits. Do NOT release manually for these jobs. Poll job_status.", {
+            add("run_with_permit", "Run the heavy command you hold a permit for, with full lifecycle ownership: spawns it in its own process group, atomically associates it with the permit, returns a job_id immediately (background), and auto-releases the permit when the job exits. Do NOT release manually for these jobs. Set wait:true to sleep through execution in this one call; otherwise sleep via wait_for_completion(job_id), quick-check via job_status.", {
                 permit_token: { type: "string" },
                 command: { type: "string", description: "The heavy shell command (not unrelated light commands)" },
                 cwd: { type: "string" },
+                wait: { type: "boolean", description: "true = sleep through execution in this one call; wake promptly when the job finishes (bounded by wait_timeout_ms)" },
+                wait_timeout_ms: { type: "number", description: "Bounded sleep for wait:true (ms, default 600000); still_running checkpoint on timeout" },
             }, async (input, context) => {
                 const child = spawn(input.command, {
                     shell: true,
@@ -168,15 +172,20 @@ export default Plugin.define({
                     env: process.env,
                     stdio: ["ignore", "pipe", "pipe"],
                 });
+                let resolveExit;
                 const job = {
                     id: "job_" + child.pid + "_" + Math.random().toString(36).slice(2, 8),
                     child,
                     permitToken: input.permit_token,
                     command: input.command,
                     sessionID: context.sessionID,
+                    startedAt: Date.now(),
                     exited: false,
                     exitCode: null,
                     output: [],
+                    exitPromise: new Promise((resolve) => {
+                        resolveExit = resolve;
+                    }),
                 };
                 const push = (b) => {
                     job.output.push(b.toString("utf8"));
@@ -190,18 +199,43 @@ export default Plugin.define({
                 // round-trip to the daemon, or the permit would never auto-release.
                 child.on("exit", (code) => {
                     job.exited = true;
+                    job.exitedAt = Date.now();
                     job.exitCode = code;
-                    void client.request("release", { permitToken: job.permitToken, outcome: code === 0 ? "success" : "failure" }).catch(() => { });
+                    // 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" })
+                        .then(() => {
+                        job.permitReleased = true;
+                    }, () => { });
+                    resolveExit(code);
                 });
                 try {
-                    await client.request("start_job", { permitToken: input.permit_token, pid: child.pid, pgid: child.pid });
+                    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");
                     return { error: `permit no longer startable (${err.message}); job killed before doing work; acquire again` };
                 }
                 jobs.set(job.id, job);
-                return { job_id: job.id, pid: child.pid, state: "running", note: "auto-releases when the job exits; poll job_status" };
+                if (!input.wait) {
+                    return { job_id: job.id, pid: child.pid, state: "running", note: "auto-releases when the job exits; sleep via wait_for_completion(job_id), quick-check via job_status" };
+                }
+                const r = await waitForLocalJob(job, { timeoutMs: input.wait_timeout_ms, signal: context.signal });
+                return {
+                    job_id: job.id,
+                    pid: child.pid,
+                    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,
+                };
             });
             add("job_status", "Poll a run_with_permit job: running/exited, exit code, output tail.", { job_id: { type: "string" } }, (input) => {
                 const job = jobs.get(input.job_id);
@@ -220,6 +254,7 @@ export default Plugin.define({
                 if (!job)
                     return { error: "unknown job_id" };
                 if (!job.exited) {
+                    job.stopRequested = true;
                     killProcessGroup(job.child.pid, "SIGTERM");
                     setTimeout(() => {
                         if (!job.exited) {
@@ -229,6 +264,51 @@ export default Plugin.define({
                 }
                 return { job_id: job.id, stopping: true };
             });
+            add("wait_for_completion", "Sleep honestly through the EXECUTION phase (replaces sleep-and-poll): bounded blocking wait that wakes promptly when the heavy job finishes. Pass job_id (run_with_permit job; exact exit-code wake) or request_id (daemon-tracked permit; liveness-sweep wake, permit released before you are woken). Structured result on every path: finished (exit_code/output_tail/duration/permit_released), still_running (checkpoint — call again), timeout (wait aborted, job untouched), job_unknown, stopped_by_request. timeout_ms bounds one call (default 600000; 0 = check-only).", {
+                job_id: { type: "string", description: "A run_with_permit job_id" },
+                request_id: { type: "string", description: "A daemon-tracked permit's request_id" },
+                timeout_ms: { type: "number", description: "Bounded sleep (ms, default 600000); still_running checkpoint on timeout — re-call" },
+            }, async (input, context) => {
+                if (!input.job_id && !input.request_id) {
+                    return {
+                        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: context.signal });
+                    return {
+                        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,
+                    };
+                }
+                const requestId = input.request_id ?? input.job_id;
+                const r = await waitForTrackedJob({ client, requestId, timeoutMs: input.timeout_ms, signal: context.signal });
+                return {
+                    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,
+                };
+            });
             add("attach_pid", "Associate a process you already started (e.g. a background shell task) with your claimed permit. Atomic; auto-releases when the process group exits.", { permit_token: { type: "string" }, pid: { type: "number" } }, (input) => client.request("attach_pid", { permitToken: input.permit_token, pid: input.pid }));
             add("mark_started", "Tell load-lock you started the work when no process can be associated. Weaker guarantee: heartbeat lease applies (see docs). Prefer run_with_permit.", { permit_token: { type: "string" } }, (input) => client.request("mark_started", { permitToken: input.permit_token }));
         });

package/dist/adapters/opencode/tui.js

@@ -89,13 +89,17 @@ function dashboardLines(v, width, f) {
     const syncAge = v.lastSyncAt ? fmtDuration(Math.max(0, v.now - v.lastSyncAt)) : "never";
     push(`load-lock dashboard   ${STATE_LABEL[v.state] ?? v.state}   synced ${syncAge} ago`, stateColor(v.state, f));
     if (v.daemon) {
-        push(`daemon pid ${v.daemon.pid} · uptime ${fmtDuration(v.daemon.uptimeMs)} · config v${v.daemon.configVersion} · protocol v${v.daemon.protocolVersion} · events through #${v.latestEventId}`, f.dim);
+        push(`daemon pid ${v.daemon.pid} · uptime ${fmtDuration(v.daemon.uptimeMs)} · config v${v.daemon.configVersion} · protocol v${v.daemon.protocolVersion}` +
+            (v.daemon.daemonVersion ? ` · daemon v${v.daemon.daemonVersion}` : "") +
+            ` · events through #${v.latestEventId}`, f.dim);
     }
     else {
         push(`daemon unreachable — it auto-spawns on the next load-lock command`, f.dim);
     }
     if (v.daemonRestartNote)
         push(`note: ${v.daemonRestartNote}`, f.warn);
+    if (v.versionSkewNote)
+        push(`note: ${v.versionSkewNote}`, f.warn);
     if (v.machine) {
         const m = v.machine;
         const cg = m.cgroupCpuQuota != null ? ` · cgroup quota ${m.cgroupCpuQuota / 100} CPU` : "";

package/dist/cli/copies.d.ts

@@ -0,0 +1,28 @@
+export interface InstalledCopy {
+    /** Where this copy was found. */
+    source: "cli" | "path" | "opencode-cache";
+    /** Path of the copy's package root (its package.json's directory). */
+    path: string;
+    /** Version string, or null when the package.json could not be read. */
+    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): {
+    path: string;
+    version: string | null;
+} | null;
+/** The copy of load-lock this process runs from (its own package root). */
+export declare function thisCopy(): InstalledCopy | null;
+/**
+ * All installed copies of load-lock detectable on this machine:
+ *  - "cli": the copy this process runs from.
+ *  - "path": any `load-lock` binary found on PATH (deduped by real path,
+ *    so a symlink to the running copy is recognized and not double-listed
+ *    — a copy is only listed under "path" when it differs from "cli").
+ *  - "opencode-cache": copies under opencode's private npm cache.
+ */
+export declare function findInstalledCopies(platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): InstalledCopy[];

package/dist/cli/copies.js

@@ -0,0 +1,207 @@
+/**
+ * Installed-copy detection (issue #34): on a given machine several copies
+ * of load-lock commonly coexist — the globally-installed CLI on PATH, and
+ * the private copy opencode maintains under its npm cache (because
+ * `install --harness opencode` registers the bare package name, opencode
+ * installs and refreshes its own copy on its own schedule).
+ *
+ * All scanning is best-effort: missing paths, unreadable files, and
+ * unexpected layouts yield skipped entries or null versions — never a throw.
+ */
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { isWindows } from "../shared/transport.js";
+/** Package name of this package (used to find enclosing package roots). */
+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;
+}
+/** The copy of load-lock this process runs from (its own package root). */
+export function thisCopy() {
+    // dist/cli/copies.js -> dist/cli -> ... -> <pkg>/package.json
+    const startDir = dirname(dirname(fileURLToPath(import.meta.url)));
+    const found = enclosingPackage(startDir);
+    if (!found)
+        return null;
+    return { source: "cli", path: found.path, version: found.version };
+}
+/**
+ * All installed copies of load-lock detectable on this machine:
+ *  - "cli": the copy this process runs from.
+ *  - "path": any `load-lock` binary found on PATH (deduped by real path,
+ *    so a symlink to the running copy is recognized and not double-listed
+ *    — a copy is only listed under "path" when it differs from "cli").
+ *  - "opencode-cache": copies under opencode's private npm cache.
+ */
+export function findInstalledCopies(platform = process.platform, env = process.env) {
+    const copies = [];
+    const seen = new Set();
+    const add = (c) => {
+        if (!c)
+            return;
+        let real;
+        try {
+            real = realpathSync(c.path);
+        }
+        catch {
+            real = c.path;
+        }
+        if (seen.has(real))
+            return;
+        seen.add(real);
+        copies.push(c);
+    };
+    add(thisCopy());
+    // --- PATH scan ------------------------------------------------------------
+    try {
+        const binNames = isWindows(platform)
+            ? ["load-lock.cmd", "load-lock.exe", "load-lock"]
+            : ["load-lock"];
+        const dirs = (env.PATH ?? "").split(isWindows(platform) ? ";" : ":").filter(Boolean);
+        for (const dir of dirs) {
+            for (const bin of binNames) {
+                try {
+                    const binPath = join(dir, bin);
+                    if (!statSync(binPath).isFile())
+                        continue;
+                    // A shim/wrapper script is not itself the copy — resolve through
+                    // its enclosing package (works for npm/bun global layouts where
+                    // the bin sits in <pkg>/bin or node_modules/.bin via a symlink).
+                    let realBin;
+                    try {
+                        realBin = realpathSync(binPath);
+                    }
+                    catch {
+                        realBin = binPath;
+                    }
+                    const found = enclosingPackage(dirname(realBin)) ?? enclosingPackage(dir);
+                    if (found)
+                        add({ source: "path", path: found.path, version: found.version });
+                }
+                catch {
+                    /* unreadable PATH entry — skip */
+                }
+            }
+        }
+    }
+    catch {
+        /* PATH scan is best-effort */
+    }
+    // --- opencode npm-cache scan ----------------------------------------------
+    // Layout (verified live): <cacheRoot>/opencode/npm/@aron98/load-lock@latest/<ts>/
+    // where "@aron98" and "load-lock@latest" are two nested directories (a
+    // normal npm scoped layout); URL-escaped single-directory variants like
+    // "@aron98%2Fload-lock@latest" also occur. Under each <ts>: either the
+    // real package at node_modules/@aron98/load-lock, or a top-level
+    // package.json (npm-install root).
+    try {
+        const cacheRoot = opencodeCacheRoot(platform, env);
+        if (cacheRoot) {
+            const npmDir = join(cacheRoot, "opencode", "npm");
+            if (existsSync(npmDir)) {
+                const scanTimestampDirs = (pkgBase) => {
+                    let tsDirs = [];
+                    try {
+                        tsDirs = readdirSync(pkgBase).filter((d) => statSync(join(pkgBase, d)).isDirectory());
+                    }
+                    catch {
+                        return;
+                    }
+                    for (const ts of tsDirs) {
+                        const nested = join(pkgBase, ts, "node_modules", "@aron98", "load-lock");
+                        const topLevel = join(pkgBase, ts);
+                        for (const cand of [nested, topLevel]) {
+                            try {
+                                const pkgPath = join(cand, "package.json");
+                                if (!existsSync(pkgPath))
+                                    continue;
+                                const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+                                if (pkg?.name !== PKG_NAME)
+                                    continue;
+                                add({
+                                    source: "opencode-cache",
+                                    path: cand,
+                                    version: typeof pkg.version === "string" ? pkg.version : null,
+                                });
+                                break;
+                            }
+                            catch {
+                                /* skip unreadable timestamp dir */
+                            }
+                        }
+                    }
+                };
+                let scopeDirs = [];
+                try {
+                    scopeDirs = readdirSync(npmDir).filter((d) => statSync(join(npmDir, d)).isDirectory());
+                }
+                catch {
+                    scopeDirs = [];
+                }
+                for (const scopeDir of scopeDirs) {
+                    if (scopeDir.startsWith("@aron98%2Fload-lock")) {
+                        // URL-escaped single-directory form.
+                        scanTimestampDirs(join(npmDir, scopeDir));
+                    }
+                    else if (scopeDir === "@aron98") {
+                        // Scoped layout: @aron98/<name>@<version-range>/<ts>/...
+                        let inner = [];
+                        try {
+                            inner = readdirSync(join(npmDir, scopeDir)).filter((d) => statSync(join(npmDir, scopeDir, d)).isDirectory());
+                        }
+                        catch {
+                            continue;
+                        }
+                        for (const nameDir of inner) {
+                            if (nameDir.startsWith("load-lock"))
+                                scanTimestampDirs(join(npmDir, scopeDir, nameDir));
+                        }
+                    }
+                }
+            }
+        }
+    }
+    catch {
+        /* cache scan is best-effort */
+    }
+    return copies;
+}
+/** Cache root the way opencode resolves it (its npm cache lives under it). */
+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");
+}