@indigoai-us/hq-cloud 6.14.46 → 6.14.48

package/src/cli/share.test.ts

@@ -2826,17 +2826,25 @@ describe("share", () => {
   });
 
   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)",
+    "vault-litter drain: a `.drift-*` marker with direction:'down' and NO delete intent tombstones " +
+      "even under owned-only, because litter bypasses the policy gate (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.
+      // Provenance: this test was written for a `prs_`-scoped coercion that
+      // rewrote owned-only -> currency-gated. That coercion is gone (6.14.48 —
+      // it silently defeated the rollback knob; see `createPushRunContext`).
+      // The test still passes, and is retained, because what actually drains
+      // this key is the vault-litter path (6.0.2): `isVaultLitterArtifact`
+      // routes `.drift-<ts>-<pid>` keys to `litterToDelete` BEFORE any policy,
+      // intent, ignore-filter or breaker check runs. That is the durable
+      // guarantee worth pinning — the May-27 `personal/.obsidian/*.drift-*`
+      // pair (journal direction "down", local rm, push silently swallowed the
+      // delete) must drain regardless of which delete policy is in force.
+      //
+      // Note the inputs deliberately keep `direction: "down"`, no
+      // `localDeleteIntent`, and an explicit `owned-only` policy: every one of
+      // those would refuse this key on the normal path, so a regression that
+      // removed the litter bypass would fail here rather than silently
+      // re-stranding litter.
       const stateDirPersonal = fs.mkdtempSync(
         path.join(os.tmpdir(), "hq-state-prs-"),
       );
@@ -2886,10 +2894,8 @@ describe("share", () => {
           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.
+          // Pinned owned-only — the strictest policy. Litter must drain
+          // anyway; that bypass is the property under test.
           propagateDeletePolicy: "owned-only",
         });
 
@@ -2995,15 +3001,14 @@ describe("share", () => {
   });
 
   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)",
+    "owned-only on a cmp_ entity 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.
+      // owned-only's multi-user semantics: a behind machine that pulled
+      // Alice's upload and then rm'd it locally must NOT tombstone Alice's
+      // file. Paired with the prs_ test below, this pins owned-only as
+      // uniformly strict across BOTH vault kinds — the property a rollback
+      // knob has to have to be worth reaching for.
       const companyRoot = path.join(tmpDir, "companies", "acme");
       fs.mkdirSync(companyRoot, { recursive: true });
       // No file on disk under companies/acme/peer-uploaded.md → local missing.
@@ -3044,6 +3049,118 @@ describe("share", () => {
     },
   );
 
+  it(
+    "ROLLBACK KNOB: owned-only is honored on a prs_ personal vault — an intent-less entry with a " +
+      "matching remote etag is REFUSED, not deleted",
+    async () => {
+      // Regression guard for the coercion removed in 6.14.48. A `prs_`-scoped
+      // rewrite of owned-only -> currency-gated used to sit in
+      // `createPushRunContext`. While both policies refused intent-less
+      // deletes it was invisible. Once currency-gated started authorizing on
+      // ETag currency alone, that rewrite meant an operator who set
+      // `HQ_SYNC_DELETE_POLICY=owned-only` — the documented rollback, reached
+      // for precisely BECAUSE deletes were misbehaving — still got intent-less
+      // etag-only deletes on their personal vault. The rollback rolled back
+      // company vaults only.
+      //
+      // The inputs below are exactly the shape that DOES delete under the
+      // default policy (see "currency-gated: propagates a delete with NO
+      // watcher intent…"): local file absent, no `localDeleteIntent`, journal
+      // etag matching live remote. Under owned-only it must refuse. If the
+      // coercion ever returns, `filesDeleted` becomes 1 and this fails.
+      const stateDirPersonal = fs.mkdtempSync(
+        path.join(os.tmpdir(), "hq-state-prs-rollback-"),
+      );
+      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: {
+              // direction:"up" — so the refusal cannot be attributed to
+              // owned-only's direction filter. The ONLY thing refusing this
+              // key is the intent requirement the rollback restores.
+              "personal/knowledge/gone.md": {
+                hash: "rollback-hash",
+                size: 42,
+                syncedAt: new Date(Date.now() - 86400000).toISOString(),
+                direction: "up",
+                remoteEtag: "rollback-etag",
+                kind: "file",
+                // NO localDeleteIntent — no watcher was running.
+              },
+            },
+          }),
+        );
+
+        // Live remote still matches the journal — so under currency-gated this
+        // key is a definite `toDelete`. Without this, the beforeEach default
+        // (null = 404) would route a regression to `toTombstone` instead and
+        // the test would catch it only via the weaker journal assertion.
+        //
+        // Deliberately NOT `mockResolvedValueOnce`: on the PASSING path
+        // owned-only refuses before any HEAD is issued, so a queued one-shot
+        // would go unconsumed and leak into the next test (`vi.clearAllMocks`
+        // in afterEach does not drain a `…Once` queue — it clears call
+        // records, not queued implementations). That is the same trap already
+        // documented in the `.drift-*` litter test above. A persistent impl
+        // reset in `finally` cannot leak either way.
+        vi.mocked(headRemoteFile).mockResolvedValue({
+          lastModified: new Date(),
+          etag: '"rollback-etag"',
+          size: 42,
+        });
+
+        const refusals: Array<{ path: string; reason: string }> = [];
+        const result = await share({
+          paths: [tmpDir],
+          entityContext: makeEntityContext({
+            uid: "prs_01HASSAANTESTUSER",
+            slug: "__hq_personal_vault__",
+            bucketName: "hq-vault-prs-01HASSAANTESTUSER",
+          }),
+          hqRoot: tmpDir,
+          personalMode: true,
+          skipUnchanged: true,
+          propagateDeletes: true,
+          propagateDeletePolicy: "owned-only",
+          onEvent: (event) => {
+            if (event.type === "delete-refused-stale-etag") {
+              refusals.push({ path: event.path, reason: event.reason });
+            }
+          },
+        });
+
+        expect(result.filesDeleted).toBe(0);
+        expect(deleteRemoteFile).not.toHaveBeenCalled();
+        // owned-only refuses on the intent gate, which sits BEFORE the HEAD
+        // pass — so no currency check is ever issued. Asserting this also
+        // keeps the mock above honest about never being consumed.
+        expect(headRemoteFile).not.toHaveBeenCalled();
+        // Refused for want of an intent — NOT silently dropped, and not
+        // refused for some incidental reason that would mask a regression.
+        expect(refusals).toEqual([
+          { path: "personal/knowledge/gone.md", reason: "missing-delete-intent" },
+        ]);
+        // Journal entry survives, so a later run (or a watcher-minted intent)
+        // can still authorize the delete properly.
+        const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+        expect(journal.files["personal/knowledge/gone.md"]).toBeDefined();
+      } finally {
+        vi.mocked(headRemoteFile).mockReset();
+        vi.mocked(headRemoteFile).mockResolvedValue(null);
+        fs.rmSync(stateDirPersonal, { recursive: true, force: true });
+        delete process.env.HQ_STATE_DIR;
+      }
+    },
+  );
+
   it("propagateDeletes: deletes journal-tracked files whose local copy is gone", async () => {
     const companyRoot = path.join(tmpDir, "companies", "acme");
     fs.mkdirSync(companyRoot, { recursive: true });
@@ -3806,7 +3923,11 @@ describe("share", () => {
       expect.objectContaining({
         type: "delete-refused-stale-etag",
         path: "racy.md",
-        reason: "intent-changed",
+        // The file came back on disk between planning and applying. That is
+        // now reported as what it is, rather than as an intent-version change:
+        // the re-check is no longer nested inside the intent branch, so it
+        // also covers etag-only candidates that carry no intent version.
+        reason: "recreated-locally",
       }),
     );
   });
@@ -3974,20 +4095,23 @@ describe("share", () => {
 
     expect(result.filesDeleted).toBe(0);
     expect(deleteRemoteFile).not.toHaveBeenCalled();
-    // HEAD must NOT be called — the explicit-intent gate rejects legacy
-    // entries before any remote operation.
+    // HEAD must NOT be called — an entry with no recorded etag has nothing to
+    // compare against, so currency-gated refuses it before any remote
+    // operation. (Pre-etag-gated-deletes this was refused one gate earlier, for
+    // want of a watcher intent; the outcome — nothing deleted, no remote call —
+    // is deliberately identical.)
     expect(headRemoteFile).not.toHaveBeenCalled();
     const refused = events.find((e) => e.type === "delete-refused-stale-etag");
     expect(refused).toMatchObject({
-      journalEtag: "<missing-delete-intent>",
-      reason: "missing-delete-intent",
+      journalEtag: "<legacy-no-etag>",
+      reason: "legacy-no-etag",
     });
     expect(result.filesRefusedStale).toBe(1);
     expect(result.pathResults).toContainEqual({
       path: "legacy-no-etag.md",
       status: "refused",
       operation: "delete",
-      reason: "missing-delete-intent",
+      reason: "legacy-no-etag",
     });
   });
 
@@ -4047,6 +4171,366 @@ describe("share", () => {
     );
   });
 
+  // ── etag-gated deletes without a watcher ──────────────────────────────────
+  //
+  // A delete intent is minted ONLY by a live watcher at the instant it sees the
+  // unlink. Three of the four ways HQ syncs never construct a watcher (outpost
+  // and agent boxes run a one-shot runner, `hq sync now` is one-shot, and the
+  // desktop drops the whole TreeWatcher when Instant-sync is off), so requiring
+  // an intent made deletes structurally impossible there rather than merely
+  // gated. currency-gated now authorizes on etag currency alone.
+  //
+  // The per-file question is unchanged: "has any peer touched this since we
+  // journaled it". The whole-set question stays with the bulk-asymmetry
+  // breaker, which these candidates still count toward — see the breaker
+  // coverage above and policy `sync-delete-bulk-asymmetry-guard`.
+
+  it("currency-gated: propagates a delete with NO watcher intent when the remote etag still matches", async () => {
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    const journalPath = path.join(stateDir, "sync-journal.acme.json");
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          "notes/gone.md": {
+            hash: "h", size: 12, syncedAt: new Date().toISOString(),
+            direction: "down",
+            remoteEtag: "current-etag",
+            kind: "file",
+            // NO localDeleteIntent — deleted while no watcher was running.
+          },
+        },
+      }),
+    );
+    vi.mocked(headRemoteFile).mockResolvedValueOnce({
+      lastModified: new Date(),
+      etag: '"current-etag"',
+      size: 12,
+    });
+
+    const result = await share({
+      paths: [companyRoot],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      skipUnchanged: true,
+      propagateDeletes: true,
+      propagateDeletePolicy: "currency-gated",
+    });
+
+    expect(result.filesDeleted).toBe(1);
+    expect(deleteRemoteFile).toHaveBeenCalledWith(expect.anything(), "notes/gone.md");
+  });
+
+  it("currency-gated: refuses an intent-less delete when a peer has touched the remote", async () => {
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    const journalPath = path.join(stateDir, "sync-journal.acme.json");
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          "notes/peer-edited.md": {
+            hash: "h", size: 12, syncedAt: new Date().toISOString(),
+            direction: "down",
+            remoteEtag: "etag-we-journaled",
+            kind: "file",
+          },
+        },
+      }),
+    );
+    // A peer overwrote it since we journaled — their work must survive.
+    vi.mocked(headRemoteFile).mockResolvedValueOnce({
+      lastModified: new Date(),
+      etag: '"a-different-etag"',
+      size: 99,
+    });
+
+    const events: Array<{ type: string; reason?: 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(0);
+    expect(deleteRemoteFile).not.toHaveBeenCalled();
+    expect(events).toContainEqual(
+      expect.objectContaining({ type: "delete-refused-stale-etag", reason: "stale-etag" }),
+    );
+  });
+
+  it("currency-gated: abandons an etag-only delete when the file reappears between plan and apply", async () => {
+    // Guards the apply-time absence re-check in `executeDeletes`. That check
+    // used to live INSIDE the intent-version branch, so it was skipped for any
+    // item carrying `intentVersion: null`. That was harmless while null meant
+    // only litter and decommission — but etag-only candidates now travel with
+    // `intentVersion: null` too, and without the restructure a file recreated
+    // during the sync would be deleted from the remote while present on disk.
+    //
+    // The recreate is staged from inside the delete-plan HEAD, which is the
+    // real TOCTOU window: planning has already decided the file is absent, and
+    // the apply loop has not yet run. The push plan is computed BEFORE the
+    // delete plan, so the new file is not uploaded by this run — it is purely
+    // a late arrival the delete loop must notice.
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    const recreatedPath = path.join(companyRoot, "notes", "gone.md");
+    const journalPath = path.join(stateDir, "sync-journal.acme.json");
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          "notes/gone.md": {
+            hash: "h", size: 12, syncedAt: new Date().toISOString(),
+            direction: "down",
+            remoteEtag: "current-etag",
+            kind: "file",
+            // NO localDeleteIntent — this is an etag-only candidate.
+          },
+        },
+      }),
+    );
+    vi.mocked(headRemoteFile).mockImplementationOnce(async () => {
+      // A pull leg (or the user) puts the file back, mid-sync.
+      fs.mkdirSync(path.dirname(recreatedPath), { recursive: true });
+      fs.writeFileSync(recreatedPath, "back again");
+      return { lastModified: new Date(), etag: '"current-etag"', size: 12 };
+    });
+
+    const events: Array<{ type: string; reason?: 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(0);
+    expect(deleteRemoteFile).not.toHaveBeenCalled();
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        type: "delete-refused-stale-etag",
+        reason: "recreated-locally",
+      }),
+    );
+    // The file that came back is still on disk — the whole point.
+    expect(fs.existsSync(recreatedPath)).toBe(true);
+  });
+
+  it("currency-gated: refuses an intent-less delete when the journal has no recorded etag", async () => {
+    // Legacy journal entries (written before etag tracking) carry no
+    // `remoteEtag`. Currency is the ONLY authorization an intent-less entry
+    // has, so with nothing to compare there is nothing to authorize — refuse,
+    // and keep the entry so a later sync that records an etag can re-evaluate.
+    // No HEAD is issued: there is no etag to check it against.
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    const journalPath = path.join(stateDir, "sync-journal.acme.json");
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          "notes/legacy.md": {
+            hash: "h", size: 12, syncedAt: new Date().toISOString(),
+            direction: "down",
+            kind: "file",
+            // No remoteEtag, no localDeleteIntent.
+          },
+        },
+      }),
+    );
+
+    const events: Array<{ type: string; reason?: 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(0);
+    expect(deleteRemoteFile).not.toHaveBeenCalled();
+    expect(headRemoteFile).not.toHaveBeenCalled();
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        type: "delete-refused-stale-etag",
+        reason: "legacy-no-etag",
+      }),
+    );
+    const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+    expect(journal.files["notes/legacy.md"]).toBeDefined();
+  });
+
+  it("owned-only still requires an intent — it is the documented rollback knob", async () => {
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    const journalPath = path.join(stateDir, "sync-journal.acme.json");
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          "notes/gone.md": {
+            hash: "h", size: 12, syncedAt: new Date().toISOString(),
+            direction: "up",
+            remoteEtag: "current-etag",
+            kind: "file",
+          },
+        },
+      }),
+    );
+
+    const result = await share({
+      paths: [companyRoot],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      skipUnchanged: true,
+      propagateDeletes: true,
+      propagateDeletePolicy: "owned-only",
+    });
+
+    expect(result.filesDeleted).toBe(0);
+    expect(deleteRemoteFile).not.toHaveBeenCalled();
+    expect(headRemoteFile).not.toHaveBeenCalled();
+  });
+
+  // THE load-bearing safety test for this change. An etag match cannot tell
+  // "the user deleted this" from "the local mirror vanished" — in the steady
+  // state nobody has overwritten anything, so a moved hqRoot / unmounted volume
+  // / fresh clone presents mass-ENOENT with perfectly matching etags. That is
+  // exactly how the 2026-05-25 indigo vault mass-delete destroyed 559 objects.
+  // Relaxing the per-file gate must NOT weaken the whole-set guard.
+  it("bulk-asymmetry breaker still refuses a mass intent-less disappearance", async () => {
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    const files: Record<string, unknown> = {};
+    // 40 of 100 entries missing locally = 40%, far past the 10% threshold.
+    for (let i = 0; i < 100; i++) {
+      const present = i >= 40;
+      const rel = `docs/f${i}.md`;
+      if (present) {
+        fs.mkdirSync(path.join(companyRoot, "docs"), { recursive: true });
+        fs.writeFileSync(path.join(companyRoot, rel), "x");
+      }
+      files[rel] = {
+        hash: "h", size: 1, syncedAt: new Date().toISOString(),
+        direction: "down",
+        remoteEtag: `etag-${i}`,
+        kind: "file",
+      };
+    }
+    fs.writeFileSync(
+      path.join(stateDir, "sync-journal.acme.json"),
+      JSON.stringify({ version: "1", lastSync: new Date().toISOString(), files }),
+    );
+
+    const result = await share({
+      paths: [companyRoot],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      skipUnchanged: true,
+      propagateDeletes: true,
+      propagateDeletePolicy: "currency-gated",
+    });
+
+    expect(result.filesDeleted).toBe(0);
+    expect(deleteRemoteFile).not.toHaveBeenCalled();
+    // All 40 absent entries are refused as one set. (No assertion on
+    // headRemoteFile here: the push leg HEADs the 60 files that ARE present,
+    // so a global call-count says nothing about the delete plan.)
+    expect(result.filesRefusedStale).toBe(40);
+  });
+
+  // Regression: moving a company vault from syncMode 'all' to 'shared'.
+  // `hq sync narrow --apply` / scope-shrink calls `tombstoneEntry`, which
+  // deliberately KEEPS hash, direction and remoteEtag so a recovery flow can
+  // see what was pruned — and it removes the file locally. Every such entry
+  // therefore looks exactly like an etag-current intent-less delete candidate.
+  // Propagating those would delete OTHER members' files out of the shared
+  // company vault because one member narrowed their own scope.
+  //
+  // Deliberately asserted with NO prefixSet passed: the scope filter used to be
+  // the only thing preventing this, and that made an implicit dependency
+  // load-bearing for a destructive operation.
+  it("all -> shared: scope-shrink tombstones are never propagated as remote deletes", async () => {
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    const now = new Date().toISOString();
+    const shrunk = (reason: string) => ({
+      hash: "h", size: 3, syncedAt: now,
+      direction: "down",
+      remoteEtag: "still-current",
+      kind: "file",
+      removedAt: now,
+      removedReason: reason,
+    });
+    fs.writeFileSync(
+      path.join(stateDir, "sync-journal.acme.json"),
+      JSON.stringify({
+        version: "2",
+        lastSync: now,
+        files: {
+          "teammate/a.md": shrunk("scope_shrink"),
+          "teammate/b.md": shrunk("narrow_apply"),
+          "teammate/c.md": shrunk("manual"),
+        },
+        pulls: [],
+      }),
+    );
+
+    // The remote is ALIVE and still exactly what the journal recorded. Without
+    // this the keys would 404 into `toTombstone` and the test would pass for
+    // the wrong reason — verified by disabling the guard and watching it still
+    // go green.
+    vi.mocked(headRemoteFile).mockResolvedValue({
+      lastModified: new Date(),
+      etag: '"still-current"',
+      size: 3,
+    });
+
+    const result = await share({
+      paths: [companyRoot],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      skipUnchanged: true,
+      propagateDeletes: true,
+      propagateDeletePolicy: "currency-gated",
+    });
+
+    expect(result.filesDeleted).toBe(0);
+    expect(deleteRemoteFile).not.toHaveBeenCalled();
+    // Not refusals either — they are simply not delete candidates at all, so
+    // they never enter the plan and never count toward the breaker ratio.
+    expect(result.filesRefusedStale).toBe(0);
+  });
+
   // ── Conflict-mirror exclusion (ephemeral pattern) ──────────────────────────
   //
   // Conflict mirrors (`*.conflict-<ISO>-<machineHash>.<ext>`) are local-only
@@ -7041,6 +7525,78 @@ describe("scope-invalid key hardening on push (doubled companies/ tree — incid
     expect(events.some((e) => e.type === "error")).toBe(false);
   });
 
+  it("never plans an upload for macOS Finder Icon\\r files — silent skip, valid files still ship", async () => {
+    // The incident: Finder writes an `Icon\r` file into every directory it
+    // renders a custom icon for, and a folder-level cloud-sync agent spreads
+    // them tree-wide. A CR is a control character, so validateVaultUploadKey
+    // throws INVALID_KEY_CONTROL_CHARS inside executeUploads; that throw lands
+    // in the generic catch and emits type:"error". errors[] non-empty makes
+    // the runner return PARTIAL_SYNC_EXIT, so ONE such file marks EVERY sync
+    // pass failed forever. On the reporting machine there were 100+ per run.
+    //
+    // They are excluded during the walk, like .DS_Store, so they never reach
+    // the planner at all — and, being expected noise, without a per-file
+    // "EXCLUDED from sync" warning.
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(path.join(companyRoot, "docs"), { recursive: true });
+    fs.writeFileSync(path.join(companyRoot, "docs", "good.md"), "good");
+    fs.writeFileSync(path.join(companyRoot, "Icon\r"), "finder cruft");
+    fs.writeFileSync(path.join(companyRoot, "docs", "Icon\r"), "finder cruft");
+
+    const events: Array<{ type?: string; path?: string }> = [];
+    const result = await share({
+      paths: [companyRoot],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      onEvent: (e) => events.push(e as { type?: string }),
+    });
+
+    expect(result.aborted).toBe(false);
+    const uploadedKeys = vi.mocked(uploadFile).mock.calls.map((c) => c[2]);
+    expect(uploadedKeys).toEqual(["docs/good.md"]);
+    expect(result.filesUploaded).toBe(1);
+    // The failure class this guards: an error event is what flips the runner
+    // pass to exit 2.
+    expect(events.some((e) => e.type === "error")).toBe(false);
+    // Expected OS noise — excluded without the "review in case this is
+    // unintended" warning that real content would earn.
+    expect(events.some((e) => e.type === "ignore-excluded")).toBe(false);
+  });
+
+  it("refuses any other control-character key up front — skip event, never an error", async () => {
+    // Belt-and-suspenders for control-char paths that are not the Finder icon
+    // spelling, and for callers that bypass the walker. Symmetric with the
+    // pull leg, which has classified such keys since the same incident.
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(path.join(companyRoot, "docs"), { recursive: true });
+    fs.writeFileSync(path.join(companyRoot, "docs", "good.md"), "good");
+    fs.writeFileSync(path.join(companyRoot, "docs", "bad\u0001name.md"), "bad");
+
+    const events: Array<{ type?: string; path?: string; errorCode?: string }> = [];
+    const result = await share({
+      paths: [companyRoot],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      onEvent: (e) => events.push(e as { type?: string }),
+    });
+
+    expect(result.aborted).toBe(false);
+    const uploadedKeys = vi.mocked(uploadFile).mock.calls.map((c) => c[2]);
+    expect(uploadedKeys).toEqual(["docs/good.md"]);
+
+    const skipEvents = events.filter((e) => e.type === "skip-invalid-scoped-key");
+    expect(skipEvents).toEqual([
+      {
+        type: "skip-invalid-scoped-key",
+        path: "docs/bad\u0001name.md",
+        errorCode: "INVALID_KEY_CONTROL_CHARS",
+      },
+    ]);
+    expect(events.some((e) => e.type === "error")).toBe(false);
+  });
+
   it("tombstones (journal drop, no remote HEAD/DELETE) a companies/ journal key in company mode instead of re-uploading", async () => {
     // Delete-propagation on a poisoned journal entry: HEAD/DeleteObject on a
     // companies/-prefixed key would be rejected by the presign transport's
@@ -7199,3 +7755,89 @@ describe("isForbiddenCompanyVaultKey (company-vault double-scope contract)", ()
     expect(isForbiddenCompanyVaultKey(key, personalMode)).toBe(expected);
   });
 });
+
+// ── delete-refusal rendering ───────────────────────────────────────────────
+//
+// Every refusal cause shares ONE event type (`delete-refused-stale-etag`),
+// with the real cause carried in `reason`. Before this cover, the renderer
+// only branched on two of the five causes and the rest fell through to the
+// stale-etag wording — printing a real journal etag next to a
+// `<not-checked>` remote for a comparison that never happened. Operators
+// (including a customer bug report on 2026-08-04, and the investigation into
+// it) read that as an etag/currency defect and chased the wrong root cause.
+// Pin all five so no cause can silently fall through to etag wording again.
+describe("defaultConsoleLogger — delete refusal wording per reason", () => {
+  const render = (reason: string): string => {
+    const lines: string[] = [];
+    const spy = vi.spyOn(console, "error").mockImplementation((msg?: unknown) => {
+      lines.push(String(msg));
+    });
+    try {
+      shareTesting.defaultConsoleLogger({
+        type: "delete-refused-stale-etag",
+        path: "knowledge/example.md",
+        // A REAL etag, as the engine emits whenever the entry has one — the
+        // `<missing-delete-intent>` placeholder only appears for entries that
+        // never had an etag, which is the rare case.
+        journalEtag: "0156114498af2c8939c50d7ef0d3a0b1",
+        remoteEtag: "<not-checked>",
+        reason,
+      } as never);
+    } finally {
+      spy.mockRestore();
+    }
+    return lines.join("\n");
+  };
+
+  it("names the missing authorization instead of blaming the etag", () => {
+    const out = render("missing-delete-intent");
+    expect(out).toContain("no-delete-authorization");
+    expect(out).toContain("watcher did not observe this removal");
+    // The specific regression: neither etag is meaningful, so neither may be
+    // shown, and the stale-etag wording must not appear.
+    expect(out).not.toContain("stale-etag");
+    expect(out).not.toContain("<not-checked>");
+    expect(out).not.toContain("0156114498af2c8939c50d7ef0d3a0b1");
+  });
+
+  it("names local divergence instead of blaming the etag", () => {
+    const out = render("divergent-local");
+    expect(out).toContain("divergent-local");
+    expect(out).not.toContain("stale-etag");
+    expect(out).not.toContain("<not-checked>");
+  });
+
+  it("still explains legacy entries that predate etag tracking", () => {
+    const out = render("legacy-no-etag");
+    expect(out).toContain("no-etag-on-record");
+    expect(out).not.toContain("stale-etag");
+  });
+
+  it("still keeps bulk-asymmetry per-key lines compact", () => {
+    const out = render("bulk-asymmetry");
+    expect(out).toContain("bulk-asymmetry refusal");
+    expect(out).not.toContain("stale-etag");
+  });
+
+  it("still reports a genuine etag mismatch with both etags", () => {
+    const lines: string[] = [];
+    const spy = vi.spyOn(console, "error").mockImplementation((msg?: unknown) => {
+      lines.push(String(msg));
+    });
+    try {
+      shareTesting.defaultConsoleLogger({
+        type: "delete-refused-stale-etag",
+        path: "knowledge/example.md",
+        journalEtag: "aaa111",
+        remoteEtag: "bbb222",
+        reason: "stale-etag",
+      } as never);
+    } finally {
+      spy.mockRestore();
+    }
+    const out = lines.join("\n");
+    expect(out).toContain("stale-etag");
+    expect(out).toContain("aaa111");
+    expect(out).toContain("bbb222");
+  });
+});