@aron98/load-lock 1.4.0 → 1.6.0

package/dist/policy/text.js

@@ -4,12 +4,17 @@
  *
  *  - OpenCode plugin: injected via session "context" hook (every model call,
  *    compaction-proof) + registered skill for detail.
- *  - Claude Code: SessionStart hook stdout (matcher startup|resume|clear|compact|fork).
+ *  - Claude Code: SessionStart hook stdout (matcher startup|resume|clear|compact|fork),
+ *    from the loose install or the load-lock-plugin Claude Code plugin.
  *  - Codex CLI: SessionStart/SubagentStart hook stdout (needs /hooks trust).
  *  - MCP server: `instructions` field on every harness that surfaces it.
+ *  - Skill only (ladder rung 0, docs/OPERATIONS.md): no brief is injected;
+ *    skills/load-lock/SKILL.md carries its own version of these rules plus the
+ *    MCP -> PATH -> pinned-npx bootstrap (docs/AGENT_GUIDE.md section 0).
  *
  * Deliberately SHORT (spec: no noisy reminders). The detailed playbook lives
- * in the skill / docs/AGENT_GUIDE.md.
+ * in docs/AGENT_GUIDE.md, served by the MCP agent_guide tool, the skill and
+ * `load-lock agent-guide`.
  */
 export const POLICY_BRIEF = `# load-lock: machine-wide heavy-work budget
 
@@ -49,7 +54,13 @@ Rules:
    including container limits) and adjust with configure (explain why). Don't
    assume N cores = N parallel heavy jobs.
 
-Detailed guide: the "load-lock" skill or \`load-lock agent-guide\`.`;
+Detailed guide: the load-lock agent_guide tool (MCP/plugin), else the
+"load-lock" skill or \`load-lock agent-guide\` (CLI) where installed.`;
+/**
+ * The one upgrade hint every rung carries (#47 ladder, #59): appended after
+ * the brief in the MCP instructions and the session-start hook output.
+ */
+export const SETUP_HINT = "Wiring: `load-lock setup` lists this machine's load-lock integrations per harness; `load-lock setup --yes` converges them to the recommended layout (hooks for idle wakeups, policy that survives compaction).";
 export function policyWithContext(statusSummary, configSummary) {
     let s = POLICY_BRIEF + "\n\n";
     s += statusSummary;

package/dist/shared/agent-guide.d.ts

@@ -0,0 +1,3 @@
+export declare function agentGuidePath(): string;
+/** The guide text; throws when this copy ships without docs/. */
+export declare function agentGuideText(): string;

package/dist/shared/agent-guide.js

@@ -0,0 +1,16 @@
+/**
+ * The full agent guide: docs/AGENT_GUIDE.md, shipped next to dist/ in every
+ * copy of the package (the file `load-lock agent-guide` prints). The MCP
+ * `agent_guide` tool (issue #61) returns the same file, so a plugin-only
+ * install (no skill, no CLI on PATH) can still reach the detailed guide.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { packageRoot } from "./version.js";
+export function agentGuidePath() {
+    return join(packageRoot(), "docs", "AGENT_GUIDE.md");
+}
+/** The guide text; throws when this copy ships without docs/. */
+export function agentGuideText() {
+    return readFileSync(agentGuidePath(), "utf8");
+}

package/dist/shared/client.js

@@ -29,7 +29,8 @@ import { setTimeout as delay } from "node:timers/promises";
 import { ProtocolError } from "./protocol.js";
 import { socketPath as defaultSocket, stateDir as defaultStateDir } from "../core/persist.js";
 import { probeTransport } from "./transport.js";
-import { packageVersion } from "./version.js";
+import { packageVersion, packageRoot } from "./version.js";
+import { resolveDaemonEntry } from "./installs.js";
 export class LLClient {
     sock = null;
     nextId = 1;
@@ -172,8 +173,10 @@ export class LLClient {
             });
             const sock = this.ensureSock();
             // clientVersion: lets the daemon detect version skew and self-restart
-            // onto newer on-disk code (pre-handshake daemons ignore the field).
-            sock.write(JSON.stringify({ id, method, params, clientVersion: packageVersion() }) + "\n");
+            // onto newer on-disk code (pre-handshake daemons ignore the field);
+            // clientRoot: where that code lives, so the daemon can record known
+            // runtime copies (issue #52; older daemons ignore it too).
+            sock.write(JSON.stringify({ id, method, params, clientVersion: packageVersion(), clientRoot: packageRoot() }) + "\n");
         });
     }
     /** Subscribe to daemon events targeted at agentId (or "*" for all). */
@@ -230,7 +233,12 @@ function daemonMainPath() {
     if (process.env.LOAD_LOCK_DAEMON_BIN)
         return process.env.LOAD_LOCK_DAEMON_BIN;
     const here = dirname(fileURLToPath(import.meta.url)); // .../dist/shared
-    return join(here, "..", "core", "daemon-main.js");
+    const own = join(here, "..", "core", "daemon-main.js");
+    // Issue #39: a harness (e.g. opencode's timestamped plugin cache) may
+    // prune this copy's directory while a session still executes it from
+    // memory — resolve to the PATH-installed CLI's daemon entry instead of
+    // spawning an ENOENT forever.
+    return resolveDaemonEntry(own);
 }
 /** Idempotently ensure a daemon is running and listening on `sockPath`. */
 export async function ensureDaemon(stateDir, sockPath) {
@@ -274,6 +282,10 @@ export async function ensureDaemon(stateDir, sockPath) {
                     stdio: "ignore",
                     env: { ...process.env, LOAD_LOCK_DAEMON_SPAWNED: "1" },
                 });
+                // Issue #39: an unreadable/vanished entry must surface as the
+                // "did not come up" probe failure below, not crash the host process
+                // with an uncaught ENOENT 'error' event.
+                child.on("error", () => { });
                 child.unref();
             }
         }

package/dist/shared/drift.d.ts

@@ -0,0 +1,23 @@
+export interface CliDrift {
+    /** Version of this (adapter) copy — the newer one. */
+    ownVersion: string;
+    /** Version of the PATH-resolved `load-lock` CLI copy — the older one. */
+    cliVersion: string;
+    /** Package root of the PATH-resolved CLI copy. */
+    cliPath: string;
+    /** Where this (adapter) copy lives: the npx cache, or anywhere else. */
+    ownSource: "npx-cache" | "adapter";
+    /** The one clear notice, with the exact command. */
+    message: string;
+}
+/** The notice text (exported for tests and doc-sync checks). */
+export declare function driftMessage(ownVersion: string, cliVersion: string, ownSource?: CliDrift["ownSource"]): string;
+/**
+ * Compare `ownVersion` (this adapter copy) with the version of the
+ * `load-lock` binary that PATH resolves to, by reading that copy's
+ * package.json — never by spawning the old CLI, which may predate any
+ * introspection. Returns a drift notice when the PATH CLI is strictly
+ * older; null when it is the same or newer, absent, or unreadable.
+ * Best-effort: never throws.
+ */
+export declare function detectCliDrift(ownVersion: string, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, ownPath?: string | null): CliDrift | null;

package/dist/shared/drift.js

@@ -0,0 +1,95 @@
+/**
+ * Adapter-init drift notice (issue #38): when a harness adapter copy NEWER
+ * than the PATH-installed `load-lock` CLI initializes — typically because
+ * opencode refreshed its private cache copy — surface ONE clear notice
+ * naming the exact command (`load-lock update`).
+ *
+ * Notify-first, NEVER auto-install: spawning a package manager from inside
+ * a harness plugin needs explicit opt-in; the default is to tell the
+ * agent/user, who can run `load-lock update` as an ordinary command or
+ * tool call.
+ *
+ * Honest limitation (documented in docs/OPERATIONS.md): a harness session
+ * that was already running keeps the OLD adapter code in memory until the
+ * harness restarts — this notice is emitted by the NEW copy at its init,
+ * which is the best it can do for sessions started before the refresh.
+ *
+ * npx-vs-PATH skew (issue #57): an MCP server launched via a pinned
+ * `npx -y @aron98/load-lock@<pin>` runs from the npx cache; when that copy
+ * is newer than the PATH CLI the notice names it as the npx copy.
+ *
+ * Pure and synchronous (PATH scan + package.json reads only) so both the
+ * OpenCode plugin setup and the MCP server startup can call it inline.
+ */
+import { existsSync, realpathSync, statSync } from "node:fs";
+import { dirname, join, sep as pathSep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { isWindows } from "./transport.js";
+import { enclosingPackage, npxCacheRoot, PKG_NAME } from "./pkginfo.js";
+import { compareVersions } from "./version.js";
+/** The notice text (exported for tests and doc-sync checks). */
+export function driftMessage(ownVersion, cliVersion, ownSource = "adapter") {
+    const own = ownSource === "npx-cache" ? "npx-cache copy (launched via npx)" : "adapter copy";
+    return (`load-lock: this load-lock ${own} (v${ownVersion}) is newer than the installed CLI (v${cliVersion}). ` +
+        `Run \`load-lock update\` to update the CLI on PATH and restart the daemon. ` +
+        `(Notify only — nothing is auto-installed; if your CLI predates the \`update\` command, run ` +
+        `\`npm i -g ${PKG_NAME}@latest\` instead.)`);
+}
+/** Package root of the copy this module runs from, or null. */
+function ownPackageRoot() {
+    try {
+        return enclosingPackage(dirname(dirname(fileURLToPath(import.meta.url))))?.path ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Compare `ownVersion` (this adapter copy) with the version of the
+ * `load-lock` binary that PATH resolves to, by reading that copy's
+ * package.json — never by spawning the old CLI, which may predate any
+ * introspection. Returns a drift notice when the PATH CLI is strictly
+ * older; null when it is the same or newer, absent, or unreadable.
+ * Best-effort: never throws.
+ */
+export function detectCliDrift(ownVersion, env = process.env, platform = process.platform, ownPath = ownPackageRoot()) {
+    try {
+        const npxRoot = npxCacheRoot(platform, env);
+        const ownSource = ownPath && npxRoot && (ownPath + pathSep).startsWith(npxRoot.endsWith(pathSep) ? npxRoot : npxRoot + pathSep) ? "npx-cache" : "adapter";
+        const sep = isWindows(platform) ? ";" : ":";
+        const binNames = isWindows(platform) ? ["load-lock.cmd", "load-lock.exe", "load-lock"] : ["load-lock"];
+        const dirs = (env.PATH ?? "").split(sep).filter(Boolean);
+        for (const dir of dirs) {
+            for (const bin of binNames) {
+                const binPath = join(dir, bin);
+                if (!existsSync(binPath) || !statSync(binPath).isFile())
+                    continue;
+                // Resolve through symlinks/shims to the copy that owns the bin.
+                let realBin;
+                try {
+                    realBin = realpathSync(binPath);
+                }
+                catch {
+                    realBin = binPath;
+                }
+                const found = enclosingPackage(dirname(realBin)) ?? enclosingPackage(dir);
+                if (!found || found.version === null)
+                    return null; // first PATH hit wins; cannot compare honestly
+                if (compareVersions(found.version, ownVersion) < 0) {
+                    return {
+                        ownVersion,
+                        cliVersion: found.version,
+                        cliPath: found.path,
+                        ownSource,
+                        message: driftMessage(ownVersion, found.version, ownSource),
+                    };
+                }
+                return null; // PATH CLI is same/newer — no drift
+            }
+        }
+    }
+    catch {
+        /* best-effort: unreadable PATH entries are skipped, never fatal */
+    }
+    return null; // no load-lock on PATH — nothing to compare against
+}

package/dist/shared/identity.d.ts

@@ -0,0 +1,51 @@
+export type IdentitySource = "override" | "env" | "harness-env" | "ancestor" | "fallback";
+export interface SessionIdentity {
+    /** The agentId sent to the daemon. */
+    id: string;
+    /** Short human-readable label for holder lists (defaults to the id). */
+    label: string;
+    source: IdentitySource;
+}
+/**
+ * Harness session env vars exported to child processes (verified only; a
+ * harness that is not listed falls through to the ancestor walk).
+ *
+ * - Claude Code (2.1.x): `CLAUDE_CODE_SESSION_ID` in tool/hook/MCP children;
+ *   the same value hooks receive on stdin as `session_id`.
+ * - OpenCode (2.x): the bash tool exports `OPENCODE_SESSION_ID` = the
+ *   session's `sessionID`, which is exactly the agentId the native plugin
+ *   uses — so CLI calls from an OpenCode shell share the plugin's identity
+ *   (hence no prefix).
+ */
+export declare const HARNESS_SESSION_ENV: {
+    env: string;
+    harness: string;
+    id: (sid: string) => string;
+}[];
+export interface ResolveOptions {
+    /** Explicit id (e.g. `--agent` / `agent_id`); wins over everything. */
+    override?: string;
+    /** Used when nothing session-scoped is found. */
+    fallback: string;
+    env?: NodeJS.ProcessEnv;
+    /** First process to inspect (default: the caller's parent). */
+    startPid?: number;
+    /** /proc root (tests plant a fake tree). */
+    procRoot?: string;
+    platform?: NodeJS.Platform;
+}
+export declare function sessionIdentity(opts: ResolveOptions): SessionIdentity;
+export interface ProcInfo {
+    pid: number;
+    ppid: number;
+    comm: string;
+    /** /proc/<pid>/stat field 22 (clock ticks since boot). */
+    startTime: string;
+}
+export declare function readProc(pid: number, procRoot?: string): ProcInfo | null;
+/**
+ * First ancestor (starting at `startPid`, inclusive) that is not a shell or
+ * launcher wrapper. null when the walk reaches init (pid <= 1) or /proc is
+ * unreadable — an orphaned caller has no harness to share an identity with.
+ */
+export declare function harnessAncestor(startPid: number, procRoot?: string): ProcInfo | null;

package/dist/shared/identity.js

@@ -0,0 +1,116 @@
+/**
+ * Session-derived agent identity (issue #49, umbrella #47 item 1).
+ *
+ * The daemon routes offers, `pending` and op-key duplicate suppression by
+ * agentId, so the id must be "one per harness session": the same for every
+ * call a session makes (whichever wiring — CLI, MCP server, hook — made it),
+ * and different between sessions. Resolution order:
+ *
+ *   1. explicit override: `--agent` / `agent_id` (callers pass it as
+ *      `override`) or `LOAD_LOCK_AGENT`;
+ *   2. a harness session env var, where the harness exports one to the
+ *      processes it spawns (see HARNESS_SESSION_ENV);
+ *   3. the stable harness ancestor process: walk up from the caller's
+ *      parent past shells and launcher wrappers (npm/npx, env, ...) to the
+ *      first real ancestor, identified by pid + /proc start time (pid-reuse
+ *      safe). Linux only; elsewhere this step is skipped;
+ *   4. the caller's fallback (the CLI's legacy `cli:$USER@$HOSTNAME`).
+ *
+ * Pure apart from reading /proc; every input is injectable for tests.
+ */
+import { readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+/**
+ * Harness session env vars exported to child processes (verified only; a
+ * harness that is not listed falls through to the ancestor walk).
+ *
+ * - Claude Code (2.1.x): `CLAUDE_CODE_SESSION_ID` in tool/hook/MCP children;
+ *   the same value hooks receive on stdin as `session_id`.
+ * - OpenCode (2.x): the bash tool exports `OPENCODE_SESSION_ID` = the
+ *   session's `sessionID`, which is exactly the agentId the native plugin
+ *   uses — so CLI calls from an OpenCode shell share the plugin's identity
+ *   (hence no prefix).
+ */
+export const HARNESS_SESSION_ENV = [
+    { env: "CLAUDE_CODE_SESSION_ID", harness: "claude-code", id: (sid) => "claude-code:" + sid },
+    { env: "OPENCODE_SESSION_ID", harness: "opencode", id: (sid) => sid },
+];
+/** Interpreters/shells that sit between a harness and the CLI per tool call. */
+const SHELLS = new Set([
+    "sh", "bash", "dash", "zsh", "ksh", "mksh", "fish", "tcsh", "csh", "nu", "pwsh", "busybox",
+    "env", "timeout", "nohup", "setsid", "stdbuf", "nice", "xargs",
+]);
+/** Launcher scripts recognized in argv[0..1] (node/bun running npm/npx, nested load-lock, plugin launcher). */
+const WRAPPER_SCRIPTS = new Set([
+    "npm", "npx", "npm-cli.js", "npx-cli.js", "pnpm", "pnpx", "yarn", "bunx", "load-lock", "load-lock.mjs",
+]);
+export function sessionIdentity(opts) {
+    const env = opts.env ?? process.env;
+    const override = opts.override?.trim();
+    if (override)
+        return { id: override, label: override, source: "override" };
+    const envAgent = env.LOAD_LOCK_AGENT?.trim();
+    if (envAgent)
+        return { id: envAgent, label: envAgent, source: "env" };
+    for (const h of HARNESS_SESSION_ENV) {
+        const sid = env[h.env]?.trim();
+        if (sid)
+            return { id: h.id(sid), label: `${h.harness}:${sid.slice(0, 8)}`, source: "harness-env" };
+    }
+    const platform = opts.platform ?? process.platform;
+    if (platform === "linux") {
+        const anc = harnessAncestor(opts.startPid ?? process.ppid, opts.procRoot ?? "/proc");
+        if (anc) {
+            return { id: `proc:${anc.pid}:${anc.startTime}`, label: `${anc.comm}:${anc.pid}`, source: "ancestor" };
+        }
+    }
+    return { id: opts.fallback, label: opts.fallback, source: "fallback" };
+}
+export function readProc(pid, procRoot = "/proc") {
+    try {
+        const stat = readFileSync(join(procRoot, String(pid), "stat"), "utf8");
+        // comm is parenthesized and may itself contain spaces or parens.
+        const open = stat.indexOf("(");
+        const close = stat.lastIndexOf(")");
+        if (open < 0 || close < open)
+            return null;
+        const rest = stat.slice(close + 2).split(" ");
+        const ppid = Number(rest[1]);
+        const startTime = rest[19];
+        if (!Number.isInteger(ppid) || !startTime)
+            return null;
+        return { pid, ppid, comm: stat.slice(open + 1, close), startTime };
+    }
+    catch {
+        return null;
+    }
+}
+function isWrapper(p, procRoot) {
+    if (SHELLS.has(p.comm))
+        return true;
+    let argv = [];
+    try {
+        argv = readFileSync(join(procRoot, String(p.pid), "cmdline"), "utf8").split("\0");
+    }
+    catch {
+        return false;
+    }
+    return argv.slice(0, 2).some((a) => a && WRAPPER_SCRIPTS.has(basename(a)));
+}
+/**
+ * First ancestor (starting at `startPid`, inclusive) that is not a shell or
+ * launcher wrapper. null when the walk reaches init (pid <= 1) or /proc is
+ * unreadable — an orphaned caller has no harness to share an identity with.
+ */
+export function harnessAncestor(startPid, procRoot = "/proc") {
+    let pid = startPid;
+    for (let depth = 0; depth < 32 && pid > 1; depth++) {
+        const p = readProc(pid, procRoot);
+        if (!p)
+            return null;
+        if (!isWrapper(p, procRoot))
+            return p;
+        pid = p.ppid;
+    }
+    return null;
+}

package/dist/shared/installs.d.ts

@@ -0,0 +1,39 @@
+/** All `load-lock` binaries found on PATH, in PATH order (files only). */
+export declare function pathBinCandidates(platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): string[];
+export interface PathInstall {
+    /** Package root of the install (the directory containing package.json). */
+    path: string;
+    /** Version from that package.json, or null when unreadable. */
+    version: string | null;
+}
+/**
+ * The FIRST PATH-resolved `load-lock`'s enclosing install. Symlinks are
+ * resolved (npm/bun global layouts symlink the bin into the install), and a
+ * plain shim script falls back to the PATH directory itself.
+ */
+export declare function pathInstall(platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): PathInstall | null;
+export interface InstallDrift {
+    /** Version of THIS running copy (src/shared/version.ts, cached). */
+    ownVersion: string;
+    /** Version of the PATH-resolved CLI install, or null when unresolvable. */
+    pathVersion: string | null;
+    /** True when the PATH install is strictly newer than this running copy. */
+    stale: boolean;
+}
+/**
+ * In-memory staleness probe (issue #39): a harness that loads plugin code
+ * once at startup (opencode never hot-reloads plugins) keeps executing the
+ * old copy after `npm i -g @aron98/load-lock@latest` — this detects exactly
+ * that: the running copy vs. what the PATH `load-lock` resolves to.
+ */
+export declare function detectInstallDrift(platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): InstallDrift;
+/**
+ * Daemon entry to auto-spawn (issue #39, hypothesis 2): normally the running
+ * copy's own dist/core/daemon-main.js. When that file has vanished — a
+ * harness may prune its old plugin-cache timestamped dir while a session
+ * still runs that copy in memory — spawn from the PATH-installed CLI's copy
+ * instead, which is what the user most recently installed. If nothing on
+ * PATH resolves either, the own path is returned unchanged so the spawn
+ * fails with the original error rather than a misleading one.
+ */
+export declare function resolveDaemonEntry(ownEntry: string, platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): string;

package/dist/shared/installs.js

@@ -0,0 +1,101 @@
+/**
+ * Shared install-location helpers (issue #39): resolving the PATH-installed
+ * copy of the CLI, detecting version drift between the running copy and that
+ * install, and finding a usable daemon entry when the running copy's own
+ * entry has vanished (e.g. a harness pruned an old plugin-cache copy while a
+ * session still executes it from memory).
+ *
+ * `enclosingPackage` / `PKG_NAME` live in `./pkginfo.js` (shipped by #38's
+ * adapter-init drift notice) and are reused here; this module adds the
+ * PATH-install scan and the two #39-specific probes on top of them:
+ * `detectInstallDrift` (running copy OLDER than the PATH CLI — the mirror
+ * image of pkginfo-neighbor `drift.ts`'s `detectCliDrift`, which flags the
+ * PATH CLI being older) and `resolveDaemonEntry` (spawn fallback when this
+ * copy's own entry has vanished).
+ *
+ * Everything here is best-effort and never throws: missing paths, unreadable
+ * files, and unexpected layouts yield null / false / the input unchanged.
+ */
+import { existsSync, realpathSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { isWindows } from "./transport.js";
+import { compareVersions, packageVersion } from "./version.js";
+import { enclosingPackage } from "./pkginfo.js";
+/** All `load-lock` binaries found on PATH, in PATH order (files only). */
+export function pathBinCandidates(platform = process.platform, env = process.env) {
+    const binNames = isWindows(platform) ? ["load-lock.cmd", "load-lock.exe", "load-lock"] : ["load-lock"];
+    const sep = isWindows(platform) ? ";" : ":";
+    const out = [];
+    for (const dir of (env.PATH ?? "").split(sep).filter(Boolean)) {
+        for (const bin of binNames) {
+            try {
+                const binPath = join(dir, bin);
+                if (statSync(binPath).isFile())
+                    out.push(binPath);
+            }
+            catch {
+                /* unreadable PATH entry — skip */
+            }
+        }
+    }
+    return out;
+}
+/**
+ * The FIRST PATH-resolved `load-lock`'s enclosing install. Symlinks are
+ * resolved (npm/bun global layouts symlink the bin into the install), and a
+ * plain shim script falls back to the PATH directory itself.
+ */
+export function pathInstall(platform = process.platform, env = process.env) {
+    for (const binPath of pathBinCandidates(platform, env)) {
+        let realBin = binPath;
+        try {
+            realBin = realpathSync(binPath);
+        }
+        catch {
+            /* keep the raw path */
+        }
+        // A shim/wrapper script is not itself the copy — resolve through its
+        // enclosing package, falling back to the PATH dir (same logic the
+        // doctor's multi-copy scan uses).
+        const found = enclosingPackage(dirname(realBin)) ?? enclosingPackage(dirname(binPath));
+        if (found)
+            return { path: found.path, version: found.version };
+    }
+    return null;
+}
+/**
+ * In-memory staleness probe (issue #39): a harness that loads plugin code
+ * once at startup (opencode never hot-reloads plugins) keeps executing the
+ * old copy after `npm i -g @aron98/load-lock@latest` — this detects exactly
+ * that: the running copy vs. what the PATH `load-lock` resolves to.
+ */
+export function detectInstallDrift(platform = process.platform, env = process.env) {
+    const ownVersion = packageVersion();
+    const inst = pathInstall(platform, env);
+    const pathVersion = inst?.version ?? null;
+    return {
+        ownVersion,
+        pathVersion,
+        stale: pathVersion != null && compareVersions(pathVersion, ownVersion) > 0,
+    };
+}
+/**
+ * Daemon entry to auto-spawn (issue #39, hypothesis 2): normally the running
+ * copy's own dist/core/daemon-main.js. When that file has vanished — a
+ * harness may prune its old plugin-cache timestamped dir while a session
+ * still runs that copy in memory — spawn from the PATH-installed CLI's copy
+ * instead, which is what the user most recently installed. If nothing on
+ * PATH resolves either, the own path is returned unchanged so the spawn
+ * fails with the original error rather than a misleading one.
+ */
+export function resolveDaemonEntry(ownEntry, platform = process.platform, env = process.env) {
+    if (existsSync(ownEntry))
+        return ownEntry;
+    const inst = pathInstall(platform, env);
+    if (inst) {
+        const candidate = join(inst.path, "dist", "core", "daemon-main.js");
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return ownEntry;
+}

package/dist/shared/pkginfo.d.ts

@@ -0,0 +1,25 @@
+/** Package name of this package (used to find enclosing package roots). */
+export declare const PKG_NAME = "@aron98/load-lock";
+export interface PkgRootInfo {
+    /** Package root (the directory holding the matching package.json). */
+    path: string;
+    /** Version string, or null when the package.json has no/invalid version. */
+    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): PkgRootInfo | null;
+/** Cache root the way opencode resolves it (its npm cache lives under it). */
+export declare function opencodeCacheRoot(platform: NodeJS.Platform, env: NodeJS.ProcessEnv): string | null;
+/**
+ * Root of npx's install cache (`<npm cache>/_npx`), where `npx -y
+ * @aron98/load-lock@<pin>` (skill / ACE / pinned MCP entries) installs its
+ * copies as `<root>/<hash>/node_modules/@aron98/load-lock`. The npm cache
+ * dir follows npm's own resolution: `npm_config_cache` (set by npm/npx for
+ * the processes they launch, or by the user), else `%LocalAppData%\npm-cache`
+ * on Windows, else `~/.npm`.
+ */
+export declare function npxCacheRoot(platform: NodeJS.Platform, env: NodeJS.ProcessEnv): string | null;

package/dist/shared/pkginfo.js

@@ -0,0 +1,70 @@
+/**
+ * Package-identity plumbing shared by copy detection (cli/copies.ts), the
+ * update command (cli/update.ts), and the adapter drift notice
+ * (shared/drift.ts): the package name and the "which package root
+ * contains this file" climb.
+ *
+ * Pure functions of their arguments (no process.env / import.meta at call
+ * time beyond what callers pass in) so tests can plant layouts.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+/** Package name of this package (used to find enclosing package roots). */
+export 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;
+}
+/** Cache root the way opencode resolves it (its npm cache lives under it). */
+export 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");
+}
+/**
+ * Root of npx's install cache (`<npm cache>/_npx`), where `npx -y
+ * @aron98/load-lock@<pin>` (skill / ACE / pinned MCP entries) installs its
+ * copies as `<root>/<hash>/node_modules/@aron98/load-lock`. The npm cache
+ * dir follows npm's own resolution: `npm_config_cache` (set by npm/npx for
+ * the processes they launch, or by the user), else `%LocalAppData%\npm-cache`
+ * on Windows, else `~/.npm`.
+ */
+export function npxCacheRoot(platform, env) {
+    const configured = env.npm_config_cache || env.NPM_CONFIG_CACHE;
+    if (configured)
+        return join(configured, "_npx");
+    if (platform === "win32")
+        return env.LOCALAPPDATA ? join(env.LOCALAPPDATA, "npm-cache", "_npx") : null;
+    return join(env.HOME ?? homedir(), ".npm", "_npx");
+}