@aron98/load-lock 1.5.0 → 1.6.0

package/dist/test/setup.test.js

@@ -0,0 +1,354 @@
+/**
+ * `load-lock setup` inventory (issue #58), run against a temp HOME / project /
+ * state dir so real user config is never read or damaged. Fixtures are
+ * planted with the real installers (`load-lock install --harness ...`) plus
+ * hand-written plugin / ACE / foreign entries.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, mkdirSync, readFileSync, writeFileSync, readdirSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+const HERE = dirname(fileURLToPath(import.meta.url));
+const cliMain = join(HERE, "..", "cli", "main.js");
+const repoRoot = resolve(HERE, "..", "..");
+const TMP_BASE = process.env.LL_TEST_TMP ?? tmpdir();
+mkdirSync(TMP_BASE, { recursive: true });
+function sandbox() {
+    const root = mkdtempSync(join(TMP_BASE, "ll-setup-"));
+    const home = join(root, "home");
+    const project = join(root, "proj");
+    mkdirSync(home, { recursive: true });
+    mkdirSync(project, { recursive: true });
+    const env = {};
+    for (const [k, v] of Object.entries(process.env)) {
+        if (v !== undefined && !["XDG_CONFIG_HOME", "CODEX_HOME", "CLINE_MCP_SETTINGS_PATH", "LOAD_LOCK_SOCKET"].includes(k))
+            env[k] = v;
+    }
+    Object.assign(env, {
+        HOME: home,
+        LOAD_LOCK_STATE_DIR: join(root, "state"),
+        XDG_CACHE_HOME: join(root, "cache"),
+        npm_config_cache: join(root, "npm-cache"),
+    });
+    return { root, home, project, env };
+}
+function runCli(sb, args) {
+    return new Promise((res, rej) => {
+        const child = spawn(process.execPath, [cliMain, ...args], { env: sb.env, cwd: sb.project });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (b) => (stdout += b));
+        child.stderr.on("data", (b) => (stderr += b));
+        child.stdin.end();
+        child.once("exit", (code) => res({ code, stdout, stderr }));
+        child.once("error", rej);
+    });
+}
+/** `setup --json` output: { inventory, plan }. */
+async function setupOut(sb) {
+    const r = await runCli(sb, ["setup", "--json", "--project", sb.project]);
+    assert.equal(r.code, 0, `setup failed: ${r.stderr}`);
+    return JSON.parse(r.stdout);
+}
+async function setupJson(sb) {
+    return (await setupOut(sb)).inventory;
+}
+async function install(sb, harness, ...extra) {
+    const r = await runCli(sb, ["install", "--harness", harness, "--project", sb.project, ...extra]);
+    assert.equal(r.code, 0, `install ${harness} failed: ${r.stderr}`);
+}
+/** Every file under dir with its bytes (to prove setup never writes). */
+function snapshot(dir, out = {}) {
+    for (const n of readdirSync(dir)) {
+        const p = join(dir, n);
+        if (statSync(p).isDirectory())
+            snapshot(p, out);
+        else
+            out[p] = readFileSync(p, "utf8");
+    }
+    return out;
+}
+function harness(inv, name) {
+    const h = inv.harnesses.find((x) => x.harness === name);
+    assert.ok(h, `harness ${name} missing from inventory`);
+    return h;
+}
+function writeJsonFile(file, data) {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(data, null, 2) + "\n");
+}
+const ALL = ["claude-code", "opencode", "codex", "cursor", "gemini-cli", "copilot-cli", "cline", "roo-code", "goose", "omac"];
+test("setup: bare HOME lists every supported harness as not installed and writes nothing", async () => {
+    const sb = sandbox();
+    const before = snapshot(sb.root);
+    const inv = await setupJson(sb);
+    assert.deepEqual(inv.harnesses.map((h) => h.harness), ALL);
+    for (const h of inv.harnesses) {
+        assert.equal(h.rung, "none", `${h.harness} rung`);
+        assert.deepEqual(h.integrations, []);
+        assert.deepEqual(h.findings, []);
+    }
+    assert.ok(inv.runtime.copies.some((c) => c.source === "cli" && c.path === repoRoot), "lists the running copy");
+    const human = await runCli(sb, ["setup", "--project", sb.project]);
+    assert.equal(human.code, 0);
+    assert.match(human.stdout, /inventory \(read-only\)/);
+    assert.match(human.stdout, /goose\s+not installed/);
+    assert.deepEqual(snapshot(sb.root), before, "setup must not write anything");
+    rmSync(sb.root, { recursive: true, force: true });
+});
+test("setup: each installer's wiring is inventoried with its rung, owner and copy; setup stays read-only", async () => {
+    const sb = sandbox();
+    for (const h of ALL)
+        await install(sb, h);
+    const before = snapshot(sb.root);
+    const inv = await setupJson(sb);
+    const expect = {
+        "claude-code": { rung: "loose", kinds: ["hooks", "mcp", "policy", "skill"] },
+        opencode: { rung: "plugin", kinds: ["plugin"] },
+        codex: { rung: "loose", kinds: ["hooks", "mcp", "policy"] },
+        cursor: { rung: "loose", kinds: ["hooks", "mcp", "policy"] },
+        "gemini-cli": { rung: "loose", kinds: ["mcp", "policy"] },
+        "copilot-cli": { rung: "loose", kinds: ["mcp", "policy"] },
+        cline: { rung: "loose", kinds: ["mcp", "policy"] },
+        "roo-code": { rung: "loose", kinds: ["mcp", "policy"] },
+        goose: { rung: "loose", kinds: ["mcp", "policy"] },
+        omac: { rung: "loose", kinds: ["grants"] },
+    };
+    for (const [name, e] of Object.entries(expect)) {
+        const h = harness(inv, name);
+        assert.equal(h.rung, e.rung, `${name} rung`);
+        assert.deepEqual([...new Set(h.integrations.map((i) => i.kind))].sort(), e.kinds, `${name} kinds`);
+        for (const i of h.integrations) {
+            assert.equal(i.owner, "installer", `${name} ${i.kind} owner`);
+            if (i.copy !== undefined) {
+                assert.equal(i.copy, repoRoot, `${name} ${i.kind} points at this copy`);
+                assert.equal(i.stale, false);
+            }
+        }
+        assert.deepEqual(h.findings, [], `${name}: a clean install has no findings`);
+    }
+    const cc = harness(inv, "claude-code");
+    assert.deepEqual(cc.integrations.find((i) => i.kind === "hooks").detail.split(", ").sort(), ["SessionStart:await-offer", "SessionStart:session-start", "Stop:stop"]);
+    assert.deepEqual(snapshot(sb.root), before, "setup must not write anything");
+    rmSync(sb.root, { recursive: true, force: true });
+});
+test("setup: flags loose + plugin double install and MCP registered more than once (Claude Code)", async () => {
+    const sb = sandbox();
+    await install(sb, "claude-code");
+    const settingsFile = join(sb.home, ".claude", "settings.json");
+    const s = JSON.parse(readFileSync(settingsFile, "utf8"));
+    s.enabledPlugins = { "load-lock-plugin@load-lock": true, "other@market": true };
+    writeJsonFile(settingsFile, s);
+    // an ACE-style project MCP patch (`servers` key, pinned npx)
+    writeJsonFile(join(sb.project, ".mcp.json"), {
+        servers: { "load-lock": { command: "npx", args: ["-y", "@aron98/load-lock@1.5.0", "mcp"] } },
+    });
+    const cc = harness(await setupJson(sb), "claude-code");
+    assert.equal(cc.rung, "plugin");
+    const plugin = cc.integrations.find((i) => i.kind === "plugin");
+    assert.equal(plugin.detail, 'enabledPlugins["load-lock-plugin@load-lock"]');
+    assert.equal(plugin.owner, "harness");
+    assert.equal(plugin.enabled, true);
+    const ace = cc.integrations.find((i) => i.kind === "mcp" && i.scope === "project");
+    assert.equal(ace.owner, "other");
+    assert.equal(ace.detail, "servers.load-lock");
+    assert.ok(cc.findings.some((f) => f.startsWith("loose + plugin double install")), cc.findings.join("\n"));
+    assert.ok(cc.findings.some((f) => f.startsWith("MCP registered 3 times")), cc.findings.join("\n"));
+    // a disabled plugin does not count as the active rung
+    s.enabledPlugins["load-lock-plugin@load-lock"] = false;
+    writeJsonFile(settingsFile, s);
+    const cc2 = harness(await setupJson(sb), "claude-code");
+    assert.equal(cc2.rung, "loose");
+    assert.ok(cc2.findings.some((f) => /installed but disabled/.test(f)));
+    rmSync(sb.root, { recursive: true, force: true });
+});
+test("setup: hooks from a second (missing) copy are flagged as stale duplicates", async () => {
+    const sb = sandbox();
+    await install(sb, "codex");
+    const hooksFile = join(sb.home, ".codex", "hooks.json");
+    const h = JSON.parse(readFileSync(hooksFile, "utf8"));
+    const gone = join(sb.root, "gone", "node_modules", "@aron98", "load-lock", "dist", "cli", "main.js");
+    h.hooks.Stop.push({ hooks: [{ type: "command", command: `/usr/bin/node ${JSON.stringify(gone)} hook codex stop` }] });
+    writeJsonFile(hooksFile, h);
+    const cx = harness(await setupJson(sb), "codex");
+    const hooks = cx.integrations.filter((i) => i.kind === "hooks");
+    assert.equal(hooks.length, 2, "one hooks line per copy");
+    const staleOne = hooks.find((i) => i.stale);
+    assert.equal(staleOne.copy, resolve(gone, "..", "..", ".."));
+    assert.equal(staleOne.owner, "installer");
+    assert.ok(cx.findings.some((f) => f.startsWith("hooks from 2 different sources")), cx.findings.join("\n"));
+    assert.ok(cx.findings.some((f) => f.startsWith("stale hooks entry")), cx.findings.join("\n"));
+    rmSync(sb.root, { recursive: true, force: true });
+});
+test("setup: OpenCode plugin listed twice plus an MCP entry; ACE skill and skills-dir plugin are attributed", async () => {
+    const sb = sandbox();
+    await install(sb, "opencode");
+    const cfgFile = join(sb.home, ".config", "opencode", "opencode.json");
+    const cfg = JSON.parse(readFileSync(cfgFile, "utf8"));
+    cfg.plugin = ["@aron98/load-lock@1.5.0"];
+    cfg.mcp = { "load-lock": { type: "local", command: ["npx", "-y", "@aron98/load-lock@1.5.0", "mcp"] }, other: { type: "local", command: ["x"] } };
+    writeJsonFile(cfgFile, cfg);
+    // ACE-installed skill and Claude plugin (each with an .ace.json stamp)
+    const skills = join(sb.home, ".claude", "skills");
+    mkdirSync(join(skills, "load-lock"), { recursive: true });
+    writeFileSync(join(skills, "load-lock", "SKILL.md"), "---\nname: load-lock\ndescription: x\n---\n# load-lock\n");
+    writeFileSync(join(skills, "load-lock", ".ace.json"), "{}\n");
+    writeJsonFile(join(skills, "load-lock-plugin", ".claude-plugin", "plugin.json"), { name: "load-lock-plugin" });
+    writeFileSync(join(skills, "load-lock-plugin", ".ace.json"), "{}\n");
+    const inv = await setupJson(sb);
+    const oc = harness(inv, "opencode");
+    assert.equal(oc.rung, "plugin");
+    assert.equal(oc.integrations.filter((i) => i.kind === "plugin").length, 2);
+    assert.equal(oc.integrations.filter((i) => i.kind === "mcp").length, 1, "only the load-lock MCP entry");
+    assert.ok(oc.findings.some((f) => f.startsWith("plugin registered 2 times")), oc.findings.join("\n"));
+    assert.ok(oc.findings.some((f) => f.startsWith("MCP registered 2 times")), oc.findings.join("\n"));
+    const cc = harness(inv, "claude-code");
+    assert.equal(cc.rung, "skill", "an ACE skills-dir plugin is not counted as an active plugin (unverified, #63)");
+    assert.equal(cc.integrations.find((i) => i.kind === "skill").owner, "ace");
+    assert.equal(cc.integrations.find((i) => i.kind === "plugin").owner, "ace");
+    assert.ok(cc.findings.some((f) => /ACE skills-dir plugin/.test(f)));
+    rmSync(sb.root, { recursive: true, force: true });
+});
+// ------------------------------------------------------------ converge (#59)
+async function setupYes(sb) {
+    const r = await runCli(sb, ["setup", "--yes", "--json", "--project", sb.project]);
+    assert.equal(r.code, 0, `setup --yes failed: ${r.stderr}`);
+    return JSON.parse(r.stdout);
+}
+async function uninstall(sb, h) {
+    const r = await runCli(sb, ["uninstall", "--harness", h, "--project", sb.project]);
+    assert.equal(r.code, 0, `uninstall ${h} failed: ${r.stderr}`);
+}
+const steps = (out, h) => out.plan.steps.filter((s) => s.harness === h).map((s) => s.action);
+test("setup converge: dry run is the default and writes nothing", async () => {
+    const sb = sandbox();
+    await install(sb, "codex");
+    const hooksFile = join(sb.home, ".codex", "hooks.json");
+    const h = JSON.parse(readFileSync(hooksFile, "utf8"));
+    h.hooks.Stop.push({ hooks: [{ type: "command", command: `/usr/bin/node ${JSON.stringify(join(sb.root, "gone", "dist", "cli", "main.js"))} hook codex stop` }] });
+    writeJsonFile(hooksFile, h);
+    const before = snapshot(sb.root);
+    const r = await runCli(sb, ["setup", "--project", sb.project]);
+    assert.equal(r.code, 0, r.stderr);
+    assert.match(r.stdout, /plan \(dry run, re-run with --yes to apply\)/);
+    assert.match(r.stdout, /codex\s+install\s+load-lock install --harness codex/);
+    const j = await setupOut(sb);
+    assert.deepEqual(steps(j, "codex"), ["install"]);
+    assert.deepEqual(snapshot(sb.root), before, "a dry run must not write anything");
+    rmSync(sb.root, { recursive: true, force: true });
+});
+test("setup converge: Claude Code plugin + loose install -> loose removed (skill kept); install/uninstall reverse it", async () => {
+    const sb = sandbox();
+    const claudeDir = join(sb.home, ".claude");
+    // the user's own config, including the plugin they enabled with /plugin
+    writeJsonFile(join(sb.home, ".claude.json"), { mcpServers: { fetch: { type: "stdio", command: "uvx", args: ["mcp-server-fetch"] } } });
+    writeJsonFile(join(claudeDir, "settings.json"), {
+        theme: "dark",
+        enabledPlugins: { "load-lock-plugin@load-lock": true },
+        hooks: { Stop: [{ hooks: [{ type: "command", command: "/usr/local/bin/user-stop" }] }] },
+    });
+    writeFileSync(join(claudeDir, "CLAUDE.md"), "# My rules\n");
+    // an ACE MCP patch the user merged into the project
+    writeJsonFile(join(sb.project, ".mcp.json"), { servers: { "load-lock": { command: "npx", args: ["-y", "@aron98/load-lock@1.5.0", "mcp"] } } });
+    const original = snapshot(sb.root);
+    // with the plugin enabled, only --legacy writes the loose wiring (#62)
+    await install(sb, "claude-code", "--legacy");
+    const out = await setupYes(sb);
+    assert.deepEqual(steps(out, "claude-code"), ["remove-loose", "manual"]);
+    assert.match(out.plan.steps.find((s) => s.action === "manual").detail, /servers\.load-lock/);
+    const cc = harness(out.inventory, "claude-code");
+    assert.equal(cc.rung, "plugin");
+    assert.deepEqual(cc.integrations.map((i) => `${i.kind}:${i.owner}`).sort(), ["mcp:other", "plugin:harness", "skill:installer"], "only the plugin, the skill and the foreign project entry remain");
+    assert.ok(!cc.findings.some((f) => f.startsWith("loose + plugin")));
+    const s = JSON.parse(readFileSync(join(claudeDir, "settings.json"), "utf8"));
+    assert.deepEqual(s.enabledPlugins, { "load-lock-plugin@load-lock": true }, "harness-owned plugin state untouched");
+    assert.equal(readFileSync(join(sb.project, ".mcp.json"), "utf8"), original[join(sb.project, ".mcp.json")], "foreign entry untouched");
+    // idempotent: a second run has only the manual step left
+    assert.deepEqual(steps(await setupYes(sb), "claude-code"), ["manual"]);
+    // reversible: install --legacy brings the loose wiring back ...
+    await install(sb, "claude-code", "--legacy");
+    assert.equal(harness(await setupJson(sb), "claude-code").integrations.filter((i) => i.owner === "installer").length, 4);
+    // ... and uninstall restores the user's original bytes
+    await uninstall(sb, "claude-code");
+    assert.deepEqual(snapshot(sb.root), original);
+    rmSync(sb.root, { recursive: true, force: true });
+});
+test("setup converge: codex with a second copy's hooks and a stale MCP block -> one current set; uninstall restores", async () => {
+    const sb = sandbox();
+    const codexDir = join(sb.home, ".codex");
+    writeJsonFile(join(codexDir, "hooks.json"), { hooks: { Stop: [{ hooks: [{ type: "command", command: "/usr/local/bin/user-stop" }] }] } });
+    mkdirSync(codexDir, { recursive: true });
+    writeFileSync(join(codexDir, "config.toml"), 'model = "o3"\n');
+    writeFileSync(join(codexDir, "AGENTS.md"), "# Mine\n");
+    const original = snapshot(sb.root);
+    await install(sb, "codex");
+    const gone = join(sb.root, "gone", "node_modules", "@aron98", "load-lock");
+    const hooksFile = join(codexDir, "hooks.json");
+    const h = JSON.parse(readFileSync(hooksFile, "utf8"));
+    h.hooks.Stop.push({ hooks: [{ type: "command", command: `/usr/bin/node ${JSON.stringify(join(gone, "dist", "cli", "main.js"))} hook codex stop` }] });
+    writeJsonFile(hooksFile, h);
+    const toml = join(codexDir, "config.toml");
+    const mcpMain = join(repoRoot, "dist", "mcp", "main.js");
+    writeFileSync(toml, readFileSync(toml, "utf8").replace(JSON.stringify(mcpMain), JSON.stringify(join(gone, "dist", "mcp", "main.js"))));
+    assert.ok(harness(await setupJson(sb), "codex").findings.length >= 2, "messy state is flagged");
+    const out = await setupYes(sb);
+    assert.deepEqual(steps(out, "codex"), ["install"]);
+    const cx = harness(out.inventory, "codex");
+    assert.deepEqual(cx.findings, [], cx.findings.join("\n"));
+    for (const i of cx.integrations.filter((x) => x.copy))
+        assert.equal(i.copy, repoRoot);
+    assert.equal(cx.integrations.filter((i) => i.kind === "hooks").length, 1);
+    assert.equal(readFileSync(toml, "utf8").split("[mcp_servers.load-lock]").length, 2, "exactly one MCP block");
+    await uninstall(sb, "codex");
+    assert.deepEqual(snapshot(sb.root), original);
+    rmSync(sb.root, { recursive: true, force: true });
+});
+test("setup converge: MCP-only cline is upgraded to the installer's wiring; the foreign entry is left for the user", async () => {
+    const sb = sandbox();
+    const file = join(sb.home, ".cline", "data", "settings", "cline_mcp_settings.json");
+    writeJsonFile(file, {
+        mcpServers: {
+            ll: { command: "npx", args: ["-y", "@aron98/load-lock@1.5.0", "mcp"] },
+            fetch: { command: "uvx", args: ["mcp-server-fetch"] },
+        },
+    });
+    const original = snapshot(sb.root);
+    assert.equal(harness(await setupJson(sb), "cline").rung, "mcp");
+    const out = await setupYes(sb);
+    assert.deepEqual(steps(out, "cline"), ["install", "manual"]);
+    assert.match(out.plan.steps.find((s) => s.action === "manual").detail, /remove mcpServers\.ll/);
+    const cl = harness(out.inventory, "cline");
+    assert.equal(cl.rung, "loose");
+    assert.ok(cl.integrations.some((i) => i.detail === "mcpServers.ll"), "foreign entry untouched");
+    await uninstall(sb, "cline");
+    assert.deepEqual(snapshot(sb.root), original);
+    rmSync(sb.root, { recursive: true, force: true });
+});
+test("setup converge: never overwrites a foreign entry in the installer's slot, an ACE skill, or from a cache copy", async () => {
+    const sb = sandbox();
+    writeJsonFile(join(sb.home, ".gemini", "settings.json"), {
+        mcpServers: { "load-lock": { command: "npx", args: ["-y", "@aron98/load-lock@1.5.0", "mcp"] } },
+    });
+    const skill = join(sb.home, ".claude", "skills", "load-lock");
+    mkdirSync(skill, { recursive: true });
+    writeFileSync(join(skill, "SKILL.md"), "---\nname: load-lock\ndescription: x\n---\n");
+    writeFileSync(join(skill, ".ace.json"), "{}\n");
+    const before = snapshot(sb.root);
+    const out = await setupYes(sb);
+    assert.deepEqual(steps(out, "gemini-cli"), ["manual"]);
+    assert.deepEqual(steps(out, "claude-code"), ["manual"]);
+    assert.deepEqual(out.applied, []);
+    assert.deepEqual(snapshot(sb.root), before);
+    // a copy running from the npx cache never wires harnesses to itself
+    const { inventory, planConverge } = await import("../cli/setup.js");
+    writeJsonFile(join(sb.home, ".copilot", "mcp-config.json"), { mcpServers: { x: { command: "npx", args: ["@aron98/load-lock", "mcp"] } } });
+    const inv = inventory({ project: sb.project, home: sb.home, env: sb.env });
+    const plan = planConverge(inv, { selfCopy: "/c/_npx/abc/node_modules/@aron98/load-lock", selfEphemeral: true });
+    const cp = plan.steps.filter((s) => s.harness === "copilot-cli");
+    assert.deepEqual(cp.map((s) => s.action), ["manual"]);
+    assert.match(cp[0].detail, /cache copy/);
+    rmSync(sb.root, { recursive: true, force: true });
+});

package/dist/test/update-command.test.js

@@ -214,6 +214,24 @@ test("planUpdate: install argvs for bun/npm; honest refusals otherwise", () => {
     assert.equal(unknown.action, "refuse");
     assert.ok(unknown.reason.includes("cannot tell"), "unknown refusal admits it cannot tell");
 });
+test("classifySelf + planUpdate: npx-cache copy refuses, naming the pin (issue #57)", () => {
+    const base = mkdtempSync(join(TMP_BASE, "classify-npx-"));
+    try {
+        const npxRoot = join(base, "home", ".npm", "_npx");
+        const ctx = { home: join(base, "home"), npmGlobalRoot: join(base, "npm-root"), cacheRoot: join(base, "cache"), npxRoot };
+        const loc = classifySelf(join(npxRoot, "0123abcd", "node_modules", "@aron98", "load-lock"), ctx);
+        assert.equal(loc.kind, "npx-cache");
+        const plan = planUpdate(loc);
+        assert.equal(plan.action, "refuse");
+        assert.ok(plan.action === "refuse" && plan.reason.includes("npx cache"), "refusal names the npx cache");
+        assert.ok(plan.action === "refuse" && plan.reason.includes("pinned version"), "refusal says to bump the pin");
+        // A sibling of the npx root is not misclassified.
+        assert.notEqual(classifySelf(join(base, "home", ".npm", "_npx-other", "x"), ctx).kind, "npx-cache");
+    }
+    finally {
+        rmSync(base, { recursive: true, force: true });
+    }
+});
 // --------------------------------------------------------- detectCliDrift (pure)
 test("detectCliDrift: older PATH copy -> one notice with the exact command", () => {
     const base = mkdtempSync(join(TMP_BASE, "drift-"));
@@ -231,6 +249,26 @@ test("detectCliDrift: older PATH copy -> one notice with the exact command", ()
         rmSync(base, { recursive: true, force: true });
     }
 });
+test("detectCliDrift: newer npx-cache copy vs older PATH CLI -> notice names the npx copy (issue #57)", () => {
+    const base = mkdtempSync(join(TMP_BASE, "drift-npx-"));
+    try {
+        const binDir = plantBinCopy(join(base, "copy"), "0.9.0");
+        const cache = join(base, "npm-cache");
+        const ownPath = join(cache, "_npx", "0123abcd", "node_modules", "@aron98", "load-lock");
+        const d = detectCliDrift("9.9.9", { PATH: binDir, npm_config_cache: cache }, "linux", ownPath);
+        assert.ok(d, "older PATH CLI is drift");
+        assert.equal(d.ownSource, "npx-cache");
+        assert.ok(d.message.includes("npx"), `notice names the npx copy: ${d.message}`);
+        assert.ok(d.message.includes("load-lock update"), "notice names the exact command");
+        // The same skew from a non-npx copy keeps the adapter wording.
+        const other = detectCliDrift("9.9.9", { PATH: binDir, npm_config_cache: cache }, "linux", join(base, "elsewhere"));
+        assert.equal(other.ownSource, "adapter");
+        assert.ok(!other.message.includes("npx"));
+    }
+    finally {
+        rmSync(base, { recursive: true, force: true });
+    }
+});
 test("detectCliDrift: same/newer PATH copy, no PATH entry, foreign bin -> no drift", () => {
     const base = mkdtempSync(join(TMP_BASE, "nodrift-"));
     try {
@@ -404,6 +442,39 @@ test("update: npm-global apply installs via the stub and restarts the service",
         rmSync(base, { recursive: true, force: true });
     }
 });
+test("update: run from a planted npx-cache copy refuses with a clear message (issue #57)", async () => {
+    const base = mkdtempSync(join(TMP_BASE, "upd-npx-"));
+    try {
+        const home = join(base, "home");
+        const plantedCli = plantCopy(join(home, ".npm", "_npx", "0123abcd", "node_modules", "@aron98", "load-lock"), packageVersion());
+        makeStubNpm(join(base, "bin"));
+        const mark = join(base, "marker");
+        const env = {
+            ...process.env,
+            HOME: home,
+            PATH: join(base, "bin") + ":" + (process.env.PATH ?? ""),
+            STUB_VERSION: "9.9.9",
+            STUB_ROOT: join(base, "no-such-npm-root"),
+            STUB_MARK: mark,
+        };
+        // Resolve the npx cache from the temp HOME, never the real npm cache.
+        delete env.npm_config_cache;
+        delete env.NPM_CONFIG_CACHE;
+        const check = await runCliEnv(env, ["update", "--check", "--json"], plantedCli);
+        assert.equal(check.code, 1, `an update exists; this copy cannot self-apply it; stderr: ${check.stderr}`);
+        const report = JSON.parse(check.stdout);
+        assert.equal(report.state, "refused");
+        assert.equal(report.location.kind, "npx-cache");
+        assert.ok(report.reason.includes("npx cache") && report.reason.includes("pinned version"), report.reason);
+        const apply = await runCliEnv(env, ["update"], plantedCli);
+        assert.equal(apply.code, 70, "refusal in apply mode is a failure exit");
+        assert.ok(apply.stderr.includes("update refused") && apply.stderr.includes("npx cache"), apply.stderr);
+        assert.ok(!existsSync(mark), "no package manager ran");
+    }
+    finally {
+        rmSync(base, { recursive: true, force: true });
+    }
+});
 // ------------------------------------------------------------- service restart
 test("service restart: running daemon -> stop + start, new daemon answers", async () => {
     const d = await startDaemon();

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