@aron98/load-lock 1.2.0 → 1.3.0

package/dist/test/update.test.js

@@ -0,0 +1,455 @@
+/**
+ * Integration tests for the update story (issue #34):
+ *  - version handshake: hello/status carry daemonVersion; clients stamp
+ *    their envelope with clientVersion
+ *  - daemon self-restart: a NEWER client orders the daemon to persist
+ *    state, drain, and respawn with the same argv (state survives)
+ *  - same/older clients never restart it; no restart loops per version
+ *  - offered entries restart as queued and are re-offered with fresh tokens
+ *  - `service stop` waits bounded, escalates to SIGKILL, verifies the
+ *    socket is free, and reports honestly
+ *  - `service start` refusals name the conflicting pid
+ *  - `doctor` reports installed copies and warns on drift
+ *
+ * Modeled after daemon.test.ts: real daemons over real sockets in temp
+ * state dirs (LL_TEST_TMP / $TMPDIR/opencode — never the user's real dir).
+ */
+import test from "node:test";
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync, existsSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { connect, createServer } from "node:net";
+import { LLClient } from "../shared/client.js";
+import { packageVersion } from "../shared/version.js";
+import { startDaemon, probe, delay, until, cliMainPath } from "./testutil.js";
+const TMP_BASE = process.env.LL_TEST_TMP ?? join(tmpdir(), "opencode");
+mkdirSync(TMP_BASE, { recursive: true });
+const ACQ = (agentId, opKey, extra = {}) => ({
+    agentId,
+    opKey,
+    reason: "update-story test",
+    ...extra,
+});
+/** Send a raw (handcrafted) envelope line; resolve the first response. */
+function rawRequest(sockPath, envelope, timeoutMs = 3000) {
+    return new Promise((resolve) => {
+        let settled = false;
+        let buf = "";
+        const done = (v) => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                s.destroy();
+            }
+            catch {
+                /* ignore */
+            }
+            resolve(v);
+        };
+        const s = connect(sockPath, () => {
+            s.write(JSON.stringify(envelope) + "\n");
+        });
+        s.on("data", (chunk) => {
+            buf += chunk.toString("utf8");
+            const idx = buf.indexOf("\n");
+            if (idx === -1)
+                return;
+            try {
+                done(JSON.parse(buf.slice(0, idx)));
+            }
+            catch {
+                done(null);
+            }
+        });
+        s.on("error", () => done(null));
+        setTimeout(() => done(null), timeoutMs).unref?.();
+    });
+}
+/** hello envelope with an explicit client version (the handshake trigger). */
+const helloFrom = (clientVersion) => ({ id: 1, method: "hello", params: {}, ...(clientVersion ? { clientVersion } : {}) });
+/** Run the CLI with an explicit env (for fake-daemon fixtures). */
+function runCliEnv(env, args, timeoutMs = 60_000) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, [cliMainPath, ...args], { env });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (b) => (stdout += b));
+        child.stderr.on("data", (b) => (stderr += b));
+        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);
+        });
+    });
+}
+/** Kill whatever daemon currently owns the state dir (respawned daemons are not our child). */
+function killDaemonFromJson(dir) {
+    try {
+        const info = JSON.parse(readFileSync(join(dir, "daemon.json"), "utf8"));
+        if (typeof info.pid === "number") {
+            try {
+                process.kill(info.pid, "SIGKILL");
+            }
+            catch {
+                /* already gone */
+            }
+        }
+    }
+    catch {
+        /* no daemon.json — nothing to kill */
+    }
+}
+/** Wait for the daemon on dir/sock to have a pid different from `oldPid`. */
+async function waitRespawned(d, oldPid, timeoutMs = 15_000) {
+    let pid = 0;
+    await until("daemon respawned with a new pid", async () => {
+        if (!(await probe(d.sock)))
+            return false;
+        const r = await rawRequest(d.sock, helloFrom(), 2000);
+        if (r && r.ok && r.result && r.result.pid !== oldPid) {
+            pid = r.result.pid;
+            return true;
+        }
+        return false;
+    }, timeoutMs);
+    return pid;
+}
+// ------------------------------------------------------------------ tests
+test("handshake: hello/status carry daemonVersion; client envelope carries clientVersion", async () => {
+    const d = await startDaemon();
+    try {
+        const c = d.client();
+        await c.connect();
+        const h = (await c.request("hello", {}));
+        assert.equal(h.daemonVersion, packageVersion(), "hello reports the daemon package version");
+        const st = (await c.request("status", {}));
+        assert.equal(st.daemon.daemonVersion, packageVersion(), "status reports the daemon package version");
+        c.close();
+        // A client with no version (pre-handshake) gets a normal response — the
+        // field is additive both ways.
+        const r = await rawRequest(d.sock, helloFrom());
+        assert.ok(r.ok);
+        assert.equal(r.result.daemonVersion, packageVersion());
+        // The shared client stamps its envelope: a fake server captures the line.
+        const capDir = mkdtempSync(join(TMP_BASE, "ll-capture-"));
+        const capSock = join(capDir, "cap.sock");
+        let captured = "";
+        const server = createServer((s) => {
+            s.on("data", (chunk) => {
+                captured += chunk.toString("utf8");
+                const idx = captured.indexOf("\n");
+                if (idx !== -1) {
+                    try {
+                        const msg = JSON.parse(captured.slice(0, idx));
+                        s.write(JSON.stringify({ id: msg.id, ok: true, result: { echo: true } }) + "\n");
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                }
+            });
+        });
+        await new Promise((r) => server.listen(capSock, r));
+        const cc = new LLClient({ socket: capSock, stateDir: capDir, spawnDaemon: false });
+        await cc.connect();
+        await cc.request("hello", {});
+        cc.close();
+        await new Promise((r) => server.close(() => r()));
+        const envelope = JSON.parse(captured.trim());
+        assert.equal(envelope.clientVersion, packageVersion(), "client envelope carries clientVersion");
+        rmSync(capDir, { recursive: true, force: true });
+        // `service status` surfaces the version too.
+        const svc = await runCliEnv(d.env, ["service", "status"]);
+        assert.equal(svc.code, 0);
+        assert.ok(svc.stdout.includes(`daemon v${packageVersion()}`), `service status shows daemon version: ${svc.stdout}`);
+    }
+    finally {
+        await d.stop();
+    }
+});
+test("self-restart: newer client respawns the daemon; held permits and queued requests survive", async () => {
+    const d = await startDaemon();
+    try {
+        const pid1 = d.child.pid;
+        const c = d.client();
+        await c.connect();
+        // A: held, tracked on a live sleeper process.
+        const g = (await c.request("acquire", ACQ("A", "op1")));
+        const permitToken = g.entry.permitToken;
+        const sleeper = spawn("sleep", ["60"], { stdio: "ignore" });
+        await c.request("attach_pid", { permitToken, pid: sleeper.pid });
+        // B: queued behind A (capacity 1).
+        const q = (await c.request("acquire", ACQ("B", "op2")));
+        assert.equal(q.state, "queued");
+        const bRequestId = q.entry.requestId;
+        c.close();
+        // A NEWER client shows up -> the daemon answers first, then restarts.
+        const r = await rawRequest(d.sock, helloFrom("999.0.0"));
+        assert.ok(r.ok, "hello response still delivered before the restart");
+        const pid2 = await waitRespawned(d, pid1);
+        assert.notEqual(pid2, pid1);
+        // Held permit survived with the same token and tracking.
+        const c2 = d.client();
+        await c2.connect();
+        const st = (await c2.request("status", {}));
+        assert.equal(st.daemon.daemonVersion, packageVersion());
+        assert.equal(st.pools[0].holders.length, 1, "held permit survives the self-restart");
+        assert.equal(st.pools[0].holders[0].phase, "running_tracked");
+        assert.equal(st.pools[0].holders[0].pid, sleeper.pid);
+        // Queued request survived, same id (idempotent re-acquire keeps working).
+        assert.equal(st.pools[0].queue.length, 1, "queued request survives the self-restart");
+        assert.equal(st.pools[0].queue[0].requestId, bRequestId);
+        // Same permit token still releases.
+        const rel = (await c2.request("release", { permitToken }));
+        assert.equal(rel.releasedNow, true);
+        // Idempotent re-acquire of the queued request resolves to the same id.
+        const again = (await c2.request("acquire", ACQ("B", "op2")));
+        assert.equal(again.entry.requestId, bRequestId);
+        c2.close();
+        sleeper.kill("SIGKILL");
+        await new Promise((r) => sleeper.once("exit", r));
+    }
+    finally {
+        killDaemonFromJson(d.dir);
+        await d.stop();
+    }
+});
+test("no restart for same/older clients, and no restart loop after a respawn", async () => {
+    const d = await startDaemon();
+    try {
+        const pid1 = d.child.pid;
+        // Same version: no restart.
+        await rawRequest(d.sock, helloFrom(packageVersion()));
+        await delay(600);
+        const s1 = await rawRequest(d.sock, helloFrom());
+        assert.equal(s1.result.pid, pid1, "same-version client does not restart the daemon");
+        // Older client: no restart.
+        await rawRequest(d.sock, helloFrom("0.0.1"));
+        await delay(600);
+        const s2 = await rawRequest(d.sock, helloFrom());
+        assert.equal(s2.result.pid, pid1, "older client does not restart the daemon");
+        // No clientVersion at all (pre-handshake client): no restart.
+        await rawRequest(d.sock, helloFrom());
+        await delay(600);
+        const s3 = await rawRequest(d.sock, helloFrom());
+        assert.equal(s3.result.pid, pid1);
+        // Now restart for 999.0.0 ...
+        await rawRequest(d.sock, helloFrom("999.0.0"));
+        const pid2 = await waitRespawned(d, pid1);
+        // ... and confirm neither 999.0.0 again nor an older version restarts
+        // it a second time (LOAD_LOCK_RESTARTED_FOR marker prevents loops).
+        await rawRequest(d.sock, helloFrom("999.0.0"));
+        await delay(600);
+        await rawRequest(d.sock, helloFrom("500.0.0"));
+        await delay(600);
+        const s4 = await rawRequest(d.sock, helloFrom());
+        assert.equal(s4.result.pid, pid2, "respawned daemon is stable (no restart loop)");
+    }
+    finally {
+        killDaemonFromJson(d.dir);
+        await d.stop();
+    }
+});
+test("offered entry restarts as queued and is re-offered with a fresh token", async () => {
+    const d = await startDaemon();
+    try {
+        const pid1 = d.child.pid;
+        const cA = d.client();
+        await cA.connect();
+        const gA = (await cA.request("acquire", ACQ("A", "op1")));
+        const cB = d.client();
+        await cB.connect();
+        const qB = (await cB.request("acquire", ACQ("B", "op1")));
+        assert.equal(qB.state, "queued");
+        // Free capacity -> B is offered (token t1).
+        await cA.request("release", { permitToken: gA.entry.permitToken });
+        const pend1 = (await cB.request("pending", { agentId: "B" }));
+        assert.equal(pend1.offers.length, 1);
+        const t1 = pend1.offers[0].offerToken;
+        assert.ok(t1);
+        cA.close();
+        cB.close();
+        // Self-restart while the offer is outstanding.
+        await rawRequest(d.sock, helloFrom("999.0.0"));
+        await waitRespawned(d, pid1);
+        // After the restart B is offered again — with a FRESH token.
+        const c2 = d.client();
+        await c2.connect();
+        const pend2 = (await c2.request("pending", { agentId: "B" }));
+        assert.equal(pend2.offers.length, 1, "queued-then-offered request is re-offered after restart");
+        const t2 = pend2.offers[0].offerToken;
+        assert.ok(t2);
+        assert.notEqual(t2, t1, "offer token is fresh after the restart");
+        // The fresh token claims; the pre-restart token is stale.
+        const cl = (await c2.request("claim", { offerToken: t2 }));
+        assert.equal(cl.entry.state, "held", "fresh offer token claims after the restart");
+        await assert.rejects(c2.request("claim", { offerToken: t1 }), (e) => e.code === "stale_token");
+        await c2.request("release", { permitToken: cl.entry.permitToken });
+        c2.close();
+    }
+    finally {
+        killDaemonFromJson(d.dir);
+        await d.stop();
+    }
+});
+test("service stop: graceful stop verified socket-free, daemon.json cleaned", async () => {
+    const d = await startDaemon();
+    try {
+        const r = await runCliEnv(d.env, ["service", "stop"]);
+        assert.equal(r.code, 0, `stdout: ${r.stdout} stderr: ${r.stderr}`);
+        assert.ok(r.stdout.includes("stopped"), `honest success message: ${r.stdout}`);
+        assert.ok(!(await probe(d.sock)), "socket is verifiably free");
+        assert.ok(!existsSync(join(d.dir, "daemon.json")), "daemon.json removed");
+    }
+    finally {
+        await d.stop();
+    }
+});
+test("service stop: escalates to SIGKILL for a hung daemon and cleans the stale socket", async () => {
+    const dir = mkdtempSync(join(TMP_BASE, "ll-hung-"));
+    const sock = join(dir, "daemon.sock");
+    // A fake daemon: owns the socket, writes daemon.json, ignores SIGTERM.
+    const script = `
+    const net = require("net");
+    const fs = require("fs");
+    const dir = process.argv[1], sock = process.argv[2];
+    fs.writeFileSync(require("path").join(dir, "daemon.json"),
+      JSON.stringify({ pid: process.pid, startedAt: Date.now(), socket: sock }));
+    process.on("SIGTERM", () => {});
+    const srv = net.createServer((s) => { s.on("data", () => {}); });
+    srv.listen(sock, () => { setInterval(() => {}, 1000); });
+  `;
+    const child = spawn(process.execPath, ["-e", script, dir, sock], {
+        stdio: "ignore",
+        env: { ...process.env, LOAD_LOCK_STATE_DIR: dir, LOAD_LOCK_SOCKET: sock },
+    });
+    await until("fake hung daemon listens", () => probe(sock));
+    const fakePid = child.pid;
+    try {
+        const r = await runCliEnv({ ...process.env, LOAD_LOCK_STATE_DIR: dir, LOAD_LOCK_SOCKET: sock }, ["service", "stop", "--timeout", "700"]);
+        assert.equal(r.code, 0, `stdout: ${r.stdout} stderr: ${r.stderr}`);
+        assert.ok(/SIGKILL/i.test(r.stdout), `reports the escalation honestly: ${r.stdout}`);
+        // The hung process is really dead and the endpoint is really free.
+        await until("hung daemon exits", () => !isAlive(fakePid));
+        assert.ok(!existsSync(sock), "stale socket file cleaned");
+        assert.ok(!existsSync(join(dir, "daemon.json")), "stale daemon.json cleaned");
+    }
+    finally {
+        try {
+            child.kill("SIGKILL");
+        }
+        catch {
+            /* ignore */
+        }
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+test("service start: refusal names the conflicting pid when the daemon hangs", async () => {
+    const dir = mkdtempSync(join(TMP_BASE, "ll-refuse-"));
+    const sock = join(dir, "daemon.sock");
+    // Accepts connections but never answers hello; writes daemon.json.
+    const script = `
+    const net = require("net");
+    const fs = require("fs");
+    const path = require("path");
+    const dir = process.argv[1], sock = process.argv[2];
+    fs.writeFileSync(path.join(dir, "daemon.json"),
+      JSON.stringify({ pid: process.pid, startedAt: Date.now(), socket: sock }));
+    const srv = net.createServer((s) => { s.on("data", () => {}); });
+    srv.listen(sock, () => { setInterval(() => {}, 1000); });
+  `;
+    const child = spawn(process.execPath, ["-e", script, dir, sock], {
+        stdio: "ignore",
+        env: { ...process.env, LOAD_LOCK_STATE_DIR: dir, LOAD_LOCK_SOCKET: sock },
+    });
+    await until("hung listener accepts", () => probe(sock));
+    const fakePid = child.pid;
+    try {
+        const r = await runCliEnv({ ...process.env, LOAD_LOCK_STATE_DIR: dir, LOAD_LOCK_SOCKET: sock }, ["service", "start", "--timeout", "1500"], 30_000);
+        assert.notEqual(r.code, 0, "start must fail honestly");
+        const combined = r.stdout + r.stderr;
+        assert.ok(combined.includes(String(fakePid)), `refusal names the conflicting pid: ${combined}`);
+        assert.ok(/daemon\.json names pid|answered from pid/.test(combined), `refusal points at the hang: ${combined}`);
+    }
+    finally {
+        try {
+            child.kill("SIGKILL");
+        }
+        catch {
+            /* ignore */
+        }
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test("service start: happy path reports pid + version", async () => {
+    const d = await startDaemon();
+    try {
+        const r = await runCliEnv(d.env, ["service", "start"]);
+        assert.equal(r.code, 0, `stdout: ${r.stdout} stderr: ${r.stderr}`);
+        assert.ok(r.stdout.includes(`running on pid ${d.child.pid}`), `names the daemon pid: ${r.stdout}`);
+        assert.ok(r.stdout.includes(`daemon v${packageVersion()}`), `names the daemon version: ${r.stdout}`);
+    }
+    finally {
+        await d.stop();
+    }
+});
+test("doctor: reports installed copies, versions, daemon skew, and copy drift", async () => {
+    const d = await startDaemon();
+    const cacheHome = mkdtempSync(join(TMP_BASE, "ll-cachehome-"));
+    const fakePkg = mkdtempSync(join(TMP_BASE, "ll-fakepkg-"));
+    try {
+        // A stale copy in opencode's npm cache (issue #34 multi-copy reality).
+        // Real layout: <cache>/opencode/npm/@aron98/load-lock@latest/<ts>/...
+        const cacheCopy = join(cacheHome, "opencode", "npm", "@aron98", "load-lock@latest", "1700000000000", "node_modules", "@aron98", "load-lock");
+        mkdirSync(cacheCopy, { recursive: true });
+        writeFileSync(join(cacheCopy, "package.json"), JSON.stringify({ name: "@aron98/load-lock", version: "0.1.2" }));
+        // A drift copy on PATH.
+        mkdirSync(join(fakePkg, "bin"), { recursive: true });
+        writeFileSync(join(fakePkg, "package.json"), JSON.stringify({ name: "@aron98/load-lock", version: "9.9.9" }));
+        writeFileSync(join(fakePkg, "bin", "load-lock"), "#!/bin/sh\ntrue\n");
+        const env = {
+            ...d.env,
+            XDG_CACHE_HOME: cacheHome,
+            PATH: join(fakePkg, "bin") + ":" + (process.env.PATH ?? ""),
+        };
+        const r = await runCliEnv(env, ["doctor", "--json"]);
+        assert.equal(r.code, 0, `stderr: ${r.stderr}`);
+        const report = JSON.parse(r.stdout);
+        assert.equal(report.installedVersion, packageVersion());
+        // Daemon reached and versioned.
+        assert.equal(report.hello.daemonVersion, packageVersion());
+        // Both planted copies are detected...
+        const versions = report.copies.map((c) => `${c.source}:${c.version}`);
+        assert.ok(versions.includes("opencode-cache:0.1.2"), `opencode cache copy found: ${versions.join(", ")}`);
+        assert.ok(versions.includes("path:9.9.9"), `PATH copy found: ${versions.join(", ")}`);
+        assert.ok(versions.includes(`cli:${packageVersion()}`), `running copy reported: ${versions.join(", ")}`);
+        // ...and the drift is warned about.
+        assert.ok(Array.isArray(report.warnings) && report.warnings.length > 0);
+        assert.ok(report.warnings.some((w) => w.includes("multiple load-lock versions") && w.includes("COMPATIBILITY")), `drift warning: ${JSON.stringify(report.warnings)}`);
+    }
+    finally {
+        await d.stop();
+        rmSync(cacheHome, { recursive: true, force: true });
+        rmSync(fakePkg, { recursive: true, force: true });
+    }
+});

package/docs/ARCHITECTURE.md

@@ -112,11 +112,15 @@ permits are journaled: on daemon restart, tracked permits are reconciled
 against real process liveness (dead ⇒ released, alive ⇒ kept, same tokens
 still valid), claimed permits keep their original start deadline, untracked
 permits get a fresh lease window, and a release arriving late for an entry
-that was reconciled is idempotent. Queues and offers are *not* journaled:
-they are ephemeral by design — queued agents are still running, notice the
-missed offer via their next tool call, and re-acquire; the daemon
-auto-spawns on the next client connection, so an agent never needs to know
-the daemon restarted. This is documented, deliberate behavior, not a bug.
+that was reconciled is idempotent. Queued *and offered* requests are journaled
+too (issue #34): they are re-queued FIFO by original enqueue time with the
+same request ids (idempotent re-acquire keeps working), entries offered at
+crash time restart as queued and are re-offered with fresh tokens — so a
+restart no longer silently drops a queue position. The daemon auto-spawns on
+the next client connection, and a *self-ordered* restart (version handshake:
+a newer client than the daemon) respawns with the same argv after persisting
+state — see the update lifecycle in
+[OPERATIONS.md](OPERATIONS.md#update-lifecycle).
 
 ## Notification honesty
 
@@ -191,7 +195,7 @@ prompts.
 | Agent disconnects mid-heavy-work | Permit retained; tracked job keeps capacity until the real process finishes; untracked job's lease survives until heartbeats stop |
 | Agent process crashes | Tracked permit auto-releases on confirmed process death; untracked reclaims after lease expiry |
 | Background job outlives the tool call | pgid tracking retains the permit until the whole group exits |
-| Daemon crash/restart | Auto-respawn on next connect; journal reconciliation of held permits (conservative: dead ⇒ released, alive ⇒ kept); queues/offers ephemeral by design |
+| Daemon crash/restart | Auto-respawn on next connect; journal reconciliation of held permits (conservative: dead ⇒ released, alive ⇒ kept); queued/offered requests re-queued FIFO with same ids, offered entries re-offered with fresh tokens |
 | Stale/forged token | Opaque tokens; wrong-owner claim/release rejected; expired offers rejected with a precise error |
 | Forgotten release | start deadline (claimed), process death (tracked), lease expiry (untracked), plus human `recover force-release` |
 | PID reuse | `/proc` start-time comparison |

package/docs/COMPATIBILITY.md

@@ -43,6 +43,7 @@ Status labels mean exactly this:
 | **Cline** | Yes (`cline_mcp_settings.json`, merge-only installer) | `~/.cline/rules/load-lock.md` (dedicated rule file) | Rules always loaded | No hooks — `wait_for_turn` bounded sleep is the primary idle mechanism | No | Via MCP `run_with_permit` only | **Implemented (fallback tier, config-tested)** |
 | **Roo Code** | Yes (project `.roo/mcp.json` + existing global `mcp_settings.json`, merge-only installer) | `~/.roo/rules/load-lock.md` (dedicated rule file) | Rules always loaded | No hooks — `wait_for_turn` bounded sleep is the primary idle mechanism | No | Via MCP `run_with_permit` only | **Implemented (fallback tier, config-tested)** |
 | **Goose** | Yes (`~/.config/goose/config.yaml` `extensions` block, merge-only installer) | `.goosehints` (global, marked section) | Hints always loaded | No hooks — `wait_for_turn` bounded sleep is the primary idle mechanism | No | Via MCP `run_with_permit` only | **Implemented (fallback tier, config-tested)** |
+| **omac** (agent sandbox; verified with 0.11.0) | N/A — omac is a sandbox runtime, not a harness: the agent inside it uses whichever harness adapter applies (OpenCode, Claude Code, …) | via the inner harness | via the inner harness | via the inner harness | via the inner harness | Full for the sandbox grants: `load-lock uninstall --harness omac` removes exactly the entries install added (match-own-entries, empty sections pruned) | **Sandbox-profile grants installed + live-verified** (`install --harness omac`: `filesystem.allow_unix_dir` += state dir, `filesystem.read` += package tree when needed, `environment.allow_vars` += `LOAD_LOCK_*`) |
 | **Aider** | **No MCP support** | CONVENTIONS.md / `.aider.conf.yml` | Read each run | N/A | N/A | CLI-only: same-shell `load-lock acquire ... && cmd; load-lock release ...` (manual) | Proposed (manual CLI tier) |
 
 ## How each integration tier works
@@ -72,6 +73,38 @@ tool round-trip (acquire → queued → wakeup → claim → release), execution
 boundary delivery without interrupting a running `sleep`, skill visible,
 and graceful handling of a deliberately missed offer (paused → cancel).
 
+#### Multiple copies of load-lock (opencode)
+
+`install --harness opencode` registers the **bare package name** in
+`~/.config/opencode/opencode.json`, so opencode maintains its own private
+copy of load-lock under
+`~/.cache/opencode/npm/@aron98/load-lock@latest/<timestamp>/node_modules/@aron98/load-lock/`,
+refreshed on opencode's schedule. That copy is *separate* from a globally
+installed CLI on PATH, and the two can drift (this was observed on a real
+machine with cache copies at 0.1.2, 1.0.0, 1.1.0 and 1.2.1 — issue #34).
+
+Which copy is authoritative for what:
+
+- **opencode plugin behavior** — the cache copy. Updated by opencode itself
+  (it refreshes the cache entry); you cannot reliably update it by hand.
+- **CLI commands** (`load-lock status`, `service`, `doctor`, …) — the copy on
+  PATH (typically a global install via npm/bun). Update it with your usual
+  global install command.
+- **The daemon's code** — whichever copy spawned it (usually the CLI copy,
+  since auto-spawn and `service start` run from the CLI client code). The
+  version handshake makes a daemon self-restart onto updated code when a
+  newer client contacts it — but the respawn reuses the daemon's original
+  argv, so it only picks up an update when its spawning copy was updated
+  *in place* (the normal global-upgrade case). A daemon spawned from a
+  different copy than the one you updated keeps running the old code until
+  `load-lock service stop` + any command re-spawns it from the new one.
+
+`load-lock doctor` lists every copy it can find (PATH-resolved CLI, this
+running copy, opencode cache copies) with versions and warns when they
+drift. Detection is best-effort (never crashes on missing paths) and was
+contract-tested with planted copies; the drift scenario itself was
+observed live on this machine before the feature existed.
+
 ### Tier 2 — Claude Code / Codex CLI (hooks + MCP, live-verified)
 
 `load-lock install --harness claude-code|codex` configures the MCP server
@@ -236,6 +269,40 @@ push channel, so a woken agent relies on tool results (which carry
 pending offers) rather than harness messages. We do not pretend these
 harnesses got push notifications.
 
+### omac — sandbox-profile grants (live-verified, issue #32)
+
+omac runs agent harnesses inside a sandbox (bubblewrap + Landlock on
+Linux, seatbelt on macOS) and strips the harness environment, allowing
+through only what the user-global profile lists — so a load-lock client
+inside omac cannot reach the host daemon without explicit grants.
+`load-lock install --harness omac` merges three grants into
+`~/.config/omac/sandbox-profiles/default.json` (merge-only, idempotent,
+reversible by uninstall; omac parses profiles strictly so the installer
+writes only known fields and never rewrites the user's bytes when
+nothing changed):
+
+- `filesystem.allow_unix_dir` += the load-lock state dir (AF_UNIX connect
+  to the host daemon socket + read/write on the state dir);
+- `filesystem.read` += the installed package tree — **only when load-lock
+  lives outside an already-granted workdir** (a repo checkout needs
+  nothing: the sandbox workdir grant covers it; a global bun/npm install
+  does need it, see OPERATIONS.md gotcha #1);
+- `environment.allow_vars` += `"LOAD_LOCK_*"` — one trailing-`*` prefix
+  entry that passes all four client vars (`LOAD_LOCK_SOCKET`,
+  `LOAD_LOCK_STATE_DIR`, `LOAD_LOCK_NO_SPAWN`, `LOAD_LOCK_LABEL_PREFIX`)
+  through omac's env filter.
+
+Verified live against omac 0.11.0 (see OPERATIONS.md for the exact
+procedure and the two gotchas): profile accepted by omac's strict parser,
+sandboxed CLI → host daemon round-trip, prefixed holder labels
+(`omac:<label>`), client-only (`LOAD_LOCK_NO_SPAWN=1`) error contract, and
+the global-install read grant proven necessary and sufficient
+(ERR_MODULE_NOT_FOUND without it, working round-trip with it).
+Install/uninstall round-trips are contract-tested in
+`src/test/install.test.ts` (temp HOME: populated profile preserved,
+idempotent re-install byte-identical, missing-profile creation, global
+read grant, refusal on broken profiles).
+
 ### Tier 4 — Aider (manual CLI)
 
 No MCP/hooks; nothing to install. Agents (or humans) use the CLI directly in
@@ -256,6 +323,7 @@ UI** — where no UI surface exists, we say so rather than claim parity.
 | **Codex CLI** | None in-app — same reason. `load_lock_status` MCP tool; `SessionStart`/`SubagentStart` machine summary. | `load-lock dashboard` (alias `top`) |
 | **Gemini CLI** | None in-app (no hooks, no UI plugin surface). `load_lock_status` MCP tool at tool boundaries. | `load-lock dashboard` (alias `top`) |
 | **Copilot CLI, Cursor, Cline, Roo Code, Goose** | None in-app. MCP `status` tool where the MCP server is configured. | `load-lock dashboard` (alias `top`) |
+| **omac** | None added by the omac installer — it only edits the sandbox profile; the inner harness keeps whatever surface its own adapter provides. | `load-lock dashboard` (alias `top`) |
 | **Aider** | None (no MCP either). | `load-lock dashboard` (alias `top`) |
 
 All dashboard surfaces are **read-only viewers that never acquire a
@@ -272,6 +340,7 @@ reconnect, view-model shaping, frame rendering) is covered by
 | Claude Code | hooks get `session_id`; MCP tools take explicit `agent_id` | policy instructs agents to pass it |
 | Codex | hooks get `session_id`; MCP tools take explicit `agent_id` | same |
 | Cursor | hooks get `conversation_id` (no `cwd` — `workspace_roots[0]` identifies the request); MCP tools take explicit `agent_id` | same |
+| omac (sandbox) | inner harness identity + `LOAD_LOCK_LABEL_PREFIX=omac` | dashboard shows holders as `omac:<label>` |
 | Tier 3 | explicit `agent_id` argument | falls back to per-server-process id |
 
 ## Platform matrix
@@ -289,19 +358,25 @@ reconnect, view-model shaping, frame rendering) is covered by
   asyncRewake wakeup paths, subagents, background-job cleanup); Codex CLI
   (Docker, interactive TUI: policy injection, MCP round-trip, FIFO queueing
   behind a CLI holder, Stop-hook decision-block wakeup; exec-mode MCP
-  injection blocked upstream — see Tier 2 notes).
+  injection blocked upstream — see Tier 2 notes); omac 0.11.0 (sandbox
+  grants installer: profile accepted by omac's strict parser, sandboxed
+  client → host daemon round-trip, `omac:`-prefixed labels,
+  `LOAD_LOCK_NO_SPAWN=1` error contract, global-install read grant proven
+  necessary and sufficient — see the omac section above and OPERATIONS.md).
 - Contract-tested: Cursor (hooks-v1 stop-hook adapter + installer, tested
   against the officially documented hooks JSON contract; no Cursor install
   on the verification machine — see the Cursor section under Tier 2).
 - Config-tested: Gemini CLI, Copilot CLI, Cline, Roo Code, Goose (installer
   round-trips, temp HOME; real harnesses not installed on the verification
   machine).
-- Core daemon/protocol/CLI: 68 automated tests + scripted 3-worktree demo
+- Core daemon/protocol/CLI + adapters: 125 automated tests + scripted 3-worktree demo
   (three independent agent processes, real git worktrees, one pool), including
   9 dashboard tests (view-model shaping, event-cursor resume across a daemon
-  restart, reconnect, and a `load-lock dashboard --once` render smoke test) and
+  restart, reconnect, and a `load-lock dashboard --once` render smoke test),
   9 bounded-wait tests (multi-process `wait_for_turn`: FIFO wake with
   auto-claim, timeout/pause/cancel/restart/abort paths, `maxTurnWaitMs` cap,
-  MCP snake_case round trip).
+  MCP snake_case round trip) and 5 omac installer contract tests
+  (populated-profile preservation, idempotent re-install, missing-profile
+  creation, global-install read grant, broken-profile refusal).
 - Proposed (researched capabilities, generic adapter only):
   Aider.