skillrepo 4.5.0 → 4.5.2

package/src/test/integration/update-list-contract.integration.test.mjs

@@ -0,0 +1,1565 @@
+/**
+ * Cross-command integration: `update` → `list` contract.
+ *
+ * Why this file exists
+ * --------------------
+ * This is the test layer the v4.5.0 production-readiness review missed.
+ *
+ * The 4.5.0 staleness epic shipped two commands that share a contract:
+ *
+ *   `update` WRITES skills to disk under every vendor it targets.
+ *   `list`   READS those placements to compute per-skill drift state.
+ *
+ * The shared contract is the set of "detected vendors." If `update`
+ * writes to a smaller set than `list` walks, the list rolls up as
+ * MISSING for every multi-vendor user — exactly the production bug
+ * that triggered the 4.5.1 hotfix.
+ *
+ * Per-command unit tests (update.test.mjs + list.test.mjs) cannot
+ * surface this. They each fix one half of the contract and mock the
+ * other. Only an end-to-end test that runs `update` THEN reads the
+ * resulting `list` output catches a contract divergence. That's what
+ * this file is — the test that would have caught 4.5.1 pre-shipping.
+ *
+ * Test isolation
+ * --------------
+ * Every test runs inside a sandbox HOME so detection env vars are
+ * controlled, on-disk placements live in temp dirs, and the
+ * `.last-sync` state file is sandbox-local. The mock server stands in
+ * for the real registry. Detection signals are toggled via env vars
+ * documented in `agent-registry.mjs`:
+ *
+ *   - claudeCode: CLAUDECODE=1
+ *   - cursor:     CURSOR_AGENT=1
+ *
+ * Detection via `home`/`project` filesystem signals is also exercised
+ * implicitly when a test seeds `.claude/` or `.agents/` directories
+ * before invoking `update`.
+ */
+
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import {
+  mkdtempSync,
+  mkdirSync,
+  rmSync,
+  existsSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { runUpdate } from "../../commands/update.mjs";
+import { runList } from "../../commands/list.mjs";
+import { runGet } from "../../commands/get.mjs";
+import { runAdd } from "../../commands/add.mjs";
+import { runRemove } from "../../commands/remove.mjs";
+import { resolvePlacementDir } from "../../lib/file-write.mjs";
+import { globalLastSyncPath } from "../../lib/paths.mjs";
+import { readLastSync } from "../../lib/sync.mjs";
+import { createMockServer } from "../e2e/mock-server.mjs";
+import { createCaptureStream } from "../helpers/capture-stream.mjs";
+import {
+  captureHome,
+  setSandboxHome,
+  restoreHome,
+} from "../helpers/sandbox-home.mjs";
+
+let sandbox;
+let server;
+let serverUrl;
+let originalCwd;
+/** @type {import("../helpers/sandbox-home.mjs").HomeEnvSnapshot} */
+let originalHomeEnv;
+let stdout;
+const VALID_KEY = "sk_live_test";
+
+/**
+ * Build a registry skill payload with a single SKILL.md file. Same
+ * helper the unit tests use; replicated here so changes in either
+ * place don't silently break the other.
+ */
+function makeSkill(owner, name, version = "1.0.0", updatedAt) {
+  const content = `---\nname: ${name}\ndescription: ${name} description\n---\n\nbody\n`;
+  return {
+    owner,
+    name,
+    version,
+    description: `${name} description`,
+    files: [
+      {
+        path: "SKILL.md",
+        content,
+        // Server-side SHAs are not used by the CLI for drift detection —
+        // the CLI re-computes from content on disk. Any non-empty
+        // placeholder works.
+        sha256: "x",
+        size: content.length,
+        contentType: "text/markdown",
+      },
+    ],
+    // Default to "now" so the mock server's `since` filter (mirrors
+    // production `gt(skills.updatedAt, since)`) treats fresh fixtures
+    // as in-window. Tests that need to simulate "skill unchanged
+    // since last sync" pass an older string explicitly. Pre-PR #1575
+    // mock-server-tightening hardcoded "2025-01-01" which made every
+    // skill look stale once `since` was applied — that masked the
+    // real production behavior.
+    updatedAt: updatedAt ?? new Date().toISOString(),
+  };
+}
+
+async function setup() {
+  sandbox = mkdtempSync(join(tmpdir(), "cli-int-update-list-"));
+  mkdirSync(join(sandbox, "project"), { recursive: true });
+  mkdirSync(join(sandbox, "home"), { recursive: true });
+  originalCwd = process.cwd();
+  originalHomeEnv = captureHome();
+  process.chdir(join(sandbox, "project"));
+  setSandboxHome(join(sandbox, "home"));
+
+  // Strip any inherited credentials/detection that would otherwise
+  // pollute the test's controlled environment.
+  delete process.env.SKILLREPO_ACCESS_KEY;
+  delete process.env.SKILLREPO_URL;
+  delete process.env.CLAUDECODE;
+  delete process.env.CURSOR_AGENT;
+  delete process.env.CURSOR_CLI;
+
+  server = createMockServer({});
+  const port = await server.start();
+  serverUrl = `http://127.0.0.1:${port}`;
+
+  stdout = createCaptureStream();
+}
+
+async function teardown() {
+  if (server) await server.stop();
+  process.chdir(originalCwd);
+  restoreHome(originalHomeEnv);
+  delete process.env.CLAUDECODE;
+  delete process.env.CURSOR_AGENT;
+  delete process.env.CURSOR_CLI;
+  if (sandbox) rmSync(sandbox, { recursive: true, force: true });
+  server = null;
+}
+
+// ───────────────────────────────────────────────────────────────────────
+// The 4.5.1 regression suite
+// ───────────────────────────────────────────────────────────────────────
+//
+// The bug: `effectiveVendors` defaulted to `["claudeCode"]` when no
+// `--agent` was passed, so `skillrepo update` (with no flags) wrote
+// ONLY to claudeCode's placement. Meanwhile, `skillrepo list` walked
+// EVERY detected vendor's placement. Result for multi-agent users:
+// every skill rolled up as MISSING for every vendor that wasn't
+// Claude Code.
+//
+// The fix: `effectiveVendors` now defaults to every detected vendor
+// (DI-injectable for testability). These tests prove the new contract
+// end-to-end.
+
+describe("update → list cross-command contract (#1574)", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("multi-vendor: update with no --agent writes to every detected vendor (no MISS in list)", async () => {
+    // ── Forcing detection of TWO vendors ─────────────────────────────
+    // This is the exact production scenario behind 4.5.1: a user with
+    // both Claude Code AND Cursor installed runs `skillrepo update`
+    // with no `--agent`. Pre-fix, only claudeCode got the files. We
+    // assert both placements receive the skill AND that `list` agrees.
+    process.env.CLAUDECODE = "1";
+    process.env.CURSOR_AGENT = "1";
+
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "shared-skill", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-01-01T00:00:00Z",
+    });
+    server.setEtag('"v1"');
+
+    // ── Step 1: update with no --agent ───────────────────────────────
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    // Both placements must exist on disk — the contract claim.
+    const claudeDir = resolvePlacementDir("claudeProject", "shared-skill");
+    const agentsDir = resolvePlacementDir("agentsProject", "shared-skill");
+    assert.ok(existsSync(claudeDir), "claudeProject placement must be written");
+    assert.ok(existsSync(agentsDir), "agentsProject (cursor) placement must be written");
+
+    // Same bytes in both placements — sync writes identical content,
+    // not a stub. A future regression that wrote to multiple targets
+    // but produced divergent content would break list's drift check
+    // and surface here.
+    const claudeBody = readFileSync(join(claudeDir, "SKILL.md"), "utf-8");
+    const agentsBody = readFileSync(join(agentsDir, "SKILL.md"), "utf-8");
+    assert.equal(claudeBody, agentsBody, "writes to multiple targets must produce identical content");
+
+    // ── Step 2: list reads the same placements ───────────────────────
+    // Use --json so we can assert the per-placement state directly.
+    stdout = createCaptureStream();
+    await runList(
+      ["--key", VALID_KEY, "--url", serverUrl, "--json"],
+      { stdout },
+    );
+    const [item] = JSON.parse(stdout.text());
+    assert.equal(item.name, "shared-skill");
+    // The rollup: both placements are current → rollup is current.
+    // Pre-fix this was "missing" because cursor's placement was empty.
+    assert.equal(item.state, "current", "rollup must be `current` when every detected vendor has the skill");
+    // Lock in the EXACT vendor count. Without this assertion a
+    // regression that over-detects (e.g., a future change that
+    // defaults to ALL seven registry entries instead of detected-only)
+    // would still pass the per-vendor `state === "current"` checks
+    // below because both claudeCode and cursor would land in the
+    // list. The `.length === 2` check catches the over-detection
+    // direction; the test above already catches under-detection.
+    assert.equal(
+      item.placements.length,
+      2,
+      "list must walk exactly the two detected vendors, not every registered one",
+    );
+    // Each vendor's placement entry reports current independently.
+    const byVendor = Object.fromEntries(item.placements.map((p) => [p.vendor, p]));
+    assert.ok(byVendor.claudeCode, "claudeCode placement must appear");
+    assert.ok(byVendor.cursor, "cursor placement must appear");
+    assert.equal(byVendor.claudeCode.state, "current");
+    assert.equal(byVendor.cursor.state, "current");
+  });
+
+  it("single-vendor: update with only cursor detected → list shows current for cursor only", async () => {
+    // The narrow contract: only the one detected vendor gets the
+    // placement, AND `list` afterwards reports `current` for that
+    // vendor — no phantom MISS for claudeCode.
+    //
+    // This test used to opt out of the `list` assertion because of a
+    // companion bug: writing `~/.claude/skillrepo/.last-sync`
+    // created `~/.claude/`, which then matched claudeCode's home
+    // detection signal. PR #1574's production-readiness audit
+    // narrowed that signal to `~/.claude/settings.json` (a file
+    // Claude Code itself creates, that SkillRepo never writes) so
+    // the false positive no longer fires. This test is now the
+    // regression guard: a Cursor-only user must see `list` reporting
+    // their skills as `current`, NOT all-MISS for a vendor they
+    // don't use.
+    process.env.CURSOR_AGENT = "1";
+
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "cursor-only", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-01-01T00:00:00Z",
+    });
+    server.setEtag('"v1"');
+
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    // Only cursor's placement exists.
+    assert.ok(
+      existsSync(resolvePlacementDir("agentsProject", "cursor-only")),
+      "agentsProject placement should exist for cursor",
+    );
+    assert.equal(
+      existsSync(resolvePlacementDir("claudeProject", "cursor-only")),
+      false,
+      "claudeProject placement should NOT exist when claudeCode is not detected at update-time",
+    );
+
+    // `list` now correctly sees ONE detected vendor and reports
+    // `current`. The false-positive claudeCode detection that
+    // shipped in 4.5.0/4.5.1 produced all-MISS output here.
+    stdout = createCaptureStream();
+    await runList(["--key", VALID_KEY, "--url", serverUrl, "--json"], { stdout });
+    const [item] = JSON.parse(stdout.text());
+    assert.equal(item.state, "current");
+    assert.equal(
+      item.placements.length,
+      1,
+      "Cursor-only user must not see a phantom claudeCode placement entry",
+    );
+    assert.equal(item.placements[0].vendor, "cursor");
+    assert.equal(item.placements[0].state, "current");
+  });
+
+  it("no-detection fallback: update with no --agent uses the historical claudeCode default", async () => {
+    // The other edge of the fix: if NOTHING is detected (no env vars,
+    // no `.claude/` or `.agents/` dirs anywhere), the CLI falls back
+    // to writing claudeCode-only — preserving the pre-4.5.1 behavior
+    // for first-run users. Without this fallback, a brand-new
+    // checkout in a clean shell would silently no-op `update` because
+    // detection returned an empty list.
+    //
+    // We don't set ANY env vars. The sandbox HOME is brand-new
+    // (no .claude / no .cursor / no .agents).
+
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "fallback", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-01-01T00:00:00Z",
+    });
+    server.setEtag('"v1"');
+
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    // claudeProject is the documented fallback target.
+    assert.ok(
+      existsSync(resolvePlacementDir("claudeProject", "fallback")),
+      "fallback to claudeProject must hold when nothing is detected",
+    );
+  });
+
+  it("explicit --agent narrows the write set even when more vendors are detected", async () => {
+    // The explicit-flag escape hatch: even if both vendors are
+    // detected, `--agent claude` (or `--agent cursor`) writes only
+    // to the named vendor. `effectiveVendors` returns the explicit
+    // list verbatim — detection is ONLY consulted when no --agent
+    // is passed.
+    process.env.CLAUDECODE = "1";
+    process.env.CURSOR_AGENT = "1";
+
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "narrowed", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-01-01T00:00:00Z",
+    });
+    server.setEtag('"v1"');
+
+    await runUpdate(
+      ["--key", VALID_KEY, "--url", serverUrl, "--agent", "claude"],
+      { stdout },
+    );
+
+    assert.ok(existsSync(resolvePlacementDir("claudeProject", "narrowed")));
+    // cursor's placement must NOT be written, even though cursor
+    // is detected. Explicit > implicit.
+    assert.equal(
+      existsSync(resolvePlacementDir("agentsProject", "narrowed")),
+      false,
+      "--agent claude must NOT incidentally write to cursor's placement",
+    );
+  });
+
+  it("explicit --agent ALSO has the listed vendor appear in list when detected", async () => {
+    // Defense-in-depth check: a user can run `update --agent claude`
+    // on a multi-vendor machine and `list` will still walk EVERY
+    // detected vendor (including cursor) and surface cursor's
+    // placement as MISS — that's the correct user-visible signal that
+    // their explicit-narrow update left a vendor un-updated.
+    process.env.CLAUDECODE = "1";
+    process.env.CURSOR_AGENT = "1";
+
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "explicit", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-01-01T00:00:00Z",
+    });
+    server.setEtag('"v1"');
+
+    await runUpdate(
+      ["--key", VALID_KEY, "--url", serverUrl, "--agent", "claude"],
+      { stdout },
+    );
+
+    stdout = createCaptureStream();
+    await runList(["--key", VALID_KEY, "--url", serverUrl, "--json"], { stdout });
+    const [item] = JSON.parse(stdout.text());
+    // Cursor's placement is empty → its per-vendor state is missing
+    // → rollup is missing (worst state wins). User sees a clear
+    // signal that one of their vendors didn't get the update.
+    assert.equal(item.state, "missing");
+    const cursor = item.placements.find((p) => p.vendor === "cursor");
+    assert.ok(cursor, "list must still include cursor's placement entry");
+    assert.equal(cursor.state, "missing");
+  });
+});
+
+// ───────────────────────────────────────────────────────────────────────
+// .last-sync v1 → v2 migration round-trip
+// ───────────────────────────────────────────────────────────────────────
+//
+// A user upgrading from 4.4.x to 4.5.x has a v1 `.last-sync` on disk.
+// The new CLI must:
+//   1. Read it without crashing.
+//   2. Preserve the etag + syncedAt so the next sync still benefits
+//      from a 304 short-circuit.
+//   3. After the next successful sync, write a v2 file with the
+//      per-skill SHA map populated.
+//
+// Sync.test.mjs has unit-level coverage. This integration test
+// exercises the path through runSync against the mock server, which
+// is the only way to verify the v2 file that lands on disk has the
+// expected shape AND the ETag carry-forward took effect.
+
+describe("v1 → v2 .last-sync migration round-trip", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("reads v1 .last-sync, performs sync, writes v2 with SHA map populated", async () => {
+    // Seed a v1 state file at the documented path. Both fields are
+    // strings — that's the v1 shape `readLastSync` migrates from.
+    const v1Path = globalLastSyncPath();
+    mkdirSync(join(v1Path, ".."), { recursive: true });
+    writeFileSync(
+      v1Path,
+      JSON.stringify({
+        schemaVersion: 1,
+        etag: '"v1-etag"',
+        syncedAt: "2025-12-01T00:00:00Z",
+      }),
+    );
+
+    process.env.CLAUDECODE = "1";
+    server.setEtag('"v2-etag"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "migrated", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-05-19T00:00:00Z",
+    });
+
+    // ── Run update — this triggers the v1→v2 in-memory migration
+    //    in readLastSync and the v2 write at the end of runSync ──
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    // The on-disk file must now be v2 and carry the per-skill SHA
+    // map. The pre-existing v1 etag/syncedAt are NOT preserved
+    // because the sync actually completed and got a fresh ETag from
+    // the server. Carry-forward applies to the per-skill SHA map
+    // (which was empty in v1), not to the library ETag itself.
+    const afterRaw = readFileSync(v1Path, "utf-8");
+    const after = JSON.parse(afterRaw);
+    assert.equal(after.schemaVersion, 2, "must persist as v2");
+    assert.equal(after.etag, '"v2-etag"', "etag must reflect server's response");
+    assert.ok(
+      after.skills && typeof after.skills === "object",
+      "skills map must be populated",
+    );
+    assert.ok(after.skills["alice/migrated"], "synced skill must appear in the SHA map");
+    const entry = after.skills["alice/migrated"];
+    assert.equal(entry.version, "1.0.0");
+    assert.match(entry.skillMdSha256, /^[a-f0-9]{64}$/, "skillMdSha256 must be a hex SHA-256");
+    assert.match(entry.filesSha256, /^[a-f0-9]{64}$/, "filesSha256 must be a hex SHA-256");
+  });
+
+  it("v1 state with NO content changes → first sync after upgrade does a full re-fetch (recovery)", async () => {
+    // The recovery path for users upgrading from v1 `.last-sync`
+    // (4.4.x and earlier) or any state where the per-skill SHA map
+    // is empty. `placementsAreComplete` returns false when the
+    // baseline map is empty — that's the "we have an etag but no
+    // per-skill cache, so we can't trust the 304" signal. runSync
+    // drops `If-None-Match`, fetches the full library, and writes
+    // both the skill bytes and the per-skill SHA cache. The "library
+    // synced" message replaces "up to date" exactly once per
+    // upgrade; subsequent syncs (now with a populated skills map
+    // AND placement directories on disk) return to the 304 fast
+    // path.
+    const v1Path = globalLastSyncPath();
+    mkdirSync(join(v1Path, ".."), { recursive: true });
+    writeFileSync(
+      v1Path,
+      JSON.stringify({
+        schemaVersion: 1,
+        etag: '"unchanged"',
+        syncedAt: "2025-12-01T00:00:00Z",
+      }),
+    );
+
+    process.env.CLAUDECODE = "1";
+    server.setEtag('"unchanged"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "unmigrated", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-05-19T00:00:00Z",
+    });
+
+    // First sync after upgrade: empty skills map → placementsAreComplete
+    // returns false → full re-fetch. User sees the "synced" message,
+    // not "up to date" — recovery is visible.
+    server.resetLibraryInspection();
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    const firstOut = stdout.text();
+    // Negative assertion: the misleading "up to date" message must
+    // not appear during the recovery sync.
+    assert.ok(
+      !/up to date/.test(firstOut),
+      "first sync after upgrade must NOT 304 — empty skills map forces full re-fetch",
+    );
+    // Positive assertion: the recovery sync must report at least
+    // one write. Without this, a future regression where the command
+    // crashed before printing anything would also pass the negative
+    // assertion above. See QA Gap 4.
+    assert.match(
+      firstOut,
+      /Library sync complete|added|updated/,
+      "first sync after upgrade must positively report a sync, not silently no-op",
+    );
+    // Wire-level: ETag was dropped — placementsAreComplete returned
+    // false for the empty baseline. This is the load-bearing
+    // mechanism, not just a side-effect of output.
+    assert.equal(
+      server.getLastLibraryIfNoneMatch(),
+      null,
+      "v1 migration must drop If-None-Match (placementsAreComplete returns false for empty map)",
+    );
+
+    // After the recovery sync, the on-disk file is v2 with the
+    // skills map populated. The skill is on disk in the claudeProject
+    // placement — the user-visible recovery.
+    const after = readLastSync();
+    assert.equal(after.schemaVersion, 2);
+    assert.ok(after.skills["alice/unmigrated"]);
+    assert.ok(existsSync(resolvePlacementDir("claudeProject", "unmigrated")));
+
+    // Second sync with the SAME vendor set: now the ETag short-circuit
+    // is safe and 304 fires (this proves we didn't accidentally make
+    // every sync do a full re-fetch — the fix is targeted).
+    stdout = createCaptureStream();
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    assert.match(
+      stdout.text(),
+      /up to date/,
+      "second sync (vendor set now in .last-sync) should 304 normally",
+    );
+  });
+});
+
+// ───────────────────────────────────────────────────────────────────────
+// End-to-end drift state through the real update path
+// ───────────────────────────────────────────────────────────────────────
+//
+// list.test.mjs synthesizes `.last-sync` and disk state by hand to
+// exercise each drift state. Those tests prove computeSkillState is
+// correct given a state. They do NOT prove that the state runSync
+// actually persists, when fed back into list, yields the expected
+// classification.
+//
+// These tests run a real update first, then mutate something, then
+// run list. They lock in the round-trip from update → on-disk state
+// → list → drift verdict — which is the only layer where a mismatch
+// between sync's persisted shape and list's expected shape would
+// surface as a user-visible bug.
+
+describe("update → mutate → list: drift verdicts on real persisted state", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("OK after update: a freshly synced skill is `current` in list with no mutation", async () => {
+    process.env.CLAUDECODE = "1";
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "fresh", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-05-19T00:00:00Z",
+    });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    stdout = createCaptureStream();
+    await runList(["--key", VALID_KEY, "--url", serverUrl, "--json"], { stdout });
+    const [item] = JSON.parse(stdout.text());
+    assert.equal(item.state, "current");
+  });
+
+  it("EDIT after update: hand-edit a SKILL.md and list shows `edited`", async () => {
+    process.env.CLAUDECODE = "1";
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "tampered", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-05-19T00:00:00Z",
+    });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    // Append a line to SKILL.md — the persisted SHA in .last-sync
+    // no longer matches the on-disk SHA. drift.mjs's contract is
+    // "version match + SHA mismatch → edited."
+    const skillPath = join(
+      resolvePlacementDir("claudeProject", "tampered"),
+      "SKILL.md",
+    );
+    const original = readFileSync(skillPath, "utf-8");
+    writeFileSync(skillPath, original + "\n<!-- user edit -->\n");
+
+    stdout = createCaptureStream();
+    await runList(["--key", VALID_KEY, "--url", serverUrl, "--json"], { stdout });
+    const [item] = JSON.parse(stdout.text());
+    assert.equal(item.state, "edited", "post-update hand-edit must surface as `edited`");
+  });
+
+  it("STALE after update: server bumps version and list shows `stale`", async () => {
+    process.env.CLAUDECODE = "1";
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "aging", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-05-19T00:00:00Z",
+    });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    // Server's library moves forward: same skill, new version. No
+    // second `update` happens — `.last-sync` still shows 1.0.0 as
+    // synced.
+    server.setEtag('"v2"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "aging", "1.1.0")],
+      removals: [],
+      syncedAt: "2026-05-19T01:00:00Z",
+    });
+
+    stdout = createCaptureStream();
+    await runList(["--key", VALID_KEY, "--url", serverUrl, "--json"], { stdout });
+    const [item] = JSON.parse(stdout.text());
+    assert.equal(item.state, "stale", "library moved ahead → `stale`");
+  });
+
+  it("MISSING after update + manual delete: removing a placement makes list show `missing`", async () => {
+    process.env.CLAUDECODE = "1";
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "deletable", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-05-19T00:00:00Z",
+    });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    // Delete the placement directory the user just synced. .last-sync
+    // still records this skill as present (the SHA map remembers it)
+    // but the disk no longer has it — drift.mjs's contract is
+    // "baseline exists + on-disk gone → missing."
+    rmSync(resolvePlacementDir("claudeProject", "deletable"), {
+      recursive: true,
+      force: true,
+    });
+
+    stdout = createCaptureStream();
+    await runList(["--key", VALID_KEY, "--url", serverUrl, "--json"], { stdout });
+    const [item] = JSON.parse(stdout.text());
+    assert.equal(item.state, "missing");
+  });
+
+  it("multi-vendor mixed drift: claudeCode edited + cursor current rolls up to `edited` (worst-state-wins)", async () => {
+    // The rollup contract is "worst state wins" — defined in
+    // drift.mjs's `rollupState`. End-to-end coverage proves the
+    // contract holds when both placements go through the real
+    // update + list path, not just the synthesized state path.
+    process.env.CLAUDECODE = "1";
+    process.env.CURSOR_AGENT = "1";
+
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "split-drift", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-05-19T00:00:00Z",
+    });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    // Edit ONLY the claudeCode placement.
+    const claudeFile = join(
+      resolvePlacementDir("claudeProject", "split-drift"),
+      "SKILL.md",
+    );
+    writeFileSync(claudeFile, readFileSync(claudeFile, "utf-8") + "// drift\n");
+
+    stdout = createCaptureStream();
+    await runList(["--key", VALID_KEY, "--url", serverUrl, "--json"], { stdout });
+    const [item] = JSON.parse(stdout.text());
+
+    // Rollup: edited vs current → edited (worst wins). The user-
+    // visible signal is "something needs attention" even though one
+    // vendor is fine.
+    assert.equal(item.state, "edited");
+    const byVendor = Object.fromEntries(item.placements.map((p) => [p.vendor, p]));
+    assert.equal(byVendor.claudeCode.state, "edited");
+    assert.equal(byVendor.cursor.state, "current");
+  });
+});
+
+// ───────────────────────────────────────────────────────────────────────
+// `get` / `add` / `remove` write-back to `.last-sync`
+// ───────────────────────────────────────────────────────────────────────
+//
+// The 4.5.1 effective-vendors fix was a write-side contract gap. PR
+// #1574's production-readiness audit surfaced THREE more of the same
+// shape: `get`, `add`, and `remove` write to disk via `writeSkillDir`
+// (or `removeSkillDir`) but never updated `.last-sync` — so the very
+// next `list` reported every freshly-fetched / freshly-added skill as
+// `MISSING` even though it was sitting right there on disk. These
+// tests lock in the closed contract.
+
+describe("get → list cross-command contract", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("after `get`, list reports the skill as current (not MISSING)", async () => {
+    process.env.CLAUDECODE = "1";
+
+    // Prime `.last-sync` with one prior-synced skill so we can also
+    // verify that `get` doesn't clobber existing entries.
+    server.setEtag('"baseline"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "prior-sync", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-01-01T00:00:00Z",
+    });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    // Now `get` a different skill that's NOT in the library
+    // response yet. The mock server serves it from setSkillResponse.
+    server.setSkillResponse(
+      "bob",
+      "fetched",
+      makeSkill("bob", "fetched", "1.0.0"),
+    );
+    stdout = createCaptureStream();
+    await runGet(
+      ["@bob/fetched", "--key", VALID_KEY, "--url", serverUrl],
+      { stdout },
+    );
+
+    // Server's library now reports both skills (the maintainer
+    // published `bob/fetched` to the catalog). list must see both
+    // as `current` — the freshly-fetched one IS on disk and IS in
+    // the baseline.
+    server.setEtag('"baseline+1"');
+    server.setLibraryResponse({
+      skills: [
+        makeSkill("alice", "prior-sync", "1.0.0"),
+        makeSkill("bob", "fetched", "1.0.0"),
+      ],
+      removals: [],
+      syncedAt: "2026-01-02T00:00:00Z",
+    });
+
+    stdout = createCaptureStream();
+    await runList(
+      ["--key", VALID_KEY, "--url", serverUrl, "--json"],
+      { stdout },
+    );
+    const parsed = JSON.parse(stdout.text());
+    const prior = parsed.find((s) => s.name === "prior-sync");
+    const fetched = parsed.find((s) => s.name === "fetched");
+    assert.equal(prior.state, "current", "prior-synced skill must stay current");
+    assert.equal(
+      fetched.state,
+      "current",
+      "skill fetched via `get` must show as current — get must update .last-sync",
+    );
+  });
+
+  it("get preserves the library-level etag (next update can still 304)", async () => {
+    // Critical invariant: `get` updates the per-skill SHA entry but
+    // leaves the library-level `etag` and `syncedAt` alone. If `get`
+    // clobbered the etag, the next `update` would do a wasted full
+    // sync. This test guards that behavior.
+    process.env.CLAUDECODE = "1";
+
+    server.setEtag('"original-etag"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "prior", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-01-01T00:00:00Z",
+    });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    server.setSkillResponse("bob", "extra", makeSkill("bob", "extra", "1.0.0"));
+    await runGet(
+      ["@bob/extra", "--key", VALID_KEY, "--url", serverUrl],
+      { stdout },
+    );
+
+    // Read the persisted state directly — the etag/syncedAt must
+    // match what the prior update wrote, not what `get` happened to
+    // synthesize.
+    const after = readLastSync();
+    assert.equal(after.etag, '"original-etag"', "get must not clobber the library etag");
+    assert.equal(
+      after.syncedAt,
+      "2026-01-01T00:00:00Z",
+      "get must not clobber the library syncedAt",
+    );
+    // The new skill entry IS in the map alongside the prior entry.
+    assert.ok(after.skills["alice/prior"], "prior entry preserved");
+    assert.ok(after.skills["bob/extra"], "newly-fetched entry recorded");
+  });
+});
+
+describe("add → list cross-command contract", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("after `add`, list reports the skill as current (not MISSING)", async () => {
+    process.env.CLAUDECODE = "1";
+
+    // `add` does POST /library/refs THEN GET /skills/<owner>/<name>.
+    // Both need responses on the mock server.
+    server.setAddResponseForAny({
+      status: 201,
+      body: {
+        added: {
+          owner: "carol",
+          name: "added-skill",
+          version: "2.0.0",
+          addedAt: "2026-01-01T00:00:00Z",
+        },
+      },
+    });
+    server.setSkillResponse(
+      "carol",
+      "added-skill",
+      makeSkill("carol", "added-skill", "2.0.0"),
+    );
+
+    await runAdd(
+      ["@carol/added-skill", "--key", VALID_KEY, "--url", serverUrl],
+      { stdout },
+    );
+
+    // Subsequent list with the catalog now showing the same skill —
+    // it should report as `current`.
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("carol", "added-skill", "2.0.0")],
+      removals: [],
+      syncedAt: "2026-01-01T00:00:00Z",
+    });
+
+    stdout = createCaptureStream();
+    await runList(
+      ["--key", VALID_KEY, "--url", serverUrl, "--json"],
+      { stdout },
+    );
+    const [item] = JSON.parse(stdout.text());
+    assert.equal(item.name, "added-skill");
+    assert.equal(
+      item.state,
+      "current",
+      "skill added via `add` must show as current — add must update .last-sync",
+    );
+  });
+});
+
+describe("remove → list cross-command contract", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("after `remove`, the skill's entry is purged from .last-sync", async () => {
+    process.env.CLAUDECODE = "1";
+
+    // Sync two skills, then remove one.
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [
+        makeSkill("alice", "keep", "1.0.0"),
+        makeSkill("alice", "drop", "1.0.0"),
+      ],
+      removals: [],
+      syncedAt: "2026-01-01T00:00:00Z",
+    });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    // Confirm both entries are present in .last-sync.
+    let state = readLastSync();
+    assert.ok(state.skills["alice/keep"]);
+    assert.ok(state.skills["alice/drop"]);
+
+    server.setRemoveResponseForAny({
+      status: 200,
+      body: { removed: { owner: "alice", name: "drop" } },
+    });
+    await runRemove(
+      ["@alice/drop", "--key", VALID_KEY, "--url", serverUrl],
+      { stdout },
+    );
+
+    // `alice/drop` is now absent from .last-sync; the kept skill is
+    // unaffected; the library-level etag is preserved (remove does
+    // NOT touch it).
+    state = readLastSync();
+    assert.ok(state.skills["alice/keep"], "kept skill's entry remains");
+    assert.equal(
+      state.skills["alice/drop"],
+      undefined,
+      "removed skill's entry must be purged",
+    );
+    assert.equal(state.etag, '"v1"', "remove must not clobber the library etag");
+  });
+
+  it("removing a skill that was never in .last-sync is idempotent (no throw, no spurious write)", async () => {
+    // Edge case: user runs `skillrepo remove @alice/never-synced`
+    // for a skill that was never on disk and was never tracked. The
+    // server returns 404 (not-in-library) but `remove` still tries
+    // to clean local files (which don't exist) and update
+    // `.last-sync` (which has no entry to remove). This must not
+    // throw and must not change the etag/syncedAt.
+    process.env.CLAUDECODE = "1";
+    server.setEtag('"unchanged"');
+    server.setLibraryResponse({
+      skills: [],
+      removals: [],
+      syncedAt: "2026-01-01T00:00:00Z",
+    });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    server.setRemoveResponseForAny({
+      status: 404,
+      body: { error: "Skill not found", code: "not_found" },
+    });
+    await assert.doesNotReject(() =>
+      runRemove(
+        ["@alice/never-synced", "--key", VALID_KEY, "--url", serverUrl],
+        { stdout },
+      ),
+    );
+
+    const state = readLastSync();
+    assert.equal(state.etag, '"unchanged"');
+  });
+});
+
+// ───────────────────────────────────────────────────────────────────────
+// QA-flagged coverage gaps (from PR #1574 production-readiness audit)
+// ───────────────────────────────────────────────────────────────────────
+
+describe("additional coverage from production-readiness audit", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("corrupt .last-sync survives — runUpdate writes a fresh v2 file and list works", async () => {
+    // Real-world failure mode: a power loss mid-write leaves a
+    // partially-written `.last-sync` that won't parse as JSON.
+    // `readLastSync` returns null on parse failure (documented
+    // forward-compat behavior) and runSync performs a full re-sync.
+    // This test holds that contract — a future refactor that removes
+    // the try/catch and throws on parse error would break every user
+    // with a corrupt cache.
+    const path = globalLastSyncPath();
+    mkdirSync(join(path, ".."), { recursive: true });
+    writeFileSync(path, "CORRUPTED-NOT-JSON{{{", "utf-8");
+
+    process.env.CLAUDECODE = "1";
+    server.setEtag('"fresh"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "recovered", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-05-19T00:00:00Z",
+    });
+
+    await assert.doesNotReject(
+      () => runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout }),
+      "runUpdate must survive a corrupt .last-sync and complete the sync",
+    );
+    const after = readLastSync();
+    assert.equal(after.schemaVersion, 2);
+    assert.equal(after.etag, '"fresh"');
+    assert.ok(after.skills["alice/recovered"]);
+  });
+
+  it("delta sync preserves entries the server didn't return in this round", async () => {
+    // The carry-forward contract. Server returns skill A on sync 1,
+    // then returns only skill B on sync 2 (delta — A didn't change).
+    // After sync 2, `.last-sync` must STILL contain A's SHA entry.
+    // Without this carry-forward, every delta sync shrinks the map
+    // until only the most-recently-touched skills remain — defeating
+    // list's drift detection for stable skills.
+    process.env.CLAUDECODE = "1";
+
+    // Sync 1: both A and B in the library.
+    server.setEtag('"sync1"');
+    server.setLibraryResponse({
+      skills: [
+        makeSkill("alice", "stable", "1.0.0"),
+        makeSkill("alice", "churning", "1.0.0"),
+      ],
+      removals: [],
+      syncedAt: "2026-01-01T00:00:00Z",
+    });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    let state = readLastSync();
+    assert.ok(state.skills["alice/stable"]);
+    assert.ok(state.skills["alice/churning"]);
+
+    // Sync 2: server returns ONLY the changed skill (delta). The
+    // stable skill is untouched. Note: production runSync sends
+    // `since` based on the persisted syncedAt; the mock server
+    // doesn't filter by `since`, so the test mimics the delta-only
+    // server response shape directly.
+    server.setEtag('"sync2"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "churning", "1.1.0")],
+      removals: [],
+      syncedAt: "2026-01-02T00:00:00Z",
+    });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    state = readLastSync();
+    assert.ok(
+      state.skills["alice/stable"],
+      "stable skill's entry must survive a delta sync that didn't return it",
+    );
+    assert.equal(state.skills["alice/churning"].version, "1.1.0");
+  });
+
+  it("three detected vendors all receive the skill (proves verbatim passthrough)", async () => {
+    // Earlier integration tests only cover two vendors. A hardcoded
+    // `["claudeCode", "cursor"]` impl would pass those — it would
+    // even produce both placements. This test forces three vendors
+    // (claudeCode + cursor + windsurf via CURSOR_AGENT + CLAUDECODE
+    // + the windsurf home signal). Detection returns three entries
+    // and `update` must write to all three.
+    process.env.CLAUDECODE = "1";
+    // Cursor needs its env signal AND its settings.json equivalent
+    // (cursor's home signal is `.cursor` which is a dir — cursor
+    // doesn't have the same `.claude` poisoning issue because we
+    // never write into `~/.cursor`).
+    process.env.CURSOR_AGENT = "1";
+    // Trigger windsurf detection via its home signal
+    // (`~/.codeium/windsurf/`). The dir-existing signal is the
+    // documented detection mechanism per the registry.
+    mkdirSync(join(process.env.HOME, ".codeium", "windsurf"), {
+      recursive: true,
+    });
+
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "everywhere", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-01-01T00:00:00Z",
+    });
+
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    // All three vendors' placements must exist on disk. claudeCode
+    // writes to `.claude/skills/`. cursor + windsurf both share the
+    // `.agents/skills/` cohort placement target — one physical
+    // write satisfies both (placementTargetsFor dedupes by target).
+    assert.ok(existsSync(resolvePlacementDir("claudeProject", "everywhere")));
+    assert.ok(existsSync(resolvePlacementDir("agentsProject", "everywhere")));
+
+    // List walks every detected vendor independently. claudeCode,
+    // cursor, AND windsurf all have project targets (windsurf's
+    // project target is `agentsProject` per the registry — windsurf
+    // joins the cohort for project-scope skills, even though its
+    // personal-scope placement is at `~/.codeium/windsurf/skills/`).
+    // All three must appear in the JSON output, all `current`.
+    stdout = createCaptureStream();
+    await runList(["--key", VALID_KEY, "--url", serverUrl, "--json"], { stdout });
+    const [item] = JSON.parse(stdout.text());
+    assert.equal(item.state, "current");
+    const vendors = item.placements.map((p) => p.vendor).sort();
+    assert.deepEqual(
+      vendors,
+      ["claudeCode", "cursor", "windsurf"],
+      "list must walk every detected vendor (3 in this case — proves no hardcoded pair)",
+    );
+    for (const p of item.placements) {
+      assert.equal(p.state, "current");
+    }
+  });
+});
+
+// ───────────────────────────────────────────────────────────────────────
+// Upgrade-path scenarios — the bugs the fresh-sandbox tests cannot see
+// ───────────────────────────────────────────────────────────────────────
+//
+// The 4.5.0 → 4.5.1 production-readiness audit missed a real user-facing
+// bug because every test in this file (and every reviewer-spawned
+// verification) ran in a freshly-created sandbox. The actual user
+// upgrade path is different: pre-existing `.last-sync` written by the
+// old CLI, then run the new CLI, expect new behavior to take effect.
+//
+// The specific bug: `runSync`'s ETag short-circuit fires when the
+// server hasn't changed library content since the last sync — but if
+// the local detected-vendor set has EXPANDED since that sync (the
+// classic 4.5.0 → 4.5.1 transition: claudeCode-only → all-detected),
+// the 304 means the new vendors NEVER receive their skills. User sees
+// "Library is up to date" followed by `list` reporting every skill as
+// MISS for the newly-detected vendors.
+//
+// These tests reproduce that specific scenario by:
+//   1. Seeding `.last-sync` with a state that mimics the old CLI's
+//      output (single-vendor sync, etag X).
+//   2. Setting the detection signals for additional vendors.
+//   3. Running `update` against a server that returns 304 for etag X.
+//   4. Asserting the new vendors' placements were populated anyway.
+
+describe("upgrade path: vendor set expands between syncs (regression for the bug 4.5.1 missed)", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("new vendor detected after prior sync → ETag is dropped and writes fire for the new vendor", async () => {
+    // STEP 1: simulate the 4.5.0 user's state — only claudeCode
+    // detected, sync completed, `.last-sync` has skill SHAs and an
+    // etag.
+    process.env.CLAUDECODE = "1";
+    server.setEtag('"library-v1"');
+    const skill = makeSkill("alice", "shared", "1.0.0");
+    server.setLibraryResponse({
+      skills: [skill],
+      removals: [],
+      syncedAt: "2026-05-01T00:00:00Z",
+    });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    // Sanity: only claudeProject got the write at this point.
+    assert.ok(
+      existsSync(resolvePlacementDir("claudeProject", "shared")),
+      "first sync wrote to claudeProject",
+    );
+    assert.equal(
+      existsSync(resolvePlacementDir("agentsProject", "shared")),
+      false,
+      "first sync did NOT write to agentsProject (cursor not detected yet)",
+    );
+
+    // STEP 2: simulate the user installing Cursor — env signal fires
+    // on the NEXT `update` invocation. The library content has not
+    // changed on the server, so the server will return 304.
+    process.env.CURSOR_AGENT = "1";
+
+    // Mock server keeps the same etag → If-None-Match match → 304.
+    // No need to change the library response: the 304 branch in
+    // runSync skips reading the body anyway.
+
+    // STEP 3: run update. Pre-fix: short-circuits on 304, no writes
+    // to cursor, user sees "Library is up to date" but cursor's
+    // placement remains empty.
+    server.resetLibraryInspection();
+    stdout = createCaptureStream();
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    // STEP 4: assert. THIS IS THE LOAD-BEARING CHECK.
+    // The newly-detected cursor vendor's placement MUST exist after
+    // the second `update`, even though the server responded 304.
+    // Pre-fix this assertion fails.
+    assert.ok(
+      existsSync(resolvePlacementDir("agentsProject", "shared")),
+      "agentsProject placement MUST exist after a 304 sync when cursor was newly detected — " +
+        "the ETag short-circuit must not prevent writes to vendors absent from the prior sync",
+    );
+    // Wire-level proof: the client did NOT send If-None-Match — the
+    // placement-presence check correctly forced a full re-fetch.
+    // Without this assertion, a regression that still sent the ETag
+    // but happened to re-write to cursor via some unrelated code
+    // path would pass the disk check above silently. See QA Gap 2.
+    assert.equal(
+      server.getLastLibraryIfNoneMatch(),
+      null,
+      "client must NOT have sent If-None-Match — placement-presence check should have dropped it",
+    );
+
+    // Confirm `list` agrees: every detected vendor reports current.
+    stdout = createCaptureStream();
+    await runList(
+      ["--key", VALID_KEY, "--url", serverUrl, "--json"],
+      { stdout },
+    );
+    const [item] = JSON.parse(stdout.text());
+    assert.equal(
+      item.state,
+      "current",
+      "list must show current after the upgrade-path sync — not MISS",
+    );
+    assert.equal(item.placements.length, 2);
+    for (const p of item.placements) {
+      assert.equal(p.state, "current");
+    }
+  });
+
+  it("vendor set unchanged across syncs → 304 short-circuit still fires (no wasted full re-fetch)", async () => {
+    // Defense-in-depth: the fix must NOT invalidate the 304 unless
+    // the placement set actually changed. A user who runs `update`
+    // twice in a row with the same vendors should still benefit from
+    // the 304 fast path. The assertion is BOTH the user-visible "up
+    // to date" output AND the wire-level `If-None-Match` header —
+    // otherwise a future regression that broke the ETag header but
+    // happened to produce the same output (e.g., full re-fetch with
+    // zero deltas) would pass this test silently. See QA reviewer
+    // Gap 2.
+    process.env.CLAUDECODE = "1";
+    process.env.CURSOR_AGENT = "1";
+    server.setEtag('"library-v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "unchanged", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-05-01T00:00:00Z",
+    });
+
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    // Second run with the SAME vendor set — should 304 and produce
+    // the "up to date" message (no writes needed).
+    server.resetLibraryInspection();
+    stdout = createCaptureStream();
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    assert.match(
+      stdout.text(),
+      /up to date/,
+      "same vendor set + same library = 304 fast path still fires",
+    );
+    // Wire-level proof: the client actually sent If-None-Match.
+    // Without this, a regression that broke the conditional request
+    // but produced the same output would slip past output-only
+    // assertions.
+    assert.equal(
+      server.getLastLibraryIfNoneMatch(),
+      '"library-v1"',
+      "second sync MUST have sent If-None-Match: <prior-etag> — the ETag fast path is load-bearing",
+    );
+  });
+
+  it("--global sync followed by project sync → project placement gets populated", async () => {
+    // Edge case the vendor-set tracking alone misses: same vendors,
+    // different scope. The user runs `update --global` (writes to
+    // ~/.claude/skills/), then runs `update` with no flag (writes to
+    // <cwd>/.claude/skills/). Same vendor key (claudeCode) but
+    // entirely different placement directory. A naive syncedVendors
+    // check would say "set unchanged" → 304 → no writes → project
+    // placement empty → list shows MISS.
+    //
+    // The proper contract: invalidate the ETag whenever the resolved
+    // placement directories for the current sync don't ALL contain
+    // the skills they should. That covers vendor-set expansion AND
+    // scope changes AND cwd switches.
+    process.env.CLAUDECODE = "1";
+    server.setEtag('"library-v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "scope-test", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-05-01T00:00:00Z",
+    });
+
+    // First sync: --global → ~/.claude/skills/ (claudeGlobal target).
+    await runUpdate(
+      ["--key", VALID_KEY, "--url", serverUrl, "--global"],
+      { stdout },
+    );
+    assert.ok(
+      existsSync(resolvePlacementDir("claudeGlobal", "scope-test")),
+      "first sync wrote to claudeGlobal",
+    );
+    assert.equal(
+      existsSync(resolvePlacementDir("claudeProject", "scope-test")),
+      false,
+      "first sync did NOT write to claudeProject (no --global flag inverted)",
+    );
+
+    // Second sync: no --global → <cwd>/.claude/skills/ (claudeProject).
+    // Same vendor (claudeCode), same library content (304 from server),
+    // but the destination directory is completely different. Without
+    // the fix, the 304 short-circuit fires and claudeProject stays
+    // empty.
+    stdout = createCaptureStream();
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    // THE LOAD-BEARING CHECK: claudeProject must exist after the
+    // project-scope sync, even though the server 304'd.
+    assert.ok(
+      existsSync(resolvePlacementDir("claudeProject", "scope-test")),
+      "claudeProject placement MUST exist after a 304 sync when the prior sync " +
+        "was --global — the ETag short-circuit must not skip writes when the " +
+        "resolved placement directory is empty",
+    );
+  });
+
+  it("cwd switch between syncs → second project's placement gets populated", async () => {
+    // Same bug class as the --global swap. User runs `update` in
+    // project A, then runs `update` in project B. Both projects use
+    // the same `.last-sync` (lives in HOME, not project) but the
+    // placement directories are cwd-dependent. Without the fix, the
+    // second project sees a 304 and never gets its placements.
+    process.env.CLAUDECODE = "1";
+    server.setEtag('"library-v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "cwd-test", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-05-01T00:00:00Z",
+    });
+
+    // First sync in project A.
+    const projectA = process.cwd();
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    assert.ok(
+      existsSync(resolvePlacementDir("claudeProject", "cwd-test")),
+      "first sync populated project A's placement",
+    );
+
+    // Switch to project B (a separate temp directory inside the same
+    // sandbox so the home-scoped `.last-sync` is shared).
+    const projectB = join(sandbox, "project-b");
+    mkdirSync(projectB, { recursive: true });
+    process.chdir(projectB);
+
+    try {
+      // Same library content, same vendor — server still 304s. Without
+      // the fix, no writes to project B.
+      stdout = createCaptureStream();
+      await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+      assert.ok(
+        existsSync(resolvePlacementDir("claudeProject", "cwd-test")),
+        "project B's claudeProject placement MUST exist after sync — " +
+          "ETag short-circuit must not skip writes when the cwd changed",
+      );
+    } finally {
+      process.chdir(projectA);
+    }
+  });
+
+  it("partial baseline recovery: delete 1 of 5 skills' placements → ETag dropped, all re-fetched (QA Gap 1)", async () => {
+    // Most probable failure mode in normal use: user has many
+    // skills, manually deletes one (or a cleanup script trims a
+    // skill they removed), then runs `update`. The library is
+    // unchanged on the server (304), but the placement-presence
+    // check sees the missing dir and forces a full re-fetch. This
+    // restores every skill in one round. The wire-level check
+    // proves the ETag was DROPPED, not silently sent and ignored.
+    process.env.CLAUDECODE = "1";
+    server.setEtag('"library-v1"');
+    server.setLibraryResponse({
+      skills: [
+        makeSkill("alice", "skill-1", "1.0.0"),
+        makeSkill("alice", "skill-2", "1.0.0"),
+        makeSkill("alice", "skill-3", "1.0.0"),
+        makeSkill("alice", "skill-4", "1.0.0"),
+        makeSkill("alice", "skill-5", "1.0.0"),
+      ],
+      removals: [],
+      syncedAt: "2026-05-01T00:00:00Z",
+    });
+
+    // Sync — all 5 land.
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    for (const n of ["skill-1", "skill-2", "skill-3", "skill-4", "skill-5"]) {
+      assert.ok(existsSync(resolvePlacementDir("claudeProject", n)));
+    }
+
+    // User deletes ONE skill — `skill-3`.
+    rmSync(resolvePlacementDir("claudeProject", "skill-3"), {
+      recursive: true,
+      force: true,
+    });
+
+    server.resetLibraryInspection();
+    stdout = createCaptureStream();
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    // `skill-3` is restored. The other 4 are untouched (idempotent
+    // write — same content, same SHA).
+    assert.ok(
+      existsSync(resolvePlacementDir("claudeProject", "skill-3")),
+      "deleted skill must be restored after self-healing sync",
+    );
+    for (const n of ["skill-1", "skill-2", "skill-4", "skill-5"]) {
+      assert.ok(
+        existsSync(resolvePlacementDir("claudeProject", n)),
+        `${n} must remain present (no collateral damage)`,
+      );
+    }
+    // Wire-level: ETag was dropped — placement-presence check fired.
+    assert.equal(
+      server.getLastLibraryIfNoneMatch(),
+      null,
+      "ETag MUST have been dropped — placement-presence check found the missing skill-3 dir",
+    );
+  });
+
+  it("multi-vendor + manual delete of ONE vendor's placement → next update self-heals", async () => {
+    // Real-world scenario flagged by reviewer: a user with two
+    // vendors syncs successfully, then manually deletes one
+    // vendor's placement directory (rm -rf the cohort dir, or a
+    // hostile cleanup script touched it). The `.last-sync` baseline
+    // and the OTHER vendor's placement are intact, so the server
+    // would 304. Without the placement-presence check, the deleted
+    // vendor's placement would stay empty forever — list would show
+    // MISS for every skill at that vendor.
+    //
+    // The placement-presence check sees the missing claudeProject
+    // SKILL.md and forces a re-fetch, restoring both vendors'
+    // placements in one round. This is the "self-healing" property
+    // of the fix.
+    process.env.CLAUDECODE = "1";
+    process.env.CURSOR_AGENT = "1";
+    server.setEtag('"library-v1"');
+    server.setLibraryResponse({
+      skills: [
+        makeSkill("alice", "a", "1.0.0"),
+        makeSkill("alice", "b", "1.0.0"),
+      ],
+      removals: [],
+      syncedAt: "2026-05-01T00:00:00Z",
+    });
+
+    // Initial sync — both vendors get both skills.
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    assert.ok(existsSync(resolvePlacementDir("claudeProject", "a")));
+    assert.ok(existsSync(resolvePlacementDir("agentsProject", "a")));
+    assert.ok(existsSync(resolvePlacementDir("claudeProject", "b")));
+    assert.ok(existsSync(resolvePlacementDir("agentsProject", "b")));
+
+    // User manually nukes the entire claudeProject cohort. cursor's
+    // placement at .agents/skills/ remains.
+    rmSync(resolvePlacementDir("claudeProject", "a"), {
+      recursive: true,
+      force: true,
+    });
+    rmSync(resolvePlacementDir("claudeProject", "b"), {
+      recursive: true,
+      force: true,
+    });
+
+    // Next update — server still 304s (same etag) — but the
+    // placement-presence check fires on missing claudeProject
+    // SKILL.md and forces full re-fetch.
+    stdout = createCaptureStream();
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    assert.ok(
+      existsSync(resolvePlacementDir("claudeProject", "a")),
+      "claudeProject `a` must be restored after self-healing sync",
+    );
+    assert.ok(
+      existsSync(resolvePlacementDir("claudeProject", "b")),
+      "claudeProject `b` must be restored after self-healing sync",
+    );
+    // cursor's placements were never touched.
+    assert.ok(existsSync(resolvePlacementDir("agentsProject", "a")));
+    assert.ok(existsSync(resolvePlacementDir("agentsProject", "b")));
+  });
+
+  it("forced re-fetch drops BOTH If-None-Match AND ?since= (BLOCKER from Round 2 code-review)", async () => {
+    // The bug that almost shipped: PR #1575's first iteration dropped
+    // `If-None-Match` when placements were incomplete but kept `since`
+    // unconditionally. Production server filters by
+    // `gt(skills.updatedAt, since)`, so a forced re-fetch would
+    // return an empty delta for any skill not modified within the
+    // window — leaving the newly-discovered missing placement empty
+    // forever. Permanent ETag-miss loop.
+    //
+    // This test makes both wire-level conditions explicit. The
+    // mock server now mirrors production's `since` filter (see
+    // mock-server.mjs change in this commit), so a regression that
+    // re-introduces the bug would fail the FULL-LIBRARY assertion
+    // even before the wire-level check.
+    process.env.CLAUDECODE = "1";
+
+    // Use an OLD updatedAt so the skill would be filtered out by
+    // `since` if the bug regressed. The default "now" timestamp
+    // would mask the issue.
+    server.setEtag('"library-v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "stale-fixture", "1.0.0", "2025-01-01T00:00:00Z")],
+      removals: [],
+      syncedAt: "2026-05-01T00:00:00Z",
+    });
+
+    // First sync: writes the skill to claudeProject.
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    const skillDir = resolvePlacementDir("claudeProject", "stale-fixture");
+    assert.ok(existsSync(join(skillDir, "SKILL.md")));
+
+    // Force the placement-incomplete path: delete the SKILL.md
+    // (placementsAreComplete will return false on next sync).
+    rmSync(skillDir, { recursive: true, force: true });
+
+    // Run update. Pre-fix: ETag dropped, since=2026-05-01 sent,
+    // server filters by `gt(updatedAt='2025-01-01', since='2026-05-01')`,
+    // returns empty skills array, runSync writes nothing, placement
+    // stays empty. Post-fix: BOTH headers dropped, server returns
+    // the full library, runSync re-writes everything.
+    server.resetLibraryInspection();
+    stdout = createCaptureStream();
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    // Outcome assertion: the skill is back on disk.
+    assert.ok(
+      existsSync(join(skillDir, "SKILL.md")),
+      "stale-fixture must be restored — full re-fetch must return it even though updatedAt < syncedAt",
+    );
+
+    // Wire-level assertions: BOTH headers dropped on the forced
+    // re-fetch path. If either is sent, the bug has regressed.
+    assert.equal(
+      server.getLastLibraryIfNoneMatch(),
+      null,
+      "If-None-Match MUST be dropped when placements are incomplete",
+    );
+    assert.equal(
+      server.getLastLibrarySince(),
+      null,
+      "?since= MUST also be dropped — otherwise server filters out unchanged skills " +
+        "and the missing placement stays empty (the BLOCKER from Round 2 code-review)",
+    );
+  });
+
+  it("placement dir exists but SKILL.md is missing (partial placement) → next update self-heals", async () => {
+    // Reviewer-flagged HIGH: `existsSync(dir)` alone would satisfy
+    // the placement-presence check even for an empty/partial
+    // directory. The fix probes for SKILL.md specifically. This
+    // test locks in that behavior: a placement directory that
+    // exists but lacks its SKILL.md is treated as MISSING and
+    // forces a re-fetch.
+    process.env.CLAUDECODE = "1";
+    server.setEtag('"library-v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "partial", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-05-01T00:00:00Z",
+    });
+
+    // Initial sync writes SKILL.md.
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    const dir = resolvePlacementDir("claudeProject", "partial");
+    const skillMd = join(dir, "SKILL.md");
+    assert.ok(existsSync(skillMd));
+
+    // User (or hostile tool) deletes just the SKILL.md, leaving the
+    // directory.
+    rmSync(skillMd);
+    assert.ok(existsSync(dir), "dir still exists");
+    assert.equal(existsSync(skillMd), false, "but SKILL.md is gone");
+
+    // Next update — placement-presence check sees no SKILL.md and
+    // forces re-fetch.
+    stdout = createCaptureStream();
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    assert.ok(
+      existsSync(skillMd),
+      "SKILL.md must be restored — empty dirs must not satisfy the placement check",
+    );
+  });
+
+  it("vendor REMOVED from detected set → next update still 304s (no over-eager full re-fetch)", async () => {
+    // Edge case: user uninstalls a tool between syncs. The detected
+    // vendor set shrinks. The library content hasn't changed.
+    // Question: should the next update do a full re-fetch?
+    //
+    // Answer (per the fix's design): no. We only invalidate the ETag
+    // when the vendor set EXPANDED (added vendors need writes). A
+    // shrunk set has no new writes to do — the remaining vendors
+    // already have what they need. The orphaned placements (from
+    // the removed vendor) are left in place; cleaning them up is a
+    // separate concern.
+    //
+    // Pre-fix: same behavior (304 fires regardless of vendor change).
+    // Post-fix: explicit policy — only invalidate on expansion.
+    process.env.CLAUDECODE = "1";
+    process.env.CURSOR_AGENT = "1";
+    server.setEtag('"library-v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "shrinkable", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-05-01T00:00:00Z",
+    });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    // "Uninstall" cursor — drop the env signal.
+    delete process.env.CURSOR_AGENT;
+
+    stdout = createCaptureStream();
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    assert.match(
+      stdout.text(),
+      /up to date/,
+      "shrinking the vendor set should not force a wasteful re-fetch",
+    );
+  });
+});