@aron98/load-lock 1.5.0 → 1.6.1

package/README.md

@@ -1,6 +1,18 @@
-# load-lock
-
-[![CI](https://github.com/aron98/load-lock/actions/workflows/ci.yml/badge.svg)](https://github.com/aron98/load-lock/actions/workflows/ci.yml)
+<h1 align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/banner.svg">
+    <img src="assets/banner.svg" width="640" alt="load-lock — machine-wide permits for parallel coding agents">
+  </picture>
+</h1>
+
+<p align="center">
+  <a href="https://github.com/aron98/load-lock/actions/workflows/ci.yml"><img src="https://github.com/aron98/load-lock/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://www.npmjs.com/package/@aron98/load-lock"><img src="https://img.shields.io/npm/v/@aron98/load-lock?color=%233fb950" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@aron98/load-lock"><img src="https://badgen.net/npm/dm/@aron98/load-lock?color=3fb950" alt="npm downloads"></a>
+  <a href="https://skills.sh/aron98/load-lock"><img src="https://skills.sh/b/aron98/load-lock" alt="skills.sh"></a>
+  <a href="https://github.com/aron98/load-lock/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="license MIT"></a>
+  <img src="https://img.shields.io/badge/node-%E2%89%A520-green" alt="node >= 20">
+</p>
 
 **A machine-wide heavy-work budget for parallel coding agents.**
 
@@ -21,6 +33,12 @@ agent A (OpenCode)        agent B (Codex)         agent C (Claude Code)
   release ✓                 release ✓               rejoin → offer → claim ✓
 ```
 
+Three agents, one budget — the queue drains FIFO while everyone keeps coding:
+
+<p align="center">
+  <img src="assets/demo.gif" width="640" alt="load-lock demo: three agents acquire permits, the queue drains FIFO, watched live via load-lock dashboard">
+</p>
+
 ## Features
 
 - **One budget for the whole machine** — every client of any harness shares
@@ -54,19 +72,45 @@ agent A (OpenCode)        agent B (Codex)         agent C (Claude Code)
 - **Resource-aware** — `inspect_machine` reports cgroup/container CPU and
   memory limits and current pressure; never assumes cores = capacity.
 
-## Quickstart
+## Install
+
+Pick a rung per harness. Each works on its own, a higher rung only adds
+capability, and mixing them is safe: one daemon, one budget, one identity
+per session, duplicate hooks dropped by the daemon.
+
+| Rung | Install | Agents get |
+| --- | --- | --- |
+| 0 — **skill** | the `load-lock` skill ([`skills/load-lock`](skills/load-lock/SKILL.md), or via ACE) | the full permit lifecycle through the CLI (on PATH, else pinned `npx`); no idle wakeup, no policy injection |
+| 1 — **MCP server** | a stdio server running `npx -y @aron98/load-lock@<version> mcp` (or the ACE `mcp` artifact) | tools, offers in every tool result, bounded `wait_for_turn` / `wait_for_completion` sleeps |
+| 2 — **plugin** | Claude Code `load-lock-plugin`, OpenCode npm plugin `@aron98/load-lock` | everything: tools, policy that survives compaction, offer wakeups |
+| — | `npm i -g` + `load-lock install --harness <h>` | the same as loose config; the route for harnesses without a plugin |
+
+Claude Code plugin (MCP server + hooks, no global install needed; the
+skill is separate):
+
+```text
+/plugin marketplace add aron98/load-lock
+/plugin install load-lock-plugin@load-lock
+```
+
+Global CLI + installer (any supported harness):
 
 ```sh
 npm install -g @aron98/load-lock
-load-lock install --harness opencode     # or claude-code | codex | gemini-cli |
+load-lock install --harness opencode     # or claude-code | codex | cursor | gemini-cli |
                                          # copilot-cli | cline | roo-code | goose |
                                          # omac (sandbox grants) | generic
+load-lock setup                          # what is installed where, per harness
+load-lock setup --yes                    # converge wired harnesses to their highest rung
 load-lock doctor
 ```
 
+Rung details and ACE: docs/OPERATIONS.md → "The install ladder"; which
+rung each harness reaches: docs/COMPATIBILITY.md → "Rung per harness".
+
 From then on, agents see the policy and tools automatically:
 OpenCode plugin (`load_lock_*` tools), Claude Code / Codex MCP tools
-(`mcp__load-lock__*`) plus session hooks. Any other MCP-capable harness can
+(named per the harness's MCP namespacing) plus session hooks. Any other MCP-capable harness can
 use the generic stdio server; plain shells use the CLI:
 
 ```sh
@@ -114,7 +158,7 @@ skills/         packaged skill
   restart semantics, notification honesty, lifecycle tradeoffs.
 - [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md) — per-harness capability
   matrix with implemented / contract-tested / proposed labels.
-- [docs/OPERATIONS.md](docs/OPERATIONS.md) — install, config,
+- [docs/OPERATIONS.md](docs/OPERATIONS.md) — install ladder, `setup`, ACE, config,
   troubleshooting, recovery, daemon lifecycle, sandbox bridging.
 - [docs/AGENT_GUIDE.md](docs/AGENT_GUIDE.md) — the playbook for agents.
 - [docs/ADAPTERS.md](docs/ADAPTERS.md) — how to write an adapter for a new
@@ -122,17 +166,21 @@ skills/         packaged skill
 
 ## Status
 
-- Core daemon/protocol/CLI: implemented, 68 automated tests passing
+- Core daemon/protocol/CLI: implemented, 253 automated tests passing
   (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 dashboard --once` render smoke test).
+  PID-reuse, subprocess survival, installer round-trips, multi-copy
+  restarts; dashboard tests cover view-model shaping, event-cursor resume
+  across a daemon restart, reconnect, and a `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).
-- Claude Code adapter: implemented, contract-tested against documented
-  hook JSON; not yet live-verified (harness not installed on the
-  verification machine).
+- Claude Code adapter: loose install (`load-lock install --harness
+  claude-code`) implemented and **live-verified** in Docker; the
+  `load-lock-plugin` plugin is **live-verified** in a real Claude Code
+  session (#63: policy at startup and after `/compact`, plugin tool names,
+  `agent_guide`, Stop offer continuation, `asyncRewake` idle wakeup). See
+  COMPATIBILITY.md for what was not observed.
 - Codex CLI adapter: implemented and **live-verified** end-to-end in
   Docker (interactive TUI via pty: policy injection, MCP round-trip,
   FIFO queueing behind a competing holder, Stop-hook decision-block

package/dist/cli/copies.d.ts

@@ -1,7 +1,7 @@
-export { enclosingPackage, opencodeCacheRoot } from "../shared/pkginfo.js";
+export { enclosingPackage, npxCacheRoot, opencodeCacheRoot } from "../shared/pkginfo.js";
 export interface InstalledCopy {
     /** Where this copy was found. */
-    source: "cli" | "path" | "opencode-cache";
+    source: "cli" | "path" | "opencode-cache" | "npx-cache";
     /** Path of the copy's package root (its package.json's directory). */
     path: string;
     /** Version string, or null when the package.json could not be read. */
@@ -16,5 +16,6 @@ export declare function thisCopy(): InstalledCopy | null;
  *    so a symlink to the running copy is recognized and not double-listed
  *    — a copy is only listed under "path" when it differs from "cli").
  *  - "opencode-cache": copies under opencode's private npm cache.
+ *  - "npx-cache": copies under npx's cache (`<npm cache>/_npx/<hash>/...`).
  */
 export declare function findInstalledCopies(platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): InstalledCopy[];

package/dist/cli/copies.js

@@ -3,7 +3,9 @@
  * of load-lock commonly coexist — the globally-installed CLI on PATH, and
  * the private copy opencode maintains under its npm cache (because
  * `install --harness opencode` registers the bare package name, opencode
- * installs and refreshes its own copy on its own schedule).
+ * installs and refreshes its own copy on its own schedule), and copies npx
+ * installs under its cache when skill / ACE / pinned MCP entries launch
+ * `npx -y @aron98/load-lock@<pin>` (issue #57).
  *
  * All scanning is best-effort: missing paths, unreadable files, and
  * unexpected layouts yield skipped entries or null versions — never a throw.
@@ -12,8 +14,8 @@ import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "n
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { isWindows } from "../shared/transport.js";
-import { enclosingPackage, opencodeCacheRoot, PKG_NAME } from "../shared/pkginfo.js";
-export { enclosingPackage, opencodeCacheRoot } from "../shared/pkginfo.js";
+import { enclosingPackage, npxCacheRoot, opencodeCacheRoot, PKG_NAME } from "../shared/pkginfo.js";
+export { enclosingPackage, npxCacheRoot, opencodeCacheRoot } from "../shared/pkginfo.js";
 /** The copy of load-lock this process runs from (its own package root). */
 export function thisCopy() {
     // dist/cli/copies.js -> dist/cli -> ... -> <pkg>/package.json
@@ -30,6 +32,7 @@ export function thisCopy() {
  *    so a symlink to the running copy is recognized and not double-listed
  *    — a copy is only listed under "path" when it differs from "cli").
  *  - "opencode-cache": copies under opencode's private npm cache.
+ *  - "npx-cache": copies under npx's cache (`<npm cache>/_npx/<hash>/...`).
  */
 export function findInstalledCopies(platform = process.platform, env = process.env) {
     const copies = [];
@@ -162,5 +165,31 @@ export function findInstalledCopies(platform = process.platform, env = process.e
     catch {
         /* cache scan is best-effort */
     }
+    // --- npx cache scan -------------------------------------------------------
+    // Layout: <npm cache>/_npx/<hash>/node_modules/@aron98/load-lock, one
+    // <hash> dir per distinct npx package spec (e.g. per pinned version).
+    try {
+        const npxRoot = npxCacheRoot(platform, env);
+        if (npxRoot && existsSync(npxRoot)) {
+            for (const hash of readdirSync(npxRoot)) {
+                try {
+                    const cand = join(npxRoot, hash, "node_modules", "@aron98", "load-lock");
+                    const pkgPath = join(cand, "package.json");
+                    if (!existsSync(pkgPath))
+                        continue;
+                    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+                    if (pkg?.name !== PKG_NAME)
+                        continue;
+                    add({ source: "npx-cache", path: cand, version: typeof pkg.version === "string" ? pkg.version : null });
+                }
+                catch {
+                    /* skip unreadable npx cache entry */
+                }
+            }
+        }
+    }
+    catch {
+        /* npx cache scan is best-effort */
+    }
     return copies;
 }

package/dist/cli/hook.js

@@ -23,7 +23,7 @@
  *    against the official docs only (contract-tested, not live-verified).
  */
 import { LLClient } from "../shared/client.js";
-import { POLICY_BRIEF } from "../policy/text.js";
+import { POLICY_BRIEF, SETUP_HINT } from "../policy/text.js";
 async function readStdin() {
     const chunks = [];
     for await (const c of process.stdin)
@@ -60,6 +60,23 @@ async function machineBrief() {
         return "load-lock daemon is not reachable right now; it will auto-start on your first load-lock tool call. Use the tools per the policy above when doing heavy work.";
     }
 }
+/**
+ * Daemon-side dedupe (issue #54): duplicate hook wiring (loose hooks +
+ * plugin, two plugins, ...) fires each hook several times. Only the first
+ * caller per (harness, session, event, occurrence) acts. Fails open: no
+ * session id, an old daemon without hook_once, or any error => act as before.
+ */
+async function firstHook(c, harness, event, sessionId, opts = {}) {
+    if (!sessionId)
+        return true;
+    try {
+        const r = (await c.request("hook_once", { harness, sessionId, event, ...opts }));
+        return r.first !== false;
+    }
+    catch {
+        return true;
+    }
+}
 function claimInstruction(offer, seconds) {
     return (`load-lock: capacity for "${offer.pool}" is now reserved for you (request ${offer.requestId}, ` +
         `op "${offer.opKey}", reason: ${offer.reason}). Claim it NOW with the load-lock claim tool ` +
@@ -79,7 +96,23 @@ export async function hookCommand(rest) {
         case "claude-code/session-start":
         case "codex/session-start":
         case "codex/subagent-start": {
-            process.stdout.write(POLICY_BRIEF + "\n\n" + (await machineBrief()) + "\n");
+            // Occurrence = SessionStart source (startup/resume/compact/...): a
+            // later compaction must re-inject; duplicates of one firing must not.
+            const c = new LLClient();
+            let first = true;
+            try {
+                await c.connect();
+                first = await firstHook(c, harness, event, input.session_id, { occurrence: input.source ?? input.agent_id });
+            }
+            catch {
+                /* daemon down: no dedupe possible; machineBrief explains */
+            }
+            finally {
+                c.close();
+            }
+            if (!first)
+                return;
+            process.stdout.write(POLICY_BRIEF + "\n\n" + SETUP_HINT + "\n\n" + (await machineBrief()) + "\n");
             return;
         }
         // ------------------------------------------------------------- wakeups
@@ -95,6 +128,9 @@ export async function hookCommand(rest) {
                     const { offers } = (await c.request("offers_for_cwd", { cwd }));
                     if (offers.length > 0) {
                         const o = offers[0];
+                        // Occurrence = the offer: each offer is delivered once per session.
+                        if (!(await firstHook(c, harness, event, input.session_id, { occurrence: o.offerToken })))
+                            return;
                         const seconds = Math.max(0, Math.round(((o.offerExpiresAt ?? Date.now()) - Date.now()) / 1000));
                         process.stdout.write(JSON.stringify({ decision: "block", reason: claimInstruction(o, seconds) }) + "\n");
                     }
@@ -124,6 +160,8 @@ export async function hookCommand(rest) {
                     const { offers } = (await c.request("offers_for_cwd", { cwd: cursorCwd }));
                     if (offers.length > 0) {
                         const o = offers[0];
+                        if (!(await firstHook(c, harness, event, input.conversation_id ?? input.session_id, { occurrence: o.offerToken })))
+                            return;
                         const seconds = Math.max(0, Math.round(((o.offerExpiresAt ?? Date.now()) - Date.now()) / 1000));
                         process.stdout.write(JSON.stringify({ followup_message: claimInstruction(o, seconds) }) + "\n");
                     }
@@ -148,6 +186,12 @@ export async function hookCommand(rest) {
             catch {
                 process.exit(0); // daemon down; policy hooks will cover it
             }
+            // One live watcher per session: the key is held on this connection
+            // and released by the daemon when the watcher exits.
+            if (!(await firstHook(c, harness, event, input.session_id, { hold: true }))) {
+                c.close();
+                process.exit(0);
+            }
             let woken = false;
             await new Promise((resolve) => {
                 const done = setTimeout(() => {
@@ -160,8 +204,8 @@ export async function hookCommand(rest) {
                         clearTimeout(done);
                         const seconds = Math.max(0, Math.round(((ev.entry.offerExpiresAt ?? Date.now()) - Date.now()) / 1000));
                         process.stderr.write(`load-lock: capacity for "${ev.entry.pool}" was just reserved for a request from this directory ` +
-                            `(op "${ev.entry.opKey}"). It expires in ~${seconds}s. Call your load-lock pending tool now and ` +
-                            `claim the offer with claim(offer_token), then start your heavy work immediately.`);
+                            `(op "${ev.entry.opKey}"). It expires in ~${seconds}s. Call the load-lock pending tool now and ` +
+                            `claim the offer with the load-lock claim tool (offer_token), then start your heavy work immediately.`);
                         c.close();
                         resolve();
                     }

package/dist/cli/install.d.ts

@@ -4,6 +4,8 @@ export interface InstallOptions {
     json?: boolean;
     global?: boolean;
     binDir?: string;
+    /** claude-code: install the loose wiring even when the plugin is enabled (#62). */
+    legacy?: boolean;
 }
 export interface UninstallOptions {
     harness: string;

package/dist/cli/install.js

@@ -13,6 +13,10 @@
  *  - claude-code  : user-scope MCP server in ~/.claude.json, SessionStart /
  *                   Stop hooks + background await-offer watcher in
  *                   ~/.claude/settings.json, CLAUDE.md section, skill.
+ *                   With the load-lock-plugin enabled at user scope it
+ *                   moves those loose entries out instead (--legacy keeps
+ *                   them); the skill is never written over one it didn't
+ *                   write (ACE).
  *  - codex        : ~/.codex/hooks.json (SessionStart/SubagentStart/Stop),
  *                   [mcp_servers.load-lock] in ~/.codex/config.toml,
  *                   ~/.codex/AGENTS.md pointer. Trust must be granted via /hooks.
@@ -59,6 +63,7 @@ import os from "node:os";
 import path from "node:path";
 import { POLICY_BRIEF } from "../policy/text.js";
 import { resolveStateDir } from "../shared/transport.js";
+import { activePlugin, inventoryHarness, removeClaudeLoose, skillDirOwner } from "./setup.js";
 const HOME = os.homedir();
 const PKG_NAME = "@aron98/load-lock";
 export function pkgRoot(binDir) {
@@ -223,8 +228,34 @@ function hookEntry(P, event, extra) {
         ],
     };
 }
+function claudeSkillDir() {
+    return path.join(HOME, ".claude", "skills", "load-lock");
+}
+function skillOwnerNote(owner) {
+    return owner === "ace" ? "managed by ACE (.ace.json), update or remove it through ACE" : "not written by load-lock install (a symlink)";
+}
+/** `load-lock-plugin@<marketplace>` from an `enabledPlugins["..."]` detail. */
+function pluginKey(i) {
+    return /^enabledPlugins\["(.+)"\]$/.exec(i.detail)?.[1] ?? "load-lock-plugin@load-lock";
+}
 function installClaudeCode(opts, P) {
+    // The plugin enabled at user scope replaces the loose MCP server, hooks
+    // and CLAUDE.md section everywhere (#62); project-scope enables don't.
+    const h = inventoryHarness("claude-code", { project: opts.project, home: HOME });
+    const plugin = h.integrations.find((i) => activePlugin(i) && i.owner === "harness" && i.scope === "user");
+    if (plugin && !opts.legacy) {
+        const actions = [
+            `plugin ${pluginKey(plugin)} is enabled in ${plugin.file}: it provides the MCP server and hooks, so the loose ones are not installed (--legacy installs them anyway)`,
+        ];
+        const removed = removeClaudeLoose(h);
+        actions.push(...(removed.length ? removed : ["no loose MCP server, hooks or CLAUDE.md section to remove"]));
+        actions.push(installClaudeSkill(P));
+        return actions;
+    }
     const actions = [];
+    if (plugin) {
+        actions.push(`--legacy: plugin ${pluginKey(plugin)} is enabled too; harmless, but two MCP servers are registered, keep one`);
+    }
     // 1. user-scope MCP server in ~/.claude.json
     const claudeJson = path.join(HOME, ".claude.json");
     const cj = readJson(claudeJson) ?? {};
@@ -256,20 +287,28 @@ function installClaudeCode(opts, P) {
     const marker = "<!-- load-lock:begin -->";
     if (mdSection(md, marker, `${marker}\n## load-lock: machine-wide heavy-work budget\n\n` +
         `Before resource-intensive local work (full builds, big test suites), coordinate with other agents on this machine:\n\n` +
-        `1. Call the MCP tool \`mcp__load-lock__acquire\` (reason + op_key) — it grants a permit or queues you.\n` +
-        `2. While queued, keep doing light work. When an offer arrives (hook wakeup or \`mcp__load-lock__pending\`), claim it via \`mcp__load-lock__claim\` within the window (default 30s).\n` +
-        `3. Only start heavy work after acquire/claim succeeds. Use \`mcp__load-lock__run_with_permit\` for full lifecycle ownership (auto-release), or \`attach_pid\` for processes you already started.\n` +
-        `4. Release (or cancel queued work) promptly. Inspect the machine with \`mcp__load-lock__inspect_machine\`; adjust capacity via \`mcp__load-lock__configure\` when warranted.\n\n` +
+        `1. Call the load-lock \`acquire\` tool (reason + op_key) — it grants a permit or queues you.\n` +
+        `2. While queued, keep doing light work. When an offer arrives (hook wakeup or the \`pending\` tool), claim it via the \`claim\` tool within the window (default 30s).\n` +
+        `3. Only start heavy work after acquire/claim succeeds. Use \`run_with_permit\` for full lifecycle ownership (auto-release), or \`attach_pid\` for processes you already started.\n` +
+        `4. Release (or cancel queued work) promptly. Inspect the machine with \`inspect_machine\`; adjust capacity via \`configure\` when warranted.\n\n` +
+        `Exact tool names vary with the wiring (standalone MCP server vs. plugin); use the load-lock tools you have.\n\n` +
         `Full guide: \`load-lock agent-guide\`.\n<!-- load-lock:end -->\n`))
         actions.push(`CLAUDE.md section in ${md}`);
     // 4. skill
-    const skillDir = path.join(HOME, ".claude", "skills", "load-lock");
+    actions.push(installClaudeSkill(P));
+    return actions;
+}
+/** Copy the skill, never over one we didn't write, e.g. ACE's (#89). */
+function installClaudeSkill(P) {
+    const skillDir = claudeSkillDir();
+    const owner = skillDirOwner(skillDir, skillDir);
+    if (owner !== "installer")
+        return `kept the skill in ${skillDir}: ${skillOwnerNote(owner)}`;
     fs.mkdirSync(skillDir, { recursive: true });
     fs.copyFileSync(P.skill, path.join(skillDir, "SKILL.md"));
-    actions.push(`skill in ${skillDir}/SKILL.md`);
-    return actions;
+    return `skill in ${skillDir}/SKILL.md`;
 }
-function uninstallClaudeCode() {
+function uninstallClaudeCode(opts) {
     const actions = [];
     const P = pkgPaths(); // cli path for our-entry matching below
     const claudeJson = path.join(HOME, ".claude.json");
@@ -313,9 +352,24 @@ function uninstallClaudeCode() {
     const md = path.join(HOME, ".claude", "CLAUDE.md");
     removeMdSection(md, "<!-- load-lock:begin -->");
     actions.push(`removed CLAUDE.md section`);
-    fs.rmSync(path.join(HOME, ".claude", "skills", "load-lock"), { recursive: true, force: true });
-    pruneEmptyDirs(path.join(HOME, ".claude", "skills"), path.join(HOME, ".claude"));
-    actions.push("removed skill");
+    const skillDir = claudeSkillDir();
+    const owner = skillDirOwner(skillDir, skillDir);
+    if (!fs.existsSync(skillDir)) {
+        // nothing to remove
+    }
+    else if (owner === "installer") {
+        fs.rmSync(skillDir, { recursive: true, force: true });
+        pruneEmptyDirs(path.join(HOME, ".claude", "skills"), path.join(HOME, ".claude"));
+        actions.push("removed skill");
+    }
+    else {
+        actions.push(`kept the skill in ${skillDir}: ${skillOwnerNote(owner)}`);
+    }
+    // Plugin state belongs to Claude Code: point at /plugin, never edit it.
+    const h = inventoryHarness("claude-code", { project: opts.project, home: HOME });
+    for (const i of h.integrations.filter((x) => x.kind === "plugin" && x.owner === "harness")) {
+        actions.push(`plugin ${pluginKey(i)} (${i.file}) is managed by Claude Code and stays; to remove it too, run /plugin uninstall ${pluginKey(i)}`);
+    }
     return actions;
 }
 // --------------------------------------------------------------------- codex
@@ -369,7 +423,7 @@ function installCodex(opts, P) {
     // 3. AGENTS.md pointer
     const agentsMd = path.join(codexHome, "AGENTS.md");
     if (mdSection(agentsMd, "<!-- load-lock:begin -->", `<!-- load-lock:begin -->\n## load-lock: machine-wide heavy-work budget\n\n` +
-        `Before resource-intensive local work (full builds, big test suites), coordinate with other agents on this machine via the \`load-lock\` MCP tools (mcp__load-lock__acquire / claim / release / run_with_permit / pending / status / inspect_machine / configure). ` +
+        `Before resource-intensive local work (full builds, big test suites), coordinate with other agents on this machine via the \`load-lock\` MCP tools (acquire / claim / release / run_with_permit / pending / status / inspect_machine / configure). ` +
         `Acquire before heavy work, keep doing light work while queued, claim offers promptly (they expire), release when done. Full guide: \`load-lock agent-guide\`.\n<!-- load-lock:end -->\n`))
         actions.push(`AGENTS.md section in ${agentsMd}`);
     actions.push("IMPORTANT: run `/hooks` inside Codex and grant trust to the new hooks (they are inert until trusted)");
@@ -1230,7 +1284,7 @@ export async function uninstallCommand(opts) {
             break;
         case "claude-code":
         case "claude":
-            actions = uninstallClaudeCode();
+            actions = uninstallClaudeCode(opts);
             break;
         case "codex":
             actions = uninstallCodex();

package/dist/cli/main.js

@@ -14,6 +14,7 @@ import { ProtocolError } from "../shared/protocol.js";
 import { waitForTurn } from "../shared/wait-turn.js";
 import { waitForTrackedJob } from "../shared/wait-completion.js";
 import { stateDir, socketPath } from "../core/persist.js";
+import { loadRuntimes, readDaemonInfo } from "../shared/runtimes.js";
 import { isWindows, probeTransport, killProcessGroup } from "../shared/transport.js";
 import { packageVersion, compareVersions } from "../shared/version.js";
 import { findInstalledCopies } from "./copies.js";
@@ -22,6 +23,8 @@ import { hookCommand } from "./hook.js";
 import { topCommand } from "./top.js";
 import { awaitDaemonUpgraded, serviceRestart, serviceStart, serviceStop, ServiceError } from "./service.js";
 import { updateCommand } from "./update.js";
+import { applyPlan, claudeCodeMode, formatInventory, formatPlan, inventory, inventoryHarness, planConverge, selfCopy } from "./setup.js";
+import { sessionIdentity } from "../shared/identity.js";
 // ---------------------------------------------------------------- arg parsing
 const argv = process.argv.slice(2);
 let flags = {};
@@ -36,7 +39,7 @@ for (let i = 0; i < argv.length; i++) {
         const eq = a.indexOf("=");
         if (eq !== -1)
             flags[a.slice(2, eq)] = a.slice(eq + 1);
-        else if (["json", "follow", "force", "admin", "quiet", "check", "version"].includes(a.slice(2)))
+        else if (["json", "follow", "force", "admin", "quiet", "check", "version", "yes"].includes(a.slice(2)))
             flags[a.slice(2)] = true;
         else if (i + 1 < argv.length && !argv[i + 1].startsWith("--"))
             flags[a.slice(2)] = argv[++i];
@@ -63,9 +66,24 @@ function out(v, human) {
     else
         process.stdout.write((human ? human() : JSON.stringify(v, null, 2)) + "\n");
 }
+// Session-derived default identity (issue #49): one id per harness session,
+// so CLI-driven agents on one machine no longer share `cli:$USER@$HOSTNAME`
+// (that remains the fallback when no session can be found).
+let identity;
+function sessionId() {
+    return (identity ??= sessionIdentity({
+        fallback: "cli:" + (process.env.USER || "user") + "@" + (process.env.HOSTNAME || "localhost"),
+    }));
+}
 function defaultAgent() {
-    return (process.env.LOAD_LOCK_AGENT ||
-        "cli:" + (process.env.USER || "user") + "@" + (process.env.HOSTNAME || "localhost"));
+    return sessionId().id;
+}
+/** Readable holder label for a session-derived id (explicit ids label themselves). */
+function defaultLabel() {
+    if (S("agent"))
+        return undefined;
+    const s = sessionId();
+    return s.label !== s.id ? s.label : undefined;
 }
 const HELP_GROUPS = [
     {
@@ -112,9 +130,11 @@ const HELP_GROUPS = [
     {
         title: "setup & docs",
         items: [
-            { names: ["install"], desc: "install the load-lock adapter for a harness: --harness <name>" },
+            { names: ["install"], desc: "install the load-lock adapter for a harness: --harness <name> (claude-code: with the plugin enabled, moves the loose wiring out; --legacy keeps it)" },
             { names: ["uninstall"], desc: "remove what install added: --harness <name>" },
+            { names: ["setup"], desc: "inventory every load-lock integration across all harnesses and plan the recommended layout (dry run); --yes applies it: [--project <dir>] [--json]" },
             { names: ["hook"], desc: "harness hook handlers (called by integrations, not humans)" },
+            { names: ["mcp"], desc: "run the MCP stdio server (same as the load-lock-mcp binary; started by harnesses, 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" },
         ],
@@ -269,7 +289,7 @@ async function main() {
             const r = await withClient((c) => c.request("acquire", {
                 pool: S("pool", "heavy"),
                 agentId: S("agent", defaultAgent()),
-                agentLabel: S("label") || undefined,
+                agentLabel: S("label") || defaultLabel(),
                 labelPrefix: S("label-prefix") || undefined,
                 cwd: S("cwd", process.cwd()),
                 opKey: S("op-key") || fail("acquire: --op-key is required"),
@@ -492,12 +512,25 @@ async function main() {
             // when their versions drift apart.
             const copies = findInstalledCopies();
             report.copies = copies;
+            // Runtime copies the daemon has seen via the handshake (issue #52),
+            // and the copy the daemon itself runs from.
+            const dinfo = readDaemonInfo(dir);
+            if (dinfo?.packageRoot)
+                report.daemonRuntime = { path: dinfo.packageRoot, version: dinfo.version ?? null };
+            report.knownRuntimes = loadRuntimes(dir);
             const versions = new Set(copies.map((c) => c.version).filter((v) => v !== null));
             if (versions.size > 1) {
                 warnings.push(`multiple load-lock versions installed (${[...versions].sort().join(", ")}): ` +
                     copies.map((c) => `${c.source}=${c.version ?? "?"} (${c.path})`).join("; ") +
                     ` — see docs/COMPATIBILITY.md "Multiple copies of load-lock" for which copy is authoritative for what`);
             }
+            // Claude Code wiring mode (#62): plugin, loose install, both or none.
+            const ccMode = claudeCodeMode(inventoryHarness("claude-code", { project: process.cwd() }));
+            report.claudeCodeMode = ccMode;
+            if (ccMode === "both") {
+                warnings.push("Claude Code: the plugin and the loose `load-lock install` wiring are both active (harmless, but two MCP servers); " +
+                    "`load-lock install --harness claude-code` or `load-lock setup --yes` moves the loose entries out");
+            }
             report.warnings = warnings;
             out(report, () => JSON.stringify(report, null, 2));
             return;
@@ -534,15 +567,39 @@ async function main() {
                 json: B("json"),
                 global: true,
                 binDir: import.meta.dirname ? join(import.meta.dirname, "..") : undefined,
+                legacy: B("legacy"),
             });
             return;
         case "uninstall":
             await uninstallCommand({ harness: S("harness"), project: S("project", process.cwd()) });
             return;
+        case "setup": {
+            const project = S("project", process.cwd());
+            const inv = inventory({ project });
+            const plan = planConverge(inv, selfCopy());
+            if (!B("yes")) {
+                out({ inventory: inv, plan }, () => formatInventory(inv) + "\n" + formatPlan(plan));
+                return;
+            }
+            const binDir = import.meta.dirname ? join(import.meta.dirname, "..") : undefined;
+            const applied = await applyPlan(inv, plan, { project, binDir });
+            const after = inventory({ project });
+            out({ inventory: after, plan, applied }, () => formatInventory(after) + "\n" + formatPlan(plan, applied));
+            return;
+        }
         // ------------------------------------------------------------------ hooks
         case "hook":
             await hookCommand(rest);
             return;
+        // ------------------------------------------------------------ mcp server
+        // Same server as the `load-lock-mcp` bin, reachable through the default
+        // `load-lock` bin so `npx -y @aron98/load-lock@<pin> mcp` works (ACE, #65).
+        // Imported lazily: other commands never load the MCP SDK.
+        case "mcp": {
+            const { runStdioMcp } = await import("../mcp/server.js");
+            await runStdioMcp();
+            return;
+        }
         case "agent-guide": {
             const p = join(import.meta.dirname ?? ".", "..", "..", "docs", "AGENT_GUIDE.md");
             process.stdout.write(readFileSync(existsSync(p) ? p : join(import.meta.dirname ?? ".", "..", "..", "docs", "AGENT_GUIDE.md"), "utf8"));