@indigoai-us/hq-cloud 5.23.0 → 5.24.0

package/src/cli/share.ts

@@ -25,6 +25,50 @@ import { resolveConflict } from "./conflict.js";
 import type { ConflictStrategy } from "./conflict.js";
 import type { SyncProgressEvent } from "./sync.js";
 
+/**
+ * Local-only ephemeral artifacts: conflict-mirror files written by the pull
+ * leg whenever a 3-way merge keeps local AND wants to preserve the remote
+ * version for inspection. Format: `<orig>.conflict-<ISO-utc>-<machineHash>.<ext>`
+ * (e.g. `.claude/CLAUDE.md.conflict-2026-05-13T19-40-40Z-e5797a.md`).
+ *
+ * These files MUST never round-trip to S3 — they're local-only safety backups
+ * the user reviews and deletes once the merge is resolved. Pre-fix, the push
+ * walker happily uploaded them, the journal recorded them, and the
+ * `owned-only` delete policy then refused to clean them up when the user
+ * deleted them locally (because pull-confirmation had stamped them as
+ * `direction: "down"`). Net effect: a permanent litter ratchet on remote.
+ *
+ * Wire-points: (1) push walker — `collectFiles` / `walkDir` skip these so
+ * they never upload; (2) `computeDeletePlan` — skip these so an already-
+ * journaled mirror that's been deleted locally doesn't get included in the
+ * regular delete plan (the dedicated reconcile path handles existing litter).
+ */
+const EPHEMERAL_PATH_PATTERN =
+  /\.conflict-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}Z-[a-f0-9]+\./;
+
+/**
+ * Cheap pure check — pass the relative key OR a basename; either works. Used
+ * in both the file walker (basename matching) and the delete-plan walker
+ * (relative-key matching). The regex matches anywhere in the string, which is
+ * fine: the `.conflict-<ISO>-<hash>.` token is unambiguous.
+ */
+function isEphemeralPath(p: string): boolean {
+  return EPHEMERAL_PATH_PATTERN.test(p);
+}
+
+/**
+ * Test-only export. Kept under a `_testing` namespace so the module's public
+ * surface stays focused on `share()` / `ShareOptions` / `ShareResult` while
+ * regression-critical regex contracts (the conflict-mirror pattern) can be
+ * pinned by direct unit tests without round-tripping through share().
+ *
+ * Do NOT import from `_testing` outside of tests in this package.
+ */
+export const _testing = {
+  isEphemeralPath,
+  EPHEMERAL_PATH_PATTERN,
+};
+
 /**
  * Stage-1 classification for a single local file in a push run. Pre-HEAD —
  * only inputs we can evaluate locally (size limit, journal hash, optional
@@ -245,29 +289,44 @@ export interface ShareOptions {
    * convert into remote `DeleteObject` calls. Only consulted when
    * `propagateDeletes === true`.
    *
-   *   - `"owned-only"` (default, safer): only entries whose journal
-   *     `direction === "up"` are eligible. That is, only files this
-   *     machine previously uploaded can be remotely deleted on its
-   *     behalf. Entries the journal records as pulled from elsewhere
-   *     (`direction === "down"`) are never delete-propagated — the
-   *     local absence may just be an unpulled state or a filter
-   *     mismatch, both of which previously caused this machine to
-   *     erase other machines' uploads.
+   *   - `"currency-gated"` (safest; default scheduled for 5.25 after soak):
+   *     for each candidate, issue a remote HEAD and compare the current
+   *     remote ETag against the journal's
+   *     last-recorded `remoteEtag`. Match → safe-to-delete (this machine is
+   *     current for the file, so the local deletion reflects an intentional
+   *     removal AFTER seeing the latest remote version). Mismatch → refuse
+   *     and emit `delete-refused-stale-etag`; the journal entry is left
+   *     intact so the next pull leg re-pulls via the same hasRemoteChanged
+   *     path. 404 → tombstone: drop the journal entry, no DeleteObject (the
+   *     remote was already gone). Strictly safer than `owned-only` because
+   *     it gates on per-file proof of currency rather than direction-of-
+   *     origin — files that arrived via `/update-hq` (direction:"down") can
+   *     legitimately be deleted by the device that pulled them, as long as
+   *     no other device has touched them since.
+   *   - `"owned-only"` (current default in 5.24): only entries whose journal
+   *     `direction === "up"` are eligible. That is, only files this machine
+   *     previously uploaded can be remotely deleted on its behalf. Entries
+   *     recorded as pulled from elsewhere are never delete-propagated.
+   *     Default in 5.24 while currency-gated soaks; scheduled to lose the
+   *     default in 5.25. Downside: any file that arrived via `/update-hq`
+   *     or another device's push is stuck on remote forever once locally
+   *     removed, because no device "owns" it under this rule.
    *   - `"all"`: legacy behaviour — every in-scope journal entry whose
-   *     local file is missing is eligible (regardless of direction). The
-   *     bidirectional runner's first-push and any tool that wants to
-   *     mirror a destructive local checkout opts in here explicitly.
+   *     local file is missing is eligible (regardless of direction or
+   *     currency). The bidirectional runner's first-push and any tool that
+   *     wants to mirror a destructive local checkout opts in here
+   *     explicitly. Use with care — a stale device can erase peer uploads.
    *
-   * Independently of this policy, an entry is also dropped from the
-   * plan when neither the file-shape nor the directory-shape probe of
-   * `shouldSync` accepts the path — i.e. the current ignore filter
-   * would have skipped the path on pull (whether classified as a
-   * regular file or a symlink record / directory). That symmetry
-   * blocks the failure mode where a path was filtered locally but
-   * lived in the vault (and the journal) from an older HQ layout or
-   * a different machine, causing the next push to erase it.
+   * Independently of this policy, an entry is also dropped from the plan
+   * when (a) it matches `EPHEMERAL_PATH_PATTERN` (conflict mirrors never
+   * propagate), or (b) neither the file-shape nor the directory-shape probe
+   * of `shouldSync` accepts the path — i.e. the current ignore filter would
+   * have skipped the path on pull. That symmetry blocks the failure mode
+   * where a path was filtered locally but lived in the vault (and the
+   * journal) from an older HQ layout or a different machine, causing the
+   * next push to erase it.
    */
-  propagateDeletePolicy?: "owned-only" | "all";
+  propagateDeletePolicy?: "currency-gated" | "owned-only" | "all";
   /**
    * Identity stamped onto each uploaded object's S3 user metadata
    * (`created-by`, `created-by-sub`, `created-at`). The hq-console vault UI
@@ -303,8 +362,30 @@ export interface ShareResult {
    * Number of remote `DeleteObject` calls that succeeded this run. Always 0
    * when `propagateDeletes` is false. The corresponding journal entries are
    * removed in the same pass so the next sync sees the key as truly gone.
+   * Does NOT include tombstones (remote was already 404; no DELETE was
+   * issued — see `filesTombstoned`) or refused-stale entries (currency-
+   * gated refused because remote etag drifted — see `filesRefusedStale`).
    */
   filesDeleted: number;
+  /**
+   * Number of journal entries dropped because the remote was already 404 at
+   * HEAD time (cleaned out-of-band — e.g. someone hand-deleted via the S3
+   * console, or another tool ran a destructive operation). No `DeleteObject`
+   * was issued for these; the journal converges with reality. Always 0 when
+   * `propagateDeletes` is false or `propagateDeletePolicy !== "currency-gated"`.
+   */
+  filesTombstoned: number;
+  /**
+   * Number of delete candidates refused by the `currency-gated` policy
+   * because the remote object's current ETag no longer matches the journal's
+   * recorded one (some other device modified the file since this device last
+   * synced it) — OR because the journal entry is a legacy record with no
+   * `remoteEtag` to compare against. Neither S3 nor the journal is mutated
+   * for these; the next pull leg re-pulls naturally via `hasRemoteChanged`.
+   * Always 0 when `propagateDeletes` is false or policy is not
+   * `currency-gated`.
+   */
+  filesRefusedStale: number;
   /**
    * Paths (company-relative) that were detected as push conflicts. Mirrors
    * `SyncResult.conflictPaths` so push and pull surface conflicts the same
@@ -319,13 +400,16 @@ export interface ShareResult {
  */
 export async function share(options: ShareOptions): Promise<ShareResult> {
   const { paths, company, message, onConflict, vaultConfig, entityContext, hqRoot, skipUnchanged, propagateDeletes } = options;
-  // Default to the safer "owned-only" policy when delete-propagation is on
-  // but the caller hasn't pinned a policy. Pre-existing callers that passed
-  // `propagateDeletes: true` (the `sync now` push leg, the runner's
-  // bidirectional sync, the `--all` fanout) thereby flip to the safer
-  // semantics automatically. Set `propagateDeletePolicy: "all"` explicitly
-  // to opt back into the legacy any-missing-file-deletes behaviour.
-  const propagateDeletePolicy: "owned-only" | "all" =
+  // Default to "owned-only" — the pre-5.24 behavior — when delete-propagation
+  // is on but the caller hasn't pinned a policy. Staged-default rollout
+  // (see CHANGELOG / PR for hq-cloud 5.24.0): 5.24 ships the currency-gated
+  // CODE PATH plus the conflict-mirror exclusion (which is policy-
+  // independent and immediately stops new litter), but holds the default
+  // flip to a later release after soak. Opt into the safer policy now via
+  // `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" =
     options.propagateDeletePolicy ?? "owned-only";
   const emit = options.onEvent ?? defaultConsoleLogger;
 
@@ -387,6 +471,13 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
   let bytesUploaded = 0;
   let filesSkipped = 0;
   let filesDeleted = 0;
+  // Tombstone and refused-stale counts mirror the deletePlan buckets so the
+  // ShareResult can report them without the caller having to count events.
+  // Populated only after Stage 3 runs (deletePlan is computed first, then
+  // mutated through the execution loop) — initial zero handles the
+  // propagateDeletes=false path.
+  let filesTombstoned = 0;
+  let filesRefusedStale = 0;
   const conflictPaths: string[] = [];
 
   // Collect all files to share
@@ -406,15 +497,16 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
   const deleteScopeRoots = propagateDeletes === true
     ? resolveDeleteScopeRoots(paths, hqRoot, syncRoot)
     : [];
-  const deletePlan = propagateDeletes === true
-    ? computeDeletePlan(
+  const deletePlan: DeletePlan = propagateDeletes === true
+    ? await computeDeletePlan(
         journal,
         syncRoot,
         deleteScopeRoots,
         shouldSync,
         propagateDeletePolicy,
+        ctx,
       )
-    : [];
+    : { toDelete: [], toTombstone: [], refusedStale: [] };
 
   emit({
     type: "plan",
@@ -427,7 +519,11 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
     // Push conflicts require a remote HEAD; we don't yet do that in Stage 1,
     // so this stays 0. V1.5 (single LIST) will let us classify them up-front.
     filesToConflict: 0,
-    filesToDelete: deletePlan.length,
+    // Reported count is the deletes we're actually going to issue — does NOT
+    // include tombstones (no S3 call) or refused-stale (no journal change).
+    // Refusals surface as their own event stream so consumers that care can
+    // render a "kept on remote: N" line separately.
+    filesToDelete: deletePlan.toDelete.length,
   });
 
   // Stage 2: execute. Skip items pre-classified as no-ops, then for each
@@ -498,6 +594,11 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
             bytesUploaded,
             filesSkipped,
             filesDeleted,
+            // Abort path: delete stage never runs, so tombstone + refused-
+            // stale counts are necessarily zero. Explicit fields keep the
+            // ShareResult shape stable for consumers that destructure.
+            filesTombstoned,
+            filesRefusedStale,
             conflictPaths,
             aborted: true,
           };
@@ -554,12 +655,28 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
     }
   }
 
-  // Stage 3: propagate deletes. Each call writes a delete-marker (versioning
-  // is enabled on the bucket) and removes the corresponding journal entry so
-  // the next sync sees the key as truly gone on this machine. A failed
-  // DeleteObject leaves both the journal entry and the remote object intact
-  // — the next run will retry.
-  for (const relativePath of deletePlan) {
+  // Stage 3: propagate deletes. Three buckets, three actions:
+  //
+  //   1. `toDelete` — write a delete-marker (versioning is enabled on the
+  //      bucket so the delete is soft and prior versions remain recoverable)
+  //      and remove the journal entry so the next sync sees the key as
+  //      truly gone on this machine. A failed DeleteObject leaves both
+  //      the journal entry and remote object intact — the next run retries.
+  //
+  //   2. `toTombstone` — the remote was 404 at HEAD time (cleaned up out
+  //      of band, e.g. someone hand-deleted via console). No DeleteObject
+  //      needed; just drop the journal entry so the journal converges with
+  //      reality. Emit a synthetic `progress` event with `deleted: true`
+  //      and bytes=0 so consumers see the convergence.
+  //
+  //   3. `refusedStale` — under `currency-gated`, the remote's current
+  //      ETag no longer matches the journal's recorded one. Some other
+  //      device modified the file since this device last synced it. Keep
+  //      the remote intact; keep the journal entry intact. The next pull
+  //      leg of `sync now` re-pulls naturally via the existing
+  //      `hasRemoteChanged` path. Emit a dedicated event so UIs can
+  //      surface the refusal without inferring it from absence.
+  for (const relativePath of deletePlan.toDelete) {
     if (vaultConfig && isExpiringSoon(ctx.expiresAt)) {
       ctx = await refreshEntityContext(companyRef, vaultConfig);
     }
@@ -583,6 +700,27 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
       });
     }
   }
+  for (const relativePath of deletePlan.toTombstone) {
+    removeEntry(journal, relativePath);
+    filesTombstoned++;
+    emit({
+      type: "progress",
+      path: relativePath,
+      bytes: 0,
+      deleted: true,
+      message: "tombstone (remote already 404)",
+    });
+  }
+  for (const refused of deletePlan.refusedStale) {
+    filesRefusedStale++;
+    emit({
+      type: "delete-refused-stale-etag",
+      path: refused.key,
+      journalEtag: refused.journalEtag,
+      remoteEtag: refused.remoteEtag,
+      reason: refused.reason,
+    });
+  }
 
   // See cli/sync.ts: stamp lastSync on completion so a no-op share still
   // ticks the "Last sync" indicator.
@@ -594,6 +732,8 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
     bytesUploaded,
     filesSkipped,
     filesDeleted,
+    filesTombstoned,
+    filesRefusedStale,
     conflictPaths,
     aborted: false,
   };
@@ -612,7 +752,12 @@ function defaultConsoleLogger(event: SyncProgressEvent): void {
     }
   } else if (event.type === "progress") {
     if (event.deleted) {
-      console.log(`  ✗ ${event.path} (deleted)`);
+      // Append `message` when present (e.g. tombstone events carry
+      // "tombstone (remote already 404)"). Without this, tombstones and
+      // real deletes render byte-identically in the tty stream, and
+      // operators have no way to distinguish from logs alone.
+      const suffix = event.message ? ` — ${event.message}` : "";
+      console.log(`  ✗ ${event.path} (deleted)${suffix}`);
     } else if (event.message) {
       console.log(`  ✓ ${event.path} — "${event.message}"`);
     } else {
@@ -624,6 +769,19 @@ function defaultConsoleLogger(event: SyncProgressEvent): void {
     );
   } else if (event.type === "error") {
     console.error(`  ✗ ${event.path} — ${event.message}`);
+  } else if (event.type === "delete-refused-stale-etag") {
+    // Branch on `reason`, not on the sentinel etag strings, so legacy
+    // entries render with a clear explanation instead of "<legacy-no-etag>"
+    // leaking into operator-visible output.
+    if (event.reason === "legacy-no-etag") {
+      console.error(
+        `  ⚠ no-etag-on-record, kept on remote: ${event.path} (journal entry predates etag tracking)`,
+      );
+    } else {
+      console.error(
+        `  ⚠ stale-etag, kept on remote: ${event.path} (journal=${event.journalEtag}, remote=${event.remoteEtag})`,
+      );
+    }
   }
 }
 
@@ -680,6 +838,12 @@ function collectFiles(
   for (const p of paths) {
     const absolutePath = path.isAbsolute(p) ? p : path.resolve(hqRoot, p);
 
+    // Ephemeral artifacts (conflict mirrors) — see EPHEMERAL_PATH_PATTERN doc.
+    // Caller may pass one explicitly; we still refuse to upload it. Basename
+    // check matches the walkDir gate so behavior is identical whether the
+    // mirror is the user-supplied path or found during directory recursion.
+    if (isEphemeralPath(path.basename(absolutePath))) continue;
+
     // existsSync follows symlinks: a dangling top-level link will report
     // not-existing and be skipped here. lstatSync below handles the
     // valid-link case directly without needing the existsSync gate.
@@ -758,6 +922,11 @@ function walkDir(
 
   const entries = fs.readdirSync(dir, { withFileTypes: true });
   for (const entry of entries) {
+    // Ephemeral artifacts (conflict mirrors) are local-only safety backups
+    // that MUST NEVER round-trip to S3. Check basename here so the filter
+    // applies regardless of which company root contains them. See
+    // EPHEMERAL_PATH_PATTERN doc for the full rationale.
+    if (isEphemeralPath(entry.name)) continue;
     const absolutePath = path.join(dir, entry.name);
     const isDir = entry.isDirectory();
 
@@ -898,38 +1067,144 @@ function resolveDeleteScopeRoots(
   return Array.from(prefixes);
 }
 
+/**
+ * Reason a candidate was bucketed into `refusedStale`. Discriminated so
+ * consumers (UI, telemetry, the event logger) can branch on intent without
+ * string-comparing the placeholder etag value.
+ *   - `"stale-etag"`     → currency-gated saw a real etag mismatch (peer
+ *                          drift). `journalEtag` and `remoteEtag` are both
+ *                          real ETag values.
+ *   - `"legacy-no-etag"` → journal entry was written before remoteEtag was
+ *                          tracked. `journalEtag` and `remoteEtag` are
+ *                          placeholder sentinels — do not display as ETags.
+ */
+type RefusedStaleReason = "stale-etag" | "legacy-no-etag";
+
+/**
+ * Three buckets returned by computeDeletePlan, exposed so the execution
+ * loop can take a different action for each:
+ *   - `toDelete`     → issue DeleteObject + drop journal entry.
+ *   - `toTombstone`  → no DeleteObject (remote already 404), drop journal
+ *                      entry. Lets the journal converge with reality even
+ *                      when the remote was cleaned out-of-band.
+ *   - `refusedStale` → no DeleteObject, no journal change. Some other
+ *                      device modified the remote object since this device
+ *                      last synced it; the next pull leg re-pulls via the
+ *                      same `hasRemoteChanged` path the conflict detector
+ *                      uses. Emitted as `delete-refused-stale-etag` events.
+ */
+interface DeletePlan {
+  toDelete: string[];
+  toTombstone: string[];
+  refusedStale: Array<{
+    key: string;
+    journalEtag: string;
+    remoteEtag: string;
+    reason: RefusedStaleReason;
+  }>;
+}
+
+/**
+ * Concurrency cap for the per-file HEAD-O-meter (currency-gated). Sequential
+ * HEADs would add ~N×(50-200ms) to a sync — for the 261-mirror real-world
+ * case that's 15-50s of latency. 16-way concurrency keeps S3 well within
+ * per-prefix burst limits (~3,500 GET/HEAD/sec/prefix is the documented
+ * floor) and bounded under the AWS-SDK default agent's max-sockets so we
+ * don't compete with the in-flight upload pool.
+ */
+const DELETE_PLAN_HEAD_CONCURRENCY = 16;
+
 /**
  * Walk every journal key in `scopeRoots` whose local file is missing from
- * disk and return the keys eligible for a remote `DeleteObject`. An entry
- * is in the plan only when ALL of the following hold:
+ * disk and bucket each candidate into the right action per `policy`. Hard
+ * filters that drop a candidate entirely (no bucket) — regardless of policy:
  *
- *   1. Its key matches (or sits beneath) one of the `scopeRoots` prefixes.
- *   2. Its local file is missing from disk.
- *   3. The current ignore filter (`shouldSync`) accepts the key — so paths
+ *   1. Its key must match (or sit beneath) one of the `scopeRoots` prefixes.
+ *   2. Its local file must be missing from disk (lstat ENOENT). We use
+ *      `lstat` (not `existsSync`) so a dangling symlink — a link whose
+ *      target has been removed but whose link file is still on disk —
+ *      counts as "still present locally" and is NOT delete-propagated.
+ *      Pre-fix, existsSync followed the link, returned false, and the
+ *      entry was queued for remote DeleteObject in the same sync that
+ *      had just uploaded it via `uploadSymlink` — the link round-tripped
+ *      as "upload, then delete" in one cycle. ENOENT means truly absent
+ *      → eligible; other lstat errors propagate.
+ *   3. The current ignore filter (`shouldSync`) accepts the key — paths
  *      filtered out by `.hqignore` / `.gitignore` / `DEFAULT_IGNORES` are
- *      never delete-propagated. This blocks the failure mode where a path
- *      lives in the vault (and the journal) but the local walk skips it
- *      because of asymmetric ignore rules; without this guard the push
- *      leg would erase it.
- *   4. When `policy === "owned-only"`: the journal entry's `direction`
- *      is `"up"` (i.e. this machine previously uploaded the file). This
- *      blocks the failure mode where a behind machine's first `sync now`
- *      push leg would otherwise erase recent uploads from peers, since
- *      those entries are recorded as `direction: "down"` (pulled) or
- *      absent (never seen). Set `policy: "all"` to opt back into the
- *      legacy any-missing-file-deletes behaviour.
+ *      never delete-propagated. Closes the failure mode where a path lives
+ *      in the vault (and journal) but the local walk skips it because of
+ *      asymmetric ignore rules.
+ *
+ *      Dual-hint probe: by the time we're considering this entry for
+ *      remote deletion, the local file is already gone — we have no way to
+ *      know whether it was a regular file or a symlink record. A single
+ *      `isDir=false` probe would silently keep the remote record alive
+ *      whenever the only matching `.hqinclude` allowlist pattern is dir-
+ *      only (e.g. `companies/*\/knowledge/`), since gitignore's slash
+ *      semantics reject the slashless probe. The same dual-hint pattern in
+ *      `walkDir`/`collectFiles` (push) and `computePullPlan` (pull) applies
+ *      symmetrically here. Pure path lookup, no I/O.
+ *   4. The key does NOT match `EPHEMERAL_PATH_PATTERN`. Conflict mirrors
+ *      are local-only artifacts that should never have been journaled in
+ *      the first place; the dedicated reconcile command sweeps already-
+ *      journaled mirrors. Excluding them here keeps a regular `sync now`
+ *      from accidentally deleting a mirror another device is still
+ *      reviewing.
+ *
+ * Then per-policy bucketing:
+ *
+ *   - `"currency-gated"` (default, safest): issue a HEAD against the remote.
+ *     200 + `normalizeEtag(remote) === entry.remoteEtag` → `toDelete`.
+ *     200 + mismatch → `refusedStale` (peer drift; let pull re-pull).
+ *     404 → `toTombstone` (remote was cleaned out-of-band).
+ *     If the journal entry has no recorded `remoteEtag` (legacy entries
+ *     written before etag tracking), the candidate falls back to
+ *     `refusedStale` with `reason: "legacy-no-etag"` — we can't prove
+ *     currency without an etag, so refusal is the safe direction. The
+ *     journal entry survives so a future sync with a recorded etag can
+ *     re-evaluate.
+ *
+ *     HEAD calls are batched at `DELETE_PLAN_HEAD_CONCURRENCY` so a large
+ *     candidate set (e.g. a one-shot reconcile sweep) doesn't serialize
+ *     into N×RTT latency. The candidate set is materialized into a list
+ *     first (synchronous filters above), then the HEAD pass runs in
+ *     bounded-parallel chunks.
+ *
+ *     Note: there is a TOCTOU window between this HEAD and the eventual
+ *     `deleteRemoteFile` call in the share() execution loop. If a peer
+ *     overwrites the object in that window (~50-200ms), the resulting
+ *     delete-marker lands on a newer version than we verified. S3
+ *     versioning makes the worst case recoverable (prior versions are
+ *     retained), and the conditional-delete primitive does not exist on
+ *     S3 DeleteObject — only PutObject/CopyObject accept `IfMatch`. The
+ *     window is bounded, not zero. Realtime sync (separate work) reduces
+ *     it further by keeping the journal continuously fresh.
+ *   - `"owned-only"`: include only entries with `direction === "up"`. No
+ *     HEAD round-trip. Goes to `toDelete`. Legacy fallback.
+ *   - `"all"`: include every candidate. No HEAD, no direction check. Goes
+ *     to `toDelete`. Caller has explicitly opted out of safety gates.
  *
  * Empty `scopeRoots` ⇒ empty plan (caller didn't opt in).
  */
-function computeDeletePlan(
+async function computeDeletePlan(
   journal: SyncJournal,
   syncRoot: string,
   scopeRoots: string[],
   shouldSync: (filePath: string, isDir?: boolean) => boolean,
-  policy: "owned-only" | "all",
-): string[] {
-  if (scopeRoots.length === 0) return [];
-  const out: string[] = [];
+  policy: "currency-gated" | "owned-only" | "all",
+  ctx: EntityContext,
+): Promise<DeletePlan> {
+  const plan: DeletePlan = { toDelete: [], toTombstone: [], refusedStale: [] };
+  if (scopeRoots.length === 0) return plan;
+
+  // Stage 1: synchronous pre-filter. Walk every journal entry and either
+  // drop it (hard filter), assign it directly to a bucket (owned-only /
+  // 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 };
+  const headCandidates: HeadCandidate[] = [];
+
   for (const [relativeKey, entry] of Object.entries(journal.files)) {
     const inScope = scopeRoots.some(
       (root) =>
@@ -939,14 +1214,6 @@ function computeDeletePlan(
     );
     if (!inScope) continue;
     const localPath = path.join(syncRoot, relativeKey);
-    // lstat (not existsSync) so a dangling symlink — a link whose
-    // target has been removed but whose link file is still on disk —
-    // counts as "still present locally" and is NOT delete-propagated.
-    // Pre-fix, existsSync followed the link, returned false, and the
-    // entry was queued for remote DeleteObject in the same sync that
-    // had just uploaded it via uploadSymlink. The link round-tripped
-    // as "upload, then delete" in one cycle. ENOENT means truly
-    // absent → eligible; other lstat errors propagate.
     let presentLocally = true;
     try {
       fs.lstatSync(localPath);
@@ -963,24 +1230,67 @@ function computeDeletePlan(
       }
     }
     if (presentLocally) continue;
-    // (3) Symmetric filter guard. `shouldSync` is constructed from the same
-    //     hqRoot the pull leg uses, so a key the pull would have skipped
-    //     ("ignored") is also one we must not delete-propagate.
-    //
-    //     Dual-hint probe: by the time we're considering this entry for
-    //     remote deletion, the local file is already gone — we have no
-    //     way to know whether it was a regular file or a symlink record.
-    //     A single isDir=false probe would silently keep the remote
-    //     record alive whenever the only matching .hqinclude allowlist
-    //     pattern is dir-only (e.g. `companies/*/knowledge/`), since
-    //     gitignore's slash semantics reject the slashless probe. The
-    //     same dual-hint pattern in walkDir/collectFiles (push) and
-    //     computePullPlan (pull) applies symmetrically here. Pure path
-    //     lookup, no I/O.
     if (!shouldSync(localPath, false) && !shouldSync(localPath, true)) continue;
-    // (4) Direction guard under "owned-only" policy.
-    if (policy === "owned-only" && entry.direction !== "up") continue;
-    out.push(relativeKey);
+    // Ephemeral artifacts (conflict mirrors) never propagate-delete via the
+    // normal path — see EPHEMERAL_PATH_PATTERN doc.
+    if (isEphemeralPath(relativeKey)) continue;
+
+    if (policy === "all") {
+      plan.toDelete.push(relativeKey);
+      continue;
+    }
+    if (policy === "owned-only") {
+      if (entry.direction !== "up") continue;
+      plan.toDelete.push(relativeKey);
+      continue;
+    }
+    // currency-gated: queue for HEAD unless the entry is legacy (no etag).
+    const journalEtag = entry.remoteEtag;
+    if (!journalEtag) {
+      plan.refusedStale.push({
+        key: relativeKey,
+        journalEtag: "<legacy-no-etag>",
+        remoteEtag: "<unknown>",
+        reason: "legacy-no-etag",
+      });
+      continue;
+    }
+    headCandidates.push({ key: relativeKey, journalEtag });
+  }
+
+  // Stage 2: bounded-parallel HEAD pass. Promise.all over chunks of size
+  // `DELETE_PLAN_HEAD_CONCURRENCY` so a large candidate set doesn't
+  // serialize into N round-trips, and so we don't burst past the AWS-SDK
+  // default agent's per-host socket cap. Each result is bucketed
+  // independently — one failed HEAD doesn't poison the others (errors
+  // propagate from the chunk's Promise.all and are surfaced by share()'s
+  // outer try/catch, mirroring the existing pre-share error handling).
+  for (let i = 0; i < headCandidates.length; i += DELETE_PLAN_HEAD_CONCURRENCY) {
+    const chunk = headCandidates.slice(i, i + DELETE_PLAN_HEAD_CONCURRENCY);
+    const results = await Promise.all(
+      chunk.map(async (c) => ({
+        candidate: c,
+        remote: await headRemoteFile(ctx, c.key),
+      })),
+    );
+    for (const { candidate, remote } of results) {
+      if (remote === null) {
+        plan.toTombstone.push(candidate.key);
+        continue;
+      }
+      const currentEtag = normalizeEtag(remote.etag);
+      if (currentEtag === candidate.journalEtag) {
+        plan.toDelete.push(candidate.key);
+      } else {
+        plan.refusedStale.push({
+          key: candidate.key,
+          journalEtag: candidate.journalEtag,
+          remoteEtag: currentEtag,
+          reason: "stale-etag",
+        });
+      }
+    }
   }
-  return out;
+
+  return plan;
 }

package/src/cli/sync.ts

@@ -92,6 +92,34 @@ export type SyncProgressEvent =
   | {
       type: "new-files";
       files: Array<{ path: string; bytes: number; addedBy: string | null }>;
+    }
+  | {
+      /**
+       * Emitted by the `currency-gated` delete policy when a delete candidate
+       * is refused. Two reasons, discriminated by `reason`:
+       *
+       *   - `"stale-etag"`: the local file is missing but the remote object's
+       *     current ETag no longer matches the journal's last-recorded etag.
+       *     Some other device (or another out-of-band write) modified the
+       *     remote object since this machine last synced it. The pull leg of
+       *     `sync now` will re-pull naturally via the same `hasRemoteChanged`
+       *     path that powers conflict detection. Journal entry is left intact
+       *     so the pull can use it as the baseline for the 3-way merge.
+       *     `journalEtag` and `remoteEtag` are real ETag strings.
+       *
+       *   - `"legacy-no-etag"`: the journal entry predates remoteEtag tracking
+       *     (no `remoteEtag` recorded). We can't prove currency without an
+       *     etag, so the delete is refused in the safe direction. A future
+       *     sync that picks up an etag for this entry can re-evaluate.
+       *     `journalEtag` and `remoteEtag` are sentinel strings
+       *     (`<legacy-no-etag>` / `<unknown>`) — do not render as ETags.
+       *     Consumers should branch on `reason`, not on the etag values.
+       */
+      type: "delete-refused-stale-etag";
+      path: string;
+      journalEtag: string;
+      remoteEtag: string;
+      reason: "stale-etag" | "legacy-no-etag";
     };
 
 export interface SyncOptions {