@aron98/load-lock 0.1.2 → 1.1.0

package/dist/dashboard/view.js

@@ -0,0 +1,214 @@
+// ---------------------------------------------------------------- formatters
+/** Compact human duration: "412ms", "3s", "4m 12s", "2h 05m", "3d 4h". */
+export function fmtDuration(ms) {
+    if (!Number.isFinite(ms))
+        return "–";
+    const neg = ms < 0;
+    let s = Math.floor(Math.abs(ms) / 1000);
+    let out;
+    if (s < 1)
+        out = `${Math.max(0, Math.round(Math.abs(ms)))}ms`;
+    else if (s < 60)
+        out = `${s}s`;
+    else if (s < 3600)
+        out = `${Math.floor(s / 60)}m ${String(s % 60).padStart(2, "0")}s`;
+    else if (s < 86400)
+        out = `${Math.floor(s / 3600)}h ${String(Math.floor((s % 3600) / 60)).padStart(2, "0")}m`;
+    else
+        out = `${Math.floor(s / 86400)}d ${Math.floor((s % 86400) / 3600)}h`;
+    return neg ? `-${out}` : out;
+}
+/** Byte counts: "12.4Gi", "512Mi", "3.4Ki". */
+export function fmtBytes(bytes) {
+    if (!Number.isFinite(bytes) || bytes < 0)
+        return "–";
+    const units = ["B", "Ki", "Mi", "Gi", "Ti"];
+    let v = bytes;
+    let u = 0;
+    while (v >= 1024 && u < units.length - 1) {
+        v /= 1024;
+        u++;
+    }
+    return `${v >= 100 || u === 0 ? Math.round(v) : v.toFixed(1)}${units[u]}`;
+}
+/** Local clock time HH:MM:SS. */
+export function fmtClock(ts) {
+    const d = new Date(ts);
+    return [d.getHours(), d.getMinutes(), d.getSeconds()].map((n) => String(n).padStart(2, "0")).join(":");
+}
+/** One-line label for a permit phase. */
+export function phaseLabel(p) {
+    switch (p) {
+        case "claimed":
+            return "claimed (must start)";
+        case "running_tracked":
+            return "running (tracked)";
+        case "running_untracked":
+            return "running (untracked)";
+    }
+}
+/** Truncate with ellipsis, keeping the head (ids, reasons). */
+export function trunc(s, max) {
+    if (s.length <= max)
+        return s;
+    return s.slice(0, Math.max(1, max - 1)) + "…";
+}
+export function agentName(e) {
+    return e.agentLabel || e.agentId;
+}
+// -------------------------------------------------------------- event text
+/** One-line human sentence for a daemon event (durable ids are kept). */
+export function eventText(ev) {
+    const who = ev.entry ? agentName(ev.entry) : ev.targetAgent && ev.targetAgent !== "*" ? ev.targetAgent : undefined;
+    const reason = ev.entry?.reason ? ` (${trunc(ev.entry.reason, 48)})` : "";
+    const w = who ? ` ${who}` : "";
+    const detail = ev.detail ? ` — ${ev.detail}` : "";
+    switch (ev.type) {
+        case "daemon_started":
+            return `daemon started${detail}`;
+        case "daemon_recovered":
+            return `daemon recovered after restart${detail}`;
+        case "granted":
+            return `granted ${ev.pool ?? ""}${w}${reason}`;
+        case "queued":
+            return `queued${w}${reason}`;
+        case "offered":
+            return `offered ${ev.pool ?? ""}${w} — awaiting claim${reason}`;
+        case "claimed":
+            return `claimed${w} — permit held${reason}`;
+        case "started":
+            return `started${w}: ${ev.detail ?? "execution began"}`;
+        case "released":
+            return `released ${ev.pool ?? ""}${w}${reason}${detail}`;
+        case "auto_released":
+            return `auto-released ${ev.pool ?? ""}${w}${detail}${reason}`;
+        case "reclaimed":
+            return `reclaimed ${ev.pool ?? ""}${w} — ${ev.detail ?? "permit revoked"}${reason}`;
+        case "offer_expired":
+            return `offer expired ${ev.pool ?? ""}${w} → paused (rejoin to requeue)`;
+        case "declined":
+            return `declined offer${w}${reason}`;
+        case "paused":
+            return `paused${w}${reason}`;
+        case "rejoined":
+            return `rejoined queue${w}${reason}`;
+        case "cancelled":
+            return `cancelled${w}${reason}`;
+        case "config_changed":
+            return `config changed: ${ev.detail ?? ""}`.trim();
+        default:
+            return `${String(ev.type)}${w}${detail}`;
+    }
+}
+function holderCard(e, now) {
+    const phase = e.phase ?? "claimed";
+    return {
+        requestId: e.requestId,
+        pool: e.pool,
+        agent: agentName(e),
+        agentId: e.agentId,
+        reason: e.reason,
+        weight: e.weight,
+        phase,
+        phaseLabel: phaseLabel(phase),
+        pid: e.pid,
+        pgid: e.pgid,
+        heldMs: now - e.since,
+        startDeadlineInMs: e.startDeadline !== undefined ? e.startDeadline - now : undefined,
+        leaseDeadlineInMs: e.leaseDeadline !== undefined ? e.leaseDeadline - now : undefined,
+    };
+}
+export function buildDashboardView(inps) {
+    const now = inps.now;
+    const pools = [];
+    for (const p of inps.status?.pools ?? []) {
+        const heldWeight = p.holders.reduce((a, h) => a + h.weight, 0);
+        const offeredWeight = p.offers.reduce((a, o) => a + o.weight, 0);
+        pools.push({
+            pool: p.pool,
+            capacity: p.capacity,
+            used: p.used,
+            heldWeight,
+            offeredWeight,
+            free: Math.max(0, p.capacity - p.used),
+            utilization: p.capacity > 0 ? Math.min(1, p.used / p.capacity) : 1,
+            holders: p.holders.map((h) => holderCard(h, now)),
+            offers: p.offers.map((o) => ({
+                requestId: o.requestId,
+                pool: o.pool,
+                agent: agentName(o),
+                agentId: o.agentId,
+                reason: o.reason,
+                weight: o.weight,
+                claimInMs: (o.offerExpiresAt ?? 0) - now,
+                expiresAt: o.offerExpiresAt ?? 0,
+            })),
+            queue: p.queue.map((q, i) => ({
+                requestId: q.requestId,
+                pool: q.pool,
+                agent: agentName(q),
+                agentId: q.agentId,
+                reason: q.reason,
+                weight: q.weight,
+                position: q.position ?? i + 1,
+                waitMs: now - q.since,
+            })),
+            paused: p.paused.map((q) => ({
+                requestId: q.requestId,
+                pool: q.pool,
+                agent: agentName(q),
+                agentId: q.agentId,
+                reason: q.reason,
+                weight: q.weight,
+                pausedMs: now - q.since,
+            })),
+        });
+    }
+    const d = inps.status?.daemon;
+    const machine = inps.inspect
+        ? {
+            cpuModel: inps.inspect.cpu.model,
+            logicalCores: inps.inspect.cpu.logicalCores,
+            effectiveCores: inps.inspect.cpu.effectiveCores,
+            cgroupVersion: inps.inspect.cpu.cgroupVersion,
+            cgroupCpuQuota: inps.inspect.cpu.cgroupCpuQuota,
+            loadavg: inps.inspect.cpu.loadavg,
+            loadPerEffectiveCore: inps.inspect.cpu.loadPerEffectiveCore,
+            memTotalBytes: inps.inspect.memory.totalBytes,
+            memAvailableBytes: inps.inspect.memory.availableBytes,
+            memEffectiveLimitBytes: inps.inspect.memory.effectiveLimitBytes,
+            loadPressure: inps.inspect.pressure.loadPressure,
+            memPressure: inps.inspect.pressure.memPressure,
+            note: inps.inspect.pressure.note,
+            suggestion: inps.inspect.loadLock.suggestion,
+        }
+        : null;
+    // Newest first; keep the tail (feed already bounds history length).
+    const evs = [...inps.events].reverse();
+    return {
+        now,
+        state: inps.state,
+        daemonRestartNote: inps.daemonRestartNote,
+        daemon: d
+            ? {
+                pid: d.pid,
+                startedAt: d.startedAt,
+                uptimeMs: now - d.startedAt,
+                protocolVersion: d.protocolVersion,
+                configVersion: inps.status?.config.version ?? 0,
+            }
+            : null,
+        pools,
+        events: evs.map((e) => ({
+            id: e.id,
+            ts: e.ts,
+            agoMs: now - e.ts,
+            type: e.type,
+            pool: e.pool,
+            text: eventText(e),
+        })),
+        latestEventId: inps.latestEventId,
+        machine,
+        lastSyncAt: inps.lastSyncAt,
+    };
+}

package/dist/mcp/server.d.ts

@@ -10,7 +10,8 @@
  * into the model's context. load-lock therefore relies on:
  *   (a) tool-boundary delivery — every acquire/claim/release/... response
  *       carries the agent's pending offers and queue positions;
- *   (b) bounded blocking wait in acquire (waitMs);
+ *   (b) bounded blocking wait in acquire (waitMs) and wait_for_turn
+ *       (the "sleep until it is my turn" tool);
  *   (c) harness-specific idle wakeup (hooks/plugins) where verified.
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

package/dist/mcp/server.js

@@ -10,7 +10,8 @@
  * into the model's context. load-lock therefore relies on:
  *   (a) tool-boundary delivery — every acquire/claim/release/... response
  *       carries the agent's pending offers and queue positions;
- *   (b) bounded blocking wait in acquire (waitMs);
+ *   (b) bounded blocking wait in acquire (waitMs) and wait_for_turn
+ *       (the "sleep until it is my turn" tool);
  *   (c) harness-specific idle wakeup (hooks/plugins) where verified.
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -19,6 +20,8 @@ import { z } from "zod";
 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 { 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).
 
 Pass a short reason and a stable op_key identifying the pending operation (duplicate acquires for the same op_key return the existing request — do not invent a new key while one is live). Set wait_ms (default a few seconds) to block briefly for capacity instead of returning queued immediately; keep doing light work while queued. You will receive an offer to claim when capacity frees. Never start heavy work while merely queued.`;
@@ -134,6 +137,51 @@ export function buildServer(opts) {
             entry: res.entry,
         });
     });
+    server.registerTool("wait_for_turn", {
+        title: "Sleep until it is your turn",
+        description: `Bounded blocking sleep for one of your queued/offered/paused requests: "sleep until it is my turn". Returns a STRUCTURED result on every path — never an error for a normal resolution:
+- granted: capacity reached you and the offer was AUTO-CLAIMED on your behalf (permit_token in entry, auto_claimed: true) — start the heavy work now;
+- still_queued: timed out; you are still queued — queue_position, queue_length and holders (who is ahead of you) included; call wait_for_turn again to keep sleeping;
+- paused: the offer expired or was declined meanwhile; next_action has rejoin instructions;
+- cancelled: the request was cancelled/declined/reclaimed meanwhile;
+- not_found: the request ended or the daemon restarted (queues are ephemeral); acquire again.
+Input: request_id (default: your oldest offered, then front-most queued, then oldest paused request), timeout_ms (default 600000, clamped to the machine's maxTurnWaitMs config — get_config shows the cap). timeout_ms 0 = check-only. The wait holds NO permit and NO capacity (it is light work); cancelling this call is safe and never strands anything — you simply stop sleeping and the request keeps its queue position. A daemon restart mid-wait resolves promptly with not_found + re-acquire instructions.`,
+        inputSchema: {
+            request_id: z.string().optional().describe("Request to watch (default: your oldest offered/front-most queued/oldest paused request)"),
+            timeout_ms: z.number().int().optional().describe("Bounded sleep (ms); default 600000, clamped to the machine's maxTurnWaitMs cap. 0 = check-only."),
+            agent_id: z.string().optional().describe("Override agent identity (rarely needed)"),
+        },
+    }, async (input, extra) => {
+        try {
+            const r = await waitForTurn({
+                client,
+                agentId: agentIdOf(input),
+                requestId: input.request_id,
+                timeoutMs: input.timeout_ms,
+                signal: extra?.signal,
+            });
+            return json({
+                state: r.state,
+                request_id: r.requestId,
+                auto_claimed: r.autoClaimed,
+                permit_token: r.state === "granted" ? r.entry?.permitToken : undefined,
+                waited_ms: r.waitedMs,
+                effective_wait_ms: r.effectiveWaitMs,
+                entry: r.entry,
+                queue_position: r.queuePosition,
+                queue_length: r.queueLength,
+                holders: r.holders,
+                next_action: r.nextAction,
+                detail: r.detail,
+            });
+        }
+        catch (err) {
+            if (err instanceof WaitAbortedError) {
+                return json({ state: "aborted", detail: "wait cancelled by the harness/caller; the request keeps its queue position" });
+            }
+            throw err;
+        }
+    });
     server.registerTool("pending", {
         title: "Your offers/queue/permits",
         description: "List your outstanding offers (claim these NOW — they expire), queue positions, paused and held requests.",
@@ -164,6 +212,7 @@ export function buildServer(opts) {
                 pools: z.record(z.string(), z.object({ capacity: z.number().int() })).optional(),
                 offer_timeout_ms: z.number().int().optional(),
                 max_wait_ms: z.number().int().optional(),
+                max_turn_wait_ms: z.number().int().optional(),
                 start_timeout_ms: z.number().int().optional(),
                 untracked_lease_ms: z.number().int().optional(),
                 guidance: z
@@ -185,6 +234,7 @@ export function buildServer(opts) {
             ...input.changes,
             offerTimeoutMs: input.changes.offer_timeout_ms,
             maxWaitMs: input.changes.max_wait_ms,
+            maxTurnWaitMs: input.changes.max_turn_wait_ms,
             startTimeoutMs: input.changes.start_timeout_ms,
             untrackedLeaseMs: input.changes.untracked_lease_ms,
             guidance: input.changes.guidance
@@ -265,12 +315,7 @@ export function buildServer(opts) {
             });
         }
         catch (err) {
-            try {
-                process.kill(-child.pid, "SIGKILL");
-            }
-            catch {
-                /* already gone */
-            }
+            killProcessGroup(child.pid, "SIGKILL");
             return json({
                 error: `permit no longer startable (${err.message}); job killed before doing work; acquire again`,
             });
@@ -309,20 +354,10 @@ export function buildServer(opts) {
         if (!job)
             return json({ error: "unknown job_id" });
         if (!job.exited) {
-            try {
-                process.kill(-job.child.pid, "SIGTERM");
-            }
-            catch {
-                /* already gone */
-            }
+            killProcessGroup(job.child.pid, "SIGTERM");
             setTimeout(() => {
                 if (!job.exited) {
-                    try {
-                        process.kill(-job.child.pid, "SIGKILL");
-                    }
-                    catch {
-                        /* already gone */
-                    }
+                    killProcessGroup(job.child.pid, "SIGKILL");
                 }
             }, 5_000).unref?.();
         }

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.\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.\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

@@ -28,6 +28,9 @@ Rules:
 3. If you are queued: keep working on light tasks. When you receive an offer
    (in any load-lock tool result or a wakeup message), claim it promptly —
    offers expire (default 30s) and capacity passes to the next waiter.
+   Out of light work? Sleep honestly with wait_for_turn (MCP/plugin) or
+   'load-lock wait' (CLI) — a bounded sleep until your turn that
+   auto-claims and holds no capacity.
 4. Start heavy work ONLY after acquire/claim succeeds. Never start heavy work
    on a "queued" result; never treat a notification as authorization.
 5. Hold the permit until the heavy process actually finishes — including when

package/dist/shared/client.d.ts

@@ -8,6 +8,8 @@ export declare class LLClient {
     private nextId;
     private pending;
     private eventCb;
+    /** Optional disconnect notifications (dashboard feeds and other watchers). */
+    private disconnectCbs;
     private buf;
     private opts;
     constructor(opts?: ClientOptions);
@@ -16,12 +18,20 @@ export declare class LLClient {
     connect(): Promise<void>;
     private tryConnect;
     private attach;
+    private fireDisconnect;
     private failAll;
     private ensureSock;
     /** Issue one RPC. Reconnects once if the connection was lost. */
     request<T = any>(method: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<T>;
     /** Subscribe to daemon events targeted at agentId (or "*" for all). */
     watch(agentId: string, onEvent: (ev: Record<string, unknown>) => void): Promise<void>;
+    /**
+     * Register a callback fired whenever the daemon connection drops (socket
+     * closed or errored) — including after later reconnects; the callback
+     * stays registered until its unregister function is called. Dashboard
+     * feeds use this to reconnect and resume via the durable event cursor.
+     */
+    onDisconnect(cb: () => void): () => void;
     close(): void;
 }
 /** Idempotently ensure a daemon is running and listening on `sockPath`. */

package/dist/shared/client.js

@@ -1,13 +1,17 @@
 /**
- * NDJSON-over-UDS client for the load-lock daemon, shared by the CLI, the
+ * NDJSON transport client for the load-lock daemon, shared by the CLI, the
  * MCP server, and harness hook scripts. The OpenCode plugin ships a
  * self-contained copy of this logic (see adapters/opencode).
  *
- * Auto-spawn: if the daemon socket is absent, exactly one client becomes the
- * spawner (serialized by a mkdir-based lock — atomic on POSIX) and starts a
- * detached daemon; losers wait for the socket to appear. The freshly spawned
- * daemon itself re-checks the socket before binding, so a double-spawn is
- * harmless (the loser exits).
+ * Transport: Unix-domain socket on POSIX, named pipe (`\\.\pipe\load-lock`)
+ * on Windows — Node's `net` handles both transparently, so only endpoint
+ * resolution differs (see shared/transport.ts).
+ *
+ * Auto-spawn: if the daemon endpoint is absent, exactly one client becomes
+ * the spawner (serialized by a mkdir-based lock — atomic on POSIX and on
+ * NTFS) and starts a detached daemon; losers wait for the endpoint to
+ * appear. The freshly spawned daemon itself re-checks the endpoint before
+ * binding, so a double-spawn is harmless (the loser exits).
  */
 import { connect } from "node:net";
 import { existsSync, mkdirSync, rmSync, writeFileSync, readFileSync } from "node:fs";
@@ -17,11 +21,14 @@ import { spawn } from "node:child_process";
 import { setTimeout as delay } from "node:timers/promises";
 import { ProtocolError } from "./protocol.js";
 import { socketPath as defaultSocket, stateDir as defaultStateDir } from "../core/persist.js";
+import { probeTransport } from "./transport.js";
 export class LLClient {
     sock = null;
     nextId = 1;
     pending = new Map();
     eventCb = null;
+    /** Optional disconnect notifications (dashboard feeds and other watchers). */
+    disconnectCbs = [];
     buf = "";
     opts;
     constructor(opts = {}) {
@@ -94,12 +101,27 @@ export class LLClient {
         sock.on("error", () => {
             this.failAll(new ProtocolError("unavailable", "daemon connection lost"));
             this.sock = null;
+            this.fireDisconnect();
         });
         sock.on("close", () => {
             this.failAll(new ProtocolError("unavailable", "daemon connection closed"));
             this.sock = null;
+            this.fireDisconnect();
         });
     }
+    fireDisconnect() {
+        // Callbacks stay registered: a long-lived consumer (e.g. a dashboard
+        // feed) reconnects and must keep hearing about later disconnects.
+        // Copy first — a callback may (un)register during iteration.
+        for (const cb of [...this.disconnectCbs]) {
+            try {
+                cb();
+            }
+            catch {
+                /* consumer errors must not break reconnect bookkeeping */
+            }
+        }
+    }
     failAll(err) {
         for (const p of this.pending.values())
             p.reject(err);
@@ -139,6 +161,18 @@ export class LLClient {
         this.eventCb = onEvent;
         await this.request("watch", { agentId });
     }
+    /**
+     * Register a callback fired whenever the daemon connection drops (socket
+     * closed or errored) — including after later reconnects; the callback
+     * stays registered until its unregister function is called. Dashboard
+     * feeds use this to reconnect and resume via the durable event cursor.
+     */
+    onDisconnect(cb) {
+        this.disconnectCbs.push(cb);
+        return () => {
+            this.disconnectCbs = this.disconnectCbs.filter((c) => c !== cb);
+        };
+    }
     close() {
         this.sock?.destroy();
         this.sock = null;
@@ -205,14 +239,7 @@ export async function ensureDaemon(stateDir, sockPath) {
     }
 }
 function probe(sockPath) {
-    return new Promise((resolve) => {
-        const s = connect(sockPath);
-        s.once("connect", () => {
-            s.end();
-            resolve(true);
-        });
-        s.once("error", () => resolve(false));
-    });
+    return probeTransport(sockPath);
 }
 /** One-shot helper: connect (auto-spawning), run fn, close. */
 export async function withClient(fn, opts = {}) {

package/dist/shared/protocol.d.ts

@@ -29,6 +29,12 @@ export interface MachineConfig {
     offerTimeoutMs: number;
     /** Upper bound for bounded blocking waits in acquire (advisory). */
     maxWaitMs: number;
+    /**
+     * Upper bound for ONE wait_for_turn call ("sleep until it is my turn",
+     * issue #11), in milliseconds. Callers' timeout_ms is clamped to this —
+     * operators tune how long an agent may block in a single tool call.
+     */
+    maxTurnWaitMs: number;
     /**
      * Start deadline: after a permit is claimed/granted, execution must begin
      * (run_with_permit / attach_pid / mark_started) within this window, or the
@@ -61,6 +67,7 @@ export interface ConfigChange {
     pools?: Record<string, PoolConfig>;
     offerTimeoutMs?: number;
     maxWaitMs?: number;
+    maxTurnWaitMs?: number;
     startTimeoutMs?: number;
     untrackedLeaseMs?: number;
     guidance?: {
@@ -162,6 +169,7 @@ export interface StatusResult {
         pools: Record<string, PoolConfig>;
         offerTimeoutMs: number;
         maxWaitMs: number;
+        maxTurnWaitMs: number;
         startTimeoutMs: number;
         untrackedLeaseMs: number;
     };
@@ -319,6 +327,27 @@ export interface EventsResult {
     events: MachineEvent[];
     latestEventId: number;
 }
+export type WaitForTurnState = "granted" | "still_queued" | "paused" | "cancelled" | "not_found";
+export interface WaitForTurnResult {
+    state: WaitForTurnState;
+    requestId?: string;
+    /** True when THIS wait claimed the offer on the caller's behalf (explicit auto-claim). */
+    autoClaimed?: 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;
+    /** Owner snapshot of the request at resolution time (carries permit_token when granted). */
+    entry?: OwnerEntrySnapshot;
+    /** 1-based FIFO position (still_queued). */
+    queuePosition?: number;
+    /** Queue depth of the request's pool (still_queued). */
+    queueLength?: number;
+    /** Who holds the pool's capacity (still_queued) — the agents ahead of you. */
+    holders?: EntrySnapshot[];
+    nextAction: string;
+    detail?: string;
+}
 /** Recovery diagnostics: held permits with holder + job information. */
 export interface HolderDiag {
     entry: EntrySnapshot;

package/dist/shared/transport.d.ts

@@ -0,0 +1,40 @@
+export declare const DEFAULT_PIPE_NAME = "load-lock";
+export declare function isWindows(platform?: NodeJS.Platform): boolean;
+/** Windows named-pipe endpoint for the given pipe name. */
+export declare function namedPipePath(name?: string): string;
+/**
+ * Resolve the state directory. Precedence: explicit override >
+ * LOAD_LOCK_STATE_DIR > platform default (POSIX: XDG_STATE_HOME or
+ * ~/.local/state; Windows: %LOCALAPPDATA% or %USERPROFILE%\AppData\Local),
+ * each + "/load-lock". Pure function of its arguments so tests can
+ * exercise the Windows branches on Linux.
+ */
+export declare function resolveStateDir(platform: NodeJS.Platform, env: NodeJS.ProcessEnv, override?: string): string;
+/**
+ * Resolve the transport endpoint. Precedence: explicit override >
+ * LOAD_LOCK_SOCKET > platform default (Windows: named pipe; POSIX:
+ * <state dir>/daemon.sock). The same precedence rules are used by every
+ * caller, so the CLI, MCP server, hooks, and the daemon all agree on the
+ * endpoint without further coordination.
+ */
+export declare function resolveSocketPath(platform: NodeJS.Platform, env: NodeJS.ProcessEnv, override?: string): string;
+/**
+ * Probe whether a daemon is listening on the endpoint (UDS or named
+ * pipe — Node's connect handles both). Never throws.
+ */
+export declare function probeTransport(path: string): Promise<boolean>;
+/**
+ * Remove a stale endpoint left behind by a crashed daemon.
+ * POSIX: unlink the socket file (a crashed daemon leaves it behind).
+ * Windows: no-op — named pipes are kernel objects and vanish when the
+ * last handle closes, so there is nothing to clean up.
+ */
+export declare function removeStaleEndpoint(path: string, platform?: NodeJS.Platform): void;
+/**
+ * Terminate a job process tree. POSIX: negative-pid group kill (callers
+ * spawn jobs detached, so pgid === child pid). Windows: `taskkill /PID
+ * <pid> /T` (tree kill; add /F for the uncatchable SIGKILL equivalent —
+ * plain taskkill posts WM_CLOSE, which console processes don't handle).
+ * Fire-and-forget; never throws.
+ */
+export declare function killProcessGroup(pid: number, signal: "SIGTERM" | "SIGINT" | "SIGKILL", platform?: NodeJS.Platform): void;