skillrepo 4.5.0 → 4.5.2

package/package.json

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

package/src/commands/add.mjs

@@ -46,6 +46,7 @@ import {
   effectiveVendors,
   requireVendorTargets,
 } from "../lib/cli-config.mjs";
+import { upsertLastSyncEntry } from "../lib/sync.mjs";
 import { parseIdentifier, formatIdentifier } from "../lib/identifier.mjs";
 import { validationError } from "../lib/errors.mjs";
 
@@ -158,6 +159,20 @@ export async function runAdd(argv, io = {}) {
 
   writeSkillDir(skill, { vendors, global: flags.global });
 
+  // Update `.last-sync` so `list` immediately recognizes this skill
+  // as `current`. Without this the user adds a skill, then runs
+  // `list`, and sees their freshly-added skill marked MISS — the
+  // exact same class of contract gap that PR #1574 fixed for the
+  // multi-vendor case in `update`/`list`. See `upsertLastSyncEntry`
+  // docstring for the etag-preservation rationale.
+  try {
+    upsertLastSyncEntry(skill);
+  } catch {
+    // Non-fatal: skill is on disk, the state file write failure
+    // does not change that. Same semantics as runSync's warn-and-
+    // proceed for last-sync persistence failures.
+  }
+
   if (flags.json) {
     stdout.write(
       JSON.stringify(
@@ -181,11 +196,11 @@ export async function runAdd(argv, io = {}) {
     .join(", ")})`;
   if (wasNewlyAdded) {
     stdout.write(
-      `\n  ✓ Added ${formatIdentifier({ owner, name })} to your library (${skill.files.length} files) → ${where}\n\n`,
+      `\n  ✓ Added ${formatIdentifier({ owner, name })} to your library (${skill.files.length} file${skill.files.length === 1 ? "" : "s"}) → ${where}\n\n`,
     );
   } else {
     stdout.write(
-      `\n  ✓ ${formatIdentifier({ owner, name })} was already in your library — refreshed (${skill.files.length} files) → ${where}\n\n`,
+      `\n  ✓ ${formatIdentifier({ owner, name })} was already in your library — refreshed (${skill.files.length} file${skill.files.length === 1 ? "" : "s"}) → ${where}\n\n`,
     );
   }
 }

package/src/commands/get.mjs

@@ -36,6 +36,7 @@ import {
   effectiveVendors,
   requireVendorTargets,
 } from "../lib/cli-config.mjs";
+import { upsertLastSyncEntry } from "../lib/sync.mjs";
 import { parseIdentifier, formatIdentifier } from "../lib/identifier.mjs";
 import { validationError } from "../lib/errors.mjs";
 
@@ -109,6 +110,21 @@ export async function runGet(argv, io = {}) {
 
   writeSkillDir(skill, { vendors, global: flags.global });
 
+  // Update `.last-sync` so `list` recognizes this skill as `current`
+  // afterward instead of reporting a stale `MISSING`. Best-effort:
+  // a state-file write failure is non-fatal (the files are already
+  // on disk), but writeLastSync throws diskError if it cannot
+  // persist — we catch and continue. Pre-PR #1574 `get` skipped
+  // this entirely, which surfaced every freshly-fetched skill as
+  // MISS in the very next `list` invocation.
+  try {
+    upsertLastSyncEntry(skill);
+  } catch {
+    // Same failure semantics as runSync's "couldn't persist last
+    // sync state" path: warn and proceed, the user's intent (files
+    // on disk) was honored.
+  }
+
   if (flags.json) {
     stdout.write(
       JSON.stringify({
@@ -127,6 +143,6 @@ export async function runGet(argv, io = {}) {
     .map(describePlacementTarget)
     .join(", ")})`;
   stdout.write(
-    `\n  ✓ Fetched ${formatIdentifier({ owner, name })} (${skill.files.length} files) → ${where}\n\n`,
+    `\n  ✓ Fetched ${formatIdentifier({ owner, name })} (${skill.files.length} file${skill.files.length === 1 ? "" : "s"}) → ${where}\n\n`,
   );
 }

package/src/commands/list.mjs

@@ -243,9 +243,13 @@ function printTable(augmented, detected, out) {
       .join(", ");
     out.write(`\n  Detected: ${detectedLabel}\n`);
   } else {
-    out.write(
-      "\n  No agents detected in this project — drift cannot be reported.\n",
-    );
+    // Earlier copy said "drift cannot be reported" but the table
+    // below DOES report drift — every skill rolls up as MISSING
+    // because no placement exists to compare against. The simpler
+    // statement of fact is what users need; the footer ("No sync
+    // history…" / "library has changed…") tells them what to do
+    // next.
+    out.write("\n  No agents detected in this project.\n");
   }
 
   const sorted = augmented.slice().sort(sortByOwnerAndName);
@@ -337,12 +341,27 @@ function printFooter(augmented, libraryEtag, lastSync, out, useGlyphs) {
   }
 
   if (etagMatches && driftCount > 0) {
-    out.write(
-      `\n  ${warn} library in sync — but ${driftCount} skill${
-        driftCount === 1 ? "" : "s"
-      } show${driftCount === 1 ? "s" : ""} local drift.\n` +
-        "    Run `skillrepo update` to refresh.\n\n",
-    );
+    // Distinguish EDITED (running update loses user changes) from
+    // MISS/STALE (running update is non-destructive — fills gaps or
+    // pulls a newer version). The earlier copy said "Run `skillrepo
+    // update` to refresh" for every drift case, which silently
+    // destroyed user edits when EDITED rows were present. Now we
+    // warn explicitly when edits are at risk.
+    const editedCount = augmented.filter(
+      (s) => s.state === SKILL_STATE.EDITED,
+    ).length;
+    const driftPhrase = `${driftCount} skill${driftCount === 1 ? "" : "s"} show${driftCount === 1 ? "s" : ""}`;
+    if (editedCount > 0) {
+      out.write(
+        `\n  ${warn} library in sync — but ${driftPhrase} local drift, including ${editedCount} with local edit${editedCount === 1 ? "" : "s"}.\n` +
+          "    Run `skillrepo update` to refresh — this will OVERWRITE local edits.\n\n",
+      );
+    } else {
+      out.write(
+        `\n  ${warn} library in sync — but ${driftPhrase} local drift.\n` +
+          "    Run `skillrepo update` to refresh.\n\n",
+      );
+    }
     return;
   }
 

package/src/commands/remove.mjs

@@ -43,6 +43,7 @@ import {
   effectiveVendors,
   requireVendorTargets,
 } from "../lib/cli-config.mjs";
+import { deleteLastSyncEntry } from "../lib/sync.mjs";
 import { parseIdentifier, formatIdentifier } from "../lib/identifier.mjs";
 import { validationError } from "../lib/errors.mjs";
 
@@ -111,6 +112,18 @@ export async function runRemove(argv, io = {}) {
   // owner-namespacing caveat.
   const localResult = removeSkillDir(name, { vendors, global: flags.global });
 
+  // Step 2.5: purge the `.last-sync` entry for this skill so a future
+  // re-add of the same identifier doesn't compare against a stale
+  // baseline. Idempotent: no-op if the entry isn't there. Non-fatal
+  // on write failure — the user's primary intent (skill gone from
+  // library + disk) was honored; a stale baseline is recoverable
+  // via the next `update`.
+  try {
+    deleteLastSyncEntry(owner, name);
+  } catch {
+    // Same warn-and-proceed semantics as runSync's last-sync writes.
+  }
+
   if (flags.json) {
     stdout.write(
       JSON.stringify(

package/src/lib/agent-registry.mjs

@@ -140,7 +140,21 @@ export const AGENT_REGISTRY = Object.freeze([
     agentHook: null,
     detectionSignals: Object.freeze([
       Object.freeze({ type: "env", value: "CLAUDECODE" }),
-      Object.freeze({ type: "home", value: ".claude" }),
+      // Home signal MUST be a file Claude Code creates that SkillRepo
+      // itself never writes. The earlier `.claude` (bare dir) signal
+      // false-positive-detected on any user who'd ever run a SkillRepo
+      // command — because `init` writes config to
+      // `~/.claude/skillrepo/config.json` and every `runSync` writes
+      // `.last-sync` to the same parent, both of which create the
+      // `~/.claude/` directory as a side effect. Cursor-only users
+      // (or any non-Claude-Code user) were then incorrectly detected
+      // as Claude Code users on every subsequent `list` invocation,
+      // producing MISS for every skill at the claudeProject placement
+      // that was never populated. Probing `settings.json` — created by
+      // Claude Code on first run and never touched by SkillRepo — is
+      // the load-bearing distinction. See PR #1574 production-
+      // readiness audit for the full chain.
+      Object.freeze({ type: "home", value: ".claude/settings.json" }),
       Object.freeze({ type: "project", value: ".claude" }),
     ]),
   }),

package/src/lib/cli-config.mjs

@@ -25,6 +25,7 @@ import {
   AGENTS_COHORT_KEYS,
   getAgentByAlias,
 } from "./agent-registry.mjs";
+import { detectAgents } from "./detect-agents.mjs";
 import { authError, validationError } from "./errors.mjs";
 
 const ALL_VENDOR_KEYS = AGENT_REGISTRY.map((entry) => entry.key);
@@ -204,22 +205,48 @@ export function resolveFlags(argv, opts = {}) {
  *      always wins. Both flags propagate together, so `--global
  *      --agent windsurf` correctly resolves to `["windsurf"]` and
  *      placementTargetsFor maps that to `windsurfGlobal`.
- *   2. No `--agent` defaults to `["claudeCode"]`, regardless of
- *      `--global`. The v3.0.0 CLI deliberately does NOT silently
- *      fall back to `[claudeCode, cursor]` like v2.0.0 did.
+ *   2. No `--agent` defaults to ALL DETECTED vendors (4.5.1+) — every
+ *      agent whose detection signal fires in the current cwd / HOME /
+ *      env. This matches `init`'s picker behavior and `list`'s drift
+ *      detection model: the CLI assumes you want to keep every
+ *      agent on your machine in sync.
+ *   3. Fallback to `["claudeCode"]` when nothing is detected (fresh
+ *      machine with no agent installed yet — extremely rare, but
+ *      preserves the historical default so `skillrepo init` from
+ *      scratch still has a meaningful behavior).
+ *
+ * History: 4.4.0 and earlier defaulted to `["claudeCode"]` only,
+ * which created a mismatch with `list`'s drift detection in 4.5.0:
+ * `list` reported drift against all detected vendors while
+ * `update`/`add`/`remove`/`get` only wrote to Claude Code's
+ * placement. Multi-agent users saw every skill as `MISS` even after
+ * a full sync because the cohort `.agents/skills/` directory was
+ * never written to. See #1573 follow-up.
  *
  * The empty-array `--agent none` sentinel is returned verbatim —
  * callers detect "no placement" via `vendors.length === 0`. The
  * default-fallback branch uses an explicit null/undefined check so
  * the empty array survives.
  */
-export function effectiveVendors(flags) {
+export function effectiveVendors(flags, { detect = defaultDetectVendors } = {}) {
   if (flags.vendors === null || flags.vendors === undefined) {
-    return ["claudeCode"];
+    const detected = detect();
+    return detected.length > 0 ? detected : ["claudeCode"];
   }
   return flags.vendors;
 }
 
+/**
+ * Default detection callable for `effectiveVendors`. Exposed for tests
+ * that want to inject a deterministic vendor list via the second-arg
+ * `{ detect }` option — production callers should not pass anything.
+ */
+function defaultDetectVendors() {
+  return detectAgents()
+    .filter((d) => d.detected)
+    .map((d) => d.key);
+}
+
 /**
  * Reject `--agent none` for commands that have no meaningful behavior
  * without a placement target. `init` and `update` accept `--agent none`

package/src/lib/detect-agents.mjs

@@ -34,12 +34,51 @@
  * so probes are sandbox-isolated on every platform.
  */
 
-import { existsSync } from "node:fs";
+import { existsSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
 import { AGENT_REGISTRY } from "./agent-registry.mjs";
 
+/**
+ * Returns true when `path` exists and is reachable. Wraps `existsSync`
+ * for symmetry with the file-vs-dir formatters below; kept as a
+ * separate helper so a future refinement (e.g., disallow broken
+ * symlinks) can land in one place.
+ */
+function probeFsPath(path) {
+  return existsSync(path);
+}
+
+/**
+ * Format the `reason` for a fired `home` signal. Bare-directory signals
+ * (`.cursor`, `~/.codeium/windsurf`) get a trailing slash; file-shaped
+ * signals (`.claude/settings.json`) do not, because rendering a file
+ * path with a trailing slash misleads the user in init's
+ * "(detected: …)" hint string. We `statSync` to distinguish — that
+ * avoids brittle string heuristics (we cannot just look for a dot in
+ * the last segment, because directories with dots in their names are
+ * permitted by every supported filesystem).
+ */
+function formatHomeReason(value, path) {
+  return isFile(path) ? `~/${value}` : `~/${value}/`;
+}
+
+function formatProjectReason(value, path) {
+  return isFile(path) ? value : `${value}/`;
+}
+
+function isFile(path) {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    // statSync after a successful existsSync is unlikely to throw, but
+    // a TOCTOU between the two would crash the picker. Default to the
+    // directory format on any read error.
+    return false;
+  }
+}
+
 /**
  * @typedef {Object} AgentDetection
  * @property {string} key                 - Canonical agent key.
@@ -72,13 +111,11 @@ function probeSignal(signal) {
   }
   if (signal.type === "home") {
     const path = join(homedir(), signal.value);
-    if (!existsSync(path)) return null;
-    return `~/${signal.value}/`;
+    return probeFsPath(path) ? formatHomeReason(signal.value, path) : null;
   }
   if (signal.type === "project") {
     const path = join(process.cwd(), signal.value);
-    if (!existsSync(path)) return null;
-    return `${signal.value}/`;
+    return probeFsPath(path) ? formatProjectReason(signal.value, path) : null;
   }
   // Unknown type — defensive guard. Callers should never see this
   // because the registry's frozen entries are typed.

package/src/lib/sync.mjs

@@ -85,6 +85,7 @@
  */
 
 import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 
 import { getLibrary } from "./http.mjs";
 import {
@@ -110,6 +111,103 @@ import { computeSkillShas } from "./crypto-shas.mjs";
  */
 export const LAST_SYNC_SCHEMA_VERSION = 2;
 
+/**
+ * Check whether every skill in the `.last-sync` baseline already exists
+ * under every placement target the current sync would write to. Returns
+ * true when the 304 short-circuit is safe (skipping writes won't leave
+ * any placement empty), false when at least one (skill, target) pair
+ * is missing on disk.
+ *
+ * This is the load-bearing guard for the ETag fast path. The contract:
+ * "library content unchanged AND every expected placement already has
+ * its content" — the second clause is what this function enforces.
+ *
+ * See the call site in runSync for the full motivation (upgrade-path,
+ * --global ↔ project swap, and cwd-switch scenarios all funnel through
+ * this gate).
+ *
+ * @param {Record<string, {skillMdSha256: string, filesSha256: string, version: string}> | null | undefined} skillsMap
+ *   The `.skills` map from `.last-sync` — keyed by `"<owner>/<name>"`.
+ * @param {string[] | undefined} vendors
+ *   The current sync's vendor list (output of `effectiveVendors`).
+ * @param {boolean | undefined} global
+ *   Whether the current sync is `--global` mode.
+ * @returns {boolean}
+ */
+export function placementsAreComplete(skillsMap, vendors, global) {
+  // Empty baseline: we cannot trust the ETag short-circuit. Two
+  // legitimate code paths land here:
+  //   1. Genuine fresh install — no `.last-sync` file at all; this
+  //      function isn't called because runSync's caller checks
+  //      `lastSync?.etag` before invoking. So we never see this
+  //      branch in the fresh-install case.
+  //   2. v1 → v2 migration — `readLastSync` synthesizes an empty
+  //      `skills` map for a v1 file (which had no per-skill SHA
+  //      cache). The etag IS present but the baseline is empty;
+  //      a 304 would tell us "library unchanged" but we'd still
+  //      have no per-skill cache, so `list` would render every
+  //      skill as MISS. Forcing a re-fetch here populates the
+  //      cache and surfaces the actual library state.
+  // The conservative direction is "force re-fetch" — wire cost
+  // happens once per upgrade, not every time.
+  if (
+    !skillsMap ||
+    typeof skillsMap !== "object" ||
+    Object.keys(skillsMap).length === 0
+  ) {
+    return false;
+  }
+
+  // No vendors: this is the `--agent none` case or a degenerate config.
+  // requireVendorTargets will catch this downstream; from here, treat
+  // as "no placements to verify" → trivially complete.
+  if (!Array.isArray(vendors) || vendors.length === 0) {
+    return true;
+  }
+
+  let targets;
+  try {
+    targets = placementTargetsFor({ vendors, global: global === true });
+  } catch {
+    // placementTargetsFor throws on an invalid vendor + scope combo
+    // (e.g., `--global` with a vendor that has no `globalTarget`).
+    // The downstream runSync write loop will surface the same error
+    // with the correct typed exception; conservatively treat as
+    // "placement incomplete" so we drop the ETag and force the
+    // full-fetch path (which is what we'd want under any error).
+    return false;
+  }
+
+  for (const key of Object.keys(skillsMap)) {
+    // Skill keys are `"<owner>/<name>"`. We only need the name half
+    // because placement directories are keyed by skill name alone.
+    const slashAt = key.indexOf("/");
+    if (slashAt < 0) continue; // malformed entry — skip rather than crash
+    const skillName = key.slice(slashAt + 1);
+    if (!skillName) continue;
+
+    for (const target of targets) {
+      const dir = resolvePlacementDir(target, skillName);
+      // Probe `SKILL.md` rather than the bare directory. An empty or
+      // partial directory left behind by a hostile filesystem
+      // condition (manual mkdir, third-party tool, interrupted write
+      // before the atomic rename — rare but possible) would otherwise
+      // satisfy `existsSync(dir)` and let the 304 fire, leaving the
+      // user with a placement that contains no usable skill content.
+      // SKILL.md is the spec-required entry point; its presence is
+      // the load-bearing invariant the placement-presence check is
+      // really asserting.
+      if (!existsSync(join(dir, "SKILL.md"))) {
+        // ONE missing placement is enough — full re-fetch will re-write
+        // EVERY skill to EVERY target, restoring the invariant in one
+        // round.
+        return false;
+      }
+    }
+  }
+  return true;
+}
+
 /**
  * Read the persisted last-sync state from ~/.claude/skillrepo/.last-sync.
  * Returns null if the file doesn't exist, is malformed, or has a
@@ -218,6 +316,99 @@ export function writeLastSync({ etag, syncedAt, skills } = {}) {
   }
 }
 
+/**
+ * Add or replace a single skill's entry in `.last-sync` without
+ * touching the library-level `etag`/`syncedAt` fields.
+ *
+ * Why this exists: `get` and `add` write skills to disk one at a time
+ * without going through `runSync`. Pre-PR #1574 those commands left
+ * `.last-sync` untouched — meaning `list` afterwards couldn't see the
+ * skill in its baseline map and rendered it as `MISSING` even though
+ * it was sitting right there on disk. This helper closes that
+ * contract gap: any command that writes one skill's bytes to disk
+ * MUST also record the corresponding SHAs in `.last-sync` so the
+ * read-side drift detection can find them.
+ *
+ * Library-level `etag` and `syncedAt` are preserved verbatim from the
+ * prior state because they describe "what library snapshot did we
+ * fetch last" — `get` and `add` did not refresh that snapshot, so
+ * overwriting those fields would break the 304 short-circuit on the
+ * NEXT `update` (the server would think we're already past a state
+ * we never reached).
+ *
+ * Non-fatal on read/write failure: the actual skill files were
+ * already written to disk before we got here, so a broken state file
+ * should not roll back the user's intent. We throw on `writeLastSync`
+ * failure (same as the bulk path) so the caller can surface the
+ * warning, but otherwise this function is best-effort.
+ *
+ * @param {Object} skill - The skill that was just written.
+ * @param {string} skill.owner
+ * @param {string} skill.name
+ * @param {string} skill.version
+ * @param {{ path: string, content: string }[]} skill.files
+ */
+export function upsertLastSyncEntry(skill) {
+  if (!skill || typeof skill !== "object") return;
+  if (typeof skill.owner !== "string" || typeof skill.name !== "string") return;
+  if (!Array.isArray(skill.files)) return;
+
+  const shas = computeSkillShas(skill.files);
+  // computeSkillShas returns nulls when there's no SKILL.md; persisting
+  // null SHAs would later classify as `edited`, which is wrong for a
+  // skill we just installed. Skip the upsert in that pathological case
+  // — list.mjs's `MISSING` verdict for an unknown skill is a more
+  // accurate signal than a fabricated `current` or `edited`.
+  if (shas.skillMdSha256 === null || shas.filesSha256 === null) return;
+
+  const prior = readLastSync();
+  const priorSkills =
+    prior && prior.skills && typeof prior.skills === "object"
+      ? prior.skills
+      : {};
+
+  const key = `${skill.owner}/${skill.name}`;
+  const updated = {
+    ...priorSkills,
+    [key]: {
+      version: typeof skill.version === "string" ? skill.version : "",
+      skillMdSha256: shas.skillMdSha256,
+      filesSha256: shas.filesSha256,
+      syncedAt: new Date().toISOString(),
+    },
+  };
+
+  writeLastSync({
+    // Preserve etag and syncedAt — see docstring "why this exists."
+    etag: prior?.etag ?? null,
+    syncedAt: prior?.syncedAt,
+    skills: updated,
+  });
+}
+
+/**
+ * Remove a single skill's entry from `.last-sync` without touching
+ * library-level fields. Used by `remove` after deleting the on-disk
+ * files. Idempotent: if the entry isn't there, no-op.
+ *
+ * @param {string} owner
+ * @param {string} name
+ */
+export function deleteLastSyncEntry(owner, name) {
+  if (typeof owner !== "string" || typeof name !== "string") return;
+  const prior = readLastSync();
+  if (!prior || !prior.skills || typeof prior.skills !== "object") return;
+  const key = `${owner}/${name}`;
+  if (!(key in prior.skills)) return;
+  // eslint-disable-next-line no-unused-vars -- destructure-to-omit pattern
+  const { [key]: _removed, ...rest } = prior.skills;
+  writeLastSync({
+    etag: prior.etag ?? null,
+    syncedAt: prior.syncedAt,
+    skills: rest,
+  });
+}
+
 /**
  * Run a library sync against the server.
  *
@@ -277,8 +468,61 @@ export async function runSync(options) {
 
   // Step 3: fetch with conditional headers
   const opts = {};
-  if (lastSync?.etag) opts.ifNoneMatch = lastSync.etag;
-  if (lastSync?.syncedAt) opts.since = lastSync.syncedAt;
+  // The ETag short-circuit is only safe when EVERY skill in
+  // `.last-sync`'s baseline is present in EVERY placement directory
+  // the current sync would write to. The 304 means "library content
+  // unchanged" — but the local placement set can change between
+  // syncs even when content does not:
+  //
+  //   - User upgrades from 4.5.0 (single-vendor default) to 4.5.1+
+  //     (all-detected default) — new vendors detected, their
+  //     placement dirs are empty.
+  //   - User runs `update --global` once, then `update` (no flag)
+  //     later — same vendor, but the resolved placement dir is
+  //     project-scoped now instead of global.
+  //   - User runs `update` in project A, then in project B — same
+  //     vendor and scope, but `<cwd>/.claude/skills/` resolves to a
+  //     different directory in B than in A.
+  //
+  // Without this check, any of those cases produces 304 → no writes
+  // → all-MISS output in `list`. The fix is a placement-presence
+  // check: for every (skill, target) pair the current sync would
+  // touch, the skill's directory MUST already exist under the
+  // target's root. If ANY is missing, drop `If-None-Match` so the
+  // server returns the full library and we populate the empty
+  // placement.
+  //
+  // Performance: N targets × M skills `existsSync` calls. For a 14-
+  // skill library with 2 targets, that's 28 stat calls — well under
+  // a millisecond. The conditional-fetch wire savings on a clean
+  // repeat sync still applies; this is the safety guard above it.
+  // BOTH the ETag short-circuit AND the `since` delta-query optimization
+  // depend on the same trust invariant: "the local placement set has
+  // every skill we expect." If a placement is missing, dropping ONLY
+  // `If-None-Match` is insufficient — the server filters `result.skills`
+  // by `updatedAt > since`, so a server response that we trigger by
+  // dropping the ETag will STILL omit any skill whose content hasn't
+  // changed on the server since the last sync. The missing placement
+  // would never be repopulated, producing a permanent ETag-miss loop
+  // that the user can only escape by `rm ~/.claude/skillrepo/.last-sync`.
+  //
+  // Verified against the production server at
+  // src/lib/queries/library.ts (`gt(skills.updatedAt, since)`): `since`
+  // alone is enough to filter unchanged skills out of the response.
+  //
+  // Fix: gate BOTH headers on the same `placementsAreComplete` check.
+  // When placements are incomplete, drop both — server returns the
+  // full library, runSync writes every skill to every detected
+  // vendor's placement, recovery is complete in one round.
+  const placementsComplete =
+    lastSync?.etag &&
+    placementsAreComplete(lastSync.skills, vendors, global);
+  if (placementsComplete) {
+    opts.ifNoneMatch = lastSync.etag;
+  }
+  if (lastSync?.syncedAt && placementsComplete) {
+    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
@@ -427,7 +671,13 @@ export async function runSync(options) {
     }
   }
 
-  // Step 7: persist new ETag + skills map (only if the response was complete)
+  // Step 7: persist new ETag + skills map (only if the response was
+  // complete). The placement-presence check in `placementsAreComplete`
+  // (called above before the conditional request) handles the safety
+  // gate for the ETag short-circuit — no need to persist a separate
+  // vendor-set field; the on-disk placements themselves are the
+  // source of truth for "did the local placement set change in a way
+  // that would invalidate 304?"
   if (!anyIncomplete && result.etag) {
     try {
       writeLastSync({