@aron98/load-lock 1.4.0 → 1.6.0

package/dist/core/persist.js

@@ -19,35 +19,73 @@ export function stateDir(override) {
 export function socketPath(override) {
     return resolveSocketPath(process.platform, process.env, override);
 }
+// --------------------------------------------------------------------------
+// Format version + compatibility (issue #51). Several runtime copies may share
+// one state dir, so an OLDER daemon can load files written by a NEWER one
+// (downgrade) and vice versa. The promise (docs/ARCHITECTURE.md):
+//  - format changes are additive; readers ignore what they don't understand;
+//  - unknown fields survive a rewrite (config.json: top level, inside
+//    `config`, inside pools; journal: per entry while the entry is live);
+//  - unknown journal entry kinds are skipped (reported), never fatal;
+//  - an incompatible change would use a NEW file name, never reinterpret
+//    these files.
+// Files written before versioning carry no formatVersion (=> 0).
+/** Format version this code writes into config.json and journal entries. */
+export const STATE_FORMAT_VERSION = 1;
+const KNOWN_STATE_KEYS = new Set(["formatVersion", "config", "history"]);
+function isObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
 export function loadState(dir) {
     const path = join(dir, "config.json");
     if (!existsSync(path))
-        return { config: defaultConfig(), history: [] };
+        return { config: defaultConfig(), history: [], formatVersion: STATE_FORMAT_VERSION };
     const raw = JSON.parse(readFileSync(path, "utf8"));
-    const config = { ...defaultConfig(), ...raw.config };
+    // Unknown fields inside `config` ride along in memory and are written back
+    // by saveState (configure() mutates in place).
+    const config = { ...defaultConfig(), ...(isObject(raw?.config) ? raw.config : {}) };
     // Defensive: always at least the default pool.
-    if (!config.pools || Object.keys(config.pools).length === 0)
+    if (!isObject(config.pools) || Object.keys(config.pools).length === 0)
         config.pools = { heavy: { capacity: 1 } };
-    return { config, history: Array.isArray(raw.history) ? raw.history : [] };
+    const formatVersion = typeof raw?.formatVersion === "number" ? raw.formatVersion : 0;
+    return { config, history: Array.isArray(raw?.history) ? raw.history : [], formatVersion };
 }
 export function saveState(dir, config, history) {
     mkdirSync(dir, { recursive: true });
     const path = join(dir, "config.json");
+    // Preserve top-level fields written by a newer format (never rewrite
+    // destructively). Best-effort: an unreadable file has nothing to keep.
+    const extra = {};
+    try {
+        const prev = JSON.parse(readFileSync(path, "utf8"));
+        if (isObject(prev))
+            for (const [k, v] of Object.entries(prev))
+                if (!KNOWN_STATE_KEYS.has(k))
+                    extra[k] = v;
+    }
+    catch {
+        /* missing or corrupt: nothing to preserve */
+    }
     const tmp = join(dirname(path), ".config.json.tmp-" + process.pid);
-    writeFileSync(tmp, JSON.stringify({ config, history }, null, 2) + "\n", { mode: 0o644 });
+    writeFileSync(tmp, JSON.stringify({ formatVersion: STATE_FORMAT_VERSION, ...extra, config, history }, null, 2) + "\n", { mode: 0o644 });
     renameSync(tmp, path); // atomic on POSIX
 }
 // --------------------------------------------------------------------------
-// Journal: held permits, persisted so a daemon restart can conservatively
-// reconcile running ownership (tracked jobs keep their permit; confirmed-dead
-// jobs release; queued/offered requests are NOT journaled — agents re-acquire).
+// Journal: held permits AND queued/offered requests, persisted so a daemon
+// restart can conservatively reconcile running ownership (tracked jobs keep
+// their permit; confirmed-dead jobs release) and re-queue waiters FIFO with
+// the same requestIds (offered entries come back as queued; issue #34).
 export function journalPath(dir) {
     return join(dir, "journal.json");
 }
+// The journal stays a bare JSON array (what every released daemon reads); the
+// format version is stamped per entry. An object form `{ entries: [...] }` is
+// accepted too, so a future format may wrap the array without breaking us.
 export function loadJournal(dir) {
     try {
         const raw = JSON.parse(readFileSync(journalPath(dir), "utf8"));
-        return Array.isArray(raw) ? raw : [];
+        const list = Array.isArray(raw) ? raw : isObject(raw) && Array.isArray(raw.entries) ? raw.entries : [];
+        return list.filter(isObject);
     }
     catch {
         return [];
@@ -56,6 +94,7 @@ export function loadJournal(dir) {
 export function saveJournal(dir, entries) {
     const path = journalPath(dir);
     const tmp = join(dirname(path), ".journal.json.tmp-" + process.pid);
-    writeFileSync(tmp, JSON.stringify(entries, null, 2) + "\n", { mode: 0o644 });
+    const stamped = entries.map((e) => ({ formatVersion: STATE_FORMAT_VERSION, ...e }));
+    writeFileSync(tmp, JSON.stringify(stamped, null, 2) + "\n", { mode: 0o644 });
     renameSync(tmp, path);
 }

package/dist/core/state.d.ts

@@ -56,6 +56,8 @@ interface Entry {
     leaseDeadline?: number;
     lastSeen?: number;
     enqueuedAt?: number;
+    /** Journal fields this version doesn't know (written by a newer daemon); written back as-is (issue #51). */
+    journalExtra?: Record<string, unknown>;
 }
 export declare class Machine {
     config: MachineConfig;
@@ -197,6 +199,12 @@ export declare class Machine {
      *    alive => keep (same token, so a late explicit release still works).
      *  - claimed: keep the start deadline (reclaimed by tick if already past).
      *  - untracked: keep, with a FRESH lease window from restore time.
+     *  - forward compatibility (issue #51): entries of an unknown `state`
+     *    (written by a newer daemon) or missing required fields are skipped
+     *    and reported, never fatal; a held entry with an unknown `phase` is
+     *    kept as untracked with a fresh lease (capacity stays accounted, but
+     *    the lease reclaims it if nobody heartbeats). Unknown fields are kept
+     *    and written back to the journal while the entry lives.
      */
     restore(journal: JournalEntry[], liveness: (e: {
         pid?: number;
@@ -206,6 +214,7 @@ export declare class Machine {
         kept: number;
         releasedDead: number;
         queued: number;
+        skipped: number;
     };
 }
 export {};

package/dist/core/state.js

@@ -48,6 +48,21 @@ export function defaultConfig() {
         guidance: {},
     };
 }
+/** Journal entry fields this version understands; everything else is carried through (issue #51). */
+const KNOWN_JOURNAL_KEYS = new Set([
+    "formatVersion", "requestId", "pool", "agentId", "agentLabel", "cwd", "opKey", "reason", "weight",
+    "permitToken", "phase", "pid", "pgid", "pidStartTime", "claimedAt", "startedAt", "leaseDeadline", "state", "enqueuedAt",
+]);
+const KNOWN_PHASES = new Set(["claimed", "running_tracked", "running_untracked"]);
+function journalExtra(j) {
+    let out;
+    for (const [k, v] of Object.entries(j)) {
+        if (KNOWN_JOURNAL_KEYS.has(k))
+            continue;
+        (out ??= {})[k] = v;
+    }
+    return out;
+}
 const rid = () => "req_" + randomBytes(12).toString("hex");
 const tok = (p) => p + "_" + randomBytes(16).toString("hex");
 export class Machine {
@@ -793,8 +808,9 @@ export class Machine {
         }
         this.config.version += 1;
         if (c.pools) {
+            // Spread the previous pool config so fields from a newer format survive (issue #51).
             for (const [name, pc] of Object.entries(c.pools))
-                this.config.pools[name] = { capacity: pc.capacity };
+                this.config.pools[name] = { ...this.config.pools[name], capacity: pc.capacity };
         }
         if (c.offerTimeoutMs !== undefined)
             this.config.offerTimeoutMs = c.offerTimeoutMs;
@@ -853,6 +869,7 @@ export class Machine {
             if (e.state !== "held")
                 continue;
             out.push({
+                ...e.journalExtra,
                 requestId: e.id,
                 pool: e.pool,
                 agentId: e.agentId,
@@ -876,6 +893,7 @@ export class Machine {
             if (e.state !== "queued" && e.state !== "offered")
                 continue;
             out.push({
+                ...e.journalExtra,
                 requestId: e.id,
                 pool: e.pool,
                 agentId: e.agentId,
@@ -901,12 +919,27 @@ export class Machine {
      *    alive => keep (same token, so a late explicit release still works).
      *  - claimed: keep the start deadline (reclaimed by tick if already past).
      *  - untracked: keep, with a FRESH lease window from restore time.
+     *  - forward compatibility (issue #51): entries of an unknown `state`
+     *    (written by a newer daemon) or missing required fields are skipped
+     *    and reported, never fatal; a held entry with an unknown `phase` is
+     *    kept as untracked with a fresh lease (capacity stays accounted, but
+     *    the lease reclaims it if nobody heartbeats). Unknown fields are kept
+     *    and written back to the journal while the entry lives.
      */
     restore(journal, liveness) {
         let kept = 0;
         let releasedDead = 0;
+        let skipped = 0;
         const queuedEntries = [];
         for (const j of journal) {
+            const st = j.state;
+            if ((st !== undefined && st !== "held" && st !== "queued") ||
+                typeof j.requestId !== "string" ||
+                typeof j.pool !== "string" ||
+                typeof j.agentId !== "string") {
+                skipped++;
+                continue;
+            }
             if (j.state === "queued") {
                 queuedEntries.push({ j, at: j.enqueuedAt ?? j.claimedAt });
                 continue;
@@ -929,7 +962,10 @@ export class Machine {
                 pidStartTime: j.pidStartTime,
                 startedAt: j.startedAt,
                 lastSeen: this.now(),
+                journalExtra: journalExtra(j),
             };
+            if (!KNOWN_PHASES.has(e.phase))
+                e.phase = "running_untracked";
             if (e.phase === "claimed") {
                 e.startDeadline = j.claimedAt + this.config.startTimeoutMs;
             }
@@ -974,6 +1010,7 @@ export class Machine {
                 state: "queued",
                 since: this.now(),
                 enqueuedAt: j.enqueuedAt ?? j.claimedAt,
+                journalExtra: journalExtra(j),
             };
             this.entries.set(e.id, e);
             this.byKey.set(`${e.agentId}\u0000${e.opKey}`, e.id);
@@ -988,8 +1025,9 @@ export class Machine {
         this.pushEvent({
             type: "daemon_recovered",
             targetAgent: "*",
-            detail: `restored ${kept} held permit(s) from journal (${releasedDead} confirmed dead and released); re-queued ${queued} waiting request(s)`,
+            detail: `restored ${kept} held permit(s) from journal (${releasedDead} confirmed dead and released); re-queued ${queued} waiting request(s)` +
+                (skipped ? `; skipped ${skipped} unrecognized journal entr${skipped === 1 ? "y" : "ies"} (newer format?)` : ""),
         });
-        return { kept, releasedDead, queued };
+        return { kept, releasedDead, queued, skipped };
     }
 }

package/dist/dashboard/feed.d.ts

@@ -18,6 +18,19 @@ export interface FeedOptions {
     inspectEveryMs?: number;
     /** Reconnect backoff base (default 250 ms). */
     reconnectBaseMs?: number;
+    /**
+     * How often to re-check install drift between this running copy and the
+     * PATH-resolved `load-lock` CLI (default 15_000 ms; 0 disables). A harness
+     * that loads plugin code once at startup keeps running the OLD copy after
+     * an update — this makes that visible on the dashboard (issue #39).
+     */
+    driftCheckMs?: number;
+    /**
+     * Wording of the drift hint: "opencode" says "restart opencode to pick up
+     * vX" (the plugin cannot hot-reload), "cli" (default) says the running
+     * copy is stale relative to the PATH CLI.
+     */
+    driftSurface?: "cli" | "opencode";
 }
 export declare class DashboardFeed {
     private client;
@@ -33,10 +46,14 @@ export declare class DashboardFeed {
     private daemonStartedAt;
     private refreshTimer;
     private slowTimer;
+    private driftTimer;
+    private drift;
     private stopped;
     private unsub;
     private connecting;
     private viewSeq;
+    /** daemonVersion seen at the previous resync — powers the "restarted onto" note. */
+    private lastDaemonVersion;
     /** Fired whenever the rendered view might have changed (state or data). */
     onChange?: () => void;
     /** Fired on connection-state transitions. */
@@ -69,6 +86,12 @@ export declare class DashboardFeed {
      * Returns the reclaimed request's one-line description for toasts.
      */
     forceRelease(requestId: string): Promise<void>;
+    /**
+     * 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(): void;
     /** Render-ready snapshot; countdowns are computed at `now`. */
     view(now?: number): DashboardView;
 }

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

@@ -1,9 +1,10 @@
 /**
  * load-lock MCP server (stdio) — the universal adapter for harnesses that
  * speak MCP (Claude Code, Codex CLI, Gemini CLI, Copilot CLI, Cline, Roo,
- * Goose, ...). Each harness session spawns one MCP server process; the
- * process-scoped agent identity routes offers back through tool results and
- * watch pushes.
+ * Goose, ...). Each harness session spawns one MCP server process per
+ * registration; the session-derived agent identity (issue #50, see
+ * shared/identity.ts) routes offers back through tool results and watch
+ * pushes, and is shared by every registration in the same session.
  *
  * Notification honesty (see docs/COMPATIBILITY.md): MCP transports can
  * surface server-initiated *messages*, but most harnesses do not inject them
@@ -16,11 +17,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

@@ -1,9 +1,10 @@
 /**
  * load-lock MCP server (stdio) — the universal adapter for harnesses that
  * speak MCP (Claude Code, Codex CLI, Gemini CLI, Copilot CLI, Cline, Roo,
- * Goose, ...). Each harness session spawns one MCP server process; the
- * process-scoped agent identity routes offers back through tool results and
- * watch pushes.
+ * Goose, ...). Each harness session spawns one MCP server process per
+ * registration; the session-derived agent identity (issue #50, see
+ * shared/identity.ts) routes offers back through tool results and watch
+ * pushes, and is shared by every registration in the same session.
  *
  * Notification honesty (see docs/COMPATIBILITY.md): MCP transports can
  * surface server-initiated *messages*, but most harnesses do not inject them
@@ -19,10 +20,14 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { spawn } from "node:child_process";
 import { LLClient } from "../shared/client.js";
-import { POLICY_BRIEF } from "../policy/text.js";
+import { POLICY_BRIEF, SETUP_HINT } 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";
+import { sessionIdentity } from "../shared/identity.js";
+import { agentGuideText } from "../shared/agent-guide.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.`;
@@ -30,8 +35,19 @@ const CLAIM_DESC = `Claim an offered permit within its claim window (offers expi
 const RELEASE_DESC = `Release a held permit immediately after the heavy work finishes — success, failure, or termination (idempotent: releasing twice is fine). A permit survives the tool call and session that acquired it; automatic cleanup releases it when a tracked job exits or, for untracked permits, when your adapter stops heartbeating — but do not rely on that: release as soon as the work is done.`;
 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 });
+    // Session-derived (issue #50): two registrations in one harness session
+    // (plugin-bundled + standalone) resolve to the same id; the per-process
+    // random id remains the fallback when no session can be found.
+    const defaultAgent = opts.agentId ??
+        sessionIdentity({ fallback: "agt_" + process.pid.toString(36) + Math.random().toString(36).slice(2, 8) }).id;
+    // 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 + "\n\n" + SETUP_HINT + (drift ? "\n\n" + drift.message : "") });
     const json = (v) => ({
         content: [{ type: "text", text: JSON.stringify(v, null, 2) }],
     });
@@ -205,6 +221,20 @@ Input: request_id (default: your oldest offered, then front-most queued, then ol
         description: "Current config: pools/capacity, offer timeout, heavy-work guidance, and change history with rationale.",
         inputSchema: {},
     }, async () => json(await client.request("get_config", {})));
+    // Issue #61: a plugin-only install may have neither the skill nor the CLI
+    // on PATH, so the policy brief's pointer to the detailed guide lands here.
+    server.registerTool("agent_guide", {
+        title: "Full agent guide",
+        description: "The detailed load-lock playbook (same text as `load-lock agent-guide`): heavy-vs-light heuristics, offer claiming, background jobs, configuration and recovery. Read it when the short policy is not enough. No daemon call.",
+        inputSchema: {},
+    }, async () => {
+        try {
+            return { content: [{ type: "text", text: agentGuideText() }] };
+        }
+        catch {
+            return { content: [{ type: "text", text: POLICY_BRIEF }] };
+        }
+    });
     server.registerTool("configure", {
         title: "Update config (CAS)",
         description: "Compare-and-swap config update so concurrent agents never silently overwrite each other. Read get_config, pass its version as expected_version, describe changes and a reason. Capacity decreases let current holders finish; increases admit queued requests immediately.",
@@ -468,6 +498,8 @@ Input: job_id OR request_id (one of them), timeout_ms (default 600000, clamped t
     // Automatic adapter heartbeat: while this server process lives, untracked
     // permits of this agent keep their lease; if the harness session dies, the
     // lease lapses and the daemon reclaims. The model never has to remember.
+    // Servers sharing a session identity each renew the same lease; heartbeats
+    // are idempotent, so that is harmless.
     const heartbeat = setInterval(() => {
         void client.request("heartbeat", { agentId: defaultAgent }).catch(() => {
             /* daemon unreachable; next tool call reconnects */

package/dist/policy/text.d.ts

@@ -4,14 +4,24 @@
  *
  *  - 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 declare const POLICY_BRIEF = "# load-lock: machine-wide heavy-work budget\n\nMultiple coding agents share this machine. Before resource-intensive local work\n(builds, test suites, bulky containers, big compiles), get a permit from the\nshared, machine-wide counting semaphore. While queued, keep doing useful light\nwork (reading, editing, searching, planning); you will be offered capacity.\n\nRules:\n1. Heavy vs light: judge by expected CPU/memory/IO cost for the whole machine.\n   A quick lint or single-file check is light. Full builds/tests are heavy.\n   When unsure, call the status tool \u2014 it shows current machine pressure.\n2. Immediately before starting heavy work: acquire a permit\n   (tool: load-lock acquire, CLI: load-lock acquire). Pass a short reason and\n   a stable op_key for the pending operation.\n3. If you are queued: keep working on light tasks. When you receive an offer\n   (in any load-lock tool result or a wakeup message), claim it promptly \u2014\n   offers expire (default 30s) and capacity passes to the next waiter.\n   Out of light work? Sleep honestly with wait_for_turn (MCP/plugin) or\n   'load-lock wait' (CLI) \u2014 a bounded sleep until your turn that\n   auto-claims and holds no capacity.\n4. Start heavy work ONLY after acquire/claim succeeds. Never start heavy work\n   on a \"queued\" result; never treat a notification as authorization.\n5. Hold the permit until the heavy process actually finishes \u2014 including when\n   it runs in the background beyond this tool call or session. Optionally\n   attach its pid (load-lock attach_pid) so a dead process auto-releases.\n   Out of light work while it runs? Sleep honestly with wait_for_completion\n   (MCP/plugin: run_with_permit job_id or tracked request_id; or run_with_permit\n   with wait:true) or 'load-lock wait --job <request-id>' (CLI) \u2014 a bounded\n   sleep that wakes promptly when the job finishes (exit code + output tail;\n   the permit is freed before you are woken). On still_running it is a\n   checkpoint: call again. Do NOT guess sleeps or poll job_status in a loop.\n6. Release immediately when done (success or failure), and cancel queued\n   requests you no longer need.\n7. Capacity is a cooperative budget, not an enforced one. If the budget seems\n   wrong for this machine, check load-lock inspect_machine (real cores/memory,\n   including container limits) and adjust with configure (explain why). Don't\n   assume N cores = N parallel heavy jobs.\n\nDetailed guide: the \"load-lock\" skill or `load-lock agent-guide`.";
+export declare const POLICY_BRIEF = "# load-lock: machine-wide heavy-work budget\n\nMultiple coding agents share this machine. Before resource-intensive local work\n(builds, test suites, bulky containers, big compiles), get a permit from the\nshared, machine-wide counting semaphore. While queued, keep doing useful light\nwork (reading, editing, searching, planning); you will be offered capacity.\n\nRules:\n1. Heavy vs light: judge by expected CPU/memory/IO cost for the whole machine.\n   A quick lint or single-file check is light. Full builds/tests are heavy.\n   When unsure, call the status tool \u2014 it shows current machine pressure.\n2. Immediately before starting heavy work: acquire a permit\n   (tool: load-lock acquire, CLI: load-lock acquire). Pass a short reason and\n   a stable op_key for the pending operation.\n3. If you are queued: keep working on light tasks. When you receive an offer\n   (in any load-lock tool result or a wakeup message), claim it promptly \u2014\n   offers expire (default 30s) and capacity passes to the next waiter.\n   Out of light work? Sleep honestly with wait_for_turn (MCP/plugin) or\n   'load-lock wait' (CLI) \u2014 a bounded sleep until your turn that\n   auto-claims and holds no capacity.\n4. Start heavy work ONLY after acquire/claim succeeds. Never start heavy work\n   on a \"queued\" result; never treat a notification as authorization.\n5. Hold the permit until the heavy process actually finishes \u2014 including when\n   it runs in the background beyond this tool call or session. Optionally\n   attach its pid (load-lock attach_pid) so a dead process auto-releases.\n   Out of light work while it runs? Sleep honestly with wait_for_completion\n   (MCP/plugin: run_with_permit job_id or tracked request_id; or run_with_permit\n   with wait:true) or 'load-lock wait --job <request-id>' (CLI) \u2014 a bounded\n   sleep that wakes promptly when the job finishes (exit code + output tail;\n   the permit is freed before you are woken). On still_running it is a\n   checkpoint: call again. Do NOT guess sleeps or poll job_status in a loop.\n6. Release immediately when done (success or failure), and cancel queued\n   requests you no longer need.\n7. Capacity is a cooperative budget, not an enforced one. If the budget seems\n   wrong for this machine, check load-lock inspect_machine (real cores/memory,\n   including container limits) and adjust with configure (explain why). Don't\n   assume N cores = N parallel heavy jobs.\n\nDetailed guide: the load-lock agent_guide tool (MCP/plugin), else the\n\"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 declare 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 declare function policyWithContext(statusSummary: string, configSummary?: string): string;
 export declare function statusLine(st: {
     pools: {