@aron98/load-lock 1.5.0 → 1.6.0

package/dist/cli/update.d.ts

@@ -1,4 +1,4 @@
-export type SelfLocationKind = "bun-global" | "npm-global" | "opencode-cache" | "repo-checkout" | "unknown";
+export type SelfLocationKind = "bun-global" | "npm-global" | "opencode-cache" | "npx-cache" | "repo-checkout" | "unknown";
 export interface SelfLocation {
     kind: SelfLocationKind;
     /** Package root of this copy. */
@@ -15,6 +15,8 @@ export interface ClassifyCtx {
     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:
@@ -22,6 +24,8 @@ export interface ClassifyCtx {
  *  - 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

package/dist/cli/update.js

@@ -3,7 +3,7 @@
  * 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, unknown locations) rather than guessing. After a
+ * 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.
@@ -24,7 +24,7 @@ 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 { opencodeCacheRoot, PKG_NAME } from "../shared/pkginfo.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"). */
@@ -39,6 +39,8 @@ function isUnder(dir, root) {
  *  - 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
@@ -54,6 +56,9 @@ export function classifySelf(pkgRoot, ctx) {
     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})` };
@@ -63,7 +68,7 @@ export function classifySelf(pkgRoot, ctx) {
             break;
         dir = parent;
     }
-    return { kind: "unknown", path: pkgRoot, detail: "not a recognized bun/npm global, opencode cache, or git checkout location" };
+    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) {
@@ -78,6 +83,13 @@ export function planUpdate(loc) {
                 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",
@@ -170,6 +182,7 @@ export async function updateCommand(opts) {
         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);

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;

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/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