@indigoai-us/hq-cloud 6.15.31 → 6.15.32

package/dist/cli/share.js

@@ -76,9 +76,10 @@ async function remoteContentDiffers(ctx, relativePath, localHash, hqRoot) {
     }
 }
 /**
- * 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]`
+ * Local-only ephemeral artifacts: conflict-side files written whenever a
+ * 3-way merge preserves the displaced side for inspection. Depending on the
+ * selected strategy, that side may be local or remote. Format:
+ * `<orig>.conflict-<ISO-utc>-<machineHash>[.ext]`
  * (e.g. `.claude/CLAUDE.md.conflict-2026-05-13T19-40-40Z-e5797a.md`,
  * or `.gitignore.conflict-2026-05-13T19-40-40Z-e5797a` — extensionless
  * originals produce no trailing dot, see `buildConflictPath` in
@@ -236,17 +237,109 @@ export const _testing = {
     resolveNamedPath,
     isWithinLexicalOrReal,
     defaultConsoleLogger,
+    statMatchesJournal,
 };
+/** Snapshot of `absolutePath`, or null when it is missing or not a plain file. */
+function statSnapshot(absolutePath) {
+    try {
+        const lstat = fs.lstatSync(absolutePath);
+        if (!lstat.isFile())
+            return null;
+        return { size: lstat.size, mtimeMs: lstat.mtimeMs, ctimeMs: lstat.ctimeMs };
+    }
+    catch {
+        return null;
+    }
+}
+function sameStatSnapshot(a, b) {
+    return (a !== null &&
+        b !== null &&
+        a.size === b.size &&
+        a.mtimeMs === b.mtimeMs &&
+        a.ctimeMs === b.ctimeMs);
+}
+/**
+ * The `ctimeMs` it is safe to stamp alongside a hash, or undefined.
+ *
+ * `hashedStat` is the stat the hash was computed against. If the file has moved
+ * since, the hash in hand describes bytes that are no longer on disk, and
+ * pairing it with the current timestamps would let every later pass skip the
+ * new body on stat alone. Returning undefined leaves the entry without a ctime,
+ * which the skip gate refuses — so the next pass hashes it.
+ */
+function ctimeToStamp(hashedStat, lstat) {
+    if (!hashedStat)
+        return undefined;
+    const current = {
+        size: lstat.size,
+        mtimeMs: lstat.mtimeMs,
+        ctimeMs: lstat.ctimeMs,
+    };
+    return sameStatSnapshot(hashedStat, current) ? lstat.ctimeMs : undefined;
+}
+/**
+ * True when a timestamp pair is too coarse to be evidence of anything.
+ *
+ * FAT/exFAT, some FUSE mounts and cached network filesystems round timestamps
+ * to whole seconds (FAT's mtime granularity is two), and may synthesize ctime
+ * from mtime. On such a volume a same-size rewrite inside one tick leaves both
+ * fields equal to the journal's, and the skip gate would strand the edit
+ * forever. Every filesystem this gate can safely run on — APFS, ext4, NTFS —
+ * records sub-second precision, so a pair sitting exactly on the second is
+ * treated as untrustworthy and sent back to hashing.
+ *
+ * The cost of the false positive is one hash: on a real filesystem a file whose
+ * mtime AND ctime both land exactly on a second boundary is rare, and it is
+ * simply hashed as it was before the fast path existed.
+ */
+function timestampsTooCoarseToTrust(mtimeMs, ctimeMs) {
+    return mtimeMs % 1000 === 0 && ctimeMs % 1000 === 0;
+}
 /**
- * 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
- * plan plus aggregate counts. No S3 calls, no journal writes, no event
- * emission.
+ * True when `absolutePath` provably has not been written since its journal
+ * entry was stamped, judged from stat alone.
+ *
+ * Fails closed. Anything unusual about the entry — no stat recorded, a
+ * tombstone, a pending local delete, a pull-held divergence, a symlink record,
+ * or a local object that is no longer a plain file — returns false and sends
+ * the caller down the hashing path, which is the pre-fast-path behaviour.
  *
- * The conflict count is intentionally absent from the returned `PushPlan` —
- * detecting a push conflict requires a remote HEAD that we defer to Stage 2.
- * Consumers that want a conflict count get it from the `complete` event.
+ * The three fields are compared exactly, on purpose. `mtimeMs` from `lstat`
+ * carries sub-millisecond precision that `utimes` cannot reproduce, so a
+ * restored timestamp differs from the original anyway — but that is an
+ * accident of precision, not a guarantee, and nothing here leans on it.
+ * `ctimeMs` is the field doing the real work.
  */
+function statMatchesJournal(absolutePath, entry) {
+    if (!entry)
+        return false;
+    if (!entry.hash)
+        return false;
+    if (entry.kind === "symlink")
+        return false;
+    if (entry.localDiverges)
+        return false;
+    if (entry.removedAt !== undefined)
+        return false;
+    if (entry.localDeleteIntent !== undefined)
+        return false;
+    if (entry.mtimeMs === undefined || entry.ctimeMs === undefined)
+        return false;
+    if (timestampsTooCoarseToTrust(entry.mtimeMs, entry.ctimeMs))
+        return false;
+    let lstat;
+    try {
+        lstat = fs.lstatSync(absolutePath);
+    }
+    catch {
+        return false;
+    }
+    if (!lstat.isFile())
+        return false;
+    return (lstat.size === entry.size &&
+        lstat.mtimeMs === entry.mtimeMs &&
+        lstat.ctimeMs === entry.ctimeMs);
+}
 function computePushPlan(filesToShare, journal, skipUnchanged, onHeartbeat) {
     const items = [];
     for (const entry of filesToShare) {
@@ -264,7 +357,10 @@ function computePushPlan(filesToShare, journal, skipUnchanged, onHeartbeat) {
             const localHash = hashSymlinkTarget(entry.target);
             if (skipUnchanged) {
                 const existing = journal.files[relativePath];
-                if (existing && existing.hash === localHash) {
+                // `!localDiverges`: see the regular-file gate below — a divergent entry
+                // stores the current LOCAL hash, so hash equality here proves only that
+                // local has not moved since the pull-side hold, never that it matches remote.
+                if (existing && existing.hash === localHash && !existing.localDiverges) {
                     items.push({ action: "skip-unchanged", absolutePath, relativePath });
                     continue;
                 }
@@ -284,28 +380,59 @@ function computePushPlan(filesToShare, journal, skipUnchanged, onHeartbeat) {
             items.push({ action: "skip-size-limit", absolutePath, relativePath });
             continue;
         }
-        // Stat metadata is not content identity: tools can rewrite a file with
-        // the same byte length and restore its mtime. Hash every regular file so
-        // such an edit cannot be skipped indefinitely.
+        // Stat fast path. Reading and hashing every regular file every pass costs
+        // one full read of the vault — hundreds of thousands of files on a real
+        // install — to answer a question stat can usually answer for free.
+        //
+        // The gate is size + mtime + ctime, and ctime is what makes it safe. mtime
+        // is forgeable: `cp -p`, `touch -r` and `rsync --times` put an old mtime
+        // back on new bytes, so a size+mtime check would skip such an edit forever
+        // — the failure this code previously hashed everything to avoid. ctime is
+        // the inode-change stamp and userspace cannot set it; the very utimes call
+        // that restores mtime moves ctime to now. A file that clears all three has
+        // not been written since we hashed it.
+        //
+        // Deliberately NOT skipped here:
+        //   - entries with no recorded mtime/ctime (written before stat tracking,
+        //     or by a downloader that did not stamp) — hashed once, then stamped
+        //     by the restamp below so the next pass is free;
+        //   - `localDiverges` entries — see the hash gate below for why equality
+        //     proves nothing about them.
+        if (skipUnchanged && statMatchesJournal(absolutePath, journal.files[relativePath])) {
+            items.push({ action: "skip-unchanged", absolutePath, relativePath });
+            continue;
+        }
+        // Snapshot stat either side of the read. If the two differ the file was
+        // rewritten while we hashed it, so `localHash` may describe bytes that are
+        // already gone — and nothing downstream may stamp a timestamp against it.
+        const statBeforeHash = statSnapshot(absolutePath);
         const localHash = hashFile(absolutePath);
+        const statAfterHash = statSnapshot(absolutePath);
+        const statAtHash = sameStatSnapshot(statBeforeHash, statAfterHash)
+            ? statAfterHash ?? undefined
+            : undefined;
         if (skipUnchanged) {
             const existing = journal.files[relativePath];
-            if (existing && existing.hash === localHash) {
+            // A `localDiverges` entry records the hash of the KEPT LOCAL body, so
+            // `existing.hash === localHash` is true for every such file by
+            // construction. Skipping on that equality asserts "local matches remote",
+            // which is precisely the claim the flag exists to deny — and it would
+            // strand the file: the runner's push leg always passes skipUnchanged,
+            // so the conflict path that could publish it never runs, and the pull leg
+            // sees an unchanged remote and re-arms the flag. Route these to the HEAD
+            // + conflict path instead and let the resolution decide.
+            if (existing && existing.hash === localHash && !existing.localDiverges) {
                 // The hash proved the bytes are unchanged — a no-op skip. Capture the
                 // current (mtimeMs, size) so the journal metadata stays accurate. Only
                 // attach when the stored stat actually differs (avoid a needless
                 // journal write on an already-current entry). Stat failure → no
                 // restamp; the skip still stands.
                 let restamp;
-                try {
-                    const lstat = fs.lstatSync(absolutePath);
-                    if (lstat.isFile() &&
-                        (existing.mtimeMs !== lstat.mtimeMs || existing.size !== lstat.size)) {
-                        restamp = { mtimeMs: lstat.mtimeMs, size: lstat.size };
-                    }
-                }
-                catch {
-                    /* best-effort; a stat error just forgoes the fast-path refresh */
+                if (statAtHash &&
+                    (existing.mtimeMs !== statAtHash.mtimeMs ||
+                        existing.ctimeMs !== statAtHash.ctimeMs ||
+                        existing.size !== statAtHash.size)) {
+                    restamp = statAtHash;
                 }
                 items.push({ action: "skip-unchanged", absolutePath, relativePath, restamp });
                 continue;
@@ -319,6 +446,7 @@ function computePushPlan(filesToShare, journal, skipUnchanged, onHeartbeat) {
             relativePath,
             localHash,
             size,
+            ...(statAtHash ? { statAtHash } : {}),
         });
     }
     let filesToUpload = 0;
@@ -335,6 +463,52 @@ function computePushPlan(filesToShare, journal, skipUnchanged, onHeartbeat) {
     }
     return { items, filesToUpload, bytesToUpload, filesToSkip };
 }
+/** Re-read one collected path at the execution seam. */
+function recollectPushEntry(item) {
+    let lstat;
+    try {
+        lstat = fs.lstatSync(item.absolutePath);
+    }
+    catch {
+        return null;
+    }
+    if (lstat.isSymbolicLink()) {
+        const target = readlinkOrNull(item.absolutePath);
+        return target === null
+            ? null
+            : {
+                kind: "symlink",
+                absolutePath: item.absolutePath,
+                relativePath: item.relativePath,
+                target,
+            };
+    }
+    return lstat.isFile()
+        ? {
+            kind: "file",
+            absolutePath: item.absolutePath,
+            relativePath: item.relativePath,
+        }
+        : null;
+}
+/**
+ * Turn the whole-run push plan into a preview only. The item returned here was
+ * classified from the bytes and journal state that exist immediately before a
+ * worker starts, so callers never upload with a hash captured near pass entry.
+ */
+function replanPushItemAtExecution(item, journal, skipUnchanged, onHeartbeat) {
+    const current = recollectPushEntry(item);
+    if (current === null)
+        return null;
+    return computePushPlan([current], journal, skipUnchanged, onHeartbeat).items[0] ?? null;
+}
+function uploadBodyMatchesPlan(planned, current) {
+    if (planned.kind !== current.kind || planned.localHash !== current.localHash) {
+        return false;
+    }
+    return planned.kind === "file" ||
+        (current.kind === "symlink" && planned.target === current.target);
+}
 /**
  * Thrown by `share()` when a caller-named path cannot be pushed and
  * `unreachablePathPolicy` is `"error"` (the default). Raised while the plans
@@ -805,75 +979,115 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
         (!run.ctx.uid.startsWith("prs_") && run.vaultConfig
             ? await fetchCompanyTombstones(run.vaultConfig, run.ctx.uid)
             : new Map());
-    const uploadItems = [];
-    for (const item of pushPlan.items) {
+    const isUploadSuppressedByTombstone = (item) => {
+        if (fileTombstones.size === 0)
+            return false;
+        const tombstone = fileTombstones.get(toPosixKey(item.relativePath));
+        if (tombstone === undefined)
+            return false;
+        const entry = run.journal.files[item.relativePath];
+        return entry !== undefined && entry.hash === item.localHash;
+    };
+    // Prime from the preview's likely uploads for transport efficiency. The
+    // candidate is refreshed after the plan event and tombstone suppression is
+    // applied BEFORE any presigns are minted. The queue below still re-plans
+    // every preview item before admission, so a later edit cannot disappear from
+    // the pass or carry a stale hash into its journal entry.
+    const initiallyPlannedUploads = [];
+    for (const previewItem of pushPlan.items) {
+        if (previewItem.action !== "upload")
+            continue;
+        const item = replanPushItemAtExecution(previewItem, run.journal, run.skipUnchanged === true, run.options.onHeartbeat);
+        if (item?.action === "upload" &&
+            !isUploadSuppressedByTombstone(item)) {
+            initiallyPlannedUploads.push(item);
+        }
+    }
+    await primeUploads(run.ctx, initiallyPlannedUploads.map((it) => ({
+        key: it.relativePath,
+        localPath: it.absolutePath,
+        isSymlink: it.kind === "symlink",
+        author: run.options.author,
+    })));
+    // Warm the GET presigns the per-item conflict HEAD (remoteMeta) reuses, so a
+    // large upload set doesn't mint one presign per HEAD and burst/trip the
+    // presign breaker. Mirrors the new-files + tombstone pre-primes on the pull.
+    await primeObjectTransport(run.ctx, "get", initiallyPlannedUploads.map((it) => it.relativePath));
+    let aborted = false;
+    let abortFlightConflictPaths = [];
+    let hadUploadFailure = false;
+    const settleFreshSkip = (item) => {
         if (item.action === "skip-size-limit") {
             // A file over the size cap is a permanent, benign skip — NOT an error.
-            // Emitting it as `type: "error"` pushed it into the runner's `errors[]`,
-            // so every watch pass returned exit 2 and the menubar reported an
-            // "auto-sync watcher exited unexpectedly (code=Some(2))" crash on every
-            // tick (the HQ-SYNC-4 flood across user machines). Surface it for visibility, but
-            // do not let it flip the pass to a non-zero exit.
             let bytes = 0;
             try {
                 bytes = fs.statSync(item.absolutePath).size;
             }
             catch {
-                // Best-effort size for display only; a stat race must not break the sync.
+                // Best-effort size for display only; a stat race must not break sync.
             }
             run.emit({
                 type: "skip-size-limit",
                 path: item.relativePath,
                 bytes,
             });
-            counters.filesSkipped++;
-            continue;
         }
-        if (item.action === "upload") {
-            if (fileTombstones.size > 0) {
-                const ts = fileTombstones.get(toPosixKey(item.relativePath));
-                if (ts !== undefined) {
-                    const entry = run.journal.files[item.relativePath];
-                    if (entry && entry.hash === item.localHash) {
-                        counters.filesSuppressedByTombstone++;
-                        run.emit({
-                            type: "upload-suppressed-tombstone",
-                            path: item.relativePath,
-                            deletedAt: ts.deletedAt,
-                        });
-                        continue;
-                    }
-                }
-            }
-            uploadItems.push(item);
-            continue;
-        }
-        if (item.restamp) {
+        else if (item.restamp) {
             const existing = run.journal.files[item.relativePath];
             if (existing && existing.hash) {
                 existing.mtimeMs = item.restamp.mtimeMs;
+                existing.ctimeMs = item.restamp.ctimeMs;
                 existing.size = item.restamp.size;
             }
         }
         counters.filesSkipped++;
-    }
-    await primeUploads(run.ctx, uploadItems.map((it) => ({
-        key: it.relativePath,
-        localPath: it.absolutePath,
-        isSymlink: it.kind === "symlink",
-        author: run.options.author,
-    })));
-    // Warm the GET presigns the per-item conflict HEAD (remoteMeta) reuses, so a
-    // large upload set doesn't mint one presign per HEAD and burst/trip the
-    // presign breaker. Mirrors the new-files + tombstone pre-primes on the pull.
-    await primeObjectTransport(run.ctx, "get", uploadItems.map((it) => it.relativePath));
-    let aborted = false;
-    let abortFlightConflictPaths = [];
-    let hadUploadFailure = false;
-    const processUploadItem = async (item) => {
+    };
+    const suppressFreshTombstone = (item) => {
+        if (!isUploadSuppressedByTombstone(item))
+            return false;
+        const tombstone = fileTombstones.get(toPosixKey(item.relativePath));
+        if (tombstone === undefined)
+            return false;
+        counters.filesSuppressedByTombstone++;
+        run.emit({
+            type: "upload-suppressed-tombstone",
+            path: item.relativePath,
+            deletedAt: tombstone.deletedAt,
+        });
+        return true;
+    };
+    const processUploadItem = async (item, replanAttempts = 0) => {
         if (aborted)
             return;
         const { absolutePath, relativePath, localHash } = item;
+        const refreshUploadItem = () => {
+            const refreshed = replanPushItemAtExecution(item, run.journal, run.skipUnchanged === true, run.options.onHeartbeat);
+            if (refreshed === null) {
+                counters.filesSkipped++;
+                return null;
+            }
+            if (refreshed.action !== "upload") {
+                settleFreshSkip(refreshed);
+                return null;
+            }
+            if (suppressFreshTombstone(refreshed))
+                return null;
+            return refreshed;
+        };
+        const restartForChangedBody = async (refreshed) => {
+            // An actively-written file must never become a synthetic conflict or a
+            // journal row for bytes we did not upload. Bound retries so a hot log
+            // cannot monopolise a worker; the next sync pass will try it again.
+            if (replanAttempts >= 3) {
+                counters.filesSkipped++;
+                return;
+            }
+            await processUploadItem(refreshed, replanAttempts + 1);
+        };
+        // Set when `publish-local` was chosen for a FRESH two-sided conflict rather
+        // than for the `localDiverges` recovery. The two cases need different write
+        // fences — see the precondition block below.
+        let fenceOnObservedRemote = false;
         // Cloud-authoritative paths (server-regenerated: company-brief.md, board.json,
         // ontology/ signals/ sources/) are PULL-WINS and server-owned. The push leg must
         // NEVER upload the local copy over them — not just on a two-sided conflict, but on
@@ -904,12 +1118,54 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
             }
             throw headErr;
         }
+        // HEAD is an await boundary. Re-read the local object afterwards and
+        // restart the whole per-file decision if it moved while the remote check
+        // was in flight. The old HEAD result must not classify the new body.
+        const afterHead = refreshUploadItem();
+        if (afterHead === null)
+            return;
+        if (!uploadBodyMatchesPlan(item, afterHead)) {
+            await restartForChangedBody(afterHead);
+            return;
+        }
         // Journal entry for this key (if any). Used both for 3-way conflict
         // classification and for the write fence below: Prefer last-synced
         // `remoteEtag` over live HEAD so a peer-advanced object cannot be
         // silently LWW-overwritten by a journaled stale local body (Ace-shaped
         // vault regression 2026-08-03).
         const journalEntry = run.journal.files[relativePath];
+        // A `localDiverges` entry whose remote object is GONE (HEAD null — peer
+        // delete, or an operator purge with no tombstone) must not fall through to
+        // the ordinary recreation path below. That path fences with
+        // `If-None-Match: *`, which succeeds precisely because the object is absent,
+        // so the divergent local body would resurrect a key the peer deliberately
+        // removed — the exact opposite of this strategy's promise that local is
+        // promoted ONLY while the remote still sits at the recorded etag. A missing
+        // object is the strongest possible statement that it does not.
+        //
+        // Scoped to divergent entries: `keep`'s recreate-once behaviour for an
+        // ordinary journaled key whose remote was deleted is unchanged.
+        if (!remoteMeta && journalEntry?.localDiverges) {
+            conflictPaths.push(relativePath);
+            const resolution = await resolveConflictSerialized({
+                path: relativePath,
+                localHash,
+                direction: "push",
+            });
+            run.emit({ type: "conflict", path: relativePath, direction: "push", resolution });
+            if (resolution === "abort") {
+                aborted = true;
+                abortFlightConflictPaths = [...conflictPaths];
+                return;
+            }
+            if (resolution !== "overwrite") {
+                // `publish-local`, `keep` and `skip` all decline to resurrect. Only an
+                // explicit `overwrite` — consent given with the deletion in view — falls
+                // through to the create below.
+                counters.filesSkipped++;
+                return;
+            }
+        }
         if (remoteMeta) {
             const localChanged = !!journalEntry && journalEntry.hash !== localHash;
             const remoteChanged = !!journalEntry && hasRemoteChanged(remoteMeta, journalEntry);
@@ -932,6 +1188,7 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
                 updateEntry(run.journal, relativePath, localHash, lstat.size, "up", absolutePath, {
                     remoteEtag: remoteMeta.etag,
                     mtimeMs: lstat.mtimeMs,
+                    ctimeMs: ctimeToStamp(item.kind === "file" ? item.statAtHash : undefined, lstat),
                     kind: item.kind,
                 });
                 // Same checkpoint contract as an actual upload. After repeated
@@ -945,8 +1202,8 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
                 counters.filesSkipped++;
                 return;
             }
-            // `localDiverges` means a prior pull-keep stamped the remote etag for
-            // re-fire silence (#137) while local never matched that remote. The
+            // `localDiverges` means a prior pull-side hold stamped the remote etag
+            // for re-fire silence (#137) while local never matched that remote. The
             // journal-baseline If-Match fence alone would SUCCEED when remote is
             // still at that etag, silently promoting the divergent local to write
             // authority. Route through conflict (keep/abort/overwrite) instead.
@@ -973,18 +1230,52 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
                     abortFlightConflictPaths = [...conflictPaths];
                     return;
                 }
-                if (resolution === "keep" || resolution === "skip") {
+                if (resolution === "keep") {
+                    await writePushConflictMirror(run, item, normalizeEtag(remoteMeta.etag), "local");
+                    counters.filesSkipped++;
+                    return;
+                }
+                if (resolution === "skip") {
                     if (isFreshCollision) {
-                        await writePushConflictMirror(run, item, normalizeEtag(remoteMeta.etag));
+                        await writePushConflictMirror(run, item, normalizeEtag(remoteMeta.etag), "remote");
                     }
                     counters.filesSkipped++;
                     return;
                 }
-                // overwrite: fall through to conditional PUT (or unfenced retry on 412).
+                // `publish-local` on a FRESH two-sided conflict must fence on the etag
+                // just observed by HEAD, not on the journal's. Here `remoteChanged` is
+                // true, which means the journal etag is stale BY DEFINITION — fencing on
+                // it would 412 every time and the file could never publish, leaving the
+                // operator's explicit choice permanently unhonoured. Consent given at
+                // this prompt is consent against the remote they were just shown.
+                //
+                // The `divergentLocalHonesty` recovery keeps the JOURNAL etag: there the
+                // recorded etag is exactly the version the operator saw when they chose
+                // to keep, and a mismatch is the signal to fail closed.
+                fenceOnObservedRemote =
+                    resolution === "publish-local" && !divergentLocalHonesty;
+                // `overwrite` falls through to the conditional PUT and, on 412, retries
+                // with no precondition — unconditional by design.
+                //
+                // `publish-local` falls through to the SAME conditional PUT but stops
+                // there: see the 412 handler below, which fails it closed instead of
+                // retrying unfenced. That fence is the whole point of the strategy — it
+                // promotes the divergent local body only while the remote is still the
+                // version the operator saw when they chose to keep it.
             }
         }
         if (aborted)
             return;
+        // Conflict probes and prompts above are also await boundaries. Make the
+        // PUT inseparable from a final fresh local classification: if the body
+        // changed, discard this decision and begin again with a new HEAD.
+        const beforePut = refreshUploadItem();
+        if (beforePut === null)
+            return;
+        if (!uploadBodyMatchesPlan(item, beforePut)) {
+            await restartForChangedBody(beforePut);
+            return;
+        }
         // Write fence: when remote exists, prefer last-synced journal remoteEtag
         // over live HEAD so a peer-advanced object fails closed (412 → keep/
         // abort/overwrite). Live-HEAD If-Match alone only covers HEAD→PUT TOCTOU.
@@ -994,19 +1285,22 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
         // If-Match against a missing object cannot succeed and false-conflicts.
         // Legacy entries without remoteEtag fall back to live HEAD (prior behavior).
         const precondition = remoteMeta
-            ? journalEntry?.remoteEtag
-                ? { ifMatch: journalEntry.remoteEtag }
-                : { ifMatch: remoteMeta.etag }
+            ? fenceOnObservedRemote
+                ? { ifMatch: normalizeEtag(remoteMeta.etag) }
+                : journalEntry?.remoteEtag
+                    ? { ifMatch: journalEntry.remoteEtag }
+                    : { ifMatch: remoteMeta.etag }
             : { ifNoneMatch: "*" };
         const performUpload = async (pc) => {
             const isSymlinkUpload = item.kind === "symlink";
             const lstat = fs.lstatSync(absolutePath);
             const size = isSymlinkUpload ? 0 : lstat.size;
             const mtimeMs = lstat.mtimeMs;
+            const ctimeMs = ctimeToStamp(item.kind === "file" ? item.statAtHash : undefined, lstat);
             const { etag } = isSymlinkUpload
                 ? await uploadSymlink(run.ctx, item.target, relativePath, run.options.author, pc)
                 : await uploadFile(run.ctx, absolutePath, relativePath, run.options.author, pc);
-            updateEntry(run.journal, relativePath, localHash, size, "up", absolutePath, { remoteEtag: etag, mtimeMs, kind: item.kind });
+            updateEntry(run.journal, relativePath, localHash, size, "up", absolutePath, { remoteEtag: etag, mtimeMs, ctimeMs, kind: item.kind });
             if (run.message) {
                 run.journal.files[relativePath] = {
                     ...run.journal.files[relativePath],
@@ -1055,6 +1349,22 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
                     abortFlightConflictPaths = [...conflictPaths];
                     return;
                 }
+                // A 412 here means the remote advanced between the plan and the PUT.
+                // `publish-local` consented to replacing ONE specific version; that
+                // version is gone, so the consent no longer covers what is there now.
+                // Fail closed — mirror the remote and skip — rather than inheriting
+                // `overwrite`'s unfenced retry, which would clobber the peer's write.
+                //
+                // Keyed off the FRESH resolution above, not the earlier one: an
+                // interactive operator re-prompted at this point may legitimately
+                // escalate to `overwrite`, and that is new consent against the remote
+                // as it stands now. Only a repeated `publish-local` — which is what the
+                // non-interactive strategy returns — stays fenced.
+                if (resolution === "publish-local") {
+                    await writePushConflictMirror(run, item, remoteMeta ? normalizeEtag(remoteMeta.etag) : "", "remote");
+                    counters.filesSkipped++;
+                    return;
+                }
                 if (resolution === "overwrite") {
                     try {
                         await performUpload(undefined);
@@ -1071,7 +1381,7 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
                     }
                     return;
                 }
-                await writePushConflictMirror(run, item, remoteMeta ? normalizeEtag(remoteMeta.etag) : "");
+                await writePushConflictMirror(run, item, remoteMeta ? normalizeEtag(remoteMeta.etag) : "", resolution === "keep" ? "local" : "remote");
                 counters.filesSkipped++;
                 return;
             }
@@ -1097,19 +1407,35 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
         // unless nothing is in flight, so a single file larger than the entire
         // budget still makes progress and the pool never deadlocks.
         const byteBudget = resolveUploadByteBudget(run.hostLoadAtStart.availableMemFraction);
-        const queue = [...uploadItems];
+        const queue = [...pushPlan.items];
         const inFlight = new Set();
         let inFlightBytes = 0;
         while (queue.length > 0 || inFlight.size > 0) {
             while (!aborted && inFlight.size < TRANSFER_CONCURRENCY && queue.length > 0) {
+                const previewItem = queue[0];
+                const item = replanPushItemAtExecution(previewItem, run.journal, run.skipUnchanged === true, run.options.onHeartbeat);
+                if (item === null) {
+                    queue.shift();
+                    counters.filesSkipped++;
+                    continue;
+                }
+                if (item.action !== "upload") {
+                    queue.shift();
+                    settleFreshSkip(item);
+                    continue;
+                }
+                if (suppressFreshTombstone(item)) {
+                    queue.shift();
+                    continue;
+                }
                 // Reserve the file's CURRENT on-disk size, not the planned size: an
                 // active log/session file can grow between planning and upload, and
                 // uploadFile buffers the whole current body. A stale planned size would
                 // let several "small" files all be admitted and then blow the budget.
-                const nextBytes = currentUploadBytes(queue[0]);
+                const nextBytes = currentUploadBytes(item);
                 if (inFlight.size > 0 && inFlightBytes + nextBytes > byteBudget)
                     break;
-                const item = queue.shift();
+                queue.shift();
                 inFlightBytes += nextBytes;
                 const p = processUploadItem(item)
                     .catch((err) => {
@@ -1136,13 +1462,17 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
     }
     return { aborted, abortFlightConflictPaths, workerErrors, hadUploadFailure };
 }
-async function writePushConflictMirror(run, item, remoteHash) {
+async function writePushConflictMirror(run, item, remoteHash, preserved) {
+    let localMovedAside = false;
+    let remoteAdopted = false;
+    let conflictAbs;
+    let effectiveRemoteHash = remoteHash;
     try {
         const detectedAt = new Date().toISOString();
         const machineId = readShortMachineId(run.hqRoot);
         const originalRelative = vaultKeyForLocalPath(run.hqRoot, item.absolutePath);
         const conflictRelative = buildConflictPath(originalRelative, detectedAt, machineId);
-        const conflictAbs = localPathForVaultKey(run.hqRoot, conflictRelative);
+        conflictAbs = localPathForVaultKey(run.hqRoot, conflictRelative);
         if (!isMaterializationPathStillContained(run.syncRoot, conflictAbs)) {
             run.emit({
                 type: "error",
@@ -1151,7 +1481,42 @@ async function writePushConflictMirror(run, item, remoteHash) {
             });
         }
         else {
-            await downloadFile(run.ctx, item.relativePath, conflictAbs);
+            if (preserved === "local") {
+                // A keep reached after a 412 may have been planned against no object or
+                // an older one. Refresh the version token before journalling the body we
+                // are about to adopt; retain the observed token if HEAD is unavailable.
+                const latestRemote = await headRemoteFile(run.ctx, item.relativePath);
+                if (latestRemote?.etag) {
+                    effectiveRemoteHash = normalizeEtag(latestRemote.etag);
+                }
+                // `keep` has one meaning in both directions: cloud wins the working
+                // name while the displaced local body remains recoverable beside it.
+                // Rename first, then reuse the ordinary tested download path for the
+                // replacement instead of hand-rolling a swap around an ad-hoc GET.
+                fs.renameSync(item.absolutePath, conflictAbs);
+                localMovedAside = true;
+                const downloaded = await downloadFile(run.ctx, item.relativePath, item.absolutePath);
+                remoteAdopted = true;
+                const localLstat = fs.lstatSync(item.absolutePath);
+                const isLocalSymlink = localLstat.isSymbolicLink();
+                const remoteBodyHash = isLocalSymlink
+                    ? hashSymlinkTarget(fs.readlinkSync(item.absolutePath))
+                    : (downloaded?.contentHash ?? hashFile(item.absolutePath));
+                const remoteBodySize = isLocalSymlink
+                    ? 0
+                    : (downloaded?.contentSize ?? localLstat.size);
+                const createdBySub = downloaded?.metadata?.["created-by-sub"];
+                updateEntry(run.journal, item.relativePath, remoteBodyHash, remoteBodySize, "down", item.absolutePath, {
+                    remoteEtag: effectiveRemoteHash,
+                    mtimeMs: localLstat.mtimeMs,
+                    ctimeMs: localLstat.ctimeMs,
+                    ...(createdBySub !== undefined ? { createdBySub } : {}),
+                    kind: isLocalSymlink ? "symlink" : "file",
+                });
+            }
+            else {
+                await downloadFile(run.ctx, item.relativePath, conflictAbs);
+            }
             appendConflictEntry(run.hqRoot, {
                 id: buildConflictId(originalRelative, detectedAt),
                 originalPath: originalRelative,
@@ -1160,13 +1525,40 @@ async function writePushConflictMirror(run, item, remoteHash) {
                 side: "push",
                 machineId,
                 localHash: item.localHash,
-                remoteHash,
+                remoteHash: effectiveRemoteHash,
+                preserved,
             });
+            if (preserved === "local") {
+                // Persist the converged remote-backed entry immediately. A conflict
+                // resolution is a completed transfer even though the push counter is
+                // recorded as skipped, and an interrupted pass must not revive it.
+                checkpointShareJournal(run);
+            }
         }
     }
     catch (mirrorErr) {
+        // If adopting the remote failed before it became the working copy, put the
+        // local body back. The remote remains authoritative in cloud, so replacing
+        // any partial local materialization is safe and leaves this pass no worse
+        // than the pre-conflict state.
+        if (localMovedAside && !remoteAdopted && conflictAbs) {
+            try {
+                fs.rmSync(item.absolutePath, { force: true });
+                fs.renameSync(conflictAbs, item.absolutePath);
+                localMovedAside = false;
+            }
+            catch (rollbackErr) {
+                run.emit({
+                    type: "error",
+                    path: item.relativePath,
+                    message: "conflict keep rollback failed: " + describeError(rollbackErr),
+                });
+            }
+        }
         if (mirrorErr instanceof VaultAuthError)
             throw mirrorErr;
+        if (mirrorErr instanceof JournalCheckpointError)
+            throw mirrorErr;
         if (mirrorErr instanceof WindowsSymlinkPrivilegeError) {
             // The remote symlink record cannot be materialized to a conflict mirror
             // on this unprivileged Windows host. Emit the deliberate skip (never