@aron98/load-lock 0.0.0-stage → 0.1.0

package/dist/core/daemon.js

@@ -0,0 +1,526 @@
+/**
+ * load-lock daemon: single process owning all semaphore state.
+ *
+ * Ownership/lifecycle rationale (see docs/ARCHITECTURE.md): MCP tool calls
+ * are short-lived; a lock held by a tool call would die with the call. The
+ * daemon is the persistent owner: permits live in the daemon, independent of
+ * any agent connection, so a background build outliving its tool call or
+ * session keeps its authorization until released — or until its associated
+ * process is confirmed dead.
+ *
+ * Automatic cleanup (all sweeps run here, on real process evidence):
+ *   - offers expire after offerTimeoutMs (claim window)
+ *   - claimed permits are reclaimed after startTimeoutMs if execution never starts
+ *   - tracked permits are released when their pid/process-group is confirmed dead
+ *   - untracked permits are reclaimed when their heartbeat lease lapses
+ * 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 { existsSync, mkdirSync, unlinkSync, writeFileSync, readFileSync, rmSync } from "node:fs";
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+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";
+export class Daemon {
+    machine;
+    server = null;
+    watchers = new Set();
+    waiters = new Map();
+    sentEventId;
+    stateDirPath;
+    socketPath;
+    sweepTimer = null;
+    expiryTimer = null;
+    stopped = false;
+    constructor(opts = {}) {
+        this.stateDirPath = defaultStateDir(opts.stateDir);
+        this.socketPath = defaultSocket(opts.socket);
+        if (opts.machine) {
+            this.machine = opts.machine;
+        }
+        else {
+            mkdirSync(this.stateDirPath, { recursive: true });
+            const st = loadState(this.stateDirPath);
+            this.machine = new Machine(Date.now, st.config);
+            this.machine.history.push(...st.history);
+            // Conservative restart reconciliation: keep permits whose job still
+            // runs; release permits whose process is confirmed dead. Same permit
+            // tokens remain valid, so a late explicit release after restart works.
+            if (opts.recover !== false) {
+                this.machine.restore(loadJournal(this.stateDirPath), (e) => jobAlive(e.pid, e.pgid, e.pidStartTime));
+            }
+        }
+        this.sentEventId = this.machine.latestEventId(); // don't replay history to watchers
+    }
+    // -------------------------------------------------------------------- start
+    async start() {
+        await this.claimSocket();
+        await new Promise((resolve, reject) => {
+            this.server = createServer((sock) => this.onConnection(sock));
+            this.server.on("error", reject);
+            this.server.listen(this.socketPath, () => resolve());
+        });
+        writeFileSync(join(this.stateDirPath, "daemon.json"), JSON.stringify({ pid: process.pid, startedAt: Date.now(), socket: this.socketPath }, null, 2) + "\n");
+        process.once("SIGTERM", () => this.stop());
+        process.once("SIGINT", () => this.stop());
+        this.sweepTimer = setInterval(() => this.sweep(), 5_000);
+        this.sweepTimer.unref?.();
+        this.sweep(); // catch anything that expired while we were down
+    }
+    /** Bind the socket, replacing it only if it is verifiably stale. */
+    async claimSocket() {
+        if (existsSync(this.socketPath)) {
+            const live = await probeUnixSocket(this.socketPath);
+            if (live) {
+                throw new ProtocolError("denied", `another daemon is already listening on ${this.socketPath}`);
+            }
+            try {
+                unlinkSync(this.socketPath);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    stop() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        if (this.sweepTimer)
+            clearInterval(this.sweepTimer);
+        if (this.expiryTimer)
+            clearTimeout(this.expiryTimer);
+        for (const w of this.watchers)
+            w.socket.destroy();
+        this.watchers.clear();
+        this.server?.close();
+        try {
+            if (existsSync(this.socketPath))
+                unlinkSync(this.socketPath);
+        }
+        catch {
+            /* ignore */
+        }
+        try {
+            rmSync(join(this.stateDirPath, "daemon.json"), { force: true });
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    // ----------------------------------------------------------------- framing
+    onConnection(sock) {
+        let buf = "";
+        sock.on("data", (chunk) => {
+            buf += chunk.toString("utf8");
+            let idx;
+            while ((idx = buf.indexOf("\n")) !== -1) {
+                const line = buf.slice(0, idx);
+                buf = buf.slice(idx + 1);
+                if (line.trim())
+                    void this.handleLine(sock, line);
+            }
+        });
+        sock.on("error", () => sock.destroy());
+        sock.on("close", () => {
+            for (const w of [...this.watchers])
+                if (w.socket === sock)
+                    this.watchers.delete(w);
+        });
+    }
+    send(sock, obj) {
+        if (!sock.destroyed)
+            sock.write(JSON.stringify(obj) + "\n");
+    }
+    async handleLine(sock, lineText) {
+        let msg;
+        try {
+            msg = JSON.parse(lineText);
+        }
+        catch {
+            this.send(sock, { id: null, ok: false, error: { code: "invalid", message: "malformed JSON line" } });
+            return;
+        }
+        let result;
+        let agentId;
+        try {
+            const [res, agent] = await this.dispatch(sock, msg.method, msg.params ?? {});
+            result = res;
+            agentId = agent;
+            this.afterOp();
+        }
+        catch (err) {
+            this.afterOp();
+            if (err instanceof ProtocolError) {
+                this.send(sock, { id: msg.id, ok: false, error: { code: err.code, message: err.message, details: err.details } });
+            }
+            else {
+                this.send(sock, { id: msg.id, ok: false, error: { code: "internal", message: String(err?.message ?? err) } });
+            }
+            return;
+        }
+        // Tool-boundary delivery: surface this agent's outstanding offers/queue
+        // on every response so the next tool result always carries them.
+        if (agentId) {
+            result.pending = this.machine.pending(agentId);
+        }
+        this.send(sock, { id: msg.id, ok: true, result });
+    }
+    // --------------------------------------------------------------- dispatch
+    /** Returns [result, agentIdForPendingAttachment]. */
+    async dispatch(sock, method, p) {
+        const m = this.machine;
+        switch (method) {
+            case "hello":
+                return [{ protocolVersion: 1, pid: process.pid, startedAt: m.startedAt, configVersion: m.config.version }, undefined];
+            case "acquire": {
+                const params = p;
+                let res = m.acquire(params);
+                if (res.state === "offered") {
+                    // An offer was already waiting for this op (idempotent re-acquire):
+                    // auto-claim to honor "wait" semantics without a second round trip.
+                    res = { state: "granted", entry: m.claimByRequestId(res.entry.requestId).entry };
+                }
+                else if (res.state === "queued") {
+                    const waitMs = Math.min(Math.max(0, params.waitMs ?? 0), m.config.maxWaitMs);
+                    if (waitMs > 0) {
+                        const waited = await this.waitForAdmission(res.entry.requestId, waitMs);
+                        if (waited)
+                            res = waited;
+                    }
+                }
+                return [res, params.agentId];
+            }
+            case "claim": {
+                const res = m.claim(String(p.offerToken));
+                return [res, res.entry.agentId];
+            }
+            case "release": {
+                const res = m.release(String(p.permitToken));
+                return [res, res.entry.agentId];
+            }
+            case "decline": {
+                m.decline(String(p.offerToken));
+                return [{ ok: true }, undefined];
+            }
+            case "cancel": {
+                const res = m.cancel(p);
+                return [res, res.entry.agentId];
+            }
+            case "rejoin": {
+                const snap = m.rejoin({ requestId: String(p.requestId) });
+                return [{ state: snap.state, entry: snap }, snap.agentId];
+            }
+            case "start_job": {
+                // Atomic execution association. pidStartTime read daemon-side from
+                // /proc (pid-reuse-safe on Linux).
+                const snap = m.startJob(String(p.permitToken), Number(p.pid), p.pgid !== undefined ? Number(p.pgid) : undefined, processStartTime(Number(p.pid)));
+                return [{ entry: snap }, snap.agentId];
+            }
+            case "mark_started": {
+                const snap = m.markStarted(String(p.permitToken));
+                return [{ entry: snap }, snap.agentId];
+            }
+            case "attach_pid": {
+                // Convenience alias: associate a manually-started process.
+                const pid = Number(p.pid);
+                const snap = m.startJob(String(p.permitToken), pid, undefined, processStartTime(pid));
+                return [{ entry: snap }, snap.agentId];
+            }
+            case "heartbeat": {
+                m.heartbeat(String(p.agentId));
+                return [{ ok: true }, String(p.agentId)];
+            }
+            case "pending": {
+                const res = m.pending(String(p.agentId));
+                return [res, String(p.agentId)];
+            }
+            case "status":
+                return [m.status(p.pool ? String(p.pool) : undefined), undefined];
+            case "get_config":
+                return [m.get_config(), undefined];
+            case "configure": {
+                const res = m.configure(p);
+                saveState(this.stateDirPath, m.config, m.history);
+                return [res, undefined];
+            }
+            case "inspect":
+                return [inspectMachine(m.config), undefined];
+            case "events": {
+                const since = Number(p.sinceEventId ?? 0);
+                const agentId = p.agentId ? String(p.agentId) : undefined;
+                const evs = m.eventsSince(since, agentId);
+                if (agentId) {
+                    // Owner-filtered pulls carry claim tokens (durable identities +
+                    // tokens survive reconnects); unfiltered pulls never do.
+                    for (const ev of evs) {
+                        if (ev.type === "offered" && ev.entry && ev.targetAgent === agentId) {
+                            const t = m.offerTokenOf(ev.entry.requestId);
+                            if (t)
+                                ev.offerToken = t;
+                        }
+                    }
+                }
+                return [{ events: evs, latestEventId: m.latestEventId() }, undefined];
+            }
+            case "watch": {
+                const agentId = p.agentId ? String(p.agentId) : "*";
+                this.watchers.add({ socket: sock, agentId });
+                this.send(sock, { event: true, type: "watch_started", targetAgent: agentId, latestEventId: m.latestEventId() });
+                return [{ ok: true }, undefined];
+            }
+            case "offers_for_cwd": {
+                // Used by Claude Code / Codex hook scripts, which lack the MCP
+                // process's agent identity: match offers by the cwd recorded at
+                // acquire time. Claiming still requires the opaque token, so a
+                // match can wake a session but can never authorize work by itself.
+                const cwd = String(p.cwd);
+                return [{ offers: m.allOffers().filter((e) => e.cwd === cwd) }, undefined];
+            }
+            case "admin_list":
+                return [{ holders: m.diagnose((e) => jobAlive(e.pid, e.pgid, e.pidStartTime)), latestEventId: m.latestEventId() }, undefined];
+            case "admin_release": {
+                // Force-release recovery: reclaims the permit and frees capacity.
+                m.adminRelease(String(p.requestId));
+                return [{ ok: true }, undefined];
+            }
+            default:
+                throw new ProtocolError("invalid", `unknown method "${method}"`);
+        }
+    }
+    /**
+     * Bounded blocking wait for a queued request. Resolves with a granted
+     * result if capacity is admitted within waitMs, else null (caller returns
+     * the queued state). This is the honest fallback for harnesses without
+     * push notifications — no model-authored busy-polling required.
+     */
+    waitForAdmission(requestId, waitMs) {
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.waiters.delete(requestId);
+                resolve(null);
+            }, waitMs);
+            this.waiters.set(requestId, { requestId, resolve, timer });
+        });
+    }
+    // ------------------------------------------------------------- post-op pass
+    /** Runs after every dispatch: sweep deadlines, auto-claim for waiters, flush events, journal. */
+    afterOp() {
+        const m = this.machine;
+        m.tick(m.now());
+        // Auto-claim on behalf of blocking waiters when their request is offered.
+        for (const [requestId, waiter] of [...this.waiters]) {
+            const entry = m.entryById(requestId);
+            if (!entry)
+                continue;
+            if (entry.state === "offered") {
+                const granted = m.claimByRequestId(requestId);
+                clearTimeout(waiter.timer);
+                this.waiters.delete(requestId);
+                waiter.resolve({ state: "granted", entry: granted.entry });
+            }
+            else if (entry.state === "held") {
+                clearTimeout(waiter.timer);
+                this.waiters.delete(requestId);
+                waiter.resolve({ state: "granted", entry: m.ownerSnapshotById(requestId) });
+            }
+            else if (entry.state === "paused" || entry.state === "cancelled" || entry.state === "released") {
+                clearTimeout(waiter.timer);
+                this.waiters.delete(requestId);
+                waiter.resolve(null);
+            }
+        }
+        // Flush events produced by this op to watchers.
+        const fresh = m.eventsSince(this.sentEventId);
+        if (fresh.length > 0) {
+            this.sentEventId = m.latestEventId();
+            for (const ev of fresh)
+                this.broadcast(ev);
+        }
+        // Persist held permits for restart reconciliation.
+        try {
+            saveJournal(this.stateDirPath, m.journalEntries());
+        }
+        catch {
+            /* journal is best-effort; config.json already persisted */
+        }
+        this.armExpiryTimer();
+    }
+    armExpiryTimer() {
+        const next = this.machine.nextExpiry();
+        if (this.expiryTimer) {
+            clearTimeout(this.expiryTimer);
+            this.expiryTimer = null;
+        }
+        if (next === null)
+            return;
+        const ms = Math.max(5, next - Date.now());
+        this.expiryTimer = setTimeout(() => {
+            this.machine.tick(this.machine.now());
+            const fresh = this.machine.eventsSince(this.sentEventId);
+            if (fresh.length > 0) {
+                this.sentEventId = this.machine.latestEventId();
+                for (const ev of fresh)
+                    this.broadcast(ev);
+            }
+            try {
+                saveJournal(this.stateDirPath, this.machine.journalEntries());
+            }
+            catch {
+                /* ignore */
+            }
+            this.armExpiryTimer();
+        }, ms);
+        this.expiryTimer.unref?.();
+    }
+    broadcast(ev) {
+        for (const w of this.watchers) {
+            if (w.agentId === "*" || ev.targetAgent === "*" || ev.targetAgent === w.agentId) {
+                const out = { ...ev, event: true };
+                if (ev.type === "offered" && ev.entry && (w.agentId === ev.targetAgent || w.agentId === "*")) {
+                    // Deliver the claim token to the owner, and to trusted "*"
+                    // multiplexer watchers (e.g. the OpenCode plugin, which routes the
+                    // event to the right session by targetAgent). Claiming still
+                    // requires the token; the event itself authorizes nothing.
+                    const tok = this.machine.offerTokenOf(ev.entry.requestId);
+                    if (tok)
+                        out.offerToken = tok;
+                }
+                this.send(w.socket, out);
+            }
+        }
+    }
+    // ------------------------------------------------------------------ sweeps
+    /**
+     * Periodic cleanup with positive process evidence:
+     *  - tracked permits: release when pid AND process group are confirmed dead
+     *  - claimed/untracked deadlines: handled by machine.tick() (start
+     *    deadline, heartbeat lease) here as well so timers alone are not load-bearing.
+     * Untracked permits are never released on duration alone — only when their
+     * lease lapses, which requires the owner's adapter to be gone.
+     */
+    sweep() {
+        const m = this.machine;
+        for (const e of m.heldEntries()) {
+            if (e.phase === "running_tracked") {
+                const alive = jobAlive(e.pid, e.pgid, e.pidStartTime);
+                if (alive === false) {
+                    m.autoRelease(e.requestId, `tracked process ${e.pid}${e.pgid ? ` / pgid ${e.pgid}` : ""} is no longer running`);
+                }
+            }
+        }
+        m.tick(m.now());
+        try {
+            saveJournal(this.stateDirPath, m.journalEntries());
+        }
+        catch {
+            /* ignore */
+        }
+        const fresh = m.eventsSince(this.sentEventId);
+        if (fresh.length > 0) {
+            this.sentEventId = m.latestEventId();
+            for (const ev of fresh)
+                this.broadcast(ev);
+        }
+    }
+}
+// --------------------------------------------------------------------- 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));
+    });
+}
+/** Linux: /proc/<pid>/stat field 22 (starttime) defeats pid reuse. */
+export function isProcessAlive(pid, expectedStartTime) {
+    try {
+        const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+        if (expectedStartTime !== undefined) {
+            const close = stat.lastIndexOf(")");
+            const fields = stat.slice(close + 2).split(" ");
+            const starttime = fields[19]; // field 22 overall (1-based), minus pid + comm
+            if (starttime !== expectedStartTime)
+                return false; // pid was reused
+        }
+        return true;
+    }
+    catch {
+        // /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;
+        }
+    }
+}
+/**
+ * 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).
+ */
+export function jobAlive(pid, pgid, pidStartTime) {
+    if (pid !== undefined) {
+        const alive = isProcessAlive(pid, pidStartTime);
+        if (alive === true)
+            return true;
+    }
+    if (pgid !== undefined) {
+        const scan = scanProcessGroup(pgid);
+        if (scan !== null)
+            return scan;
+    }
+    if (pid === undefined)
+        return null;
+    return false;
+}
+/** Scan /proc for any live process whose pgrp matches pgid. null = /proc unavailable. */
+function scanProcessGroup(pgid) {
+    let names;
+    try {
+        names = readdirSync("/proc");
+    }
+    catch {
+        return null;
+    }
+    for (const name of names) {
+        if (!/^\d+$/.test(name))
+            continue;
+        try {
+            const stat = readFileSync(`/proc/${name}/stat`, "utf8");
+            const close = stat.lastIndexOf(")");
+            const fields = stat.slice(close + 2).split(" ");
+            const pgrp = Number(fields[2]); // field 5 overall, minus pid + comm
+            if (pgrp === pgid)
+                return true;
+        }
+        catch {
+            /* process vanished mid-scan */
+        }
+    }
+    return false;
+}
+/** Read the Linux start time of a pid (pid-reuse-safe association). */
+export function processStartTime(pid) {
+    try {
+        const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+        const close = stat.lastIndexOf(")");
+        const fields = stat.slice(close + 2).split(" ");
+        return fields[19];
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/core/persist.d.ts

@@ -0,0 +1,11 @@
+import { MachineConfig, ConfigHistoryEntry, JournalEntry } from "../shared/protocol.js";
+export declare function stateDir(override?: string): string;
+export declare function socketPath(override?: string): string;
+export declare function loadState(dir: string): {
+    config: MachineConfig;
+    history: ConfigHistoryEntry[];
+};
+export declare function saveState(dir: string, config: MachineConfig, history: ConfigHistoryEntry[]): void;
+export declare function journalPath(dir: string): string;
+export declare function loadJournal(dir: string): JournalEntry[];
+export declare function saveJournal(dir: string, entries: JournalEntry[]): void;

package/dist/core/persist.js

@@ -0,0 +1,66 @@
+/**
+ * Atomic JSON persistence for daemon config + change history.
+ * State dir: $XDG_STATE_HOME/load-lock (default ~/.local/state/load-lock).
+ *
+ * Only *configuration* persists across daemon restarts. Permits and queue
+ * are ephemeral by design (see docs/ARCHITECTURE.md — restart behavior):
+ * tokens are daemon-instance-scoped, and agents re-acquire after a restart.
+ */
+import { mkdirSync, writeFileSync, renameSync, readFileSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { defaultConfig } from "./state.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");
+}
+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");
+}
+export function loadState(dir) {
+    const path = join(dir, "config.json");
+    if (!existsSync(path))
+        return { config: defaultConfig(), history: [] };
+    const raw = JSON.parse(readFileSync(path, "utf8"));
+    const config = { ...defaultConfig(), ...raw.config };
+    // Defensive: always at least the default pool.
+    if (!config.pools || Object.keys(config.pools).length === 0)
+        config.pools = { heavy: { capacity: 1 } };
+    return { config, history: Array.isArray(raw.history) ? raw.history : [] };
+}
+export function saveState(dir, config, history) {
+    mkdirSync(dir, { recursive: true });
+    const path = join(dir, "config.json");
+    const tmp = join(dirname(path), ".config.json.tmp-" + process.pid);
+    writeFileSync(tmp, JSON.stringify({ config, history }, null, 2) + "\n", { mode: 0o644 });
+    renameSync(tmp, path); // atomic on POSIX
+}
+// --------------------------------------------------------------------------
+// Journal: held permits, persisted so a daemon restart can conservatively
+// reconcile running ownership (tracked jobs keep their permit; confirmed-dead
+// jobs release; queued/offered requests are NOT journaled — agents re-acquire).
+export function journalPath(dir) {
+    return join(dir, "journal.json");
+}
+export function loadJournal(dir) {
+    try {
+        const raw = JSON.parse(readFileSync(journalPath(dir), "utf8"));
+        return Array.isArray(raw) ? raw : [];
+    }
+    catch {
+        return [];
+    }
+}
+export function saveJournal(dir, entries) {
+    const path = journalPath(dir);
+    const tmp = join(dirname(path), ".journal.json.tmp-" + process.pid);
+    writeFileSync(tmp, JSON.stringify(entries, null, 2) + "\n", { mode: 0o644 });
+    renameSync(tmp, path);
+}