@indigoai-us/hq-cloud 6.14.46 → 6.14.48

package/src/cli/share.ts

@@ -32,11 +32,17 @@ import {
   hashSymlinkTarget,
   updateEntry,
   removeEntry,
+  isTombstone,
   normalizeEtag,
   PERSONAL_VAULT_JOURNAL_SLUG,
   migratePersonalVaultJournal,
 } from "../journal.js";
-import { createIgnoreFilter, isExpectedIgnore, isWithinSizeLimit } from "../ignore.js";
+import {
+  createIgnoreFilter,
+  hasControlCharacters,
+  isExpectedIgnore,
+  isWithinSizeLimit,
+} from "../ignore.js";
 import {
   wrapFilterWithPersonalVaultDefaults,
   type PersonalVaultExclusion,
@@ -295,6 +301,7 @@ export const _testing = {
   collectFiles,
   resolveNamedPath,
   isWithinLexicalOrReal,
+  defaultConsoleLogger,
 };
 
 /**
@@ -641,8 +648,10 @@ export interface ShareOptions {
    * belong in THIS bucket regardless of local state" and uses the same
    * DeleteObject + journal-removal path as `propagateDeletes`.
    *
-   * Honors `propagateDeletePolicy` — `"owned-only"` (default) only
-   * decommissions journal entries with `direction === "up"`, so a
+   * Honors `propagateDeletePolicy`. Under `"owned-only"` (this function's
+   * own fallback when the caller passes nothing; every live caller passes
+   * `resolveDeletePolicy()`, which defaults to `"currency-gated"`) only
+   * journal entries with `direction === "up"` are decommissioned, so a
    * misconfigured caller never erases content pulled from elsewhere.
    *
    * Independent of `propagateDeletes`: callers can opt into decommission
@@ -888,6 +897,7 @@ export type ShareDeleteRefusalReason =
   | "divergent-local"
   | "missing-delete-intent"
   | "intent-changed"
+  | "recreated-locally"
   | "transfer-error";
 
 export interface SharePathResult {
@@ -1088,7 +1098,7 @@ const REFUSED_STALE_PATH_CAP = 50;
 
 async function createPushRunContext(options: ShareOptions): Promise<PushRunContext> {
   const { paths, company, message, onConflict, vaultConfig, entityContext, hqRoot, skipUnchanged, propagateDeletes } = options;
-  let propagateDeletePolicy: DeletePolicy =
+  const propagateDeletePolicy: DeletePolicy =
     options.propagateDeletePolicy ?? "owned-only";
   const baseEmit = options.onEvent ?? defaultConsoleLogger;
 
@@ -1118,9 +1128,30 @@ async function createPushRunContext(options: ShareOptions): Promise<PushRunConte
     ? entityContext
     : await resolveEntityContext(companyRef, vaultConfig!);
 
-  if (ctx.uid.startsWith("prs_") && propagateDeletePolicy === "owned-only") {
-    propagateDeletePolicy = "currency-gated";
-  }
+  // NOTE (removed 6.14.48): a `prs_`-scoped coercion used to silently rewrite
+  // `owned-only` -> `currency-gated` here (366721b). It was correct for the
+  // problem it was written against and is now actively harmful, for three
+  // reasons that only became true later:
+  //
+  //   1. Its ONLY reachable effect in production was to override an EXPLICIT
+  //      `owned-only`. Every live caller passes a policy
+  //      (`sync-runner-company.ts` -> `resolveDeletePolicy()`), and that
+  //      resolver already defaults to `currency-gated`. So the coercion never
+  //      fired on a default run — it fired exactly when an operator had set
+  //      `HQ_SYNC_DELETE_POLICY=owned-only`, i.e. the documented rollback.
+  //   2. Once delete authorization moved to ETag currency (no watcher-minted
+  //      intent required), that override stopped being cosmetic: an operator
+  //      reaching for the rollback because deletes were misbehaving would keep
+  //      getting intent-less etag-only deletes on their personal vault. A
+  //      rollback knob that silently exempts a vault is not a rollback knob.
+  //   3. Its motivating bug — the May-27 `personal/.obsidian/*.drift-*` leak —
+  //      is fixed twice over by mechanisms that postdate it: the vault-litter
+  //      drain (6.0.2) drains `.drift-*` markers ahead of every policy gate,
+  //      and etag-gated deletes propagate an intent-less `direction:"down"`
+  //      removal under the default policy without needing any coercion.
+  //
+  // So `owned-only` now means owned-only on every vault kind. It is the strict
+  // rollback path and must stay strictly stricter than the default everywhere.
 
   // Mirror push progress into the shared cross-process snapshot (see sync.ts).
   // Record the friendly company slug, or null for the personal vault so the
@@ -1247,6 +1278,35 @@ async function buildSharePlans(run: PushRunContext): Promise<SharePlans> {
     emitUnreachablePathEvent(run);
     throw new UnreachablePushPathsError(fatal, run.syncRoot);
   }
+  // Control-character key filter (macOS Finder Icon\r incident). A key
+  // containing a control character can never be stored — validateVaultUploadKey
+  // rejects it with INVALID_KEY_CONTROL_CHARS — so planning an upload for one
+  // only buys a guaranteed throw inside executeUploads, which lands in the
+  // generic catch and emits `type: "error"`. That is the failure this filter
+  // exists to stop: a non-empty errors[] makes the runner return
+  // PARTIAL_SYNC_EXIT, so ONE such file on disk marks EVERY sync pass failed
+  // forever. A macOS tree seeded with Finder `Icon\r` files produced 100+ per
+  // run, wedging sync indefinitely.
+  //
+  // Structurally identical to the size-limit skip in executeUploads: a
+  // permanently-invalid path is a benign skip, never an error. Symmetric with
+  // the pull leg, which has classified such keys since the 2026-07-11 incident
+  // (see computePullPlan's classifyVaultKey call). Applied before the mode
+  // branch below so it covers personal and company vaults alike.
+  //
+  // Finder icon files are normally already gone by here — createIgnoreFilter
+  // drops them during the walk. This stays as the general guard for any other
+  // control-char path, and as defense for callers that bypass the walker.
+  const controlCharFiltered = collected.filter((entry) => {
+    if (!hasControlCharacters(entry.relativePath)) return true;
+    run.emit({
+      type: "skip-invalid-scoped-key",
+      path: entry.relativePath,
+      errorCode: "INVALID_KEY_CONTROL_CHARS",
+    });
+    return false;
+  });
+
   // Scope-invalid key filter (incident 2026-07-11). In company mode the sync
   // root IS the company folder, so a local entry whose vault key starts with
   // `companies/` can only come from a stale doubled local tree
@@ -1260,7 +1320,7 @@ async function buildSharePlans(run: PushRunContext): Promise<SharePlans> {
   // `companies/{slug}/…` keys, so this only applies in company mode.
   const filesToShare =
     run.options.personalMode === true
-      ? collected.filter((entry) => {
+      ? controlCharFiltered.filter((entry) => {
           // `core/<type>` symlinks are generated projections of canonical
           // personal/package content. Reindex or package wiring owns their
           // lifecycle, so uploading them creates remote objects that a later
@@ -1281,7 +1341,7 @@ async function buildSharePlans(run: PushRunContext): Promise<SharePlans> {
           }
           return false;
         })
-      : collected.filter((entry) => {
+      : controlCharFiltered.filter((entry) => {
           if (!entry.relativePath.startsWith("companies/")) return true;
           run.emit({
             type: "skip-invalid-scoped-key",
@@ -1519,10 +1579,12 @@ async function executeUploads(
           localHash,
           lstat.size,
           "up",
-          remoteMeta.etag,
-          lstat.mtimeMs,
-          undefined,
-          item.kind,
+          absolutePath,
+          {
+            remoteEtag: remoteMeta.etag,
+            mtimeMs: lstat.mtimeMs,
+            kind: item.kind,
+          },
         );
         run.emit({ type: "reconciled", path: relativePath, direction: "push" });
         counters.filesSkipped++;
@@ -1604,10 +1666,8 @@ async function executeUploads(
         localHash,
         size,
         "up",
-        etag,
-        mtimeMs,
-        undefined,
-        item.kind,
+        absolutePath,
+        { remoteEtag: etag, mtimeMs, kind: item.kind },
       );
       if (run.message) {
         run.journal.files[relativePath] = {
@@ -1773,21 +1833,34 @@ async function executeDeletes(
     }
     try {
       const entry = run.journal.files[relativePath];
-      if (
+      // Last-second absence re-check. Applies to EVERY propagated delete,
+      // intent-backed or etag-only: a pull leg or the user can recreate the
+      // file between planning and applying, and deleting it remotely then
+      // destroys a file that exists locally right now. This used to sit inside
+      // the intent-version check, which meant it was skipped for any item
+      // carrying `intentVersion: null` — harmless while that only covered
+      // litter and decommission, but not once etag-only candidates travel that
+      // way too.
+      //
+      // Codec boundary: journal keys are canonical; the probe must use the
+      // ENCODED local path or a win32 colon key always looks absent (a raw `:`
+      // name can never exist on disk) and the remote delete proceeds while the
+      // encoded local file is still present.
+      const recreatedLocally =
+        !item.decommission &&
+        !isLocallyAbsent(localPathForVaultKey(run.syncRoot, relativePath));
+      const intentChanged =
         !item.decommission &&
         item.intentVersion !== null &&
         (!hasCurrentLocalDeleteIntent(entry) ||
-          entry!.localDeleteIntent!.version !== item.intentVersion ||
-          // Codec boundary: journal keys are canonical; the last-second
-          // absence re-check must probe the ENCODED local path or a win32
-          // colon key always looks absent (a raw `:` name can never exist
-          // on disk) and the remote delete proceeds while the encoded local
-          // file is still present.
-          !isLocallyAbsent(localPathForVaultKey(run.syncRoot, relativePath)))
-      ) {
+          entry!.localDeleteIntent!.version !== item.intentVersion);
+      if (recreatedLocally || intentChanged) {
         if (entry?.localDeleteIntent) {
           delete entry.localDeleteIntent;
         }
+        const refusalReason = recreatedLocally
+          ? ("recreated-locally" as const)
+          : ("intent-changed" as const);
         counters.filesRefusedStale++;
         if (filesRefusedStalePaths.length < REFUSED_STALE_PATH_CAP) {
           filesRefusedStalePaths.push(relativePath);
@@ -1797,13 +1870,13 @@ async function executeDeletes(
           path: relativePath,
           journalEtag: entry?.remoteEtag ?? "<missing-delete-intent>",
           remoteEtag: "<not-checked>",
-          reason: "intent-changed",
+          reason: refusalReason,
         });
         pathResults.push({
           path: relativePath,
           status: "refused",
           operation: "delete",
-          reason: "intent-changed",
+          reason: refusalReason,
         });
         continue;
       }
@@ -2149,6 +2222,32 @@ function defaultConsoleLogger(event: SyncProgressEvent): void {
       // 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 if (event.reason === "missing-delete-intent") {
+      // NEITHER etag is meaningful here: no HEAD was issued, so `remoteEtag`
+      // is the `<not-checked>` sentinel, and `journalEtag` is the entry's
+      // real recorded etag. Printing them under the `stale-etag` wording
+      // (which this branch used to fall through to) reads as an etag
+      // conflict and has repeatedly sent operators chasing a currency bug
+      // that does not exist — the actual cause is that no watcher observed
+      // the removal, so no delete authorization was ever recorded.
+      console.error(
+        `  ⚠ no-delete-authorization, kept on remote: ${event.path} ` +
+          `(the sync watcher did not observe this removal, so the delete was never authorized)`,
+      );
+    } else if (event.reason === "recreated-locally") {
+      console.error(
+        `  ⚠ recreated-locally, kept on remote: ${event.path} ` +
+          `(the file exists locally again, so the delete was abandoned)`,
+      );
+    } else if (event.reason === "divergent-local") {
+      // Same trap as above — `remoteEtag` is `<not-checked>`. The entry's
+      // recorded etag was stamped only to silence a re-fired conflict; the
+      // local copy never matched it, so propagating the delete would destroy
+      // divergent remote work.
+      console.error(
+        `  ⚠ divergent-local, kept on remote: ${event.path} ` +
+          `(the local copy never matched the recorded remote version; pull to reconcile first)`,
+      );
     } else {
       console.error(
         `  ⚠ stale-etag, kept on remote: ${event.path} (journal=${event.journalEtag}, remote=${event.remoteEtag})`,
@@ -2877,7 +2976,8 @@ type RefusedStaleReason =
   | "bulk-asymmetry"
   | "divergent-local"
   | "missing-delete-intent"
-  | "intent-changed";
+  | "intent-changed"
+  | "recreated-locally";
 
 /**
  * Bulk-asymmetry circuit-breaker — refuses to convert a suspiciously-large
@@ -3100,7 +3200,7 @@ async function computeDeletePlan(
   // all), or queue it for HEAD (currency-gated). Keeping this synchronous
   // means the HEAD pass below sees a single, deduplicated candidate list
   // and the journal-mutation buckets are already settled before any I/O.
-  type HeadCandidate = { key: string; journalEtag: string; intentVersion: 1 };
+  type HeadCandidate = { key: string; journalEtag: string; intentVersion: 1 | null };
   const headCandidates: HeadCandidate[] = [];
   // Litter drain bucket — kept separate from `plan.toDelete` so the
   // bulk-asymmetry breaker (which moves toDelete + headCandidates into
@@ -3143,6 +3243,41 @@ async function computeDeletePlan(
         relativeKey.startsWith(`${root}/`),
     );
     if (!inScope) continue;
+
+    // A tombstoned entry has ALREADY had its disposition decided — by a scope
+    // shrink, `hq sync narrow --apply`, a manual prune, or a pull-side
+    // intentional-delete record. It must never be re-evaluated as a fresh
+    // delete candidate.
+    //
+    // This matters most for `all` -> `shared`: `tombstoneEntry` deliberately
+    // KEEPS `hash`, `direction` and `remoteEtag` (so a recovery flow can see
+    // what was there), and the shrink removes the file locally. Every one of
+    // those entries therefore presents as locally-absent, intent-less and
+    // etag-current — which, now that authorization is etag-only, is an
+    // instruction to delete another member's files out of the shared company
+    // vault, for the crime of having narrowed one's own sync scope.
+    //
+    // Until now the ONLY thing standing in the way was `shouldSync` happening
+    // to carry a `prefixSet` (see `createPushRunContext`); any run that
+    // resolved no prefix set — a degraded scope lookup, a caller that does not
+    // set one — would have walked straight through. That is far too load-
+    // bearing for an implicit dependency, so the invariant is stated here
+    // directly.
+    //
+    // `local-delete` is the ONE reason that must pass: the pull leg stamps it
+    // as a deliberate producer hand-off ("the user removed this; push leg,
+    // finish the job"), and skipping it would strand exactly the deletes this
+    // change exists to enable. Every other reason — scope_shrink,
+    // narrow_apply, manual, or an absent/unrecognised one — means "stop
+    // tracking, do NOT touch the remote", so the test is written fail-closed:
+    // only the explicit hand-off is let through.
+    //
+    // Skipped BEFORE `inScopeJournalEntries++` so these inflate neither the
+    // numerator nor the denominator of the bulk-asymmetry ratio. Excluding
+    // them from the denominator can only make the breaker MORE likely to trip,
+    // which is the safe direction.
+    if (isTombstone(entry) && entry.removedReason !== "local-delete") continue;
+
     inScopeJournalEntries++;
     const localPath = localPathForVaultKey(syncRoot, relativeKey);
 
@@ -3222,13 +3357,78 @@ async function computeDeletePlan(
     }
 
     if (!hasCurrentLocalDeleteIntent(entry)) {
-      if (
-        policy === "currency-gated" ||
-        (policy === "owned-only" && entry.direction === "up")
-      ) {
+      // A delete intent is minted ONLY by a live watcher, at the instant it
+      // observes the unlink. Three of the four ways HQ syncs never construct a
+      // watcher at all — outpost/agent boxes run a one-shot runner, `hq sync
+      // now` is one-shot, and the desktop app drops `--event-push` (and with it
+      // the whole TreeWatcher) whenever Instant-sync is off. On those surfaces
+      // an intent can never exist, so requiring one made deletes structurally
+      // impossible rather than merely gated. Files deleted while no watcher was
+      // running also stranded permanently: the file is already gone, so no
+      // watcher can ever retroactively witness it.
+      //
+      // `currency-gated` therefore authorizes on ETag currency alone. The
+      // per-file question it answers is unchanged — "is the remote object still
+      // exactly what this journal recorded, i.e. has no peer touched it since"
+      // — and a mismatch still refuses (`stale-etag`) so a peer's newer work is
+      // never destroyed.
+      //
+      // The whole-set question ("does my local mirror look catastrophically
+      // empty") is NOT answered by the ETag, and must not be conflated with it:
+      // in the steady state nobody has overwritten anything, so a moved hqRoot,
+      // unmounted volume, fresh clone or partial restore presents mass-ENOENT
+      // with perfectly matching ETags. That is exactly how the 2026-05-25
+      // indigo vault mass-delete destroyed 559 objects. The bulk-asymmetry
+      // breaker below is the guard for that class and is deliberately left
+      // intact — these candidates are counted into `bulkCandidatePicks` on the
+      // SAME line as intent-backed ones, so relaxing the per-file gate cannot
+      // weaken the whole-set one. See policy `sync-delete-bulk-asymmetry-guard`
+      // (hard) and workspace/reports/indigo-vault-mass-delete-debug.md.
+      //
+      // `owned-only` keeps requiring an intent: it is the documented rollback
+      // knob, and an operator who selects it is asking for the stricter path.
+      if (policy === "owned-only") {
+        // Still counted into the breaker exactly as before: an owned-only run
+        // whose mirror has gone missing must trip the whole-set guard even
+        // though each individual key is refused for want of an intent.
+        if (entry.direction === "up") {
+          bulkCandidatePicks++;
+          intentlessKeys.add(relativeKey);
+        }
+        plan.refusedStale.push({
+          key: relativeKey,
+          journalEtag: entry.remoteEtag ?? "<missing-delete-intent>",
+          remoteEtag: "<not-checked>",
+          reason: "missing-delete-intent",
+        });
+        continue;
+      }
+      if (policy === "currency-gated") {
         bulkCandidatePicks++;
         intentlessKeys.add(relativeKey);
+        // No etag on record ⇒ nothing to compare ⇒ no authorization. Refused
+        // for the same reason an intent-backed legacy entry is (below).
+        if (!entry.remoteEtag) {
+          plan.refusedStale.push({
+            key: relativeKey,
+            journalEtag: "<legacy-no-etag>",
+            remoteEtag: "<unknown>",
+            reason: "legacy-no-etag",
+          });
+          continue;
+        }
+        headCandidates.push({
+          key: relativeKey,
+          journalEtag: entry.remoteEtag,
+          intentVersion: null,
+        });
+        continue;
       }
+      // policy === "all" is deliberately NOT relaxed here. It already skips the
+      // bulk-asymmetry breaker, so letting it skip the intent gate too would
+      // make it a wholly unguarded mass delete — a strictly larger blast radius
+      // than this change is scoped to. It keeps refusing intent-less entries
+      // exactly as before.
       plan.refusedStale.push({
         key: relativeKey,
         journalEtag: entry.remoteEtag ?? "<missing-delete-intent>",

package/src/cli/sync.ts

@@ -238,7 +238,8 @@ export type SyncProgressEvent =
         | "bulk-asymmetry"
         | "divergent-local"
         | "missing-delete-intent"
-        | "intent-changed";
+        | "intent-changed"
+        | "recreated-locally";
     }
   | {
       /**
@@ -398,10 +399,14 @@ export type SyncProgressEvent =
     }
   | {
       /**
-       * Emitted by the PULL leg once per remote key skipped because the server
-       * will never presign it (for example, a `companies/…`-prefixed key in a
-       * company-scoped vault or a key with control characters). Such keys are
-       * bucket poisoning from an outdated direct-S3 client. Like
+       * Emitted once per key skipped because it is permanently unstorable.
+       *
+       * PULL leg: a remote key the server will never presign (for example, a
+       * `companies/…`-prefixed key in a company-scoped vault or a key with
+       * control characters) — bucket poisoning from an outdated direct-S3
+       * client. PUSH leg: a local key the upload validator would reject, so
+       * the upload can only ever throw — a doubled-tree `companies/…` key, or
+       * a control-character path such as a macOS Finder `Icon\r` file. Like
        * `skip-size-limit`, this is deliberately NOT `type: "error"` — one bad
        * object must never error a whole company sync (erroring gated
        * heartbeat toolset refreshes fleet-wide in the incident). Surfaced for
@@ -1467,9 +1472,12 @@ async function executeConflictItem(
       item.localHash,
       item.localSize,
       "down",
-      remoteFile.etag,
-      item.localMtime.getTime(),
-      item.localSnapshot.kind === "symlink" ? "symlink" : "file",
+      localPath,
+      {
+        remoteEtag: remoteFile.etag,
+        mtimeMs: item.localMtime.getTime(),
+        kind: item.localSnapshot.kind === "symlink" ? "symlink" : "file",
+      },
     );
     run.emit({ type: "reconciled", path: remoteFile.key, direction: "pull" });
     counters.filesSkipped++;
@@ -1557,9 +1565,12 @@ async function executeConflictItem(
       item.localHash,
       item.localSize,
       "down",
-      remoteFile.etag,
-      item.localMtime.getTime(),
-      item.localSnapshot.kind === "symlink" ? "symlink" : "file",
+      localPath,
+      {
+        remoteEtag: remoteFile.etag,
+        mtimeMs: item.localMtime.getTime(),
+        kind: item.localSnapshot.kind === "symlink" ? "symlink" : "file",
+      },
     );
     // Journal-honesty: we recorded the remote etag so this conflict can't
     // re-fire (#137), but the KEPT local copy diverges from that remote — it
@@ -1690,10 +1701,13 @@ async function downloadOne(
       hash,
       size,
       "down",
-      remoteFile.etag,
-      localLstat.mtimeMs,
-      createdBySub,
-      isLocalSymlink ? "symlink" : "file",
+      localPath,
+      {
+        remoteEtag: remoteFile.etag,
+        mtimeMs: localLstat.mtimeMs,
+        ...(createdBySub !== undefined ? { createdBySub } : {}),
+        kind: isLocalSymlink ? "symlink" : "file",
+      },
     );
 
     const priorEntry = getEntry(run.journal, remoteFile.key);

package/src/ignore.test.ts

@@ -33,6 +33,24 @@ describe("isExpectedIgnore", () => {
     expect(isExpectedIgnore(".claude/skills/foo/.skill-media/hero.png")).toBe(true);
   });
 
+  it("classifies macOS Finder Icon\\r files as expected noise", () => {
+    // Finder scatters one into every directory it renders a custom icon for,
+    // and a folder-level cloud-sync agent propagates them tree-wide. Treated
+    // exactly like .DS_Store so a seeded tree stays silent rather than firing
+    // the "EXCLUDED from sync — review in case this is unintended" warning
+    // once per file.
+    expect(isExpectedIgnore("Icon\r")).toBe(true);
+    expect(isExpectedIgnore("companies/indigo/Icon\r")).toBe(true);
+  });
+
+  it("keeps a real file named Icons noteworthy (no `Icon?` over-match)", () => {
+    // The `Icon?` gitignore workaround would swallow these. Dropping real
+    // user content is a worse failure than the cruft being excluded.
+    expect(isExpectedIgnore("companies/indigo/Icons")).toBe(false);
+    expect(isExpectedIgnore("companies/indigo/Icon")).toBe(false);
+    expect(isExpectedIgnore("companies/indigo/Icons.md")).toBe(false);
+  });
+
   it("keeps nested repos/workspace and ordinary content noteworthy", () => {
     expect(isExpectedIgnore("companies/indigo/knowledge/repos/foo/notes.md")).toBe(false);
     expect(isExpectedIgnore("companies/indigo/knowledge/overview.md")).toBe(false);
@@ -85,6 +103,43 @@ describe("createIgnoreFilter", () => {
     expect(shouldSync(path.join(hqRoot, "node_modules/react/index.js"))).toBe(false);
   });
 
+  it("permissive mode: macOS Finder Icon\\r files never enter the walk", () => {
+    // A CR is a control character, so the vault key validator rejects the key
+    // (INVALID_KEY_CONTROL_CHARS) and the upload can only ever throw. Dropping
+    // them during the walk is what keeps them off the upload path entirely.
+    const shouldSync = createIgnoreFilter(hqRoot);
+    expect(shouldSync(path.join(hqRoot, "Icon\r"))).toBe(false);
+    expect(shouldSync(path.join(hqRoot, "companies/indigo/Icon\r"))).toBe(false);
+    expect(shouldSync(path.join(hqRoot, ".agents/Icon\r"))).toBe(false);
+    // Caught at any depth, like the other OS-cruft exclusions.
+    expect(shouldSync(path.join(hqRoot, "a/b/c/d/Icon\r"))).toBe(false);
+  });
+
+  it("permissive mode: a real file named Icons still syncs", () => {
+    // Regression guard for the `Icon?` gitignore workaround, whose `?`
+    // single-char wildcard also matches Icons / Icon1 / IconX. This exclusion
+    // matches the exact Finder byte sequence instead, so real content survives.
+    const shouldSync = createIgnoreFilter(hqRoot);
+    expect(shouldSync(path.join(hqRoot, "companies/indigo/Icons"))).toBe(true);
+    expect(shouldSync(path.join(hqRoot, "companies/indigo/Icon"))).toBe(true);
+    expect(shouldSync(path.join(hqRoot, "companies/indigo/Icon1"))).toBe(true);
+    expect(shouldSync(path.join(hqRoot, "companies/indigo/Icons.md"))).toBe(true);
+  });
+
+  it("a literal Icon+CR line in .gitignore does NOT reach the ignore lib", () => {
+    // This is why the exclusion is a predicate and not a DEFAULT_IGNORES
+    // entry. ignore@5 strips a trailing CR from a pattern line, so the
+    // spelling git itself requires silently never matches. Pinning the
+    // upstream behavior here means a future ignore-lib bump that changes it
+    // surfaces as a failing test rather than a silent double-exclusion.
+    fs.writeFileSync(path.join(hqRoot, ".gitignore"), "Icon\r\n");
+    const shouldSync = createIgnoreFilter(hqRoot);
+    // Still excluded — by the predicate, not by the pattern.
+    expect(shouldSync(path.join(hqRoot, "Icon\r"))).toBe(false);
+    // Proof the pattern itself is inert: it did not take `Icons` with it.
+    expect(shouldSync(path.join(hqRoot, "Icons"))).toBe(true);
+  });
+
   it("repos/ exclusion is root-anchored to hqRoot (DEV-1791)", () => {
     const shouldSync = createIgnoreFilter(hqRoot);
     expect(shouldSync(path.join(hqRoot, "repos/private/hq-cloud/src/x.ts"))).toBe(false);

package/src/ignore.ts

@@ -244,6 +244,52 @@ function segmentToRegex(seg: string): RegExp {
   return new RegExp(`^${body}$`);
 }
 
+/**
+ * Match a path whose basename is the macOS Finder custom-icon file: the
+ * literal `Icon` followed by a carriage return (U+000D).
+ *
+ * This CANNOT be expressed as a `DEFAULT_IGNORES` entry, which is why it is a
+ * predicate instead of a pattern string. Two independent reasons:
+ *
+ *   1. A pattern line ending in a literal CR is inert. The `ignore` package
+ *      strips the trailing CR, so the line degrades to `Icon` and never
+ *      matches — verified against ignore@5.3.2:
+ *      `ignore().add("Icon\r\n").ignores("Icon\r") === false`. Git does the
+ *      same thing (it reads the CR as part of the line ending), which is why
+ *      the GitHub macOS template has to end that line with TWO CRs.
+ *   2. The usual workaround pattern `Icon?` DOES match, but `?` is a
+ *      single-character wildcard in gitignore syntax, so it also swallows any
+ *      real file named `Icons`, `Icon1`, `IconX`. Silently dropping user
+ *      content is worse than the cruft we are excluding.
+ *
+ * Matching the exact byte sequence keeps the exclusion precise. Finder writes
+ * these into every directory it renders a custom icon for, and a folder-level
+ * cloud-sync agent (iCloud Desktop, backup tooling) propagates them across an
+ * entire tree — including into `.git/`. They carry no user content.
+ *
+ * They are also unsyncable by construction: a CR is a control character, so
+ * the vault key validator rejects the key outright
+ * (INVALID_KEY_CONTROL_CHARS). Excluding them at the walk is what keeps them
+ * from reaching the upload path at all.
+ */
+export function isMacFinderIconFile(relPath: string): boolean {
+  const basename = relPath.replace(/\/$/, "").split("/").pop() ?? "";
+  return basename === "Icon\r";
+}
+
+/**
+ * True when any segment of `relPath` contains a character the vault key
+ * validator rejects (see `KEY_CONTROL_CHARS` in s3.ts — C0 controls plus DEL).
+ *
+ * Kept in lock-step with that validator on purpose: a key this returns `true`
+ * for can never be stored, so planning an upload for it only produces a
+ * guaranteed per-file failure.
+ */
+export function hasControlCharacters(relPath: string): boolean {
+  // eslint-disable-next-line no-control-regex
+  return /[\x00-\x1F\x7F]/.test(relPath);
+}
+
 export const EXPECTED_IGNORE_SEGMENTS = new Set([
   ".git",
   "node_modules",
@@ -307,6 +353,11 @@ export function isExpectedIgnore(relPath: string): boolean {
   return (
     basename === ".DS_Store" ||
     basename === "Thumbs.db" ||
+    // Same class as .DS_Store: OS-generated, zero user content. Classified
+    // expected so a tree full of them stays silent instead of firing the
+    // "EXCLUDED from sync — review in case this is unintended" warning once
+    // per file (Finder scatters one into every directory it touches).
+    basename === "Icon\r" ||
     basename === "company.yaml" ||
     basename === "INDEX.md" ||
     basename === "modules.lock" ||
@@ -373,6 +424,12 @@ export function createIgnoreFilter(
     const relative = path.relative(hqRoot, filePath);
     if (!relative || relative.startsWith("..")) return true; // outside HQ root
 
+    // macOS Finder custom-icon files. Excluded here rather than as a
+    // DEFAULT_IGNORES pattern because neither available spelling works —
+    // see isMacFinderIconFile for the ignore@5 CR-stripping proof and the
+    // `Icon?` over-match hazard.
+    if (isMacFinderIconFile(relative)) return false;
+
     // Gitignore dir-only patterns (`foo/`) only match candidate paths that
     // end with `/`. The `ignore` lib has no stat awareness, so when the
     // caller knows the entry is a directory we hand the matcher the