@aron98/load-lock 1.0.0 → 1.2.0

package/README.md

@@ -71,12 +71,26 @@ use the generic stdio server; plain shells use the CLI:
 ```sh
 load-lock run --reason "nightly build" -- npm run build   # acquire→run→release
 load-lock status                                          # machine-wide view
-load-lock top                                             # live read-only dashboard (q quits)
+load-lock dashboard                                       # live read-only dashboard (q quits)
+load-lock help                                            # one-screen usage of every command
 load-lock configure --capacity 2 --reason "16-core host" --author me
 ```
 
-OpenCode users also get a live dashboard panel inside the TUI (`/load-lock`)
-— same data, themed. See docs/OPERATIONS.md → "Dashboard".
+OpenCode users also get a live dashboard inside the TUI: `/load-lock`
+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
 
@@ -100,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.
@@ -111,7 +125,7 @@ skills/         packaged skill
   (multi-process daemons, real processes, restarts, races, expiry,
   PID-reuse, subprocess survival; plus 9 dashboard tests — view-model
   shaping, event-cursor resume across a daemon restart, reconnect, and a
-  `load-lock top --once` render smoke test).
+  `load-lock dashboard --once` render smoke test).
 - OpenCode adapter: implemented and **live-verified** (tools, policy
   injection, compaction-proof context hook, execution-boundary wakeup
   with tokens, skill).

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

@@ -11,10 +11,16 @@
  *    holder cards (label, reason, phase, pid/pgid, age, lease deadline),
  *    offer cards with claim-window countdown, FIFO queue positions,
  *    paused requests, the recent event feed, and the inspect_machine panel
- *  - a home.footer.status indicator summarizing the heavy pool
- *  - /load-lock (palette + slash command) opens the panel full-screen
- *  - 'r' resync and 'x' force-release while the panel is open; force-release
- *    is an admin action gated behind an explicit select + confirm dialog
+ *  - a home.footer.status indicator summarizing the heavy pool (home screen)
+ *  - 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) 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
  *
  * The viewer is read-only and light: it only ever READS daemon state
  * (status / events / inspect / watch) and never acquires a permit itself.
@@ -27,5 +33,30 @@
  * that boundary, eager evaluation is exactly the semantics we want.
  */
 import { Plugin } from "@opencode/plugin/tui";
+import type { PanelPresentation } from "@opencode/plugin/tui/context";
+import { type DashboardView } from "../../dashboard/view.js";
+/**
+ * The dashboard opens as an in-window panel ("panel" is the SDK's in-window
+ * PanelPresentation; "fullscreen" takes over the whole TUI). Exported so
+ * tests can pin the choice (issue #24).
+ */
+export declare const PANEL_PRESENTATION: PanelPresentation;
+/**
+ * Health of the at-a-glance summary. "down" means the daemon feed is not
+ * live (daemon down / connecting); the others describe the pool itself.
+ */
+export type GlanceHealth = "good" | "warn" | "bad" | "down";
+/** Render-ready at-a-glance summary of one pool (pure; unit-tested). */
+export interface PoolGlance {
+    /** e.g. ["2/3", "Q1", "P2"] — used/capacity, then queue/paused counts. */
+    bits: string[];
+    health: GlanceHealth;
+}
+/**
+ * One-line heavy-pool summary shared by the home footer indicator and the
+ * sidebar widget, so both surfaces always agree. Prefers the "heavy" pool
+ * and falls back to the first pool for custom configurations.
+ */
+export declare function poolGlance(v: DashboardView): PoolGlance | null;
 declare const _default: Plugin.Definition;
 export default _default;

package/dist/adapters/opencode/tui.js

@@ -1,4 +1,4 @@
-import { jsx as _jsx, Fragment as _Fragment } from "@opentui/solid/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "@opentui/solid/jsx-runtime";
 /**
  * load-lock TUI plugin for OpenCode V2 — live lock-status dashboard (issue #10).
  *
@@ -12,10 +12,16 @@ import { jsx as _jsx, Fragment as _Fragment } from "@opentui/solid/jsx-runtime";
  *    holder cards (label, reason, phase, pid/pgid, age, lease deadline),
  *    offer cards with claim-window countdown, FIFO queue positions,
  *    paused requests, the recent event feed, and the inspect_machine panel
- *  - a home.footer.status indicator summarizing the heavy pool
- *  - /load-lock (palette + slash command) opens the panel full-screen
- *  - 'r' resync and 'x' force-release while the panel is open; force-release
- *    is an admin action gated behind an explicit select + confirm dialog
+ *  - a home.footer.status indicator summarizing the heavy pool (home screen)
+ *  - 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) 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
  *
  * The viewer is read-only and light: it only ever READS daemon state
  * (status / events / inspect / watch) and never acquires a permit itself.
@@ -33,6 +39,12 @@ import { LLClient } from "../../shared/client.js";
 import { DashboardFeed } from "../../dashboard/feed.js";
 import { fmtBytes, fmtClock, fmtDuration, } from "../../dashboard/view.js";
 const PANEL_NAME = "load-lock.dashboard";
+/**
+ * The dashboard opens as an in-window panel ("panel" is the SDK's in-window
+ * PanelPresentation; "fullscreen" takes over the whole TUI). Exported so
+ * tests can pin the choice (issue #24).
+ */
+export const PANEL_PRESENTATION = "panel";
 function themeFg(t) {
     return {
         base: t.text.base,
@@ -129,24 +141,64 @@ function PanelBody(v, panel, ctx) {
     const lines = dashboardLines(v, panel.width || 100, f);
     return (_jsx("box", { children: _jsx(_Fragment, { children: lines.map((l) => (_jsx("text", { fg: l.fg, children: l.text }))) }) }));
 }
-function MiniIndicator(v, ctx) {
-    const f = themeFg(ctx.theme);
+/**
+ * One-line heavy-pool summary shared by the home footer indicator and the
+ * sidebar widget, so both surfaces always agree. Prefers the "heavy" pool
+ * and falls back to the first pool for custom configurations.
+ */
+export function poolGlance(v) {
     const pool = v.pools.find((p) => p.pool === "heavy") ?? v.pools[0];
     if (!pool)
-        return _jsx("text", { fg: f.dim, children: "lock: no pools" });
+        return null;
     const bits = [`${pool.used}/${pool.capacity}`];
     if (pool.queue.length)
         bits.push(`Q${pool.queue.length}`);
     if (pool.paused.length)
         bits.push(`P${pool.paused.length}`);
-    const fg = v.state !== "live"
-        ? f.bad
-        : pool.used >= pool.capacity
-            ? f.warn
-            : pool.queue.length
-                ? f.warn
-                : f.good;
-    return _jsx("text", { fg: fg, children: `lock ${bits.join("·")}` });
+    let health;
+    if (v.state !== "live")
+        health = "down";
+    else if ((pool.capacity > 0 && pool.used >= pool.capacity) || pool.queue.length > 0)
+        health = "warn";
+    else
+        health = "good";
+    return { bits, health };
+}
+function healthColor(h, f) {
+    if (h === "good")
+        return f.good;
+    if (h === "warn")
+        return f.warn;
+    return f.bad; // "bad" and "down" both read as the error color
+}
+function MiniIndicator(v, ctx) {
+    const f = themeFg(ctx.theme);
+    const g = poolGlance(v);
+    if (!g)
+        return _jsx("text", { fg: f.dim, children: "lock: no pools" });
+    return _jsx("text", { fg: healthColor(g.health, f), children: `lock ${g.bits.join("·")}` });
+}
+/**
+ * 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 via the /load-lock
+ * slash command (or the command palette) named on the hint line.
+ */
+function SidebarWidget(v, ctx) {
+    const f = themeFg(ctx.theme);
+    const openDashboard = (e) => {
+        if (e.button !== 0)
+            return; // 0 = MouseButton.LEFT; ignore other buttons
+        ctx.ui.panel.open(PANEL_NAME, { presentation: PANEL_PRESENTATION });
+    };
+    const g = poolGlance(v);
+    if (!g) {
+        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` : "/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
 export default Plugin.define({
@@ -164,6 +216,17 @@ export default Plugin.define({
         const tick = setInterval(() => setView(feed.view()), 1000);
         tick.unref?.();
         const panelOpen = () => ctx.ui.panel.current()?.name === PANEL_NAME;
+        // Esc-close gate: only when OUR panel is the current one and no dialog is
+        // on top. Dialogs (select/confirm/command palette) push the host's "modal"
+        // keymap mode; in any mode other than the documented default "base"
+        // (KeymapLayer.mode), this command stays unreachable so Esc keeps its
+        // native meaning there — cancelling the dialog — instead of closing the
+        // panel underneath it. With the dashboard open and no dialog, the mode is
+        // exactly "base": the panel opens fullscreen, which the host treats as
+        // non-interactive for the session pane, so session-scoped modes (composer,
+        // autocomplete, menu) are all suspended. ctx.ui.panel.close() closes only
+        // this plugin's panel.
+        const escClosesPanel = () => panelOpen() && ctx.keymap.mode.current() === "base";
         // ------------------------------------------------------ force-release
         async function forceReleaseFlow() {
             const holders = (feed.view().pools ?? []).flatMap((p) => p.holders);
@@ -206,16 +269,45 @@ export default Plugin.define({
                     id: "load-lock.dashboard.open",
                     title: "load-lock: open the lock-status dashboard",
                     group: "load-lock",
+                    // 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: () => {
-                        ctx.ui.panel.open(PANEL_NAME, { presentation: "fullscreen" });
+                        ctx.ui.panel.open(PANEL_NAME, { presentation: PANEL_PRESENTATION });
+                    },
+                },
+                {
+                    id: "load-lock.dashboard.close",
+                    title: "load-lock: close the lock-status dashboard",
+                    group: "load-lock",
+                    bind: "escape",
+                    enabled: escClosesPanel,
+                    run: () => {
+                        ctx.ui.panel.close();
                     },
                 },
                 {
                     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: () => {
@@ -257,11 +349,26 @@ export default Plugin.define({
                 children: (v) => MiniIndicator(v, ctx),
             }),
         });
+        // Right-sidebar at-a-glance widget (session screens). The sidebar.footer
+        // slot pins it at the bottom of the sidebar so it stays visible even
+        // when the session list is long. Disjoint from the home footer above,
+        // so the two indicators never render on the same screen.
+        const offSidebar = ctx.ui.slot({
+            append: "sidebar.footer",
+            render: () => createComponent(Show, {
+                get when() {
+                    return view() ?? false;
+                },
+                keyed: true,
+                children: (v) => SidebarWidget(v, ctx),
+            }),
+        });
         return () => {
             if (tick)
                 clearInterval(tick);
             offPanel();
             offFooter();
+            offSidebar();
             void feed.stop();
         };
     },

package/dist/cli/main.js

@@ -61,7 +61,84 @@ function defaultAgent() {
     return (process.env.LOAD_LOCK_AGENT ||
         "cli:" + (process.env.USER || "user") + "@" + (process.env.HOSTNAME || "localhost"));
 }
+const HELP_GROUPS = [
+    {
+        title: "permit operations",
+        items: [
+            { 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]" },
+            { names: ["rejoin"], desc: "rejoin the queue after your offer expired or you declined: --id <request-id>" },
+            { names: ["mark-started"], desc: "mark a permit as started when no pid can be attached: --permit <token>" },
+            { names: ["attach-pid"], desc: "tie a running process to a permit (auto-release on exit): --permit <token> --pid <pid>" },
+        ],
+    },
+    {
+        title: "waiting & running",
+        items: [
+            { names: ["wait"], desc: "sleep until a queued request's turn, then auto-claim the offer: --id <request-id> [--timeout <ms>]" },
+            { names: ["run"], desc: "acquire (or reuse) a permit and run a command under it: run [--permit <token> | acquire flags] -- <cmd>" },
+        ],
+    },
+    {
+        title: "read-only",
+        items: [
+            { names: ["status"], desc: "pools, holders, offers, queue — the machine-wide view" },
+            { names: ["pending"], desc: "your outstanding offers, queue entries and paused requests" },
+            { names: ["events"], desc: "durable event log: [--since <id>] [--follow]" },
+            { names: ["inspect", "machine"], desc: "machine resources (incl. cgroup limits) and current pressure" },
+            { names: ["config", "get-config"], desc: "current configuration" },
+            { names: ["configure"], desc: "change configuration (compare-and-swap): --reason required" },
+            { names: ["dashboard", "top"], desc: "full-screen live dashboard, read-only (never acquires): [--once]" },
+        ],
+    },
+    {
+        title: "service & diagnostics",
+        items: [
+            { names: ["service"], desc: "daemon lifecycle: start | stop | status" },
+            { names: ["doctor"], desc: "health report: state dir, socket, daemon, machine" },
+            { names: ["recover"], desc: "list held permits with diagnostics; recover force-release --id <request-id>" },
+        ],
+    },
+    {
+        title: "setup & docs",
+        items: [
+            { names: ["install"], desc: "install the load-lock adapter for a harness: --harness <name>" },
+            { names: ["uninstall"], desc: "remove what install added: --harness <name>" },
+            { names: ["hook"], desc: "harness hook handlers (called by integrations, not humans)" },
+            { names: ["agent-guide"], desc: "print the full agent guide" },
+            { names: ["help"], desc: "this usage; also bare load-lock, --help, -h; help <command> for one line" },
+        ],
+    },
+];
+function displayName(item) {
+    return item.names[0] + (item.names.length > 1 ? ` (${item.names.slice(1).join(", ")})` : "");
+}
+const HELP_PAD = Math.max(...HELP_GROUPS.flatMap((g) => g.items.map((i) => displayName(i).length)));
+function helpLine(item) {
+    return `  ${displayName(item).padEnd(HELP_PAD)} ${item.desc}`;
+}
+/** Grouped one-screen usage, printed by `help`, bare `load-lock`, `--help`/`-h`. */
+function usage() {
+    const lines = [
+        "load-lock — machine-wide heavy-work budget shared by all coding agents",
+        "usage: load-lock <command> [flags]        (--json works on read commands)",
+    ];
+    for (const g of HELP_GROUPS) {
+        lines.push("", `${g.title}:`);
+        for (const item of g.items)
+            lines.push(helpLine(item));
+    }
+    lines.push("", "exit codes: 0 ok, 64 usage, 65 protocol, 68 not granted yet, 69 offer/claim failed, 70 internal");
+    process.stdout.write(lines.join("\n") + "\n");
+}
 async function main() {
+    // `--help`, `-h` and a bare `load-lock` all print the same usage as `help`.
+    if (f["help"] !== undefined || cmd === "-h" || (positional.length === 0 && argv.length === 0)) {
+        usage();
+        return;
+    }
     switch (cmd) {
         // ------------------------------------------------------------- read-only
         case "status": {
@@ -85,12 +162,29 @@ async function main() {
             return;
         }
         // ------------------------------------------------------------- dashboard
+        case "dashboard":
         case "top": {
             // Full-screen live dashboard (read-only, never acquires a permit).
-            // Falls back to a single rendered frame when stdout is not a TTY.
+            // `dashboard` is the primary name; `top` stays as a hidden compat
+            // alias. Falls back to a single rendered frame when stdout is not a
+            // TTY (or with --once).
             await topCommand({ once: B("once") });
             return;
         }
+        case "help": {
+            // `load-lock help` — grouped one-screen usage. `help <command>` is
+            // the optional per-command form: just that command's one-liner.
+            const topic = rest[0];
+            if (topic === undefined) {
+                usage();
+                return;
+            }
+            const item = HELP_GROUPS.flatMap((g) => g.items).find((i) => i.names.includes(topic));
+            if (!item)
+                fail(`help: unknown command "${topic}" — run "load-lock help" for the full list`);
+            process.stdout.write(`load-lock ${item.names[0]} — ${item.desc}\n`);
+            return;
+        }
         case "inspect":
         case "machine":
             out(await withClient((c) => c.request("inspect", {})));
@@ -159,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"),
@@ -341,7 +436,7 @@ async function main() {
             return;
         }
         default:
-            fail(`unknown command "${cmd}". Commands: status, top, inspect, config, pending, events, acquire, claim, release, cancel, rejoin, mark-started, attach-pid, wait, run, service, doctor, recover, install, uninstall, hook, agent-guide`);
+            fail(`unknown command "${cmd}" — run "load-lock help" for the list of commands`);
     }
 }
 // ------------------------------------------------------------------ run helper
@@ -367,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/cli/top.js

@@ -1,6 +1,7 @@
 /**
- * `load-lock top` — portable, zero-dependency full-screen terminal dashboard
- * for the machine-wide budget. Uses the library's own client + protocol
+ * `load-lock dashboard` (hidden compat alias: `load-lock top`) — portable,
+ * zero-dependency full-screen terminal dashboard for the machine-wide
+ * budget. Uses the library's own client + protocol
  * (never scrapes CLI output); live updates come from the `watch` event
  * stream, with reconnect + event-cursor resume across daemon restarts.
  *

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/dashboard/frame.d.ts

@@ -1,6 +1,7 @@
 /**
- * Plain-text frame renderer for `load-lock top` — and for any other
- * terminal surface that wants the same dashboard without a TUI toolkit.
+ * Plain-text frame renderer for `load-lock dashboard` (alias `top`) — and
+ * for any other terminal surface that wants the same dashboard without a
+ * TUI toolkit.
  * Pure function: view-model in, string[] out (one line per row).
  *
  * Deliberately zero-dependency (ANSI handled by the caller): this keeps

package/dist/dashboard/frame.js

@@ -1,6 +1,7 @@
 /**
- * Plain-text frame renderer for `load-lock top` — and for any other
- * terminal surface that wants the same dashboard without a TUI toolkit.
+ * Plain-text frame renderer for `load-lock dashboard` (alias `top`) — and
+ * for any other terminal surface that wants the same dashboard without a
+ * TUI toolkit.
  * Pure function: view-model in, string[] out (one line per row).
  *
  * Deliberately zero-dependency (ANSI handled by the caller): this keeps
@@ -56,7 +57,7 @@ export function renderFrame(view, width = 100, height = 40) {
     };
     const state = STATE_LABEL[view.state] ?? String(view.state);
     const syncAge = view.lastSyncAt ? fmtDuration(Math.max(0, view.now - view.lastSyncAt)) : "never";
-    push(`load-lock top — machine-wide heavy-work budget   ${state}   synced ${syncAge} ago`);
+    push(`load-lock dashboard — machine-wide heavy-work budget   ${state}   synced ${syncAge} ago`);
     if (view.daemon) {
         push(`daemon pid ${view.daemon.pid} · uptime ${fmtDuration(view.daemon.uptimeMs)} · config v${view.daemon.configVersion} · protocol v${view.daemon.protocolVersion} · events through #${view.latestEventId}`);
     }

package/dist/dashboard/view.d.ts

@@ -2,7 +2,8 @@
  * Dashboard view-model: pure shaping of daemon data (status / inspect /
  * durable events) into the cards every dashboard surface renders.
  *
- * Shared by `load-lock top` (src/cli/top.ts) and the OpenCode TUI plugin
+ * Shared by `load-lock dashboard` (alias `top`, src/cli/top.ts) and the
+ * OpenCode TUI plugin
  * (src/adapters/opencode/tui.tsx) so both show exactly the same state and
  * only differ in rendering. Everything here is pure and synchronous —
  * "now" is always an explicit parameter, which makes countdowns testable.

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. */