@indigoai-us/hq-cloud 6.14.22 → 6.14.24

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,
@@ -307,6 +312,32 @@ export type SyncProgressEvent =
       count: number;
       samplePaths: string[];
     }
+  | {
+      /**
+       * Emitted at most ONCE per PULL leg when the leg ran under a
+       * membership-scoped `syncMode` (`"shared"` or `"custom"` — never `"all"`)
+       * AND one or more remote keys were skipped as out-of-scope
+       * (`filesOutOfScope > 0`). This turns the silent shared-vs-all gap into a
+       * VISIBLE, actionable surface. The reporter of feedback_d2082110 lost
+       * files across devices precisely because four memberships defaulted to
+       * `shared` rather than `all`, so not all vault content materialized on the
+       * second device — and nothing told them; they had to notice the gap and
+       * flip each membership to `all` by hand. This event names the gap and the
+       * lever (raise the membership's access level to `all`) so FULL
+       * materialization is a deliberate, visible choice rather than a silent
+       * omission.
+       *
+       * `count` is the number of remote keys skipped as out-of-scope on this
+       * leg; `samplePaths` carries up to 10 company-relative keys for display;
+       * `syncMode` is the active scoped mode. Distinct from the push-side
+       * `scope-excluded` (which reports what a grantee could not PUSH). Not
+       * emitted in `all` mode or when `count === 0` — no gap, no noise.
+       */
+      type: "scope-materialization-gap";
+      count: number;
+      samplePaths: string[];
+      syncMode: SyncMode;
+    }
   | {
       /**
        * Emitted at most ONCE per `share()` push leg when the base ignore
@@ -375,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 {
@@ -856,6 +908,8 @@ async function syncWithOperationLockHeld(
   await verifyPlannedJournalTombstones(run, plan);
   executeJournalTombstoneDeletes(run, plan, counters);
 
+  emitScopeMaterializationGap(run, plan, counters);
+
   return finalizePullRun(run, plan, scopeRun, counters);
 }
 
@@ -1170,7 +1224,8 @@ async function executeConflictExecutor(
       item.action === "skip-personal-mode" ||
       item.action === "skip-unchanged" ||
       item.action === "skip-local-only" ||
-      item.action === "skip-stale-overlay-marker"
+      item.action === "skip-stale-overlay-marker" ||
+      item.action === "skip-overlay-marker-with-children"
     ) {
       counters.filesSkipped++;
       continue;
@@ -1182,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;
@@ -1844,6 +1911,37 @@ function finalizePullRun(
   };
 }
 
+/**
+ * Surface the shared-vs-all materialization gap (feedback_d2082110). When a
+ * pull leg ran under a membership-scoped `syncMode` and skipped one or more
+ * remote keys as out-of-scope, emit a single summary event so the operator
+ * SEES that not all vault content materialized on this device and knows the
+ * lever — raise the membership's access level to `all`. Silent in `all` mode
+ * (nothing is scoped away) and when nothing fell out of scope: no gap, no
+ * noise. Deliberately AFTER the transfer executors, so `filesOutOfScope` is
+ * final; sample keys are read off the plan's `skip-out-of-scope` items (pure,
+ * no I/O). This is the visible complement to the previously-silent
+ * `SyncResult.filesOutOfScope` count.
+ */
+function emitScopeMaterializationGap(
+  run: PullRunContext,
+  plan: PullPlan,
+  counters: PullCounters,
+): void {
+  if (run.syncMode === "all") return;
+  if (counters.filesOutOfScope <= 0) return;
+  const samplePaths = plan.items
+    .filter((item) => item.action === "skip-out-of-scope")
+    .slice(0, 10)
+    .map((item) => item.remoteFile.key);
+  run.emit({
+    type: "scope-materialization-gap",
+    count: counters.filesOutOfScope,
+    samplePaths,
+    syncMode: run.syncMode,
+  });
+}
+
 /**
  * Decide whether a remote object present in the LIST is a GENUINE RE-CREATE
  * written AFTER a FILE_TOMBSTONE — in which case the tombstone is stale and the
@@ -2034,6 +2132,15 @@ type PullPlanItem =
   // no-action-needed case is never surfaced with the alarming "rm -rf the
   // local directory" reconciliation advice.
   | { action: "skip-stale-overlay-marker"; remoteFile: RemoteFile; localPath: string }
+  // A directory-overlay marker (a single vault object at a key that ALSO has
+  // child objects under it in the same LIST — a symlink record for a directory
+  // mirrored from another tree) colliding with a local REAL directory whose
+  // contents are already materialized. The marker can never be renamed over the
+  // directory; its children carry the real content and materialize via their own
+  // plan items. A benign, no-action skip — distinct from skip-local-only so the
+  // case is never surfaced with the alarming (and, for a materialized directory,
+  // data-destroying) "rm -rf the local directory to pull" advice. feedback_d2082110.
+  | { action: "skip-overlay-marker-with-children"; remoteFile: RemoteFile; localPath: string }
   // Remote keys refused by ephemeral-mirror policy. The push walker has
   // refused to upload these since 5.33.0; the pull walker now refuses to
   // download them so legacy litter in cloud staging drains naturally.
@@ -2042,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
@@ -2139,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,
@@ -2176,6 +2324,46 @@ 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
+  // company skill mirrored from a shared repo) as a symlink RECORD at the
+  // directory's own key AND stores the directory's contents as separate child
+  // objects beneath it. A REAL directory, by contrast, only ever syncs as
+  // those child objects — never as a single object AT its own key. So a single
+  // remote object sitting at a key that also has children is unambiguously a
+  // directory-overlay marker, not a regular file. Precomputed once (pure path
+  // derivation, no I/O — the planner is synchronous) so the dir-vs-object
+  // collision branch can tell an inert overlay marker apart from a genuine
+  // file-vs-directory structural collision. feedback_d2082110.
+  const remoteKeysWithChildren = new Set<string>();
+  for (const rf of remoteFiles) {
+    const key = toPosixKey(rf.key);
+    let slash = key.indexOf("/");
+    while (slash !== -1) {
+      remoteKeysWithChildren.add(key.slice(0, slash));
+      slash = key.indexOf("/", slash + 1);
+    }
+  }
+
   for (const remoteFile of remoteFiles) {
     const invalidKey = classifyVaultKey(
       remoteFile.key,
@@ -2315,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
@@ -2437,6 +2662,30 @@ function computePullPlan(
           });
           continue;
         }
+        // Directory-overlay marker vs. a locally-materialized directory:
+        // the remote object at this key carries CHILD objects under it in the
+        // same LIST (`remoteKeysWithChildren`), so it is a symlink/overlay
+        // record for a directory — e.g. the DPP vault's `skills/cody-copywriter`
+        // overlay whose 13 child objects are already materialized locally. The
+        // marker can never be renamed over the real directory, and its children
+        // carry the actual content and materialize via their own plan items, so
+        // the marker is a benign, no-action skip. The generic "rm -rf the local
+        // directory to pull" advice below would tell the operator to DELETE the
+        // materialized (and possibly locally-authored) contents to install an
+        // inert link, and it recurred on EVERY sync cycle. feedback_d2082110.
+        if (remoteKeysWithChildren.has(toPosixKey(remoteFile.key))) {
+          console.error(
+            `  Note: ${remoteFile.key} is a directory-overlay marker whose ` +
+              `contents already exist locally as a directory; keeping the ` +
+              `local directory and ignoring the marker (no action needed).`,
+          );
+          items.push({
+            action: "skip-overlay-marker-with-children",
+            remoteFile,
+            localPath,
+          });
+          continue;
+        }
         console.error(
           `  Warning: ${remoteFile.key} exists locally as a directory; ` +
             `cloud has a single object at this key. Skipping; manual ` +
@@ -2537,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;
       }
@@ -2730,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
@@ -2740,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)
@@ -2896,6 +3189,16 @@ function defaultConsoleLogger(event: SyncProgressEvent): void {
     if (event.count > event.samplePaths.length) {
       console.log(`    ... and ${event.count - event.samplePaths.length} more`);
     }
+  } else if (event.type === "scope-materialization-gap") {
+    console.warn(
+      `  ! ${event.count} item${event.count === 1 ? "" : "s"} in this vault did NOT sync to this device — your access level is "${event.syncMode}", so only shared paths materialize. To pull everything you have access to, set this membership's access level to "all":`,
+    );
+    for (const p of event.samplePaths) {
+      console.warn(`    · ${p}`);
+    }
+    if (event.count > event.samplePaths.length) {
+      console.warn(`    ... and ${event.count - event.samplePaths.length} more`);
+    }
   } else if (event.type === "ignore-excluded") {
     console.warn(
       `  ! ${event.count} path${event.count === 1 ? "" : "s"} were EXCLUDED from sync by an ignore rule and did NOT reach the vault (review in case this is unintended):`,
@@ -2915,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";
@@ -136,6 +137,13 @@ export interface PruneConflictIndexResult {
   removedMirrors: number;
   /** Rows kept (genuine divergence, or unprovable — fail-safe retained). */
   kept: number;
+  /**
+   * Up to 10 ORIGINAL (non-mirror) paths of the kept rows, for a
+   * post-sync reconcile surface (`conflicts-remaining`). Empty when
+   * `kept === 0`. Lets a caller name the preserved conflict variants a human
+   * still has to resolve without re-reading the index. feedback_d2082110.
+   */
+  keptSamplePaths: string[];
 }
 
 /**
@@ -198,6 +206,7 @@ export function pruneConflictIndex(hqRoot: string): PruneConflictIndexResult {
     prunedIdentical: 0,
     removedMirrors: 0,
     kept: 0,
+    keptSamplePaths: [],
   };
 
   const index = readConflictIndex(hqRoot);
@@ -207,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 {
@@ -254,6 +267,9 @@ export function pruneConflictIndex(hqRoot: string): PruneConflictIndexResult {
     }
   }
 
+  // Name the preserved divergences for the post-sync reconcile surface.
+  result.keptSamplePaths = kept.slice(0, 10).map((e) => e.originalPath);
+
   // No row dropped → leave the file (and its mtime) untouched.
   if (kept.length === index.conflicts.length) return result;
 

package/src/lib/conflict.test.ts

@@ -194,6 +194,7 @@ describe("pruneConflictIndex", () => {
       prunedIdentical: 0,
       removedMirrors: 0,
       kept: 0,
+      keptSamplePaths: [],
     });
     expect(fs.existsSync(getConflictIndexPath(tmpHq))).toBe(false);
   });
@@ -292,6 +293,7 @@ describe("pruneConflictIndex", () => {
       prunedIdentical: 1,
       removedMirrors: 1,
       kept: 1,
+      keptSamplePaths: ["dir/real.md"],
     });
     expect(readConflictIndex(tmpHq).conflicts.map((c) => c.id)).toEqual(["real"]);
   });
@@ -312,4 +314,35 @@ describe("pruneConflictIndex", () => {
     pruneConflictIndex(tmpHq);
     expect(fs.statSync(indexPath).mtimeMs).toBe(before);
   });
+
+  it("names the preserved conflict variants (keptSamplePaths, capped at 10) for the reconcile surface (feedback_d2082110)", () => {
+    // Reporter feedback_d2082110 finished a full sync with "20 older preserved
+    // conflict entries" still on disk and NO signal they were there. The prune
+    // self-heals the ledger but conservatively KEEPS genuine divergences; those
+    // were silent. keptSamplePaths surfaces the original (non-mirror) paths so
+    // the runner can emit a `conflicts-remaining` reconcile line pointing the
+    // operator at `/resolve-conflicts`.
+    const rows: ConflictIndexEntry[] = [];
+    for (let i = 0; i < 12; i++) {
+      const id = `real-${String(i).padStart(2, "0")}`;
+      const row = rowFor(id);
+      put(row.originalPath, `local-${i}`);
+      put(row.conflictPath, `remote-${i}`);
+      rows.push(row);
+    }
+    writeConflictIndex(tmpHq, { version: 1, conflicts: rows });
+
+    const res = pruneConflictIndex(tmpHq);
+    expect(res.kept).toBe(12);
+    // Capped at 10 samples, drawn from the kept (detectedAt-sorted) rows.
+    expect(res.keptSamplePaths).toHaveLength(10);
+    expect(res.keptSamplePaths.every((p) => p.startsWith("dir/real-"))).toBe(true);
+    // Orphaned/identical rows never contribute to the surfaced sample.
+    const orphan = rowFor("orphan");
+    put(orphan.originalPath, "x"); // mirror missing → dropped, not sampled
+    writeConflictIndex(tmpHq, { version: 1, conflicts: [orphan] });
+    const res2 = pruneConflictIndex(tmpHq);
+    expect(res2.kept).toBe(0);
+    expect(res2.keptSamplePaths).toEqual([]);
+  });
 });

package/src/lib/machine-id.test.ts

@@ -17,22 +17,27 @@ function freshTmp(prefix: string): string {
 
 describe("getOrCreateMachineId (four-tier resolver)", () => {
   let originalHome: string | undefined;
+let originalUserProfile: string | undefined;
   let originalEnvId: string | undefined;
   let tmpHome: string;
   let tmpHqRoot: string;
 
   beforeEach(() => {
     originalHome = process.env.HOME;
+  originalUserProfile = process.env.USERPROFILE;
     originalEnvId = process.env.HQ_MACHINE_ID;
     delete process.env.HQ_MACHINE_ID;
     tmpHome = freshTmp("hq-machineid-home-");
     tmpHqRoot = freshTmp("hq-machineid-root-");
     process.env.HOME = tmpHome;
+  process.env.USERPROFILE = tmpHome;
   });
 
   afterEach(() => {
     if (originalHome) process.env.HOME = originalHome;
     else delete process.env.HOME;
+    if (originalUserProfile) process.env.USERPROFILE = originalUserProfile;
+    else delete process.env.USERPROFILE;
     if (originalEnvId !== undefined) process.env.HQ_MACHINE_ID = originalEnvId;
     else delete process.env.HQ_MACHINE_ID;
     fs.rmSync(tmpHome, { recursive: true, force: true });
@@ -135,22 +140,27 @@ describe("getOrCreateMachineId (four-tier resolver)", () => {
 
 describe("readShortMachineId", () => {
   let originalHome: string | undefined;
+let originalUserProfile: string | undefined;
   let originalEnvId: string | undefined;
   let tmpHome: string;
   let tmpHqRoot: string;
 
   beforeEach(() => {
     originalHome = process.env.HOME;
+  originalUserProfile = process.env.USERPROFILE;
     originalEnvId = process.env.HQ_MACHINE_ID;
     delete process.env.HQ_MACHINE_ID;
     tmpHome = freshTmp("hq-machineid-short-home-");
     tmpHqRoot = freshTmp("hq-machineid-short-root-");
     process.env.HOME = tmpHome;
+  process.env.USERPROFILE = tmpHome;
   });
 
   afterEach(() => {
     if (originalHome) process.env.HOME = originalHome;
     else delete process.env.HOME;
+    if (originalUserProfile) process.env.USERPROFILE = originalUserProfile;
+    else delete process.env.USERPROFILE;
     if (originalEnvId !== undefined) process.env.HQ_MACHINE_ID = originalEnvId;
     else delete process.env.HQ_MACHINE_ID;
     fs.rmSync(tmpHome, { recursive: true, force: true });