@indigoai-us/hq-cloud 5.36.0 → 5.38.0

package/src/cli/share.test.ts

@@ -702,7 +702,8 @@ describe("share", () => {
         if (
           e.type === "plan" ||
           e.type === "new-files" ||
-          e.type === "personal-vault-out-of-policy"
+          e.type === "personal-vault-out-of-policy" ||
+          e.type === "delete-refused-bulk-asymmetry"
         ) return;
         events.push({
           type: e.type,
@@ -2533,6 +2534,315 @@ describe("share", () => {
       expect(calls.find((c) => c[2].includes("secret.md"))).toBeUndefined();
     });
   });
+
+  // ── Bulk-asymmetry circuit-breaker ─────────────────────────────────────
+  //
+  // Defends against the "local mirror lost, journal still full" failure
+  // mode that caused the 2026-05-25 indigo vault mass-delete (269 signals/
+  // + 290 sources/ delete-markers in one afternoon).
+  //
+  // Trip rule: candidates >= 10 absolute AND candidates / inScope >= 0.10.
+  // Bypass: HQ_SYNC_DELETE_BULK_OVERRIDE=1 OR propagateDeletePolicy: "all".
+  //
+  // See `workspace/reports/indigo-vault-mass-delete-debug.md` for the full
+  // investigation and `BULK_ASYMMETRY_*` constants in share.ts for the
+  // rationale behind these specific thresholds.
+  describe("bulk-asymmetry circuit-breaker", () => {
+    // Helper — write a journal of N entries, marking the first `missing`
+    // entries as absent locally (the rest get a real file on disk).
+    // `direction` default "up" so the owned-only branch accepts every
+    // candidate (direction:"down" silently skips and never trips the guard).
+    function setupJournal({
+      total,
+      missing,
+      direction = "up" as "up" | "down",
+    }: {
+      total: number;
+      missing: number;
+      direction?: "up" | "down";
+    }): { companyRoot: string; journalPath: string } {
+      const companyRoot = path.join(tmpDir, "companies", "acme");
+      fs.mkdirSync(companyRoot, { recursive: true });
+      const files: Record<
+        string,
+        {
+          hash: string;
+          size: number;
+          syncedAt: string;
+          direction: "up" | "down";
+          remoteEtag: string;
+        }
+      > = {};
+      for (let i = 0; i < total; i++) {
+        const key = `f-${i.toString().padStart(4, "0")}.md`;
+        files[key] = {
+          hash: "h",
+          size: 5,
+          syncedAt: new Date().toISOString(),
+          direction,
+          remoteEtag: `etag-${i}`,
+        };
+        if (i >= missing) {
+          fs.writeFileSync(path.join(companyRoot, key), "hi");
+        }
+      }
+      const journalPath = path.join(stateDir, "sync-journal.acme.json");
+      fs.writeFileSync(
+        journalPath,
+        JSON.stringify({
+          version: "1",
+          lastSync: new Date().toISOString(),
+          files,
+        }),
+      );
+      return { companyRoot, journalPath };
+    }
+
+    afterEach(() => {
+      delete process.env.HQ_SYNC_DELETE_BULK_OVERRIDE;
+    });
+
+    it("trips at the 11/100 boundary (11% > 10%, abs >= 10): refuses every delete and emits bulk-asymmetry event", async () => {
+      const { companyRoot, journalPath } = setupJournal({ total: 100, missing: 11 });
+      // currency-gated: remote HEAD would match every journal etag — guard
+      // must trip BEFORE any HEAD round-trip occurs.
+      vi.mocked(headRemoteFile).mockImplementation(async (_ctx, key) => ({
+        etag: `etag-${parseInt(key.replace(/[^0-9]/g, ""), 10)}`,
+        lastModified: new Date(),
+        size: 5,
+      }));
+
+      const events: Array<{ type: string; [k: string]: unknown }> = [];
+      const result = await share({
+        paths: [companyRoot],
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+        skipUnchanged: true,
+        propagateDeletes: true,
+        propagateDeletePolicy: "currency-gated",
+        onEvent: (e) => events.push(e as { type: string }),
+      });
+
+      expect(result.filesDeleted).toBe(0);
+      expect(deleteRemoteFile).not.toHaveBeenCalled();
+      // No HEAD was issued for any of the 11 MISSING keys — the guard
+      // short-circuits before Stage 2 HEAD pass. `headRemoteFile` may still
+      // be called for the 89 present-locally upload candidates (3-way
+      // conflict check), so the assertion targets only the would-be
+      // delete-candidates.
+      const headedKeys = vi
+        .mocked(headRemoteFile)
+        .mock.calls.map((c) => c[1] as string);
+      for (let i = 0; i < 11; i++) {
+        const missingKey = `f-${i.toString().padStart(4, "0")}.md`;
+        expect(headedKeys).not.toContain(missingKey);
+      }
+      // All 11 missing entries refused with reason "bulk-asymmetry".
+      expect(result.filesRefusedStale).toBe(11);
+      const summary = events.find((e) => e.type === "delete-refused-bulk-asymmetry") as
+        | { candidates: number; inScope: number; ratio: number; samplePaths: string[] }
+        | undefined;
+      expect(summary).toBeDefined();
+      expect(summary!.candidates).toBe(11);
+      expect(summary!.inScope).toBe(100);
+      expect(summary!.ratio).toBeCloseTo(0.11, 5);
+      expect(summary!.samplePaths.length).toBeGreaterThan(0);
+      expect(summary!.samplePaths.length).toBeLessThanOrEqual(10);
+      // Journal entries for the missing files SURVIVE — guard never mutates.
+      const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+      expect(Object.keys(journal.files).length).toBe(100);
+      // Per-key delete-refused-stale-etag events for each candidate.
+      const perKeyRefusals = events.filter(
+        (e) => e.type === "delete-refused-stale-etag" && e.reason === "bulk-asymmetry",
+      );
+      expect(perKeyRefusals.length).toBe(11);
+    });
+
+    it("does NOT trip at 9/100 (below ratio): all candidates delete normally", async () => {
+      const { companyRoot } = setupJournal({ total: 100, missing: 9 });
+      vi.mocked(headRemoteFile).mockImplementation(async (_ctx, key) => ({
+        etag: `etag-${parseInt(key.replace(/[^0-9]/g, ""), 10)}`,
+        lastModified: new Date(),
+        size: 5,
+      }));
+
+      const events: Array<{ type: string }> = [];
+      const result = await share({
+        paths: [companyRoot],
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+        skipUnchanged: true,
+        propagateDeletes: true,
+        propagateDeletePolicy: "currency-gated",
+        onEvent: (e) => events.push(e as { type: string }),
+      });
+
+      expect(result.filesDeleted).toBe(9);
+      expect(deleteRemoteFile).toHaveBeenCalledTimes(9);
+      expect(events.find((e) => e.type === "delete-refused-bulk-asymmetry")).toBeUndefined();
+    });
+
+    it("HQ_SYNC_DELETE_BULK_OVERRIDE=1 bypasses the guard: 11/100 deletes proceed", async () => {
+      process.env.HQ_SYNC_DELETE_BULK_OVERRIDE = "1";
+      const { companyRoot } = setupJournal({ total: 100, missing: 11 });
+      vi.mocked(headRemoteFile).mockImplementation(async (_ctx, key) => ({
+        etag: `etag-${parseInt(key.replace(/[^0-9]/g, ""), 10)}`,
+        lastModified: new Date(),
+        size: 5,
+      }));
+
+      const result = await share({
+        paths: [companyRoot],
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+        skipUnchanged: true,
+        propagateDeletes: true,
+        propagateDeletePolicy: "currency-gated",
+      });
+
+      expect(result.filesDeleted).toBe(11);
+      expect(deleteRemoteFile).toHaveBeenCalledTimes(11);
+    });
+
+    it("propagateDeletePolicy: 'all' bypasses the guard: 11/100 deletes proceed", async () => {
+      const { companyRoot } = setupJournal({ total: 100, missing: 11 });
+
+      const result = await share({
+        paths: [companyRoot],
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+        skipUnchanged: true,
+        propagateDeletes: true,
+        propagateDeletePolicy: "all",
+      });
+
+      expect(result.filesDeleted).toBe(11);
+      expect(deleteRemoteFile).toHaveBeenCalledTimes(11);
+    });
+
+    it("fully-empty mirror (100/100) trips the guard — the canonical mass-delete failure mode", async () => {
+      const { companyRoot, journalPath } = setupJournal({ total: 50, missing: 50 });
+      vi.mocked(headRemoteFile).mockImplementation(async (_ctx, key) => ({
+        etag: `etag-${parseInt(key.replace(/[^0-9]/g, ""), 10)}`,
+        lastModified: new Date(),
+        size: 5,
+      }));
+
+      const events: Array<{ type: string; [k: string]: unknown }> = [];
+      const result = await share({
+        paths: [companyRoot],
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+        skipUnchanged: true,
+        propagateDeletes: true,
+        propagateDeletePolicy: "currency-gated",
+        onEvent: (e) => events.push(e as { type: string }),
+      });
+
+      expect(result.filesDeleted).toBe(0);
+      expect(deleteRemoteFile).not.toHaveBeenCalled();
+      expect(result.filesRefusedStale).toBe(50);
+      const summary = events.find((e) => e.type === "delete-refused-bulk-asymmetry") as
+        | { candidates: number; inScope: number; ratio: number }
+        | undefined;
+      expect(summary).toBeDefined();
+      expect(summary!.ratio).toBeCloseTo(1.0, 5);
+      // Journal untouched.
+      const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+      expect(Object.keys(journal.files).length).toBe(50);
+    });
+
+    it("small absolute count (9/9 = 100% ratio but < MIN_ABS=10) does NOT trip: all 9 delete normally", async () => {
+      const { companyRoot } = setupJournal({ total: 9, missing: 9 });
+      vi.mocked(headRemoteFile).mockImplementation(async (_ctx, key) => ({
+        etag: `etag-${parseInt(key.replace(/[^0-9]/g, ""), 10)}`,
+        lastModified: new Date(),
+        size: 5,
+      }));
+
+      const result = await share({
+        paths: [companyRoot],
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+        skipUnchanged: true,
+        propagateDeletes: true,
+        propagateDeletePolicy: "currency-gated",
+      });
+
+      // 9 candidates, ratio 1.0, but abs < 10 → guard does not trip.
+      expect(result.filesDeleted).toBe(9);
+      expect(deleteRemoteFile).toHaveBeenCalledTimes(9);
+    });
+
+    it("owned-only policy also goes through the guard: 11/100 missing direction:'up' entries refused", async () => {
+      const { companyRoot, journalPath } = setupJournal({ total: 100, missing: 11 });
+
+      const events: Array<{ type: string }> = [];
+      const result = await share({
+        paths: [companyRoot],
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+        skipUnchanged: true,
+        propagateDeletes: true,
+        propagateDeletePolicy: "owned-only",
+        onEvent: (e) => events.push(e as { type: string }),
+      });
+
+      expect(result.filesDeleted).toBe(0);
+      expect(deleteRemoteFile).not.toHaveBeenCalled();
+      expect(events.find((e) => e.type === "delete-refused-bulk-asymmetry")).toBeDefined();
+      // Journal entries survive.
+      const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+      expect(Object.keys(journal.files).length).toBe(100);
+    });
+
+    it("direction:'down' entries don't count toward the bulk numerator (owned-only silently skips them)", async () => {
+      // 50 "down" entries all missing locally + 1 "up" entry missing.
+      // Under owned-only: only the 1 "up" candidate goes to toDelete; the
+      // 50 "down" entries are silently dropped from the plan (existing
+      // behavior). The bulk numerator should be 1, not 51 — so the guard
+      // does NOT trip and the 1 legitimate delete proceeds.
+      const companyRoot = path.join(tmpDir, "companies", "acme");
+      fs.mkdirSync(companyRoot, { recursive: true });
+      const files: Record<string, {
+        hash: string; size: number; syncedAt: string;
+        direction: "up" | "down"; remoteEtag: string;
+      }> = {};
+      const now = new Date().toISOString();
+      for (let i = 0; i < 50; i++) {
+        files[`d-${i.toString().padStart(4, "0")}.md`] = {
+          hash: "h", size: 5, syncedAt: now,
+          direction: "down", remoteEtag: `down-etag-${i}`,
+        };
+      }
+      files["only-up.md"] = {
+        hash: "h", size: 5, syncedAt: now,
+        direction: "up", remoteEtag: "up-etag",
+      };
+      const journalPath = path.join(stateDir, "sync-journal.acme.json");
+      fs.writeFileSync(journalPath, JSON.stringify({ version: "1", lastSync: now, files }));
+
+      const result = await share({
+        paths: [companyRoot],
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+        skipUnchanged: true,
+        propagateDeletes: true,
+        propagateDeletePolicy: "owned-only",
+      });
+
+      expect(result.filesDeleted).toBe(1);
+      expect(deleteRemoteFile).toHaveBeenCalledWith(expect.anything(), "only-up.md");
+    });
+  });
 });
 
 // ── Pure-function unit coverage: isEphemeralPath ─────────────────────────────

package/src/cli/share.ts

@@ -716,6 +716,20 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
     filesToDelete: deletePlan.toDelete.length + decommissionPlan.length,
   });
 
+  // Bulk-asymmetry summary event. Emitted once if the circuit-breaker
+  // tripped inside `computeDeletePlan` — see DeletePlan.bulkAsymmetry doc.
+  // Per-key refusal events fire later in the refusedStale loop with
+  // reason: "bulk-asymmetry" so the UI can also show the affected paths.
+  if (deletePlan.bulkAsymmetry) {
+    emit({
+      type: "delete-refused-bulk-asymmetry",
+      candidates: deletePlan.bulkAsymmetry.candidates,
+      inScope: deletePlan.bulkAsymmetry.inScope,
+      ratio: deletePlan.bulkAsymmetry.ratio,
+      samplePaths: deletePlan.bulkAsymmetry.samplePaths,
+    });
+  }
+
   // Stage 2: execute. Skip items pre-classified as no-ops, then for each
   // upload candidate run the HEAD + 3-way conflict check + actual PUT.
   //
@@ -1235,11 +1249,24 @@ function defaultConsoleLogger(event: SyncProgressEvent): void {
       console.error(
         `  ⚠ no-etag-on-record, kept on remote: ${event.path} (journal entry predates etag tracking)`,
       );
+    } else if (event.reason === "bulk-asymmetry") {
+      // The one-shot summary below carries the count + bypass instructions.
+      // Per-key lines stay compact so a 100-candidate refusal doesn't bury
+      // the summary banner.
+      console.error(`  ⚠ bulk-asymmetry refusal, kept on remote: ${event.path}`);
     } else {
       console.error(
         `  ⚠ stale-etag, kept on remote: ${event.path} (journal=${event.journalEtag}, remote=${event.remoteEtag})`,
       );
     }
+  } else if (event.type === "delete-refused-bulk-asymmetry") {
+    const pct = (event.ratio * 100).toFixed(1);
+    console.error(
+      `  ⚠ bulk-asymmetry circuit-breaker tripped: ${event.candidates}/${event.inScope} in-scope journal entries (${pct}%) are missing locally.\n` +
+      `    Refusing to propagate deletes — this looks like a local-mirror loss (moved hqRoot, partial restore, fresh clone, unmounted volume, accidental rm) rather than an intentional cleanup.\n` +
+      `    Sample refused paths: ${event.samplePaths.slice(0, 5).join(", ")}${event.samplePaths.length > 5 ? ", …" : ""}\n` +
+      `    To proceed anyway: re-run with HQ_SYNC_DELETE_BULK_OVERRIDE=1 (or propagateDeletePolicy:"all").`,
+    );
   }
 }
 
@@ -1536,7 +1563,55 @@ function resolveDeleteScopeRoots(
  *                          tracked. `journalEtag` and `remoteEtag` are
  *                          placeholder sentinels — do not display as ETags.
  */
-type RefusedStaleReason = "stale-etag" | "legacy-no-etag";
+type RefusedStaleReason = "stale-etag" | "legacy-no-etag" | "bulk-asymmetry";
+
+/**
+ * Bulk-asymmetry circuit-breaker — refuses to convert a suspiciously-large
+ * fraction of the in-scope journal entries into remote `DeleteObject` calls.
+ *
+ * Failure mode this defends against: the local mirror is corrupt
+ * (moved hqRoot, partial restore from backup, fresh clone over an inherited
+ * `~/.hq/sync-journal.*.json`, unmounted external volume, accidental
+ * `rm -rf` of a populated subtree). `computeDeletePlan` walks every journal
+ * entry, lstats locally, and any ENOENT is a delete candidate; under
+ * `currency-gated` the per-file HEAD passes in the steady state (nobody
+ * else rewrote the object) so the delete proceeds. Per-file currency is
+ * orthogonal to whole-set health — when a large slice of the mirror is
+ * absent at once, the engine should refuse rather than amplify the
+ * accident into a mass-DELETE.
+ *
+ * The guard fires when **both** conditions hold:
+ *   - `candidates / inScope >= BULK_ASYMMETRY_RATIO` (default 10%).
+ *   - `candidates >= BULK_ASYMMETRY_MIN_ABS` (default 10).
+ *
+ * The MIN_ABS floor is what lets small intentional deletes through —
+ * `rm 1 file` from a 5-entry mirror is 20% but 1 absolute candidate; never
+ * tripped. The RATIO is what lets large intentional uploads-then-deletes
+ * through — a 10000-entry journal where 50 files were intentionally
+ * removed is 0.5%; never tripped.
+ *
+ * Bypass paths (both intentional opt-outs of safety):
+ *   - Env `HQ_SYNC_DELETE_BULK_OVERRIDE=1|true|yes` (case-insensitive). The
+ *     rollback knob for the rare legitimate mass-delete; symmetric to
+ *     `HQ_SYNC_DELETE_POLICY` as a per-invocation policy override.
+ *   - `propagateDeletePolicy: "all"`. The emergency-reconcile policy
+ *     already opts out of safety gates (currency check, owned-only).
+ *     This guard honors that explicit opt-out.
+ *
+ * `"owned-only"` and `"currency-gated"` both go through the guard. The
+ * `direction === "up"` filter in `owned-only` is no defense once a user
+ * has ever run full bidirectional sync (every uploaded file gets
+ * direction:'up') — see investigation report
+ * `workspace/reports/indigo-vault-mass-delete-debug.md`.
+ */
+const BULK_ASYMMETRY_RATIO = 0.10;
+const BULK_ASYMMETRY_MIN_ABS = 10;
+const BULK_ASYMMETRY_SAMPLE_CAP = 10;
+
+function isBulkAsymmetryOverride(): boolean {
+  const v = (process.env.HQ_SYNC_DELETE_BULK_OVERRIDE ?? "").toLowerCase();
+  return v === "1" || v === "true" || v === "yes";
+}
 
 /**
  * Three buckets returned by computeDeletePlan, exposed so the execution
@@ -1560,6 +1635,18 @@ interface DeletePlan {
     remoteEtag: string;
     reason: RefusedStaleReason;
   }>;
+  /**
+   * Populated only when the bulk-asymmetry circuit-breaker tripped. The
+   * caller emits `delete-refused-bulk-asymmetry` as a one-shot summary so
+   * the UI gets one banner-grade signal in addition to the per-key
+   * `delete-refused-stale-etag` events under `refusedStale`.
+   */
+  bulkAsymmetry?: {
+    candidates: number;
+    inScope: number;
+    ratio: number;
+    samplePaths: string[];
+  };
 }
 
 /**
@@ -1662,6 +1749,14 @@ async function computeDeletePlan(
   // and the journal-mutation buckets are already settled before any I/O.
   type HeadCandidate = { key: string; journalEtag: string };
   const headCandidates: HeadCandidate[] = [];
+  // Bulk-asymmetry tracking: count every in-scope journal entry (denominator)
+  // and every entry that would have been a delete-candidate before the guard
+  // (numerator). Numerator = headCandidates + owned-only/all toDelete picks +
+  // legacy-no-etag refusals. We do NOT count "ENOENT but ignore-filtered" or
+  // "ENOENT but ephemeral" — those drop out of the plan entirely on their own
+  // and don't reflect mirror-loss intent.
+  let inScopeJournalEntries = 0;
+  let bulkCandidatePicks = 0;
 
   for (const [relativeKey, entry] of Object.entries(journal.files)) {
     const inScope = scopeRoots.some(
@@ -1671,6 +1766,7 @@ async function computeDeletePlan(
         relativeKey.startsWith(`${root}/`),
     );
     if (!inScope) continue;
+    inScopeJournalEntries++;
     const localPath = path.join(syncRoot, relativeKey);
     let presentLocally = true;
     try {
@@ -1694,11 +1790,21 @@ async function computeDeletePlan(
     if (isEphemeralPath(relativeKey)) continue;
 
     if (policy === "all") {
+      // policy:"all" is the explicit-opt-out emergency-reconcile mode; the
+      // bulk-asymmetry guard skips this branch (caller asserted intent).
       plan.toDelete.push(relativeKey);
       continue;
     }
+    bulkCandidatePicks++;
     if (policy === "owned-only") {
-      if (entry.direction !== "up") continue;
+      if (entry.direction !== "up") {
+        // Not a delete candidate under owned-only, but it WAS missing
+        // locally. Don't count it for the bulk guard — direction:'down'
+        // entries that vanish locally are silently ignored by this policy
+        // anyway, so they don't represent intent to mass-delete.
+        bulkCandidatePicks--;
+        continue;
+      }
       plan.toDelete.push(relativeKey);
       continue;
     }
@@ -1716,6 +1822,44 @@ async function computeDeletePlan(
     headCandidates.push({ key: relativeKey, journalEtag });
   }
 
+  // Bulk-asymmetry circuit-breaker. See `BULK_ASYMMETRY_*` constants for
+  // rationale + bypass paths. Skipped under policy:"all" (caller asserted
+  // intent) and under `HQ_SYNC_DELETE_BULK_OVERRIDE` (operator rollback knob).
+  if (
+    policy !== "all" &&
+    !isBulkAsymmetryOverride() &&
+    bulkCandidatePicks >= BULK_ASYMMETRY_MIN_ABS &&
+    inScopeJournalEntries > 0 &&
+    bulkCandidatePicks / inScopeJournalEntries >= BULK_ASYMMETRY_RATIO
+  ) {
+    // Move every staged candidate (both already-bucketed toDelete from
+    // owned-only and queued headCandidates from currency-gated) into
+    // refusedStale with reason "bulk-asymmetry". Journal is not mutated;
+    // no DeleteObject is issued.
+    const samplePaths: string[] = [];
+    const pushRefused = (key: string): void => {
+      plan.refusedStale.push({
+        key,
+        journalEtag: "<bulk-asymmetry>",
+        remoteEtag: "<not-checked>",
+        reason: "bulk-asymmetry",
+      });
+      if (samplePaths.length < BULK_ASYMMETRY_SAMPLE_CAP) {
+        samplePaths.push(key);
+      }
+    };
+    for (const key of plan.toDelete) pushRefused(key);
+    for (const c of headCandidates) pushRefused(c.key);
+    plan.toDelete = [];
+    plan.bulkAsymmetry = {
+      candidates: bulkCandidatePicks,
+      inScope: inScopeJournalEntries,
+      ratio: bulkCandidatePicks / inScopeJournalEntries,
+      samplePaths,
+    };
+    return plan;
+  }
+
   // Stage 2: bounded-parallel HEAD pass. Promise.all over chunks of size
   // `DELETE_PLAN_HEAD_CONCURRENCY` so a large candidate set doesn't
   // serialize into N round-trips, and so we don't burst past the AWS-SDK

package/src/cli/sync.ts

@@ -135,12 +135,47 @@ export type SyncProgressEvent =
        *     `journalEtag` and `remoteEtag` are sentinel strings
        *     (`<legacy-no-etag>` / `<unknown>`) — do not render as ETags.
        *     Consumers should branch on `reason`, not on the etag values.
+       *
+       *   - `"bulk-asymmetry"`: the bulk-asymmetry circuit-breaker tripped
+       *     (see `delete-refused-bulk-asymmetry`). Each candidate that would
+       *     have been deleted also surfaces here for path-level visibility.
+       *     `journalEtag` and `remoteEtag` are sentinel strings
+       *     (`<bulk-asymmetry>` / `<not-checked>`) since no HEAD was issued.
        */
       type: "delete-refused-stale-etag";
       path: string;
       journalEtag: string;
       remoteEtag: string;
-      reason: "stale-etag" | "legacy-no-etag";
+      reason: "stale-etag" | "legacy-no-etag" | "bulk-asymmetry";
+    }
+  | {
+      /**
+       * Emitted at most ONCE per `share()` call when the bulk-asymmetry
+       * circuit-breaker tripped: a large fraction of the in-scope journal
+       * entries are missing locally, suggesting the local mirror is corrupt
+       * (moved hqRoot, partial restore, fresh clone over inherited state,
+       * unmounted volume, accidental `rm -rf`) rather than a deliberate
+       * delete. The engine refuses to convert the missing entries into
+       * remote `DeleteObject` calls; every refused candidate also surfaces
+       * via `delete-refused-stale-etag` with `reason: "bulk-asymmetry"`.
+       *
+       * Trip condition: `candidates >= 10 AND candidates / inScope >= 0.10`.
+       * Bypass: set `HQ_SYNC_DELETE_BULK_OVERRIDE=1` (truthy: `1|true|yes`,
+       * case-insensitive) OR pass `propagateDeletePolicy: "all"` (the
+       * existing emergency-reconcile policy which already opts out of
+       * safety gates).
+       *
+       * `candidates` is the number of journal entries whose local file is
+       * missing AND would have been delete-candidates absent the guard;
+       * `inScope` is the total journal entries under the share's scope
+       * roots; `ratio = candidates / inScope`; `samplePaths` carries up to
+       * 10 refused keys for diagnostic display.
+       */
+      type: "delete-refused-bulk-asymmetry";
+      candidates: number;
+      inScope: number;
+      ratio: number;
+      samplePaths: string[];
     }
   | {
       /**
@@ -576,6 +611,16 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
         // drift independently of mtime drift. Stamp mtimeMs from localLstat
         // (5.36.0) so the next push planner's lstat fast-path can skip the
         // SHA256 for this file without reading its bytes.
+        //
+        // 5.37.0 ordering invariant: downloadFile applies hq-mtime via
+        // utimesSync AFTER its byte write but BEFORE returning, and this
+        // lstat runs AFTER downloadFile resolves — so localLstat.mtimeMs
+        // already reflects the source-stamped mtime, not the wall-clock
+        // write-time. The journal therefore matches what the next push's
+        // lstat fast-path will see, and the file is correctly skipped on
+        // re-sync instead of being hashed every tick. Do not move this
+        // lstat earlier; do not stamp the journal from any pre-download
+        // mtime.
         updateEntry(
           journal,
           remoteFile.key,