@aron98/load-lock 1.0.0 → 1.2.0

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.d.ts

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

package/dist/test/cli.test.js

@@ -0,0 +1,106 @@
+/**
+ * CLI dispatch tests (issue #22): `dashboard` as the primary name of the
+ * live dashboard (with `top` as a hidden compat alias) and the `help`
+ * command (bare `load-lock`, `--help`, `-h`, `help`, `help <command>`),
+ * plus the unknown-command pointer to `load-lock help`.
+ *
+ * The help paths never connect to the daemon; the dashboard paths run the
+ * real CLI against a real daemon (piped stdout, so `--once` behavior is
+ * exercised both explicitly and via the non-TTY auto-once fallback).
+ */
+import test, { before, after } from "node:test";
+import assert from "node:assert/strict";
+import { startDaemon, runCli } from "./testutil.js";
+let d;
+before(async () => {
+    d = await startDaemon();
+});
+after(async () => {
+    await d.stop();
+});
+// ------------------------------------------------------------------ help
+test("load-lock help prints a grouped one-screen usage", async () => {
+    const r = await runCli(d, ["help"]);
+    assert.equal(r.code, 0);
+    for (const group of ["permit operations:", "waiting & running:", "read-only:", "service & diagnostics:", "setup & docs:"]) {
+        assert.ok(r.stdout.includes(group), `group "${group}" present`);
+    }
+    // Every command (primary names and aliases) gets a one-liner.
+    for (const name of [
+        "acquire", "claim", "release", "cancel", "rejoin", "mark-started", "attach-pid",
+        "wait", "run", "status", "pending", "events", "inspect", "config", "configure",
+        "dashboard", "top", "service", "doctor", "recover", "install", "uninstall",
+        "hook", "agent-guide", "help",
+    ]) {
+        assert.ok(r.stdout.includes(name), `command "${name}" described`);
+    }
+    assert.ok(r.stdout.includes("exit codes"), "exit codes line present");
+});
+test("bare load-lock and --help/-h print the same usage as help", async () => {
+    const help = await runCli(d, ["help"]);
+    const bare = await runCli(d, []);
+    const longFlag = await runCli(d, ["--help"]);
+    const shortFlag = await runCli(d, ["-h"]);
+    for (const r of [help, bare, longFlag, shortFlag])
+        assert.equal(r.code, 0);
+    assert.equal(bare.stdout, help.stdout, "bare load-lock matches help");
+    assert.equal(longFlag.stdout, help.stdout, "--help matches help");
+    assert.equal(shortFlag.stdout, help.stdout, "-h matches help");
+});
+test("load-lock help <command> prints one line; unknown topic fails", async () => {
+    const r = await runCli(d, ["help", "dashboard"]);
+    assert.equal(r.code, 0);
+    assert.ok(r.stdout.includes("load-lock dashboard"), "primary name shown");
+    assert.ok(r.stdout.includes("--once"), "one-liner mentions --once");
+    const alias = await runCli(d, ["help", "top"]);
+    assert.equal(alias.code, 0);
+    assert.equal(alias.stdout, r.stdout, "alias resolves to the same command");
+    const bad = await runCli(d, ["help", "frobnicate"]);
+    assert.equal(bad.code, 64);
+    assert.ok(bad.stderr.includes("load-lock help"), "points back to help");
+});
+test("unknown command points at load-lock help", async () => {
+    const r = await runCli(d, ["frobnicate"]);
+    assert.equal(r.code, 64);
+    assert.ok(r.stderr.includes('unknown command "frobnicate"'), "names the bad command");
+    assert.ok(r.stderr.includes("load-lock help"), "points to help");
+});
+test("flags without a command still default to status (not help)", async () => {
+    // Regression guard: only a *bare* invocation prints usage; `--json` alone
+    // keeps the historical status default.
+    const r = await runCli(d, ["--json"]);
+    assert.equal(r.code, 0);
+    const parsed = JSON.parse(r.stdout);
+    assert.ok(Array.isArray(parsed.pools), "status JSON");
+});
+// -------------------------------------------------------------- dashboard
+test("load-lock dashboard --once renders one frame and exits clean", async () => {
+    const r = await runCli(d, ["dashboard", "--once"]);
+    assert.equal(r.code, 0);
+    assert.ok(r.stdout.includes("load-lock dashboard"), "banner present");
+    assert.ok(r.stdout.includes("POOL heavy"), "pool line present");
+    assert.ok(r.stdout.includes("never acquires a permit"), "read-only note present");
+});
+test("load-lock dashboard auto-once when stdout is not a TTY", async () => {
+    // Piped stdout must not enter the alt-screen live loop.
+    const r = await runCli(d, ["dashboard"]);
+    assert.equal(r.code, 0);
+    assert.ok(r.stdout.includes("load-lock dashboard"), "frame rendered");
+    assert.ok(!r.stdout.includes("\x1b[?1049h"), "no alt-screen escape in a pipe");
+});
+test("top stays a working compat alias for dashboard", async () => {
+    const alias = await runCli(d, ["top", "--once"]);
+    const primary = await runCli(d, ["dashboard", "--once"]);
+    assert.equal(alias.code, 0);
+    assert.equal(primary.code, 0);
+    // "synced N ago" and daemon uptime tick between runs; normalize before comparing.
+    // 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/dashboard.test.js

@@ -1,6 +1,6 @@
 /**
- * Dashboard tests (issue #10): the data plumbing behind `load-lock top`
- * and the OpenCode TUI plugin panel.
+ * Dashboard tests (issue #10): the data plumbing behind `load-lock
+ * dashboard` (alias `top`) and the OpenCode TUI plugin panel.
  *
  *  - view-model shaping (buildDashboardView) against protocol fixtures,
  *    with "now" pinned so countdowns are deterministic
@@ -10,7 +10,8 @@
  *  - DashboardFeed against a REAL daemon: live view, queue visibility,
  *    release, resync idempotence, and reconnect + event-cursor resume
  *    across a daemon SIGKILL -> fresh-daemon-on-the-same-socket restart
- *  - `load-lock top --once` smoke test (read-only, never acquires)
+ *  - `load-lock top --once` smoke test (read-only, never acquires; `top`
+ *    is the compat alias of the same `dashboard` command)
  */
 import test from "node:test";
 import assert from "node:assert/strict";
@@ -394,7 +395,7 @@ test("load-lock top --once renders one frame and exits clean", async () => {
     try {
         const r = await runCli(d, ["top", "--once"]);
         assert.equal(r.code, 0);
-        assert.ok(r.stdout.includes("load-lock top"), "banner present");
+        assert.ok(r.stdout.includes("load-lock dashboard"), "banner present");
         assert.ok(r.stdout.includes("POOL heavy"), "pool line present");
         assert.ok(r.stdout.includes("q quit"), "footer present");
         assert.ok(r.stdout.includes("never acquires a permit"), "read-only note present");

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/dist/test/tui.test.d.ts

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

package/dist/test/tui.test.js

@@ -0,0 +1,89 @@
+/**
+ * TUI plugin tests (issue #24): the at-a-glance summary behind the
+ * home.footer.status indicator and the new clickable sidebar.footer widget.
+ *
+ * What is testable here without a TUI host:
+ *  - the compiled plugin module loads headless (its runtime imports are
+ *    only @opencode/plugin/tui, solid-js, and the shared client/feed —
+ *    @opentui/* are type-only) and self-describes as "load-lock.tui"
+ *  - the dashboard opens via the in-window PanelPresentation ("panel",
+ *    never fullscreen), pinned by the exported PANEL_PRESENTATION constant
+ *  - poolGlance(): the pure per-pool summary (bits + health) both
+ *    indicator surfaces share
+ *
+ * What is NOT testable here: actual slot rendering, mouse delivery in a
+ * live terminal, and panel.open behavior — those are live-verified in a
+ * real OpenCode session and documented in the PR (see docs/ updates).
+ * plugin.setup() is deliberately NOT invoked: it starts a DashboardFeed
+ * against a real daemon and would spawn/connect outside test isolation.
+ */
+import test from "node:test";
+import assert from "node:assert/strict";
+import tui, { PANEL_PRESENTATION, poolGlance } from "../adapters/opencode/tui.js";
+// ------------------------------------------------------------- fixtures
+function poolView(over = {}) {
+    return {
+        pool: "heavy",
+        capacity: 3,
+        used: 1,
+        heldWeight: 1,
+        offeredWeight: 0,
+        free: 2,
+        utilization: 1 / 3,
+        holders: [],
+        offers: [],
+        queue: [],
+        paused: [],
+        ...over,
+    };
+}
+function view(pools, state = "live") {
+    return {
+        now: 1_760_000_000_000,
+        state,
+        daemon: null,
+        pools,
+        events: [],
+        latestEventId: 0,
+        machine: null,
+        lastSyncAt: 1_760_000_000_000,
+    };
+}
+// ------------------------------------------------------ module contract
+test("tui plugin module loads headless and self-describes", () => {
+    assert.ok(tui, "default export exists");
+    // @opencode/plugin's define() is a passthrough, so the raw shape is
+    // visible without a TUI host.
+    const anyTui = tui;
+    assert.equal(anyTui.id, "load-lock.tui");
+});
+test("dashboard opens in-window: PANEL_PRESENTATION is \"panel\"", () => {
+    // PanelPresentation is exactly "panel" | "fullscreen"; "panel" is the
+    // in-window presentation (issue #24 requirement 1).
+    assert.equal(PANEL_PRESENTATION, "panel");
+});
+// ------------------------------------------------------------ poolGlance
+test("poolGlance reports bits and health per pool state", () => {
+    const healthy = poolGlance(view([poolView({ used: 1, capacity: 3 })]));
+    assert.deepEqual(healthy, { bits: ["1/3"], health: "good" });
+    const full = poolGlance(view([poolView({ used: 3, capacity: 3, free: 0, utilization: 1 })]));
+    assert.deepEqual(full, { bits: ["3/3"], health: "warn" });
+    const queued = poolGlance(view([poolView({ used: 1, capacity: 3, queue: [{}, {}] })]));
+    assert.deepEqual(queued, { bits: ["1/3", "Q2"], health: "warn" });
+    const paused = poolGlance(view([poolView({ used: 1, capacity: 3, paused: [{}] })]));
+    // paused shows in bits but does not degrade health on its own
+    assert.deepEqual(paused, { bits: ["1/3", "P1"], health: "good" });
+    const down = poolGlance(view([poolView({ used: 1, capacity: 3 })], "reconnecting"));
+    assert.deepEqual(down, { bits: ["1/3"], health: "down" });
+});
+test("poolGlance prefers the heavy pool and tolerates missing pools", () => {
+    const heavy = poolGlance(view([
+        poolView({ pool: "gpu-heavy", used: 1, capacity: 1 }),
+        poolView({ pool: "heavy", used: 0, capacity: 3, free: 3, utilization: 0 }),
+    ]));
+    assert.deepEqual(heavy, { bits: ["0/3"], health: "good" });
+    // custom configs: falls back to the first pool when no "heavy" exists
+    const fallback = poolGlance(view([poolView({ pool: "build", used: 2, capacity: 2, free: 0, utilization: 1 })]));
+    assert.deepEqual(fallback, { bits: ["2/2"], health: "warn" });
+    assert.equal(poolGlance(view([])), null);
+});

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/AGENT_GUIDE.md

@@ -137,6 +137,7 @@ load-lock run --permit <permit-token> -- cargo test --quiet       # tracks + rel
 # or acquire+run in one go:
 load-lock run --reason "nightly build" -- npm run build
 load-lock wait --id <request-id> --timeout 120000                # sleep until your turn → auto-claim
+load-lock help                                                    # one-screen usage of every command
 ```
 
 ## 4. Reading state

package/docs/ARCHITECTURE.md

@@ -208,7 +208,7 @@ is configuration, not code.
 
 The read-only status surface also extends without protocol changes: the
 `status` + `events` (durable ids) + `watch` + `inspect` methods are enough
-to build live viewers. `load-lock top` and the OpenCode TUI panel
+to build live viewers. `load-lock dashboard` (alias `top`) and the OpenCode TUI panel
 (`src/dashboard/`) are exactly that — pure view-model shaping over the
 library client (`./shared/client`), never CLI-output scraping, and never
 acquiring a permit themselves. Any future harness UI can reuse the same

package/docs/COMPATIBILITY.md

@@ -59,11 +59,13 @@ Global plugin (`load-lock install --harness opencode`) registers:
 - per-session heartbeats,
 - the package's `./tui` export: a **live lock-status dashboard panel**
   (issue #10) inside the opencode TUI — `/load-lock` opens the
-  `load-lock.dashboard` session panel (pools, holder cards, offer
-  countdowns, queue, paused, event feed, `inspect_machine`), 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).
+  `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; `/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).
 
 Verified live on opencode v2.0.29: plugin load, policy visible to the model,
 tool round-trip (acquire → queued → wakeup → claim → release), execution-
@@ -242,19 +244,19 @@ acquire→run→release in one command line.
 
 ## Live dashboard surfaces (issue #10)
 
-`load-lock top` is portable and harness-agnostic: any integration that
+`load-lock dashboard` is portable and harness-agnostic: any integration that
 spawns the daemon gets the same live dashboard in any terminal. The table
 below is deliberately honest about what each harness gets **inside its own
 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` (session panel, full-screen) with pools, holder cards, offer claim-window countdowns, queue, paused, event feed, `inspect_machine`; home-footer `lock 1/1` indicator; `x` force-release behind select + confirm. Implemented as the package's `./tui` companion plugin (main plugin unchanged). Live-verified against opencode 2.0.29: panel render + palette/slash command + confirm-gated force-release exercised in the real TUI. | `load-lock 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 top` (any terminal) |
-| **Codex CLI** | None in-app — same reason. `load_lock_status` MCP tool; `SessionStart`/`SubagentStart` machine summary. | `load-lock top` |
-| **Gemini CLI** | None in-app (no hooks, no UI plugin surface). `load_lock_status` MCP tool at tool boundaries. | `load-lock top` |
-| **Copilot CLI, Cursor, Cline, Roo Code, Goose** | None in-app. MCP `status` tool where the MCP server is configured. | `load-lock top` |
-| **Aider** | None (no MCP either). | `load-lock top` |
+| **OpenCode** | Native TUI panel: `/load-lock` opens `load-lock.dashboard` **in-window** as a side panel (also opened by clicking the sidebar widget; deliberately **not** bound to any key — issue #28: the old `gl` sequence swallowed plain `g` typing, and the candidate `ctrl+g` is the host's `session.first` default) with pools, holder cards, offer claim-window countdowns, queue, paused, event feed, `inspect_machine`; home-footer `lock 1/1` indicator on the home screen plus a clickable, health-colored `load-lock 0/3` widget in the session sidebar; `x` force-release behind select + confirm. Implemented as the package's `./tui` companion plugin (main plugin unchanged). Live-verified: opencode 2.0.29 (panel render, palette/slash command, confirm-gated force-release) and opencode 2.0.32 in a real pty (sidebar widget render, click-to-open, in-window presentation, plain `g` reaches the composer, `ctrl+g` not intercepted by load-lock). | `load-lock dashboard` (alias `top`) |
+| **Claude Code** | None in-app — Claude Code has no plugin UI surface. The model can report status via the `load_lock_status` MCP tool at tool boundaries, and each `SessionStart` hook injects a one-line machine summary. | `load-lock dashboard` (any terminal) |
+| **Codex CLI** | None in-app — same reason. `load_lock_status` MCP tool; `SessionStart`/`SubagentStart` machine summary. | `load-lock dashboard` (alias `top`) |
+| **Gemini CLI** | None in-app (no hooks, no UI plugin surface). `load_lock_status` MCP tool at tool boundaries. | `load-lock dashboard` (alias `top`) |
+| **Copilot CLI, Cursor, Cline, Roo Code, Goose** | None in-app. MCP `status` tool where the MCP server is configured. | `load-lock dashboard` (alias `top`) |
+| **Aider** | None (no MCP either). | `load-lock dashboard` (alias `top`) |
 
 All dashboard surfaces are **read-only viewers that never acquire a
 permit**; the single admin action (force-release) is gated behind an
@@ -297,7 +299,7 @@ reconnect, view-model shaping, frame rendering) is covered by
 - Core daemon/protocol/CLI: 68 automated tests + scripted 3-worktree demo
   (three independent agent processes, real git worktrees, one pool), including
   9 dashboard tests (view-model shaping, event-cursor resume across a daemon
-  restart, reconnect, and a `load-lock top --once` render smoke test) and
+  restart, reconnect, and a `load-lock dashboard --once` render smoke test) and
   9 bounded-wait tests (multi-process `wait_for_turn`: FIFO wake with
   auto-claim, timeout/pause/cancel/restart/abort paths, `maxTurnWaitMs` cap,
   MCP snake_case round trip).