@indigoai-us/hq-cloud 6.14.23 → 6.14.24

package/src/cli/sync.test.ts

@@ -53,7 +53,8 @@ vi.mock("./reindex.js", () => ({
   reindex: vi.fn(() => ({ status: 0 })),
 }));
 
-import { sync, reportNewFilesToNotify } from "./sync.js";
+import { sync, reportNewFilesToNotify, win32SymlinkFlavorBroken } from "./sync.js";
+import type { SyncProgressEvent } from "./sync.js";
 import { share } from "./share.js";
 import * as s3Module from "../s3.js";
 import { reindex } from "./reindex.js";
@@ -4613,3 +4614,282 @@ describe("scope-invalid key hardening (companies/ prefix in a company vault —
     expect(fs.existsSync(path.join(tmpDir, "companies", "localco", "notes.md"))).toBe(true);
   });
 });
+
+describe("win32SymlinkFlavorBroken (round-8 flavor-health probe)", () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = fs.mkdtempSync(path.join(os.tmpdir(), "flavor-probe-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("false for a healthy dir link, false for a dangling target, always false off win32", () => {
+    const target = path.join(tmp, "real-dir");
+    fs.mkdirSync(target);
+    const healthy = path.join(tmp, "healthy-link");
+    fs.symlinkSync(target, healthy, "dir");
+    expect(win32SymlinkFlavorBroken(healthy, true)).toBe(false);
+    expect(win32SymlinkFlavorBroken(healthy, false)).toBe(false);
+
+    const dangling = path.join(tmp, "dangling-link");
+    fs.symlinkSync(path.join(tmp, "missing"), dangling);
+    expect(win32SymlinkFlavorBroken(dangling, true)).toBe(false);
+  });
+
+  it.runIf(process.platform === "win32")(
+    "true for a real FILE-flavor link at a DIRECTORY target (the broken shape the repair branch re-downloads)",
+    () => {
+      // Only constructible on Windows: flavor is a win32-only concept. The
+      // physical shape from the incident — link minted 'file' while the
+      // target was absent, target directory created afterwards.
+      const target = path.join(tmp, "late-dir");
+      const link = path.join(tmp, "wrong-flavor-link");
+      fs.symlinkSync(target, link, "file");
+      fs.mkdirSync(target);
+      expect(win32SymlinkFlavorBroken(link, true)).toBe(true);
+    },
+  );
+});
+
+describe("junk key-spelling guard (US-002 mixed-version amplifier)", () => {
+  let tmpDir: string;
+  let stateDir: string;
+  let journalPath: string;
+
+  // Journal keys are company-root-relative; sync() resolves the company to
+  // slug "acme", so entries land in sync-journal.acme.json and materialize
+  // under {hqRoot}/companies/acme/.
+  const canonicalKey = ".claude/skills/indigo:call-prep-brief/scripts";
+  const junkKey = ".claude/skills/indigo%3Acall-prep-brief/scripts";
+
+  function seedJournal(files: Record<string, unknown>): void {
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "2",
+        lastSync: new Date().toISOString(),
+        files,
+        pulls: [],
+      }),
+    );
+  }
+
+  function journalEntry(remoteEtag: string): Record<string, unknown> {
+    return {
+      hash: "0".repeat(64),
+      size: 0,
+      syncedAt: new Date().toISOString(),
+      direction: "up",
+      remoteEtag,
+      kind: "symlink",
+    };
+  }
+
+  async function runSync(): Promise<{
+    events: SyncProgressEvent[];
+    result: Awaited<ReturnType<typeof sync>>;
+  }> {
+    const events: SyncProgressEvent[] = [];
+    const result = await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      skipReindex: true,
+      onEvent: (e) => events.push(e),
+    });
+    return { events, result };
+  }
+
+  beforeEach(() => {
+    clearContextCache();
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-sync-junkkey-test-"));
+    stateDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-state-junkkey-test-"));
+    process.env.HQ_STATE_DIR = stateDir;
+    journalPath = path.join(stateDir, "sync-journal.acme.json");
+    setupFetchMock();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.clearAllMocks();
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+    fs.rmSync(stateDir, { recursive: true, force: true });
+    delete process.env.HQ_STATE_DIR;
+  });
+
+  it("skips a remote %3A twin of an already-journaled canonical key — loudly, never as an error", async () => {
+    seedJournal({ [canonicalKey]: journalEntry("aaa111") });
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      { key: junkKey, size: 20, lastModified: new Date(), etag: '"junk1"' },
+    ]);
+
+    const { events, result } = await runSync();
+
+    // The twin never downloads, never materializes, never journals.
+    expect(vi.mocked(s3Module.downloadFile)).not.toHaveBeenCalled();
+    const skips = events.filter((e) => e.type === "skip-junk-key-spelling");
+    expect(skips).toHaveLength(1);
+    expect(skips[0]).toMatchObject({ path: junkKey, journaledKey: canonicalKey });
+    // Policy hq-sync-deliberate-skip-not-fatal-error-exit2: a deliberate
+    // per-file skip must never surface as a fatal {type:"error"} event.
+    expect(events.filter((e) => e.type === "error")).toHaveLength(0);
+    expect(result.aborted).toBe(false);
+    expect(result.filesSkipped).toBe(1);
+    const journalAfter = JSON.parse(fs.readFileSync(journalPath, "utf-8")) as {
+      files: Record<string, unknown>;
+    };
+    expect(Object.keys(journalAfter.files)).not.toContain(junkKey);
+  });
+
+  it("still pulls a junk-spelling key that is ALREADY journaled under that exact spelling", async () => {
+    // Pre-existing fork (both machines journaled the %3A family before the
+    // guard shipped): the established spelling keeps syncing untouched —
+    // collapsing the family is the vault doctor's job (US-003), not the
+    // planner's.
+    seedJournal({ [junkKey]: journalEntry("aaa111") });
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      { key: junkKey, size: 20, lastModified: new Date(), etag: '"bbb222"' },
+    ]);
+
+    const { events, result } = await runSync();
+
+    expect(vi.mocked(s3Module.downloadFile)).toHaveBeenCalledTimes(1);
+    expect(vi.mocked(s3Module.downloadFile).mock.calls[0]![1]).toBe(junkKey);
+    expect(events.filter((e) => e.type === "skip-junk-key-spelling")).toHaveLength(0);
+    expect(result.filesDownloaded).toBe(1);
+  });
+
+  it("downloads a %3A key with NO journaled twin — the guard needs an established spelling to defend", async () => {
+    seedJournal({});
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      { key: junkKey, size: 20, lastModified: new Date(), etag: '"junk1"' },
+    ]);
+
+    const { events, result } = await runSync();
+
+    expect(vi.mocked(s3Module.downloadFile)).toHaveBeenCalledTimes(1);
+    expect(events.filter((e) => e.type === "skip-junk-key-spelling")).toHaveLength(0);
+    expect(result.filesDownloaded).toBe(1);
+  });
+
+  it("an exact FILE_TOMBSTONE for the journaled canonical key beats the junk-twin protection (authoritative delete propagates)", async () => {
+    // Round-7 review P2: a deliberately-deleted wrapper must not be kept
+    // alive by a stale junk spelling lingering in the LIST.
+    seedJournal({ [canonicalKey]: journalEntry("aaa111") });
+    setupFetchMock({
+      tombstones: [{ key: canonicalKey, deletedAt: new Date().toISOString() }],
+    });
+    // Earlier suites install persistent keyed headRemoteFile implementations;
+    // the HEAD-verify pass must see the canonical key as absent here.
+    vi.mocked(s3Module.headRemoteFile).mockResolvedValue(null);
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      { key: junkKey, size: 20, lastModified: new Date(), etag: '"junk1"' },
+    ]);
+
+    const { events, result } = await runSync();
+
+    // Junk twin still gated; the canonical journal entry tombstones out.
+    expect(events.filter((e) => e.type === "skip-junk-key-spelling")).toHaveLength(1);
+    expect(result.filesTombstoned).toBe(1);
+    const journalAfter = JSON.parse(fs.readFileSync(journalPath, "utf-8")) as {
+      files: Record<string, unknown>;
+    };
+    expect(Object.keys(journalAfter.files)).not.toContain(canonicalKey);
+  });
+
+  it("always downloads a CANONICAL remote key even when the journal holds only its junk twin (post-doctor convergence)", async () => {
+    // Round-6 review P1: after `hq sync doctor` collapses the vault to the
+    // canonical spelling, a machine whose journal still carries the junk
+    // spelling must pick the canonical object up — gating it would deadlock
+    // that machine out of the wrapper (and all future updates) forever.
+    seedJournal({ [junkKey]: journalEntry("aaa111") });
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      { key: canonicalKey, size: 20, lastModified: new Date(), etag: '"can1"' },
+    ]);
+
+    const { events, result } = await runSync();
+
+    expect(events.filter((e) => e.type === "skip-junk-key-spelling")).toHaveLength(0);
+    expect(vi.mocked(s3Module.downloadFile)).toHaveBeenCalledTimes(1);
+    expect(vi.mocked(s3Module.downloadFile).mock.calls[0]![1]).toBe(canonicalKey);
+    expect(result.filesDownloaded).toBe(1);
+    const journalAfter = JSON.parse(fs.readFileSync(journalPath, "utf-8")) as {
+      files: Record<string, unknown>;
+    };
+    expect(Object.keys(journalAfter.files)).toContain(canonicalKey);
+  });
+
+  it("does not tombstone a journaled canonical key when the LIST holds only its junk twin", async () => {
+    // Round-4 review P1: skip-junk-key-spelling alone is self-defeating if
+    // the delete-resync pass then classes the canonical journal entry as
+    // remote-deleted (raw remoteKeySet miss) — it would unlink the good
+    // local wrapper and drop the journal entry, and the NEXT pull would
+    // materialize the junk spelling the guard just refused.
+    seedJournal({ [canonicalKey]: journalEntry("aaa111") });
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      { key: junkKey, size: 20, lastModified: new Date(), etag: '"junk1"' },
+    ]);
+
+    const { events, result } = await runSync();
+
+    // Junk twin skipped, canonical entry NOT tombstoned.
+    expect(events.filter((e) => e.type === "skip-junk-key-spelling")).toHaveLength(1);
+    const journalAfter = JSON.parse(fs.readFileSync(journalPath, "utf-8")) as {
+      files: Record<string, unknown>;
+    };
+    expect(Object.keys(journalAfter.files)).toContain(canonicalKey);
+    expect(result.filesTombstoned ?? 0).toBe(0);
+    expect(events.filter((e) => e.type === "error")).toHaveLength(0);
+  });
+
+  it("never gates COLON-FREE skill names — foo%20bar and foo bar are distinct skills (round-9)", async () => {
+    seedJournal({ [".claude/skills/foo bar/SKILL.md"]: journalEntry("aaa111") });
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      { key: ".claude/skills/foo%20bar/SKILL.md", size: 20, lastModified: new Date(), etag: '"pct1"' },
+    ]);
+
+    const { events, result } = await runSync();
+
+    expect(events.filter((e) => e.type === "skip-junk-key-spelling")).toHaveLength(0);
+    expect(vi.mocked(s3Module.downloadFile)).toHaveBeenCalledTimes(1);
+    expect(result.filesDownloaded).toBe(1);
+  });
+
+  it("never gates keys outside .claude/skills/ — percent-decode collisions there are distinct files", async () => {
+    // `notes/a b.md` and `notes/a%20b.md` canonicalize to the same fixpoint
+    // string, but outside the skill farm they are two legitimate files (the
+    // win32 codec encodes the literal '%' as '%25' locally). The guard must
+    // not skip the unjournaled one.
+    seedJournal({ ["notes/a b.md"]: journalEntry("aaa111") });
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      { key: "notes/a%20b.md", size: 20, lastModified: new Date(), etag: '"pct1"' },
+    ]);
+
+    const { events, result } = await runSync();
+
+    expect(vi.mocked(s3Module.downloadFile)).toHaveBeenCalledTimes(1);
+    expect(vi.mocked(s3Module.downloadFile).mock.calls[0]![1]).toBe("notes/a%20b.md");
+    expect(events.filter((e) => e.type === "skip-junk-key-spelling")).toHaveLength(0);
+    expect(result.filesDownloaded).toBe(1);
+  });
+
+  it("keeps syncing BOTH spellings when both are already journaled (no retroactive gating)", async () => {
+    seedJournal({
+      [canonicalKey]: journalEntry("aaa111"),
+      [junkKey]: journalEntry("ccc333"),
+    });
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      { key: canonicalKey, size: 20, lastModified: new Date(), etag: '"bbb222"' },
+      { key: junkKey, size: 20, lastModified: new Date(), etag: '"ddd444"' },
+    ]);
+
+    const { events, result } = await runSync();
+
+    expect(vi.mocked(s3Module.downloadFile)).toHaveBeenCalledTimes(2);
+    expect(events.filter((e) => e.type === "skip-junk-key-spelling")).toHaveLength(0);
+    expect(result.filesDownloaded).toBe(2);
+  });
+});

package/src/cli/sync.ts

@@ -19,7 +19,12 @@ import {
 } from "../telemetry-events.js";
 import { resolveEntityContext, isExpiringSoon, refreshEntityContext } from "../context.js";
 import { createSyncProgressRecorder } from "../sync-progress.js";
-import { localPathForVaultKey, vaultKeyForLocalPath } from "../local-path-codec.js";
+import {
+  canonicalVaultKeySpelling,
+  localPathForVaultKey,
+  vaultKeyForLocalPath,
+} from "../local-path-codec.js";
+import { SKILLS_KEY_PREFIX } from "./doctor.js";
 import {
   downloadFile,
   listRemoteFiles,
@@ -401,6 +406,27 @@ export type SyncProgressEvent =
       path: string;
       /** Server-compatible invalid-key code, such as INVALID_KEY_CONTROL_CHARS. */
       errorCode?: string;
+    }
+  | {
+      /**
+       * Emitted by the PULL leg once per remote key skipped because its
+       * spelling percent-decodes to the same logical path as an
+       * already-journaled key with a DIFFERENT spelling — the mixed-version
+       * amplifier (a pre-codec peer minting `%3A`/`%253A` twins of a
+       * canonical `:` key). Downloading the twin would materialize a junk
+       * local dir and fork the journal into a second key family for one
+       * logical path, so the established spelling wins and the twin is
+       * skipped. Like `skip-size-limit`, this is deliberately NOT
+       * `type: "error"` (policy hq-sync-deliberate-skip-not-fatal-error-exit2:
+       * a recurring benign per-file skip emitted as an error lands in the
+       * runner's `errors[]`, forces exit 2 on every pass, and the menubar
+       * Sentry-alerts each time). The US-003 vault doctor is the cleanup
+       * path that collapses the junk family itself.
+       */
+      type: "skip-junk-key-spelling";
+      path: string;
+      /** The already-journaled spelling that owns this logical path. */
+      journaledKey: string;
     };
 
 export interface SyncOptions {
@@ -1211,6 +1237,18 @@ async function executeConflictExecutor(
       counters.filesOutOfScope++;
       continue;
     }
+    if (item.action === "skip-junk-key-spelling") {
+      // Deliberate, recoverable skip — counted as skipped and surfaced via a
+      // dedicated warning event, never `type: "error"` (see the event doc /
+      // policy hq-sync-deliberate-skip-not-fatal-error-exit2).
+      counters.filesSkipped++;
+      run.emit({
+        type: "skip-junk-key-spelling",
+        path: item.remoteFile.key,
+        journaledKey: item.journaledKey,
+      });
+      continue;
+    }
     if (item.action === "tombstone-delete") {
       executeFileTombstoneDelete(run, item, counters);
       continue;
@@ -2111,6 +2149,14 @@ type PullPlanItem =
   // the remote LIST (and accessible per STS) but deliberately not downloaded
   // because the membership's sync scope doesn't cover them.
   | { action: "skip-out-of-scope"; remoteFile: RemoteFile; localPath: string }
+  | {
+      // Mixed-version amplifier guard — see the `skip-junk-key-spelling`
+      // event doc. Carries the journaled spelling for the warning surface.
+      action: "skip-junk-key-spelling";
+      remoteFile: RemoteFile;
+      localPath: string;
+      journaledKey: string;
+    }
   // Remote key present in the LIST but carrying a FILE_TOMBSTONE that marks it
   // intentionally deleted (and the remote object is NOT a newer re-create). The
   // executor deletes any local copy and drops the journal entry — the
@@ -2208,6 +2254,39 @@ interface PullPlan {
 const PULL_INTENTIONAL_DELETE_MIN_ABS = 10;
 const PULL_INTENTIONAL_DELETE_RATIO = 0.1;
 
+/**
+ * win32 only: true when an existing local symlink's TARGET exists but the
+ * link cannot be traversed as that target's type — the file-flavor-link-at-
+ * a-directory shape minted while the target was absent (or by an older
+ * client). A dangling link is NOT broken-flavored (there is nothing to
+ * repair until the target appears). POSIX links are flavorless: always
+ * false off win32.
+ */
+export function win32SymlinkFlavorBroken(
+  localPath: string,
+  win32: boolean = process.platform === "win32",
+): boolean {
+  if (!win32) return false;
+  let target: string;
+  try {
+    target = fs.readlinkSync(localPath);
+  } catch {
+    return false;
+  }
+  const resolved = path.resolve(path.dirname(localPath), target);
+  let targetIsDir: boolean;
+  try {
+    targetIsDir = fs.statSync(resolved).isDirectory();
+  } catch {
+    return false; // dangling target — nothing to repair yet
+  }
+  try {
+    return fs.statSync(localPath).isDirectory() !== targetIsDir;
+  } catch {
+    return true; // target exists but the link cannot traverse: wrong flavor
+  }
+}
+
 function computePullPlan(
   remoteFiles: RemoteFile[],
   journal: SyncJournal,
@@ -2245,6 +2324,24 @@ function computePullPlan(
     localPath: string;
   }> = [];
 
+  // Junk-spelling guard (mixed-version amplifier): index every journaled key
+  // by its canonical (percent-decode fixpoint) form so a remote twin minted
+  // under a different spelling is recognized before it materializes. When
+  // several journaled spellings already share one canonical form (a
+  // pre-guard fork), the exactly-canonical spelling is preferred as the
+  // representative; entries journaled under their own exact spelling are
+  // never gated by this map (see the guard below), so pre-existing families
+  // keep syncing untouched until the vault doctor (US-003) collapses them.
+  const journaledKeyByCanonical = new Map<string, string>();
+  for (const journaledKey of Object.keys(journal.files)) {
+    if (!journaledKey.startsWith(SKILLS_KEY_PREFIX)) continue;
+    const canonical = canonicalVaultKeySpelling(journaledKey);
+    const existing = journaledKeyByCanonical.get(canonical);
+    if (existing === undefined || journaledKey === canonical) {
+      journaledKeyByCanonical.set(canonical, journaledKey);
+    }
+  }
+
   // Remote keys that ALSO appear as an ancestor of another remote key — i.e.
   // keys that carry child objects under `${key}/…` in this same LIST. The
   // vault stores a directory OVERLAY (a symlink into another tree, e.g. a
@@ -2406,6 +2503,43 @@ function computePullPlan(
       continue;
     }
 
+    // Junk-spelling guard — SKILL-FARM KEYS ONLY. The amplifier is specific
+    // to `.claude/skills/<ns>:<skill>` wrapper spellings; outside that prefix,
+    // keys whose percent-decode fixpoints collide (`notes/a b.md` vs a genuine
+    // `notes/a%20b.md`) are DISTINCT files that must both pull.
+    // Within the farm: a remote key that is NOT journaled under its own
+    // spelling but whose percent-decode fixpoint matches an already-journaled
+    // key with a different spelling is a mixed-version twin (`%3A`/`%253A`
+    // generations of a canonical `:` key). Materializing it would mint junk
+    // local dirs and fork the journal into a second key family for the same
+    // logical path — skip it (loudly, never fatally; see the
+    // `skip-junk-key-spelling` event doc) and leave the journaled spelling
+    // authoritative for this machine.
+    if (
+      journalEntry === undefined &&
+      remoteFile.key.startsWith(SKILLS_KEY_PREFIX) &&
+      // Gate NON-canonical remote spellings only. A remote key that already
+      // IS the canonical spelling must always be downloadable — after the
+      // doctor collapses the vault, a machine whose journal still holds only
+      // the junk spelling would otherwise skip the canonical object forever
+      // (and the delete-resync twin protection keeps that stale junk entry),
+      // deadlocking it out of every future update.
+      canonicalVaultKeySpelling(remoteFile.key) !== remoteFile.key
+    ) {
+      const journaledTwin = journaledKeyByCanonical.get(
+        canonicalVaultKeySpelling(remoteFile.key),
+      );
+      if (journaledTwin !== undefined && journaledTwin !== remoteFile.key) {
+        items.push({
+          action: "skip-junk-key-spelling",
+          remoteFile,
+          localPath,
+          journaledKey: journaledTwin,
+        });
+        continue;
+      }
+    }
+
     // ── FILE_TOMBSTONE consult (delete-resync) ───────────────────────────────
     // A remote object present in the LIST may be an intentionally-deleted key
     // (a peer re-pushed it, or its delete-marker hasn't propagated to this
@@ -2652,6 +2786,25 @@ function computePullPlan(
         continue;
       }
       if (journalEntry && !localChanged && !remoteChanged) {
+        // Flavor-health repair (win32 skill farm): a link journaled while its
+        // target was absent was minted file-flavor; once the target directory
+        // exists the hashes still match (hash = sha256(target)) so this
+        // branch would skip it forever, leaving the wrapper broken. Re-download
+        // instead — the materializer's flavor-aware path recreates it 'dir'.
+        if (
+          isLocalSymlink &&
+          remoteFile.key.startsWith(SKILLS_KEY_PREFIX) &&
+          win32SymlinkFlavorBroken(localPath)
+        ) {
+          items.push({
+            action: "download",
+            remoteFile,
+            localPath,
+            isNew: false,
+            localSnapshot: plannedLocalSnapshot,
+          });
+          continue;
+        }
         items.push({ action: "skip-unchanged", remoteFile, localPath });
         continue;
       }
@@ -2845,7 +2998,20 @@ function computePullPlan(
   // as a local delete + journal removal. Symmetric to the push side's
   // `propagateDeletes` plan in share.ts.
   const remoteKeySet = new Set<string>();
-  for (const rf of remoteFiles) remoteKeySet.add(rf.key);
+  // Skill-farm twin protection (companion to the junk-spelling pull guard):
+  // when the LIST holds only a junk spelling of a journaled canonical key,
+  // the logical object is still remotely present — a raw has() would class
+  // the canonical journal entry as remote-deleted, unlink the good local
+  // wrapper, and drop the journal entry (after which the next pull would
+  // materialize the junk spelling the guard just refused). Track canonical
+  // forms of listed skill keys and consult them below.
+  const remoteCanonicalSkillKeys = new Set<string>();
+  for (const rf of remoteFiles) {
+    remoteKeySet.add(rf.key);
+    if (rf.key.startsWith(SKILLS_KEY_PREFIX)) {
+      remoteCanonicalSkillKeys.add(canonicalVaultKeySpelling(rf.key));
+    }
+  }
   const tombstones: PullPlan["tombstones"] = [];
   for (const key of Object.keys(journal.files)) {
     // Compare membership in POSIX space. A pre-5.47.2 Windows journal key can
@@ -2855,6 +3021,18 @@ function computePullPlan(
     // POSIX compare is defense-in-depth (ridge data-loss, feedback_b8d09d0f).
     const posixKey = toPosixKey(key);
     if (remoteKeySet.has(posixKey)) continue;
+    if (
+      posixKey.startsWith(SKILLS_KEY_PREFIX) &&
+      remoteCanonicalSkillKeys.has(canonicalVaultKeySpelling(posixKey)) &&
+      // An EXACT FILE_TOMBSTONE for the journaled key is an authoritative
+      // delete and wins over the twin protection — a lingering junk
+      // spelling in the LIST must not keep a deliberately-deleted wrapper
+      // alive forever. (The key is absent from the LIST here, so there is
+      // no newer re-create to defer to.)
+      fileTombstones.get(posixKey) === undefined
+    ) {
+      continue;
+    }
     const localPath = resolveContainedVaultPath(companyRoot, key);
     if (localPath === null) continue;
     // PersonalMode key gating — mirror the download branch. Local (non-cloud)
@@ -3040,5 +3218,9 @@ function defaultConsoleLogger(event: SyncProgressEvent): void {
     console.warn(
       `  ! ${event.path} skipped — invalid vault key (${event.errorCode ?? "INVALID_KEY_COMPANIES_SCOPED"})`,
     );
+  } else if (event.type === "skip-junk-key-spelling") {
+    console.warn(
+      `  ! ${event.path} skipped — junk key spelling; this logical path is already synced as ${event.journaledKey} (mixed-version peer artifact; the vault doctor collapses the family)`,
+    );
   }
 }

package/src/cognito-auth.test.ts

@@ -14,18 +14,23 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 // Sandbox HOME *before* importing the module — it reads os.homedir() at load
 // time to compute the cache file path.
 let originalHome: string | undefined;
+let originalUserProfile: string | undefined;
 let tmpHome: string;
 
 beforeEach(() => {
   originalHome = process.env.HOME;
+  originalUserProfile = process.env.USERPROFILE;
   tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "hq-cognito-auth-test-"));
   process.env.HOME = tmpHome;
+  process.env.USERPROFILE = tmpHome;
   vi.resetModules();
 });
 
 afterEach(() => {
   if (originalHome === undefined) delete process.env.HOME;
   else process.env.HOME = originalHome;
+  if (originalUserProfile === undefined) delete process.env.USERPROFILE;
+  else process.env.USERPROFILE = originalUserProfile;
   fs.rmSync(tmpHome, { recursive: true, force: true });
   vi.unstubAllGlobals();
   vi.restoreAllMocks();

package/src/index.ts

@@ -300,6 +300,16 @@ export type { ReindexOptions, ReindexResult } from "./cli/index.js";
 export { rescue, buildRescueArgs } from "./cli/index.js";
 export type { RescueOptions, RescueResult } from "./cli/index.js";
 
+// `hq sync doctor` — skill-key dedupe + local farm GC (US-003). Consumed by
+// @indigoai-us/hq-cli's `sync doctor` subcommand.
+export { syncDoctor, SKILLS_KEY_PREFIX } from "./cli/index.js";
+export type {
+  SyncDoctorOptions,
+  SyncDoctorResult,
+  SyncDoctorPlan,
+  DoctorStore,
+} from "./cli/index.js";
+
 export type {
   EntityContext,
   VaultCredentials,

package/src/lib/conflict-file.ts

@@ -18,6 +18,8 @@
 import * as fs from "fs";
 import * as path from "path";
 
+import { localPathForVaultKey } from "../local-path-codec.js";
+
 export { readShortMachineId, getOrCreateMachineId } from "./machine-id.js";
 
 /**
@@ -58,7 +60,10 @@ export function writeConflictFile(
   conflictRelative: string,
   contents: Buffer,
 ): void {
-  const abs = path.join(hqRoot, conflictRelative);
+  // Codec boundary: conflict paths are canonical (hq-root-relative,
+  // forward-slash) keys, so the mirror must land at the encoded local name
+  // on win32 — a raw join of a colon key can never be created there.
+  const abs = localPathForVaultKey(hqRoot, conflictRelative);
   fs.mkdirSync(path.dirname(abs), { recursive: true });
   fs.writeFileSync(abs, contents);
 }

package/src/lib/conflict-index.ts

@@ -22,6 +22,7 @@
 import * as crypto from "crypto";
 import * as fs from "fs";
 import * as path from "path";
+import { localPathForVaultKey } from "../local-path-codec.js";
 import type { ConflictIndex, ConflictIndexEntry } from "../types.js";
 
 const CONFLICTS_DIR = ".hq-conflicts";
@@ -215,8 +216,12 @@ export function pruneConflictIndex(hqRoot: string): PruneConflictIndexResult {
   const mirrorsToRemove: string[] = [];
 
   for (const entry of index.conflicts) {
-    const mirrorAbs = path.join(hqRoot, entry.conflictPath);
-    const originalAbs = path.join(hqRoot, entry.originalPath);
+    // Codec boundary: index rows store canonical (hq-root-relative) keys, so
+    // both probes must resolve through the codec — a raw join of a win32
+    // colon key always lstat-fails, which would mis-classify a live encoded
+    // mirror as an orphaned row and silently drop it.
+    const mirrorAbs = localPathForVaultKey(hqRoot, entry.conflictPath);
+    const originalAbs = localPathForVaultKey(hqRoot, entry.originalPath);
 
     let mirrorStat: fs.Stats;
     try {