@aron98/load-lock 0.1.2 → 1.1.0

package/dist/cli/main.js

@@ -7,12 +7,15 @@
  */
 import { spawn } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
 import { LLClient, withClient } from "../shared/client.js";
 import { ProtocolError } from "../shared/protocol.js";
+import { waitForTurn } from "../shared/wait-turn.js";
+import { stateDir, socketPath } from "../core/persist.js";
+import { isWindows, probeTransport, killProcessGroup } from "../shared/transport.js";
 import { installCommand, uninstallCommand } from "./install.js";
 import { hookCommand } from "./hook.js";
+import { topCommand } from "./top.js";
 // ---------------------------------------------------------------- arg parsing
 const argv = process.argv.slice(2);
 let flags = {};
@@ -58,7 +61,84 @@ function defaultAgent() {
     return (process.env.LOAD_LOCK_AGENT ||
         "cli:" + (process.env.USER || "user") + "@" + (process.env.HOSTNAME || "localhost"));
 }
+const HELP_GROUPS = [
+    {
+        title: "permit operations",
+        items: [
+            { names: ["acquire"], desc: "request a permit: --pool --op-key --reason [--wait-ms] [--no-queue]" },
+            { names: ["claim"], desc: "claim an offered permit before its window expires: --offer <token>" },
+            { names: ["release"], desc: "release a held permit: --permit <token> [--outcome success|failure]" },
+            { names: ["cancel"], desc: "cancel a queued/offered/paused request: --id <request-id> [--admin]" },
+            { names: ["rejoin"], desc: "rejoin the queue after your offer expired or you declined: --id <request-id>" },
+            { names: ["mark-started"], desc: "mark a permit as started when no pid can be attached: --permit <token>" },
+            { names: ["attach-pid"], desc: "tie a running process to a permit (auto-release on exit): --permit <token> --pid <pid>" },
+        ],
+    },
+    {
+        title: "waiting & running",
+        items: [
+            { names: ["wait"], desc: "sleep until a queued request's turn, then auto-claim the offer: --id <request-id> [--timeout <ms>]" },
+            { names: ["run"], desc: "acquire (or reuse) a permit and run a command under it: run [--permit <token> | acquire flags] -- <cmd>" },
+        ],
+    },
+    {
+        title: "read-only",
+        items: [
+            { names: ["status"], desc: "pools, holders, offers, queue — the machine-wide view" },
+            { names: ["pending"], desc: "your outstanding offers, queue entries and paused requests" },
+            { names: ["events"], desc: "durable event log: [--since <id>] [--follow]" },
+            { names: ["inspect", "machine"], desc: "machine resources (incl. cgroup limits) and current pressure" },
+            { names: ["config", "get-config"], desc: "current configuration" },
+            { names: ["configure"], desc: "change configuration (compare-and-swap): --reason required" },
+            { names: ["dashboard", "top"], desc: "full-screen live dashboard, read-only (never acquires): [--once]" },
+        ],
+    },
+    {
+        title: "service & diagnostics",
+        items: [
+            { names: ["service"], desc: "daemon lifecycle: start | stop | status" },
+            { names: ["doctor"], desc: "health report: state dir, socket, daemon, machine" },
+            { names: ["recover"], desc: "list held permits with diagnostics; recover force-release --id <request-id>" },
+        ],
+    },
+    {
+        title: "setup & docs",
+        items: [
+            { names: ["install"], desc: "install the load-lock adapter for a harness: --harness <name>" },
+            { names: ["uninstall"], desc: "remove what install added: --harness <name>" },
+            { names: ["hook"], desc: "harness hook handlers (called by integrations, not humans)" },
+            { names: ["agent-guide"], desc: "print the full agent guide" },
+            { names: ["help"], desc: "this usage; also bare load-lock, --help, -h; help <command> for one line" },
+        ],
+    },
+];
+function displayName(item) {
+    return item.names[0] + (item.names.length > 1 ? ` (${item.names.slice(1).join(", ")})` : "");
+}
+const HELP_PAD = Math.max(...HELP_GROUPS.flatMap((g) => g.items.map((i) => displayName(i).length)));
+function helpLine(item) {
+    return `  ${displayName(item).padEnd(HELP_PAD)} ${item.desc}`;
+}
+/** Grouped one-screen usage, printed by `help`, bare `load-lock`, `--help`/`-h`. */
+function usage() {
+    const lines = [
+        "load-lock — machine-wide heavy-work budget shared by all coding agents",
+        "usage: load-lock <command> [flags]        (--json works on read commands)",
+    ];
+    for (const g of HELP_GROUPS) {
+        lines.push("", `${g.title}:`);
+        for (const item of g.items)
+            lines.push(helpLine(item));
+    }
+    lines.push("", "exit codes: 0 ok, 64 usage, 65 protocol, 68 not granted yet, 69 offer/claim failed, 70 internal");
+    process.stdout.write(lines.join("\n") + "\n");
+}
 async function main() {
+    // `--help`, `-h` and a bare `load-lock` all print the same usage as `help`.
+    if (f["help"] !== undefined || cmd === "-h" || (positional.length === 0 && argv.length === 0)) {
+        usage();
+        return;
+    }
     switch (cmd) {
         // ------------------------------------------------------------- read-only
         case "status": {
@@ -81,6 +161,30 @@ async function main() {
             });
             return;
         }
+        // ------------------------------------------------------------- dashboard
+        case "dashboard":
+        case "top": {
+            // Full-screen live dashboard (read-only, never acquires a permit).
+            // `dashboard` is the primary name; `top` stays as a hidden compat
+            // alias. Falls back to a single rendered frame when stdout is not a
+            // TTY (or with --once).
+            await topCommand({ once: B("once") });
+            return;
+        }
+        case "help": {
+            // `load-lock help` — grouped one-screen usage. `help <command>` is
+            // the optional per-command form: just that command's one-liner.
+            const topic = rest[0];
+            if (topic === undefined) {
+                usage();
+                return;
+            }
+            const item = HELP_GROUPS.flatMap((g) => g.items).find((i) => i.names.includes(topic));
+            if (!item)
+                fail(`help: unknown command "${topic}" — run "load-lock help" for the full list`);
+            process.stdout.write(`load-lock ${item.names[0]} — ${item.desc}\n`);
+            return;
+        }
         case "inspect":
         case "machine":
             out(await withClient((c) => c.request("inspect", {})));
@@ -108,6 +212,8 @@ async function main() {
                     changes.offerTimeoutMs = N("offer-timeout-ms", 0);
                 if (S("max-wait-ms"))
                     changes.maxWaitMs = N("max-wait-ms", 0);
+                if (S("max-turn-wait-ms"))
+                    changes.maxTurnWaitMs = N("max-turn-wait-ms", 0);
                 if (S("start-timeout-ms"))
                     changes.startTimeoutMs = N("start-timeout-ms", 0);
                 if (S("untracked-lease-ms"))
@@ -115,7 +221,7 @@ async function main() {
                 if (S("heavy-work-heuristic"))
                     changes.guidance = { heavyWorkHeuristic: S("heavy-work-heuristic") };
                 if (!Object.keys(changes).length)
-                    fail("configure: no changes given (--capacity, --offer-timeout-ms, --max-wait-ms, --start-timeout-ms, --untracked-lease-ms, --heavy-work-heuristic)");
+                    fail("configure: no changes given (--capacity, --offer-timeout-ms, --max-wait-ms, --max-turn-wait-ms, --start-timeout-ms, --untracked-lease-ms, --heavy-work-heuristic)");
                 out(await c.request("configure", { expectedVersion: expected, changes, reason, author }));
             });
             return;
@@ -196,55 +302,24 @@ async function main() {
         case "wait": {
             // Watches a queued request; auto-claims the offer when capacity is
             // handed to it and prints the permit token. Honest bounded blocking
-            // for scriptable flows (aider, plain shell scripts).
+            // for scriptable flows (aider, plain shell scripts). Shares the exact
+            // implementation with the MCP wait_for_turn tool and the OpenCode
+            // plugin (src/shared/wait-turn.ts).
             const id = S("id") || fail("wait: --id <request-id> required");
             const timeoutMs = N("timeout", 600_000);
             const agent = S("agent", defaultAgent());
             const c = new LLClient();
             await c.connect();
             try {
-                let last = 0;
-                let resolved = false;
-                const permit = await new Promise((resolve) => {
-                    const finish = (v) => {
-                        if (!resolved) {
-                            resolved = true;
-                            resolve(v);
-                        }
-                    };
-                    const timer = timeoutMs > 0 ? setTimeout(() => finish(null), timeoutMs) : null;
-                    void (async () => {
-                        while (!resolved) {
-                            try {
-                                const r = (await c.request("events", { sinceEventId: last, agentId: agent }));
-                                last = r.latestEventId;
-                                for (const ev of r.events) {
-                                    if (ev.entry?.requestId !== id)
-                                        continue;
-                                    if (ev.type === "offered" && ev.offerToken) {
-                                        const claimed = (await c.request("claim", { offerToken: ev.offerToken }));
-                                        if (timer)
-                                            clearTimeout(timer);
-                                        finish(claimed.entry.permitToken);
-                                    }
-                                    else if (ev.type === "cancelled" || ev.type === "paused" || ev.type === "reclaimed") {
-                                        if (timer)
-                                            clearTimeout(timer);
-                                        finish(null);
-                                    }
-                                }
-                            }
-                            catch {
-                                /* transient; retry */
-                            }
-                            await new Promise((r2) => setTimeout(r2, 200));
-                        }
-                    })();
-                });
-                if (!permit)
-                    fail("wait: timed out or the request was cancelled/paused/reclaimed", 69);
-                out({ permit_token: permit });
-                return;
+                const r = await waitForTurn({ client: c, agentId: agent, requestId: id, timeoutMs });
+                if (r.state === "granted" && r.entry?.permitToken) {
+                    out({ permit_token: r.entry.permitToken, state: r.state, request_id: r.requestId, auto_claimed: r.autoClaimed ?? false });
+                    return;
+                }
+                out({ state: r.state, request_id: r.requestId, detail: r.detail ?? r.nextAction });
+                if (r.state === "still_queued")
+                    fail(`wait: still queued (position ${r.queuePosition ?? "?"}) after ${r.waitedMs}ms`, 68);
+                fail(`wait: request is ${r.state.replace("_", " ")} — ${r.nextAction}`, 69);
             }
             finally {
                 c.close();
@@ -264,7 +339,7 @@ async function main() {
             const sub = rest[0] ?? "status";
             if (sub === "stop") {
                 // Connect and ask... simplest: SIGTERM via daemon.json pid.
-                const dir = process.env.LOAD_LOCK_STATE_DIR || join(process.env.HOME ?? "~", ".local", "state", "load-lock");
+                const dir = stateDir();
                 try {
                     const info = JSON.parse(readFileSync(join(dir, "daemon.json"), "utf8"));
                     process.kill(info.pid, "SIGTERM");
@@ -291,9 +366,13 @@ async function main() {
             const report = {};
             report.node = process.version;
             report.platform = process.platform;
-            const dir = process.env.LOAD_LOCK_STATE_DIR || join(homedir(), ".local", "state", "load-lock");
+            const dir = stateDir();
             report.stateDir = dir;
-            report.socketExists = existsSync(join(dir, "daemon.sock"));
+            const sock = socketPath();
+            report.socket = sock;
+            // Named pipes are kernel objects, not filesystem entries — probe by
+            // connecting on Windows; on POSIX a file check is enough.
+            report.socketExists = isWindows() ? await probeTransport(sock) : existsSync(sock);
             report.configExists = existsSync(join(dir, "config.json"));
             report.journalExists = existsSync(join(dir, "journal.json"));
             try {
@@ -356,7 +435,7 @@ async function main() {
             return;
         }
         default:
-            fail(`unknown command "${cmd}". Commands: status, inspect, config, pending, events, acquire, claim, release, cancel, rejoin, mark-started, attach-pid, wait, run, service, doctor, recover, install, uninstall, hook, agent-guide`);
+            fail(`unknown command "${cmd}" — run "load-lock help" for the list of commands`);
     }
 }
 // ------------------------------------------------------------------ run helper
@@ -416,21 +495,11 @@ async function runWithPermit(jobArgv) {
             await client.request("start_job", { permitToken, pid: child.pid, pgid });
         }
         catch (err) {
-            try {
-                process.kill(-pgid, "SIGKILL");
-            }
-            catch {
-                /* already gone */
-            }
+            killProcessGroup(pgid, "SIGKILL");
             fail(`permit no longer startable (${err.message}); job not started`, 69);
         }
         const forward = (sig) => {
-            try {
-                process.kill(-pgid, sig);
-            }
-            catch {
-                /* already gone */
-            }
+            killProcessGroup(pgid, sig);
         };
         process.on("SIGTERM", () => forward("SIGTERM"));
         process.on("SIGINT", () => forward("SIGINT"));

package/dist/cli/top.d.ts

@@ -0,0 +1,7 @@
+export interface TopOptions {
+    /** Render one frame and exit (also implied when stdout is not a TTY). */
+    once?: boolean;
+    /** Local re-render cadence for countdowns (default 500 ms). */
+    tickMs?: number;
+}
+export declare function topCommand(opts?: TopOptions): Promise<void>;

package/dist/cli/top.js

@@ -0,0 +1,99 @@
+/**
+ * `load-lock dashboard` (hidden compat alias: `load-lock top`) — portable,
+ * zero-dependency full-screen terminal dashboard for the machine-wide
+ * budget. Uses the library's own client + protocol
+ * (never scrapes CLI output); live updates come from the `watch` event
+ * stream, with reconnect + event-cursor resume across daemon restarts.
+ *
+ * Read-only. The viewer itself is light work — it never acquires a permit.
+ */
+import { DashboardFeed } from "../dashboard/feed.js";
+import { renderFrame } from "../dashboard/frame.js";
+import { LLClient } from "../shared/client.js";
+const HIDE_CURSOR = "\x1b[?25l";
+const SHOW_CURSOR = "\x1b[?25h";
+const ALT_SCREEN = "\x1b[?1049h";
+const LEAVE_ALT = "\x1b[?1049l";
+export async function topCommand(opts = {}) {
+    const once = opts.once || !process.stdout.isTTY;
+    const client = new LLClient();
+    const feed = new DashboardFeed(client);
+    try {
+        await feed.start();
+        if (once) {
+            const frame = renderFrame(feed.view(), process.stdout.columns || 100, 1000);
+            process.stdout.write(frame.join("\n") + "\n");
+            return;
+        }
+        await runLive(feed, opts);
+    }
+    finally {
+        await feed.stop();
+    }
+}
+async function runLive(feed, opts) {
+    const out = process.stdout;
+    const tickMs = Math.max(100, opts.tickMs ?? 500);
+    let stopped = false;
+    const paint = () => {
+        const width = out.columns || 100;
+        const height = out.rows || 40;
+        const frame = renderFrame(feed.view(), width, Math.max(1, height - 1));
+        // Pad to full height so old content never lingers after shrinking.
+        while (frame.length < height - 1)
+            frame.push("");
+        const body = frame.map((l) => l + "\x1b[K").join("\n");
+        out.write(`\x1b[H\x1b[2J${body}\n`);
+    };
+    // The feed signals change asynchronously; the tick loop below repaints on
+    // every tick anyway (cheap string render) so new events and countdowns
+    // both appear promptly without a paint storm per event burst.
+    out.write(ALT_SCREEN + HIDE_CURSOR);
+    out.write("\x1b[H\x1b[2J");
+    process.stdin.setRawMode?.(true);
+    process.stdin.resume();
+    const restore = () => {
+        process.stdin.setRawMode?.(false);
+        out.write(SHOW_CURSOR + LEAVE_ALT);
+    };
+    let exiting = false;
+    const quit = () => {
+        if (exiting)
+            return;
+        exiting = true;
+        restore();
+        stopped = true;
+        process.stdin.pause();
+    };
+    const onKey = (data) => {
+        const k = data.toString("utf8");
+        if (k === "q" || k === "Q" || k === "\x1b" || k === "\x03")
+            quit();
+        else if (k === "r" || k === "R")
+            void feed.resync().catch(() => { });
+    };
+    process.stdin.on("data", onKey);
+    const onResize = () => paint();
+    out.on("resize", onResize);
+    const onSignal = () => {
+        quit();
+    };
+    process.on("SIGINT", onSignal);
+    process.on("SIGTERM", onSignal);
+    paint();
+    try {
+        while (!stopped) {
+            await new Promise((r) => setTimeout(r, tickMs));
+            if (stopped)
+                continue;
+            paint(); // cheap local re-render keeps countdowns ticking and shows new events
+        }
+    }
+    finally {
+        restore();
+        process.stdin.removeListener("data", onKey);
+        out.removeListener("resize", onResize);
+        process.removeListener("SIGINT", onSignal);
+        process.removeListener("SIGTERM", onSignal);
+    }
+}

package/dist/core/daemon.d.ts

@@ -22,6 +22,10 @@ export declare class Daemon {
     machine: Machine;
     server: Server | null;
     private watchers;
+    /** All open client connections — destroyed on stop() so a graceful
+     *  shutdown cuts waiting clients loose (they reconnect + detect the
+     *  restart via the event cursor) and the process can exit promptly. */
+    private conns;
     private waiters;
     private sentEventId;
     private stateDirPath;
@@ -36,7 +40,11 @@ export declare class Daemon {
         recover?: boolean;
     });
     start(): Promise<void>;
-    /** Bind the socket, replacing it only if it is verifiably stale. */
+    /**
+     * Bind the endpoint, replacing it only if it is verifiably stale.
+     * Windows: named pipes are kernel objects — no stale file can exist, so
+     * just refuse if another daemon owns the pipe.
+     */
     private claimSocket;
     stop(): void;
     private onConnection;
@@ -65,15 +73,28 @@ export declare class Daemon {
      */
     private sweep;
 }
-/** Linux: /proc/<pid>/stat field 22 (starttime) defeats pid reuse. */
-export declare function isProcessAlive(pid: number, expectedStartTime?: string): boolean | null;
+/**
+ * Liveness via signal 0 — the /proc-less fallback (macOS, Windows).
+ * EPERM counts as alive: the process exists but is not signalable by us.
+ */
+export declare function aliveBySignalZero(pid: number): boolean;
+/**
+ * Linux: /proc/<pid>/stat field 22 (starttime) defeats pid reuse.
+ * Windows: no /proc and no start time — signal-0 fallback only; the
+ * pid-reuse defense is unavailable there (documented limitation).
+ * macOS: /proc is absent, so the signal-0 fallback applies too.
+ */
+export declare function isProcessAlive(pid: number, expectedStartTime?: string, platform?: NodeJS.Platform): boolean | null;
 /**
  * Job liveness: a tracked job is alive if its pid is alive (start-time
  * matched) OR any process in its process group is alive — covering
  * subprocesses and background jobs that outlive their parent. Returns
  * true/false on Linux; on platforms without /proc the pgid scan is
  * unavailable and the result may be null (unknown => conservative keep).
+ * Windows: no process groups — only the main pid is checked, so a permit
+ * is released once the main pid dies even if children survive (documented
+ * limitation; adapters should kill the tree via taskkill /T).
  */
-export declare function jobAlive(pid?: number, pgid?: number, pidStartTime?: string): boolean | null;
+export declare function jobAlive(pid?: number, pgid?: number, pidStartTime?: string, platform?: NodeJS.Platform): boolean | null;
 /** Read the Linux start time of a pid (pid-reuse-safe association). */
 export declare function processStartTime(pid: number): string | undefined;

package/dist/core/daemon.js

@@ -16,7 +16,7 @@
  * All state mutations run on one event loop => every RPC is atomic wrt all
  * others; start_job is therefore atomic wrt reclamation.
  */
-import { connect, createServer } from "node:net";
+import { createServer } from "node:net";
 import { existsSync, mkdirSync, unlinkSync, writeFileSync, readFileSync, rmSync } from "node:fs";
 import { readdirSync } from "node:fs";
 import { join } from "node:path";
@@ -24,10 +24,15 @@ import { Machine } from "./state.js";
 import { loadState, saveState, loadJournal, saveJournal, socketPath as defaultSocket, stateDir as defaultStateDir } from "./persist.js";
 import { inspectMachine } from "./sysinfo.js";
 import { ProtocolError } from "../shared/protocol.js";
+import { isWindows, probeTransport } from "../shared/transport.js";
 export class Daemon {
     machine;
     server = null;
     watchers = new Set();
+    /** All open client connections — destroyed on stop() so a graceful
+     *  shutdown cuts waiting clients loose (they reconnect + detect the
+     *  restart via the event cursor) and the process can exit promptly. */
+    conns = new Set();
     waiters = new Map();
     sentEventId;
     stateDirPath;
@@ -70,10 +75,20 @@ export class Daemon {
         this.sweepTimer.unref?.();
         this.sweep(); // catch anything that expired while we were down
     }
-    /** Bind the socket, replacing it only if it is verifiably stale. */
+    /**
+     * Bind the endpoint, replacing it only if it is verifiably stale.
+     * Windows: named pipes are kernel objects — no stale file can exist, so
+     * just refuse if another daemon owns the pipe.
+     */
     async claimSocket() {
+        if (isWindows()) {
+            if (await probeTransport(this.socketPath)) {
+                throw new ProtocolError("denied", `another daemon is already listening on ${this.socketPath}`);
+            }
+            return;
+        }
         if (existsSync(this.socketPath)) {
-            const live = await probeUnixSocket(this.socketPath);
+            const live = await probeTransport(this.socketPath);
             if (live) {
                 throw new ProtocolError("denied", `another daemon is already listening on ${this.socketPath}`);
             }
@@ -96,13 +111,23 @@ export class Daemon {
         for (const w of this.watchers)
             w.socket.destroy();
         this.watchers.clear();
+        // Cut every client loose too: a graceful stop must not leave a zombie
+        // serving already-connected clients while the socket path moves on.
+        // Clients see the disconnect, reconnect, and detect the restart.
+        for (const s of this.conns)
+            s.destroy();
+        this.conns.clear();
         this.server?.close();
-        try {
-            if (existsSync(this.socketPath))
-                unlinkSync(this.socketPath);
-        }
-        catch {
-            /* ignore */
+        if (!isWindows()) {
+            // Windows: the named pipe is a kernel object and vanishes on close;
+            // touching the pipe path from the filesystem side can block.
+            try {
+                if (existsSync(this.socketPath))
+                    unlinkSync(this.socketPath);
+            }
+            catch {
+                /* ignore */
+            }
         }
         try {
             rmSync(join(this.stateDirPath, "daemon.json"), { force: true });
@@ -113,6 +138,7 @@ export class Daemon {
     }
     // ----------------------------------------------------------------- framing
     onConnection(sock) {
+        this.conns.add(sock);
         let buf = "";
         sock.on("data", (chunk) => {
             buf += chunk.toString("utf8");
@@ -126,6 +152,7 @@ export class Daemon {
         });
         sock.on("error", () => sock.destroy());
         sock.on("close", () => {
+            this.conns.delete(sock);
             for (const w of [...this.watchers])
                 if (w.socket === sock)
                     this.watchers.delete(w);
@@ -428,18 +455,31 @@ export class Daemon {
     }
 }
 // --------------------------------------------------------------------- helpers
-async function probeUnixSocket(path) {
-    return new Promise((resolve) => {
-        const sock = connect(path);
-        sock.once("connect", () => {
-            sock.end();
-            resolve(true);
-        });
-        sock.once("error", () => resolve(false));
-    });
+/**
+ * Liveness via signal 0 — the /proc-less fallback (macOS, Windows).
+ * EPERM counts as alive: the process exists but is not signalable by us.
+ */
+export function aliveBySignalZero(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err?.code === "EPERM";
+    }
 }
-/** Linux: /proc/<pid>/stat field 22 (starttime) defeats pid reuse. */
-export function isProcessAlive(pid, expectedStartTime) {
+/**
+ * Linux: /proc/<pid>/stat field 22 (starttime) defeats pid reuse.
+ * Windows: no /proc and no start time — signal-0 fallback only; the
+ * pid-reuse defense is unavailable there (documented limitation).
+ * macOS: /proc is absent, so the signal-0 fallback applies too.
+ */
+export function isProcessAlive(pid, expectedStartTime, platform = process.platform) {
+    if (isWindows(platform)) {
+        // Start time is unobtainable without native APIs; pid reuse is possible
+        // during this window (documented in docs/OPERATIONS.md).
+        return aliveBySignalZero(pid);
+    }
     try {
         const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
         if (expectedStartTime !== undefined) {
@@ -455,13 +495,7 @@ export function isProcessAlive(pid, expectedStartTime) {
         // /proc unavailable (macOS): fall back to signal 0. Pid reuse is possible
         // here; documented limitation — that is why adapters should prefer
         // run_with_permit / process-group tracking where available.
-        try {
-            process.kill(pid, 0);
-            return true;
-        }
-        catch {
-            return false;
-        }
+        return aliveBySignalZero(pid);
     }
 }
 /**
@@ -470,14 +504,17 @@ export function isProcessAlive(pid, expectedStartTime) {
  * subprocesses and background jobs that outlive their parent. Returns
  * true/false on Linux; on platforms without /proc the pgid scan is
  * unavailable and the result may be null (unknown => conservative keep).
+ * Windows: no process groups — only the main pid is checked, so a permit
+ * is released once the main pid dies even if children survive (documented
+ * limitation; adapters should kill the tree via taskkill /T).
  */
-export function jobAlive(pid, pgid, pidStartTime) {
+export function jobAlive(pid, pgid, pidStartTime, platform = process.platform) {
     if (pid !== undefined) {
-        const alive = isProcessAlive(pid, pidStartTime);
+        const alive = isProcessAlive(pid, pidStartTime, platform);
         if (alive === true)
             return true;
     }
-    if (pgid !== undefined) {
+    if (pgid !== undefined && !isWindows(platform)) {
         const scan = scanProcessGroup(pgid);
         if (scan !== null)
             return scan;

package/dist/core/persist.js

@@ -1,6 +1,7 @@
 /**
  * Atomic JSON persistence for daemon config + change history.
- * State dir: $XDG_STATE_HOME/load-lock (default ~/.local/state/load-lock).
+ * State dir: $XDG_STATE_HOME/load-lock (default ~/.local/state/load-lock;
+ * Windows: %LOCALAPPDATA%\load-lock — see shared/transport.ts).
  *
  * Only *configuration* persists across daemon restarts. Permits and queue
  * are ephemeral by design (see docs/ARCHITECTURE.md — restart behavior):
@@ -9,20 +10,12 @@
 import { mkdirSync, writeFileSync, renameSync, readFileSync, existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { defaultConfig } from "./state.js";
+import { resolveStateDir, resolveSocketPath } from "../shared/transport.js";
 export function stateDir(override) {
-    if (override)
-        return override;
-    if (process.env.LOAD_LOCK_STATE_DIR)
-        return process.env.LOAD_LOCK_STATE_DIR;
-    const xdg = process.env.XDG_STATE_HOME || join(process.env.HOME ?? "~", ".local", "state");
-    return join(xdg, "load-lock");
+    return resolveStateDir(process.platform, process.env, override);
 }
 export function socketPath(override) {
-    if (override)
-        return override;
-    if (process.env.LOAD_LOCK_SOCKET)
-        return process.env.LOAD_LOCK_SOCKET;
-    return join(stateDir(), "daemon.sock");
+    return resolveSocketPath(process.platform, process.env, override);
 }
 export function loadState(dir) {
     const path = join(dir, "config.json");