@aron98/load-lock 1.5.0 → 1.6.0

package/dist/test/identity.test.js

@@ -0,0 +1,155 @@
+/**
+ * Session-derived agent identity (issue #49): the shared resolver
+ * (override → harness session env → stable harness ancestor → fallback)
+ * against planted /proc trees, plus the CLI default identity end to end:
+ * same session → one id (op-key dedupe, `pending`), different sessions →
+ * distinct ids.
+ */
+import test, { before, after } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { sessionIdentity, harnessAncestor, readProc } from "../shared/identity.js";
+import { startDaemon, runCli } from "./testutil.js";
+const TMP_BASE = process.env.LL_TEST_TMP ?? join(tmpdir(), "opencode");
+mkdirSync(TMP_BASE, { recursive: true });
+/** Plant /proc/<pid>/{stat,cmdline} entries: [pid, ppid, comm, startTime, argv]. */
+function plantProc(rows) {
+    const root = mkdtempSync(join(TMP_BASE, "ll-proc-"));
+    for (const [pid, ppid, comm, start, argv] of rows) {
+        mkdirSync(join(root, String(pid)));
+        // Fields after comm: state ppid pgrp session tty tpgid flags minflt
+        // cminflt majflt cmajflt utime stime cutime cstime priority nice
+        // num_threads itrealvalue starttime ...
+        const after = ["S", ppid, pid, pid, 0, -1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 20, 0, 1, 0, start, 1000, 10];
+        writeFileSync(join(root, String(pid), "stat"), `${pid} (${comm}) ${after.join(" ")}\n`);
+        writeFileSync(join(root, String(pid), "cmdline"), argv.join("\0") + "\0");
+    }
+    return root;
+}
+const tree = plantProc([
+    [100, 1, "claude", 5000, ["claude"]],
+    [110, 100, "bash", 5100, ["/bin/bash", "-c", "load-lock acquire"]],
+    [111, 100, "bash", 5200, ["/bin/bash", "-c", "load-lock pending"]],
+    // npx launcher between the harness and the CLI: node running npx-cli.js, then sh.
+    [120, 110, "node", 5300, ["node", "/usr/lib/node_modules/npm/bin/npx-cli.js", "-y", "@aron98/load-lock"]],
+    [121, 120, "sh", 5301, ["sh", "-c", "load-lock acquire"]],
+    [200, 1, "codex", 6000, ["codex"]],
+    [210, 200, "zsh", 6100, ["zsh", "-c", "load-lock acquire"]],
+    // comm with spaces and parens must parse.
+    [300, 1, "tmux: (server)", 7000, ["tmux"]],
+    [310, 300, "fish", 7100, ["fish"]],
+    // a shell chain that ends at init: no harness.
+    [400, 1, "bash", 8000, ["bash"]],
+]);
+after(() => rmSync(tree, { recursive: true, force: true }));
+const resolve = (startPid, env = {}, override) => sessionIdentity({ fallback: "cli:u@h", env, startPid, procRoot: tree, platform: "linux", override });
+test("identity: two calls from the same harness session resolve to the same id", () => {
+    const a = resolve(110);
+    const b = resolve(111);
+    assert.equal(a.source, "ancestor");
+    assert.equal(a.id, "proc:100:5000");
+    assert.equal(b.id, a.id);
+    assert.equal(a.label, "claude:100");
+    // npx/sh wrappers are walked past too.
+    assert.equal(resolve(121).id, a.id);
+});
+test("identity: different harness sessions resolve to different ids", () => {
+    assert.equal(resolve(210).id, "proc:200:6000");
+    assert.notEqual(resolve(210).id, resolve(110).id);
+    assert.equal(resolve(310).id, "proc:300:7000");
+    assert.equal(readProc(300, tree)?.comm, "tmux: (server)");
+});
+test("identity: a reused pid with a new start time is a different session", () => {
+    const reused = plantProc([[100, 1, "claude", 9999, ["claude"]], [110, 100, "bash", 10000, ["bash"]]]);
+    try {
+        const id = sessionIdentity({ fallback: "f", env: {}, startPid: 110, procRoot: reused, platform: "linux" }).id;
+        assert.equal(id, "proc:100:9999");
+        assert.notEqual(id, resolve(110).id);
+    }
+    finally {
+        rmSync(reused, { recursive: true, force: true });
+    }
+});
+test("identity: falls back when the walk reaches init, /proc is missing, or not on Linux", () => {
+    assert.equal(harnessAncestor(400, tree), null);
+    assert.deepEqual(resolve(400), { id: "cli:u@h", label: "cli:u@h", source: "fallback" });
+    assert.equal(resolve(99999).source, "fallback");
+    const mac = sessionIdentity({ fallback: "cli:u@h", env: {}, startPid: 110, procRoot: tree, platform: "darwin" });
+    assert.equal(mac.source, "fallback");
+});
+test("identity: harness session env vars beat the ancestor walk", () => {
+    const cc = resolve(110, { CLAUDE_CODE_SESSION_ID: "ee690007-78c4-48d0-8f80-77b74e95a7fd" });
+    assert.deepEqual(cc, {
+        id: "claude-code:ee690007-78c4-48d0-8f80-77b74e95a7fd",
+        label: "claude-code:ee690007",
+        source: "harness-env",
+    });
+    // OpenCode: the bare sessionID, i.e. the native plugin's agentId.
+    assert.equal(resolve(110, { OPENCODE_SESSION_ID: "ses_abc123" }).id, "ses_abc123");
+});
+test("identity: overrides still win (explicit > LOAD_LOCK_AGENT > harness env)", () => {
+    const env = { LOAD_LOCK_AGENT: "pinned", CLAUDE_CODE_SESSION_ID: "s1" };
+    assert.equal(resolve(110, env).id, "pinned");
+    assert.equal(resolve(110, env).source, "env");
+    assert.equal(resolve(110, env, " explicit ").id, "explicit");
+    assert.equal(resolve(110, { LOAD_LOCK_AGENT: "  " }).source, "ancestor", "blank override ignored");
+});
+// ------------------------------------------------------------ CLI end to end
+let d;
+before(async () => {
+    d = await startDaemon();
+    // The test runner itself may be running inside a harness session.
+    for (const k of ["LOAD_LOCK_AGENT", "CLAUDE_CODE_SESSION_ID", "OPENCODE_SESSION_ID"])
+        delete d.env[k];
+});
+after(async () => {
+    await d.stop();
+});
+function cliIn(env, args) {
+    return runCli({ ...d, env: { ...d.env, ...env } }, args);
+}
+async function acquireJson(env, opKey, extra = []) {
+    const r = await cliIn(env, ["acquire", "--op-key", opKey, "--reason", "identity test", "--json", ...extra]);
+    assert.ok(r.code === 0 || r.code === 68, r.stderr); // 68 = queued
+    return JSON.parse(r.stdout);
+}
+test("cli: same session shares one identity; different sessions get distinct ids", async () => {
+    const a1 = await acquireJson({ CLAUDE_CODE_SESSION_ID: "aaaaaaaa-1" }, "op/shared");
+    const a2 = await acquireJson({ CLAUDE_CODE_SESSION_ID: "aaaaaaaa-1" }, "op/shared");
+    const b = await acquireJson({ CLAUDE_CODE_SESSION_ID: "bbbbbbbb-2" }, "op/shared");
+    assert.equal(a1.entry.agentId, "claude-code:aaaaaaaa-1");
+    assert.equal(a1.entry.agentLabel, "claude-code:aaaaaaaa", "short readable label");
+    assert.equal(a2.entry.requestId, a1.entry.requestId, "same session: op-key dedupe returns the existing request");
+    assert.equal(b.entry.agentId, "claude-code:bbbbbbbb-2");
+    assert.notEqual(b.entry.requestId, a1.entry.requestId, "different sessions are not merged");
+    // Fill the pool so the next requests queue, then check `pending` isolation.
+    const status = JSON.parse((await cliIn({}, ["status", "--json"])).stdout);
+    const cap = status.config.pools.heavy.capacity;
+    for (let i = 2; i < cap; i++)
+        await acquireJson({ CLAUDE_CODE_SESSION_ID: "filler" }, `op/fill-${i}`);
+    const qa = await acquireJson({ CLAUDE_CODE_SESSION_ID: "aaaaaaaa-1" }, "op/queued");
+    assert.equal(qa.state, "queued");
+    const pa = JSON.parse((await cliIn({ CLAUDE_CODE_SESSION_ID: "aaaaaaaa-1" }, ["pending", "--json"])).stdout);
+    const pb = JSON.parse((await cliIn({ CLAUDE_CODE_SESSION_ID: "bbbbbbbb-2" }, ["pending", "--json"])).stdout);
+    assert.ok(JSON.stringify(pa).includes(qa.entry.requestId), "own queue entry visible");
+    assert.ok(!JSON.stringify(pb).includes(qa.entry.requestId), "other session does not see it");
+});
+test("cli: without session env, calls from one parent process share an ancestor identity", async () => {
+    if (process.platform !== "linux")
+        return;
+    const r1 = await acquireJson({}, "op/ancestor");
+    const r2 = await acquireJson({}, "op/ancestor");
+    // The CLI's parent is this test process (node, not a wrapper).
+    const start = readFileSync(`/proc/${process.pid}/stat`, "utf8").split(") ")[1].split(" ")[19];
+    assert.equal(r1.entry.agentId, `proc:${process.pid}:${start}`);
+    assert.equal(r2.entry.requestId, r1.entry.requestId);
+});
+test("cli: --agent and LOAD_LOCK_AGENT overrides still win", async () => {
+    const env = await acquireJson({ LOAD_LOCK_AGENT: "pinned-agent", CLAUDE_CODE_SESSION_ID: "aaaaaaaa-1" }, "op/override");
+    assert.equal(env.entry.agentId, "pinned-agent");
+    assert.equal(env.entry.agentLabel, undefined, "explicit ids label themselves");
+    const flag = await acquireJson({ CLAUDE_CODE_SESSION_ID: "aaaaaaaa-1" }, "op/override", ["--agent", "flag-agent"]);
+    assert.equal(flag.entry.agentId, "flag-agent");
+});

package/dist/test/install.test.js

@@ -5,7 +5,7 @@
  */
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, rmSync, mkdirSync, readFileSync, writeFileSync, existsSync, cpSync } from "node:fs";
+import { mkdtempSync, rmSync, mkdirSync, readFileSync, writeFileSync, existsSync, cpSync, symlinkSync, lstatSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -424,6 +424,7 @@ test("claude-code: install/uninstall round-trip on a populated HOME; re-install
     const md = readFileSync(claudeMd, "utf8");
     assert.ok(md.includes("# My rules"), "existing CLAUDE.md content preserved");
     assert.equal(count(md, MARKER_BEGIN), 1, "exactly one marked section");
+    assert.ok(!md.includes("mcp__"), "section names tools neutrally (plugin tools are namespaced differently)");
     assert.ok(existsSync(join(claudeDir, "skills", "load-lock", "SKILL.md")), "skill installed");
     // -- idempotent re-install: no duplicate hook entries (issue #19)
     r = await runCli(home, ["install", "--harness", "claude-code"]);
@@ -464,6 +465,43 @@ test("claude-code: bare HOME install then uninstall removes exactly what we adde
     assert.ok(!("load-lock" in cj.mcpServers), "our MCP server key removed");
     rmSync(home, { recursive: true, force: true });
 });
+test("claude-code: an ACE-stamped skill survives install and uninstall byte for byte (#89)", async () => {
+    const home = tempHome();
+    const skillDir = join(home, ".claude", "skills", "load-lock");
+    mkdirSync(skillDir, { recursive: true });
+    const aceSkill = "---\nname: load-lock\ndescription: from ACE\n---\nACE copy\n";
+    const stamp = JSON.stringify({ artifact: "load-lock", version: "1.4.0" }) + "\n";
+    writeFileSync(join(skillDir, "SKILL.md"), aceSkill);
+    writeFileSync(join(skillDir, ".ace.json"), stamp);
+    let r = await runCli(home, ["install", "--harness", "claude-code"]);
+    assert.equal(r.code, 0, `install failed: ${r.stderr}`);
+    assert.match(r.stdout, /kept the skill .*managed by ACE/);
+    assert.equal(readFileSync(join(skillDir, "SKILL.md"), "utf8"), aceSkill, "install must not overwrite ACE's skill");
+    // the rest of the loose wiring is still installed
+    const cj = JSON.parse(readFileSync(join(home, ".claude.json"), "utf8"));
+    assert.ok(cj.mcpServers["load-lock"], "MCP server installed");
+    r = await runCli(home, ["uninstall", "--harness", "claude-code"]);
+    assert.equal(r.code, 0, `uninstall failed: ${r.stderr}`);
+    assert.match(r.stdout, /kept the skill .*managed by ACE/);
+    assert.equal(readFileSync(join(skillDir, "SKILL.md"), "utf8"), aceSkill, "uninstall must not delete ACE's skill");
+    assert.equal(readFileSync(join(skillDir, ".ace.json"), "utf8"), stamp, "ACE stamp untouched");
+    rmSync(home, { recursive: true, force: true });
+});
+test("claude-code: a symlinked skill dir is neither written through nor removed (#89)", async () => {
+    const home = tempHome();
+    const checkout = join(home, "dev", "skill");
+    mkdirSync(checkout, { recursive: true });
+    writeFileSync(join(checkout, "SKILL.md"), "mine\n");
+    mkdirSync(join(home, ".claude", "skills"), { recursive: true });
+    symlinkSync(checkout, join(home, ".claude", "skills", "load-lock"));
+    let r = await runCli(home, ["install", "--harness", "claude-code"]);
+    assert.equal(r.code, 0, `install failed: ${r.stderr}`);
+    assert.equal(readFileSync(join(checkout, "SKILL.md"), "utf8"), "mine\n", "install must not write through the symlink");
+    r = await runCli(home, ["uninstall", "--harness", "claude-code"]);
+    assert.equal(r.code, 0, `uninstall failed: ${r.stderr}`);
+    assert.ok(lstatSync(join(home, ".claude", "skills", "load-lock")).isSymbolicLink(), "symlink kept");
+    rmSync(home, { recursive: true, force: true });
+});
 test("claude-code: uninstall with nothing installed is a harmless no-op", async () => {
     const home = tempHome();
     const r = await runCli(home, ["uninstall", "--harness", "claude-code"]);
@@ -472,6 +510,101 @@ test("claude-code: uninstall with nothing installed is a harmless no-op", async
     assert.ok(!existsSync(join(home, ".claude.json")), "no files created by uninstall");
     rmSync(home, { recursive: true, force: true });
 });
+// claude-code plugin migration (#62)
+const PLUGIN_KEY = "load-lock-plugin@load-lock";
+/** `doctor --json` against a temp HOME and a state dir no daemon ever runs in. */
+async function doctorMode(home) {
+    const state = join(home, "st");
+    const r = await runCli(home, ["doctor", "--json"], {
+        LOAD_LOCK_STATE_DIR: state,
+        LOAD_LOCK_SOCKET: join(state, "d.sock"),
+        LOAD_LOCK_NO_SPAWN: "1",
+    });
+    assert.equal(r.code, 0, `doctor failed: ${r.stderr}`);
+    const rep = JSON.parse(r.stdout);
+    return { mode: rep.claudeCodeMode, warnings: rep.warnings };
+}
+function enablePlugin(home, on) {
+    const file = join(home, ".claude", "settings.json");
+    const s = existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : {};
+    s.enabledPlugins = { ...s.enabledPlugins, [PLUGIN_KEY]: on };
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(s, null, 2) + "\n");
+}
+test("claude-code: loose → plugin migration, --legacy, uninstall; doctor reports the mode", async () => {
+    const home = tempHome();
+    const claudeDir = join(home, ".claude");
+    mkdirSync(claudeDir, { recursive: true });
+    writeFileSync(join(home, ".claude.json"), JSON.stringify({ mcpServers: { fetch: { command: "uvx" } } }, null, 2) + "\n");
+    writeFileSync(join(claudeDir, "settings.json"), JSON.stringify({ theme: "dark", hooks: { Stop: [{ hooks: [{ type: "command", command: "/usr/local/bin/user-stop" }] }] } }, null, 2) + "\n");
+    writeFileSync(join(claudeDir, "CLAUDE.md"), "# My rules\n");
+    const claudeJson = join(home, ".claude.json");
+    const settingsFile = join(claudeDir, "settings.json");
+    const claudeMd = join(claudeDir, "CLAUDE.md");
+    const skill = join(claudeDir, "skills", "load-lock", "SKILL.md");
+    let r = await runCli(home, ["install", "--harness", "claude-code"]);
+    assert.equal(r.code, 0, `install failed: ${r.stderr}`);
+    assert.equal((await doctorMode(home)).mode, "loose");
+    // the user enables the plugin: both are active, doctor flags it
+    enablePlugin(home, true);
+    let d = await doctorMode(home);
+    assert.equal(d.mode, "both");
+    assert.ok(d.warnings.some((w) => /plugin and the loose/.test(w)), "doctor flags both");
+    // -- install moves the loose entries out, reporting each step
+    r = await runCli(home, ["install", "--harness", "claude-code"]);
+    assert.equal(r.code, 0, `migrating install failed: ${r.stderr}`);
+    assert.match(r.stdout, new RegExp(`plugin ${PLUGIN_KEY} is enabled`));
+    assert.match(r.stdout, /removed mcpServers\.load-lock/);
+    assert.match(r.stdout, /removed load-lock hooks/);
+    assert.match(r.stdout, /removed the load-lock section/);
+    let cj = JSON.parse(readFileSync(claudeJson, "utf8"));
+    assert.ok(!("load-lock" in cj.mcpServers), "loose MCP server removed");
+    assert.ok(cj.mcpServers.fetch, "user MCP server untouched");
+    let s = JSON.parse(readFileSync(settingsFile, "utf8"));
+    assert.ok(!("SessionStart" in s.hooks), "loose SessionStart hooks removed");
+    assert.deepEqual(s.hooks.Stop, [{ hooks: [{ type: "command", command: "/usr/local/bin/user-stop" }] }], "user hook untouched");
+    assert.equal(s.enabledPlugins[PLUGIN_KEY], true, "plugin state untouched");
+    assert.equal(s.theme, "dark");
+    assert.equal(readFileSync(claudeMd, "utf8"), "# My rules\n", "CLAUDE.md section removed exactly");
+    assert.ok(existsSync(skill), "the skill stays (the plugin ships none)");
+    assert.equal((await doctorMode(home)).mode, "plugin");
+    // a second run is a no-op
+    r = await runCli(home, ["install", "--harness", "claude-code"]);
+    assert.equal(r.code, 0);
+    assert.match(r.stdout, /no loose MCP server, hooks or CLAUDE\.md section to remove/);
+    // -- --legacy keeps the loose install next to the plugin
+    r = await runCli(home, ["install", "--harness", "claude-code", "--legacy"]);
+    assert.equal(r.code, 0, `legacy install failed: ${r.stderr}`);
+    assert.match(r.stdout, /--legacy: plugin .* is enabled too/);
+    cj = JSON.parse(readFileSync(claudeJson, "utf8"));
+    assert.ok(cj.mcpServers["load-lock"], "--legacy installs the loose MCP server");
+    s = JSON.parse(readFileSync(settingsFile, "utf8"));
+    assert.equal(s.hooks.SessionStart.length, 2, "--legacy installs the loose hooks");
+    assert.equal((await doctorMode(home)).mode, "both");
+    // -- uninstall removes loose entries only and points at /plugin uninstall
+    r = await runCli(home, ["uninstall", "--harness", "claude-code"]);
+    assert.equal(r.code, 0, `uninstall failed: ${r.stderr}`);
+    assert.match(r.stdout, new RegExp(`/plugin uninstall ${PLUGIN_KEY}`));
+    s = JSON.parse(readFileSync(settingsFile, "utf8"));
+    assert.equal(s.enabledPlugins[PLUGIN_KEY], true, "uninstall never edits plugin state");
+    assert.ok(!("SessionStart" in s.hooks), "loose hooks removed");
+    cj = JSON.parse(readFileSync(claudeJson, "utf8"));
+    assert.ok(!("load-lock" in cj.mcpServers), "loose MCP server removed");
+    assert.equal(readFileSync(claudeMd, "utf8"), "# My rules\n");
+    assert.ok(!existsSync(skill), "our skill removed");
+    assert.equal((await doctorMode(home)).mode, "plugin");
+    rmSync(home, { recursive: true, force: true });
+});
+test("claude-code: a disabled plugin doesn't stop the loose install", async () => {
+    const home = tempHome();
+    enablePlugin(home, false);
+    const r = await runCli(home, ["install", "--harness", "claude-code"]);
+    assert.equal(r.code, 0, `install failed: ${r.stderr}`);
+    const cj = JSON.parse(readFileSync(join(home, ".claude.json"), "utf8"));
+    assert.ok(cj.mcpServers["load-lock"], "loose MCP server installed");
+    assert.equal((await doctorMode(home)).mode, "loose");
+    rmSync(home, { recursive: true, force: true });
+});
 // --------------------------------------------------------------------- codex
 test("codex: install/uninstall round-trip on a populated HOME; re-install never duplicates hooks", async () => {
     const home = tempHome();
@@ -510,6 +643,7 @@ test("codex: install/uninstall round-trip on a populated HOME; re-install never
     const md = readFileSync(agentsMd, "utf8");
     assert.ok(md.includes("# My codex rules"), "existing AGENTS.md content preserved");
     assert.equal(count(md, MARKER_BEGIN), 1, "exactly one marked section");
+    assert.ok(!md.includes("mcp__"), "section names tools neutrally");
     // -- idempotent re-install: no duplicate hook entries (issue #19)
     r = await runCli(home, ["install", "--harness", "codex"], { CODEX_HOME: codexDir });
     assert.equal(r.code, 0, `re-install failed: ${r.stderr}`);

package/dist/test/launcher.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/launcher.test.js

@@ -0,0 +1,222 @@
+/**
+ * Tests for the dependency-free plugin launcher (issue #60):
+ * plugins/claude-code/scripts/load-lock.mjs over planted fake runtime
+ * copies (PATH, state dir) and a fake npx-cli.js. Light: no daemon, no
+ * network; every case runs in its own temp HOME/state dir.
+ */
+import test from "node:test";
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync, symlinkSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(HERE, "..", "..");
+const LAUNCHER = join(REPO_ROOT, "plugins", "claude-code", "scripts", "load-lock.mjs");
+const PKG_VERSION = JSON.parse(readFileSync(join(REPO_ROOT, "package.json"), "utf8")).version;
+const L = await import(pathToFileURL(LAUNCHER).href);
+const TMP_BASE = process.env.LL_TEST_TMP ?? tmpdir();
+mkdirSync(TMP_BASE, { recursive: true });
+/** A fake entry that reports what it was run with, then exits per FAKE_EXIT / FAKE_HANG. */
+const FAKE_ENTRY = (tag) => `
+let s = "";
+process.stdin.on("data", (d) => (s += d));
+process.stdin.on("end", () => {
+  process.stdout.write(JSON.stringify({ entry: ${JSON.stringify(tag)}, argv: process.argv.slice(2), stdin: s }) + "\\n");
+  if (process.env.FAKE_HANG === "1") setInterval(() => {}, 1000);
+  else process.exitCode = Number(process.env.FAKE_EXIT ?? 0);
+});
+`;
+/** Plant a fake @aron98/load-lock package root with both bins. */
+function plantPkg(root, version, name = "@aron98/load-lock") {
+    mkdirSync(join(root, "dist", "cli"), { recursive: true });
+    mkdirSync(join(root, "dist", "mcp"), { recursive: true });
+    writeFileSync(join(root, "package.json"), JSON.stringify({ name, version }));
+    writeFileSync(join(root, "dist", "cli", "main.js"), FAKE_ENTRY(`cli@${version}`));
+    writeFileSync(join(root, "dist", "mcp", "main.js"), FAKE_ENTRY(`mcp@${version}`));
+    return root;
+}
+function sandbox() {
+    const dir = mkdtempSync(join(TMP_BASE, "ll-launch-"));
+    const bin = join(dir, "bin");
+    const state = join(dir, "state");
+    mkdirSync(bin, { recursive: true });
+    mkdirSync(state, { recursive: true });
+    const env = {
+        HOME: dir,
+        PATH: bin, // only planted copies; the launcher runs node via process.execPath
+        LOAD_LOCK_STATE_DIR: state,
+        LOAD_LOCK_LAUNCHER_DEBUG: "1",
+        // No npx unless a test plants one: a missing override never falls back.
+        LOAD_LOCK_LAUNCHER_NPX_CLI: join(dir, "no-npx-cli.js"),
+    };
+    return { dir, bin, state, env };
+}
+/** Put a POSIX-npm-style `load-lock` link for `root` on the sandbox PATH. */
+function linkOnPath(sb, root) {
+    symlinkSync(join(root, "dist", "cli", "main.js"), join(sb.bin, "load-lock"));
+}
+function run(sb, args, extraEnv = {}, input = '{"session_id":"s1"}') {
+    const t0 = Date.now();
+    const r = spawnSync(process.execPath, [LAUNCHER, ...args], {
+        env: { ...sb.env, ...extraEnv },
+        input,
+        encoding: "utf8",
+        timeout: 20_000,
+    });
+    return { ...r, ms: Date.now() - t0 };
+}
+const posix = process.platform !== "win32";
+test("launcher pin equals package.json version", () => {
+    const text = readFileSync(LAUNCHER, "utf8");
+    assert.match(text, new RegExp(`"@aron98/load-lock@${PKG_VERSION.replace(/\./g, "\\.")}"`));
+});
+test("PATH branch: a new-enough load-lock on PATH runs its compiled entry with stdin and args", { skip: !posix }, () => {
+    const sb = sandbox();
+    try {
+        linkOnPath(sb, plantPkg(join(sb.dir, "global", "lib", "node_modules", "@aron98", "load-lock"), "99.0.0"));
+        const r = run(sb, ["hook", "claude-code", "stop"]);
+        assert.equal(r.status, 0, r.stderr);
+        const out = JSON.parse(r.stdout);
+        assert.equal(out.entry, "cli@99.0.0");
+        assert.deepEqual(out.argv, ["hook", "claude-code", "stop"]);
+        assert.equal(out.stdin, '{"session_id":"s1"}');
+        assert.match(r.stderr, /launcher: path 99\.0\.0/);
+        const m = run(sb, ["--bin", "load-lock-mcp"], {}, "");
+        assert.equal(m.status, 0, m.stderr);
+        assert.equal(JSON.parse(m.stdout).entry, "mcp@99.0.0");
+    }
+    finally {
+        rmSync(sb.dir, { recursive: true, force: true });
+    }
+});
+test("state branch: a too-old PATH copy is skipped for the newest known copy >= pin", { skip: !posix }, () => {
+    const sb = sandbox();
+    try {
+        linkOnPath(sb, plantPkg(join(sb.dir, "old"), "0.1.0"));
+        const a = plantPkg(join(sb.dir, "copy-a"), "98.0.0");
+        const b = plantPkg(join(sb.dir, "copy-b"), "98.1.0");
+        const tooOld = plantPkg(join(sb.dir, "copy-old"), "0.0.1");
+        const notOurs = plantPkg(join(sb.dir, "copy-other"), "999.0.0", "something-else");
+        writeFileSync(join(sb.state, "runtimes.json"), JSON.stringify({
+            copies: [a, tooOld, notOurs, join(sb.dir, "gone")].map((path) => ({ path, version: "x", lastSeen: 1 })),
+        }));
+        writeFileSync(join(sb.state, "daemon.json"), JSON.stringify({ pid: 1, startedAt: 1, socket: "s", packageRoot: b }));
+        const r = run(sb, ["hook", "claude-code", "stop"]);
+        assert.equal(r.status, 0, r.stderr);
+        assert.equal(JSON.parse(r.stdout).entry, "cli@98.1.0");
+        assert.match(r.stderr, /launcher: state 98\.1\.0/);
+    }
+    finally {
+        rmSync(sb.dir, { recursive: true, force: true });
+    }
+});
+test("npx branch: pinned --package, --offline only in hook mode, bin after --", () => {
+    const sb = sandbox();
+    try {
+        const npxCli = join(sb.dir, "npx-cli.js");
+        writeFileSync(npxCli, `process.stdout.write(JSON.stringify(process.argv.slice(2)) + "\\n");`);
+        const env = { LOAD_LOCK_LAUNCHER_NPX_CLI: npxCli };
+        const h = run(sb, ["hook", "claude-code", "session-start"], env);
+        assert.equal(h.status, 0, h.stderr);
+        assert.deepEqual(JSON.parse(h.stdout), [
+            "--yes", "--offline", `--package=@aron98/load-lock@${PKG_VERSION}`, "--", "load-lock", "hook", "claude-code", "session-start",
+        ]);
+        const m = run(sb, ["--bin", "load-lock-mcp"], env, "");
+        assert.equal(m.status, 0, m.stderr);
+        assert.deepEqual(JSON.parse(m.stdout), ["--yes", `--package=@aron98/load-lock@${PKG_VERSION}`, "--", "load-lock-mcp"]);
+    }
+    finally {
+        rmSync(sb.dir, { recursive: true, force: true });
+    }
+});
+test("no runtime at all: hooks exit 0, SessionStart prints one install hint, the MCP server fails loudly", () => {
+    const sb = sandbox();
+    try {
+        const s = run(sb, ["hook", "claude-code", "session-start"]);
+        assert.equal(s.status, 0);
+        assert.equal(s.stdout.trim().split("\n").length, 1);
+        assert.match(s.stdout, /npm i -g @aron98\/load-lock/);
+        for (const ev of ["stop", "await-offer"]) {
+            const r = run(sb, ["hook", "claude-code", ev]);
+            assert.equal(r.status, 0);
+            assert.equal(r.stdout, "");
+        }
+        const m = run(sb, ["--bin", "load-lock-mcp"], {}, "");
+        assert.equal(m.status, 1);
+        assert.match(m.stderr, /no runtime found/);
+        assert.equal(run(sb, ["--bin", "nope"]).status, 64);
+    }
+    finally {
+        rmSync(sb.dir, { recursive: true, force: true });
+    }
+});
+test("exit codes: hooks pass 0/2 through and swallow the rest; the MCP server passes everything through", { skip: !posix }, () => {
+    const sb = sandbox();
+    try {
+        linkOnPath(sb, plantPkg(join(sb.dir, "pkg"), "99.0.0"));
+        assert.equal(run(sb, ["hook", "claude-code", "await-offer"], { FAKE_EXIT: "2" }).status, 2);
+        assert.equal(run(sb, ["hook", "claude-code", "stop"], { FAKE_EXIT: "1" }).status, 0);
+        // SessionStart that already printed output gets no extra hint.
+        const s = run(sb, ["hook", "claude-code", "session-start"], { FAKE_EXIT: "1" });
+        assert.equal(s.status, 0);
+        assert.doesNotMatch(s.stdout, /npm i -g/);
+        assert.equal(run(sb, ["--bin", "load-lock-mcp"], { FAKE_EXIT: "3" }, "").status, 3);
+    }
+    finally {
+        rmSync(sb.dir, { recursive: true, force: true });
+    }
+});
+test("timeout: a stalled hook is killed and exits 0 fast; await-offer is not bounded by it", { skip: !posix }, () => {
+    const sb = sandbox();
+    try {
+        const npxCli = join(sb.dir, "npx-cli.js");
+        // A stalled npx whose own child holds stdout: the process group dies too.
+        writeFileSync(npxCli, `const { spawn } = require("node:child_process");
+       spawn(process.execPath, ["-e", "setInterval(() => {}, 1000)"], { stdio: "inherit" });
+       setInterval(() => {}, 1000);`);
+        writeFileSync(join(sb.dir, "package.json"), JSON.stringify({ type: "commonjs" }));
+        const env = { LOAD_LOCK_LAUNCHER_NPX_CLI: npxCli, LOAD_LOCK_LAUNCHER_TIMEOUT_MS: "300" };
+        const r = run(sb, ["hook", "claude-code", "session-start"], env);
+        assert.equal(r.status, 0);
+        assert.ok(r.ms < 5000, `took ${r.ms}ms`);
+        assert.match(r.stdout, /npm i -g/); // nothing came out, so the hint does
+        linkOnPath(sb, plantPkg(join(sb.dir, "pkg"), "99.0.0"));
+        const w = spawnSync(process.execPath, [LAUNCHER, "hook", "claude-code", "await-offer"], {
+            env: { ...sb.env, FAKE_HANG: "1", LOAD_LOCK_LAUNCHER_TIMEOUT_MS: "200" },
+            input: "{}",
+            encoding: "utf8",
+            timeout: 1500,
+        });
+        assert.equal(w.error?.code, "ETIMEDOUT", "await-offer must outlive the hook timeout");
+    }
+    finally {
+        rmSync(sb.dir, { recursive: true, force: true });
+    }
+});
+test("resolution helpers: Windows npm shim layout, npx.cmd fallback, state dir precedence", () => {
+    const sb = sandbox();
+    try {
+        // Windows npm global layout: <prefix>\load-lock.cmd + <prefix>\node_modules\@aron98\load-lock
+        const prefix = join(sb.dir, "npm-prefix");
+        plantPkg(join(prefix, "node_modules", "@aron98", "load-lock"), "99.2.0");
+        writeFileSync(join(prefix, "load-lock.cmd"), "@echo off\r\n");
+        const found = L.pathCopy({ PATH: prefix }, "win32", "dist/cli/main.js");
+        assert.equal(found?.version, "99.2.0");
+        assert.equal(found?.source, "path");
+        const noNode = join(sb.dir, "nodeless", "node.exe");
+        assert.deepEqual(L.npxCommand({}, "win32", noNode), { command: "npx.cmd", args: [], shell: true });
+        assert.deepEqual(L.npxCommand({}, "linux", noNode), { command: "npx", args: [], shell: false });
+        assert.equal(L.stateDir({ LOAD_LOCK_STATE_DIR: "/x" }, "linux"), "/x");
+        assert.equal(L.stateDir({ XDG_STATE_HOME: "/xdg", HOME: "/h" }, "linux"), join("/xdg", "load-lock"));
+        assert.equal(L.stateDir({ HOME: "/h" }, "linux"), join("/h", ".local", "state", "load-lock"));
+        assert.equal(L.stateDir({ LOCALAPPDATA: "C:/AppData" }, "win32"), join("C:/AppData", "load-lock"));
+        assert.equal(L.compareVersions("1.10.0", "1.9.9"), 1);
+        assert.equal(L.compareVersions("1.5.0", "1.5"), 0);
+        assert.equal(L.compareVersions("1.4.9", "1.5.0"), -1);
+    }
+    finally {
+        rmSync(sb.dir, { recursive: true, force: true });
+    }
+});