@aron98/load-lock 1.4.0 → 1.6.0

package/docs/OPERATIONS.md

@@ -7,6 +7,49 @@ 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).
 
+### The install ladder
+
+load-lock can be installed at several levels ("rungs"). Each rung works on
+its own, and a higher rung only adds capability. Installing more than one,
+in any order, is safe: there is still one daemon and one budget, one
+identity per session, and duplicate hooks are dropped by the daemon (see
+[ARCHITECTURE.md](ARCHITECTURE.md#three-layers-daemon-runtime-copies-harness-wiring)).
+
+| Rung | What you install | Runtime it runs | What the agent gets |
+| --- | --- | --- | --- |
+| 0 | **Skill only** (`skills/load-lock/SKILL.md`) | the load-lock MCP tools if listed, else `load-lock` on PATH, else `npx -y @aron98/load-lock@<version>` (pinned in the skill) | the full permit lifecycle through the CLI (`run`, `wait`, `acquire` / `claim` / `release`, `cancel`); the first call starts the daemon. No idle wakeup, no policy injection, nothing after compaction |
+| 1 | **MCP server** (`npx -y @aron98/load-lock@<version> mcp`) | the pinned npx copy | the tools; your offers in every load-lock tool result; `wait_for_turn` / `wait_for_completion` bounded sleeps; the policy in the MCP `instructions` where the harness shows them; the `agent_guide` tool |
+| 2 | **Harness plugin**: Claude Code `load-lock-plugin`, OpenCode npm plugin `@aron98/load-lock` | Claude Code: the plugin launcher (PATH CLI if new enough, else a known copy, else pinned npx); OpenCode: its own plugin cache copy | everything the harness supports: tools, policy at session start that survives compaction, offer wakeups at turn ends and while idle |
+| — | **`npm i -g` + `load-lock install --harness <h>`** | the global CLI | the same wiring as loose config files. The only route for harnesses without a plugin, and the escape hatch where plugins aren't allowed |
+
+Each rung points at the next one once: the skill, the MCP `instructions`
+and the session-start brief end with a one-line pointer to
+[`load-lock setup`](#load-lock-setup-what-is-installed-where), which lists
+what is installed where and converges it. The rung each harness can reach
+is in [COMPATIBILITY.md](COMPATIBILITY.md#rung-per-harness).
+
+How to install each rung:
+
+- **Skill (0).** Through ACE (the `load-lock` skill artifact, see
+  [Installing via ACE](#installing-via-ace)), or copy `skills/load-lock/`
+  (shipped in the npm package and the repo) into your harness's skills
+  directory. `load-lock install --harness claude-code` also copies it to
+  `~/.claude/skills/load-lock/`.
+- **MCP server (1).** Through ACE (the `ace/mcp` artifact), or register a
+  stdio server named `load-lock` with command `npx` and args
+  `["-y", "@aron98/load-lock@<version>", "mcp"]`, exactly what
+  `ace/mcp/mcp.json` declares. `load-lock mcp` is the same server as the
+  `load-lock-mcp` binary. With a global install,
+  `load-lock install --harness generic` prints a snippet that runs that
+  copy instead of npx.
+- **Plugin (2).** Claude Code: see [Claude Code plugin](#claude-code-plugin).
+  OpenCode: add `@aron98/load-lock` to the `plugins` array of
+  `~/.config/opencode/opencode.json` (OpenCode downloads and updates it),
+  or let `load-lock install --harness opencode` register it.
+- **Loose wiring.** The installers below.
+
+### `npm i -g` + `load-lock install`
+
 ```sh
 npm install -g @aron98/load-lock    # or: npm install -g ./aron98-load-lock-<ver>.tgz
 load-lock install --harness opencode
@@ -32,13 +75,23 @@ 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`.
+- **opencode** — registers the published package `@aron98/load-lock` in
+  the `plugins` array of `~/.config/opencode/opencode.json` (OpenCode
+  installs and updates it itself) and removes the legacy plugin stub
+  `~/.config/opencode/plugins/load-lock/` if an older install left one.
 - **claude-code** — adds `mcpServers.load-lock` to `~/.claude.json`; hooks
   (`SessionStart`, `Stop`, async `await-offer`) to `~/.claude/settings.json`;
   a marked section to `~/.claude/CLAUDE.md`; copies the skill to
-  `~/.claude/skills/load-lock/`.
+  `~/.claude/skills/load-lock/`. A skill dir it didn't write (an ACE
+  install with an `.ace.json` stamp, or a symlink) is left alone by both
+  `install` and `uninstall`, which say so (#89). With the
+  [Claude Code plugin](#claude-code-plugin) enabled in
+  `~/.claude/settings.json` (`enabledPlugins["load-lock-plugin@…"]: true`),
+  `install` instead removes the loose MCP server, hooks and `CLAUDE.md`
+  section, reporting each step, and only installs the skill (the plugin
+  ships none); `--legacy` installs the loose wiring anyway. `uninstall`
+  removes loose entries only and names the `/plugin uninstall …` command
+  for the plugin (#62).
 - **codex** — writes `~/.codex/hooks.json` (`SessionStart`, `SubagentStart`,
   `Stop`), appends `[mcp_servers.load-lock]` to `~/.codex/config.toml` if
   absent, adds a marked section to `~/.codex/AGENTS.md`. **Then run `/hooks`
@@ -83,6 +136,135 @@ uninstall — see issue #19); not live-verified inside the real CLIs.
 
 `load-lock uninstall --harness <harness>` reverses any of these.
 
+### `load-lock setup`: what is installed where
+
+`load-lock setup [--project <dir>] [--json]` lists every load-lock
+integration it finds, for every harness `install` supports (the project
+defaults to the cwd). It is **read-only**: it never writes a file.
+
+For each harness it reports:
+
+- **what** it found: plugins (Claude Code `enabledPlugins` entries named
+  `load-lock-plugin@…`, OpenCode `plugin` / `plugins` entries), MCP
+  registrations (user and project scope, including ACE's `.mcp.json`
+  `servers` patch), loose hooks, policy sections / rule files, skill
+  copies, and omac sandbox grants;
+- **who** wrote each entry: `installer` (the exact shape `load-lock
+  install` writes), `harness` (the harness's own plugin state), `ace`
+  (an `.ace.json` stamp sits next to it), or `other` (manual, npx, …);
+- **which copy** an entry runs, and whether that copy is gone (stale);
+- the **rung**: `plugin`, `loose` (`load-lock install` wiring), `MCP only`,
+  `skill only`, or `not installed`;
+- **findings**: loose hooks next to an active plugin, the MCP server
+  registered more than once (a Claude Code plugin's bundled server counts),
+  hooks from more than one copy, duplicate hook entries, several skill
+  copies, stale entries, disabled plugins.
+
+It ends with the runtime copies: those on disk (as in `doctor`), the copy
+the daemon runs (`daemon.json`), and the copies the daemon has seen.
+
+An ACE-installed Claude plugin (unzipped into `.claude/skills/<name>/`) is
+listed but not counted as an active plugin: whether Claude Code loads it
+there is not verified yet (#63).
+
+#### Converging: `load-lock setup --yes`
+
+After the inventory, `setup` prints a **plan** that brings every harness
+that already has some load-lock wiring to the recommended layout: the
+highest rung available, exactly one of each. Without `--yes` it is a dry
+run. `--yes` applies it (`--json` adds `plan` and `applied`). Harnesses with
+nothing installed are left alone; the plan names them once.
+
+The plan only uses moves the installers can reverse:
+
+| Situation | Step |
+|---|---|
+| Claude Code plugin enabled **and** loose `install` wiring | `remove-loose`: drop the loose MCP server, hooks and `CLAUDE.md` section (the plugin provides them). The skill stays: the plugin ships none. Undo: `load-lock install --harness claude-code --legacy`. |
+| Installer wiring incomplete, pointing at a missing copy, or hooks from several copies / duplicated | `install`: remove the installer-shaped hooks of every copy (and a stale codex `[mcp_servers.load-lock]` block), then `load-lock install --harness <h>` from the running copy |
+| Only an MCP registration or only the skill | `install` (moves up to the installer's rung) |
+| Anything not written by `load-lock install` (plugin state, ACE entries, manual / npx entries, extra skill copies) | `manual`: printed with what to remove or run (`/plugin uninstall …`), never applied |
+
+Guards, each turning an `install` into a `manual` step:
+
+- a foreign entry sits in the slot `install` would overwrite (e.g. a
+  hand-written `mcpServers.load-lock`);
+- the Claude Code skill directory is managed by ACE (`.ace.json`);
+- the running copy lives in the npx or opencode cache, which npm may prune
+  (install globally first);
+- `cursor` / `roo-code` write into the project, so they are only refreshed
+  when the project already has their installer wiring.
+
+`load-lock uninstall --harness <h>` still removes everything load-lock
+added, after a converge as before it. The MCP instructions and the
+session-start brief end with a one-line pointer to `load-lock setup`.
+
+### Claude Code plugin
+
+Instead of `install --harness claude-code`, Claude Code can load load-lock
+as a plugin (issue #61). The repo root is a marketplace
+(`.claude-plugin/marketplace.json`) listing one plugin, `load-lock-plugin`,
+in `plugins/claude-code/`:
+
+```text
+/plugin marketplace add aron98/load-lock
+/plugin install load-lock-plugin@load-lock
+```
+
+- **MCP server** `load-lock`, declared inline in `plugin.json` and started
+  through the launcher (`--bin load-lock-mcp`). Tools are named
+  `mcp__plugin_load-lock-plugin_load-lock__<tool>`.
+- **Hooks** in `hooks/hooks.json`, the same three as the loose install:
+  `SessionStart` (policy + machine summary), `Stop` (offer continuation)
+  and the `async` + `asyncRewake` `await-offer` watcher. Each runs in shell
+  form, one command string `node "${CLAUDE_PLUGIN_ROOT}/scripts/load-lock.mjs"
+  hook claude-code <event>` with the root quoted (#63). Shell form is the
+  long-documented hook shape; exec form (`command` + `args`) has no
+  documented minimum Claude Code version. The string has no shell
+  metacharacters, so ACE's `plugin_hooks_command_safe` check passes.
+- **No skill and no CLAUDE.md section.** The policy arrives through the
+  SessionStart hook (re-fired after compaction), and the full guide through
+  the `agent_guide` MCP tool. Install the `load-lock` skill separately if
+  wanted. The plugin is not named `load-lock`, so it doesn't clash with the
+  skill on ACE (#64).
+- **Runtime**: the plugin ships no `dist/`. See [Plugin launcher](#plugin-launcher)
+  for how hooks and the MCP server find one.
+- `plugin.json` `version` is pinned to `package.json` by `check-pins`. A
+  pinned version keeps users on it until the next release changes it.
+
+Combining the plugin with a loose `install --harness claude-code` is safe
+(one session identity, duplicate hooks dropped by the daemon, #54), but
+registers two MCP servers; keep one. Once the plugin is enabled, re-running
+`load-lock install --harness claude-code` (or `load-lock setup --yes`) moves
+the loose MCP server, hooks and `CLAUDE.md` section out (`--legacy` keeps
+them), and `load-lock doctor` reports the mode (`claudeCodeMode`: `plugin`,
+`loose`, `both` or `none`) and warns on `both`.
+
+### Installing via ACE
+
+[ACE](https://github.com/TNG/ace) imports artifacts from this repository.
+ACE does not edit harness config itself: its `install_artifact` tool hands
+the agent a download plus instructions, and the agent unpacks and wires it
+(findings in issue #64). This repo provides one artifact per folder:
+
+| Folder | ACE kind | What installing it gives you |
+| --- | --- | --- |
+| `skills/load-lock/` | skill `load-lock` | rung 0; unpacked into the harness's skills directory (e.g. `.claude/skills/load-lock/`) |
+| `ace/mcp/` | MCP server `load-lock` (local, stdio) | rung 1; ACE returns a patch with `npx -y @aron98/load-lock@<version> mcp` for the agent to merge into the MCP config (e.g. `.mcp.json`) |
+| `plugins/claude-code/` | Claude Code plugin `load-lock-plugin` | rung 2; ACE unpacks Claude plugins as skills-directory plugins (`.claude/skills/load-lock-plugin/`), not through `/plugin install` |
+| `ace/opencode/` | OpenCode plugin (pointer) | rung 2; install the published `@aron98/load-lock` into `opencode.json` as above, not the folder (see [COMPATIBILITY.md](COMPATIBILITY.md#ace-listing-opencode-issue-79)) |
+
+Install the MCP server **or** the Claude Code plugin, not both: the plugin
+already bundles the server (two registrations are harmless, just
+redundant). The plugin is not named `load-lock`, so it doesn't unpack into
+the skill's directory. ACE updates what it installed (it writes an
+`.ace.json` stamp next to each bundle); `load-lock setup` reports those
+entries as `ace` and never rewrites them.
+
+Not yet verified (#63, #66): whether Claude Code loads a plugin from a
+skills directory (and resolves `${CLAUDE_PLUGIN_ROOT}` there), and the ACE
+install end to end on a clean machine. Until then `load-lock setup` lists an
+ACE-installed Claude plugin but does not count it as an active plugin.
+
 ## The daemon
 
 - State dir: `~/.local/state/load-lock` (Windows: `%LOCALAPPDATA%\load-lock`;
@@ -96,12 +278,23 @@ uninstall — see issue #19); not live-verified inside the real CLIs.
 - Also honored by the shared client: `LOAD_LOCK_LABEL_PREFIX` (prefix for
   holder labels; see Sandboxes).
 - Files: `config.json` (settings + history), `journal.json` (held permits +
-  queued requests), `daemon.json` (pid), `spawn.lock` (bootstrap race guard).
+  queued requests), `daemon.json` (pid, plus since #52 the daemon's
+  `packageRoot` and `version`), `runtimes.json` (known runtime copies, see
+  below), `spawn.lock` (bootstrap race guard).
+- **Known runtime copies** (since #52): every client envelope carries its
+  package root (`clientRoot`); the daemon validates it (a package.json
+  naming `@aron98/load-lock`; the version is read from disk, not trusted
+  from the client) and records `{path, version, lastSeen}` in
+  `runtimes.json`, deduped by real path, pruning copies whose path is gone.
+  Small entry points (skill, plugin launchers) can read `daemon.json` /
+  `runtimes.json` to find an existing runtime without npx; `doctor` lists
+  them as `daemonRuntime` and `knownRuntimes`.
 
 ```sh
 load-lock service status   # hello + pid + daemon version
 load-lock service start    # ensure running (idempotent); refusals name the conflicting pid
 load-lock service stop     # SIGTERM → bounded wait → SIGKILL; verifies the socket is free
+load-lock service restart  # stop then start; both phases reported; failures name the phase
 ```
 
 `service stop` is honest, not fire-and-forget: it signals the daemon
@@ -110,6 +303,64 @@ socket still answers, and only reports success once the endpoint is
 verifiably free (stale `daemon.json`/socket files are cleaned up either way).
 `service start` refuses loudly when something else owns the endpoint —
 naming the conflicting pid — instead of a bare "did not come up within 10s".
+`service restart` (since #38) composes the same two hardened phases and
+reports both lines; a failure names the phase and reason
+(`restart failed in the STOP phase: ...` / `... in the START phase ...`).
+Stopping when nothing runs is not an error: the start phase simply spawns a
+fresh daemon.
+
+## Plugin launcher
+
+Plugin and ACE bundles are git folders without `dist/`, so their hooks and
+MCP server go through a committed, dependency-free launcher,
+`plugins/claude-code/scripts/load-lock.mjs` (issue #60; plain ESM, Node
+built-ins only, no build step):
+
+```sh
+node plugins/claude-code/scripts/load-lock.mjs hook claude-code stop   # any `load-lock` CLI args
+node plugins/claude-code/scripts/load-lock.mjs --bin load-lock-mcp     # the MCP server
+```
+
+It runs the first runtime it finds:
+
+1. `load-lock` on PATH, when its version is at least the launcher's pin;
+2. else the newest known copy at least the pin from the state dir
+   (`runtimes.json`, `daemon.json`'s `packageRoot`; see #52 above);
+3. else `npx --yes --package=@aron98/load-lock@<pin> -- <bin>`.
+
+Branches 1 and 2 run the copy's compiled entry (`dist/cli/main.js` /
+`dist/mcp/main.js`) with the launcher's own `node`, so no shell and no
+`.cmd` shim is involved. For npx it prefers the `npx-cli.js` shipped next to
+`node`, falling back to `npx` (POSIX) or `npx.cmd` through a shell
+(Windows). The pin is kept equal to `package.json` by `check-pins`.
+
+Hook mode (`hook ...`) never breaks or stalls a session:
+
+- npx runs with `--offline` (npm cache only), so a cold cache fails in
+  well under a second instead of downloading. The MCP server's npx start
+  is online and warms the cache for later hooks.
+- The run is bounded by `LOAD_LOCK_LAUNCHER_TIMEOUT_MS` (default 15000;
+  the process group is killed). Not applied to the long-lived
+  `await-offer` watcher.
+- Any failure exits 0; exit 2 passes through (the `asyncRewake` wakeup).
+  A failed SessionStart that printed nothing prints one install hint
+  instead of the policy.
+
+The MCP server mode passes the runtime's exit code through and reports a
+missing runtime on stderr. `LOAD_LOCK_LAUNCHER_DEBUG=1` prints the chosen
+branch to stderr.
+
+**Measured latency (PATH branch).** On a Linux box (Node 22, 32 cores, warm
+file cache, daemon running), median over 20 runs:
+
+| Hook | Direct `node dist/cli/main.js` | Through the launcher |
+|---|---|---|
+| `hook claude-code stop` | 31 ms | 52 ms |
+| `hook claude-code session-start` | 32 ms | 52 ms |
+
+So the launcher adds about 20 ms (one extra Node start plus PATH/package.json
+lookups). A warm npx (`--offline`) run adds about 0.2 s; a cold one fails in
+about 0.2 s.
 
 ## Update lifecycle
 
@@ -121,9 +372,13 @@ code. The **version handshake** closes that gap (v1.3.0+):
   carry `daemonVersion` (the package version of the code the daemon runs).
 - When a **newer** client contacts an older daemon, the daemon finishes
   answering, then **self-restarts**: it persists state + journal, drains all
-  connections, respawns itself with the same argv (`process.execPath` +
-  original arguments, so it runs whatever is now on disk at the same path),
-  and exits. The respawn inherits a `LOAD_LOCK_RESTARTED_FOR` marker so
+  connections, respawns, and exits. Since #53 the respawn runs the **newer
+  client's copy** when the envelope's `clientRoot` checks out (a
+  `@aron98/load-lock` package.json whose on-disk version equals the
+  claimed `clientVersion`, plus a `dist/core/daemon-main.js`), so a daemon
+  spawned by an old global CLI moves onto e.g. a newer npx copy. Without a
+  valid hint it falls back to the same argv (`process.execPath` + original
+  arguments, so it runs whatever is now on disk at the same path). The respawn inherits a `LOAD_LOCK_RESTARTED_FOR` marker so
   repeated contact with the same version cannot cause a restart loop — one
   respawn attempt per version.
 - Clients that were connected see a disconnect and simply reconnect to the
@@ -139,17 +394,117 @@ code. The **version handshake** closes that gap (v1.3.0+):
   pending self-restart; `doctor` actively waits a few seconds to confirm the
   daemon came back on the new version.
 
-Limits, stated honestly: the respawn re-runs the **same argv** — it picks up
-an updated copy only if the daemon's launching copy was updated *in place*
-(the normal `npm i -g` case). A daemon spawned from a different copy (e.g.
-opencode's private cache copy) keeps running that copy's code after a
-restart; see the multi-copy notes in
+### `load-lock update` (since #38)
+
+The update command checks npm for a newer version, classifies where *this*
+copy lives **before touching anything**, and applies the update via the
+detected package manager — or refuses honestly rather than guessing:
+
+| this copy is...                       | `load-lock update` does                                            |
+| ------------------------------------- | ------------------------------------------------------------------ |
+| bun global (`~/.bun/install/global/…`)  | `bun i -g @aron98/load-lock@latest`                                |
+| npm global (under `npm root -g`)        | `npm i -g @aron98/load-lock@latest`                                |
+| opencode's npm-cache copy               | refuses — opencode manages this copy and refreshes it on its own schedule |
+| npx cache copy (`~/.npm/_npx/<hash>/…`, since #57) | refuses — it is whatever version the launching `npx -y @aron98/load-lock@<pin>` pins; bump that pin (MCP/skill config or ACE artifact) |
+| a git checkout (nearest `.git`)         | refuses — update it via your git workflow (`git pull` etc.)        |
+| anything else                           | refuses — "cannot tell how this copy was installed"                 |
+
+After a successful apply it runs `service restart` explicitly, so the
+daemon moves onto the new code immediately (the version handshake remains
+the safety net, not the primary means). The package manager's output is
+shown live. `--check` is a dry run that touches nothing and uses
+script-friendly exit codes:
+
+- exit `0` — up to date (or this copy is ahead of the registry)
+- exit `1` — an update is available (including the honest refusals above:
+  the update *exists*, this copy just cannot self-apply it)
+- exit `70` — failure (registry unreachable, package manager failed, or a
+  refusal in apply mode)
+
+Reports are prose for humans and `--json` structured objects for agents
+(`state`: `up-to-date` | `update-available` | `refused` | `updated`).
+
+### Adapter-init drift notice
+
+The mirror problem is a *newer adapter copy* with an *older CLI on PATH*
+(typically: opencode refreshed its private cache copy, the global install
+was never updated). At init, the OpenCode plugin and the MCP server compare
+their own version with the PATH-resolved CLI copy's `package.json` and
+surface **one clear notice** naming the exact command (`load-lock update`),
+on stderr and in the injected context / MCP `instructions`. Notify only —
+**nothing is ever auto-installed**. Honest limitation: a harness session
+that was already running keeps the *old* adapter code in memory until the
+harness itself restarts, so the notice fires from the new copy at its init
+— sessions started before a refresh see it on their next restart.
+The same check covers **npx-vs-PATH skew** (#57): an MCP server launched
+via a pinned `npx -y @aron98/load-lock@<pin>` runs from the npx cache, and
+when that copy is newer than the PATH CLI the notice names it as the npx
+copy. (The reverse — a pin older than the PATH CLI — is not flagged here;
+the daemon's version handshake already keeps the daemon on the newer code.)
+
+Limits, stated honestly: the respawn moves onto the newer client's copy
+only when that client sends a valid `clientRoot` (#52/#53). Clients older
+than #52 don't, so the respawn re-runs the **same argv** and picks up an
+updated copy only if the daemon's launching copy was updated *in place*
+(the normal `npm i -g` case); `load-lock service restart` moves it onto
+the current CLI copy. See the multi-copy notes in
 [COMPATIBILITY.md](COMPATIBILITY.md#multiple-copies-of-load-lock-opencode).
 Pre-1.3.0 daemons do not answer the handshake and never self-restart —
-`service stop` followed by any load-lock command moves them onto current
-code. The restart behavior itself is live-verified on Linux by the test
-suite (`src/test/update.test.ts`); the in-place-update path beyond
-same-argv respawn is inspected, not live-tested.
+`service restart` (or `service stop` followed by any load-lock command)
+moves them onto current code. The restart behavior itself is live-verified
+on Linux by the test suite (`src/test/update.test.ts`); the in-place-update
+path beyond same-argv respawn is inspected, not live-tested. The `update`
+command's stop→start compositing, its refusals, `--check` exit codes, and
+the adapter-init drift notice are live-verified on Linux by
+`src/test/update-command.test.ts` — with a **stubbed npm on PATH and a
+planted copy**; no test ever contacts the real npm registry or installs
+anything, so the genuine `npm i -g` round trip is contract-tested, not
+live-tested.
+
+### Plugin in-memory staleness (issue #39)
+
+The daemon heals itself via the handshake, but the **opencode plugin does
+not**: opencode loads plugin code **once per process at startup** and never
+hot-reloads it. After `npm i -g @aron98/load-lock@latest` (or opencode
+refreshing its plugin cache for *new* sessions), an already-running opencode
+session keeps executing the **old copy in memory** — even though the panel
+and dashboards reconnect to the daemon just fine. A stale in-memory plugin
+is not a reconnect failure; restarting opencode is the only way to pick up
+the new plugin code.
+
+To make that visible instead of mysterious (v1.4.1+):
+
+- The dashboards (TUI panel and `load-lock dashboard`) periodically compare
+  the running copy's version with the PATH-resolved `load-lock` install.
+  When the PATH CLI is newer, the panel shows
+  `note: plugin updated — restart opencode to pick up vX (this session
+  still runs vY; opencode does not hot-reload plugins)`; the CLI surface
+  says the running copy is stale instead.
+- When the daemon itself restarts onto a **different version** (update
+  self-restart, or a manual restart of a newer install), the reconnect note
+  names it: `daemon restarted onto v1.5.0 (was v1.4.0; pid N); event
+  history re-synced`.
+- If a harness pruned the running copy's plugin-cache directory mid-session
+  (making the on-disk daemon entry vanish), client auto-spawn falls back to
+  the PATH-installed CLI's daemon instead of failing with ENOENT forever.
+- Recovery story: the daemon side is automatic (handshake self-restart);
+  the plugin side needs exactly one action — **restart opencode**. Until
+  then everything keeps working; only the plugin's code (and its notes)
+  is one version behind.
+
+The reverse direction — a *newer* adapter copy with an *older* CLI on PATH —
+is #38's [adapter-init drift notice](#adapter-init-drift-notice), above.
+
+Verification split (honest): live-verified on Linux by
+`src/test/reconnect.test.ts` against real daemons — the daemon-kill
+auto-respawn reconnect (the H1 repro), the failed-initial-connect recovery,
+and the vanished daemon entry not crashing the host (real ENOENT spawn
+through the compiled client). Contract-tested — mock client / planted
+fixture PATH layouts, no version is ever really upgraded in a test — the
+"restarted onto vX (was vY)" note wording, install-drift detection and its
+per-surface hints, and the `resolveDaemonEntry` fallback table. The genuine
+`npm i -g` + opencode-cache-refresh round trip is inspected, not
+live-tested.
 
 ## Configuration
 
@@ -240,6 +595,14 @@ companion to the main plugin, which is unchanged). Inside the opencode TUI:
   palette — is open, so Esc keeps cancelling the dialog instead of
   closing the panel underneath it.
 
+The panel surfaces two kinds of operational notes inline (issue #39): a
+`daemon restarted (onto vX)` line after the daemon restarts underneath the
+session (event history is re-synced automatically), and — because opencode
+never hot-reloads plugins — a `plugin updated — restart opencode to pick
+up vX` hint whenever the PATH `load-lock` install is newer than the copy
+this session is running. See "Plugin in-memory staleness" under
+[Update lifecycle](#update-lifecycle).
+
 The open command deliberately ships with **no global key binding** (issue
 #28). Never bind unmodified single letters or letter sequences (the old
 `gl`) at global scope: while the keymap engine waits for the next key of a
@@ -697,9 +1060,10 @@ unless you want the grants in your real profile):
 #    GOTCHA 2: the machine's real daemon was still v1.1.0 — a daemon
 #    started before v1.2.0 silently strips the unknown labelPrefix field
 #    (zod), so prefixed labels disappear without any error. Upgrade and
-#    restart: load-lock service stop && load-lock service start. This
-#    verification deliberately
-#    used its own daemon on a temp state dir.
+#    restart: load-lock service stop && load-lock service start (at
+#    verification time there was no `service restart` subcommand; it exists
+#    since issue #38 and is the shorter spelling today). This verification
+#    deliberately used its own daemon on a temp state dir.
 LOAD_LOCK_STATE_DIR=/tmp/ll-32-test node dist/cli/main.js service start
 
 # 1. install the grants (merge-only; prints exactly what it merged)
@@ -763,7 +1127,7 @@ The two gotchas that shaped the installer:
 2. **Label prefixes need a current daemon on the host.** A daemon
    started before v1.2.0 strips the unknown `labelPrefix` field silently
    (zod); the dashboard shows the bare label with no error anywhere.
-   `load-lock service stop && load-lock service start` after upgrading.
+   `load-lock service restart` after upgrading.
 
 What was NOT verified: omac's macOS seatbelt path (same profile schema,
 per omac's docs, but the verification machine is Linux) and omac's agent
@@ -942,3 +1306,25 @@ Caveats to watch for (unverified expectations):
   `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.
+
+## Releasing (maintainers)
+
+Publishing is automated: publishing a GitHub Release runs
+`.github/workflows/publish.yml` (npm Trusted Publishing; read its comments
+before changing the flow). The release commit itself is manual:
+
+1. Bump `version` in `package.json` (and `package-lock.json`), e.g.
+   `npm version 1.6.0 --no-git-tag-version`.
+2. Sync every pinned `@aron98/load-lock@<version>` to it:
+   `npm run check-pins -- --write` (alias for
+   `node scripts/check-pins.mjs --write`), then `npm run check-pins` must
+   print `pins ok`. Commit the bump and the pin updates together.
+3. Merge, then publish a GitHub Release tagged `v<version>`.
+
+Pinned files (the skill's npx fallback, ACE `ace/mcp/mcp.json` and
+`ace/opencode/package.json`, the Claude Code plugin's `plugin.json` and
+launcher) are declared in the
+`PINNED` list at the top of `scripts/check-pins.mjs`; add an entry whenever
+a new artifact pins a version. CI (`pins` job in `ci.yml`) fails on any
+pin that differs from `package.json`, on a declared file that is missing,
+and on a declared file that no longer contains a pin.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aron98/load-lock",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Machine-wide counting semaphore coordinating resource-intensive work across parallel coding agents (OpenCode, Codex CLI, Claude Code, ...)",
   "type": "module",
   "license": "MIT",
@@ -88,7 +88,8 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "test": "tsc -p tsconfig.json && node --test dist/test/*.test.js",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "check-pins": "node scripts/check-pins.mjs"
   },
   "engines": {
     "node": ">=20"

package/skills/load-lock/SKILL.md

@@ -1,3 +1,17 @@
+---
+name: load-lock
+description: >-
+  Teach parallel AI coding agents sharing one machine to take turns on heavy
+  work such as full builds and test suites. Agents acquire a machine-wide
+  permit before resource-intensive local work, keep doing light work while
+  queued FIFO, sleep honestly with bounded waits instead of polling, and
+  release the permit when done. Use when several agents on one machine risk
+  overloading it by starting heavy work in the same minute. If load-lock is
+  not installed, this skill runs it via `npx -y @aron98/load-lock@1.6.0`
+  (downloads the pinned npm package), and load-lock keeps its shared state in
+  ~/.local/state/load-lock (a small per-user daemon started on first use).
+---
+
 # load-lock: machine-wide heavy-work coordination
 
 All coding agents on this machine (any harness, any repo/worktree) share one
@@ -5,6 +19,54 @@ small budget of heavy-work permits. Before resource-intensive local work, a
 polite agent acquires a permit; everyone else keeps doing light work until an
 offer arrives.
 
+## How to call load-lock
+
+Use the first of these that works; they all talk to the same daemon:
+
+1. **load-lock MCP tools** (`acquire`, `wait_for_turn`, `run_with_permit`,
+   ...), if your harness lists them. The rest of this skill names them.
+2. **`load-lock` on PATH**: check with `load-lock version`.
+3. **Pinned npx**: `npx -y @aron98/load-lock@1.6.0 <command>` (Node >= 20).
+   It downloads that exact npm package once into the npx cache. Below,
+   read `load-lock` as this whole prefix. `npm install -g @aron98/load-lock`
+   makes it permanent.
+
+The first call starts the daemon on its own (shared state in
+`~/.local/state/load-lock`, or `$XDG_STATE_HOME/load-lock`); you never start
+it yourself.
+
+### CLI-only use (no MCP tools)
+
+`load-lock help` lists every command. The safest flow is `load-lock run`,
+which acquires a permit, runs the command, and releases it when the command
+exits (success or failure):
+
+```sh
+load-lock run --reason "full test suite" --op-key test/all -- npm test
+```
+
+- Exit code **68** with `queued at position N (request <id>)` means you are
+  not allowed to start yet. Keep doing light work. Out of light work? Sleep
+  honestly with `load-lock wait --id <request-id> --timeout 600000`: it
+  wakes you on your turn, claims the offer, and prints a `permit_token`.
+  Then `load-lock run --permit <permit_token> -- npm test`. A `wait` that
+  exits 68 again (still queued) is a checkpoint: call it again.
+- No longer need a queued request: `load-lock cancel --id <request-id>`.
+  Your own offers, queue entries and paused requests: `load-lock pending`.
+
+**Identity.** The daemon routes offers and `pending` per agent. The CLI
+derives your agent id from your harness session (Claude Code and OpenCode
+session env vars; on Linux, otherwise your harness process), so every call
+from one session counts as one agent, and other sessions are other agents.
+If `pending` does not show a request you made, pin the id yourself: set
+`LOAD_LOCK_AGENT=<unique-name>` (or pass `--agent <unique-name>`) on every
+call.
+
+Skill-only use has no idle wakeup (nothing tells you an offer arrived while
+you sit idle; use `load-lock wait`) and no policy reminder after context
+compaction. To get both, install the harness integration once:
+`load-lock setup` (or `load-lock install --harness <name>`).
+
 ## When to use it
 
 **Heavy** (acquire first): full builds, `cargo build`/`npm run build`, whole