@indigoai-us/hq-cloud 6.18.44-alpha.48 → 6.18.44-alpha.49

package/dist/cli/doctor.test.js

@@ -0,0 +1,607 @@
+/**
+ * Unit tests for `hq sync doctor` (US-003,
+ * hq-sync-windows-skill-symlink-collision): skill-key family dedupe in the
+ * vault + junk-wrapper GC in the local `.claude/skills/` farm.
+ *
+ * The object store is dependency-injected (`SyncDoctorOptions.store`) with an
+ * in-memory fake, so no test touches a network or a real vault. Local-farm
+ * cases run against a mkdtemp root with real symlinks (the same approach as
+ * s3.symlink-materialize.test.ts) and pin win32 naming via the injectable
+ * `win32` option rather than the host platform.
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { syncDoctor, SKILLS_KEY_PREFIX } from "./doctor.js";
+vi.mock("../sync/mass-delete-guards.js", async (importOriginal) => {
+    const actual = await importOriginal();
+    return { ...actual, resolveMassDeleteGuards: vi.fn().mockResolvedValue(false) };
+});
+import { resolveMassDeleteGuards } from "../sync/mass-delete-guards.js";
+const vaultConfig = {
+    apiUrl: "https://vault-api.test",
+    authToken: "test-jwt-token",
+    region: "us-east-1",
+};
+/**
+ * In-memory DoctorStore. Pages listings two keys at a time so the doctor's
+ * continuation-token loop is exercised by every test, and records every
+ * mutation so dry-run tests can assert "nothing was written".
+ */
+class FakeStore {
+    objects = new Map();
+    puts = [];
+    deletes = [];
+    set(key, body, lastModified, metadata) {
+        this.objects.set(key, {
+            body: Buffer.from(body, "utf-8"),
+            lastModified: new Date(lastModified),
+            metadata,
+        });
+    }
+    async listObjects(input) {
+        const keys = [...this.objects.keys()]
+            .filter((k) => k.startsWith(input.prefix ?? ""))
+            .sort();
+        const start = input.continuationToken ? Number(input.continuationToken) : 0;
+        const page = keys.slice(start, start + 2);
+        return {
+            objects: page.map((key) => ({
+                key,
+                size: this.objects.get(key).body.length,
+                lastModified: this.objects.get(key).lastModified,
+                etag: `"etag-${key}"`,
+            })),
+            nextContinuationToken: start + 2 < keys.length ? String(start + 2) : undefined,
+        };
+    }
+    async getObject(key) {
+        const obj = this.objects.get(key);
+        if (!obj)
+            throw new Error(`NoSuchKey: ${key}`);
+        return { body: obj.body, metadata: obj.metadata };
+    }
+    async putObject(input) {
+        this.puts.push(input.key);
+        this.objects.set(input.key, {
+            body: input.body,
+            lastModified: new Date(),
+            metadata: input.metadata,
+        });
+        return { etag: '"put-etag"' };
+    }
+    async deleteObject(key) {
+        this.deletes.push(key);
+        this.objects.delete(key);
+    }
+}
+const FARM = `${SKILLS_KEY_PREFIX}`;
+describe("syncDoctor — vault skill-key dedupe", () => {
+    let tmpRoot;
+    let store;
+    beforeEach(() => {
+        tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-doctor-test-"));
+        store = new FakeStore();
+        vi.mocked(resolveMassDeleteGuards).mockReset().mockResolvedValue(false);
+        // Keep the plan printer quiet in test output; assertions run against the
+        // returned result, not the console.
+        vi.spyOn(console, "log").mockImplementation(() => { });
+        vi.spyOn(console, "error").mockImplementation(() => { });
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+        fs.rmSync(tmpRoot, { recursive: true, force: true });
+        delete process.env.HQ_SYNC_DELETE_BULK_OVERRIDE;
+    });
+    function run(overrides = {}) {
+        return syncDoctor({
+            entity: "prs_TEST",
+            vaultConfig,
+            hqRoot: tmpRoot,
+            store,
+            win32: true,
+            ...overrides,
+        });
+    }
+    it("flagged release-owned deletion refuses a low-ratio doctor plan", async () => {
+        vi.mocked(resolveMassDeleteGuards).mockResolvedValue(true);
+        const canonical = `${FARM}indigo:design/SKILL.md`;
+        const duplicate = `${FARM}indigo%3Adesign/SKILL.md`;
+        store.set(canonical, "hq-symlink:../old", "2026-07-01T00:00:00Z");
+        store.set(duplicate, "hq-symlink:../new", "2026-07-02T00:00:00Z");
+        for (let index = 0; index < 100; index++) {
+            store.set(`${FARM}indigo:unrelated-${index}/SKILL.md`, "skill body", "2026-07-03T00:00:00Z");
+        }
+        const result = await run({ yes: true });
+        expect(result.keysRewritten).toBe(0);
+        expect(result.keysDeleted).toBe(0);
+        expect(store.puts).toEqual([]);
+        expect(store.deletes).toEqual([]);
+        expect(result.plan.bulkRefused).toBe(false);
+        expect(result.plan.massDeleteGuard).toMatchObject({
+            reason: "release-owned-root", candidates: 1, samplePaths: [duplicate],
+        });
+        expect(store.objects.has(canonical)).toBe(true);
+        expect(store.objects.has(duplicate)).toBe(true);
+    });
+    it("flagged high-volume doctor deletes are refused before mutation", async () => {
+        vi.mocked(resolveMassDeleteGuards).mockResolvedValue(true);
+        const plannedDeletes = 100;
+        for (let index = 0; index < plannedDeletes; index++) {
+            const canonical = `${FARM}indigo:duplicate-${index}/SKILL.md`;
+            const duplicate = `${FARM}indigo%3Aduplicate-${index}/SKILL.md`;
+            store.set(canonical, "same wrapper body", "2026-07-03T00:00:00Z");
+            store.set(duplicate, "same wrapper body", "2026-07-02T00:00:00Z");
+        }
+        for (let index = 0; index < 1_100; index++) {
+            store.set(`${FARM}indigo:unrelated-${index}/SKILL.md`, "skill body", "2026-07-03T00:00:00Z");
+        }
+        const result = await run({ yes: true });
+        // This doctor only deletes under .claude/skills, so its release-root
+        // protection is the decisive reason even when the count reaches the cap.
+        expect(result.keysRewritten).toBe(0);
+        expect(result.keysDeleted).toBe(0);
+        expect(store.puts).toEqual([]);
+        expect(store.deletes).toEqual([]);
+        expect(result.plan.bulkRefused).toBe(false);
+        expect(result.plan.tombstones).toHaveLength(plannedDeletes);
+        expect(result.plan.massDeleteGuard).toMatchObject({
+            reason: "release-owned-root", candidates: plannedDeletes,
+        });
+        expect(store.objects.size).toBe(1_300);
+    });
+    it("the existing explicit doctor override still permits the intended release-owned cleanup", async () => {
+        vi.mocked(resolveMassDeleteGuards).mockResolvedValue(true);
+        const canonical = `${FARM}indigo:design/SKILL.md`;
+        const duplicate = `${FARM}indigo%3Adesign/SKILL.md`;
+        store.set(canonical, "hq-symlink:../same", "2026-07-02T00:00:00Z");
+        store.set(duplicate, "hq-symlink:../same", "2026-07-01T00:00:00Z");
+        const result = await run({ yes: true, bulkDeleteOverride: true });
+        expect(result.plan.massDeleteGuard).toBeUndefined();
+        expect(result.keysDeleted).toBe(1);
+        expect(store.deletes).toEqual([duplicate]);
+        expect(store.objects.has(canonical)).toBe(true);
+        expect(store.objects.has(duplicate)).toBe(false);
+        expect(resolveMassDeleteGuards).not.toHaveBeenCalled();
+    });
+    it("groups 3+ encoded generations into one canonical family and (re)writes the missing ':' key from the newest body", async () => {
+        // Three junk generations of the same logical wrapper, no canonical key.
+        // %3A -> %253A -> %25253A all decode (to fixpoint) to ':'.
+        store.set(`${FARM}eng%3Aarchitect/SKILL.md`, "hq-symlink:../a", "2026-07-01T00:00:00Z");
+        store.set(`${FARM}eng%253Aarchitect/SKILL.md`, "hq-symlink:../b", "2026-07-02T00:00:00Z");
+        store.set(`${FARM}eng%25253Aarchitect/SKILL.md`, "hq-symlink:../c", "2026-07-03T00:00:00Z");
+        const res = await run({ yes: true });
+        // One family; the newest-bodied spelling (%25253A generation) wins.
+        expect(res.plan.rewrites).toEqual([
+            {
+                key: `${FARM}eng:architect/SKILL.md`,
+                fromSpelling: `${FARM}eng%25253Aarchitect/SKILL.md`,
+            },
+        ]);
+        expect(res.keysRewritten).toBe(1);
+        expect(store.objects.get(`${FARM}eng:architect/SKILL.md`).body.toString("utf-8")).toBe("hq-symlink:../c");
+        // Every non-canonical spelling is tombstoned (marker bodies = safe).
+        expect(res.plan.tombstones.sort()).toEqual([
+            `${FARM}eng%25253Aarchitect/SKILL.md`,
+            `${FARM}eng%253Aarchitect/SKILL.md`,
+            `${FARM}eng%3Aarchitect/SKILL.md`,
+        ]);
+        expect(res.keysDeleted).toBe(3);
+        expect([...store.objects.keys()]).toEqual([`${FARM}eng:architect/SKILL.md`]);
+        expect(res.plan.manualReview).toEqual([]);
+    });
+    it("newest-wins: a junk spelling newer than the canonical key rewrites the canonical body", async () => {
+        store.set(`${FARM}indigo:capture/scripts`, "hq-symlink:../old", "2026-07-01T00:00:00Z");
+        store.set(`${FARM}indigo%3Acapture/scripts`, "hq-symlink:../new", "2026-07-05T00:00:00Z");
+        const res = await run({ yes: true });
+        expect(res.plan.rewrites).toEqual([
+            {
+                key: `${FARM}indigo:capture/scripts`,
+                fromSpelling: `${FARM}indigo%3Acapture/scripts`,
+            },
+        ]);
+        expect(store.objects.get(`${FARM}indigo:capture/scripts`).body.toString("utf-8")).toBe("hq-symlink:../new");
+        expect(res.plan.tombstones).toEqual([`${FARM}indigo%3Acapture/scripts`]);
+        expect(store.objects.has(`${FARM}indigo%3Acapture/scripts`)).toBe(false);
+    });
+    it("keeps an up-to-date canonical key untouched when its body is already the newest", async () => {
+        store.set(`${FARM}indigo:recall/SKILL.md`, "hq-symlink:../t", "2026-07-05T00:00:00Z");
+        store.set(`${FARM}indigo%3Arecall/SKILL.md`, "hq-symlink:../t", "2026-07-01T00:00:00Z");
+        const res = await run({ yes: true });
+        expect(res.plan.rewrites).toEqual([]);
+        expect(res.plan.keep).toContain(`${FARM}indigo:recall/SKILL.md`);
+        expect(store.puts).toEqual([]);
+        expect(res.plan.tombstones).toEqual([`${FARM}indigo%3Arecall/SKILL.md`]);
+    });
+    it("safety gate: a non-marker body that differs from the canonical twin goes to manual review, never deleted", async () => {
+        // Canonical is newest (so the junk spelling is NOT the winner); the junk
+        // body is real content, not a symlink marker, and differs byte-wise.
+        store.set(`${FARM}indigo:notes/SKILL.md`, "canonical content", "2026-07-05T00:00:00Z");
+        store.set(`${FARM}indigo%3Anotes/SKILL.md`, "divergent real content", "2026-07-01T00:00:00Z");
+        const res = await run({ yes: true });
+        expect(res.plan.tombstones).toEqual([]);
+        expect(res.keysDeleted).toBe(0);
+        expect(res.plan.manualReview).toEqual([
+            {
+                key: `${FARM}indigo%3Anotes/SKILL.md`,
+                reason: "body is neither a symlink marker nor byte-identical to the canonical key — not auto-deleted",
+            },
+        ]);
+        // The divergent object is still in the store — surfaced, not removed.
+        expect(store.objects.has(`${FARM}indigo%3Anotes/SKILL.md`)).toBe(true);
+    });
+    it("safety gate: a non-marker body byte-identical to the canonical twin IS safe to delete", async () => {
+        store.set(`${FARM}indigo:notes/SKILL.md`, "same real content", "2026-07-05T00:00:00Z");
+        store.set(`${FARM}indigo%3Anotes/SKILL.md`, "same real content", "2026-07-01T00:00:00Z");
+        const res = await run({ yes: true });
+        expect(res.plan.tombstones).toEqual([`${FARM}indigo%3Anotes/SKILL.md`]);
+        expect(res.keysDeleted).toBe(1);
+        expect(res.plan.manualReview).toEqual([]);
+    });
+    it("a body-fetch failure is a loud non-fatal skip: the spelling lands in manual review and the run continues", async () => {
+        store.set(`${FARM}indigo:ok/SKILL.md`, "hq-symlink:../t", "2026-07-05T00:00:00Z");
+        store.set(`${FARM}indigo%3Aok/SKILL.md`, "hq-symlink:../t", "2026-07-01T00:00:00Z");
+        const failingKey = `${FARM}indigo%253Aok/SKILL.md`;
+        store.set(failingKey, "hq-symlink:../t", "2026-07-02T00:00:00Z");
+        const realGet = store.getObject.bind(store);
+        vi.spyOn(store, "getObject").mockImplementation(async (key) => {
+            if (key === failingKey)
+                throw new Error("simulated 500");
+            return realGet(key);
+        });
+        const res = await run({ yes: true });
+        expect(res.plan.manualReview).toEqual([
+            { key: failingKey, reason: "body fetch failed — bytes unknown, not touched" },
+        ]);
+        expect(res.warnings).toBeGreaterThan(0);
+        // The healthy sibling was still processed.
+        expect(res.plan.tombstones).toEqual([`${FARM}indigo%3Aok/SKILL.md`]);
+    });
+    it("does not delete a family's tombstones when its canonical rewrite failed (the junk spelling may hold the only body)", async () => {
+        // Newest (only) body lives at the junk spelling; canonical key is absent,
+        // so applying requires rewrite-then-delete. Fail the rewrite: the delete
+        // leg must skip this family's tombstones or the only copy is lost.
+        store.set(`${FARM}eng%3Afoo/SKILL.md`, "hq-symlink:../only", "2026-07-01T00:00:00Z");
+        const put = store.putObject.bind(store);
+        vi.spyOn(store, "putObject").mockImplementation(async (input) => {
+            if (input.key === `${FARM}eng:foo/SKILL.md`)
+                throw new Error("503 SlowDown");
+            return put(input);
+        });
+        const res = await run({ yes: true });
+        expect(res.keysRewritten).toBe(0);
+        expect(res.keysDeleted).toBe(0);
+        expect(store.deletes).toEqual([]);
+        expect(store.objects.has(`${FARM}eng%3Afoo/SKILL.md`)).toBe(true);
+        expect(res.warnings).toBeGreaterThanOrEqual(2); // failed rewrite + skipped delete
+    });
+    it("colon-free percent spellings are their own canonical: no rewrite, no move, no delete (round-9)", async () => {
+        // A legitimate skill whose NAME contains a percent escape must never be
+        // 'collapsed' into the decoded name — that would move/delete real
+        // content. Both spellings coexist as independent keys.
+        store.set(`${FARM}foo%20bar/SKILL.md`, "real skill content", "2026-07-01T00:00:00Z");
+        store.set(`${FARM}foo bar/SKILL.md`, "a different real skill", "2026-07-01T00:00:00Z");
+        const res = await run({ yes: true });
+        expect(res.plan.rewrites).toEqual([]);
+        expect(res.plan.tombstones).toEqual([]);
+        expect(res.keysDeleted).toBe(0);
+        expect(store.objects.has(`${FARM}foo%20bar/SKILL.md`)).toBe(true);
+        expect(store.objects.has(`${FARM}foo bar/SKILL.md`)).toBe(true);
+        expect(res.plan.keep.sort()).toEqual([
+            `${FARM}foo bar/SKILL.md`,
+            `${FARM}foo%20bar/SKILL.md`,
+        ]);
+    });
+    it("fences canonical rewrites with CAS: ifNoneMatch:'*' when absent, ifMatch:<listed etag> when stale", async () => {
+        store.set(`${FARM}eng%3Acasnew/SKILL.md`, "hq-symlink:../a", "2026-07-01T00:00:00Z");
+        store.set(`${FARM}eng:casstale/SKILL.md`, "hq-symlink:../old", "2026-07-01T00:00:00Z");
+        store.set(`${FARM}eng%3Acasstale/SKILL.md`, "hq-symlink:../new", "2026-07-02T00:00:00Z");
+        const putSpy = vi.spyOn(store, "putObject");
+        await run({ yes: true });
+        const puts = putSpy.mock.calls.map((c) => c[0]);
+        const created = puts.find((p) => p.key === `${FARM}eng:casnew/SKILL.md`);
+        expect(created.ifNoneMatch).toBe("*");
+        expect(created.ifMatch).toBeUndefined();
+        const updated = puts.find((p) => p.key === `${FARM}eng:casstale/SKILL.md`);
+        expect(updated.ifMatch).toBe(`"etag-${FARM}eng:casstale/SKILL.md"`);
+        expect(updated.ifNoneMatch).toBeUndefined();
+    });
+    it("a 412 precondition failure on the rewrite keeps the family's tombstones (no clobber, no orphaned delete)", async () => {
+        store.set(`${FARM}eng:casrace/SKILL.md`, "hq-symlink:../old", "2026-07-01T00:00:00Z");
+        store.set(`${FARM}eng%3Acasrace/SKILL.md`, "hq-symlink:../new", "2026-07-02T00:00:00Z");
+        vi.spyOn(store, "putObject").mockImplementation(async () => {
+            throw Object.assign(new Error("PreconditionFailed"), { $metadata: { httpStatusCode: 412 } });
+        });
+        const res = await run({ yes: true });
+        expect(res.keysRewritten).toBe(0);
+        expect(res.keysDeleted).toBe(0);
+        expect(store.objects.has(`${FARM}eng%3Acasrace/SKILL.md`)).toBe(true);
+        expect(res.warnings).toBeGreaterThanOrEqual(2);
+    });
+    it("parks the whole family when the canonical body fetch fails — no rewrite from a junk sibling, no deletes", async () => {
+        // Round-4 review P1: a transient/403 canonical read must not let the
+        // newest junk sibling overwrite unknown canonical bytes.
+        store.set(`${FARM}eng:parked/SKILL.md`, "possibly-real user content", "2026-07-01T00:00:00Z");
+        store.set(`${FARM}eng%3Aparked/SKILL.md`, "hq-symlink:../newer", "2026-07-02T00:00:00Z");
+        const get = store.getObject.bind(store);
+        vi.spyOn(store, "getObject").mockImplementation(async (key) => {
+            if (key === `${FARM}eng:parked/SKILL.md`)
+                throw new Error("403 slow down");
+            return get(key);
+        });
+        const res = await run({ yes: true });
+        expect(res.plan.rewrites).toEqual([]);
+        expect(res.plan.tombstones).toEqual([]);
+        expect(res.keysRewritten).toBe(0);
+        expect(res.keysDeleted).toBe(0);
+        expect(res.plan.manualReview).toEqual(expect.arrayContaining([
+            {
+                key: `${FARM}eng:parked/SKILL.md`,
+                reason: "body fetch failed — bytes unknown, not touched",
+            },
+            {
+                key: `${FARM}eng%3Aparked/SKILL.md`,
+                reason: "canonical body unknown (fetch failed) — family not touched",
+            },
+        ]));
+        expect(store.objects.has(`${FARM}eng:parked/SKILL.md`)).toBe(true);
+        expect(store.objects.has(`${FARM}eng%3Aparked/SKILL.md`)).toBe(true);
+    });
+    it("bulk-asymmetry guard: a large delete plan is refused without an explicit override (policy sync-delete-bulk-asymmetry-guard)", async () => {
+        // 12 families, each canonical + one identical junk twin: 12 tombstones out
+        // of 24 in-scope keys (50% >= 10%, 12 >= 10) — the breaker must trip.
+        for (let i = 0; i < 12; i++) {
+            store.set(`${FARM}ns:skill-${i}/SKILL.md`, `hq-symlink:../${i}`, "2026-07-05T00:00:00Z");
+            store.set(`${FARM}ns%3Askill-${i}/SKILL.md`, `hq-symlink:../${i}`, "2026-07-01T00:00:00Z");
+        }
+        const refused = await run({ yes: true });
+        expect(refused.plan.bulkRefused).toBe(true);
+        expect(refused.plan.tombstones).toHaveLength(12);
+        expect(refused.keysDeleted).toBe(0);
+        expect(store.deletes).toEqual([]);
+        // Explicit override flag applies the same plan.
+        const applied = await run({ yes: true, bulkDeleteOverride: true });
+        expect(applied.plan.bulkRefused).toBe(false);
+        expect(applied.keysDeleted).toBe(12);
+    });
+    it("bulk-asymmetry guard honors the HQ_SYNC_DELETE_BULK_OVERRIDE env rollback knob", async () => {
+        for (let i = 0; i < 12; i++) {
+            store.set(`${FARM}ns:skill-${i}/SKILL.md`, `hq-symlink:../${i}`, "2026-07-05T00:00:00Z");
+            store.set(`${FARM}ns%3Askill-${i}/SKILL.md`, `hq-symlink:../${i}`, "2026-07-01T00:00:00Z");
+        }
+        process.env.HQ_SYNC_DELETE_BULK_OVERRIDE = "1";
+        const res = await run({ yes: true });
+        expect(res.plan.bulkRefused).toBe(false);
+        expect(res.keysDeleted).toBe(12);
+    });
+    it("dry-run is the default: the full plan is produced and NOTHING is written", async () => {
+        store.set(`${FARM}eng%3Aarchitect/SKILL.md`, "hq-symlink:../a", "2026-07-01T00:00:00Z");
+        store.set(`${FARM}eng%253Aarchitect/SKILL.md`, "hq-symlink:../b", "2026-07-02T00:00:00Z");
+        // Junk local wrapper next to its canonical twin, GC-eligible.
+        const skillsDir = path.join(tmpRoot, ".claude", "skills");
+        fs.mkdirSync(path.join(skillsDir, "eng%3Aarchitect"), { recursive: true });
+        const junkDir = path.join(skillsDir, "eng%25253Aarchitect");
+        fs.mkdirSync(junkDir);
+        fs.writeFileSync(path.join(tmpRoot, "target.md"), "x");
+        fs.symlinkSync(path.join(tmpRoot, "target.md"), path.join(junkDir, "link.md"));
+        const res = await run(); // no `yes`
+        // Plan is fully populated…
+        expect(res.plan.rewrites).toHaveLength(1);
+        expect(res.plan.tombstones).toHaveLength(2);
+        expect(res.plan.localRemovals).toEqual([junkDir]);
+        // …but nothing was applied: no puts, no deletes, junk dir still on disk.
+        expect(res.applied).toBe(false);
+        expect(store.puts).toEqual([]);
+        expect(store.deletes).toEqual([]);
+        expect(store.objects.has(`${FARM}eng%3Aarchitect/SKILL.md`)).toBe(true);
+        expect(fs.existsSync(junkDir)).toBe(true);
+        expect(res.keysRewritten).toBe(0);
+        expect(res.keysDeleted).toBe(0);
+        expect(res.dirsRemoved).toBe(0);
+    });
+});
+describe("syncDoctor — local skill-farm GC", () => {
+    let tmpRoot;
+    let skillsDir;
+    let store;
+    beforeEach(() => {
+        tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-doctor-gc-test-"));
+        skillsDir = path.join(tmpRoot, ".claude", "skills");
+        fs.mkdirSync(skillsDir, { recursive: true });
+        store = new FakeStore();
+        vi.spyOn(console, "log").mockImplementation(() => { });
+        vi.spyOn(console, "error").mockImplementation(() => { });
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+        fs.rmSync(tmpRoot, { recursive: true, force: true });
+    });
+    function run(overrides = {}) {
+        return syncDoctor({
+            entity: "prs_TEST",
+            vaultConfig,
+            hqRoot: tmpRoot,
+            store,
+            win32: true,
+            ...overrides,
+        });
+    }
+    /** Junk-named dir containing only symlinks — the 134-dirs incident shape. */
+    function makeSymlinkFarmDir(name) {
+        const dir = path.join(skillsDir, name);
+        fs.mkdirSync(dir);
+        const target = path.join(tmpRoot, `${name}-target.md`);
+        fs.writeFileSync(target, "target");
+        fs.symlinkSync(target, path.join(dir, "link.md"));
+        return dir;
+    }
+    it("removes a junk dir whose name decodes to a canonical wrapper that exists on disk (symlink content only)", async () => {
+        // The incident's exact shape: 'hq-pack-engineering%25253Aarchitect'
+        // decodes to 'hq-pack-engineering:architect', whose canonical win32
+        // wrapper 'hq-pack-engineering%3Aarchitect' already exists.
+        fs.mkdirSync(path.join(skillsDir, "hq-pack-engineering%3Aarchitect"));
+        const junk = makeSymlinkFarmDir("hq-pack-engineering%25253Aarchitect");
+        const res = await run({ yes: true });
+        expect(res.plan.localRemovals).toEqual([junk]);
+        expect(res.dirsRemoved).toBe(1);
+        expect(fs.existsSync(junk)).toBe(false);
+        // The canonical wrapper is untouched.
+        expect(fs.existsSync(path.join(skillsDir, "hq-pack-engineering%3Aarchitect"))).toBe(true);
+    });
+    it("refuses a junk dir that contains any real (non-symlink) file — manual review only", async () => {
+        fs.mkdirSync(path.join(skillsDir, "eng%3Aweb"));
+        const junk = path.join(skillsDir, "eng%253Aweb");
+        fs.mkdirSync(junk);
+        fs.writeFileSync(path.join(junk, "real-file.md"), "user data");
+        const res = await run({ yes: true });
+        expect(res.plan.localRemovals).toEqual([]);
+        expect(res.plan.localManualReview).toEqual([
+            { path: junk, reason: "contains real (non-symlink) files — never auto-deleted" },
+        ]);
+        expect(res.dirsRemoved).toBe(0);
+        expect(fs.existsSync(path.join(junk, "real-file.md"))).toBe(true);
+    });
+    it("apply-time recheck: a regular file that replaced a planned entry between plan and apply is never removed", async () => {
+        // The plan/apply race the recheck exists for: planning classifies a junk
+        // SYMLINK entry as removable; before the apply loop reaches it, a sync
+        // pass or user edit replaces it with a REGULAR FILE. printPlan() runs
+        // between the two phases, so the first plan-print callback is the exact
+        // race window — swap the entry there.
+        fs.mkdirSync(path.join(skillsDir, "eng%3Arace"));
+        const junk = path.join(skillsDir, "eng%253Arace");
+        fs.symlinkSync(path.join(skillsDir, "eng%3Arace"), junk);
+        let swapped = false;
+        vi.spyOn(console, "log").mockImplementation(() => {
+            if (swapped)
+                return;
+            swapped = true;
+            try {
+                fs.unlinkSync(junk);
+            }
+            catch {
+                fs.rmdirSync(junk); // win32 directory symlink
+            }
+            fs.writeFileSync(junk, "user data written mid-run");
+        });
+        const res = await run({ yes: true });
+        expect(swapped).toBe(true);
+        expect(res.plan.localRemovals).toEqual([junk]);
+        expect(res.dirsRemoved).toBe(0);
+        expect(fs.readFileSync(junk, "utf-8")).toBe("user data written mid-run");
+        expect(res.warnings).toBeGreaterThanOrEqual(1);
+    });
+    it("refuses a junk-named entry when its canonical wrapper is missing on disk (it may be the only copy)", async () => {
+        const junk = makeSymlinkFarmDir("eng%253Aorphan");
+        const res = await run({ yes: true });
+        expect(res.plan.localRemovals).toEqual([]);
+        expect(res.plan.localManualReview).toEqual([
+            {
+                path: junk,
+                reason: "canonical wrapper 'eng%3Aorphan' missing on disk — junk-named entry may be the only copy",
+            },
+        ]);
+        expect(fs.existsSync(junk)).toBe(true);
+    });
+    it("removes a junk-named entry that is itself a symlink (farm content by definition)", async () => {
+        const target = path.join(tmpRoot, "wrapper-target.md");
+        fs.writeFileSync(target, "t");
+        fs.mkdirSync(path.join(skillsDir, "eng%3Alink"));
+        const junkLink = path.join(skillsDir, "eng%253Alink");
+        fs.symlinkSync(target, junkLink);
+        const res = await run({ yes: true });
+        expect(res.plan.localRemovals).toEqual([junkLink]);
+        expect(res.dirsRemoved).toBe(1);
+        expect(fs.existsSync(junkLink)).toBe(false);
+        // Symlink removal never follows through to the target.
+        expect(fs.existsSync(target)).toBe(true);
+    });
+    it("never GCs a colon-free percent-named wrapper, even when its double-encoded twin exists on disk", async () => {
+        // Codex P2 (round-9 follow-up): `canonicalVaultSegmentSpelling` returns
+        // colon-free names UNCHANGED on purpose — `foo%25bar` is the legitimate
+        // win32 wrapper for the canonical skill name `foo%bar`, not a generation
+        // of a `<ns>:<skill>` amplifier family. Pre-fix, the local GC re-encoded
+        // that already-canonical name for the host (`foo%2525bar`); because that
+        // spelling differs from the entry's own, the entry fell through the
+        // "already canonical" guard and, with a matching double-encoded sibling
+        // on disk, `--yes` deleted the legitimate wrapper. Both spellings here
+        // are their own canonical form, so BOTH must survive untouched.
+        const legit = makeSymlinkFarmDir("foo%25bar");
+        const twin = makeSymlinkFarmDir("foo%2525bar");
+        // A genuine namespaced amplifier family in the same directory proves the
+        // guard is scoped to colon-free names and did not disable the GC.
+        fs.mkdirSync(path.join(skillsDir, "eng%3Aarchitect"));
+        const amplifierJunk = makeSymlinkFarmDir("eng%253Aarchitect");
+        const res = await run({ yes: true });
+        expect(res.plan.localRemovals).toEqual([amplifierJunk]);
+        expect(res.plan.localManualReview).toEqual([]);
+        expect(fs.existsSync(legit)).toBe(true);
+        expect(fs.existsSync(twin)).toBe(true);
+        expect(fs.existsSync(amplifierJunk)).toBe(false);
+    });
+    it("leaves canonical wrapper names and ordinary skill dirs alone", async () => {
+        fs.mkdirSync(path.join(skillsDir, "eng%3Aarchitect")); // canonical win32 wrapper
+        fs.mkdirSync(path.join(skillsDir, "plain-skill")); // no encoding at all
+        const res = await run({ yes: true });
+        expect(res.plan.localRemovals).toEqual([]);
+        expect(res.plan.localManualReview).toEqual([]);
+        expect(fs.existsSync(path.join(skillsDir, "eng%3Aarchitect"))).toBe(true);
+        expect(fs.existsSync(path.join(skillsDir, "plain-skill"))).toBe(true);
+    });
+});
+describe("syncDoctor --reconcile-conflicts (legacy sibling twins)", () => {
+    let tmpRoot;
+    let store;
+    beforeEach(() => {
+        tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-doctor-twins-"));
+        store = new FakeStore();
+        vi.spyOn(console, "log").mockImplementation(() => { });
+        vi.spyOn(console, "error").mockImplementation(() => { });
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+        fs.rmSync(tmpRoot, { recursive: true, force: true });
+    });
+    function put(rel, content) {
+        const abs = path.join(tmpRoot, rel);
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        fs.writeFileSync(abs, content);
+    }
+    it("is local-only, dry-run by default, and applies with --yes without touching the vault", async () => {
+        const live = "companies/acme/policies/p.md";
+        const twin = `${live}.conflict-2026-04-27T22-05-14Z-abc123.md`;
+        put(live, "---\nversion: 8\n---\nolder\n");
+        put(twin, "---\nversion: 10\n---\nnewer\n");
+        // A skills key in the vault proves the dedupe leg is NOT run in this mode.
+        store.set(`${SKILLS_KEY_PREFIX}eng%3Aarchitect/SKILL.md`, "hq-symlink:../a", "2026-07-01T00:00:00Z");
+        const dry = await syncDoctor({
+            entity: "prs_TEST",
+            vaultConfig,
+            hqRoot: tmpRoot,
+            store,
+            reconcileConflicts: true,
+        });
+        expect(dry.applied).toBe(false);
+        expect(dry.conflictTwins?.plan).toHaveLength(1);
+        expect(dry.conflictTwins?.plan[0]).toMatchObject({ action: "promote-twin", livePath: live });
+        expect(dry.plan.inScopeKeys).toBe(0);
+        expect(fs.existsSync(path.join(tmpRoot, twin))).toBe(true);
+        expect(store.puts).toEqual([]);
+        expect(store.deletes).toEqual([]);
+        const applied = await syncDoctor({
+            entity: "prs_TEST",
+            vaultConfig,
+            hqRoot: tmpRoot,
+            store,
+            reconcileConflicts: true,
+            yes: true,
+        });
+        expect(applied.applied).toBe(true);
+        expect(applied.conflictTwins).toMatchObject({ promoted: 1, backedUp: 1 });
+        expect(fs.readFileSync(path.join(tmpRoot, live), "utf8")).toContain("version: 10");
+        expect(fs.existsSync(path.join(tmpRoot, twin))).toBe(false);
+        expect(store.puts).toEqual([]);
+        expect(store.deletes).toEqual([]);
+    });
+});
+//# sourceMappingURL=doctor.test.js.map