@aron98/load-lock 1.1.0 → 1.2.0

package/README.md

@@ -81,6 +81,17 @@ opens it in-window, every session screen shows a clickable at-a-glance
 widget in the right sidebar, and the home screen has a footer indicator —
 same data, themed. See docs/OPERATIONS.md → "Dashboard".
 
+## Sandboxed agents
+
+Agents running inside a sandbox (bubblewrap/omac, Docker, macOS seatbelt,
+WSL2) share the host's budget instead of getting their own: bridge the
+daemon's Unix socket into the sandbox, set `LOAD_LOCK_NO_SPAWN=1` so the
+client never spawns a useless sandbox-local daemon, and optionally tag
+holds with `LOAD_LOCK_LABEL_PREFIX` (e.g. `bwrap:issue-42 build`).
+Ready-to-run per-sandbox recipes — live-verified for bubblewrap,
+contract-inspected for the rest, plus the cross-PID-namespace lease
+lifecycle — live in docs/OPERATIONS.md → "Sandboxes".
+
 ## Layout
 
 ```
@@ -103,7 +114,7 @@ skills/         packaged skill
 - [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md) — per-harness capability
   matrix with implemented / contract-tested / proposed labels.
 - [docs/OPERATIONS.md](docs/OPERATIONS.md) — install, config,
-  troubleshooting, recovery, daemon lifecycle.
+  troubleshooting, recovery, daemon lifecycle, sandbox bridging.
 - [docs/AGENT_GUIDE.md](docs/AGENT_GUIDE.md) — the playbook for agents.
 - [docs/ADAPTERS.md](docs/ADAPTERS.md) — how to write an adapter for a new
   harness, using the published library surface.

package/dist/adapters/opencode/tui.d.ts

@@ -15,8 +15,9 @@
  *  - a clickable sidebar.footer widget with the same summary (session
  *    screens) — onMouseDown opens the dashboard; the two slots render on
  *    disjoint surfaces, so this is not a double-render
- *  - /load-lock (palette + slash command, also bound to "gl") opens the
- *    panel IN-WINDOW via presentation: "panel" instead of fullscreen
+ *  - /load-lock (palette + slash command) opens the panel IN-WINDOW via
+ *    presentation: "panel" instead of fullscreen (deliberately NOT bound to
+ *    any key — see the "no global key binding" comment in the keymap layer)
  *  - 'r' resync, 'x' force-release, and 'Esc' close while the panel is open;
  *    force-release is an admin action gated behind an explicit select +
  *    confirm dialog

package/dist/adapters/opencode/tui.js

@@ -16,8 +16,9 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "@opentui/soli
  *  - a clickable sidebar.footer widget with the same summary (session
  *    screens) — onMouseDown opens the dashboard; the two slots render on
  *    disjoint surfaces, so this is not a double-render
- *  - /load-lock (palette + slash command, also bound to "gl") opens the
- *    panel IN-WINDOW via presentation: "panel" instead of fullscreen
+ *  - /load-lock (palette + slash command) opens the panel IN-WINDOW via
+ *    presentation: "panel" instead of fullscreen (deliberately NOT bound to
+ *    any key — see the "no global key binding" comment in the keymap layer)
  *  - 'r' resync, 'x' force-release, and 'Esc' close while the panel is open;
  *    force-release is an admin action gated behind an explicit select +
  *    confirm dialog
@@ -181,8 +182,8 @@ function MiniIndicator(v, ctx) {
  * Right-sidebar widget: the same glance summary plus a "click to open"
  * affordance. Click support is contract-level (opentui enables mouse and
  * bubbles mouse-down events to slot renderables); terminals that don't
- * deliver mouse events can still open the dashboard with the keymap
- * binding shown on the hint line.
+ * deliver mouse events can still open the dashboard via the /load-lock
+ * slash command (or the command palette) named on the hint line.
  */
 function SidebarWidget(v, ctx) {
     const f = themeFg(ctx.theme);
@@ -196,7 +197,7 @@ function SidebarWidget(v, ctx) {
         return (_jsx("box", { onMouseDown: openDashboard, children: _jsx("text", { fg: f.dim, children: "load-lock: no pools configured" }) }));
     }
     const shortcut = ctx.keymap.shortcuts("load-lock.dashboard.open")[0];
-    const hint = shortcut ? `${shortcut} / click opens dashboard` : "click opens dashboard";
+    const hint = shortcut ? `${shortcut} / click opens dashboard` : "/load-lock or click opens dashboard";
     return (_jsxs("box", { onMouseDown: openDashboard, children: [_jsx("text", { fg: healthColor(g.health, f), children: `load-lock ${g.bits.join("·")}` }), _jsx("text", { fg: f.dim, children: hint })] }));
 }
 // ---------------------------------------------------------------- plugin
@@ -268,9 +269,21 @@ export default Plugin.define({
                     id: "load-lock.dashboard.open",
                     title: "load-lock: open the lock-status dashboard",
                     group: "load-lock",
-                    // Always-works fallback for the sidebar widget's click affordance
-                    // (some terminals don't deliver mouse events to the TUI).
-                    bind: "gl",
+                    // NO global key binding, on purpose (issue #28):
+                    //
+                    // 1. Never bind unmodified single letters or letter sequences
+                    //    (the old "gl") at global scope: while the keymap engine waits
+                    //    for the next key of a sequence it swallows the prefix, so
+                    //    plain "g" never reached the composer. Modifier chords don't
+                    //    have this problem.
+                    // 2. The obvious chord, ctrl+g, is already the host's documented
+                    //    default binding for session.first ("Navigate to first
+                    //    message", bound to ctrl+g,home,alt+home in opencode >=
+                    //    2.0.32); our layer is mode "global" + priority 5 and would
+                    //    shadow it. Rather than shadow the host or pick another
+                    //    unmodified key, the command ships unbound: the sidebar
+                    //    widget (click), the command palette, and the /load-lock
+                    //    slash command remain as entry points.
                     palette: true,
                     slash: { name: "load-lock", aliases: ["lock", "ll"] },
                     run: () => {
@@ -291,6 +304,10 @@ export default Plugin.define({
                     id: "load-lock.dashboard.resync",
                     title: "load-lock: resync the dashboard",
                     group: "load-lock",
+                    // Unmodified letters are fine here (unlike the global-scope rule
+                    // above): `enabled` gates these to moments when OUR panel is the
+                    // fullscreen current one and the composer is suspended, so there is
+                    // no typing to swallow.
                     bind: "r",
                     enabled: panelOpen,
                     run: () => {

package/dist/cli/main.js

@@ -65,7 +65,7 @@ const HELP_GROUPS = [
     {
         title: "permit operations",
         items: [
-            { names: ["acquire"], desc: "request a permit: --pool --op-key --reason [--wait-ms] [--no-queue]" },
+            { names: ["acquire"], desc: "request a permit: --pool --op-key --reason [--label] [--label-prefix] [--wait-ms] [--no-queue]" },
             { names: ["claim"], desc: "claim an offered permit before its window expires: --offer <token>" },
             { names: ["release"], desc: "release a held permit: --permit <token> [--outcome success|failure]" },
             { names: ["cancel"], desc: "cancel a queued/offered/paused request: --id <request-id> [--admin]" },
@@ -253,6 +253,7 @@ async function main() {
                 pool: S("pool", "heavy"),
                 agentId: S("agent", defaultAgent()),
                 agentLabel: S("label") || undefined,
+                labelPrefix: S("label-prefix") || undefined,
                 cwd: S("cwd", process.cwd()),
                 opKey: S("op-key") || fail("acquire: --op-key is required"),
                 reason: S("reason") || fail("acquire: --reason is required"),
@@ -461,6 +462,7 @@ async function runWithPermit(jobArgv) {
                 pool: S("pool", "heavy"),
                 agentId: S("agent", defaultAgent()),
                 agentLabel: S("label") || "load-lock run",
+                labelPrefix: S("label-prefix") || undefined,
                 cwd: process.cwd(),
                 opKey: S("op-key") || `run/${command}/${Date.now()}`,
                 reason: S("reason") || command,

package/dist/core/state.js

@@ -239,6 +239,15 @@ export class Machine {
         const weight = p.weight ?? 1;
         if (!Number.isInteger(weight) || weight < 1)
             throw new ProtocolError("invalid", "weight must be a positive integer");
+        // Holder-label prefix (sandbox tagging): composed here so every adapter
+        // gets identical behavior; falls back to agentId when no label is given.
+        let agentLabel = p.agentLabel;
+        if (p.labelPrefix !== undefined) {
+            const prefix = p.labelPrefix.trim();
+            if (!prefix)
+                throw new ProtocolError("invalid", "labelPrefix must be a non-empty string");
+            agentLabel = `${prefix}:${p.agentLabel ?? p.agentId}`;
+        }
         // Idempotency: a live request for the same (agent, op) returns its state
         // (including its offer/permit token for the owner).
         const existing = this.liveEntryByOpKey(p.agentId, p.opKey);
@@ -259,7 +268,7 @@ export class Machine {
                 id: rid(),
                 pool,
                 agentId: p.agentId,
-                agentLabel: p.agentLabel,
+                agentLabel,
                 cwd: p.cwd,
                 opKey: p.opKey,
                 reason: p.reason,
@@ -281,7 +290,7 @@ export class Machine {
             id: rid(),
             pool,
             agentId: p.agentId,
-            agentLabel: p.agentLabel,
+            agentLabel,
             cwd: p.cwd,
             opKey: p.opKey,
             reason: p.reason,

package/dist/mcp/server.js

@@ -42,6 +42,7 @@ export function buildServer(opts) {
             reason: z.string().describe("Why you need the machine (shown to other agents, e.g. 'cargo test --all in worktree feat-x')"),
             op_key: z.string().describe("Stable key for the pending operation (idempotency; e.g. 'wt-feat-x/cargo-test')"),
             agent_id: z.string().optional().describe("Override agent identity (rarely needed)"),
+            label_prefix: z.string().optional().describe("Prefix prepended to your holder label so sandboxed clients are identifiable, e.g. 'omac' -> 'omac:<label>' (or set env LOAD_LOCK_LABEL_PREFIX)"),
             wait_ms: z.number().int().optional().describe("Bounded blocking wait for capacity, clamped by config (default 0)"),
             subscribe_if_busy: z.boolean().optional().describe("false = fail fast instead of queueing (default true)"),
             pool: z.string().optional().describe("Resource pool (default 'heavy')"),
@@ -50,6 +51,7 @@ export function buildServer(opts) {
         const res = await client.request("acquire", {
             pool: input.pool,
             agentId: agentIdOf(input),
+            labelPrefix: input.label_prefix,
             cwd: process.cwd(),
             opKey: input.op_key,
             reason: input.reason,

package/dist/shared/client.d.ts

@@ -34,6 +34,19 @@ export declare class LLClient {
     onDisconnect(cb: () => void): () => void;
     close(): void;
 }
+/**
+ * Client-only mode: LOAD_LOCK_NO_SPAWN set to any non-empty value except
+ * "0" forbids auto-spawning a daemon. Set this inside OS-level sandboxes
+ * (bubblewrap/omac, Docker, ...) so a sandbox-local daemon is never
+ * silently spawned and an unreachable host socket fails loudly instead.
+ */
+export declare function noSpawnRequested(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Env-supplied holder-label prefix (LOAD_LOCK_LABEL_PREFIX), applied to
+ * every acquire so sandboxed clients are identifiable in the dashboard
+ * (e.g. "omac:issue-42 build"). An explicit labelPrefix param wins.
+ */
+export declare function envLabelPrefix(env?: NodeJS.ProcessEnv): string | undefined;
 /** Idempotently ensure a daemon is running and listening on `sockPath`. */
 export declare function ensureDaemon(stateDir: string, sockPath: string): Promise<void>;
 /** One-shot helper: connect (auto-spawning), run fn, close. */

package/dist/shared/client.js

@@ -12,6 +12,13 @@
  * NTFS) and starts a detached daemon; losers wait for the endpoint to
  * appear. The freshly spawned daemon itself re-checks the endpoint before
  * binding, so a double-spawn is harmless (the loser exits).
+ *
+ * Client-only mode (LOAD_LOCK_NO_SPAWN): sandboxed clients must be thin
+ * clients of the HOST daemon. A sandbox-local daemon is useless (it cannot
+ * see host processes or host-wide load) and hides the failure — so when the
+ * env var is set (any non-empty value except "0"), no daemon is ever
+ * auto-spawned here or in ensureDaemon(); an unreachable endpoint fails
+ * loudly with a pointer to the Sandboxes section of docs/OPERATIONS.md.
  */
 import { connect } from "node:net";
 import { existsSync, mkdirSync, rmSync, writeFileSync, readFileSync } from "node:fs";
@@ -48,6 +55,9 @@ export class LLClient {
         catch {
             /* fall through to spawn */
         }
+        if (noSpawnRequested()) {
+            throw new ProtocolError("unavailable", noSpawnError(this.socketPath()));
+        }
         if (!this.opts.spawnDaemon) {
             throw new ProtocolError("unavailable", `load-lock daemon is not running on ${this.socketPath()}`);
         }
@@ -134,6 +144,13 @@ export class LLClient {
     }
     /** Issue one RPC. Reconnects once if the connection was lost. */
     async request(method, params = {}, timeoutMs = 20_000) {
+        if (method === "acquire" && params.labelPrefix === undefined) {
+            // Sandbox wrapper tagging (LOAD_LOCK_LABEL_PREFIX): applied by the
+            // shared client so every adapter (CLI, MCP, plugin, hooks) gets it.
+            const prefix = envLabelPrefix();
+            if (prefix)
+                params = { ...params, labelPrefix: prefix };
+        }
         if (!this.sock || this.sock.destroyed)
             await this.connect();
         const id = this.nextId++;
@@ -179,6 +196,33 @@ export class LLClient {
     }
 }
 // ------------------------------------------------------------------- spawning
+/**
+ * Client-only mode: LOAD_LOCK_NO_SPAWN set to any non-empty value except
+ * "0" forbids auto-spawning a daemon. Set this inside OS-level sandboxes
+ * (bubblewrap/omac, Docker, ...) so a sandbox-local daemon is never
+ * silently spawned and an unreachable host socket fails loudly instead.
+ */
+export function noSpawnRequested(env = process.env) {
+    const v = env.LOAD_LOCK_NO_SPAWN;
+    return v !== undefined && v !== "" && v !== "0";
+}
+/**
+ * Env-supplied holder-label prefix (LOAD_LOCK_LABEL_PREFIX), applied to
+ * every acquire so sandboxed clients are identifiable in the dashboard
+ * (e.g. "omac:issue-42 build"). An explicit labelPrefix param wins.
+ */
+export function envLabelPrefix(env = process.env) {
+    const v = env.LOAD_LOCK_LABEL_PREFIX?.trim();
+    return v || undefined;
+}
+function noSpawnError(sockPath) {
+    return (`load-lock daemon is not reachable at ${sockPath} and auto-spawn is disabled (LOAD_LOCK_NO_SPAWN is set): ` +
+        `this client is client-only and started no daemon. Run the daemon on the host machine ` +
+        `(e.g. load-lock service start) and bridge its socket into this sandbox, ` +
+        `then point LOAD_LOCK_SOCKET at the bridged path — see the "Sandboxes" section of ` +
+        `docs/OPERATIONS.md for per-sandbox recipes (bubblewrap/omac, Docker, seatbelt, WSL2). ` +
+        `To allow spawning a daemon here instead, unset LOAD_LOCK_NO_SPAWN.`);
+}
 function daemonMainPath() {
     if (process.env.LOAD_LOCK_DAEMON_BIN)
         return process.env.LOAD_LOCK_DAEMON_BIN;
@@ -187,6 +231,10 @@ function daemonMainPath() {
 }
 /** Idempotently ensure a daemon is running and listening on `sockPath`. */
 export async function ensureDaemon(stateDir, sockPath) {
+    if (noSpawnRequested()) {
+        // Client-only mode: never spawn, even for direct callers.
+        throw new ProtocolError("unavailable", noSpawnError(sockPath));
+    }
     if (await probe(sockPath))
         return;
     const lockDir = join(stateDir, "spawn.lock");

package/dist/shared/protocol.d.ts

@@ -226,6 +226,14 @@ export interface AcquireParams {
     pool?: string;
     agentId: string;
     agentLabel?: string;
+    /**
+     * Optional prefix prepended to the holder label (composed daemon-side) so
+     * sandboxed/thin clients are identifiable in the dashboard, e.g.
+     * labelPrefix "omac" + agentLabel "issue-42 build" -> "omac:issue-42
+     * build". Falls back to agentId when no agentLabel is given. Adapters may
+     * source it from LOAD_LOCK_LABEL_PREFIX (the shared client injects it).
+     */
+    labelPrefix?: string;
     cwd?: string;
     opKey: string;
     reason: string;

package/dist/test/cli.test.js

@@ -94,6 +94,13 @@ test("top stays a working compat alias for dashboard", async () => {
     assert.equal(alias.code, 0);
     assert.equal(primary.code, 0);
     // "synced N ago" and daemon uptime tick between runs; normalize before comparing.
-    const norm = (s) => s.replace(/synced \S+ ago/g, "synced N ago").replace(/uptime \S+/g, "uptime N");
+    // The MACHINE block is live host telemetry — load averages, available memory
+    // and the used-percentage in the pressure note move (and round across
+    // boundaries) between the two back-to-back runs — so collapse it wholesale;
+    // the alias check is that everything *else* renders identically.
+    const norm = (s) => s
+        .replace(/synced \S+ ago/g, "synced N ago")
+        .replace(/uptime \S+/g, "uptime N")
+        .replace(/^MACHINE.*\n\s*pressure:.*\n/m, "MACHINE <live telemetry>\n");
     assert.equal(norm(alias.stdout), norm(primary.stdout), "identical rendering");
 });

package/dist/test/core.test.js

@@ -279,3 +279,30 @@ test("diagnose reports holder info and flags long holds without revoking", () =>
     assert.equal(stateOf(m, a.requestId), "held", "long hold alone never revokes a running job");
     assert.ok(diags[0].diagnostics.note.includes("pid 333"));
 });
+// ------------------------------------------------------- labelPrefix (issue #29)
+test("labelPrefix composes the holder label; agentId fallback when unlabeled", () => {
+    const { m } = mk();
+    const a = grant(m, A, "op1", { agentLabel: "issue-42 build", labelPrefix: "omac" });
+    assert.equal(a.agentLabel, "omac:issue-42 build");
+    // queued entry composes too, falling back to agentId without a label
+    const b = m.acquire({ agentId: B, opKey: "op1", reason: "b", labelPrefix: "omac" });
+    assert.equal(b.state, "queued");
+    assert.equal(b.entry.agentLabel, "omac:" + B);
+    // status (dashboard data source) shows the composed labels
+    const st = m.status();
+    assert.equal(st.pools[0].holders[0].agentLabel, "omac:issue-42 build");
+    assert.equal(st.pools[0].queue[0].agentLabel, "omac:" + B);
+    // events and journal carry the composed label (restart reconciliation)
+    assert.equal(m.eventsSince(0)[1].entry.agentLabel, "omac:issue-42 build");
+    assert.equal(m.journalEntries()[0].agentLabel, "omac:issue-42 build");
+    // no prefix: unchanged behavior
+    const c = m.acquire({ agentId: C, opKey: "op1", reason: "c", agentLabel: "plain" });
+    assert.equal(c.entry.agentLabel, "plain");
+});
+test("labelPrefix is trimmed and must be non-empty when present", () => {
+    const { m } = mk();
+    const a = grant(m, A, "op1", { agentLabel: "build", labelPrefix: " omac " });
+    assert.equal(a.agentLabel, "omac:build");
+    assert.throws(() => m.acquire({ agentId: A, opKey: "op2", reason: "r", labelPrefix: "  " }), (e) => e instanceof ProtocolError && e.code === "invalid");
+    assert.throws(() => m.acquire({ agentId: A, opKey: "op3", reason: "r", labelPrefix: "" }), (e) => e instanceof ProtocolError && e.code === "invalid");
+});

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

@@ -62,8 +62,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).
 
@@ -251,7 +251,7 @@ 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`) |

package/docs/OPERATIONS.md

@@ -89,7 +89,12 @@ uninstall — see issue #19); not live-verified inside the real CLIs.
   override `LOAD_LOCK_STATE_DIR`).
 - Socket: `<state dir>/daemon.sock` (Windows: named pipe `\\.\pipe\load-lock`;
   override `LOAD_LOCK_SOCKET`).
-- **Auto-spawns** on first client connection; no service unit needed.
+- **Auto-spawns** on first client connection; no service unit needed. Set
+  `LOAD_LOCK_NO_SPAWN` to any non-empty value except `0` to forbid
+  spawning (client-only mode for sandboxes — see
+  [Sandboxes](#sandboxes)).
+- Also honored by the shared client: `LOAD_LOCK_LABEL_PREFIX` (prefix for
+  holder labels; see Sandboxes).
 - Files: `config.json` (settings + history), `journal.json` (held permits),
   `daemon.json` (pid), `spawn.lock` (bootstrap race guard).
 
@@ -169,16 +174,16 @@ alternate screen, so it works anywhere the CLI works.
 The OpenCode installer also ships the package's `./tui` plugin export (a
 companion to the main plugin, which is unchanged). Inside the opencode TUI:
 
-- `/load-lock` (or the command palette, or the `gl` keybinding) opens the
+- `/load-lock` (or the command palette) opens the
   **load-lock.dashboard** session panel **in-window** as a side panel —
   same data as `load-lock dashboard`, themed, live-updating, with the rest
   of the TUI layout still visible beside it.
 - Every session screen shows an at-a-glance widget at the bottom of the
   right sidebar: `load-lock 0/3` colored by pool health (green ok, yellow
   full/queued, red daemon down) plus a hint line. Clicking it opens the
-  dashboard; `gl` is the fallback for terminals that don't deliver mouse
-  events. The home screen keeps its `lock 1/1·Q2` footer indicator — the
-  sidebar widget only renders on session screens, so the two never
+  dashboard; `/load-lock` is the fallback for terminals that don't deliver
+  mouse events. The home screen keeps its `lock 1/1·Q2` footer indicator —
+  the sidebar widget only renders on session screens, so the two never
   double-render.
 - `r` resyncs; `x` opens force-release, which requires an explicit
   select + confirm — the panel itself is read-only.
@@ -187,15 +192,31 @@ companion to the main plugin, which is unchanged). Inside the opencode TUI:
   palette — is open, so Esc keeps cancelling the dialog instead of
   closing the panel underneath it.
 
+The open command deliberately ships with **no global key binding** (issue
+#28). Never bind unmodified single letters or letter sequences (the old
+`gl`) at global scope: while the keymap engine waits for the next key of a
+sequence it swallows the prefix, so plain `g` never reached the composer.
+The obvious modifier chord, `ctrl+g`, is already the host's documented
+default for `session.first` ("Navigate to first message") in opencode
+>= 2.0.32, so binding it would shadow a host feature; per the issue's
+fallback the command is unbound instead — the sidebar click, the command
+palette, and `/load-lock` are the entry points. (The panel-scoped `r` and
+`x` bindings are fine: they are `enabled` only while the dashboard panel
+itself is fullscreen, when the composer is suspended and no typing can be
+swallowed.)
+
 Verified live against opencode 2.0.32 (real pty session): the sidebar
 widget renders with live daemon data, a mouse press on the widget opens
-the dashboard in-window with the chat still visible beside it, `gl` opens
-it as well, and the `/load-lock` command appears in the slash suggestions.
+the dashboard in-window with the chat still visible beside it, plain `g`
+types into the composer with no keymap interception, `ctrl+g` is not
+intercepted by load-lock (the host's documented `session.first` default
+is left untouched), and the `/load-lock` command appears in the slash
+suggestions and opens the panel.
 Earlier live verification (2.0.29): panel render, palette/slash entry
 points, and the confirm-gated force-release flow. Click handling itself
 is contract-level from opentui (mouse reporting enabled by default,
 mouse-down events bubble to slot renderables) — the pty test above
-exercises the full path; the `gl` binding works regardless.
+exercises the full path; the `/load-lock` command works regardless.
 Plugins configured in `opencode.json` that expose `./tui` are loaded
 automatically by the CLI, so the published package needs no extra config.
 For local development against a checkout, opencode also auto-discovers
@@ -317,6 +338,10 @@ Limitations observed (all inherent to containers, not load-lock bugs):
   respawns with defaults (fine for ephemeral CI containers; volume-mount
   `~/.local/state/load-lock` if you want persistence).
 
+The setup above gives the container its *own* daemon. To make a container
+a thin client of the **host's** daemon instead (bridged socket +
+`LOAD_LOCK_NO_SPAWN`), see the [Sandboxes](#sandboxes) section below.
+
 Reproduce from a checkout (needs `dist/` built; tarball from `npm pack`):
 
 ```sh
@@ -381,6 +406,356 @@ Caveats to watch for (unverified expectations):
 - Keep the state dir on the Linux filesystem (`~/.local/state/load-lock`),
   not on `/mnt/c` (drvfs/9p is slow and lock semantics differ).
 
+## Sandboxes
+
+Sandboxed agents (bubblewrap/omac, Docker, macOS seatbelt, WSL2) face one
+core problem: the budget belongs on the *host*, but a sandbox that cannot
+see the host's daemon will happily auto-spawn its own useless local daemon
+and fragment the budget. The recipes below all use the same two mechanisms:
+
+1. **Bridge the host daemon's socket into the sandbox.** The daemon listens
+   on an AF_UNIX *path* socket. Path sockets are scoped by the **mount**
+   namespace, not the network namespace — so a bind mount of the state dir
+   survives `--unshare-net` (bubblewrap), and only needs the right
+   filesystem mapping/allow rules elsewhere. Point the sandboxed client at
+   the bridged path with `LOAD_LOCK_SOCKET`.
+2. **Run the client in client-only mode** so it can never auto-spawn a
+   daemon inside the sandbox (see below).
+
+A third mechanism matters once the client is inside a PID namespace:
+**lease-mode (untracked) permits**, because the host daemon cannot
+`kill(pid, 0)` a sandbox pid it cannot see (lifecycle below).
+
+### Client-only mode: `LOAD_LOCK_NO_SPAWN`
+
+Set `LOAD_LOCK_NO_SPAWN=1` (any non-empty value except `0`) and the shared
+client will never spawn a daemon, no matter which adapter asks:
+`ensureDaemon` refuses before creating anything, and `connect` fails loudly
+instead of falling back to a spawn. The error is actionable and points
+here:
+
+```
+load-lock: load-lock daemon is not reachable at /run/load-lock/daemon.sock
+and auto-spawn is disabled (LOAD_LOCK_NO_SPAWN is set): this client is
+client-only and started no daemon. Run the daemon on the host machine
+(e.g. load-lock service start) and bridge its socket into this sandbox,
+then point LOAD_LOCK_SOCKET at the bridged path — see the "Sandboxes"
+section of docs/OPERATIONS.md for per-sandbox recipes (bubblewrap/omac,
+Docker, seatbelt, WSL2). To allow spawning a daemon here instead, unset
+LOAD_LOCK_NO_SPAWN. (code: unavailable)
+```
+
+The CLI exits with code 70 for this failure (unavailable transport). Use
+this mode inside every sandbox: it turns "mysteriously isolated budget"
+into a loud, documented failure, and it is what the tests in
+`src/test/sandbox.test.ts` enforce (no state dir is ever created, and the
+error names the docs).
+
+### Label prefixes: identifying sandboxed holders
+
+Sandboxed clients can prefix their holder labels so the dashboard shows
+*where* a permit came from, e.g. `omac:issue-42 build`. Three equivalent
+entry points, all composing `prefix:label` (or `prefix:<agentId>` when no
+label was given) daemon-side:
+
+- `LOAD_LOCK_LABEL_PREFIX` env var — the shared client injects it into
+  every `acquire` request (including CLI, MCP, plugin and hook paths)
+  unless a request already carries an explicit prefix. This is the natural
+  place for a sandbox wrapper (omac profile, Docker `-e`, bwrap
+  `--setenv`) to tag everything an agent does inside it.
+- CLI: `--label-prefix` on `acquire` and `run`.
+- MCP: the `label_prefix` input on the `acquire` tool; the RPC field is
+  `labelPrefix` (see `docs/ADAPTERS.md`).
+
+A present-but-empty prefix is rejected (`labelPrefix must be a non-empty
+string`); prefixes are trimmed.
+
+### Cross-PID-namespace permits: the lease-mode lifecycle
+
+With `--unshare-pid` (bubblewrap) or default Docker containers, the host
+daemon cannot see the sandboxed client's pid — verified live below: inside
+the sandbox `kill -0 <host-daemon-pid>` fails with "No such process" while
+the daemon is plainly running. That makes **tracked** permits
+(`start_job` / `attach_pid`, liveness via `kill(pid, 0)` +
+`/proc/<pid>/stat`) meaningless across PID namespaces. Worse, calling
+`attach_pid` from *inside* the sandbox passes a pid that is invisible or
+reused on the host; the daemon's liveness check fails immediately and the
+permit is auto-released. Only use tracked mode when the host sees the same
+pid you do (host-run jobs, or containers started with `--pid=host`).
+
+**Lease mode** is the cross-namespace lifecycle:
+
+1. `acquire` → permit granted (holder label visible in the dashboard).
+2. `mark_started` → permit moves to `running_untracked` with a lease
+   deadline of `now + untrackedLeaseMs` (default 15 minutes,
+   configurable — see Configuration). No host-side pid is recorded.
+3. **Heartbeats renew the lease.** Heartbeat sources: an MCP server
+   process heartbeats every 30s for its own agent (`agent_id` /
+   `defaultAgentId`); the OpenCode plugin heartbeats every 30s per known
+   session. The CLI has **no** automatic heartbeat — for a CLI-held
+   untracked permit the lease is a hard ceiling, so finish within
+   `untrackedLeaseMs` or release promptly.
+4. `release` → capacity freed immediately, whatever remains on the lease.
+5. **Lease expiry:** if no heartbeat arrives before the deadline, the
+   daemon reclaims the permit and admits queued waiters, journaling
+   `untracked lease expired: no heartbeat from the owning agent`. After a
+   daemon restart, `restore` grants surviving untracked permits a *fresh*
+   lease window from restore time.
+
+The same trap catches `load-lock run` / `run_with_permit`: those helpers
+use *tracked* mode (`start_job` with the spawned job's pid). Run from
+inside a PID-namespace sandbox, the pid is invisible to the host daemon,
+whose liveness sweep then auto-releases the permit while the job is still
+running. Inside sandboxes the recipe is therefore always:
+`acquire` → `mark_started` (+ heartbeats where the harness provides them)
+→ explicit `release` — never `run`, `attach-pid`, or `start-job` from the
+sandboxed side. Save `run` for host-side invocations where the daemon sees
+the job's pid.
+
+Tradeoff (deliberate, and the `recover list` output says so): an untracked
+permit whose owner is alive but silent is reclaimed after the lease, so
+overlap with an unobserved survivor is possible — e.g. two builds may run
+concurrently for up to `untrackedLeaseMs` after a sandbox stopped
+heartbeating. That is the price of not being able to see pids across
+namespaces; keep heartbeating (or release promptly) and size
+`untrackedLeaseMs` accordingly.
+
+### bubblewrap — live-verified
+
+Verified 2026-10-20 with bubblewrap 0.6.1 on Linux 6.8.0-138-generic,
+Node v22.23.2, load-lock 1.1.0 working tree (issue-29 branch). The daemon
+ran on the *host* in an isolated state dir; every client call below ran
+inside `bwrap --unshare-net --unshare-pid` and reached the **host** daemon.
+
+1. Start the daemon on the host, in a state dir you will bind into the
+   sandbox (here a temp dir; for real use `~/.local/state/load-lock`):
+
+   ```sh
+   LOAD_LOCK_STATE_DIR=/tmp/ll-bwrap-29 node dist/cli/main.js service start
+   # load-lock: daemon running on pid 2259769 (default socket)
+   ```
+
+   The socket appears at `/tmp/ll-bwrap-29/daemon.sock` with mode
+   `srwxrwxr-x` (775): connecting needs *write* on the socket inode, so a
+   sandbox running as the same user (or group) can talk to it.
+
+2. Run the CLI inside the sandbox, binding the state dir and pointing
+   `LOAD_LOCK_SOCKET` at it. Bind the **state dir**, not the socket file —
+   the socket inode is replaced when the daemon restarts, so a file-only
+   bind goes stale, while the dir bind follows the new socket
+   automatically. Binding to an existing path keeps this simple (see
+   caveats):
+
+   ```sh
+   bwrap --dev-bind / / --unshare-net --unshare-pid --proc /proc \
+     --bind /tmp/ll-bwrap-29 /tmp/ll-bwrap-29 \
+     --setenv LOAD_LOCK_SOCKET /tmp/ll-bwrap-29/daemon.sock \
+     --setenv LOAD_LOCK_NO_SPAWN 1 \
+     --setenv LOAD_LOCK_LABEL_PREFIX bwrap \
+     node dist/cli/main.js status --json
+   ```
+
+   Observed: `status --json` answered by the *host* daemon — same pid as
+   the host's `service status` (`2259769`, protocol v1, heavy pool
+   capacity 1, `untrackedLeaseMs` 900000). `--unshare-net` does not
+   interfere: the path socket is reached through the mount namespace.
+
+3. PID-namespace proof: inside the same sandbox,
+   `kill -0 2259769` → `No such process` — the host daemon pid is
+   invisible to the sandbox, confirming the client crossed namespaces via
+   the filesystem, and that lease mode (not tracked mode) is required for
+   long holds (below).
+
+4. Full permit round trip from inside the sandbox:
+
+   ```sh
+   # acquire (env LOAD_LOCK_LABEL_PREFIX=bwrap was set by bwrap):
+   node dist/cli/main.js acquire --op-key bwrap-check \
+     --reason "issue-29 live verification build" --label "issue-29 build"
+   # → permit prm_… ; entry.agentLabel = "bwrap:issue-29 build"
+
+   node dist/cli/main.js mark-started --permit prm_…
+   # → running_untracked (lease 900s)
+
+   node dist/cli/main.js release --permit prm_…
+   # → host pool "heavy": 0/1
+   ```
+
+   Host-side `status` while the permit was held:
+
+   ```
+   pool "heavy": 1/1 in use
+   held: bwrap:issue-29 build — issue-29 live verification build (5s) [untracked, leased]
+   ```
+
+   and `recover list` reported `[running_untracked] bwrap:issue-29 build`
+   with `heartbeat lease 895s remaining — reclaimed when the owning agent
+   stops heartbeating (overlap with an unobserved survivor is possible;
+   see docs)`. Five durable events on the host journal: `daemon_started`,
+   `daemon_recovered`, `granted bwrap:issue-29 build`, `started`,
+   `released`.
+
+Caveats observed (verified):
+
+- `bwrap` creates missing bind destinations by mkdir-ing them, so
+  `--bind <state-dir> /run/load-lock` failed here with
+  `bwrap: Can't mkdir /run/load-lock: Permission denied` (`/run` is
+  root-owned). Either bind at an existing path (as above), pre-create the
+  destination, or pick a parent you can write to.
+- Client-only mode matters: with `LOAD_LOCK_NO_SPAWN=1` unset, a sandbox
+  whose bind/env was misconfigured would silently spawn its own daemon
+  inside the sandbox and split the budget. The tests in
+  `src/test/sandbox.test.ts` pin the loud failure instead.
+
+### omac — contract-inspected
+
+**omac is not installed on the verification machine**, so nothing in this
+subsection was executed here; it is assembled from omac's documented
+behavior (the facts below are from omac's docs, not invented) and the
+bubblewrap recipe above, which omac wraps on Linux. Treat it as a
+ready-to-run procedure with expected outcomes, and record what you find.
+
+omac sandboxes agents with bubblewrap on Linux (seatbelt on macOS, WSL2
+elsewhere) and **strips the harness environment** before starting the
+agent, allowing through only variables listed in the sandbox profile's
+`environment.allow_vars` — `~/.config/omac/sandbox-profiles/default.json`
+by default. That file is the whole recipe:
+
+1. Make sure the load-lock state dir is visible inside omac's bubblewrap
+   sandbox (the `LOAD_LOCK_SOCKET` path must resolve inside it). How
+   omac's sandbox mounts map to bwrap `--bind`s is an omac sandbox-config
+   question — omac's own facade socket under `~/.local/state/omac/run/`
+   is the project's precedent for a sandbox process connecting to a
+   host-owned socket through its profile.
+2. Add the load-lock variables to the profile's `environment.allow_vars`:
+
+   ```json
+   {
+     "environment": {
+       "allow_vars": [
+         "LOAD_LOCK_SOCKET",
+         "LOAD_LOCK_STATE_DIR",
+         "LOAD_LOCK_NO_SPAWN",
+         "LOAD_LOCK_LABEL_PREFIX"
+       ]
+     }
+   }
+   ```
+
+   Set the values themselves in your harness env (or the profile's env
+   mechanism): `LOAD_LOCK_SOCKET` to the host daemon socket as seen inside
+   the sandbox, `LOAD_LOCK_NO_SPAWN=1`, and — recommended —
+   `LOAD_LOCK_LABEL_PREFIX=omac` so the dashboard shows holders as
+   `omac:<label>`.
+3. Watch out: **omac never rewrites a profile it has created**, so if your
+   `default.json` already exists, edit it by hand (adding the entries
+   above); and **unknown profile fields are errors**, so don't invent
+   other keys — `allow_vars` entries are plain variable names.
+
+Expected outcome (unverified here): with those four variables allowed and
+the state dir mounted, an agent inside omac behaves exactly like the
+verified bubblewrap case above — host daemon answers, labels carry the
+`omac:` prefix, and long holds need `mark_started` + heartbeats (lease
+mode) because of the PID namespace.
+
+### Docker — contract-inspected
+
+Docker *was* verified for in-container daemons (see the verified Docker
+subsection above). What was **not** verified here is the thin-client shape
+below: the verification machine has a `docker` binary but the verifying
+user cannot reach `/var/run/docker.sock`, so this recipe is
+contract-inspected — ready to run, expected outcomes marked, not executed
+by us.
+
+1. Run the daemon on the host (normal install, default state dir).
+2. Run the container as a thin client of the *host* daemon:
+
+   ```sh
+   docker run --rm -it \
+     -v ~/.local/state/load-lock:/run/load-lock \
+     -e LOAD_LOCK_SOCKET=/run/load-lock/daemon.sock \
+     -e LOAD_LOCK_NO_SPAWN=1 \
+     -e LOAD_LOCK_LABEL_PREFIX=docker \
+     node:24 bash
+   # inside: npm install -g <load-lock tarball> && load-lock status
+   ```
+
+   Expected: `load-lock status` reports the *host* daemon's pid and pool
+   counts, and holders created inside the container appear on the host
+   dashboard as `docker:<label>`.
+
+Notes and caveats (unverified expectations):
+
+- Bind the **state dir**, not the socket file (the socket inode is
+  replaced on daemon restart; the dir bind follows it — same reasoning as
+  bubblewrap above).
+- Connecting to the socket needs *write* on the socket inode (mode `775`,
+  user/group). Container root gets this via `CAP_DAC_OVERRIDE` when no user
+  namespace remapping is in play; for non-root containers run with
+  `--user "$(id -u):$(id -g)"` and rely on the group permission, or relax
+  the socket mode/group to match your setup.
+- Container pids are not host pids, so — exactly as in the bubblewrap
+  case — use `mark_started` + heartbeat lease mode for long holds, never
+  `attach_pid`/`start_job` from inside, unless the container runs with
+  `--pid=host`.
+- The verified caveats from the Docker subsection above still apply from
+  the client's point of view (`/proc/loadavg` and `nproc` reflect the
+  host; the container's own cgroup quota is what `inspect` reports).
+
+### macOS seatbelt — contract-inspected
+
+**No macOS machine was available** for this verification, so this is
+contract-inspected against the `sandbox-exec(5)`/seatbelt documentation,
+not executed here.
+
+On macOS the daemon listens on a Unix domain socket at
+`~/.local/state/load-lock/daemon.sock`, and connecting to a UDS is
+mediated by seatbelt as a *file* operation, not a network one — so a
+profile needs read and write access to the socket path, e.g.:
+
+```lisp
+(allow file-read-data
+  (literal "/Users/you/.local/state/load-lock/daemon.sock"))
+(allow file-write*
+  (literal "/Users/you/.local/state/load-lock/daemon.sock"))
+```
+
+(no `network-outbound` rules required for the path-socket transport;
+`allow network*` forms are not the mechanism a UDS connect goes through
+under seatbelt). Since the socket inode is recreated when the daemon
+restarts, allow the containing directory too if your profile is
+path-literal strict, or re-generate the profile. Expected outcome
+(unverified): with those file rules plus the env vars
+(`LOAD_LOCK_SOCKET`, `LOAD_LOCK_NO_SPAWN=1`,
+`LOAD_LOCK_LABEL_PREFIX=…`) passed through to the agent, a seatbelt-sandboxed
+client talks to the host daemon exactly as in the verified bubblewrap
+case. omac's macOS sandboxing uses seatbelt under the hood with the same
+`environment.allow_vars` env-stripping as on Linux, so the omac recipe
+above (profile `allow_vars` + bridged socket path) applies unchanged.
+
+### WSL2 — honest state
+
+There is no verified cross-boundary story for WSL2, and we won't pretend
+otherwise:
+
+- The Windows transport is a named pipe (`\\.\pipe\load-lock`); named
+  pipes are not reachable from inside a WSL2 distro. A WSL-side Unix
+  socket is likewise not reachable from Windows-native processes.
+- There is deliberately no TCP transport (a non-goal), so there is no
+  loopback bridge to fake one.
+
+The realistic shape: **the WSL2 Linux VM is the host.** Run the daemon
+inside the distro (`~/.local/state/load-lock`, normal install — see the
+WSL2 procedure subsection above for the unverified-but-expected resource
+reporting), and treat Windows-native agents as out of scope for now.
+Cross-distro bridging (two distros sharing one daemon via a `/mnt/wsl`
+shared directory bind-mounted as the state dir) is an *unverified
+expectation*: `/mnt/wsl` is shared across distros, so the same
+bind-the-state-dir recipe should apply, but nobody has run it — verify
+and record before relying on it. Keep the state dir on the Linux
+filesystem, not `/mnt/c` (drvfs/9p is slow and lock semantics differ, as
+in the WSL2 caveats above).
+
 ## macOS / Windows notes
 
 - macOS: no cgroup limits; process-liveness checks fall back from

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aron98/load-lock",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Machine-wide counting semaphore coordinating resource-intensive work across parallel coding agents (OpenCode, Codex CLI, Claude Code, ...)",
   "type": "module",
   "license": "MIT",