@aron98/load-lock 1.4.0 → 1.6.0

package/README.md

@@ -1,6 +1,17 @@
-# 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://img.shields.io/npm/dm/@aron98/load-lock?color=%233fb950" alt="npm downloads"></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 +32,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 +71,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 +157,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 +165,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/adapters/opencode/plugin.js

@@ -24,6 +24,8 @@ import { POLICY_BRIEF } from "../../policy/text.js";
 import { waitForTurn, WaitAbortedError } from "../../shared/wait-turn.js";
 import { waitForLocalJob, waitForTrackedJob } from "../../shared/wait-completion.js";
 import { killProcessGroup } from "../../shared/transport.js";
+import { detectCliDrift } from "../../shared/drift.js";
+import { packageVersion } from "../../shared/version.js";
 const client = new LLClient();
 const knownSessions = new Set();
 const jobs = new Map();
@@ -44,6 +46,18 @@ function toolContent(v) {
 export default Plugin.define({
     id: "load-lock",
     setup(ctx) {
+        // Drift notice (issue #38): when this adapter copy is NEWER than the
+        // `load-lock` CLI that PATH resolves to (opencode refreshed its cache
+        // copy but the global install was never updated), surface one clear
+        // notice naming the exact command — on stderr at init, and once in the
+        // injected context. Notify only: nothing is ever auto-installed. Note
+        // the honest limitation (docs/OPERATIONS.md): a harness session that
+        // was already running keeps the OLD adapter code in memory until the
+        // harness itself restarts — this fires from the NEW copy at its init.
+        const cliDrift = detectCliDrift(packageVersion());
+        if (cliDrift)
+            process.stderr.write(cliDrift.message + "\n");
+        const DRIFT_NOTE = cliDrift ? "\n\n" + cliDrift.message : "";
         // ------------------------------------------------------------- tools
         ctx.tool.transform((editor) => {
             editor.namespace({
@@ -314,7 +328,7 @@ export default Plugin.define({
         });
         // ------------------------------------------- policy on every model call
         void ctx.session.hook("context", async (event) => {
-            event.system.push({ type: "text", text: POLICY_BRIEF + "\n\n" + (await statusBrief()) });
+            event.system.push({ type: "text", text: POLICY_BRIEF + "\n\n" + (await statusBrief()) + DRIFT_NOTE });
         });
         // -------------------------------------------------- idle wakeup via watch
         void (async () => {

package/dist/adapters/opencode/tui.js

@@ -100,6 +100,8 @@ function dashboardLines(v, width, f) {
         push(`note: ${v.daemonRestartNote}`, f.warn);
     if (v.versionSkewNote)
         push(`note: ${v.versionSkewNote}`, f.warn);
+    if (v.installDriftNote)
+        push(`note: ${v.installDriftNote}`, f.warn);
     if (v.machine) {
         const m = v.machine;
         const cg = m.cgroupCpuQuota != null ? ` · cgroup quota ${m.cgroupCpuQuota / 100} CPU` : "";
@@ -209,11 +211,14 @@ export default Plugin.define({
     id: "load-lock.tui",
     setup(ctx) {
         const [view, setView] = createSignal(null);
-        const feed = new DashboardFeed(new LLClient());
+        // driftSurface "opencode": when this session's copy is older than the
+        // PATH CLI, the hint says to restart opencode (plugins never hot-reload).
+        const feed = new DashboardFeed(new LLClient(), { driftSurface: "opencode" });
         feed.onChange = () => setView(feed.view());
         feed.onState = () => setView(feed.view());
         void feed.start().catch(() => {
-            /* daemon down or spawning; the feed keeps retrying and will go live */
+            /* daemon down or spawning; the reconnect loop keeps retrying and
+               will go live — start() only reports the FIRST connect failure */
         });
         // Local countdown tick: produces a fresh snapshot once per second so
         // ages/deadlines advance even between daemon events.

package/dist/cli/copies.d.ts

@@ -1,20 +1,12 @@
+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. */
     version: string | null;
 }
-/**
- * Find the package.json of the @aron98/load-lock copy that contains the
- * given file, by climbing parent directories. Best-effort: returns null if
- * no enclosing package.json matches (or is readable).
- */
-export declare function enclosingPackage(startDir: string, maxDepth?: number): {
-    path: string;
-    version: string | null;
-} | null;
 /** The copy of load-lock this process runs from (its own package root). */
 export declare function thisCopy(): InstalledCopy | null;
 /**
@@ -24,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,48 +3,19 @@
  * 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.
  */
 import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { isWindows } from "../shared/transport.js";
-/** Package name of this package (used to find enclosing package roots). */
-const PKG_NAME = "@aron98/load-lock";
-/**
- * Find the package.json of the @aron98/load-lock copy that contains the
- * given file, by climbing parent directories. Best-effort: returns null if
- * no enclosing package.json matches (or is readable).
- */
-export function enclosingPackage(startDir, maxDepth = 12) {
-    let dir = startDir;
-    for (let i = 0; i < maxDepth; i++) {
-        const pkgPath = join(dir, "package.json");
-        try {
-            if (existsSync(pkgPath)) {
-                const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
-                if (pkg?.name === PKG_NAME) {
-                    return { path: dir, version: typeof pkg.version === "string" ? pkg.version : null };
-                }
-                // A foreign package.json terminates the climb (e.g. a PATH bin
-                // inside some other tool's package).
-                return null;
-            }
-        }
-        catch {
-            return null;
-        }
-        const parent = dirname(dir);
-        if (parent === dir)
-            return null;
-        dir = parent;
-    }
-    return null;
-}
+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
@@ -61,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 = [];
@@ -193,15 +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;
 }
-/** Cache root the way opencode resolves it (its npm cache lives under it). */
-function opencodeCacheRoot(platform, env) {
-    if (env.XDG_CACHE_HOME)
-        return env.XDG_CACHE_HOME;
-    if (platform === "win32")
-        return env.LOCALAPPDATA ?? null;
-    if (platform === "darwin")
-        return join(env.HOME ?? homedir(), "Library", "Caches");
-    return join(env.HOME ?? homedir(), ".cache");
-}

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)");
@@ -1154,7 +1208,7 @@ function installOmac(opts, P) {
         "LOAD_LOCK_LABEL_PREFIX=omac (dashboard shows holders as omac:<label>); " +
         "LOAD_LOCK_SOCKET only if the default <state dir>/daemon.sock is not what the sandbox sees");
     actions.push("label prefixes need load-lock >= 1.2.0 on BOTH ends: a daemon started before v1.2.0 " +
-        "silently strips the unknown labelPrefix field — upgrade and restart the daemon (load-lock service stop && load-lock service start)");
+        "silently strips the unknown labelPrefix field — upgrade and restart the daemon (load-lock service restart)");
     actions.push("verified live against omac 0.11.0 (bubblewrap + Landlock): sandboxed client -> host daemon " +
         "round-trip, prefixed labels, LOAD_LOCK_NO_SPAWN error contract");
     return actions;
@@ -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();