skillrepo 4.17.0 → 4.17.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillrepo",
-  "version": "4.17.0",
+  "version": "4.17.1",
   "description": "Pull-based CLI for agent skills — init, sync, search, add, remove your library, synced across your dev environment",
   "type": "module",
   "bin": {

package/src/commands/list-render.mjs

@@ -46,7 +46,12 @@ export function formatLibraryJson(rows, metaByKey) {
       return {
         owner: r.owner,
         name: r.name,
+        // #2824 R1/R4 — `version` is the INSTALLED (on-disk) version;
+        // `servedVersion` is the server's served/available version. Distinct,
+        // correctly-labeled fields (pre-#2824 the top-level `version` was the
+        // server's, with no installed-version field at all).
         version: r.version,
+        servedVersion: r.servedVersion ?? null,
         description: meta?.description ?? null,
         updatedAt: meta?.updatedAt ?? null,
         filesIncomplete: meta?.filesIncomplete ?? false,
@@ -101,7 +106,10 @@ export function formatSkillsetJson({ skillsetRef, repoName, rows, metaByKey, com
         return {
           owner: r.owner,
           name: r.name,
+          // #2824 R1/R4 — installed (disk) version + the server's served/
+          // available version as distinct fields, mirroring the whole-library JSON.
           version: r.version,
+          servedVersion: r.servedVersion ?? null,
           // description/updatedAt mirror the whole-library JSON (they come
           // from the probe's manifest response) so both views' machine
           // output matches too, not just the tables.
@@ -472,15 +480,28 @@ export function renderSignal(row, useGlyphs, variant = "library") {
     case SIGNAL.EDITED:
       return { chip: g("✎ edited", "EDITED"), suffix: "local changes — sync won't overwrite" };
     case SIGNAL.SERVING: {
-      // Governance rollback (#2787 SERVING): the row's own `version` is the
-      // served fallback; `governance.recalledVersion` is what was pulled.
+      // Governance rollback (#2787 SERVING). The Version column shows the
+      // INSTALLED version on disk (#2824 R1); this reason names what was
+      // recalled (`governance.recalledVersion`) and what the SERVER now serves
+      // (`row.servedVersion`). It reads `servedVersion`, NOT `row.version` —
+      // `row.version` is the disk version, not the rollback.
       const recalled = row.governance?.recalledVersion ?? null;
-      const served = row.version ?? null;
+      const served = row.servedVersion ?? null;
+      // "run update" ONLY when the installed version still differs from the
+      // served rollback — i.e. you still hold the recalled version and syncing
+      // actually changes something. Once you are synced to the rollback
+      // (installed === served), SERVING persists to flag the rollback, but
+      // there is nothing to update — a "run update" CTA there is a no-op that
+      // erodes trust in the guidance (reviewer finding, #2824). This is the
+      // common steady state AFTER a user complies with a recall.
+      const onRollback = served !== null && served === (row.version ?? null);
       return {
         chip: g("⚠ serving", "SERVING"),
         suffix:
           recalled && served
-            ? `${recalled} recalled — rolled back to ${served}`
+            ? onRollback
+              ? `${recalled} recalled — server serves ${served}`
+              : `${recalled} recalled — server serves ${served} — run update`
             : "a newer version was recalled — serving a rollback",
       };
     }
@@ -495,7 +516,9 @@ export function renderSignal(row, useGlyphs, variant = "library") {
       // declared repo already flags as non-compliant and re-syncs.)
       return { chip: g("⚠ withdrawn", "WITHDRAWN"), suffix: "no longer served — remove?" };
     case SIGNAL.BEHIND: {
-      const v = row.version ?? null;
+      // The "available" version is what the SERVER serves (#2824 R2), NOT
+      // `row.version` — that is the older installed version on disk.
+      const v = row.servedVersion ?? null;
       return {
         chip: g("↑ behind", "BEHIND"),
         suffix: v ? `${v} available — run update` : "a newer version is available — run update",
@@ -565,7 +588,15 @@ function computeColWidths(terminalColumns) {
   return [skillCol, versionCol, stateCol, updatedCol, descCol];
 }
 
-function truncate(s, n) {
+/**
+ * Cap a string at `n` visible chars, ellipsizing the overflow. Exported for
+ * direct unit testing (#2824 audit): the integration table test cannot guard
+ * this — cli-table3's own `wordWrap` produces an ellipsis and drops the full
+ * string regardless of whether this ran, so removing it left every table
+ * assertion green. This is a real cap (it bounds ROW HEIGHT for very long
+ * descriptions before cli-table3 wraps), so it is unit-tested on its own.
+ */
+export function truncate(s, n) {
   if (s.length <= n) return s;
   return s.slice(0, n - 1) + "…";
 }

package/src/lib/list-engine.mjs

@@ -290,7 +290,11 @@ export function classifyRows({
         finalizeRow({
           owner: exp.owner,
           name: exp.name,
+          // Served but guard-refused → nothing of ours on disk. Show the
+          // declared version (what it WOULD be), marked not-installed by the
+          // classification. No server-truth lookup happens on this branch.
           version: exp.version ?? null,
+          servedVersion: null,
           classification: CLASSIFICATION.NOT_DELIVERED,
           local: LOCAL_STATE.MISSING,
           governance: null,
@@ -313,7 +317,12 @@ export function classifyRows({
         finalizeRow({
           owner: exp.owner,
           name: exp.name,
+          // Not on disk → there is no installed version to report. The spec's
+          // not-installed rule shows the server/expected version instead; the
+          // MISSING classification is what marks it not-installed. `version`
+          // and `servedVersion` coincide here — both are the server's.
           version: server?.servedVersion ?? exp.version ?? baseline?.version ?? null,
+          servedVersion: server?.servedVersion ?? null,
           classification: CLASSIFICATION.MISSING,
           local: LOCAL_STATE.MISSING,
           governance: server?.governance ?? null,
@@ -333,7 +342,15 @@ export function classifyRows({
       finalizeRow({
         owner: exp.owner,
         name: exp.name,
-        version: server?.servedVersion ?? exp.version ?? baseline?.version ?? null,
+        // #2824 R1 — THE fix. The headline version is the INSTALLED version:
+        // the `.last-sync` baseline (what the last sync wrote to disk). It is
+        // NEVER the server's served version, which would read false for a
+        // recalled-not-synced / behind / restored-not-synced row (you would be
+        // told you are on a version you are not). `null` when there is no
+        // baseline (an on-disk-but-never-synced row, which `local` already
+        // reports as MISSING) — we do not fabricate a version from the server.
+        version: baseline?.version ?? null,
+        servedVersion: server?.servedVersion ?? null,
         classification: CLASSIFICATION.TRACKED,
         local,
         governance: server?.governance ?? null,
@@ -364,7 +381,10 @@ export function classifyRows({
         finalizeRow({
           owner: orphan.owner,
           name,
+          // A disowned orphan's only version truth is what's on disk (baseline);
+          // the server no longer serves it, so there is no served version.
           version: orphan.baseline.version ?? null,
+          servedVersion: null,
           classification: CLASSIFICATION.ORPHAN,
           local,
           governance: null,
@@ -384,7 +404,10 @@ export function classifyRows({
       finalizeRow({
         owner: null,
         name,
+        // Hand-authored / never CLI-managed → no baseline, no library entry, so
+        // no known version from either side.
         version: null,
+        servedVersion: null,
         classification: CLASSIFICATION.FOREIGN,
         local: LOCAL_STATE.PRESENT,
         governance: null,

package/src/test/commands/list.test.mjs

@@ -24,6 +24,7 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 
 import { runList } from "../../commands/list.mjs";
+import { truncate } from "../../commands/list-render.mjs";
 import { EXIT_AUTH } from "../../lib/errors.mjs";
 import { computeSkillShas } from "../../lib/crypto-shas.mjs";
 import { globalLastSyncPath, globalGovernanceSeenPath } from "../../lib/paths.mjs";
@@ -121,6 +122,29 @@ function baselineEntry(version, files) {
   return { version, skillMdSha256: shas.skillMdSha256, filesSha256: shas.filesSha256, syncedAt: "x" };
 }
 
+// ════════════════════════════════════════════════════════════════════════
+// truncate helper (unit) — guards the description cap directly (#2824 audit)
+// ════════════════════════════════════════════════════════════════════════
+//
+// The integration "truncates a long description" test CANNOT guard truncate():
+// cli-table3's wordWrap emits an ellipsis and drops the contiguous long string
+// on its own, so removing truncate left that test green. This unit test asserts
+// truncate's actual contract, independent of the table renderer.
+describe("truncate", () => {
+  it("returns short strings unchanged", () => {
+    assert.equal(truncate("hello", 60), "hello");
+    assert.equal(truncate("x".repeat(60), 60), "x".repeat(60));
+  });
+
+  it("caps an over-long string at n chars, ending in a single ellipsis", () => {
+    const out = truncate("x".repeat(120), 60);
+    assert.equal(out.length, 60, "capped to exactly n visible chars");
+    assert.ok(out.endsWith("…"), "the overflow is marked with an ellipsis");
+    assert.equal(out, "x".repeat(59) + "…");
+    assert.ok(!out.includes("x".repeat(60)), "the full run is not present");
+  });
+});
+
 // ════════════════════════════════════════════════════════════════════════
 // Whole-library view
 // ════════════════════════════════════════════════════════════════════════
@@ -199,7 +223,11 @@ describe("runList — library row taxonomy", () => {
     assert.match(out, /all healthy|library in sync/);
   });
 
-  it("behind: server served version is newer than the baseline", async () => {
+  it("behind: Version column shows the INSTALLED version, the available version is context", async () => {
+    // disk/baseline = 1.0.0; the server has moved to 2.0.0. The Version column
+    // must show 1.0.0 (what you have) — the row must not read as "you're on
+    // 2.0.0". The newer 2.0.0 is named only in the attention block. (#2824
+    // R1/R2/R3; pre-fix the Version cell showed the server's 2.0.0.)
     const files = [{ path: "SKILL.md", content: SKILL_MD_BODY("aging") }];
     seedClaudeSkillOnDisk("aging", files); // disk matches baseline v1.0.0 → local present
     seedLastSync({ skills: { "alice/aging": baselineEntry("1.0.0", files) } });
@@ -208,7 +236,13 @@ describe("runList — library row taxonomy", () => {
     await runList(["--key", VALID_KEY, "--url", serverUrl], { stdout });
     const out = stdout.text();
     assert.match(out, /\bBEHIND\b/);
-    assert.match(out, /2\.0\.0 available — run update/);
+    // R3 — the row's own Version cell (the boxed table line, not the block) shows
+    // the disk version and never the server's newer version.
+    const boxedRow = out.split("\n").find((l) => l.includes("aging") && l.includes("│"));
+    assert.ok(boxedRow, "the aging row renders in the table");
+    assert.match(boxedRow, /\b1\.0\.0\b/, "R1/R3: Version column = installed (disk) version");
+    assert.doesNotMatch(boxedRow, /\b2\.0\.0\b/, "the Version cell never shows the server's newer version");
+    assert.match(out, /2\.0\.0 available — run update/, "R2: the available version is named in the attention block");
     assert.match(out, /need.? attention/);
   });
 
@@ -228,10 +262,17 @@ describe("runList — library row taxonomy", () => {
     assert.match(out, /OVERWRITES local edits/);
   });
 
-  it("serving: governance reports a recall fallback", async () => {
+  it("serving (recalled-not-synced): Version column shows the INSTALLED recalled version, the served rollback is context", async () => {
+    // THE real recall-not-synced state (#2824 R1/R2). You synced 2.0.0; the team
+    // recalled 2.0.0 and the server now serves the 1.9.0 rollback — but 2.0.0 is
+    // still on disk (the file your agent loads). The Version column must show
+    // 2.0.0 (what you have); the block names what the server serves (1.9.0) and
+    // what to do. Pre-fix the column showed 1.9.0 — the row read false. The
+    // fixture DIVERGES disk (2.0.0) from served (1.9.0); the old test set both
+    // to 1.9.0, so it could never tell "shows disk" from "shows served".
     const files = [{ path: "SKILL.md", content: SKILL_MD_BODY("sec") }];
     seedClaudeSkillOnDisk("sec", files);
-    seedLastSync({ skills: { "alice/sec": baselineEntry("1.9.0", files) } });
+    seedLastSync({ skills: { "alice/sec": baselineEntry("2.0.0", files) } });
     server.setLibraryResponse({
       skills: [
         makeSkill("alice", "sec", "1.9.0", {
@@ -245,18 +286,57 @@ describe("runList — library row taxonomy", () => {
     await runList(["--key", VALID_KEY, "--url", serverUrl], { stdout });
     const out = stdout.text();
     assert.match(out, /\bSERVING\b/);
-    // #2807: the served fallback is not green, and the reason names what was
-    // recalled and the version rolled back to (doc §4 copy, verbatim).
-    assert.match(out, /2\.0\.0 recalled — rolled back to 1\.9\.0/);
+    // R3 — the row's own Version cell shows the installed 2.0.0, never the
+    // server's 1.9.0 rollback.
+    const boxedRow = out.split("\n").find((l) => l.includes("sec") && l.includes("│"));
+    assert.ok(boxedRow, "the sec row renders in the table");
+    assert.match(boxedRow, /\b2\.0\.0\b/, "R1/R3: Version column = the installed (recalled) version on disk");
+    assert.doesNotMatch(boxedRow, /\b1\.9\.0\b/, "the Version cell never shows the server's served rollback");
+    // R2 — the attention block names what was recalled, what the server serves
+    // now, and what to do.
+    assert.match(out, /2\.0\.0 recalled — server serves 1\.9\.0 — run update/);
     assert.doesNotMatch(out, /\bLATEST\b|✓ ok/, "no green for a non-latest served version");
   });
 
+  it("serving (recalled-SYNCED): already on the rollback → states the recall but NO no-op 'run update'", async () => {
+    // The steady state AFTER a user complies with a recall: they ran update and
+    // now hold the 1.9.0 rollback (disk == served == 1.9.0), but 2.0.0 is still
+    // recalled so governance stays `serving`. This test's fixture is disk ==
+    // served BY DESIGN — that is the sync-state condition being tested (the CTA
+    // logic), NOT the version display (covered by the recalled-not-synced test
+    // above with disk ≠ served). SERVING must still flag the rollback, but must
+    // NOT tell the user to "run update" — updating changes nothing here.
+    const files = [{ path: "SKILL.md", content: SKILL_MD_BODY("sec") }];
+    seedClaudeSkillOnDisk("sec", files);
+    seedLastSync({ skills: { "alice/sec": baselineEntry("1.9.0", files) } });
+    server.setLibraryResponse({
+      skills: [
+        makeSkill("alice", "sec", "1.9.0", {
+          governance: { status: "serving", head: "2.0.0", recalledVersion: "2.0.0" },
+        }),
+      ],
+      removals: [],
+      syncedAt: "x",
+    });
+
+    await runList(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    const out = stdout.text();
+    assert.match(out, /\bSERVING\b/, "the rollback is still flagged");
+    assert.match(out, /2\.0\.0 recalled — server serves 1\.9\.0/, "the recall + served version are stated");
+    assert.doesNotMatch(out, /run update/, "no no-op CTA: you are already on the served rollback");
+  });
+
   it("missing: in the library, not on disk", async () => {
     server.setLibraryResponse({ skills: [makeSkill("alice", "ghost", "1.0.0")], removals: [], syncedAt: "x" });
     await runList(["--key", VALID_KEY, "--url", serverUrl], { stdout });
     const out = stdout.text();
     assert.match(out, /\bMISSING\b/);
     assert.match(out, /in your library, not installed/);
+    // Not-installed shows the server/expected version (spec), marked
+    // not-installed by the MISSING chip — the Version cell is not left blank.
+    const boxedRow = out.split("\n").find((l) => l.includes("ghost") && l.includes("│"));
+    assert.ok(boxedRow, "the missing row renders in the table");
+    assert.match(boxedRow, /\b1\.0\.0\b/, "not-installed: the server/expected version is shown in the Version cell");
   });
 
   it("foreign: on disk, not in the library, no baseline — no longer hidden", async () => {
@@ -379,6 +459,13 @@ describe("runList — library row taxonomy", () => {
     await runList(["--key", VALID_KEY, "--url", serverUrl], { stdout });
     const out = stdout.text();
     assert.match(out, /@alice\/recalled/, "the stranded orphan is finally visible");
+    // R1/R3 at the OUTPUT level (#2824 audit): the orphan is the one non-tracked
+    // row that carries a REAL on-disk baseline version (the stranded #2804 copy
+    // the agent still loads), so its Version cell must show that disk version —
+    // 1.2.0 — not blank. The engine field is unit-tested; this guards the render.
+    const boxedRow = out.split("\n").find((l) => l.includes("recalled") && l.includes("│"));
+    assert.ok(boxedRow, "the orphan row renders in the table");
+    assert.match(boxedRow, /\b1\.2\.0\b/, "R1: the orphan's Version cell shows the installed (disk) version");
     // #2807 + owner rule 2026-08-26: a server-disowned orphan renders as
     // cause-neutral WITHDRAWN, NEVER `recalled` — absence alone is not a
     // verified recall (could be an unpublish / unshare / skillset re-scope).
@@ -422,6 +509,12 @@ describe("runList — library row taxonomy", () => {
     assert.equal(row.signal, "behind");
     assert.deepEqual(row.governance, { status: "latest", head: "2.0.0" });
     assert.ok(Array.isArray(row.placements) && row.placements[0].vendor === "claudeCode");
+    // #2824 R4 — the disk version and the server's served version are DISTINCT,
+    // correctly-labeled fields. disk = 1.0.0 (baseline), served = 2.0.0. Pre-fix
+    // the top-level `version` was the server's (2.0.0) and `servedVersion` did
+    // not exist.
+    assert.equal(row.version, "1.0.0", "R1/R4: top-level version is the installed (disk) version");
+    assert.equal(row.servedVersion, "2.0.0", "R4: the server's served/available version is a distinct labeled field");
   });
 });
 
@@ -647,7 +740,16 @@ describe("runList — skillset-declared view", () => {
     });
 
     await runList(["--key", VALID_KEY, "--url", serverUrl], { stdout });
-    assert.match(stdout.text(), /\bBEHIND\b/, "the restore is visible even inside the sync throttle window");
+    const out = stdout.text();
+    assert.match(out, /\bBEHIND\b/, "the restore is visible even inside the sync throttle window");
+    // #2824 R1/R2/R3 — the row shows the INSTALLED 1.0.0 (the rollback still on
+    // disk); the restored 2.0.0 is named only as context. disk (1.0.0) ≠ served
+    // (2.0.0), so the Version cell distinguishes the two.
+    const boxedRow = out.split("\n").find((l) => l.includes("svc") && l.includes("│"));
+    assert.ok(boxedRow, "the svc row renders in the table");
+    assert.match(boxedRow, /\b1\.0\.0\b/, "R1/R3: Version column = installed (disk) version");
+    assert.doesNotMatch(boxedRow, /\b2\.0\.0\b/, "the Version cell never shows the restored server version");
+    assert.match(out, /2\.0\.0 available — run update/, "R2: the restored version is named as context");
   });
 
   it("probe failure degrades with the SAME offline guard as the whole-library view", async () => {
@@ -676,18 +778,20 @@ describe("runList — skillset-declared view", () => {
     assert.doesNotMatch(out, /needs? attention/, "a synced repo is not all-attention on a probe hiccup");
   });
 
-  it("--json carries the freshness axis and stays a top-level object", async () => {
+  it("--json carries the freshness axis + distinct installed/served versions, top-level object", async () => {
     declareSkillset();
+    // Disk/baseline = 1.0.0; the server has moved to 2.0.0 → BEHIND. disk ≠
+    // served so the two version fields are distinguishable (#2824 R4). (A
+    // steady-state up-to-date member is covered by the delivered-set test
+    // above; this one is deliberately divergent.)
     writeRepoSyncState(process.cwd(), {
       repoName: "checkout",
       skillsetRef: "acme/backend-core",
       etag: "ss-1",
       resolved: [deliveredMember("acme", "svc", "1.0.0", [{ path: "SKILL.md", content: SKILL_MD_BODY("svc") }])],
     });
-    // Unconditional 200 (#2807): the member is served at its baseline
-    // version, so freshness resolves to up-to-date off the body.
     server.setSkillsetResponse({
-      skills: [makeSkill("acme", "svc", "1.0.0")],
+      skills: [makeSkill("acme", "svc", "2.0.0", { governance: { status: "latest", head: "2.0.0" } })],
       removals: [],
       syncedAt: "x",
       skillset: { name: "backend-core", updatedAt: "x", skippedExtras: [] },
@@ -698,8 +802,12 @@ describe("runList — skillset-declared view", () => {
     assert.equal(json.skillset.ref, "acme/backend-core");
     assert.equal(json.skillset.synced, true);
     const svc = json.skills.find((s) => s.name === "svc");
-    assert.equal(svc.freshness, "up-to-date");
+    assert.equal(svc.freshness, "behind");
     assert.equal(svc.classification, "tracked");
+    // R4 — the installed (disk) version and the server's served version are
+    // distinct, correctly-labeled fields in the skillset JSON too.
+    assert.equal(svc.version, "1.0.0", "R1/R4: version is the installed (disk) version");
+    assert.equal(svc.servedVersion, "2.0.0", "R4: servedVersion is the server's served/available version");
     // description/updatedAt now ride the skillset JSON too (probe metadata).
     assert.equal(svc.description, "svc description");
   });
@@ -740,7 +848,13 @@ describe("runList — skillset-declared view", () => {
     await runList(["--key", VALID_KEY, "--url", serverUrl], { stdout });
     const out = stdout.text();
     assert.match(out, /NOT DELIVERED/);
-    assert.match(out, /edited locally/);
+    // Row-scoped (#2824 audit): the not-delivered REASON detail must render on
+    // `locked`'s OWN attention line. A bare `/edited locally/` match is
+    // confirm-the-code — the compliance summary ALSO prints "N members edited
+    // locally" (foreign-content.mjs), so it passes even if the not-delivered
+    // reason mapping is wrong. Scope it to the member's row to actually guard it.
+    const lockedLine = out.split("\n").find((l) => l.includes("/locked") && l.includes("edited locally"));
+    assert.ok(lockedLine, "the not-delivered member's reason detail renders on its own attention row, not just in the compliance summary");
   });
 
   it("renders each not-delivered refusal reason with its matching detail", async () => {
@@ -786,14 +900,17 @@ describe("runList — skillset-declared view", () => {
     assert.ok(!stdout.text().includes(""), "raw ANSI from the state file must be escaped");
   });
 
-  it("governance: a serving member speaks the same SERVING vocabulary + shows probe metadata", async () => {
+  it("governance (recalled-not-synced): serving member shows the INSTALLED version + names the served rollback", async () => {
     declareSkillset();
     const files = [{ path: "SKILL.md", content: SKILL_MD_BODY("svc") }];
+    // Disk/baseline = 2.0.0 (the recalled version the CLI last synced); the
+    // server now serves the 1.9.0 rollback. disk ≠ served, the real Fault-A
+    // state — the old fixture set the baseline to 1.9.0 too, masking the bug.
     writeRepoSyncState(process.cwd(), {
       repoName: "checkout",
       skillsetRef: "acme/backend-core",
       etag: "ss-1",
-      resolved: [deliveredMember("acme", "svc", "1.9.0", files)],
+      resolved: [deliveredMember("acme", "svc", "2.0.0", files)],
     });
     // The unconditional 200 carries governance (recall flag on, server-side)
     // + description/updatedAt: svc serves 1.9.0 because 2.0.0 was recalled.
@@ -812,7 +929,12 @@ describe("runList — skillset-declared view", () => {
     await runList(["--key", VALID_KEY, "--url", serverUrl], { stdout });
     const out = stdout.text();
     assert.match(out, /\bSERVING\b/, "the skillset view speaks the whole-library view's governance word");
-    assert.match(out, /2\.0\.0 recalled — rolled back to 1\.9\.0/, "the recall reason renders in the shared block");
+    // R3 — the Version cell shows the installed 2.0.0, never the served 1.9.0.
+    const boxedRow = out.split("\n").find((l) => l.includes("svc") && l.includes("│"));
+    assert.ok(boxedRow, "the svc row renders in the table");
+    assert.match(boxedRow, /\b2\.0\.0\b/, "R1/R3: Version column = the installed (recalled) version on disk");
+    assert.doesNotMatch(boxedRow, /\b1\.9\.0\b/, "the Version cell never shows the server's served rollback");
+    assert.match(out, /2\.0\.0 recalled — server serves 1\.9\.0 — run update/, "the recall reason renders in the shared block");
     assert.match(out, /deploys the service/, "the Description column populates from the probe (5-column table, like library)");
     assert.doesNotMatch(out, /all members delivered and current/, "a serving member is not treated as healthy");
   });

package/src/test/integration/update-list-contract.integration.test.mjs

@@ -613,6 +613,13 @@ describe("update → mutate → list: drift verdicts on real persisted state", (
     await runList(["--key", VALID_KEY, "--url", serverUrl, "--json"], { stdout });
     const [item] = JSON.parse(stdout.text());
     assert.equal(item.state, "stale", "library moved ahead → `stale`");
+    // #2824 R1/R4 at the REAL entry point (update then list, genuinely
+    // persisted .last-sync): `.last-sync` recorded 1.0.0 on disk; the server
+    // now serves 1.1.0. `version` is the INSTALLED 1.0.0 (what the agent
+    // loads), `servedVersion` the available 1.1.0. Pre-#2824 `version` was
+    // 1.1.0 (the server's) — this asserts against that exact regression.
+    assert.equal(item.version, "1.0.0", "R1: installed (disk) version from the real .last-sync");
+    assert.equal(item.servedVersion, "1.1.0", "R4: the server's served version as a distinct field");
   });
 
   it("MISSING after update + manual delete: removing a placement makes list show `missing`", async () => {

package/src/test/lib/drift.test.mjs

@@ -15,7 +15,17 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
 
-import { computeSkillState, rollupState, SKILL_STATE } from "../../lib/drift.mjs";
+import {
+  computeSkillState,
+  rollupState,
+  SKILL_STATE,
+  computeFreshness,
+  computeLocalIntegrity,
+  rollupLocal,
+  versionIsNewer,
+  FRESHNESS,
+  LOCAL_STATE,
+} from "../../lib/drift.mjs";
 
 // Test fixtures — keep them readable. SHAs use distinct repeated
 // characters so an assertion comparing the wrong field is obvious.
@@ -287,3 +297,131 @@ describe("rollupState", () => {
     );
   });
 });
+
+// ── computeFreshness (#2806) ─────────────────────────────────────────────
+//
+// The freshness axis is baseline(disk) vs the server's SERVED version. It is
+// load-bearing for #2824: it must fire BEHIND only when the server moved
+// FORWARD, and stay UP_TO_DATE when the server rolled BACK (a recall
+// fallback) — otherwise a recalled-not-synced row would read "behind" and
+// prompt an "available" version that is actually older. These direct tests
+// were missing (the axis had only indirect coverage via the list engine).
+
+describe("computeFreshness", () => {
+  it("BEHIND when the served version is strictly newer than the baseline (server moved forward)", () => {
+    assert.equal(
+      computeFreshness({ baselineVersion: "1.0.0", servedVersion: "2.0.0" }),
+      FRESHNESS.BEHIND,
+    );
+  });
+
+  it("UP_TO_DATE when served equals the baseline", () => {
+    assert.equal(
+      computeFreshness({ baselineVersion: "1.0.0", servedVersion: "1.0.0" }),
+      FRESHNESS.UP_TO_DATE,
+    );
+  });
+
+  it("UP_TO_DATE (never BEHIND) when the server ROLLED BACK below the baseline — the recall-fallback case", () => {
+    // Disk holds 2.0.0 (the recalled version); the server serves the 1.9.0
+    // rollback. The server did NOT move forward, so freshness is UP_TO_DATE —
+    // the SERVING governance signal, not freshness, is what surfaces the
+    // recall. If this returned BEHIND, `list` would offer "1.9.0 available",
+    // i.e. tell you to "update" DOWN to the rollback via the freshness path.
+    assert.equal(
+      computeFreshness({ baselineVersion: "2.0.0", servedVersion: "1.9.0" }),
+      FRESHNESS.UP_TO_DATE,
+    );
+  });
+
+  it("NOT_CHECKED when the served version is absent (server not consulted) — never a false UP_TO_DATE", () => {
+    assert.equal(
+      computeFreshness({ baselineVersion: "1.0.0", servedVersion: null }),
+      FRESHNESS.NOT_CHECKED,
+    );
+    assert.equal(
+      computeFreshness({ baselineVersion: "1.0.0", servedVersion: "" }),
+      FRESHNESS.NOT_CHECKED,
+    );
+  });
+
+  it("BEHIND for a non-semver served label that differs from the baseline (string fallback, safe direction)", () => {
+    assert.equal(
+      computeFreshness({ baselineVersion: "beta", servedVersion: "rc" }),
+      FRESHNESS.BEHIND,
+    );
+  });
+});
+
+// ── versionIsNewer (#2806) — shared ordering rule ────────────────────────
+
+describe("versionIsNewer", () => {
+  it("semver: strict greater-than only", () => {
+    assert.equal(versionIsNewer("2.0.0", "1.0.0"), true);
+    assert.equal(versionIsNewer("1.0.0", "1.0.0"), false);
+    assert.equal(versionIsNewer("1.0.0", "2.0.0"), false);
+  });
+
+  it("non-semver: any difference reads newer (bias toward prompting an update, never masking one)", () => {
+    assert.equal(versionIsNewer("rc", "beta"), true);
+    assert.equal(versionIsNewer("beta", "beta"), false);
+  });
+
+  it("absent/empty candidate or reference is inconclusive → false", () => {
+    assert.equal(versionIsNewer(null, "1.0.0"), false);
+    assert.equal(versionIsNewer("1.0.0", null), false);
+    assert.equal(versionIsNewer("", "1.0.0"), false);
+  });
+});
+
+// ── computeLocalIntegrity + rollupLocal (#2806) ──────────────────────────
+
+describe("computeLocalIntegrity", () => {
+  it("PRESENT when both SHAs match the baseline", () => {
+    assert.equal(
+      computeLocalIntegrity({ baseline: BASELINE, placement: localPresence(SHA_A, SHA_B) }),
+      LOCAL_STATE.PRESENT,
+    );
+  });
+
+  it("EDITED when either SHA differs from the baseline", () => {
+    assert.equal(
+      computeLocalIntegrity({ baseline: BASELINE, placement: localPresence(SHA_C, SHA_B) }),
+      LOCAL_STATE.EDITED,
+    );
+    assert.equal(
+      computeLocalIntegrity({ baseline: BASELINE, placement: localPresence(SHA_A, SHA_D) }),
+      LOCAL_STATE.EDITED,
+    );
+  });
+
+  it("MISSING when not on disk, or on disk with no baseline to verify against", () => {
+    assert.equal(
+      computeLocalIntegrity({ baseline: BASELINE, placement: { present: false, skillMdSha256: null, filesSha256: null } }),
+      LOCAL_STATE.MISSING,
+    );
+    assert.equal(
+      computeLocalIntegrity({ baseline: null, placement: localPresence(SHA_A, SHA_B) }),
+      LOCAL_STATE.MISSING,
+    );
+  });
+
+  it("EDITED (never PRESENT) when a disk SHA is null — cannot verify → conservative", () => {
+    assert.equal(
+      computeLocalIntegrity({ baseline: BASELINE, placement: { present: true, skillMdSha256: null, filesSha256: SHA_B } }),
+      LOCAL_STATE.EDITED,
+    );
+  });
+});
+
+describe("rollupLocal", () => {
+  it("precedence missing > edited > present", () => {
+    assert.equal(rollupLocal([LOCAL_STATE.PRESENT, LOCAL_STATE.EDITED, LOCAL_STATE.MISSING]), LOCAL_STATE.MISSING);
+    assert.equal(rollupLocal([LOCAL_STATE.PRESENT, LOCAL_STATE.EDITED]), LOCAL_STATE.EDITED);
+    assert.equal(rollupLocal([LOCAL_STATE.PRESENT, LOCAL_STATE.PRESENT]), LOCAL_STATE.PRESENT);
+  });
+
+  it("empty array is MISSING (nothing to vouch for) — the conservative floor", () => {
+    assert.equal(rollupLocal([]), LOCAL_STATE.MISSING);
+  });
+});

package/src/test/lib/list-engine.test.mjs

@@ -84,11 +84,24 @@ describe("buildDiskByName", () => {
 });
 
 // ── tracked rows (on disk ∩ expected) ───────────────────────────────────
+//
+// DISK-TRUTH INVARIANT (#2824 R1): `row.version` is the INSTALLED version —
+// the `.last-sync` baseline (what the last sync wrote to disk) — NEVER the
+// server's served version, which rides `row.servedVersion` as context (R2/R4).
+// Every fixture below DIVERGES disk ≠ served so "show disk" and "show server"
+// produce different output; the ONE exception is the explicitly-labelled
+// steady-state test (a healthy LATEST row is disk == served by definition).
+// Each `version` assertion therefore FAILS on the pre-#2824 build (which put
+// `servedVersion` in `version`) and passes after — red-first, per
+// docs/CLI-LIST-TEST-STANDARD.md.
 
 describe("classifyRows — tracked", () => {
   const detected = ["claudeCode"];
 
-  it("present + latest + up-to-date collapses to ok (silent)", () => {
+  it("STEADY STATE (the one allowed disk==served): present + latest + up-to-date → ok, version is installed", () => {
+    // The ONLY test permitted to set disk === served: a healthy LATEST row is
+    // disk==served BY DEFINITION (you hold exactly what is served). Labelled so
+    // it can never be mistaken for a version-distinguishing test.
     const rows = classifyRows({
       diskByName: buildDiskByName(placementsMap([placement("claudeCode", "pdf", SHA_A, SHA_B)])),
       detectedVendorKeys: detected,
@@ -103,23 +116,37 @@ describe("classifyRows — tracked", () => {
     assert.equal(r.freshness, FRESHNESS.UP_TO_DATE);
     assert.equal(r.governance.status, "latest");
     assert.equal(r.signal, SIGNAL.OK);
+    assert.equal(r.version, "1.0.0", "installed (disk) version");
+    assert.equal(r.servedVersion, "1.0.0", "served == installed in the steady state");
   });
 
-  it("edited content → local edited, signal edited", () => {
+  it("recalled-not-synced: disk holds the recalled version, server serves the rollback → version is DISK, servedVersion is the rollback", () => {
+    // THE canonical Fault-A state (#2824 R1/R2). You synced 2.0.0; the team
+    // then recalled 2.0.0 and the server now serves the 1.9.0 rollback — but
+    // 2.0.0 is still the file on disk (and still what the agent loads). `list`
+    // must report 2.0.0 (what you have), never 1.9.0 (what the server serves).
+    // Pre-#2824 this row reported 1.9.0 → this assertion fails on that build.
     const rows = classifyRows({
-      diskByName: buildDiskByName(placementsMap([placement("claudeCode", "pdf", SHA_EDIT, SHA_B)])),
+      diskByName: buildDiskByName(placementsMap([placement("claudeCode", "sec", SHA_A, SHA_B)])),
       detectedVendorKeys: detected,
-      expected: [{ owner: "alice", name: "pdf", version: "1.0.0" }],
-      baselineByKey: baseline({ "alice/pdf": { version: "1.0.0", skillMdSha256: SHA_A, filesSha256: SHA_B } }),
-      serverTruth: serverTruth200({ "alice/pdf": { servedVersion: "1.0.0", governance: { status: "latest", head: "1.0.0" } } }),
+      expected: [{ owner: "alice", name: "sec", version: "1.9.0" }],
+      baselineByKey: baseline({ "alice/sec": { version: "2.0.0", skillMdSha256: SHA_A, filesSha256: SHA_B } }),
+      serverTruth: serverTruth200({
+        "alice/sec": { servedVersion: "1.9.0", governance: { status: "serving", head: "2.0.0", recalledVersion: "2.0.0" } },
+      }),
       variant: "library",
     });
-    const r = rowByName(rows, "pdf");
-    assert.equal(r.local, LOCAL_STATE.EDITED);
-    assert.equal(r.signal, SIGNAL.EDITED);
+    const r = rowByName(rows, "sec");
+    assert.equal(r.version, "2.0.0", "R1: the INSTALLED (disk/baseline) version, NOT the server's 1.9.0 rollback");
+    assert.equal(r.servedVersion, "1.9.0", "R2/R4: the server's served rollback is carried as distinct context");
+    assert.equal(r.local, LOCAL_STATE.PRESENT, "the on-disk 2.0.0 matches its baseline");
+    assert.equal(r.freshness, FRESHNESS.UP_TO_DATE, "the server rolled BACK, it did not move forward — never 'behind'");
+    assert.equal(r.governance.status, "serving");
+    assert.equal(r.governance.recalledVersion, "2.0.0");
+    assert.equal(r.signal, SIGNAL.SERVING);
   });
 
-  it("server moved forward → freshness behind, signal behind", () => {
+  it("behind: server moved forward → version is DISK, servedVersion is the newer available version", () => {
     const rows = classifyRows({
       diskByName: buildDiskByName(placementsMap([placement("claudeCode", "pdf", SHA_A, SHA_B)])),
       detectedVendorKeys: detected,
@@ -129,27 +156,29 @@ describe("classifyRows — tracked", () => {
       variant: "library",
     });
     const r = rowByName(rows, "pdf");
+    assert.equal(r.version, "1.0.0", "R1: installed (disk) version, NOT the newer served 2.0.0");
+    assert.equal(r.servedVersion, "2.0.0", "R2: the available version rides servedVersion as context");
     assert.equal(r.freshness, FRESHNESS.BEHIND);
     assert.equal(r.signal, SIGNAL.BEHIND);
   });
 
-  it("serving governance (recall fallback) surfaces as serving", () => {
+  it("edited content → local edited, signal edited, version stays DISK", () => {
     const rows = classifyRows({
-      diskByName: buildDiskByName(placementsMap([placement("claudeCode", "sec", SHA_A, SHA_B)])),
+      diskByName: buildDiskByName(placementsMap([placement("claudeCode", "pdf", SHA_EDIT, SHA_B)])),
       detectedVendorKeys: detected,
-      expected: [{ owner: "alice", name: "sec", version: "1.9.0" }],
-      baselineByKey: baseline({ "alice/sec": { version: "1.9.0", skillMdSha256: SHA_A, filesSha256: SHA_B } }),
-      serverTruth: serverTruth200({
-        "alice/sec": { servedVersion: "1.9.0", governance: { status: "serving", head: "2.0.0", recalledVersion: "2.0.0" } },
-      }),
+      expected: [{ owner: "alice", name: "pdf", version: "2.0.0" }],
+      baselineByKey: baseline({ "alice/pdf": { version: "1.0.0", skillMdSha256: SHA_A, filesSha256: SHA_B } }),
+      serverTruth: serverTruth200({ "alice/pdf": { servedVersion: "2.0.0", governance: { status: "latest", head: "2.0.0" } } }),
       variant: "library",
     });
-    const r = rowByName(rows, "sec");
-    assert.equal(r.governance.status, "serving");
-    assert.equal(r.signal, SIGNAL.SERVING);
+    const r = rowByName(rows, "pdf");
+    assert.equal(r.local, LOCAL_STATE.EDITED);
+    assert.equal(r.signal, SIGNAL.EDITED, "edited is more actionable than behind");
+    assert.equal(r.version, "1.0.0", "R1: installed (disk) version even on an edited, behind row");
+    assert.equal(r.servedVersion, "2.0.0");
   });
 
-  it("edited outranks behind + serving in the collapsed signal", () => {
+  it("edited outranks behind + serving in the collapsed signal, version stays DISK", () => {
     const rows = classifyRows({
       diskByName: buildDiskByName(placementsMap([placement("claudeCode", "pdf", SHA_EDIT, SHA_B)])),
       detectedVendorKeys: detected,
@@ -164,21 +193,25 @@ describe("classifyRows — tracked", () => {
     assert.equal(r.local, LOCAL_STATE.EDITED);
     assert.equal(r.freshness, FRESHNESS.BEHIND);
     assert.equal(r.signal, SIGNAL.EDITED, "edited is more actionable than behind/serving");
+    assert.equal(r.version, "1.0.0", "R1: installed (disk) version regardless of the collapsed signal");
+    assert.equal(r.servedVersion, "2.0.0");
   });
 
-  it("present at one vendor, absent at another → local missing (worst-wins)", () => {
+  it("present at one vendor, absent at another → local missing (worst-wins), version is DISK", () => {
     const rows = classifyRows({
       diskByName: buildDiskByName(placementsMap([placement("claudeCode", "pdf", SHA_A, SHA_B)])),
       detectedVendorKeys: ["claudeCode", "cursor"],
-      expected: [{ owner: "alice", name: "pdf", version: "1.0.0" }],
+      expected: [{ owner: "alice", name: "pdf", version: "2.0.0" }],
       baselineByKey: baseline({ "alice/pdf": { version: "1.0.0", skillMdSha256: SHA_A, filesSha256: SHA_B } }),
-      serverTruth: serverTruth200({ "alice/pdf": { servedVersion: "1.0.0", governance: { status: "latest", head: "1.0.0" } } }),
+      serverTruth: serverTruth200({ "alice/pdf": { servedVersion: "2.0.0", governance: { status: "latest", head: "2.0.0" } } }),
       variant: "library",
     });
     const r = rowByName(rows, "pdf");
     assert.equal(r.local, LOCAL_STATE.MISSING);
     assert.equal(r.placements.length, 2);
     assert.equal(r.placements.find((p) => p.vendor === "cursor").present, false);
+    assert.equal(r.version, "1.0.0", "R1: installed (disk) version");
+    assert.equal(r.servedVersion, "2.0.0");
   });
 });
 
@@ -190,17 +223,24 @@ describe("classifyRows — server-truth modes", () => {
   const expected = [{ owner: "alice", name: "pdf", version: "1.0.0" }];
   const base = () => baseline({ "alice/pdf": { version: "1.0.0", skillMdSha256: SHA_A, filesSha256: SHA_B } });
 
-  it("server not consulted (null) → freshness not-checked, never up-to-date", () => {
+  it("server not consulted (null) → freshness not-checked, version is still DISK, servedVersion null", () => {
     const rows = classifyRows({ diskByName: disk(), detectedVendorKeys: detected, expected, baselineByKey: base(), serverTruth: null, variant: "library" });
     const r = rowByName(rows, "pdf");
     assert.equal(r.freshness, FRESHNESS.NOT_CHECKED);
     assert.equal(r.governance, null);
     assert.equal(r.signal, SIGNAL.NOT_CHECKED);
+    // Offline still shows the on-disk version (the local axis needs no network);
+    // the server's version is unknown → null, never a fabricated value.
+    assert.equal(r.version, "1.0.0", "installed (disk) version, offline");
+    assert.equal(r.servedVersion, null, "server not consulted → no served version");
   });
 
-  it("checked:false (offline probe) → not-checked", () => {
+  it("checked:false (offline probe) → not-checked, version DISK, servedVersion null", () => {
     const rows = classifyRows({ diskByName: disk(), detectedVendorKeys: detected, expected, baselineByKey: base(), serverTruth: { checked: false, byKey: null }, variant: "library" });
-    assert.equal(rowByName(rows, "pdf").freshness, FRESHNESS.NOT_CHECKED);
+    const r = rowByName(rows, "pdf");
+    assert.equal(r.freshness, FRESHNESS.NOT_CHECKED);
+    assert.equal(r.version, "1.0.0", "installed (disk) version, offline probe");
+    assert.equal(r.servedVersion, null);
   });
 });
 
@@ -220,6 +260,11 @@ describe("classifyRows — missing / not-delivered", () => {
     assert.equal(r.classification, CLASSIFICATION.MISSING);
     assert.equal(r.local, LOCAL_STATE.MISSING);
     assert.equal(r.signal, SIGNAL.MISSING);
+    // Not installed → there is no disk version. The spec's not-installed rule
+    // shows the server/expected version instead; the MISSING classification is
+    // what marks it not-installed, so this is not a "false installed version".
+    assert.equal(r.version, "1.0.0", "not-installed: the server/expected version is shown");
+    assert.equal(r.servedVersion, "1.0.0");
   });
 
   it("skillset served-but-unwritten → not-delivered with reason", () => {
@@ -235,6 +280,9 @@ describe("classifyRows — missing / not-delivered", () => {
     assert.equal(r.classification, CLASSIFICATION.NOT_DELIVERED);
     assert.equal(r.reason, "modified");
     assert.equal(r.signal, SIGNAL.NOT_DELIVERED);
+    // Not on disk (guard-refused) → the declared version is shown, not installed.
+    assert.equal(r.version, "1.0.0", "the declared/expected version for a not-delivered member");
+    assert.equal(r.servedVersion, null, "no server-truth lookup on the not-delivered branch");
   });
 });
 
@@ -255,6 +303,9 @@ describe("classifyRows — foreign / orphan", () => {
     assert.equal(r.owner, null);
     assert.equal(r.local, LOCAL_STATE.PRESENT);
     assert.equal(r.signal, SIGNAL.FOREIGN);
+    // No baseline and not from the library → no known version either way.
+    assert.equal(r.version, null, "a hand-authored dir has no known version");
+    assert.equal(r.servedVersion, null);
   });
 
   it("on disk + in baseline but NOT served → orphan (#2804)", () => {
@@ -271,7 +322,8 @@ describe("classifyRows — foreign / orphan", () => {
     const r = rowByName(rows, "recalled");
     assert.equal(r.classification, CLASSIFICATION.ORPHAN);
     assert.equal(r.owner, "alice");
-    assert.equal(r.version, "1.2.0");
+    assert.equal(r.version, "1.2.0", "R1: the version on disk (baseline), the only truth for a disowned orphan");
+    assert.equal(r.servedVersion, null, "the server no longer serves it → no served version");
     assert.equal(r.local, LOCAL_STATE.PRESENT);
     assert.equal(r.signal, SIGNAL.ORPHAN);
   });
@@ -289,6 +341,8 @@ describe("classifyRows — foreign / orphan", () => {
     assert.equal(r.classification, CLASSIFICATION.ORPHAN);
     assert.equal(r.local, LOCAL_STATE.EDITED);
     assert.equal(r.signal, SIGNAL.ORPHAN, "orphan outranks edited");
+    assert.equal(r.version, "1.2.0", "R1: still the on-disk baseline version, even when edited");
+    assert.equal(r.servedVersion, null);
   });
 });