@aron98/load-lock 0.1.2 → 1.0.0

package/docs/OPERATIONS.md

@@ -3,19 +3,35 @@
 ## Install
 
 Requirements: Node 20+, Linux (macOS works with the limitations noted below;
-Windows would need a named-pipe adapter — not implemented).
+Windows has a named-pipe transport adapter — implemented and unit-tested on
+Linux via platform injection, not yet verified on a Windows machine; see the
+Windows section at the bottom).
 
 ```sh
 npm install -g @aron98/load-lock    # or: npm install -g ./aron98-load-lock-<ver>.tgz
 load-lock install --harness opencode
 load-lock install --harness claude-code
 load-lock install --harness codex
+load-lock install --harness gemini-cli
+load-lock install --harness copilot-cli
+load-lock install --harness cline
+load-lock install --harness roo-code
+load-lock install --harness goose
+load-lock install --harness cursor --project /path/to/repo
 load-lock install --harness generic   # prints MCP snippets for other harnesses
 ```
 
 What each installer does (all merges are non-destructive; uninstall removes
 exactly the entries it added):
 
+Hook-bearing installers (claude-code, codex, cursor) recognize their own
+hook entries by the JSON-quoted CLI path embedded in the hook command, so
+re-running an installer is idempotent and uninstall removes exactly our
+entries, leaving user hooks alone. This is contract-tested via temp-HOME
+round-trips in `src/test/install.test.ts` for all three (an earlier matcher
+never matched its own entries — duplicate installs and hooks that survived
+uninstall — see issue #19); not live-verified inside the real CLIs.
+
 - **opencode** — writes a plugin stub to
   `~/.config/opencode/plugins/load-lock/` (npm-installed against the global
   package), registers it in `~/.config/opencode/opencode.json`.
@@ -27,15 +43,52 @@ exactly the entries it added):
   `Stop`), appends `[mcp_servers.load-lock]` to `~/.codex/config.toml` if
   absent, adds a marked section to `~/.codex/AGENTS.md`. **Then run `/hooks`
   inside Codex once to trust the hooks.**
-- **generic** — prints MCP stdio config snippets (Gemini CLI, Cursor,
-  Cline/Roo, Goose) plus a suggested instructions-file section.
+- **gemini-cli** — writes `mcpServers.load-lock` (stdio: `node` + absolute
+  path to `dist/mcp/main.js`) into `~/.gemini/settings.json`, adds a marked
+  section to `~/.gemini/GEMINI.md`. MCP-fallback tier: Gemini CLI has no
+  hooks and no async push, so there is no idle wakeup — offers surface at
+  tool boundaries.
+- **copilot-cli** — merges `mcpServers.load-lock` (`type: local`) into
+  `~/.copilot/mcp-config.json` (verify with `copilot mcp list`) and adds a
+  marked section to `~/.copilot/copilot-instructions.md`. MCP-fallback
+  tier: hooks are reported in ecosystem content but not verified in
+  official docs, so none are installed — no idle wakeup is claimed; offers
+  surface at tool boundaries.
+- **cline** — merges `mcpServers.load-lock` into
+  `~/.cline/data/settings/cline_mcp_settings.json` (or the path in
+  `CLINE_MCP_SETTINGS_PATH`) and writes a dedicated
+  `~/.cline/rules/load-lock.md`. MCP-fallback tier: no hooks, no async
+  push — no idle wakeup.
+- **roo-code** — merges `mcpServers.load-lock` into `<project>/.roo/mcp.json`
+  (the CLI's cwd unless `--project` is passed) and into every **existing**
+  global `mcp_settings.json` (VS Code globalStorage; existing files only —
+  never created), plus a dedicated `~/.roo/rules/load-lock.md`. MCP-fallback
+  tier: no hooks, no async push — no idle wakeup.
+- **goose** — merges an `extensions.load-lock` stdio block (marker-tagged
+  block-mapping YAML; refuses flow-style `extensions:`) into
+  `~/.config/goose/config.yaml` (XDG_CONFIG_HOME respected) and adds a
+  marked section to `~/.config/goose/.goosehints`. MCP-fallback tier: no
+  hooks, no async push — no idle wakeup.
+- **cursor** — project-level (pass `--project`, defaults to cwd): merges
+  `mcpServers.load-lock` into `<project>/.cursor/mcp.json`, merges a flat
+  hooks-v1 stop entry into `<project>/.cursor/hooks.json` (`version` added
+  only if absent; user entries preserved), writes a dedicated Always-apply
+  rule `<project>/.cursor/rules/load-lock.mdc`. Hooks tier: the stop hook
+  returns `{"followup_message":...}` so Cursor continues the session when an
+  offer arrives. Contract-tested against the documented hooks JSON
+  (https://cursor.com/docs/hooks); not live-verified.
+- **generic** — prints MCP stdio config snippets (harnesses without a
+  dedicated installer) plus a suggested
+  instructions-file section.
 
 `load-lock uninstall --harness <harness>` reverses any of these.
 
 ## The daemon
 
-- State dir: `~/.local/state/load-lock` (override `LOAD_LOCK_STATE_DIR`).
-- Socket: `<state dir>/daemon.sock` (override `LOAD_LOCK_SOCKET`).
+- State dir: `~/.local/state/load-lock` (Windows: `%LOCALAPPDATA%\load-lock`;
+  override `LOAD_LOCK_STATE_DIR`).
+- Socket: `<state dir>/daemon.sock` (Windows: named pipe `\\.\pipe\load-lock`;
+  override `LOAD_LOCK_SOCKET`).
 - **Auto-spawns** on first client connection; no service unit needed.
 - Files: `config.json` (settings + history), `journal.json` (held permits),
   `daemon.json` (pid), `spawn.lock` (bootstrap race guard).
@@ -61,8 +114,9 @@ load-lock get-config
 ```
 
 Defaults: one pool `heavy` capacity 1 · offer window 30s · blocking wait 5s ·
+turn-wait cap (`maxTurnWaitMs`, bounds `wait_for_turn`/`load-lock wait`) 10min ·
 start deadline 120s · untracked lease 15min. Valid ranges:
-offer window 1s–10min, wait 0–10min, start deadline 1s–1h, lease 10s–24h.
+offer window 1s–10min, wait 0–10min, turn-wait cap 1s–1h, start deadline 1s–1h, lease 10s–24h.
 
 Semantics of changes:
 
@@ -76,6 +130,64 @@ limits (containers respected — we never assume 2 cores means 2 jobs),
 available memory, and current load/memory pressure with an advisory
 suggestion. Agents are expected to consult it before proposing capacity.
 
+## Dashboard: watching the budget live
+
+Two read-only viewers surface the machine-wide state in real time. Both use
+the library's own client + protocol (`./shared/client`, `./shared/protocol`)
+over the daemon's watch event stream — neither scrapes CLI output — and
+both resume cleanly across daemon restarts (event-cursor `events since` +
+journal recovery).
+
+**The viewers never acquire a permit.** Watching the lock is light work by
+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)
+
+```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)
+```
+
+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
+event feed, and the `inspect_machine` panel. It reconnects with backoff if
+the daemon dies, and a daemon restart is announced and re-synced (durable
+event ids are per daemon lifetime; the cursor resets on restart).
+
+Zero extra dependencies: it renders plain text lines over the standard
+alternate screen, so it works anywhere the CLI works.
+
+### OpenCode TUI panel
+
+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.
+- `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.
+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
+plugins laid out like a package under `<project>/.opencode/plugins/<name>/`
+(`index.ts` re-exporting the main plugin, `tui.ts` re-exporting
+`./dist/adapters/opencode/tui.js`).
+
+### 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`.
+
 ## Diagnostics & recovery
 
 ```sh
@@ -117,10 +229,203 @@ Recovery policy summary:
 | Config change lost | Configuration is CAS-versioned: fetch `get_config`, retry with the fresh `version` on `version_conflict`. |
 | After OS reboot | Nothing to do: state dir persists config; daemon respawns on first use; journal reconciliation releases permits whose processes died. |
 
+## Containers / WSL2
+
+### Docker — verified
+
+Verified 2026-10-16 with Docker Engine 29.1.3 on Linux (amd64) and
+`node:24-bookworm-slim`, running load-lock 0.1.2 installed from the packed
+tarball (`npm pack`, then `npm install -g --omit=dev <tgz>` inside the
+container). Two runs, both in containers started with `--cpus=1.5
+--memory=2g`:
+
+- a sanity-check container (`load-lock doctor`, `load-lock inspect`,
+  auto-spawn proof, `attach-pid` round trip), and
+- the full `demo/demo.sh` (which needs bash + git + node; the slim image
+  needs `apt-get install -y git` first).
+
+**Cgroup v2 quota detection.** `load-lock inspect` inside the constrained
+container reported the *container* limits, not the host's:
+
+```json
+"cpu": { "logicalCores": 2, "cgroupVersion": "v2", "cgroupCpuQuota": 150000,
+         "cgroupCpuPeriod": 100000, "effectiveCores": 1 },
+"memory": { "totalBytes": 8195100672, "cgroupMemoryLimitBytes": 2147483648,
+            "effectiveLimitBytes": 2147483648 }
+```
+
+`/sys/fs/cgroup/cpu.max` reads `150000 100000` inside the container; the 2
+logical cores are still visible (`os.cpus()`/`nproc` are not namespaced),
+but `effectiveCores` is 1 (floor of the 1.5-CPU quota) and
+`effectiveLimitBytes` is exactly the 2 GiB `--memory=2g` limit while
+`totalBytes` shows the ~8 GiB host view. Pressure and the inspect
+suggestion therefore scale to the container, not the host — exactly the
+"don't assume the host's cores" behavior the inspect output promises.
+
+**Auto-spawn + default state dir.** With no `LOAD_LOCK_*` environment
+variables set, the first CLI call auto-spawned the daemon on the
+container-default `~/.local/state/load-lock` (state dir contained
+`daemon.json`, `daemon.sock`, `journal.json`; `service status` reported
+`pid 35, protocol v1, config version 1`). No special env or volumes
+needed.
+
+**Process tracking.** `/proc`-based tracking works unchanged in the
+container: `attach-pid` recorded the target with its
+`/proc/<pid>/stat` start time (`pidStartTime`), `recover list` reported
+`tracked process (pid 3367) is running`, and after the process was killed
+the daemon's 5s sweep auto-released the permit (`pool "heavy": 0/1 in
+use`). `run_with_permit` and journal reconciliation use the same mechanism.
+
+**demo.sh.** The scripted three-agent demo ran to completion (exit 0)
+inside the same plain node:24 container. Its inventory line reflected
+container limits — `cpu: 2 logical / 1 effective (v2)`, `memory: 7.6 GiB
+total / 2.0 GiB effective limit` — and the full flow played out: A
+granted, B and C queued, strict FIFO hand-off, C's offer expired →
+`paused` (not recycled), explicit `rejoin` → claim → run → release; 21
+durable events.
+
+Limitations observed (all inherent to containers, not load-lock bugs):
+
+- `/proc/loadavg` and CPU inventory are not namespaced: `loadPerEffectiveCore`
+  reflects host load, so a quiet container on a busy host can still show
+  "high" load pressure, and `nproc` shows the host CPU set. The cgroup quota
+  (`effectiveCores`) is the honest number to reason with.
+- State dir is per-container: with `docker run --rm` the daemon, config
+  history and journal vanish with the container; the next use just
+  respawns with defaults (fine for ephemeral CI containers; volume-mount
+  `~/.local/state/load-lock` if you want persistence).
+
+Reproduce from a checkout (needs `dist/` built; tarball from `npm pack`):
+
+```sh
+npm ci && npm run build && npm pack --pack-destination /tmp
+docker run --rm --cpus=1.5 --memory=2g \
+  -v "$PWD":/src:ro -v /tmp:/pkg:ro \
+  node:24 bash -c '
+    cp -a /src /work && cd /work
+    apt-get update -qq && apt-get install -y -qq git
+    npm install -g --omit=dev /pkg/aron98-load-lock-<version>.tgz
+    load-lock doctor && load-lock inspect
+    bash demo/demo.sh'
+```
+
+### WSL2 — procedure (NOT verified here)
+
+**No WSL2 environment was available on the verification machine** (the
+Docker results above were produced on a plain Linux VM). Nothing in this
+subsection has been executed by us; it is a ready-to-run procedure with
+*expected* outcomes, to be verified and recorded by someone with a WSL2
+setup.
+
+1. Use a WSL2 distro with Node 20+ (e.g. Ubuntu 24.04). Check the cgroup
+   layout inside the distro:
+
+   ```sh
+   stat -fc %T /sys/fs/cgroup      # expect cgroup2fs (cgroup v2)
+   cat /sys/fs/cgroup/cpu.max /sys/fs/cgroup/memory.max
+   ```
+
+2. Run load-lock on the distro itself (not in Docker):
+
+   ```sh
+   load-lock doctor && load-lock inspect
+   ```
+
+   Expected: WSL2 presents a full VM, so `inspect` reports the *WSL VM's*
+   resources, not the Windows host's. `.wslconfig` caps (`memory=`,
+   `processors=`) are enforced by the VM itself (vCPU count / VM RAM), not
+   via cgroup quotas — so `cgroupVersion` should read `v2` on a
+   systemd-enabled distro, `cgroupCpuQuota` typically `null` (`max`), and
+   `effectiveCores` = the `.wslconfig` `processors=` value with
+   `memory.totalBytes`/`effectiveLimitBytes` ≈ the `memory=` cap. If the
+   distro runs without systemd the cgroup controllers may not be mounted;
+   expect `cgroupVersion` to degrade to `none` and the raw VM numbers to be
+   reported — either way, no host overstating.
+
+3. With Docker inside WSL2 (docker-ce in the distro, or Docker Desktop's
+   WSL2 backend), re-run the constrained-container check from the verified
+   Docker procedure above. Expected: containers get their own nested
+   cgroup, so `inspect` should report the container quota exactly as in the
+   verified results above, regardless of the extra nesting level.
+
+4. Run `demo/demo.sh` in the distro (needs bash, git, node) and in a plain
+   `node:24` container under WSL2's Docker.
+
+Caveats to watch for (unverified expectations):
+
+- Nested cgroups (Docker Desktop's WSL2 backend adds a level) must not mask
+  the container's own `cpu.max`/`memory.max` — that's what `inspect` reads.
+- `/proc/loadavg` reflects the WSL VM, not Windows.
+- Keep the state dir on the Linux filesystem (`~/.local/state/load-lock`),
+  not on `/mnt/c` (drvfs/9p is slow and lock semantics differ).
+
 ## macOS / Windows notes
 
 - macOS: no cgroup limits; process-liveness checks fall back from
   `/proc/<pid>/stat` start times to `kill(pid, 0)` (weaker PID-reuse
   defense — document and prefer `run_with_permit`). Everything else works.
-- Windows: Unix-domain sockets are not used; a named-pipe transport adapter
-  would be required (planned, not implemented).
+
+### Windows — procedure (NOT verified here)
+
+**No Windows environment was available on the verification machine** (all
+development and testing happened on Linux). The transport adapter is
+implemented in `src/shared/transport.ts` and its logic is covered by
+`src/test/platform.test.ts` (endpoint resolution, pipe naming, probe,
+stale-cleanup, liveness, and job-tree kill paths, exercised via platform
+injection on Linux) — but nothing in this subsection has been executed on
+Windows. It is a ready-to-run procedure with *expected* outcomes, to be
+verified and recorded by someone with a Windows setup.
+
+What the adapter does:
+
+- Transport: clients and the daemon talk over the named pipe
+  `\\.\pipe\load-lock` (Node's `net` module accepts pipe paths in
+  `connect`/`createServer` natively). No Unix-domain socket is involved.
+- State dir: `%LOCALAPPDATA%\load-lock` (falls back to
+  `%USERPROFILE%\AppData\Local\load-lock`); `LOAD_LOCK_STATE_DIR` and
+  `LOAD_LOCK_SOCKET` overrides still win, as on POSIX.
+- Daemon claim: a second daemon probes the pipe before listening and
+  exits with "denied" if a live daemon answers (same semantics as the
+  POSIX socket claim). Because a named pipe is a kernel object, there is
+  no stale-socket file to clean up.
+
+1. Install Node 20+ on Windows and install the package:
+
+   ```powershell
+   npm install -g @aron98/load-lock
+   load-lock install --harness <harness>
+   load-lock doctor
+   ```
+
+   Expected: `doctor` reports the `%LOCALAPPDATA%\load-lock` state dir and
+   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`.
+
+   Expected: the same queue/permit behavior as on Linux — the pipe carries
+   the identical NDJSON protocol.
+
+3. Start a permit-tracked job (`run_with_permit` / `load-lock run`), kill
+   the job, and confirm the permit auto-releases via the sweep.
+
+4. Run `load-lock service stop`, then any tool call.
+
+   Expected: the daemon exits and the next client auto-spawns a fresh one.
+
+Caveats to watch for (unverified expectations):
+
+- **No PID-reuse defense.** Windows has no `/proc`-style start time, so
+  `isProcessAlive` can only use `kill(pid, 0)` semantics. A recycled PID
+  could be mistaken for the original job — the same limitation as macOS,
+  documented here rather than solved.
+- **No process-group scan.** The `/proc`-based process-group scan does not
+  exist on Windows. Tracked permits release when the main PID dies even if
+  child processes survive; job stop/kill uses `taskkill /PID <pid> /T`
+  (`/F` for SIGKILL) to take down the tree.
+- **Pipe name is machine-wide.** Unlike POSIX, where each user gets their
+  own state dir and socket, a named pipe named `\\.\pipe\load-lock` is
+  machine-global — two Windows users on one host share one daemon. Point
+  `LOAD_LOCK_SOCKET` at a different pipe name if that is a problem.
+- `inspect_machine` cgroup detection reads `/sys/fs/cgroup` and will
+  degrade gracefully (`cgroupVersion: "none"`), reporting raw host numbers.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aron98/load-lock",
-  "version": "0.1.2",
+  "version": "1.0.0",
   "description": "Machine-wide counting semaphore coordinating resource-intensive work across parallel coding agents (OpenCode, Codex CLI, Claude Code, ...)",
   "type": "module",
   "license": "MIT",
@@ -72,6 +72,10 @@
       "types": "./dist/core/daemon.d.ts",
       "default": "./dist/core/daemon.js"
     },
+    "./tui": {
+      "types": "./dist/adapters/opencode/tui.d.ts",
+      "default": "./dist/adapters/opencode/tui.js"
+    },
     "./dist/*": "./dist/*"
   },
   "files": [
@@ -97,8 +101,28 @@
     "@opencode/plugin": "^2.0.29",
     "zod": "^3.24.0"
   },
+  "peerDependencies": {
+    "@opentui/core": ">=0.5.8",
+    "@opentui/solid": ">=0.5.8",
+    "solid-js": ">=1.9.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentui/core": {
+      "optional": true
+    },
+    "@opentui/solid": {
+      "optional": true
+    },
+    "solid-js": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@opencode/theme": "2.0.29",
+    "@opentui/core": "0.5.17",
+    "@opentui/solid": "0.5.17",
     "@types/node": "^24.0.0",
+    "solid-js": "1.9.12",
     "typescript": "^5.9.0"
   }
 }

package/skills/load-lock/SKILL.md

@@ -23,6 +23,10 @@ Judge by *expected* CPU/memory/IO impact, not by command name. When unsure,
    `granted` (you hold a permit; start heavy work now) or `queued`
    (keep doing light work; an offer will arrive).
 2. While queued: **continue useful light work**. Do not idle-poll.
+   Out of light work? `wait_for_turn(request_id?, timeout_ms?)` — a
+   bounded blocking sleep until your turn that auto-claims the offer and
+   wakes you with the permit_token (holds no capacity; cancellation
+   leaves nothing behind).
 3. When an offer arrives (harness wakeup or `pending`): `claim(offer_token)`
    inside the claim window (default 30s). Expired offers are rejected; your
    request pauses until you `rejoin`.