@aron98/load-lock 1.4.0 → 1.6.0

package/dist/test/ace-opencode.test.js

@@ -0,0 +1,287 @@
+/**
+ * ACE detection of the `ace/opencode/` pointer folder (issue #79).
+ *
+ * Reimplements ACE's repo-sync discovery as of TNG/ace@b703410
+ * (https://github.com/TNG/ace/tree/b703410218833071800cc918cb95718e0404640a):
+ *  - backend/app/features/repo_ingestion/service/repo_ingest/
+ *    repo_ingestion_archive_discovery_service.py: `_discover`,
+ *    `_opencode_local_candidates`, `_npm_plugin_candidates`
+ *  - backend/app/domain/kinds/__init__.py: `detect_kind`,
+ *    `entry_point_filenames` (SPEC order skill, subagent, mcp, policy, plugin)
+ *  - backend/app/domain/kinds/plugin_kind.py: `ENTRY_POINT_PATH`,
+ *    `OPENCODE_LOCAL_ENTRY_POINT`, `OPENCODE_PLUGIN_DIRS`,
+ *    `opencode_local_plugin_dir`, `_resolve_package_main`,
+ *    `resolve_npm_entry_point`, `is_opencode_npm_candidate`,
+ *    `derive_npm_plugin_name`
+ * and runs it over this repo's git tree (what a GitHub zipball contains).
+ * Light: files only, no daemon.
+ */
+import test from "node:test";
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync, readFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(HERE, "..", "..");
+// plugin_kind.py
+const ENTRY_POINT_PATH = ".claude-plugin/plugin.json";
+const OPENCODE_LOCAL_ENTRY_POINT = ".opencode/plugins/plugin.ts";
+const OPENCODE_PLUGIN_DIRS = [".opencode/plugins", ".opencode/plugin"];
+const JS_ENTRY_EXTENSIONS = [".ts", ".js", ".mjs", ".cjs"];
+// kinds/__init__.py: each SPEC's entry_point_filename, in SPEC order.
+const KIND_ENTRIES = [
+    ["skill", ["SKILL.md"]],
+    ["subagent", ["AGENT.md"]],
+    ["mcp", ["mcp.json"]],
+    ["policy", ["policy.md"]],
+    ["plugin", [ENTRY_POINT_PATH, OPENCODE_LOCAL_ENTRY_POINT]],
+];
+function detectKind(names) {
+    const matched = KIND_ENTRIES.filter(([, entries]) => entries.some((e) => names.has(e))).map(([k]) => k);
+    return matched.length === 1 ? matched[0] : null;
+}
+function loadPackageJson(files) {
+    const raw = files.get("package.json");
+    if (raw === undefined)
+        return null;
+    try {
+        const m = JSON.parse(raw);
+        return m && typeof m === "object" && !Array.isArray(m) ? m : null;
+    }
+    catch {
+        return null;
+    }
+}
+const normaliseRelpath = (p) => {
+    p = p.replace(/\\/g, "/");
+    return p.startsWith("./") ? p.slice(2) : p;
+};
+function resolvePackageMain(m) {
+    const main = m.main;
+    if (typeof main === "string" && main.trim())
+        return normaliseRelpath(main);
+    const exp = m.exports;
+    let candidate = null;
+    if (typeof exp === "string")
+        candidate = exp;
+    else if (exp && typeof exp === "object") {
+        const root = exp["."];
+        if (typeof root === "string")
+            candidate = root;
+        else if (root && typeof root === "object") {
+            const r = root;
+            candidate = r.import || r.require || r.default; // Python `or` chain
+        }
+    }
+    return typeof candidate === "string" ? normaliseRelpath(candidate) : null;
+}
+function opencodeLocalPluginDir(path) {
+    const p = path.replace(/\\/g, "/");
+    if (!JS_ENTRY_EXTENSIONS.some((e) => p.endsWith(e)))
+        return null;
+    for (const pdir of OPENCODE_PLUGIN_DIRS) {
+        const seg = pdir + "/";
+        if (p.startsWith(seg)) {
+            if (!p.slice(seg.length).includes("/"))
+                return "";
+        }
+        else {
+            const marker = "/" + seg;
+            const i = p.indexOf(marker);
+            if (i !== -1 && !p.slice(i + marker.length).includes("/"))
+                return p.slice(0, i);
+        }
+    }
+    return null;
+}
+function resolveNpmEntryPoint(files) {
+    const m = loadPackageJson(files);
+    if (m === null)
+        return null;
+    const entry = resolvePackageMain(m);
+    return entry !== null && files.has(entry) ? entry : null;
+}
+function isOpencodeNpmCandidate(files, entry) {
+    if (!JS_ENTRY_EXTENSIONS.some((e) => entry.endsWith(e)))
+        return false;
+    const m = loadPackageJson(files);
+    if (m === null)
+        return false;
+    let haystack = typeof m.name === "string" ? m.name : "";
+    if (Array.isArray(m.keywords))
+        haystack += " " + m.keywords.filter((k) => typeof k === "string").join(" ");
+    return haystack.toLowerCase().includes("opencode");
+}
+function deriveNpmPluginName(files) {
+    const name = loadPackageJson(files)?.name;
+    if (typeof name !== "string" || !name.trim())
+        return null;
+    return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || null;
+}
+function npmPluginCandidates(files, claimed) {
+    const dirs = new Set();
+    for (const p of files.keys()) {
+        if (p === "package.json")
+            dirs.add("");
+        else if (p.endsWith("/package.json"))
+            dirs.add(p.slice(0, -"/package.json".length));
+    }
+    const out = new Map();
+    for (const d of dirs) {
+        if (claimed.has(d))
+            continue;
+        const prefix = d === "" ? "" : d + "/";
+        const local = new Map();
+        for (const [p, data] of files)
+            if (p === d || p.startsWith(prefix))
+                local.set(p.slice(prefix.length), data);
+        const entry = resolveNpmEntryPoint(local);
+        if (entry !== null && isOpencodeNpmCandidate(local, entry))
+            out.set(d, entry);
+    }
+    return out;
+}
+function discover(files) {
+    const entries = KIND_ENTRIES.flatMap(([, e]) => e);
+    const roots = new Map();
+    const add = (d, e) => (roots.get(d) ?? roots.set(d, new Set()).get(d)).add(e);
+    for (const p of files.keys()) {
+        for (const entry of entries) {
+            if (p === entry)
+                add("", entry);
+            else if (p.endsWith("/" + entry))
+                add(p.slice(0, -(entry.length + 1)), entry);
+        }
+    }
+    const discovered = [];
+    const skips = [];
+    for (const [d, present] of roots) {
+        const kind = detectKind(present);
+        if (kind === null) {
+            skips.push(`${d || "<root>"}: ambiguous entry-point files ${[...present].sort().join(",")}`);
+            continue;
+        }
+        let format = null;
+        if (kind === "plugin") {
+            const claude = present.has(ENTRY_POINT_PATH);
+            if (claude && present.has(OPENCODE_LOCAL_ENTRY_POINT))
+                skips.push(`${d || "<root>"}: both Claude Code and OpenCode plugin entry points present`);
+            format = claude ? "claude" : "opencode";
+        }
+        discovered.push({ subpath: d, kind, format, npmEntryPoint: null });
+    }
+    let claimed = new Set(roots.keys());
+    const claudeDirs = new Set(discovered.filter((x) => x.kind === "plugin" && x.format === "claude").map((x) => x.subpath));
+    const localDirs = new Set();
+    for (const p of files.keys()) {
+        const d = opencodeLocalPluginDir(p);
+        if (d !== null)
+            localDirs.add(d);
+    }
+    for (const d of [...localDirs].filter((x) => !claimed.has(x)).sort()) {
+        discovered.push({ subpath: d, kind: "plugin", format: "opencode", npmEntryPoint: null });
+        skips.push(`${d || "<root>"}: detected as a local OpenCode plugin (.opencode/plugins/) — verify before registering`);
+    }
+    for (const d of [...localDirs].filter((x) => claudeDirs.has(x)).sort()) {
+        skips.push(`${d || "<root>"}: both Claude Code and OpenCode plugin entry points present`);
+    }
+    claimed = new Set([...claimed, ...localDirs]);
+    for (const [d, entry] of npmPluginCandidates(files, claimed)) {
+        discovered.push({ subpath: d, kind: "plugin", format: "opencode", npmEntryPoint: entry });
+        skips.push(`${d || "<root>"}: detected as an npm-distributed OpenCode plugin via package.json heuristic — verify before registering`);
+    }
+    return { discovered, skips };
+}
+// ------------------------------------------------------------ fixtures
+/** The repo's git tree (tracked + untracked-not-ignored), as a GitHub zipball would carry it. */
+function repoTree() {
+    const r = spawnSync("git", ["ls-files", "-z", "--cached", "--others", "--exclude-standard"], { cwd: REPO_ROOT, encoding: "utf8" });
+    if (r.status !== 0)
+        return null;
+    const files = new Map();
+    for (const p of r.stdout.split("\0")) {
+        if (!p || !existsSync(join(REPO_ROOT, p)))
+            continue; // deleted-but-staged
+        files.set(p, p.endsWith(".json") ? readFileSync(join(REPO_ROOT, p), "utf8") : "");
+    }
+    return files;
+}
+const opencodePlugins = (d) => d.filter((x) => x.kind === "plugin" && x.format === "opencode");
+// ------------------------------------------------------------ tests
+test("ace-opencode: mirror matches ACE on known shapes", () => {
+    // Root package.json whose entry is gitignored build output: not detected (#64 finding).
+    const root = discover(new Map([["package.json", JSON.stringify({ name: "@aron98/load-lock", keywords: ["opencode"], exports: { ".": { default: "./dist/x.js" } } })]]));
+    assert.deepEqual(opencodePlugins(root.discovered), []);
+    // Resolvable entry but no "opencode" naming signal: not detected.
+    const noSignal = discover(new Map([["p/package.json", JSON.stringify({ name: "x", main: "i.js" })], ["p/i.js", ""]]));
+    assert.deepEqual(opencodePlugins(noSignal.discovered), []);
+    // A folder claimed by a Claude plugin manifest is never an npm candidate.
+    const claimed = discover(new Map([
+        ["p/package.json", JSON.stringify({ name: "x-opencode", main: "i.js" })],
+        ["p/i.js", ""],
+        ["p/.claude-plugin/plugin.json", "{}"],
+    ]));
+    assert.deepEqual(opencodePlugins(claimed.discovered), []);
+    // exports "." import condition wins over require/default.
+    const exp = discover(new Map([
+        ["p/package.json", JSON.stringify({ name: "y", keywords: ["OpenCode"], exports: { ".": { import: "./a.mjs", default: "./b.js" } } })],
+        ["p/a.mjs", ""],
+    ]));
+    assert.deepEqual(opencodePlugins(exp.discovered).map((x) => [x.subpath, x.npmEntryPoint]), [["p", "a.mjs"]]);
+});
+test("ace-opencode: this repo yields exactly one OpenCode plugin, at ace/opencode", (t) => {
+    const files = repoTree();
+    if (files === null)
+        return t.skip("not a git checkout");
+    assert.ok(files.has("ace/opencode/package.json"), "ace/opencode/package.json must be tracked");
+    const { discovered, skips } = discover(files);
+    const oc = opencodePlugins(discovered);
+    assert.deepEqual(oc.map((x) => [x.subpath, x.npmEntryPoint]), [["ace/opencode", "index.js"]], JSON.stringify(discovered));
+    // Detected only via the npm heuristic, never via a flat entry point or a local .opencode/plugins/ file.
+    assert.ok(!discovered.some((x) => x.subpath === "ace/opencode" && x.npmEntryPoint === null));
+    // No ambiguity / dual-format skip for the folder; ACE's only note is the informational "verify before registering".
+    const ours = skips.filter((s) => s.startsWith("ace/opencode:"));
+    assert.equal(ours.length, 1, ours.join("\n"));
+    assert.match(ours[0], /npm-distributed OpenCode plugin .* verify before registering/);
+    assert.ok(!skips.some((s) => s.includes("ambiguous") || s.includes("both Claude Code and OpenCode")), skips.join("\n"));
+    // Artifact name ACE derives from package.json.
+    const bundle = new Map();
+    for (const [p, d] of files)
+        if (p.startsWith("ace/opencode/"))
+            bundle.set(p.slice("ace/opencode/".length), d);
+    assert.equal(deriveNpmPluginName(bundle), "load-lock-opencode");
+});
+test("ace-opencode: folder is a thin pointer to the published package, pinned to package.json", () => {
+    const dir = join(REPO_ROOT, "ace", "opencode");
+    const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+    const version = JSON.parse(readFileSync(join(REPO_ROOT, "package.json"), "utf8")).version;
+    assert.equal(pkg.private, true, "never publishable by accident");
+    assert.equal(pkg.dependencies["@aron98/load-lock"], version);
+    const code = readFileSync(join(dir, pkg.main), "utf8")
+        .split("\n")
+        .filter((l) => l.trim() && !l.trim().startsWith("//"));
+    assert.deepEqual(code, [`export { default } from "@aron98/load-lock";`]);
+});
+test("ace-opencode: pin is declared in check-pins and --write rewrites it", async () => {
+    const script = join(REPO_ROOT, "scripts", "check-pins.mjs");
+    const pins = await import(pathToFileURL(script).href);
+    const entry = pins.PINNED.find((e) => e.path === "ace/opencode/package.json");
+    assert.deepEqual(entry, { path: "ace/opencode/package.json", kind: "json", key: "dependencies.@aron98/load-lock" });
+    const root = mkdtempSync(join(tmpdir(), "ll-aceoc-"));
+    try {
+        mkdirSync(join(root, "ace", "opencode"), { recursive: true });
+        const src = readFileSync(join(REPO_ROOT, "ace", "opencode", "package.json"), "utf8");
+        writeFileSync(join(root, "ace", "opencode", "package.json"), src.replace(/"@aron98\/load-lock": "[^"]+"/, `"@aron98/load-lock": "0.0.1"`));
+        assert.equal(pins.checkPins(root, "9.9.9", [entry]).length, 1);
+        assert.deepEqual(pins.writePins(root, "9.9.9", [entry]), ["ace/opencode/package.json"]);
+        assert.deepEqual(pins.checkPins(root, "9.9.9", [entry]), []);
+        const after = JSON.parse(readFileSync(join(root, "ace", "opencode", "package.json"), "utf8"));
+        assert.equal(after.dependencies["@aron98/load-lock"], "9.9.9");
+        assert.equal(after.name, "load-lock-opencode");
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});

package/dist/test/check-pins.test.d.ts

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

package/dist/test/check-pins.test.js

@@ -0,0 +1,108 @@
+/**
+ * Tests for the version-pin sync check (issue #48): scripts/check-pins.mjs
+ * over planted files in a temp root, plus the real script on this repo.
+ * Light: no daemon, files only.
+ */
+import test from "node:test";
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(HERE, "..", "..");
+const SCRIPT = join(REPO_ROOT, "scripts", "check-pins.mjs");
+const pins = (await import(pathToFileURL(SCRIPT).href));
+function plant(files) {
+    const root = mkdtempSync(join(tmpdir(), "ll-pins-"));
+    for (const [rel, body] of Object.entries(files)) {
+        mkdirSync(dirname(join(root, rel)), { recursive: true });
+        writeFileSync(join(root, rel), body);
+    }
+    return root;
+}
+const DECLARED = [
+    { path: "skills/load-lock/SKILL.md", kind: "spec" },
+    { path: "ace/mcp.json", kind: "spec" },
+    { path: "plugin/.claude-plugin/plugin.json", kind: "json", key: "version" },
+];
+function plantedRepo(skillPin, mcpPin, pluginVersion) {
+    return plant({
+        "skills/load-lock/SKILL.md": `Else run \`npx -y @aron98/load-lock@${skillPin} status\`.\n` +
+            `Upgrade with \`npm i -g @aron98/load-lock@latest\` (unpinned, ignored).\n`,
+        "ace/mcp.json": JSON.stringify({ mcpServers: { "load-lock": { command: "npx", args: ["-y", `@aron98/load-lock@${mcpPin}`] } } }, null, 2) + "\n",
+        "plugin/.claude-plugin/plugin.json": JSON.stringify({ name: "load-lock", version: pluginVersion, description: "x" }, null, 2) + "\n",
+    });
+}
+test("check-pins: in-sync planted files pass", () => {
+    const root = plantedRepo("1.6.0", "1.6.0", "1.6.0");
+    try {
+        assert.deepEqual(pins.checkPins(root, "1.6.0", DECLARED), []);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test("check-pins: mismatches are reported per pin, then --write fixes them all", () => {
+    const root = plantedRepo("1.5.0", "1.6.0-rc.1", "1.4.2");
+    try {
+        const problems = pins.checkPins(root, "1.6.0", DECLARED);
+        assert.equal(problems.length, 3, problems.join("\n"));
+        assert.ok(problems.some((p) => p.startsWith("skills/load-lock/SKILL.md:1: pins 1.5.0")), problems.join("\n"));
+        assert.ok(problems.some((p) => p.includes("ace/mcp.json") && p.includes("1.6.0-rc.1")), problems.join("\n"));
+        assert.ok(problems.some((p) => p.includes("plugin.json (version): pins 1.4.2")), problems.join("\n"));
+        const changed = pins.writePins(root, "1.6.0", DECLARED);
+        assert.deepEqual(changed.sort(), DECLARED.map((d) => d.path).sort());
+        assert.deepEqual(pins.checkPins(root, "1.6.0", DECLARED), []);
+        const skill = readFileSync(join(root, "skills/load-lock/SKILL.md"), "utf8");
+        assert.match(skill, /@aron98\/load-lock@1\.6\.0 status/);
+        assert.match(skill, /@aron98\/load-lock@latest/, "non-version tags are left alone");
+        const plugin = JSON.parse(readFileSync(join(root, "plugin/.claude-plugin/plugin.json"), "utf8"));
+        assert.deepEqual(plugin, { name: "load-lock", version: "1.6.0", description: "x" });
+        // idempotent
+        assert.deepEqual(pins.writePins(root, "1.6.0", DECLARED), []);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test("check-pins: --write keeps a JSON file's own formatting", () => {
+    const body = `{\n  "name": "load-lock-plugin",\n  "version": "1.5.0",\n  "keywords": ["a", "b"],\n` +
+        `  "deps": { "@aron98/load-lock": "1.5.0" }\n}\n`;
+    const root = plant({ "p.json": body });
+    const declared = [
+        { path: "p.json", kind: "json", key: "version" },
+        { path: "p.json", kind: "json", key: "deps.@aron98/load-lock" },
+    ];
+    try {
+        pins.writePins(root, "1.6.0", declared);
+        assert.equal(readFileSync(join(root, "p.json"), "utf8"), body.replaceAll("1.5.0", "1.6.0"));
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test("check-pins: a declared file that is missing or lost its pin fails", () => {
+    const root = plant({ "skills/load-lock/SKILL.md": "use `npx -y @aron98/load-lock@latest`\n" });
+    try {
+        const problems = pins.checkPins(root, "1.6.0", [
+            { path: "skills/load-lock/SKILL.md", kind: "spec" },
+            { path: "ace/mcp.json", kind: "spec" },
+        ]);
+        assert.equal(problems.length, 2, problems.join("\n"));
+        assert.match(problems[0], /SKILL\.md: no @aron98\/load-lock@<version> pin found/);
+        assert.match(problems[1], /ace\/mcp\.json: declared pinned file is missing/);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test("check-pins: the script passes on this repo", () => {
+    const r = spawnSync(process.execPath, [SCRIPT], { encoding: "utf8" });
+    assert.equal(r.status, 0, r.stdout + r.stderr);
+    assert.match(r.stdout, /pins ok/);
+    // every declared path is relative and inside the repo
+    for (const e of pins.PINNED)
+        assert.ok(!e.path.startsWith("/") && !e.path.includes(".."), e.path);
+});

package/dist/test/compat.test.d.ts

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

package/dist/test/compat.test.js

@@ -0,0 +1,190 @@
+/**
+ * Persisted state format compatibility (issue #51): a state dir written by a
+ * NEWER format (higher formatVersion, extra fields, unknown journal entry
+ * kinds) must load in the current code, and unknown fields must survive a
+ * rewrite. Also: what we write stays readable by older daemons (the journal
+ * stays a bare array; config.json keeps `config` + `history`).
+ */
+import test from "node:test";
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { LLClient } from "../shared/client.js";
+import { Machine } from "../core/state.js";
+import { loadState, saveState, loadJournal, saveJournal, STATE_FORMAT_VERSION } from "../core/persist.js";
+import { daemonMainPath, probe, until } from "./testutil.js";
+const TMP_BASE = process.env.LL_TEST_TMP ?? join(tmpdir(), "opencode");
+mkdirSync(TMP_BASE, { recursive: true });
+const FUTURE = STATE_FORMAT_VERSION + 7;
+function newerConfigFile() {
+    return {
+        formatVersion: FUTURE,
+        futureTopLevel: { keep: "me" },
+        config: {
+            version: 4,
+            pools: { heavy: { capacity: 2, futurePoolField: "pool-x" }, gpu: { capacity: 1 } },
+            offerTimeoutMs: 30_000,
+            maxWaitMs: 5_000,
+            maxTurnWaitMs: 600_000,
+            startTimeoutMs: 120_000,
+            untrackedLeaseMs: 15 * 60_000,
+            guidance: { notes: "n", futureGuidance: 42 },
+            futureConfigField: ["a", "b"],
+        },
+        history: [{ ts: 1, author: "newer", reason: "r", changes: {}, resultingVersion: 4, futureHistoryField: true }],
+    };
+}
+function newerJournal(now) {
+    return [
+        // a held permit with an extra field + newer per-entry version
+        {
+            formatVersion: FUTURE,
+            requestId: "req_held",
+            pool: "heavy",
+            agentId: "A",
+            opKey: "op1",
+            reason: "build",
+            weight: 1,
+            state: "held",
+            permitToken: "pmt_held",
+            phase: "running_untracked",
+            claimedAt: now,
+            futureEntryField: { x: 1 },
+        },
+        // an entry kind this version doesn't know
+        { formatVersion: FUTURE, requestId: "req_future", pool: "heavy", agentId: "B", opKey: "op", reason: "r", weight: 1, state: "suspended", claimedAt: now },
+        // a held permit in a phase this version doesn't know
+        { requestId: "req_phase", pool: "gpu", agentId: "C", opKey: "op", reason: "r", weight: 1, state: "held", permitToken: "pmt_phase", phase: "paused_by_future", claimedAt: now },
+        // malformed garbage
+        "not an entry",
+        { state: "held" },
+        // a queued request with an extra field
+        { requestId: "req_q", pool: "heavy", agentId: "D", opKey: "op", reason: "r", weight: 1, state: "queued", enqueuedAt: now, claimedAt: now, futureQueued: "q" },
+    ];
+}
+function tmpDir() {
+    return mkdtempSync(join(TMP_BASE, "ll-compat-"));
+}
+test("compat: newer config.json loads and unknown fields survive a config change", () => {
+    const dir = tmpDir();
+    try {
+        writeFileSync(join(dir, "config.json"), JSON.stringify(newerConfigFile()));
+        const st = loadState(dir);
+        assert.equal(st.formatVersion, FUTURE);
+        assert.equal(st.config.pools.heavy.capacity, 2);
+        const m = new Machine(Date.now, st.config);
+        m.history.push(...st.history);
+        m.configure({ expectedVersion: 4, changes: { pools: { heavy: { capacity: 3 } }, guidance: { notes: "n2" } }, reason: "t", author: "me" });
+        saveState(dir, m.config, m.history);
+        const raw = JSON.parse(readFileSync(join(dir, "config.json"), "utf8"));
+        assert.equal(raw.formatVersion, STATE_FORMAT_VERSION);
+        assert.deepEqual(raw.futureTopLevel, { keep: "me" });
+        assert.deepEqual(raw.config.futureConfigField, ["a", "b"]);
+        assert.equal(raw.config.pools.heavy.capacity, 3);
+        assert.equal(raw.config.pools.heavy.futurePoolField, "pool-x");
+        assert.equal(raw.config.guidance.notes, "n2");
+        assert.equal(raw.config.guidance.futureGuidance, 42);
+        assert.equal(raw.history[0].futureHistoryField, true);
+        assert.equal(raw.history.length, 2);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test("compat: pre-versioning config.json reads as format 0; our writes keep the old shape", () => {
+    const dir = tmpDir();
+    try {
+        const old = newerConfigFile();
+        writeFileSync(join(dir, "config.json"), JSON.stringify({ config: old.config, history: [] }));
+        const st = loadState(dir);
+        assert.equal(st.formatVersion, 0);
+        saveState(dir, st.config, st.history);
+        const raw = JSON.parse(readFileSync(join(dir, "config.json"), "utf8"));
+        // older daemons read exactly `config` + `history`
+        assert.equal(typeof raw.config, "object");
+        assert.ok(Array.isArray(raw.history));
+        // journal stays a bare array (what every released daemon reads)
+        saveJournal(dir, [{ requestId: "r", pool: "heavy", agentId: "A", opKey: "o", reason: "r", weight: 1, claimedAt: 1, state: "queued" }]);
+        const j = JSON.parse(readFileSync(join(dir, "journal.json"), "utf8"));
+        assert.ok(Array.isArray(j));
+        assert.equal(j[0].formatVersion, STATE_FORMAT_VERSION);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test("compat: unknown journal entry kinds don't break restore; unknown fields round-trip", () => {
+    const dir = tmpDir();
+    try {
+        const now = Date.now();
+        writeFileSync(join(dir, "config.json"), JSON.stringify(newerConfigFile()));
+        writeFileSync(join(dir, "journal.json"), JSON.stringify(newerJournal(now)));
+        const st = loadState(dir);
+        const m = new Machine(Date.now, st.config);
+        const res = m.restore(loadJournal(dir), () => null);
+        assert.equal(res.kept, 2, "held + unknown-phase held");
+        assert.equal(res.queued, 1);
+        assert.equal(res.skipped, 2, "unknown kind + malformed entry");
+        const ev = m.eventsSince(0).find((e) => e.type === "daemon_recovered");
+        assert.match(String(ev?.detail), /skipped 2 unrecognized/, "skips are reported in the recovery event");
+        // unknown phase: kept, conservatively as untracked with a lease
+        const out = m.journalEntries();
+        const phase = out.find((e) => e.requestId === "req_phase");
+        assert.equal(phase.phase, "running_untracked");
+        assert.ok(phase.leaseDeadline && phase.leaseDeadline > now);
+        // unknown per-entry fields are written back while the entry lives
+        saveJournal(dir, out);
+        const back = loadJournal(dir);
+        assert.deepEqual(back.find((e) => e.requestId === "req_held").futureEntryField, { x: 1 });
+        assert.equal(back.find((e) => e.requestId === "req_q").futureQueued, "q");
+        assert.ok(back.every((e) => e.formatVersion === STATE_FORMAT_VERSION));
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test("compat: a daemon started on a newer-format state dir serves it and preserves unknown fields", async () => {
+    const dir = tmpDir();
+    const sock = join(dir, "daemon.sock");
+    writeFileSync(join(dir, "config.json"), JSON.stringify(newerConfigFile()));
+    writeFileSync(join(dir, "journal.json"), JSON.stringify(newerJournal(Date.now())));
+    const child = spawn(process.execPath, [daemonMainPath, "--state-dir", dir, "--socket", sock], {
+        stdio: ["ignore", "pipe", "pipe"],
+        env: { ...process.env, LOAD_LOCK_STATE_DIR: dir, LOAD_LOCK_SOCKET: sock },
+    });
+    try {
+        await until("daemon listens", async () => await probe(sock));
+        const c = new LLClient({ socket: sock, stateDir: dir, spawnDaemon: false });
+        await c.connect();
+        const st = (await c.request("status", {}));
+        const heavy = st.pools.find((p) => p.pool === "heavy");
+        assert.ok(heavy, "heavy pool present");
+        assert.equal(heavy.holders.length, 1, "known held permit restored");
+        const cfg = (await c.request("get_config", {}));
+        await c.request("configure", {
+            expectedVersion: cfg.config.version,
+            changes: { pools: { heavy: { capacity: 5 } } },
+            reason: "compat test",
+            author: "test",
+        });
+        // the restored token still releases
+        const rel = (await c.request("release", { permitToken: "pmt_held" }));
+        assert.equal(rel.releasedNow, true);
+        c.close();
+        const raw = JSON.parse(readFileSync(join(dir, "config.json"), "utf8"));
+        assert.equal(raw.config.pools.heavy.capacity, 5);
+        assert.equal(raw.config.pools.heavy.futurePoolField, "pool-x");
+        assert.deepEqual(raw.config.futureConfigField, ["a", "b"]);
+        assert.deepEqual(raw.futureTopLevel, { keep: "me" });
+        const j = JSON.parse(readFileSync(join(dir, "journal.json"), "utf8"));
+        assert.ok(Array.isArray(j));
+        assert.equal(j.find((e) => e.requestId === "req_q")?.futureQueued, "q");
+    }
+    finally {
+        child.kill("SIGTERM");
+        await new Promise((r) => (child.exitCode !== null ? r() : child.once("exit", () => r())));
+        rmSync(dir, { recursive: true, force: true });
+    }
+});