@aron98/load-lock 1.4.0 → 1.5.0

package/dist/dashboard/feed.js

@@ -1,10 +1,13 @@
 import { buildDashboardView } from "./view.js";
+import { detectInstallDrift } from "../shared/installs.js";
 const DEFAULTS = {
     eventHistory: 60,
     slowRefreshMs: 15_000,
     refreshDebounceMs: 40,
     inspectEveryMs: 60_000,
     reconnectBaseMs: 250,
+    driftCheckMs: 15_000,
+    driftSurface: "cli",
 };
 export class DashboardFeed {
     client;
@@ -20,10 +23,14 @@ export class DashboardFeed {
     daemonStartedAt = 0;
     refreshTimer = null;
     slowTimer = null;
+    driftTimer = null;
+    drift = null;
     stopped = false;
     unsub = null;
     connecting = null;
     viewSeq = 0;
+    /** daemonVersion seen at the previous resync — powers the "restarted onto" note. */
+    lastDaemonVersion;
     /** Fired whenever the rendered view might have changed (state or data). */
     onChange;
     /** Fired on connection-state transitions. */
@@ -63,7 +70,9 @@ export class DashboardFeed {
             typeof this.client.onDisconnect === "function"
                 ? (this.client.onDisconnect(() => void this.handleDisconnect()) ?? undefined)
                 : null;
-        await this.connectAndSync();
+        // Timers are installed BEFORE the first connect: a failed initial
+        // connect must not leave the feed without its slow-refresh/drift
+        // timers once the reconnect loop eventually recovers (issue #39 H3).
         this.slowTimer =
             this.opts.slowRefreshMs > 0
                 ? setInterval(() => {
@@ -72,6 +81,27 @@ export class DashboardFeed {
                 }, this.opts.slowRefreshMs)
                 : null;
         this.slowTimer?.unref?.();
+        this.driftTimer =
+            this.opts.driftCheckMs > 0
+                ? setInterval(() => {
+                    void this.refreshDrift();
+                }, this.opts.driftCheckMs)
+                : null;
+        this.driftTimer?.unref?.();
+        void this.refreshDrift();
+        try {
+            await this.connectAndSync();
+        }
+        catch (e) {
+            // Issue #39 (hypothesis 3): previously a failed initial connect
+            // rejected start() with no socket ever attached, so no close event
+            // could ever fire handleDisconnect and the feed wedged in
+            // "connecting" forever. Enter the standard reconnect loop instead —
+            // the loop owns recovery, and start() still reports the failure.
+            this.setState("reconnecting");
+            void this.reconnectLoop();
+            throw e;
+        }
     }
     async stop() {
         this.stopped = true;
@@ -79,8 +109,11 @@ export class DashboardFeed {
             clearTimeout(this.refreshTimer);
         if (this.slowTimer)
             clearInterval(this.slowTimer);
+        if (this.driftTimer)
+            clearInterval(this.driftTimer);
         this.refreshTimer = null;
         this.slowTimer = null;
+        this.driftTimer = null;
         this.unsub?.();
         this.unsub = null;
         this.client.close();
@@ -112,12 +145,23 @@ export class DashboardFeed {
         let restartNote;
         if (daemonStartChanged || evRes.latestEventId < this.latestEventId) {
             // Daemon restarted: ids restarted from scratch. Reset and re-pull.
-            restartNote = `daemon restarted (pid ${status.daemon?.pid ?? "?"}); event history re-synced`;
+            const pid = status.daemon?.pid ?? "?";
+            const newVersion = status.daemon?.daemonVersion;
+            // Issue #39 (deliverable d): when the v1.3.0 handshake reports a
+            // DIFFERENT version than the daemon we were talking to, say which
+            // version the daemon restarted onto (e.g. after an update).
+            if (this.lastDaemonVersion && newVersion && newVersion !== this.lastDaemonVersion) {
+                restartNote = `daemon restarted onto v${newVersion} (was v${this.lastDaemonVersion}; pid ${pid}); event history re-synced`;
+            }
+            else {
+                restartNote = `daemon restarted (pid ${pid}); event history re-synced`;
+            }
             this.events = [];
             this.latestEventId = 0;
             const fresh = await this.client.request("events", { sinceEventId: 0 });
             this.mergeEvents(fresh.events, fresh.latestEventId);
         }
+        this.lastDaemonVersion = status.daemon?.daemonVersion;
         this.restartNote = restartNote;
         if (this.inspectAt === 0 || Date.now() - this.inspectAt > this.opts.inspectEveryMs) {
             await this.refreshInspect();
@@ -240,6 +284,22 @@ export class DashboardFeed {
         await this.client.request("admin_release", { requestId });
         await this.refresh().catch(() => { });
     }
+    /**
+     * Re-probe install drift (running copy vs PATH-resolved CLI) and surface
+     * it on the next view. Public so surfaces can trigger it on demand
+     * (e.g. right after a plugin's panel regains focus).
+     */
+    refreshDrift() {
+        if (this.stopped || this.opts.driftCheckMs === 0)
+            return;
+        try {
+            this.drift = detectInstallDrift();
+        }
+        catch {
+            this.drift = null;
+        }
+        this.emitChange();
+    }
     /** Render-ready snapshot; countdowns are computed at `now`. */
     view(now = Date.now()) {
         return buildDashboardView({
@@ -250,6 +310,8 @@ export class DashboardFeed {
             state: this.state,
             lastSyncAt: this.lastSyncAt,
             daemonRestartNote: this.restartNote,
+            installDrift: this.drift,
+            driftSurface: this.opts.driftSurface,
             now,
         });
     }

package/dist/dashboard/frame.js

@@ -70,6 +70,8 @@ export function renderFrame(view, width = 100, height = 40) {
         push(`note: ${view.daemonRestartNote}`);
     if (view.versionSkewNote)
         push(`note: ${view.versionSkewNote}`);
+    if (view.installDriftNote)
+        push(`note: ${view.installDriftNote}`);
     if (view.machine) {
         const m = view.machine;
         const cg = m.cgroupCpuQuota != null ? ` · cgroup ${m.cgroupVersion ?? ""} quota ${m.cgroupCpuQuota / 100} CPU` : "";

package/dist/dashboard/view.d.ts

@@ -9,6 +9,7 @@
  * "now" is always an explicit parameter, which makes countdowns testable.
  */
 import type * as P from "../shared/protocol.js";
+import type { InstallDrift } from "../shared/installs.js";
 /** Connection state of the dashboard's daemon feed. */
 export type FeedState = "connecting" | "live" | "reconnecting" | "down";
 export interface HolderCard {
@@ -116,6 +117,12 @@ export interface DashboardView {
     daemonRestartNote?: string;
     /** Set when the running daemon is older than the installed copy. */
     versionSkewNote?: string;
+    /**
+     * Set when the RUNNING copy is older than the PATH-resolved CLI install
+     * (issue #39: harnesses like opencode load plugin code once and never
+     * hot-reload it, so an update leaves this session running stale code).
+     */
+    installDriftNote?: string;
     daemon: DaemonView | null;
     pools: PoolView[];
     events: EventLine[];
@@ -148,6 +155,10 @@ export interface DashboardInputs {
     state: FeedState;
     lastSyncAt: number;
     daemonRestartNote?: string;
+    /** Running-copy vs PATH-install drift probe result (null = unknown). */
+    installDrift?: InstallDrift | null;
+    /** Wording hint for the drift note; the TUI plugin passes "opencode". */
+    driftSurface?: "cli" | "opencode";
     now: number;
 }
 export declare function buildDashboardView(inps: DashboardInputs): DashboardView;

package/dist/dashboard/view.js

@@ -186,10 +186,23 @@ export function buildDashboardView(inps) {
         : null;
     // Newest first; keep the tail (feed already bounds history length).
     const evs = [...inps.events].reverse();
+    // Issue #39: make in-memory staleness visible. A harness that loads
+    // plugin code once (opencode never hot-reloads plugins) keeps running
+    // the OLD copy after `npm i -g @aron98/load-lock@latest`; the panel can
+    // only hint at the recovery action, which differs per surface.
+    const drift = inps.installDrift;
+    let installDriftNote;
+    if (drift?.stale && drift.pathVersion) {
+        installDriftNote =
+            inps.driftSurface === "opencode"
+                ? `plugin updated — restart opencode to pick up v${drift.pathVersion} (this session still runs v${drift.ownVersion}; opencode does not hot-reload plugins)`
+                : `PATH CLI v${drift.pathVersion} is newer than this copy v${drift.ownVersion} — you are running a stale install`;
+    }
     return {
         now,
         state: inps.state,
         daemonRestartNote: inps.daemonRestartNote,
+        installDriftNote,
         versionSkewNote: d && typeof d.daemonVersion === "string" && compareVersions(d.daemonVersion, packageVersion()) < 0
             ? `daemon v${d.daemonVersion} is older than installed v${packageVersion()} — it self-restarts on newer-client contact`
             : undefined,

package/dist/mcp/server.d.ts

@@ -16,11 +16,18 @@
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { LLClient } from "../shared/client.js";
+import { type CliDrift } from "../shared/drift.js";
 export interface McpServerOptions {
     client: LLClient;
     serverName?: string;
     /** Overridden by OpenCode's per-request session metadata when present. */
     agentId?: string;
+    /**
+     * CLI-drift notice to surface (issue #38). Defaults to auto-detection at
+     * build time (this adapter copy vs. the PATH-resolved CLI copy);
+     * pass null to suppress / a value to inject in tests.
+     */
+    drift?: CliDrift | null;
 }
 export declare function buildServer(opts: McpServerOptions): McpServer;
 export declare function runStdioMcp(opts?: {

package/dist/mcp/server.js

@@ -23,6 +23,8 @@ import { POLICY_BRIEF } from "../policy/text.js";
 import { waitForTurn, WaitAbortedError } from "../shared/wait-turn.js";
 import { waitForLocalJob, waitForTrackedJob } from "../shared/wait-completion.js";
 import { killProcessGroup } from "../shared/transport.js";
+import { detectCliDrift } from "../shared/drift.js";
+import { packageVersion } from "../shared/version.js";
 const ACQUIRE_DESC = `Acquire a machine-wide permit before starting resource-intensive local work (full builds, test suites, big compiles/containers).
 
 Pass a short reason and a stable op_key identifying the pending operation (duplicate acquires for the same op_key return the existing request — do not invent a new key while one is live). Set wait_ms (default a few seconds) to block briefly for capacity instead of returning queued immediately; keep doing light work while queued. You will receive an offer to claim when capacity frees. Never start heavy work while merely queued.`;
@@ -31,7 +33,14 @@ const RELEASE_DESC = `Release a held permit immediately after the heavy work fin
 export function buildServer(opts) {
     const client = opts.client;
     const defaultAgent = opts.agentId ?? "agt_" + process.pid.toString(36) + Math.random().toString(36).slice(2, 8);
-    const server = new McpServer({ name: opts.serverName ?? "load-lock", version: "0.1.0" }, { instructions: POLICY_BRIEF });
+    // Drift notice (issue #38): one clear notice naming the exact command when
+    // this adapter copy is newer than the PATH-installed CLI. Notify only —
+    // never auto-install. Printed to stderr at init and embedded in the
+    // initialize instructions so any MCP client sees it exactly once.
+    const drift = opts.drift !== undefined ? opts.drift : detectCliDrift(packageVersion());
+    if (drift)
+        process.stderr.write(drift.message + "\n");
+    const server = new McpServer({ name: opts.serverName ?? "load-lock", version: "0.1.0" }, { instructions: POLICY_BRIEF + (drift ? "\n\n" + drift.message : "") });
     const json = (v) => ({
         content: [{ type: "text", text: JSON.stringify(v, null, 2) }],
     });

package/dist/shared/client.js

@@ -30,6 +30,7 @@ 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 { resolveDaemonEntry } from "./installs.js";
 export class LLClient {
     sock = null;
     nextId = 1;
@@ -230,7 +231,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 +280,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,21 @@
+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;
+    /** 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): 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): CliDrift | null;

package/dist/shared/drift.js

@@ -0,0 +1,77 @@
+/**
+ * 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.
+ *
+ * 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 } from "node:path";
+import { isWindows } from "./transport.js";
+import { enclosingPackage, 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) {
+    return (`load-lock: this load-lock adapter copy (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.)`);
+}
+/**
+ * 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) {
+    try {
+        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,
+                        message: driftMessage(ownVersion, found.version),
+                    };
+                }
+                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/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,16 @@
+/** 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;

package/dist/shared/pkginfo.js

@@ -0,0 +1,54 @@
+/**
+ * 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");
+}

package/dist/test/reconnect.test.d.ts

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