@aron98/load-lock 1.4.0 → 1.6.0

package/dist/cli/update.d.ts

@@ -0,0 +1,57 @@
+export type SelfLocationKind = "bun-global" | "npm-global" | "opencode-cache" | "npx-cache" | "repo-checkout" | "unknown";
+export interface SelfLocation {
+    kind: SelfLocationKind;
+    /** Package root of this copy. */
+    path: string;
+    /** Explanation shown in reports (part of the refusal reason when refusing). */
+    detail: string;
+}
+/** Inputs classifySelf needs; callers resolve them (tests plant values). */
+export interface ClassifyCtx {
+    home: string;
+    /** bun global node_modules root; default <home>/.bun/install/global/node_modules. */
+    bunGlobalRoot?: string;
+    /** `npm root -g` result; null when npm could not answer. */
+    npmGlobalRoot: string | null;
+    /** opencode cache root (XDG_CACHE_HOME | platform default); null when unknown. */
+    cacheRoot: string | null;
+    /** npx cache root (<npm cache>/_npx); null/absent when unknown. */
+    npxRoot?: string | null;
+}
+/**
+ * Classify where this copy of load-lock lives, BEFORE touching anything:
+ *  - bun global (<home>/.bun/install/global/node_modules/...) → update via bun
+ *  - npm global (under `npm root -g`) → update via npm
+ *  - opencode cache copy (<cache>/opencode/npm/...) → refuse: opencode
+ *    manages this copy and refreshes it on its own schedule
+ *  - npx cache copy (<npm cache>/_npx/...) → refuse: whatever launches it
+ *    via `npx @aron98/load-lock@<pin>` (skill / ACE / MCP entry) owns the pin
+ *  - repo checkout (nearest .git found by walking up, like the omac
+ *    read-grant logic) → refuse with a pointer to the git workflow
+ *  - anything else → unknown → refuse honestly rather than guessing
+ */
+export declare function classifySelf(pkgRoot: string, ctx: ClassifyCtx): SelfLocation;
+export type UpdatePlan = {
+    action: "install";
+    argv: string[];
+    detail: string;
+} | {
+    action: "refuse";
+    reason: string;
+};
+/** What to run for the detected location — or why we refuse to guess. */
+export declare function planUpdate(loc: SelfLocation): UpdatePlan;
+export interface UpdateOptions {
+    /** --check: report only, never install or restart. */
+    check: boolean;
+    /** --json: machine-readable output (house style: humans get prose). */
+    json: boolean;
+}
+/**
+ * The `load-lock update` command. Prints a structured report (JSON with
+ * --json, prose otherwise) and returns the exit code:
+ *   0  up-to-date (check) or applied successfully
+ *   1  update available (--check; includes "cannot self-apply" refusals)
+ *   70 failure or refusal in apply mode
+ */
+export declare function updateCommand(opts: UpdateOptions): Promise<number>;

package/dist/cli/update.js

@@ -0,0 +1,287 @@
+/**
+ * `load-lock update` (issue #38): check the npm registry for a newer
+ * version (npm is the only distribution channel), classify where THIS copy
+ * lives before touching anything, and apply the update via the detected
+ * package manager — or refuse honestly (repo checkouts, opencode-managed
+ * cache copies, npx cache copies, unknown locations) rather than guessing. After a
+ * successful apply, `service restart` moves the daemon onto the new code
+ * immediately; the v1.3.0 version handshake stays as the safety net for
+ * daemons nobody explicitly restarts.
+ *
+ * Classification and planning are pure functions of their arguments
+ * (planted-layout testable, like shared/transport.ts); the registry and
+ * package-manager spawns resolve `npm` through PATH so tests stub them
+ * with a fake `npm` on PATH — the real registry is never contacted in
+ * tests and nothing is ever installed by them.
+ *
+ * Exit codes: 0 up-to-date / applied; 1 update available (`--check`,
+ * including "an update exists but this copy cannot self-apply" refusals);
+ * 70 failure (registry unreachable, package manager failed, refused in
+ * apply mode, or restart failed after an applied update).
+ */
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join, sep } from "node:path";
+import { homedir } from "node:os";
+import { compareVersions, packageVersion } from "../shared/version.js";
+import { npxCacheRoot, opencodeCacheRoot, PKG_NAME } from "../shared/pkginfo.js";
+import { thisCopy } from "./copies.js";
+import { serviceRestart, ServiceError } from "./service.js";
+/** Path containment with separator awareness ("a" contains "a" and "a/b"). */
+function isUnder(dir, root) {
+    if (dir === root)
+        return true;
+    return dir.startsWith(root.endsWith(sep) ? root : root + sep);
+}
+/**
+ * Classify where this copy of load-lock lives, BEFORE touching anything:
+ *  - bun global (<home>/.bun/install/global/node_modules/...) → update via bun
+ *  - npm global (under `npm root -g`) → update via npm
+ *  - opencode cache copy (<cache>/opencode/npm/...) → refuse: opencode
+ *    manages this copy and refreshes it on its own schedule
+ *  - npx cache copy (<npm cache>/_npx/...) → refuse: whatever launches it
+ *    via `npx @aron98/load-lock@<pin>` (skill / ACE / MCP entry) owns the pin
+ *  - repo checkout (nearest .git found by walking up, like the omac
+ *    read-grant logic) → refuse with a pointer to the git workflow
+ *  - anything else → unknown → refuse honestly rather than guessing
+ */
+export function classifySelf(pkgRoot, ctx) {
+    const bunRoot = ctx.bunGlobalRoot ?? join(ctx.home, ".bun", "install", "global", "node_modules");
+    if (isUnder(pkgRoot, bunRoot)) {
+        return { kind: "bun-global", path: pkgRoot, detail: `bun global install under ${bunRoot}` };
+    }
+    if (ctx.npmGlobalRoot && isUnder(pkgRoot, ctx.npmGlobalRoot)) {
+        return { kind: "npm-global", path: pkgRoot, detail: `npm global install under ${ctx.npmGlobalRoot}` };
+    }
+    if (ctx.cacheRoot && isUnder(pkgRoot, join(ctx.cacheRoot, "opencode", "npm"))) {
+        return { kind: "opencode-cache", path: pkgRoot, detail: `opencode-managed cache copy under ${ctx.cacheRoot}` };
+    }
+    if (ctx.npxRoot && isUnder(pkgRoot, ctx.npxRoot)) {
+        return { kind: "npx-cache", path: pkgRoot, detail: `npx cache copy under ${ctx.npxRoot}` };
+    }
+    for (let dir = pkgRoot;;) {
+        if (existsSync(join(dir, ".git"))) {
+            return { kind: "repo-checkout", path: pkgRoot, detail: `git checkout (.git at ${dir})` };
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return { kind: "unknown", path: pkgRoot, detail: "not a recognized bun/npm global, opencode/npx cache, or git checkout location" };
+}
+/** What to run for the detected location — or why we refuse to guess. */
+export function planUpdate(loc) {
+    switch (loc.kind) {
+        case "bun-global":
+            return { action: "install", argv: ["bun", "i", "-g", `${PKG_NAME}@latest`], detail: loc.detail };
+        case "npm-global":
+            return { action: "install", argv: ["npm", "i", "-g", `${PKG_NAME}@latest`], detail: loc.detail };
+        case "opencode-cache":
+            return {
+                action: "refuse",
+                reason: `this copy lives in opencode's npm cache (${loc.path}); opencode manages it and refreshes it on its own schedule — ` +
+                    `update the PATH-installed CLI instead (npm i -g ${PKG_NAME}@latest)`,
+            };
+        case "npx-cache":
+            return {
+                action: "refuse",
+                reason: `this copy lives in the npx cache (${loc.path}); it is whatever version the launching npx command pins — ` +
+                    `bump the pinned version (the \`npx -y ${PKG_NAME}@<version>\` in your MCP/skill config, or the ACE artifact) ` +
+                    `to move it, and update the PATH-installed CLI separately (npm i -g ${PKG_NAME}@latest)`,
+            };
+        case "repo-checkout":
+            return {
+                action: "refuse",
+                reason: `this copy is a git checkout (${loc.path}) — update it via your git workflow (e.g. git pull), not a package manager`,
+            };
+        case "unknown":
+            return {
+                action: "refuse",
+                reason: `cannot tell how this copy (${loc.path}) was installed — refusing to guess; ` +
+                    `if it is a global install, run npm i -g ${PKG_NAME}@latest (or the bun equivalent) by hand`,
+            };
+    }
+}
+/** One npm invocation, bounded; resolves null on timeout/spawn failure. */
+function npmOutput(args, timeoutMs) {
+    return new Promise((resolve) => {
+        let stdout = "";
+        let stderr = "";
+        let child;
+        try {
+            child = spawn("npm", args, { stdio: ["ignore", "pipe", "pipe"] });
+        }
+        catch {
+            resolve(null);
+            return;
+        }
+        const timer = setTimeout(() => {
+            child.kill("SIGKILL");
+            resolve(null);
+        }, timeoutMs);
+        timer.unref?.();
+        child.stdout?.on("data", (b) => (stdout += b));
+        child.stderr?.on("data", (b) => (stderr += b));
+        child.once("error", () => {
+            clearTimeout(timer);
+            resolve(null);
+        });
+        child.once("exit", (code) => {
+            clearTimeout(timer);
+            resolve({ code, stdout, stderr });
+        });
+    });
+}
+/** Latest published version from the npm registry, or null on failure. */
+async function viewLatest(timeoutMs) {
+    const r = await npmOutput(["view", PKG_NAME, "version"], timeoutMs);
+    if (!r || r.code !== 0)
+        return null;
+    // `npm view <pkg> version` prints the bare version (possibly quoted).
+    const line = r.stdout.trim().split("\n").pop() ?? "";
+    const v = line.replace(/^"|"$/g, "").trim();
+    return /^\d+(\.\d+)*(-.*)?$/.test(v) ? v : null;
+}
+/** `npm root -g` (the global node_modules dir), or null on failure. */
+async function npmGlobalRoot(timeoutMs) {
+    const r = await npmOutput(["root", "-g"], timeoutMs);
+    if (!r || r.code !== 0)
+        return null;
+    const line = r.stdout.trim().split("\n").pop() ?? "";
+    return line || null;
+}
+function fail(msg, code = 70) {
+    process.stderr.write(`load-lock: ${msg}\n`);
+    process.exit(code);
+}
+/**
+ * The `load-lock update` command. Prints a structured report (JSON with
+ * --json, prose otherwise) and returns the exit code:
+ *   0  up-to-date (check) or applied successfully
+ *   1  update available (--check; includes "cannot self-apply" refusals)
+ *   70 failure or refusal in apply mode
+ */
+export async function updateCommand(opts) {
+    const timeoutMs = 30_000;
+    const out = (v, human) => {
+        if (opts.json)
+            process.stdout.write(JSON.stringify(v, null, 2) + "\n");
+        else
+            process.stdout.write(human() + "\n");
+    };
+    const locationReport = (loc) => ({ kind: loc.kind, path: loc.path });
+    // 1. Classify self BEFORE touching anything (local only, no registry).
+    const self = thisCopy();
+    const own = packageVersion();
+    if (!self) {
+        fail(`cannot resolve this copy's package root — run \`load-lock doctor\``);
+    }
+    const root = await npmGlobalRoot(timeoutMs);
+    const loc = classifySelf(self.path, {
+        home: process.env.HOME ?? homedir(),
+        npmGlobalRoot: root,
+        cacheRoot: opencodeCacheRoot(process.platform, process.env),
+        npxRoot: npxCacheRoot(process.platform, process.env),
+    });
+    // 2. Check the registry (npm is the only distribution channel).
+    const latest = await viewLatest(timeoutMs);
+    if (latest === null) {
+        fail(`could not determine the latest published version of ${PKG_NAME} (npm view failed — is the registry reachable?)`);
+    }
+    // 3. Up to date (or this copy is ahead of the registry — nothing to do).
+    if (compareVersions(latest, own) <= 0) {
+        const ahead = compareVersions(latest, own) < 0;
+        const report = {
+            state: "up-to-date",
+            current_version: own,
+            latest_version: latest,
+            location: locationReport(loc),
+            ...(ahead ? { note: `this copy (v${own}) is newer than the registry latest (v${latest}) — nothing to do` } : {}),
+        };
+        out(report, () => `load-lock: up to date (v${own}; registry latest v${latest}; location: ${loc.kind})` +
+            (ahead ? ` — this copy is ahead of the registry` : ""));
+        return 0;
+    }
+    // 4. An update exists: plan the apply for the classified location.
+    const plan = planUpdate(loc);
+    if (plan.action === "refuse") {
+        const report = {
+            state: "refused",
+            current_version: own,
+            latest_version: latest,
+            location: locationReport(loc),
+            reason: plan.reason,
+            next_action: "resolve the location issue, then run `load-lock update` again (see docs/OPERATIONS.md)",
+        };
+        out(report, () => `load-lock: update to v${latest} available, but refused: ${plan.reason}`);
+        if (opts.check)
+            return 1; // an update exists — this copy just cannot self-apply it
+        process.stderr.write(`load-lock: update refused — ${plan.reason}\n`);
+        return 70;
+    }
+    // 5. --check: report what WOULD happen; touch nothing.
+    if (opts.check) {
+        const report = {
+            state: "update-available",
+            current_version: own,
+            latest_version: latest,
+            location: locationReport(loc),
+            command: plan.argv,
+            next_action: "run `load-lock update` to apply it; the service restarts automatically afterwards",
+        };
+        out(report, () => `load-lock: update available: v${own} -> v${latest} (location: ${loc.kind}; would run: ${plan.argv.join(" ")})`);
+        return 1;
+    }
+    // 6. Apply: run the detected package manager (output shown live).
+    process.stdout.write(opts.json
+        ? JSON.stringify({ state: "applying", current_version: own, latest_version: latest, command: plan.argv }, null, 2) + "\n"
+        : `load-lock: updating v${own} -> v${latest} via ${plan.argv.join(" ")}\n`);
+    const code = await new Promise((resolve) => {
+        let child;
+        try {
+            child = spawn(plan.argv[0], plan.argv.slice(1), { stdio: "inherit" });
+        }
+        catch (e) {
+            fail(`cannot run ${plan.argv[0]}: ${e.message}`);
+        }
+        child.once("error", (e) => fail(`cannot run ${plan.argv[0]}: ${e.message}`));
+        child.once("exit", (c) => resolve(c));
+    });
+    if (code !== 0) {
+        fail(`update not applied: ${plan.argv.join(" ")} exited with code ${code} — the daemon keeps running the current code`);
+    }
+    // 7. Restart the service so the daemon moves onto the new code now
+    // (the version handshake remains the safety net, not the primary means).
+    try {
+        const r = await serviceRestart();
+        const report = {
+            state: "updated",
+            from: own,
+            to: latest,
+            location: locationReport(loc),
+            command: plan.argv,
+            restarted: true,
+            restart: { stop: r.stop, start: r.start },
+        };
+        out(report, () => `load-lock: updated v${own} -> v${latest}; ${r.stop}; ${r.start}`);
+        return 0;
+    }
+    catch (e) {
+        const reason = e instanceof ServiceError ? e.message : String(e?.message ?? e);
+        const report = {
+            state: "updated",
+            from: own,
+            to: latest,
+            location: locationReport(loc),
+            command: plan.argv,
+            restarted: false,
+            restart_error: reason,
+            next_action: "the update IS applied; the daemon still runs old code — the version handshake will self-restart it on the " +
+                "next client contact, or run `load-lock service restart` manually (see docs/OPERATIONS.md)",
+        };
+        out(report, () => `load-lock: updated v${own} -> v${latest}, but the service restart failed: ${reason}`);
+        process.stderr.write(`load-lock: ${reason}\n`);
+        return 70;
+    }
+}

package/dist/core/daemon.d.ts

@@ -29,6 +29,9 @@ export declare class Daemon {
     private waiters;
     /** wait_for_completion calls blocked on tracked jobs; multiple waiters per job are fine. */
     private completionWaiters;
+    /** hook_once keys (issue #54): in-memory only, never persisted. A key is
+     *  live until expiresAt, or — when held — until its socket closes. */
+    private hookKeys;
     private sentEventId;
     private stateDirPath;
     private socketPath;
@@ -36,6 +39,10 @@ export declare class Daemon {
     private expiryTimer;
     private restartTimer;
     private stopped;
+    /** Known runtime copies (issue #52), mirrored to runtimes.json. */
+    private runtimes;
+    /** clientRoot hints already resolved this run: raw hint -> real path (null = invalid). */
+    private runtimeHints;
     constructor(opts?: {
         stateDir?: string;
         socket?: string;
@@ -53,6 +60,13 @@ export declare class Daemon {
     private onConnection;
     private send;
     private handleLine;
+    /**
+     * Known runtime copies (issue #52): remember a copy seen via the
+     * handshake. Deduped by real path; the version is read from the copy's
+     * own package.json. Disk writes only on a new copy, a version change, or
+     * a stale lastSeen — never per request. Best-effort: never throws.
+     */
+    private recordRuntime;
     /**
      * Self-restart handshake (issue #34): if a client identifies a NEWER
      * package version than this daemon runs, schedule a respawn so the daemon
@@ -65,9 +79,12 @@ export declare class Daemon {
     /**
      * Drain + respawn onto the updated on-disk code. Persists state and the
      * journal FIRST, then stops (destroying all client connections — they
-     * reconnect to the fresh daemon), then spawns the replacement with the
-     * exact same argv so a daemon started via the old copy runs the new copy's
-     * code, and exits.
+     * reconnect to the fresh daemon), then spawns the replacement and exits.
+     *
+     * The replacement runs the newer client's copy when its package root
+     * (clientRoot, issue #53) checks out — see restartEntry(). Otherwise it
+     * reruns the exact same argv, which picks up an in-place update of the
+     * daemon's own copy (e.g. `npm i -g`).
      */
     private selfRestart;
     /** Returns [result, agentIdForPendingAttachment]. */
@@ -140,3 +157,12 @@ export declare function isProcessAlive(pid: number, expectedStartTime?: string,
 export declare function jobAlive(pid?: number, pgid?: number, pidStartTime?: string, platform?: NodeJS.Platform): boolean | null;
 /** Read the Linux start time of a pid (pid-reuse-safe association). */
 export declare function processStartTime(pid: number): string | undefined;
+/**
+ * Daemon entry point of the newer client's copy (issue #53), or null to
+ * fall back to the same-argv respawn. The hint must name a load-lock
+ * package root whose on-disk version equals the version the client
+ * claimed, with a dist/core/daemon-main.js. The hint arrives over the
+ * same-user socket, so following it grants no privilege the client did
+ * not already have (it could run that file itself).
+ */
+export declare function restartEntry(clientRoot: string | undefined, clientVersion: string): string | null;

package/dist/core/daemon.js

@@ -25,8 +25,10 @@ import { Machine } from "./state.js";
 import { loadState, saveState, loadJournal, saveJournal, socketPath as defaultSocket, stateDir as defaultStateDir } from "./persist.js";
 import { inspectMachine } from "./sysinfo.js";
 import { ProtocolError } from "../shared/protocol.js";
+import { HOOK_ONCE_DEFAULT_TTL_MS, HOOK_ONCE_MAX_TTL_MS } from "../shared/protocol.js";
 import { isWindows, probeTransport } from "../shared/transport.js";
-import { packageVersion, compareVersions } from "../shared/version.js";
+import { packageVersion, packageRoot, compareVersions } from "../shared/version.js";
+import { inspectPackageRoot, loadRuntimes, mergeRuntime, saveRuntimes } from "../shared/runtimes.js";
 /** Package version of the copy of load-lock this daemon process runs from. */
 const DAEMON_VERSION = packageVersion();
 /**
@@ -35,6 +37,8 @@ const DAEMON_VERSION = packageVersion();
  * only one respawn per version bump.
  */
 const RESTARTED_FOR_ENV = "LOAD_LOCK_RESTARTED_FOR";
+/** Re-persist a known copy's lastSeen at most this often (issue #52). */
+const RUNTIME_TOUCH_MS = 60_000;
 export class Daemon {
     machine;
     server = null;
@@ -46,6 +50,9 @@ export class Daemon {
     waiters = new Map();
     /** wait_for_completion calls blocked on tracked jobs; multiple waiters per job are fine. */
     completionWaiters = new Map();
+    /** hook_once keys (issue #54): in-memory only, never persisted. A key is
+     *  live until expiresAt, or — when held — until its socket closes. */
+    hookKeys = new Map();
     sentEventId;
     stateDirPath;
     socketPath;
@@ -53,6 +60,10 @@ export class Daemon {
     expiryTimer = null;
     restartTimer = null;
     stopped = false;
+    /** Known runtime copies (issue #52), mirrored to runtimes.json. */
+    runtimes = [];
+    /** clientRoot hints already resolved this run: raw hint -> real path (null = invalid). */
+    runtimeHints = new Map();
     constructor(opts = {}) {
         this.stateDirPath = defaultStateDir(opts.stateDir);
         this.socketPath = defaultSocket(opts.socket);
@@ -81,7 +92,17 @@ export class Daemon {
             this.server.on("error", reject);
             this.server.listen(this.socketPath, () => resolve());
         });
-        writeFileSync(join(this.stateDirPath, "daemon.json"), JSON.stringify({ pid: process.pid, startedAt: Date.now(), socket: this.socketPath }, null, 2) + "\n");
+        const own = inspectPackageRoot(packageRoot());
+        const info = {
+            pid: process.pid,
+            startedAt: Date.now(),
+            socket: this.socketPath,
+            packageRoot: own?.path ?? packageRoot(),
+            version: DAEMON_VERSION,
+        };
+        writeFileSync(join(this.stateDirPath, "daemon.json"), JSON.stringify(info, null, 2) + "\n");
+        this.runtimes = loadRuntimes(this.stateDirPath);
+        this.recordRuntime(packageRoot());
         process.once("SIGTERM", () => this.stop());
         process.once("SIGINT", () => this.stop());
         this.sweepTimer = setInterval(() => this.sweep(), 5_000);
@@ -187,6 +208,9 @@ export class Daemon {
             for (const w of [...this.watchers])
                 if (w.socket === sock)
                     this.watchers.delete(w);
+            for (const [k, v] of this.hookKeys)
+                if (v.sock === sock)
+                    this.hookKeys.delete(k);
         });
     }
     send(sock, obj) {
@@ -204,6 +228,8 @@ export class Daemon {
         }
         // Version handshake: remember the client's version for skew detection.
         const clientVersion = typeof msg.clientVersion === "string" ? msg.clientVersion : undefined;
+        if (typeof msg.clientRoot === "string")
+            this.recordRuntime(msg.clientRoot);
         let result;
         let agentId;
         try {
@@ -222,7 +248,7 @@ export class Daemon {
             }
             // Respond first, then consider a self-restart — even on errors, a
             // newer client means this daemon is running stale on-disk code.
-            this.maybeScheduleSelfRestart(clientVersion);
+            this.maybeScheduleSelfRestart(clientVersion, msg.clientRoot);
             return;
         }
         // Tool-boundary delivery: surface this agent's outstanding offers/queue
@@ -231,9 +257,41 @@ export class Daemon {
             result.pending = this.machine.pending(agentId);
         }
         this.send(sock, { id: msg.id, ok: true, result });
-        this.maybeScheduleSelfRestart(clientVersion);
+        this.maybeScheduleSelfRestart(clientVersion, msg.clientRoot);
     }
     // -------------------------------------------------------- version handshake
+    /**
+     * Known runtime copies (issue #52): remember a copy seen via the
+     * handshake. Deduped by real path; the version is read from the copy's
+     * own package.json. Disk writes only on a new copy, a version change, or
+     * a stale lastSeen — never per request. Best-effort: never throws.
+     */
+    recordRuntime(root) {
+        try {
+            let real = this.runtimeHints.get(root);
+            const now = Date.now();
+            if (real === undefined) {
+                real = inspectPackageRoot(root)?.path ?? null;
+                if (this.runtimeHints.size > 256)
+                    this.runtimeHints.clear();
+                this.runtimeHints.set(root, real);
+            }
+            if (real === null)
+                return;
+            const known = this.runtimes.find((c) => c.path === real);
+            if (known && now - known.lastSeen < RUNTIME_TOUCH_MS)
+                return;
+            const merged = mergeRuntime(this.runtimes, real, now);
+            if (!merged)
+                return;
+            // Drop copies whose path disappeared since they were last seen.
+            this.runtimes = merged.filter((c) => c.path === real || existsSync(join(c.path, "package.json")));
+            saveRuntimes(this.stateDirPath, this.runtimes);
+        }
+        catch {
+            /* bookkeeping only */
+        }
+    }
     /**
      * Self-restart handshake (issue #34): if a client identifies a NEWER
      * package version than this daemon runs, schedule a respawn so the daemon
@@ -242,7 +300,7 @@ export class Daemon {
      * entirely daemon-side and best-effort: pre-handshake clients that send
      * no version never trigger a restart.
      */
-    maybeScheduleSelfRestart(clientVersion) {
+    maybeScheduleSelfRestart(clientVersion, clientRoot) {
         if (this.stopped || this.restartTimer || !clientVersion)
             return;
         if (compareVersions(clientVersion, DAEMON_VERSION) <= 0)
@@ -252,18 +310,21 @@ export class Daemon {
             return; // already tried
         this.restartTimer = setTimeout(() => {
             this.restartTimer = null;
-            this.selfRestart(clientVersion);
+            this.selfRestart(clientVersion, typeof clientRoot === "string" ? clientRoot : undefined);
         }, 250);
         this.restartTimer.unref?.();
     }
     /**
      * Drain + respawn onto the updated on-disk code. Persists state and the
      * journal FIRST, then stops (destroying all client connections — they
-     * reconnect to the fresh daemon), then spawns the replacement with the
-     * exact same argv so a daemon started via the old copy runs the new copy's
-     * code, and exits.
+     * reconnect to the fresh daemon), then spawns the replacement and exits.
+     *
+     * The replacement runs the newer client's copy when its package root
+     * (clientRoot, issue #53) checks out — see restartEntry(). Otherwise it
+     * reruns the exact same argv, which picks up an in-place update of the
+     * daemon's own copy (e.g. `npm i -g`).
      */
-    selfRestart(clientVersion) {
+    selfRestart(clientVersion, clientRoot) {
         if (this.stopped)
             return;
         // Best-effort persistence; a failed save must not block the restart.
@@ -276,7 +337,9 @@ export class Daemon {
         }
         this.stop();
         try {
-            const child = spawn(process.execPath, process.argv.slice(1), {
+            const entry = restartEntry(clientRoot, clientVersion);
+            const args = entry ? [entry, "--state-dir", this.stateDirPath, "--socket", this.socketPath] : process.argv.slice(1);
+            const child = spawn(process.execPath, args, {
                 detached: true,
                 stdio: "ignore",
                 cwd: process.cwd(),
@@ -406,6 +469,26 @@ export class Daemon {
                 const cwd = String(p.cwd);
                 return [{ offers: m.allOffers().filter((e) => e.cwd === cwd) }, undefined];
             }
+            case "hook_once": {
+                // Duplicate hook wiring (loose + plugin, two plugins, ...) fires the
+                // same hook several times; the first caller per key acts, the rest
+                // stay silent. Keys are in-memory only and expire on their own
+                // (ttlMs) or, with hold, live exactly as long as this connection.
+                const params = p;
+                if (!params.harness || !params.sessionId || !params.event) {
+                    throw new ProtocolError("invalid", "hook_once: harness, sessionId and event are required");
+                }
+                const now = Date.now();
+                for (const [k, v] of this.hookKeys)
+                    if (!v.sock && v.expiresAt <= now)
+                        this.hookKeys.delete(k);
+                const key = JSON.stringify([params.harness, params.sessionId, params.event, params.occurrence ?? ""]);
+                if (this.hookKeys.has(key))
+                    return [{ first: false }, undefined];
+                const ttl = Math.min(Math.max(Number(params.ttlMs ?? HOOK_ONCE_DEFAULT_TTL_MS) || HOOK_ONCE_DEFAULT_TTL_MS, 1_000), HOOK_ONCE_MAX_TTL_MS);
+                this.hookKeys.set(key, params.hold ? { expiresAt: Infinity, sock } : { expiresAt: now + ttl });
+                return [{ first: true }, undefined];
+            }
             case "admin_list":
                 return [{ holders: m.diagnose((e) => jobAlive(e.pid, e.pgid, e.pidStartTime)), latestEventId: m.latestEventId() }, undefined];
             case "admin_release": {
@@ -863,3 +946,20 @@ export function processStartTime(pid) {
         return undefined;
     }
 }
+/**
+ * Daemon entry point of the newer client's copy (issue #53), or null to
+ * fall back to the same-argv respawn. The hint must name a load-lock
+ * package root whose on-disk version equals the version the client
+ * claimed, with a dist/core/daemon-main.js. The hint arrives over the
+ * same-user socket, so following it grants no privilege the client did
+ * not already have (it could run that file itself).
+ */
+export function restartEntry(clientRoot, clientVersion) {
+    if (!clientRoot)
+        return null;
+    const found = inspectPackageRoot(clientRoot);
+    if (!found || found.version !== clientVersion)
+        return null;
+    const entry = join(found.path, "dist", "core", "daemon-main.js");
+    return existsSync(entry) ? entry : null;
+}

package/dist/core/persist.d.ts

@@ -1,9 +1,12 @@
 import { MachineConfig, ConfigHistoryEntry, JournalEntry } from "../shared/protocol.js";
 export declare function stateDir(override?: string): string;
 export declare function socketPath(override?: string): string;
+/** Format version this code writes into config.json and journal entries. */
+export declare const STATE_FORMAT_VERSION = 1;
 export declare function loadState(dir: string): {
     config: MachineConfig;
     history: ConfigHistoryEntry[];
+    formatVersion: number;
 };
 export declare function saveState(dir: string, config: MachineConfig, history: ConfigHistoryEntry[]): void;
 export declare function journalPath(dir: string): string;