@indigoai-us/hq-cloud 6.11.11 → 6.11.13

package/src/cli/share.ts

@@ -46,7 +46,17 @@ import {
   fetchCompanyTombstones,
   type CompanyTombstone,
 } from "./tombstones.js";
-import { isCoveredByAny, isDirInScope } from "../prefix-coalesce.js";
+import {
+  isCoveredByAny,
+  isDirInScope,
+  type ScopePrefixInput,
+} from "../prefix-coalesce.js";
+import {
+  hasRemoteChanged,
+  isAccessDenied,
+  resolveActiveCompany,
+  resolveTransferConcurrency,
+} from "../sync-core.js";
 import {
   buildConflictId,
   buildConflictPath,
@@ -637,7 +647,7 @@ export interface ShareOptions {
    * filter — full access. An empty array means "no granted prefixes" → every
    * path is out of scope (mirrors the pull side's `isCoveredByAny([])`).
    */
-  prefixSet?: string[];
+  prefixSet?: ScopePrefixInput[];
   /**
    * Pre-fetched FILE_TOMBSTONE map (POSIX key → tombstone) for the push-side
    * delete-resync consult. When omitted, share() fetches it itself via
@@ -732,21 +742,6 @@ export interface ShareResult {
   aborted: boolean;
 }
 
-/**
- * Is this error the S3/STS "access denied" class? Expected when a scoped
- * member/guest credential touches a key outside its granted ACL prefixes
- * (the server's `SCOPE_EXCEEDS_PARENT` surfaces as a 403 AccessDenied /
- * Forbidden). Mirrors the pull-side `isAccessDenied` in sync.ts so the push
- * leg can treat a stray out-of-scope key as a skip rather than a fatal throw.
- */
-function isAccessDenied(err: unknown): boolean {
-  if (err && typeof err === "object" && "name" in err) {
-    const name = (err as { name?: unknown }).name;
-    return name === "AccessDenied" || name === "Forbidden";
-  }
-  return false;
-}
-
 /**
  * A conditional-write fence rejection — the SDK's 412 (`name:
  * "PreconditionFailed"`) or the presigned transport's mirror of it. Means
@@ -778,7 +773,7 @@ function isPreconditionFailed(err: unknown): boolean {
 function wrapFilterWithScope(
   underlying: (absPath: string, isDir?: boolean) => boolean,
   syncRoot: string,
-  prefixSet: readonly string[],
+  prefixSet: readonly ScopePrefixInput[],
   onScopeExcluded: (rel: string) => void,
 ): (absPath: string, isDir?: boolean) => boolean {
   return (absPath: string, isDir?: boolean) => {
@@ -800,23 +795,99 @@ function wrapFilterWithScope(
  * Share local file(s) to the entity vault.
  */
 export async function share(options: ShareOptions): Promise<ShareResult> {
+  const run = await createPushRunContext(options);
+  const counters = createShareCounters();
+  const filesRefusedStalePaths: string[] = [];
+  const conflictPaths: string[] = [];
+
+  const plans = await buildSharePlans(run);
+  const uploadResult = await executeUploads(
+    run,
+    plans.pushPlan,
+    counters,
+    conflictPaths,
+  );
+  if (uploadResult.aborted) {
+    return buildShareResult(
+      run,
+      counters,
+      filesRefusedStalePaths,
+      uploadResult.abortFlightConflictPaths,
+      true,
+    );
+  }
+
+  await executeDeletes(
+    run,
+    plans.deletePlan,
+    plans.decommissionPlan,
+    counters,
+    filesRefusedStalePaths,
+  );
+  finalizeShareJournal(run);
+  throwUploadWorkerErrors(uploadResult.workerErrors);
+
+  return buildShareResult(run, counters, filesRefusedStalePaths, conflictPaths, false);
+}
+
+type DeletePolicy = NonNullable<ShareOptions["propagateDeletePolicy"]>;
+type ShareEmit = (event: SyncProgressEvent) => void;
+type UploadPlanItem = Extract<PushPlanItem, { action: "upload" }>;
+type JournalFileEntry = SyncJournal["files"][string];
+
+interface PushRunContext {
+  options: ShareOptions;
+  paths: string[];
+  message?: string;
+  onConflict?: ConflictStrategy;
+  vaultConfig?: VaultServiceConfig;
+  entityContext?: EntityContext;
+  hqRoot: string;
+  skipUnchanged?: boolean;
+  propagateDeletes?: boolean;
+  propagateDeletePolicy: DeletePolicy;
+  emit: ShareEmit;
+  companyRef: string;
+  ctx: EntityContext;
+  syncRoot: string;
+  shouldSync: (filePath: string, isDir?: boolean) => boolean;
+  journalSlug: string;
+  journal: SyncJournal;
+  excludedSet: Set<string>;
+  excludedById: Record<string, number>;
+  scopeExcludedSet: Set<string>;
+}
+
+interface ShareCounters {
+  filesUploaded: number;
+  bytesUploaded: number;
+  filesSkipped: number;
+  filesDeleted: number;
+  filesTombstoned: number;
+  filesRefusedStale: number;
+  filesSuppressedByTombstone: number;
+}
+
+interface SharePlans {
+  pushPlan: PushPlan;
+  deletePlan: DeletePlan;
+  decommissionPlan: string[];
+}
+
+interface UploadExecutionResult {
+  aborted: boolean;
+  abortFlightConflictPaths: string[];
+  workerErrors: Error[];
+}
+
+const REFUSED_STALE_PATH_CAP = 50;
+
+async function createPushRunContext(options: ShareOptions): Promise<PushRunContext> {
   const { paths, company, message, onConflict, vaultConfig, entityContext, hqRoot, skipUnchanged, propagateDeletes } = options;
-  // Default to "owned-only" — the pre-5.24 behavior — when delete-propagation
-  // is on but the caller hasn't pinned a policy. Staged-default rollout
-  // (see CHANGELOG / PR for hq-cloud 5.24.0): 5.24 ships the currency-gated
-  // CODE PATH plus the conflict-mirror exclusion (which is policy-
-  // independent and immediately stops new litter), but holds the default
-  // flip to a later release after soak. Opt into the safer policy now via
-  // `propagateDeletePolicy: "currency-gated"` (explicit) or
-  // `HQ_SYNC_DELETE_POLICY=currency-gated` (env, honored by sync-runner).
-  // The default flip to `"currency-gated"` is scheduled for 5.25.0.
-  let propagateDeletePolicy: "currency-gated" | "owned-only" | "all" =
+  let propagateDeletePolicy: DeletePolicy =
     options.propagateDeletePolicy ?? "owned-only";
   const emit = options.onEvent ?? defaultConsoleLogger;
 
-  // Exactly-one-of contract: either we vend (vaultConfig) or the caller did
-  // (entityContext). Both supplied is ambiguous (which credentials win?), and
-  // neither leaves us with no way to talk to S3.
   if (vaultConfig && entityContext) {
     throw new Error(
       "share() requires exactly one of `vaultConfig` or `entityContext`, not both. " +
@@ -830,9 +901,6 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
     );
   }
 
-  // Resolve company — slug, UID, or from active config. When the caller
-  // provided a pre-resolved entityContext, prefer its slug as the canonical
-  // ref (the caller already knows what entity these creds are for).
   const companyRef =
     company ?? entityContext?.slug ?? resolveActiveCompany(hqRoot);
   if (!companyRef) {
@@ -842,67 +910,18 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
     );
   }
 
-  // Resolve entity context. Two paths:
-  //   1. vaultConfig provided → resolveEntityContext does the lookup + STS vend
-  //      (cached + auto-refreshable mid-run).
-  //   2. entityContext provided → use it directly. No lookup, no vending,
-  //      no auto-refresh (we have no Cognito token to re-vend with).
-  //      Caller is responsible for vending credentials with enough TTL to
-  //      cover the run; if they under-vend, the AWS SDK surfaces ExpiredToken
-  //      naturally on the first failing PUT.
-  let ctx: EntityContext = entityContext
+  const ctx: EntityContext = entityContext
     ? entityContext
     : await resolveEntityContext(companyRef, vaultConfig!);
 
-  // Personal-vault policy correction (6.0.1). The `owned-only` rule encodes a
-  // multi-user curation premise — "don't tombstone peer-uploaded content even
-  // if my journal says I pulled it" — which is meaningful when several humans
-  // share a company bucket (a behind machine's first sync must not erase
-  // recent uploads from peers). On a personal vault that premise collapses:
-  // every file is the same human's content, just routed through different
-  // machines, and `direction: "down"` only means "uploaded from my laptop,
-  // pulled by my EC2" — it never means "uploaded by someone else." With
-  // `owned-only` in effect, `rm <file>` followed by `hq sync` silently fails
-  // to propagate the delete, leaving permanent vault litter (the May-27
-  // `personal/.obsidian/*.drift-*` files were diagnosed exactly this way).
-  // The etag-based `currency-gated` policy already captures the only safety
-  // intent that survives the single-user case ("don't tombstone if remote
-  // drifted since I last synced"); coerce to it here so the policy is right
-  // regardless of which caller's default landed. Explicit `"all"` is
-  // preserved — it's the emergency-reconcile opt-out and the caller has
-  // already asserted intent.
   if (ctx.uid.startsWith("prs_") && propagateDeletePolicy === "owned-only") {
     propagateDeletePolicy = "currency-gated";
   }
 
-  // Remote keys are company-relative; the on-disk scoping prefix is
-  // companies/{slug}/. Anything outside this folder gets skipped to avoid
-  // leaking cross-company state into the vault.
-  //
-  // In personalMode the syncRoot is `hqRoot` itself — remote keys are
-  // hq-root-relative to match the Rust personal first-push (which uploads
-  // every non-excluded top-level dir under ~/HQ). The exclusion list is
-  // enforced upstream by the runner; share() just trusts `paths`.
   const syncRoot = options.personalMode === true
     ? hqRoot
     : path.join(hqRoot, "companies", ctx.slug);
 
-  // Personal-vault default exclusions (introduced in 5.25): wrap the base
-  // ignore filter so paths matching `PERSONAL_VAULT_DEFAULT_EXCLUSIONS` are
-  // rejected before they upload OR enter the delete plan. Refuses & warns —
-  // an already-leaked remote object stays put as an orphan; a separate one-
-  // shot purge handles legacy litter.
-  //
-  // Out-of-policy hits are deduplicated in `excludedSet` so the same path
-  // hitting the filter from both the upload walk and the delete-plan walk
-  // counts once. `excludedById` powers the per-rule breakdown on the
-  // `personal-vault-out-of-policy` event so UI can render which class
-  // (secret / machine-local / scratch / …) did the work.
-  //
-  // Company-mode syncs skip this wrap entirely — company vaults have their
-  // own first-push protection (settings/, data/, workers/, .git/) defined
-  // in hq-sync's Rust util/ignore.rs, and a company may legitimately ship
-  // `output/` or `.env*` paths inside its `companies/{slug}/data/` folder.
   const ignoreFilter = createIgnoreFilter(hqRoot);
   const excludedSet = new Set<string>();
   const excludedById: Record<string, number> = {};
@@ -911,12 +930,6 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
     excludedSet.add(rel);
     excludedById[match.id] = (excludedById[match.id] ?? 0) + 1;
   };
-  // ACL scope filter (member/guest scoped push). The vended child credential
-  // is scoped to `options.prefixSet`; any candidate outside those prefixes
-  // would draw the server's correct 403 SCOPE_EXCEEDS_PARENT on PUT and abort
-  // the whole company. Pre-filter the plan to the granted subset instead —
-  // the push-side analogue of the pull leg's `skip-out-of-scope` (US-005).
-  // `undefined` = owner/`all` → no scope filter (full access).
   const scopeExcludedSet = new Set<string>();
   const onScopeExcluded = (rel: string) => {
     scopeExcludedSet.add(rel);
@@ -928,124 +941,93 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
     ? wrapFilterWithScope(baseFilter, syncRoot, options.prefixSet, onScopeExcluded)
     : baseFilter;
   const journalSlug = options.journalSlug ?? ctx.slug;
-  // Seed the canonical personal-vault journal from the legacy `personal` file
-  // exactly once — engine-side so every consumer (sync-runner, hq-cli) gets
-  // it; see the matching guard in sync.ts.
   if (journalSlug === PERSONAL_VAULT_JOURNAL_SLUG) migratePersonalVaultJournal();
   const journal = readJournal(journalSlug);
 
-  let filesUploaded = 0;
-  let bytesUploaded = 0;
-  let filesSkipped = 0;
-  let filesDeleted = 0;
-  // Tombstone and refused-stale counts mirror the deletePlan buckets so the
-  // ShareResult can report them without the caller having to count events.
-  // Populated only after Stage 3 runs (deletePlan is computed first, then
-  // mutated through the execution loop) — initial zero handles the
-  // propagateDeletes=false path.
-  let filesTombstoned = 0;
-  let filesRefusedStale = 0;
-  // Count of uploads suppressed by the push-side FILE_TOMBSTONE consult (a
-  // behind peer's stale copy of an authoritatively-deleted key). Always 0 when
-  // there are no tombstones for in-scope keys.
-  let filesSuppressedByTombstone = 0;
-  // Capped at 50 to bound event payload size — `newFiles` uses the same cap.
-  const REFUSED_STALE_PATH_CAP = 50;
-  const filesRefusedStalePaths: string[] = [];
-  const conflictPaths: string[] = [];
+  return {
+    options,
+    paths,
+    message,
+    onConflict,
+    vaultConfig,
+    entityContext,
+    hqRoot,
+    skipUnchanged,
+    propagateDeletes,
+    propagateDeletePolicy,
+    emit,
+    companyRef,
+    ctx,
+    syncRoot,
+    shouldSync,
+    journalSlug,
+    journal,
+    excludedSet,
+    excludedById,
+    scopeExcludedSet,
+  };
+}
 
-  // Collect all files to share
-  const filesToShare = collectFiles(paths, hqRoot, syncRoot, shouldSync);
-
-  // Stage 1: classify each file. Pre-HEAD — only inputs we can evaluate
-  // locally (size limit, journal hash, optional skip-unchanged) are
-  // considered. The plan event below carries an upper-bound `filesToUpload`
-  // (true conflicts emerge from the per-file HEAD in Stage 2 and aren't
-  // knowable here). The final `complete` event reports authoritative counts.
-  const plan = computePushPlan(filesToShare, journal, skipUnchanged === true);
-
-  // Delete-propagation plan: walk journal entries whose key falls under the
-  // requested scope; any whose local file is gone is a candidate for a
-  // remote DeleteObject. Only computed when the caller opts in — `hq share
-  // <file>` must never sweep deletes outside the explicit path list.
-  const deleteScopeRoots = propagateDeletes === true
-    ? resolveDeleteScopeRoots(paths, hqRoot, syncRoot)
+function createShareCounters(): ShareCounters {
+  return {
+    filesUploaded: 0,
+    bytesUploaded: 0,
+    filesSkipped: 0,
+    filesDeleted: 0,
+    filesTombstoned: 0,
+    filesRefusedStale: 0,
+    filesSuppressedByTombstone: 0,
+  };
+}
+
+async function buildSharePlans(run: PushRunContext): Promise<SharePlans> {
+  const filesToShare = collectFiles(
+    run.paths,
+    run.hqRoot,
+    run.syncRoot,
+    run.shouldSync,
+  );
+  const pushPlan = computePushPlan(
+    filesToShare,
+    run.journal,
+    run.skipUnchanged === true,
+  );
+  const deleteScopeRoots = run.propagateDeletes === true
+    ? resolveDeleteScopeRoots(run.paths, run.hqRoot, run.syncRoot)
     : [];
-  const deletePlan: DeletePlan = propagateDeletes === true
+  const deletePlan: DeletePlan = run.propagateDeletes === true
     ? await computeDeletePlan(
-        journal,
-        syncRoot,
+        run.journal,
+        run.syncRoot,
         deleteScopeRoots,
-        shouldSync,
-        propagateDeletePolicy,
-        ctx,
+        run.shouldSync,
+        run.propagateDeletePolicy,
+        run.ctx,
       )
     : { toDelete: [], toTombstone: [], refusedStale: [] };
-
-  // Decommission plan: journal entries under explicit prefixes the caller
-  // has asserted no longer belong in this bucket (typically a promoted
-  // company's `companies/{slug}/` keys in the personal bucket). Independent
-  // of `propagateDeletes` and DOES NOT require the local file to be missing
-  // — the caller is making a stronger claim than "local says delete this".
-  // Honors the same owned-only safety policy so a misconfigured caller
-  // can never erase content the journal records as pulled from elsewhere.
-  // Dedupes against `deletePlan` so a key in both plans is only processed
-  // once (DeleteObject is idempotent on S3 but the journal-write would
-  // race a no-op pass through the loop body).
   const decommissionPlan =
-    (options.decommissionPrefixes ?? []).length > 0
+    (run.options.decommissionPrefixes ?? []).length > 0
       ? computeDecommissionPlan(
-          journal,
-          options.decommissionPrefixes ?? [],
-          propagateDeletePolicy,
-          // Dedup against `toDelete` (decommission and propagate-delete
-          // would both issue DeleteObject — single call wins) and against
-          // `toTombstone` (the remote is already 404; the tombstone loop
-          // drops the journal entry without a network call — decommission
-          // yields, both for efficiency and to avoid emitting two
-          // "deleted" events for the same key).
-          //
-          // We do NOT dedup against `refusedStale`. A key whose remote
-          // ETag drifted (peer wrote a newer version) but which decommission
-          // claims should still be removed — the caller has asserted this
-          // key doesn't belong in this bucket regardless of peer activity.
-          // Under owned-only (default) `computeDecommissionPlan`'s
-          // direction:'up' filter already excludes peer-written entries;
-          // under policy:'all' the caller has opted out of that safety
-          // anyway. The refusedStale loop below filters out keys we're
-          // about to decommission to avoid emitting a spurious "kept on
-          // remote" event for content we're deleting.
+          run.journal,
+          run.options.decommissionPrefixes ?? [],
+          run.propagateDeletePolicy,
           new Set([...deletePlan.toDelete, ...deletePlan.toTombstone]),
         )
       : [];
 
-  emit({
+  run.emit({
     type: "plan",
-    // share() is push-only; pull counts are sourced from sync()'s plan event.
     filesToDownload: 0,
     bytesToDownload: 0,
-    filesToUpload: plan.filesToUpload,
-    bytesToUpload: plan.bytesToUpload,
-    filesToSkip: plan.filesToSkip,
-    // Push conflicts require a remote HEAD; we don't yet do that in Stage 1,
-    // so this stays 0. V1.5 (single LIST) will let us classify them up-front.
+    filesToUpload: pushPlan.filesToUpload,
+    bytesToUpload: pushPlan.bytesToUpload,
+    filesToSkip: pushPlan.filesToSkip,
     filesToConflict: 0,
-    // Reported count is the deletes we're actually going to issue — does NOT
-    // include tombstones (no S3 call) or refused-stale (no journal change).
-    // Refusals surface as their own event stream so consumers that care can
-    // render a "kept on remote: N" line separately. `decommissionPlan` adds
-    // to this count because every decommission entry IS an issued
-    // DeleteObject (different intent than propagate-deletes, same network
-    // effect).
     filesToDelete: deletePlan.toDelete.length + decommissionPlan.length,
   });
 
-  // Bulk-asymmetry summary event. Emitted once if the circuit-breaker
-  // tripped inside `computeDeletePlan` — see DeletePlan.bulkAsymmetry doc.
-  // Per-key refusal events fire later in the refusedStale loop with
-  // reason: "bulk-asymmetry" so the UI can also show the affected paths.
   if (deletePlan.bulkAsymmetry) {
-    emit({
+    run.emit({
       type: "delete-refused-bulk-asymmetry",
       candidates: deletePlan.bulkAsymmetry.candidates,
       inScope: deletePlan.bulkAsymmetry.inScope,
@@ -1054,213 +1036,111 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
     });
   }
 
-  // Stage 2: execute. Skip items pre-classified as no-ops, then for each
-  // upload candidate run the HEAD + 3-way conflict check + actual PUT.
-  //
-  // 5.36.0: upload candidates go through a bounded-concurrent pool
-  // (`TRANSFER_CONCURRENCY`, default 16, tunable via
-  // `HQ_SYNC_TRANSFER_CONCURRENCY`) for 4-8x speedup on transfer-heavy
-  // syncs. Skip-size-limit and skip-unchanged are handled inline first
-  // (pure local-state mutation). Upload candidates are collected into
-  // `uploadItems[]` and processed in parallel via the pool below.
-  //
-  // Abort handling: when any item's conflict resolution is "abort", we
-  // set `aborted = true` so the pool stops queueing new items, drain
-  // in-flight cleanly, and short-circuit to the abort return. In-flight
-  // PUTs that already issued will complete (S3 doesn't have client-side
-  // cancellation in this code path); their results are still recorded on
-  // the journal so the next sync's planner doesn't re-fire them.
-  // Interactive-mode prompts: when `onConflict` is unset the per-item conflict
-  // path calls resolveConflict()'s readline prompt on process.stdin, and two
-  // pool workers prompting at once would race for the terminal and interleave
-  // answers. The 5.36.x guard solved this by forcing the WHOLE pool to
-  // concurrency=1 — which made an interactive `hq sync now` crawl even when
-  // zero conflicts existed (every transfer serialized just in case one might
-  // prompt). Instead, keep full env-tunable concurrency and serialize ONLY the
-  // prompt (see `resolveConflictSerialized` below): at most one prompt awaits
-  // input at a time while transfers stay parallel.
-  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;
-  })();
-
-  // Chained lock around the (possibly interactive) conflict prompt. Each
-  // resolveConflict() runs only after the previous one settles, so concurrent
-  // pool workers never prompt over each other on stdin — without dropping the
-  // transfer pool's parallelism. A rejected prompt must not wedge the chain,
-  // so the link swallows errors (the original promise still rejects to its
-  // awaiter). In non-interactive mode resolveConflict applies the configured
-  // strategy without reading stdin, so the lock adds no real serialization.
+  return { pushPlan, deletePlan, decommissionPlan };
+}
+
+async function executeUploads(
+  run: PushRunContext,
+  pushPlan: PushPlan,
+  counters: ShareCounters,
+  conflictPaths: string[],
+): Promise<UploadExecutionResult> {
+  const TRANSFER_CONCURRENCY = resolveTransferConcurrency();
   let conflictPromptChain: Promise<unknown> = Promise.resolve();
   const resolveConflictSerialized = (
     info: Parameters<typeof resolveConflict>[0],
   ): ReturnType<typeof resolveConflict> => {
-    const run = conflictPromptChain.then(() => resolveConflict(info, onConflict));
-    conflictPromptChain = run.then(
+    const resolution = conflictPromptChain.then(() =>
+      resolveConflict(info, run.onConflict),
+    );
+    conflictPromptChain = resolution.then(
       () => undefined,
       () => undefined,
     );
-    return run;
+    return resolution;
   };
 
-  // Push-side FILE_TOMBSTONE consult (delete-resync) — symmetric to the pull
-  // planner's suppression in sync.ts. An authoritative delete
-  // (`hq files delete <prefix>`) writes a FILE_TOMBSTONE and removes the S3
-  // object; the pull side already honors it. But the PUSH side did not: a behind
-  // peer who still holds the deleted file locally would re-upload it here, and
-  // because the re-uploaded object post-dates the tombstone, the pull planner's
-  // timestamp-only re-create heuristic (`isRemoteRecreateAfterTombstone`) treats
-  // it as a genuine re-create and resurrects the key for EVERYONE — defeating the
-  // authoritative delete. Consult the tombstones so a stale-baseline upload is
-  // skipped at the source.
-  //
-  // Source: an injected `fileTombstones` (a sync run can hand the push leg the
-  // map it already fetched for the pull leg), else a self-fetch for COMPANY
-  // vaults that have a `vaultConfig`. Personal vaults have no company tombstones
-  // (the pull side skips them too), and `entityContext`-only callers have no
-  // auth to fetch with — both degrade to an empty map (no suppression), the
-  // safe/legacy direction.
   const fileTombstones: Map<string, CompanyTombstone> =
-    options.fileTombstones ??
-    (!ctx.uid.startsWith("prs_") && vaultConfig
-      ? await fetchCompanyTombstones(vaultConfig, ctx.uid)
+    run.options.fileTombstones ??
+    (!run.ctx.uid.startsWith("prs_") && run.vaultConfig
+      ? await fetchCompanyTombstones(run.vaultConfig, run.ctx.uid)
       : new Map<string, CompanyTombstone>());
 
-  // Phase A: serial classification pass — handle skips inline, collect
-  // upload candidates for the parallel pool.
-  const uploadItems: Array<typeof plan.items[number] & { action: "upload" }> = [];
-  for (const item of plan.items) {
+  const uploadItems: UploadPlanItem[] = [];
+  for (const item of pushPlan.items) {
     if (item.action === "skip-size-limit") {
-      emit({
+      run.emit({
         type: "error",
         path: item.relativePath,
         message: "file exceeds size limit",
       });
-      filesSkipped++;
+      counters.filesSkipped++;
       continue;
     }
-    // Suppress the re-upload of an authoritatively-deleted key when the local
-    // copy is still the deleted baseline. Discrimination mirrors the pull side's
-    // `localChanged || !journalEntry` test: a journal entry whose hash matches
-    // the upload's localHash means the file is byte-identical to what was last
-    // synced — i.e. the deleted version a behind peer never pulled away — so
-    // SKIP it. A locally-changed file (hash differs) or one with no journal
-    // entry is genuine new content (a real re-create or a post-delete edit) and
-    // uploads normally. The deleter's own stale local copy is removed by the
-    // pull leg's `tombstone-delete`; this guard only stops the resurrection.
-    if (item.action === "upload" && fileTombstones.size > 0) {
-      const ts = fileTombstones.get(toPosixKey(item.relativePath));
-      if (ts !== undefined) {
-        const entry = journal.files[item.relativePath];
-        if (entry && entry.hash === item.localHash) {
-          filesSuppressedByTombstone++;
-          emit({
-            type: "upload-suppressed-tombstone",
-            path: item.relativePath,
-            deletedAt: ts.deletedAt,
-          });
-          continue;
+    if (item.action === "upload") {
+      if (fileTombstones.size > 0) {
+        const ts = fileTombstones.get(toPosixKey(item.relativePath));
+        if (ts !== undefined) {
+          const entry = run.journal.files[item.relativePath];
+          if (entry && entry.hash === item.localHash) {
+            counters.filesSuppressedByTombstone++;
+            run.emit({
+              type: "upload-suppressed-tombstone",
+              path: item.relativePath,
+              deletedAt: ts.deletedAt,
+            });
+            continue;
+          }
         }
       }
+      uploadItems.push(item);
+      continue;
     }
-    if (item.action === "skip-unchanged") {
-      // Refresh the journal's (mtimeMs, size) for a touched-but-identical file
-      // so the next sync's lstat fast-path matches and skips without re-hashing.
-      // Guarded on item.restamp (only set when the fast-path missed AND the
-      // stored stat actually differs) and on the entry still carrying a hash —
-      // never alters the content hash, so this stays a pure no-op skip. The
-      // journal is persisted unconditionally by writeJournal at the end of the
-      // run, so this survives even when nothing uploads.
-      if (item.restamp) {
-        const existing = journal.files[item.relativePath];
-        if (existing && existing.hash) {
-          existing.mtimeMs = item.restamp.mtimeMs;
-          existing.size = item.restamp.size;
-        }
+    if (item.restamp) {
+      const existing = run.journal.files[item.relativePath];
+      if (existing && existing.hash) {
+        existing.mtimeMs = item.restamp.mtimeMs;
+        existing.size = item.restamp.size;
       }
-      filesSkipped++;
-      continue;
     }
-    uploadItems.push(item);
+    counters.filesSkipped++;
   }
 
-  // Batch pre-mint PUT URLs (+ the created-at HEADs) for the whole upload set,
-  // signing the SAME metadata the pool below computes so each task replays the
-  // cached headers and skips its own presign. Turns an N-file push from ~N
-  // presign calls into ceil(N/1000) GET + ceil(N/1000) PUT — keeping a bulk
-  // push under the 100/hr limit. No-op on the S3 SDK transport; best-effort.
   await primeUploads(
-    ctx,
+    run.ctx,
     uploadItems.map((it) => ({
       key: it.relativePath,
       localPath: it.absolutePath,
       isSymlink: it.kind === "symlink",
-      author: options.author,
+      author: run.options.author,
     })),
   );
+  // Warm the GET presigns the per-item conflict HEAD (remoteMeta) reuses, so a
+  // large upload set doesn't mint one presign per HEAD and burst/trip the
+  // presign breaker. Mirrors the new-files + tombstone pre-primes on the pull.
+  await primeObjectTransport(
+    run.ctx,
+    "get",
+    uploadItems.map((it) => it.relativePath),
+  );
 
-  // Phase B: parallel upload pool. Each task runs the full per-item flow
-  // (HEAD + conflict + PUT + journal stamp + emit). Aborts flip the
-  // shared `aborted` flag and the pool stops draining the queue; tasks
-  // already in flight complete normally.
   let aborted = false;
   let abortFlightConflictPaths: string[] = [];
 
-  const processUploadItem = async (
-    item: typeof uploadItems[number],
-  ): Promise<void> => {
+  const processUploadItem = async (item: UploadPlanItem): Promise<void> => {
     if (aborted) return;
     const { absolutePath, relativePath, localHash } = item;
 
-    // Auto-refresh context if credentials expiring. Only available on the
-    // vaultConfig path — pre-vended contexts have no source to re-vend
-    // from, so we let the AWS SDK surface ExpiredToken naturally on the
-    // PUT below if the caller under-vended.
-    if (vaultConfig && isExpiringSoon(ctx.expiresAt)) {
-      ctx = await refreshEntityContext(companyRef, vaultConfig);
+    if (run.vaultConfig && isExpiringSoon(run.ctx.expiresAt)) {
+      run.ctx = await refreshEntityContext(run.companyRef, run.vaultConfig);
     }
 
-    // Check for remote conflict — refuse to overwrite newer remote version.
-    //
-    // A real conflict requires BOTH sides to have moved since the last sync.
-    // The previous predicate only checked `journalEntry.hash !== localHash`,
-    // which mislabelled every local edit as a conflict and (combined with
-    // `--on-conflict keep`) silently dropped the user's edit. We now compare
-    // the current remote ETag against the one captured at last sync; when
-    // missing (legacy entries), we fall back to the same `lastModified >
-    // syncedAt` heuristic the pull side uses.
-    //
-    // Bug #7 (data-loss class — see workspace/reports/hq-cloud-5.33.0-
-    // deep-test.md): for a path with NO prior journal entry (first push
-    // from this machine), the localChanged/remoteChanged predicates above
-    // both evaluate FALSE (their guards require `!!journalEntry`). Push
-    // fell through to an unconditional PUT, silently clobbering any
-    // peer's content already at that key. The verification report's V7
-    // isolated this — the bug is independent of \`--on-conflict\` mode;
-    // it's keyed on "do I have a prior journal entry?" not on the flag.
-    //
-    // Fresh-collision branch: when remoteMeta exists and there's no
-    // journal entry, hash the local body (MD5 for parity with S3's
-    // single-part etag) and compare. Match → no conflict, silently skip
-    // the PUT (the bytes are already there). Mismatch → treat as a
-    // conflict in the same shared branch below.
-    // Defense-in-depth for the scoped-push 403: the `prefixSet` filter above
-    // should already have dropped any out-of-scope key from the plan, but a
-    // grant that changed mid-run, a pinned prefix outside the grant, or
-    // prefix-coalesce imprecision can still leave an out-of-scope key here.
-    // This HEAD sits OUTSIDE the per-file PUT try/catch below, so a thrown
-    // 403 used to bubble to `workerErrors` and abort the ENTIRE company with
-    // a generic message and exit 2. Catch the access-denied class, surface
-    // the offending PATH clearly, and skip just this key — the rest of the
-    // company still syncs. Non-access-denied errors re-throw unchanged.
     let remoteMeta: Awaited<ReturnType<typeof headRemoteFile>>;
     try {
-      remoteMeta = await headRemoteFile(ctx, relativePath);
+      remoteMeta = await headRemoteFile(run.ctx, relativePath);
     } catch (headErr) {
       if (isAccessDenied(headErr)) {
-        emit({
+        run.emit({
           type: "error",
           path: relativePath,
           message:
@@ -1273,19 +1153,15 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
       throw headErr;
     }
     if (remoteMeta) {
-      const journalEntry = journal.files[relativePath];
+      const journalEntry = run.journal.files[relativePath];
       const localChanged = !!journalEntry && journalEntry.hash !== localHash;
       const remoteChanged = !!journalEntry && hasRemoteChanged(remoteMeta, journalEntry);
 
       let isFreshCollision = false;
       let multipartConverged = false;
-      if (!journalEntry && item.kind === "file") {
-        // Single-part S3 PUT etag is MD5 of the body. Multipart uploads
-        // produce \`<md5>-<partCount>\`. Symlink records (\`kind: "symlink"\`)
-        // skip the check entirely — the wire body shape (\`hq-symlink:\`
-        // prefix + target) isn't a pure byte mirror and would mis-
-        // classify; symlink overwrites are rare and an audit pass after
-        // the broader bug-cleanup wave can extend coverage if needed.
+      if (!journalEntry && item.kind === "symlink") {
+        isFreshCollision = true;
+      } else if (!journalEntry && item.kind === "file") {
         const remoteEtagNormalized = normalizeEtag(remoteMeta.etag);
         const isMultipart = /-\d+$/.test(remoteEtagNormalized);
         if (!isMultipart) {
@@ -1294,38 +1170,16 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
           if (localMd5 !== remoteEtagNormalized) {
             isFreshCollision = true;
           }
-          // Match → bytes are already there; fall through to upload
-          // path which is idempotent (S3 will overwrite with identical
-          // content + carry our metadata). Cheap, no behavior change.
         } else {
-          // Multipart remote etag is \`<md5>-<partCount>\`, NOT a usable
-          // content hash, so — unlike the single-part branch — we cannot
-          // decide collision-vs-identical from the etag alone. The old
-          // behavior assumed a collision here, which minted a FALSE
-          // conflict for the most common fresh-install case: re-pushing a
-          // byte-identical \`core/\` scaffold file whose remote copy happened
-          // to be multipart-uploaded. Every fresh install that hit an
-          // already-populated bucket therefore came up "with conflicts".
-          //
-          // Instead, fetch the remote bytes once and compare content
-          // hashes directly — the same convergence guard the pull side
-          // uses (sync.ts). Identical content is NOT a conflict. On any
-          // fetch/hash failure we fail safe to "conflict" (false positives
-          // prompt the operator; false negatives risk clobbering a peer).
           const remoteDiffers = await remoteContentDiffers(
-            ctx,
+            run.ctx,
             relativePath,
             localHash,
-            hqRoot,
+            run.hqRoot,
           );
           if (remoteDiffers) {
             isFreshCollision = true;
           } else {
-            // Byte-identical multipart object already present. Seed the
-            // journal baseline from the remote so the next sync sees no
-            // change on either side, and skip the redundant PUT —
-            // re-uploading would needlessly rewrite remote and churn its
-            // etag from multipart to single-part.
             multipartConverged = true;
           }
         }
@@ -1334,7 +1188,7 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
       if (multipartConverged) {
         const lstat = fs.lstatSync(absolutePath);
         updateEntry(
-          journal,
+          run.journal,
           relativePath,
           localHash,
           lstat.size,
@@ -1342,8 +1196,8 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
           remoteMeta.etag,
           lstat.mtimeMs,
         );
-        emit({ type: "reconciled", path: relativePath, direction: "push" });
-        filesSkipped++;
+        run.emit({ type: "reconciled", path: relativePath, direction: "push" });
+        counters.filesSkipped++;
         return;
       }
 
@@ -1357,7 +1211,7 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
           direction: "push",
         });
 
-        emit({
+        run.emit({
           type: "conflict",
           path: relativePath,
           direction: "push",
@@ -1365,124 +1219,51 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
         });
 
         if (resolution === "abort") {
-          // Flip the shared aborted flag — the pool drainer below sees this
-          // and stops queueing new items. In-flight tasks complete normally
-          // (S3 PUTs have no client-side cancel here). The outer abort
-          // return is built after the pool drains.
           aborted = true;
           abortFlightConflictPaths = [...conflictPaths];
           return;
         }
         if (resolution === "keep" || resolution === "skip") {
-          // Bug #7 mirror branch: when the resolution is keep/skip on a
-          // FRESH collision (no prior journal entry), download the
-          // remote bytes to \`<orig>.conflict-<ts>-<short>\` so both
-          // versions survive on disk. Mirrors the pull-side mirror-write
-          // routine in sync.ts exactly. Skipped for stale-journal
-          // conflicts (the pre-Bug-#7 codepath) — those already produce
-          // a pull-side mirror on the next sync cycle.
           if (isFreshCollision) {
-            try {
-              const detectedAt = new Date().toISOString();
-              const machineId = readShortMachineId(hqRoot);
-              const originalRelative = path.relative(hqRoot, absolutePath);
-              const conflictRelative = buildConflictPath(
-                originalRelative,
-                detectedAt,
-                machineId,
-              );
-              const conflictAbs = path.join(hqRoot, conflictRelative);
-              await downloadFile(ctx, relativePath, conflictAbs);
-              appendConflictEntry(hqRoot, {
-                id: buildConflictId(originalRelative, detectedAt),
-                originalPath: originalRelative,
-                conflictPath: conflictRelative,
-                detectedAt,
-                side: "push",
-                machineId,
-                localHash,
-                remoteHash: normalizeEtag(remoteMeta.etag),
-              });
-            } catch (mirrorErr) {
-              emit({
-                type: "error",
-                path: relativePath,
-                message: `conflict mirror write failed: ${
-                  mirrorErr instanceof Error ? mirrorErr.message : String(mirrorErr)
-                }`,
-              });
-            }
+            await writePushConflictMirror(run, item, normalizeEtag(remoteMeta.etag));
           }
-          filesSkipped++;
+          counters.filesSkipped++;
           return;
         }
-        // "overwrite" falls through to upload
       }
     }
 
-    // Re-check abort flag right before the PUT — if a peer task aborted
-    // while we were waiting on HEAD, skip the PUT entirely. This is
-    // belt-and-suspenders alongside the queue-drain check; without it,
-    // up to TRANSFER_CONCURRENCY in-flight uploads could still issue PUTs
-    // after the user signaled abort.
     if (aborted) return;
 
-    // Conditional-write fence (storage-level backstop for the entire
-    // stale-clobber class). Every PUT asserts the remote state this pass
-    // just inspected:
-    //   - remote exists  → If-Match on the observed etag ("replace exactly
-    //     what I HEAD'd"). Closes the HEAD→PUT TOCTOU: a peer's write
-    //     landing in the window makes S3 itself reject with 412 instead of
-    //     this machine silently regressing the object.
-    //   - remote absent  → If-None-Match:* ("create only"). If the HEAD was
-    //     wrong about absence (any transport/state bug — the 2026-06-10..12
-    //     regression storm's shape), the PUT 412s instead of clobbering.
-    // Enforced natively on the SDK transport; on the presigned transport it
-    // activates when files-presign signs the headers (see object-io.ts).
     const precondition: PutPrecondition = remoteMeta
       ? { ifMatch: remoteMeta.etag }
       : { ifNoneMatch: "*" };
 
-    // Upload — symlinks go through uploadSymlink (zero-byte body + target
-    // metadata), regular files through uploadFile (file contents). The
-    // discriminator is item.kind set by computePushPlan; both branches
-    // converge on the same journal/event update path below. Factored into a
-    // closure so the 412 "overwrite" resolution below can re-run it without
-    // the fence after explicit user consent.
     const performUpload = async (pc: PutPrecondition | undefined): Promise<void> => {
       const isSymlinkUpload = item.kind === "symlink";
-      // Capture lstat post-upload so size + mtimeMs stamped into the
-      // journal reflect the bytes we actually shipped. lstat (not stat)
-      // so a symlink stamps the link's own mtime, not the target's —
-      // matches the fast-path's lstat comparison so the next sync can
-      // skip without dereferencing.
       const lstat = fs.lstatSync(absolutePath);
       const size = isSymlinkUpload ? 0 : lstat.size;
       const mtimeMs = lstat.mtimeMs;
 
       const { etag } = isSymlinkUpload
-        ? await uploadSymlink(ctx, item.target, relativePath, options.author, pc)
-        : await uploadFile(ctx, absolutePath, relativePath, options.author, pc);
-
-      // Update journal with optional message; capture the post-upload ETag
-      // so the next sync can distinguish "remote moved since we last wrote"
-      // from "user edited locally" without conflating the two. mtimeMs
-      // feeds the 5.36.0 lstat fast-path on the next push.
-      updateEntry(journal, relativePath, localHash, size, "up", etag, mtimeMs);
-      if (message) {
-        journal.files[relativePath] = {
-          ...journal.files[relativePath],
-          message,
-        } as typeof journal.files[string] & { message: string };
+        ? await uploadSymlink(run.ctx, item.target, relativePath, run.options.author, pc)
+        : await uploadFile(run.ctx, absolutePath, relativePath, run.options.author, pc);
+
+      updateEntry(run.journal, relativePath, localHash, size, "up", etag, mtimeMs);
+      if (run.message) {
+        run.journal.files[relativePath] = {
+          ...run.journal.files[relativePath],
+          message: run.message,
+        } as JournalFileEntry & { message: string };
       }
 
-      filesUploaded++;
-      bytesUploaded += size;
-      emit({
+      counters.filesUploaded++;
+      counters.bytesUploaded += size;
+      run.emit({
         type: "progress",
         path: relativePath,
         bytes: size,
-        ...(message ? { message } : {}),
+        ...(run.message ? { message: run.message } : {}),
       });
     };
 
@@ -1490,17 +1271,13 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
       await performUpload(precondition);
     } catch (err) {
       if (isPreconditionFailed(err)) {
-        // The fence fired: the remote moved past (If-Match) or appeared at
-        // (If-None-Match) this key between our HEAD and the PUT — exactly
-        // the race the fence exists to catch. Surface as a push conflict;
-        // never silently overwrite.
         conflictPaths.push(relativePath);
         const resolution = await resolveConflictSerialized({
           path: relativePath,
           localHash,
           direction: "push",
         });
-        emit({
+        run.emit({
           type: "conflict",
           path: relativePath,
           direction: "push",
@@ -1512,12 +1289,10 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
           return;
         }
         if (resolution === "overwrite") {
-          // Explicit clobber consent — retry once without the fence. A
-          // second failure falls through to the generic error emit.
           try {
             await performUpload(undefined);
           } catch (retryErr) {
-            emit({
+            run.emit({
               type: "error",
               path: relativePath,
               message:
@@ -1526,46 +1301,15 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
           }
           return;
         }
-        // keep/skip: preserve the racing remote next to the local copy so
-        // both versions survive — same mirror routine as the fresh-collision
-        // branch above.
-        try {
-          const detectedAt = new Date().toISOString();
-          const machineId = readShortMachineId(hqRoot);
-          const originalRelative = path.relative(hqRoot, absolutePath);
-          const conflictRelative = buildConflictPath(
-            originalRelative,
-            detectedAt,
-            machineId,
-          );
-          const conflictAbs = path.join(hqRoot, conflictRelative);
-          await downloadFile(ctx, relativePath, conflictAbs);
-          appendConflictEntry(hqRoot, {
-            id: buildConflictId(originalRelative, detectedAt),
-            originalPath: originalRelative,
-            conflictPath: conflictRelative,
-            detectedAt,
-            side: "push",
-            machineId,
-            localHash,
-            // remoteMeta (if any) predates the racing write that fired the
-            // fence — record what we knew ("" when the key was believed
-            // absent); the mirror file carries the authoritative remote bytes.
-            remoteHash: remoteMeta ? normalizeEtag(remoteMeta.etag) : "",
-          });
-        } catch (mirrorErr) {
-          emit({
-            type: "error",
-            path: relativePath,
-            message: `conflict mirror write failed: ${
-              mirrorErr instanceof Error ? mirrorErr.message : String(mirrorErr)
-            }`,
-          });
-        }
-        filesSkipped++;
+        await writePushConflictMirror(
+          run,
+          item,
+          remoteMeta ? normalizeEtag(remoteMeta.etag) : "",
+        );
+        counters.filesSkipped++;
         return;
       }
-      emit({
+      run.emit({
         type: "error",
         path: relativePath,
         message: isAccessDenied(err)
@@ -1579,25 +1323,6 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
     }
   };
 
-  // Drain the upload queue with bounded concurrency. Per-file progress
-  // events fire from inside processUploadItem at file-settle time, so
-  // cross-file event ordering is settle-order, not plan-walk-order — the
-  // menubar's stream parser already tolerates per-company interleave so
-  // this is shape-compatible. allSettled-style waiting (via Promise.race
-  // on the in-flight set) keeps the pool topped up without idling on slow
-  // members.
-  //
-  // Codex P1 (5.36.x): each worker promise is wrapped in a .catch that
-  // records the error to `workerErrors` and resolves normally — so
-  // `Promise.race(inFlight)` can never reject and unwind the drain loop
-  // mid-flight. Without the wrap, an unhandled rejection inside
-  // processUploadItem (e.g. headRemoteFile or refreshEntityContext, both
-  // of which sit outside the per-item PUT try/catch) bubbled out of the
-  // race, abandoned still-in-flight uploads that kept mutating remote
-  // state, and skipped writeJournal — leaving remote and journal
-  // permanently out of sync for the next run. After the pool fully
-  // drains we throw an aggregated error so the caller still surfaces the
-  // failure (and the journal reflects the writes that actually landed).
   const workerErrors: Error[] = [];
   {
     const queue = [...uploadItems];
@@ -1617,96 +1342,86 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
       if (inFlight.size > 0) {
         await Promise.race(Array.from(inFlight));
       } else {
-        // Aborted with nothing in flight → exit the drain loop.
         break;
       }
     }
   }
 
-  if (aborted) {
-    return {
-      filesUploaded,
-      bytesUploaded,
-      filesSkipped,
-      filesDeleted,
-      // Abort path: delete stage never runs, so tombstone + refused-
-      // stale counts are necessarily zero. Explicit fields keep the
-      // ShareResult shape stable for consumers that destructure.
-      filesTombstoned,
-      filesRefusedStale,
-      // Always present so consumers can destructure without a
-      // defaulting fallback. Empty on the abort path because the
-      // delete-plan execution loop is short-circuited.
-      filesRefusedStalePaths,
-      // Tombstone-suppressed uploads are classified in Phase A, which runs
-      // before the upload pool can abort, so the count is meaningful here.
-      filesSuppressedByTombstone,
-      // Exclusions are computed during the upload walk which has
-      // already completed by the time we hit a per-file conflict-
-      // abort, so the count is meaningful here. No event emit on
-      // abort (matches the existing convention: abort short-circuits
-      // before the end-of-run telemetry emits).
-      filesExcludedByPolicy: excludedSet.size,
-      // Scope exclusions are likewise computed during the upload walk, so the
-      // count is meaningful on the abort path too.
-      filesExcludedByScope: scopeExcludedSet.size,
-      // Use the snapshot of conflictPaths taken at the moment the abort
-      // fired — additional in-flight items may have appended to the
-      // shared array after the abort signal, and those should not show
-      // up in the abort result.
-      conflictPaths: abortFlightConflictPaths,
-      aborted: true,
-    };
+  return { aborted, abortFlightConflictPaths, workerErrors };
+}
+
+async function writePushConflictMirror(
+  run: PushRunContext,
+  item: UploadPlanItem,
+  remoteHash: string,
+): Promise<void> {
+  try {
+    const detectedAt = new Date().toISOString();
+    const machineId = readShortMachineId(run.hqRoot);
+    const originalRelative = path.relative(run.hqRoot, item.absolutePath);
+    const conflictRelative = buildConflictPath(
+      originalRelative,
+      detectedAt,
+      machineId,
+    );
+    const conflictAbs = path.join(run.hqRoot, conflictRelative);
+    if (!isMaterializationPathStillContained(run.syncRoot, conflictAbs)) {
+      run.emit({
+        type: "error",
+        path: item.relativePath,
+        message: "conflict mirror skipped: local parent escaped the sync root",
+      });
+    } else {
+      await downloadFile(run.ctx, item.relativePath, conflictAbs);
+      appendConflictEntry(run.hqRoot, {
+        id: buildConflictId(originalRelative, detectedAt),
+        originalPath: originalRelative,
+        conflictPath: conflictRelative,
+        detectedAt,
+        side: "push",
+        machineId,
+        localHash: item.localHash,
+        remoteHash,
+      });
+    }
+  } catch (mirrorErr) {
+    run.emit({
+      type: "error",
+      path: item.relativePath,
+      message:
+        "conflict mirror write failed: " +
+        (mirrorErr instanceof Error ? mirrorErr.message : String(mirrorErr)),
+    });
   }
+}
 
-  // Stage 3: propagate deletes. Three buckets, three actions:
-  //
-  //   1. `toDelete` (PLUS `decommissionPlan` concatenated in) — write a
-  //      delete-marker (versioning is enabled on the bucket so the delete
-  //      is soft and prior versions remain recoverable) and remove the
-  //      journal entry so the next sync sees the key as truly gone on
-  //      this machine. A failed DeleteObject leaves both the journal
-  //      entry and remote object intact — the next run retries.
-  //      Decommission keys join this bucket because their effect is
-  //      identical (DeleteObject + journal removal); the difference is
-  //      intent only, and the dedupe at plan-computation time ensures we
-  //      don't double-issue for a key both plans matched.
-  //
-  //   2. `toTombstone` — the remote was 404 at HEAD time (cleaned up out
-  //      of band, e.g. someone hand-deleted via console). No DeleteObject
-  //      needed; just drop the journal entry so the journal converges with
-  //      reality. Emit a synthetic `progress` event with `deleted: true`
-  //      and bytes=0 so consumers see the convergence.
-  //
-  //   3. `refusedStale` — under `currency-gated`, the remote's current
-  //      ETag no longer matches the journal's recorded one. Some other
-  //      device modified the file since this device last synced it. Keep
-  //      the remote intact; keep the journal entry intact. The next pull
-  //      leg of `sync now` re-pulls naturally via the existing
-  //      `hasRemoteChanged` path. Emit a dedicated event so UIs can
-  //      surface the refusal without inferring it from absence.
-  // Batch pre-mint DELETE URLs so a large delete set is ~ceil(N/1000) presign
-  // calls, not N. No-op on the S3 SDK transport; best-effort.
+async function executeDeletes(
+  run: PushRunContext,
+  deletePlan: DeletePlan,
+  decommissionPlan: string[],
+  counters: ShareCounters,
+  filesRefusedStalePaths: string[],
+): Promise<void> {
   const deleteKeys = [...deletePlan.toDelete, ...decommissionPlan];
-  await primeObjectTransport(ctx, "delete", deleteKeys);
+  await primeObjectTransport(run.ctx, "delete", deleteKeys);
   for (const relativePath of deleteKeys) {
-    if (vaultConfig && isExpiringSoon(ctx.expiresAt)) {
-      ctx = await refreshEntityContext(companyRef, vaultConfig);
+    if (run.vaultConfig && isExpiringSoon(run.ctx.expiresAt)) {
+      run.ctx = await refreshEntityContext(run.companyRef, run.vaultConfig);
     }
     try {
-      const entry = journal.files[relativePath];
+      const entry = run.journal.files[relativePath];
       const size = entry?.size ?? 0;
-      await deleteRemoteFile(ctx, relativePath);
-      removeEntry(journal, relativePath);
-      filesDeleted++;
-      emit({
+      await deleteRemoteFile(run.ctx, relativePath);
+      removeEntry(run.journal, relativePath);
+      counters.filesDeleted++;
+      run.emit({
         type: "progress",
         path: relativePath,
         bytes: size,
         deleted: true,
       });
     } catch (err) {
-      emit({
+      run.emit({
         type: "error",
         path: relativePath,
         message: err instanceof Error ? err.message : String(err),
@@ -1714,9 +1429,9 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
     }
   }
   for (const relativePath of deletePlan.toTombstone) {
-    removeEntry(journal, relativePath);
-    filesTombstoned++;
-    emit({
+    removeEntry(run.journal, relativePath);
+    counters.filesTombstoned++;
+    run.emit({
       type: "progress",
       path: relativePath,
       bytes: 0,
@@ -1724,20 +1439,15 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
       message: "tombstone (remote already 404)",
     });
   }
-  // Decommission overrides refusedStale: a key whose peer drifted but
-  // which the caller has claimed via `decommissionPrefixes` is processed
-  // by the DeleteObject loop above; skip the refusal event here so the
-  // event stream doesn't simultaneously claim "we deleted it" and "we
-  // kept it on remote" for the same key.
   const decommissionedSet =
     decommissionPlan.length > 0 ? new Set(decommissionPlan) : null;
   for (const refused of deletePlan.refusedStale) {
     if (decommissionedSet && decommissionedSet.has(refused.key)) continue;
-    filesRefusedStale++;
+    counters.filesRefusedStale++;
     if (filesRefusedStalePaths.length < REFUSED_STALE_PATH_CAP) {
       filesRefusedStalePaths.push(refused.key);
     }
-    emit({
+    run.emit({
       type: "delete-refused-stale-etag",
       path: refused.key,
       journalEtag: refused.journalEtag,
@@ -1745,78 +1455,74 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
       reason: refused.reason,
     });
   }
+}
 
-  // See cli/sync.ts: stamp lastSync on completion so a no-op share still
-  // ticks the "Last sync" indicator.
-  journal.lastSync = new Date().toISOString();
-  writeJournal(journalSlug, journal);
+function finalizeShareJournal(run: PushRunContext): void {
+  run.journal.lastSync = new Date().toISOString();
+  writeJournal(run.journalSlug, run.journal);
 
-  // Personal-vault out-of-policy summary. Emit at most once, only when at
-  // least one path was excluded. Sample is capped at 10 to keep the event
-  // small (Set iteration order = insertion order, so samples are the first
-  // ten paths encountered during the walk — deterministic, not random).
-  if (excludedSet.size > 0) {
+  if (run.excludedSet.size > 0) {
     const samplePaths: string[] = [];
-    for (const p of excludedSet) {
+    for (const p of run.excludedSet) {
       samplePaths.push(p);
       if (samplePaths.length >= 10) break;
     }
-    emit({
+    run.emit({
       type: "personal-vault-out-of-policy",
-      count: excludedSet.size,
+      count: run.excludedSet.size,
       samplePaths,
-      byId: { ...excludedById },
+      byId: { ...run.excludedById },
     });
   }
 
-  // ACL scope-exclusion summary. Emit at most once when one or more candidate
-  // paths fell outside the run's granted `prefixSet` and were skipped from the
-  // upload/delete plan. Informational (NOT an error): the company still syncs
-  // its in-scope subset and the run exits 0. Sample capped at 10 (insertion
-  // order = walk order, deterministic).
-  if (scopeExcludedSet.size > 0) {
+  if (run.scopeExcludedSet.size > 0) {
     const samplePaths: string[] = [];
-    for (const p of scopeExcludedSet) {
+    for (const p of run.scopeExcludedSet) {
       samplePaths.push(p);
       if (samplePaths.length >= 10) break;
     }
-    emit({
+    run.emit({
       type: "scope-excluded",
-      count: scopeExcludedSet.size,
+      count: run.scopeExcludedSet.size,
       samplePaths,
     });
   }
+}
 
-  // Codex P1 (5.36.x): if any worker rejected (unhandled error in
-  // headRemoteFile / refreshEntityContext / resolveConflict — paths
-  // outside the per-item PUT try/catch), we deliberately let the pool
-  // drain AND let post-pool stages (deletes, tombstones, journal write,
-  // personal-vault summary) run to completion so journal + remote stay
-  // converged on what actually landed. NOW surface the failure to the
-  // caller — preserving the first error's stack so debugging works.
-  // Aggregate count is reported in the message for visibility when
-  // multiple workers failed.
+function throwUploadWorkerErrors(workerErrors: Error[]): void {
   if (workerErrors.length > 0) {
     const first = workerErrors[0]!;
     if (workerErrors.length > 1) {
-      first.message = `${first.message} (and ${workerErrors.length - 1} more upload-worker errors)`;
+      first.message =
+        first.message +
+        " (and " +
+        (workerErrors.length - 1) +
+        " more upload-worker errors)";
     }
     throw first;
   }
+}
 
+function buildShareResult(
+  run: PushRunContext,
+  counters: ShareCounters,
+  filesRefusedStalePaths: string[],
+  conflictPaths: string[],
+  aborted: boolean,
+): ShareResult {
   return {
-    filesUploaded,
-    bytesUploaded,
-    filesSkipped,
-    filesDeleted,
-    filesTombstoned,
-    filesRefusedStale,
+    filesUploaded: counters.filesUploaded,
+    bytesUploaded: counters.bytesUploaded,
+    filesSkipped: counters.filesSkipped,
+    filesDeleted: counters.filesDeleted,
+    filesTombstoned: counters.filesTombstoned,
+    filesRefusedStale: counters.filesRefusedStale,
     filesRefusedStalePaths,
-    filesSuppressedByTombstone,
-    filesExcludedByPolicy: excludedSet.size,
-    filesExcludedByScope: scopeExcludedSet.size,
+    filesSuppressedByTombstone: counters.filesSuppressedByTombstone,
+    filesExcludedByPolicy: run.excludedSet.size,
+    filesExcludedByScope: run.scopeExcludedSet.size,
     conflictPaths,
-    aborted: false,
+    aborted,
   };
 }
 
@@ -1879,22 +1585,6 @@ function defaultConsoleLogger(event: SyncProgressEvent): void {
   }
 }
 
-/**
- * Resolve active company from .hq/config.json or parent directory chain.
- */
-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;
-}
-
 /**
  * One entry produced by collectFiles/walkDir. Files describe regular
  * payloads that get hashed + size-checked + uploaded via uploadFile;
@@ -2082,6 +1772,11 @@ function isWithin(parent: string, child: string): boolean {
   return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
 }
 
+function isPathWithin(parent: string, child: string): boolean {
+  const rel = path.relative(parent, child);
+  return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+
 function realpathSafe(p: string): string {
   try {
     return fs.realpathSync.native(p);
@@ -2090,6 +1785,48 @@ function realpathSafe(p: string): string {
   }
 }
 
+function deepestExistingAncestor(start: string): string | null {
+  let current = start;
+  for (;;) {
+    try {
+      fs.lstatSync(current);
+      return current;
+    } catch (err: unknown) {
+      const code =
+        err && typeof err === "object" && "code" in err
+          ? (err as { code?: string }).code
+          : undefined;
+      if (code !== "ENOENT" && code !== "ENOTDIR") return null;
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function isMaterializationPathStillContained(root: string, localPath: string): boolean {
+  const resolvedRoot = path.resolve(root);
+  const resolvedLocal = path.resolve(localPath);
+  if (!isPathWithin(resolvedRoot, resolvedLocal)) return false;
+
+  let realRoot: string;
+  try {
+    realRoot = fs.realpathSync.native(resolvedRoot);
+  } catch {
+    return false;
+  }
+
+  const existingAncestor = deepestExistingAncestor(path.dirname(resolvedLocal));
+  if (existingAncestor === null) return false;
+  try {
+    const realAncestor = fs.realpathSync.native(existingAncestor);
+    return isPathWithin(realRoot, realAncestor);
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Containment check tailored for symlinks. Canonicalizes the link's
  * PARENT DIR (which is a real dir, not the link), then compares the
@@ -2112,24 +1849,6 @@ function isWithinForLink(parent: string, linkPath: string): boolean {
   return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
 }
 
-/**
- * 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") so an
- * S3-side mtime that exactly equals our syncedAt is not treated as drift.
- */
-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;
-}
-
 /**
  * Resolve each user-supplied share path to a directory under `syncRoot`,
  * returning the company-relative prefix that constrains delete propagation.
@@ -2510,6 +2229,14 @@ async function computeDeletePlan(
   // independently — one failed HEAD doesn't poison the others (errors
   // propagate from the chunk's Promise.all and are surfaced by share()'s
   // outer try/catch, mirroring the existing pre-share error handling).
+  // Warm the GET presigns the HEAD pass reuses so a large candidate set doesn't
+  // mint one presign per HEAD and trip the presign breaker. Mirrors the
+  // new-files + tombstone HEAD-pass pre-primes.
+  await primeObjectTransport(
+    ctx,
+    "get",
+    headCandidates.map((c) => c.key),
+  );
   for (let i = 0; i < headCandidates.length; i += DELETE_PLAN_HEAD_CONCURRENCY) {
     const chunk = headCandidates.slice(i, i + DELETE_PLAN_HEAD_CONCURRENCY);
     const results = await Promise.all(