skillrepo 4.9.0 → 4.9.2

package/package.json

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

package/src/commands/init.mjs

@@ -605,8 +605,17 @@ export async function runInit(argv, io = {}, deps = {}) {
   // placementTargetsFor (no vendors specified), and even if it
   // didn't, fetching skill files we have nowhere to write is
   // pure waste.
-  const skipFirstSync =
-    Array.isArray(vendors) && vendors.length === 0 && !flags.global;
+  //
+  // `--global` does NOT change that. `effectiveVendors` returns the
+  // `--agent none` sentinel verbatim under --global precisely because
+  // "--global --agent none" still means "no placement writes" (see its
+  // test in cli-config.test.mjs), and this guard has to honour the same
+  // contract. It previously carried `&& !flags.global`, which defeated
+  // the skip for exactly the combination the comment above says would
+  // throw: every skill in the library was quarantined one-by-one with a
+  // misleading "will be retried next session" warning, and init then
+  // printed "No skills in library yet" and "SkillRepo is ready" (#2433).
+  const skipFirstSync = Array.isArray(vendors) && vendors.length === 0;
   if (skipFirstSync) {
     p.success("Skipped first sync (--agent none).");
     syncSummary = {
@@ -681,13 +690,29 @@ export async function runInit(argv, io = {}, deps = {}) {
     }
   }
 
+  // `skipped` counts here: a run that dropped a skill is NOT a
+  // zero-delta run, and reporting "No skills in library yet" or
+  // "up to date" for it is a false statement to the user. Same defect
+  // class as the printSummary/hook fix in update.mjs (#2433).
   const zeroDeltas =
-    syncSummary.added + syncSummary.updated + syncSummary.removed === 0;
+    syncSummary.added +
+      syncSummary.updated +
+      syncSummary.removed +
+      (syncSummary.skipped ?? 0) ===
+    0;
 
-  if (syncFailedReason) {
-    // The warning already printed; the step-summary success line
-    // would be misleading, so we skip it. Any helpful "next steps"
-    // is in the final `SkillRepo is ready` block.
+  if (syncFailedReason || skipFirstSync) {
+    // The warning (or the "Skipped first sync" line) already printed;
+    // the step-summary success line would be misleading, so we skip
+    // it. Any helpful "next steps" is in the final `SkillRepo is
+    // ready` block.
+    //
+    // `skipFirstSync` belongs here for the same reason the synthesized
+    // summary above uses `fullSync: null`: the network call never ran,
+    // so we do not know the library's state. Falling through printed
+    // "Library is up to date (no changes since last sync)" — a
+    // confident claim about a server we never contacted, on the same
+    // screen as "Skipped first sync" (#2433).
   } else if (syncSummary.notModified) {
     // 304 Not Modified — the client had the current ETag already.
     // Definitively "up to date" regardless of whether the library

package/src/commands/update.mjs

@@ -155,7 +155,13 @@ export async function runUpdate(argv, io = {}) {
         throttle: true,
         io: { stdout: BLACK_HOLE_STREAM, stderr: BLACK_HOLE_STREAM },
       });
-      const total = summary.added + summary.updated + summary.removed;
+      // `skipped` is included so the hook cannot go silent on a dropped
+      // skill: this path black-holes BOTH streams, so if the count that
+      // gates output ignores skips, a quarantined skill produces no output
+      // anywhere and exits 0 (#2413 adversarial review).
+      const skipped = summary.skipped ?? 0;
+      const total =
+        summary.added + summary.updated + summary.removed + skipped;
       if (summary.notModified || total === 0) {
         // 304 Not Modified OR 200 with zero deltas — silent by
         // contract. Users should not see "Syncing..." on every
@@ -163,7 +169,9 @@ export async function runUpdate(argv, io = {}) {
         return;
       }
       stdout.write(
-        `[SkillRepo] Library synced: ${summary.added} added, ${summary.updated} updated, ${summary.removed} removed.\n`,
+        `[SkillRepo] Library synced: ${summary.added} added, ${summary.updated} updated, ${summary.removed} removed` +
+          (skipped > 0 ? `, ${skipped} SKIPPED (could not be written)` : "") +
+          `.\n`,
       );
     } catch (err) {
       // The one-line failure message is the user's primary signal
@@ -266,7 +274,11 @@ export async function runUpdate(argv, io = {}) {
 }
 
 function printSummary(s, out) {
-  const total = s.added + s.updated + s.removed;
+  // `skipped` counts here: a run that dropped a skill is NOT "up to date",
+  // and saying so was a false statement to the user (#2413 adversarial
+  // review — the counter was incremented and never read).
+  const skipped = s.skipped ?? 0;
+  const total = s.added + s.updated + s.removed + skipped;
   if (s.notModified || total === 0) {
     out.write("  ✓ Library is up to date.\n");
     return;
@@ -275,6 +287,7 @@ 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`);
+  if (skipped > 0)   out.write(`    ! ${skipped} skipped (see warnings above)\n`);
   out.write("\n");
 }
 

package/src/lib/file-write.mjs

@@ -27,6 +27,8 @@
  *     next `update` run fully overwrites it.
  *
  *   • Safety checks (NOT layout enforcement):
+ *       - Control characters (C0/DEL/C1, raw or URL-encoded) — rejected
+ *         (matches server CONTROL_CHARS, #2402)
  *       - Path traversal (..) — rejected
  *       - Absolute paths — rejected
  *       - Depth > 5 — rejected (matches server MAX_PATH_DEPTH)
@@ -131,6 +133,31 @@ const GLOBAL_TARGETS = Object.freeze([
 
 // ── Public API ──────────────────────────────────────────────────────────
 
+// Unicode Cc: C0 controls, DEL, and C1 controls. Same rule as the
+// server-side validator (#2402): a control character in a path can inject
+// line breaks or terminal escapes into prompts, logs, and rendered file
+// trees — and the CLI writes these paths to the user's disk on sync.
+// Mirrors CONTROL_CHAR_CLASS in src/lib/skills/file-validation.ts (the
+// CLI cannot import server TS). Always extend via \uXXXX escapes — NEVER
+// paste a raw control byte; a raw byte silently corrupts the class.
+const CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f]/;
+const CONTROL_CHARS_GLOBAL = /[\u0000-\u001f\u007f-\u009f]/g;
+
+/**
+ * Render a path for an error message with control characters
+ * \uXXXX-escaped, so the error string can never re-inject the characters
+ * it rejects into terminal output or sync logs.
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+function escapeControlChars(value) {
+  return value.replace(
+    CONTROL_CHARS_GLOBAL,
+    (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`,
+  );
+}
+
 /**
  * Validate a single file path inside a skill directory.
  *
@@ -142,6 +169,12 @@ const GLOBAL_TARGETS = Object.freeze([
  * @returns {string | null}
  */
 export function validateFilePath(rawPath) {
+  // Checked before decoding so no error message below (they interpolate
+  // the raw path verbatim) can ever echo a raw control character.
+  if (CONTROL_CHARS.test(rawPath)) {
+    return `Blocked control character in path "${escapeControlChars(rawPath)}".`;
+  }
+
   // Decode URL-encoded characters before validation
   let path;
   try {
@@ -150,6 +183,12 @@ export function validateFilePath(rawPath) {
     return `Invalid URL encoding in path "${rawPath}".`;
   }
 
+  // Re-check after the single decode: %0A-style encodings become real
+  // control characters here.
+  if (CONTROL_CHARS.test(path)) {
+    return `Blocked control character in path "${escapeControlChars(path)}".`;
+  }
+
   // Path traversal
   if (path.includes("..")) {
     return `Blocked path traversal in "${rawPath}".`;

package/src/lib/sync.mjs

@@ -145,7 +145,12 @@ import {
 } from "./file-write.mjs";
 import { writeFileAtomic } from "./fs-utils.mjs";
 import { globalLastSyncPath } from "./paths.mjs";
-import { diskError, validationError } from "./errors.mjs";
+import {
+  diskError,
+  validationError,
+  CliError,
+  EXIT_VALIDATION,
+} from "./errors.mjs";
 import { computeSkillShas } from "./crypto-shas.mjs";
 
 /**
@@ -923,6 +928,10 @@ export async function runSync(options) {
     added: 0,
     updated: 0,
     removed: 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.
+    skipped: 0,
     notModified: false,
     fullSync,
     syncedAt: result.syncedAt,
@@ -1011,13 +1020,61 @@ export async function runSync(options) {
     delete skillsMap[key];
   }
 
+  // Placement configuration is validated ONCE, before any skill is
+  // written. `placementTargetsFor` depends only on `vendors` and
+  // `global` — both constant for the whole sync — so everything it
+  // throws is a GLOBAL misconfiguration, never a per-skill problem.
+  // Reaching the per-skill quarantine below, it was swallowed once per
+  // skill: N copies of a misleading "this one will be retried next
+  // session" warning for a condition no retry can fix, and the caller
+  // still reported success (#2433).
+  //
+  // Guarded on there being something to write, so a no-op sync (empty
+  // response, tombstones only) is unaffected.
+  if (result.skills.length > 0) {
+    placementTargetsFor({ vendors, global: global === true });
+  }
+
   for (const skill of result.skills) {
     if (skill.filesIncomplete) {
       anyIncomplete = true;
       continue;
     }
     const wasAlreadyOnDisk = isAnyTargetPresent(skill.name, { vendors, global });
-    writeSkillDir(skill, { vendors, global });
+    // Quarantine-and-continue, NOT abort (#2413 audit). `writeSkillDir` ->
+    // `validateSkill` throws on the first unusable skill, and this loop used
+    // to have no catch — so ONE bad skill anywhere in a subscriber's library
+    // aborted the whole sync, delivered none of the others, and failed
+    // identically on every retry. #2402's control-character rejection made
+    // that reachable from stored data: a path accepted by an older server
+    // now fails validation on the client. A single publisher could therefore
+    // break sync for every member of every account holding that skill.
+    // Degrade per skill exactly as `filesIncomplete` above does: warn, mark
+    // the payload partial so local state does not advance (the run is
+    // retried next session rather than throttled away), and move on.
+    try {
+      writeSkillDir(skill, { vendors, global });
+    } catch (err) {
+      // ONLY a validation failure is quarantinable. `writeSkillDir` also
+      // throws EXIT_DISK for ENOSPC, EACCES, a read-only filesystem, and the
+      // Windows rename failure whose `hint` tells the user their only copy is
+      // in a `.tmp` directory. Those are not per-skill problems — every
+      // remaining skill will hit them too — and swallowing them turned a
+      // loud, actionable failure into a silent one, because the SessionStart
+      // hook passes a black-hole stderr and gates its output on
+      // added+updated+removed. Rethrow so the command's own handler reports
+      // them with the hint intact. (#2413 adversarial review.)
+      if (!(err instanceof CliError) || err.exitCode !== EXIT_VALIDATION) {
+        throw err;
+      }
+      anyIncomplete = true;
+      summary.skipped++;
+      stderr.write(
+        `  warning: skipped ${skill.owner}/${skill.name} (${err.message}). ` +
+          `Other skills were still synced; this one will be retried next session.\n`,
+      );
+      continue;
+    }
     if (wasAlreadyOnDisk) {
       summary.updated++;
     } else {

package/src/test/commands/init.test.mjs

@@ -516,6 +516,96 @@ describe("runInit — --agent none", () => {
     assert.equal(cfg.apiKey, VALID_KEY);
     assert.equal(cfg.serverUrl, serverUrl);
   });
+
+  it("--agent none --global skips the sync too, and never claims success over dropped skills (#2433)", async () => {
+    // REGRESSION. `skipFirstSync` used to carry `&& !flags.global`, so
+    // this combination reached `runSync` with an empty vendor list —
+    // the exact case the skip exists to avoid. Every skill in the
+    // library was then quarantined one-by-one by the per-skill catch
+    // with "Other skills were still synced; this one will be retried
+    // next session" (both halves false), and init went on to print
+    // "No skills in library yet" AND "SkillRepo is ready".
+    //
+    // A non-empty library is essential: with zero skills the old code
+    // produced no warnings and the bug was invisible. This is why the
+    // pre-existing `--agent none` tests above never caught it.
+    server.setLibraryResponse({
+      skills: [
+        {
+          owner: "alice",
+          name: "pdf-helper",
+          version: "1.0.0",
+          files: [{ path: "SKILL.md", content: "# PDF Helper\n" }],
+        },
+      ],
+      removals: [],
+      syncedAt: "2026-01-01T00:00:00Z",
+    });
+
+    await runInit(
+      [
+        "--key", VALID_KEY,
+        "--url", serverUrl,
+        "--yes",
+        "--agent", "none",
+        "--global",
+      ],
+      { stdout, stderr },
+    );
+
+    const out = stdout.text();
+    const err = stderr.text();
+
+    assert.match(out, /Skipped first sync/, "the sync must be skipped under --agent none --global");
+    assert.doesNotMatch(
+      err,
+      /retried next session/,
+      "a global misconfiguration must never be reported as a per-skill quarantine",
+    );
+    assert.doesNotMatch(
+      out,
+      /No skills in library yet/,
+      "must not claim the library is empty when it holds a skill",
+    );
+  });
+
+  it("a skipped sync makes no claim about the library's state (#2433)", async () => {
+    // "Skipped first sync" used to be followed by "Library is up to
+    // date (no changes since last sync)" — a confident claim about a
+    // server that was never contacted, printed on the same screen as
+    // the line saying we didn't contact it. Same rationale as the
+    // synthesized summary's `fullSync: null`: the state is UNKNOWN,
+    // so the honest output is no claim at all.
+    //
+    // The library deliberately holds a skill, so "up to date" would
+    // additionally be false on the merits.
+    server.setLibraryResponse({
+      skills: [
+        {
+          owner: "alice",
+          name: "pdf-helper",
+          version: "1.0.0",
+          files: [{ path: "SKILL.md", content: "# PDF Helper\n" }],
+        },
+      ],
+      removals: [],
+      syncedAt: "2026-01-01T00:00:00Z",
+    });
+
+    await runInit(
+      ["--key", VALID_KEY, "--url", serverUrl, "--yes", "--agent", "none"],
+      { stdout, stderr },
+    );
+
+    const out = stdout.text();
+    assert.match(out, /Skipped first sync/);
+    assert.doesNotMatch(
+      out,
+      /Library is up to date/,
+      "a sync that never ran cannot report the library as up to date",
+    );
+    assert.doesNotMatch(out, /No skills in library yet/);
+  });
 });
 
 // ── Idempotency ────────────────────────────────────────────────────────

package/src/test/lib/file-write.test.mjs

@@ -150,6 +150,41 @@ describe("validateFilePath", () => {
     assert.match(err, /URL encoding/);
   });
 
+  it("rejects control characters (newline prompt-injection vector, #2402)", () => {
+    const err = validateFilePath("references/a\n## heading\ntext.md");
+    assert.match(err ?? "", /control character/);
+  });
+
+  it("rejects NUL, DEL, and C1 controls", () => {
+    for (const code of [0x00, 0x1b, 0x1f, 0x7f, 0x85, 0x9f]) {
+      const err = validateFilePath(`a${String.fromCharCode(code)}b.md`);
+      assert.match(
+        err ?? "",
+        /control character/,
+        `U+${code.toString(16).padStart(4, "0")} should be blocked`,
+      );
+    }
+  });
+
+  it("rejects URL-encoded control characters", () => {
+    for (const enc of ["%0A", "%0a", "%00", "%1B", "%7F", "%C2%9B"]) {
+      const err = validateFilePath(`a${enc}b.md`);
+      assert.match(err ?? "", /control character/, `${enc} should be blocked`);
+    }
+  });
+
+  it("escapes control characters in the error message instead of echoing them", () => {
+    // The message ends up in terminal output and sync logs — echoing the
+    // raw character would recreate the injection there.
+    const err = validateFilePath("a\nb.md");
+    assert.ok(err != null && !err.includes("\n"), "error must not contain a raw newline");
+    assert.ok(err.includes("\\u000a"), "error should render the escaped codepoint");
+  });
+
+  it("accepts double-encoded %250A (single-decode policy, matches %252E%252E precedent)", () => {
+    assert.equal(validateFilePath("a%250Ab.md"), null);
+  });
+
   // QA cross-PR review (#1252): lock the current behavior of the
   // safety pre-check against backslash + Unicode-encoded traversal
   // patterns. validateFilePath uses an ASCII `..` substring check —

package/src/test/lib/http.test.mjs

@@ -551,6 +551,66 @@ describe("getLibrary", () => {
     }
   });
 
+  // ── Wire identity (#2358 — skillset epic no-file contract) ──────────
+  //
+  // The skillset epic's D2 contract: a repo with no skillset declaration
+  // must produce request/receipt payloads byte-identical to the
+  // pre-skillset CLI, forever. These tests capture today's wire shape so
+  // any future change to it — a new query param, a pin/skillset header —
+  // fails here first and has to be made deliberately.
+
+  it("wire identity: a plain sync sends the exact pre-skillset request shape (#2358)", async () => {
+    let captured;
+    const srv = await startServer((req, res) => {
+      captured = { url: req.url, method: req.method, headers: { ...req.headers } };
+      jsonRes(res, 200, { skills: [], removals: [], syncedAt: "x" });
+    });
+    try {
+      await getLibrary(srv.url, VALID_KEY);
+
+      // Exact path — no query string at all on a plain sync.
+      assert.equal(captured.url, "/api/v1/library");
+      assert.equal(captured.method, "GET");
+      // Auth rides the Authorization header, and no pin/skillset-shaped
+      // vocabulary appears in any header name or value.
+      assert.match(captured.headers.authorization, /^Bearer /);
+      const headerBlob = JSON.stringify(captured.headers);
+      assert.doesNotMatch(headerBlob, /skillset|approved|pin/i);
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("wire identity: a pin-suffixed ETag round-trips verbatim as an opaque string (#2358)", async () => {
+    // Servers emit `"{ts}-{count}-{removals}-p{ts}-{n}"` for accounts
+    // with pin history. The CLI must treat every ETag as opaque: store
+    // it exactly, send it back exactly. A client that parsed the legacy
+    // three-segment shape would corrupt the conditional-GET cycle for
+    // pinned accounts.
+    const SUFFIXED = '"1754680000000-12-3-p1754690000000-2"';
+    let conditional;
+    const srv = await startServer((req, res) => {
+      if (req.headers["if-none-match"]) {
+        conditional = req.headers["if-none-match"];
+        res.statusCode = 304;
+        res.end();
+        return;
+      }
+      jsonRes(res, 200, { skills: [], removals: [], syncedAt: "x" }, { ETag: SUFFIXED });
+    });
+    try {
+      const first = await getLibrary(srv.url, VALID_KEY);
+      assert.equal(first.etag, SUFFIXED);
+
+      const second = await getLibrary(srv.url, VALID_KEY, { ifNoneMatch: first.etag });
+      assert.equal(conditional, SUFFIXED);
+      assert.equal(second.notModified, true);
+      assert.equal(second.etag, SUFFIXED);
+    } finally {
+      await srv.close();
+    }
+  });
+
   it("throws authError on 401", async () => {
     const srv = await startServer((req, res) => jsonRes(res, 401, { error: "nope" }));
     try {

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

@@ -27,11 +27,12 @@ import {
   mkdtempSync,
   rmSync,
   mkdirSync,
+  chmodSync,
   writeFileSync,
   existsSync,
   readFileSync,
 } from "node:fs";
-import { join } from "node:path";
+import { join, dirname } from "node:path";
 import { tmpdir } from "node:os";
 
 import {
@@ -48,7 +49,7 @@ import {
 } from "../../lib/sync.mjs";
 import { resolvePlacementDir } from "../../lib/file-write.mjs";
 import { globalLastSyncPath } from "../../lib/paths.mjs";
-import { CliError, EXIT_VALIDATION } from "../../lib/errors.mjs";
+import { CliError, EXIT_VALIDATION, EXIT_DISK } from "../../lib/errors.mjs";
 import { computeSkillShas } from "../../lib/crypto-shas.mjs";
 import { walkDetectedPlacements } from "../../lib/placement-walk.mjs";
 import { createMockServer } from "../e2e/mock-server.mjs";
@@ -2534,3 +2535,168 @@ describe("runSync — SessionStart throttle (#2174)", () => {
     assert.equal(server.getLibraryRequestCount(), 0, "verbose throttle still makes no GET");
   });
 });
+
+// A skill whose stored path fails client-side validation is the failure mode
+// #2402 made reachable: a path an older server accepted now throws inside
+// validateSkill. Before the #2413 audit fix the apply loop had no catch, so
+// ONE such skill aborted the entire sync — every other skill in the library
+// went undelivered and every retry failed identically. A single publisher
+// could break sync for every member of every account holding that skill.
+describe("runSync — a poisoned skill is quarantined, not fatal (#2413 audit)", () => {
+  beforeEach(setupServer);
+  afterEach(teardownServer);
+
+  function poisonedSkill(name) {
+    const skill = makeSkill(name);
+    // Control character in a stored path — rejected by validateFilePath.
+    skill.files.push({
+      path: "references/a\nb.md",
+      content: "x",
+      sha256: "y",
+      size: 1,
+      contentType: "text/plain",
+    });
+    return skill;
+  }
+
+  it("a GLOBAL placement misconfiguration throws once, before any skill is written (#2433)", async () => {
+    // The quarantine is for per-skill data problems only. An empty
+    // vendor list is a global misconfiguration — `placementTargetsFor`
+    // reads only `vendors`/`global`, both constant for the whole sync,
+    // so it fails identically for every skill. Left inside the loop it
+    // was caught by the per-skill handler and emitted one misleading
+    // "will be retried next session" warning PER SKILL, while runSync
+    // returned normally and the caller reported success.
+    //
+    // Two skills, so a per-skill quarantine would produce two warnings
+    // and a resolved promise — a single throw is the discriminator.
+    const { createCaptureStream } = await import(
+      "../helpers/capture-stream.mjs"
+    );
+    const stderr = createCaptureStream();
+    server.setLibraryResponse({
+      skills: [makeSkill("alpha"), makeSkill("beta")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+
+    await assert.rejects(
+      () =>
+        runSync({
+          serverUrl,
+          apiKey: VALID_KEY,
+          vendors: [],
+          global: true,
+          io: { stderr },
+        }),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+      "an empty vendor list must propagate, not be quarantined per skill",
+    );
+
+    assert.doesNotMatch(
+      stderr.text(),
+      /retried next session/,
+      "a permanent misconfiguration must not be described as retryable",
+    );
+  });
+
+  it("delivers the healthy skills and reports the bad one instead of throwing", async () => {
+    const { createCaptureStream } = await import(
+      "../helpers/capture-stream.mjs"
+    );
+    const stderr = createCaptureStream();
+    server.setLibraryResponse({
+      skills: [poisonedSkill("poisoned"), makeSkill("healthy")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+
+    const result = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+      io: { stderr },
+    });
+
+    // Did not throw, and the healthy skill still landed.
+    assert.equal(result.added, 1, "the healthy skill must still be delivered");
+    assert.equal(result.skipped, 1, "the poisoned skill must be counted as skipped");
+    assert.match(stderr.text(), /skipped alice\/poisoned/);
+    assert.match(stderr.text(), /retried next session/);
+  });
+
+  it("does NOT quarantine a disk error — it propagates loudly", { skip: process.platform === "win32" ? "POSIX perms" : false }, async () => {
+    // The quarantine is for validation failures only. A disk condition
+    // (ENOSPC, EACCES, a read-only FS, the Windows rename failure whose
+    // `hint` names the user's only surviving copy) is not a per-skill
+    // problem — every remaining skill hits it too. Swallowing it turned an
+    // actionable failure into silence, because the SessionStart hook
+    // black-holes stderr and gates its output on added+updated+removed.
+    // Simulated with a read-only working directory. (#2413 adversarial
+    // review.)
+    const { createCaptureStream } = await import(
+      "../helpers/capture-stream.mjs"
+    );
+    const stderr = createCaptureStream();
+    server.setLibraryResponse({
+      skills: [makeSkill("blocked")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+
+    const projectDir = process.cwd();
+    chmodSync(projectDir, 0o500);
+    try {
+      await assert.rejects(
+        () =>
+          runSync({
+            serverUrl,
+            apiKey: VALID_KEY,
+            vendors: ["claudeCode"],
+            io: { stderr },
+          }),
+        (err) => err instanceof CliError && err.exitCode === EXIT_DISK,
+        "a disk error must propagate, not be quarantined as a skip",
+      );
+    } finally {
+      chmodSync(projectDir, 0o700);
+    }
+  });
+
+  it("does not advance local sync state when a skill was skipped", async () => {
+    // Same guard as `filesIncomplete`: a partial apply must not persist the
+    // ETag, or the next run 304s and the skipped skill is never retried.
+    const { createCaptureStream } = await import(
+      "../helpers/capture-stream.mjs"
+    );
+    const stderr = createCaptureStream();
+    // The ETag must be set on the SERVER (a response-header concern) — passing
+    // `etag` inside setLibraryResponse does nothing, which is what made an
+    // earlier version of this test vacuous: it passed even with
+    // `anyIncomplete` deleted, because `result.etag` was null and the state
+    // write was skipped for an unrelated reason (#2413 adversarial review).
+    server.setEtag('"poisoned-v1"');
+    server.setLibraryResponse({
+      skills: [poisonedSkill("poisoned"), makeSkill("healthy")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+
+    await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+      io: { stderr },
+    });
+
+    // Assert the INVARIANT directly rather than inferring it from request
+    // counts: no `.last-sync` ETag may be persisted while a skill was
+    // skipped, or the next run 304s and the skipped skill is never retried.
+    const state = readLastSync();
+    assert.equal(
+      state?.etag ?? null,
+      null,
+      "a skipped skill must leave the ETag unpersisted",
+    );
+  });
+});