@aron98/load-lock 0.0.0-stage → 0.1.0

package/dist/test/hook.test.js

@@ -0,0 +1,126 @@
+/**
+ * Hook contract tests: `load-lock hook <harness> <event>` invoked exactly the
+ * way Claude Code / Codex invoke hooks (harness JSON on stdin), against a real
+ * daemon with real offers outstanding.
+ */
+import test from "node:test";
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { startDaemon, delay, cliMainPath } from "./testutil.js";
+const POLICY_MARK = "# load-lock: machine-wide heavy-work budget";
+function runHook(d, args, input, env) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, [cliMainPath, "hook", ...args], {
+            env: { ...d.env, ...env },
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (b) => (stdout += b));
+        child.stderr.on("data", (b) => (stderr += b));
+        child.on("exit", (code) => resolve({ code, stdout, stderr }));
+        child.on("error", reject);
+        child.stdin.end(input === undefined ? "" : JSON.stringify(input));
+    });
+}
+/** Set up: A holds, B queued with cwd; release A so B has an outstanding offer. */
+async function outstandingOffer(d, cwd) {
+    const c = d.client();
+    await c.connect();
+    await c.request("acquire", { agentId: "hook-holder", opKey: "h1", reason: "holding" });
+    await c.request("acquire", { agentId: "hook-waiter", opKey: "w1", reason: "waiting", cwd });
+    const rel = (await c.request("release", { permitToken: (await c.request("pending", { agentId: "hook-holder" })).held[0].permitToken }));
+    const offers = (await c.request("offers_for_cwd", { cwd }));
+    c.close();
+    return offers.offers[0];
+}
+test("hooks: session-start events print the policy brief + machine state", async () => {
+    const d = await startDaemon();
+    try {
+        for (const ev of [
+            ["claude-code", "session-start"],
+            ["codex", "session-start"],
+            ["codex", "subagent-start"],
+        ]) {
+            const r = await runHook(d, ev, { session_id: "s1", cwd: "/tmp", source: "startup" });
+            assert.equal(r.code, 0, `${ev.join("/")} exits 0`);
+            assert.ok(r.stdout.startsWith(POLICY_MARK), `${ev.join("/")} emits the policy brief as stdout context`);
+            assert.ok(r.stdout.includes("effective core"), "includes machine awareness line");
+            assert.equal(r.stderr, "");
+        }
+    }
+    finally {
+        await d.stop();
+    }
+});
+test("hooks: claude-code stop with a matching offer -> decision block carrying the offer token", async () => {
+    const d = await startDaemon();
+    try {
+        const cwd = mkdtempSync(join(tmpdir(), "opencode", "ll-hook-wt-"));
+        const offer = await outstandingOffer(d, cwd);
+        assert.ok(offer?.offerToken, "waiter has an outstanding offer");
+        const r = await runHook(d, ["claude-code", "stop"], { session_id: "s1", cwd });
+        assert.equal(r.code, 0);
+        const out = JSON.parse(r.stdout);
+        assert.equal(out.decision, "block", "Stop hook continues the session");
+        assert.ok(out.reason.includes(offer.offerToken), "reason tells the agent which offer_token to claim");
+        assert.ok(out.reason.includes("claim"), "reason instructs claiming");
+        assert.ok(out.reason.includes(offer.opKey));
+        // stop_hook_active: never loop
+        const quiet = await runHook(d, ["claude-code", "stop"], { session_id: "s1", cwd, stop_hook_active: true });
+        assert.equal(quiet.code, 0);
+        assert.equal(quiet.stdout, "", "already-continued stops are silent");
+        // no matching offers -> silent
+        const none = await runHook(d, ["claude-code", "stop"], { session_id: "s1", cwd: "/definitely/not/a/worktree" });
+        assert.equal(none.stdout, "");
+    }
+    finally {
+        await d.stop();
+    }
+});
+test("hooks: codex stop behaves the same (decision block JSON)", async () => {
+    const d = await startDaemon();
+    try {
+        const cwd = mkdtempSync(join(tmpdir(), "opencode", "ll-hook-wt-"));
+        const offer = await outstandingOffer(d, cwd);
+        assert.ok(offer?.offerToken);
+        const r = await runHook(d, ["codex", "stop"], { session_id: "s1", cwd, stop_hook_active: false });
+        const out = JSON.parse(r.stdout);
+        assert.equal(out.decision, "block");
+        assert.ok(out.reason.includes(offer.offerToken));
+    }
+    finally {
+        await d.stop();
+    }
+});
+test("hooks: claude-code await-offer wakes (exit 2 + stderr, no token leak) on offer", async () => {
+    const d = await startDaemon();
+    try {
+        const cwd = mkdtempSync(join(tmpdir(), "opencode", "ll-hook-wt-"));
+        const c = d.client();
+        await c.connect();
+        // holder + waiter, offer NOT yet delivered
+        await c.request("acquire", { agentId: "hook-holder2", opKey: "h2", reason: "holding" });
+        await c.request("acquire", { agentId: "hook-waiter2", opKey: "w2", reason: "waiting", cwd });
+        const awaiting = runHook(d, ["claude-code", "await-offer"], { session_id: "s1", cwd }, { LOAD_LOCK_AWAIT_MS: "8000" });
+        await delay(400);
+        // release the holder -> offer created for the waiter in `cwd`
+        const held = (await c.request("pending", { agentId: "hook-holder2" }));
+        await c.request("release", { permitToken: held.held[0].permitToken });
+        const r = await awaiting;
+        assert.equal(r.code, 2, "asyncRewake contract: exit code 2 wakes Claude");
+        assert.ok(r.stderr.includes("claim"), "stderr explains how to claim");
+        assert.ok(!r.stderr.includes("off_"), "the offer token itself is NOT in stderr (session must claim via pending)");
+        assert.equal(r.stdout, "");
+        // timeout path: no offer in window -> exit 0, silent
+        const t = await runHook(d, ["claude-code", "await-offer"], { session_id: "s1", cwd: "/nowhere" }, { LOAD_LOCK_AWAIT_MS: "500" });
+        assert.equal(t.code, 0);
+        assert.equal(t.stderr, "");
+    }
+    finally {
+        await d.stop();
+    }
+});

package/dist/test/mcp.test.d.ts

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

package/dist/test/mcp.test.js

@@ -0,0 +1,139 @@
+/**
+ * MCP server integration tests: spawn dist/mcp/main.js as a real MCP stdio
+ * server (the way harnesses launch it) and exercise the tool round trips,
+ * including the run_with_permit lifecycle.
+ */
+import test from "node:test";
+import assert from "node:assert/strict";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { startDaemon, delay, mcpMainPath } from "./testutil.js";
+async function connectMcp(d) {
+    const client = new Client({ name: "load-lock-test", version: "0.1.0" }, { capabilities: {} });
+    const transport = new StdioClientTransport({
+        command: process.execPath,
+        args: [mcpMainPath],
+        env: d.env,
+    });
+    await client.connect(transport);
+    return client;
+}
+async function callJson(c, name, args) {
+    const res = await c.callTool({ name, arguments: args });
+    assert.equal(res.isError, undefined, `tool ${name} errored: ${JSON.stringify(res.content)}`);
+    return JSON.parse(res.content[0].text);
+}
+test("mcp: tool listing + acquire/release/configure round trip", async () => {
+    const d = await startDaemon();
+    const c = await connectMcp(d);
+    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"]) {
+            assert.ok(names.includes(expected), `tool ${expected} registered`);
+        }
+        const acq = await callJson(c, "acquire", { reason: "build", op_key: "mcp-rt", agent_id: "mcpAgentA" });
+        assert.equal(acq.state, "granted");
+        assert.ok(acq.permit_token, "acquire result carries permit_token");
+        assert.ok(acq.next_action, "structured next_action present");
+        // idempotent acquire with the same op_key
+        const acq2 = await callJson(c, "acquire", { reason: "build", op_key: "mcp-rt", agent_id: "mcpAgentA" });
+        assert.equal(acq2.request_id, acq.request_id, "same op_key -> same request");
+        // a second agent queues
+        const acqB = await callJson(c, "acquire", { reason: "tests", op_key: "mcp-b", agent_id: "mcpAgentB" });
+        assert.equal(acqB.state, "queued");
+        assert.equal(acqB.queue_position, 1);
+        // configure: capacity up (CAS)
+        const cfg = await callJson(c, "get_config", {});
+        const conf = await callJson(c, "configure", {
+            expected_version: cfg.config.version,
+            changes: { pools: { heavy: { capacity: 2 } } },
+            reason: "test: two cores of headroom",
+            author: "mcp test",
+        });
+        assert.equal(conf.config.version, cfg.config.version + 1);
+        // capacity increase admits the queued request -> offered to B
+        const pend = await callJson(c, "pending", { agent_id: "mcpAgentB" });
+        assert.equal(pend.offers.length, 1, "B has an outstanding offer after capacity increase");
+        assert.ok(pend.offers[0].offerToken, "offer carries token");
+        // claim it
+        const claimed = await callJson(c, "claim", { offer_token: pend.offers[0].offerToken });
+        assert.equal(claimed.state, "held");
+        assert.ok(claimed.permit_token);
+        // duplicate claim must fail cleanly (expired/stale token), not corrupt state
+        const dup = await c.callTool({ name: "claim", arguments: { offer_token: pend.offers[0].offerToken } });
+        assert.ok(dup.isError, "duplicate claim rejected (stale offer token)");
+        // releases are idempotent
+        const rel1 = await callJson(c, "release", { permit_token: acq.permit_token });
+        assert.equal(rel1.released_now, true);
+        const rel2 = await callJson(c, "release", { permit_token: acq.permit_token });
+        assert.equal(rel2.released_now, false, "second release is idempotent");
+        const st = await callJson(c, "status", {});
+        assert.equal(st.pools[0].capacity, 2);
+        assert.ok(st.pools[0].holders.length <= 1);
+    }
+    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);
+    try {
+        const acq = await callJson(c, "acquire", { reason: "build", op_key: "mcp-job" });
+        assert.equal(acq.state, "granted");
+        const job = await callJson(c, "run_with_permit", {
+            permit_token: acq.permit_token,
+            command: `sh -c 'sleep 1 && echo done'`,
+        });
+        assert.ok(job.job_id, "returns a job handle for background execution");
+        assert.equal(job.state, "running");
+        // status while running
+        const running = await callJson(c, "job_status", { job_id: job.job_id });
+        assert.equal(running.running, true);
+        // wait for completion (poll with cap)
+        let exited = null;
+        for (let i = 0; i < 40 && !exited; i++) {
+            await delay(150);
+            const s = await callJson(c, "job_status", { job_id: job.job_id });
+            if (!s.running)
+                exited = s;
+        }
+        assert.ok(exited, "job completed");
+        assert.equal(exited.exit_code, 0);
+        assert.ok(exited.output_tail.includes("done"));
+        // auto-release happened without an explicit release call
+        await delay(300);
+        const st = await callJson(c, "status", {});
+        assert.equal(st.pools[0].holders.length, 0, "permit auto-released after job exit");
+    }
+    finally {
+        await c.close();
+        await d.stop();
+    }
+});
+test("mcp: multiple server processes share one machine-wide budget", async () => {
+    const d = await startDaemon();
+    const c1 = await connectMcp(d);
+    const c2 = await connectMcp(d); // separate process = separate harness session
+    try {
+        const a1 = await callJson(c1, "acquire", { reason: "agent1 build", op_key: "a1" });
+        assert.equal(a1.state, "granted");
+        const a2 = await callJson(c2, "acquire", { reason: "agent2 tests", op_key: "a2" });
+        assert.equal(a2.state, "queued", "second harness session sees the same capacity budget");
+        assert.equal(a2.queue_position, 1);
+        await callJson(c1, "release", { permit_token: a1.permit_token });
+        // the offer for agent2 shows up in ITS tool boundary results
+        const pend = await callJson(c2, "pending", {});
+        assert.equal(pend.offers.length, 1);
+        const claimed = await callJson(c2, "claim", { offer_token: pend.offers[0].offerToken });
+        assert.equal(claimed.state, "held");
+        await callJson(c2, "release", { permit_token: claimed.permit_token });
+    }
+    finally {
+        await c1.close();
+        await c2.close();
+        await d.stop();
+    }
+});

package/dist/test/run-helper.test.d.ts

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

package/dist/test/run-helper.test.js

@@ -0,0 +1,84 @@
+/**
+ * End-to-end tests for the `load-lock run` helper: separate CLI processes
+ * (independent OS processes, as a real agent would spawn them) against a real
+ * daemon; exit codes and automatic release semantics.
+ */
+import test from "node:test";
+import assert from "node:assert/strict";
+import { startDaemon, runCli, delay } from "./testutil.js";
+test("run: success and failure propagate exit codes and auto-release", async () => {
+    const d = await startDaemon();
+    try {
+        const ok = await runCli(d, ["run", "--reason", "build", "--op-key", "ok1", "--", "sh", "-c", "echo heavy-done"]);
+        assert.equal(ok.code, 0, `stdout: ${ok.stdout}\nstderr: ${ok.stderr}`);
+        assert.ok(ok.stdout.includes("heavy-done"));
+        const bad = await runCli(d, ["run", "--reason", "build", "--op-key", "bad1", "--", "sh", "-c", "exit 3"]);
+        assert.equal(bad.code, 3, "the job's exit code propagates");
+        // both permits auto-released
+        const c = d.client();
+        await c.connect();
+        const st = (await c.request("status", {}));
+        assert.equal(st.pools[0].holders.length, 0);
+        assert.equal(st.pools[0].used, 0);
+        c.close();
+    }
+    finally {
+        await d.stop();
+    }
+});
+test("run: exits 68 (queued) while another process holds the permit; FIFO continuation", async () => {
+    const d = await startDaemon();
+    const c = d.client();
+    try {
+        await c.connect();
+        // a holder that keeps the permit for ~2s, in a SEPARATE process
+        const holder = runCli(d, ["run", "--reason", "hold", "--op-key", "hold1", "--wait-ms", "0", "--", "sleep", "2"]);
+        await (async () => {
+            // wait until the holder actually holds
+            for (let i = 0; i < 50; i++) {
+                const st = (await c.request("status", {}));
+                if (st.pools[0].holders.length === 1)
+                    return;
+                await delay(100);
+            }
+            throw new Error("holder did not acquire");
+        })();
+        const queued = await runCli(d, ["run", "--reason", "second", "--op-key", "q1", "--wait-ms", "0", "--", "true"]);
+        assert.equal(queued.code, 68, "queued run exits 68 instead of blocking forever");
+        assert.equal((await holder).code, 0);
+        // after the holder finishes, capacity is free again
+        const st2 = (await c.request("status", {}));
+        assert.equal(st2.pools[0].holders.length, 0);
+    }
+    finally {
+        await d.stop();
+    }
+});
+test("wait: bounded blocking offer-watcher for scriptable flows", async () => {
+    const d = await startDaemon();
+    const c = d.client();
+    try {
+        await c.connect();
+        // A holds; B queues (as a separate CLI process for realism)
+        const acqA = await runCli(d, ["acquire", "--agent", "agentA", "--op-key", "a1", "--reason", "hold", "--json"]);
+        assert.equal(acqA.code, 0);
+        const aPermit = JSON.parse(acqA.stdout).entry.permitToken;
+        const acqB = await runCli(d, ["acquire", "--agent", "agentB", "--op-key", "b1", "--reason", "waiter", "--json"]);
+        assert.equal(acqB.code, 68);
+        const bReqId = JSON.parse(acqB.stdout).entry.requestId;
+        // waiter watches for its offer in a separate process
+        const waiter = runCli(d, ["wait", "--id", bReqId, "--agent", "agentB", "--timeout", "8000", "--json"]);
+        await delay(300);
+        await c.request("release", { permitToken: aPermit });
+        const w = await waiter;
+        assert.equal(w.code, 0, `waiter stdout: ${w.stdout}\nstderr: ${w.stderr}`);
+        const permit = JSON.parse(w.stdout).permit_token;
+        assert.ok(permit, "wait prints the claimed permit token");
+        // clean up: release B
+        const rel = await runCli(d, ["release", "--permit", permit, "--json"]);
+        assert.equal(rel.code, 0);
+    }
+    finally {
+        await d.stop();
+    }
+});

package/dist/test/testutil.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared helpers for integration tests (not matched by the test-file pattern).
+ */
+import { type ChildProcess } from "node:child_process";
+import { LLClient } from "../shared/client.js";
+export declare const daemonMainPath: string;
+export declare const cliMainPath: string;
+export declare const mcpMainPath: string;
+export interface DaemonHandle {
+    child: ChildProcess;
+    dir: string;
+    sock: string;
+    env: Record<string, string>;
+    client(): LLClient;
+    stop(): Promise<void>;
+}
+export declare function startDaemon(): Promise<DaemonHandle>;
+export declare function probe(sock: string): Promise<boolean>;
+export declare function delay(ms: number): Promise<void>;
+export declare function until(desc: string, fn: () => boolean | Promise<boolean>, timeoutMs?: number, step?: number): Promise<void>;
+export interface CliResult {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+}
+/** Run the compiled CLI as a separate process against the given daemon env. */
+export declare function runCli(d: DaemonHandle, args: string[], input?: string, timeoutMs?: number): Promise<CliResult>;

package/dist/test/testutil.js

@@ -0,0 +1,111 @@
+/**
+ * Shared helpers for integration tests (not matched by the test-file pattern).
+ */
+import { spawn } from "node:child_process";
+import { mkdtempSync, rmSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+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");
+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");
+export const mcpMainPath = join(dirname(fileURLToPath(import.meta.url)), "..", "mcp", "main.js");
+export async function startDaemon() {
+    const dir = mkdtempSync(join(TMP_BASE, "ll-daemon-"));
+    const sock = join(dir, "daemon.sock");
+    const env = {
+        ...process.env,
+        LOAD_LOCK_STATE_DIR: dir,
+        LOAD_LOCK_SOCKET: sock,
+    };
+    const child = spawn(process.execPath, [daemonMainPath, "--state-dir", dir, "--socket", sock], {
+        stdio: ["ignore", "pipe", "pipe"],
+        env,
+    });
+    const deadline = Date.now() + 10_000;
+    for (;;) {
+        if (await probe(sock))
+            break;
+        if (Date.now() > deadline) {
+            child.kill("SIGKILL");
+            throw new Error("daemon did not come up");
+        }
+        await delay(100);
+    }
+    const handle = {
+        child,
+        dir,
+        sock,
+        env,
+        client: () => new LLClient({ socket: sock, stateDir: dir, spawnDaemon: false }),
+        stop: async () => {
+            if (child.exitCode === null && !child.killed) {
+                child.kill("SIGTERM");
+                await new Promise((resolve) => {
+                    const t = setTimeout(() => {
+                        child.kill("SIGKILL");
+                        resolve();
+                    }, 3000);
+                    child.once("exit", () => {
+                        clearTimeout(t);
+                        resolve();
+                    });
+                });
+            }
+            rmSync(dir, { recursive: true, force: true });
+        },
+    };
+    return handle;
+}
+export function probe(sock) {
+    return new Promise((resolve) => {
+        const s = connect(sock);
+        s.once("connect", () => {
+            s.destroy();
+            resolve(true);
+        });
+        s.once("error", () => resolve(false));
+    });
+}
+export function delay(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+export async function until(desc, fn, timeoutMs = 15_000, step = 200) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        if (await fn())
+            return;
+        if (Date.now() > deadline)
+            throw new Error(`timeout waiting for: ${desc}`);
+        await delay(step);
+    }
+}
+/** Run the compiled CLI as a separate process against the given daemon env. */
+export function runCli(d, args, input, timeoutMs = 60_000) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, [cliMainPath, ...args], { env: d.env });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (b) => (stdout += b));
+        child.stderr.on("data", (b) => (stderr += b));
+        if (input !== undefined)
+            child.stdin.end(input);
+        else
+            child.stdin.end();
+        const timer = setTimeout(() => {
+            child.kill("SIGKILL");
+            reject(new Error(`CLI timed out: load-lock ${args.join(" ")}`));
+        }, timeoutMs);
+        child.once("exit", (code) => {
+            clearTimeout(timer);
+            resolve({ code, stdout, stderr });
+        });
+        child.once("error", (e) => {
+            clearTimeout(timer);
+            reject(e);
+        });
+    });
+}

package/docs/ADAPTERS.md

@@ -0,0 +1,118 @@
+# Writing a harness adapter for load-lock
+
+load-lock ships first-class support for OpenCode, Claude Code, and Codex CLI,
+plus a generic MCP fallback that works with any MCP-capable harness. This
+guide is for anyone adding support for a *new* harness. Everything you need
+is importable from the published package — no private APIs required.
+
+```ts
+import { LLClient, withClient } from "@aron98/load-lock/shared/client";
+import type * as P from "@aron98/load-lock/shared/protocol";
+import { POLICY_BRIEF } from "@aron98/load-lock/policy/text";
+import { buildServer } from "@aron98/load-lock/mcp/server";
+```
+
+## What a good adapter provides (in priority order)
+
+1. **Tools** — the agent must be able to call acquire / claim / release /
+   cancel / pending / status / inspect_machine / get_config / configure, and
+   ideally the lifecycle helpers (run_with_permit / job_status / attach_pid /
+   mark_started).
+2. **Policy at session start** — inject `POLICY_BRIEF` where the harness
+   puts per-session instructions, and re-inject after context compaction if
+   the harness supports it. This is the part agents actually follow; tools
+   without teaching get ignored.
+3. **Idle wakeup (if the harness allows it)** — when the daemon emits an
+   `offered` event for your session, deliver it to the agent at a safe
+   point (execution boundary), including the claim token and expiry. Never
+   interrupt an in-flight tool call.
+4. **Heartbeats** — every ~30s while the session is alive, so
+   `mark_started` (untracked) permits aren't reclaimed while the agent is
+   merely quiet.
+
+Pick the tier your harness allows:
+
+## Tier 1 — native plugin (best)
+
+For harnesses with an in-process extension API (this is what the OpenCode
+adapter does — see `src/adapters/opencode/plugin.ts` as the worked example):
+
+- One module-level `LLClient` (it auto-spawns the daemon on first use; a
+  machine typically runs one client per plugin host).
+- Register tools that translate your harness's tool-call format into
+  `client.request(...)`. Give the agent a stable identity (harness session
+  id) and pass the session's cwd at acquire time.
+- Subscribe `client.watch("*")` and route `offered` events to the owning
+  session via the harness's wake/synthetic-message API.
+- Inject `POLICY_BRIEF` on session start and after every compaction.
+- For heavy work, implement a `run_with_permit` helper following the
+  lifecycle contract below — or teach agents to use the CLI
+  (`load-lock run --permit ... -- <cmd>`), which already implements it.
+
+## Tier 2 — hooks + MCP
+
+For harnesses with lifecycle hooks but no in-process API (Claude Code and
+Codex CLI use this): keep the stock MCP server (`load-lock-mcp` binary, or
+`node .../dist/mcp/main.js`) for tools, and add hook handlers that shell out
+to the CLI:
+
+- `load-lock hook <harness> session-start` → prints `POLICY_BRIEF` +
+  machine summary for context injection (register for post-compaction too,
+  if the harness has a compact matcher).
+- `load-lock hook <harness> stop` → checks cwd-matched offers and, if one
+  exists, prints the harness's "continue the session" JSON with the claim
+  token. Honors any stop-loop flags the harness provides.
+- See `src/cli/hook.ts` for the implementation pattern and
+  `src/cli/install.ts` for the config-writing/installer pattern.
+
+## Tier 3 — MCP only
+
+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).
+
+## Protocol quick reference
+
+Wire protocol: NDJSON over a Unix domain socket; `LLClient` handles
+framing, timeouts, auto-spawn, and event subscriptions. Methods an adapter
+normally touches:
+
+| Method | Purpose |
+| --- | --- |
+| `acquire {pool?, agentId, agentLabel?, cwd?, opKey, reason, weight?, waitMs?, subscribeIfBusy?}` | grant / queue (idempotent per agent+opKey) |
+| `claim {offerToken}` | offer → permit (before starting heavy work) |
+| `release {permitToken, outcome?}` | idempotent |
+| `cancel {requestId}` / `rejoin {requestId}` / `decline {offerToken}` | queue hygiene |
+| `pending {agentId}` | the caller's offers/queue/holds (attach to every tool result) |
+| `status {pool?}` / `inspect` / `get_config` / `configure {expectedVersion, changes, reason, author}` | state + versioned CAS config |
+| `start_job {permitToken, pid, pgid?}` | atomic permit↔process association (tracked) |
+| `mark_started {permitToken}` | untracked lease fallback |
+| `heartbeat {agentId}` | keep untracked leases alive |
+| `watch {agentId\|*}` / `events {sinceEventId, agentId?}` | push/pull event streams (durable ids) |
+| `offers_for_cwd {cwd}` | for hook scripts without session identity |
+
+## Lifecycle contract (the part that must not be improvised)
+
+- Associate a permit with real execution **atomically**: spawn the job in
+  its own process group, then `start_job` with pid+pgid; if association
+  fails, kill the group immediately. Register exit listeners *before*
+  awaiting the association RPC (a fast-exiting job can otherwise lose its
+  release event — this was a real bug here).
+- Never release because the shell returned a background-task id; release
+  (or auto-release) on actual process-group completion.
+- Do not auto-release on agent disconnect; that's the whole point of the
+  daemon holding ownership.
+- Untracked (`mark_started`) permits are only as good as your heartbeats;
+  document the tradeoff and steer agents toward tracked paths.
+
+## Testing your adapter
+
+Reuse `src/test/testutil.ts`-style harness spawning (isolated
+`LOAD_LOCK_STATE_DIR`/`LOAD_LOCK_SOCKET`, probe the socket, then
+`LLClient`), or simply script against the CLI. Concurrency rules to verify:
+capacity is never exceeded by held+offered, FIFO order holds, duplicate
+acquires are idempotent, and a daemon restart keeps tracked permits
+alive. Label your adapter honestly in docs/COMPATIBILITY.md:
+implemented / contract-tested / live-verified.