@indigoai-us/hq-cloud 6.11.12 → 6.11.14

package/src/cli/sync.ts

@@ -7,9 +7,14 @@
 
 import * as fs from "fs";
 import * as path from "path";
-import type { VaultServiceConfig, SyncJournal } from "../types.js";
+import type {
+  EntityContext,
+  VaultServiceConfig,
+  SyncJournal,
+} from "../types.js";
 import type { SyncMode } from "../vault-client.js";
 import { resolveEntityContext, isExpiringSoon, refreshEntityContext } from "../context.js";
+import { createSyncProgressRecorder } from "../sync-progress.js";
 import {
   downloadFile,
   listRemoteFiles,
@@ -49,6 +54,12 @@ import {
   type ScopePrefixInput,
 } 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 type { ConflictStrategy, ConflictResolution } from "./conflict.js";
@@ -489,6 +500,52 @@ export interface SyncResult {
   scopeOrphansBlocked: number;
 }
 
+type SyncEventEmitter = (event: SyncProgressEvent) => void;
+
+type PullDownloadItem = Extract<PullPlanItem, { action: "download" }>;
+
+interface PullRunContext {
+  options: SyncOptions;
+  companyRef: string;
+  vaultConfig: VaultServiceConfig;
+  hqRoot: string;
+  emit: SyncEventEmitter;
+  ctx: EntityContext;
+  companyRoot: string;
+  shouldSync: (filePath: string, isDir?: boolean) => boolean;
+  journalSlug: string;
+  startedAt: string;
+  journal: SyncJournal;
+  remoteFiles: RemoteFile[];
+  syncMode: SyncMode;
+  currentPrefixSet: string[];
+  fileTombstones: ReadonlyMap<string, CompanyTombstone>;
+}
+
+interface PullCounters {
+  filesDownloaded: number;
+  bytesDownloaded: number;
+  filesSkipped: number;
+  conflicts: number;
+  filesTombstoned: number;
+  filesOutOfScope: number;
+  conflictPaths: string[];
+}
+
+interface ScopeShrinkPlanState {
+  lastRecord: ReturnType<typeof lastPullRecord>;
+  shrinkPlan: ReturnType<typeof buildScopeShrinkPlan>;
+  autoRecover: boolean;
+  adviceContext: ScopeShrinkAdviceContext;
+  effectiveForce: boolean;
+}
+
+interface ScopeShrinkRun {
+  shrinkPlan: ReturnType<typeof buildScopeShrinkPlan>;
+  shrinkResult: ReturnType<typeof applyScopeShrink>;
+  scopeOrphansRemoved: number;
+}
+
 /**
  * Resolve the auto-prune safety cap (US-005 bulk-delete guard). An automatic
  * scope shrink that would delete more than this many CLEAN local files in one
@@ -616,10 +673,55 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
 async function syncWithOperationLockHeld(
   options: SyncOptions,
 ): Promise<SyncResult> {
-  const { company, onConflict, vaultConfig, hqRoot } = options;
-  const emit = options.onEvent ?? defaultConsoleLogger;
+  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: SyncOptions): Promise<PullRunContext> {
+  const { company, vaultConfig, hqRoot } = options;
+  const baseEmit = options.onEvent ?? defaultConsoleLogger;
+  // Mirror every progress event into the shared cross-process snapshot so the
+  // menubar shows live progress for THIS sync regardless of who launched it
+  // (auto-sync / Sync Now / CLI). Best-effort; never affects the sync.
+  const recordProgress = createSyncProgressRecorder({
+    company: company ?? null,
+    phase: "pull",
+  });
+  const emit: SyncEventEmitter = (event) => {
+    baseEmit(event);
+    recordProgress(event);
+  };
 
-  // Resolve company
   const companyRef = company ?? resolveActiveCompany(hqRoot);
   if (!companyRef) {
     throw new Error(
@@ -628,184 +730,131 @@ async function syncWithOperationLockHeld(
     );
   }
 
-  // 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: SyncMode = options.syncMode ?? "all";
-  const currentPrefixSet =
+  const currentPrefixSet: string[] =
     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: string[] = [];
 
-  // 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 =
+  const fileTombstones =
     options.personalMode === true
       ? new Map<string, CompanyTombstone>()
       : 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,
+  return {
+    options,
+    companyRef,
+    vaultConfig,
+    hqRoot,
+    emit,
+    ctx,
     companyRoot,
     shouldSync,
-    options.personalMode === true,
-    options.includeLocalCompanies === true,
-    options.teamSyncedSlugs ?? null,
+    journalSlug,
+    startedAt,
+    journal,
+    remoteFiles,
+    syncMode,
     currentPrefixSet,
-    tombstones,
+    fileTombstones,
+  };
+}
+
+function planPull(run: PullRunContext): PullPlan {
+  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: SyncEventEmitter, plan: PullPlan): void {
   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(): PullCounters {
+  return {
+    filesDownloaded: 0,
+    bytesDownloaded: 0,
+    filesSkipped: 0,
+    conflicts: 0,
+    filesTombstoned: 0,
+    filesOutOfScope: 0,
+    conflictPaths: [],
+  };
+}
+
+function planScopeShrink(run: PullRunContext): ScopeShrinkPlanState {
+  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: ScopeShrinkAdviceContext = 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: PullRunContext,
+  scopePlan: ScopeShrinkPlanState,
+): ScopeShrinkRun {
+  const { lastRecord, shrinkPlan, adviceContext, effectiveForce } = scopePlan;
 
   if (shrinkPlan.dirty.length > 0 && !effectiveForce) {
     throw new ScopeShrinkBlockedError(
-      ctx.uid,
+      run.ctx.uid,
       lastRecord?.syncMode ?? "unknown",
-      syncMode,
+      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 &&
@@ -813,40 +862,32 @@ async function syncWithOperationLockHeld(
     shrinkPlan.clean.length > autoPruneCap
   ) {
     throw new ScopeShrinkLargePruneError(
-      ctx.uid,
-      syncMode,
+      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,
+    run.hqRoot,
     ".hq",
     "scope-quarantine",
-    journalSlug,
+    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,
@@ -855,7 +896,7 @@ async function syncWithOperationLockHeld(
     });
   }
   for (const relPath of shrinkResult.removedPaths) {
-    emit({
+    run.emit({
       type: "progress",
       path: relPath,
       bytes: 0,
@@ -864,7 +905,7 @@ async function syncWithOperationLockHeld(
     });
   }
   for (const relPath of shrinkResult.dirtyKeptPaths) {
-    emit({
+    run.emit({
       type: "progress",
       path: relPath,
       bytes: 0,
@@ -872,547 +913,410 @@ async function syncWithOperationLockHeld(
         "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.
-  const downloadItems: Array<typeof plan.items[number] & { action: "download" }> = [];
-  let aborted = false;
-  let abortResult: SyncResult | null = null;
+
+  return {
+    shrinkPlan,
+    shrinkResult,
+    scopeOrphansRemoved:
+      shrinkResult.cleanRemoved + shrinkResult.cleanQuarantined,
+  };
+}
+
+async function refreshRunContextIfExpiring(
+  run: PullRunContext,
+): Promise<void> {
+  if (isExpiringSoon(run.ctx.expiresAt)) {
+    run.ctx = await refreshEntityContext(run.companyRef, run.vaultConfig);
+  }
+}
+
+async function executeConflictExecutor(
+  run: PullRunContext,
+  plan: PullPlan,
+  scopeRun: ScopeShrinkRun,
+  counters: PullCounters,
+): Promise<{ downloadItems: PullDownloadItem[]; abortResult: SyncResult | null }> {
+  const downloadItems: PullDownloadItem[] = [];
 
   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). Traversal keys are likewise
-      // refused before any local filesystem or journal mutation.
-      const tombstonePath = resolveContainedVaultPath(companyRoot, tombstoneKey);
-      if (tombstonePath === null) continue;
-      try {
-        const lstat = fs.lstatSync(tombstonePath);
-        if (tombstoneTargetDiverged(journal, tombstoneKey, tombstonePath, lstat)) {
-          continue;
-        }
-        if (lstat.isSymbolicLink() || lstat.isFile()) {
-          fs.unlinkSync(tombstonePath);
-        }
-        // 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: unknown) {
-        const code =
-          err && typeof err === "object" && "code" in err
-            ? (err as { code?: string }).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;
+    const abortResult = await executeConflictItem(
+      run,
+      plan,
+      scopeRun,
+      counters,
+      downloadItems,
+      item,
+    );
+    if (abortResult) {
+      return { downloadItems, abortResult };
+    }
+  }
+
+  return { downloadItems, abortResult: null };
+}
 
-    // 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);
+function executeFileTombstoneDelete(
+  run: PullRunContext,
+  item: Extract<PullPlanItem, { action: "tombstone-delete" }>,
+  counters: PullCounters,
+): void {
+  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: unknown) {
+    const code =
+      err && typeof err === "object" && "code" in err
+        ? (err as { code?: string }).code
+        : undefined;
+    if (code !== "ENOENT") {
+      run.emit({
+        type: "error",
+        path: tombstoneKey,
+        message: `tombstone-suppress unlink failed: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      });
+      return;
+    }
+  }
+  removeEntry(run.journal, tombstoneKey);
+  counters.filesTombstoned++;
+  run.emit({ type: "progress", path: tombstoneKey, bytes: 0 });
+}
 
-    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);
-      const conflictKey = toPosixKey(path.relative(companyRoot, conflictAbs));
+async function executeConflictItem(
+  run: PullRunContext,
+  plan: PullPlan,
+  scopeRun: ScopeShrinkRun,
+  counters: PullCounters,
+  downloadItems: PullDownloadItem[],
+  item: Extract<PullPlanItem, { action: "conflict" }>,
+): Promise<SyncResult | null> {
+  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;
+  }
 
-      if (!isDownloadWritePathStillContained(companyRoot, conflictKey, conflictAbs)) {
-        filesSkipped++;
-        emit({
-          type: "error",
-          path: remoteFile.key,
-          message: "conflict mirror skipped: local parent escaped the sync root",
-        });
-        continue;
-      }
+  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;
+  } catch (probeErr) {
+    run.emit({
+      type: "error",
+      path: remoteFile.key,
+      message: `conflict convergence probe failed: ${
+        probeErr instanceof Error ? probeErr.message : String(probeErr)
+      }`,
+    });
+  }
 
-      let remoteFetched = false;
-      let converged = false;
+  if (converged) {
+    if (remoteFetched) {
       try {
-        const downloaded = 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))
-          : (downloaded.contentHash ?? 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)
-          }`,
-        });
+        fs.rmSync(conflictAbs, { force: true });
+      } catch {
+        /* best-effort cleanup; a stray identical mirror is harmless */
       }
+    }
+    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;
+  }
 
-      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;
-      }
+  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,
+  );
 
-      // ── Genuine divergence ───────────────────────────────────────────
-      conflicts++;
-      conflictPaths.push(remoteFile.key);
+  run.emit({
+    type: "conflict",
+    path: remoteFile.key,
+    direction: "pull",
+    resolution,
+  });
 
-      const resolution = await resolveConflict(
-        {
-          path: remoteFile.key,
+  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,
-          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;
+          remoteHash: remoteFile.etag ? normalizeEtag(remoteFile.etag) : "",
+        });
+      } catch (mirrorErr) {
+        run.emit({
+          type: "error",
+          path: remoteFile.key,
+          message: `conflict mirror index write failed: ${
+            mirrorErr instanceof Error ? mirrorErr.message : String(mirrorErr)
+          }`,
+        });
       }
-      // "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,
-      });
-      continue;
+    }
+  } else if (remoteFetched) {
+    try {
+      fs.rmSync(conflictAbs, { force: true });
+    } catch {
+      /* best-effort; a leftover mirror is cosmetic, not corrupting */
     }
   }
 
-  // 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;
+  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,
+    };
   }
 
-  // ── 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),
+  if (resolution === "keep" || resolution === "skip") {
+    counters.filesSkipped++;
+    updateEntry(
+      run.journal,
+      remoteFile.key,
+      item.localHash,
+      item.localSize,
+      "down",
+      remoteFile.etag,
+      item.localMtime.getTime(),
     );
+    return null;
+  }
 
-    const queue = [...downloadItems];
-    const inFlight: Set<Promise<unknown>> = new Set();
+  downloadItems.push({
+    action: "download",
+    remoteFile,
+    localPath,
+    isNew: false,
+  });
+  return null;
+}
 
-    const downloadOne = async (
-      downloadItem: typeof downloadItems[number],
-    ): Promise<void> => {
-      const { remoteFile, localPath } = downloadItem;
+async function executeDownloadExecutor(
+  run: PullRunContext,
+  downloadItems: PullDownloadItem[],
+  transferConcurrency: number,
+  counters: PullCounters,
+): Promise<void> {
+  if (downloadItems.length === 0) return;
 
-      // 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);
-      }
+  await primeObjectTransport(
+    run.ctx,
+    "get",
+    downloadItems.map((d) => d.remoteFile.key),
+  );
 
-      if (!isDownloadWritePathStillContained(companyRoot, remoteFile.key, localPath)) {
-        filesSkipped++;
-        emit({
-          type: "error",
-          path: remoteFile.key,
-          message: "download skipped: local parent escaped the sync root",
+  const queue = [...downloadItems];
+  const inFlight: Set<Promise<unknown>> = new Set();
+  const workerErrors: Error[] = [];
+
+  while (queue.length > 0 || inFlight.size > 0) {
+    while (inFlight.size < transferConcurrency && queue.length > 0) {
+      const downloadItem = queue.shift()!;
+      const p: Promise<void> = downloadOne(run, downloadItem, counters)
+        .catch((err: unknown) => {
+          workerErrors.push(err instanceof Error ? err : new Error(String(err)));
+        })
+        .finally(() => {
+          inFlight.delete(p);
         });
-        return;
-      }
+      inFlight.add(p);
+    }
+    if (inFlight.size > 0) {
+      await Promise.race(Array.from(inFlight));
+    }
+  }
 
-      try {
-        const { metadata, contentHash, contentSize } = 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))
-          : (contentHash ?? hashFile(localPath));
-        const size = isLocalSymlink ? 0 : (contentSize ?? 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,
-        );
+  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;
+  }
+}
 
-        // 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 as { message?: string } | undefined)?.message;
-        emit({
-          type: "progress",
-          path: remoteFile.key,
-          bytes: size,
-          ...(remoteJournalMessage ? { message: remoteJournalMessage } : {}),
-          ...(author ? { author } : {}),
-        });
+async function downloadOne(
+  run: PullRunContext,
+  downloadItem: PullDownloadItem,
+  counters: PullCounters,
+): Promise<void> {
+  const { remoteFile, localPath } = downloadItem;
 
-        filesDownloaded++;
-        bytesDownloaded += size;
-      } 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),
-          });
-        }
-      }
-    };
+  await refreshRunContextIfExpiring(run);
 
-    // 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: Error[] = [];
-    while (queue.length > 0 || inFlight.size > 0) {
-      while (inFlight.size < TRANSFER_CONCURRENCY && queue.length > 0) {
-        const downloadItem = queue.shift()!;
-        const p: Promise<void> = downloadOne(downloadItem)
-          .catch((err: unknown) => {
-            workerErrors.push(err instanceof Error ? err : new Error(String(err)));
-          })
-          .finally(() => {
-            inFlight.delete(p);
-          });
-        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));
-      }
-    }
+  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;
+  }
 
-    // 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;
+  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 as { message?: string } | undefined)?.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: PullRunContext,
+  plan: PullPlan,
+): Promise<void> {
   const enrichedNewFiles: Array<{ path: string; bytes: number; addedBy: string | null }> = [];
+  // 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);
@@ -1420,13 +1324,11 @@ async function syncWithOperationLockHeld(
       batch.map(async (nf) => {
         let addedBy: string | null = 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}: ${
@@ -1442,220 +1344,150 @@ async function syncWithOperationLockHeld(
     );
     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: string[] = [];
-    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)
-              }`,
-            });
-            return null;
-          }
-        }),
-      );
-      for (const k of results) {
-        if (k !== null) verified.push(k);
-      }
+  run.emit({ type: "new-files", files: enrichedNewFiles });
+  await reportNewFilesToNotify(
+    run.vaultConfig,
+    run.ctx.uid,
+    run.ctx.slug,
+    enrichedNewFiles,
+  );
+}
+
+async function verifyPlannedJournalTombstones(
+  run: PullRunContext,
+  plan: PullPlan,
+): Promise<void> {
+  if (plan.tombstones.length === 0) return;
+
+  await primeObjectTransport(run.ctx, "get", plan.tombstones);
+
+  const HEAD_VERIFY_CONCURRENCY = 5;
+  const verified: string[] = [];
+  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;
+          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;
   }
+  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.
+function executeJournalTombstoneDeletes(
+  run: PullRunContext,
+  plan: PullPlan,
+  counters: PullCounters,
+): void {
   for (const key of plan.tombstones) {
-    // Last line of defense: a malformed or traversal key must NEVER reach
-    // fs.unlinkSync or journal mutation for a path outside the sync root.
-    const localPath = resolveContainedVaultPath(companyRoot, key);
+    const localPath = resolveContainedVaultPath(run.companyRoot, key);
     if (localPath === null) continue;
     let removedSomething = false;
     try {
       const lstat = fs.lstatSync(localPath);
-      if (tombstoneTargetDiverged(journal, key, localPath, lstat)) {
+      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: unknown) {
       const code =
         err && typeof err === "object" && "code" in err
           ? (err as { code?: string }).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: PullRunContext,
+  plan: PullPlan,
+  scopeRun: ScopeShrinkRun,
+  counters: PullCounters,
+): SyncResult {
+  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.
+  run.journal.lastSync = new Date().toISOString();
+  writeJournal(run.journalSlug, run.journal);
+
   const changedOnDisk =
-    filesDownloaded > 0 ||
-    filesTombstoned > 0 ||
-    scopeOrphansRemoved > 0;
-  if (!options.skipReindex && 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: string): string | undefined {
-  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: { lastModified: Date; etag: string },
-  entry: { syncedAt: string; remoteEtag?: string },
-): boolean {
-  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
@@ -2355,16 +2187,6 @@ function computePullPlan(
   };
 }
 
-/**
- * Check if an error is an S3 access denied (expected for filtered guests).
- */
-function isAccessDenied(err: unknown): boolean {
-  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