@aron98/load-lock 1.4.0 → 1.6.0

package/dist/test/update.test.js

@@ -9,7 +9,7 @@
  *  - `service stop` waits bounded, escalates to SIGKILL, verifies the
  *    socket is free, and reports honestly
  *  - `service start` refusals name the conflicting pid
- *  - `doctor` reports installed copies and warns on drift
+ *  - `doctor` reports installed copies (incl. npx-cache, #57) and warns on drift
  *
  * Modeled after daemon.test.ts: real daemons over real sockets in temp
  * state dirs (LL_TEST_TMP / $TMPDIR/opencode — never the user's real dir).
@@ -453,3 +453,35 @@ test("doctor: reports installed copies, versions, daemon skew, and copy drift",
         rmSync(fakePkg, { recursive: true, force: true });
     }
 });
+test("doctor: lists a planted npx-cache copy (issue #57)", async () => {
+    const d = await startDaemon();
+    const home = mkdtempSync(join(TMP_BASE, "ll-npxhome-"));
+    try {
+        // npx layout under the default npm cache: ~/.npm/_npx/<hash>/node_modules/@aron98/load-lock
+        const npxCopy = join(home, ".npm", "_npx", "0123abcd4567ef89", "node_modules", "@aron98", "load-lock");
+        mkdirSync(npxCopy, { recursive: true });
+        writeFileSync(join(npxCopy, "package.json"), JSON.stringify({ name: "@aron98/load-lock", version: "0.4.2" }));
+        // A foreign npx entry is ignored.
+        const foreign = join(home, ".npm", "_npx", "ffff", "node_modules", "@aron98", "load-lock");
+        mkdirSync(foreign, { recursive: true });
+        writeFileSync(join(foreign, "package.json"), JSON.stringify({ name: "something-else", version: "1.0.0" }));
+        const env = { ...d.env, HOME: home };
+        // npm sets npm_config_cache for scripts it runs (`npm test`); the test
+        // must resolve the planted temp HOME's default cache, never the real one.
+        delete env.npm_config_cache;
+        delete env.NPM_CONFIG_CACHE;
+        const r = await runCliEnv(env, ["doctor", "--json"]);
+        assert.equal(r.code, 0, `stderr: ${r.stderr}`);
+        const report = JSON.parse(r.stdout);
+        const copies = report.copies;
+        const npx = copies.filter((c) => c.source === "npx-cache");
+        assert.equal(npx.length, 1, `exactly the planted npx copy: ${JSON.stringify(copies)}`);
+        assert.equal(npx[0].version, "0.4.2");
+        assert.equal(npx[0].path, npxCopy);
+        assert.ok(report.warnings.some((w) => w.includes("multiple load-lock versions") && w.includes("npx-cache=0.4.2")), `drift warning names the npx copy: ${JSON.stringify(report.warnings)}`);
+    }
+    finally {
+        await d.stop();
+        rmSync(home, { recursive: true, force: true });
+    }
+});

package/docs/ADAPTERS.md

@@ -52,8 +52,8 @@ adapter does — see `src/adapters/opencode/plugin.ts` as the worked example):
 ## Tier 2 — hooks + MCP
 
 For harnesses with lifecycle hooks but no in-process API (Claude Code and
-Codex CLI use this): keep the stock MCP server (`load-lock-mcp` binary, or
-`node .../dist/mcp/main.js`) for tools, and add hook handlers that shell out
+Codex CLI use this): keep the stock MCP server (`load-lock-mcp` binary,
+`load-lock mcp`, or `node .../dist/mcp/main.js`) for tools, and add hook handlers that shell out
 to the CLI:
 
 - `load-lock hook <harness> session-start` → prints `POLICY_BRIEF` +
@@ -96,6 +96,7 @@ normally touches:
 | `heartbeat {agentId}` | keep untracked leases alive |
 | `watch {agentId\|*}` / `events {sinceEventId, agentId?}` | push/pull event streams (durable ids) |
 | `offers_for_cwd {cwd}` | for hook scripts without session identity |
+| `hook_once {harness, sessionId, event, occurrence?, ttlMs?, hold?}` | hook dedupe: `{first}` is true only for the first caller per key; keys expire (TTL, default 60s) or, with `hold`, live as long as the connection; in-memory only |
 
 ## Lifecycle contract (the part that must not be improvised)
 

package/docs/AGENT_GUIDE.md

@@ -6,8 +6,42 @@ wide capacity budget. Before resource-intensive work, acquire a permit. The
 whole thing is cooperative: you decide what is heavy; the budget only works
 if everyone participates.
 
-This guide is also available as `load-lock agent-guide` and as a skill in
-supported harnesses.
+This guide is also available as the `agent_guide` MCP tool, as
+`load-lock agent-guide`, and as a skill in supported harnesses.
+
+## 0. How to reach load-lock
+
+Use the first of these that works; they all talk to the same daemon:
+
+1. **load-lock tools** in your harness (MCP tools, or `load_lock_*` in
+   OpenCode). The rest of this guide names the tools.
+2. **`load-lock` on PATH** (check with `load-lock version`).
+3. **Pinned npx**: `npx -y @aron98/load-lock@<version> <command>`, with the
+   version the load-lock skill pins (Node >= 20). Read `load-lock` below as
+   this whole prefix.
+
+The first call starts the shared daemon; you never start it yourself.
+
+**CLI only (skill-only install, no tools).** Prefer `load-lock run`: it
+acquires, runs the command, and releases when it exits, success or failure:
+
+```sh
+load-lock run --reason "full test suite" --op-key test/all -- npm test
+```
+
+Exit code **68** means "not granted yet" (queued, with the request id in
+the message): don't start the work. Keep doing light work; when you run out,
+`load-lock wait --id <request-id>` sleeps until your turn, claims the offer
+and prints a `permit_token` for `load-lock run --permit <permit_token> -- <cmd>`.
+A `wait` that exits 68 again is a checkpoint: call it again. Your own
+requests and offers: `load-lock pending`.
+
+Your agent id is derived from your harness session, so all calls from one
+session count as one agent. If `pending` doesn't show a request you made,
+pin the id yourself with `LOAD_LOCK_AGENT=<unique-name>` (or `--agent`) on
+every call. Without tools nothing wakes you while you sit idle and nothing
+re-teaches the policy after context compaction; `load-lock setup` shows how
+to add the harness integration that does.
 
 ## 1. Deciding heavy vs light
 
@@ -219,3 +253,15 @@ When you hold the permit, you own a share of the machine — bound your own
 work too: prefer e.g. `cargo test -j 2` or a bounded test-worker count over
 unbounded parallelism, and publish what you did via
 `configure(... guidance ...)` notes if it should become convention.
+
+## 7. Keeping load-lock itself current
+
+If load-lock tells you its adapter copy is newer than the installed CLI
+(`load-lock: this load-lock adapter copy (vX) is newer than the installed
+CLI (vY). Run \`load-lock update\` ...`), run it **as an ordinary command**
+(CLI: `load-lock update`; MCP/plugin: spawn the CLI or tell the user) —
+never try to install anything behind the notice; it is notify-only.
+`load-lock update --check` is the safe dry run: exit 0 = up to date,
+1 = update available (or this copy cannot self-apply it — repo checkouts
+and opencode-managed copies are refused honestly), 70 = failure. A
+successful apply restarts the service itself; you do not need to.

package/docs/ARCHITECTURE.md

@@ -99,8 +99,13 @@ wrong-state error), and a failed start kills the process group immediately.
 Background execution is handled honestly: the helper returns after *the whole
 process group* finishes, never merely when a shell returns a task id.
 
-**Identity.** Per-agent identity comes from the harness (OpenCode session ID)
-or an explicit `agent_id` argument; every entry also records an agent label,
+**Identity.** Per-agent identity is derived from the harness session
+(issues #49/#50): an explicit `agent_id` / `--agent` / `LOAD_LOCK_AGENT`
+wins, else a harness session id (OpenCode `sessionID`, Claude Code
+`CLAUDE_CODE_SESSION_ID`, hook `session_id`), else the stable harness
+ancestor process on Linux, so every wiring of one session (CLI, MCP
+server, hooks) acts as one agent (details in
+[COMPATIBILITY.md](COMPATIBILITY.md#session-identity-per-harness)); every entry also records an agent label,
 cwd, op key (for idempotent duplicate suppression), and reason. Idempotency:
 a duplicate `acquire` from the same agent for the same pending op key returns
 the existing request rather than a second one; multiple distinct ops per
@@ -118,10 +123,86 @@ same request ids (idempotent re-acquire keeps working), entries offered at
 crash time restart as queued and are re-offered with fresh tokens — so a
 restart no longer silently drops a queue position. The daemon auto-spawns on
 the next client connection, and a *self-ordered* restart (version handshake:
-a newer client than the daemon) respawns with the same argv after persisting
-state — see the update lifecycle in
+a newer client than the daemon) persists state and respawns onto the newer
+client's copy (#53; same argv when that copy can't be validated) — see the update lifecycle in
 [OPERATIONS.md](OPERATIONS.md#update-lifecycle).
 
+**Persisted format compatibility (issue #51).** Several runtime copies may
+share one state dir, so a downgrade is possible: a newer daemon dies and an
+older client starts its older copy, which must then load files the newer one
+wrote. `config.json` carries a top-level `formatVersion` (absent = 0, the
+pre-versioning format); the journal stays a bare JSON array (what every
+released daemon reads) with `formatVersion` stamped on each entry. The
+promise, in both directions:
+
+- Format changes are **additive**. A reader never rejects a file because its
+  `formatVersion` is higher than its own; it uses what it understands.
+- Unknown fields are **never dropped destructively**: top-level and
+  `config`/pool/guidance fields of `config.json` survive a rewrite (e.g. a
+  `configure`), and unknown fields on a journal entry are written back while
+  that entry lives. Each writer stamps its *own* `formatVersion`, so readers
+  must treat fields from a newer format as possibly stale.
+- Unknown journal entry kinds (a `state` this version doesn't know) and
+  malformed entries are **skipped**, never fatal; the count is reported in the
+  `daemon_recovered` event. A held entry with an unknown `phase` is kept as an
+  untracked permit with a fresh lease (capacity stays accounted; the lease
+  reclaims it if nobody heartbeats).
+- An incompatible change would use a **new file name**, never reinterpret
+  `config.json` / `journal.json`.
+
+## Three layers: daemon, runtime copies, harness wiring
+
+load-lock reaches a machine through many entry points (a skill, an MCP
+registration, a harness plugin, ACE, `npm i -g` + `load-lock install`), and
+users mix them across harnesses and over time. The design rule (issue #47):
+**any combination, installed in any order, gives one working budget.** It
+holds because load-lock is split into three layers with different
+multiplicity:
+
+| Layer | Per machine | What it is | Rule |
+| --- | --- | --- | --- |
+| **Daemon** | exactly 1 (one socket, one state dir) | the long-lived process that owns all state, started on demand by whichever client connects first (`src/shared/client.ts`) | the newest copy runs it |
+| **Runtime copies** | many | installed copies of the npm package: global npm/bun, the npx cache, OpenCode's plugin cache, a git checkout; the Claude Code plugin's launcher picks one of them | copies interoperate in both directions; none "owns" the daemon |
+| **Harness wiring** | ideally 1 per harness, possibly several | MCP registrations, hooks, policy text, skill copies, written by a plugin, ACE, `load-lock install` or by hand | duplicates are **harmless**, not merely discouraged |
+
+**Duplicates are harmless.** Each overlap is defused where the singleton
+lives, not by hoping the user cleans up:
+
+- *Hooks*: two wirings of the same hook (loose + plugin, two plugins, ACE)
+  both fire, but the daemon's `hook_once` lets only the first act — one
+  policy injection, one Stop continuation, one idle watcher per session
+  (see "Duplicate hook wiring is harmless" below).
+- *MCP servers*: two registrations in one session (e.g. ACE's `mcp.json` +
+  the plugin's bundled server) are two processes with the **same**
+  session-derived identity (see Identity above), so an `acquire` through
+  one shows up in `pending` through the other. Both talk to the one daemon.
+- *Skill copies*: identical text; the skill only tells the agent how to
+  reach the daemon.
+
+Housekeeping is still offered: `load-lock setup` lists every integration
+per harness and, with `--yes`, converges each harness to one wiring at its
+highest rung (see [OPERATIONS.md](OPERATIONS.md#load-lock-setup-what-is-installed-where)).
+Correctness never depends on running it.
+
+**Compatibility promise between copies.** Because several copies of
+different versions talk to one daemon and one state dir:
+
+- every client envelope carries its version and package root; a strictly
+  newer client makes the daemon persist state and respawn onto that
+  client's copy (#52/#53, see "Runtime copies and the restart hint"
+  below), with one attempt per version;
+- the persisted files are versioned and additive in both directions, so
+  an older daemon started after a newer one died reads the newer files
+  safely (#51, "Persisted format compatibility" above);
+- newer client features degrade against an older daemon instead of
+  failing: hooks without `hook_once` act as before, `wait_for_completion`
+  falls back to an events-based poll.
+
+The **install ladder** built on top of this (skill → MCP server → harness
+plugin, plus `npm i -g` + `load-lock install`) is described in
+[OPERATIONS.md](OPERATIONS.md#the-install-ladder); which rung each harness
+reaches is in [COMPATIBILITY.md](COMPATIBILITY.md#rung-per-harness).
+
 ## Notification honesty
 
 A critical constraint discovered by research: **no harness reliably pushes
@@ -168,7 +249,8 @@ mechanisms, and labels exactly which apply per harness:
      calls `ctx.session.synthetic(...)`, delivering the offer (with token)
      to an idle session at its next execution boundary — it never
      interrupts an in-flight shell command.
-   - Claude Code (contract-tested): a `Stop` hook checks for cwd-matching
+   - Claude Code (live-verified in Docker with the loose install; the
+     plugin's hooks are not yet live-verified, #63): a `Stop` hook checks for cwd-matching
      offers and continues the session with a claim instruction; an async
      `await-offer` watcher with `asyncRewake: true` wakes idle sessions.
    - Codex CLI (live-verified in Docker): `Stop` hook with `decision: "block"`
@@ -191,8 +273,10 @@ and restored after context compaction:
 - **OpenCode**: plugin `context` hook injects the brief on every model call
   (compaction-proof, live-verified), plus a registered skill with the full
   guide.
-- **Claude Code**: `SessionStart` hook (matchers include `compact`) +
-  `~/.claude/CLAUDE.md` section + skill.
+- **Claude Code**: `SessionStart` hook (re-fires after `compact`), from
+  either the `load-lock-plugin` plugin or the loose install; the loose
+  install adds a `~/.claude/CLAUDE.md` section + skill, the plugin ships
+  neither (full guide via the `agent_guide` MCP tool).
 - **Codex CLI**: `SessionStart` hook (matcher `compact`) + `SubagentStart`
   hook + `~/.codex/AGENTS.md` section (hooks require the interactive
   hook-trust review once; live-verified in Docker).
@@ -203,6 +287,21 @@ Policy is short (one brief, no repeated reminders), reinforced by tool
 names/descriptions, and never interrupts ordinary work with approval
 prompts.
 
+**Duplicate hook wiring is harmless (issue #54).** Loose hooks, a plugin
+and ACE wiring may all be installed at once, so one harness event can fire
+the same load-lock hook several times. The daemon is the singleton, so it
+drops duplicates: each hook handler first calls `hook_once` with the key
+`(harness, session_id, event, occurrence)`; only the first caller acts, the
+rest exit 0 silently. The occurrence separates legitimate repeats:
+SessionStart uses its `source` (a later `compact` re-injects the policy),
+Stop hooks (Claude Code, Codex, Cursor) use the offer token being delivered
+(each offer becomes at most one continuation per session). Keys expire on
+their own (default 60s) and are never persisted; the `await-offer` watcher
+instead *holds* its key for its connection's lifetime, so a session has at
+most one live watcher and the key frees when the watcher exits. Hooks fail
+open: no session id, a daemon without `hook_once` (`unknown method`), or
+any error means the hook acts exactly as before.
+
 ## Failure modes covered
 
 | Failure | Behavior |
@@ -217,6 +316,22 @@ prompts.
 | Config change while offers outstanding | Capacity increase admits queued agents immediately; capacity decrease lets holders finish and delays new admissions; outstanding offers keep their reservations |
 | Duplicate claims/releases | Idempotent or precise `stale_token`/`offer_expired` errors, never double effects |
 
+### Runtime copies and the restart hint
+
+`daemon.json` records the daemon's package root and version, and
+`runtimes.json` the copies seen via the handshake (#52). When a strictly
+newer client connects, the daemon respawns onto that client's copy (#53)
+if the envelope's `clientRoot` names a `@aron98/load-lock` package whose
+on-disk version equals the claimed `clientVersion` and which ships
+`dist/core/daemon-main.js`; otherwise it reruns its own argv. The
+`LOAD_LOCK_RESTARTED_FOR` marker keeps one restart per version either way.
+
+Security: the hint arrives over the daemon's socket, which only the same
+user can reach. Following it grants no privilege the client did not
+already have — that client could run the same file itself. The checks
+exist to avoid respawning onto garbage (wrong package, mismatched version,
+missing entry), not as a trust boundary.
+
 ## Extension points
 
 The protocol already carries weights (a request may ask for >1 units of

package/docs/COMPATIBILITY.md

@@ -46,6 +46,30 @@ Status labels mean exactly this:
 | **omac** (agent sandbox; verified with 0.11.0) | N/A — omac is a sandbox runtime, not a harness: the agent inside it uses whichever harness adapter applies (OpenCode, Claude Code, …) | via the inner harness | via the inner harness | via the inner harness | via the inner harness | Full for the sandbox grants: `load-lock uninstall --harness omac` removes exactly the entries install added (match-own-entries, empty sections pruned) | **Sandbox-profile grants installed + live-verified** (`install --harness omac`: `filesystem.allow_unix_dir` += state dir, `filesystem.read` += package tree when needed, `environment.allow_vars` += `LOAD_LOCK_*`) |
 | **Aider** | **No MCP support** | CONVENTIONS.md / `.aider.conf.yml` | Read each run | N/A | N/A | CLI-only: same-shell `load-lock acquire ... && cmd; load-lock release ...` (manual) | Proposed (manual CLI tier) |
 
+## Rung per harness
+
+The install ladder (OPERATIONS.md, "The install ladder") has rungs 0 = skill
+only, 1 = MCP server, 2 = harness plugin, plus the loose
+`npm i -g` + `load-lock install --harness <h>` wiring. **Rung 0 works
+everywhere** an agent can read the skill and run a shell: it only needs
+the CLI (on PATH or through the skill's pinned `npx`), so it is not
+repeated per row. `load-lock setup` reports the rung it finds per harness
+as `plugin`, `loose`, `MCP only`, `skill only` or `not installed`.
+
+| Harness | MCP server (1) | Plugin (2) | Loose `install` | Highest rung |
+| --- | --- | --- | --- | --- |
+| **OpenCode** | generic stdio registration works; the plugin's native `load_lock_*` tools are better | npm plugin `@aron98/load-lock` (also listed on ACE via `ace/opencode/`) — live-verified | `install --harness opencode` registers that same npm plugin | **plugin** |
+| **Claude Code** | ACE `ace/mcp` or a manual stdio registration | `load-lock-plugin` from this repo's marketplace — contract-tested, passes `claude plugin validate --strict`; not yet live-verified as a plugin (pending #63); ACE's skills-dir install unverified (#63/#66) | `install --harness claude-code`: MCP + hooks + `CLAUDE.md` section + skill — live-verified in Docker | **plugin** (loose gives the same capability) |
+| **Codex CLI** | `[mcp_servers]` entry in `~/.codex/config.toml` | none shipped | `install --harness codex`: MCP + hooks + `AGENTS.md` section — live-verified in Docker | **loose** |
+| **Cursor** | project `.cursor/mcp.json` | none shipped | `install --harness cursor --project <dir>`: MCP + stop hook + rule — contract-tested | **loose** |
+| **Gemini CLI, Copilot CLI, Cline, Roo Code, Goose** | the harness's MCP config | none shipped | `install --harness <h>`: MCP + instructions/rule file, no hooks — config-tested | **loose** (rung 1 plus a policy file; no idle wakeup) |
+| **omac** | n/a (sandbox, not a harness) | — | `install --harness omac`: sandbox-profile grants — live-verified | the inner harness's rung |
+| **Aider** | no MCP support | none | none | **0** (CLI only) |
+
+"Highest rung" is what `load-lock setup --yes` converges a harness to once
+it has some load-lock wiring (OPERATIONS.md, "Converging"). Mixing rungs in
+one harness is safe (ARCHITECTURE.md, "Three layers").
+
 ## How each integration tier works
 
 ### Tier 1 — OpenCode (native plugin, live-verified)
@@ -73,6 +97,23 @@ tool round-trip (acquire → queued → wakeup → claim → release), execution
 boundary delivery without interrupting a running `sleep`, skill visible,
 and graceful handling of a deliberately missed offer (paused → cancel).
 
+#### ACE listing (opencode, issue #79)
+
+ACE ([TNG/ace](https://github.com/TNG/ace)) cannot detect the root
+`package.json` as an OpenCode plugin, because its entry point is the
+gitignored `dist/`. The OpenCode listing therefore comes from the dedicated
+folder `ace/opencode/`. It is a thin pointer: `index.js` re-exports
+`@aron98/load-lock`, and `package.json` (`load-lock-opencode`, private) pins
+that dependency to the release version through `scripts/check-pins.mjs`.
+ACE finds the folder through its npm-package heuristic (a `main` that exists
+in the git tree, plus `opencode` in the name or keywords). ACE marks every
+such detection as **"verify before registering"**, so that note is expected.
+`src/test/ace-opencode.test.ts` mirrors the heuristic (TNG/ace@b703410) and
+asserts that this repo yields exactly one OpenCode plugin, at `ace/opencode`.
+Users install the published package as usual (a `plugins` entry
+`@aron98/load-lock` in `opencode.json`), not the folder itself. The
+end-to-end ACE install is not yet live-verified (#66).
+
 #### Multiple copies of load-lock (opencode)
 
 `install --harness opencode` registers the **bare package name** in
@@ -89,15 +130,37 @@ Which copy is authoritative for what:
   (it refreshes the cache entry); you cannot reliably update it by hand.
 - **CLI commands** (`load-lock status`, `service`, `doctor`, …) — the copy on
   PATH (typically a global install via npm/bun). Update it with your usual
-  global install command.
+  global install command, or `load-lock update` (since #38), which detects
+  the package manager from the copy's location and refuses to touch copies
+  it does not manage: it will not "update" the opencode cache copy (opencode
+  owns it) nor a git checkout (your git workflow owns it), and it restarts
+  the service after a successful apply.
 - **The daemon's code** — whichever copy spawned it (usually the CLI copy,
   since auto-spawn and `service start` run from the CLI client code). The
   version handshake makes a daemon self-restart onto updated code when a
-  newer client contacts it — but the respawn reuses the daemon's original
-  argv, so it only picks up an update when its spawning copy was updated
-  *in place* (the normal global-upgrade case). A daemon spawned from a
-  different copy than the one you updated keeps running the old code until
-  `load-lock service stop` + any command re-spawns it from the new one.
+  newer client contacts it. Since #53 the respawn moves onto the newer
+  client's own copy (validated from its `clientRoot` hint), so a daemon
+  spawned from a different copy than the one you updated follows the
+  newer client. Clients older than #52 send no `clientRoot`; for them the
+  respawn reuses the daemon's original argv and only picks up an in-place
+  update of its spawning copy — `load-lock service restart` (since #38)
+  re-spawns it from the current CLI copy.
+- **npx-launched copies** (since #57) — skill / ACE / pinned MCP entries run
+  `npx -y @aron98/load-lock@<pin>`, which installs a copy under the npm
+  cache at `~/.npm/_npx/<hash>/node_modules/@aron98/load-lock/` (or under
+  `$npm_config_cache/_npx`; `%LocalAppData%\npm-cache\_npx` on Windows).
+  `doctor` lists these as `npx-cache`. They are owned by the pin that
+  launches them: `load-lock update` refuses to touch them and points at
+  bumping the pinned version (or the ACE artifact) instead.
+
+The mirror drift — a *newer* adapter copy (opencode refreshed its cache)
+with an *older* CLI on PATH — surfaces at adapter init (issue #38): the
+plugin/MCP server prints one clear notice naming `load-lock update` and
+embeds it in the injected context/instructions. Notify only, never
+auto-install. See
+[OPERATIONS.md](OPERATIONS.md#adapter-init-drift-notice) for the
+in-memory-staleness limitation (a running session keeps the old adapter
+code until the harness restarts).
 
 `load-lock doctor` lists every copy it can find (PATH-resolved CLI, this
 running copy, opencode cache copies) with versions and warns when they
@@ -121,6 +184,51 @@ observed live on this machine before the feature existed.
   idle Claude. The token is deliberately NOT in that message (stderr may be
   shown); the agent claims via `pending`/`claim`.
 
+**Tool names depend on the wiring.** A loose install (`load-lock install`)
+registers the MCP server as `load-lock`, so Claude Code exposes
+`mcp__load-lock__<tool>`. A plugin-bundled server is namespaced by plugin
+and server key, `mcp__plugin_<plugin>_<server>__<tool>` (per the Claude Code
+MCP docs), e.g. `mcp__plugin_load-lock-plugin_load-lock__claim` for the
+`load-lock-plugin` Claude Code plugin. Every text
+load-lock injects (policy brief, hook claim/wakeup messages, CLAUDE.md /
+AGENTS.md sections, skill) therefore names tools neutrally ("the load-lock
+`claim` tool") instead of hard-coding a prefix.
+
+**Claude Code plugin** (`/plugin install load-lock-plugin@load-lock`, see
+OPERATIONS "Claude Code plugin"): the same MCP server and hooks, bundled
+and run through the dependency-free launcher; no skill, the detailed guide
+comes from the `agent_guide` tool. Its manifest, hooks file and
+marketplace entry are contract-tested (`src/test/plugin.test.ts`) and pass
+`claude plugin validate --strict` (Claude Code 2.1.312), and the hook
+commands are tested the way the plugin invokes them. Hooks use shell form
+(one `command` string, `${CLAUDE_PLUGIN_ROOT}` quoted; #63).
+
+**Plugin live verification** (#63; Claude Code 2.1.312, 2026-10-29, Linux
+host): a real session with a throwaway `CLAUDE_CONFIG_DIR` and `HOME`,
+load-lock isolated by `LOAD_LOCK_STATE_DIR` / `LOAD_LOCK_SOCKET`, the
+plugin installed from this repo's marketplace with `claude plugin
+marketplace add <checkout>` + `claude plugin install
+load-lock-plugin@load-lock`, and the checkout's CLI first on `PATH`.
+Headless `claude -p` and an interactive pty session. Status: **plugin
+live-verified** for the checks marked observed:
+
+| Check | Result |
+| --- | --- |
+| Shell-form hooks run, launcher takes the PATH branch | Observed (`load-lock launcher: path 1.5.0` on every hook) |
+| SessionStart policy at startup | Observed (model quoted the isolated daemon's `load-lock now:` line) |
+| SessionStart policy after `/compact` | Observed (`SessionStart:compact` hook ran; model quoted the fresh `1/1` line where the startup brief said `0/1`) |
+| MCP tools named `mcp__plugin_load-lock-plugin_load-lock__<tool>` | Observed (all 19 tools listed under that prefix; server `plugin:load-lock-plugin:load-lock` connected) |
+| `agent_guide` tool | Observed (called; returned the guide) |
+| Stop offer continuation | Observed (headless: Stop hook returned `decision: block` with the offer token; model claimed and released) |
+| `await-offer` idle wakeup (`async` + `asyncRewake`) | Observed (interactive: session idle ~18s, offer arrived, the watcher's exit 2 woke the session with a task notification; model ran `pending` → `claim` → `release`) |
+| Daemon started by the plugin | Observed (fresh state dir; the daemon came up during session start with `CLAUDE_PLUGIN_ROOT` in its environment and `daemon.json` naming the PATH copy). Which plugin component spawned it first (hook or MCP server) was not determined. |
+| Session-derived identity | Observed for the plugin MCP server (requests carried agent `claude-code:<session id>` matching the session's transcript). That hooks read the same `session_id` from stdin was not separately inspected. |
+| Loose install + plugin together | Not observed (not run; covered by the #54 dedupe tests only) |
+| Launcher npx / known-copy branches inside a live session | Not observed (only the PATH branch ran) |
+
+The TUI labels the asyncRewake wake as "Stop hook blocking error from
+command SessionStart:startup"; the message text is the watcher's.
+
 Contract tests cover all hook stdin/stdout shapes against the documented
 harness contracts. Claude Code is additionally **live-verified** (in Docker,
 via `docker/run-claude-verify.sh` against the real `claude` CLI): SessionStart
@@ -253,7 +361,7 @@ without a dedicated installer.
 Idle policy: these harnesses get no push notifications, so the PRIMARY
 idle mechanism is the MCP `wait_for_turn` tool — a bounded, honest sleep
 until it is the caller's turn. Queued agents call
-`mcp__load-lock__wait_for_turn` (optionally with `timeout_ms`, default
+the load-lock `wait_for_turn` tool (optionally with `timeout_ms`, default
 600000, capped by the machine's `maxTurnWaitMs` config) and get a
 structured result on every path: `granted` (the offer was auto-claimed —
 `permit_token` included), `still_queued` (timeout, with queue position
@@ -319,7 +427,7 @@ 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` **in-window** as a side panel (also opened by clicking the sidebar widget; deliberately **not** bound to any key — issue #28: the old `gl` sequence swallowed plain `g` typing, and the candidate `ctrl+g` is the host's `session.first` default) with pools, holder cards, offer claim-window countdowns, queue, paused, event feed, `inspect_machine`; home-footer `lock 1/1` indicator on the home screen plus a clickable, health-colored `load-lock 0/3` widget in the session sidebar; `x` force-release behind select + confirm. Implemented as the package's `./tui` companion plugin (main plugin unchanged). Live-verified: opencode 2.0.29 (panel render, palette/slash command, confirm-gated force-release) and opencode 2.0.32 in a real pty (sidebar widget render, click-to-open, in-window presentation, plain `g` reaches the composer, `ctrl+g` not intercepted by load-lock). | `load-lock dashboard` (alias `top`) |
-| **Claude Code** | None in-app — Claude Code has no plugin UI surface. The model can report status via the `load_lock_status` MCP tool at tool boundaries, and each `SessionStart` hook injects a one-line machine summary. | `load-lock dashboard` (any terminal) |
+| **Claude Code** | None in-app — load-lock ships no in-app view for Claude Code: `load-lock-plugin` bundles the MCP server + hooks only, and the loose install adds no UI either. 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`) |
@@ -334,14 +442,49 @@ reconnect, view-model shaping, frame rendering) is covered by
 
 ## Session identity per harness
 
+The daemon routes offers, `pending` and op-key duplicate suppression by agent
+id, so each harness session needs exactly one id, whichever wiring (CLI, MCP
+server, hook) made the call. The default identity of the CLI (issue #49) and
+of the MCP server (issue #50) comes from the shared resolver in
+`src/shared/identity.ts`, first match wins:
+
+1. explicit override: `--agent` (CLI), `agent_id` (MCP tools), or
+   `LOAD_LOCK_AGENT`;
+2. a harness session env var exported to the processes the harness spawns:
+   `CLAUDE_CODE_SESSION_ID` → `claude-code:<session_id>` (the same value hooks
+   receive as `session_id`; verified on Claude Code 2.1.x), and
+   `OPENCODE_SESSION_ID` → the bare `sessionID` (exported by OpenCode's bash
+   tool; verified on opencode 2.1.1). The bare id is exactly the native
+   plugin's agent id, so CLI calls from an OpenCode shell share the plugin's
+   identity;
+3. the stable harness ancestor process (Linux): walk up from the CLI's parent
+   past shells and launcher wrappers (`sh`/`bash`/`zsh`/…, `env`, `timeout`,
+   `npm`/`npx`, nested `load-lock`) to the first other ancestor, identified as
+   `proc:<pid>:<start time>` (pid-reuse safe via `/proc/<pid>/stat`), labelled
+   `<comm>:<pid>`. This covers harnesses without a verified env var (Codex,
+   Cursor, Gemini CLI, …), since one session = one long-lived harness process;
+4. otherwise (no harness ancestor, or no `/proc` — macOS/Windows without a
+   session env var) the legacy default: `cli:$USER@$HOSTNAME` for the CLI, a
+   random per-process `agt_…` id for the MCP server.
+
+So two MCP registrations in one session (plugin-bundled + standalone) share
+one id: an `acquire` through one shows in `pending` through the other, and
+both heartbeat the same id (idempotent). The CLI and the MCP server of one
+session share an id too when both see the same session env var or the same
+harness ancestor; whether a harness exports its session env var to MCP
+server processes is not verified for every harness.
+
+Labels stay human-readable: session-derived ids get a short holder label
+(`claude-code:ee690007`, `codex:12345`); explicit ids label themselves.
+
 | Harness | Identity | Notes |
 | --- | --- | --- |
-| OpenCode | plugin context `sessionID` (also MCP `_meta` when used) | automatic |
-| Claude Code | hooks get `session_id`; MCP tools take explicit `agent_id` | policy instructs agents to pass it |
-| Codex | hooks get `session_id`; MCP tools take explicit `agent_id` | same |
-| Cursor | hooks get `conversation_id` (no `cwd` — `workspace_roots[0]` identifies the request); MCP tools take explicit `agent_id` | same |
+| OpenCode | plugin context `sessionID` (also MCP `_meta` when used); CLI via `OPENCODE_SESSION_ID` (same id) | automatic |
+| Claude Code | hooks get `session_id`; CLI and MCP server via `CLAUDE_CODE_SESSION_ID`, else the harness ancestor; MCP tools also take explicit `agent_id` | automatic; explicit `agent_id` still wins |
+| Codex | hooks get `session_id`; CLI and MCP server via harness ancestor process; MCP tools also take explicit `agent_id` | same |
+| Cursor | hooks get `conversation_id` (no `cwd` — `workspace_roots[0]` identifies the request); CLI and MCP server via harness ancestor process; MCP tools also take explicit `agent_id` | same |
 | omac (sandbox) | inner harness identity + `LOAD_LOCK_LABEL_PREFIX=omac` | dashboard shows holders as `omac:<label>` |
-| Tier 3 | explicit `agent_id` argument | falls back to per-server-process id |
+| Tier 3 | explicit `agent_id` argument; CLI and MCP server via harness ancestor process | MCP falls back to a per-server-process id only when no session is found |
 
 ## Platform matrix