@aron98/load-lock 1.0.0 → 1.1.0

package/README.md

@@ -71,12 +71,15 @@ 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".
 
 ## Layout
 
@@ -111,7 +114,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,15 @@
  *    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, also bound to "gl") opens the
+ *    panel IN-WINDOW via presentation: "panel" instead of fullscreen
+ *  - '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 +32,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,15 @@ 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, also bound to "gl") opens the
+ *    panel IN-WINDOW via presentation: "panel" instead of fullscreen
+ *  - '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 +38,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 +140,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 with the keymap
+ * binding shown 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` : "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 +215,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,10 +268,23 @@ 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",
                     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();
                     },
                 },
                 {
@@ -257,11 +332,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 [--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", {})));
@@ -341,7 +435,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

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

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

package/dist/test/cli.test.js

@@ -0,0 +1,99 @@
+/**
+ * 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.
+    const norm = (s) => s.replace(/synced \S+ ago/g, "synced N ago").replace(/uptime \S+/g, "uptime N");
+    assert.equal(norm(alias.stdout), norm(primary.stdout), "identical rendering");
+});

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/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/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; `gl` 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 the `gl` binding or a click on the sidebar widget) with pools, holder cards, offer claim-window countdowns, queue, paused, event feed, `inspect_machine`; home-footer `lock 1/1` indicator on the home screen plus a clickable, health-colored `load-lock 0/3` widget in the session sidebar; `x` force-release behind select + confirm. Implemented as the package's `./tui` companion plugin (main plugin unchanged). Live-verified: opencode 2.0.29 (panel render, palette/slash command, confirm-gated force-release) and opencode 2.0.32 in a real pty (sidebar widget render, click-to-open, `gl`, in-window presentation). | `load-lock dashboard` (alias `top`) |
+| **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).

package/docs/OPERATIONS.md

@@ -143,13 +143,17 @@ construction: they only ever call `status` / `events` / `inspect` / `watch`.
 The one admin action they expose — force-release — sits behind an explicit
 select + confirm step and never runs automatically.
 
-### `load-lock top` (portable, any terminal)
+### `load-lock dashboard` (portable, any terminal)
 
 ```sh
-load-lock top          # full-screen live dashboard (q quit, r resync)
-load-lock top --once   # render one frame and exit (pipes, scripts, CI logs)
+load-lock dashboard          # full-screen live dashboard (q quit, r resync)
+load-lock dashboard --once   # render one frame and exit (pipes, scripts, CI logs)
 ```
 
+`top` still works as a hidden compatibility alias for `dashboard` (same
+command, same flags) — existing scripts keep running; new docs and muscle
+memory should use `dashboard`.
+
 Shows pools with capacity vs in-use, holder cards (label, reason, phase,
 pid/pgid, age, start-deadline or lease countdown), offer cards with the
 claim-window countdown, FIFO queue positions, paused requests, the recent
@@ -165,16 +169,33 @@ alternate screen, so it works anywhere the CLI works.
 The OpenCode installer also ships the package's `./tui` plugin export (a
 companion to the main plugin, which is unchanged). Inside the opencode TUI:
 
-- `/load-lock` (or the command palette) opens the **load-lock.dashboard**
-  session panel full-screen: same data as `load-lock top`, themed,
-  live-updating.
-- The home footer gains a small `lock 1/1·Q2` indicator.
+- `/load-lock` (or the command palette, or the `gl` keybinding) opens the
+  **load-lock.dashboard** session panel **in-window** as a side panel —
+  same data as `load-lock dashboard`, themed, live-updating, with the rest
+  of the TUI layout still visible beside it.
+- Every session screen shows an at-a-glance widget at the bottom of the
+  right sidebar: `load-lock 0/3` colored by pool health (green ok, yellow
+  full/queued, red daemon down) plus a hint line. Clicking it opens the
+  dashboard; `gl` is the fallback for terminals that don't deliver mouse
+  events. The home screen keeps its `lock 1/1·Q2` footer indicator — the
+  sidebar widget only renders on session screens, so the two never
+  double-render.
 - `r` resyncs; `x` opens force-release, which requires an explicit
   select + confirm — the panel itself is read-only.
-
-Verified live against opencode 2.0.29: the panel renders pools, holder
-cards, queue positions and the event feed against the real daemon, and the
-`x` flow refuses to release anything until the confirm dialog accepts.
+- `Esc` closes the panel (the footer has always advertised this). It is
+  deliberately inactive while a dialog — force-release, the command
+  palette — is open, so Esc keeps cancelling the dialog instead of
+  closing the panel underneath it.
+
+Verified live against opencode 2.0.32 (real pty session): the sidebar
+widget renders with live daemon data, a mouse press on the widget opens
+the dashboard in-window with the chat still visible beside it, `gl` opens
+it as well, and the `/load-lock` command appears in the slash suggestions.
+Earlier live verification (2.0.29): panel render, palette/slash entry
+points, and the confirm-gated force-release flow. Click handling itself
+is contract-level from opentui (mouse reporting enabled by default,
+mouse-down events bubble to slot renderables) — the pty test above
+exercises the full path; the `gl` binding works regardless.
 Plugins configured in `opencode.json` that expose `./tui` are loaded
 automatically by the CLI, so the published package needs no extra config.
 For local development against a checkout, opencode also auto-discovers
@@ -184,13 +205,14 @@ plugins laid out like a package under `<project>/.opencode/plugins/<name>/`
 
 ### Notes for other harnesses
 
-`load-lock top` is the dashboard for every harness (it only needs the
-daemon, which every integration spawns). Harnesses without an in-app UI
-surface get exactly that — no parity claims; see `docs/COMPATIBILITY.md`.
+`load-lock dashboard` is the dashboard for every harness (it only needs
+the daemon, which every integration spawns). Harnesses without an in-app
+UI surface get exactly that — no parity claims; see `docs/COMPATIBILITY.md`.
 
 ## Diagnostics & recovery
 
 ```sh
+load-lock help             # one-screen usage of every command
 load-lock doctor            # state dir, socket, daemon reachability, effective cores, pressure
 load-lock status            # human view: usage, holders w/ phase+pid, offers, queue, paused
 load-lock pending           # your own offers/queue entries (JSON)
@@ -401,7 +423,7 @@ What the adapter does:
    reaches the daemon over the pipe (it probes by connecting, since a pipe
    is not a filesystem entry).
 
-2. Run two `load-lock acquire` in separate shells, then `load-lock top --once`.
+2. Run two `load-lock acquire` in separate shells, then `load-lock dashboard --once`.
 
    Expected: the same queue/permit behavior as on Linux — the pipe carries
    the identical NDJSON protocol.

package/package.json

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