@aron98/load-lock 1.3.0 → 1.5.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,7 +22,10 @@ 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";
+import { detectCliDrift } from "../../shared/drift.js";
+import { packageVersion } from "../../shared/version.js";
 const client = new LLClient();
 const knownSessions = new Set();
 const jobs = new Map();
@@ -42,6 +46,18 @@ function toolContent(v) {
 export default Plugin.define({
     id: "load-lock",
     setup(ctx) {
+        // Drift notice (issue #38): when this adapter copy is NEWER than the
+        // `load-lock` CLI that PATH resolves to (opencode refreshed its cache
+        // copy but the global install was never updated), surface one clear
+        // notice naming the exact command — on stderr at init, and once in the
+        // injected context. Notify only: nothing is ever auto-installed. Note
+        // the honest limitation (docs/OPERATIONS.md): a harness session that
+        // was already running keeps the OLD adapter code in memory until the
+        // harness itself restarts — this fires from the NEW copy at its init.
+        const cliDrift = detectCliDrift(packageVersion());
+        if (cliDrift)
+            process.stderr.write(cliDrift.message + "\n");
+        const DRIFT_NOTE = cliDrift ? "\n\n" + cliDrift.message : "";
         // ------------------------------------------------------------- tools
         ctx.tool.transform((editor) => {
             editor.namespace({
@@ -156,10 +172,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 +186,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 +213,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 +268,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,12 +278,57 @@ 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 }));
         });
         // ------------------------------------------- policy on every model call
         void ctx.session.hook("context", async (event) => {
-            event.system.push({ type: "text", text: POLICY_BRIEF + "\n\n" + (await statusBrief()) });
+            event.system.push({ type: "text", text: POLICY_BRIEF + "\n\n" + (await statusBrief()) + DRIFT_NOTE });
         });
         // -------------------------------------------------- idle wakeup via watch
         void (async () => {

package/dist/adapters/opencode/tui.js

@@ -100,6 +100,8 @@ function dashboardLines(v, width, f) {
         push(`note: ${v.daemonRestartNote}`, f.warn);
     if (v.versionSkewNote)
         push(`note: ${v.versionSkewNote}`, f.warn);
+    if (v.installDriftNote)
+        push(`note: ${v.installDriftNote}`, f.warn);
     if (v.machine) {
         const m = v.machine;
         const cg = m.cgroupCpuQuota != null ? ` · cgroup quota ${m.cgroupCpuQuota / 100} CPU` : "";
@@ -209,11 +211,14 @@ export default Plugin.define({
     id: "load-lock.tui",
     setup(ctx) {
         const [view, setView] = createSignal(null);
-        const feed = new DashboardFeed(new LLClient());
+        // driftSurface "opencode": when this session's copy is older than the
+        // PATH CLI, the hint says to restart opencode (plugins never hot-reload).
+        const feed = new DashboardFeed(new LLClient(), { driftSurface: "opencode" });
         feed.onChange = () => setView(feed.view());
         feed.onState = () => setView(feed.view());
         void feed.start().catch(() => {
-            /* daemon down or spawning; the feed keeps retrying and will go live */
+            /* daemon down or spawning; the reconnect loop keeps retrying and
+               will go live — start() only reports the FIRST connect failure */
         });
         // Local countdown tick: produces a fresh snapshot once per second so
         // ages/deadlines advance even between daemon events.

package/dist/cli/copies.d.ts

@@ -1,3 +1,4 @@
+export { enclosingPackage, opencodeCacheRoot } from "../shared/pkginfo.js";
 export interface InstalledCopy {
     /** Where this copy was found. */
     source: "cli" | "path" | "opencode-cache";
@@ -6,15 +7,6 @@ export interface InstalledCopy {
     /** 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;
 /**

package/dist/cli/copies.js

@@ -10,41 +10,10 @@
  */
 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;
-}
+import { enclosingPackage, opencodeCacheRoot, PKG_NAME } from "../shared/pkginfo.js";
+export { enclosingPackage, opencodeCacheRoot } from "../shared/pkginfo.js";
 /** 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
@@ -195,13 +164,3 @@ export function findInstalledCopies(platform = process.platform, env = process.e
     }
     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");
-}

package/dist/cli/install.js

@@ -1154,7 +1154,7 @@ function installOmac(opts, P) {
         "LOAD_LOCK_LABEL_PREFIX=omac (dashboard shows holders as omac:<label>); " +
         "LOAD_LOCK_SOCKET only if the default <state dir>/daemon.sock is not what the sandbox sees");
     actions.push("label prefixes need load-lock >= 1.2.0 on BOTH ends: a daemon started before v1.2.0 " +
-        "silently strips the unknown labelPrefix field — upgrade and restart the daemon (load-lock service stop && load-lock service start)");
+        "silently strips the unknown labelPrefix field — upgrade and restart the daemon (load-lock service restart)");
     actions.push("verified live against omac 0.11.0 (bubblewrap + Landlock): sandboxed client -> host daemon " +
         "round-trip, prefixed labels, LOAD_LOCK_NO_SPAWN error contract");
     return actions;