@aron98/load-lock 1.1.0 → 1.2.1

package/README.md

@@ -59,7 +59,8 @@ agent A (OpenCode)        agent B (Codex)         agent C (Claude Code)
 ```sh
 npm install -g @aron98/load-lock
 load-lock install --harness opencode     # or claude-code | codex | gemini-cli |
-                                         # copilot-cli | cline | roo-code | goose | generic
+                                         # copilot-cli | cline | roo-code | goose |
+                                         # omac (sandbox grants) | generic
 load-lock doctor
 ```
 
@@ -81,6 +82,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 and omac,
+contract-inspected for the rest, plus the cross-PID-namespace lease
+lifecycle — live in docs/OPERATIONS.md → "Sandboxes".
+
 ## Layout
 
 ```
@@ -103,7 +115,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/install.js

@@ -43,11 +43,22 @@
  *                   .cursor/rules/load-lock.mdc. Contract-tested against
  *                   the documented hooks JSON; not live-verified.
  *  - generic      : prints an MCP stdio config snippet (any MCP-capable harness).
+ *  - omac         : merges load-lock grants into omac's user-global sandbox
+ *                   profile (~/.config/omac/sandbox-profiles/default.json):
+ *                   filesystem.allow_unix_dir += the state dir (host-daemon
+ *                   socket bridge), filesystem.read += the installed package
+ *                   tree when load-lock lives outside any granted workdir
+ *                   (global bun/npm installs; gotcha verified live), and
+ *                   environment.allow_vars += "LOAD_LOCK_*". omac parses
+ *                   profiles strictly (unknown fields are errors) and never
+ *                   rewrites a profile it has created, so the installer only
+ *                   writes known fields and touches nothing else.
  */
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { POLICY_BRIEF } from "../policy/text.js";
+import { resolveStateDir } from "../shared/transport.js";
 const HOME = os.homedir();
 const PKG_NAME = "@aron98/load-lock";
 export function pkgRoot(binDir) {
@@ -948,6 +959,206 @@ function uninstallCursor(opts) {
     pruneEmptyDirs(cursorDir, cursorDir);
     return actions;
 }
+// --------------------------------------------------------------------- omac
+// omac (verified against 0.11.0) sandboxes agents with bubblewrap +
+// Landlock on Linux and strips the harness environment, allowing through
+// only what the user-global sandbox profile lists. Known profile fields
+// (strict parsing — unknown fields are hard errors): top-level `workdir`,
+// `network`, `filesystem`, `environment`; `workdir.access`,
+// `network.allow_domain`/`deny_domain`/`allow_tcp_connect`,
+// `filesystem.allow`/`read`/`write`/`allow_unix_dir`/`deny`,
+// `environment.allow_vars` — all lists of strings. omac never rewrites a
+// profile it has created, so the profile file is the whole extension
+// point and we only ever write known fields.
+const OMAC_LL_ENV_ENTRY = "LOAD_LOCK_*"; // allow_vars trailing-* prefix (verified: accepted by 0.11.0)
+/** omac's user-global sandbox profile (no project equivalent exists). */
+function omacProfileFile() {
+    return path.join(configHome(), "omac", "sandbox-profiles", "default.json");
+}
+/** Read + shape-check the profile; undefined when the file does not exist. */
+function omacReadProfile(file) {
+    if (!fs.existsSync(file))
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (e) {
+        throw new Error(`${file} is not valid JSON (${e instanceof Error ? e.message : String(e)}). omac parses ` +
+            `profiles strictly; load-lock refuses to overwrite it — fix or remove the file, then re-run install`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`${file} is not a JSON object; refusing to overwrite`);
+    }
+    return parsed;
+}
+/** The profile sub-object `key`, created when absent; refuses non-objects. */
+function omacSection(profile, key) {
+    const v = profile[key];
+    if (v === undefined) {
+        const section = {};
+        profile[key] = section;
+        return section;
+    }
+    if (typeof v !== "object" || v === null || Array.isArray(v)) {
+        throw new Error(`omac profile: "${key}" is not an object; refusing to overwrite`);
+    }
+    return v;
+}
+/**
+ * Merge string entries into section[key] (created only when something is
+ * added, so we never write empty arrays). Returns the entries actually
+ * added; refuses non-string-array values instead of mangling them.
+ */
+function omacMergeList(section, key, entries) {
+    const v = section[key];
+    let list;
+    if (v === undefined)
+        list = [];
+    else if (Array.isArray(v) && v.every((x) => typeof x === "string"))
+        list = [...v];
+    else
+        throw new Error(`omac profile: "${key}" is not an array of strings; refusing to overwrite`);
+    const added = entries.filter((e) => !list.includes(e));
+    if (added.length)
+        section[key] = [...list, ...added];
+    return added;
+}
+/**
+ * The installed package tree a sandboxed CLI must be able to *read*.
+ * Live-verified gotcha: a global bun/npm install grants the bin dir, but
+ * the launcher resolves the dist tree under `.../node_modules/@aron98/
+ * load-lock` — without a read grant the CLI dies with ERR_MODULE_NOT_FOUND
+ * before ever reaching the socket. Returns the realpath of the package
+ * root, or null when load-lock lives in a repo checkout / worktree (the
+ * nearest `.git`): there the agent's omac workdir grant already covers
+ * it, and a read grant would be noise.
+ */
+function omacReadGrant(P) {
+    let root = P.root;
+    try {
+        root = fs.realpathSync(root);
+    }
+    catch {
+        /* keep the unresolved path — omac grants are not existence-filtered */
+    }
+    for (let dir = root;;) {
+        if (fs.existsSync(path.join(dir, ".git")))
+            return null; // repo checkout / git worktree
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return root;
+}
+/**
+ * Remove our entries (match-own-entries style: exact current state dir,
+ * the "LOAD_LOCK_*" prefix entry, and read entries pointing at the
+ * current package root or at a global `node_modules/@aron98/load-lock`
+ * tree — the shape the installer writes). Keys whose lists we emptied are
+ * dropped; sections that become empty are dropped; the file is removed
+ * (and dirs pruned) when nothing user-owned remains.
+ */
+function uninstallOmac() {
+    const actions = [];
+    const file = omacProfileFile();
+    const profile = omacReadProfile(file);
+    if (!profile)
+        return actions; // nothing installed; uninstall never creates anything
+    const stateDir = resolveStateDir(process.platform, process.env);
+    const readTree = omacReadGrant(pkgPaths());
+    const globalPkgSuffix = path.join("node_modules", PKG_NAME);
+    let changed = false;
+    const drop = (sectionKey, key, isOurs) => {
+        const section = profile[sectionKey];
+        if (!section || typeof section !== "object" || Array.isArray(section))
+            return;
+        const list = section[key];
+        if (!Array.isArray(list) || !list.every((x) => typeof x === "string"))
+            return;
+        const kept = list.filter((e) => !isOurs(e));
+        if (kept.length === list.length)
+            return;
+        changed = true;
+        if (kept.length)
+            section[key] = kept;
+        else
+            delete section[key];
+    };
+    drop("filesystem", "allow_unix_dir", (e) => e === stateDir);
+    drop("filesystem", "read", (e) => (readTree !== null && e === readTree) || e.endsWith(globalPkgSuffix));
+    drop("environment", "allow_vars", (e) => e === OMAC_LL_ENV_ENTRY);
+    // prune sections our removals emptied (never anything the user still has)
+    for (const key of ["filesystem", "environment"]) {
+        const section = profile[key];
+        if (section && typeof section === "object" && !Array.isArray(section) && Object.keys(section).length === 0) {
+            delete profile[key];
+        }
+    }
+    if (!changed) {
+        actions.push(`no load-lock grants found in ${file}`);
+        return actions;
+    }
+    if (Object.keys(profile).length === 0) {
+        fs.rmSync(file);
+        actions.push(`removed ${file} (nothing else was in it)`);
+        pruneEmptyDirs(path.dirname(file), path.join(configHome(), "omac"));
+    }
+    else {
+        writeJson(file, profile);
+        actions.push(`removed load-lock grants from ${file}`);
+    }
+    return actions;
+}
+function installOmac(opts, P) {
+    const actions = [];
+    const file = omacProfileFile();
+    const existed = fs.existsSync(file);
+    const profile = omacReadProfile(file) ?? {};
+    const stateDir = resolveStateDir(process.platform, process.env);
+    const grants = [];
+    const fsSection = omacSection(profile, "filesystem");
+    grants.push(...omacMergeList(fsSection, "allow_unix_dir", [stateDir]));
+    const readTree = omacReadGrant(P);
+    if (readTree)
+        grants.push(...omacMergeList(fsSection, "read", [readTree]));
+    const envSection = omacSection(profile, "environment");
+    grants.push(...omacMergeList(envSection, "allow_vars", [OMAC_LL_ENV_ENTRY]));
+    // merge-only: never rewrite the file when nothing changed (idempotent
+    // re-install leaves the user's bytes untouched)
+    if (grants.length || !existed)
+        writeJson(file, profile);
+    if (!existed)
+        actions.push(`created ${file} (omac's user-global sandbox profile)`);
+    else if (grants.length)
+        actions.push(`grants merged into ${file}`);
+    else
+        actions.push(`all grants already present in ${file} — nothing to do`);
+    for (const g of grants) {
+        if (g === OMAC_LL_ENV_ENTRY) {
+            actions.push(`environment.allow_vars += "${OMAC_LL_ENV_ENTRY}" (prefix pattern; passes all four LOAD_LOCK_* vars through the sandbox env filter)`);
+        }
+        else if (g === stateDir) {
+            actions.push(`filesystem.allow_unix_dir += ${stateDir} (AF_UNIX connect to the host daemon socket + read/write on the state dir)`);
+        }
+        else {
+            actions.push(`filesystem.read += ${g} (installed package tree — the bin-dir grant alone is not enough; without this the CLI dies with ERR_MODULE_NOT_FOUND before reaching the socket)`);
+        }
+    }
+    if (!readTree) {
+        actions.push(`skipped filesystem.read: load-lock lives in a repo checkout (${P.root}) — the omac workdir grant already covers it`);
+    }
+    actions.push("set the values in your harness env (the grants only allow the names through): " +
+        "LOAD_LOCK_NO_SPAWN=1 (client-only; the daemon must run on the host, e.g. load-lock service start), " +
+        "LOAD_LOCK_LABEL_PREFIX=omac (dashboard shows holders as omac:<label>); " +
+        "LOAD_LOCK_SOCKET only if the default <state dir>/daemon.sock is not what the sandbox sees");
+    actions.push("label prefixes need load-lock >= 1.2.0 on BOTH ends: a daemon started before v1.2.0 " +
+        "silently strips the unknown labelPrefix field — upgrade and restart the daemon (load-lock service stop && load-lock service start)");
+    actions.push("verified live against omac 0.11.0 (bubblewrap + Landlock): sandboxed client -> host daemon " +
+        "round-trip, prefixed labels, LOAD_LOCK_NO_SPAWN error contract");
+    return actions;
+}
 // -------------------------------------------------------------------- public
 export async function installCommand(opts) {
     const P = pkgPaths(opts.binDir);
@@ -956,7 +1167,7 @@ export async function installCommand(opts) {
     }
     const harness = opts.harness;
     if (!harness)
-        throw new Error("install: --harness <opencode|claude-code|codex|cursor|gemini-cli|copilot-cli|cline|roo-code|goose|generic> is required");
+        throw new Error("install: --harness <opencode|claude-code|codex|cursor|gemini-cli|copilot-cli|cline|roo-code|goose|omac|generic> is required");
     let actions;
     switch (harness) {
         case "opencode":
@@ -992,6 +1203,9 @@ export async function installCommand(opts) {
         case "goose":
             actions = installGoose(opts, P);
             break;
+        case "omac":
+            actions = installOmac(opts, P);
+            break;
         case "generic":
         case "all":
         default:
@@ -1044,6 +1258,9 @@ export async function uninstallCommand(opts) {
         case "goose":
             actions = uninstallGoose();
             break;
+        case "omac":
+            actions = uninstallOmac();
+            break;
         default:
             throw new Error(`uninstall: unknown harness "${opts.harness}"`);
     }

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");
+});