skillrepo 4.17.2 → 4.18.1

package/src/lib/mergers/gitignore.mjs

@@ -14,8 +14,13 @@
  * entries through the same core, so every CLI-authored gitignore line
  * lives in the one marked section the uninstall remover strips (#2361).
  *
- * Idempotent: entries already present are skipped; a legacy sync-time
- * section is healed into the marked section as a side effect.
+ * Idempotent: entries already present are skipped, and so are the two
+ * skill-root entries when an ignore rule git honours already covers them
+ * (`git check-ignore`, #2903). The always-added entries never take that
+ * shortcut — `.env.local` holds a live key, and its line in the TRACKED
+ * .gitignore is what protects every clone (see `isCoverageProbed` in
+ * `../gitignore-section.mjs`). A legacy sync-time section is healed into
+ * the marked section as a side effect.
  */
 
 import { placementTargetsFor } from "../file-write.mjs";
@@ -64,11 +69,13 @@ function entriesFor(options) {
 }
 
 /**
- * Ensure the init-required paths are in .gitignore. Creates the file
- * if it doesn't exist. Idempotent — returns `"skipped"` if every
- * required entry is already present and no legacy section needed
- * healing, `"created"` if the file didn't exist, `"updated"` if it did
- * and at least one entry was missing (or a legacy section was healed).
+ * Ensure the init-required paths are gitignored. Creates the file if it
+ * doesn't exist and something needs writing. Idempotent — returns
+ * `"skipped"` if every required entry is already present (or, for the
+ * skill roots only, covered by an existing ignore rule) and no legacy
+ * section needed healing, `"created"` if the file didn't exist,
+ * `"updated"` if it did and at least one entry was missing (or a legacy
+ * section was healed).
  *
  * @param {{ vendors?: string[], global?: boolean }} [options]
  * @returns {{ path: string; action: "created" | "updated" | "skipped"; added: string[] }}

package/src/lib/paths.mjs

@@ -81,6 +81,18 @@ export const globalGovernanceSeenPath = () =>
 export const globalRepoStateDir = () =>
   join(homedir(), ".claude", "skillrepo", "repos");
 
+/**
+ * Quarantine area for the full-sync reconcile (#2804). When a recalled /
+ * removed skill's on-disk dir was written by the CLI but has since been
+ * locally EDITED, compliance requires it leave the loadable placement
+ * dirs, but the user's edits must not be destroyed — so the dir is moved
+ * here instead of deleted. NO vendor scans `~/.claude/skillrepo/`, so a
+ * quarantined skill is never loaded by an agent. Same parent dir as
+ * `.last-sync`, so `rm -rf ~/.claude/skillrepo/` still removes it.
+ */
+export const globalQuarantineDir = () =>
+  join(homedir(), ".claude", "skillrepo", "quarantine");
+
 // ── Skill placement targets ────────────────────────────────────────────
 //
 // Per-vendor placement decisions live in `agent-registry.mjs`. This

package/src/lib/sync.mjs

@@ -77,7 +77,15 @@
  * @typedef {Object} SyncSummary
  * @property {number} added       - Skills newly written that were not on disk
  * @property {number} updated     - Skills overwritten on disk
- * @property {number} removed     - Tombstones applied
+ * @property {number} removed     - Skills removed from the loadable set,
+ *                                  counted PER SKILL: delta tombstones plus
+ *                                  the full-sync orphan reconcile (#2804). A
+ *                                  quarantine counts here too (it left the
+ *                                  loadable set).
+ * @property {number} [quarantined] - Subset of `removed` MOVED to quarantine
+ *                                  (an edited copy of a removed skill)
+ *                                  rather than deleted, so the summary can
+ *                                  show edits were preserved (#2804)
  * @property {boolean} notModified - True if 304 short-circuit fired
  * @property {boolean} [throttled] - True when the SessionStart staleness
  *                                   throttle skipped this run entirely — no
@@ -221,8 +229,11 @@ import { getCliVersion } from "./cli-version.mjs";
 import {
   writeSkillDir,
   removeSkillDir,
+  removeManagedDir,
+  quarantineSkillDir,
   cleanupOrphans,
   placementTargetsFor,
+  placementTargetsForScopeLenient,
   resolvePlacementDir,
   describePlacementTarget,
   escapeControlChars,
@@ -1152,6 +1163,19 @@ async function runWholeLibrarySync({
     opts.since = lastSync.syncedAt;
   }
 
+  // #2804: the ACTUAL full-fetch wire decision. The server returns the
+  // complete authoritative set (no `since` delta filter) exactly when
+  // `opts.since` is absent — so absence from `result.skills` on such a
+  // response means the skill has genuinely left the library and must be
+  // reconciled off disk. This is deliberately NOT `summary.fullSync` below
+  // (= "no prior state existed"): a forced full re-fetch from incomplete
+  // placements or the #1911 upgrade heal still reports `fullSync:false`, yet
+  // its response IS a complete set that must be reconciled. Keying the orphan
+  // reconcile off `since`-absence is load-bearing — key it off `fullSync` and
+  // the routine forced-full-fetch cases (new vendor, CLI upgrade) never clean
+  // up a recalled skill.
+  const fullFetch = opts.since === undefined;
+
   // Track whether this is a full or delta sync BEFORE the network
   // call, for the returned summary's `fullSync` field. The documented
   // semantic is "no PRIOR last-sync state existed" — NOT "no `since` was
@@ -1262,6 +1286,10 @@ async function runWholeLibrarySync({
     added: 0,
     updated: 0,
     removed: 0,
+    // Subset of `removed` that was MOVED to quarantine (an edited copy of a
+    // removed skill) rather than deleted (#2804). Surfaced so the summary
+    // can tell the user their edits were preserved, not destroyed.
+    quarantined: 0,
     // Skills the server sent that could not be written locally (e.g. a
     // stored path that fails client-side validation). Counted rather than
     // fatal — see the quarantine-and-continue block in the apply loop.
@@ -1298,6 +1326,43 @@ async function runWholeLibrarySync({
     // machine A, this is machine B) is not an error.
   }
 
+  // #2804: full-sync orphan reconcile (also closes #2532's full-sync case).
+  // On a full fetch the server sends the complete served set with
+  // removals:[] (route.ts:624), so a skill that has LEFT the library —
+  // recalled to absence with no fallback (#2367), owner-deleted (#2532),
+  // membership-removed, pin-rolled-back — is in NEITHER skills[] NOR
+  // removals[], and the tombstone loop above never touches it. Treat the
+  // full response's skills[] as authoritative and reconcile every prior
+  // baseline entry absent from it off disk, guarded by the recorded write
+  // baseline: unmodified → deleted; CLI-written-then-EDITED → quarantined
+  // (not destroyed); never-written → never visited (the reconcile iterates
+  // the CLI's own `.last-sync` baseline). DELTA fetches carry a PARTIAL
+  // skills[] and MUST NEVER be reconciled by absence — hence the fullFetch
+  // gate (see the `fullFetch` derivation above).
+  /** @type {string[]} */
+  let reconciledKeys = [];
+  if (fullFetch) {
+    const servedKeys = new Set(
+      result.skills.map((skill) => `${skill.owner}/${skill.name}`),
+    );
+    const servedNames = new Set(result.skills.map((skill) => skill.name));
+    const reconcile = reconcileWholeLibraryOrphans({
+      baselineSkills: lastSync?.skills,
+      servedKeys,
+      servedNames,
+      vendors,
+      global,
+      stderr,
+    });
+    // A quarantine counts toward `removed` too (it left the loadable set,
+    // so a quarantine-only reconcile can't leave added+updated+removed at 0
+    // and go silent on the hook — the #2413 lesson) AND toward `quarantined`
+    // so the move stays distinguishable from a delete in the summary.
+    summary.removed += reconcile.removed;
+    summary.quarantined += reconcile.quarantined;
+    reconciledKeys = reconcile.reconciledKeys;
+  }
+
   // Apply skills. We don't have on-disk SHAs to compute "unchanged"
   // efficiently — `unchanged` stays 0 unless a future enhancement
   // adds disk-side hashing. For the user-facing summary, "added" vs
@@ -1353,6 +1418,13 @@ async function runWholeLibrarySync({
     const key = `${tombstone.owner}/${tombstone.name}`;
     delete skillsMap[key];
   }
+  // Drop reconciled orphans (#2804) from the persisted map too, so
+  // `.last-sync` stops listing a skill we just removed from disk — mirrors
+  // the tombstone purge above. Absent from the map, it is not carried
+  // forward and `list` will not report it as a phantom managed skill.
+  for (const key of reconciledKeys) {
+    delete skillsMap[key];
+  }
 
   // Placement configuration is validated ONCE, before any skill is
   // written. `placementTargetsFor` depends only on `vendors` and
@@ -1854,6 +1926,8 @@ async function runSkillsetScopedSync({
     added: 0,
     updated: 0,
     removed: 0,
+    // Subset of `removed` moved to quarantine rather than deleted (#2804).
+    quarantined: 0,
     skipped: 0,
     notModified: false,
     // Scoped syncs have no delta mode; `fullSync` keeps its documented
@@ -1866,6 +1940,7 @@ async function runSkillsetScopedSync({
   const servedKeys = new Set(
     result.skills.map((skill) => `${skill.owner}/${skill.name}`),
   );
+  const servedNames = new Set(result.skills.map((skill) => skill.name));
   const priorResolved = prior?.resolved ?? [];
 
   // Composed-state guard evidence (#2365 prod-readiness HIGH finding;
@@ -1898,18 +1973,24 @@ async function runSkillsetScopedSync({
   for (const entry of priorResolved) {
     const key = `${entry.owner}/${entry.name}`;
     if (servedKeys.has(key)) continue;
-    if (
-      reconcileDeleteGuarded({
-        entry,
-        targets,
-        rootDir,
-        vendors,
-        stderr,
-        bulkBaselines,
-      })
-    ) {
-      summary.removed++;
-    }
+    // Re-attribution guard (mirrors reconcileWholeLibraryOrphans): a member
+    // whose bare NAME is still served — under a DIFFERENT owner — was
+    // re-keyed, not removed (a skillset response's owner is the live
+    // `attributionSlug`, which a claim/rename changes while membership is
+    // stable). Skip the reconcile so an edited member isn't spuriously
+    // quarantined moments before the apply loop rewrites it under the new
+    // key; the per-repo manifest is rebuilt from the served set below, so
+    // the stale entry drops on its own.
+    if (servedNames.has(entry.name)) continue;
+    const outcome = reconcileDeleteGuarded({
+      entry,
+      targets,
+      rootDir,
+      stderr,
+      bulkBaselines,
+    });
+    if (outcome.changed) summary.removed++;
+    if (outcome.quarantined) summary.quarantined++;
   }
 
   // Full-set apply with the #2108-class serve guard: a placement dir
@@ -1922,6 +2003,17 @@ async function runSkillsetScopedSync({
   const priorByKey = new Map(
     priorResolved.map((entry) => [`${entry.owner}/${entry.name}`, entry]),
   );
+  // Name-keyed fallback for the re-attribution case (#2804 review): after a
+  // claim/rename the served owner changes but the placement dir (name-keyed)
+  // and the per-repo baseline (recorded under the OLD owner key) do not — so
+  // the owner-keyed lookup misses, and for a skillset-only repo `.last-sync`
+  // has no entry either, which would make `decideScopedWrite` mislabel a
+  // CLI-authored-then-edited member as "unmanaged" instead of "modified"
+  // (a materially different, wrong compliance signal). Names are unique
+  // within a repo's manifest, so this never collides.
+  const priorByName = new Map(
+    priorResolved.map((entry) => [entry.name, entry]),
+  );
 
   for (const skill of result.skills) {
     const version = typeof skill.version === "string" ? skill.version : "";
@@ -1944,7 +2036,9 @@ async function runSkillsetScopedSync({
       skill,
       targets,
       rootDir,
-      priorEntry: priorByKey.get(`${skill.owner}/${skill.name}`),
+      priorEntry:
+        priorByKey.get(`${skill.owner}/${skill.name}`) ??
+        priorByName.get(skill.name),
       bulkBaselines,
     });
 
@@ -2277,46 +2371,191 @@ function decideScopedWrite({ skill, targets, rootDir, priorEntry, bulkBaselines
 }
 
 /**
- * Guarded reconcile-delete for one manifest entry absent from the
- * served set. All-or-nothing across targets, same rationale as the
- * write guard: delete ONLY when every existing placement's content
- * still matches a recorded write baseline — the per-repo manifest's
- * OR the machine-global `.last-sync` map's (#2365 prod-readiness
- * HIGH, same composed-state shape as `decideScopedWrite`: a bulk sync
- * during an undeclared interval rewrites the dir and moves the only
- * valid baseline into `.last-sync`; a per-repo-only check would then
- * refuse a legitimate reconcile-delete forever). Entries matching
- * NEITHER store (hand-authored, or genuinely user-modified) are never
- * deleted — the #2108 invariant. Returns true when at least one dir
- * was removed.
+ * Full-sync orphan reconcile for the whole-library path (#2804; also
+ * closes #2532's full-sync case). Given the authoritative served-key set
+ * from a FULL response, every prior `.last-sync` baseline entry ABSENT
+ * from it has left the library and is reconciled off disk, guarded by the
+ * per-entry write baseline the CLI itself recorded:
+ *
+ *   • disk matches the entry's baseline SHAs (exactly what the CLI wrote)
+ *     → deleted;
+ *   • disk diverged (the CLI wrote it — it IS in `.last-sync` — and the
+ *     user has since edited or replaced it) → moved to quarantine, not
+ *     destroyed (compliance: it leaves the loadable folder; safety: the
+ *     content survives outside every vendor's scan path);
+ *   • a name the CLI never wrote is never visited — this iterates the
+ *     CLI's OWN baseline, so hand-authored dirs (no `.last-sync` entry)
+ *     are structurally out of scope; no separate foreign guard is needed,
+ *     unlike the skillset path whose per-repo/bulk stores can disagree.
+ *
+ * Deletions and quarantines are counted PER SKILL (once each, never once
+ * per placement target — the tombstone and skillset-reconcile paths count
+ * the same way); a quarantine also counts as `removed` (it left the
+ * loadable set, so the SessionStart hook is never silent) and additionally
+ * as `quarantined` so the move stays legible even when the per-skill
+ * warning goes to a black-holed hook stderr. A skill still served under a
+ * DIFFERENT owner (a re-attributed Skillbot claim) is NOT a removal and is
+ * skipped. The state KEY is dropped only when the skill is no longer on
+ * disk in EITHER scope: `.last-sync` is machine-global and does not record
+ * which scope wrote a skill, so purging a `--global`-placed skill's key
+ * during a project sync (which cleans only project dirs) would strand its
+ * global dir loadable forever. The caller runs this ONLY when `opts.since`
+ * was absent (a genuine full fetch); a delta response's `skills[]` is
+ * partial and absence there is not removal.
+ *
+ * @param {object} args
+ * @param {Record<string, SyncedSkillEntry> | undefined} args.baselineSkills
+ *        Prior `.last-sync` skills map (`owner/name` → entry with SHAs).
+ * @param {Set<string>} args.servedKeys  `owner/name` keys in the full response.
+ * @param {Set<string>} args.servedNames  Bare skill names in the full response.
+ *        A library has one owner per name, so a served name means the same
+ *        skill (used to skip a re-attributed skill rather than remove it).
+ * @param {string[]} [args.vendors]
+ * @param {boolean} [args.global]
+ * @param {NodeJS.WritableStream} args.stderr
+ * @returns {{ removed: number, quarantined: number, reconciledKeys: string[] }}
+ */
+function reconcileWholeLibraryOrphans({
+  baselineSkills,
+  servedKeys,
+  servedNames,
+  vendors,
+  global,
+  stderr,
+}) {
+  /** @type {string[]} */
+  const reconciledKeys = [];
+  let removed = 0;
+  let quarantined = 0;
+  if (!baselineSkills || typeof baselineSkills !== "object") {
+    return { removed, quarantined, reconciledKeys };
+  }
+
+  // Clean only the CURRENT sync's scope; the other scope is PROBED
+  // read-only for the key-purge guard below (never cleaned — `.last-sync`
+  // doesn't record which scope wrote a skill, so cleaning the other scope
+  // could move hand-authored content the CLI never wrote there). The probe
+  // is lenient so a vendor with no global scope contributes no target
+  // instead of throwing.
+  const currentTargets = placementTargetsFor({ vendors, global: global === true });
+  const otherTargets = placementTargetsForScopeLenient(vendors, global !== true);
+
+  for (const [key, entry] of Object.entries(baselineSkills)) {
+    if (!entry || typeof entry !== "object") continue;
+    if (servedKeys.has(key)) continue; // still served — keep
+
+    // `.last-sync` is local data, not trusted input: never resolve an
+    // invalid name into a path (a traversal shape must never reach `join`).
+    const slashAt = key.indexOf("/");
+    const name = slashAt >= 0 ? key.slice(slashAt + 1) : key;
+    if (!isValidSkillName(name)) continue;
+
+    // Re-attribution guard: a skill whose NAME is still served — under a
+    // different owner — was re-keyed, not removed (e.g. a Skillbot skill
+    // `skillrepo/foo` claimed to `alice/foo` changes the owner slug but not
+    // the name-keyed placement dir). The server enforces one owner per name
+    // within a library, so a served name is the same skill: leave its dir
+    // for the apply loop to rewrite under the new key, and just drop the
+    // stale old key so state doesn't carry a phantom.
+    if (servedNames.has(name)) {
+      reconciledKeys.push(key);
+      continue;
+    }
+
+    let leftLoadable = false;
+    let wasQuarantined = false;
+    for (const target of currentTargets) {
+      const dir = resolvePlacementDir(target, name);
+      if (!existsSync(dir)) continue;
+      const diskShas = computeShasFromDir(dir);
+      if (
+        shasMatch(diskShas, {
+          skillMdSha256: entry.skillMdSha256,
+          filesSha256: entry.filesSha256,
+        })
+      ) {
+        // Exactly what the CLI wrote — delete outright.
+        if (removeManagedDir(dir)) leftLoadable = true;
+      } else {
+        // The CLI wrote this name (it is in our baseline) but the content
+        // diverged: a local edit or a same-named replacement. Compliance
+        // requires it leave the loadable folder; quarantine preserves it.
+        const dest = quarantineSkillDir(dir, { skillName: name });
+        leftLoadable = true;
+        wasQuarantined = true;
+        const displayPath = `${describePlacementTarget(target)}${escapeControlChars(name)}`;
+        stderr.write(
+          `  warning: ${displayPath}/ is no longer in your library but has local edits — ` +
+            `moved to quarantine (${dest}) instead of deleted, so it stops loading in your agents ` +
+            `while your changes are preserved. Recover them from that folder if needed.\n`,
+        );
+      }
+    }
+    // Count ONCE per skill (not once per target).
+    if (leftLoadable) removed++;
+    if (wasQuarantined) quarantined++;
+
+    // Drop the state key only when the skill is no longer on disk in the
+    // OTHER scope either — otherwise a `--global`-placed skill reconciled
+    // during a project sync (its dir in `otherTargets`, which this pass
+    // does not clean) would be stranded loadable forever once its key is
+    // gone. Leaving the key lets the next same-scope sync reconcile it. A
+    // true phantom (no dir in either scope) still drops.
+    const stillInOtherScope = otherTargets.some((target) =>
+      existsSync(resolvePlacementDir(target, name)),
+    );
+    if (!stillInOtherScope) reconciledKeys.push(key);
+  }
+
+  return { removed, quarantined, reconciledKeys };
+}
+
+/**
+ * Guarded reconcile for one manifest entry absent from the served set —
+ * the skillset-scoped counterpart to `reconcileWholeLibraryOrphans`.
+ * Classifies each existing placement dir against the recorded write
+ * baseline (the per-repo manifest's OR the machine-global `.last-sync`
+ * map's — #2365 composed-state, same shape as `decideScopedWrite`):
+ *
+ *   • matches a baseline (exactly what the CLI wrote) → deleted;
+ *   • diverged AND the PER-REPO manifest recorded writing this repo's dir
+ *     (positive proof the CLI wrote it here, and the user then edited it)
+ *     → moved to quarantine, not destroyed (#2804 compliance: a removed
+ *     skill must leave the loadable folder; the edits are preserved);
+ *   • diverged with only a BULK `.last-sync` baseline (proves the CLI
+ *     wrote SOME placement — possibly the global one — not necessarily
+ *     this repo's dir) OR no baseline at all (hand-authored) → kept
+ *     untouched with a warning. This is the surviving half of the #2108
+ *     invariant: the owner's remove-and-quarantine decision covers a
+ *     CLI-authored-then-edited skill, NEVER content whose authorship of
+ *     THIS repo's dir the CLI cannot prove.
+ *
+ * Returns `{changed, quarantined}`: `changed` is true when at least one
+ * dir was removed or quarantined (the caller's per-skill `removed`
+ * increment); `quarantined` is true when any was MOVED to quarantine
+ * rather than deleted (a subset of `changed`, surfaced for the summary).
  *
  * @param {object} args
  * @param {import("./repo-sync-state.mjs").RepoResolvedEntry} args.entry
  * @param {string[]} args.targets
  * @param {string} args.rootDir
- * @param {string[]} [args.vendors]
  * @param {NodeJS.WritableStream} args.stderr
  * @param {Map<string, {skillMdSha256: string, filesSha256: string}>} args.bulkBaselines
  *        Name-keyed `.last-sync` write baselines, read once per sync.
- * @returns {boolean}
+ * @returns {{ changed: boolean, quarantined: boolean }}
  */
-function reconcileDeleteGuarded({ entry, targets, rootDir, vendors, stderr, bulkBaselines }) {
+function reconcileDeleteGuarded({ entry, targets, rootDir, stderr, bulkBaselines }) {
   // A state file is local data, not a trusted input: an entry whose
   // name fails spec validation is never resolved into a path (the
   // join would otherwise honor traversal shapes like "../x").
-  if (!isValidSkillName(entry.name)) return false;
+  if (!isValidSkillName(entry.name)) return { changed: false, quarantined: false };
 
   const hasPerRepoBaseline =
     typeof entry.skillMdSha256 === "string" &&
     typeof entry.filesSha256 === "string";
   const bulkEntry = bulkBaselines.get(entry.name);
 
-  const existing = targets.filter((target) =>
-    existsSync(resolvePlacementDir(target, entry.name, rootDir)),
-  );
-  if (existing.length === 0) return false; // nothing on disk — just drops from state
-
-  const mismatched = existing.filter((target) => {
+  const matchesBaseline = (target) => {
     const diskShas = computeShasFromDir(
       resolvePlacementDir(target, entry.name, rootDir),
     );
@@ -2327,34 +2566,57 @@ function reconcileDeleteGuarded({ entry, targets, rootDir, vendors, stderr, bulk
         filesSha256: entry.filesSha256,
       })
     ) {
-      return false;
+      return true;
     }
-    return !(bulkEntry && shasMatch(diskShas, bulkEntry));
-  });
+    return !!(bulkEntry && shasMatch(diskShas, bulkEntry));
+  };
 
-  if (mismatched.length > 0) {
-    const hadAnyBaseline = hasPerRepoBaseline || !!bulkEntry;
-    for (const target of mismatched) {
-      const displayPath = `${describePlacementTarget(target)}${escapeControlChars(entry.name)}`;
+  const existing = targets.filter((target) =>
+    existsSync(resolvePlacementDir(target, entry.name, rootDir)),
+  );
+  if (existing.length === 0) return { changed: false, quarantined: false }; // nothing on disk — just drops from state
+
+  const classified = existing.map((target) => ({
+    target,
+    match: matchesBaseline(target),
+  }));
+
+  let changed = false;
+  let quarantined = false;
+  for (const { target, match } of classified) {
+    const dir = resolvePlacementDir(target, entry.name, rootDir);
+    const displayPath = `${describePlacementTarget(target)}${escapeControlChars(entry.name)}`;
+    if (match) {
+      // Exactly what the CLI wrote — safe to delete outright.
+      if (removeManagedDir(dir)) changed = true;
+    } else if (hasPerRepoBaseline) {
+      // The per-repo manifest proves the CLI wrote THIS repo's placement
+      // and it has since been edited: quarantine (compliance + no data
+      // loss). A bulk-only baseline is deliberately NOT sufficient here —
+      // it proves the CLI wrote SOME placement, not this repo's dir, so a
+      // divergence could be hand-authored project content.
+      const dest = quarantineSkillDir(dir, { skillName: entry.name });
+      changed = true;
+      quarantined = true;
       stderr.write(
-        hadAnyBaseline
-          ? `  warning: ${displayPath}/ was removed from this repo's skillset but has local changes, ` +
-              `so it was not deleted. Push it to your library with 'skillrepo push ${displayPath}', ` +
-              `or remove the directory yourself.\n`
-          : `  warning: ${displayPath}/ was removed from this repo's skillset but was not written ` +
-              `by this CLI, so it was not deleted. Push it to your library with ` +
-              `'skillrepo push ${displayPath}', or remove the directory yourself.\n`,
+        `  warning: ${displayPath}/ was removed from this repo's skillset but has local edits — ` +
+          `moved to quarantine (${dest}) instead of deleted, so it stops loading in your agents ` +
+          `while your changes are preserved. Recover them from that folder if needed.\n`,
+      );
+    } else {
+      // Diverged with no per-repo authorship proof — either genuinely
+      // hand-authored (no baseline anywhere) or the #2365 composed-state
+      // where only a bulk `.last-sync` baseline exists, which proves the CLI
+      // wrote SOME placement but not THIS repo's dir. Same safe action
+      // either way: never move content the CLI cannot prove it wrote here.
+      stderr.write(
+        `  warning: ${displayPath}/ was removed from this repo's skillset but was not written ` +
+          `by this CLI, so it was not deleted. Push it to your library with ` +
+          `'skillrepo push ${displayPath}', or remove the directory yourself.\n`,
       );
     }
-    return false;
   }
-
-  const removeResult = removeSkillDir(entry.name, {
-    vendors,
-    global: false,
-    baseDir: rootDir,
-  });
-  return removeResult.removed.length > 0;
+  return { changed, quarantined };
 }
 
 /**

package/src/test/commands/update.test.mjs

@@ -126,9 +126,12 @@ describe("runUpdate — summary printer (removed line)", () => {
   it("prints the removed line in the human summary when a tombstone deletes a skill", async () => {
     // printSummary only emits `− N removed` when `s.removed > 0`. Every
     // other human-mode test produces added/updated-only summaries, so the
-    // `if (s.removed > 0)` true branch was never taken. Sync a skill,
-    // then re-sync with it tombstoned so `removed` is non-zero and the
-    // line is rendered.
+    // `if (s.removed > 0)` true branch was never taken. Sync a skill (with
+    // an etag baseline so the next sync is a genuine DELTA), then re-sync
+    // with it tombstoned so `removed` is non-zero and the line renders.
+    // (A tombstone only rides a DELTA — a full sync carries removals:[],
+    // #2804 — so the etag is load-bearing here.)
+    server.setEtag('"v1"');
     server.setLibraryResponse({
       skills: [makeSkill("doomed")],
       removals: [],
@@ -139,6 +142,7 @@ describe("runUpdate — summary printer (removed line)", () => {
 
     stdout.clear();
     server.resetLibraryInspection?.();
+    server.setEtag('"v2"');
     server.setLibraryResponse({
       skills: [],
       removals: [{ owner: "alice", name: "doomed", removedAt: "x" }],
@@ -154,6 +158,36 @@ describe("runUpdate — summary printer (removed line)", () => {
       "the tombstoned skill is gone from disk",
     );
   });
+
+  it("surfaces the quarantine in the summary when an EDITED removed skill is moved (#2804)", async () => {
+    // Sync a skill, edit it locally, then recall it on a full fetch so the
+    // reconcile QUARANTINES rather than deletes. The summary must say so —
+    // otherwise the user thinks their edits were deleted.
+    server.setEtag('"v1"');
+    server.setLibraryResponse({ skills: [makeSkill("edited")], removals: [], syncedAt: "x" });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl, "--agent", "claude"], { stdout });
+    const dir = resolvePlacementDir("claudeProject", "edited");
+    writeFileSync(join(dir, "SKILL.md"), "---\nname: edited\n---\nlocally changed\n");
+
+    // Force a full fetch (pre-floor cliVersion) that recalls the skill.
+    const prior = readLastSync();
+    writeLastSync({
+      etag: prior.etag,
+      syncedAt: prior.syncedAt,
+      skills: prior.skills,
+      cliVersion: "4.7.0",
+    });
+    server.setEtag('"v2"');
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "y" });
+
+    stdout.clear();
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl, "--agent", "claude"], { stdout });
+
+    const out = stdout.text();
+    assert.match(out, /−\s*1 removed/, "still counts as removed (left the loadable set)");
+    assert.match(out, /quarantine/, "and tells the user it was MOVED, not deleted");
+    assert.ok(!existsSync(dir), "the loadable copy is gone");
+  });
 });
 
 describe("runUpdate — credential resolution", () => {

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

@@ -689,6 +689,14 @@ export function createMockServer(initialPayload, options = {}) {
       const filteredResponse = {
         ...libraryResponse,
         skills: respondedSkills,
+        // Match production (src/app/api/v1/library/route.ts:624): a FULL
+        // library sync (no `since`) NEVER carries removals — a departed
+        // skill is expressed by ABSENCE from the complete `skills[]`, and
+        // the client reconciles it (#2804). Only delta syncs (with `since`)
+        // carry tombstones. The mock previously spread `removals` through
+        // unfiltered, so a "full-sync tombstone" test passed against a shape
+        // production never sends and the #2804 orphan gap had NO coverage.
+        removals: sinceParam ? (libraryResponse.removals ?? []) : [],
       };
 
       const headers = { "Content-Type": "application/json" };