@aron98/load-lock 1.3.0 → 1.4.0

package/dist/mcp/server.js

@@ -21,6 +21,7 @@ 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";
 const ACQUIRE_DESC = `Acquire a machine-wide permit before starting resource-intensive local work (full builds, test suites, big compiles/containers).
 
@@ -263,13 +264,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 +280,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 +290,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 +306,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 +337,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 +389,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 +399,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/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;

package/dist/shared/wait-completion.d.ts

@@ -0,0 +1,67 @@
+import { WaitForCompletionResult } from "./protocol.js";
+import { LLClient } from "./client.js";
+/**
+ * What adapters expose for a run_with_permit job so it can be waited on.
+ * `exitPromise` must resolve when the child exits, and the exit handler must
+ * assign `releasePromise` BEFORE resolving it, so a woken waiter can observe
+ * the permit-release round-trip.
+ */
+export interface WaitableAdapterJob {
+    id: string;
+    /** The permit's request id, when known (for cross-referencing with the daemon). */
+    requestId?: string;
+    startedAt: number;
+    exited: boolean;
+    exitedAt?: number;
+    exitCode?: number | null;
+    output: string[];
+    /** Set by job_stop before killing — a later wake reports stopped_by_request. */
+    stopRequested?: boolean;
+    /** True once the daemon confirmed the release RPC. */
+    permitReleased?: boolean;
+    /** Resolves with the child's exit code when it exits. */
+    exitPromise?: Promise<number | null>;
+    /** The permit-release round-trip started by the exit handler. */
+    releasePromise?: Promise<unknown>;
+}
+export interface WaitForTrackedJobOpts {
+    client: LLClient;
+    /** The request id whose daemon-tracked job to wait for. */
+    requestId: string;
+    /**
+     * Requested bound (ms), clamped to the machine's maxTurnWaitMs config.
+     * 0 = check-only (immediate return). Default 600_000.
+     */
+    timeoutMs?: number;
+    /** Poll cadence for the old-daemon fallback loop (default 200ms). */
+    pollMs?: number;
+    /** Caller cancellation — resolves as { state: "timeout" }; the job is untouched. */
+    signal?: AbortSignal;
+}
+export interface WaitForLocalJobOpts {
+    /**
+     * Bound for this call (ms). 0 = check-only. Default 600_000. NOT clamped
+     * by machine config — the adapter already has the exit event, so the wait
+     * is bounded only by the caller's own budget (documented divergence).
+     */
+    timeoutMs?: number;
+    /** Caller cancellation — resolves as { state: "timeout" }; the job is untouched. */
+    signal?: AbortSignal;
+}
+/**
+ * Bounded blocking wait for a daemon-tracked job. Uses the daemon's
+ * server-side wait_for_completion hold when available; falls back to a light
+ * client-side poll against the SAME wire events on old daemons; retries
+ * through transient daemon unavailability (tracked permits survive
+ * restarts via the journal). Returns a structured result on every path.
+ */
+export declare function waitForTrackedJob(opts: WaitForTrackedJobOpts): Promise<WaitForCompletionResult>;
+/**
+ * Bounded, event-driven wait for a run_with_permit child the adapter owns.
+ * No polling: the child's exit event wakes the waiter directly, with the
+ * exact exit code and output tail. The permit-release round-trip is awaited
+ * before reporting finished, so permitReleased is truthful (the daemon
+ * releases the permit before adapter waits wake by construction of the
+ * adapters' exit handlers).
+ */
+export declare function waitForLocalJob(job: WaitableAdapterJob, opts?: WaitForLocalJobOpts): Promise<WaitForCompletionResult>;