@indigoai-us/hq-cloud 6.18.22-alpha.732d → 6.18.23

package/dist/cli/sync.js

@@ -30,6 +30,7 @@ import { buildScopeShrinkPlan, applyScopeShrink, ScopeShrinkBlockedError, ScopeS
 import { coalescePrefixes, compileScopeMatcher, intersectPrefixSets, pathToScopePrefix, toScopePrefixEntries, } from "../prefix-coalesce.js";
 import { SESSION_LOGS_PUSH_ONLY_PREFIX } from "../sync/pull-scope.js";
 import { contentHashMatchesRawSha256 } from "../sync/content-hash.js";
+import { isKms10CopyOfJournalBase } from "../kms10-etag-safe-pull.js";
 import { isTargetedUpsertExactListEnabled } from "../sync/targeted-upsert-exact-list.js";
 import { coalesceDenseTargetedPullPaths } from "../sync/targeted-pull-prefixes.js";
 import { listRemoteForScope, POST_FILTER_THRESHOLD } from "../remote-pull.js";
@@ -1109,6 +1110,10 @@ async function executeConflictExecutor(run, plan, scopeRun, counters) {
             executeContentMatchSkip(run, item, counters);
             continue;
         }
+        if (item.action === "skip-kms10-copy") {
+            executeKms10CopySkip(run, item, counters);
+            continue;
+        }
         if (item.action === "skip-unreadable-link") {
             // An unreadable local link must stay non-fatal: the runner treats a
             // generic error event as a failed company leg. Surface the exact remote
@@ -1227,6 +1232,47 @@ function executeContentMatchSkip(run, item, counters) {
     run.journalChangesSinceCheckpoint++;
     counters.filesSkipped++;
 }
+/**
+ * Size prefilter for KMS-10 copy proof. A symlink's journal row records size 0
+ * while LIST reports the byte length of its encoded `hq-symlink:<target>` body,
+ * so the sizes never compare; the HEAD proof (original ETag, since link uploads
+ * carry no content hash) still has to match before the copy is accepted.
+ */
+function kms10ListedSizeMatchesJournal(remoteFile, entry) {
+    return entry.kind === "symlink" || remoteFile.size === entry.size;
+}
+function executeKms10CopySkip(run, item, counters) {
+    const key = item.remoteFile.key;
+    if (!isDownloadWritePathStillContained(run.companyRoot, key, item.localPath)) {
+        throw new Error(`KMS-10 copy skip escaped the sync root for ${key}`);
+    }
+    if (!matchesLocalSnapshot(item.localPath, item.localSnapshot)) {
+        counters.filesSkipped++;
+        counters.hasRetryableOutcome = true;
+        run.emit({
+            type: "error",
+            diagnostic: true,
+            path: key,
+            message: "KMS-10 copy skip deferred because the local file changed after planning",
+        });
+        return;
+    }
+    const entry = journalRows(run.journal).get(key);
+    const remoteEtag = normalizeEtag(item.remoteFile.etag);
+    if (!entry ||
+        entry.hash !== item.journalBaseHash ||
+        !kms10ListedSizeMatchesJournal(item.remoteFile, entry) ||
+        remoteEtag === "" ||
+        remoteEtag === entry.remoteEtag) {
+        counters.filesSkipped++;
+        return;
+    }
+    // HEAD proved the remote hash matches the journal baseline. Preserve local
+    // bytes and record only the copied remote revision.
+    journalRows(run.journal).set(key, { ...entry, remoteEtag });
+    run.journalChangesSinceCheckpoint++;
+    counters.filesSkipped++;
+}
 async function executeConflictItem(run, plan, scopeRun, counters, downloadItems, item) {
     const { remoteFile, localPath } = item;
     // Cloud-authoritative paths (server-regenerated: company-brief.md, board.json,
@@ -2705,6 +2751,7 @@ propagateDeletePolicy = "owned-only", onHeartbeat, journalRowCount = journalRows
             if (item.action === "download" ||
                 item.action === "conflict" ||
                 item.action === "skip-content-match" ||
+                item.action === "skip-kms10-copy" ||
                 item.action === "tombstone-delete" ||
                 item.action === "skip-junk-key-spelling" ||
                 item.action === "skip-unreadable-link") {
@@ -2820,679 +2867,752 @@ propagateDeletePolicy = "owned-only", onHeartbeat, journalRowCount = journalRows
     // promise/microtask work per object even though no I/O is being awaited.
     const cooperativeWork = { rowsSinceYield: 0 };
     let plannedRows = 0;
-    for (const remoteFile of listedFiles) {
-        onHeartbeat?.();
-        noteCooperativeRowVisit("plan", remoteFile.key);
-        plannedRows++;
-        if (cooperativeCheckpoint &&
-            plannedRows % cooperativeUnitSize() === 0) {
-            dropJournalDecodeWindow();
-            if (await yieldToCooperativeCheckpoint(cooperativeWork, cooperativeCheckpoint, true, plannedRows)) {
-                onCooperativeHandoff?.();
-            }
-        }
-        else if (plannedRows % decodeWindowSize() === 0) {
-            dropJournalDecodeWindow();
-        }
-        const posixRemoteKey = toPosixKey(remoteFile.key);
-        // S3 object keys are POSIX. Match the old delete-sweep membership check:
-        // a legacy backslash journal entry counts as present only when its POSIX
-        // form appears in the LIST, while a malformed backslash remote key does
-        // not accidentally change that behavior.
-        if (remoteFile.key === posixRemoteKey) {
-            unseenJournalKeys.delete(remoteFile.key);
-            for (const legacyKey of legacyJournalKeysByPosix.get(remoteFile.key) ?? []) {
-                unseenJournalKeys.delete(legacyKey);
-            }
-        }
-        if (remoteFile.key.startsWith(SKILLS_KEY_PREFIX)) {
-            // A remote junk spelling means its canonical journal twin is still
-            // remotely present. Keep that twin out of the delete sweep unless an
-            // exact FILE_TOMBSTONE is authoritative, precisely matching the old
-            // remoteCanonicalSkillKeys protection without retaining remote keys.
-            const canonical = canonicalVaultKeySpelling(remoteFile.key);
-            for (const journaledKey of journaledSkillKeysByCanonical.get(canonical) ?? []) {
-                if (fileTombstones.get(toPosixKey(journaledKey)) === undefined) {
-                    unseenJournalKeys.delete(journaledKey);
+    const listedIterator = listedFiles[Symbol.iterator]();
+    const pullHeadBatchSize = 16;
+    while (true) {
+        const remoteBatch = [];
+        while (remoteBatch.length < pullHeadBatchSize) {
+            const next = listedIterator.next();
+            if (next.done)
+                break;
+            remoteBatch.push(next.value);
+        }
+        if (remoteBatch.length === 0)
+            break;
+        // KMS-10 copies change ETags without changing the journal content hash.
+        // Probe bounded batches so large vaults never queue an unbounded HEAD set.
+        const prefetchedHeads = new Map();
+        const headCandidates = ctx === undefined
+            ? []
+            : remoteBatch.filter((remoteFile) => {
+                const entry = getEntry(journal, remoteFile.key);
+                return entry !== undefined &&
+                    hasRemoteChanged(remoteFile, entry) &&
+                    kms10ListedSizeMatchesJournal(remoteFile, entry) &&
+                    normalizeEtag(remoteFile.etag) !== "" &&
+                    normalizeEtag(remoteFile.etag) !== entry.remoteEtag;
+            });
+        if (headCandidates.length > 0 && ctx !== undefined) {
+            await Promise.all(headCandidates.map(async (remoteFile) => {
+                try {
+                    prefetchedHeads.set(remoteFile.key, {
+                        head: await headRemoteFile(ctx, remoteFile.key),
+                    });
+                }
+                catch (error) {
+                    prefetchedHeads.set(remoteFile.key, { head: null, error });
+                }
+            }));
+        }
+        for (const remoteFile of remoteBatch) {
+            onHeartbeat?.();
+            noteCooperativeRowVisit("plan", remoteFile.key);
+            plannedRows++;
+            if (cooperativeCheckpoint &&
+                plannedRows % cooperativeUnitSize() === 0) {
+                dropJournalDecodeWindow();
+                if (await yieldToCooperativeCheckpoint(cooperativeWork, cooperativeCheckpoint, true, plannedRows)) {
+                    onCooperativeHandoff?.();
                 }
             }
-        }
-        const invalidKey = classifyVaultKey(remoteFile.key, personalMode ? "personal" : "company");
-        if (invalidKey !== null) {
-            invalidRemoteKeys.push({
-                path: remoteFile.key,
-                errorCode: invalidKey.code,
-            });
-            items.push({
-                action: "skip-excluded-policy",
-                remoteFile,
-                localPath: companyRoot,
-            });
-            continue;
-        }
-        const localPath = resolveContainedVaultPath(companyRoot, remoteFile.key);
-        if (localPath === null) {
-            items.push({ action: "skip-excluded-policy", remoteFile, localPath: companyRoot });
-            continue;
-        }
-        // This is intentionally exact-prefix and storage-class-specific. Other
-        // archived objects retain their established sync behavior until a separate
-        // policy explicitly defines it. LIST retains the object in remoteKeys, so
-        // an existing journal row is neither tombstoned nor deleted.
-        if (remoteFile.key.startsWith("workspace/.session-logs/") &&
-            remoteFile.storageClass === "DEEP_ARCHIVE") {
-            items.push({ action: "skip-archived-session-log", remoteFile, localPath });
-            continue;
-        }
-        // Ephemeral-mirror filter — symmetric with the push-side walker. Bug #2
-        // in the 5.33.0 deep-test: the push side has refused to upload conflict
-        // mirrors since 5.33.0, but the pull side downloaded them freely from
-        // staging, so legacy `.conflict-*` litter rode every sync into clean
-        // trees. Refuse them here; the V2 verification test (direct S3 inject
-        // bypassing the push filter entirely) is the regression contract.
-        if (isEphemeralPath(remoteFile.key)) {
-            items.push({ action: "skip-excluded-policy", remoteFile, localPath });
-            continue;
-        }
-        // Personal-vault policy must be symmetric across both transfer legs.
-        // The push walker refuses derived/machine-local/sensitive paths, but old
-        // objects can remain in the bucket from clients that predate an exclusion.
-        // Refuse those objects here too so a pull cannot rematerialize them (or,
-        // for generated skill wrappers, fight reindex over a directory link).
-        if (personalMode &&
-            isPersonalVaultExcluded(remoteFile.key) &&
-            !(allowRootMcpConfig && remoteFile.key === ".mcp.json")) {
-            items.push({ action: "skip-excluded-policy", remoteFile, localPath });
-            continue;
-        }
-        if (personalMode &&
-            remoteFile.key.startsWith("companies/") &&
-            // EXEMPTION: companies/manifest.yaml is the routing source-of-truth
-            // carved INTO the personal vault on the push side
-            // (computePersonalVaultPaths). It must round-trip on the pull leg too —
-            // skipping it here leaves it forever unjournaled, which re-fires a
-            // transient push-side conflict every sync (no journal baseline). Let it
-            // fall through to download + journal like any personal file.
-            remoteFile.key !== PERSONAL_VAULT_MANIFEST_KEY) {
-            // Local (non-cloud) companies sync to the personal vault: keys under
-            // `companies/{slug}/...` are legitimate content a peer machine pushed
-            // for a company that is not cloud-backed. Allow them through EXCEPT
-            // for slugs the operator has an active team-bucket Membership for:
-            // those are orphan remnants from before the company became cloud-true,
-            // and downloading them would clash with the team-bucket pull at the
-            // same disk path.
-            //
-            // Symmetric to the push-side `decommissionPrefixes` logic in
-            // share.ts — both target the same orphan class, both honor the
-            // same `teamSyncedSlugs` set derived from the operator's live
-            // membership at runtime.
-            const slug = remoteFile.key.split("/")[1] ?? "";
-            const isTeamSyncedOrphan = teamSyncedSlugs !== null && slug !== "" && teamSyncedSlugs.has(slug);
-            if (isTeamSyncedOrphan) {
-                items.push({ action: "skip-personal-mode", remoteFile, localPath });
-                continue;
+            else if (plannedRows % decodeWindowSize() === 0) {
+                dropJournalDecodeWindow();
+            }
+            const posixRemoteKey = toPosixKey(remoteFile.key);
+            // S3 object keys are POSIX. Match the old delete-sweep membership check:
+            // a legacy backslash journal entry counts as present only when its POSIX
+            // form appears in the LIST, while a malformed backslash remote key does
+            // not accidentally change that behavior.
+            if (remoteFile.key === posixRemoteKey) {
+                unseenJournalKeys.delete(remoteFile.key);
+                for (const legacyKey of legacyJournalKeysByPosix.get(remoteFile.key) ?? []) {
+                    unseenJournalKeys.delete(legacyKey);
+                }
             }
-        }
-        // Scope filter (US-005). Keys outside the effective `syncMode` prefix set
-        // are not downloaded. `prefixSet` is `[""]` in `all` mode, which
-        // `isCoveredByAny` treats as covering everything — so this is a no-op for
-        // `all` and preserves the legacy full-bucket pull bit-for-bit. The
-        // previously-downloaded counterparts of these keys (if scope just shrank)
-        // are pruned separately by the scope-shrink pass in `sync()`.
-        // A key can fail the inclusion check AND sit under a push-only exclude
-        // prefix. Attribute it to `push-only` in that case: widening the
-        // membership to `all` would move it into `prefixSet` but the exclusion
-        // below would still withhold it, so it is NOT part of the shared-vs-all
-        // gap and must not be advertised as fixable by raising the access level.
-        if (!prefixMatcher.coversPath(remoteFile.key)) {
-            items.push({
-                action: "skip-out-of-scope",
-                remoteFile,
-                localPath,
-                reason: excludeMatcher.coversPath(remoteFile.key)
-                    ? "push-only"
-                    : "membership-scope",
-            });
-            continue;
-        }
-        // Push-only exclusion filter (US-006). A key that PASSED the inclusion check
-        // above is STILL not downloaded if it falls under a push-only exclude prefix
-        // (`sessions/`). This is what makes sessions push-only in EVERY mode — it
-        // subtracts from `all` (whose `prefixSet` is `[""]`, covering everything)
-        // and from an owner's role-wide scope alike. Empty `excludePrefixes` (the
-        // default) makes this a no-op. Deliberately AFTER inclusion and reported on
-        // the same `filesOutOfScope` axis. The matching local file (if a session was
-        // previously pulled, authored locally, or pinned+materialized) is NOT pruned
-        // here or by scope-shrink — see `planScopeShrink`, which never sees this set.
-        if (excludeMatcher.coversPath(remoteFile.key)) {
-            items.push({
-                action: "skip-out-of-scope",
-                remoteFile,
-                localPath,
-                reason: "push-only",
-            });
-            continue;
-        }
-        // LIST gives us no kind signal for the remote object — we don't
-        // know whether this key is a regular file or a symlink record
-        // until we either HEAD it (expensive — N extra calls per pull) or
-        // download it. So probe the ignore filter with BOTH isDir hints
-        // and include the entry if either probe passes. Without this,
-        // a symlink record at a dir-only-allowlisted path (e.g. an
-        // .hqinclude of `companies/*/knowledge/`) would be classified
-        // skip-ignored and the symlinks freshly uploaded by the
-        // push-side fix would never propagate. Mirrors the dual-hint
-        // probe in walkDir/collectFiles. Pure path lookup, no I/O.
-        if (!shouldSync(localPath, false) && !shouldSync(localPath, true)) {
-            items.push({ action: "skip-ignored", remoteFile, localPath });
-            continue;
-        }
-        const journalEntry = getEntry(journal, remoteFile.key);
-        // Reindex and package wiring own symlinks under these `core/<type>`
-        // surfaces; their canonical sources are elsewhere. A prior pull records
-        // the remote object as a symlink, then reindex removes the generated link.
-        // Without this classification the next pull sees only an absent local path
-        // and downloads the same marker forever. Retain regular core files: the
-        // journal kind is the discriminator, because LIST exposes no object type.
-        // An unchanged ETag is also required: a remote writer can replace a legacy
-        // symlink with canonical file content at the same key, and that replacement
-        // must still be pulled.
-        if (personalMode &&
-            journalEntry?.kind === "symlink" &&
-            isGeneratedCoreMirrorKey(remoteFile.key) &&
-            journalEntry.remoteEtag !== undefined &&
-            !hasRemoteChanged(remoteFile, journalEntry)) {
-            items.push({ action: "skip-excluded-policy", remoteFile, localPath });
-            continue;
-        }
-        // Junk-spelling guard — SKILL-FARM KEYS ONLY. The amplifier is specific
-        // to `.claude/skills/<ns>:<skill>` wrapper spellings; outside that prefix,
-        // keys whose percent-decode fixpoints collide (`notes/a b.md` vs a genuine
-        // `notes/a%20b.md`) are DISTINCT files that must both pull.
-        // Within the farm: a remote key that is NOT journaled under its own
-        // spelling but whose percent-decode fixpoint matches an already-journaled
-        // key with a different spelling is a mixed-version twin (`%3A`/`%253A`
-        // generations of a canonical `:` key). Materializing it would mint junk
-        // local dirs and fork the journal into a second key family for the same
-        // logical path — skip it (loudly, never fatally; see the
-        // `skip-junk-key-spelling` event doc) and leave the journaled spelling
-        // authoritative for this machine.
-        if (journalEntry === undefined &&
-            remoteFile.key.startsWith(SKILLS_KEY_PREFIX) &&
-            // Gate NON-canonical remote spellings only. A remote key that already
-            // IS the canonical spelling must always be downloadable — after the
-            // doctor collapses the vault, a machine whose journal still holds only
-            // the junk spelling would otherwise skip the canonical object forever
-            // (and the delete-resync twin protection keeps that stale junk entry),
-            // deadlocking it out of every future update.
-            canonicalVaultKeySpelling(remoteFile.key) !== remoteFile.key) {
-            const journaledTwin = journaledKeyByCanonical.get(canonicalVaultKeySpelling(remoteFile.key));
-            if (journaledTwin !== undefined && journaledTwin !== remoteFile.key) {
+            if (remoteFile.key.startsWith(SKILLS_KEY_PREFIX)) {
+                // A remote junk spelling means its canonical journal twin is still
+                // remotely present. Keep that twin out of the delete sweep unless an
+                // exact FILE_TOMBSTONE is authoritative, precisely matching the old
+                // remoteCanonicalSkillKeys protection without retaining remote keys.
+                const canonical = canonicalVaultKeySpelling(remoteFile.key);
+                for (const journaledKey of journaledSkillKeysByCanonical.get(canonical) ?? []) {
+                    if (fileTombstones.get(toPosixKey(journaledKey)) === undefined) {
+                        unseenJournalKeys.delete(journaledKey);
+                    }
+                }
+            }
+            const invalidKey = classifyVaultKey(remoteFile.key, personalMode ? "personal" : "company");
+            if (invalidKey !== null) {
+                invalidRemoteKeys.push({
+                    path: remoteFile.key,
+                    errorCode: invalidKey.code,
+                });
                 items.push({
-                    action: "skip-junk-key-spelling",
+                    action: "skip-excluded-policy",
                     remoteFile,
-                    localPath,
-                    journaledKey: journaledTwin,
+                    localPath: companyRoot,
                 });
                 continue;
             }
-        }
-        // ── FILE_TOMBSTONE consult (delete-resync) ───────────────────────────────
-        // A remote object present in the LIST may be an intentionally-deleted key
-        // (a peer re-pushed it, or its delete-marker hasn't propagated to this
-        // caller's view). `tombstoneSuppresses` is true when a FILE_TOMBSTONE marks
-        // this key deleted AND the remote object is NOT a newer re-create — i.e. the
-        // object is the stale/deleted version and must NOT be downloaded. A genuine
-        // re-create (object newer than the tombstone) leaves this false so the
-        // normal download/merge path runs (the tombstone is not permanent
-        // suppression). An empty tombstone map (the default / degraded-fetch case)
-        // makes this always false — legacy behavior preserved bit-for-bit.
-        const tombstone = fileTombstones.get(toPosixKey(remoteFile.key));
-        const tombstoneSuppresses = tombstone !== undefined &&
-            !isRemoteRecreateAfterTombstone(remoteFile, tombstone);
-        // LOCAL journal tombstone — this machine's own intentional-delete record,
-        // independent of the (best-effort, intermittently-degraded) server
-        // FILE_TOMBSTONE fetch above. When a clean local delete is classified, the
-        // push leg stamps `removedAt` on the journal entry; honoring it here makes
-        // the delete-vs-drift-restore outcome DETERMINISTIC, closing the
-        // intermittent respawn where a degraded tombstone fetch let the pull leg
-        // re-materialize an intentionally-deleted file. Reuses the same re-create
-        // guard (a remote object newer than the local delete is a genuine re-create
-        // and still downloads). Consulted ONLY on the `!localExists` re-download
-        // path below — never to delete a file that is present locally.
-        const localTombstoneSuppresses = journalEntry !== undefined &&
-            isTombstone(journalEntry) &&
-            hasCurrentLocalDeleteIntent(journalEntry) &&
-            journalEntry.removedAt !== undefined &&
-            !isRemoteRecreateAfterTombstone(remoteFile, {
-                deletedAt: journalEntry.removedAt,
-            });
-        // Only a key that passed validation, policy, scope and ignore filtering
-        // and is not itself a deleted object can own a local file, so only such a
-        // key may protect a case-only twin from deletion (feedback_c8ed69d1). A
-        // local file whose folder merely keeps an older case spelling is not
-        // protected: when no live key owns it, the remote delete still applies.
-        if (!tombstoneSuppresses && !localTombstoneSuppresses) {
-            caseAliasTracker?.observeRemote(remoteFile.key);
-        }
-        // lstat (not existsSync/statSync) handles three cases the legacy
-        // checks got wrong for symlinks:
-        //   1. A valid symlink at localPath: existsSync returns true and the
-        //      planner falls through to hashFile, which follows the link and
-        //      hashes the target file's bytes — never matching the journal's
-        //      sha256(target string), so every pull would mis-classify a
-        //      pristine symlink as locally changed.
-        //   2. A dangling symlink: existsSync returns false (existsSync
-        //      follows links) so the planner treats the entry as missing and
-        //      re-downloads, silently clobbering the user's intentional
-        //      dangling link on every run.
-        //   3. A regular file: indistinguishable from current behaviour.
-        let localLstat = null;
-        let plannedLocalSnapshot = { kind: "absent" };
-        let localPathBlockedByFileAncestor = false;
-        try {
-            localLstat = fs.lstatSync(localPath);
-        }
-        catch (err) {
-            const code = err && typeof err === "object" && "code" in err
-                ? err.code
-                : undefined;
-            // ENOENT  → truly absent → treated as "new file from cloud".
-            // ENOTDIR → an ancestor of localPath is a regular file (cloud has a
-            //           dir at that key, local has a file). Pre-fix this threw
-            //           and aborted the whole company sync (Bug #10 in the
-            //           5.33.0 deep-test verification — \`v4-dir-vs-file\` repro
-            //           wedged the personal company at \"errored\" status,
-            //           skipping every later file). Recover by classifying as
-            //           a structural collision the operator must resolve
-            //           manually, and let the rest of the company process.
-            if (code !== "ENOENT" && code !== "ENOTDIR") {
-                throw err;
-            }
-            if (code === "ENOTDIR") {
-                localPathBlockedByFileAncestor = true;
-            }
-        }
-        const localExists = localLstat !== null;
-        if (localPathBlockedByFileAncestor) {
-            // Symmetric counterpart to the (local-dir, cloud-file) warning below.
-            // Emit the same "manual reconciliation required" surface so the
-            // operator sees one consistent message for both topologies; record as
-            // skip-local-only so the file is not silently dropped from the
-            // count and the executor never tries to lstat/write it.
-            console.error(`  Warning: an ancestor of ${remoteFile.key} exists locally as a regular file; ` +
-                `cloud has a deeper key under that path. Skipping; manual ` +
-                `reconciliation required (rm the conflicting local file to pull).`);
-            items.push({ action: "skip-local-only", remoteFile, localPath });
-            continue;
-        }
-        if (localExists) {
-            const isLocalSymlink = localLstat.isSymbolicLink();
-            // Kind-mismatch guard: a remote LIST entry is always a single
-            // S3 object (regular file or symlink record), but the local
-            // path may be a real directory if the user previously had a
-            // dir at this key. Hashing a directory throws EISDIR and
-            // aborts the whole pull. We don't auto-replace because that
-            // would `rm -rf` the user's directory; surface as a non-fatal
-            // skip and warn so the operator can reconcile manually
-            // (delete the local dir, or restructure the remote).
-            if (localLstat.isDirectory() && !isLocalSymlink) {
-                // Stale personal-overlay marker vs. release-shipped core directory:
-                // a single vault object at a `core/<overlay-type>/.../<entry>` key
-                // whose local counterpart is a real directory is an orphaned overlay
-                // symlink marker (reindex mirror artifact) left behind after a release
-                // shipped a real core dir of the same name. The local release-shipped
-                // directory is authoritative and the marker can never be materialized
-                // over it, so keep local and ignore the marker QUIETLY — the generic
-                // "rm -rf the local directory" advice below is actively dangerous here
-                // (it would destroy release-shipped core content to pull inert derived
-                // state), and it recurred on every sync. feedback_ce9aeede.
-                if (isGeneratedCoreMirrorKey(remoteFile.key)) {
-                    console.error(`  Note: ${remoteFile.key} is a stale personal-overlay marker ` +
-                        `shadowing a release-shipped core directory; keeping the local ` +
-                        `directory and ignoring the marker (no action needed).`);
-                    items.push({
-                        action: "skip-stale-overlay-marker",
-                        remoteFile,
-                        localPath,
-                    });
-                    continue;
-                }
-                // Directory-overlay marker vs. a locally-materialized directory:
-                // the remote object at this key carries CHILD objects under it in the
-                // same LIST (`remoteKeysWithChildren`), so it is a symlink/overlay
-                // record for a directory — e.g. the DPP vault's `skills/cody-copywriter`
-                // overlay whose 13 child objects are already materialized locally. The
-                // marker can never be renamed over the real directory, and its children
-                // carry the actual content and materialize via their own plan items, so
-                // the marker is a benign, no-action skip. The generic "rm -rf the local
-                // directory to pull" advice below would tell the operator to DELETE the
-                // materialized (and possibly locally-authored) contents to install an
-                // inert link, and it recurred on EVERY sync cycle. feedback_d2082110.
-                if (remoteKeysWithChildren.has(toPosixKey(remoteFile.key))) {
-                    console.error(`  Note: ${remoteFile.key} is a directory-overlay marker whose ` +
-                        `contents already exist locally as a directory; keeping the ` +
-                        `local directory and ignoring the marker (no action needed).`);
-                    items.push({
-                        action: "skip-overlay-marker-with-children",
-                        remoteFile,
-                        localPath,
-                    });
-                    continue;
-                }
-                console.error(`  Warning: ${remoteFile.key} exists locally as a directory; ` +
-                    `cloud has a single object at this key. Skipping; manual ` +
-                    `reconciliation required (rm -rf the local directory to pull).`);
-                items.push({ action: "skip-local-only", remoteFile, localPath });
+            const localPath = resolveContainedVaultPath(companyRoot, remoteFile.key);
+            if (localPath === null) {
+                items.push({ action: "skip-excluded-policy", remoteFile, localPath: companyRoot });
                 continue;
             }
-            let localHash;
-            if (isLocalSymlink) {
-                const target = readlinkOrNull(localPath);
-                if (target === null) {
-                    // We cannot prove whether the local link diverged, so never
-                    // overwrite or tombstone it from this plan. A later pass can retry
-                    // once the OS exposes a readable target.
-                    items.push({ action: "skip-unreadable-link", remoteFile, localPath });
-                    continue;
-                }
-                localHash = hashSymlinkTarget(target);
-            }
-            else if (journalEntry && journalEntryMatchesStat(journalEntry, localLstat)) {
-                // size + mtime + ctime all match the row that recorded this hash, so
-                // the bytes have not been written since (ctime cannot be set from
-                // userspace — see `journalEntryMatchesStat`). Reading them would only
-                // reproduce the recorded hash. This is the pull half of the push
-                // planner's stat fast path; without it every local file with a remote
-                // counterpart was hashed on every pass — about 13 GB per runner start
-                // on a real install, a quarter of the first pass's CPU.
-                localHash = journalEntry.hash;
+            // This is intentionally exact-prefix and storage-class-specific. Other
+            // archived objects retain their established sync behavior until a separate
+            // policy explicitly defines it. LIST retains the object in remoteKeys, so
+            // an existing journal row is neither tombstoned nor deleted.
+            if (remoteFile.key.startsWith("workspace/.session-logs/") &&
+                remoteFile.storageClass === "DEEP_ARCHIVE") {
+                items.push({ action: "skip-archived-session-log", remoteFile, localPath });
+                continue;
             }
-            else {
-                // A same-size rewrite can preserve mtime, so mtime alone cannot prove
-                // content identity, and rows without stamps carry no evidence at all.
-                // Hash the file before deciding whether local state diverged from the
-                // journal baseline.
-                localHash = hashFile(localPath);
-            }
-            const localChanged = !!journalEntry && journalEntry.hash !== localHash;
-            plannedLocalSnapshot = {
-                kind: isLocalSymlink ? "symlink" : "file",
-                hash: localHash,
-            };
-            const remoteChanged = !!journalEntry && hasRemoteChanged(remoteFile, journalEntry);
-            const announcedContentHash = pullContentHashes[remoteFile.key];
-            // ── Authoritative delete reaches a machine that still holds the file ──
-            // A FILE_TOMBSTONE marks this key deleted and the remote object is not a
-            // newer re-create, but this machine still has a local copy. Honor the
-            // delete — EXCEPT never destroy unsynced local work: if the local copy
-            // diverges from the synced baseline (a post-tombstone edit, or an
-            // untracked local file with no journal entry), surface a CONFLICT instead
-            // of silently deleting (the safety guard the brief requires + the 3-way
-            // merge invariant). A local copy that still matches the deleted baseline
-            // is the stale version → delete it + drop the journal entry so it stays
-            // gone on this machine.
-            if (tombstoneSuppresses) {
-                if (localChanged || !journalEntry) {
-                    items.push({
-                        action: "conflict",
-                        remoteFile,
-                        localPath,
-                        localHash,
-                        localMtime: localLstat.mtime,
-                        localSize: isLocalSymlink ? 0 : localLstat.size,
-                        localSnapshot: plannedLocalSnapshot,
-                    });
-                }
-                else {
-                    items.push({
-                        action: "tombstone-delete",
-                        remoteFile,
-                        localPath,
-                        localSnapshot: plannedLocalSnapshot,
-                    });
-                }
+            // Ephemeral-mirror filter — symmetric with the push-side walker. Bug #2
+            // in the 5.33.0 deep-test: the push side has refused to upload conflict
+            // mirrors since 5.33.0, but the pull side downloaded them freely from
+            // staging, so legacy `.conflict-*` litter rode every sync into clean
+            // trees. Refuse them here; the V2 verification test (direct S3 inject
+            // bypassing the push filter entirely) is the regression contract.
+            if (isEphemeralPath(remoteFile.key)) {
+                items.push({ action: "skip-excluded-policy", remoteFile, localPath });
                 continue;
             }
-            // ── Untracked-local guard (unjournaled local file) ──────────────
-            // Both `localChanged` and `remoteChanged` are gated on `!!journalEntry`,
-            // so a key with NO journal entry reads "clean on both sides" and falls
-            // all the way through to a plain `download` — silently replacing a local
-            // file that exists on disk. There is no conflict, no `.conflict-` mirror
-            // and no conflict-index record, so the loss is invisible unless someone
-            // happens to know what the file should contain.
-            //
-            // This destroyed in-progress edits to
-            // `companies/*/projects/*/prd.json` three times on 2026-08-01/02, but
-            // nothing about it is prd- or project-specific: it fires for ANY synced
-            // path whose journal entry is absent. Absence is common — a file created
-            // on this machine and on a peer under the same key before either pushed,
-            // a journal shard reset/lost/rebuilt (`readJournal` returns an empty
-            // `files` map for a missing shard, so EVERY divergent local file is in
-            // scope), a run under a different `HQ_STATE_DIR`, or an entry dropped by
-            // scope-shrink or rescue.
-            //
-            // No journal entry means no evidence that local and remote ever agreed,
-            // which is exactly when an overwrite is least safe. Route it through the
-            // conflict path instead: the executor's convergence probe fetches the
-            // remote once and, when the bytes already match (the ordinary
-            // fresh-machine / rebuilt-journal case), reconciles silently — no
-            // conflict, no mirror, journal stamped. Only genuine divergence surfaces,
-            // and there local is PRESERVED as-is with the cloud copy written beside
-            // it under `--on-conflict keep`, or the run halts under `abort`.
-            // Cloud-authoritative paths (board.json, ontology/, signals/, …) are
-            // unaffected — the conflict executor short-circuits those back to a
-            // pull-wins download before any mirror is minted.
-            if (!journalEntry) {
-                items.push({
-                    action: "conflict",
-                    remoteFile,
-                    localPath,
-                    localHash,
-                    localMtime: localLstat.mtime,
-                    localSize: isLocalSymlink ? 0 : localLstat.size,
-                    localSnapshot: plannedLocalSnapshot,
-                });
+            // Personal-vault policy must be symmetric across both transfer legs.
+            // The push walker refuses derived/machine-local/sensitive paths, but old
+            // objects can remain in the bucket from clients that predate an exclusion.
+            // Refuse those objects here too so a pull cannot rematerialize them (or,
+            // for generated skill wrappers, fight reindex over a directory link).
+            if (personalMode &&
+                isPersonalVaultExcluded(remoteFile.key) &&
+                !(allowRootMcpConfig && remoteFile.key === ".mcp.json")) {
+                items.push({ action: "skip-excluded-policy", remoteFile, localPath });
                 continue;
             }
-            // An event hash and a LIST row are separate observations. Only use the
-            // event to skip a changed ETag after HEAD proves that the exact listed
-            // revision carries that hash; otherwise the event may be stale and the
-            // LIST may already describe newer bytes.
-            let listedRevisionMatchesAnnouncement = false;
-            if (ctx !== undefined &&
-                remoteChanged &&
-                !isLocalSymlink &&
-                !localChanged &&
-                announcedContentHash !== undefined &&
-                contentHashMatchesRawSha256(announcedContentHash, journalEntry.hash) &&
-                journalEntryMatchesStat(journalEntry, localLstat) &&
-                remoteFile.size === localLstat.size &&
-                normalizeEtag(remoteFile.etag) !== "" &&
-                normalizeEtag(remoteFile.etag) !== journalEntry.remoteEtag) {
-                try {
-                    const head = await headRemoteFile(ctx, remoteFile.key);
-                    const remoteContentHash = head?.metadata?.[FILE_CONTENT_SHA256_META_KEY];
-                    listedRevisionMatchesAnnouncement =
-                        head !== null &&
-                            normalizeEtag(head.etag) === normalizeEtag(remoteFile.etag) &&
-                            head.size === remoteFile.size &&
-                            remoteContentHash !== undefined &&
-                            contentHashMatchesRawSha256(announcedContentHash, remoteContentHash);
-                }
-                catch (headError) {
-                    // No proof means the ordinary GET path remains authoritative.
-                    console.error(`sync: unable to verify announced content hash for ${remoteFile.key}; falling back to GET`, headError);
+            if (personalMode &&
+                remoteFile.key.startsWith("companies/") &&
+                // EXEMPTION: companies/manifest.yaml is the routing source-of-truth
+                // carved INTO the personal vault on the push side
+                // (computePersonalVaultPaths). It must round-trip on the pull leg too —
+                // skipping it here leaves it forever unjournaled, which re-fires a
+                // transient push-side conflict every sync (no journal baseline). Let it
+                // fall through to download + journal like any personal file.
+                remoteFile.key !== PERSONAL_VAULT_MANIFEST_KEY) {
+                // Local (non-cloud) companies sync to the personal vault: keys under
+                // `companies/{slug}/...` are legitimate content a peer machine pushed
+                // for a company that is not cloud-backed. Allow them through EXCEPT
+                // for slugs the operator has an active team-bucket Membership for:
+                // those are orphan remnants from before the company became cloud-true,
+                // and downloading them would clash with the team-bucket pull at the
+                // same disk path.
+                //
+                // Symmetric to the push-side `decommissionPrefixes` logic in
+                // share.ts — both target the same orphan class, both honor the
+                // same `teamSyncedSlugs` set derived from the operator's live
+                // membership at runtime.
+                const slug = remoteFile.key.split("/")[1] ?? "";
+                const isTeamSyncedOrphan = teamSyncedSlugs !== null && slug !== "" && teamSyncedSlugs.has(slug);
+                if (isTeamSyncedOrphan) {
+                    items.push({ action: "skip-personal-mode", remoteFile, localPath });
+                    continue;
                 }
             }
-            if (listedRevisionMatchesAnnouncement) {
+            // Scope filter (US-005). Keys outside the effective `syncMode` prefix set
+            // are not downloaded. `prefixSet` is `[""]` in `all` mode, which
+            // `isCoveredByAny` treats as covering everything — so this is a no-op for
+            // `all` and preserves the legacy full-bucket pull bit-for-bit. The
+            // previously-downloaded counterparts of these keys (if scope just shrank)
+            // are pruned separately by the scope-shrink pass in `sync()`.
+            // A key can fail the inclusion check AND sit under a push-only exclude
+            // prefix. Attribute it to `push-only` in that case: widening the
+            // membership to `all` would move it into `prefixSet` but the exclusion
+            // below would still withhold it, so it is NOT part of the shared-vs-all
+            // gap and must not be advertised as fixable by raising the access level.
+            if (!prefixMatcher.coversPath(remoteFile.key)) {
                 items.push({
-                    action: "skip-content-match",
+                    action: "skip-out-of-scope",
                     remoteFile,
                     localPath,
-                    contentHash: announcedContentHash,
+                    reason: excludeMatcher.coversPath(remoteFile.key)
+                        ? "push-only"
+                        : "membership-scope",
                 });
                 continue;
             }
-            // Mirror the original 3-way merge from the inline loop. Tested by
-            // `does NOT flag a pull conflict when only local changed since last
-            // sync` and `detects conflicts with local changes…`.
-            if (localChanged && remoteChanged) {
+            // Push-only exclusion filter (US-006). A key that PASSED the inclusion check
+            // above is STILL not downloaded if it falls under a push-only exclude prefix
+            // (`sessions/`). This is what makes sessions push-only in EVERY mode — it
+            // subtracts from `all` (whose `prefixSet` is `[""]`, covering everything)
+            // and from an owner's role-wide scope alike. Empty `excludePrefixes` (the
+            // default) makes this a no-op. Deliberately AFTER inclusion and reported on
+            // the same `filesOutOfScope` axis. The matching local file (if a session was
+            // previously pulled, authored locally, or pinned+materialized) is NOT pruned
+            // here or by scope-shrink — see `planScopeShrink`, which never sees this set.
+            if (excludeMatcher.coversPath(remoteFile.key)) {
                 items.push({
-                    action: "conflict",
+                    action: "skip-out-of-scope",
                     remoteFile,
                     localPath,
-                    localHash,
-                    // localLstat is non-null inside this `if (localExists)`
-                    // branch — the planner already lstat'd the path. Carry
-                    // its mtime forward so the executor doesn't have to
-                    // re-stat (which would follow links and crash on a
-                    // dangling symlink). Same goes for size: the conflict
-                    // executor's keep/skip branch needs to stamp the
-                    // journal with a size, and statSync on a dangling
-                    // symlink throws ENOENT (silently swallowed pre-fix),
-                    // leaving the journal stale and re-firing the conflict
-                    // every sync.
-                    localMtime: localLstat.mtime,
-                    localSize: isLocalSymlink ? 0 : localLstat.size,
-                    localSnapshot: plannedLocalSnapshot,
+                    reason: "push-only",
                 });
                 continue;
             }
-            if (journalEntry && localChanged && !remoteChanged) {
-                items.push({ action: "skip-local-only", remoteFile, localPath });
+            // LIST gives us no kind signal for the remote object — we don't
+            // know whether this key is a regular file or a symlink record
+            // until we either HEAD it (expensive — N extra calls per pull) or
+            // download it. So probe the ignore filter with BOTH isDir hints
+            // and include the entry if either probe passes. Without this,
+            // a symlink record at a dir-only-allowlisted path (e.g. an
+            // .hqinclude of `companies/*/knowledge/`) would be classified
+            // skip-ignored and the symlinks freshly uploaded by the
+            // push-side fix would never propagate. Mirrors the dual-hint
+            // probe in walkDir/collectFiles. Pure path lookup, no I/O.
+            if (!shouldSync(localPath, false) && !shouldSync(localPath, true)) {
+                items.push({ action: "skip-ignored", remoteFile, localPath });
+                continue;
+            }
+            const journalEntry = getEntry(journal, remoteFile.key);
+            // Reindex and package wiring own symlinks under these `core/<type>`
+            // surfaces; their canonical sources are elsewhere. A prior pull records
+            // the remote object as a symlink, then reindex removes the generated link.
+            // Without this classification the next pull sees only an absent local path
+            // and downloads the same marker forever. Retain regular core files: the
+            // journal kind is the discriminator, because LIST exposes no object type.
+            // An unchanged ETag is also required: a remote writer can replace a legacy
+            // symlink with canonical file content at the same key, and that replacement
+            // must still be pulled.
+            if (personalMode &&
+                journalEntry?.kind === "symlink" &&
+                isGeneratedCoreMirrorKey(remoteFile.key) &&
+                journalEntry.remoteEtag !== undefined &&
+                !hasRemoteChanged(remoteFile, journalEntry)) {
+                items.push({ action: "skip-excluded-policy", remoteFile, localPath });
                 continue;
             }
-            if (journalEntry && !localChanged && !remoteChanged) {
-                // Flavor-health repair (win32 skill farm): a link journaled while its
-                // target was absent was minted file-flavor; once the target directory
-                // exists the hashes still match (hash = sha256(target)) so this
-                // branch would skip it forever, leaving the wrapper broken. Re-download
-                // instead — the materializer's flavor-aware path recreates it 'dir'.
-                if (isLocalSymlink &&
-                    remoteFile.key.startsWith(SKILLS_KEY_PREFIX) &&
-                    win32SymlinkFlavorBroken(localPath)) {
+            // Junk-spelling guard — SKILL-FARM KEYS ONLY. The amplifier is specific
+            // to `.claude/skills/<ns>:<skill>` wrapper spellings; outside that prefix,
+            // keys whose percent-decode fixpoints collide (`notes/a b.md` vs a genuine
+            // `notes/a%20b.md`) are DISTINCT files that must both pull.
+            // Within the farm: a remote key that is NOT journaled under its own
+            // spelling but whose percent-decode fixpoint matches an already-journaled
+            // key with a different spelling is a mixed-version twin (`%3A`/`%253A`
+            // generations of a canonical `:` key). Materializing it would mint junk
+            // local dirs and fork the journal into a second key family for the same
+            // logical path — skip it (loudly, never fatally; see the
+            // `skip-junk-key-spelling` event doc) and leave the journaled spelling
+            // authoritative for this machine.
+            if (journalEntry === undefined &&
+                remoteFile.key.startsWith(SKILLS_KEY_PREFIX) &&
+                // Gate NON-canonical remote spellings only. A remote key that already
+                // IS the canonical spelling must always be downloadable — after the
+                // doctor collapses the vault, a machine whose journal still holds only
+                // the junk spelling would otherwise skip the canonical object forever
+                // (and the delete-resync twin protection keeps that stale junk entry),
+                // deadlocking it out of every future update.
+                canonicalVaultKeySpelling(remoteFile.key) !== remoteFile.key) {
+                const journaledTwin = journaledKeyByCanonical.get(canonicalVaultKeySpelling(remoteFile.key));
+                if (journaledTwin !== undefined && journaledTwin !== remoteFile.key) {
                     items.push({
-                        action: "download",
+                        action: "skip-junk-key-spelling",
                         remoteFile,
                         localPath,
-                        isNew: false,
-                        localSnapshot: plannedLocalSnapshot,
+                        journaledKey: journaledTwin,
                     });
                     continue;
                 }
-                items.push({ action: "skip-unchanged", remoteFile, localPath });
+            }
+            // ── FILE_TOMBSTONE consult (delete-resync) ───────────────────────────────
+            // A remote object present in the LIST may be an intentionally-deleted key
+            // (a peer re-pushed it, or its delete-marker hasn't propagated to this
+            // caller's view). `tombstoneSuppresses` is true when a FILE_TOMBSTONE marks
+            // this key deleted AND the remote object is NOT a newer re-create — i.e. the
+            // object is the stale/deleted version and must NOT be downloaded. A genuine
+            // re-create (object newer than the tombstone) leaves this false so the
+            // normal download/merge path runs (the tombstone is not permanent
+            // suppression). An empty tombstone map (the default / degraded-fetch case)
+            // makes this always false — legacy behavior preserved bit-for-bit.
+            const tombstone = fileTombstones.get(toPosixKey(remoteFile.key));
+            const tombstoneSuppresses = tombstone !== undefined &&
+                !isRemoteRecreateAfterTombstone(remoteFile, tombstone);
+            // LOCAL journal tombstone — this machine's own intentional-delete record,
+            // independent of the (best-effort, intermittently-degraded) server
+            // FILE_TOMBSTONE fetch above. When a clean local delete is classified, the
+            // push leg stamps `removedAt` on the journal entry; honoring it here makes
+            // the delete-vs-drift-restore outcome DETERMINISTIC, closing the
+            // intermittent respawn where a degraded tombstone fetch let the pull leg
+            // re-materialize an intentionally-deleted file. Reuses the same re-create
+            // guard (a remote object newer than the local delete is a genuine re-create
+            // and still downloads). Consulted ONLY on the `!localExists` re-download
+            // path below — never to delete a file that is present locally.
+            const localTombstoneSuppresses = journalEntry !== undefined &&
+                isTombstone(journalEntry) &&
+                hasCurrentLocalDeleteIntent(journalEntry) &&
+                journalEntry.removedAt !== undefined &&
+                !isRemoteRecreateAfterTombstone(remoteFile, {
+                    deletedAt: journalEntry.removedAt,
+                });
+            // Only a key that passed validation, policy, scope and ignore filtering
+            // and is not itself a deleted object can own a local file, so only such a
+            // key may protect a case-only twin from deletion (feedback_c8ed69d1). A
+            // local file whose folder merely keeps an older case spelling is not
+            // protected: when no live key owns it, the remote delete still applies.
+            if (!tombstoneSuppresses && !localTombstoneSuppresses) {
+                caseAliasTracker?.observeRemote(remoteFile.key);
+            }
+            // lstat (not existsSync/statSync) handles three cases the legacy
+            // checks got wrong for symlinks:
+            //   1. A valid symlink at localPath: existsSync returns true and the
+            //      planner falls through to hashFile, which follows the link and
+            //      hashes the target file's bytes — never matching the journal's
+            //      sha256(target string), so every pull would mis-classify a
+            //      pristine symlink as locally changed.
+            //   2. A dangling symlink: existsSync returns false (existsSync
+            //      follows links) so the planner treats the entry as missing and
+            //      re-downloads, silently clobbering the user's intentional
+            //      dangling link on every run.
+            //   3. A regular file: indistinguishable from current behaviour.
+            let localLstat = null;
+            let plannedLocalSnapshot = { kind: "absent" };
+            let localPathBlockedByFileAncestor = false;
+            try {
+                localLstat = fs.lstatSync(localPath);
+            }
+            catch (err) {
+                const code = err && typeof err === "object" && "code" in err
+                    ? err.code
+                    : undefined;
+                // ENOENT  → truly absent → treated as "new file from cloud".
+                // ENOTDIR → an ancestor of localPath is a regular file (cloud has a
+                //           dir at that key, local has a file). Pre-fix this threw
+                //           and aborted the whole company sync (Bug #10 in the
+                //           5.33.0 deep-test verification — \`v4-dir-vs-file\` repro
+                //           wedged the personal company at \"errored\" status,
+                //           skipping every later file). Recover by classifying as
+                //           a structural collision the operator must resolve
+                //           manually, and let the rest of the company process.
+                if (code !== "ENOENT" && code !== "ENOTDIR") {
+                    throw err;
+                }
+                if (code === "ENOTDIR") {
+                    localPathBlockedByFileAncestor = true;
+                }
+            }
+            const localExists = localLstat !== null;
+            if (localPathBlockedByFileAncestor) {
+                // Symmetric counterpart to the (local-dir, cloud-file) warning below.
+                // Emit the same "manual reconciliation required" surface so the
+                // operator sees one consistent message for both topologies; record as
+                // skip-local-only so the file is not silently dropped from the
+                // count and the executor never tries to lstat/write it.
+                console.error(`  Warning: an ancestor of ${remoteFile.key} exists locally as a regular file; ` +
+                    `cloud has a deeper key under that path. Skipping; manual ` +
+                    `reconciliation required (rm the conflicting local file to pull).`);
+                items.push({ action: "skip-local-only", remoteFile, localPath });
                 continue;
             }
-            if (journalEntry && !localChanged && remoteChanged) {
-                // ── Anti-rollback guard (silent newer→older overwrite) ───────────
-                // Remote etag moved but local still matches the journal baseline, so
-                // the classic 3-way merge calls this a clean `download` and overwrites
-                // local with remote. That assumes the remote *advanced*. It can also
-                // REGRESS: a second device (or a stale re-push) can replace the S3
-                // object with an OLDER, SMALLER copy. `hasRemoteChanged` is pure-ETag
-                // and cannot tell an advance from a rollback — ListObjectsV2 carries no
-                // content hash, and `lastModified` is the upload time (newer even for
-                // stale content), so neither distinguishes the two. A silent download
-                // then DESTROYS newer local bytes with no conflict surfaced.
-                //
-                // This bit append-only bot chat logs on 2026-06-10, the day
-                // event-driven bidirectional sync (which lets a peer device push to
-                // S3 between this device's pulls) first rolled out: a regressed S3
-                // object truncated freshly-appended lines, undetected by the planner.
+            if (localExists) {
+                const isLocalSymlink = localLstat.isSymbolicLink();
+                // Kind-mismatch guard: a remote LIST entry is always a single
+                // S3 object (regular file or symlink record), but the local
+                // path may be a real directory if the user previously had a
+                // dir at this key. Hashing a directory throws EISDIR and
+                // aborts the whole pull. We don't auto-replace because that
+                // would `rm -rf` the user's directory; surface as a non-fatal
+                // skip and warn so the operator can reconcile manually
+                // (delete the local dir, or restructure the remote).
+                if (localLstat.isDirectory() && !isLocalSymlink) {
+                    // Stale personal-overlay marker vs. release-shipped core directory:
+                    // a single vault object at a `core/<overlay-type>/.../<entry>` key
+                    // whose local counterpart is a real directory is an orphaned overlay
+                    // symlink marker (reindex mirror artifact) left behind after a release
+                    // shipped a real core dir of the same name. The local release-shipped
+                    // directory is authoritative and the marker can never be materialized
+                    // over it, so keep local and ignore the marker QUIETLY — the generic
+                    // "rm -rf the local directory" advice below is actively dangerous here
+                    // (it would destroy release-shipped core content to pull inert derived
+                    // state), and it recurred on every sync. feedback_ce9aeede.
+                    if (isGeneratedCoreMirrorKey(remoteFile.key)) {
+                        console.error(`  Note: ${remoteFile.key} is a stale personal-overlay marker ` +
+                            `shadowing a release-shipped core directory; keeping the local ` +
+                            `directory and ignoring the marker (no action needed).`);
+                        items.push({
+                            action: "skip-stale-overlay-marker",
+                            remoteFile,
+                            localPath,
+                        });
+                        continue;
+                    }
+                    // Directory-overlay marker vs. a locally-materialized directory:
+                    // the remote object at this key carries CHILD objects under it in the
+                    // same LIST (`remoteKeysWithChildren`), so it is a symlink/overlay
+                    // record for a directory — e.g. the DPP vault's `skills/cody-copywriter`
+                    // overlay whose 13 child objects are already materialized locally. The
+                    // marker can never be renamed over the real directory, and its children
+                    // carry the actual content and materialize via their own plan items, so
+                    // the marker is a benign, no-action skip. The generic "rm -rf the local
+                    // directory to pull" advice below would tell the operator to DELETE the
+                    // materialized (and possibly locally-authored) contents to install an
+                    // inert link, and it recurred on EVERY sync cycle. feedback_d2082110.
+                    if (remoteKeysWithChildren.has(toPosixKey(remoteFile.key))) {
+                        console.error(`  Note: ${remoteFile.key} is a directory-overlay marker whose ` +
+                            `contents already exist locally as a directory; keeping the ` +
+                            `local directory and ignoring the marker (no action needed).`);
+                        items.push({
+                            action: "skip-overlay-marker-with-children",
+                            remoteFile,
+                            localPath,
+                        });
+                        continue;
+                    }
+                    console.error(`  Warning: ${remoteFile.key} exists locally as a directory; ` +
+                        `cloud has a single object at this key. Skipping; manual ` +
+                        `reconciliation required (rm -rf the local directory to pull).`);
+                    items.push({ action: "skip-local-only", remoteFile, localPath });
+                    continue;
+                }
+                let localHash;
+                if (isLocalSymlink) {
+                    const target = readlinkOrNull(localPath);
+                    if (target === null) {
+                        // We cannot prove whether the local link diverged, so never
+                        // overwrite or tombstone it from this plan. A later pass can retry
+                        // once the OS exposes a readable target.
+                        items.push({ action: "skip-unreadable-link", remoteFile, localPath });
+                        continue;
+                    }
+                    localHash = hashSymlinkTarget(target);
+                }
+                else if (journalEntry && journalEntryMatchesStat(journalEntry, localLstat)) {
+                    // size + mtime + ctime all match the row that recorded this hash, so
+                    // the bytes have not been written since (ctime cannot be set from
+                    // userspace — see `journalEntryMatchesStat`). Reading them would only
+                    // reproduce the recorded hash. This is the pull half of the push
+                    // planner's stat fast path; without it every local file with a remote
+                    // counterpart was hashed on every pass — about 13 GB per runner start
+                    // on a real install, a quarter of the first pass's CPU.
+                    localHash = journalEntry.hash;
+                }
+                else {
+                    // A same-size rewrite can preserve mtime, so mtime alone cannot prove
+                    // content identity, and rows without stamps carry no evidence at all.
+                    // Hash the file before deciding whether local state diverged from the
+                    // journal baseline.
+                    localHash = hashFile(localPath);
+                }
+                const localChanged = !!journalEntry && journalEntry.hash !== localHash;
+                plannedLocalSnapshot = {
+                    kind: isLocalSymlink ? "symlink" : "file",
+                    hash: localHash,
+                };
+                const remoteChanged = !!journalEntry && hasRemoteChanged(remoteFile, journalEntry);
+                const announcedContentHash = pullContentHashes[remoteFile.key];
+                // ── Authoritative delete reaches a machine that still holds the file ──
+                // A FILE_TOMBSTONE marks this key deleted and the remote object is not a
+                // newer re-create, but this machine still has a local copy. Honor the
+                // delete — EXCEPT never destroy unsynced local work: if the local copy
+                // diverges from the synced baseline (a post-tombstone edit, or an
+                // untracked local file with no journal entry), surface a CONFLICT instead
+                // of silently deleting (the safety guard the brief requires + the 3-way
+                // merge invariant). A local copy that still matches the deleted baseline
+                // is the stale version → delete it + drop the journal entry so it stays
+                // gone on this machine.
+                if (tombstoneSuppresses) {
+                    if (localChanged || !journalEntry) {
+                        items.push({
+                            action: "conflict",
+                            remoteFile,
+                            localPath,
+                            localHash,
+                            localMtime: localLstat.mtime,
+                            localSize: isLocalSymlink ? 0 : localLstat.size,
+                            localSnapshot: plannedLocalSnapshot,
+                        });
+                    }
+                    else {
+                        items.push({
+                            action: "tombstone-delete",
+                            remoteFile,
+                            localPath,
+                            localSnapshot: plannedLocalSnapshot,
+                        });
+                    }
+                    continue;
+                }
+                // ── Untracked-local guard (unjournaled local file) ──────────────
+                // Both `localChanged` and `remoteChanged` are gated on `!!journalEntry`,
+                // so a key with NO journal entry reads "clean on both sides" and falls
+                // all the way through to a plain `download` — silently replacing a local
+                // file that exists on disk. There is no conflict, no `.conflict-` mirror
+                // and no conflict-index record, so the loss is invisible unless someone
+                // happens to know what the file should contain.
                 //
-                // Guard: if the incoming remote object is strictly SMALLER than the
-                // local file we already hold (a size regression on a tracked regular
-                // file), do NOT silently clobber. Route through the conflict path —
-                // the executor's convergence probe fetches the remote once and, on
-                // genuine divergence, PRESERVES local as a `.conflict-*` mirror instead
-                // of overwriting it (and under `--on-conflict abort` halts loudly
-                // rather than losing data). A byte-identical remote can never be
-                // smaller, so this never manufactures a false conflict on a no-op
-                // re-upload. Symlinks are exempt: their on-disk size is not the target
-                // length, so the comparison is meaningless.
+                // This destroyed in-progress edits to
+                // `companies/*/projects/*/prd.json` three times on 2026-08-01/02, but
+                // nothing about it is prd- or project-specific: it fires for ANY synced
+                // path whose journal entry is absent. Absence is common — a file created
+                // on this machine and on a peer under the same key before either pushed,
+                // a journal shard reset/lost/rebuilt (`readJournal` returns an empty
+                // `files` map for a missing shard, so EVERY divergent local file is in
+                // scope), a run under a different `HQ_STATE_DIR`, or an entry dropped by
+                // scope-shrink or rescue.
                 //
-                // Direction gate: only guard copies this device AUTHORED (last synced
-                // UP). A consumer copy (last synced DOWN) has no local authorship to
-                // protect — the remote is authoritative, so a smaller remote is a
-                // legitimate update (e.g. the gardener rewriting a shorter brief), not a
-                // regression. Without this gate a consumer device floods `.conflict`
-                // mirrors and stalls on stale gardener output forever (the 786-file
-                // pile-up, 2026-06-22). `"up"` and any missing/unknown direction stay
-                // guarded exactly as before — the 2026-06-10 chat-log protection holds.
-                if (journalEntry.direction !== "down" &&
+                // No journal entry means no evidence that local and remote ever agreed,
+                // which is exactly when an overwrite is least safe. Route it through the
+                // conflict path instead: the executor's convergence probe fetches the
+                // remote once and, when the bytes already match (the ordinary
+                // fresh-machine / rebuilt-journal case), reconciles silently — no
+                // conflict, no mirror, journal stamped. Only genuine divergence surfaces,
+                // and there local is PRESERVED as-is with the cloud copy written beside
+                // it under `--on-conflict keep`, or the run halts under `abort`.
+                // Cloud-authoritative paths (board.json, ontology/, signals/, …) are
+                // unaffected — the conflict executor short-circuits those back to a
+                // pull-wins download before any mirror is minted.
+                if (!journalEntry) {
+                    items.push({
+                        action: "conflict",
+                        remoteFile,
+                        localPath,
+                        localHash,
+                        localMtime: localLstat.mtime,
+                        localSize: isLocalSymlink ? 0 : localLstat.size,
+                        localSnapshot: plannedLocalSnapshot,
+                    });
+                    continue;
+                }
+                // An event hash and a LIST row are separate observations. Only use the
+                // event to skip a changed ETag after HEAD proves that the exact listed
+                // revision carries that hash; otherwise the event may be stale and the
+                // LIST may already describe newer bytes.
+                let listedRevisionMatchesAnnouncement = false;
+                let kms10CopyMatchesJournalBase = false;
+                if (ctx !== undefined &&
+                    remoteChanged &&
                     !isLocalSymlink &&
-                    remoteFile.size < localLstat.size) {
+                    !localChanged &&
+                    announcedContentHash !== undefined &&
+                    contentHashMatchesRawSha256(announcedContentHash, journalEntry.hash) &&
+                    journalEntryMatchesStat(journalEntry, localLstat) &&
+                    remoteFile.size === localLstat.size &&
+                    normalizeEtag(remoteFile.etag) !== "" &&
+                    normalizeEtag(remoteFile.etag) !== journalEntry.remoteEtag) {
+                    try {
+                        const headResult = prefetchedHeads.get(remoteFile.key);
+                        if (headResult?.error !== undefined)
+                            throw headResult.error;
+                        const head = headResult
+                            ? headResult.head
+                            : await headRemoteFile(ctx, remoteFile.key);
+                        const remoteContentHash = head?.metadata?.[FILE_CONTENT_SHA256_META_KEY];
+                        listedRevisionMatchesAnnouncement =
+                            head !== null &&
+                                normalizeEtag(head.etag) === normalizeEtag(remoteFile.etag) &&
+                                head.size === remoteFile.size &&
+                                remoteContentHash !== undefined &&
+                                contentHashMatchesRawSha256(announcedContentHash, remoteContentHash);
+                    }
+                    catch (headError) {
+                        // No proof means the ordinary GET path remains authoritative.
+                        console.error(`sync: unable to verify announced content hash for ${remoteFile.key}; falling back to GET`, headError);
+                    }
+                }
+                const kmsHeadResult = prefetchedHeads.get(remoteFile.key);
+                if (kmsHeadResult !== undefined) {
+                    if (kmsHeadResult.error !== undefined) {
+                        console.error(`sync: unable to verify marked KMS-10 copy for ${remoteFile.key}; falling back to GET`, kmsHeadResult.error);
+                    }
+                    else {
+                        kms10CopyMatchesJournalBase = isKms10CopyOfJournalBase(remoteFile, kmsHeadResult.head, journalEntry.hash, journalEntry.remoteEtag ?? "", remoteFile.key);
+                    }
+                }
+                if (listedRevisionMatchesAnnouncement) {
+                    items.push({
+                        action: "skip-content-match",
+                        remoteFile,
+                        localPath,
+                        contentHash: announcedContentHash,
+                    });
+                    continue;
+                }
+                if (kms10CopyMatchesJournalBase) {
+                    if (localChanged || !journalEntryMatchesStat(journalEntry, localLstat)) {
+                        items.push({
+                            action: "skip-kms10-copy",
+                            remoteFile,
+                            localPath,
+                            localSnapshot: plannedLocalSnapshot,
+                            journalBaseHash: journalEntry.hash,
+                        });
+                    }
+                    else {
+                        items.push({
+                            action: "skip-content-match",
+                            remoteFile,
+                            localPath,
+                            contentHash: `sha256:${journalEntry.hash}`,
+                        });
+                    }
+                    continue;
+                }
+                // Mirror the original 3-way merge from the inline loop. Tested by
+                // `does NOT flag a pull conflict when only local changed since last
+                // sync` and `detects conflicts with local changes…`.
+                if (localChanged && remoteChanged) {
                     items.push({
                         action: "conflict",
                         remoteFile,
                         localPath,
                         localHash,
+                        // localLstat is non-null inside this `if (localExists)`
+                        // branch — the planner already lstat'd the path. Carry
+                        // its mtime forward so the executor doesn't have to
+                        // re-stat (which would follow links and crash on a
+                        // dangling symlink). Same goes for size: the conflict
+                        // executor's keep/skip branch needs to stamp the
+                        // journal with a size, and statSync on a dangling
+                        // symlink throws ENOENT (silently swallowed pre-fix),
+                        // leaving the journal stale and re-firing the conflict
+                        // every sync.
                         localMtime: localLstat.mtime,
-                        localSize: localLstat.size,
+                        localSize: isLocalSymlink ? 0 : localLstat.size,
                         localSnapshot: plannedLocalSnapshot,
                     });
                     continue;
                 }
-                // Remote genuinely advanced (same-or-larger) → normal catch-up
-                // download below.
-            }
-            // No journal entry, or remote-only changed (non-shrinking) → fall
-            // through to download.
-        }
-        // Suppress the re-download of an intentionally-deleted key (delete-resync).
-        // Reaches here only for the `!localExists` case — the `localExists` branch
-        // above already handled (and `continue`d) any suppressing tombstone, so a
-        // tombstone that survives to here means "remote present, local absent, not a
-        // re-create": the classic resurrection ("remote present → I'm behind →
-        // download") the planner must NOT do. Route to `tombstone-delete` so the
-        // executor drops any stale journal entry and the key stays gone, instead of
-        // pulling the deleted object back in. `localTombstoneSuppresses` adds the
-        // same protection driven by this machine's own journal tombstone, so an
-        // intentional delete is not resurrected even when the server FILE_TOMBSTONE
-        // fetch is degraded.
-        if (tombstoneSuppresses || localTombstoneSuppresses) {
-            // A persisting `local-delete` tombstone (stamped by the intentional-delete
-            // producer below) must KEEP its journal entry — the push leg still needs
-            // it to propagate the S3 delete. Skip the re-download without dropping the
-            // entry. Other tombstone kinds (scope-shrink / FILE_TOMBSTONE) drop it.
-            if (journalEntry?.removedReason === "local-delete") {
+                if (journalEntry && localChanged && !remoteChanged) {
+                    items.push({ action: "skip-local-only", remoteFile, localPath });
+                    continue;
+                }
+                if (journalEntry && !localChanged && !remoteChanged) {
+                    // Flavor-health repair (win32 skill farm): a link journaled while its
+                    // target was absent was minted file-flavor; once the target directory
+                    // exists the hashes still match (hash = sha256(target)) so this
+                    // branch would skip it forever, leaving the wrapper broken. Re-download
+                    // instead — the materializer's flavor-aware path recreates it 'dir'.
+                    if (isLocalSymlink &&
+                        remoteFile.key.startsWith(SKILLS_KEY_PREFIX) &&
+                        win32SymlinkFlavorBroken(localPath)) {
+                        items.push({
+                            action: "download",
+                            remoteFile,
+                            localPath,
+                            isNew: false,
+                            localSnapshot: plannedLocalSnapshot,
+                        });
+                        continue;
+                    }
+                    items.push({ action: "skip-unchanged", remoteFile, localPath });
+                    continue;
+                }
+                if (journalEntry && !localChanged && remoteChanged) {
+                    // ── Anti-rollback guard (silent newer→older overwrite) ───────────
+                    // Remote etag moved but local still matches the journal baseline, so
+                    // the classic 3-way merge calls this a clean `download` and overwrites
+                    // local with remote. That assumes the remote *advanced*. It can also
+                    // REGRESS: a second device (or a stale re-push) can replace the S3
+                    // object with an OLDER, SMALLER copy. `hasRemoteChanged` is pure-ETag
+                    // and cannot tell an advance from a rollback — ListObjectsV2 carries no
+                    // content hash, and `lastModified` is the upload time (newer even for
+                    // stale content), so neither distinguishes the two. A silent download
+                    // then DESTROYS newer local bytes with no conflict surfaced.
+                    //
+                    // This bit append-only bot chat logs on 2026-06-10, the day
+                    // event-driven bidirectional sync (which lets a peer device push to
+                    // S3 between this device's pulls) first rolled out: a regressed S3
+                    // object truncated freshly-appended lines, undetected by the planner.
+                    //
+                    // Guard: if the incoming remote object is strictly SMALLER than the
+                    // local file we already hold (a size regression on a tracked regular
+                    // file), do NOT silently clobber. Route through the conflict path —
+                    // the executor's convergence probe fetches the remote once and, on
+                    // genuine divergence, PRESERVES local as a `.conflict-*` mirror instead
+                    // of overwriting it (and under `--on-conflict abort` halts loudly
+                    // rather than losing data). A byte-identical remote can never be
+                    // smaller, so this never manufactures a false conflict on a no-op
+                    // re-upload. Symlinks are exempt: their on-disk size is not the target
+                    // length, so the comparison is meaningless.
+                    //
+                    // Direction gate: only guard copies this device AUTHORED (last synced
+                    // UP). A consumer copy (last synced DOWN) has no local authorship to
+                    // protect — the remote is authoritative, so a smaller remote is a
+                    // legitimate update (e.g. the gardener rewriting a shorter brief), not a
+                    // regression. Without this gate a consumer device floods `.conflict`
+                    // mirrors and stalls on stale gardener output forever (the 786-file
+                    // pile-up, 2026-06-22). `"up"` and any missing/unknown direction stay
+                    // guarded exactly as before — the 2026-06-10 chat-log protection holds.
+                    if (journalEntry.direction !== "down" &&
+                        !isLocalSymlink &&
+                        remoteFile.size < localLstat.size) {
+                        items.push({
+                            action: "conflict",
+                            remoteFile,
+                            localPath,
+                            localHash,
+                            localMtime: localLstat.mtime,
+                            localSize: localLstat.size,
+                            localSnapshot: plannedLocalSnapshot,
+                        });
+                        continue;
+                    }
+                    // Remote genuinely advanced (same-or-larger) → normal catch-up
+                    // download below.
+                }
+                // No journal entry, or remote-only changed (non-shrinking) → fall
+                // through to download.
+            }
+            // Suppress the re-download of an intentionally-deleted key (delete-resync).
+            // Reaches here only for the `!localExists` case — the `localExists` branch
+            // above already handled (and `continue`d) any suppressing tombstone, so a
+            // tombstone that survives to here means "remote present, local absent, not a
+            // re-create": the classic resurrection ("remote present → I'm behind →
+            // download") the planner must NOT do. Route to `tombstone-delete` so the
+            // executor drops any stale journal entry and the key stays gone, instead of
+            // pulling the deleted object back in. `localTombstoneSuppresses` adds the
+            // same protection driven by this machine's own journal tombstone, so an
+            // intentional delete is not resurrected even when the server FILE_TOMBSTONE
+            // fetch is degraded.
+            if (tombstoneSuppresses || localTombstoneSuppresses) {
+                // A persisting `local-delete` tombstone (stamped by the intentional-delete
+                // producer below) must KEEP its journal entry — the push leg still needs
+                // it to propagate the S3 delete. Skip the re-download without dropping the
+                // entry. Other tombstone kinds (scope-shrink / FILE_TOMBSTONE) drop it.
+                if (journalEntry?.removedReason === "local-delete") {
+                    continue;
+                }
+                items.push({
+                    action: "tombstone-delete",
+                    remoteFile,
+                    localPath,
+                    localSnapshot: plannedLocalSnapshot,
+                });
+                continue;
+            }
+            // Intentional-delete producer: a clean, CURRENT (etag matches), non-divergent
+            // file that is MISSING locally is the user deleting a genuinely-synced file.
+            // A watcher intent is the strict proof used by `owned-only` (and `all`).
+            // `currency-gated` additionally admits an intent-less candidate because a
+            // watcherless runner can never mint one; the matching ETag still proves no
+            // peer changed this individual object. The post-loop bulk-asymmetry decision
+            // remains the whole-set guard for BOTH candidate classes. A stale-etag,
+            // divergent, tombstoned, or never-journaled missing file falls through to
+            // the normal download below.
+            if (!localExists &&
+                journalEntry !== undefined &&
+                !isTombstone(journalEntry) &&
+                !journalEntry.localDiverges &&
+                (hasCurrentLocalDeleteIntent(journalEntry) ||
+                    propagateDeletePolicy === "currency-gated") &&
+                normalizeEtag(remoteFile.etag) === journalEntry.remoteEtag) {
+                intentionalDeleteCandidates.push({ remoteFile, localPath });
                 continue;
             }
             items.push({
-                action: "tombstone-delete",
+                action: "download",
                 remoteFile,
                 localPath,
+                isNew: !localExists,
                 localSnapshot: plannedLocalSnapshot,
             });
-            continue;
         }
-        // Intentional-delete producer: a clean, CURRENT (etag matches), non-divergent
-        // file that is MISSING locally is the user deleting a genuinely-synced file.
-        // A watcher intent is the strict proof used by `owned-only` (and `all`).
-        // `currency-gated` additionally admits an intent-less candidate because a
-        // watcherless runner can never mint one; the matching ETag still proves no
-        // peer changed this individual object. The post-loop bulk-asymmetry decision
-        // remains the whole-set guard for BOTH candidate classes. A stale-etag,
-        // divergent, tombstoned, or never-journaled missing file falls through to
-        // the normal download below.
-        if (!localExists &&
-            journalEntry !== undefined &&
-            !isTombstone(journalEntry) &&
-            !journalEntry.localDiverges &&
-            (hasCurrentLocalDeleteIntent(journalEntry) ||
-                propagateDeletePolicy === "currency-gated") &&
-            normalizeEtag(remoteFile.etag) === journalEntry.remoteEtag) {
-            intentionalDeleteCandidates.push({ remoteFile, localPath });
-            continue;
-        }
-        items.push({
-            action: "download",
-            remoteFile,
-            localPath,
-            isNew: !localExists,
-            localSnapshot: plannedLocalSnapshot,
-        });
     }
     dropJournalDecodeWindow();
     if (cooperativeCheckpoint &&