@aron98/load-lock 0.1.1 → 1.0.0

package/dist/test/mcp.test.js

@@ -29,7 +29,7 @@ test("mcp: tool listing + acquire/release/configure round trip", async () => {
     try {
         const tools = await c.listTools();
         const names = tools.tools.map((t) => t.name);
-        for (const expected of ["acquire", "claim", "release", "cancel", "rejoin", "pending", "status", "inspect_machine", "get_config", "configure", "run_with_permit", "job_status", "job_stop", "attach_pid", "mark_started"]) {
+        for (const expected of ["acquire", "claim", "release", "cancel", "rejoin", "pending", "wait_for_turn", "status", "inspect_machine", "get_config", "configure", "run_with_permit", "job_status", "job_stop", "attach_pid", "mark_started"]) {
             assert.ok(names.includes(expected), `tool ${expected} registered`);
         }
         const acq = await callJson(c, "acquire", { reason: "build", op_key: "mcp-rt", agent_id: "mcpAgentA" });
@@ -77,6 +77,41 @@ test("mcp: tool listing + acquire/release/configure round trip", async () => {
         await d.stop();
     }
 });
+test("mcp: wait_for_turn sleeps bounded and returns structured snake_case results", async () => {
+    const d = await startDaemon();
+    const c = await connectMcp(d);
+    try {
+        const a = await callJson(c, "acquire", { reason: "build", op_key: "wft-a", agent_id: "mcpWaitA" });
+        assert.equal(a.state, "granted");
+        const b = await callJson(c, "acquire", { reason: "tests", op_key: "wft-b", agent_id: "mcpWaitB" });
+        assert.equal(b.state, "queued");
+        // Timeout is a structured still_queued result — never a tool error.
+        const t0 = Date.now();
+        const out1 = await callJson(c, "wait_for_turn", { agent_id: "mcpWaitB", timeout_ms: 700 });
+        assert.equal(out1.state, "still_queued");
+        assert.equal(out1.request_id, b.request_id);
+        assert.equal(out1.queue_position, 1);
+        assert.equal(out1.queue_length, 1);
+        assert.ok(Array.isArray(out1.holders) && out1.holders.length >= 1, "holder info included");
+        assert.equal(out1.holders[0].agentId, "mcpWaitA");
+        assert.ok(out1.waited_ms >= 600 && Date.now() - t0 < 5_000, "wait respected the bound");
+        // The cap is discoverable via configure + get_config (snake_case surface).
+        const cfg = await callJson(c, "get_config", {});
+        assert.equal(cfg.config.maxTurnWaitMs, 600_000, "default turn-wait cap present in config");
+        // Wake path: release, sleep again, wake holding an auto-claimed permit.
+        await callJson(c, "release", { permit_token: a.permit_token });
+        const out2 = await callJson(c, "wait_for_turn", { agent_id: "mcpWaitB", timeout_ms: 10_000 });
+        assert.equal(out2.state, "granted");
+        assert.equal(out2.auto_claimed, true, "auto-claim is explicit in the response");
+        assert.ok(out2.permit_token, "granted result carries a top-level permit_token");
+        assert.equal(out2.request_id, b.request_id);
+        await callJson(c, "release", { permit_token: out2.permit_token });
+    }
+    finally {
+        await c.close();
+        await d.stop();
+    }
+});
 test("mcp: run_with_permit tracks a background job and auto-releases", async () => {
     const d = await startDaemon();
     const c = await connectMcp(d);

package/dist/test/platform.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/platform.test.js

@@ -0,0 +1,193 @@
+/**
+ * Unit tests for the cross-platform transport seam (src/shared/transport.ts)
+ * and its integration into state-dir/socket-path resolution (persist.ts).
+ *
+ * These tests run on Linux: the Windows branches are exercised by
+ * explicitly injecting platform = "win32" into the pure functions. No
+ * Windows machine was available for live verification — see
+ * docs/COMPATIBILITY.md (platform matrix).
+ */
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, mkdirSync, existsSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createServer } from "node:net";
+import { spawn } from "node:child_process";
+import { DEFAULT_PIPE_NAME, isWindows, namedPipePath, resolveStateDir, resolveSocketPath, probeTransport, removeStaleEndpoint, killProcessGroup, } from "../shared/transport.js";
+import { stateDir, socketPath } from "../core/persist.js";
+import { isProcessAlive, jobAlive, aliveBySignalZero, processStartTime } from "../core/daemon.js";
+const TMP_BASE = process.env.LL_TEST_TMP ?? join(tmpdir(), "opencode");
+mkdirSync(TMP_BASE, { recursive: true });
+const tmp = mkdtempSync(join(TMP_BASE, "ll-platform-"));
+test("namedPipePath builds \\\\.\\pipe\\load-lock by default", () => {
+    assert.equal(namedPipePath(), "\\\\.\\pipe\\load-lock");
+    assert.equal(namedPipePath(), `\\\\.\\pipe\\${DEFAULT_PIPE_NAME}`);
+    assert.equal(namedPipePath("other"), "\\\\.\\pipe\\other");
+});
+test("isWindows only matches win32", () => {
+    assert.equal(isWindows("win32"), true);
+    assert.equal(isWindows("linux"), false);
+    assert.equal(isWindows("darwin"), false);
+});
+test("resolveStateDir: override wins over env and default", () => {
+    const env = { LOAD_LOCK_STATE_DIR: "/from-env", HOME: "/home/u" };
+    assert.equal(resolveStateDir("win32", env, "/explicit"), "/explicit");
+    assert.equal(resolveStateDir("linux", env, "/explicit"), "/explicit");
+    assert.equal(resolveStateDir("win32", env), "/from-env");
+});
+test("resolveStateDir: win32 uses LOCALAPPDATA, then USERPROFILE fallback", () => {
+    const env = { LOCALAPPDATA: "C:\\Users\\u\\AppData\\Local", USERPROFILE: "C:\\Users\\u" };
+    assert.equal(resolveStateDir("win32", env), "C:\\Users\\u\\AppData\\Local\\load-lock");
+    const env2 = { USERPROFILE: "C:\\Users\\u" };
+    assert.equal(resolveStateDir("win32", env2), "C:\\Users\\u\\AppData\\Local\\load-lock");
+});
+test("resolveStateDir: linux uses XDG_STATE_HOME, then HOME fallback", () => {
+    const env = { XDG_STATE_HOME: "/xdg/state", HOME: "/home/u" };
+    assert.equal(resolveStateDir("linux", env), "/xdg/state/load-lock");
+    const env2 = { HOME: "/home/u" };
+    assert.equal(resolveStateDir("linux", env2), "/home/u/.local/state/load-lock");
+});
+test("resolveSocketPath: win32 default is the named pipe", () => {
+    const env = { LOCALAPPDATA: "C:\\Users\\u\\AppData\\Local" };
+    assert.equal(resolveSocketPath("win32", env), "\\\\.\\pipe\\load-lock");
+});
+test("resolveSocketPath: LOAD_LOCK_SOCKET override wins on every platform", () => {
+    const env = { LOAD_LOCK_SOCKET: "C:\\somewhere\\other.sock" };
+    assert.equal(resolveSocketPath("win32", env), "C:\\somewhere\\other.sock");
+    assert.equal(resolveSocketPath("linux", env), "C:\\somewhere\\other.sock");
+});
+test("resolveSocketPath: linux default is <state dir>/daemon.sock", () => {
+    const env = { HOME: "/home/u" };
+    assert.equal(resolveSocketPath("linux", env), "/home/u/.local/state/load-lock/daemon.sock");
+});
+test("resolveSocketPath: explicit override wins over everything", () => {
+    const env = { LOAD_LOCK_SOCKET: "/from-env", LOAD_LOCK_STATE_DIR: "/s" };
+    assert.equal(resolveSocketPath("linux", env, "/explicit"), "/explicit");
+});
+test("persist stateDir()/socketPath() delegate with the real platform", () => {
+    // On Linux (the only platform these tests run on) the defaults must keep
+    // their current shape, and env overrides must flow through.
+    const savedState = process.env.LOAD_LOCK_STATE_DIR;
+    const savedSock = process.env.LOAD_LOCK_SOCKET;
+    try {
+        delete process.env.LOAD_LOCK_STATE_DIR;
+        delete process.env.LOAD_LOCK_SOCKET;
+        assert.equal(socketPath(), resolveSocketPath(process.platform, process.env));
+        assert.equal(stateDir(), resolveStateDir(process.platform, process.env));
+        process.env.LOAD_LOCK_SOCKET = "/tmp/opencode/ll-platform-override.sock";
+        assert.equal(socketPath(), "/tmp/opencode/ll-platform-override.sock");
+        assert.equal(socketPath("/cli-flag.sock"), "/cli-flag.sock");
+    }
+    finally {
+        if (savedState === undefined)
+            delete process.env.LOAD_LOCK_STATE_DIR;
+        else
+            process.env.LOAD_LOCK_STATE_DIR = savedState;
+        if (savedSock === undefined)
+            delete process.env.LOAD_LOCK_SOCKET;
+        else
+            process.env.LOAD_LOCK_SOCKET = savedSock;
+    }
+});
+async function withUdsServer(fn) {
+    const sockPath = join(tmp, "probe.sock");
+    const server = createServer();
+    await new Promise((resolve) => server.listen(sockPath, resolve));
+    try {
+        await fn(sockPath, server);
+    }
+    finally {
+        await new Promise((resolve) => server.close(() => resolve()));
+        rmSync(sockPath, { force: true });
+    }
+}
+test("probeTransport: true for a live server, false after close", async () => {
+    await withUdsServer(async (sockPath, server) => {
+        assert.equal(await probeTransport(sockPath), true);
+        await new Promise((resolve) => server.close(() => resolve()));
+        assert.equal(await probeTransport(sockPath), false);
+    });
+});
+test("probeTransport: false for a nonexistent endpoint (never throws)", async () => {
+    assert.equal(await probeTransport(join(tmp, "no-such.sock")), false);
+});
+test("removeStaleEndpoint: POSIX unlinks, win32 is a no-op", () => {
+    const stale = join(tmp, "stale.sock");
+    writeFileSync(stale, "");
+    removeStaleEndpoint(stale, "linux");
+    assert.equal(existsSync(stale), false);
+    const stale2 = join(tmp, "stale2.sock");
+    writeFileSync(stale2, "");
+    removeStaleEndpoint(stale2, "win32");
+    assert.equal(existsSync(stale2), true); // untouched on Windows
+    rmSync(stale2, { force: true });
+    // Missing file: must not throw.
+    removeStaleEndpoint(join(tmp, "never-there.sock"), "linux");
+});
+test("killProcessGroup: POSIX path kills a detached process group", async () => {
+    const child = spawn("sleep", ["30"], { detached: true, stdio: "ignore" });
+    child.unref();
+    const pid = child.pid;
+    // Give the process a moment to be scheduled.
+    await new Promise((r) => setTimeout(r, 100));
+    killProcessGroup(pid, "SIGKILL", "linux");
+    const exited = await new Promise((resolve) => {
+        const t = setTimeout(() => resolve(false), 5000);
+        child.once("exit", () => {
+            clearTimeout(t);
+            resolve(true);
+        });
+    });
+    assert.equal(exited, true);
+});
+test("killProcessGroup: win32 branch on Linux swallows taskkill failure", () => {
+    // taskkill does not exist on Linux; the spawn must not throw.
+    assert.doesNotThrow(() => killProcessGroup(12345, "SIGKILL", "win32"));
+    assert.doesNotThrow(() => killProcessGroup(12345, "SIGTERM", "win32"));
+});
+test("killProcessGroup: POSIX path tolerates a dead pgid", () => {
+    assert.doesNotThrow(() => killProcessGroup(999_999, "SIGKILL", "linux"));
+});
+// ------------------------------------------------------------- liveness (win32)
+test("isProcessAlive: win32 branch uses signal-0 semantics (injected platform)", () => {
+    assert.equal(isProcessAlive(process.pid, undefined, "win32"), true);
+    // A start time can't be verified without /proc — pid must still count as
+    // alive (conservative; the pid-reuse defense is documented as absent).
+    assert.equal(isProcessAlive(process.pid, "9999", "win32"), true);
+    // 4194303 is the Windows ceiling; a pid that high is never in use here.
+    assert.equal(isProcessAlive(4_194_303, undefined, "win32"), false);
+});
+test("aliveBySignalZero: own pid alive, pid 1 alive (ours or EPERM), huge pid dead", () => {
+    assert.equal(aliveBySignalZero(process.pid), true);
+    // On Linux init is owned by root: signal 0 yields EPERM, which must count
+    // as alive. On a container where we are root, it trivially succeeds.
+    assert.equal(aliveBySignalZero(1), true);
+    assert.equal(aliveBySignalZero(4_194_303), false);
+});
+test("isProcessAlive: Linux branch still checks /proc start time", () => {
+    const st = processStartTime(process.pid);
+    assert.ok(st !== undefined, "/proc start time must be readable on Linux");
+    assert.equal(isProcessAlive(process.pid, st, "linux"), true);
+    assert.equal(isProcessAlive(process.pid, "9999", "linux"), false); // mismatch = reuse
+});
+test("jobAlive: win32 skips the process-group scan", () => {
+    assert.equal(jobAlive(process.pid, undefined, undefined, "win32"), true);
+    // Dead main pid: released even though a group scan would have been
+    // possible on Linux — Windows has no process groups.
+    assert.equal(jobAlive(4_194_303, process.pid, undefined, "win32"), false);
+    // pgid-only on win32: unknown => conservative keep.
+    assert.equal(jobAlive(undefined, 12345, undefined, "win32"), null);
+});
+test("jobAlive: Linux still scans process groups", () => {
+    assert.equal(jobAlive(process.pid, undefined, undefined, "linux"), true);
+    // pgid 1 exists but a dead pid + live foreign pgid keeps the job "alive"
+    // via the group scan — semantics unchanged on Linux.
+    assert.equal(jobAlive(4_194_303, 1, undefined, "linux"), true);
+    // Both dead => false on Linux (group 999999 has no members).
+    assert.equal(jobAlive(4_194_303, 999_999, undefined, "linux"), false);
+});
+// Clean up once everything finished.
+test("cleanup tmp dir", () => {
+    rmSync(tmp, { recursive: true, force: true });
+});

package/dist/test/testutil.js

@@ -8,7 +8,10 @@ import { join, dirname } from "node:path";
 import { connect } from "node:net";
 import { fileURLToPath } from "node:url";
 import { LLClient } from "../shared/client.js";
-const TMP_BASE = join(tmpdir(), "opencode");
+// Tests must never touch the user's real state dir. LL_TEST_TMP lets the
+// suite run on machines where /tmp/opencode is not writable (same override
+// as daemon.test.ts).
+const TMP_BASE = process.env.LL_TEST_TMP ?? join(tmpdir(), "opencode");
 mkdirSync(TMP_BASE, { recursive: true });
 export const daemonMainPath = join(dirname(fileURLToPath(import.meta.url)), "..", "core", "daemon-main.js");
 export const cliMainPath = join(dirname(fileURLToPath(import.meta.url)), "..", "cli", "main.js");

package/dist/test/wait-turn.test.d.ts

@@ -0,0 +1 @@
+export {};

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: