@indigoai-us/hq-cloud 6.0.0 → 6.0.2

package/src/cli/share.test.ts

@@ -1091,6 +1091,140 @@ describe("share", () => {
     expect(journal.files["dangling-link.md"]).toBeDefined();
   });
 
+  it(
+    "personal-vault override: `owned-only` is coerced to `currency-gated` so a direction:'down' " +
+      "entry whose local file is gone DOES tombstone in the vault (the May-27 .drift-* leak class)",
+    async () => {
+      // The personal vault is a single-human-many-machines target. The
+      // owned-only "I won't tombstone peer content" rule has no peer to
+      // protect against, so it traps legitimate local deletes as permanent
+      // vault litter — exactly what the May-27 `personal/.obsidian/*.drift-*`
+      // pair did on this EC2 (journal direction "down", local rm, push
+      // silently swallowed the delete). Coercing to currency-gated keeps the
+      // only safety intent that still applies (HEAD-verify etag matches the
+      // journal before tombstone) without the multi-user premise.
+      const stateDirPersonal = fs.mkdtempSync(
+        path.join(os.tmpdir(), "hq-state-prs-"),
+      );
+      process.env.HQ_STATE_DIR = stateDirPersonal;
+      try {
+        // Personal-vault syncRoot is `hqRoot` itself in personalMode, so the
+        // missing file's absolute path resolves to <hqRoot>/<key>.
+        // No on-disk file = local missing. Journal records a prior pull.
+        const journalPath = path.join(
+          stateDirPersonal,
+          "sync-journal.__hq_personal_vault__.json",
+        );
+        fs.writeFileSync(
+          journalPath,
+          JSON.stringify({
+            version: "1",
+            lastSync: new Date().toISOString(),
+            files: {
+              "personal/scripts/run-project.sh.drift-1779863862-42519": {
+                hash: "personal-vault-drift-hash",
+                size: 1054,
+                syncedAt: new Date(Date.now() - 86400000).toISOString(),
+                direction: "down",
+                remoteEtag: "personal-vault-drift-etag",
+              },
+            },
+          }),
+        );
+
+        // (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",
+          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,
+          // Caller pinned owned-only. The override MUST take precedence on a
+          // personal-vault entity — the whole point of the fix is that owned-
+          // only's "don't tombstone peer-uploaded content" rule has no peer
+          // to protect against here, so we coerce to currency-gated.
+          propagateDeletePolicy: "owned-only",
+        });
+
+        expect(result.filesDeleted).toBe(1);
+        expect(deleteRemoteFile).toHaveBeenCalledWith(
+          expect.anything(),
+          "personal/scripts/run-project.sh.drift-1779863862-42519",
+        );
+        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        expect(
+          journal.files["personal/scripts/run-project.sh.drift-1779863862-42519"],
+        ).toBeUndefined();
+      } finally {
+        fs.rmSync(stateDirPersonal, { recursive: true, force: true });
+        delete process.env.HQ_STATE_DIR;
+      }
+    },
+  );
+
+  it(
+    "personal-vault override does NOT apply to company vaults: `owned-only` on cmp_ entity still " +
+      "refuses to tombstone a direction:'down' entry (multi-user curation intact)",
+    async () => {
+      // Sibling guard for the previous test: the override is scoped strictly
+      // to `prs_` entities. Company vaults preserve owned-only's multi-user
+      // semantics — a behind machine pulling Alice's upload, then rm'ing it
+      // locally, must NOT tombstone Alice's file. Without this guard the
+      // override could silently widen its blast radius the next time someone
+      // refactors share()'s entity-typing.
+      const companyRoot = path.join(tmpDir, "companies", "acme");
+      fs.mkdirSync(companyRoot, { recursive: true });
+      // No file on disk under companies/acme/peer-uploaded.md → local missing.
+
+      const journalPath = path.join(stateDir, "sync-journal.acme.json");
+      fs.writeFileSync(
+        journalPath,
+        JSON.stringify({
+          version: "1",
+          lastSync: new Date().toISOString(),
+          files: {
+            "peer-uploaded.md": {
+              hash: "alice-hash",
+              size: 100,
+              syncedAt: new Date(Date.now() - 86400000).toISOString(),
+              direction: "down",
+              remoteEtag: "alice-etag",
+            },
+          },
+        }),
+      );
+
+      const result = await share({
+        paths: [companyRoot],
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+        skipUnchanged: true,
+        propagateDeletes: true,
+        // Company-vault entity (cmp_) → owned-only stays in effect.
+        propagateDeletePolicy: "owned-only",
+      });
+
+      expect(result.filesDeleted).toBe(0);
+      expect(deleteRemoteFile).not.toHaveBeenCalled();
+      const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+      expect(journal.files["peer-uploaded.md"]).toBeDefined();
+    },
+  );
+
   it("propagateDeletes: deletes journal-tracked files whose local copy is gone", async () => {
     const companyRoot = path.join(tmpDir, "companies", "acme");
     fs.mkdirSync(companyRoot, { recursive: true });
@@ -1834,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,
@@ -1863,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"',
@@ -1879,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);
 }
@@ -538,7 +596,7 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
   // `propagateDeletePolicy: "currency-gated"` (explicit) or
   // `HQ_SYNC_DELETE_POLICY=currency-gated` (env, honored by sync-runner).
   // The default flip to `"currency-gated"` is scheduled for 5.25.0.
-  const propagateDeletePolicy: "currency-gated" | "owned-only" | "all" =
+  let propagateDeletePolicy: "currency-gated" | "owned-only" | "all" =
     options.propagateDeletePolicy ?? "owned-only";
   const emit = options.onEvent ?? defaultConsoleLogger;
 
@@ -581,6 +639,28 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
   let ctx: EntityContext = entityContext
     ? entityContext
     : await resolveEntityContext(companyRef, vaultConfig!);
+
+  // Personal-vault policy correction (6.0.1). The `owned-only` rule encodes a
+  // multi-user curation premise — "don't tombstone peer-uploaded content even
+  // if my journal says I pulled it" — which is meaningful when several humans
+  // share a company bucket (a behind machine's first sync must not erase
+  // recent uploads from peers). On a personal vault that premise collapses:
+  // every file is the same human's content, just routed through different
+  // machines, and `direction: "down"` only means "uploaded from my laptop,
+  // pulled by my EC2" — it never means "uploaded by someone else." With
+  // `owned-only` in effect, `rm <file>` followed by `hq sync` silently fails
+  // to propagate the delete, leaving permanent vault litter (the May-27
+  // `personal/.obsidian/*.drift-*` files were diagnosed exactly this way).
+  // The etag-based `currency-gated` policy already captures the only safety
+  // intent that survives the single-user case ("don't tombstone if remote
+  // drifted since I last synced"); coerce to it here so the policy is right
+  // regardless of which caller's default landed. Explicit `"all"` is
+  // preserved — it's the emergency-reconcile opt-out and the caller has
+  // already asserted intent.
+  if (ctx.uid.startsWith("prs_") && propagateDeletePolicy === "owned-only") {
+    propagateDeletePolicy = "currency-gated";
+  }
+
   // Remote keys are company-relative; the on-disk scoping prefix is
   // companies/{slug}/. Anything outside this folder gets skipped to avoid
   // leaking cross-company state into the vault.
@@ -1777,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;
 
@@ -1812,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") {
@@ -1885,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;
   }
 
@@ -1922,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;
 }