@aron98/load-lock 1.1.0 → 1.2.1

package/dist/test/install.test.js

@@ -5,7 +5,7 @@
  */
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, rmSync, mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { mkdtempSync, rmSync, mkdirSync, readFileSync, writeFileSync, existsSync, cpSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -656,3 +656,183 @@ test("cursor: uninstall with nothing installed is a harmless no-op", async () =>
     assert.ok(!existsSync(join(proj, ".cursor")), "no files created by uninstall");
     rmSync(home, { recursive: true, force: true });
 });
+// --------------------------------------------------------------------- omac
+// The omac profile the installer must merge into without damaging it:
+// entries in every known section plus an unknown field (a newer omac
+// would accept it; we must preserve it untouched).
+function omacUserProfile(home) {
+    return JSON.stringify({
+        workdir: { access: "readwrite" },
+        network: { allow_domain: ["example.com"], allow_tcp_connect: [22] },
+        filesystem: {
+            allow: ["/data"],
+            read: ["/docs"],
+            write: ["/out"],
+            allow_unix_dir: ["/tmp/other-socks"],
+            deny: [".env"],
+        },
+        environment: { allow_vars: ["ANTHROPIC_API_KEY", "MY_*"] },
+        someFutureField: { nested: true },
+    }, null, 2) + "\n";
+}
+function omacProfilePath(home) {
+    return join(home, ".config", "omac", "sandbox-profiles", "default.json");
+}
+test("omac: install/uninstall round-trip on a populated profile; re-install is byte-identical", async () => {
+    const home = tempHome();
+    const xdg = join(home, ".config");
+    const profileFile = omacProfilePath(home);
+    mkdirSync(dirname(profileFile), { recursive: true });
+    const before = omacUserProfile(home);
+    writeFileSync(profileFile, before);
+    const stateDir = join(home, "ll-state");
+    const env = { XDG_CONFIG_HOME: xdg, LOAD_LOCK_STATE_DIR: stateDir, XDG_STATE_HOME: join(home, ".local", "state") };
+    // -- install
+    let r = await runCli(home, ["install", "--harness", "omac"], env);
+    assert.equal(r.code, 0, `install failed: ${r.stderr}`);
+    // honesty: live-verified claim, the env prefix entry, and the state-dir grant
+    assert.match(r.stdout, /live-verified.*omac 0\.11\.0|verified live against omac 0\.11\.0/i, "installer output must state the verification status");
+    assert.match(r.stdout, /LOAD_LOCK_\*/, "installer output must mention the LOAD_LOCK_* allow_vars entry");
+    assert.match(r.stdout, /allow_unix_dir \+=/, "installer output must mention the state-dir grant");
+    assert.match(r.stdout, /skipped filesystem\.read.*repo checkout/, "installer output must honestly note the skipped read grant (CLI runs from a repo checkout)");
+    const p = JSON.parse(readFileSync(profileFile, "utf8"));
+    // user entries preserved everywhere
+    assert.deepEqual(p.workdir, { access: "readwrite" }, "user workdir section preserved");
+    assert.deepEqual(p.network, { allow_domain: ["example.com"], allow_tcp_connect: [22] }, "user network section preserved");
+    assert.deepEqual(p.filesystem.allow, ["/data"], "user filesystem.allow preserved");
+    assert.deepEqual(p.filesystem.write, ["/out"], "user filesystem.write preserved");
+    assert.deepEqual(p.filesystem.deny, [".env"], "user filesystem.deny preserved");
+    assert.deepEqual(p.filesystem.read, ["/docs"], "read untouched — repo checkout needs no package-tree grant");
+    assert.deepEqual(p.someFutureField, { nested: true }, "unknown (newer-omac) field preserved");
+    // our grants, exactly once, alongside the user's
+    assert.deepEqual(p.filesystem.allow_unix_dir, ["/tmp/other-socks", stateDir], "state dir appended to allow_unix_dir");
+    assert.deepEqual(p.environment.allow_vars, ["ANTHROPIC_API_KEY", "MY_*", "LOAD_LOCK_*"], "LOAD_LOCK_* appended to allow_vars");
+    assert.equal(p.filesystem.allow_unix_dir.filter((e) => e === stateDir).length, 1, "state dir granted exactly once");
+    // -- idempotent re-install: the file is not rewritten at all
+    const afterInstall = readFileSync(profileFile, "utf8");
+    r = await runCli(home, ["install", "--harness", "omac"], env);
+    assert.equal(r.code, 0, `re-install failed: ${r.stderr}`);
+    assert.equal(readFileSync(profileFile, "utf8"), afterInstall, "re-install must be byte-identical");
+    assert.match(r.stdout, /already present.*nothing to do/, "re-install must say nothing was needed");
+    // -- uninstall removes exactly our entries
+    r = await runCli(home, ["uninstall", "--harness", "omac"], env);
+    assert.equal(r.code, 0, `uninstall failed: ${r.stderr}`);
+    const u = JSON.parse(readFileSync(profileFile, "utf8"));
+    assert.deepEqual(u.filesystem.allow_unix_dir, ["/tmp/other-socks"], "our state dir removed, user entry kept");
+    assert.ok(!u.filesystem.read.includes(stateDir), "no stray read grant");
+    assert.deepEqual(u.filesystem.read, ["/docs"], "user read entry kept");
+    assert.deepEqual(u.environment.allow_vars, ["ANTHROPIC_API_KEY", "MY_*"], "our env entry removed, user entries kept");
+    assert.deepEqual(u.workdir, { access: "readwrite" }, "user sections untouched by uninstall");
+    assert.deepEqual(u.someFutureField, { nested: true }, "unknown field untouched by uninstall");
+    rmSync(home, { recursive: true, force: true });
+});
+test("omac: install on a missing profile creates a minimal valid one (XDG_STATE_HOME honored); uninstall cleans it", async () => {
+    const home = tempHome();
+    const xdg = join(home, ".config");
+    const profileFile = omacProfilePath(home);
+    const xdgState = join(home, ".local", "state");
+    // LOAD_LOCK_STATE_DIR: "" clears any inherited override so XDG_STATE_HOME is honored
+    const env = { XDG_CONFIG_HOME: xdg, LOAD_LOCK_STATE_DIR: "", XDG_STATE_HOME: xdgState };
+    let r = await runCli(home, ["install", "--harness", "omac"], env);
+    assert.equal(r.code, 0, `install failed: ${r.stderr}`);
+    assert.ok(existsSync(profileFile), "profile created");
+    const p = JSON.parse(readFileSync(profileFile, "utf8"));
+    // minimal valid profile: only known fields, no empty arrays, no read grant (repo checkout)
+    assert.deepEqual(p, {
+        environment: { allow_vars: ["LOAD_LOCK_*"] },
+        filesystem: { allow_unix_dir: [join(xdgState, "load-lock")] },
+    }, "created profile holds exactly our grants");
+    // XDG_STATE_HOME honored: default state dir, not ~/.local/state off the real HOME
+    assert.ok(p.filesystem.allow_unix_dir[0].startsWith(xdgState), "state dir derived from XDG_STATE_HOME");
+    // idempotent re-install: byte-identical
+    const bytes = readFileSync(profileFile, "utf8");
+    r = await runCli(home, ["install", "--harness", "omac"], env);
+    assert.equal(r.code, 0, `re-install failed: ${r.stderr}`);
+    assert.equal(readFileSync(profileFile, "utf8"), bytes, "re-install is byte-identical");
+    // uninstall removes the file (nothing user-owned was ever in it) and prunes dirs
+    r = await runCli(home, ["uninstall", "--harness", "omac"], env);
+    assert.equal(r.code, 0, `uninstall failed: ${r.stderr}`);
+    assert.ok(!existsSync(profileFile), "our file removed");
+    assert.ok(!existsSync(join(xdg, "omac")), "empty omac config tree pruned");
+    rmSync(home, { recursive: true, force: true });
+});
+test("omac: a global-style install (package outside any repo) adds the package-tree read grant; uninstall removes it by shape", async () => {
+    const home = tempHome();
+    const xdg = join(home, ".config");
+    const stateDir = join(home, "ll-state");
+    const env = { XDG_CONFIG_HOME: xdg, LOAD_LOCK_STATE_DIR: stateDir, XDG_STATE_HOME: join(home, ".local", "state") };
+    // simulate a global install: package tree under node_modules, outside any .git
+    const pkgMock = join(home, "bun-mock", "install", "global", "node_modules", "@aron98", "load-lock");
+    mkdirSync(dirname(pkgMock), { recursive: true });
+    cpSync(join(HERE, ".."), join(pkgMock, "dist"), { recursive: true }); // dist/ from the worktree build
+    const mockCli = join(pkgMock, "dist", "cli", "main.js");
+    const profileFile = omacProfilePath(home);
+    const runMock = (args) => new Promise((resolveP, reject) => {
+        const child = spawn(process.execPath, [mockCli, ...args], { env: { ...process.env, HOME: home, ...env } });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (b) => (stdout += b));
+        child.stderr.on("data", (b) => (stderr += b));
+        child.stdin.end();
+        child.once("exit", (code) => resolveP({ code, stdout, stderr }));
+        child.once("error", reject);
+    });
+    let r = await runMock(["install", "--harness", "omac"]);
+    assert.equal(r.code, 0, `install failed: ${r.stderr}`);
+    assert.match(r.stdout, /filesystem\.read \+=/, "installer output must mention the package-tree read grant");
+    const p = JSON.parse(readFileSync(profileFile, "utf8"));
+    const pkgReal = resolve(pkgMock);
+    assert.deepEqual(p.filesystem.read, [pkgReal], "read grant is the realpath of the package root");
+    assert.ok(p.filesystem.allow_unix_dir.includes(stateDir), "state dir granted too");
+    // idempotent re-install from the global copy: byte-identical
+    const bytes = readFileSync(profileFile, "utf8");
+    r = await runMock(["install", "--harness", "omac"]);
+    assert.equal(r.code, 0, `re-install failed: ${r.stderr}`);
+    assert.equal(readFileSync(profileFile, "utf8"), bytes, "re-install is byte-identical");
+    // uninstall from the WORKTREE CLI (a different location, readTree is null
+    // there): the read entry still matches by its node_modules/@aron98/load-lock shape
+    r = await runCli(home, ["uninstall", "--harness", "omac"], env);
+    assert.equal(r.code, 0, `uninstall failed: ${r.stderr}`);
+    assert.ok(!existsSync(profileFile), "profile held only our grants — removed");
+    rmSync(home, { recursive: true, force: true });
+});
+test("omac: uninstall with nothing installed is a harmless no-op", async () => {
+    const home = tempHome();
+    const r = await runCli(home, ["uninstall", "--harness", "omac"], { XDG_CONFIG_HOME: join(home, ".config"), LOAD_LOCK_STATE_DIR: join(home, "ll-state") });
+    assert.equal(r.code, 0, `uninstall failed: ${r.stderr}`);
+    assert.ok(!existsSync(join(home, ".config", "omac")), "no files created by uninstall");
+    rmSync(home, { recursive: true, force: true });
+});
+test("omac: install refuses to touch a broken or misshapen profile", async () => {
+    const home = tempHome();
+    const xdg = join(home, ".config");
+    const profileFile = omacProfilePath(home);
+    mkdirSync(dirname(profileFile), { recursive: true });
+    const env = { XDG_CONFIG_HOME: xdg, LOAD_LOCK_STATE_DIR: join(home, "ll-state") };
+    // (a) invalid JSON
+    const broken = "{ not json";
+    writeFileSync(profileFile, broken);
+    let r = await runCli(home, ["install", "--harness", "omac"], env);
+    assert.notEqual(r.code, 0, "install must refuse invalid JSON");
+    assert.match(r.stderr + r.stdout, /not valid JSON|refus/i, "error must explain the refusal");
+    assert.equal(readFileSync(profileFile, "utf8"), broken, "file untouched on refusal");
+    // (b) allow_vars present but not an array of strings
+    const misshapen = JSON.stringify({ environment: { allow_vars: "PATH" } }, null, 2) + "\n";
+    writeFileSync(profileFile, misshapen);
+    r = await runCli(home, ["install", "--harness", "omac"], env);
+    assert.notEqual(r.code, 0, "install must refuse a non-array allow_vars");
+    assert.match(r.stderr + r.stdout, /allow_vars.*not an array/i, "error must name the offending field");
+    assert.equal(readFileSync(profileFile, "utf8"), misshapen, "file untouched on refusal");
+    // uninstall also refuses (never "fixes" the file by overwriting it) on invalid JSON
+    writeFileSync(profileFile, broken);
+    r = await runCli(home, ["uninstall", "--harness", "omac"], env);
+    assert.notEqual(r.code, 0, "uninstall must refuse invalid JSON too");
+    assert.equal(readFileSync(profileFile, "utf8"), broken, "file untouched on refusal");
+    // on a merely misshapen value (valid JSON, allow_vars not an array) uninstall
+    // is a graceful no-op: it never wrote that value, so it leaves it alone
+    writeFileSync(profileFile, misshapen);
+    r = await runCli(home, ["uninstall", "--harness", "omac"], env);
+    assert.equal(r.code, 0, `uninstall failed: ${r.stderr}`);
+    assert.equal(readFileSync(profileFile, "utf8"), misshapen, "file untouched by uninstall");
+    rmSync(home, { recursive: true, force: true });
+});

package/dist/test/mcp.test.js

@@ -32,10 +32,11 @@ test("mcp: tool listing + acquire/release/configure round trip", async () => {
         for (const expected of ["acquire", "claim", "release", "cancel", "rejoin", "pending", "wait_for_turn", "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" });
+        const acq = await callJson(c, "acquire", { reason: "build", op_key: "mcp-rt", agent_id: "mcpAgentA", label_prefix: "omac" });
         assert.equal(acq.state, "granted");
         assert.ok(acq.permit_token, "acquire result carries permit_token");
         assert.ok(acq.next_action, "structured next_action present");
+        assert.equal(acq.entry.agentLabel, "omac:mcpAgentA", "label_prefix composes the holder label");
         // 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");

package/dist/test/sandbox.test.d.ts

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

package/dist/test/sandbox.test.js

@@ -0,0 +1,155 @@
+/**
+ * Issue #29: sandboxed thin clients.
+ *
+ *  - Client-only mode (LOAD_LOCK_NO_SPAWN): with the env set and the socket
+ *    unreachable, the client must NEVER auto-spawn a daemon and must fail
+ *    loudly, pointing at the Sandboxes section of docs/OPERATIONS.md.
+ *  - Holder-label prefixing (labelPrefix / LOAD_LOCK_LABEL_PREFIX) so
+ *    sandboxed clients are identifiable in the dashboard.
+ */
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+import { LLClient, ensureDaemon } from "../shared/client.js";
+import { ProtocolError } from "../shared/protocol.js";
+import { startDaemon, delay, probe, cliMainPath } from "./testutil.js";
+const ACQ = (agentId, opKey, extra = {}) => ({
+    agentId,
+    opKey,
+    reason: "sandbox test",
+    ...extra,
+});
+/** Fresh empty state dir + socket path; the dir is NOT created. */
+function freshDir(prefix) {
+    const dir = mkdtempSync(join(process.env.LL_TEST_TMP ?? "/tmp", prefix));
+    rmSync(dir, { recursive: true, force: true }); // we want it absent
+    const sock = join(dir, "daemon.sock");
+    return { dir, sock, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+}
+/** Stop a daemon spawned via auto-spawn (pid recorded in daemon.json). */
+async function killSpawnedDaemon(dir) {
+    const info = JSON.parse(readFileSync(join(dir, "daemon.json"), "utf8"));
+    try {
+        process.kill(info.pid, "SIGTERM");
+    }
+    catch {
+        /* already gone */
+    }
+    await delay(300);
+}
+test("LOAD_LOCK_NO_SPAWN: no daemon spawned, loud error pointing at the docs", async () => {
+    const { dir, sock, cleanup } = freshDir("ll-nospawn-");
+    process.env.LOAD_LOCK_NO_SPAWN = "1";
+    try {
+        const c = new LLClient({ socket: sock, stateDir: dir });
+        await assert.rejects(() => c.connect(), (e) => {
+            assert.ok(e instanceof ProtocolError);
+            assert.equal(e.code, "unavailable");
+            assert.ok(e.message.includes("LOAD_LOCK_NO_SPAWN"), "error names the env var");
+            assert.ok(e.message.includes("docs/OPERATIONS.md"), "error points at the docs");
+            assert.ok(e.message.includes("Sandboxes"), "error points at the Sandboxes section");
+            assert.ok(e.message.includes(sock), "error names the unreachable socket");
+            return true;
+        });
+        // No daemon process was spawned: the state dir was never even created
+        // (ensureDaemon creates it only when spawning) and nothing is listening.
+        assert.equal(existsSync(dir), false, "no state dir created");
+        assert.equal(await probe(sock), false, "nothing listening on the socket");
+        await delay(1_000); // would-be spawner waits up to 10s; give it a beat
+        assert.equal(existsSync(dir), false, "still no state dir after a wait");
+        assert.equal(await probe(sock), false, "still no daemon after a wait");
+    }
+    finally {
+        delete process.env.LOAD_LOCK_NO_SPAWN;
+        cleanup();
+    }
+});
+test("LOAD_LOCK_NO_SPAWN: ensureDaemon refuses directly too", async () => {
+    const { dir, sock, cleanup } = freshDir("ll-nospawn2-");
+    process.env.LOAD_LOCK_NO_SPAWN = "true";
+    try {
+        await assert.rejects(() => ensureDaemon(dir, sock), (e) => e instanceof ProtocolError && e.message.includes("docs/OPERATIONS.md"));
+        assert.equal(existsSync(dir), false, "ensureDaemon created nothing");
+    }
+    finally {
+        delete process.env.LOAD_LOCK_NO_SPAWN;
+        cleanup();
+    }
+});
+test("LOAD_LOCK_NO_SPAWN=0 disables client-only mode (daemon auto-spawns)", async () => {
+    const { dir, sock, cleanup } = freshDir("ll-nospawn0-");
+    process.env.LOAD_LOCK_NO_SPAWN = "0";
+    try {
+        const c = new LLClient({ socket: sock, stateDir: dir });
+        await c.connect();
+        const hello = (await c.request("hello", {}));
+        assert.ok(hello.pid, "daemon spawned and reachable");
+        c.close();
+        await killSpawnedDaemon(dir);
+    }
+    finally {
+        delete process.env.LOAD_LOCK_NO_SPAWN;
+        cleanup();
+    }
+});
+test("CLI under LOAD_LOCK_NO_SPAWN fails loudly with a docs pointer", async () => {
+    const { dir, sock, cleanup } = freshDir("ll-nospawncli-");
+    const res = await new Promise((resolve) => {
+        const child = spawn(process.execPath, [cliMainPath, "status"], {
+            env: {
+                ...process.env,
+                LOAD_LOCK_NO_SPAWN: "1",
+                LOAD_LOCK_STATE_DIR: dir,
+                LOAD_LOCK_SOCKET: sock,
+            },
+        });
+        let stderr = "";
+        child.stderr.on("data", (b) => (stderr += b));
+        child.once("exit", (code) => resolve({ code, stderr }));
+    });
+    try {
+        assert.equal(res.code, 70, "unavailable -> exit 70");
+        assert.ok(res.stderr.includes("docs/OPERATIONS.md"), "stderr points at the docs");
+        assert.ok(res.stderr.includes("Sandboxes"), "stderr points at the Sandboxes section");
+        assert.equal(existsSync(dir), false, "CLI spawned no daemon");
+    }
+    finally {
+        cleanup();
+    }
+});
+test("daemon-side labelPrefix end-to-end: holder shows prefixed label", async () => {
+    const d = await startDaemon();
+    try {
+        const c = d.client();
+        const acq = (await c.request("acquire", ACQ("agentSbx", "sbx-1", { agentLabel: "issue-42 build", labelPrefix: "omac" })));
+        assert.equal(acq.state, "granted");
+        assert.equal(acq.entry.agentLabel, "omac:issue-42 build");
+        const st = (await c.request("status", {}));
+        assert.equal(st.pools[0].holders[0].agentLabel, "omac:issue-42 build");
+    }
+    finally {
+        await d.stop();
+    }
+});
+test("LOAD_LOCK_LABEL_PREFIX env is injected by the shared client; explicit param wins", async () => {
+    const d = await startDaemon();
+    process.env.LOAD_LOCK_LABEL_PREFIX = "bwrap";
+    try {
+        const c = d.client();
+        // injected from env when the acquire does not pass labelPrefix itself
+        const a = (await c.request("acquire", ACQ("agentEnv", "env-1", { agentLabel: "cargo test" })));
+        assert.equal(a.entry.agentLabel, "bwrap:cargo test");
+        // an explicit labelPrefix overrides the env-injected one
+        const b = (await c.request("acquire", ACQ("agentEnv", "env-2", { agentLabel: "x", labelPrefix: "omac" })));
+        assert.equal(b.entry.agentLabel, "omac:x");
+        // unprefixable clients (no label) still show the prefix via agentId fallback
+        const e2 = (await c.request("acquire", ACQ("agentEnv2", "env-3", { pool: "heavy", weight: 1 })));
+        assert.ok(String(e2.entry.agentLabel).startsWith("bwrap:"), `fallback label was ${e2.entry.agentLabel}`);
+    }
+    finally {
+        delete process.env.LOAD_LOCK_LABEL_PREFIX;
+        await d.stop();
+    }
+});

package/docs/ADAPTERS.md

@@ -84,7 +84,7 @@ normally touches:
 
 | Method | Purpose |
 | --- | --- |
-| `acquire {pool?, agentId, agentLabel?, cwd?, opKey, reason, weight?, waitMs?, subscribeIfBusy?}` | grant / queue (idempotent per agent+opKey) |
+| `acquire {pool?, agentId, agentLabel?, labelPrefix?, cwd?, opKey, reason, weight?, waitMs?, subscribeIfBusy?}` | grant / queue (idempotent per agent+opKey); labelPrefix composes `prefix:label` holder labels for sandboxed clients (env `LOAD_LOCK_LABEL_PREFIX` is injected by the shared client) |
 | `claim {offerToken}` | offer → permit (before starting heavy work) |
 | `release {permitToken, outcome?}` | idempotent |
 | `cancel {requestId}` / `rejoin {requestId}` / `decline {offerToken}` | queue hygiene |

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
@@ -62,8 +63,8 @@ Global plugin (`load-lock install --harness opencode`) registers:
   `load-lock.dashboard` session panel in-window (issue #24: side panel,
   not full-screen) with pools, holder cards, offer countdowns, queue,
   paused, event feed, `inspect_machine`; a clickable sidebar widget
-  (`load-lock 0/3`, health-colored; `gl` as the mouse-free fallback) and
-  a home-footer `lock 1/1·Q2` indicator; and an `x` force-release flow
+  (`load-lock 0/3`, health-colored; `/load-lock` as the mouse-free
+  fallback) and a home-footer `lock 1/1·Q2` indicator; and an `x` force-release flow
   gated behind an explicit select + confirm (the panel itself is read-only
   and never acquires a permit).
 
@@ -236,6 +237,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
@@ -251,11 +286,12 @@ UI** — where no UI surface exists, we say so rather than claim parity.
 
 | Harness | In-harness dashboard | Also available |
 | --- | --- | --- |
-| **OpenCode** | Native TUI panel: `/load-lock` opens `load-lock.dashboard` **in-window** as a side panel (also opened by the `gl` binding or a click on the sidebar widget) with pools, holder cards, offer claim-window countdowns, queue, paused, event feed, `inspect_machine`; home-footer `lock 1/1` indicator on the home screen plus a clickable, health-colored `load-lock 0/3` widget in the session sidebar; `x` force-release behind select + confirm. Implemented as the package's `./tui` companion plugin (main plugin unchanged). Live-verified: opencode 2.0.29 (panel render, palette/slash command, confirm-gated force-release) and opencode 2.0.32 in a real pty (sidebar widget render, click-to-open, `gl`, in-window presentation). | `load-lock dashboard` (alias `top`) |
+| **OpenCode** | Native TUI panel: `/load-lock` opens `load-lock.dashboard` **in-window** as a side panel (also opened by clicking the sidebar widget; deliberately **not** bound to any key — issue #28: the old `gl` sequence swallowed plain `g` typing, and the candidate `ctrl+g` is the host's `session.first` default) with pools, holder cards, offer claim-window countdowns, queue, paused, event feed, `inspect_machine`; home-footer `lock 1/1` indicator on the home screen plus a clickable, health-colored `load-lock 0/3` widget in the session sidebar; `x` force-release behind select + confirm. Implemented as the package's `./tui` companion plugin (main plugin unchanged). Live-verified: opencode 2.0.29 (panel render, palette/slash command, confirm-gated force-release) and opencode 2.0.32 in a real pty (sidebar widget render, click-to-open, in-window presentation, plain `g` reaches the composer, `ctrl+g` not intercepted by load-lock). | `load-lock dashboard` (alias `top`) |
 | **Claude Code** | None in-app — Claude Code has no plugin UI surface. The model can report status via the `load_lock_status` MCP tool at tool boundaries, and each `SessionStart` hook injects a one-line machine summary. | `load-lock dashboard` (any terminal) |
 | **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 +308,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 +326,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.