@indigoai-us/hq-cloud 6.0.1 → 6.0.2

package/src/cli/share.test.ts

@@ -1132,14 +1132,12 @@ describe("share", () => {
           }),
         );
 
-        // Currency-gated HEADs the candidate; return an etag matching the
-        // journal so the entry resolves as "remote still current → safe to
-        // tombstone."
-        vi.mocked(headRemoteFile).mockResolvedValueOnce({
-          lastModified: new Date(),
-          etag: '"personal-vault-drift-etag"',
-          size: 1054,
-        });
+        // (Pre-6.0.2: currency-gated would have HEADed the candidate; the
+        // mockResolvedValueOnce that lived here is now redundant because the
+        // vault-litter drain bypasses HEAD entirely for `.drift-` markers.
+        // Leaving the mock here would queue an unconsumed return value and
+        // poison the next test's HEAD call — removed so the assertion above
+        // verifies the litter path, not the etag path.)
 
         const personalCtx = makeEntityContext({
           uid: "prs_01HASSAANTESTUSER",
@@ -1970,14 +1968,23 @@ describe("share", () => {
     expect(uploadFile).not.toHaveBeenCalled();
   });
 
-  it("conflict-mirror exclusion: journaled mirror with local-missing is NOT swept by delete plan", async () => {
+  it("vault-litter drain (6.0.2): journaled `.conflict-*` mirror with local-missing IS swept by the delete plan", async () => {
+    // Updated semantics (6.0.2): the existing-litter state — a conflict
+    // mirror that leaked into the journal from a prior buggy upload and was
+    // subsequently deleted locally — used to survive every sync because the
+    // `isEphemeralPath` skip in computeDeletePlan was wired to drop it
+    // before tombstoning. The deferred "dedicated reconcile command" the
+    // doc-comment promised never materialized, and the litter accumulated
+    // until users noticed it (e.g. the May-27 `personal/.obsidian/*.drift-*`
+    // pair on the EC2 outpost). The fix: drain unconditionally via the
+    // litter bucket — bypass shouldSync, ephemeral-skip, policy, and the
+    // bulk-asymmetry breaker. By construction litter is not user content
+    // (the EPHEMERAL_PATH_PATTERN / DRIFT_PATH_PATTERN regexes are precise
+    // enough that a false-positive on a real user filename is vanishingly
+    // unlikely), so the absence of those gates is the correct behavior.
     const companyRoot = path.join(tmpDir, "companies", "acme");
     fs.mkdirSync(companyRoot, { recursive: true });
-    // Simulate the existing-litter state: a conflict mirror that leaked
-    // into the journal in a prior buggy version. Locally missing (user
-    // already deleted it). The regular delete plan must NOT issue a
-    // DeleteObject — that's the dedicated reconcile command's job, and
-    // a sync should not accidentally race a user reviewing the mirror.
+
     const journalPath = path.join(stateDir, "sync-journal.acme.json");
     fs.writeFileSync(
       journalPath,
@@ -1999,7 +2006,10 @@ describe("share", () => {
       }),
     );
 
-    // HEAD needed for the non-mirror entry under currency-gated.
+    // HEAD needed for the non-mirror entry under currency-gated. The litter
+    // drain bypasses HEAD by design — the etag check encodes a "remote
+    // hasn't drifted since I last synced" invariant that doesn't apply to
+    // never-should-have-been-there litter.
     vi.mocked(headRemoteFile).mockResolvedValue({
       lastModified: new Date(),
       etag: '"regular-etag"',
@@ -2015,19 +2025,81 @@ describe("share", () => {
       propagateDeletes: true,
     });
 
-    expect(result.filesDeleted).toBe(1);
-    expect(deleteRemoteFile).toHaveBeenCalledTimes(1);
+    // BOTH the regular file AND the conflict mirror tombstone in one pass.
+    expect(result.filesDeleted).toBe(2);
+    expect(deleteRemoteFile).toHaveBeenCalledTimes(2);
     expect(deleteRemoteFile).toHaveBeenCalledWith(expect.anything(), "regular.md");
-    expect(deleteRemoteFile).not.toHaveBeenCalledWith(
+    expect(deleteRemoteFile).toHaveBeenCalledWith(
       expect.anything(),
-      expect.stringContaining("conflict-"),
+      "CLAUDE.md.conflict-2026-05-13T19-40-40Z-e5797a.md",
     );
-    // Mirror's journal entry survives — reconcile command (separate skill)
-    // sweeps it once the user explicitly opts in.
+    // Both journal entries are removed by the delete loop's removeEntry call.
     const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
     expect(
       journal.files["CLAUDE.md.conflict-2026-05-13T19-40-40Z-e5797a.md"],
-    ).toBeDefined();
+    ).toBeUndefined();
+    expect(journal.files["regular.md"]).toBeUndefined();
+  });
+
+  it("vault-litter drain (6.0.2): `.drift-<unixts>-<pid>` rescue markers drain regardless of personal-vault exclusion path (the live obsidian case)", async () => {
+    // The exact failure mode that motivated the fix: a rescue-overlay
+    // `.drift-` marker sitting under a personal-vault default exclusion
+    // (`.obsidian/**`) survives every sync because `shouldSync` rejects
+    // the parent path before the delete plan ever considers the entry.
+    // The litter bypass routes such keys around shouldSync directly into
+    // `litterToDelete`.
+    const stateDirPersonal = fs.mkdtempSync(
+      path.join(os.tmpdir(), "hq-state-prs-drift-"),
+    );
+    process.env.HQ_STATE_DIR = stateDirPersonal;
+    try {
+      const journalPath = path.join(
+        stateDirPersonal,
+        "sync-journal.__hq_personal_vault__.json",
+      );
+      fs.writeFileSync(
+        journalPath,
+        JSON.stringify({
+          version: "1",
+          lastSync: new Date().toISOString(),
+          files: {
+            "personal/.obsidian/graph.json.drift-1779863862-42519": {
+              hash: "h", size: 1054, syncedAt: new Date().toISOString(),
+              direction: "down",
+              remoteEtag: "obsidian-drift-etag",
+            },
+          },
+        }),
+      );
+
+      const personalCtx = makeEntityContext({
+        uid: "prs_01HASSAANTESTUSER",
+        slug: "__hq_personal_vault__",
+        bucketName: "hq-vault-prs-01HASSAANTESTUSER",
+      });
+
+      const result = await share({
+        paths: [tmpDir],
+        entityContext: personalCtx,
+        hqRoot: tmpDir,
+        personalMode: true,
+        skipUnchanged: true,
+        propagateDeletes: true,
+      });
+
+      expect(result.filesDeleted).toBe(1);
+      expect(deleteRemoteFile).toHaveBeenCalledWith(
+        expect.anything(),
+        "personal/.obsidian/graph.json.drift-1779863862-42519",
+      );
+      const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+      expect(
+        journal.files["personal/.obsidian/graph.json.drift-1779863862-42519"],
+      ).toBeUndefined();
+    } finally {
+      fs.rmSync(stateDirPersonal, { recursive: true, force: true });
+      delete process.env.HQ_STATE_DIR;
+    }
   });
 
   // ── personalMode ───────────────────────────────────────────────────────────

package/src/cli/share.ts

@@ -100,6 +100,64 @@ export const EPHEMERAL_PATH_PATTERN =
  * matches anywhere in the string, which is fine: the
  * `.conflict-<ISO>-<hash>.` token is unambiguous.
  */
+/**
+ * Rescue-overlay drift marker pattern. Written by `replace-rescue.sh`
+ * (`rescue_one` / `conflict_one`) when its rescue target already exists:
+ * `<orig>.drift-<unix-ts>-<pid>` — a collision suffix so the previous override
+ * is never silently overwritten. Distinct from `EPHEMERAL_PATH_PATTERN` —
+ * different producer (the rescue script vs the sync conflict-mirror path),
+ * different filename grammar (decimal timestamp + decimal pid vs ISO timestamp
+ * + hex machine hash). Like conflict mirrors, drift markers should never live
+ * in the vault; if a buggy past run uploaded one, the delete plan must be
+ * able to drain it regardless of where it sits.
+ */
+export const DRIFT_PATH_PATTERN = /\.drift-\d+-\d+$/;
+
+/**
+ * True iff the key is local-only ephemeral vault litter — a sync conflict
+ * mirror (`.conflict-<ISO>-<machine>[.ext]`) OR a rescue drift marker
+ * (`.drift-<unixts>-<pid>`).
+ *
+ * Used by `computeDeletePlan` to UNCONDITIONALLY drain existing vault litter,
+ * bypassing every "skip" gate that would otherwise trap it:
+ *
+ *   1. `shouldSync` — the personal-vault default exclusions (introduced in
+ *      5.25) reject paths like `**.obsidian/**`, `**.env`, `**output/**`,
+ *      `**node_modules/**`, etc. from BOTH the upload walk AND the delete
+ *      plan. That's correct for fresh content (don't upload), but it also
+ *      strands any litter already in the vault at those paths — `<orig>.drift`
+ *      / `<orig>.conflict` files inside an excluded parent get re-pulled
+ *      every sync and never tombstoned. The live obsidian case here:
+ *      `personal/.obsidian/graph.json.drift-1779863862-42519` survived every
+ *      sync for two weeks because `.obsidian` is excluded.
+ *   2. `isEphemeralPath` — the existing skip in `computeDeletePlan` was
+ *      designed to prevent a FRESH local `.conflict-*` mirror (written by the
+ *      pull leg's "keep" branch as a side-by-side comparison file) from being
+ *      miscounted as a delete candidate before the user has resolved the
+ *      conflict. That intent stands, but it accidentally protects EXISTING
+ *      cloud litter too. The fix: when the local file is already gone AND the
+ *      key matches the litter pattern, drain it; the "fresh mirror, hasn't
+ *      been resolved yet" case is impossible because that mirror would still
+ *      be on disk.
+ *   3. The policy gate — `owned-only`'s direction filter and
+ *      `currency-gated`'s etag check both encode user-content invariants
+ *      that don't apply to litter (a `.drift-…-PID` file has no meaningful
+ *      "ownership" or "freshness"; it's a stale local-overlay collision
+ *      marker, by construction).
+ *   4. The bulk-asymmetry circuit breaker — litter cleanup is intentional
+ *      ratchet-drain, not a "corrupt local mirror, refuse mass-delete"
+ *      signal. Litter is queued via a separate bucket the breaker never
+ *      sweeps.
+ *
+ * Together: a vault key matching either pattern always tombstones on the
+ * next push leg, regardless of personal-vault exclusions, ephemeral skip,
+ * policy, or breaker. Producer-side exclusions (upload walker + rescue
+ * script) close the ratchet on new litter; this drains the legacy buildup.
+ */
+export function isVaultLitterArtifact(p: string): boolean {
+  return EPHEMERAL_PATH_PATTERN.test(p) || DRIFT_PATH_PATTERN.test(p);
+}
+
 export function isEphemeralPath(p: string): boolean {
   return EPHEMERAL_PATH_PATTERN.test(p);
 }
@@ -1799,12 +1857,21 @@ async function computeDeletePlan(
   // and the journal-mutation buckets are already settled before any I/O.
   type HeadCandidate = { key: string; journalEtag: string };
   const headCandidates: HeadCandidate[] = [];
+  // Litter drain bucket — kept separate from `plan.toDelete` so the
+  // bulk-asymmetry breaker (which moves toDelete + headCandidates into
+  // `refusedStale` when it trips) can't sweep these out. See
+  // `isVaultLitterArtifact` for the patterns and rationale: by construction
+  // these aren't user content losses, so a high ratio of litter must not
+  // refuse the drain — that's the whole point of the bypass. Merged into
+  // `plan.toDelete` after the breaker check.
+  const litterToDelete: string[] = [];
   // 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.
+  // and don't reflect mirror-loss intent — and litter drains (see above),
+  // which are intentional ratchet-cleanup, not mass-delete intent.
   let inScopeJournalEntries = 0;
   let bulkCandidatePicks = 0;
 
@@ -1834,9 +1901,28 @@ async function computeDeletePlan(
       }
     }
     if (presentLocally) continue;
+
+    // Vault-litter drain (6.0.2): conflict mirrors + rescue drift markers
+    // ALWAYS drain, bypassing `shouldSync` (which would skip them when the
+    // parent path is in personal-vault default exclusions like
+    // `.obsidian/**`), the `isEphemeralPath` skip (which protects FRESH
+    // local conflict mirrors but accidentally also protects existing vault
+    // litter), the policy gate (no meaningful ownership/freshness for
+    // litter), and the bulk-asymmetry breaker (intentional ratchet-drain,
+    // not corrupt-mirror mass-delete intent). See `isVaultLitterArtifact`
+    // for the full rationale and patterns. Queued via the separate
+    // `litterToDelete` bucket so the breaker can't sweep these out.
+    if (isVaultLitterArtifact(relativeKey)) {
+      litterToDelete.push(relativeKey);
+      continue;
+    }
+
     if (!shouldSync(localPath, false) && !shouldSync(localPath, true)) continue;
     // Ephemeral artifacts (conflict mirrors) never propagate-delete via the
-    // normal path — see EPHEMERAL_PATH_PATTERN doc.
+    // normal path — see EPHEMERAL_PATH_PATTERN doc. NOTE: this is a no-op
+    // post-litter-drain above — any key matching EPHEMERAL_PATH_PATTERN was
+    // already routed to `litterToDelete`. Retained as defense-in-depth +
+    // documentation of the policy-side intent.
     if (isEphemeralPath(relativeKey)) continue;
 
     if (policy === "all") {
@@ -1907,6 +1993,12 @@ async function computeDeletePlan(
       ratio: bulkCandidatePicks / inScopeJournalEntries,
       samplePaths,
     };
+    // Litter still drains even when the breaker trips — see `litterToDelete`
+    // declaration. The breaker protects against corrupt-mirror mass-deletes
+    // of user content; litter cleanup is orthogonal and should never be
+    // refused for the same reason new-litter producer-side exclusions
+    // shouldn't block it.
+    plan.toDelete.push(...litterToDelete);
     return plan;
   }
 
@@ -1944,6 +2036,13 @@ async function computeDeletePlan(
     }
   }
 
+  // Litter drains alongside the normal candidates — bypasses every gate but
+  // settles into the same plan.toDelete bucket so the share() executor's
+  // delete loop tombstones each key identically (DeleteObject + remove from
+  // journal). Merged at the end so the bulk-asymmetry breaker above had its
+  // chance to NOT include litter in either the numerator or the sweep.
+  plan.toDelete.push(...litterToDelete);
+
   return plan;
 }