@indigoai-us/hq-cloud 6.14.22 → 6.14.24

package/src/cli/doctor.ts

@@ -0,0 +1,640 @@
+/**
+ * `hq sync doctor` — bounded skill-key dedupe + local farm GC (US-003,
+ * hq-sync-windows-skill-symlink-collision).
+ *
+ * The mixed-version amplifier (see `canonicalVaultKeySpelling` in
+ * local-path-codec.ts) leaves the vault holding several percent-encoded
+ * GENERATIONS of every `.claude/skills/<ns>:<skill>` wrapper key (`:`, `%3A`,
+ * `%253A`, `%25253A`, …) and the local farm holding junk-named wrapper dirs.
+ * US-001/US-002 stop NEW generations from being minted; this doctor is the
+ * one-shot reconcile that collapses the families already in the wild:
+ *
+ *   1. Vault dedupe — list keys under `.claude/skills/`, group them by their
+ *      decode-to-fixpoint canonical form, let the newest-bodied spelling win,
+ *      (re)write the canonical `:` key when it is missing or stale, and delete
+ *      every non-canonical spelling. Deletion is gated hard: only bodies that
+ *      start with the `hq-symlink:` marker, or that are byte-identical to the
+ *      canonical twin, are auto-deleted — anything else is surfaced for manual
+ *      review, never silently removed.
+ *   2. Local farm GC — remove `.claude/skills/` entries whose names decode to
+ *      a canonical wrapper that already exists on disk and whose content is
+ *      exclusively symlink-farm material. A real file anywhere is a refusal.
+ *
+ * Dry-run is the DEFAULT: the full keep/rewrite/tombstone/rm plan is printed
+ * (counts + every key/path) and nothing is written until `--yes`
+ * (`options.yes`). Remote deletes respect the sync-delete-bulk-asymmetry-guard
+ * policy — same thresholds, env override, and refusal semantics as
+ * `computeDeletePlan` in share.ts. Per-item failures are loud warnings, never
+ * process-fatal (hq-sync-deliberate-skip-not-fatal-error-exit2).
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import { resolveEntityContext } from "../context.js";
+import { resolveObjectIO, type ObjectIO } from "../object-io.js";
+import type { ListedRemoteObject } from "../object-io.js";
+import { SYMLINK_BODY_PREFIX } from "../s3.js";
+import {
+  canonicalVaultKeySpelling,
+  canonicalVaultSegmentSpelling,
+  encodeLocalVaultSegment,
+} from "../local-path-codec.js";
+import { withOperationLock } from "../operation-lock.js";
+import type { VaultServiceConfig } from "../types.js";
+
+/** Vault prefix the doctor is bounded to — the skill wrapper link farm. */
+export const SKILLS_KEY_PREFIX = ".claude/skills/";
+
+/**
+ * Bulk-asymmetry circuit-breaker, per the sync-delete-bulk-asymmetry-guard
+ * policy: any new delete-propagation site must ship the guard inline with the
+ * SAME threshold defaults and env-var name as the reference implementation
+ * (share.ts `BULK_ASYMMETRY_*` + `isBulkAsymmetryOverride`). Here the
+ * numerator is the planned tombstone count and the denominator is every
+ * in-scope `.claude/skills/` key — a dedupe pass that wants to delete a large
+ * slice of the farm at once must be explicitly confirmed, because that shape
+ * is indistinguishable from a planner bug eating the vault.
+ */
+const BULK_ASYMMETRY_RATIO = 0.10;
+const BULK_ASYMMETRY_MIN_ABS = 10;
+
+function isBulkDeleteOverride(explicit: boolean | undefined): boolean {
+  if (explicit) return true;
+  const v = (process.env.HQ_SYNC_DELETE_BULK_OVERRIDE ?? "").toLowerCase();
+  return v === "1" || v === "true" || v === "yes";
+}
+
+/**
+ * The narrow object-store seam the doctor needs. Structurally satisfied by
+ * every `ObjectIO` transport; tests inject an in-memory fake (the same
+ * dependency-injection convention the s3.ts suites use via
+ * `setObjectIOFactory`).
+ */
+export type DoctorStore = Pick<
+  ObjectIO,
+  "listObjects" | "getObject" | "putObject" | "deleteObject"
+>;
+
+export interface SyncDoctorOptions {
+  /** Entity whose vault to reconcile (prs_/agt_ uid, cmp_ uid, or slug). */
+  entity: string;
+  /** Vault service config (auth + region), as for `sync()`/`share()`. */
+  vaultConfig: VaultServiceConfig;
+  /** HQ root whose local `.claude/skills/` farm the GC pass walks. */
+  hqRoot: string;
+  /** Apply the plan. Default false = dry-run: print the plan, write nothing. */
+  yes?: boolean;
+  /**
+   * Explicit bulk-delete override (the `--force-bulk` CLI flag). Equivalent to
+   * `HQ_SYNC_DELETE_BULK_OVERRIDE=1`; without either, a tombstone plan that
+   * trips the asymmetry thresholds is refused (writes and local GC still run).
+   */
+  bulkDeleteOverride?: boolean;
+  /** DI seam for tests; defaults to the entity's resolved ObjectIO. */
+  store?: DoctorStore;
+  /**
+   * Platform override for local farm-name encoding (local-path-codec
+   * convention). Decode-to-fixpoint always uses win32 semantics — junk
+   * spellings are a key-space phenomenon, not a host one — but the canonical
+   * LOCAL wrapper name a junk dir must collapse into is host-specific
+   * (`ns%3Askill` on win32, `ns:skill` on POSIX).
+   */
+  win32?: boolean;
+  /**
+   * The doctor takes the same per-root operation lock as `sync()`. Set when a
+   * caller (runner/daemon) already holds it for this root.
+   */
+  operationLockAlreadyHeld?: boolean;
+}
+
+/** One canonical key the doctor will (re)write, and the spelling it copies. */
+export interface SkillKeyRewrite {
+  key: string;
+  /** Winning (newest-bodied) spelling whose body becomes the canonical body. */
+  fromSpelling: string;
+}
+
+export interface DoctorManualReviewItem {
+  key: string;
+  reason: string;
+}
+
+export interface LocalGcManualReviewItem {
+  path: string;
+  reason: string;
+}
+
+export interface SyncDoctorPlan {
+  /** Every listed `.claude/skills/` key (the bulk-guard denominator). */
+  inScopeKeys: number;
+  /** Canonical-spelling keys that need no action. */
+  keep: string[];
+  /** Canonical keys to (re)write from their winning spelling's body. */
+  rewrites: SkillKeyRewrite[];
+  /** Non-canonical spellings safe to delete (marker body or byte-identical). */
+  tombstones: string[];
+  /** Keys the safety gate refused to auto-delete — surfaced, never removed. */
+  manualReview: DoctorManualReviewItem[];
+  /** Junk-named local farm entries (symlink-farm content only) to remove. */
+  localRemovals: string[];
+  /** Junk-named local entries the GC refused to touch — surfaced only. */
+  localManualReview: LocalGcManualReviewItem[];
+  /** True when the tombstone plan tripped the bulk-asymmetry breaker. */
+  bulkRefused: boolean;
+}
+
+export interface SyncDoctorResult {
+  plan: SyncDoctorPlan;
+  /** False on dry-run (the default) and when `--yes` was absent. */
+  applied: boolean;
+  keysRewritten: number;
+  keysDeleted: number;
+  dirsRemoved: number;
+  /** Loud non-fatal warnings emitted during plan + apply. */
+  warnings: number;
+}
+
+/** A group member whose body was fetched for winner selection / gating. */
+interface FetchedSpelling {
+  key: string;
+  lastModified: Date;
+  body: Buffer;
+  metadata?: Record<string, string>;
+}
+
+/** Payload for one canonical-key rewrite, staged at plan time. */
+interface RewritePayload {
+  key: string;
+  body: Buffer;
+  metadata?: Record<string, string>;
+  /** CAS fence: canonical key was listed with this ETag. */
+  ifMatch?: string;
+  /** CAS fence: canonical key was absent at list time. */
+  ifNoneMatch?: "*";
+}
+
+function isSymlinkMarkerBody(body: Buffer): boolean {
+  return (
+    body.subarray(0, SYMLINK_BODY_PREFIX.length).toString("utf-8") ===
+    SYMLINK_BODY_PREFIX
+  );
+}
+
+/** Exhaustively page the skills prefix (the transport caps pages at ~1000). */
+async function listSkillObjects(
+  store: DoctorStore,
+): Promise<ListedRemoteObject[]> {
+  const objects: ListedRemoteObject[] = [];
+  let continuationToken: string | undefined;
+  do {
+    const page = await store.listObjects({
+      prefix: SKILLS_KEY_PREFIX,
+      continuationToken,
+    });
+    objects.push(...page.objects);
+    continuationToken = page.nextContinuationToken;
+  } while (continuationToken);
+  return objects;
+}
+
+/**
+ * Winner ordering: newest lastModified first ("newest-bodied spelling wins");
+ * ties prefer the canonical spelling, then the lexicographically smallest key
+ * so the plan is deterministic under equal timestamps.
+ */
+function pickWinner(
+  members: FetchedSpelling[],
+  canonicalKey: string,
+): FetchedSpelling {
+  return members.reduce((best, m) => {
+    if (m.lastModified.getTime() !== best.lastModified.getTime()) {
+      return m.lastModified.getTime() > best.lastModified.getTime() ? m : best;
+    }
+    if ((m.key === canonicalKey) !== (best.key === canonicalKey)) {
+      return m.key === canonicalKey ? m : best;
+    }
+    return m.key < best.key ? m : best;
+  });
+}
+
+/**
+ * True when every entry under `dir` (recursively) is symlink-farm material:
+ * symlinks, or directories that themselves contain only symlink-farm
+ * material. Any regular file — or anything that is neither a symlink nor a
+ * directory (fifo, socket) — makes the tree untouchable.
+ */
+function containsOnlySymlinkFarmContent(dir: string): boolean {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isSymbolicLink()) continue;
+    if (entry.isDirectory()) {
+      if (!containsOnlySymlinkFarmContent(path.join(dir, entry.name))) {
+        return false;
+      }
+      continue;
+    }
+    return false;
+  }
+  return true;
+}
+
+/** lstat-based existence probe — a broken symlink wrapper still "exists". */
+function entryExists(p: string): boolean {
+  try {
+    fs.lstatSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Plan the local `.claude/skills/` farm GC. Pure planning — no removal here.
+ * An entry qualifies when its name percent-decodes (to fixpoint) to a
+ * canonical wrapper name DIFFERENT from its own spelling, that canonical
+ * wrapper already exists on disk, and the entry is a symlink or a directory
+ * of exclusively symlink-farm content. Everything else that is junk-named is
+ * listed for manual review with the reason it was refused.
+ */
+function planLocalSkillFarmGc(
+  skillsDir: string,
+  win32: boolean,
+  warn: (message: string) => void,
+): { removals: string[]; manualReview: LocalGcManualReviewItem[] } {
+  const removals: string[] = [];
+  const manualReview: LocalGcManualReviewItem[] = [];
+  if (!entryExists(skillsDir)) return { removals, manualReview };
+
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+  } catch (err) {
+    warn(`local GC skipped — cannot read ${skillsDir}: ${String(err)}`);
+    return { removals, manualReview };
+  }
+
+  for (const entry of entries) {
+    // Fixpoint-decode the name (win32 key-space semantics unconditionally —
+    // a mac's literal `ns%3Askill` junk dir is junk too), then re-encode for
+    // THIS host to get the canonical local wrapper spelling.
+    const canonicalName = canonicalVaultSegmentSpelling(entry.name);
+    // A no-op canonicalization means this name is NOT an amplifier
+    // generation: generated wrapper generations always decode back to a
+    // `<ns>:<skill>` name, and canonicalVaultSegmentSpelling deliberately
+    // returns colon-free names unchanged (`foo%25bar` is a legitimate
+    // wrapper for the canonical skill name `foo%bar`, distinct from a
+    // literal `foo%bar` dir). Encoding such a name for the host would
+    // re-escape it into a different spelling (`foo%2525bar` on win32) and,
+    // if that double-encoded sibling happens to exist, `--yes` would delete
+    // the legitimate wrapper. Bail before the host encode — the amplifier
+    // family this GC exists to collapse always changes spelling here.
+    if (canonicalName === entry.name) continue;
+    const canonicalLocalName = encodeLocalVaultSegment(canonicalName, win32);
+    if (entry.name === canonicalLocalName) continue; // already canonical
+
+    const fullPath = path.join(skillsDir, entry.name);
+    if (!entryExists(path.join(skillsDir, canonicalLocalName))) {
+      manualReview.push({
+        path: fullPath,
+        reason: `canonical wrapper '${canonicalLocalName}' missing on disk — junk-named entry may be the only copy`,
+      });
+      continue;
+    }
+    if (entry.isSymbolicLink()) {
+      removals.push(fullPath);
+      continue;
+    }
+    if (entry.isDirectory()) {
+      let farmOnly = false;
+      try {
+        farmOnly = containsOnlySymlinkFarmContent(fullPath);
+      } catch (err) {
+        warn(`local GC cannot inspect ${fullPath}: ${String(err)}`);
+        manualReview.push({ path: fullPath, reason: "unreadable — not inspected" });
+        continue;
+      }
+      if (farmOnly) {
+        removals.push(fullPath);
+      } else {
+        manualReview.push({
+          path: fullPath,
+          reason: "contains real (non-symlink) files — never auto-deleted",
+        });
+      }
+      continue;
+    }
+    manualReview.push({
+      path: fullPath,
+      reason: "junk-named regular file — never auto-deleted",
+    });
+  }
+  return { removals, manualReview };
+}
+
+/** Remove one farm entry: unlink symlinks (rmdir for win32 dir links), rm dirs. */
+function removeFarmEntry(fullPath: string): void {
+  const st = fs.lstatSync(fullPath);
+  if (st.isSymbolicLink()) {
+    try {
+      fs.unlinkSync(fullPath);
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      // A Windows directory symlink is a directory reparse point; unlink()
+      // refuses it (EPERM/EISDIR) and rmdir removes the LINK, not the target.
+      if (code === "EPERM" || code === "EISDIR") {
+        fs.rmdirSync(fullPath);
+      } else {
+        throw err;
+      }
+    }
+    return;
+  }
+  fs.rmSync(fullPath, { recursive: true });
+}
+
+/**
+ * Run the doctor: build the dedupe + GC plan, print it in full, and — only
+ * with `yes: true` — apply it. See the module doc for semantics.
+ */
+export async function syncDoctor(
+  options: SyncDoctorOptions,
+): Promise<SyncDoctorResult> {
+  if (options.operationLockAlreadyHeld) {
+    return syncDoctorWithOperationLockHeld(options);
+  }
+  return withOperationLock(options.hqRoot, "sync-doctor", () =>
+    syncDoctorWithOperationLockHeld(options),
+  );
+}
+
+async function syncDoctorWithOperationLockHeld(
+  options: SyncDoctorOptions,
+): Promise<SyncDoctorResult> {
+  let warnings = 0;
+  const warn = (message: string): void => {
+    warnings++;
+    console.error(`  ! ${message}`);
+  };
+
+  const win32 = options.win32 ?? process.platform === "win32";
+  const store =
+    options.store ??
+    resolveObjectIO(
+      await resolveEntityContext(options.entity, options.vaultConfig),
+    );
+
+  // ── Vault leg: plan ────────────────────────────────────────────────────────
+  const listed = await listSkillObjects(store);
+  const groups = new Map<string, ListedRemoteObject[]>();
+  for (const obj of listed) {
+    const canonicalKey = canonicalVaultKeySpelling(obj.key);
+    const members = groups.get(canonicalKey);
+    if (members) {
+      members.push(obj);
+    } else {
+      groups.set(canonicalKey, [obj]);
+    }
+  }
+
+  const keep: string[] = [];
+  const rewrites: SkillKeyRewrite[] = [];
+  const rewritePayloads: RewritePayload[] = [];
+  const tombstones: string[] = [];
+  const manualReview: DoctorManualReviewItem[] = [];
+
+  for (const [canonicalKey, members] of groups) {
+    // Fast path: one spelling and it is already canonical — nothing to do,
+    // and no body fetch (the common case must stay O(list), not O(get)).
+    if (members.length === 1 && members[0]!.key === canonicalKey) {
+      keep.push(canonicalKey);
+      continue;
+    }
+
+    // Actionable family: fetch every member's body. A fetch failure demotes
+    // that spelling to manual review (unknown bytes are never deleted) and
+    // never aborts the run.
+    const fetched: FetchedSpelling[] = [];
+    for (const member of members) {
+      try {
+        const res = await store.getObject(member.key);
+        fetched.push({
+          key: member.key,
+          lastModified: member.lastModified,
+          body: res.body,
+          metadata: res.metadata,
+        });
+      } catch (err) {
+        warn(`body fetch failed for ${member.key}: ${String(err)} — left for manual review`);
+        manualReview.push({
+          key: member.key,
+          reason: "body fetch failed — bytes unknown, not touched",
+        });
+      }
+    }
+    if (fetched.length === 0) continue; // every member failed; all warned above
+
+    // A canonical spelling that is LISTED but whose body fetch failed means
+    // the canonical bytes are unknown — rewriting from a junk sibling could
+    // overwrite a non-marker object behind a transient read fault. Park the
+    // whole family: no rewrite, no deletes; re-run once the read recovers.
+    const canonicalListed = members.some((m) => m.key === canonicalKey);
+    const canonicalMember = fetched.find((m) => m.key === canonicalKey);
+    if (canonicalListed && canonicalMember === undefined) {
+      for (const member of fetched) {
+        manualReview.push({
+          key: member.key,
+          reason: "canonical body unknown (fetch failed) — family not touched",
+        });
+      }
+      continue;
+    }
+
+    const winner = pickWinner(fetched, canonicalKey);
+
+    // The body the canonical key will hold after this pass: the newest-bodied
+    // spelling's. (Re)write when the canonical key is missing entirely or its
+    // bytes are stale relative to the winner.
+    const finalBody = winner.body;
+    if (!canonicalMember || !canonicalMember.body.equals(finalBody)) {
+      rewrites.push({ key: canonicalKey, fromSpelling: winner.key });
+      // CAS fence (same contract as the push path): if the canonical key was
+      // listed, the PUT lands only while its ETag is unchanged; if it was
+      // absent, only while it is still absent. A concurrent upload from
+      // another machine turns the rewrite into a 412 warning (and the
+      // failed-rewrite guard below keeps the family's tombstones), never a
+      // clobber of bytes this run has not seen.
+      const listedCanonical = members.find((m) => m.key === canonicalKey);
+      rewritePayloads.push({
+        key: canonicalKey,
+        body: finalBody,
+        metadata: winner.metadata,
+        ...(listedCanonical
+          ? { ifMatch: listedCanonical.etag }
+          : { ifNoneMatch: "*" as const }),
+      });
+    } else {
+      keep.push(canonicalKey);
+    }
+
+    // Safety gate, per spelling: auto-delete ONLY symlink-marker bodies or
+    // bodies byte-identical to the canonical twin's final content.
+    for (const member of fetched) {
+      if (member.key === canonicalKey) continue;
+      if (isSymlinkMarkerBody(member.body) || member.body.equals(finalBody)) {
+        tombstones.push(member.key);
+      } else {
+        manualReview.push({
+          key: member.key,
+          reason: "body is neither a symlink marker nor byte-identical to the canonical key — not auto-deleted",
+        });
+      }
+    }
+  }
+
+  // ── Bulk-asymmetry decision (policy: sync-delete-bulk-asymmetry-guard) ────
+  const bulkRefused =
+    !isBulkDeleteOverride(options.bulkDeleteOverride) &&
+    tombstones.length >= BULK_ASYMMETRY_MIN_ABS &&
+    listed.length > 0 &&
+    tombstones.length / listed.length >= BULK_ASYMMETRY_RATIO;
+
+  // ── Local leg: plan ───────────────────────────────────────────────────────
+  const skillsDir = path.join(options.hqRoot, ".claude", "skills");
+  const localGc = planLocalSkillFarmGc(skillsDir, win32, warn);
+
+  const plan: SyncDoctorPlan = {
+    inScopeKeys: listed.length,
+    keep,
+    rewrites,
+    tombstones,
+    manualReview,
+    localRemovals: localGc.removals,
+    localManualReview: localGc.manualReview,
+    bulkRefused,
+  };
+  printPlan(plan);
+
+  const result: SyncDoctorResult = {
+    plan,
+    applied: false,
+    keysRewritten: 0,
+    keysDeleted: 0,
+    dirsRemoved: 0,
+    warnings,
+  };
+
+  // ── Dry-run is the default: full plan printed, nothing written. ───────────
+  if (!options.yes) {
+    console.log("\nDry-run (default): nothing written. Re-run with --yes to apply.");
+    result.warnings = warnings;
+    return result;
+  }
+
+  // ── Apply: canonical rewrites first (additive), then gated deletes, then
+  //    local GC. Per-item failures warn and continue — never fatal. ─────────
+  // Canonical keys whose rewrite failed: their families' tombstones must NOT
+  // be deleted below — when the canonical body was missing or stale, the junk
+  // spelling may hold the newest (or only) remote copy, and deleting it after
+  // a failed rewrite would drop that body permanently.
+  const failedRewriteCanonicals = new Set<string>();
+  for (const payload of rewritePayloads) {
+    try {
+      await store.putObject({
+        key: payload.key,
+        body: payload.body,
+        // Content-type is not consulted by the engine's read path; marker
+        // records upload as octet-stream (s3.ts uploadSymlink convention).
+        contentType: "application/octet-stream",
+        metadata: payload.metadata,
+        ifMatch: payload.ifMatch,
+        ifNoneMatch: payload.ifNoneMatch,
+      });
+      result.keysRewritten++;
+    } catch (err) {
+      failedRewriteCanonicals.add(payload.key);
+      warn(`canonical rewrite failed for ${payload.key}: ${String(err)}`);
+    }
+  }
+
+  if (bulkRefused) {
+    // Refusal is event-only (policy req #4): nothing deleted, nothing
+    // journaled away — re-run with the override once the plan is reviewed.
+    console.error(
+      `  ! bulk-asymmetry circuit-breaker tripped: ${tombstones.length}/${listed.length} in-scope skill keys planned for deletion.\n` +
+        `    Refusing the delete leg — review the plan above, then re-run with --force-bulk (or HQ_SYNC_DELETE_BULK_OVERRIDE=1) to apply it.`,
+    );
+  } else {
+    for (const key of tombstones) {
+      if (failedRewriteCanonicals.has(canonicalVaultKeySpelling(key))) {
+        warn(
+          `skipping delete of ${key} — its canonical rewrite failed; re-run the doctor once the write path recovers`,
+        );
+        continue;
+      }
+      try {
+        await store.deleteObject(key);
+        result.keysDeleted++;
+      } catch (err) {
+        warn(`delete failed for ${key}: ${String(err)}`);
+      }
+    }
+  }
+
+  for (const fullPath of plan.localRemovals) {
+    try {
+      // Re-verify at apply time: the entry may have changed between plan and
+      // apply (sync pass, user edit). Positive check — remove ONLY what is
+      // still a symlink or a farm-only directory; anything else (a regular
+      // file that replaced the planned entry, a dir that grew real files) is
+      // refused rather than trusted from the plan.
+      const st = fs.lstatSync(fullPath);
+      const stillFarmEntry =
+        st.isSymbolicLink() ||
+        (st.isDirectory() && containsOnlySymlinkFarmContent(fullPath));
+      if (!stillFarmEntry) {
+        warn(`skipped ${fullPath} — no longer symlink-farm content (changed since planning)`);
+        continue;
+      }
+      removeFarmEntry(fullPath);
+      result.dirsRemoved++;
+    } catch (err) {
+      warn(`local removal failed for ${fullPath}: ${String(err)}`);
+    }
+  }
+
+  result.applied = true;
+  result.warnings = warnings;
+  console.log(
+    `\nApplied: ${result.keysRewritten} canonical key(s) written, ${result.keysDeleted} spelling(s) deleted, ${result.dirsRemoved} local entr(ies) removed.`,
+  );
+  return result;
+}
+
+/** Print the full plan: counts plus every key/path in each bucket. */
+function printPlan(plan: SyncDoctorPlan): void {
+  console.log(`hq sync doctor — skill-key dedupe plan (${SKILLS_KEY_PREFIX})`);
+  console.log(`  in-scope keys: ${plan.inScopeKeys}`);
+  console.log(`  keep (canonical, no action): ${plan.keep.length}`);
+  for (const key of plan.keep) console.log(`    = ${key}`);
+  console.log(`  rewrite canonical: ${plan.rewrites.length}`);
+  for (const r of plan.rewrites) {
+    console.log(`    + ${r.key}  (body from ${r.fromSpelling})`);
+  }
+  console.log(`  tombstone (delete non-canonical spelling): ${plan.tombstones.length}`);
+  for (const key of plan.tombstones) console.log(`    - ${key}`);
+  console.log(`  manual review (NOT deleted): ${plan.manualReview.length}`);
+  for (const item of plan.manualReview) {
+    console.log(`    ? ${item.key} — ${item.reason}`);
+  }
+  console.log(`  local farm GC — remove: ${plan.localRemovals.length}`);
+  for (const p of plan.localRemovals) console.log(`    - ${p}`);
+  console.log(`  local farm GC — manual review: ${plan.localManualReview.length}`);
+  for (const item of plan.localManualReview) {
+    console.log(`    ? ${item.path} — ${item.reason}`);
+  }
+  if (plan.bulkRefused) {
+    console.log(
+      `  bulk-asymmetry: delete leg WOULD BE REFUSED (${plan.tombstones.length}/${plan.inScopeKeys} keys; override with --force-bulk or HQ_SYNC_DELETE_BULK_OVERRIDE=1)`,
+    );
+  }
+}

package/src/cli/index.ts

@@ -33,3 +33,17 @@ export type { ReindexOptions, ReindexResult } from "./reindex.js";
 // menubar app). Now shared between the app and `hq rescue`.
 export { rescue, buildRescueArgs } from "./rescue.js";
 export type { RescueOptions, RescueResult } from "./rescue.js";
+
+// Bounded skill-key dedupe + local `.claude/skills/` farm GC for the
+// mixed-version amplifier (`hq sync doctor`, US-003
+// hq-sync-windows-skill-symlink-collision). Dry-run by default; --yes applies.
+export { syncDoctor, SKILLS_KEY_PREFIX } from "./doctor.js";
+export type {
+  SyncDoctorOptions,
+  SyncDoctorResult,
+  SyncDoctorPlan,
+  SkillKeyRewrite,
+  DoctorManualReviewItem,
+  LocalGcManualReviewItem,
+  DoctorStore,
+} from "./doctor.js";

package/src/cli/share.test.ts

@@ -1673,6 +1673,7 @@ describe("share", () => {
           e.type === "new-files" ||
           e.type === "personal-vault-out-of-policy" ||
           e.type === "scope-excluded" ||
+          e.type === "scope-materialization-gap" ||
           e.type === "ignore-excluded" ||
           e.type === "delete-refused-bulk-asymmetry"
         ) return;

package/src/cli/share.ts

@@ -1604,7 +1604,12 @@ async function executeDeletes(
         item.intentVersion !== null &&
         (!hasCurrentLocalDeleteIntent(entry) ||
           entry!.localDeleteIntent!.version !== item.intentVersion ||
-          !isLocallyAbsent(path.join(run.syncRoot, relativePath)))
+          // Codec boundary: journal keys are canonical; the last-second
+          // absence re-check must probe the ENCODED local path or a win32
+          // colon key always looks absent (a raw `:` name can never exist
+          // on disk) and the remote delete proceeds while the encoded local
+          // file is still present.
+          !isLocallyAbsent(localPathForVaultKey(run.syncRoot, relativePath)))
       ) {
         if (entry?.localDeleteIntent) {
           delete entry.localDeleteIntent;