@aron98/load-lock 1.5.0 → 1.6.0

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,12 +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.`;
@@ -32,7 +35,11 @@ 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);
+    // 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
@@ -40,7 +47,7 @@ export function buildServer(opts) {
     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 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) }],
     });
@@ -214,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.",
@@ -477,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: {

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,7 @@ 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;
@@ -173,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). */

package/dist/shared/drift.d.ts

@@ -5,11 +5,13 @@ export interface CliDrift {
     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): string;
+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
@@ -18,4 +20,4 @@ export declare function driftMessage(ownVersion: string, cliVersion: string): st
  * 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;
+export declare function detectCliDrift(ownVersion: string, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, ownPath?: string | null): CliDrift | null;

package/dist/shared/drift.js

@@ -14,21 +14,36 @@
  * 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 } from "node:path";
+import { dirname, join, sep as pathSep } from "node:path";
+import { fileURLToPath } from "node:url";
 import { isWindows } from "./transport.js";
-import { enclosingPackage, PKG_NAME } from "./pkginfo.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) {
-    return (`load-lock: this load-lock adapter copy (v${ownVersion}) is newer than the installed CLI (v${cliVersion}). ` +
+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
@@ -37,8 +52,10 @@ export function driftMessage(ownVersion, cliVersion) {
  * 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) {
+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);
@@ -63,7 +80,8 @@ export function detectCliDrift(ownVersion, env = process.env, platform = process
                         ownVersion,
                         cliVersion: found.version,
                         cliPath: found.path,
-                        message: driftMessage(ownVersion, found.version),
+                        ownSource,
+                        message: driftMessage(ownVersion, found.version, ownSource),
                     };
                 }
                 return null; // PATH CLI is same/newer — no drift

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/pkginfo.d.ts

@@ -14,3 +14,12 @@ export interface PkgRootInfo {
 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

@@ -52,3 +52,19 @@ export function opencodeCacheRoot(platform, env) {
         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");
+}

package/dist/shared/protocol.d.ts

@@ -11,6 +11,9 @@
  *           the extra field (forward-compatible); newer daemons use it
  *           for the update handshake: a client strictly newer than the
  *           running daemon triggers a daemon self-restart (issue #34).
+ *           Since #52 the envelope also carries "clientRoot" (the client
+ *           copy's package root); the daemon records it as a known
+ *           runtime copy (runtimes.json). Also ignored by older daemons.
  * Response: {"id": <number>, "ok": true, "result": {...}}
  *           {"id": <number>, "ok": false, "error": {"code": "...", "message": "..."}}
  * Watch push: {"event": true, ...event fields...}
@@ -139,6 +142,8 @@ export interface OwnerEntrySnapshot extends EntrySnapshot {
     permitToken?: string;
 }
 export interface JournalEntry {
+    /** Persisted format version of the writer (issue #51); absent before versioning. */
+    formatVersion?: number;
     requestId: string;
     pool: string;
     agentId: string;
@@ -438,3 +443,20 @@ export interface HolderDiag {
         note: string;
     };
 }
+export declare const HOOK_ONCE_DEFAULT_TTL_MS = 60000;
+export declare const HOOK_ONCE_MAX_TTL_MS: number;
+export interface HookOnceParams {
+    harness: string;
+    sessionId: string;
+    event: string;
+    /** Distinguishes legitimate repeats within one session (e.g. SessionStart source, offer token). */
+    occurrence?: string;
+    /** Key lifetime, ms (clamped to [1s, HOOK_ONCE_MAX_TTL_MS]); ignored with hold. */
+    ttlMs?: number;
+    /** Hold the key until this connection closes instead of a TTL. */
+    hold?: boolean;
+}
+export interface HookOnceResult {
+    /** True when the caller is the first for this key and should act. */
+    first: boolean;
+}

package/dist/shared/protocol.js

@@ -11,6 +11,9 @@
  *           the extra field (forward-compatible); newer daemons use it
  *           for the update handshake: a client strictly newer than the
  *           running daemon triggers a daemon self-restart (issue #34).
+ *           Since #52 the envelope also carries "clientRoot" (the client
+ *           copy's package root); the daemon records it as a known
+ *           runtime copy (runtimes.json). Also ignored by older daemons.
  * Response: {"id": <number>, "ok": true, "result": {...}}
  *           {"id": <number>, "ok": false, "error": {"code": "...", "message": "..."}}
  * Watch push: {"event": true, ...event fields...}
@@ -25,3 +28,15 @@ export class ProtocolError extends Error {
         this.details = details;
     }
 }
+// ---------------------------------------------------------------------------
+// hook_once (issue #54): daemon-side dedupe for duplicate hook wiring.
+// Loose hooks + plugin hooks (or two plugins) fire the same harness hook
+// more than once. Each hook handler first claims the key
+// (harness, sessionId, event, occurrence); only the first caller acts, the
+// rest exit 0 silently. Keys are in-memory only (never persisted, gone on
+// daemon restart) and expire after ttlMs — or, with hold, live exactly as
+// long as the calling connection (long-running await-offer watchers).
+// Daemons without the method answer `unknown method`; callers then act as
+// before (no dedupe).
+export const HOOK_ONCE_DEFAULT_TTL_MS = 60_000;
+export const HOOK_ONCE_MAX_TTL_MS = 10 * 60_000;

package/dist/shared/runtimes.d.ts

@@ -0,0 +1,41 @@
+export interface RuntimeCopy {
+    /** Real path of the copy's package root. */
+    path: string;
+    /** Version read from the copy's package.json (not from the client). */
+    version: string;
+    /** Epoch ms of the last handshake from this copy. */
+    lastSeen: number;
+}
+/** daemon.json contents (fields beyond pid/startedAt/socket since #52). */
+export interface DaemonInfo {
+    pid: number;
+    startedAt: number;
+    socket: string;
+    /** Package root the daemon runs from (since #52). */
+    packageRoot?: string;
+    /** Package version the daemon runs (since #52). */
+    version?: string;
+}
+/** Cap on remembered copies; the least recently seen are dropped first. */
+export declare const MAX_RUNTIMES = 32;
+export declare function runtimesPath(stateDir: string): string;
+/**
+ * Validate a package root: it must hold a package.json naming
+ * @aron98/load-lock with a string version. Returns the real path and the
+ * on-disk version, or null.
+ */
+export declare function inspectPackageRoot(root: string): {
+    path: string;
+    version: string;
+} | null;
+/** Known copies from the state dir, dropping entries whose path is gone. */
+export declare function loadRuntimes(stateDir: string): RuntimeCopy[];
+export declare function saveRuntimes(stateDir: string, copies: RuntimeCopy[]): void;
+/**
+ * Merge one sighting into the list (dedupe by real path, newest first,
+ * capped). Returns the new list, or null when the root is not a valid
+ * load-lock copy.
+ */
+export declare function mergeRuntime(copies: RuntimeCopy[], root: string, now: number): RuntimeCopy[] | null;
+/** daemon.json contents, or null when missing/unreadable. */
+export declare function readDaemonInfo(stateDir: string): DaemonInfo | null;