skillrepo 4.6.0 → 4.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillrepo",
-  "version": "4.6.0",
+  "version": "4.8.0",
   "description": "Pull-based CLI for agent skills — init, sync, search, add, remove your library from any IDE",
   "type": "module",
   "bin": {

package/src/lib/sync.mjs

@@ -31,6 +31,11 @@
  *        version + content SHAs of every skill written in the last
  *        successful sync. Unblocks per-skill drift detection in `list`
  *        (#1555) and any future `status`-style command.
+ *        Later (#1911) v2 also carries `cliVersion` — the version of the
+ *        CLI that last wrote the state file. Additive, not a schema bump:
+ *        absence is meaningful (a state file with no `cliVersion` was
+ *        written by a pre-#1911 CLI and triggers the one-time membership
+ *        heal). See `FULL_RESYNC_FLOOR` / `cliVersionBelowFloor`.
  *
  * Forward/backward compatibility
  * ------------------------------
@@ -69,7 +74,14 @@
  *                                   render accurate user messages (see
  *                                   init.mjs step 7).
  * @property {string} [syncedAt]
- * @property {string} syncedAt    - ISO timestamp from the server response
+ * @property {string} syncedAt    - ISO timestamp of the sync: the server
+ *                                   response `syncedAt` on a 200, or the
+ *                                   previously-cached sync timestamp on a
+ *                                   304 (the server sends no body). NOTE:
+ *                                   this is distinct from the re-assertion
+ *                                   receipt's own timestamp on a 304, which
+ *                                   is the CLI's "now" (a liveness signal),
+ *                                   not this cached value.
  *
  * @typedef {Object} SyncedSkillEntry
  * @property {string} version       - Version of the skill as synced (e.g. "1.4.0").
@@ -81,13 +93,20 @@
  * @property {number} schemaVersion
  * @property {string|null} etag
  * @property {string} syncedAt
+ * @property {string} [cliVersion] - v2+ (#1911). Version of the CLI that last
+ *                                   wrote this state. Absent on files written
+ *                                   by a pre-#1911 CLI; absence triggers the
+ *                                   one-time membership heal.
  * @property {Record<string, SyncedSkillEntry>} skills - v2+. Keyed by `"<owner>/<name>"`.
  */
 
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
+import semver from "semver";
+
 import { getLibrary, postSyncReceipt } from "./http.mjs";
+import { getCliVersion } from "./cli-version.mjs";
 import {
   writeSkillDir,
   removeSkillDir,
@@ -111,6 +130,66 @@ import { computeSkillShas } from "./crypto-shas.mjs";
  */
 export const LAST_SYNC_SCHEMA_VERSION = 2;
 
+/**
+ * One-time heal floor (#1911).
+ *
+ * A `.last-sync` written by a CLI BELOW this version predates the
+ * server-side delta-membership fix. Such a state file can be permanently
+ * missing skills that were added to the library but never delivered: the
+ * old delta filter keyed only on `skills.updatedAt`, so a skill whose
+ * content predated the user's `since` was skipped even though the library
+ * ETag advanced (count++). The client then cached the advanced ETag and
+ * every subsequent `update` short-circuited on a 304 — the skill could
+ * never arrive via delta.
+ *
+ * The server fix makes FUTURE adds correct, but it cannot rescue a client
+ * that already cached the advanced ETag (it still matches → 304). So the
+ * FIRST sync performed by a CLI at/above this floor forces ONE full fetch
+ * (drops `If-None-Match` AND `since`), re-fetching the entire library to
+ * fill any gap, then resumes normal delta. `writeLastSync` stamps the
+ * running CLI version on every write, so the heal fires at most once per
+ * upgrade.
+ *
+ * MUST equal the CLI version that ships this fix (see packages/cli/package.json).
+ */
+export const FULL_RESYNC_FLOOR = "4.8.0";
+
+/**
+ * True when a `.last-sync`'s recorded writer version is below the heal
+ * floor — i.e. the state file was written before the #1911 fix and may be
+ * missing never-delivered skills. A missing or unparseable version is
+ * treated as below the floor (older CLIs never stamped `cliVersion`), so
+ * every pre-fix state file heals exactly once.
+ *
+ * @param {unknown} recordedVersion - `.last-sync`'s `cliVersion` field.
+ * @param {string} floor - The heal floor (a valid semver string).
+ * @returns {boolean}
+ */
+export function cliVersionBelowFloor(recordedVersion, floor) {
+  if (typeof recordedVersion !== "string" || !semver.valid(recordedVersion)) {
+    return true;
+  }
+  return semver.lt(recordedVersion, floor);
+}
+
+/**
+ * The running CLI's version, or null if it cannot be read. `getCliVersion`
+ * throws on a malformed/absent package.json (a broken tarball); persisting
+ * last-sync state must never fail on that, so we soft-handle to null here.
+ * A null stamp simply means the next run treats this state as pre-floor and
+ * heals again — safe, just one extra full fetch in the (production-
+ * impossible) broken-tarball case.
+ *
+ * @returns {string | null}
+ */
+function safeCliVersion() {
+  try {
+    return getCliVersion();
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Check whether every skill in the `.last-sync` baseline already exists
  * under every placement target the current sync would write to. Returns
@@ -290,17 +369,26 @@ export function readLastSync() {
  * sync"; consumers should treat absent entries as "unknown" rather
  * than as "missing from library."
  *
+ * Always stamps `cliVersion` with the running CLI's version (#1911). This
+ * is the writer-version record the heal gate (`cliVersionBelowFloor`) reads
+ * on the next run; a state file written by the current CLI is therefore
+ * never re-healed. A caller-supplied `cliVersion` overrides the stamp (used
+ * only by tests to simulate a pre-fix writer); production callers omit it.
+ *
  * @param {object} state
  * @param {string | null} [state.etag]
  * @param {string} [state.syncedAt]
  * @param {Record<string, SyncedSkillEntry>} [state.skills]
+ * @param {string | null} [state.cliVersion] - Override the writer-version
+ *        stamp. Defaults to the running CLI's version.
  */
-export function writeLastSync({ etag, syncedAt, skills } = {}) {
+export function writeLastSync({ etag, syncedAt, skills, cliVersion } = {}) {
   const path = globalLastSyncPath();
   const body = {
     schemaVersion: LAST_SYNC_SCHEMA_VERSION,
     etag: etag ?? null,
     syncedAt: syncedAt ?? new Date().toISOString(),
+    cliVersion: cliVersion !== undefined ? cliVersion : safeCliVersion(),
     skills: skills && typeof skills === "object" && !Array.isArray(skills) ? skills : {},
   };
   try {
@@ -383,6 +471,15 @@ export function upsertLastSyncEntry(skill) {
     etag: prior?.etag ?? null,
     syncedAt: prior?.syncedAt,
     skills: updated,
+    // Preserve the prior writer-version too (#1911). `add`/`get` fetch a
+    // SINGLE skill — they do NOT perform the full-library reconciliation
+    // the membership heal needs, so they must NOT advance the heal gate.
+    // Letting `writeLastSync` default-stamp the running version here would
+    // let a stuck user "spend" their one-time heal on a single-skill add,
+    // leaving every OTHER never-delivered skill stuck forever. `?? null`
+    // carries a pre-fix file's absent version forward as an explicit null
+    // so the next `update` still heals. Same rationale as etag/syncedAt.
+    cliVersion: prior?.cliVersion ?? null,
   });
 }
 
@@ -406,6 +503,10 @@ export function deleteLastSyncEntry(owner, name) {
     etag: prior.etag ?? null,
     syncedAt: prior.syncedAt,
     skills: rest,
+    // Preserve the prior writer-version (#1911) — `remove` is not a full
+    // reconciliation, so it must not advance the one-time heal gate.
+    // See upsertLastSyncEntry for the full rationale.
+    cliVersion: prior.cliVersion ?? null,
   });
 }
 
@@ -417,7 +518,8 @@ export function deleteLastSyncEntry(owner, name) {
  *   2. Read the last-sync state file
  *   3. Call GET /api/v1/library with `If-None-Match` (if we have a
  *      cached ETag) AND `since` (always, for delta semantics)
- *   4. Short-circuit on 304 — return `notModified: true`
+ *   4. On 304 — re-assert the on-disk state via a receipt (liveness +
+ *      heal) and short-circuit with `notModified: true`
  *   5. For each skill in the response:
  *      a. Write it via `writeSkillDir` — overwrites if changed
  *      b. Skip writing skills with `filesIncomplete: true` (see comment)
@@ -425,7 +527,9 @@ export function deleteLastSyncEntry(owner, name) {
  *      a. Call `removeSkillDir` — deletes from all configured targets
  *   7. Persist the new ETag (if the response was complete) for the
  *      next sync
- *   8. Return the summary
+ *   8. Re-assert the full on-disk state via a sync receipt (#1832) —
+ *      the confirmed-write signal that sets team sync state
+ *   9. Return the summary
  *
  * Error handling: any thrown error from the network or filesystem
  * layer propagates unchanged. The caller (a command) decides how to
@@ -517,25 +621,64 @@ export async function runSync(options) {
   const placementsComplete =
     lastSync?.etag &&
     placementsAreComplete(lastSync.skills, vendors, global);
-  if (placementsComplete) {
+
+  // One-time membership-heal (#1911). A `.last-sync` written by a CLI below
+  // the heal floor predates the server delta-membership fix and may be
+  // permanently missing skills that were added to the library but never
+  // delivered (their content predated `since`, so the old delta skipped
+  // them while the ETag still advanced — the client cached the advanced
+  // ETag and every later sync 304'd). The server fix can't rescue such a
+  // client: its cached ETag still matches, so it keeps getting 304s. Force
+  // ONE full fetch (drop BOTH conditional headers) so the entire library
+  // is re-fetched and the gap is filled. `writeLastSync` stamps the running
+  // version on the resulting write, so this fires at most once per upgrade.
+  //
+  // Mixed-version note (benign, do NOT "fix" with a different mechanism): if
+  // a pre-4.8.0 CLI shares this same global `.last-sync` and runs after a
+  // 4.8.0 heal, its `writeLastSync` re-emits a file with no `cliVersion`, so
+  // the next 4.8.0 run heals again. That loop is harmless — a full re-fetch
+  // is idempotent — and self-resolves once the older install is upgraded.
+  const needsFullResync =
+    !!lastSync && cliVersionBelowFloor(lastSync.cliVersion, FULL_RESYNC_FLOOR);
+
+  if (placementsComplete && !needsFullResync) {
     opts.ifNoneMatch = lastSync.etag;
   }
-  if (lastSync?.syncedAt && placementsComplete) {
+  if (lastSync?.syncedAt && placementsComplete && !needsFullResync) {
     opts.since = lastSync.syncedAt;
   }
 
   // Track whether this is a full or delta sync BEFORE the network
-  // call, for the returned summary's `fullSync` field. A "full" sync
-  // is one where no `since` was sent — which is exactly when no
-  // prior last-sync state existed. The distinction matters to
-  // consumers (init.mjs) that need to tell "empty library" from
-  // "nothing changed since last sync" in the zero-counters case.
+  // call, for the returned summary's `fullSync` field. The documented
+  // semantic is "no PRIOR last-sync state existed" — NOT "no `since` was
+  // sent". A forced full re-fetch (placement-incomplete, or the #1911
+  // membership heal) still reports `fullSync:false` because prior state
+  // existed; only a genuine first sync reports true. Consumers (init.mjs)
+  // rely on this to tell "empty library" from "nothing changed since last
+  // sync" in the zero-counters case. Locked by sync.test.mjs.
   const fullSync = !lastSync?.syncedAt;
 
   const result = await getLibrary(serverUrl, apiKey, opts);
 
   // Step 4: 304 short-circuit
   if (result.notModified) {
+    // Re-assert the on-disk state even though nothing changed (#1832).
+    // The library is unchanged, so what's on disk is exactly the prior
+    // `.last-sync` skills map. This receipt:
+    //   • is the liveness signal that REPLACES the GET-side 304 heartbeat
+    //     for receipt-era servers (>= 4.7.0 CLIs no longer trigger it), so
+    //     a deliberately-stable library doesn't drift to "stale"; and
+    //   • heals any delivery the server missed (a receipt POST that failed
+    //     on a prior sync), correcting drift in the safe direction.
+    // Timestamp is the CLI's "now" so freshness advances; the server's
+    // 5-minute future tolerance absorbs ordinary clock skew. Best-effort.
+    await reportReceipt(
+      serverUrl,
+      apiKey,
+      receiptEntriesFromSkillsMap(lastSync?.skills),
+      new Date().toISOString(),
+      stderr,
+    );
     return {
       added: 0,
       updated: 0,
@@ -606,11 +749,6 @@ export async function runSync(options) {
   let anyIncomplete = false;
   /** @type {Record<string, SyncedSkillEntry>} */
   const skillsMap = {};
-  // Skills actually written to disk this sync, for the confirmed-write
-  // receipt (#1832). Only what we WRITE this round — carry-forward skills
-  // were reported on the sync that wrote them.
-  /** @type {{owner: string, name: string, version: string}[]} */
-  const writtenThisSync = [];
   // Carry forward entries from the previous sync for skills we did
   // NOT re-fetch this round. A delta sync that touched 2 of 50
   // skills must keep the other 48's metadata — otherwise the
@@ -674,17 +812,6 @@ export async function runSync(options) {
         syncedAt: result.syncedAt,
       };
     }
-
-    // Record this write for the sync receipt (#1832). Only entries with a
-    // real version label can resolve to a delivery server-side, so skip
-    // null/empty versions (a skill with no current published version).
-    if (typeof skill.version === "string" && skill.version !== "") {
-      writtenThisSync.push({
-        owner: skill.owner,
-        name: skill.name,
-        version: skill.version,
-      });
-    }
   }
 
   // Step 7: persist new ETag + skills map (only if the response was
@@ -712,33 +839,92 @@ export async function runSync(options) {
     }
   }
 
-  // Post a sync receipt for the skills actually written this sync
-  // (#1832). This confirmed-write signal — not the fetch itself — is what
-  // sets team sync state. Independent of the ETag persist above: skills
-  // skipped for `filesIncomplete` are excluded from `writtenThisSync`, so
-  // a partial sync still reports exactly what landed on disk. Best-effort:
-  // the files are already written and the server dedups replays, so a
-  // failed receipt is a non-fatal warning, never a sync failure.
-  if (writtenThisSync.length > 0) {
-    try {
-      await postSyncReceipt(serverUrl, apiKey, {
-        skills: writtenThisSync,
-        syncedAt: result.syncedAt,
-      });
-    } catch (err) {
-      stderr.write(
-        `  warning: failed to report sync receipt (${err.message}). ` +
-          `Your skills are synced locally; team sync status may lag until ` +
-          `your next sync.\n`,
-      );
-    }
-  }
+  // Re-assert the full on-disk state via a sync receipt (#1832). This
+  // confirmed-write signal — not the fetch itself — is what sets team
+  // sync state. We post the COMPLETE post-sync on-disk set (`skillsMap`:
+  // carry-forward skills + the skills written this round), not just what
+  // changed, so the receipt heals any delivery the server missed (a prior
+  // receipt POST that failed) and re-stamps freshness, replacing the
+  // GET-side heartbeat. `skillsMap` already reflects exactly what is on
+  // disk: skills skipped for `filesIncomplete` keep their prior carry-
+  // forward version (still on disk) and tombstoned skills were deleted
+  // from the map, so a partial or delta sync still re-asserts precisely
+  // what landed on disk. The server dedups (user, skill, version, UTC
+  // day), so re-asserting unchanged versions doesn't bloat the event log.
+  // Best-effort: files are already written, so a failed receipt is a
+  // non-fatal warning, never a sync failure.
+  await reportReceipt(
+    serverUrl,
+    apiKey,
+    receiptEntriesFromSkillsMap(skillsMap),
+    result.syncedAt,
+    stderr,
+  );
 
   return summary;
 }
 
 // ── Internals ──────────────────────────────────────────────────────────
 
+/**
+ * Build sync-receipt entries from a `.last-sync` skills map (#1832).
+ *
+ * Each key is `"<owner>/<name>"`; the value carries the version label of
+ * the skill as written to disk. The returned `[{ owner, name, version }]`
+ * array is the CLI's assertion of what it actually has on disk — the
+ * evidence the server treats as the single source of truth for sync
+ * state. Entries with no version label are skipped: a skill with no
+ * published version can't resolve to a delivery server-side. Malformed
+ * keys (no `/`, empty owner/name) are skipped defensively rather than
+ * producing a bogus receipt entry.
+ *
+ * @param {Record<string, {version?: string}> | null | undefined} skillsMap
+ * @returns {{owner: string, name: string, version: string}[]}
+ */
+function receiptEntriesFromSkillsMap(skillsMap) {
+  /** @type {{owner: string, name: string, version: string}[]} */
+  const entries = [];
+  if (!skillsMap || typeof skillsMap !== "object") return entries;
+  for (const [key, entry] of Object.entries(skillsMap)) {
+    if (!entry || typeof entry !== "object") continue;
+    const version = typeof entry.version === "string" ? entry.version : "";
+    if (version === "") continue;
+    const slashAt = key.indexOf("/");
+    if (slashAt < 0) continue;
+    const owner = key.slice(0, slashAt);
+    const name = key.slice(slashAt + 1);
+    if (!owner || !name) continue;
+    entries.push({ owner, name, version });
+  }
+  return entries;
+}
+
+/**
+ * Post a sync receipt, best-effort (#1832). A no-op when `skills` is
+ * empty (nothing on disk to assert — e.g. an empty library). The skill
+ * files are already on disk and the server dedups replays, so a failed
+ * receipt is a non-fatal warning surfaced via the injected stderr
+ * stream — never a sync failure.
+ *
+ * @param {string} serverUrl
+ * @param {string} apiKey
+ * @param {{owner: string, name: string, version: string}[]} skills
+ * @param {string} syncedAt - ISO timestamp for the delivery + dedup key.
+ * @param {NodeJS.WritableStream} stderr
+ */
+async function reportReceipt(serverUrl, apiKey, skills, syncedAt, stderr) {
+  if (skills.length === 0) return;
+  try {
+    await postSyncReceipt(serverUrl, apiKey, { skills, syncedAt });
+  } catch (err) {
+    stderr.write(
+      `  warning: failed to report sync receipt (${err.message}). ` +
+        `Your skills are synced locally; team sync status may lag until ` +
+        `your next sync.\n`,
+    );
+  }
+}
+
 /**
  * Check whether ANY of the configured placement targets already
  * contains a directory for the given skill name. Used to distinguish

package/src/test/e2e/mock-server.mjs

@@ -571,21 +571,29 @@ export function createMockServer(initialPayload, options = {}) {
       // newly-detected vendor placements empty forever. Mirroring the
       // filter here means any future regression of that class fails
       // at test time. See src/lib/queries/library.ts in the server
-      // for the production behavior (`gt(skills.updatedAt, since)`).
+      // for the production behavior. As of #1911 the production delta is
+      // `or(gt(skills.updatedAt, since), gt(skillLibraryItems.addedAt, since))`
+      // — a membership add delivers a skill whose CONTENT predates `since`.
+      // Mirror BOTH arms here, otherwise no CLI-layer test can exercise the
+      // addedAt branch and a server-side revert of it would pass every CLI
+      // test. Fixture skills may carry an optional `addedAt` ISO string to
+      // drive that arm; absent → only the updatedAt arm applies.
       let respondedSkills = libraryResponse.skills ?? [];
       if (sinceParam && Array.isArray(respondedSkills)) {
         const sinceDate = new Date(sinceParam);
         if (!Number.isNaN(sinceDate.getTime())) {
-          respondedSkills = respondedSkills.filter((s) => {
-            // updatedAt is a string ISO timestamp in the fixture skills.
-            // Missing/invalid → treat as "older than since" → exclude
-            // (matches the production semantic of "not modified in
-            // the window").
-            if (typeof s.updatedAt !== "string") return false;
-            const updated = new Date(s.updatedAt);
-            if (Number.isNaN(updated.getTime())) return false;
-            return updated.getTime() > sinceDate.getTime();
-          });
+          const afterSince = (iso) => {
+            // Missing/invalid → treat as "older than since" (excluded by
+            // this arm), matching the production semantic of "not modified
+            // / not added in the window".
+            if (typeof iso !== "string") return false;
+            const t = new Date(iso);
+            if (Number.isNaN(t.getTime())) return false;
+            return t.getTime() > sinceDate.getTime();
+          };
+          respondedSkills = respondedSkills.filter(
+            (s) => afterSince(s.updatedAt) || afterSince(s.addedAt),
+          );
         }
       }
 

package/src/test/lib/sync.test.mjs

@@ -38,7 +38,11 @@ import {
   runSync,
   readLastSync,
   writeLastSync,
+  upsertLastSyncEntry,
+  deleteLastSyncEntry,
   placementsAreComplete,
+  cliVersionBelowFloor,
+  FULL_RESYNC_FLOOR,
   LAST_SYNC_SCHEMA_VERSION,
 } from "../../lib/sync.mjs";
 import { resolvePlacementDir } from "../../lib/file-write.mjs";
@@ -263,6 +267,22 @@ describe("readLastSync / writeLastSync", () => {
     writeLastSync({ etag: "x", syncedAt: "x" });
     assert.ok(existsSync(globalLastSyncPath()));
   });
+
+  it("stamps cliVersion with the running CLI version by default (#1911)", () => {
+    // Every write records the writer's version so the heal gate
+    // (cliVersionBelowFloor) can tell on the next run whether the state
+    // predates the #1911 fix. getCliVersion() reads the real
+    // packages/cli/package.json, so this is a genuine semver.
+    writeLastSync({ etag: '"v"', syncedAt: "x" });
+    const onDisk = JSON.parse(readFileSync(globalLastSyncPath(), "utf-8"));
+    assert.match(onDisk.cliVersion, /^\d+\.\d+\.\d+/);
+  });
+
+  it("honors an explicit cliVersion override (test seam for pre-fix state) (#1911)", () => {
+    writeLastSync({ etag: '"v"', syncedAt: "x", cliVersion: "4.7.0" });
+    const onDisk = JSON.parse(readFileSync(globalLastSyncPath(), "utf-8"));
+    assert.equal(onDisk.cliVersion, "4.7.0");
+  });
 });
 
 // ── runSync — empty library ────────────────────────────────────────────
@@ -415,7 +435,7 @@ describe("runSync — sync receipts (#1832)", () => {
     }
   });
 
-  it("does NOT post a receipt on a 304 (nothing written)", async () => {
+  it("re-asserts the on-disk state on a 304 (liveness + heal), not nothing", async () => {
     server.setEtag('"v1"');
     server.setLibraryResponse({
       skills: [makeSkill("pdf-helper")],
@@ -427,14 +447,120 @@ describe("runSync — sync receipts (#1832)", () => {
     assert.equal(server.getReceiptRequestCount(), 1);
     server.resetReceipts();
 
-    // Second sync 304-short-circuits (etag matches, placement present).
+    // Second sync 304-short-circuits (etag matches, placement present) but
+    // STILL posts a receipt re-asserting the on-disk set. This is the
+    // liveness signal that replaces the GET-side 304 heartbeat for
+    // receipt-era servers, and it heals any delivery a prior failed
+    // receipt POST lost (#1832 PR B).
     const result = await runSync({
       serverUrl,
       apiKey: VALID_KEY,
       vendors: ["claudeCode"],
     });
     assert.equal(result.notModified, true);
-    assert.equal(server.getReceiptRequestCount(), 0);
+    assert.equal(server.getReceiptRequestCount(), 1);
+    const receipt = server.getLastReceipt();
+    assert.deepEqual(
+      receipt.skills.map((s) => s.name),
+      ["pdf-helper"],
+    );
+    assert.equal(receipt.skills[0].version, "1.0.0");
+    // syncedAt on a 304 is the CLI's "now" (the server sends no body),
+    // so freshness advances — not the stale first-sync timestamp.
+    assert.ok(
+      Number.isFinite(new Date(receipt.syncedAt).getTime()),
+      "304 receipt carries a valid ISO syncedAt",
+    );
+    assert.notEqual(
+      receipt.syncedAt,
+      "2025-06-01T00:00:00Z",
+      "304 receipt uses the CLI's now, not the prior sync timestamp",
+    );
+    // Stronger than "not the fixture": prove the timestamp is wall-clock
+    // FRESH. A regression that stamped the receipt with any stale cached
+    // value (e.g. lastSync.syncedAt) could differ from the fixture and
+    // still pass the notEqual above — but it would fail this. The liveness
+    // signal that replaces the 304 heartbeat must advance every sync.
+    assert.ok(
+      Date.now() - new Date(receipt.syncedAt).getTime() < 60_000,
+      "304 receipt syncedAt must be wall-clock fresh (within the last minute)",
+    );
+  });
+
+  it("re-asserts the full on-disk set (carry-forward + newly written) on a delta sync", async () => {
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alpha"), makeSkill("beta")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+    server.resetReceipts();
+
+    // Library changes: only `gamma` is new this round; alpha+beta are
+    // unchanged and arrive only via the carry-forward `.last-sync` map.
+    server.setEtag('"v2"');
+    server.setLibraryResponse({
+      skills: [makeSkill("gamma")],
+      removals: [],
+      syncedAt: "2025-01-02T00:00:00Z",
+    });
+    const result = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+    });
+
+    assert.equal(result.notModified, false);
+    assert.equal(server.getReceiptRequestCount(), 1);
+    const receipt = server.getLastReceipt();
+    // The receipt re-asserts EVERYTHING on disk, not just the changed
+    // skill — that is what heals server drift and keeps freshness honest.
+    assert.deepEqual(
+      receipt.skills.map((s) => s.name).sort(),
+      ["alpha", "beta", "gamma"],
+    );
+    // A 200 uses the server's response syncedAt for the delivery time.
+    assert.equal(receipt.syncedAt, "2025-01-02T00:00:00Z");
+  });
+
+  it("re-asserts carry-forward on a 200 delta that writes nothing new", async () => {
+    // Distinct from the 304 short-circuit: here the ETag changes (a real
+    // 200) but the response carries no skills to write, so nothing new
+    // lands on disk. The receipt must still re-assert the full carry-
+    // forward set — the 200 path's re-assertion is driven by the on-disk
+    // `.last-sync` map, not by what was written this round.
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alpha"), makeSkill("beta")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+    server.resetReceipts();
+
+    server.setEtag('"v2"');
+    server.setLibraryResponse({
+      skills: [],
+      removals: [],
+      syncedAt: "2025-01-02T00:00:00Z",
+    });
+    const result = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+    });
+
+    assert.equal(result.notModified, false);
+    assert.equal(result.added, 0);
+    assert.equal(result.updated, 0);
+    assert.equal(server.getReceiptRequestCount(), 1);
+    const receipt = server.getLastReceipt();
+    assert.deepEqual(
+      receipt.skills.map((s) => s.name).sort(),
+      ["alpha", "beta"],
+    );
+    assert.equal(receipt.syncedAt, "2025-01-02T00:00:00Z");
   });
 
   it("excludes a filesIncomplete skill from the receipt", async () => {
@@ -454,9 +580,48 @@ describe("runSync — sync receipts (#1832)", () => {
     );
   });
 
-  it("does NOT post a receipt when ALL skills are filesIncomplete", async () => {
-    // Distinct branch from the mixed case above: `writtenThisSync` stays
-    // empty, so the `writtenThisSync.length > 0` guard skips the POST.
+  it("re-asserts the OLD on-disk version when a newer version fails to inline (filesIncomplete carry-forward)", async () => {
+    // First sync writes pdf-helper@1.0.0.
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("pdf-helper")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+    server.resetReceipts();
+
+    // The server tries to deliver pdf-helper@1.1.0 but its files fail to
+    // inline. The CLI skips the write (1.0.0 stays on disk) and must
+    // re-assert the OLD version it still has — not the version it failed
+    // to write, and not nothing.
+    const newer = makeSkill("pdf-helper");
+    newer.version = "1.1.0";
+    newer.filesIncomplete = true;
+    server.setEtag('"v2"');
+    server.setLibraryResponse({
+      skills: [newer],
+      removals: [],
+      syncedAt: "2025-01-02T00:00:00Z",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+
+    assert.equal(server.getReceiptRequestCount(), 1);
+    const receipt = server.getLastReceipt();
+    assert.deepEqual(receipt.skills, [
+      { owner: "alice", name: "pdf-helper", version: "1.0.0" },
+    ]);
+    // Freshness still advances on a partial sync: the receipt carries the
+    // SERVER's 200 response syncedAt (the fresh sync time), not the stale
+    // carry-forward entry's own recorded syncedAt.
+    assert.equal(receipt.syncedAt, "2025-01-02T00:00:00Z");
+  });
+
+  it("does NOT post a receipt when ALL skills are filesIncomplete (nothing on disk to assert)", async () => {
+    // A first sync where every skill is filesIncomplete writes nothing
+    // and has no carry-forward `.last-sync` baseline, so the post-sync
+    // on-disk set is empty and `reportReceipt`'s empty-skills guard skips
+    // the POST.
     const a = makeSkill("inc-a");
     a.filesIncomplete = true;
     const b = makeSkill("inc-b");
@@ -821,10 +986,41 @@ describe("runSync — tombstones", () => {
     });
     assert.equal(result.removed, 1);
     assert.ok(!existsSync(resolvePlacementDir("claudeProject", "doomed")));
-    // A tombstone-only sync writes nothing → posts no receipt (#1832).
+    // The `.last-sync` baseline was reset (rm above) and the only skill
+    // was tombstoned, so the post-sync on-disk set is empty → the
+    // re-assertion receipt has nothing to send and is skipped (#1832).
     assert.equal(server.getReceiptRequestCount(), 0);
   });
 
+  it("re-asserts surviving skills but excludes a tombstoned one", async () => {
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("keep"), makeSkill("drop")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+    server.resetReceipts();
+
+    // `drop` is tombstoned; `keep` stays on disk and must be re-asserted.
+    server.setEtag('"v2"');
+    server.setLibraryResponse({
+      skills: [],
+      removals: [
+        { owner: "alice", name: "drop", removedAt: "2025-01-02T00:00:00Z" },
+      ],
+      syncedAt: "2025-01-02T00:00:00Z",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+
+    assert.equal(server.getReceiptRequestCount(), 1);
+    const receipt = server.getLastReceipt();
+    assert.deepEqual(
+      receipt.skills.map((s) => s.name),
+      ["keep"],
+    );
+  });
+
   it("applies removals BEFORE writes (re-add scenario)", async () => {
     // The server returns a tombstone AND a skill with the same name
     // (the user removed and re-added in the same window). The CLI
@@ -950,6 +1146,286 @@ describe("runSync — ETag round-trip", () => {
 
 // ── runSync — argument validation ──────────────────────────────────────
 
+describe("runSync — one-time membership heal (#1911)", () => {
+  beforeEach(setupServer);
+  afterEach(teardownServer);
+
+  it("cliVersionBelowFloor: missing/invalid/older → true; equal/newer → false", () => {
+    assert.equal(cliVersionBelowFloor(undefined, "4.8.0"), true);
+    assert.equal(cliVersionBelowFloor(null, "4.8.0"), true);
+    assert.equal(cliVersionBelowFloor("", "4.8.0"), true);
+    assert.equal(cliVersionBelowFloor("not-semver", "4.8.0"), true);
+    assert.equal(cliVersionBelowFloor("4.7.0", "4.8.0"), true);
+    assert.equal(cliVersionBelowFloor("4.7.9", "4.8.0"), true);
+    assert.equal(cliVersionBelowFloor("4.8.0", "4.8.0"), false);
+    assert.equal(cliVersionBelowFloor("4.8.1", "4.8.0"), false);
+    assert.equal(cliVersionBelowFloor("5.0.0", "4.8.0"), false);
+  });
+
+  it("FULL_RESYNC_FLOOR equals the shipped CLI version", () => {
+    // The floor MUST equal the version that ships this fix; otherwise the
+    // running CLI's own writes would stamp a version below the floor and
+    // it would re-heal on every run. Lock them together.
+    const pkg = JSON.parse(
+      readFileSync(new URL("../../../package.json", import.meta.url), "utf-8"),
+    );
+    assert.equal(FULL_RESYNC_FLOOR, pkg.version);
+  });
+
+  it("a pre-fix .last-sync forces ONE full re-fetch, then resumes delta", async () => {
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("healme")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+
+    // 1) Normal sync by the current CLI → disk + .last-sync stamped with
+    //    the current (>= floor) version.
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+
+    // 2) Rewrite .last-sync to mimic a PRE-#1911 writer: identical
+    //    etag/skills/syncedAt — so placements are complete and a 304 WOULD
+    //    normally fire — but stamped below the heal floor.
+    const prior = readLastSync();
+    writeLastSync({
+      etag: prior.etag,
+      syncedAt: prior.syncedAt,
+      skills: prior.skills,
+      cliVersion: "4.7.0",
+    });
+    server.resetLibraryInspection();
+
+    // 3) Heal: must force a FULL fetch — NEITHER conditional header sent —
+    //    despite complete placements and a matching etag.
+    const heal = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+    });
+    assert.equal(
+      server.getLastLibraryIfNoneMatch(),
+      null,
+      "heal must NOT send If-None-Match",
+    );
+    assert.equal(server.getLastLibrarySince(), null, "heal must NOT send since");
+    assert.equal(heal.notModified, false, "heal performs a real fetch, not a 304");
+
+    // 4) The heal write re-stamped the current version → the next sync
+    //    resumes normal delta (sends the conditional, gets a 304).
+    const after = readLastSync();
+    assert.equal(
+      cliVersionBelowFloor(after.cliVersion, FULL_RESYNC_FLOOR),
+      false,
+      "heal must restamp cliVersion at/above the floor",
+    );
+    server.resetLibraryInspection();
+    const resumed = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+    });
+    assert.equal(
+      server.getLastLibraryIfNoneMatch(),
+      '"v1"',
+      "post-heal sync sends If-None-Match",
+    );
+    assert.equal(
+      resumed.notModified,
+      true,
+      "post-heal sync short-circuits on 304",
+    );
+  });
+
+  it("does NOT force a re-fetch when .last-sync was written at/above the floor", async () => {
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("steady")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    // First sync stamps the current (>= floor) version.
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+    server.resetLibraryInspection();
+
+    const second = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+    });
+    assert.equal(
+      server.getLastLibraryIfNoneMatch(),
+      '"v1"',
+      "steady-state sync still sends the conditional (no spurious heal)",
+    );
+    assert.equal(second.notModified, true, "no heal → normal 304");
+  });
+
+  it("heals a REAL pre-fix v2 .last-sync (cliVersion key absent, not just old)", async () => {
+    // The actual on-disk shape for users still on < 4.8.0 is a v2 file with
+    // NO `cliVersion` key at all (writeLastSync didn't emit it pre-#1911) —
+    // distinct from an explicit "4.7.0". Prove the heal fires for that shape
+    // end-to-end through runSync (the unit test of cliVersionBelowFloor(undefined)
+    // covers the gate in isolation; this covers the full path).
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("healme2")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+    const prior = readLastSync();
+
+    // Rewrite as a genuine pre-#1911 v2 file: cliVersion key entirely absent.
+    mkdirSync(join(process.env.HOME, ".claude", "skillrepo"), { recursive: true });
+    writeFileSync(
+      globalLastSyncPath(),
+      JSON.stringify({
+        schemaVersion: 2,
+        etag: prior.etag,
+        syncedAt: prior.syncedAt,
+        skills: prior.skills,
+      }),
+    );
+    const onDisk = JSON.parse(readFileSync(globalLastSyncPath(), "utf-8"));
+    assert.equal(
+      Object.prototype.hasOwnProperty.call(onDisk, "cliVersion"),
+      false,
+      "precondition: cliVersion must be ABSENT, not old",
+    );
+    server.resetLibraryInspection();
+
+    const heal = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+    });
+    assert.equal(server.getLastLibraryIfNoneMatch(), null, "absent cliVersion must heal");
+    assert.equal(server.getLastLibrarySince(), null, "absent cliVersion must heal");
+    assert.equal(heal.notModified, false);
+    assert.equal(
+      cliVersionBelowFloor(readLastSync().cliVersion, FULL_RESYNC_FLOOR),
+      false,
+      "heal restamps a real version so it won't re-heal",
+    );
+  });
+
+  it("delta delivers a skill whose content predates `since` but was added after it", async () => {
+    // The CLI-layer counterpart of the server fix: a steady-state DELTA sync
+    // (since sent, NOT a heal) must still receive a skill whose updatedAt is
+    // older than `since` when its addedAt is newer. The mock mirrors the
+    // server's `or(updatedAt, addedAt)` filter so a server-side revert of the
+    // addedAt branch would fail here, not silently pass.
+    const S = "2025-06-01T00:00:00Z";
+    server.setEtag('"e1"');
+    server.setLibraryResponse({
+      skills: [{ ...makeSkill("base"), updatedAt: "2025-06-02T00:00:00Z" }],
+      removals: [],
+      syncedAt: S,
+    });
+    // Baseline sync: puts `base` on disk, stamps current version (no heal).
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+
+    // A new skill enters the library: OLD content (updatedAt < S), just ADDED
+    // (addedAt > S). Library etag changes (not a 304).
+    server.setEtag('"e2"');
+    server.setLibraryResponse({
+      skills: [
+        { ...makeSkill("base"), updatedAt: "2025-06-02T00:00:00Z" },
+        {
+          ...makeSkill("added-old"),
+          updatedAt: "2025-01-01T00:00:00Z",
+          addedAt: "2025-12-01T00:00:00Z",
+        },
+      ],
+      removals: [],
+      syncedAt: "2025-12-02T00:00:00Z",
+    });
+    server.resetLibraryInspection();
+    const result = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+    });
+
+    assert.equal(server.getLastLibrarySince(), S, "must be a DELTA (since sent), not a heal");
+    assert.ok(
+      existsSync(join(resolvePlacementDir("claudeProject", "added-old"), "SKILL.md")),
+      "addedAt-only skill must be delivered via the membership branch",
+    );
+    assert.equal(result.added, 1, "the added-old skill counts as newly added");
+  });
+
+  it("upsertLastSyncEntry preserves a pre-fix cliVersion so the heal isn't burned", () => {
+    // A stuck pre-fix client whose FIRST 4.8.0 command is `add`/`get`
+    // (→ upsertLastSyncEntry) must NOT have its heal-gate version advanced —
+    // add fetches ONE skill, not the full library, so other stuck skills
+    // remain missing and the next `update` must still heal.
+    writeLastSync({
+      etag: '"e"',
+      syncedAt: "2025-01-01T00:00:00Z",
+      skills: {},
+      cliVersion: "4.7.0",
+    });
+    upsertLastSyncEntry({
+      owner: "alice",
+      name: "added",
+      version: "1.0.0",
+      files: [
+        { path: "SKILL.md", content: "---\nname: added\ndescription: d\n---\nbody" },
+      ],
+    });
+    assert.equal(
+      readLastSync().cliVersion,
+      "4.7.0",
+      "add/get must not advance the heal-gate version",
+    );
+  });
+
+  it("upsertLastSyncEntry carries an ABSENT cliVersion forward (still below floor)", () => {
+    mkdirSync(join(process.env.HOME, ".claude", "skillrepo"), { recursive: true });
+    writeFileSync(
+      globalLastSyncPath(),
+      JSON.stringify({ schemaVersion: 2, etag: '"e"', syncedAt: "s", skills: {} }),
+    );
+    upsertLastSyncEntry({
+      owner: "alice",
+      name: "added",
+      version: "1.0.0",
+      files: [
+        { path: "SKILL.md", content: "---\nname: added\ndescription: d\n---\nbody" },
+      ],
+    });
+    assert.equal(
+      cliVersionBelowFloor(readLastSync().cliVersion, FULL_RESYNC_FLOOR),
+      true,
+      "absent cliVersion stays below floor → next update still heals",
+    );
+  });
+
+  it("deleteLastSyncEntry preserves a pre-fix cliVersion", () => {
+    writeLastSync({
+      etag: '"e"',
+      syncedAt: "s",
+      skills: {
+        "alice/x": {
+          version: "1.0.0",
+          skillMdSha256: "a".repeat(64),
+          filesSha256: "b".repeat(64),
+          syncedAt: "s",
+        },
+      },
+      cliVersion: "4.7.0",
+    });
+    deleteLastSyncEntry("alice", "x");
+    assert.equal(
+      readLastSync().cliVersion,
+      "4.7.0",
+      "remove must not advance the heal-gate version",
+    );
+  });
+});
+
 describe("runSync — input validation", () => {
   beforeEach(setupServer);
   afterEach(teardownServer);