@indigoai-us/hq-cloud 5.23.0 → 5.24.0

package/dist/cli/share.d.ts

@@ -8,6 +8,25 @@ import type { EntityContext, VaultServiceConfig } from "../types.js";
 import type { UploadAuthor } from "../s3.js";
 import type { ConflictStrategy } from "./conflict.js";
 import type { SyncProgressEvent } from "./sync.js";
+/**
+ * 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.
+ */
+declare function isEphemeralPath(p: string): boolean;
+/**
+ * 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 declare const _testing: {
+    isEphemeralPath: typeof isEphemeralPath;
+    EPHEMERAL_PATH_PATTERN: RegExp;
+};
 export interface ShareOptions {
     /** Path(s) to share (files or directories) */
     paths: string[];
@@ -87,29 +106,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
@@ -144,8 +178,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
@@ -158,4 +214,5 @@ export interface ShareResult {
  * Share local file(s) to the entity vault.
  */
 export declare function share(options: ShareOptions): Promise<ShareResult>;
+export {};
 //# sourceMappingURL=share.d.ts.map

package/dist/cli/share.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"share.d.ts","sourceRoot":"","sources":["../../src/cli/share.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAe,MAAM,aAAa,CAAC;AAGlF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAY7C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AA+InD,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC;;;;;;;;;;;;;;;;;;OAkBG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,wBAAwB;IACxB,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAC7C;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;;;;;;;;;;;;OAgBG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,qBAAqB,CAAC,EAAE,YAAY,GAAG,KAAK,CAAC;IAC7C;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,wBAAsB,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAwRvE"}
+{"version":3,"file":"share.d.ts","sourceRoot":"","sources":["../../src/cli/share.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAe,MAAM,aAAa,CAAC;AAGlF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAY7C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAuBnD;;;;;GAKG;AACH,iBAAS,eAAe,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAE3C;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ;;;CAGpB,CAAC;AA+IF,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC;;;;;;;;;;;;;;;;;;OAkBG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,wBAAwB;IACxB,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAC7C;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;;;;;;;;;;;;OAgBG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAyCG;IACH,qBAAqB,CAAC,EAAE,gBAAgB,GAAG,YAAY,GAAG,KAAK,CAAC;IAChE;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB;;;;;;;;;OASG;IACH,iBAAiB,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,wBAAsB,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAmVvE"}

package/dist/cli/share.js

@@ -11,6 +11,46 @@ import { uploadFile, uploadSymlink, headRemoteFile, deleteRemoteFile } from "../
 import { readJournal, writeJournal, hashFile, hashSymlinkTarget, updateEntry, removeEntry, normalizeEtag, } from "../journal.js";
 import { createIgnoreFilter, isWithinSizeLimit } from "../ignore.js";
 import { resolveConflict } from "./conflict.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) {
+    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,
+};
 /**
  * Pure Stage-1 pass for push: walk the candidate file list, hash each one,
  * apply the size-limit and skip-unchanged gates, and return a classified
@@ -94,12 +134,15 @@ function computePushPlan(filesToShare, journal, skipUnchanged) {
  */
 export async function share(options) {
     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.
+    // 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 = options.propagateDeletePolicy ?? "owned-only";
     const emit = options.onEvent ?? defaultConsoleLogger;
     // Exactly-one-of contract: either we vend (vaultConfig) or the caller did
@@ -150,6 +193,13 @@ export async function share(options) {
     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 = [];
     // Collect all files to share
     const filesToShare = collectFiles(paths, hqRoot, syncRoot, shouldSync);
@@ -167,8 +217,8 @@ export async function share(options) {
         ? resolveDeleteScopeRoots(paths, hqRoot, syncRoot)
         : [];
     const deletePlan = propagateDeletes === true
-        ? computeDeletePlan(journal, syncRoot, deleteScopeRoots, shouldSync, propagateDeletePolicy)
-        : [];
+        ? await computeDeletePlan(journal, syncRoot, deleteScopeRoots, shouldSync, propagateDeletePolicy, ctx)
+        : { toDelete: [], toTombstone: [], refusedStale: [] };
     emit({
         type: "plan",
         // share() is push-only; pull counts are sourced from sync()'s plan event.
@@ -180,7 +230,11 @@ export async function share(options) {
         // 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
     // upload candidate run the HEAD + 3-way conflict check + actual PUT.
@@ -240,6 +294,11 @@ export async function share(options) {
                         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,
                     };
@@ -292,12 +351,28 @@ export async function share(options) {
             });
         }
     }
-    // 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);
         }
@@ -322,6 +397,27 @@ export async function share(options) {
             });
         }
     }
+    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.
     journal.lastSync = new Date().toISOString();
@@ -331,6 +427,8 @@ export async function share(options) {
         bytesUploaded,
         filesSkipped,
         filesDeleted,
+        filesTombstoned,
+        filesRefusedStale,
         conflictPaths,
         aborted: false,
     };
@@ -347,7 +445,12 @@ function defaultConsoleLogger(event) {
     }
     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}"`);
@@ -362,6 +465,17 @@ function defaultConsoleLogger(event) {
     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})`);
+        }
+    }
 }
 /**
  * Resolve active company from .hq/config.json or parent directory chain.
@@ -395,6 +509,12 @@ function collectFiles(paths, hqRoot, syncRoot, filter) {
     const results = [];
     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.
@@ -468,6 +588,12 @@ function walkDir(dir, syncRoot, filter) {
         return results;
     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();
         // Symlinks need their own filter probe BEFORE the regular gate.
@@ -598,33 +724,92 @@ function resolveDeleteScopeRoots(paths, hqRoot, syncRoot) {
     }
     return Array.from(prefixes);
 }
+/**
+ * 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(journal, syncRoot, scopeRoots, shouldSync, policy) {
+async function computeDeletePlan(journal, syncRoot, scopeRoots, shouldSync, policy, ctx) {
+    const plan = { toDelete: [], toTombstone: [], refusedStale: [] };
     if (scopeRoots.length === 0)
-        return [];
-    const out = [];
+        return plan;
+    const headCandidates = [];
     for (const [relativeKey, entry] of Object.entries(journal.files)) {
         const inScope = scopeRoots.some((root) => root === "" ||
             relativeKey === root ||
@@ -632,14 +817,6 @@ function computeDeletePlan(journal, syncRoot, scopeRoots, shouldSync, policy) {
         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);
@@ -657,27 +834,67 @@ function computeDeletePlan(journal, syncRoot, scopeRoots, shouldSync, policy) {
         }
         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")
+        // 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;
-        out.push(relativeKey);
+        }
+        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;
 }
 //# sourceMappingURL=share.js.map