skillrepo 4.17.2 → 4.18.1

package/README.md

@@ -166,11 +166,18 @@ skillrepo update [--global] [--agent <list>] [--json] [--silent]
 ```
 
 Pulls the latest state of your library from the server using a delta
-sync. Writes new and updated skills, removes skills that were removed
-from the library, and skips skills that are unchanged. In a repo that
-declares a skillset, `update` instead reconciles that declared set (a
-full-set resolve, not a delta). Uses ETag caching so repeat runs return
-`304 Not Modified` when nothing has changed.
+sync. Writes new and updated skills, removes skills that left your
+library, and skips skills that are unchanged. Removals apply on both the
+delta sync and the periodic full re-sync (the one that runs on a first
+sync, after a CLI upgrade, or when a new editor is detected), so a skill
+your team recalled or deleted stops loading everywhere rather than
+lingering on disk. If you had edited a removed skill locally, its folder
+isn't discarded — it is moved to a quarantine area
+(`~/.claude/skillrepo/quarantine/`) with a warning, so it leaves the
+folders your agents load while your changes are preserved. In a repo
+that declares a skillset, `update` instead reconciles that declared set
+(a full-set resolve, not a delta). Uses ETag caching so repeat runs
+return `304 Not Modified` when nothing has changed.
 
 `--silent` suppresses normal output and writes a single `{}` line to
 stdout on success. Designed for SessionStart hooks that pipe stdout
@@ -221,9 +228,12 @@ receives its declared skillset. Skillset-scoped sync resolves the
 complete set on every pass: skills added to the skillset appear,
 skills removed from it are deleted from the repo's skill folders, and
 everything lands at the repository root no matter which subdirectory
-you run from. Deletes are guarded — a directory the CLI did not write,
-or one you modified locally, is never removed or overwritten; it stays
-put with a warning and shows up in your team's sync reporting instead.
+you run from. Deletes are guarded — a directory the CLI did not write is
+never removed or overwritten; it stays put with a warning and shows up
+in your team's sync reporting instead. A skill the CLI wrote that you
+then edited is moved to the quarantine area
+(`~/.claude/skillrepo/quarantine/`) rather than deleted when it leaves
+the set, so it stops loading while your edits are preserved.
 Declared entries in `extra` that cannot be honored (for example when
 extras are not enabled for your organization) are skipped loudly with
 the reason, never silently. If the registry is unreachable, the repo
@@ -652,9 +662,11 @@ Skills land at one of two project paths, depending on the agent:
 | Cursor / Windsurf / Gemini CLI / Codex CLI / Cline / GitHub Copilot | `.agents/skills/<name>/` | `~/.agents/skills/<name>/` |
 | Windsurf (personal-scope override) | — | `~/.codeium/windsurf/skills/<name>/` |
 
-The CLI keeps `.claude/skills/` and `.agents/skills/` listed in the
-SkillRepo section of your project `.gitignore`, re-checked on every
-sync — skills are a per-developer cache, not committed content. The `--agent` flag overrides detection (e.g.
+The CLI keeps `.claude/skills/` and `.agents/skills/` gitignored,
+re-checked on every sync: an entry is added to the SkillRepo section of
+your project `.gitignore` only when no existing rule already ignores
+that path (a repo that ignores `.claude/` gets no `.claude/skills/`
+line) — skills are a per-developer cache, not committed content. The `--agent` flag overrides detection (e.g.
 `--agent claude,agents` writes both paths). See
 [`docs/vendor-paths.md`](docs/vendor-paths.md) for primary-source
 citations on each agent's read paths.

package/package.json

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

package/src/commands/init.mjs

@@ -443,7 +443,8 @@ export async function runInit(argv, io = {}, deps = {}) {
         `.gitignore updated (added: ${gitignoreResult.added.join(", ")})`,
       );
     }
-    // "skipped" → all entries already present, no output needed
+    // "skipped" → every entry already present (or, for the skill roots,
+    // already ignored by an existing rule — #2903), no output needed
   } catch (err) {
     p.warning(
       `Could not update .gitignore: ${err?.message ?? String(err)}. ` +
@@ -1077,7 +1078,7 @@ async function runDetectionPicker({ yes, json, stdout, detections }) {
         "    .agents/skills/   (for Cursor, Windsurf, Gemini CLI, Codex CLI, " +
         "Cline, Copilot, and others)\n" +
         "\n" +
-        "  Both paths are added to .gitignore — skills are a per-developer " +
+        "  Both paths are gitignored — skills are a per-developer " +
         "cache, not committed.\n\n",
     );
   }

package/src/commands/update.mjs

@@ -172,6 +172,11 @@ export async function runUpdate(argv, io = {}) {
       // gates output ignores skips, a quarantined skill produces no output
       // anywhere and exits 0 (#2413 adversarial review).
       const skipped = summary.skipped ?? 0;
+      // Quarantines (#2804) are a subset of `removed`, so they're already in
+      // `total`; surfaced separately below so this black-holed hook vector —
+      // where the per-skill quarantine warning is lost — still tells the
+      // user a removed skill they'd EDITED was moved (not deleted) and where.
+      const quarantined = summary.quarantined ?? 0;
       const total =
         summary.added + summary.updated + summary.removed + skipped;
       const subject = syncSubject(summary);
@@ -236,6 +241,9 @@ export async function runUpdate(argv, io = {}) {
       }
       stdout.write(
         `[SkillRepo] ${subject} synced: ${summary.added} added, ${summary.updated} updated, ${summary.removed} removed` +
+          (quarantined > 0
+            ? ` (${quarantined} edited, moved to ~/.claude/skillrepo/quarantine/)`
+            : "") +
           (skipped > 0 ? `, ${skipped} SKIPPED (could not be written)` : "") +
           `.\n`,
       );
@@ -366,6 +374,11 @@ function printSummary(s, out) {
   if (s.added > 0)   out.write(`    + ${s.added} added\n`);
   if (s.updated > 0) out.write(`    ↻ ${s.updated} updated\n`);
   if (s.removed > 0) out.write(`    − ${s.removed} removed\n`);
+  const quarantined = s.quarantined ?? 0;
+  if (quarantined > 0)
+    out.write(
+      `      (${quarantined} of those were edited — moved to ~/.claude/skillrepo/quarantine/, your changes preserved)\n`,
+    );
   if (skipped > 0)   out.write(`    ! ${skipped} skipped (see warnings above)\n`);
   out.write("\n");
 }

package/src/lib/file-write.mjs

@@ -51,9 +51,11 @@ import {
   writeFileSync,
   renameSync,
   rmSync,
+  cpSync,
   readdirSync,
   statSync,
 } from "node:fs";
+import { randomBytes } from "node:crypto";
 import { dirname, join, isAbsolute, relative } from "node:path";
 
 import {
@@ -68,6 +70,7 @@ import {
   windsurfSkillsGlobal,
   windsurfSkillsGlobalRoot,
   gitignorePath,
+  globalQuarantineDir,
 } from "./paths.mjs";
 import { AGENT_REGISTRY, getAgentByKey } from "./agent-registry.mjs";
 import { ensureManagedRootIgnores } from "./gitignore-section.mjs";
@@ -372,6 +375,34 @@ export function placementTargetsFor({ vendors, global = false }) {
   return targets;
 }
 
+/**
+ * Placement targets for `vendors` in the given scope, SKIPPING any vendor
+ * that doesn't support it — unlike `placementTargetsFor`, which throws.
+ * For READ-ONLY probing where a partial answer is correct and an
+ * unsupported vendor should contribute nothing rather than fail the whole
+ * resolve: the full-sync reconcile (#2804) uses it to check whether a
+ * recalled skill still lives in the OTHER scope (`.last-sync` is
+ * machine-global and scope-agnostic) before dropping its state key, and a
+ * vendor with no global scope (e.g. VS Code + Copilot) simply has no
+ * global dir to probe. Never use this to decide WRITES/DELETES — those
+ * must use the strict `placementTargetsFor` so a misconfigured scope fails
+ * loudly.
+ *
+ * @param {string[]} vendors
+ * @param {boolean} global
+ * @returns {PlacementTarget[]}
+ */
+export function placementTargetsForScopeLenient(vendors, global) {
+  const targets = [];
+  for (const vendor of Array.isArray(vendors) ? vendors : []) {
+    const entry = getAgentByKey(vendor);
+    if (!entry) continue;
+    const target = global ? entry.globalTarget : entry.projectTarget;
+    if (target && !targets.includes(target)) targets.push(target);
+  }
+  return targets;
+}
+
 /**
  * Find the SKILL.md file inside a skill's files array and return its
  * frontmatter `name` value, or null if none could be parsed.
@@ -435,11 +466,13 @@ export function writeSkillDir(skill, options = {}) {
   const targets = placementTargetsFor(options);
 
   // Pre-flight: if any target writes to a project-scope managed root
-  // (.claude/skills/, .agents/skills/), ensure the root's blanket
-  // ignore is present in the CLI's marked .gitignore section before
-  // starting any writes (#2361 — heal on every sync, both roots; the
+  // (.claude/skills/, .agents/skills/), ensure the root is gitignored
+  // before starting any writes — the blanket entry lands in the CLI's
+  // marked .gitignore section only when no existing rule already covers
+  // the root (#2903: a repo ignoring `.claude/` gets no redundant
+  // `.claude/skills/` line). #2361 — heal on every sync, both roots; the
   // pre-4.10.0 code covered only .agents/skills/ under a separate
-  // header). A failure here is recoverable (user fixes their
+  // header. A failure here is recoverable (user fixes their
   // .gitignore and re-runs) because nothing has hit disk yet. A
   // failure here AFTER a successful write to an earlier target would
   // leave the user with a half-applied state and an error message
@@ -463,6 +496,68 @@ export function writeSkillDir(skill, options = {}) {
   return { written };
 }
 
+/**
+ * Run a filesystem mutation, retrying briefly on the transient lock
+ * errors Windows raises (EBUSY / EPERM / ENOTEMPTY) when another process
+ * — antivirus, an editor, a vendor agent mid-scan — holds a handle on a
+ * file inside the target dir. The op typically succeeds a few ms later
+ * once the handle is released; POSIX effectively never hits this. After
+ * the last delay the ORIGINAL error is rethrown, so a genuine permission
+ * failure still surfaces. `removeSkillDir` / `removeManagedDir` /
+ * `quarantineSkillDir` route their rm/rename/copy through here — a
+ * compliance delete (#2804) must not silently fail on a momentary lock.
+ * Delays are injectable so unit tests exercise the retry loop without
+ * real sleeps.
+ *
+ * @template T
+ * @param {() => T} op
+ * @param {number[]} [delaysMs]
+ * @returns {T}
+ */
+export function withFsRetry(op, delaysMs = [20, 50, 100, 200]) {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return op();
+    } catch (err) {
+      const transient =
+        !!err &&
+        (err.code === "EBUSY" ||
+          err.code === "EPERM" ||
+          err.code === "ENOTEMPTY");
+      if (!transient || attempt >= delaysMs.length) throw err;
+      const ms = delaysMs[attempt];
+      // Synchronous sleep: this whole pipeline is sync (rmSync/renameSync),
+      // so there is no event loop to yield to. Atomics.wait on a throwaway
+      // SharedArrayBuffer blocks the thread for `ms` without a busy spin.
+      if (ms > 0) {
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+      }
+    }
+  }
+}
+
+/**
+ * Recursively remove a single resolved placement directory, with the
+ * Windows-lock retry above. Returns true if the dir existed and was
+ * removed, false if it was already absent. Throws a typed disk error on
+ * a genuine failure. The per-directory primitive shared by
+ * `removeSkillDir` (all targets of a name) and the full-sync reconcile
+ * (#2804, one target at a time, alongside quarantine).
+ *
+ * @param {string} dir
+ * @returns {boolean}
+ */
+export function removeManagedDir(dir) {
+  if (!existsSync(dir)) return false;
+  try {
+    withFsRetry(() => rmSync(dir, { recursive: true, force: true }));
+  } catch (err) {
+    if (err instanceof CliError) throw err;
+    throw diskError(`Failed to remove ${dir}: ${err.message}`, { cause: err });
+  }
+  return true;
+}
+
 /**
  * Remove a skill directory from all configured placement targets.
  *
@@ -487,21 +582,71 @@ export function removeSkillDir(skillName, options = {}) {
 
   for (const target of targets) {
     const targetDir = resolvePlacementDir(target, skillName, options.baseDir);
-    if (!existsSync(targetDir)) {
-      notFound.push(targetDir);
-      continue;
-    }
-    try {
-      rmSync(targetDir, { recursive: true, force: true });
+    if (removeManagedDir(targetDir)) {
       removed.push(targetDir);
-    } catch (err) {
-      throw diskError(`Failed to remove ${targetDir}: ${err.message}`, { cause: err });
+    } else {
+      notFound.push(targetDir);
     }
   }
 
   return { removed, notFound };
 }
 
+/**
+ * Move a skill's loadable placement directory into the non-loaded
+ * quarantine area (`~/.claude/skillrepo/quarantine/`), preserving its
+ * contents, and return the destination path.
+ *
+ * The full-sync reconcile (#2804) calls this for a recalled / removed
+ * skill whose on-disk dir the CLI provably wrote (it is in the recorded
+ * write baseline) but which has since been locally EDITED. Deleting it
+ * would lose the user's edits; leaving it in place would keep the
+ * recalled skill loadable by agents — the exact compliance hole recall
+ * exists to close. Quarantine resolves both: the loadable copy goes away,
+ * the edited content survives outside every vendor's scan path. Unmodified
+ * recalled skills are deleted outright (`removeManagedDir`); a dir the CLI
+ * never wrote is never quarantined (the reconcile guards on the baseline).
+ *
+ * Destination names are uniquely stamped so quarantining the same skill
+ * from several placement targets in one sync never collides.
+ *
+ * @param {string} sourceDir  Absolute path of the loadable dir to move.
+ * @param {object} opts
+ * @param {string} opts.skillName  Spec-valid skill name (caller-validated).
+ * @returns {string} The quarantine destination path.
+ */
+export function quarantineSkillDir(sourceDir, { skillName } = {}) {
+  // Local state / server payloads are untrusted: never build a path from
+  // an invalid name (a traversal shape must never reach `join`).
+  if (!isValidSkillName(skillName)) {
+    throw validationError(`Invalid skill name: "${skillName}"`);
+  }
+
+  const root = globalQuarantineDir();
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const dest = join(root, `${skillName}-${stamp}-${randomBytes(4).toString("hex")}`);
+
+  try {
+    withFsRetry(() => mkdirSync(root, { recursive: true }));
+    // Copy-then-remove rather than rename. The quarantine root lives under
+    // HOME while the placement dir lives under the repo, which can be a
+    // different filesystem (a mounted volume) — renameSync can't cross
+    // devices (EXDEV). Copying first and removing the loadable copy second
+    // is also the fail-safe order: if the remove fails, the edits are
+    // already preserved in quarantine (worst case the loadable dir lingers
+    // and is re-quarantined next sync), never lost.
+    withFsRetry(() => cpSync(sourceDir, dest, { recursive: true }));
+    withFsRetry(() => rmSync(sourceDir, { recursive: true, force: true }));
+  } catch (err) {
+    if (err instanceof CliError) throw err;
+    throw diskError(`Failed to quarantine ${sourceDir}: ${err.message}`, {
+      cause: err,
+    });
+  }
+
+  return dest;
+}
+
 /**
  * Scan all configured placement roots and remove orphan .tmp/ and .old/
  * directories left over from a crashed write. Called at the start of

package/src/lib/gitignore-section.mjs

@@ -14,13 +14,21 @@
  * surfaced by the sync-time foreign-content scan (`foreign-content.mjs`)
  * — never something the ignore machinery accommodates.
  *
- * Idempotent: entries already present anywhere in the file are skipped;
- * missing entries are inserted INTO the existing marked section when one
- * exists (never a duplicate header), else appended as a new section.
- * Every call also heals the retired pre-4.10.0 sync-time section shape
- * (see `healLegacySection`).
+ * Idempotent: entries already present anywhere in the file are skipped.
+ * The managed-root entries are also skipped when an existing ignore rule
+ * already covers them — asked of git itself via `git check-ignore`
+ * (#2903), so a repo that ignores `.claude/` never gets a redundant
+ * `.claude/skills/` line; the init-only entries stay on the literal
+ * scan (see `isCoverageProbed` for why). Genuinely missing entries are
+ * inserted INTO the existing marked section when one exists (never a
+ * duplicate header), else appended as a new section. Nothing is written
+ * when nothing is missing. Every call also heals the retired pre-4.10.0
+ * sync-time section shape (see `healLegacySection`).
  */
 
+import { spawnSync } from "node:child_process";
+import { dirname } from "node:path";
+
 import { readFileSafe, writeFileSafe } from "./fs-utils.mjs";
 import { gitignorePath } from "./paths.mjs";
 import { diskError } from "./errors.mjs";
@@ -79,12 +87,18 @@ export function ensureManagedRootIgnores(targets, options = {}) {
 }
 
 /**
- * Core ensure: required entries end up line-exact in the file, inside
- * the CLI's marked section, with the legacy sync-time section healed
- * away. Single writer for every gitignore mutation the CLI performs.
+ * Core ensure: every required entry ends up ignored — either it is
+ * already present line-exact somewhere in the file, an existing ignore
+ * rule already covers it (managed roots only — `git check-ignore`, see
+ * `isCoverageProbed` / `isCoveredByGit`), or it is written into the
+ * CLI's marked section — with the legacy sync-time section healed away.
+ * Single writer for every gitignore mutation the CLI performs; at most
+ * ONE write per call.
  *
- * Returns `"skipped"` if every required entry is already present and no
- * legacy section needed healing, `"created"` if the file didn't exist,
+ * Returns `"skipped"` if nothing needed writing (every required entry
+ * present or covered, no legacy section to heal) — the file is not
+ * touched at all in that case, not even for a comment — `"created"` if
+ * the file didn't exist and at least one entry needed writing,
  * `"updated"` otherwise.
  *
  * @param {string[]} requiredEntries
@@ -107,28 +121,52 @@ export function ensureGitignoreEntries(requiredEntries, options = {}) {
     });
   }
 
+  const dir = dirname(filePath);
+
   if (existing === null) {
-    // Fresh .gitignore — write all required entries as one section.
-    const content =
-      GITIGNORE_SECTION_HEADER + "\n" + requiredEntries.join("\n") + "\n";
+    // Fresh .gitignore — one section holding every entry that still
+    // needs a line: the init-only entries always, a managed root only
+    // when no other ignore source (a nested .gitignore, info/exclude,
+    // a global excludes file) already covers it. Nothing to add →
+    // nothing to create.
+    const toAdd = dropCoveredEntries(requiredEntries, dir);
+    if (toAdd.length === 0) {
+      return { path: ".gitignore", action: "skipped", added: [] };
+    }
+    const content = GITIGNORE_SECTION_HEADER + "\n" + toAdd.join("\n") + "\n";
     writeSectionFile(filePath, content);
-    return {
-      path: ".gitignore",
-      action: "created",
-      added: [...requiredEntries],
-    };
+    return { path: ".gitignore", action: "created", added: toAdd };
   }
 
   // Preserve the original line-ending style throughout.
   const lineEnding = existing.includes("\r\n") ? "\r\n" : "\n";
 
-  const { lines, healed } = healLegacySection(existing.split(/\r?\n/));
+  const { lines, healed, removed } = healLegacySection(
+    existing.split(/\r?\n/),
+  );
 
   // Line-exact match check. `.env.local` as a line is distinct from
   // `.env.local.backup` or a comment `# .env.local` — compare trimmed
-  // lines so we match the entry literally.
+  // lines so we match the entry literally. A managed-root entry not
+  // present line-exact may still be covered by a broader rule
+  // (`.claude/` covers `.claude/skills/`); git is the authority on that
+  // — except for the line the heal just removed, which git still sees
+  // on disk (`removed`, see `dropCoveredEntries`).
+  //
+  // Whatever the heal removed is re-homed even when this call did not
+  // ask for that root (a Claude-only sync in a repo still carrying the
+  // legacy `.agents/skills/` line): the heal migrates protection, never
+  // drops it. Before #2903 that line was silently lost in this case.
+  const wanted =
+    removed.length > 0
+      ? [...new Set([...requiredEntries, ...removed])]
+      : requiredEntries;
   const trimmed = lines.map((l) => l.trim());
-  const missing = requiredEntries.filter((entry) => !trimmed.includes(entry));
+  const missing = dropCoveredEntries(
+    wanted.filter((entry) => !trimmed.includes(entry)),
+    dir,
+    removed,
+  );
 
   if (missing.length === 0 && !healed) {
     return {
@@ -195,6 +233,125 @@ function writeSectionFile(filePath, content) {
       hint: GITIGNORE_HINT,
     });
   }
+  forgetCoverage(dirname(filePath));
+}
+
+/**
+ * Per-process memo of `isCoveredByGit` answers, keyed by
+ * `<dir>\0<entry>`. The sync pre-flight runs once per written skill, so
+ * without it a sync writing N skills would spawn git N times for every
+ * entry that is covered-but-not-literal (~10 ms each). Every write this
+ * module makes to a directory's .gitignore forgets that directory's
+ * answers (`forgetCoverage`), so a memoized answer never outlives the
+ * file state it was computed from. Anything else editing the file
+ * mid-process is outside this module's contract — this is the only
+ * writer of that section.
+ */
+const coverageMemo = new Map();
+
+/**
+ * Forget every memoized answer for `dir`. Called after each write.
+ *
+ * @param {string} dir
+ */
+function forgetCoverage(dir) {
+  const prefix = `${dir}\0`;
+  for (const key of coverageMemo.keys()) {
+    if (key.startsWith(prefix)) coverageMemo.delete(key);
+  }
+}
+
+/**
+ * Only the managed skill roots consult git for coverage. They are
+ * per-checkout cache directories the CLI alone populates, so any ignore
+ * source git honours in THIS checkout (the repo's .gitignore files,
+ * `.git/info/exclude`, the global excludes file) makes an entry
+ * redundant here, and every other developer's own sync heals their own
+ * checkout. The init-only entries are a different contract: `.env.local`
+ * holds a live access key and `.claude/settings.local.json` per-developer
+ * settings, and their line in the TRACKED .gitignore is what protects
+ * every clone — it must not be withheld because the one developer running
+ * `init` happens to have a personal global excludes rule that covers it.
+ * They stay on the literal scan, exactly as before #2903.
+ *
+ * Considered and rejected for them: probing every entry but counting
+ * only in-tree `.gitignore` sources (parse `git check-ignore -v -z` for
+ * the matching rule's source). It would also quiet the one-time,
+ * init-only redundancy when a TRACKED `.env*` rule already covers
+ * `.env.local`, at the cost of output parsing and a second probe shape
+ * for a cosmetic gain. Revisit if that redundancy ever matters.
+ *
+ * @param {string} entry
+ * @returns {boolean}
+ */
+function isCoverageProbed(entry) {
+  return Object.values(MANAGED_ROOT_ENTRIES).includes(entry);
+}
+
+/**
+ * Ask git whether `entry` is already ignored in the work tree that owns
+ * the `.gitignore` at `dir` — the authoritative answer to "would adding
+ * this line be redundant?", honouring every ignore source git does
+ * (that `.gitignore`, nested ones, `.git/info/exclude`, the global
+ * excludes file). Per-checkout sources count deliberately for the
+ * entries this is asked about — see `isCoverageProbed`.
+ *
+ * `--no-index`: pattern coverage regardless of whether a tracked cache
+ * happens to sit under the root (#2361's tracked-cache case) — a rule
+ * that is already there is still redundant to add. The trailing slash
+ * on directory entries is load-bearing: `git check-ignore .agents/skills`
+ * (no slash) does NOT match an `.agents/skills/` rule while the
+ * directory does not exist yet, and on a first sync it does not. The
+ * probe runs WITH `dir` as its cwd because git resolves the path against
+ * its cwd — asked from a subdirectory, an unanchored `.claude/` rule
+ * would match `sub/.claude/skills/` and an anchored `/.claude/` would
+ * not, both wrong answers about the root.
+ *
+ * @param {string} dir - Directory holding the managed `.gitignore`.
+ * @param {string} entry - A `GITIGNORE_REQUIRED_ENTRIES` line.
+ * @returns {boolean | null} `true` covered, `false` not covered, `null`
+ *          no signal — git absent (`spawnSync` reports ENOENT via
+ *          `error`, it does not throw), not a work tree (exit 128), or
+ *          the probe timed out. Callers fall back to the literal scan.
+ */
+function isCoveredByGit(dir, entry) {
+  const key = `${dir}\0${entry}`;
+  if (coverageMemo.has(key)) return coverageMemo.get(key);
+  const probe = spawnSync(
+    "git",
+    ["check-ignore", "-q", "--no-index", "--", entry],
+    { cwd: dir, stdio: "ignore", windowsHide: true, timeout: 5000 },
+  );
+  let covered = null;
+  if (!probe.error && probe.status === 0) covered = true;
+  else if (!probe.error && probe.status === 1) covered = false;
+  coverageMemo.set(key, covered);
+  return covered;
+}
+
+/**
+ * Drop the managed-root entries git reports as already ignored. Entries
+ * that are not probed (`isCoverageProbed`) and entries in `exempt` stay.
+ * `exempt` names the line a pending legacy heal removed from the
+ * in-memory lines but not yet from disk: git would report that entry
+ * covered by the very line about to disappear, so it is re-homed
+ * unconditionally — the heal's whole purpose. With no signal from git
+ * (`null`) the literal scan the caller already ran is the only evidence,
+ * so the entry stays — outside a git work tree nothing can be committed
+ * anyway, and the pre-#2903 behaviour is preserved exactly.
+ *
+ * @param {string[]} entries - Entries not present line-exact in the file.
+ * @param {string} dir
+ * @param {string[]} [exempt]
+ * @returns {string[]}
+ */
+function dropCoveredEntries(entries, dir, exempt = []) {
+  return entries.filter(
+    (entry) =>
+      !isCoverageProbed(entry) ||
+      exempt.includes(entry) ||
+      isCoveredByGit(dir, entry) !== true,
+  );
 }
 
 /**
@@ -210,20 +367,29 @@ function writeSectionFile(filePath, content) {
  * legacy header — survives verbatim.
  *
  * @param {string[]} lines
- * @returns {{ lines: string[]; healed: boolean }}
+ * @returns {{ lines: string[]; healed: boolean; removed: string[] }}
+ *          `removed` names the entry line dropped (at most the
+ *          `.agents/skills/` root) so the caller re-homes it without
+ *          asking git, which still sees it on disk.
  */
 function healLegacySection(lines) {
   const headerIdx = lines.findIndex(
     (l) => l.trim() === LEGACY_GITIGNORE_SECTION_HEADER,
   );
-  if (headerIdx === -1) return { lines, healed: false };
+  if (headerIdx === -1) return { lines, healed: false, removed: [] };
 
   let end = headerIdx + 1;
-  if (end < lines.length && lines[end].trim() === ".agents/skills/") {
+  const removed = [];
+  if (
+    end < lines.length &&
+    lines[end].trim() === MANAGED_ROOT_ENTRIES.agentsProject
+  ) {
+    removed.push(MANAGED_ROOT_ENTRIES.agentsProject);
     end += 1;
   }
   return {
     lines: [...lines.slice(0, headerIdx), ...lines.slice(end)],
     healed: true,
+    removed,
   };
 }

package/src/lib/http.mjs

@@ -662,8 +662,30 @@ export async function getLibrary(serverUrl, apiKey, opts = {}) {
   }
 
   const body = await parseJsonOrThrow(res, url);
+  // #2804 / #2879 data-safety: a 200 whose JSON lacks a top-level `skills`
+  // ARRAY is a malformed library response (an upstream proxy/CDN body, an
+  // API-gateway health envelope, or a changed server contract). Before #2804
+  // the `?? []` collapse was a harmless no-op; now a FULL-sync reconcile
+  // treats an empty served set as AUTHORITATIVE and removes every local skill
+  // absent from it. Refuse to read a missing/non-array `skills` as "empty
+  // library" — fail loud instead of silently reconciling the user's whole
+  // library off disk. A genuine empty library sends `skills: []` (a real
+  // array), so this never fires on the legitimate empty-library reconcile.
+  // `--session-hook` callers catch this and exit 0 WITHOUT reconciling
+  // (getLibrary throws before the reconcile is reached); `list` degrades to
+  // its EXIT_NETWORK disk fallback. The transient legit-empty `skills: []`
+  // case (replica lag / transient empty accessible set) is NOT this guard's
+  // job — it needs a server-side guarantee, tracked in #2880.
+  if (!Array.isArray(body.skills)) {
+    throw networkError(
+      `Server returned a ${res.status} library response with no skills[] array from ${url}`,
+      {
+        hint: "An upstream proxy or CDN may have replaced the response body, or the server contract changed. The CLI refuses to treat a malformed library response as an authoritative empty library. Check the URL or retry.",
+      },
+    );
+  }
   return {
-    skills: body.skills ?? [],
+    skills: body.skills,
     removals: body.removals ?? [],
     syncedAt: body.syncedAt ?? new Date().toISOString(),
     // Verbatim as received (#2365 ETag rule): Vercel serves strong