@aron98/load-lock 0.1.2 → 1.1.0

package/dist/test/wait-turn.test.js

@@ -0,0 +1,376 @@
+/**
+ * Integration tests for wait_for_turn (issue #11): a REAL daemon process over
+ * a real Unix socket with multiple independent client connections. Exercises
+ * the shared client-side bounded wait (src/shared/wait-turn.ts) that serves
+ * the CLI `wait` command, the MCP wait_for_turn tool and the OpenCode plugin
+ * tool: FIFO wakeup with auto-claim, structured timeout, paused/rejoin,
+ * mid-wait cancellation, bounded resolution across a daemon restart, and
+ * clean AbortSignal cancellation with no orphaned waiter.
+ */
+import test from "node:test";
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { waitForTurn, WaitAbortedError } from "../shared/wait-turn.js";
+import { startDaemon, delay, until, probe, daemonMainPath } from "./testutil.js";
+const ACQ = (agentId, opKey, extra = {}) => ({
+    agentId,
+    opKey,
+    reason: "integration test",
+    ...extra,
+});
+/** Start a wait that is expected to stay pending for at least `ms`. */
+function expectPending(ms) {
+    return delay(ms).then(() => "pending");
+}
+test("wait_for_turn: sleeper wakes granted with an auto-claimed permit after the holder releases (FIFO preserved)", async () => {
+    const d = await startDaemon();
+    const clients = [];
+    try {
+        const cA = d.client();
+        await cA.connect();
+        clients.push(cA);
+        await cA.request("configure", {
+            expectedVersion: 1,
+            changes: { offerTimeoutMs: 60_000, maxWaitMs: 0 },
+            reason: "test timings",
+            author: "test",
+        });
+        const a = (await cA.request("acquire", ACQ("agentA", "opA")));
+        assert.equal(a.state, "granted");
+        const cB = d.client();
+        const cC = d.client();
+        await cB.connect();
+        await cC.connect();
+        clients.push(cB, cC);
+        const b = (await cB.request("acquire", ACQ("agentB", "opB")));
+        assert.equal(b.state, "queued");
+        assert.equal(b.entry.position, 1);
+        const c = (await cC.request("acquire", ACQ("agentC", "opC")));
+        assert.equal(c.state, "queued");
+        assert.equal(c.entry.position, 2);
+        // B sleeps (no request_id: default target resolution must pick the queued one).
+        const waitB = waitForTurn({ client: cB, agentId: "agentB", timeoutMs: 15_000 });
+        const early = await Promise.race([waitB.then(() => "done"), expectPending(400)]);
+        assert.equal(early, "pending", "the wait blocks while the holder keeps the permit");
+        const st = (await cA.request("status", {}));
+        assert.equal(st.pools[0].used, 1, "the sleeping wait holds no capacity");
+        // The holder finishes; B must wake already holding a claimed permit.
+        await cA.request("release", { permitToken: a.entry.permitToken });
+        const rB = await waitB;
+        assert.equal(rB.state, "granted");
+        assert.equal(rB.autoClaimed, true, "the offer was auto-claimed inside the claim window");
+        assert.ok(rB.entry?.permitToken, "granted result carries the permit token");
+        assert.ok(rB.entry.offerToken === undefined || !rB.entry.offerToken, "claimed permit has no lingering offer token");
+        assert.ok(rB.waitedMs >= 300);
+        // FIFO: C is still queued behind B's claimed permit, and goes next.
+        const pendC = (await cC.request("pending", { agentId: "agentC" }));
+        assert.equal(pendC.queue.length, 1);
+        assert.equal(pendC.queue[0].position, 1);
+        await cB.request("release", { permitToken: rB.entry.permitToken });
+        const rC = await waitForTurn({ client: cC, agentId: "agentC", timeoutMs: 15_000 });
+        assert.equal(rC.state, "granted");
+        assert.equal(rC.autoClaimed, true);
+        assert.ok(rC.entry?.permitToken);
+        await cC.request("release", { permitToken: rC.entry.permitToken });
+    }
+    finally {
+        for (const cl of clients)
+            cl.close();
+        await d.stop();
+    }
+});
+test("wait_for_turn: timeout returns still_queued with position and holders, not an error", async () => {
+    const d = await startDaemon();
+    const clients = [];
+    try {
+        const cA = d.client();
+        await cA.connect();
+        clients.push(cA);
+        await cA.request("configure", {
+            expectedVersion: 1,
+            changes: { offerTimeoutMs: 60_000, maxWaitMs: 0 },
+            reason: "test timings",
+            author: "test",
+        });
+        const a = (await cA.request("acquire", ACQ("holderA", "opA")));
+        assert.equal(a.state, "granted");
+        const cB = d.client();
+        await cB.connect();
+        clients.push(cB);
+        const b = (await cB.request("acquire", ACQ("waiterB", "opB")));
+        assert.equal(b.state, "queued");
+        const requestId = b.entry.requestId;
+        const r = await waitForTurn({ client: cB, agentId: "waiterB", requestId, timeoutMs: 900 });
+        assert.equal(r.state, "still_queued", "timeout is a structured result, not an error");
+        assert.equal(r.requestId, requestId);
+        assert.equal(r.queuePosition, 1);
+        assert.equal(r.queueLength, 1);
+        assert.ok(Array.isArray(r.holders) && r.holders.length >= 1, "holder info included");
+        assert.equal(r.holders[0].agentId, "holderA");
+        assert.ok(r.waitedMs >= 800, `waited the full bound (waitedMs=${r.waitedMs})`);
+        assert.match(r.nextAction ?? "", /wait_for_turn|wait again/i);
+        // The queued request is untouched by the timed-out wait.
+        const pend = (await cB.request("pending", { agentId: "waiterB" }));
+        assert.equal(pend.queue.length, 1);
+        assert.equal(pend.queue[0].position, 1);
+    }
+    finally {
+        for (const cl of clients)
+            cl.close();
+        await d.stop();
+    }
+});
+test("wait_for_turn: paused request returns rejoin instructions, and rejoin then wait succeeds", async () => {
+    const d = await startDaemon();
+    const clients = [];
+    try {
+        const cA = d.client();
+        await cA.connect();
+        clients.push(cA);
+        const cfg = (await cA.request("get_config", {}));
+        await cA.request("configure", {
+            expectedVersion: cfg.config.version,
+            changes: { offerTimeoutMs: 1_000, maxWaitMs: 0 },
+            reason: "fast offer expiry for the paused path",
+            author: "test",
+        });
+        const a = (await cA.request("acquire", ACQ("holdA", "opA")));
+        assert.equal(a.state, "granted");
+        const cB = d.client();
+        await cB.connect();
+        clients.push(cB);
+        const b = (await cB.request("acquire", ACQ("pauseB", "opB")));
+        assert.equal(b.state, "queued");
+        const requestId = b.entry.requestId;
+        // Let the offer expire so the request lands in paused.
+        await cA.request("release", { permitToken: a.entry.permitToken });
+        await until("offer expires and B lands in paused", async () => {
+            const p = (await cB.request("pending", { agentId: "pauseB" }));
+            return p.paused.length === 1;
+        }, 15_000);
+        const r = await waitForTurn({ client: cB, agentId: "pauseB", requestId, timeoutMs: 5_000 });
+        assert.equal(r.state, "paused", "paused resolves immediately with a structured result");
+        assert.match(r.nextAction ?? "", /rejoin/i, "rejoin instructions included");
+        assert.equal(r.entry?.state, "paused");
+        // Rejoin, then sleep again: the freed capacity must reach B and auto-claim.
+        await cB.request("rejoin", { requestId });
+        const r2 = await waitForTurn({ client: cB, agentId: "pauseB", timeoutMs: 10_000 });
+        assert.equal(r2.state, "granted");
+        assert.equal(r2.autoClaimed, true);
+        assert.ok(r2.entry?.permitToken);
+        await cB.request("release", { permitToken: r2.entry.permitToken });
+    }
+    finally {
+        for (const cl of clients)
+            cl.close();
+        await d.stop();
+    }
+});
+test("wait_for_turn: request cancelled mid-wait resolves cancelled with re-acquire instructions", async () => {
+    const d = await startDaemon();
+    const clients = [];
+    try {
+        const cA = d.client();
+        await cA.connect();
+        clients.push(cA);
+        await cA.request("configure", {
+            expectedVersion: 1,
+            changes: { offerTimeoutMs: 60_000, maxWaitMs: 0 },
+            reason: "test timings",
+            author: "test",
+        });
+        const a = (await cA.request("acquire", ACQ("holdA", "opA")));
+        assert.equal(a.state, "granted");
+        const cB = d.client();
+        await cB.connect();
+        clients.push(cB);
+        const b = (await cB.request("acquire", ACQ("waitB", "opB")));
+        assert.equal(b.state, "queued");
+        const requestId = b.entry.requestId;
+        const wait = waitForTurn({ client: cB, agentId: "waitB", requestId, timeoutMs: 15_000 });
+        const early = await Promise.race([wait.then(() => "done"), expectPending(400)]);
+        assert.equal(early, "pending");
+        // Someone else cancels the request while we sleep.
+        await cA.request("cancel", { requestId });
+        const r = await wait;
+        assert.equal(r.state, "cancelled", "cancellation resolves the wait with the request's state");
+        assert.match(r.nextAction ?? "", /acquire/i, "re-acquire instructions included");
+        const pend = (await cB.request("pending", { agentId: "waitB" }));
+        assert.equal(pend.queue.length + pend.paused.length + pend.offers.length, 0, "nothing orphaned in pending");
+    }
+    finally {
+        for (const cl of clients)
+            cl.close();
+        await d.stop();
+    }
+});
+test("wait_for_turn: daemon restart mid-wait resolves bounded with not_found + re-acquire guidance", async () => {
+    const d = await startDaemon();
+    const clients = [];
+    let child2 = null;
+    try {
+        const cA = d.client();
+        await cA.connect();
+        clients.push(cA);
+        await cA.request("configure", {
+            expectedVersion: 1,
+            changes: { offerTimeoutMs: 60_000, maxWaitMs: 0 },
+            reason: "test timings",
+            author: "test",
+        });
+        const a = (await cA.request("acquire", ACQ("holdA", "opA")));
+        assert.equal(a.state, "granted");
+        const cB = d.client();
+        await cB.connect();
+        clients.push(cB);
+        const b = (await cB.request("acquire", ACQ("waitB", "opB")));
+        assert.equal(b.state, "queued");
+        const requestId = b.entry.requestId;
+        const wait = waitForTurn({ client: cB, agentId: "waitB", requestId, timeoutMs: 60_000 });
+        const early = await Promise.race([wait.then(() => "done"), expectPending(400)]);
+        assert.equal(early, "pending");
+        // Restart the daemon mid-wait.
+        const t0 = Date.now();
+        d.child.kill("SIGTERM");
+        await new Promise((r) => d.child.once("exit", r));
+        child2 = spawn(process.execPath, [daemonMainPath, "--state-dir", d.dir, "--socket", d.sock], {
+            stdio: ["ignore", "pipe", "pipe"],
+            env: { ...process.env, LOAD_LOCK_STATE_DIR: d.dir, LOAD_LOCK_SOCKET: d.sock },
+        });
+        await until("restarted daemon listens", async () => await probe(d.sock));
+        const r = await wait;
+        const elapsed = Date.now() - t0;
+        assert.ok(elapsed < 5_000, `restart resolution is bounded (took ${elapsed}ms)`);
+        assert.equal(r.state, "not_found", "queued requests do not survive a restart");
+        assert.match(r.nextAction ?? "", /acquire/i, "re-acquire guidance included");
+        assert.ok(r.waitedMs >= 300);
+    }
+    finally {
+        if (child2 && child2.exitCode === null && !child2.killed)
+            child2.kill("SIGKILL");
+        for (const cl of clients)
+            cl.close();
+        // stop() would kill the already-dead child again + rm the dir; safe either way.
+        d.child.kill("SIGKILL");
+        await delay(100);
+        await d.stop();
+    }
+});
+test("wait_for_turn: caller abort leaves no orphan — the request stays healthy and FIFO", async () => {
+    const d = await startDaemon();
+    const clients = [];
+    try {
+        const cA = d.client();
+        await cA.connect();
+        clients.push(cA);
+        await cA.request("configure", {
+            expectedVersion: 1,
+            changes: { offerTimeoutMs: 60_000, maxWaitMs: 0 },
+            reason: "test timings",
+            author: "test",
+        });
+        const a = (await cA.request("acquire", ACQ("holdA", "opA")));
+        assert.equal(a.state, "granted");
+        const cB = d.client();
+        await cB.connect();
+        clients.push(cB);
+        const b = (await cB.request("acquire", ACQ("waitB", "opB")));
+        assert.equal(b.state, "queued");
+        const requestId = b.entry.requestId;
+        const ac = new AbortController();
+        const wait = waitForTurn({ client: cB, agentId: "waitB", requestId, timeoutMs: 60_000, signal: ac.signal });
+        const early = await Promise.race([wait.then(() => "done"), expectPending(400)]);
+        assert.equal(early, "pending");
+        // The harness cancels the tool call mid-sleep.
+        ac.abort();
+        await assert.rejects(wait, (e) => e instanceof WaitAbortedError && e.name === "AbortError");
+        // Nothing orphaned: the request is still queued, capacity untouched, no claim consumed.
+        const pend = (await cB.request("pending", { agentId: "waitB" }));
+        assert.equal(pend.queue.length, 1, "the request keeps its queue slot after the abort");
+        assert.equal(pend.queue[0].position, 1);
+        assert.equal(pend.offers.length, 0);
+        const st = (await cA.request("status", {}));
+        assert.equal(st.pools[0].used, 1, "no capacity was consumed by the wait or the abort");
+        // The request is still perfectly usable: release, sleep again, get the turn.
+        await cA.request("release", { permitToken: a.entry.permitToken });
+        const r = await waitForTurn({ client: cB, agentId: "waitB", requestId, timeoutMs: 15_000 });
+        assert.equal(r.state, "granted");
+        assert.equal(r.autoClaimed, true);
+        assert.ok(r.entry?.permitToken);
+        await cB.request("release", { permitToken: r.entry.permitToken });
+    }
+    finally {
+        for (const cl of clients)
+            cl.close();
+        await d.stop();
+    }
+});
+test("wait_for_turn: the maxTurnWaitMs config caps the bound (validated, persisted)", async () => {
+    const d = await startDaemon();
+    const clients = [];
+    try {
+        const cA = d.client();
+        await cA.connect();
+        clients.push(cA);
+        await cA.request("configure", {
+            expectedVersion: 1,
+            changes: { offerTimeoutMs: 60_000, maxWaitMs: 0 },
+            reason: "test timings",
+            author: "test",
+        });
+        const a = (await cA.request("acquire", ACQ("holdA", "opA")));
+        assert.equal(a.state, "granted");
+        const cB = d.client();
+        await cB.connect();
+        clients.push(cB);
+        const b = (await cB.request("acquire", ACQ("waitB", "opB")));
+        assert.equal(b.state, "queued");
+        // Out-of-range values are rejected by the configure validation.
+        await assert.rejects(cA.request("configure", {
+            expectedVersion: 2,
+            changes: { maxTurnWaitMs: 500 },
+            reason: "below the floor",
+            author: "test",
+        }), /maxTurnWaitMs/);
+        const cfg = (await cA.request("get_config", {}));
+        assert.equal(cfg.config.maxTurnWaitMs, 600_000, "default cap is 10 minutes");
+        const conf = (await cA.request("configure", {
+            expectedVersion: cfg.config.version,
+            changes: { maxTurnWaitMs: 1_000 },
+            reason: "short cap for the test",
+            author: "test",
+        }));
+        assert.equal(conf.config.maxTurnWaitMs, 1_000, "cap persisted via CAS configure");
+        // A 10-minute ask is clamped to the 1-second machine cap and reported.
+        const t0 = Date.now();
+        const r = await waitForTurn({ client: cB, agentId: "waitB", timeoutMs: 600_000 });
+        const elapsed = Date.now() - t0;
+        assert.equal(r.state, "still_queued");
+        assert.equal(r.effectiveWaitMs, 1_000, "the effective (clamped) bound is reported");
+        assert.ok(elapsed < 2_500, `the wait respected the clamp (took ${elapsed}ms)`);
+    }
+    finally {
+        for (const cl of clients)
+            cl.close();
+        await d.stop();
+    }
+});
+test("wait_for_turn: nothing to watch resolves not_found immediately", async () => {
+    const d = await startDaemon();
+    const clients = [];
+    try {
+        const c = d.client();
+        await c.connect();
+        clients.push(c);
+        const t0 = Date.now();
+        const r = await waitForTurn({ client: c, agentId: "nobody", timeoutMs: 5_000 });
+        assert.ok(Date.now() - t0 < 1_000, "no busy-wait when there is nothing to watch");
+        assert.equal(r.state, "not_found");
+        assert.match(r.nextAction ?? "", /acquire/i);
+    }
+    finally {
+        for (const cl of clients)
+            cl.close();
+        await d.stop();
+    }
+});

package/docs/ADAPTERS.md

@@ -71,11 +71,14 @@ Register the MCP server with the harness and put a short policy section in
 whatever global instructions file the harness reads (GEMINI.md / rules /
 hints...). Offers are surfaced in every tool result (tool-boundary
 delivery), so correctness is preserved; what you lose is idle wakeup —
-document that honestly (see docs/COMPATIBILITY.md).
+steer agents to `wait_for_turn` (bounded blocking sleep that auto-claims
+and returns a `permit_token`) as the primary idle mechanism, and document
+the remaining gap honestly (see docs/COMPATIBILITY.md).
 
 ## Protocol quick reference
 
-Wire protocol: NDJSON over a Unix domain socket; `LLClient` handles
+Wire protocol: NDJSON over a Unix domain socket (named pipe on Windows);
+`LLClient` handles
 framing, timeouts, auto-spawn, and event subscriptions. Methods an adapter
 normally touches:
 

package/docs/AGENT_GUIDE.md

@@ -32,6 +32,8 @@ acquire(reason, op_key)
   ├─ granted  → you hold a permit → do the heavy work now
   ├─ queued   → keep doing LIGHT work; offers reach you at your next
   │             load-lock tool call, or via a wakeup message
+  │             no light work left? wait_for_turn() = "sleep until it
+  │             is my turn" (bounded; auto-claims the offer for you)
   └─ ...
 offer arrives (token, expiry) → claim(token) BEFORE the window closes
 claim → held → start the heavy work
@@ -71,6 +73,36 @@ Notes on the details:
   explicitly `rejoin(request_id)`. If you know you can't start in time,
   `decline` instead of letting it expire.
 
+### Sleeping until your turn (`wait_for_turn`)
+
+Rule 2 says keep doing light work while queued — but sometimes there is
+nothing useful left. `wait_for_turn(request_id?, timeout_ms?)` is the honest
+way to idle: a **bounded blocking sleep** over one of your queued, offered
+or paused requests (default: your most urgent one). When capacity reaches
+you mid-sleep, the offer is **auto-claimed inside the claim window** and
+you wake holding the permit (`granted`, `permit_token` + `auto_claimed:
+true` in the response).
+
+Every resolution is a structured result, never an opaque error:
+
+- `granted` — your turn came; the permit is already claimed for you.
+- `still_queued` — the bound expired; you get your queue position, queue
+  length and who is holding the capacity. Call it again to keep sleeping.
+- `paused` — your offer expired or was declined meanwhile; `next_action`
+  has the rejoin instructions.
+- `cancelled` — the request was cancelled/declined/reclaimed meanwhile.
+- `not_found` — the request ended, or the daemon restarted (queues are
+  ephemeral); acquire again.
+
+The sleep is bounded and **safe by construction**: it holds no permit and
+no capacity, cancelling the tool call just stops the local sleep (nothing
+is orphaned — your request keeps its queue position), and a daemon restart
+mid-sleep resolves promptly with `not_found` instead of hanging. `timeout_ms`
+defaults to 600000 (10 minutes) and is clamped to the machine's
+`maxTurnWaitMs` cap (`get_config` shows it; `configure` can set it, valid
+range 1000–3600000 ms). `timeout_ms: 0` means check-only. The CLI form is
+`load-lock wait --id <request-id> --timeout <ms>`.
+
 ## 3. Running heavy work (lifecycle options)
 
 How you start the work determines how reliably the permit cleans up after
@@ -104,7 +136,8 @@ load-lock acquire --reason "cargo test" --op-key "test/core"      # prints JSON
 load-lock run --permit <permit-token> -- cargo test --quiet       # tracks + releases
 # or acquire+run in one go:
 load-lock run --reason "nightly build" -- npm run build
-load-lock wait --id <request-id> --timeout 120000                # bounded wait → auto-claim
+load-lock wait --id <request-id> --timeout 120000                # sleep until your turn → auto-claim
+load-lock help                                                    # one-screen usage of every command
 ```
 
 ## 4. Reading state

package/docs/ARCHITECTURE.md

@@ -42,7 +42,8 @@ and inherit unrelated constraints.
 
 **One daemon, one budget.** A single `load-lock` daemon process per machine
 owns all state. Every client — any harness, any repo, any worktree — talks to
-the same Unix-domain socket, so all sessions share one capacity budget
+the same Unix-domain socket (named pipe `\\.\pipe\load-lock` on Windows),
+so all sessions share one capacity budget
 regardless of working directory. The default configuration is one pool
 `heavy` with capacity 1; pools, capacity, and timings are changed at runtime
 through `configure` (versioned compare-and-swap, persisted with author +
@@ -131,8 +132,18 @@ mechanisms, and labels exactly which apply per harness:
    offer at its next tool call, without polling.
 2. **Bounded blocking wait.** `acquire(wait_ms)` blocks briefly (default
    5s) inside the tool call and auto-claims if capacity frees during the
-   wait. The CLI `wait` command and MCP `wait` pattern provide longer
-   bounded waits. No model-authored busy-polling required.
+   wait. For longer sleeps there is one shared client-side
+   implementation, `waitForTurn` (`src/shared/wait-turn.ts`), surfaced as
+   the CLI `wait` command, the MCP `wait_for_turn` tool and the OpenCode
+   plugin's `load_lock_wait_for_turn` tool: it polls light
+   events+pending pulls on the local socket, auto-claims inside the
+   offer window, returns structured results on every path (granted /
+   still_queued with position / paused / cancelled / not_found), is
+   bounded by `timeout_ms` (capped by the `maxTurnWaitMs` config), and —
+   being purely client-side — holds no permit, consumes no capacity, and
+   can never orphan a daemon-side waiter when the harness cancels the
+   tool mid-sleep. Daemon restarts are detected via the event cursor and
+   resolve bounded. No model-authored busy-polling required.
 3. **Idle wakeup where the harness genuinely supports it.**
    - OpenCode (live-verified): the native plugin watches daemon events and
      calls `ctx.session.synthetic(...)`, delivering the offer (with token)
@@ -141,7 +152,7 @@ mechanisms, and labels exactly which apply per harness:
    - Claude Code (contract-tested): a `Stop` hook checks for cwd-matching
      offers and continues the session with a claim instruction; an async
      `await-offer` watcher with `asyncRewake: true` wakes idle sessions.
-   - Codex CLI (contract-tested): `Stop` hook with `decision: "block"`
+   - Codex CLI (live-verified in Docker): `Stop` hook with `decision: "block"`
      continuation. Note: Codex async background hooks do **not** start a new
      turn — documented as a limitation.
 4. **Durable event identities.** All events have monotonic IDs; agents can
@@ -164,7 +175,8 @@ and restored after context compaction:
 - **Claude Code**: `SessionStart` hook (matchers include `compact`) +
   `~/.claude/CLAUDE.md` section + skill.
 - **Codex CLI**: `SessionStart` hook (matcher `compact`) + `SubagentStart`
-  hook + `~/.codex/AGENTS.md` section (hooks require `/hooks` trust review).
+  hook + `~/.codex/AGENTS.md` section (hooks require the interactive
+  hook-trust review once; live-verified in Docker).
 - Other harnesses: MCP server `instructions` + a global instructions file
   snippet where the harness supports one (see COMPATIBILITY.md).
 
@@ -193,3 +205,11 @@ capacity; admission is FIFO with head-of-line blocking) and multiple pools;
 the machine currently uses one pool by default but accepts arbitrary pool
 names through the same code paths. Adding a second budget (e.g. `network`)
 is configuration, not code.
+
+The read-only status surface also extends without protocol changes: the
+`status` + `events` (durable ids) + `watch` + `inspect` methods are enough
+to build live viewers. `load-lock dashboard` (alias `top`) and the OpenCode TUI panel
+(`src/dashboard/`) are exactly that — pure view-model shaping over the
+library client (`./shared/client`), never CLI-output scraping, and never
+acquiring a permit themselves. Any future harness UI can reuse the same
+`src/dashboard/` pipeline.