@indigoai-us/hq-cloud 6.11.11 → 6.11.13

package/dist/cli/sync.js

@@ -11,13 +11,15 @@ import { downloadFile, listRemoteFiles, headRemoteFile, primeObjectTransport, to
 import { readJournal, writeJournal, hashFile, hashSymlinkTarget, updateEntry, removeEntry, getEntry, normalizeEtag, migrateToV2, gcTombstones, lastPullRecord, appendPullRecord, generatePullId, PERSONAL_VAULT_JOURNAL_SLUG, migratePersonalVaultJournal, } from "../journal.js";
 import { PERSONAL_VAULT_MANIFEST_KEY } from "../personal-vault.js";
 import { buildScopeShrinkPlan, applyScopeShrink, ScopeShrinkBlockedError, ScopeShrinkLargePruneError, } from "../scope-shrink.js";
-import { coalescePrefixes, isCoveredByAny } from "../prefix-coalesce.js";
+import { coalescePrefixes, isCoveredByAny, } from "../prefix-coalesce.js";
 import { createIgnoreFilter } from "../ignore.js";
+import { hasRemoteChanged, isAccessDenied, resolveActiveCompany, resolveTransferConcurrency, } from "../sync-core.js";
 import { isEphemeralPath, isMalformedVaultKey } from "./share.js";
 import { resolveConflict } from "./conflict.js";
 import { buildConflictId, buildConflictPath, readShortMachineId, } from "../lib/conflict-file.js";
 import { appendConflictEntry } from "../lib/conflict-index.js";
 import { reindex } from "./reindex.js";
+import { withOperationLock } from "../operation-lock.js";
 import { fetchCompanyTombstones, } from "./tombstones.js";
 /**
  * Resolve the auto-prune safety cap (US-005 bulk-delete guard). An automatic
@@ -36,6 +38,15 @@ export function resolveAutoPruneCap() {
 }
 /** Max time to wait on the best-effort new-files notification POST. */
 const NOTIFY_FILE_ADDED_TIMEOUT_MS = 5000;
+/**
+ * Server cap on files per `/v1/notify/file-added` report. The endpoint rejects
+ * an oversized batch wholesale, so the client MUST split a large report into
+ * chunks at or under this size — otherwise a first sync with more than this many
+ * new files reports none of them, and the same oversized batch re-triggers every
+ * sync cycle (wasted work + dropped notifications). Keep in lockstep with the
+ * server-side limit.
+ */
+const NOTIFY_FILE_ADDED_MAX_BATCH = 1000;
 /**
  * Best-effort report of the files that were new to this drive during the sync,
  * so the HQ Sync app can show a persistent cross-session "new files" history.
@@ -44,17 +55,31 @@ const NOTIFY_FILE_ADDED_TIMEOUT_MS = 5000;
  * FILE_EVENT rows for the calling user (the one the files are new for). Fully
  * non-fatal: any error, non-2xx, or timeout is swallowed — the durable signal
  * is the synced file itself; this is only a notification mirror. Bounded by a
- * 5s timeout so a hung endpoint can't stall sync completion. No-op when there
- * are no new files.
+ * 5s timeout PER request so a hung endpoint can't stall sync completion. No-op
+ * when there are no new files.
+ *
+ * Large reports are split into chunks of at most NOTIFY_FILE_ADDED_MAX_BATCH
+ * files (the server's per-report cap). Each chunk is POSTed independently and
+ * best-effort, so one failing/oversized batch can never block the others or the
+ * sync. Exported only so the chunking can be unit-tested directly.
  */
-async function reportNewFilesToNotify(vaultConfig, companyUid, companySlug, files) {
+export async function reportNewFilesToNotify(vaultConfig, companyUid, companySlug, files) {
     if (files.length === 0)
         return;
+    let token;
     try {
-        const token = typeof vaultConfig.authToken === "function"
-            ? await vaultConfig.authToken()
-            : vaultConfig.authToken;
-        const base = vaultConfig.apiUrl.replace(/\/+$/, "");
+        token =
+            typeof vaultConfig.authToken === "function"
+                ? await vaultConfig.authToken()
+                : vaultConfig.authToken;
+    }
+    catch (err) {
+        logNotifyFailure(err);
+        return;
+    }
+    const base = vaultConfig.apiUrl.replace(/\/+$/, "");
+    for (let i = 0; i < files.length; i += NOTIFY_FILE_ADDED_MAX_BATCH) {
+        const batch = files.slice(i, i + NOTIFY_FILE_ADDED_MAX_BATCH);
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), NOTIFY_FILE_ADDED_TIMEOUT_MS);
         try {
@@ -67,7 +92,7 @@ async function reportNewFilesToNotify(vaultConfig, companyUid, companySlug, file
                 body: JSON.stringify({
                     companyUid,
                     companySlug,
-                    files: files.map((f) => ({
+                    files: batch.map((f) => ({
                         path: f.path,
                         bytes: f.bytes,
                         ...(f.addedBy ? { addedBy: f.addedBy } : {}),
@@ -76,211 +101,169 @@ async function reportNewFilesToNotify(vaultConfig, companyUid, companySlug, file
                 signal: controller.signal,
             });
         }
+        catch (err) {
+            // Best-effort per chunk: never let notification reporting affect the sync
+            // result, and a failed chunk must not abort the remaining chunks.
+            logNotifyFailure(err);
+        }
         finally {
             clearTimeout(timer);
         }
     }
-    catch (err) {
-        // Best-effort: never let notification reporting affect the sync result.
-        try {
-            console.error(`[hq-sync] new-files notify report failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
-        }
-        catch {
-            // swallow — logging must never break sync
-        }
+}
+/** Log a non-fatal notify failure without ever throwing out of the logger. */
+function logNotifyFailure(err) {
+    try {
+        console.error(`[hq-sync] new-files notify report failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+    }
+    catch {
+        // swallow — logging must never break sync
     }
 }
 /**
  * Sync (pull) all allowed files from the entity vault.
  */
 export async function sync(options) {
-    const { company, onConflict, vaultConfig, hqRoot } = options;
+    if (options.operationLockAlreadyHeld) {
+        return syncWithOperationLockHeld(options);
+    }
+    return withOperationLock(options.hqRoot, "sync", () => syncWithOperationLockHeld(options));
+}
+async function syncWithOperationLockHeld(options) {
+    const run = await buildPullContext(options);
+    const plan = planPull(run);
+    emitPullPlan(run.emit, plan);
+    const scopePlan = planScopeShrink(run);
+    const scopeRun = executeScopeShrink(run, scopePlan);
+    const counters = createPullCounters();
+    const transferConcurrency = resolveTransferConcurrency();
+    const conflictRun = await executeConflictExecutor(run, plan, scopeRun, counters);
+    if (conflictRun.abortResult) {
+        return conflictRun.abortResult;
+    }
+    await executeDownloadExecutor(run, conflictRun.downloadItems, transferConcurrency, counters);
+    await emitAndReportNewFiles(run, plan);
+    await verifyPlannedJournalTombstones(run, plan);
+    executeJournalTombstoneDeletes(run, plan, counters);
+    return finalizePullRun(run, plan, scopeRun, counters);
+}
+async function buildPullContext(options) {
+    const { company, vaultConfig, hqRoot } = options;
     const emit = options.onEvent ?? defaultConsoleLogger;
-    // Resolve company
     const companyRef = company ?? resolveActiveCompany(hqRoot);
     if (!companyRef) {
         throw new Error("No company specified and no active company found. " +
             "Use --company <slug> or set up .hq/config.json.");
     }
-    // Resolve entity context
-    let ctx = await resolveEntityContext(companyRef, vaultConfig);
-    // Every company's files land under companies/{slug}/ so fanning out multiple
-    // companies into the same hqRoot doesn't cross-clobber files with overlapping
-    // S3 keys (e.g. every company has a .hq/manifest.json). Remote keys stay
-    // company-relative; the prefix lives only on disk.
-    // In personalMode the journal slug + S3 keys are person-relative (e.g. "docs/foo.md");
-    // the local target is `hqRoot` directly, NOT `<hqRoot>/companies/<personSlug>/`. This
-    // keeps round-trip parity with the Rust personal first-push (Step 7) which sources
-    // `<hqRoot>/docs/foo.md`.
+    const ctx = await resolveEntityContext(companyRef, vaultConfig);
     const companyRoot = options.personalMode === true
         ? hqRoot
         : path.join(hqRoot, "companies", ctx.slug);
     const shouldSync = createIgnoreFilter(hqRoot);
     const journalSlug = options.journalSlug ?? ctx.slug;
     const startedAt = new Date().toISOString();
-    // Personal-vault callers must never start from an empty journal when only
-    // the legacy `personal` file exists (mass re-download/etag churn). Seeding
-    // here — inside the engine — covers every consumer (sync-runner already
-    // seeds; hq-cli historically didn't, which split the vault's bookkeeping
-    // across two journal files and re-flagged synced files as conflicts).
     if (journalSlug === PERSONAL_VAULT_JOURNAL_SLUG)
         migratePersonalVaultJournal();
-    // Migrate v1 → v2 in place so the scope-shrink / pull-record machinery has
-    // its fields, and GC any tombstones past the 30-day retention window before
-    // we re-evaluate orphans (so a long-pruned path can re-download cleanly).
     const journal = migrateToV2(readJournal(journalSlug));
     gcTombstones(journal, Date.now());
-    // ── Effective download scope (US-005) ─────────────────────────────────────
-    // `all`  → prefixSet `[""]`, which `isCoveredByAny` treats as "covers
-    //          everything" — so the download filter and the scope-shrink
-    //          comparison both become no-ops, preserving legacy full-bucket
-    //          behavior bit-for-bit.
-    // `shared`/`custom` → the coalesced, company-relative prefix set the runner
-    //          resolved. An empty set means "nothing in scope" → download
-    //          nothing (the runner falls back to `all` on resolution errors, so
-    //          empty here is an intentional "nothing shared", never a failure).
     const syncMode = options.syncMode ?? "all";
     const currentPrefixSet = syncMode === "all" ? [""] : coalescePrefixes(options.prefixSet ?? []);
-    // Authorship guard input (scope-shrink): the caller's own Cognito sub,
-    // injected by the entry point (the runner sources it from its decoded
-    // idToken claims — the same sub stamped onto uploads as `created-by-sub`).
-    // Undefined degrades safely: own-author files lose their special shield, but
-    // the `protectUnknownAuthors` conservative path below still prevents a
-    // routine sync from deleting anything it can't prove is foreign.
-    const callerSub = options.callerSub;
-    let filesDownloaded = 0;
-    let bytesDownloaded = 0;
-    let filesSkipped = 0;
-    let conflicts = 0;
-    let filesTombstoned = 0;
-    let filesOutOfScope = 0;
-    const conflictPaths = [];
-    // List all remote files (IAM session policy filters at the AWS layer)
     const remoteFiles = await listRemoteFiles(ctx);
-    // Fetch the company's FILE_TOMBSTONE records so the planner can suppress
-    // resurrection of an intentionally-deleted object (delete-resync). Done in
-    // parallel intent with the LIST above conceptually, but kept serial here for
-    // a clean read of `ctx`; best-effort — a failed read degrades to an empty map
-    // (no suppression), preserving the pre-fix behavior. ctx.uid is the verified
-    // companyUid the tombstone rows are keyed under.
-    //
-    // SKIP for the personal vault: its `ctx.uid` is a personUid (`prs_…`), but
-    // `GET /v1/files/tombstones?company=…` is COMPANY-scoped server-side
-    // (findCallerWithMembership), so a personal-vault request resolves
-    // `company=prs_…` to no membership and is correctly rejected with
-    // `403 "No active membership for caller in company prs_…"`. That 403 is
-    // benign for the pull (it already degrades to the empty map below), but
-    // hq-pro captures EVERY one as a Sentry warning — the per-personal-vault
-    // no-membership cluster (one Sentry issue per signed-in user). Personal-vault
-    // delete-resync was never a committed feature and there is no person-scoped
-    // tombstone path, so for the personal target we skip the fetch and use an
-    // empty map — byte-for-byte the current degraded behavior, minus the 403 spam.
-    // FUTURE FOLLOW-UP (not built here): if personal-vault delete-resync is
-    // wanted, it needs a real person-scoped tombstone endpoint + client read.
-    const tombstones = options.personalMode === true
+    const fileTombstones = options.personalMode === true
         ? new Map()
         : await fetchCompanyTombstones(vaultConfig, ctx.uid);
-    // Stage 1: classify every remote file against the journal + local disk.
-    // Hashing happens here (not in the transfer loop) so the plan event below
-    // carries an accurate denominator before any progress events fire.
-    const plan = computePullPlan(remoteFiles, journal, companyRoot, shouldSync, options.personalMode === true, options.includeLocalCompanies === true, options.teamSyncedSlugs ?? null, currentPrefixSet, tombstones);
+    return {
+        options,
+        companyRef,
+        vaultConfig,
+        hqRoot,
+        emit,
+        ctx,
+        companyRoot,
+        shouldSync,
+        journalSlug,
+        startedAt,
+        journal,
+        remoteFiles,
+        syncMode,
+        currentPrefixSet,
+        fileTombstones,
+    };
+}
+function planPull(run) {
+    return computePullPlan(run.remoteFiles, run.journal, run.companyRoot, run.shouldSync, run.options.personalMode === true, run.options.includeLocalCompanies === true, run.options.teamSyncedSlugs ?? null, run.currentPrefixSet, run.fileTombstones);
+}
+function emitPullPlan(emit, plan) {
     emit({
         type: "plan",
         filesToDownload: plan.filesToDownload,
         bytesToDownload: plan.bytesToDownload,
-        // sync() is pull-only; push counts are sourced from share()'s plan event.
         filesToUpload: 0,
         bytesToUpload: 0,
         filesToSkip: plan.filesToSkip,
         filesToConflict: plan.filesToConflict,
-        // Authoritative FILE_TOMBSTONE suppressions (delete-resync) are the only
-        // deletes known at plan time; the journal-vs-LIST tombstones are
-        // HEAD-verified later and surfaced via the final filesTombstoned count.
         filesToDelete: plan.filesToTombstoneDelete,
     });
-    // ── Scope-shrink cleanup (US-005) ─────────────────────────────────────────
-    // If the effective scope narrowed since the last pull, files that were
-    // pulled under the old scope but fall outside the new one are orphans. We
-    // delete only CLEAN orphans (provably unchanged since last sync); dirty
-    // (locally-modified) orphans are sacred. By default a dirty orphan aborts
-    // the leg with a structured error the CLI renders; `forceScopeShrink` keeps
-    // dirty files on disk and only tombstones their journal entries.
-    //
-    // `companyRoot` is passed as the module's `hqRoot` so its `path.join(root,
-    // key)` resolves company-relative journal keys correctly (the scope-shrink
-    // module is namespace-agnostic — root + keys + prefixSet must simply agree).
-    //
-    // Note: this is the durable selective-download fix for OWNERS. An owner's
-    // STS is wide (role-bypass), so the remote LIST returns everything and the
-    // AWS layer never narrows the pull. This client-side shrink is what makes
-    // `hq sync mode shared` actually stick across re-syncs for an owner.
-    const lastRecord = lastPullRecord(journal, ctx.uid);
-    // A missing record, or a v1-migrated record with an empty prefixSet, means
-    // "no recorded scope" → treat the last scope as full-bucket `all` (`[""]`),
-    // per the PullRecord.prefixSet contract in types.ts.
+}
+function createPullCounters() {
+    return {
+        filesDownloaded: 0,
+        bytesDownloaded: 0,
+        filesSkipped: 0,
+        conflicts: 0,
+        filesTombstoned: 0,
+        filesOutOfScope: 0,
+        conflictPaths: [],
+    };
+}
+function planScopeShrink(run) {
+    const lastRecord = lastPullRecord(run.journal, run.ctx.uid);
     const lastPrefixSet = lastRecord && lastRecord.prefixSet.length > 0
         ? lastRecord.prefixSet
         : [""];
     const shrinkPlan = buildScopeShrinkPlan({
-        journal,
-        hqRoot: companyRoot,
+        journal: run.journal,
+        hqRoot: run.companyRoot,
         lastPrefixSet,
-        currentPrefixSet,
-        callerSub,
-        // Automatic pull: never auto-prune content the caller authored, and never
-        // make a destructive guess about unknown-author (legacy) orphans. The
-        // explicit `hq sync narrow` ritual opts out of the unknown-author shield.
+        currentPrefixSet: run.currentPrefixSet,
+        callerSub: run.options.callerSub,
         protectUnknownAuthors: true,
     });
-    // Policy: the background menubar runner ("auto-recover") can take no
-    // interactive flag, so it must never throw on a shrink — it self-heals
-    // non-destructively (dirty kept on disk + un-tracked, clean quarantined).
-    // A foreground `hq sync` ("block", the default) keeps the protective gate
-    // but renders FOLLOWABLE advice. `autoRecover` implies force (proceed) and
-    // bypasses the bulk-prune cap (quarantine is non-destructive, so a large
-    // recovery move is safe). DEV-1768.
-    const scopeShrinkPolicy = options.scopeShrinkPolicy ?? "block";
+    const scopeShrinkPolicy = run.options.scopeShrinkPolicy ?? "block";
     const autoRecover = scopeShrinkPolicy === "auto-recover";
     const adviceContext = autoRecover ? "runner" : "cli";
-    const effectiveForce = options.forceScopeShrink === true || autoRecover;
+    const effectiveForce = run.options.forceScopeShrink === true || autoRecover;
+    return {
+        lastRecord,
+        shrinkPlan,
+        autoRecover,
+        adviceContext,
+        effectiveForce,
+    };
+}
+function executeScopeShrink(run, scopePlan) {
+    const { lastRecord, shrinkPlan, adviceContext, effectiveForce } = scopePlan;
     if (shrinkPlan.dirty.length > 0 && !effectiveForce) {
-        throw new ScopeShrinkBlockedError(ctx.uid, lastRecord?.syncMode ?? "unknown", syncMode, shrinkPlan.dirty, shrinkPlan.clean, adviceContext);
+        throw new ScopeShrinkBlockedError(run.ctx.uid, lastRecord?.syncMode ?? "unknown", run.syncMode, shrinkPlan.dirty, shrinkPlan.clean, adviceContext);
     }
-    // Bulk guard: refuse to auto-move more than the safety cap of CLEAN files in
-    // a single foreground sync. A deliberate large narrow goes through
-    // `hq sync narrow --apply` (its own confirmation); `--force-scope-shrink` (or
-    // raising HQ_SYNC_MAX_AUTO_PRUNE) overrides. Cap of 0 = unlimited. Skipped
-    // under auto-recover — quarantine is non-destructive so a big recovery is
-    // safe, and the runner has no way to act on a thrown cap. The engine moves
-    // nothing when it throws here.
     const autoPruneCap = resolveAutoPruneCap();
     if (!effectiveForce &&
         autoPruneCap > 0 &&
         shrinkPlan.clean.length > autoPruneCap) {
-        throw new ScopeShrinkLargePruneError(ctx.uid, syncMode, shrinkPlan.clean.length, autoPruneCap, adviceContext);
+        throw new ScopeShrinkLargePruneError(run.ctx.uid, run.syncMode, shrinkPlan.clean.length, autoPruneCap, adviceContext);
     }
-    // Clean orphans are QUARANTINED (moved into `.hq/scope-quarantine/<slug>/`,
-    // recoverable), never silently deleted — a background sync purging local
-    // files unannounced was DEV-1768 fix #3. The quarantine root lives under the
-    // real HQ root's `.hq/` (outside `companyRoot` and never pushed), so moved
-    // files don't round-trip back through S3.
-    const scopeQuarantineRoot = path.join(hqRoot, ".hq", "scope-quarantine", journalSlug);
+    const scopeQuarantineRoot = path.join(run.hqRoot, ".hq", "scope-quarantine", run.journalSlug);
     const shrinkResult = applyScopeShrink({
-        journal,
+        journal: run.journal,
         plan: shrinkPlan,
-        hqRoot: companyRoot,
+        hqRoot: run.companyRoot,
         forceScopeShrink: effectiveForce,
         reason: "scope_shrink",
         cleanDisposition: "quarantine",
         quarantineRoot: scopeQuarantineRoot,
     });
-    // Surface each affected orphan explicitly (named path) so the prune is never
-    // silent. Quarantined clean files render as `deleted: true` (removed from the
-    // working tree, recoverable in quarantine); dirty files KEPT on disk render
-    // as a non-deletion notice so the operator knows they were un-tracked, not
-    // removed. The Rust menubar parser already handles `deleted: true`.
     for (const relPath of shrinkResult.quarantinedPaths) {
-        emit({
+        run.emit({
             type: "progress",
             path: relPath,
             bytes: 0,
@@ -289,7 +272,7 @@ export async function sync(options) {
         });
     }
     for (const relPath of shrinkResult.removedPaths) {
-        emit({
+        run.emit({
             type: "progress",
             path: relPath,
             bytes: 0,
@@ -298,477 +281,314 @@ export async function sync(options) {
         });
     }
     for (const relPath of shrinkResult.dirtyKeptPaths) {
-        emit({
+        run.emit({
             type: "progress",
             path: relPath,
             bytes: 0,
             message: "scope-narrowed: locally-modified file KEPT on disk, un-tracked from sync (outside scope)",
         });
     }
-    // "Removed from the working tree" = deleted OR quarantined; both vacate the
-    // file's original path. Reported as `scopeOrphansRemoved` for back-compat.
-    const scopeOrphansRemoved = shrinkResult.cleanRemoved + shrinkResult.cleanQuarantined;
-    // Stage 2: execute the plan. Per-item branching mirrors the pre-refactor
-    // inline loop; the only structural change is that classification has
-    // already happened (so `localHash` is reused instead of re-hashing).
-    //
-    // 5.36.0: download items go through a bounded-concurrent pool
-    // (`TRANSFER_CONCURRENCY`, default 16, tunable via
-    // `HQ_SYNC_TRANSFER_CONCURRENCY`) for 4-8x speedup on transfer-heavy
-    // syncs. Conflict items stay serial — they may prompt the operator
-    // and the abort path must short-circuit before any further work. We
-    // partition the plan items into "conflict (serial)" and "download
-    // (parallel)" buckets and run the serial pass first; the parallel pass
-    // only runs if no conflict aborted.
-    //
-    // Per-file `progress` events fire at the moment each individual download
-    // settles (inside the pool wrapper), NOT in plan-walk order. The cross-
-    // file interleave is acceptable: the menubar stream parser already
-    // handles per-company interleave, and the same shape applies within a
-    // single company's pool. Per-file event-count correctness is preserved
-    // (one progress per download, one error per failure).
-    const TRANSFER_CONCURRENCY = (() => {
-        const raw = process.env.HQ_SYNC_TRANSFER_CONCURRENCY;
-        if (raw === undefined || raw === "")
-            return 16;
-        const parsed = Number.parseInt(raw, 10);
-        return Number.isFinite(parsed) && parsed > 0 ? parsed : 16;
-    })();
-    // First pass: serial walk for non-download outcomes (skips + conflicts).
-    // Conflicts may set `aborted = true` and short-circuit the whole pull;
-    // we detect that and skip the parallel pass. Download items are
-    // collected into `downloadItems[]` for the pool pass below.
+    return {
+        shrinkPlan,
+        shrinkResult,
+        scopeOrphansRemoved: shrinkResult.cleanRemoved + shrinkResult.cleanQuarantined,
+    };
+}
+async function refreshRunContextIfExpiring(run) {
+    if (isExpiringSoon(run.ctx.expiresAt)) {
+        run.ctx = await refreshEntityContext(run.companyRef, run.vaultConfig);
+    }
+}
+async function executeConflictExecutor(run, plan, scopeRun, counters) {
     const downloadItems = [];
-    let aborted = false;
-    let abortResult = null;
     for (const item of plan.items) {
-        if (aborted)
-            break;
         if (item.action === "skip-ignored" ||
             item.action === "skip-personal-mode" ||
             item.action === "skip-unchanged" ||
             item.action === "skip-local-only") {
-            filesSkipped++;
+            counters.filesSkipped++;
             continue;
         }
         if (item.action === "skip-excluded-policy") {
-            // Policy-excluded items count separately from `filesSkipped` so the
-            // pull result mirrors the push side's `filesExcludedByPolicy`
-            // counter — `filesSkipped` stays a measure of "unchanged on this
-            // run", not a catch-all for everything we didn't download.
             continue;
         }
         if (item.action === "skip-out-of-scope") {
-            // Outside the effective `syncMode` scope (US-005). Counted on its own
-            // axis so `filesSkipped` keeps meaning "unchanged on this run" — these
-            // are "deliberately not downloaded because of your sync scope".
-            filesOutOfScope++;
+            counters.filesOutOfScope++;
             continue;
         }
         if (item.action === "tombstone-delete") {
-            // Authoritative FILE_TOMBSTONE delete (delete-resync): the remote object
-            // is present but a tombstone marks the key intentionally deleted and it is
-            // not a newer re-create. Delete any local copy and drop the journal entry
-            // so it stays gone — the mirror of the journal-vs-LIST tombstone executor
-            // below, but WITHOUT the HEAD-verify (the remote object is present by
-            // definition; the FILE_TOMBSTONE is the deletion authority). The planner
-            // already routed any divergent local copy to `conflict`, so a local file
-            // reaching here matches the deleted baseline and is safe to remove.
-            const tombstoneKey = item.remoteFile.key;
-            // Same Windows-backslash landmine guard as the journal-tombstone executor:
-            // a malformed key must never reach fs.unlinkSync (path.join collapses the
-            // backslashes onto a REAL POSIX file). Drop the poisoned journal entry
-            // without touching disk.
-            if (isMalformedVaultKey(tombstoneKey)) {
-                removeEntry(journal, tombstoneKey);
-                continue;
-            }
-            try {
-                const lstat = fs.lstatSync(item.localPath);
-                if (lstat.isSymbolicLink() || lstat.isFile()) {
-                    fs.unlinkSync(item.localPath);
-                }
-                // A directory at the key: don't recursively rm-rf the operator's dir;
-                // just drop the journal entry (safe-by-default, same as the other path).
-            }
-            catch (err) {
-                const code = err && typeof err === "object" && "code" in err
-                    ? err.code
-                    : undefined;
-                // ENOENT → local already absent (the common case: a fresh machine that
-                // never held the file, or a prior pull already removed it) → drop the
-                // journal entry and converge. Other errors (EACCES/EPERM/…) leave the
-                // file in place; surface and KEEP the journal entry so the next sync
-                // retries rather than forgetting the delete.
-                if (code !== "ENOENT") {
-                    emit({
-                        type: "error",
-                        path: tombstoneKey,
-                        message: `tombstone-suppress unlink failed: ${err instanceof Error ? err.message : String(err)}`,
-                    });
-                    continue;
-                }
-            }
-            removeEntry(journal, tombstoneKey);
-            filesTombstoned++;
-            emit({ type: "progress", path: tombstoneKey, bytes: 0 });
+            executeFileTombstoneDelete(run, item, counters);
             continue;
         }
         if (item.action === "download") {
             downloadItems.push(item);
             continue;
         }
-        const { remoteFile, localPath } = item;
-        // Auto-refresh context if credentials expiring (kept in execute phase
-        // because Stage 1 is fast — no need to refresh just to classify).
-        if (isExpiringSoon(ctx.expiresAt)) {
-            ctx = await refreshEntityContext(companyRef, vaultConfig);
+        const abortResult = await executeConflictItem(run, plan, scopeRun, counters, downloadItems, item);
+        if (abortResult) {
+            return { downloadItems, abortResult };
         }
-        if (item.action === "conflict") {
-            // ── Convergence guard ────────────────────────────────────────────
-            // The planner flags a conflict purely from journal-relative deltas:
-            // local hash != journal hash AND remote etag != journal etag. It can
-            // NEVER compare local bytes against remote bytes directly — the remote
-            // LIST only carries {key, size, etag, lastModified}, and ListObjectsV2
-            // returns no content hash. So when the journal baseline goes stale,
-            // both deltas fire even though local and remote are byte-for-byte
-            // identical. Stale-baseline triggers seen in the wild: a shared-journal
-            // cross-root collision (personal vault + companies/personal sharing one
-            // journal), an mtime-rounding fast-path miss (journal stamps 1700..351,
-            // the FS returns 1700..350.96, the `===` fast-path misses and re-hashes
-            // — harmless on its own but combines with the etag delta), KMS/multipart
-            // etag churn on a no-op re-upload, a second machine advancing S3 + its
-            // own journal, or a manual revert. Materializing such a false positive
-            // as a conflict litters a useless byte-identical `.conflict-*` mirror
-            // and, under `--on-conflict abort`, halts the WHOLE sync over zero real
-            // divergence. (One live run produced 140 byte-identical mirrors this way.)
-            //
-            // We have no remote content hash up front, so prove convergence by
-            // fetching the remote bytes once — to the very path the conflict mirror
-            // would occupy — and hashing them. Identical bytes are not a conflict:
-            // re-stamp the journal baseline (so neither side looks changed next run)
-            // and skip. Genuine divergence reuses the already-fetched bytes as the
-            // inspection mirror, so the common keep/skip path costs no extra I/O.
-            const detectedAt = new Date().toISOString();
-            const machineId = readShortMachineId(hqRoot);
-            const originalRelative = path.relative(hqRoot, localPath);
-            const conflictRelative = buildConflictPath(originalRelative, detectedAt, machineId);
-            const conflictAbs = path.join(hqRoot, conflictRelative);
-            let remoteFetched = false;
-            let converged = false;
-            try {
-                await downloadFile(ctx, remoteFile.key, conflictAbs);
-                remoteFetched = true;
-                // Hash the fetched remote exactly the way the planner hashed local
-                // (symlink-aware) so the two hashes are directly comparable. A
-                // symlink record round-trips to a symlink on disk; hashing its
-                // target string matches `hashSymlinkTarget(localPath)`.
-                const remoteHash = fs.lstatSync(conflictAbs).isSymbolicLink()
-                    ? hashSymlinkTarget(fs.readlinkSync(conflictAbs))
-                    : hashFile(conflictAbs);
-                converged = remoteHash === item.localHash;
-            }
-            catch (probeErr) {
-                // Couldn't fetch or hash the remote — fail safe by falling through to
-                // the conventional conflict path (converged stays false). No mirror
-                // is on disk in this case.
-                emit({
-                    type: "error",
-                    path: remoteFile.key,
-                    message: `conflict convergence probe failed: ${probeErr instanceof Error ? probeErr.message : String(probeErr)}`,
-                });
-            }
-            if (converged) {
-                // False positive: remote == local. Drop the byte-identical mirror and
-                // re-stamp the baseline (current localHash + current remoteEtag) so
-                // the next sync sees "no change on either side". Counts as a skip.
-                if (remoteFetched) {
-                    try {
-                        fs.rmSync(conflictAbs, { force: true });
-                    }
-                    catch {
-                        /* best-effort cleanup; a stray identical mirror is harmless */
-                    }
-                }
-                updateEntry(journal, remoteFile.key, item.localHash, item.localSize, "down", remoteFile.etag, item.localMtime.getTime());
-                emit({ type: "reconciled", path: remoteFile.key, direction: "pull" });
-                filesSkipped++;
-                continue;
-            }
-            // ── Genuine divergence ───────────────────────────────────────────
-            conflicts++;
-            conflictPaths.push(remoteFile.key);
-            const resolution = await resolveConflict({
-                path: remoteFile.key,
-                localHash: item.localHash,
-                remoteModified: remoteFile.lastModified,
-                // Use the lstat-mtime captured by the planner — statSync
-                // here would follow a dangling symlink and throw ENOENT,
-                // aborting the pull before resolveConflict could prompt.
-                localModified: item.localMtime,
-                direction: "pull",
-            }, onConflict);
-            emit({
-                type: "conflict",
-                path: remoteFile.key,
-                direction: "pull",
-                resolution,
-            });
-            // The remote bytes were already fetched to `conflictAbs` by the
-            // convergence probe. For "keep"/"skip" they become the
-            // `<original>.conflict-<ts>-<machine>.<ext>` inspection mirror — just
-            // index it (no second download). For "abort" (user gave up) and
-            // "overwrite" (cloud bytes are about to replace local) the mirror is
-            // redundant, so discard it. Best-effort: failure here only emits an
-            // error, doesn't break the sync.
-            if (resolution !== "abort" && resolution !== "overwrite") {
-                if (remoteFetched) {
-                    try {
-                        appendConflictEntry(hqRoot, {
-                            id: buildConflictId(originalRelative, detectedAt),
-                            originalPath: originalRelative,
-                            conflictPath: conflictRelative,
-                            detectedAt,
-                            side: "pull",
-                            machineId,
-                            localHash: item.localHash,
-                            remoteHash: remoteFile.etag ? normalizeEtag(remoteFile.etag) : "",
-                        });
-                    }
-                    catch (mirrorErr) {
-                        emit({
-                            type: "error",
-                            path: remoteFile.key,
-                            message: `conflict mirror index write failed: ${mirrorErr instanceof Error ? mirrorErr.message : String(mirrorErr)}`,
-                        });
-                    }
-                }
-                // If the probe download failed (!remoteFetched) there is no mirror on
-                // disk; the probe already emitted the error. The conflict is still
-                // surfaced and journal-stamped below so it doesn't re-fire silently.
-            }
-            else if (remoteFetched) {
-                try {
-                    fs.rmSync(conflictAbs, { force: true });
-                }
-                catch {
-                    /* best-effort; a leftover mirror is cosmetic, not corrupting */
-                }
-            }
-            if (resolution === "abort") {
-                emit({ type: "new-files", files: [] });
-                writeJournal(journalSlug, journal);
-                aborted = true;
-                abortResult = {
-                    filesDownloaded,
-                    bytesDownloaded,
-                    filesSkipped,
-                    conflicts,
-                    conflictPaths,
-                    aborted: true,
-                    newFiles: plan.newFiles,
-                    newFilesCount: plan.newFilesCount,
-                    filesExcludedByPolicy: plan.filesExcludedByPolicy,
-                    // Abort short-circuits before the tombstone loop runs; report
-                    // 0 so the field shape stays stable for consumers that
-                    // destructure it.
-                    filesTombstoned: 0,
-                    // Scope-shrink ran before execution, so its counts are real even on
-                    // a conflict abort. `filesOutOfScope` reflects how far the serial
-                    // pass got before the abort; that's acceptable for an abort result.
-                    filesOutOfScope,
-                    scopeOrphansRemoved,
-                    scopeOrphansBlocked: shrinkResult.dirtyTombstoned,
-                };
-                break;
-            }
-            if (resolution === "keep" || resolution === "skip") {
-                filesSkipped++;
-                // Stamp the journal with the new baseline so the same conflict
-                // doesn't re-fire on every subsequent sync. After "keep", local
-                // wins — the user has accepted that the cloud version we just
-                // mirrored is what cloud is at this etag, and they don't want
-                // it. Recording (current localHash + current remoteEtag) tells
-                // the next sync "no change on either side" until something new
-                // diverges. Without this, both `localChanged` and `remoteChanged`
-                // stay true forever and the conflict is sticky.
-                // Stamp from planner-captured size (symlink-aware), NOT
-                // statSync — which would follow a dangling symlink and
-                // throw ENOENT, get swallowed, and leave the journal
-                // stale so this conflict would re-fire on every sync
-                // forever. localSize is sourced from the same lstat that
-                // computed localMtime + localHash above.
-                updateEntry(journal, remoteFile.key, item.localHash, item.localSize, "down", remoteFile.etag, item.localMtime.getTime());
-                continue;
-            }
-            // "overwrite" falls through to download — re-route through the pool
-            // so it benefits from parallelism too. Synthesize a download item
-            // pointing at the same remoteFile/localPath; isNew=false because
-            // there was a conflict-eligible local file present.
-            downloadItems.push({
-                action: "download",
-                remoteFile,
-                localPath,
-                isNew: false,
+    }
+    return { downloadItems, abortResult: null };
+}
+function executeFileTombstoneDelete(run, item, counters) {
+    const tombstoneKey = item.remoteFile.key;
+    const tombstonePath = resolveContainedVaultPath(run.companyRoot, tombstoneKey);
+    if (tombstonePath === null)
+        return;
+    try {
+        const lstat = fs.lstatSync(tombstonePath);
+        if (tombstoneTargetDiverged(run.journal, tombstoneKey, tombstonePath, lstat)) {
+            return;
+        }
+        if (lstat.isSymbolicLink() || lstat.isFile()) {
+            fs.unlinkSync(tombstonePath);
+        }
+    }
+    catch (err) {
+        const code = err && typeof err === "object" && "code" in err
+            ? err.code
+            : undefined;
+        if (code !== "ENOENT") {
+            run.emit({
+                type: "error",
+                path: tombstoneKey,
+                message: `tombstone-suppress unlink failed: ${err instanceof Error ? err.message : String(err)}`,
             });
-            continue;
+            return;
         }
     }
-    // Early-return on conflict abort BEFORE running the parallel download
-    // pool — the abort intent is "stop the pull now", not "stop new work but
-    // finish what's in flight". Since the pool hasn't started yet, this is
-    // a clean drain (zero items in flight) by construction.
-    if (aborted && abortResult) {
-        return abortResult;
+    removeEntry(run.journal, tombstoneKey);
+    counters.filesTombstoned++;
+    run.emit({ type: "progress", path: tombstoneKey, bytes: 0 });
+}
+async function executeConflictItem(run, plan, scopeRun, counters, downloadItems, item) {
+    const { remoteFile, localPath } = item;
+    await refreshRunContextIfExpiring(run);
+    const detectedAt = new Date().toISOString();
+    const machineId = readShortMachineId(run.hqRoot);
+    const originalRelative = path.relative(run.hqRoot, localPath);
+    const conflictRelative = buildConflictPath(originalRelative, detectedAt, machineId);
+    const conflictAbs = path.join(run.hqRoot, conflictRelative);
+    const conflictKey = toPosixKey(path.relative(run.companyRoot, conflictAbs));
+    if (!isDownloadWritePathStillContained(run.companyRoot, conflictKey, conflictAbs)) {
+        counters.filesSkipped++;
+        run.emit({
+            type: "error",
+            path: remoteFile.key,
+            message: "conflict mirror skipped: local parent escaped the sync root",
+        });
+        return null;
+    }
+    let remoteFetched = false;
+    let converged = false;
+    try {
+        const downloaded = await downloadFile(run.ctx, remoteFile.key, conflictAbs);
+        remoteFetched = true;
+        const remoteHash = fs.lstatSync(conflictAbs).isSymbolicLink()
+            ? hashSymlinkTarget(fs.readlinkSync(conflictAbs))
+            : (downloaded.contentHash ?? hashFile(conflictAbs));
+        converged = remoteHash === item.localHash;
     }
-    // ── Parallel download pool (5.36.0) ───────────────────────────────────
-    // Bounded concurrency: TRANSFER_CONCURRENCY simultaneous downloads. Same
-    // race-based shape as the HEAD-verify pool above but applied to the body
-    // of each download. Per-item progress events fire at file-settle time
-    // (inside the wrapper), so cross-file interleave is expected and the
-    // menubar's stream parser already handles it.
-    if (downloadItems.length > 0) {
-        // Batch pre-mint GET URLs for every download in one shot (chunked server-
-        // side) so the pool below — and the new-files HEAD enrichment that follows,
-        // which re-reads the same keys — reuse them instead of presigning per file.
-        // On a large initial pull this is the difference between ~ceil(N/100)
-        // presign calls and N (which would 429 past the 100-req/hr limit). No-op
-        // on the S3 SDK transport; best-effort (failure falls back to per-file).
-        await primeObjectTransport(ctx, "get", downloadItems.map((d) => d.remoteFile.key));
-        const queue = [...downloadItems];
-        const inFlight = new Set();
-        const downloadOne = async (downloadItem) => {
-            const { remoteFile, localPath } = downloadItem;
-            // Auto-refresh context if credentials expiring. Each task checks
-            // independently — refresh is idempotent on the same context object.
-            if (isExpiringSoon(ctx.expiresAt)) {
-                ctx = await refreshEntityContext(companyRef, vaultConfig);
-            }
+    catch (probeErr) {
+        run.emit({
+            type: "error",
+            path: remoteFile.key,
+            message: `conflict convergence probe failed: ${probeErr instanceof Error ? probeErr.message : String(probeErr)}`,
+        });
+    }
+    if (converged) {
+        if (remoteFetched) {
             try {
-                const { metadata } = await downloadFile(ctx, remoteFile.key, localPath);
-                const author = metadata?.["created-by"] ?? null;
-                // Author sub for the scope-shrink authorship guard — same field the
-                // upload side stamps, read straight off the GET response metadata.
-                const createdBySub = metadata?.["created-by-sub"];
-                // Symlink records materialize as real symlinks on disk. lstat
-                // (does not follow) lets us detect that case so the journal stamp
-                // mirrors what the push side would emit on the next tick:
-                //   hash = sha256(readlink target string)
-                //   size = 0
-                // Without this check, hashFile would follow the link and stamp the
-                // target file's contents — a value the next push would never
-                // produce — which makes skipUnchanged perpetually re-upload every
-                // symlink, defeating the point of the gate.
-                const localLstat = fs.lstatSync(localPath);
-                const isLocalSymlink = localLstat.isSymbolicLink();
-                const hash = isLocalSymlink
-                    ? hashSymlinkTarget(fs.readlinkSync(localPath))
-                    : hashFile(localPath);
-                const size = isLocalSymlink ? 0 : fs.statSync(localPath).size;
-                // Capture the listing's ETag so subsequent syncs can detect remote
-                // drift independently of mtime drift. Stamp mtimeMs from localLstat
-                // (5.36.0) so the next push planner's lstat fast-path can skip the
-                // SHA256 for this file without reading its bytes.
-                //
-                // 5.37.0 ordering invariant: downloadFile applies hq-mtime via
-                // utimesSync AFTER its byte write but BEFORE returning, and this
-                // lstat runs AFTER downloadFile resolves — so localLstat.mtimeMs
-                // already reflects the source-stamped mtime, not the wall-clock
-                // write-time. The journal therefore matches what the next push's
-                // lstat fast-path will see, and the file is correctly skipped on
-                // re-sync instead of being hashed every tick. Do not move this
-                // lstat earlier; do not stamp the journal from any pre-download
-                // mtime.
-                updateEntry(journal, remoteFile.key, hash, size, "down", remoteFile.etag, localLstat.mtimeMs, createdBySub);
-                // Attach message from the prior journal entry if present (set by a
-                // previous `share` operation that included a --message).
-                const priorEntry = getEntry(journal, remoteFile.key);
-                const remoteJournalMessage = priorEntry?.message;
-                emit({
-                    type: "progress",
-                    path: remoteFile.key,
-                    bytes: size,
-                    ...(remoteJournalMessage ? { message: remoteJournalMessage } : {}),
-                    ...(author ? { author } : {}),
-                });
-                filesDownloaded++;
-                bytesDownloaded += size;
+                fs.rmSync(conflictAbs, { force: true });
             }
-            catch (err) {
-                // STS session policy may deny access to some paths — this is expected
-                // for guest members with allowedPrefixes
-                if (isAccessDenied(err)) {
-                    filesSkipped++;
-                }
-                else {
-                    emit({
-                        type: "error",
-                        path: remoteFile.key,
-                        message: err instanceof Error ? err.message : String(err),
-                    });
-                }
+            catch {
+                /* best-effort cleanup; a stray identical mirror is harmless */
             }
-        };
-        // Codex P1 (5.36.x): worker promises wrapped in .catch so an
-        // unhandled rejection inside downloadOne (e.g. refreshEntityContext
-        // before the per-item try/catch, or lstatSync after the download
-        // succeeded but before journal stamping) cannot escape
-        // `Promise.race(inFlight)` and unwind the drain mid-flight. Without
-        // this wrap, sibling downloads kept running after share()/sync()
-        // had already failed, their files materialized on disk without
-        // matching journal entries, and the next sync re-downloaded
-        // everything. Errors are collected and surfaced after the pool
-        // fully drains — see workerErrors throw below.
-        const workerErrors = [];
-        while (queue.length > 0 || inFlight.size > 0) {
-            while (inFlight.size < TRANSFER_CONCURRENCY && queue.length > 0) {
-                const downloadItem = queue.shift();
-                const p = downloadOne(downloadItem)
-                    .catch((err) => {
-                    workerErrors.push(err instanceof Error ? err : new Error(String(err)));
-                })
-                    .finally(() => {
-                    inFlight.delete(p);
+        }
+        updateEntry(run.journal, remoteFile.key, item.localHash, item.localSize, "down", remoteFile.etag, item.localMtime.getTime());
+        run.emit({ type: "reconciled", path: remoteFile.key, direction: "pull" });
+        counters.filesSkipped++;
+        return null;
+    }
+    counters.conflicts++;
+    counters.conflictPaths.push(remoteFile.key);
+    const resolution = await resolveConflict({
+        path: remoteFile.key,
+        localHash: item.localHash,
+        remoteModified: remoteFile.lastModified,
+        localModified: item.localMtime,
+        direction: "pull",
+    }, run.options.onConflict);
+    run.emit({
+        type: "conflict",
+        path: remoteFile.key,
+        direction: "pull",
+        resolution,
+    });
+    if (resolution !== "abort" && resolution !== "overwrite") {
+        if (remoteFetched) {
+            try {
+                appendConflictEntry(run.hqRoot, {
+                    id: buildConflictId(originalRelative, detectedAt),
+                    originalPath: originalRelative,
+                    conflictPath: conflictRelative,
+                    detectedAt,
+                    side: "pull",
+                    machineId,
+                    localHash: item.localHash,
+                    remoteHash: remoteFile.etag ? normalizeEtag(remoteFile.etag) : "",
                 });
-                inFlight.add(p);
             }
-            if (inFlight.size > 0) {
-                // Wait for at least one in-flight task to settle before topping up
-                // the pool. allSettled-style semantics via Promise.race — the
-                // .catch wrap above guarantees no worker promise can reject.
-                await Promise.race(Array.from(inFlight));
+            catch (mirrorErr) {
+                run.emit({
+                    type: "error",
+                    path: remoteFile.key,
+                    message: `conflict mirror index write failed: ${mirrorErr instanceof Error ? mirrorErr.message : String(mirrorErr)}`,
+                });
             }
         }
-        // Pool drained. If any worker rejected, write the journal first
-        // (so the lstat fast-path stamps for successfully-downloaded files
-        // persist) then throw the first error, preserving its stack.
-        if (workerErrors.length > 0) {
-            writeJournal(journalSlug, journal);
-            const first = workerErrors[0];
-            if (workerErrors.length > 1) {
-                first.message = `${first.message} (and ${workerErrors.length - 1} more download-worker errors)`;
-            }
-            throw first;
+    }
+    else if (remoteFetched) {
+        try {
+            fs.rmSync(conflictAbs, { force: true });
+        }
+        catch {
+            /* best-effort; a leftover mirror is cosmetic, not corrupting */
+        }
+    }
+    if (resolution === "abort") {
+        run.emit({ type: "new-files", files: [] });
+        writeJournal(run.journalSlug, run.journal);
+        return {
+            filesDownloaded: counters.filesDownloaded,
+            bytesDownloaded: counters.bytesDownloaded,
+            filesSkipped: counters.filesSkipped,
+            conflicts: counters.conflicts,
+            conflictPaths: counters.conflictPaths,
+            aborted: true,
+            newFiles: plan.newFiles,
+            newFilesCount: plan.newFilesCount,
+            filesExcludedByPolicy: plan.filesExcludedByPolicy,
+            filesTombstoned: 0,
+            filesOutOfScope: counters.filesOutOfScope,
+            scopeOrphansRemoved: scopeRun.scopeOrphansRemoved,
+            scopeOrphansBlocked: scopeRun.shrinkResult.dirtyTombstoned,
+        };
+    }
+    if (resolution === "keep" || resolution === "skip") {
+        counters.filesSkipped++;
+        updateEntry(run.journal, remoteFile.key, item.localHash, item.localSize, "down", remoteFile.etag, item.localMtime.getTime());
+        return null;
+    }
+    downloadItems.push({
+        action: "download",
+        remoteFile,
+        localPath,
+        isNew: false,
+    });
+    return null;
+}
+async function executeDownloadExecutor(run, downloadItems, transferConcurrency, counters) {
+    if (downloadItems.length === 0)
+        return;
+    await primeObjectTransport(run.ctx, "get", downloadItems.map((d) => d.remoteFile.key));
+    const queue = [...downloadItems];
+    const inFlight = new Set();
+    const workerErrors = [];
+    while (queue.length > 0 || inFlight.size > 0) {
+        while (inFlight.size < transferConcurrency && queue.length > 0) {
+            const downloadItem = queue.shift();
+            const p = downloadOne(run, downloadItem, counters)
+                .catch((err) => {
+                workerErrors.push(err instanceof Error ? err : new Error(String(err)));
+            })
+                .finally(() => {
+                inFlight.delete(p);
+            });
+            inFlight.add(p);
+        }
+        if (inFlight.size > 0) {
+            await Promise.race(Array.from(inFlight));
+        }
+    }
+    if (workerErrors.length > 0) {
+        writeJournal(run.journalSlug, run.journal);
+        const first = workerErrors[0];
+        if (workerErrors.length > 1) {
+            first.message = `${first.message} (and ${workerErrors.length - 1} more download-worker errors)`;
+        }
+        throw first;
+    }
+}
+async function downloadOne(run, downloadItem, counters) {
+    const { remoteFile, localPath } = downloadItem;
+    await refreshRunContextIfExpiring(run);
+    if (!isDownloadWritePathStillContained(run.companyRoot, remoteFile.key, localPath)) {
+        counters.filesSkipped++;
+        run.emit({
+            type: "error",
+            path: remoteFile.key,
+            message: "download skipped: local parent escaped the sync root",
+        });
+        return;
+    }
+    try {
+        const { metadata, contentHash, contentSize } = await downloadFile(run.ctx, remoteFile.key, localPath);
+        const author = metadata?.["created-by"] ?? null;
+        const createdBySub = metadata?.["created-by-sub"];
+        const localLstat = fs.lstatSync(localPath);
+        const isLocalSymlink = localLstat.isSymbolicLink();
+        const hash = isLocalSymlink
+            ? hashSymlinkTarget(fs.readlinkSync(localPath))
+            : (contentHash ?? hashFile(localPath));
+        const size = isLocalSymlink ? 0 : (contentSize ?? fs.statSync(localPath).size);
+        updateEntry(run.journal, remoteFile.key, hash, size, "down", remoteFile.etag, localLstat.mtimeMs, createdBySub);
+        const priorEntry = getEntry(run.journal, remoteFile.key);
+        const remoteJournalMessage = priorEntry?.message;
+        run.emit({
+            type: "progress",
+            path: remoteFile.key,
+            bytes: size,
+            ...(remoteJournalMessage ? { message: remoteJournalMessage } : {}),
+            ...(author ? { author } : {}),
+        });
+        counters.filesDownloaded++;
+        counters.bytesDownloaded += size;
+    }
+    catch (err) {
+        if (isAccessDenied(err)) {
+            counters.filesSkipped++;
+        }
+        else {
+            run.emit({
+                type: "error",
+                path: remoteFile.key,
+                message: err instanceof Error ? err.message : String(err),
+            });
         }
     }
-    // ── New-files attribution (US-002) ─────────────────────────────────────
-    // Enrich plan.newFiles with `addedBy` from S3 user metadata. HeadObject
-    // calls are best-effort and capped at 5 concurrent to avoid hammering S3.
+}
+async function emitAndReportNewFiles(run, plan) {
     const enrichedNewFiles = [];
+    // Batch-mint the GET presigns once (chunked, breaker-aware) so the per-file
+    // created-by HEADs below reuse the cache instead of each minting its own
+    // presign. Without this, a big catch-up pull (hundreds of new files) bursts
+    // the presign endpoint, trips the circuit breaker, and every enrichment HEAD
+    // then fails. Mirrors the tombstone HEAD-verify pre-prime.
+    await primeObjectTransport(run.ctx, "get", plan.newFiles.map((nf) => nf.path));
     const HEAD_CONCURRENCY = 5;
     for (let i = 0; i < plan.newFiles.length; i += HEAD_CONCURRENCY) {
         const batch = plan.newFiles.slice(i, i + HEAD_CONCURRENCY);
         const results = await Promise.all(batch.map(async (nf) => {
             let addedBy = null;
             try {
-                const head = await headRemoteFile(ctx, nf.path);
+                const head = await headRemoteFile(run.ctx, nf.path);
                 if (head?.metadata?.["created-by"]) {
                     addedBy = head.metadata["created-by"];
                 }
             }
             catch (headErr) {
-                // Best-effort: log to console (Sentry captures via global handler)
-                // and fall through with addedBy = null.
                 try {
                     console.error(`[hq-sync] HeadObject failed for ${nf.path}: ${headErr instanceof Error ? headErr.message : String(headErr)}`);
                 }
@@ -780,210 +600,124 @@ export async function sync(options) {
         }));
         enrichedNewFiles.push(...results);
     }
-    emit({ type: "new-files", files: enrichedNewFiles });
-    // Report new files to the notification service so they persist as a
-    // cross-session "new files" history in the HQ Sync app (POST
-    // /v1/notify/file-added → per-recipient FILE_EVENT rows for THIS user, who is
-    // the one the files are new for). Best-effort and bounded: a failure or a
-    // hung request must never delay or break the sync — the durable signal is the
-    // synced file itself, this is only a notification mirror.
-    await reportNewFilesToNotify(vaultConfig, ctx.uid, ctx.slug, enrichedNewFiles);
-    // Codex P1 (PR #24 follow-up): scope-gate tombstone candidates with
-    // a per-object HEAD before unlinking. `listRemoteFiles` is STS-scoped
-    // (guest sessions with `allowedPrefixes`, role downgrade, custom
-    // sync-mode prefix sets — see the AccessDenied branch in the download
-    // loop above), so a journal entry's absence from LIST does not prove
-    // the object was deleted; it may simply be invisible to this session.
-    // HEAD each candidate:
-    //   - HEAD returns metadata → object exists → NOT in our LIST scope →
-    //     skip the tombstone (peer didn't delete it; we just can't see it).
-    //   - HEAD returns null (NotFound) → confirmed deleted → tombstone.
-    //   - HEAD throws AccessDenied → can't tell → defensive skip; journal
-    //     stays so next sync (with broader scope) can re-evaluate.
-    //   - HEAD throws transient → defensive skip + emit error.
-    // Bounded concurrency mirrors the new-files attribution pass above.
-    if (plan.tombstones.length > 0) {
-        // Pre-mint GET URLs for the tombstone HEAD-verify probes below (headRemote
-        // File presigns a GET), so a large delete set doesn't add N presign calls.
-        await primeObjectTransport(ctx, "get", plan.tombstones);
-        const HEAD_VERIFY_CONCURRENCY = 5;
-        const verified = [];
-        for (let i = 0; i < plan.tombstones.length; i += HEAD_VERIFY_CONCURRENCY) {
-            const batch = plan.tombstones.slice(i, i + HEAD_VERIFY_CONCURRENCY);
-            const results = await Promise.all(batch.map(async (key) => {
-                try {
-                    const head = await headRemoteFile(ctx, key);
-                    return head === null ? key : null;
-                }
-                catch (err) {
-                    if (isAccessDenied(err))
-                        return null;
-                    emit({
-                        type: "error",
-                        path: key,
-                        message: `tombstone HEAD verify failed (deferring): ${err instanceof Error ? err.message : String(err)}`,
-                    });
+    run.emit({ type: "new-files", files: enrichedNewFiles });
+    await reportNewFilesToNotify(run.vaultConfig, run.ctx.uid, run.ctx.slug, enrichedNewFiles);
+}
+async function verifyPlannedJournalTombstones(run, plan) {
+    if (plan.tombstones.length === 0)
+        return;
+    await primeObjectTransport(run.ctx, "get", plan.tombstones);
+    const HEAD_VERIFY_CONCURRENCY = 5;
+    const verified = [];
+    for (let i = 0; i < plan.tombstones.length; i += HEAD_VERIFY_CONCURRENCY) {
+        const batch = plan.tombstones.slice(i, i + HEAD_VERIFY_CONCURRENCY);
+        const results = await Promise.all(batch.map(async (key) => {
+            try {
+                const head = await headRemoteFile(run.ctx, key);
+                return head === null ? key : null;
+            }
+            catch (err) {
+                if (isAccessDenied(err))
                     return null;
-                }
-            }));
-            for (const k of results) {
-                if (k !== null)
-                    verified.push(k);
+                run.emit({
+                    type: "error",
+                    path: key,
+                    message: `tombstone HEAD verify failed (deferring): ${err instanceof Error ? err.message : String(err)}`,
+                });
+                return null;
             }
+        }));
+        for (const k of results) {
+            if (k !== null)
+                verified.push(k);
         }
-        plan.tombstones = verified;
     }
-    // Bug #9 — apply cross-machine delete propagation. Each tombstone is a
-    // key the journal records as previously synced but the remote LIST no
-    // longer contains. We delete the local file (or symlink, or empty dir
-    // remnant) and drop the journal entry so the next sync's planner stays
-    // converged. Failures are reported but non-fatal — the entry stays in
-    // the journal and the next run retries.
+    plan.tombstones = verified;
+}
+function executeJournalTombstoneDeletes(run, plan, counters) {
     for (const key of plan.tombstones) {
-        // Last line of defense against the Windows backslash-key landmine: a
-        // malformed key must NEVER reach fs.unlinkSync. path.join(companyRoot, key)
-        // collapses the backslashes and resolves onto the REAL POSIX file, so
-        // unlinking here destroys live data (ridge incident, feedback_b8d09d0f).
-        // The planner already refuses to enqueue malformed keys; if one still
-        // arrives, drop the poisoned journal entry without touching disk —
-        // normalizeJournalKeys rewrites it to its POSIX form on load.
-        if (isMalformedVaultKey(key)) {
-            removeEntry(journal, key);
+        const localPath = resolveContainedVaultPath(run.companyRoot, key);
+        if (localPath === null)
             continue;
-        }
-        const localPath = path.join(companyRoot, key);
         let removedSomething = false;
         try {
             const lstat = fs.lstatSync(localPath);
+            if (tombstoneTargetDiverged(run.journal, key, localPath, lstat)) {
+                continue;
+            }
             if (lstat.isSymbolicLink() || lstat.isFile()) {
                 fs.unlinkSync(localPath);
                 removedSomething = true;
             }
             else if (lstat.isDirectory()) {
-                // A dir at a key — likely from a (local-dir, cloud-file) historic
-                // state. Don't recursively rm-rf the operator's dir; just drop
-                // the journal entry so we converge with reality.
+                // A dir at a key is converged by dropping only the journal entry.
             }
         }
         catch (err) {
             const code = err && typeof err === "object" && "code" in err
                 ? err.code
                 : undefined;
-            // ENOENT → local already gone; safe to drop the journal entry.
-            // Other errors (EACCES/EPERM/EBUSY/etc.) leave the local file in
-            // place — if we dropped the journal entry anyway, the pull side
-            // would forget the peer's delete and a later push could re-upload
-            // the still-present local file, silently undoing the peer's delete.
-            // Surface the error and KEEP the journal entry so the next sync
-            // retries the unlink after the operator fixes the permission.
             if (code !== "ENOENT") {
-                emit({
+                run.emit({
                     type: "error",
                     path: key,
                     message: `tombstone unlink failed: ${err instanceof Error ? err.message : String(err)}`,
                 });
-                // Skip removeEntry / filesTombstoned / progress event — the
-                // tombstone hasn't actually been honored. Next sync retries.
                 continue;
             }
         }
-        removeEntry(journal, key);
-        filesTombstoned++;
-        emit({
+        removeEntry(run.journal, key);
+        counters.filesTombstoned++;
+        run.emit({
             type: "progress",
             path: key,
             bytes: 0,
             deleted: true,
-            // Suffix differentiates a tombstone from a normal delete in the
-            // tty stream — matches the push-side `defaultConsoleLogger`
-            // tombstone surface in share.ts.
             message: removedSomething ? "tombstone (cross-machine delete)" : "tombstone (already absent locally)",
         });
     }
-    // Record this pull's boundary (US-005) so the NEXT pull can diff its scope
-    // against ours and detect a shrink. Append before the journal write so it
-    // persists. `prefixSet` is stored in the same company-relative namespace as
-    // the journal keys; `all` mode records `[""]` (covers everything).
-    appendPullRecord(journal, {
+}
+function finalizePullRun(run, plan, scopeRun, counters) {
+    appendPullRecord(run.journal, {
         pullId: generatePullId(),
-        companyUid: ctx.uid,
-        startedAt,
+        companyUid: run.ctx.uid,
+        startedAt: run.startedAt,
         completedAt: new Date().toISOString(),
-        syncMode,
-        prefixSet: currentPrefixSet,
-        scopeChangeDetected: shrinkPlan.scopeChangeDetected,
-        orphansRemoved: scopeOrphansRemoved,
-        orphansBlocked: shrinkResult.dirtyTombstoned,
+        syncMode: run.syncMode,
+        prefixSet: run.currentPrefixSet,
+        scopeChangeDetected: scopeRun.shrinkPlan.scopeChangeDetected,
+        orphansRemoved: scopeRun.scopeOrphansRemoved,
+        orphansBlocked: scopeRun.shrinkResult.dirtyTombstoned,
     });
-    // Stamp lastSync on every successful run so the menubar's "Last sync · X ago"
-    // ticks even when nothing transferred. updateEntry only fires on actual
-    // downloads; without this, a no-op sync leaves lastSync at the time of the
-    // last file change, which is misleading.
-    journal.lastSync = new Date().toISOString();
-    writeJournal(journalSlug, journal);
-    // When the pull actually changed on-disk sources (new files, tombstoned
-    // removals, or scope-orphan cleanups), refresh the generated skill wrappers,
-    // personal-overlay mirrors, and workers registry. reindex is idempotent and
-    // best-effort — it must never fail a sync, and is skipped on no-op syncs
-    // (the common daemon case) and when the caller opts out via skipReindex.
-    const changedOnDisk = filesDownloaded > 0 ||
-        filesTombstoned > 0 ||
-        scopeOrphansRemoved > 0;
-    if (!options.skipReindex && changedOnDisk) {
+    run.journal.lastSync = new Date().toISOString();
+    writeJournal(run.journalSlug, run.journal);
+    const changedOnDisk = counters.filesDownloaded > 0 ||
+        counters.filesTombstoned > 0 ||
+        scopeRun.scopeOrphansRemoved > 0;
+    if (!run.options.skipReindex && changedOnDisk) {
         try {
-            // skipLock: the surrounding sync run already holds this root's operation
-            // lock; reindex re-acquiring would refuse against our own live PID.
-            reindex({ repoRoot: hqRoot, skipLock: true });
+            reindex({ repoRoot: run.hqRoot, skipLock: true });
         }
         catch {
             // best-effort: a post-sync refresh failure never fails the sync
         }
     }
     return {
-        filesDownloaded,
-        bytesDownloaded,
-        filesSkipped,
-        conflicts,
-        conflictPaths,
+        filesDownloaded: counters.filesDownloaded,
+        bytesDownloaded: counters.bytesDownloaded,
+        filesSkipped: counters.filesSkipped,
+        conflicts: counters.conflicts,
+        conflictPaths: counters.conflictPaths,
         aborted: false,
         newFiles: plan.newFiles,
         newFilesCount: plan.newFilesCount,
         filesExcludedByPolicy: plan.filesExcludedByPolicy,
-        filesTombstoned,
-        filesOutOfScope,
-        scopeOrphansRemoved,
-        scopeOrphansBlocked: shrinkResult.dirtyTombstoned,
+        filesTombstoned: counters.filesTombstoned,
+        filesOutOfScope: counters.filesOutOfScope,
+        scopeOrphansRemoved: scopeRun.scopeOrphansRemoved,
+        scopeOrphansBlocked: scopeRun.shrinkResult.dirtyTombstoned,
     };
 }
-/**
- * Resolve active company from .hq/config.json.
- */
-function resolveActiveCompany(hqRoot) {
-    const configPath = path.join(hqRoot, ".hq", "config.json");
-    if (fs.existsSync(configPath)) {
-        try {
-            const config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
-            return config.activeCompany ?? config.companySlug;
-        }
-        catch {
-            // Ignore parse errors
-        }
-    }
-    return undefined;
-}
-/**
- * Returns true when the remote object appears to have moved since the
- * journal entry's last-recorded sync. Prefers ETag equality; falls back to
- * `lastModified > syncedAt` for legacy entries written before remoteEtag
- * was tracked. Conservative on tie (`<=` skews "remote unchanged").
- */
-function hasRemoteChanged(remote, entry) {
-    if (entry.remoteEtag) {
-        return normalizeEtag(remote.etag) !== entry.remoteEtag;
-    }
-    const syncedAt = new Date(entry.syncedAt).getTime();
-    return remote.lastModified.getTime() > syncedAt;
-}
 /**
  * Decide whether a remote object present in the LIST is a GENUINE RE-CREATE
  * written AFTER a FILE_TOMBSTONE — in which case the tombstone is stale and the
@@ -1012,6 +746,85 @@ function isRemoteRecreateAfterTombstone(remote, tombstone) {
         return true; // no remote timestamp → don't suppress
     return remoteMs > deletedAtMs;
 }
+function hasTraversalSegment(key) {
+    return key.split("/").some((segment) => segment === "..");
+}
+function isPathWithin(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return (relative === "" ||
+        (!relative.startsWith("..") && !path.isAbsolute(relative)));
+}
+function deepestExistingAncestor(start) {
+    let current = start;
+    for (;;) {
+        try {
+            fs.lstatSync(current);
+            return current;
+        }
+        catch (err) {
+            const code = err && typeof err === "object" && "code" in err
+                ? err.code
+                : undefined;
+            if (code !== "ENOENT" && code !== "ENOTDIR")
+                return null;
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+function resolveContainedVaultPath(root, key) {
+    if (isMalformedVaultKey(key) || hasTraversalSegment(key))
+        return null;
+    const resolvedRoot = path.resolve(root);
+    const resolvedLocal = path.resolve(resolvedRoot, key);
+    if (!isPathWithin(resolvedRoot, resolvedLocal))
+        return null;
+    let realRoot;
+    try {
+        realRoot = fs.realpathSync.native(resolvedRoot);
+    }
+    catch {
+        // If the vault root does not exist yet, no below-root symlink component can
+        // already exist to redirect this key. Preserve first-pull behavior.
+        return resolvedLocal;
+    }
+    const existingAncestor = deepestExistingAncestor(path.dirname(resolvedLocal));
+    if (existingAncestor === null)
+        return null;
+    try {
+        const realAncestor = fs.realpathSync.native(existingAncestor);
+        if (!isPathWithin(realRoot, realAncestor))
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return resolvedLocal;
+}
+function isDownloadWritePathStillContained(root, key, localPath) {
+    const resolved = resolveContainedVaultPath(root, key);
+    return resolved !== null && path.resolve(resolved) === path.resolve(localPath);
+}
+function tombstoneTargetDiverged(journal, key, localPath, lstat) {
+    const journalEntry = journal.files[key];
+    if (!journalEntry?.hash) {
+        return lstat.isSymbolicLink() || lstat.isFile();
+    }
+    try {
+        if (lstat.isSymbolicLink()) {
+            return hashSymlinkTarget(fs.readlinkSync(localPath)) !== journalEntry.hash;
+        }
+        if (lstat.isFile()) {
+            return hashFile(localPath) !== journalEntry.hash;
+        }
+    }
+    catch {
+        return true;
+    }
+    return false;
+}
 /**
  * Stage-1 planning pass: classify every remote file into download / skip /
  * conflict buckets without performing any S3 transfers. Local hashes are
@@ -1037,7 +850,11 @@ prefixSet,
 fileTombstones = new Map()) {
     const items = [];
     for (const remoteFile of remoteFiles) {
-        const localPath = path.join(companyRoot, remoteFile.key);
+        const localPath = resolveContainedVaultPath(companyRoot, remoteFile.key);
+        if (localPath === null) {
+            items.push({ action: "skip-excluded-policy", remoteFile, localPath: companyRoot });
+            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
@@ -1048,16 +865,6 @@ fileTombstones = new Map()) {
             items.push({ action: "skip-excluded-policy", remoteFile, localPath });
             continue;
         }
-        // Malformed-key filter — keys with backslash separators pushed by
-        // pre-5.47.2 Windows clients. Downloading one materializes a junk local
-        // file whose NAME contains backslashes (it is not a path on POSIX), which
-        // then churns conflict mirrors forever. Refuse at planning time, same
-        // policy bucket as the ephemeral filter above. The bogus keys themselves
-        // are cleaned server-side; this keeps clean trees clean in the meantime.
-        if (isMalformedVaultKey(remoteFile.key)) {
-            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
@@ -1403,12 +1210,8 @@ fileTombstones = new Map()) {
         const posixKey = toPosixKey(key);
         if (remoteKeySet.has(posixKey))
             continue;
-        // Never tombstone-delete via a malformed (backslash) key: the executor's
-        // path.join(companyRoot, key) collapses backslashes back onto the REAL
-        // POSIX file and unlinks live data. Leave it for normalizeJournalKeys to
-        // rewrite to POSIX on the next write; the canonical key is re-evaluated
-        // (and correctly tombstoned if genuinely remote-deleted) on a later pull.
-        if (isMalformedVaultKey(key))
+        const localPath = resolveContainedVaultPath(companyRoot, key);
+        if (localPath === null)
             continue;
         // PersonalMode key gating — mirror the download branch.
         if (personalMode && key.startsWith("companies/")) {
@@ -1424,7 +1227,6 @@ fileTombstones = new Map()) {
         // Honor the current ignore filter — if a path was previously synced
         // but is now ignored (operator edited .hqignore), do NOT delete
         // the local copy. They're keeping it deliberately.
-        const localPath = path.join(companyRoot, key);
         if (!shouldSync(localPath, false) && !shouldSync(localPath, true))
             continue;
         // Codex P1 (PR #24 round 3): detect local edits before tombstoning.
@@ -1497,15 +1299,6 @@ fileTombstones = new Map()) {
         tombstones,
     };
 }
-/**
- * Check if an error is an S3 access denied (expected for filtered guests).
- */
-function isAccessDenied(err) {
-    if (err && typeof err === "object" && "name" in err) {
-        return err.name === "AccessDenied" || err.name === "Forbidden";
-    }
-    return false;
-}
 /**
  * Default human-readable event rendering. Preserves the exact output format
  * that `hq sync` emitted before SyncProgressEvent was introduced, so callers